mobile-debug-mcp 0.33.0 → 0.35.0

package/docs/specs/013-wait-and-synchronization-reliability/spec.md

@@ -1,14 +1,14 @@
-
-
 # RFC 013 — Wait and Synchronization Reliability
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Status
 
 Draft
 
 ---
 
-# 1. Summary
+## 1. Summary
 
 This RFC introduces deterministic synchronization primitives and snapshot freshness semantics for mobile-debug-mcp.
 
@@ -32,7 +32,7 @@ These capabilities are intended to improve reliability across:
 
 ---
 
-# Relationship to Existing Synchronization Contracts
+## Relationship to Existing Synchronization Contracts
 
 This RFC extends and clarifies the synchronization semantics introduced in RFC003 and the currently shipped synchronization tooling.
 
@@ -58,7 +58,7 @@ It does not invalidate existing synchronization tooling.
 
 ---
 
-# 2. Problem Statement
+## 2. Problem Statement
 
 Current interaction flows rely heavily on immediate post-action reasoning against potentially transient UI state.
 
@@ -93,7 +93,7 @@ This RFC introduces explicit synchronization semantics to address those gaps.
 
 ---
 
-# 3. Goals
+## 3. Goals
 
 The system should:
 
@@ -108,7 +108,7 @@ The system should:
 
 ---
 
-# 4. Non-Goals
+## 4. Non-Goals
 
 This RFC does not attempt to:
 
@@ -122,7 +122,7 @@ This RFC does not attempt to:
 
 ---
 
-# 5. Design Principles
+## 5. Design Principles
 
 ## 5.1 UI-First Synchronization
 
@@ -206,7 +206,7 @@ perform action
 
 ---
 
-# 6. Definitions
+## 6. Definitions
 
 ## Fresh
 
@@ -267,7 +267,7 @@ A synchronization state in which:
 
 ---
 
-# 7. Proposed Capabilities
+## 7. Proposed Capabilities
 
 ## 7.1 wait_for_ui_change
 
@@ -585,7 +585,7 @@ This capability therefore depends on the richer element identity RFC.
 
 ---
 
-# 8. Synchronization Lifecycle Model
+## 8. Synchronization Lifecycle Model
 
 Synchronization should follow a consistent lifecycle.
 
@@ -609,7 +609,7 @@ This lifecycle is intended to standardize synchronization expectations across to
 
 ---
 
-# 9. Agent Guidance and Guardrails
+## 9. Agent Guidance and Guardrails
 
 ## Preferred Flow
 
@@ -650,7 +650,7 @@ Retries should not replace synchronization primitives.
 
 ---
 
-# 10. Failure Modes
+## 10. Failure Modes
 
 ## Infinite Animations
 
@@ -714,7 +714,7 @@ Mitigation:
 
 ---
 
-# 11. Platform Considerations
+## 11. Platform Considerations
 
 ## Android Views
 
@@ -758,7 +758,7 @@ Stabilization windows are especially important.
 
 ---
 
-# 12. Telemetry and Metrics
+## 12. Telemetry and Metrics
 
 The implementation should track:
 
@@ -774,7 +774,7 @@ These metrics should be used to tune convergence heuristics.
 
 ---
 
-# 13. Rollout Strategy
+## 13. Rollout Strategy
 
 ## Phase 1
 
@@ -818,7 +818,7 @@ Introduce:
 
 ---
 
-# 14. Design Closure
+## 14. Design Closure
 
 This specification is fully defined and implementation-ready.
 
@@ -836,7 +836,7 @@ The following areas are fully specified:
 - diff semantics (structural + semantic accessibility only)
 - default synchronization scope (screen)
 
-# 15. Dependencies
+## 15. Dependencies
 
 ## Depends On
 
@@ -855,7 +855,7 @@ The following areas are fully specified:
 
 ---
 
-# 16. Conclusion
+## 16. Conclusion
 
 Reliable synchronization is foundational to deterministic mobile automation.
 

package/docs/specs/014-actionability-resolution/spec.md

@@ -1,12 +1,14 @@
 # RFC 014 — Actionability Resolution
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Status
 
 Draft
 
 ---
 
-# 1. Summary
+## 1. Summary
 
 This RFC defines a deterministic model for resolving whether a UI element is actionable within mobile-debug-mcp.
 
@@ -20,7 +22,7 @@ It builds directly on:
 
 ---
 
-# 2. Relationship to Existing Resolution System (RFC 005 / RFC 007)
+## 2. Relationship to Existing Resolution System (RFC 005 / RFC 007)
 
 This RFC refines, but does not replace, the existing resolution pipeline defined in RFC 005 (Resolved Stage) and RFC 007 (Executable Target Selection).
 
