mobile-debug-mcp 0.34.0 → 0.35.0

package/.agents/skills/mcp-builder/SKILL.md

@@ -1,67 +1,47 @@
 # MCP Builder skill
 
 name: mcp-builder
-version: 0.1.0
-summary: Reusable procedures for building, validating and installing Android/iOS apps in this repo. Designed for agents to act autonomously with project-specific guidance.
-
-# Purpose
-Provide concise, actionable procedures and schemas that encode the successful sequences used in mobile-debug-mcp: toolchain detection, build orchestration, install fallbacks, diagnostics collection, and verification (lint/tests). Keep core guidance short; link to references for details.
-
-# Activation conditions
-Activate when an agent needs to:
-- build or install an app from this repository
-- diagnose failing CI/dev machine builds
-- run lint/tests and collect reproducible diagnostics
-
-# Surface area (actions)
-- detect-toolchain
-- build-android
-- install-android
-- build-ios
-- install-ios
-- run-lint
-- run-tests
-- collect-diagnostics
-
-# Core guidance (what agent must do)
-1. Prefer project conventions and existing helpers in src/utils and src/manage.
-2. Use detect-toolchain to decide JAVA_HOME/JBR preference and whether adb/idb/xcrun are available.
-3. For Android builds, call prepareGradle() to prepare child PATH and env, then run ./gradlew (wrapper) if present.
-4. For installs, parse adb output defensively (ignore streamed-install noise) and on failure fall back to push+pm path.
-5. For iOS installs, prefer simctl for simulators; if simctl fails check idb and attempt idb install with diagnostics.
-6. On any error, call collect-diagnostics and attach env snapshot, invoked commands, stdout/stderr, and suggested fixes.
-
-# Inputs & outputs (short schemas)
-- detect-toolchain(input: { platform: 'android'|'ios'|'both', preferJBR?: boolean }) -> { tools: [{name, cmd, ok, version, suggestion}] }
-- build-android(input: { projectPath, variant?, clean?, envOverrides? }) -> { success, artifactPath?, logs?, diagnostics? }
-- install-android(input: { appPath, projectPath?, deviceId?, allowBuild? }) -> { installed:boolean, device, output?, diagnostics? }
-- build-ios/install-ios: mirror Android schema but use scheme/workspace/project and resultBundlePath
-- run-lint/run-tests -> { exitCode, stdout, stderr, artifacts[] }
-- collect-diagnostics(input: { reason, platform? }) -> { artifacts: [{ name, contentBase64?, path? }], envSnapshot }
-
-# Failure handling & suggestions
-- Always return structured diagnostics instead of throwing when possible.
-- Provide a short human-friendly suggestion in diagnostics (e.g., "Install Android Platform Tools or set ADB_PATH").
-- Redact sensitive env values (tokens, credentials) when including envSnapshot.
-
-# Progressive disclosure
-- Keep SKILL.md compact (this file). Place heavy references in skills/mcp-builder/references/*.md and instruct agents to load them only when needed.
-
-# References (implement as separate files)
-- references/toolchain-details.md — exact paths/heuristics used for JBR, JAVA_HOME, ANDROID_SDK locations.
-- references/build-flags.md — gradle/xcodebuild flags used, timeouts, and retry rationale.
-- references/diagnostics-schema.md — JSON schema for runResult and collected artifacts.
-
-# Implementation notes for maintainers
-- Implement a thin adapter in src/skills/mcp-builder/index.ts that maps skill actions to existing functions in src/manage and src/utils.
-- Provide unit tests under test/skills/mcp-builder that mock child_process to validate happy/failure paths.
-- Add env toggles: MCP_PREFERS_JBR, MCP_GRADLE_RETRIES, MCP_XCODEBUILD_RETRIES.
-
-# Example agent flow
-1. call detect-toolchain({platform:'android', preferJBR:true})
-2. if ok -> call build-android({projectPath:'/path', variant:'Debug'})
-3. call install-android({appPath:'/path/to.apk', deviceId:'emulator-5554'})
-4. if install fails -> call collect-diagnostics({reason:'install failure', platform:'android'})
-
-# License
-Same as repository (Apache-2.0).
+version: 0.1.1
+summary: Build, install and diagnose Android/iOS tooling using this repository’s existing adapters and validation commands.
+
+## Purpose
+
+Use this skill for native builds, installations, toolchain diagnosis and verification
+of `mobile-debug-mcp`. Follow the [shared development process](../../../docs/specs/process.md)
+for scope, approvals and reporting.
+
+## Workflow
+
+1. Inspect the relevant adapter under `src/manage/` and platform helpers under
+   `src/utils/`. Reuse their subprocess, timeout and diagnostic handling.
+2. Check only the tools needed by the task. Use the
+   [toolchain reference](references/toolchain-details.md) for Java/JBR, adb, idb
+   and Xcode discovery; confirm environment settings in the owning source.
+3. For Gradle builds, reuse `prepareGradle()` from `src/utils/android/utils.ts`.
+   For iOS builds, follow `src/manage/ios.ts`. Consult
+   [build configuration](references/build-flags.md) for supported overrides.
+4. Preserve installation fallbacks and error contracts. Collect command, output,
+   exit status and relevant environment details on failure; redact secrets.
+   The [diagnostic report format](references/diagnostics-schema.md) is guidance
+   for investigations, not a replacement for a tool’s public response shape.
+5. Run `npm run verify` for code changes. Lint includes the
+   [structural and architecture gates](../../../docs/code-structure.md); use
+   `npm run check:quality` and `npm run check:architecture` to diagnose failures.
+6. For native/runtime changes, run applicable device checks and report the actual
+   device, server build, observed result and cleanup. A skipped device suite or
+   successful build does not prove device behaviour. The
+   [isolated Android fixture](../../../test/fixtures/debugger-app/README.md) covers
+   interactions, labelled-control convergence and debugger journeys.
+
+## Test placement
+
+Follow the [test-authoring skill](../test-authoring/SKILL.md) when changing tests.
+Fake-toolchain tests belong under `test/unit/manage/`, `test/unit/system/` or
+`test/unit/utils/` according to the owning module. Automated native checks belong
+under `test/device/automated/`; ad hoc helpers belong under `test/device/manual/`.
+
+## References
+
+- [Toolchain details](references/toolchain-details.md): discovery and Java selection.
+- [Build configuration](references/build-flags.md): existing build flags and overrides.
+- [Diagnostics](references/diagnostics-schema.md): reporting command failures.

package/.agents/skills/mcp-builder/references/build-flags.md

@@ -1,43 +1,44 @@
-# Build flags and runtime configuration
-
-Purpose: describe the flags, environment variables and spawn-environment handling that agents should use when orchestrating Android and iOS builds for this repo.
-
-Common env variables
-- MCP_GRADLE_RETRIES (default: 1) — number of retry attempts on watchdog kills for Gradle
-- MCP_GRADLE_TIMEOUT_MS (default: 300000) — gradle watch/duration timeout
-- MCP_XCODEBUILD_RETRIES, MCP_XCODEBUILD_TIMEOUT_MS — similar for xcodebuild
-- MCP_PREFERS_JBR — prefer Android Studio JBR for JAVA_HOME
-- MCP_DERIVED_DATA, MCP_XCODE_RESULTBUNDLE_PATH — override DerivedData/result bundle locations
-
-Android (Gradle)
-- Use the Gradle wrapper if present: `./gradlew assemble<Variant>` (e.g., assembleDebug). Prefer wrapper to ensure consistent Gradle version.
-- Prepare spawn env by prepending javaBin and platform-tools dir to PATH and set GRADLE_JAVA_HOME and `-Dorg.gradle.java.home` when necessary.
-- If wrapper exists, ensure `chmod +x ./gradlew` before spawn.
-- Recommended flags:
-  - `--no-daemon` sometimes helpful in CI, but wrap with existing project conventions.
-  - Set `org.gradle.jvmargs` via env or gradle.properties only if needed.
-- Timeouts & watchdog:
-  - Use a watchdog timeout (MCP_GRADLE_TIMEOUT_MS) and retry (MCP_GRADLE_RETRIES) if killed by watchdog. Record stdout/stderr for each attempt.
-
-iOS (xcodebuild)
-- Use `xcodebuild -workspace <ws> -scheme <scheme> -configuration Debug -sdk iphonesimulator build` for simulator builds.
-- Provide `-derivedDataPath` and `-resultBundlePath` to isolate builds and produce diagnostics. Default result bundle path should be unique per run to avoid collisions.
-- Recommended flags: `-parallelizeTargets -jobs <N>` where N is from MCP_XCODE_JOBS or sensible default (4).
-- When a destination UDID is available, always pass `-destination "platform=iOS Simulator,id=<UDID>"` to avoid ambiguous device selection.
-- Timeouts & retries: respect MCP_XCODEBUILD_TIMEOUT_MS and MCP_XCODEBUILD_RETRIES; capture stdout/stderr and save logs under build-results.
-
-Install-time behavior
-- Android: prefer `adb install -r <apk>` for fast installs. If output contains spurious lines (e.g., "Performing Streamed Install" followed by "Success"), parse to extract final status. On failure try `adb push` to `/data/local/tmp` + `pm install -r <remote>` as a fallback collect push/install diagnostics.
-- iOS: prefer `xcrun simctl install <device> <app>` for simulator. On failure attempt idb install if idb exists: `idb install <ipa|app> --udid <udid>` and record its stdout/stderr.
-
-Diagnostics capture
-- Save stdout/stderr, exitCode and environment snapshot for each command. Persist logs under workspace/build-results or a temp dir provided by the caller.
-- For builds, also capture produced artifact paths to return to caller.
-
-Examples
-- Gradle invocation (pseudo):
-  spawnOpts.env.PATH = `${javaBin}:${platformTools}:${process.env.PATH}`
-  spawn('./gradlew', ['assembleDebug'], { cwd: projectRoot, env: spawnOpts.env })
-
-- xcodebuild invocation (pseudo):
-  xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Debug -sdk iphonesimulator -derivedDataPath /tmp/derived -resultBundlePath /tmp/Result-123.xcresult -parallelizeTargets -jobs 4 build
+# Build configuration
+
+Use the existing platform adapters rather than constructing a second build path.
+The owning implementation is the source of truth for accepted overrides.
+
+## Android
+
+[prepareGradle()](../../../../src/utils/android/utils.ts) selects the project
+wrapper when present and prepares Java and platform-tools in the child environment.
+[AndroidManage](../../../../src/manage/android.ts) executes that command.
+
+| Setting | Current use |
+| --- | --- |
+| `MCP_GRADLE_TASK` | Gradle task; defaults to `assembleDebug` |
+| `MCP_GRADLE_WORKERS`, then `MCP_BUILD_JOBS` | Supplies `--max-workers` |
+| `MCP_GRADLE_CACHE=0` | Disables Gradle caching |
+| `ANDROID_STUDIO_JDK`, `ANDROID_STUDIO_JBR`, `JAVA_HOME` | Java selection; see [toolchain details](toolchain-details.md) |
+
+The current Android build adapter does not implement `MCP_GRADLE_RETRIES` or
+`MCP_GRADLE_TIMEOUT_MS`. Do not assume iOS watchdog controls apply to Gradle.
+
+## iOS
+
+[iOSManage](../../../../src/manage/ios.ts) discovers the workspace/project and
+scheme, then supplies simulator destination, derived-data and result-bundle paths.
+
+| Setting | Current use |
+| --- | --- |
+| `XCODEBUILD_PATH` | Build executable; defaults to `xcodebuild` |
+| `MCP_XCODE_DESTINATION_UDID`, then `MCP_XCODE_DESTINATION` | Simulator destination when not supplied in options |
+| `MCP_DERIVED_DATA` | Derived-data path when not supplied in options |
+| `MCP_XCODE_RESULTBUNDLE_PATH` | Result bundle; otherwise generated uniquely per run |
+| `MCP_XCODE_JOBS` | Build parallelism; defaults to 4 unless supplied in options |
+| `MCP_FORCE_CLEAN=1` | Requests clean unless explicitly supplied in options |
+| `MCP_XCODEBUILD_TIMEOUT` | Watchdog duration in milliseconds; defaults to 180000 |
+| `MCP_XCODEBUILD_RETRIES` | Watchdog retries; current parsing falls back to 1 |
+
+## Installation and diagnostics
+
+Preserve adapter-specific install fallbacks and errors. Use the
+[management reference](../../../../docs/tools/manage.md) for public tool contracts.
+Record exact commands, output, exit status and artifact paths when investigating
+failures; see [diagnostics](diagnostics-schema.md). Keep environment snapshots
+limited to relevant variables and redact secrets.

package/.agents/skills/mcp-builder/references/diagnostics-schema.md

@@ -1,6 +1,9 @@
 # Diagnostics schema
 
-This document defines the JSON shapes that mcp-builder actions return when collecting diagnostics. Agents and tooling should rely on these keys.
+Use this suggested format when reporting a build or toolchain investigation.
+It is not a public MCP response schema or a claim that every adapter returns
+these fields. Preserve the actual tool response and label supplemental diagnostics
+separately; see the [management contracts](../../../../docs/tools/manage.md).
 
 Top-level diagnostic object
 {

package/.agents/skills/mcp-builder/references/toolchain-details.md

@@ -1,62 +1,49 @@
-# Toolchain details
-
-This reference documents the exact heuristics and commands used by the mcp-builder skill to detect and validate the native toolchain (Android & iOS) on contributor machines.
-
-Key environment variables
-- ADB_PATH: explicit path to adb binary
-- ANDROID_SDK_ROOT / ANDROID_HOME: SDK root; platform-tools/adb under these
-- ANDROID_STUDIO_JBR / ANDROID_STUDIO_JDK: explicit Android Studio JBR/JDK path
-- JAVA_HOME: system JDK
-- IDB_PATH / MCP_IDB_PATH: idb path for iOS
-- XCRUN_PATH: explicit xcrun path
-- MCP_PREFERS_JBR: boolean to prefer Android Studio JBR when present
-
-Android Java detection precedence
-1. ANDROID_STUDIO_JBR / ANDROID_STUDIO_JDK env vars (preferred when MCP_PREFERS_JBR set)
-2. Known Android Studio JBR locations (macOS):
-   - /Applications/Android Studio.app/Contents/jbr/Contents/Home
-   - /Applications/Android Studio Preview.app/Contents/jbr/Contents/Home
-3. Explicit JAVA_HOME (validate via `java -version`)
-4. macOS `/usr/libexec/java_home -v 17` or `-v 21`
-5. Common Linux JDK locations: `/usr/lib/jvm/*temurin*`, `/usr/lib/jvm/*zulu*`
-
-Validation rules
-- Accept only Java 17 or Java 21 for Gradle builds in this project (both tested/known working).
-- Reject GraalVM / Java 23 that causes Gradle jlink errors. If detected, return suggestion: "Prefer an Apple/Temurin/JBR Java 17 or 21. Set ANDROID_STUDIO_JBR or JAVA_HOME to a supported JDK."
-
-ADB resolution precedence
-1. process.env.ADB_PATH (explicit)
-2. ANDROID_SDK_ROOT or ANDROID_HOME -> platform-tools/adb
-3. Common SDK locations (macOS/Linux): $HOME/Library/Android/sdk/platform-tools, /opt/android-sdk/platform-tools
-4. `command -v adb` / `which adb` on PATH
-5. fallback to `adb` (best-effort)
-
-IDB / XCRUN detection (iOS)
-- IDB: check MCP_IDB_PATH -> IDB_PATH -> common locations (/opt/homebrew/bin/idb, /usr/local/bin/idb, $HOME/Library/Python/*/bin/idb). Validate by running `idb --version` or `idb list-targets --json`.
-- XCRUN: check XCRUN_PATH -> run `xcrun --version`.
-
-How to probe (commands)
-- adb: `adb --version` and `adb devices --print` (or `adb devices -l`) to list.
-- java: `java -XshowSettings:properties -version` or `java -version` parse first line.
-- xcrun: `xcrun --version`
-- idb: `idb --version` or `idb list-targets --json`
-
-Output format
-- Each probe returns { name, cmd, ok, version?, suggestion? } so agents can reason programmatically.
-- Include env snapshot (PATH, JAVA_HOME, ADB_PATH, ANDROID_SDK_ROOT, IDB_PATH, XCRUN_PATH) to aid diagnostics.
-
-Notes & rationale
-- Prefer Android Studio JBR (JBR is bundled & known-good) because developer machines often have mismatched system JDKs (e.g., Graal). Allow override via env for CI.
-- For long-running server processes, prepend java/bin and platform-tools to spawn env PATH when running child builds so external PATH/JAVA_HOME changes don't require a server restart.
-
-Examples
-- Detected result (JSON):
-  {
-    "name": "adb",
-    "cmd": "/Users/xxx/Library/Android/sdk/platform-tools/adb",
-    "ok": true,
-    "version": "Android Debug Bridge version 1.0.41"
-  }
-
-- Java suggestion when incompatible:
-  { "name": "java", "ok": false, "suggestion": "Found GraalVM (Java 23). Use Java 17 or 21: set ANDROID_STUDIO_JBR or JAVA_HOME." }
+# Toolchain discovery
+
+Inspect the owning helper before changing discovery or adding an override. Build
+adapters use these helpers; a separate probe should report the selected executable
+and its actual output, rather than infer success from an environment variable.
+
+## Android Java
+
+[detectJavaHome()](../../../../src/utils/java.ts) checks explicit
+`ANDROID_STUDIO_JDK`, then `ANDROID_STUDIO_JBR`, known Android Studio JBR locations,
+and `JAVA_HOME`, followed by macOS and Linux fallback locations. The version
+checks accept Java 17 or 21 for Android builds. Exact fallback locations live in
+the helper rather than being duplicated here.
+
+Use `java -version` on the selected executable. Distinguish Gradle’s selected JDK
+from the shell Java version and the optional debugger worker’s Java requirements;
+see [the debugger reference](../../../../docs/tools/debugger.md).
+
+## adb
+
+[resolveAdbCmd()](../../../../src/utils/android/utils.ts) checks, in order:
+
+1. An explicit nonempty `ADB_PATH`.
+2. `adb` on `PATH`.
+3. `ANDROID_SDK_ROOT` or `ANDROID_HOME` with `platform-tools/adb`.
+4. The macOS user SDK location.
+5. A final `adb` fallback, whose availability still needs checking.
+
+Probe with `adb version` and `adb devices -l`. Use an explicit serial for device
+journeys and record whether it is a physical device or an emulator.
+
+## iOS
+
+The [iOS command helpers](../../../../src/utils/ios/utils.ts) resolve idb through
+configured overrides and the current installation. `MCP_IDB_PATH` takes precedence
+over `IDB_PATH`; inspect `getConfiguredIdbPath()` for configuration-file fallbacks.
+`getXcrunCmd()` uses `XCRUN_PATH` or `xcrun`.
+
+Probe the selected binaries with `idb --version`, `idb list-targets --json`,
+`xcrun --version`, or `xcrun simctl list devices booted` as appropriate. A working
+simulator probe does not establish physical-iOS-device support.
+
+## Reporting
+
+Record executable paths, relevant versions, device identities and the commands
+that actually ran. Capture only relevant environment variables and redact secrets.
+Use the [diagnostic report guidance](diagnostics-schema.md), keeping supplemental
+diagnostics separate from public MCP responses. For available build settings,
+continue with [build configuration](build-flags.md).

