mobile-debug-mcp 0.34.0 → 0.36.0

package/dist/utils/cli/ios/preflight-ios.js

@@ -22,11 +22,10 @@ async function findFirst(root, patterns, maxDepth = 4) {
             console.error('DEBUG findFirst: entries', ents.map(e => e.name));
             for (const e of ents) {
                 const full = path.join(dir, e.name);
-                for (const p of patterns) {
-                    if (e.name.endsWith(p)) {
-                        console.error('DEBUG findFirst: matched', full);
-                        return full;
-                    }
+                const matched = patterns.some(pattern => e.name.endsWith(pattern));
+                if (matched) {
+                    console.error('DEBUG findFirst: matched', full);
+                    return full;
                 }
                 if (e.isDirectory() && depth < maxDepth)
                     queue.push({ dir: full, depth: depth + 1 });
@@ -52,26 +51,7 @@ function startCompanionIfNeeded(companionPath, udid) {
     }
 }
 async function main() {
-    const args = process.argv.slice(2);
-    let projectArg;
-    let udid;
-    let startCompanion = false;
-    let kmpBuild = null;
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        if (a === '--project' && args[i + 1]) {
-            projectArg = args[i + 1];
-            i++;
-        }
-        else if (a === '--udid' && args[i + 1]) {
-            udid = args[i + 1];
-            i++;
-        }
-        else if (a === '--start-companion')
-            startCompanion = true;
-        else if (!projectArg)
-            projectArg = a;
-    }
+    const { projectArg, udid, startCompanion, kmpBuild } = argumentsForPreflight(process.argv.slice(2));
     const cwd = process.cwd();
     const projectRoot = projectArg ? path.resolve(projectArg) : cwd;
     // If user passed a direct .xcodeproj or .xcworkspace path, accept it as the projectFile
@@ -108,15 +88,8 @@ async function main() {
     // 4) idb_companion
     const companionPath = commandWhich('idb_companion');
     const companionAvailable = !!companionPath;
-    const suggestions = [];
-    if (!projectFile)
-        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
-    if (!kmpFramework)
-        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
-    if (!idbAvailable)
-        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
-    if (!companionAvailable)
-        suggestions.push('Install idb_companion and ensure it is in PATH');
+    const suggestions = preflightSuggestions(projectFile, kmpFramework, idbAvailable, companionAvailable);
+    const companionInfo = { cmd: companionPath, installed: companionAvailable };
     const result = {
         ok: !!projectFile && !!idbAvailable,
         project: {
@@ -133,10 +106,7 @@ async function main() {
             cmd: idbPath,
             installed: idbAvailable
         },
-        idb_companion: {
-            cmd: companionPath,
-            installed: companionAvailable
-        },
+        idb_companion: companionInfo,
         suggestions
     };
     if (startCompanion && udid) {
@@ -153,3 +123,37 @@ main().catch(e => {
     console.log(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }, null, 2));
     process.exit(2);
 });
+function argumentsForPreflight(args) {
+    let projectArg;
+    let udid;
+    let startCompanion = false;
+    const kmpBuild = null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--project' && args[i + 1]) {
+            projectArg = args[i + 1];
+            i++;
+        }
+        else if (a === '--udid' && args[i + 1]) {
+            udid = args[i + 1];
+            i++;
+        }
+        else if (a === '--start-companion')
+            startCompanion = true;
+        else if (!projectArg)
+            projectArg = a;
+    }
+    return { projectArg, udid, startCompanion, kmpBuild };
+}
+function preflightSuggestions(projectFile, kmpFramework, idbAvailable, companionAvailable) {
+    const suggestions = [];
+    if (!projectFile)
+        suggestions.push('Provide correct project path or ensure .xcodeproj/.xcworkspace exists in project dir');
+    if (!kmpFramework)
+        suggestions.push('Run KMP Gradle task to produce Shared.framework before xcodebuild (e.g., :shared:embedAndSignAppleFrameworkForXcode)');
+    if (!idbAvailable)
+        suggestions.push('Ensure idb is in PATH or set MCP_IDB_PATH / IDB_PATH');
+    if (!companionAvailable)
+        suggestions.push('Install idb_companion and ensure it is in PATH');
+    return suggestions;
+}

package/dist/utils/ios/utils.js

@@ -1,3 +1,4 @@
+import { checkDebuggerGuard } from '../../debugger/guard.js';
 import { remainingBudget } from '../operation-budget.js';
 import { execFile, spawn, execSync, spawnSync } from "child_process";
 import { promises as fsPromises } from 'fs';
@@ -19,16 +20,14 @@ export function getConfiguredIdbPath() {
             if (!p)
                 continue;
             try {
-                if (fs.existsSync(p)) {
-                    const raw = fs.readFileSync(p, 'utf8');
-                    const json = JSON.parse(raw);
-                    if (json) {
-                        if (json.idbPath)
-                            return json.idbPath;
-                        if (json.IDB_PATH)
-                            return json.IDB_PATH;
-                    }
-                }
+                if (!fs.existsSync(p))
+                    continue;
+                const raw = fs.readFileSync(p, 'utf8');
+                const json = JSON.parse(raw);
+                if (json?.idbPath)
+                    return json.idbPath;
+                if (json?.IDB_PATH)
+                    return json.IDB_PATH;
             }
             catch { }
         }
@@ -96,6 +95,7 @@ export function execCommand(args, deviceId = "booted") {
     return new Promise((resolve, reject) => {
         // Use spawn for better stream control and consistency with Android implementation
         const budgetMs = remainingBudget();
+        checkDebuggerGuard();
         const child = spawn(getXcrunCmd(), args);
         let stdout = '';
         let stderr = '';
@@ -137,6 +137,7 @@ export function execCommandWithDiagnostics(args, deviceId = "booted") {
     const DEFAULT_XCRUN_LOG_TIMEOUT = parseInt(process.env.MCP_XCRUN_LOG_TIMEOUT || '', 10) || 30000;
     const DEFAULT_XCRUN_CMD_TIMEOUT = parseInt(process.env.MCP_XCRUN_TIMEOUT || '', 10) || 60000;
     const timeoutMs = budgetMs || (args.includes('log') ? DEFAULT_XCRUN_LOG_TIMEOUT : DEFAULT_XCRUN_CMD_TIMEOUT);
+    checkDebuggerGuard();
     const res = spawnSync(getXcrunCmd(), args, { encoding: 'utf8', timeout: timeoutMs });
     const runResult = {
         exitCode: typeof res.status === 'number' ? res.status : null,
@@ -214,18 +215,18 @@ export async function getIOSDeviceMetadata(deviceId = "booted") {
                 const devicesMap = data.devices || {};
                 for (const runtime in devicesMap) {
                     const devices = devicesMap[runtime];
-                    if (Array.isArray(devices)) {
-                        for (const device of devices) {
-                            if (deviceId === "booted" || device.udid === deviceId) {
-                                resolve({
-                                    platform: "ios",
-                                    id: device.udid,
-                                    osVersion: parseRuntimeName(runtime),
-                                    model: device.name,
-                                    simulator: true,
-                                });
-                                return;
-                            }
+                    if (!Array.isArray(devices))
+                        continue;
+                    for (const device of devices) {
+                        if (deviceId === "booted" || device.udid === deviceId) {
+                            resolve({
+                                platform: "ios",
+                                id: device.udid,
+                                osVersion: parseRuntimeName(runtime),
+                                model: device.name,
+                                simulator: true,
+                            });
+                            return;
                         }
                     }
                 }
@@ -257,36 +258,37 @@ export async function listIOSDevices(appId) {
                             const bmap = bdata.devices || {};
                             for (const rt in bmap) {
                                 const devs = bmap[rt];
-                                if (Array.isArray(devs))
-                                    for (const d of devs)
-                                        bootedSet.add(d.udid);
+                                if (!Array.isArray(devs))
+                                    continue;
+                                for (const d of devs)
+                                    bootedSet.add(d.udid);
                             }
                         }
                         catch { }
                     }
                     for (const runtime in devicesMap) {
                         const devices = devicesMap[runtime];
-                        if (Array.isArray(devices)) {
-                            for (const device of devices) {
-                                const info = {
-                                    platform: 'ios',
-                                    id: device.udid,
-                                    osVersion: parseRuntimeName(runtime),
-                                    model: device.name,
-                                    simulator: true,
-                                    booted: bootedSet.has(device.udid)
-                                };
-                                if (appId) {
-                                    // check if installed
-                                    const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
-                                        .then(() => { info.appInstalled = true; })
-                                        .catch(() => { info.appInstalled = false; })
-                                        .then(() => { out.push(info); });
-                                    checks.push(p);
-                                }
-                                else {
-                                    out.push(info);
-                                }
+                        if (!Array.isArray(devices))
+                            continue;
+                        for (const device of devices) {
+                            const info = {
+                                platform: 'ios',
+                                id: device.udid,
+                                osVersion: parseRuntimeName(runtime),
+                                model: device.name,
+                                simulator: true,
+                                booted: bootedSet.has(device.udid)
+                            };
+                            if (appId) {
+                                // check if installed
+                                const p = execCommand(['simctl', 'get_app_container', device.udid, appId, 'data'], device.udid)
+                                    .then(() => { info.appInstalled = true; })
+                                    .catch(() => { info.appInstalled = false; })
+                                    .then(() => { out.push(info); });
+                                checks.push(p);
+                            }
+                            else {
+                                out.push(info);
                             }
                         }
                     }

package/dist/utils/java.js

@@ -39,27 +39,9 @@ export async function detectJavaHome(options = {}) {
             }
             debug('[java.detect] ANDROID_STUDIO_JDK present but java -version did not match expected versions');
         }
-        // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
-        const jbrCandidates = [
-            '/Applications/Android Studio.app/Contents/jbr',
-            '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview.app/Contents/jbr',
-            '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
-            '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
-        ];
-        for (const p of jbrCandidates) {
-            const javaBin = path.join(p, 'bin', 'java');
-            if (existsSync(javaBin)) {
-                const v = javaVersionOf(javaBin);
-                if (isJavaVersionAcceptable(v)) {
-                    debug('[java.detect] Found Android Studio JBR at:', p);
-                    return p;
-                }
-            }
-        }
+        const jbr = findStudioJava(debug);
+        if (jbr)
+            return jbr;
         // 3) If JAVA_HOME set, validate it (accept 17 or 21)
         if (process.env.JAVA_HOME) {
             try {
@@ -96,40 +78,74 @@ export async function detectJavaHome(options = {}) {
         catch (e) {
             debug('[java.detect] /usr/libexec/java_home -v 21 failed: ' + String(e));
         }
-        // 6) macOS common JDK locations
-        try {
-            const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
-            for (const h of homes) {
-                if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
-                    const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
-                    return candidate;
-                }
+        const commonHome = findMacJavaHome(debug);
+        if (commonHome)
+            return commonHome;
+        return findLinuxJavaHome(debug);
+    }
+    catch (e) {
+        debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+    }
+    return undefined;
+}
+function findStudioJava(debug) {
+    // 2) Android Studio JBR candidates (prefer these over JAVA_HOME)
+    const jbrCandidates = [
+        '/Applications/Android Studio.app/Contents/jbr',
+        '/Applications/Android Studio.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview.app/Contents/jbr',
+        '/Applications/Android Studio Preview.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview 2022.3.app/Contents/jbr',
+        '/Applications/Android Studio Preview 2022.3.app/Contents/jbr/Contents/Home',
+        '/Applications/Android Studio Preview 2023.1.app/Contents/jbr',
+        '/Applications/Android Studio Preview 2023.1.app/Contents/jbr/Contents/Home'
+    ];
+    for (const p of jbrCandidates) {
+        const javaBin = path.join(p, 'bin', 'java');
+        if (existsSync(javaBin)) {
+            const v = javaVersionOf(javaBin);
+            if (isJavaVersionAcceptable(v)) {
+                debug('[java.detect] Found Android Studio JBR at:', p);
+                return p;
             }
         }
-        catch (e) {
-            debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
-        }
-        // 7) Linux locations
-        const linuxCandidates = [
-            '/usr/lib/jvm/java-17-openjdk-amd64',
-            '/usr/lib/jvm/java-17-openjdk',
-            '/usr/lib/jvm/zulu17',
-            '/usr/lib/jvm/temurin-17-jdk',
-            '/usr/lib/jvm/temurin-21-jdk',
-            '/usr/lib/jvm/java-21-openjdk-amd64'
-        ];
-        for (const p of linuxCandidates) {
-            try {
-                if (existsSync(p))
-                    return p;
-            }
-            catch (e) {
-                debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+    }
+    return undefined;
+}
+function findMacJavaHome(debug) {
+    // 6) macOS common JDK locations
+    try {
+        const homes = execSync('ls -1 /Library/Java/JavaVirtualMachines || true', { stdio: ['ignore', 'pipe', 'inherit'] }).toString().split(/\r?\n/).filter(Boolean);
+        for (const h of homes) {
+            if (h.toLowerCase().includes('17') || h.toLowerCase().includes('jdk-17') || h.toLowerCase().includes('21') || h.toLowerCase().includes('jdk-21')) {
+                const candidate = `/Library/Java/JavaVirtualMachines/${h}/Contents/Home`;
+                return candidate;
             }
         }
     }
     catch (e) {
-        debug('[java.detect] error detecting java home:', e instanceof Error ? e.message : String(e));
+        debug('[java.detect] listing /Library/Java/JavaVirtualMachines failed: ' + String(e));
+    }
+    return undefined;
+}
+function findLinuxJavaHome(debug) {
+    // 7) Linux locations
+    const linuxCandidates = [
+        '/usr/lib/jvm/java-17-openjdk-amd64',
+        '/usr/lib/jvm/java-17-openjdk',
+        '/usr/lib/jvm/zulu17',
+        '/usr/lib/jvm/temurin-17-jdk',
+        '/usr/lib/jvm/temurin-21-jdk',
+        '/usr/lib/jvm/java-21-openjdk-amd64'
+    ];
+    for (const p of linuxCandidates) {
+        try {
+            if (existsSync(p))
+                return p;
+        }
+        catch (e) {
+            debug(`[java.detect] checking linux candidate ${p} failed: ${String(e)}`);
+        }
     }
     return undefined;
 }

package/dist/utils/resolve-device.js

@@ -66,6 +66,9 @@ async function resolveDevice(opts) {
             throw new Error(`Device '${deviceId}' not found for platform ${platform}`);
         return found;
     }
+    return selectDevice(devices, platform, appId, prefer);
+}
+function selectDevice(devices, platform, appId, prefer) {
     let candidates = devices.slice();
     if (prefer === "physical")
         candidates = candidates.filter(d => !d.simulator);
@@ -99,8 +102,7 @@ async function resolveDevice(opts) {
             return candidates[0];
         }
         const list = candidates.map(d => ({ id: d.id, platform: d.platform, osVersion: d.osVersion, model: d.model, simulator: d.simulator, appInstalled: d.appInstalled }));
-        const err = new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`);
-        err.devices = list;
+        const err = Object.assign(new Error(`Multiple matching devices found: ${JSON.stringify(list, null, 2)}`), { devices: list });
         throw err;
     }
     throw new Error(`No devices found for platform ${platform}`);

package/dist/utils/ui/index.js

@@ -73,36 +73,11 @@ export function computeScreenFingerprint(tree, current, platform, limit = 50) {
 }
 export async function scrollToElementShared(opts) {
     const { selector, direction = 'down', maxScrolls = 10, scrollAmount = 0.7, deviceId, fetchTree, swipe, stabilizationDelayMs = 350 } = opts;
-    const matchElement = (el) => {
-        if (!el)
-            return false;
-        if (selector.text !== undefined && selector.text !== el.text)
-            return false;
-        if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
-            return false;
-        if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
-            return false;
-        if (selector.className !== undefined && selector.className !== el.type)
-            return false;
-        return true;
-    };
-    const isVisible = (el, resolution) => {
-        if (!el)
-            return false;
-        if (el.visible === false)
-            return false;
-        if (!el.bounds || !resolution || !resolution.width || !resolution.height)
-            return (el.visible === undefined ? true : !!el.visible);
-        const [left, top, right, bottom] = el.bounds;
-        const withinY = bottom > 0 && top < resolution.height;
-        const withinX = right > 0 && left < resolution.width;
-        return withinX && withinY;
-    };
     const findVisibleMatch = (elements, resolution) => {
         if (!Array.isArray(elements))
             return null;
         for (const e of elements) {
-            if (matchElement(e) && isVisible(e, resolution))
+            if (matchElement(selector, e) && isVisible(e, resolution))
                 return e;
         }
         return null;
@@ -169,3 +144,28 @@ export async function scrollToElementShared(opts) {
     }
     return { success: false, reason: 'Element not found after scrolling', scrollsPerformed: scrollsPerformed };
 }
+function matchElement(selector, el) {
+    if (!el)
+        return false;
+    if (selector.text !== undefined && selector.text !== el.text)
+        return false;
+    if (selector.resourceId !== undefined && selector.resourceId !== el.resourceId)
+        return false;
+    if (selector.contentDesc !== undefined && selector.contentDesc !== el.contentDescription)
+        return false;
+    if (selector.className !== undefined && selector.className !== el.type)
+        return false;
+    return true;
+}
+function isVisible(el, resolution) {
+    if (!el)
+        return false;
+    if (el.visible === false)
+        return false;
+    if (!el.bounds || !resolution || !resolution.width || !resolution.height)
+        return (el.visible === undefined ? true : !!el.visible);
+    const [left, top, right, bottom] = el.bounds;
+    const withinY = bottom > 0 && top < resolution.height;
+    const withinX = right > 0 && left < resolution.width;
+    return withinX && withinY;
+}

package/docs/CHANGELOG.md

@@ -1,8 +1,74 @@
 # Changelog
 
+[Documentation](README.md)
+
+Entries describe their release at the time it was recorded. Historical source
+paths and commands may have moved; use the [contribution guide](../CONTRIBUTING.md)
+and [tool reference](tools/TOOLS.md) for the current checkout.
+
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
-## Unreleased
+## [0.36.0]
+
+- Updated the agent plugin to `0.0.6`, pinned to MCP `0.36.0`.
+
+- Add an optional iOS simulator LLDB backend to the existing debugger tools,
+  including exact source-file breakpoints, bounded static inspection, stepping,
+  platform-scoped pause guards and owned cleanup. A separate Swift concurrency
+  fixture checks inspection around await, cancellation and recovery; verification
+  coverage is recorded in specification 032. Physical iOS devices remain unsupported.
+
+- Preserve iOS trace capture through isolated monitoring command failures; require
+  three consecutive non-definitive failures before discarding, while identity and
+  storage failures remain immediate and capture expiry still reconciles.
+
+- Add optional iOS simulator Time Profiler capture through Instruments, with explicit
+  device/app targeting, recording-start notification, local `.trace` validation,
+  journey evidence linkage and owned cleanup. Physical devices and other templates
+  remain unsupported in the initial matrix. Android tracing retains its preset.
+
+
+- Added plugin `0.0.5` Antigravity compatibility and a standalone distribution
+  export. Generated a Cursor-native package for its supported path variables,
+  and checked/refined installation instructions for all four clients.
+
+## [0.35.0]
+
+- Updated the agent plugin to `0.0.4`, pinned to MCP `0.35.0`.
+
+- Added an opt-in isolated Android coroutine debugger assessment fixture for
+  suspension, dispatcher changes, nested work, stepping and cancellation, with
+  explicit local dependencies. This does not add coroutine reconstruction.
+- Added an opt-in isolated Kotlin debugger validation journey for named locals
+  before/after assignment, compiler scope tables, stale references and app recovery.
+  This adds evidence and regression coverage without changing debugger behaviour.
+- Added opt-in debugger `responseMode: "compact"` to omit repeated target metadata
+  from routine commands while retaining diagnostics, execution state and cleanup.
+  Existing full responses remain the default; discovery and state stay complete.
+- Android debugger failures now include bounded, sanitized stage/reason diagnostics
+  and static recovery guidance while preserving error codes. Capability probes
+  report ordered prerequisite diagnostics; terminal summaries retain failure evidence.
+  Raw stderr, exception messages and app locals are excluded from diagnostics.
+
+- **Runtime requirement:** Node.js 22 or newer is now required. Updated Sharp,
+  Zod and transitive dependencies to clear the dependency audit findings; CI
+  configuration now uses Node 22. Public tool definitions remain unchanged.
+- Split observation, snapshot, iOS build, Android utility and system diagnostic
+  responsibilities into typed services. Removed all 136 legacy quality exceptions;
+  production source meets the default size, complexity, nesting and explicit-any
+  limits. Added screenshot encoding and snapshot log normalization regressions.
+
+- Split server handlers by capability, share target/execution-control contracts, and inject clocks into interaction polling services while preserving tool contracts. Added deterministic timing tests and an Android labelled-slider convergence journey.
+
+- Added ArchUnitTS architecture checks to lint and CI for shared contracts, server boundaries, pure interaction calculations and runtime dependency cycles. Negative controls cover NodeNext resolution, aliases, dynamic imports and re-exports.
+
+- Group interaction services by adjustment, targeting, waits and assertions; separate server schemas and handlers, and place log-derived network observations under `observe/network`. Tool contracts and behaviour are unchanged.
+
+- Reduced `ToolsInteract` to a typed composition facade within the enforced class budget. Extracted adjustment, candidate resolution, synchronization and assertion services without new legacy exceptions, and added an isolated Android interaction journey plus a permanent default-budget regression check.
+
+- Added code-quality gates to lint and CI for source/class/function size, complexity, nesting, explicit `any`, and interaction/runtime import boundaries. Legacy exceptions have per-symbol ceilings that cannot grow unnoticed.
+- Extracted typed UI/control helpers, bounded handle storage, action-result construction and capability-specific tool definitions; clarified and typed debugger session operations and worker protocol messages while retaining public tool contracts.
+- Fixed the debugger device check to fingerprint Java sources in `src/debugger/java/` after the worker relocation.
 
 ## [0.34.0]
 - Added optional Android JDI runtime debugging: explicit device/process attach, source breakpoints/events, bounded stacks and shallow locals, stepping/resume, stale-reference rejection, pause-aware UI guards/readiness, expiry and owned detach/cleanup. Requires a host JDK 17+ and a running debuggable app; evaluation, mutation, native/coroutine and iOS debugging remain unsupported.

package/docs/README.md

@@ -0,0 +1,38 @@
+# Documentation
+
+Mobile Debug MCP provides tools for building, controlling, and inspecting Android
+and iOS apps. Start with the [project README](../README.md) for requirements,
+installation, and client configuration.
+
+## Choose a starting point
+
+- **New to the server?** See the [project overview and installation options](../README.md#start-here).
+- **Looking up a tool?** Use the [tool reference](tools/TOOLS.md) for inputs,
+  responses, examples, and shared interaction principles.
+- **Troubleshooting setup?** Check [environment diagnostics](tools/system.md) and
+  the [tool path settings](../README.md#environment-setup).
+- **Investigating an app failure?** Start with [observations](tools/observe.md)
+  and [evidence correlation](tools/correlated-evidence.md). For deeper Android
+  investigation, use [system traces](tools/system-traces.md) or the
+  [runtime debugger](tools/debugger.md).
+- **Installing a client plugin?** See [client installation](../README.md#agent-plugin)
+  and the [plugin guide](../agent-plugin/README.md) for packaging and versioning.
+
+## Contributing
+
+- [Contribution guide](../CONTRIBUTING.md): local setup, validation, and documentation conventions.
+- [Code structure and quality checks](code-structure.md): module ownership, enforced limits, and existing debt.
+- [Development process](specs/process.md): maintenance and feature workflows.
+- [Agent entrypoint](../AGENTS.md) and [repository skills](../.agents/skills/README.md).
+
+## Design and evidence
+
+- [Design records](specs/): feature intent, specifications, and dated verification
+  records, grouped by feature.
+- [Changelog](CHANGELOG.md): release history.
+- [Benchmark index](benchmarks/README.md): reproducible performance checks and recorded limits.
+
+The tool reference describes the current checkout. Specifications record design
+intent and may contain earlier contracts; approval alone does not establish that
+a feature shipped. Verification records describe the named build and environment,
+not every supported platform or the currently published npm package.

package/docs/agent-plugin-installation-verification.md

@@ -0,0 +1,39 @@
+# Agent plugin installation verification
+
+Checked 2026-11-02 for plugin 0.0.5 and published MCP 0.35.0. This record separates
+command/schema checks from installation and live device evidence.
+
+| Client | Evidence | Limit |
+| --- | --- | --- |
+| Codex CLI 0.166.0-alpha.5.1 | Marketplace-add and plugin-add syntax confirmed with installed CLI help and official docs; catalog paths checked by repository verification | No new Codex installation or agent journey performed |
+| Claude Code 2.1.285 | Native strict validation passes for the marketplace, compatibility manifest and complete plugin folder; shell command syntax confirmed | No new Claude Code installation or agent journey performed |
+| Cursor | Native package and catalog generated from the canonical skill; uses documented CURSOR_PLUGIN_ROOT; local-copy instructions preserve hidden files | Host loading in Cursor is unrun |
+| Antigravity CLI 1.4.12 | Standalone export passes strict validation with zero warnings; local install discovers one skill and one MCP server | An agent print-mode attempt was denied by plan-mode MCP policy; a narrowly permitted read-only attempt timed out, so no agent tool-call success is claimed |
+
+The Antigravity export contains native `plugin.json`, `mcp_config.json`, README,
+license, logo and the shared skill. It excludes foreign client manifests and
+Finder metadata. Export destinations must be new directories. Regression coverage
+checks inventory, canonical skill/license bytes and refusal to overwrite existing
+files. Cursor's generated skill/license are checked against their canonical
+sources by `npm run check:agent-plugin`.
+
+A separate SDK test launched the exact exported npx command from an expanded
+PLUGIN_DATA working directory. It connected to published MCP 0.35.0, discovered
+52 tools, selected emulator-5554 (Android 16/API 36), launched Settings and asserted
+a fresh UI tree contained a visible Settings-owned resource. **PASS**; this is an
+exported-config/device check, not an Antigravity agent interaction. Log:
+`/tmp/antigravity-published-mcp-check.log`. The emulator remains running.
+
+`npm run verify` **PASS**, all 91 unit files, including the exporter regression,
+lint/quality/architecture, build and plugin consistency. Native Antigravity strict
+validation and Claude strict validation also **PASS**. Markdown links and diff
+whitespace were checked. No production server code or dependencies changed.
+GitHub/local distribution does not require the optional Marketplace intake form;
+no application was submitted.
+
+## Primary documentation
+
+- [OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins)
+- [Claude Code installation](https://code.claude.com/docs/en/discover-plugins)
+- [Cursor plugins and local testing](https://cursor.com/docs/plugins)
+- [Antigravity plugin building and validation](https://antigravity.google/docs/build-plugins)

package/docs/benchmarks/README.md

@@ -0,0 +1,18 @@
+# Benchmarks
+
+[Documentation](../README.md)
+
+Use these guides to run a benchmark or inspect its recorded results. Each
+benchmark has one directory containing its instructions, report, and supporting
+data. Generated filenames are retained so the harness can update them directly.
+
+These reports describe particular builds and devices. Passing a smoke check does
+not establish a performance improvement, and Android timings do not establish
+iOS latency.
+
+| Benchmark | Protocol | Recorded results | Design |
+| --- | --- | --- | --- |
+| Interaction latency | [Run the benchmark](interaction-latency/README.md) | [Android measurements](interaction-latency/final.md), [iOS interaction validation](interaction-latency/ios-validation.md) | [018](../specs/018-interaction-latency-and-batched-journeys/spec.md) |
+| UI-tree observation | [Run the paired benchmark](ui-tree-performance/README.md) | [Comparison and limitations](ui-tree-performance/comparison.md) | [019](../specs/019-ui-tree-observation-performance/spec.md) |
+
+Fixture instructions: [latency journey app](../../test/fixtures/latency-journey-app/README.md).