@@ -34,7 +36,7 @@ RFC 014 MUST be applied AFTER RFC 005/007 resolution and BEFORE any interaction
 
 ---
 
-# 3. Problem Statement
+## 3. Problem Statement
 
 Current interaction failures arise when actions are attempted on elements that are:
 
@@ -54,7 +56,7 @@ There is currently no single authoritative model defining when an element is saf
 
 ---
 
-# 4. Goals
+## 4. Goals
 
 The system should:
 
@@ -66,7 +68,7 @@ The system should:
 
 ---
 
-# 5. Non-Goals
+## 5. Non-Goals
 
 This RFC does NOT:
 
@@ -78,7 +80,7 @@ This RFC does NOT:
 
 ---
 
-# 6. Definition: Actionability
+## 6. Definition: Actionability
 
 An element is considered **actionable** if ALL of the following conditions are satisfied:
 
@@ -122,7 +124,7 @@ If identity cannot be resolved consistently across snapshots, the element MUST b
 
 ---
 
-# 7. Actionability Evaluation Model (Runtime Contract)
+## 7. Actionability Evaluation Model (Runtime Contract)
 
 Actionability is evaluated using runtime-provided fields from the resolved element and snapshot system.
 
@@ -222,7 +224,7 @@ Short-circuit evaluation is permitted for performance but MUST NOT change final
 
 ---
 
-# 8. Resolution Lifecycle
+## 8. Resolution Lifecycle
 
 Actionability MUST be evaluated in the following sequence:
 
@@ -238,7 +240,7 @@ If any step fails, the element MUST be considered non-actionable.
 
 ---
 
-# 9. Interaction Guardrail
+## 9. Interaction Guardrail
 
 Actions MUST NOT be executed unless actionability resolution returns true.
 
@@ -250,7 +252,7 @@ If actionability is false:
 
 ---
 
-# 10. Failure Modes
+## 10. Failure Modes
 
 ## 10.1 Transient Non-Actionability
 
@@ -293,7 +295,7 @@ Mitigation:
 
 ---
 
-# 11. Platform Considerations
+## 11. Platform Considerations
 
 ## Android
 
@@ -307,7 +309,7 @@ Mitigation:
 
 ---
 
-# 12. Integration with RFC 013
+## 12. Integration with RFC 013
 
 Actionability Resolution depends on:
 
@@ -318,7 +320,7 @@ It MUST NOT evaluate elements from unstable snapshots.
 
 ---
 
-# 13. Telemetry
+## 13. Telemetry
 
 Systems SHOULD track:
 
@@ -329,7 +331,7 @@ Systems SHOULD track:
 
 ---
 
-# 14. Rollout Strategy
+## 14. Rollout Strategy
 
 ## Phase 1
 
@@ -347,7 +349,7 @@ The shipped interaction layer now applies iOS semantic tap eligibility in additi
 
 ---
 
-# 15. Dependencies
+## 15. Dependencies
 
 ## Depends On
 
@@ -357,7 +359,7 @@ The shipped interaction layer now applies iOS semantic tap eligibility in additi
 
 ---
 
-# 15.1 Acceptance Criteria
+## 15.1 Acceptance Criteria
 
 An implementation of RFC 014 is considered correct if:
 
@@ -368,7 +370,7 @@ An implementation of RFC 014 is considered correct if:
 - All failures produce a defined failure code
 - Actionability is only evaluated AFTER RFC 005/007 resolution
 
-# 16. Failure Codes (Actionability Gate)
+## 16. Failure Codes (Actionability Gate)
 
 ## Failure Code Derivation Matrix
 
@@ -387,7 +389,7 @@ These are the only supported actionability failure codes.
 
 Implementations SHOULD return the structured code together with a human-readable reason.
 
-# 17. Conclusion
+## 17. Conclusion
 
 Actionability Resolution provides the final gate before UI interaction execution.
 

package/docs/specs/015-adjustable-control-support/spec.md

@@ -1,5 +1,7 @@
 # Spec: Adjustable Control Support
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Purpose
 
 Provide a deterministic, semantic interface for interacting with adjustable controls (such as sliders, steppers and other value-based controls) without relying primarily on coordinate manipulation.
@@ -8,7 +10,7 @@ The goal is to allow agents to request a target value rather than perform low-le
 
 ---
 
-# Rationale
+## Rationale
 
 Adjustable controls are common throughout modern mobile applications, but they remain one of the least reliable interaction types for autonomous agents.
 
@@ -25,7 +27,7 @@ This specification introduces a semantic adjustment model where agents request t
 
 ---
 
-# Goals
+## Goals
 
 The implementation shall:
 
@@ -38,7 +40,7 @@ The implementation shall:
 
 ---
 