package/.agents/skills/spec-review/references/spec-review-checklist.md

@@ -11,3 +11,10 @@ Ask these questions while reviewing a spec for implementation and execution read
 7. Does it match existing code paths and public tool surfaces?
 8. Can each open concern be classified as a spec issue, execution gap, or implementation issue?
 9. Is the spec ready to execute and implement without further interpretation?
+
+For structural refactors, also compare the proposed ownership and dependency
+directions against [the architecture rules](../../../../docs/code-structure.md).
+Check that new contracts are shared across schemas, validation and types, that
+timing-sensitive services have suitable clock/delay seams, and that compatibility
+checks protect public definitions and error behaviour. Passing size limits alone
+does not establish cohesive responsibilities.

package/.agents/skills/test-authoring/SKILL.md

@@ -1,7 +1,7 @@
 # Test Authoring skill
 
 name: test-authoring
-version: 0.1.0
+version: 0.1.1
 summary: Reusable guidance for adding or updating tests in this repository without tying the workflow to a single agent product.
 
 # Purpose
@@ -27,10 +27,11 @@ Activate when an agent needs to:
 2. Follow the repository's current automated test style: self-running `tsx` scripts with explicit assertions and non-zero exit on failure.
 3. Put automated unit tests under `test/unit/...`; the unit runner automatically executes every `*.test.ts` file there.
 4. Put automated device smoke tests under `test/device/automated/...`; put human-invoked helpers under `test/device/manual/...`.
