mobile-ai-agents 1.0.41 → 1.0.42

package/README.md

@@ -159,6 +159,20 @@ Available in `mobile-ai-agents@1.0.39` and newer. Use `npx mobile-ai-agents@late
 
 ---
 
+## Keep your mobile app’s architecture
+
+Turn browser API contracts into scoped tasks mapped to your existing app files:
+
+```bash
+npx mobile-ai-agents@latest network handoff \
+  --contract /tmp/mobile-api-contract-1/contract.json \
+  --mapping mapping.json --repo /path/to/mobile-app --out /tmp/mobile-handoff-1
+```
+
+Review networking, auth, domain, state and navigation ownership across Android, iOS, Flutter, React Native and KMP. Native auth or endpoint gaps block dependent tasks; generated plans never claim device verification. Includes a React Native reference flow with HTTP contract tests. Available starting in `1.0.42`. [Mapping format, reference flow and verification limits](docs/mobile-integration-handoff.md).
+
+---
+
 ## Who It Helps
 
 | Role | How Mobile AI Agents Helps |

package/cli/commands/network.js

@@ -2,11 +2,20 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { parseOptions } = require('../lib/options');
+const { buildHandoff, writeHandoff } = require('../lib/mobile-handoff');
 const { capture } = require('../lib/network-capture');
 const { readJson, buildContract, writeContract } = require('../lib/api-contract');
 
 async function cmdNetwork(args) {
   const opts = parseOptions(args);
+  if (opts._.join(' ') === 'handoff') {
+    if (!opts.contract || !opts.mapping || !opts.repo || !opts.out || Object.keys(opts).some(k => !['_', 'contract', 'mapping', 'repo', 'out'].includes(k))) throw new Error('Usage: network handoff --contract contract.json --mapping mapping.json --repo APP_ROOT --out NEW_DIRECTORY');
+    for (const key of Object.keys(opts)) if (key !== '_' && typeof opts[key] !== 'string') throw new Error(`--${key} needs a value.`);
+    const report = buildHandoff(readJson(opts.contract), readJson(opts.mapping), opts.repo);
+    writeHandoff(report, path.resolve(opts.out));
+    console.log(`${report.status}: ${report.tasks.length} scoped tasks. Mobile verification: unverified. ${path.resolve(opts.out)}`);
+    return;
+  }
   if (opts._.join(' ') === 'contract') {
     if ((!opts.capture && !opts.har) || (opts.capture && opts.har) || !opts.out || Object.keys(opts).some(key => !['_', 'capture', 'har', 'openapi', 'out'].includes(key))) throw new Error('Usage: network contract --capture capture.json | --har session.har --out NEW_DIRECTORY [--openapi openapi.json]');
     for (const key of Object.keys(opts)) if (key !== '_' && typeof opts[key] !== 'string') throw new Error(`--${key} needs a value.`);

package/cli/fixtures/mobile-handoff/App.jsx

@@ -0,0 +1,27 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { View, Text, TextInput, Button, ScrollView } from 'react-native';
+const { createClient } = require('./client');
+const { createModel } = require('./model');
+
+// Mount inside an existing React Native test app, passing its reachable demo origin.
+export default function ReferenceFlow({ baseUrl }) {
+  const model = useMemo(() => createModel(createClient({ baseUrl })), [baseUrl]);
+  const [state, setState] = useState(model.getState());
+  const [title, setTitle] = useState('');
+  useEffect(() => {
+    setState(model.getState());
+    const unsubscribe = model.subscribe(setState);
+    return () => { unsubscribe(); model.dispose(); };
+  }, [model]);
+  const busy = state.status === 'loading';
+  return <ScrollView contentContainerStyle={{ padding: 24, gap: 12 }}>
+    <Text accessibilityRole="header">Website API → mobile reference</Text>
+    <Button title="Load listings" disabled={busy} onPress={() => model.run('list')} />
+    <Button title="Open detail" disabled={busy} onPress={() => model.run('detail')} />
+    <TextInput accessibilityLabel="Listing title" placeholder="Title" value={title} onChangeText={setTitle} />
+    <Button title="Save test listing" disabled={busy || !title.trim()} onPress={() => model.run('save', title)} />
+    <Button title="Cancel" disabled={!busy} onPress={model.cancel} />
+    <View accessibilityLiveRegion="polite"><Text>{state.status}{state.error ? `: ${state.error}` : ''}</Text></View>
+    <Text selectable>{state.data ? JSON.stringify(state.data, null, 2) : ''}</Text>
+  </ScrollView>;
+}

package/cli/fixtures/mobile-handoff/client.js

@@ -0,0 +1,25 @@
+'use strict';
+// Same business flow as network-demo; transport is injected from the existing app.
+function createClient({ baseUrl, transport = fetch }) {
+  const base = new URL(baseUrl);
+  if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash || base.pathname !== '/') throw new Error('Use an explicit HTTP(S) test-server origin.');
+  async function request(route, { signal, ...options } = {}) {
+    const response = await transport(new URL(route, base).href, { ...options, signal });
+    if (response.status === 401) throw Object.assign(new Error('Session expired'), { kind: 'auth-expired' });
+    if (!response.ok) throw Object.assign(new Error('Request failed'), { kind: response.status === 422 ? 'validation' : 'http' });
+    return response.json();
+  }
+  return {
+    list: signal => request('/api/items', { signal }),
+    detail: async signal => {
+      const [item, options] = await Promise.all([request('/api/detail', { signal }), request('/api/options', { signal })]);
+      return { item, options };
+    },
+    save: (title, signal) => {
+      if (!title.trim()) throw Object.assign(new Error('Title required'), { kind: 'validation' });
+      // The owned demo does not require auth. Never copy its captured bearer token.
+      return request('/api/save', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ title: title.trim() }), signal });
+    },
+  };
+}
+module.exports = { createClient };

package/cli/fixtures/mobile-handoff/model.js

@@ -0,0 +1,22 @@
+'use strict';
+function createModel(client) {
+  let state = { status: 'idle', data: null, error: null }, active, generation = 0;
+  const listeners = new Set();
+  function set(next) { state = next; listeners.forEach(fn => fn(state)); }
+  async function run(operation, value) {
+    if (!['list', 'detail', 'save'].includes(operation)) throw new Error('Unknown operation');
+    if (state.status === 'loading') return; // No duplicate submission, no automatic retries.
+    const current = ++generation;
+    active = new AbortController();
+    set({ status: 'loading', data: null, error: null });
+    try {
+      const data = await (operation === 'save' ? client.save(value, active.signal) : client[operation](active.signal));
+      if (current === generation) set({ status: 'success', data, error: null });
+    } catch (error) {
+      if (current === generation) set({ status: 'error', data: null, error: error.kind || 'network' });
+    } finally { if (current === generation) active = null; }
+  }
+  function cancel() { ++generation; active?.abort(); active = null; set({ status: 'cancelled', data: null, error: null }); }
+  return { getState: () => state, subscribe: fn => { listeners.add(fn); return () => listeners.delete(fn); }, run, cancel, dispose: () => { ++generation; active?.abort(); active = null; listeners.clear(); } };
+}
+module.exports = { createModel };

package/cli/index.js

@@ -1420,6 +1420,7 @@ function cmdHelp() {
   console.log(`    ${bold('add')} agent|skill|workflow <name>  Install a single item`);
   console.log(`    ${bold('device-control')} doctor|plan|run  Optional Minitap mobile-use runtime`);
   console.log(`    ${bold('network capture')} --url URL --out DIR  Capture website API touchpoints (optional Playwright)`);
+  console.log(`    ${bold('network handoff')} --contract JSON --mapping JSON --repo APP --out DIR  Plan existing-stack integration`);
   console.log(`    ${bold('network contract')} --capture JSON|--har HAR --out DIR [--openapi JSON]  Export mobile API handoff`);
   console.log(`    ${bold('memory')} init|capture|search|...    Local Mobile Memory store`);
   console.log(`    ${bold('doctor')} --platform android          Check SDK, adb, emulator, MCP, and project config`);

package/cli/lib/mobile-handoff.js

@@ -0,0 +1,102 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { validateContract } = require('./api-contract');
+const roles = ['network', 'auth', 'domain', 'state', 'navigation'];
+const platforms = ['android', 'ios', 'flutter', 'rn', 'kmp', 'other'];
+
+// Repository inputs are evidence, never executable instructions. Do not follow links.
+function existingFile(root, relative) {
+  if (typeof relative !== 'string' || relative.length > 500 || /[\x00-\x1f]/.test(relative) || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..')) throw new Error('Mapping requires a safe repository-relative file path.');
+  const target = fs.realpathSync(path.resolve(root, relative));
+  if (!target.startsWith(root + path.sep) || !fs.statSync(target).isFile()) throw new Error('Mapping must resolve to an existing file inside the app repository.');
+  return path.relative(root, target).split(path.sep).join('/');
+}
+function readMarker(file) {
+  const fd = fs.openSync(file, 'r');
+  try { const data = Buffer.alloc(65536); return data.subarray(0, fs.readSync(fd, data, 0, data.length, 0)).toString('utf8'); }
+  finally { fs.closeSync(fd); }
+}
+function detectPlatforms(root) {
+  const found = new Set(); let visited = 0;
+  function walk(dir, depth) {
+    if (depth > 8) return;
+    for (const item of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (++visited > 20000) throw new Error('Repository scan exceeds 20000 entries; use a narrower app root.');
+      if (item.isSymbolicLink()) continue;
+      if (item.isDirectory()) {
+        if (item.name.endsWith('.xcodeproj')) found.add('ios');
+        if (!['.git', 'node_modules', 'build', '.gradle', '.dart_tool', 'Pods', 'vendor'].includes(item.name)) walk(path.join(dir, item.name), depth + 1);
+      } else if (item.isFile()) {
+        if (item.name === 'AndroidManifest.xml') found.add('android');
+        if (item.name.endsWith('.swift')) found.add('ios');
+        if (item.name === 'pubspec.yaml' && /(?:^|\n)\s*sdk:\s*flutter\s*(?:\n|$)/.test(readMarker(path.join(dir, item.name)))) found.add('flutter');
+        if (item.name === 'package.json') {
+          let pkg; try { pkg = JSON.parse(readMarker(path.join(dir, item.name))); } catch { continue; }
+          if (pkg.dependencies?.['react-native'] || pkg.devDependencies?.['react-native']) found.add('rn');
+        }
+        if (/^build\.gradle(?:\.kts)?$/.test(item.name) && /kotlin\(["']multiplatform["']\)|org\.jetbrains\.kotlin\.multiplatform/.test(readMarker(path.join(dir, item.name)))) found.add('kmp');
+      }
+    }
+  }
+  walk(root, 0); return [...found].sort();
+}
+function buildHandoff(contract, manifest, repository) {
+  validateContract(contract);
+  if (contract.requests.length > 500 || contract.touchpoints.length > 100 || !Array.isArray(contract.findings)) throw new Error('Invalid or oversized contract.');
+  if (manifest?.version !== 1 || !platforms.includes(manifest.platform) || !Array.isArray(manifest.touchpoints) || manifest.touchpoints.length > 100) throw new Error('Expected mapping version 1, platform and touchpoints.');
+  const root = fs.realpathSync(repository), detectedPlatforms = detectPlatforms(root);
+  if (manifest.platform !== 'other' && !detectedPlatforms.includes(manifest.platform)) throw new Error('Selected platform has no detected repository marker.');
+  const points = new Set(contract.touchpoints.map(p => p.id)), mapped = new Set();
+  const mappings = manifest.touchpoints.map(mapping => {
+    if (!points.has(mapping.id) || mapped.has(mapping.id)) throw new Error('Unknown or duplicate mapped touchpoint.');
+    mapped.add(mapping.id);
+    const files = {};
+    for (const role of roles) {
+      const file = mapping.files?.[role];
+      if (file) {
+        if (!['shared', 'native'].includes(file.ownership)) throw new Error('File ownership must be shared or native.');
+        files[role] = { path: existingFile(root, file.path), ownership: file.ownership };
+      }
+    }
+    const reviews = mapping.requests || [];
+    if (!Array.isArray(reviews)) throw new Error('Request reviews must be an array.');
+    const expected = contract.touchpoints.find(p => p.id === mapping.id).requestIds;
+    const seen = new Set();
+    const requestReviews = reviews.map(review => {
+      if (!expected.includes(review.id) || seen.has(review.id)) throw new Error('Unknown or duplicate reviewed request.');
+      seen.add(review.id);
+      if (!['supported', 'gap'].includes(review.nativeEndpoint) || !['supported', 'gap', 'not-required'].includes(review.nativeAuth)) throw new Error('Request review requires explicit native endpoint and auth decisions.');
+      return { id: review.id, nativeEndpoint: review.nativeEndpoint, nativeAuth: review.nativeAuth, evidence: existingFile(root, review.evidence), findingsReviewed: review.findingsReviewed === true };
+    });
+    return { id: mapping.id, files, requestReviews };
+  });
+  const tasks = contract.touchpoints.map(point => {
+    const mapping = mappings.find(m => m.id === point.id);
+    const gaps = roles.filter(role => !mapping?.files[role]).map(role => `map-existing-${role}-ownership`);
+    if (contract.source.captureStatus && contract.source.captureStatus !== 'captured') gaps.push('capture-incomplete');
+    if (contract.findings.some(f => !f.requestId)) gaps.push('global-contract-findings-unreviewed');
+    if (manifest.platform === 'other') gaps.push('confirm-custom-stack-and-tooling');
+    if (point.status !== 'completed') gaps.push('browser-action-incomplete');
+    if (point.provenance === 'unattributed') gaps.push('establish-user-action-attribution');
+    for (const id of point.requestIds) {
+      const review = mapping?.requestReviews.find(r => r.id === id);
+      if (!review || review.nativeEndpoint !== 'supported') gaps.push(`${id}:native-endpoint-unresolved`);
+      if (!review || review.nativeAuth === 'gap') gaps.push(`${id}:native-auth-unresolved`);
+      if (contract.findings.some(f => f.requestId === id) && !review?.findingsReviewed) gaps.push(`${id}:contract-findings-unreviewed`);
+    }
+    return { id: `implement-${point.id}`, touchpointId: point.id, requestIds: [...point.requestIds], status: gaps.length ? 'blocked' : 'ready-for-review', gaps,
+      steps: ['Review mapped client/auth/domain/state/navigation boundaries; reuse current stack.', 'Select business calls; omit preflight, analytics and duplicate fetches only after review.', 'Resolve native auth/endpoint and schema conflicts before dependent wiring.', 'Implement scoped DTO/domain/state changes in mapped files; propose new files explicitly during code review.', 'Preserve no-network validation actions and documented native navigation differences.'],
+      acceptance: ['Matching request/response contract and UI states with equivalent fixtures.', 'Cancellation reaches transport; stale results do not replace current UI state.', 'Auth expiry follows existing refresh/logout policy; no captured browser credentials.', 'Retry only supported safe/idempotent operations; no blind write retries.', 'Validate input locally and map server validation errors.', 'Uploads: document stages, progress, cancellation and retry if applicable; otherwise record not applicable.'],
+      verification: { contract: 'unverified', mobileNetwork: 'unverified', mobileUI: 'unverified' } };
+  });
+  return { handoffVersion: '1.0.0', platform: manifest.platform, detectedPlatforms, contractSha256: createHash('sha256').update(JSON.stringify(contract)).digest('hex'), status: tasks.some(t => t.status === 'blocked') ? 'blocked' : 'needs-review', mobileVerification: 'unverified', mappings, tasks,
+    limitations: ['Mappings and native support decisions are user-reviewed inputs, not automatically proven semantics.', 'Detection uses bounded markers, not architecture inference; nested app markers can overlap.', 'No app source is modified and no requests are replayed.', 'Contract findings remain in the source contract; reviewed does not mean resolved.', 'Device/network/UI evidence is required separately for every target.'] };
+}
+function writeHandoff(report, directory) {
+  fs.mkdirSync(directory, { mode: 0o700 });
+  fs.writeFileSync(path.join(directory, 'handoff.json'), JSON.stringify(report, null, 2) + '\n', { mode: 0o600 });
+  fs.writeFileSync(path.join(directory, 'handoff.md'), ['# Mobile integration handoff', '', `Status: ${report.status}; platform: ${report.platform}; mobile verification: unverified.`, '', ...report.tasks.flatMap(t => [`## ${t.id}`, `Status: ${t.status}`, ...t.gaps.map(g => `- Gap: ${g}`), ...t.steps.map(s => `- ${s}`), ...t.acceptance.map(a => `- Check: ${a}`), '']), ...report.limitations.map(l => `- ${l}`)].join('\n') + '\n', { mode: 0o600 });
+}
+module.exports = { existingFile, detectPlatforms, buildHandoff, writeHandoff };