-# Non-Goals
+## Non-Goals
 
 This specification does not:
 
@@ -50,7 +52,7 @@ This specification does not:
 
 ---
 
-# Supported Controls
+## Supported Controls
 
 Initial scope includes:
 
@@ -66,7 +68,7 @@ All supported controls must expose or deterministically parse into a numeric val
 
 ---
 
-# Runtime Interface
+## Runtime Interface
 
 The public tool contract remains the existing `adjust_control` operation.
 
@@ -134,7 +136,7 @@ These changes require corresponding updates to the existing `adjust_control` imp
 
 ---
 
-# Preconditions
+## Preconditions
 
 Before execution the following conditions must be satisfied:
 
@@ -148,7 +150,7 @@ If any precondition fails, execution shall terminate without attempting adjustme
 
 ---
 
-# Execution Model
+## Execution Model
 
 ## Phase 1 — Resolve
 
@@ -261,7 +263,7 @@ return CONTROL_CONVERGENCE_FAILED
 
 ---
 
-# Strategy Detection
+## Strategy Detection
 
 Strategy selection is deterministic and platform-specific.
 
@@ -353,7 +355,7 @@ The implementation shall use the existing coordinate gesture primitive and then
 
 ---
 
-# Value Domains and Normalization
+## Value Domains and Normalization
 
 The initial public contract is numeric.
 
@@ -425,7 +427,7 @@ The implementation shall not silently clamp an out-of-range request unless the e
 
 ---
 
-# Failure Modes
+## Failure Modes
 
 The implementation shall use existing runtime error codes.
 
@@ -440,7 +442,7 @@ The implementation shall not introduce new public failure codes for this capabil
 
 ---
 
-# Acceptance Criteria
+## Acceptance Criteria
 
 The implementation is complete when all of the following automated fixtures or smoke scenarios pass on each supported platform.
 
@@ -487,7 +489,7 @@ For every failed fixture:
 
 ---
 
-# Dependencies
+## Dependencies
 
 Depends on:
 
@@ -504,7 +506,7 @@ Strengthens:
 
 ---
 
-# Future Work
+## Future Work
 
 The following capabilities are intentionally excluded from this specification:
 
@@ -519,7 +521,7 @@ These are covered by the **Adjustable Control Precision Hardening** specificatio
 
 ---
 
-# Determinism Requirements
+## Determinism Requirements
 
 Given identical:
 
@@ -538,4 +540,4 @@ Execution shall not rely on:
 - hidden mutable state
 - undefined platform behaviour
 
----
+---

package/docs/specs/016-environment-tools/spec.md

@@ -1,7 +1,7 @@
-
-
 # Specification 016 — Environment Auto-Configuration and Toolchain Discovery
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Purpose
 
 Enable the Mobile Debug MCP to automatically discover, validate, and configure its required platform toolchains, reducing manual setup while maintaining deterministic behaviour.
@@ -10,7 +10,7 @@ The MCP should work out of the box on a standard development machine whenever th
 
 ---
 
-# Goals
+## Goals
 
 - Eliminate manual executable path configuration for standard installations.
 - Automatically discover Android and iOS toolchains.
@@ -21,7 +21,7 @@ The MCP should work out of the box on a standard development machine whenever th
 
 ---
 
-# Non-Goals
+## Non-Goals
 
 This specification does not:
 
@@ -33,7 +33,7 @@ This specification does not:
 
 ---
 
-# Supported Host Matrix
+## Supported Host Matrix
 
 | Host OS | Android discovery | iOS discovery | Expected behaviour |
 |---|---:|---:|---|
@@ -57,7 +57,7 @@ iOS discovery shall only run on macOS. On Linux and Windows, iOS status shall be
 }
 ```
 
-# Scope
+## Scope
 
 ## Android
 
@@ -87,7 +87,7 @@ iOS discovery shall only run on macOS. On Linux and Windows, iOS status shall be
 
 ---
 
-# Runtime Behaviour
+## Runtime Behaviour
 
 Toolchain discovery and validation shall be available through `get_system_status`.
 
@@ -109,7 +109,7 @@ The server shall not fail simply because one platform is unavailable.
 
 ---
 
-# Discovery Priority
+## Discovery Priority
 
 Every executable and toolchain root shall be resolved using the following deterministic order.
 
@@ -136,7 +136,7 @@ If multiple supported overrides are present for the same concern, the order show
 
 An explicitly configured path that does not exist, is not executable, or fails validation shall not silently fall back to automatic discovery. It shall return a structured failure so configuration errors remain visible and deterministic.
 
-# Tool Version Policy
+## Tool Version Policy
 
 Version validation shall be deterministic and tool-specific.
 
@@ -157,7 +157,7 @@ When a version string cannot be parsed, the tool shall return `TOOL_VERSION_UNSU
 
 ---
 