-5. Reuse existing mocking seams and test hooks before creating new ones.
+5. Prefer the extracted services’ typed dependencies and injectable [clocks](../../../src/runtime/clock.ts) over replacing static methods or process-global timers. Reuse existing test seams before adding hooks.
 6. When testing user-facing tools, protect **response shape**, required fields, and documented defaults.
 7. Keep tests deterministic: isolate process-global mocks, prefer fake binaries or injected helpers over shared mutable module state.
-8. Validate with the repository commands that already exist instead of inventing new runners.
+8. Run `npm run verify` for code/test changes and applicable native checks under the [shared process](../../../docs/specs/process.md#5-verify-and-report).
+9. Follow the [structure and architecture rules](../../../docs/code-structure.md). Keep guardrail failure cases under `test/unit/quality/` and preserve the complete public tool-definition compatibility fixture.
 
 # Inputs & outputs
 - choose-test-type(input: { changedPaths[], behaviorType, requiresRealDevice?: boolean }) -> { recommendedType: 'unit'|'device-automated'|'device-manual', rationale, targetPath }
@@ -49,9 +50,9 @@ Activate when an agent needs to:
 - Load detailed references only when deciding placement, matching existing style, or validating new tests.
 
 # References
-- `references/repo-test-layout.md` — where tests belong and what each tree means
-- `references/test-authoring-workflow.md` — step-by-step workflow for creating or changing tests
-- `references/test-quality-checklist.md` — what a good test in this repo should prove before it is considered done
+- [references/repo-test-layout.md](references/repo-test-layout.md) — where tests belong and what each tree means
+- [references/test-authoring-workflow.md](references/test-authoring-workflow.md) — step-by-step workflow for creating or changing tests
+- [references/test-quality-checklist.md](references/test-quality-checklist.md) — what a good test in this repo should prove before it is considered done
 
 # License
 Same as repository (Apache-2.0).

package/.agents/skills/test-authoring/references/repo-test-layout.md

@@ -15,11 +15,13 @@ Best for:
 - response-shape validation
 - shared utility behavior
 - deterministic edge cases
+- injected-clock polling and stabilization checks (`test/unit/interact/`)
+- structural and architectural negative controls (`test/unit/quality/`)
 
 ## Automated device smoke tests
 
 - Location: `test/device/automated/...`
-- Naming: usually `*.smoke.ts` or `*.integration.ts`
+- Naming: `*.smoke.ts`, `*.integration.ts`, or `*.test.ts` as supported by the device runner
 - Execution: `npm run test:device`
 - Runner behavior: `test/device/index.ts` runs only the automated subtree
 

package/.agents/skills/test-authoring/references/test-authoring-workflow.md

@@ -18,7 +18,8 @@ This usually determines the cheapest useful test type.
 Before writing a new test, inspect tests already covering the same area:
 
 - `test/unit/server/...` for tool registration and response-shape tests
-- `test/unit/interact/...` for handler tests and UI wait behavior
+- `test/unit/interact/...` for service, handler and injected-clock tests
+- `test/unit/quality/...` for structural and architecture rule failure cases
 - `test/unit/manage/...` for build/install flows and fake toolchain binaries
 - `test/unit/observe/...` for observe response contracts
 - `test/unit/utils/...` for shared helper coverage
@@ -44,6 +45,8 @@ For unit tests that need isolation:
 
 Before adding a new hook, search for:
 
+- typed service dependencies under `src/interact/`
+- `Clock` in `src/runtime/clock.ts` for deadlines, stability and retry/backoff tests
 - existing test-only setters/resetters
 - environment-variable based indirection
 - fake executable patterns already used in system/manage tests
@@ -61,12 +64,18 @@ When testing tools or handlers, cover:
 
 ## 6. Validate with repo commands
 
-Use only the existing validation entrypoints:
-
-- `npm run build`
-- `npm run lint`
-- `npm run test:unit`
-- `SKIP_DEVICE_TESTS=1 npm run test:device` for automated device wrappers when real devices are not part of the current validation run
+Run focused tests while iterating, then `npm run verify`. It includes ESLint,
+structural/type checks, ArchUnitTS rules, the build, unit tests and plugin checks.
+Use `npm run check:quality` or `npm run check:architecture` to isolate gate failures;
+see [code structure and quality checks](../../../../docs/code-structure.md).
+
+Run `npm run test:device` when native/runtime behaviour changes. Record each
+platform and journey that ran, and label skipped or unavailable coverage as unrun.
+`SKIP_DEVICE_TESTS=1` is honoured only by individual wrappers, not by the device
+runner as a whole. It neither disables every native test nor establishes device
+coverage; report any skipped checks explicitly.
+For isolated Android interaction coverage, see the
+[fixture instructions](../../../../test/fixtures/debugger-app/README.md).
 
 ## 7. Update docs only when structure or expectations changed
 

package/.agents/skills/test-authoring/references/test-quality-checklist.md

@@ -11,7 +11,7 @@ A new test in this repo is high quality when it does most of the following:
 
 ## Determinism
 
-- does not depend on arbitrary timing unless the behavior is inherently time-based
+- uses injected clocks for timing-dependent services so deadlines and stability can be asserted without real sleeps
 - restores mocks, env vars, and monkeypatches in `finally`
 - avoids leaking state into later tests
 - runs reliably in an isolated subprocess
@@ -27,6 +27,7 @@ A new test in this repo is high quality when it does most of the following:
 - reuses existing helpers, fake-binary patterns, or test seams
 - keeps fixtures as small as possible
 - makes the failure obvious from the assertion message or output
+- uses deliberately broken fixtures for architecture rules, including relevant import forms; an empty or unresolved graph must not count as a pass
 - stays focused on one behavior cluster instead of becoming a broad scenario script
 
 ## Completion bar

package/.github/copilot-instructions.md

@@ -1,40 +1,18 @@
-# Copilot Instructions for mobile-debug-mcp
+# Copilot instructions
 
-## Required workflow
+Read [AGENTS.md](../AGENTS.md) and follow the shared [development
+process](../docs/specs/process.md) before planning, editing, or reviewing changes.
+These instructions also apply to delegated work.
 
-Read and follow [AGENTS.md](../AGENTS.md) and the shared
-[development process](../docs/specs/process.md) before planning, editing, or
-reviewing changes. These are the authoritative repository instructions, including
-for delegated work; the notes below supplement them.
+Use the [contribution guide](../CONTRIBUTING.md) for setup, source layout,
+validation commands, and documentation conventions. The [documentation
+index](../docs/README.md) links to current tool contracts and historical designs.
+Load the applicable [repository skill](../.agents/skills/README.md) before test
+authoring, native tooling work, or specification review.
 
-## Build and Run
-- **Build**: `npm run build` (runs `tsc` to compile TypeScript to `dist/`)
-- **Start**: `npm start` (runs the compiled server at `dist/server.js`)
-- **Dev Workflow**: modify `src/*.ts` -> `npm run build` -> `npm start` to test changes.
+Follow the [module ownership and quality rules](../docs/code-structure.md) when
+changing dependencies or extracting services.
 
-## Architecture
-- **Core**: `src/server.ts` implements the MCP server using `@modelcontextprotocol/sdk`. It handles tool registration and execution.
-- **Platform Modules**:
-  - `src/android.ts`: Encapsulates `adb` commands for Android device interaction.
-  - `src/ios.ts`: Encapsulates `xcrun simctl` commands for iOS simulator interaction.
-- **Types**: `src/types.ts` defines shared interfaces for device info and tool responses.
-
-## Key Conventions
-
-### Tool Implementation
-- **Response Format**: Tools typically return a list of content blocks.
-  - `start_app`: Returns a single text block containing JSON (via `wrapResponse`).
-  - `terminate_app`: Returns a single text block containing JSON (via `wrapResponse`).
-  - `restart_app`: Returns a single text block containing JSON (via `wrapResponse`).
-  - `reset_app_data`: Returns a single text block containing JSON (via `wrapResponse`).
-  - `get_logs`: Returns a text block (JSON metadata) AND a text block (raw logs).
-  - `capture_screenshot`: Returns a text block (JSON metadata) AND an image block (base64 PNG).
-- **Metadata**: Always include a `device` object (platform, id, model, etc.) in the JSON response part.
-
-### External Tools
-- **Android**: Uses `process.env.ADB_PATH` or defaults to `adb`.
-- **iOS**: Uses `process.env.XCRUN_PATH` or defaults to `xcrun`. Assumes a booted simulator.
-- **Execution**: Uses `child_process.exec` for running shell commands.
-
-### Error Handling
-- Tools should catch execution errors and return a user-friendly error message in a `text` content block, rather than crashing the server.
+Follow existing platform adapters, subprocess helpers, error handling, and MCP
+response conventions. Inspect the relevant implementation and tests rather than
+assuming all tools share one response shape or execution strategy.

package/.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
       - name: Install dependencies
         run: npm ci
       - name: Lint
@@ -27,14 +27,14 @@ jobs:
           distribution: 'temurin'
           java-version: '17'
       - name: Compile optional debugger worker
-        run: javac --release 17 --add-modules jdk.jdi -d "$RUNNER_TEMP/mobile-debug-jdi" worker/DebuggerWorker.java
+        run: javac --release 17 --add-modules jdk.jdi -d "$RUNNER_TEMP/mobile-debug-jdi" src/debugger/java/DebuggerWorker.java
       - name: Check debugger package contents
         run: |
           npm pack --dry-run --json > "$RUNNER_TEMP/mobile-debug-package.json"
           node --input-type=module - "$RUNNER_TEMP/mobile-debug-package.json" <<'JS'
           import fs from 'node:fs'
           const files = new Set(JSON.parse(fs.readFileSync(process.argv[2], 'utf8'))[0].files.map(file => file.path))
-          for (const file of ['worker/DebuggerWorker.java', 'dist/debugger/worker.js', 'dist/server/debugger-schema.js']) {
+          for (const file of ['src/debugger/java/DebuggerWorker.java', 'dist/debugger/worker.js', 'dist/debugger/protocol.js', 'dist/runtime/action-results.js', 'dist/server/definitions/input.js', 'dist/server/schemas/debugger-schema.js', 'dist/server/handlers/tool-handlers.js', 'dist/interact/adjustment/adjustment.js', 'dist/interact/targeting/find-element.js', 'dist/interact/waits/ui-wait.js', 'dist/interact/assertions/state-assertion.js', 'dist/observe/network/index.js', 'dist/runtime/clock.js', 'dist/contracts/target.js', 'dist/contracts/execution-controls.js', 'dist/server/handlers/manage.js', 'dist/server/handlers/input.js', 'dist/server/handlers/journey.js']) {
             if (!files.has(file)) throw new Error(`Missing debugger package file: ${file}`)
           }
           JS
@@ -59,7 +59,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
 
       - name: Install dependencies
         run: npm ci

package/AGENTS.md

@@ -21,12 +21,18 @@ instructions take precedence.
 Primary areas:
 
 - `src/server.ts` — runtime entrypoint
-- `src/server-core.ts` — tool registration and dispatch logic
+- `src/server-core.ts` and `src/server/` — MCP registration, capability handlers, schemas and definitions
 - `src/interact/` — tap, swipe, typing, waits, and interaction helpers
 - `src/observe/` — logs, screenshots, UI tree, fingerprints, snapshots
 - `src/manage/` — build, install, start, terminate, restart, reset-app-data
 - `src/system/` — environment and toolchain health checks
+- `src/debugger/` — debugger sessions, protocol and Java worker
 - `src/utils/` — shared helpers and platform-specific utility code
+- `src/contracts/` — shared input shapes and validation
+- `src/runtime/` — action results, traces and injectable clocks
+
+See [code structure and quality checks](docs/code-structure.md) for interaction
+subfolders, module ownership, dependency rules and enforced limits.
 
 ## First things an agent should know
 
@@ -61,7 +67,9 @@ If the task is about **reviewing an RFC or spec draft**, load `.agents/skills/sp
 
 ### Repository docs
 
-- `README.md` — high-level repo overview and commands
+- [README.md](README.md) — project overview and setup
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development, validation, and documentation conventions
+- [Documentation index](docs/README.md) — user guides, designs, and benchmarks
 - `docs/specs/process.md` — required development workflow for all agents
 - `docs/tools/TOOLS.md` — tool documentation and contracts
 - `docs/CHANGELOG.md` — recent behavioral changes
@@ -91,7 +99,8 @@ This file is intentionally short. Keep task-specific guidance in `.agents/skills
 
 - `npm run test:unit` runs every automated unit test under `test/unit/...`
 - `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
-- `npm run verify` runs the default maintainer verification sequence: lint, build, unit tests, and agent-plugin consistency checks
+- `npm run lint` runs ESLint, structural/type limits and ArchUnitTS dependency checks
+- `npm run verify` runs lint, build, unit tests, and agent-plugin consistency checks
 - Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
 
 ## Utility Scripts