package/docs/mobile-integration-handoff.md

@@ -0,0 +1,86 @@
+# Website API contract → existing mobile app implementation
+
+`network handoff` (starting in v1.0.42) turns the [API contract](api-contracts.md) into scoped implementation tasks. It preserves the app's existing stack by requiring reviewed source-file mappings instead of generating a replacement networking layer. It reads local inputs only, never replays requests and never changes the target app.
+
+## Run
+
+```bash
+npx mobile-ai-agents@latest network handoff \
+  --contract /tmp/mobile-api-contract-1/contract.json \
+  --mapping mapping.json --repo /path/to/mobile-app \
+  --out /tmp/mobile-handoff-1
+```
+
+Every output directory must be new, with an existing parent. Inputs use the contract command's 10 MiB limit. Scanning skips dependency/build folders and symlinks, stops after 20,000 entries and eight directory levels, and reads only supported marker files. Choose a focused app root. Detection is a hint; nested Android modules inside Flutter or RN projects can also produce Android markers. The selected platform must have a marker; `other` always requires a tooling review.
+
+Supply mappings for the actual touchpoint IDs in your contract. This example shows a reviewed Android mapping; replace paths with **existing files in your app**, not invented scaffolding:
+
+```json
+{
+  "version": 1,
+  "platform": "android",
+  "touchpoints": [{
+    "id": "T1",
+    "files": {
+      "network": {"path": "app/src/main/java/com/example/data/ItemsApi.kt", "ownership": "native"},
+      "auth": {"path": "app/src/main/java/com/example/data/Session.kt", "ownership": "native"},
+      "domain": {"path": "app/src/main/java/com/example/domain/Item.kt", "ownership": "native"},
+      "state": {"path": "app/src/main/java/com/example/ui/ItemsViewModel.kt", "ownership": "native"},
+      "navigation": {"path": "app/src/main/java/com/example/ui/Navigation.kt", "ownership": "native"}
+    },
+    "requests": [{
+      "id": "R1",
+      "nativeEndpoint": "supported",
+      "nativeAuth": "supported",
+      "evidence": "docs/native-api-review.md",
+      "findingsReviewed": true
+    }]
+  }]
+}
+```
+
+`platform`: `android`, `ios`, `flutter`, `rn`, `kmp`, or `other`. File ownership is `native` or `shared`. Multiple roles may map to one existing file when that matches the real app. Evidence is a local review file, not a remote URL. Keep it free of secrets. Paths must resolve inside the repository; missing files, escapes and external symlinks are rejected. No source text, credentials or captured header values are copied to the report. Paths and hashes are still project metadata: review before sharing.
+
+Record native endpoint and auth support based on backend/mobile documentation and the existing client. `nativeEndpoint` is `supported` or `gap`; `nativeAuth` is `supported`, `not-required` or `gap`. Review evidence should identify the supported native route/auth flow, DTO/domain ownership, schema conflicts, business-call grouping and justified native differences. `findingsReviewed` is a human assertion that findings were reviewed, **not proof that discrepancies are resolved**. Do not set it merely to make a task ready. Contract findings remain authoritative until separately resolved.
+
+Missing role mappings, missing request reviews, auth/endpoint gaps, incomplete captures, unattributed HAR actions or unreviewed contract findings block dependent tasks. No-network touchpoints still get tasks and ownership mappings. Output consists of private `handoff.json` and `handoff.md` with stable touchpoint/request IDs, existing files, gaps, steps and acceptance criteria. `ready-for-review` means there is enough supplied mapping to review a task; it never means implementation or mobile verification passed. Unresolved global findings conservatively block all tasks.
+
+## Platform ownership
+
+| Target | Preserve and map | Runtime status for this feature |
+|---|---|---|
+| Android | Current Kotlin/Java HTTP client, session, DTO/domain, ViewModel and navigation | Unverified |
+| iOS | Current Swift/ObjC session/client, models, state and navigation | Unverified |
+| Flutter | Current Dart client, repositories, state and router | Unverified |
+| React Native | Current JS/TS client, auth, models, hooks/store and navigation | Reference source and Node HTTP tests; device UI unverified |
+| KMP | Existing shared client/domain ownership separately from target auth/UI/navigation | Unverified |
+| Other | Reviewed existing toolchain and equivalent boundaries | Unverified; explicit review required |
+
+The CLI does not parse every language, infer architecture from filenames, create universal SDKs, or copy browser headers, analytics, preflight calls and duplicate fetches into a client. Review business-call selection and causal dependencies before wiring code. Independent tasks can proceed while dependent tasks remain blocked.
+
+## Runnable reference: list → detail → validate → save
+
+The packaged [reference files](../cli/fixtures/mobile-handoff/App.jsx) contain a React Native screen, injected-transport client and cancellable state model. They target the repository's owned [HTTP demo](../cli/fixtures/network-demo.js), not a production API. The screen can be mounted inside an existing React Native test project:
+
+1. Start the owned server from this repository: `node cli/fixtures/network-demo.js /tmp/mobile-demo-flow.json` (new flow-file path).
+2. Copy `cli/fixtures/mobile-handoff/` into that project's source tree. Import `ReferenceFlow` from `App.jsx` and mount `<ReferenceFlow baseUrl="http://YOUR_TEST_HOST:4173" />` in the existing app. Android emulators normally reach their host using `10.0.2.2`; use a reachable host for your actual target. Configure local HTTP only in the existing debug/test configuration. Do not weaken production TLS or certificate pinning.
+3. Tap Load listings, Open detail, enter a title, Save test listing, and Cancel during an outstanding operation. Connect independent device and network evidence to the same touchpoint IDs before claiming parity.
+
+The client issues GET `/api/items`; parallel GET `/api/detail` and `/api/options`; and a single POST `/api/save` with JSON `{title}`. Empty titles are rejected before transport. The browser demo's incidental password field and demonstration bearer token are not native requirements; the owned server accepts the title without them. This is a documented fixture difference, not a strategy for bypassing real auth.
+
+The client accepts the existing app transport for integration. It does not implement token storage or refresh: 401 produces `auth-expired` for the app's established session policy. HTTP 422 produces `validation`; other HTTP failures and network failures stay errors. The model prevents duplicate submissions, makes **no automatic retries**, forwards cancellation via AbortSignal and suppresses late results after cancellation/unmount. The screen is deliberately separate from production navigation and auth ownership.
+
+Uploads are not present in this fixture and remain **not applicable**, rather than tested. If a reference contains uploads, map initialization, signed URL, transfer, completion, progress, cancellation and safe retry/idempotency policy before dependent implementation. Production refresh, upload, retry semantics and platform-specific transport cancellation need their own evidence.
+
+## Reproducible checks and remaining verification
+
+```bash
+node --test test/mobile-handoff.test.js
+npm test
+```
+
+The HTTP tests use a real local server and exercise the same client used by the reference screen. They check list/detail/save, local validation, auth expiry, server validation, cancellation, duplicate prevention and no write retries. Mapping tests cover ownership, KMP boundaries, missing evidence, path containment and output preservation. They do **not** mount a mobile UI, run Metro, build a native binary or establish browser/mobile device parity. The reference is runnable source for an existing React Native test app; no native test harness or dependency installation is bundled.
+
+Continue with [#72](https://github.com/salmanashraf/mobile-ai-agents/issues/72) for actual mobile network/UI parity, reusing Mobile MCP/device QA work in #54/#55. Run relevant build/contract checks, then capture actual mobile requests/responses and UI on each requested target. Use equivalent fixtures/environment/accounts. Screenshots alone do not prove network parity. Implementation source, mocked responses and Node HTTP tests must never be reported as a verified mobile runtime.
+
+Implementation: [#71](https://github.com/salmanashraf/mobile-ai-agents/issues/71). Follow [web-network-to-mobile](../skills/cross-platform/web-network-to-mobile.md) and PRD verification before declaring the user flow complete.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-ai-agents",
-  "version": "1.0.41",
+  "version": "1.0.42",
   "description": "AI agents, skills, and Loop Engineering workflows for building, testing, auditing, and releasing mobile apps.",
   "bin": {
     "mobile-ai-agents": "cli/index.js",

package/skills/cross-platform/web-network-to-mobile.md

@@ -25,6 +25,10 @@ Trace an authorized deployed website's network behavior at each user interaction
 
 This repository includes `node cli/index.js network capture --url URL --out NEW_DIRECTORY --flow flow.json`. Read [the capture guide](../../docs/website-api-discovery.md) for optional Playwright setup, allowed origins and controlled write actions. It produces sanitized request/response shapes and temporal touchpoint evidence; it does not export full payload values, perform mobile implementation or verify mobile traffic. Use it when that evidence is sufficient, and preserve its capture limitations in the handoff. The command requires mobile-ai-agents 1.0.39 or newer.
 
+## Existing-App Handoff Adapter
+
+After exporting `contract.json`, use `network handoff --contract contract.json --mapping mapping.json --repo APP_ROOT --out NEW_DIRECTORY`. Read [the handoff guide](../../docs/mobile-integration-handoff.md). Supply reviewed existing-file ownership and native auth/endpoint evidence; detection markers alone do not establish architecture. Missing mappings block dependent tasks. Use KMP `shared` versus `native` ownership explicitly. Requires mobile-ai-agents 1.0.42 or newer. The command writes a scoped plan and never edits the target app or claims mobile parity. Review all remaining contract findings before implementing.
+
 ## Skill Prompt
 
 For versioned artifacts, use `npx mobile-ai-agents@latest network contract --capture capture.json --out NEW_DIRECTORY`, or `--har session.har`, with optional `--openapi openapi.json`. Read [the contract guide](../../docs/api-contracts.md) for provenance, supported cross-checks and capture gaps. This exporter stays `needs-review` and does not establish a supported mobile contract or app parity. It requires mobile-ai-agents 1.0.40 or newer.