-# Capability Detection
+## Capability Detection
 
 Discovery shall determine available capabilities rather than simply locating executables.
 
@@ -185,7 +185,7 @@ iOS capabilities may include:
 
 Agents shall not need to know which underlying provider implements a capability.
 
-# Provider Selection
+## Provider Selection
 
 Multiple providers may satisfy the same capability.
 
@@ -214,7 +214,7 @@ A platform may be partially ready when only a subset of capabilities has an avai
 
 ---
 
-# Environment Validation
+## Environment Validation
 
 Validation shall confirm:
 
@@ -233,7 +233,7 @@ Examples:
 - `xcrun` and `simctl` available with no booted simulator: iOS toolchain ready, device-dependent capabilities unavailable until a simulator is booted or device is connected.
 - `adb` available with no connected device: Android toolchain ready, device-dependent capabilities unavailable until a device or emulator is connected.
 
-# Diagnostic Contract
+## Diagnostic Contract
 
 All discovery and validation failures shall use the following shape:
 
@@ -276,7 +276,7 @@ Raw shell errors may be recorded internally for diagnostics, but shall not be ex
 
 ---
 
-# Partial Availability
+## Partial Availability
 
 Platform readiness shall be reported independently.
 
@@ -295,7 +295,7 @@ A platform status shall be one of:
 - `unavailable`
 - `unsupported`
 
-# Runtime Introspection
+## Runtime Introspection
 
 `get_system_status` shall expose the environment summary using this minimum structure:
 
@@ -401,7 +401,7 @@ Each capability entry shall include:
 
 ---
 
-# Compatibility
+## Compatibility
 
 This specification extends the existing `get_system_status` surface additively.
 
@@ -429,7 +429,7 @@ Environment variables become optional overrides rather than mandatory configurat
 
 ---
 
-# Failure Modes
+## Failure Modes
 
 The implementation shall return deterministic setup failures including:
 
@@ -455,7 +455,7 @@ Failure selection rules:
 
 ---
 
-# Acceptance Criteria
+## Acceptance Criteria
 
 The implementation is complete when all of the following are true.
 
@@ -521,7 +521,7 @@ The implementation is complete when all of the following are true.
 
 ---
 
-# Future Work
+## Future Work
 
 Potential future enhancements include:
 
@@ -530,4 +530,4 @@ Potential future enhancements include:
 - Toolchain health monitoring.
 - Self-healing actions such as restarting adb, reconnecting devices, or refreshing simulator state.
 - Installation guidance and package manager integration.
-- Configurable version policies for enterprise environments.
+- Configurable version policies for enterprise environments.

package/docs/specs/018-interaction-latency-and-batched-journeys/spec.md

@@ -1,5 +1,7 @@
 # RFC 018 — Interaction Latency, Verification Modes, and Batched Journeys
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Status
 
 Implemented; Android and iOS device validation passed.

package/docs/specs/019-ui-tree-observation-performance/spec.md

@@ -1,10 +1,12 @@
 # Specification 019 — UI-Tree Observation Performance
 
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md)
+
 ## Status
 
 Implemented for Android with a paired emulator benchmark. iOS correctness has
 unit and simulator smoke coverage; iOS latency remains unmeasured. See
-`docs/benchmarks/ui-tree-performance/` for the initial baseline, paired reports,
+[benchmark guide](../../benchmarks/ui-tree-performance/README.md) for the paired reports,
 and the retained failed first comparison attempt.
 
 ## 1. Summary

package/docs/specs/020-conditional-actions/intent.md

@@ -1,6 +1,8 @@
 # Intent: conditional actions
 
-Originator: repository maintainer (user in the current conversation).
+[Design and evidence](../../README.md#design-and-evidence) · [Tool reference](../../tools/TOOLS.md) · [Specification](spec.md) · [Plan and verification](plan.md)
+
+Originator: repository maintainer (design review).
 Date: 2026-10-29.
 Status: approved.
 
@@ -9,7 +11,7 @@ Status: approved.
 “Conditional actions: Check expected state immediately before acting; stop and
 return fresh evidence if it changed.”
 
-Source: user request in the current conversation, following adoption of the
+Source: user request during design review, following adoption of the
 repository development process.
 
 ## Desired outcome
@@ -57,6 +59,6 @@ state observation, and Android/iOS adapters for supported actions.
 
 ## Approval
 
-Approved by the originator in the current conversation on 2026-10-29: “yes”,
+Approved by the originator during design review on 2026-10-29: “yes”,
 in direct response to the complete intent summary and linked artifact. Approval
 covers the captured intent; specification approval remains a separate gate.