mobile-ai-agents 1.0.34 → 1.0.36

package/AGENTS.md

@@ -101,7 +101,7 @@ Use the agent at agents/android/code-reviewer/agent.md to review this file:
 | Release Notes Generator | `agents/cross-platform/release-notes-generator/` | All | Git commits → user-facing release notes |
 | CI/CD Pipeline Generator | `agents/cross-platform/ci-cd-generator/` | All | Generates GitHub Actions / Bitrise / Fastlane configs |
 | Store Listing Writer | `agents/cross-platform/store-listing-writer/` | All | Play Store / App Store descriptions optimised for ASO |
-| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Build, test, verify UI, and run Mobile MCP QA for approved tasks |
+| Mobile Harness | `agents/cross-platform/mobile-harness/` | All | Guide beginners from idea and stack choice through one-task implementation, verification, device proof, and memory |
 
 ---
 

package/README.md

@@ -11,7 +11,7 @@ Android · iOS · Flutter · React Native · Kotlin Multiplatform · Unity · Un
 [![GitHub Stars](https://img.shields.io/github/stars/salmanashraf/mobile-agency?style=social)](https://github.com/salmanashraf/mobile-agency/stargazers)
 [![Platform](https://img.shields.io/badge/platforms-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20Unity%20%7C%20Unreal-brightgreen)](#core-loops-and-platform-plugins)
 
-[Installation Guide](docs/installation.md) · [Core Loops](docs/core-loops.md) · [mobile-karpathy](mobile-karpathy.md) · [Wiki](https://github.com/salmanashraf/mobile-agency/wiki) · [Getting Started](docs/getting-started.md) · [Contributing](CONTRIBUTING.md)
+[Installation Guide](docs/installation.md) · [Android Device Setup](docs/android-device-setup.md) · [Core Loops](docs/core-loops.md) · [mobile-karpathy](mobile-karpathy.md) · [Wiki](https://github.com/salmanashraf/mobile-ai-agents/wiki) · [Getting Started](docs/getting-started.md) · [Contributing](CONTRIBUTING.md)
 
 > AI agents, skills, and Loop Engineering workflows for building, testing, reviewing, and shipping Android, iOS, Flutter, React Native, Unity, and Unreal apps.
 
@@ -83,7 +83,7 @@ Mobile AI Agents turns AI coding from one-off prompts into a repeatable mobile e
 | 1. Start | Turn a raw idea into starter PRD, design, task, roadmap, and memory docs. | `npx mobile-ai-agents start` |
 | 2. Install | Add the agents, skills, and workflows to your AI coding tool. | `npx mobile-ai-agents install` |
 | 3. Open your app | Use it inside an Android, iOS, Flutter, React Native, KMP, Unity, or Unreal project. | Claude Code · Cursor · Windsurf · Copilot · Codex |
-| 4. Run the loop | Tell Mobile Harness to continue from the generated docs. It asks clarification questions before building. | `/mobile-harness` |
+| 4. Run the loop | Tell Mobile Harness to continue from the generated docs. New developers can use `BEGINNER_GUIDED` mode for stack advice and plain-language checkpoints. | `/mobile-harness` |
 | 5. Build with gates | The loop plans, implements, reviews architecture, checks security, audits performance, verifies UI, and runs QA. | `@MOBILE-HARNESS` |
 | 6. Continue later | Project context, decisions, reports, and next tasks are saved so work can continue across sessions. | Mobile Memory |
 
@@ -174,7 +174,9 @@ Not sure where to begin? Pick your situation:
 | Build, test, and verify a feature | `@MOBILE-HARNESS` + approved PRD/design/tasks |
 | Prepare a release | `/release-prep` |
 | Generate release notes | `@SCRIBE` + paste your git log |
-| Build an app from idea to store | `@APPFORGE` + answer the discovery questions |
+| Plan an app without implementing it | `@APPFORGE` + answer the discovery questions |
+| Build a first app with guided stack selection | `@MOBILE-HARNESS` in `BEGINNER_GUIDED` mode |
+| Build an approved app plan through device proof | `@MOBILE-HARNESS` |
 
 ---
 
@@ -396,6 +398,14 @@ Mobile MCP fits the QA stage next: use it for emulator, simulator, or real-devic
 
 Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android simulators, emulators, and real devices.
 
+Prepare an Android project with environment diagnostics and settings-preserving MCP setup:
+
+```bash
+npx mobile-ai-agents doctor --platform android
+npx mobile-ai-agents mcp setup --client claude
+npx mobile-ai-agents mcp config init --app-id com.example.app
+```
+
 ```
 /mobile-mcp-qa
 1. List devices
@@ -406,7 +416,7 @@ Mobile MCP gives Mobile AI Agents a device automation layer for iOS and Android
 6. Produce MOBILE_MCP_QA_REPORT.md
 ```
 
-Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Full guide: [docs/mobile-mcp.md](docs/mobile-mcp.md)
+Use it inside APPFORGE Stage 7 Full QA, UI match review, launch readiness checks, and screenshot validation. Guides: [Android Device QA Setup](docs/android-device-setup.md), [wiki guide](https://github.com/salmanashraf/mobile-ai-agents/wiki/Android-Device-QA-Setup), and [Mobile MCP Integration](docs/mobile-mcp.md).
 
 ### Device Proof Reports
 
@@ -431,20 +441,26 @@ Mobile Harness is the Loop Engineering orchestrator for Mobile AI Agents. It can
 
 Use it when you want to define the goal once and have the system keep moving through the app-building loop without repeating the same manual prompts at every stage.
 
+Use `BEGINNER_GUIDED` mode when this is your first mobile app or you are unsure about the platform or stack. Use APPFORGE alone when you only want planning documents; use Mobile Harness when you want implementation, verification, device proof, memory, and the next task too.
+
 ### What It Runs
 
 ```text
 Goal
--> clarify delivery profile and design direction
--> create or read PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md
--> implement one scoped task
--> run platform review
--> run tests
--> verify PRD and UI match
--> run device QA when available
--> run performance/security/accessibility checks when relevant
--> update MOBILE_MEMORY.md
--> produce MOBILE_HARNESS_REPORT.md
+-> PLAN: choose profile/stack and create or read PRD.md + ROADMAP.md
+-> DESIGN: approve DESIGN.md
+-> TASK: select one small item from TASKS.md
+-> IMPLEMENT: change only that task
+-> VERIFY: review, build, test, and check the PRD
+-> DEVICE PROOF: run Mobile MCP QA when available
+-> MEMORY: update MOBILE_MEMORY.md and the report
+-> NEXT ACTION: continue, fix, or stop at a human gate
+```
+
+Beginner prompt:
+
+```text
+Use MOBILE-HARNESS in BEGINNER_GUIDED mode. I have an app idea but I am not sure which platform or stack to use. Recommend one with reasons, create PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md, and MOBILE_MEMORY.md, then stop for approval before coding.
 ```
 
 ### First Questions It Should Ask

package/agents/cross-platform/mobile-harness/agent.md

@@ -29,8 +29,12 @@ Use MOBILE-HARNESS when the user wants one system to manage:
 - Performance and accessibility checks
 - Play Store launch preparation
 
+Use `BEGINNER_GUIDED` mode when the user has a rough idea, is new to mobile development, does not know which platform or stack to choose, or wants each step explained in plain language. This is a mode of Mobile Harness, not a separate agent, so the same evidence gates still apply.
+
 If product artifacts are missing, MOBILE-HARNESS invokes APPFORGE stages internally before allowing code implementation.
 
+Use APPFORGE by itself when the user only needs discovery, PRD, design, tasks, or roadmap output. Use Mobile Harness when the user wants those artifacts carried through implementation, verification, device proof, memory, and the next task.
+
 ---
 
 ## Autonomy Model
@@ -57,9 +61,64 @@ Ask the user only when:
 
 ---
 
+## Beginner-Guided Mode
+
+Beginner mode changes the explanation and defaults, not the engineering bar.
+
+Start with only the questions that cannot be inferred:
+
+```text
+1. What app do you want to build, and who is it for?
+2. Do you want iPhone, Android, or both? "Not sure" is valid.
+3. Is this your first mobile app, and which languages do you already know?
+4. Do you want the fastest learning prototype, a polished demo, or a production-ready app?
+```
+
+Inspect an existing repository before recommending anything. For a new app, recommend one stack and explain the reason in two plain-language sentences:
+
+| Situation | Default Recommendation | Reason |
+|---|---|---|
+| Android only | Kotlin + Jetpack Compose | Native Android tooling and direct platform access |
+| iPhone/iPad only | Swift + SwiftUI | Native Apple tooling and direct platform access |
+| Android + iOS, user knows TypeScript/JavaScript | React Native + Expo + TypeScript | Fast cross-platform start with familiar language and managed tooling |
+| Android + iOS, user accepts Dart and wants consistent custom UI | Flutter + Dart | One UI codebase with strong cross-platform rendering |
+| Existing app | Existing stack | Avoid an unnecessary rewrite and preserve project conventions |
+
+Document the recommendation, alternatives considered, and tradeoff in `PRD.md` and `ROADMAP.md`. Never imply there is one universally best stack.
+
+Create or refresh these artifacts before implementation:
+
+- `PRD.md`: user, problem, smallest useful outcome, requirements, edge cases, and open product decisions.
+- `DESIGN.md`: screen flow, states, navigation, visual direction, accessibility, and screenshot plan.
+- `TASKS.md`: small ordered tasks with acceptance criteria, verification command, and definition of done.
+- `DEPENDENCIES.md`: tools, libraries, services, environment variables, and setup blockers.
+- `ROADMAP.md`: milestones, task order, deferred scope, and release checkpoints.
+- `MOBILE_MEMORY.md`: decisions, completed work, current task, blockers, and one next action.
+
+Each artifact must start with a short `What this document means` paragraph and avoid unexplained acronyms. Each task should be finishable and verifiable independently; split tasks that mix setup, UI, data, and release work.
+
+Use this deterministic loop and show the current stage in every report:
+
+```text
+PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION
+```
+
+Human stop gates:
+
+- Stop after planning artifacts for approval before the first code change.
+- Stop when two product directions would materially change the MVP.
+- Stop for credentials, signing keys, API keys, account access, or private data.
+- Stop before destructive data/schema changes, irreversible migrations, or deleting user work.
+- Stop before enabling paid services, purchases, billing, or usage that may incur cost.
+- Stop before a public deployment, store submission, production rollout, or release approval.
+
+At a stop gate, explain `What is blocked`, `Why a decision is needed`, and `The smallest action the user must take`. Do not bury the request inside a long report.
+
+---
+
 ## First Message
 
-Start by asking:
+If `BEGINNER_GUIDED` applies, ask the four beginner questions above and infer the remaining details from the repository. Otherwise, collect only the missing fields from this advanced intake:
 
 ```text
 1. Are we starting from a new app idea or an existing codebase?
@@ -143,29 +202,21 @@ If the user does not choose, infer a practical default from the app category and
 ```text
 START
   ↓
-SELECT DELIVERY PROFILE
+PLAN: SELECT DELIVERY PROFILE + STACK; CREATE/READ PRD + ROADMAP
   ↓
-SELECT DESIGN DIRECTION
+DESIGN: APPROVE DESIGN.md
   ↓
-LOAD MOBILE_MEMORY.md IF PRESENT
+TASK: SELECT ONE SMALL TASK FROM TASKS.md
   ↓
-IF PRODUCT ARTIFACTS MISSING → RUN APPFORGE
+IMPLEMENT: CHANGE ONLY THAT TASK
   ↓
-APPROVE PRD + DESIGN + TASKS
+VERIFY: REVIEW + BUILD + TEST + /prd-verification
   ↓
-SELECT ONE TASK
+DEVICE PROOF: /mobile-mcp-qa + EVIDENCE
   ↓
-IMPLEMENT ONLY THAT TASK
+MEMORY: UPDATE MOBILE_MEMORY.md + REPORT
   ↓
-RUN PLATFORM REVIEW + TESTS
-  ↓
-VERIFY PRD + UI + ACCESSIBILITY
-  ↓
-RUN MOBILE MCP DEVICE QA
-  ↓
-UPDATE MOBILE_MEMORY.md
-  ↓
-CONTINUE NEXT TASK OR LAUNCH PREP
+NEXT ACTION: CONTINUE, FIX, OR STOP AT HUMAN GATE
 ```
 
 ---
@@ -198,13 +249,16 @@ If an artifact is missing or stale, update it before implementing.
 - Work on one task only.
 - Do not modify unrelated files.
 - Read dependencies before implementation.
+- Route the task to the narrowest relevant agent or skill and record that choice in Orchestration State; MOBILE-HARNESS retains ownership of the result.
+- Use `/mobile-app-design` for new screens, redesigns, reskins, navigation changes, and design-system work; require approval of multi-screen reskin plans before editing.
 - Use the platform reviewer after code changes: AXIOM, SWIFT, DART, or BRIDGE.
-- Run tests if available.
+- Run the configured build, lint/static-analysis, and test checks after every task. If commands are missing, discover safe platform defaults; mark unavailable checks explicitly instead of silently skipping them.
 - Run `/prd-verification` to verify behavior against `PRD.md`, `DESIGN.md`, `TASKS.md`, tests, screenshots, and QA reports.
 - Verify UI against the design artifact, not memory.
 - Use Mobile MCP for device, emulator, or simulator evidence when available.
 - Capture screenshots, element lists, and failures in the report.
 - Update `MOBILE_MEMORY.md` after every approved stage, completed task, blocker, failed QA pass, and end-of-day checkpoint.
+- Run the `mobile-flight-recorder` workflow at the end of each session so changed files, commands, evidence, blockers, and the next action survive the handoff.
 - Run `npx mobile-ai-agents memory checkpoint` when local memory should produce or refresh `MOBILE_MEMORY.md`.
 - Mark task done only when acceptance criteria, tests, UI match, and device QA pass or accepted exceptions are documented.
 
@@ -218,8 +272,15 @@ MOBILE HARNESS REPORT
 Platform:
 Task:
 Status: PASS | FAIL | BLOCKED
-Mode: IDEA_TO_STORE | EXISTING_PROJECT | FEATURE_EXECUTION | QA_ONLY
+Mode: BEGINNER_GUIDED | IDEA_TO_STORE | EXISTING_PROJECT | FEATURE_EXECUTION | QA_ONLY
 Delivery Profile: SMALLEST_MVP | DEMO_GRADE_MVP | PRODUCTION_READY_MVP
+Current Loop Stage: PLAN | DESIGN | TASK | IMPLEMENT | VERIFY | DEVICE_PROOF | MEMORY | NEXT_ACTION
+
+Beginner Checkpoint:
+- What happened:
+- Why it matters:
+- Decision needed: <plain-language request or "None">
+- What happens next:
 
 Artifacts Read:
 | Artifact | Status | Notes |
@@ -277,18 +338,24 @@ NEXT ACTION:
 ## System Prompt
 
 ```text
-You are MOBILE-HARNESS, the autonomous top-level orchestrator for Mobile AI Agents. You can take a mobile app from rough idea to shipped release, or take an existing project through implementation, tests, UI verification, device QA, and launch readiness with minimal human effort.
+You are MOBILE-HARNESS, the autonomous top-level orchestrator for Mobile AI Agents. Take a mobile app from rough idea to release, or guide an existing project through implementation and evidence-based verification.
 
 Coordinate specialized systems:
 - APPFORGE for discovery, PRD, design plan, tasks, dependencies, roadmap, and store prep.
-- Mobile Memory for long-term project memory across days or weeks.
-- mobile-ai-agents memory commands for local event capture, search, context injection, and MOBILE_MEMORY.md checkpoint generation when terminal access is available.
+- Mobile Memory and mobile-ai-agents memory commands for durable context and checkpoints.
 - AXIOM, SWIFT, DART, or BRIDGE for platform-specific code review.
 - /prd-verification for evidence-based PRD, design, task, test, and UI match checks.
+- /mobile-app-design for screens, navigation changes, redesigns, and reskins.
 - /mobile-mcp-qa for emulator, simulator, or real-device QA evidence.
-- /accessibility-audit, PERF, /perf-audit, CRASHER, LAUNCHPAD, SCRIBE, and PIPELINE when the lifecycle requires them.
+- Relevant accessibility, performance, crash, release, and store specialists when required.
+
+Require approved PRD, design, task, and dependency context before coding. If missing, create it through APPFORGE and wait for approval. Choose a delivery profile and design direction first.
+
+Use BEGINNER_GUIDED mode for a rough idea, a new mobile developer, or an unknown platform/stack. Ask only what cannot be inferred. Recommend one stack with plain-language reasons and tradeoffs. Create beginner-readable PRD.md, DESIGN.md, TASKS.md, DEPENDENCIES.md, ROADMAP.md, and MOBILE_MEMORY.md. Show the current stage in this fixed loop: PLAN -> DESIGN -> TASK -> IMPLEMENT -> VERIFY -> DEVICE PROOF -> MEMORY -> NEXT ACTION. Explain what happened, why it matters, any decision needed, and what happens next.
+
+Stop for product approval, credentials, destructive or irreversible actions, paid services, and public release approval. For demos or marketing, default to Demo-grade MVP with seeded data, multiple visible states, screenshot planning, and UI polish.
 
-Before coding, require approved PRD/design/task/dependency context. If missing, create or update it through APPFORGE and wait for approval. Before creating those artifacts, choose or ask for a delivery profile: Smallest MVP, Demo-grade MVP, or Production-ready MVP. Also choose or ask for the design direction: clean utility, polished consumer, playful gamified, premium wellness, dense dashboard, enterprise/admin, or custom reference. If the user is recording a demo, marketing the repo, or showing Loop Engineering, default to Demo-grade MVP and require a visually complete app with seeded data, multiple visible screens/states, screenshot plan, and UI polish pass. Be autonomous by default: create artifacts, choose safe defaults, run tools, verify results, and proceed to the next safe step without asking the user to do routine work. Ask only for product decisions, credentials, unavailable external systems, paid or irreversible actions, destructive actions, or approval gates. Work one task at a time. Modify only files required for the current task. After changes, run available tests, invoke the relevant platform reviewer, compare UI against the approved design, run /prd-verification against PRD.md, DESIGN.md, TASKS.md, evidence, and reports, use Mobile MCP for device evidence when available, and update MOBILE_MEMORY.md.
+Work on one task at a time and modify only required files. Use /mobile-app-design for UI work. Then run tests, platform review, UI comparison, /prd-verification, and /mobile-mcp-qa when available. Update MOBILE_MEMORY.md and run mobile-flight-recorder at session end.
 
 Never mark done unless acceptance criteria are met or exceptions are explicitly documented. Always produce MOBILE HARNESS REPORT with orchestration state, implementation summary, code review, tests, PRD verification, UI match, Mobile MCP QA, acceptance criteria with source references, Mobile Memory update, remaining issues, and one NEXT ACTION.
 

package/cli/commands/doctor.js

@@ -0,0 +1,182 @@
+'use strict';
+
+const childProcess = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { parseOptions } = require('../lib/options');
+const { inspectMcpConfiguration, loadProjectConfig } = require('./mcp');
+
+function executableOnPath(name, env, fsImpl) {
+  const entries = String(env.PATH || '').split(path.delimiter).filter(Boolean);
+  for (const entry of entries) {
+    const candidate = path.join(entry, name);
+    if (fsImpl.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function defaultRunner(command, args, env) {
+  const result = childProcess.spawnSync(command, args, {
+    encoding: 'utf8',
+    env,
+    timeout: 10000,
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error ? result.error.message : '',
+  };
+}
+
+function resultStatus(checks) {
+  if (checks.some(check => check.status === 'FAIL')) return 'FAIL';
+  if (checks.some(check => check.status === 'WARN')) return 'WARN';
+  return 'PASS';
+}
+
+function parseAdbDevices(output) {
+  return String(output)
+    .split(/\r?\n/)
+    .slice(1)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .map(line => {
+      const [serial, state] = line.split(/\s+/);
+      return { serial, state };
+    });
+}
+
+function collectAndroidDoctor(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const env = options.env || process.env;
+  const homedir = options.homedir || os.homedir();
+  const fsImpl = options.fsImpl || fs;
+  const runner = options.runner || defaultRunner;
+  const checks = [];
+  const sdkCandidates = [
+    env.ANDROID_HOME,
+    env.ANDROID_SDK_ROOT,
+    path.join(homedir, 'Library', 'Android', 'sdk'),
+    path.join(homedir, 'Android', 'Sdk'),
+  ].filter(Boolean);
+  const sdkRoot = sdkCandidates.find(candidate => fsImpl.existsSync(candidate));
+
+  checks.push(sdkRoot
+    ? { id: 'android-sdk', status: 'PASS', summary: `Android SDK found at ${sdkRoot}` }
+    : {
+      id: 'android-sdk',
+      status: 'FAIL',
+      summary: 'Android SDK was not found.',
+      action: 'Install Android Studio/SDK and set ANDROID_HOME or ANDROID_SDK_ROOT.',
+    });
+
+  const adb = executableOnPath('adb', env, fsImpl) ||
+    (sdkRoot && fsImpl.existsSync(path.join(sdkRoot, 'platform-tools', 'adb')) ? path.join(sdkRoot, 'platform-tools', 'adb') : null);
+  if (!adb) {
+    checks.push({
+      id: 'adb',
+      status: 'FAIL',
+      summary: 'adb was not found.',
+      action: 'Install Android SDK Platform-Tools and add platform-tools to PATH.',
+    });
+  } else {
+    const version = runner(adb, ['version'], env);
+    checks.push(version.status === 0
+      ? { id: 'adb', status: 'PASS', summary: `adb available at ${adb}`, details: version.stdout.split(/\r?\n/)[0] }
+      : { id: 'adb', status: 'FAIL', summary: 'adb exists but could not run.', details: version.stderr || version.error, action: 'Repair Platform-Tools or PATH permissions.' });
+
+    const devicesResult = runner(adb, ['devices'], env);
+    const devices = devicesResult.status === 0 ? parseAdbDevices(devicesResult.stdout) : [];
+    checks.push(devicesResult.status !== 0
+      ? { id: 'android-devices', status: 'FAIL', summary: 'adb could not list devices.', details: devicesResult.stderr || devicesResult.error, action: 'Restart adb and reconnect or authorize the target device.' }
+      : devices.some(device => device.state === 'device')
+        ? { id: 'android-devices', status: 'PASS', summary: `${devices.filter(device => device.state === 'device').length} ready Android device(s).`, details: devices }
+        : { id: 'android-devices', status: 'WARN', summary: 'No ready Android device or emulator is connected.', details: devices, action: 'Start an emulator or connect and authorize a device.' });
+  }
+
+  const emulator = executableOnPath('emulator', env, fsImpl) ||
+    (sdkRoot && fsImpl.existsSync(path.join(sdkRoot, 'emulator', 'emulator')) ? path.join(sdkRoot, 'emulator', 'emulator') : null);
+  if (!emulator) {
+    checks.push({
+      id: 'android-emulator',
+      status: 'WARN',
+      summary: 'Android Emulator command was not found.',
+      action: 'Install Android Emulator from SDK Manager if emulator QA is required.',
+    });
+  } else {
+    const avdResult = runner(emulator, ['-list-avds'], env);
+    const avds = avdResult.status === 0 ? avdResult.stdout.split(/\r?\n/).map(v => v.trim()).filter(Boolean) : [];
+    checks.push(avdResult.status !== 0
+      ? { id: 'android-emulator', status: 'WARN', summary: 'Emulator exists but AVDs could not be listed.', details: avdResult.stderr || avdResult.error, action: 'Open Android Studio Device Manager and repair the emulator installation.' }
+      : avds.length
+        ? { id: 'android-emulator', status: 'PASS', summary: `${avds.length} Android Virtual Device image(s) available.`, details: avds }
+        : { id: 'android-emulator', status: 'WARN', summary: 'No Android Virtual Device images are configured.', action: 'Create an AVD in Android Studio Device Manager.' });
+  }
+
+  const mcpConfigs = inspectMcpConfiguration({ cwd, homedir, fsImpl });
+  checks.push(mcpConfigs.length
+    ? { id: 'mobile-mcp', status: 'PASS', summary: `Mobile MCP configured for ${mcpConfigs.map(item => item.client).join(', ')}.`, details: mcpConfigs.map(item => item.file) }
+    : { id: 'mobile-mcp', status: 'WARN', summary: 'Mobile MCP is not configured for a supported client.', action: 'Run mobile-ai-agents mcp setup --client <client>.' });
+
+  const project = loadProjectConfig({ cwd, fsImpl, configPath: options.configPath });
+  if (!project.config) {
+    checks.push({
+      id: 'project-config',
+      status: 'WARN',
+      summary: 'Android device QA project configuration is missing.',
+      action: 'Run mobile-ai-agents mcp config init --app-id com.example.app.',
+    });
+  } else if (project.errors.length) {
+    checks.push({
+      id: 'project-config',
+      status: 'FAIL',
+      summary: 'Android device QA project configuration is invalid.',
+      details: project.errors,
+      action: 'Run mobile-ai-agents mcp config validate and correct the listed fields.',
+    });
+  } else {
+    const apk = path.resolve(cwd, project.config.apkPath);
+    checks.push(fsImpl.existsSync(apk)
+      ? { id: 'project-config', status: 'PASS', summary: 'Android device QA project configuration is valid.', details: project.file }
+      : { id: 'project-config', status: 'WARN', summary: 'Project configuration is valid, but the APK does not exist yet.', details: project.config.apkPath, action: 'Build the configured APK before device QA.' });
+  }
+
+  return {
+    platform: 'android',
+    status: resultStatus(checks),
+    checkedAt: new Date().toISOString(),
+    checks,
+  };
+}
+
+function printDoctorReport(report) {
+  console.log('');
+  console.log('  Android Environment Doctor');
+  console.log(`  Result: ${report.status}`);
+  console.log('');
+  for (const check of report.checks) {
+    const icon = check.status === 'PASS' ? '✓' : check.status === 'WARN' ? '!' : '✗';
+    console.log(`  ${icon} [${check.status}] ${check.summary}`);
+    if (check.action) console.log(`    Action: ${check.action}`);
+  }
+  console.log('');
+}
+
+async function cmdDoctor(args) {
+  const opts = parseOptions(args);
+  const platform = opts.platform === true ? '' : opts.platform;
+  if (platform !== 'android') throw new Error('doctor currently requires --platform android.');
+  const report = collectAndroidDoctor({ configPath: opts.config === true ? undefined : opts.config });
+  if (opts.json) console.log(JSON.stringify(report, null, 2));
+  else printDoctorReport(report);
+  if (report.status === 'FAIL') process.exitCode = 1;
+  return report;
+}
+
+module.exports = {
+  cmdDoctor,
+  collectAndroidDoctor,
+  parseAdbDevices,
+};