@sun-asterisk/sungen 3.2.2-beta.10 → 3.2.2-beta.13

package/src/orchestrator/project-initializer.ts

@@ -7,16 +7,31 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import { AI_RULES_FILE_MAPPING } from './ai-rules-updater';
+import {
+  MobileInitOptions,
+  emitMobileRuntime,
+  writeMobileCapabilities,
+  installMobileDriver,
+} from './mobile-runtime-scaffolder';
+
+export { MobileInitOptions };
 
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  private mobile: MobileInitOptions;
 
-  constructor(private baseUrl: string) {
+  constructor(private baseUrl: string, mobile?: MobileInitOptions) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
+    this.mobile = mobile ?? { enabled: false };
+  }
+
+  /** Mobile-only project: no Playwright/web scaffolding. */
+  private get mobileOnly(): boolean {
+    return !!this.mobile.mobileOnly;
   }
 
   /**
@@ -30,34 +45,41 @@ export class ProjectInitializer {
     this.createdItems = [];
     this.skippedItems = [];
 
-    console.log('🚀 Initializing Sungen project...\n');
+    console.log(`🚀 Initializing Sungen ${this.mobileOnly ? 'mobile-only ' : ''}project...\n`);
 
     if (normalizedProjectName) {
       this.createProjectRoot(normalizedProjectName);
     }
 
-    // Create directories
+    // Create directories (mobile-only skips the web Playwright storage dir)
     this.createDirectories();
 
     // Create qa/context.md for QA lead to fill project-wide context
     this.createContext();
 
-    // Create qa/capabilities.yaml — the platform driver profile (default: web/Playwright)
+    // Create qa/capabilities.yaml — web default; mobile path uses writeMobileCapabilities
     this.createCapabilities();
 
-    // Ensure package.json and install Playwright
+    // Ensure package.json and install deps (Playwright for web; skipped for mobile-only)
     await this.setupDependencies();
 
-    // Create playwright config if doesn't exist
-    this.createPlaywrightConfig();
+    // Web-only scaffolding — skipped entirely for a mobile-only project
+    if (!this.mobileOnly) {
+      this.createPlaywrightConfig();
+      this.createSpecsBase();
+    }
 
-    // Create tsconfig.json if doesn't exist
+    // Create tsconfig.json if doesn't exist (needed by both web + mobile)
     this.createTsConfig();
 
-    // Create specs/base.ts for shared context and specs/test-data.ts for runtime data
-    this.createSpecsBase();
+    // specs/test-data.ts (runtime YAML loader) — shared by BOTH web and mobile specs
     this.createSpecsTestData();
 
+    // Mobile harness (Appium/WebdriverIO) — when `--mobile` (a mobile-only project)
+    if (this.mobile.enabled) {
+      this.emitMobileHarness();
+    }
+
     // Create/update .gitignore
     this.updateGitignore();
 
@@ -90,17 +112,14 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create essential directories only
+   * Create essential directories only.
+   * Mobile-only: skips specs/storage (Playwright auth state); qa/screens + qa/flows still created
+   * (1-platform model — mobile uses the same tree as web, NOT a separate qa/mobile/ path).
    */
   private createDirectories(): void {
-    const dirs = [
-      'qa',
-      'qa/screens',
-      'qa/flows',
-      'specs',
-      'specs/generated',
-      'specs/storage',
-    ];
+    const dirs = this.mobileOnly
+      ? ['qa', 'qa/screens', 'qa/flows', 'specs', 'specs/generated']
+      : ['qa', 'qa/screens', 'qa/flows', 'specs', 'specs/generated', 'specs/storage'];
 
     for (const dir of dirs) {
       const fullPath = path.join(this.cwd, dir);
@@ -147,13 +166,17 @@ export class ProjectInitializer {
   }
 
   /**
-   * Update .gitignore with Sungen-specific entries
+   * Update .gitignore with Sungen-specific entries.
+   * Mobile projects add .env.appium (device ids + machine paths) and specs/.auth-mobile/
+   * (Appium auth contract). Web projects add Playwright auth state + report dirs.
    */
   private updateGitignore(): void {
     const gitignorePath = path.join(this.cwd, '.gitignore');
     const sungenEntries = [
       '# Sungen generated files',
       'specs/.auth/',          // session storage state = cookies/tokens (sensitive)
+      'specs/.auth-mobile/',   // mobile auth contract = credentials (sensitive)
+      '.env.appium',           // local mobile-test env = machine paths + device/team ids (.example IS committed)
       'test-results/',
       'playwright-report/',
       '.playwright-mcp/',
@@ -199,7 +222,8 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create VS Code settings for Copilot auto-attach
+   * Create VS Code settings for Copilot auto-attach.
+   * Mobile-only: approves wdio + npx appium instead of npx playwright.
    */
   private createVSCodeSettings(): void {
     const settingsPath = path.join(this.cwd, '.vscode', 'settings.json');
@@ -214,7 +238,9 @@ export class ProjectInitializer {
         'github.copilot.chat.agent.runTasks': true,
         'chat.tools.terminal.autoApprove': {
           sungen: true,
-          'npx playwright': true,
+          ...(this.mobileOnly
+            ? { wdio: true, 'npx appium': true }
+            : { 'npx playwright': true }),
         },
       };
 
@@ -224,15 +250,14 @@ export class ProjectInitializer {
       this.skippedItems.push('.vscode/settings.json');
     }
 
-    // .vscode/mcp.json (Copilot format) — safe-merge Playwright + Figma entries
+    // .vscode/mcp.json (Copilot format) — appium-mcp for mobile-only, Playwright MCP otherwise
     this.mergeMCPConfig(
       path.join(this.cwd, '.vscode', 'mcp.json'),
       'servers',
       {
-        playwright: {
-          command: 'npx',
-          args: ['@playwright/mcp@latest'],
-        },
+        ...(this.mobileOnly
+          ? { 'appium-mcp': { command: 'npx', args: ['-y', 'appium-mcp'] } }
+          : { playwright: { command: 'npx', args: ['@playwright/mcp@latest'] } }),
         figma: {
           type: 'http',
           url: 'https://mcp.figma.com/mcp',
@@ -243,18 +268,17 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create root .mcp.json for Claude Code — safe-merge Playwright + Figma entries
+   * Create root .mcp.json for Claude Code.
+   * Mobile-only: appium-mcp instead of Playwright MCP. Figma always included.
    */
   private createClaudeMCPConfig(): void {
     this.mergeMCPConfig(
       path.join(this.cwd, '.mcp.json'),
       'mcpServers',
       {
-        playwright: {
-          type: 'stdio',
-          command: 'npx',
-          args: ['@playwright/mcp@latest'],
-        },
+        ...(this.mobileOnly
+          ? { 'appium-mcp': { type: 'stdio', command: 'npx', args: ['-y', 'appium-mcp'] } }
+          : { playwright: { type: 'stdio', command: 'npx', args: ['@playwright/mcp@latest'] } }),
         figma: {
           type: 'http',
           url: 'https://mcp.figma.com/mcp',
@@ -337,10 +361,18 @@ export class ProjectInitializer {
     if (projectName) {
       console.log(`  ${stepIndex++}. cd ${projectName}`);
     }
-    console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name> --path <url-path>`);
-    console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
-    console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
-    console.log(`  ${stepIndex++}. Run tests: npx playwright test\n`);
+    if (this.mobileOnly) {
+      console.log(`  ${stepIndex++}. Fill in .env.appium with your device/app details (see .env.appium.example)`);
+      console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name>`);
+      console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live app`);
+      console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
+      console.log(`  ${stepIndex++}. Run tests: npm run test:mobile\n`);
+    } else {
+      console.log(`  ${stepIndex++}. Create your first screen: sungen add --screen <name> --path <url-path>`);
+      console.log(`  ${stepIndex++}. Use AI (Copilot/Claude) to generate Gherkin + selectors from the live page`);
+      console.log(`  ${stepIndex++}. Compile tests: sungen generate --screen <name>`);
+      console.log(`  ${stepIndex++}. Run tests: npx playwright test\n`);
+    }
   }
 
   /**
@@ -390,8 +422,9 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create qa/capabilities.yaml — the platform driver profile (Phase 2a).
-   * Defaults to `web` (Playwright). Mobile/API projects switch via `sungen capability add`.
+   * Create qa/capabilities.yaml — the platform driver profile.
+   * Web default: platform=web, enabled=[web].
+   * Mobile: platform=mobile, enabled=[mobile] (via writeMobileCapabilities from the scaffolder).
    */
   private createCapabilities(): void {
     const p = path.join(this.cwd, 'qa', 'capabilities.yaml');
@@ -399,13 +432,18 @@ export class ProjectInitializer {
       this.skippedItems.push('qa/capabilities.yaml');
       return;
     }
-    const content =
-      '# Sungen capability profile — which runtime/drivers this project uses.\n' +
-      '# platform: the runtime adapter — web → Playwright, mobile → Appium.\n' +
-      '# enabled: drivers turned on (add more via `sungen capability add <driver>`).\n\n' +
-      'platform: web\n' +
-      'enabled:\n  - web\n';
-    fs.writeFileSync(p, content, 'utf-8');
+
+    if (this.mobile.enabled) {
+      writeMobileCapabilities(this.cwd);
+    } else {
+      const content =
+        '# Sungen capability profile — which runtime/drivers this project uses.\n' +
+        '# platform: the runtime adapter — web → Playwright, mobile → Appium.\n' +
+        '# enabled: drivers turned on (add more via `sungen capability add <driver>`).\n\n' +
+        'platform: web\n' +
+        'enabled:\n  - web\n';
+      fs.writeFileSync(p, content, 'utf-8');
+    }
     this.createdItems.push('qa/capabilities.yaml');
   }
 
@@ -451,6 +489,20 @@ export class ProjectInitializer {
     this.createdItems.push('specs/generated/test-data.ts');
   }
 
+  /**
+   * Delegate to mobile-runtime-scaffolder to emit Appium/WDIO harness files,
+   * then best-effort install @sungen/driver-mobile at lockstep version.
+   * Called only when `--mobile` is set.
+   */
+  private emitMobileHarness(): void {
+    const result = emitMobileRuntime(this.cwd, this.mobile);
+    this.createdItems.push(...result.created);
+    this.skippedItems.push(...result.skipped);
+
+    // Best-effort driver install — non-fatal so offline init still scaffolds.
+    installMobileDriver(this.cwd);
+  }
+
   /**
    * Read a template file from the templates directory
    */
@@ -476,8 +528,11 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
-    // Check which dependencies are missing
-    const requiredDeps = ['@playwright/test', '@types/node', 'yaml'];
+    // Mobile-only drops @playwright/test (no web runner needed).
+    const requiredDeps = this.mobileOnly
+      ? ['@types/node', 'yaml']
+      : ['@playwright/test', '@types/node', 'yaml'];
+
     let missingDeps: string[] = requiredDeps;
     try {
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
@@ -489,15 +544,17 @@ export class ProjectInitializer {
 
     if (missingDeps.length === 0) {
       console.log('✓ All dependencies already installed\n');
-      return;
+    } else {
+      console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
+      execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
     }
 
-    console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
-    execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
-
-    console.log('\n🎭 Installing Chromium (default browser)...\n');
-    execSync('npx playwright install --with-deps chromium', execOpts);
-    console.log('\n💡 To install other browsers: npm run install:browsers -- firefox webkit\n');
+    // Chromium is only needed for the web (Playwright) runner — skip for mobile-only projects.
+    if (!this.mobileOnly) {
+      console.log('\n🎭 Installing Chromium (default browser)...\n');
+      execSync('npx playwright install --with-deps chromium', execOpts);
+      console.log('\n💡 To install other browsers: npm run install:browsers -- firefox webkit\n');
+    }
   }
 
   /**
@@ -516,15 +573,21 @@ export class ProjectInitializer {
       packageJson.scripts = {};
     }
 
-    const standardScripts: Record<string, string> = {
-      'test': 'playwright test specs/generated/',
-      'test:headed': 'playwright test specs/generated/ --headed',
-      'test:debug': 'playwright test specs/generated/ --debug',
-      'test:ui': 'playwright test specs/generated/ --ui',
-      'report': 'playwright show-report',
-      'generate': 'sungen generate --all',
-      'install:browsers': 'npx playwright install',
-    };
+    // Mobile-only projects get just the generate + mobile-run scripts (no Playwright web scripts).
+    const standardScripts: Record<string, string> = this.mobileOnly
+      ? {
+          'generate': 'sungen generate --all',
+          'test:mobile': 'wdio run wdio.conf.ts',
+        }
+      : {
+          'test': 'playwright test specs/generated/',
+          'test:headed': 'playwright test specs/generated/ --headed',
+          'test:debug': 'playwright test specs/generated/ --debug',
+          'test:ui': 'playwright test specs/generated/ --ui',
+          'report': 'playwright show-report',
+          'generate': 'sungen generate --all',
+          'install:browsers': 'npx playwright install',
+        };
 
     let added = 0;
     for (const [name, command] of Object.entries(standardScripts)) {

package/src/orchestrator/screen-manager.ts

@@ -6,6 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { chromium } from '@playwright/test';
+import { readCapabilities } from '../harness/capability';
 
 export interface ScreenOptions {
   name: string;
@@ -13,6 +14,20 @@ export interface ScreenOptions {
   capture?: boolean;
   feature?: string;
   description?: string;
+  /**
+   * Optional per-OS tag emitter: 'android' | 'ios'. When set, the feature stub
+   * gets @platform:android or @platform:ios for OS-specific screens. Does NOT
+   * affect directory routing (always qa/screens/). Mobile project is detected via
+   * qa/capabilities.yaml, not this flag.
+   */
+  platform?: string;
+  /**
+   * Mobile navigation recipe (the in-app web-path analog). A `>`-separated list of nav steps
+   * that take the app from launch to THIS screen, e.g. "tap [My Page] tab > tap [Settings] row".
+   * Scaffolded into the feature's Background after the `Given User is on [Home] screen` anchor.
+   * Mobile-only; ignored (with a warning) for web projects. Omit when this IS the launcher screen.
+   */
+  reach?: string;
 }
 
 export class ScreenManager {
@@ -31,15 +46,31 @@ export class ScreenManager {
     // Validate screen name
     this.validateScreenName(options.name);
 
+    // Detect project platform from qa/capabilities.yaml (single source of truth)
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    // --reach is mobile-only; warn and drop when the project is web
+    if (options.reach && !isMobile) {
+      console.warn(
+        `Warning: --reach is a mobile navigation recipe and is ignored for web projects ` +
+        `(web screens are addressed by their --path URL). Dropping it.`
+      );
+      options = { ...options, reach: undefined };
+    }
+
     // Normalize screen name for directory
     const screenName = this.normalizeScreenName(options.name);
+    // Always use qa/screens/ regardless of platform (1-platform model — no qa/mobile/ tree)
     const screenDir = path.join(this.screensDir, screenName);
 
-    // Derive filename: --feature flag creates "<screen>-<feature>" name
+    // Derive filename: --feature flag creates "<screen>-<feature>" name.
+    // For mobile, `path` is the app entry (pkg/Activity), NOT a URL — never derive
+    // the filename from it; use the screen name instead.
     let filename: string;
     if (options.feature) {
       filename = `${screenName}-${this.normalizeScreenName(options.feature)}`;
-    } else if (options.path) {
+    } else if (options.path && !isMobile) {
       filename = this.extractFilenameFromPath(options.path);
     } else {
       filename = screenName;
@@ -92,18 +123,25 @@ export class ScreenManager {
     const featureContent = this.generateFeatureTemplate(options, filename);
     fs.writeFileSync(featurePath, featureContent, 'utf-8');
 
-    // Generate empty selector YAML (with page entry)
+    // Generate empty selector YAML. Web gets a `page` entry (the route); mobile
+    // selectors come from Appium MCP at run-test, so it's just a header comment.
     if (!fs.existsSync(selectorPath)) {
-      const pagePath = options.path || `/${screenName}`;
-      fs.writeFileSync(selectorPath, [
-        `# ${options.name} Screen Selectors`,
-        `# Fill via AI or manually`,
-        ``,
-        `${screenName}:`,
-        `  type: 'page'`,
-        `  value: '${pagePath}'`,
-        ``,
-      ].join('\n'), 'utf-8');
+      const selectorLines = isMobile
+        ? [
+            `# ${options.name} Screen Selectors (mobile)`,
+            `# Generated at /sungen:run-test via Appium MCP — accessibility-id preferred.`,
+            ``,
+          ]
+        : [
+            `# ${options.name} Screen Selectors`,
+            `# Fill via AI or manually`,
+            ``,
+            `${screenName}:`,
+            `  type: 'page'`,
+            `  value: '${options.path || `/${screenName}`}'`,
+            ``,
+          ];
+      fs.writeFileSync(selectorPath, selectorLines.join('\n'), 'utf-8');
     }
 
     // Generate empty test-data YAML
@@ -186,9 +224,9 @@ export class ScreenManager {
       ].join('\n'), 'utf-8');
     }
 
-    // Auto-screenshot: capture page only when --capture is set (requires --path)
+    // Auto-screenshot: capture page only when --capture is set and not mobile (requires --path)
     // Use filename (not screenName) so each feature gets its own screenshots
-    if (options.capture && options.path) {
+    if (options.capture && options.path && !isMobile) {
       await this.captureScreenshot(options.path, requirementsUiDir, filename);
     }
 
@@ -204,12 +242,21 @@ export class ScreenManager {
     }
     console.log('');
 
-    console.log('Next steps:');
-    console.log(`  1. Fill requirements/spec.md with screen spec (fields, validation, business rules)`);
-    console.log(`     Optionally add UI designs to requirements/ui/ (screenshots, mockups)`);
-    console.log(`  2. Generate test cases: /sungen:create-test ${screenName} (or /sungen-create-test)`);
-    console.log(`  3. Compile: sungen generate --screen ${screenName}`);
-    console.log(`  4. Run: npx playwright test\n`);
+    if (isMobile) {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with screen spec (elements, actions, business rules)`);
+      console.log(`     Use /sungen:add-screen with sungen-capture-mobile to scan via Appium MCP`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${screenName}`);
+      console.log(`  3. Compile: sungen generate --screen ${screenName} --framework appium`);
+      console.log(`  4. Run: npm run test:mobile\n`);
+    } else {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with screen spec (fields, validation, business rules)`);
+      console.log(`     Optionally add UI designs to requirements/ui/ (screenshots, mockups)`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${screenName} (or /sungen-create-test)`);
+      console.log(`  3. Compile: sungen generate --screen ${screenName}`);
+      console.log(`  4. Run: npx playwright test\n`);
+    }
   }
 
   /**
@@ -291,6 +338,57 @@ export class ScreenManager {
   }
 
   private generateSpecTemplate(options: ScreenOptions, screenName: string): string {
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    if (isMobile) {
+      const appEntry = options.path || this.readWdioAppEntry() || '<appPackage>';
+      return `# ${options.name} Screen Specification
+
+## Overview
+- **App Entry:** ${appEntry}
+- **Platform:** mobile (Android + iOS)
+- **Auth Required:** no
+- **Reach:** ${options.reach || '<!-- nav recipe: how to reach this screen from app launch, e.g. "tap [My Page] tab > tap [Settings] row" -->'}
+
+## Sections
+
+### Section: [Section Name]
+- **Type:** list | card | form | modal | navigation | tab-bar
+- **Description:** [Brief description of this section]
+
+#### Elements
+| Element | Type | Identifier | Notes |
+|---------|------|------------|-------|
+| [Element Name] | button | accessibility-id | [tap target, e.g., submits form] |
+
+#### Actions
+| Action | Element | Behavior |
+|--------|---------|----------|
+| [Action Name] | button | [What happens on tap] |
+
+#### States
+| State | Condition | Visual |
+|-------|-----------|--------|
+| Default | Screen load | [Default appearance] |
+| Loading | After tap | [Loading indicator] |
+| Error | Action fails | [Error appearance] |
+| Success | Action complete | [Success behavior] |
+
+## Business Rules
+<!-- Rules that affect test logic: limits, permissions, conditions -->
+- [Rule 1]
+
+## Accessibility
+<!-- Accessibility IDs, content-desc, aria-labels -->
+- Accessibility IDs: [element: id]
+
+## Notes
+<!-- Edge cases, known issues, environment-specific behavior -->
+- [Note 1]
+`;
+    }
+
     const pagePath = options.path || `/${screenName}`;
     return `# ${options.name} Screen Specification
 
@@ -348,9 +446,48 @@ export class ScreenManager {
 
   private generateFeatureTemplate(options: ScreenOptions, filename: string): string {
     const screenName = this.normalizeScreenName(options.name);
-    const featurePath = options.path || `/${screenName}`;
     const description = options.description || `interact with the ${options.name} screen`;
 
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    if (isMobile) {
+      // Determine platform tag: --platform android/ios emits a per-OS tag for OS-specific screens.
+      // Default (no --platform) = cross-platform, no OS-specific tag.
+      const platformTag =
+        options.platform === 'android' ? '@platform:android'
+        : options.platform === 'ios' ? '@platform:ios'
+        : '@platform:mobile';
+
+      // App entry: explicit --path → wdio.conf.ts default → placeholder.
+      const appEntry = options.path || this.readWdioAppEntry() || '<appPackage>';
+
+      // Navigation recipe (Background block)
+      const background = this.buildMobileBackground(options.reach);
+
+      return `${platformTag}
+Feature: ${options.name} Screen
+
+  As a user
+  I want to ${description}
+  So that I can accomplish my tasks
+  Path: ${appEntry}
+
+  # Mobile (Appium) — selectors generated at /sungen:run-test via Appium MCP.
+  # Use accessibility-id selectors; assert text content with \`header with {{var}}\`
+  # (compiles to content-desc/label via toHaveAttribute). See sungen-mobile-gestures
+  # for swipe/long-press/scroll steps.
+
+${background}
+  @high
+  Scenario: Sample scenario for ${options.name}
+    When User tap [element]
+    Then User see [result] header with {{result_text}}
+`;
+    }
+
+    // Web feature stub
+    const featurePath = options.path || `/${screenName}`;
     return `Feature: ${options.name} Screen
 
   As a user
@@ -367,4 +504,82 @@ export class ScreenManager {
     Then User see [result] text with {{success}}
 `;
   }
+
+  /**
+   * Read the default app entry (`<appPackage>/<appActivity>`) from the project's wdio.conf.ts so a
+   * mobile `add-screen` without `--path` scaffolds a real, runnable `Path:` matching the configured
+   * app instead of a `<placeholder>`. Supports both the env-default form
+   * (`APP_PACKAGE = process.env.APP_PACKAGE || '…'`) and the literal capability form
+   * (`'appium:appPackage': '…'`). Returns null when wdio.conf.ts is absent or unparseable.
+   */
+  private readWdioAppEntry(): string | null {
+    const wdioPath = path.join(this.cwd, 'wdio.conf.ts');
+    if (!fs.existsSync(wdioPath)) return null;
+    let src: string;
+    try {
+      src = fs.readFileSync(wdioPath, 'utf-8');
+    } catch {
+      return null;
+    }
+    const pick = (re: RegExp): string | undefined => src.match(re)?.[1]?.trim();
+    const pkg =
+      pick(/APP_PACKAGE\s*=\s*process\.env\.APP_PACKAGE\s*\|\|\s*['"]([^'"]+)['"]/) ??
+      pick(/['"]appium:appPackage['"]\s*:\s*['"]([^'"]+)['"]/);
+    if (!pkg) return null;
+    const activity =
+      pick(/APP_ACTIVITY\s*=\s*process\.env\.APP_ACTIVITY\s*\|\|\s*['"]([^'"]+)['"]/) ??
+      pick(/['"]appium:appActivity['"]\s*:\s*['"]([^'"]+)['"]/);
+    return activity ? `${pkg}/${activity}` : pkg;
+  }
+
+  /**
+   * Build the Background block for a mobile screen — the navigation recipe (in-app web-path
+   * analog). Line 1 is the `Given User is on [Home] screen` launcher/landing anchor; each step
+   * from `--reach` (a `>`-separated list) becomes a `When/And User <step>` nav line, taking the
+   * app from launch to THIS screen. capture-mobile replays these to land on the target screen
+   * before scanning. With no recipe, emit a guided stub (anchor + commented placeholder).
+   */
+  private buildMobileBackground(reach?: string): string {
+    // Normalize one nav segment to a bare step body ("tap [My Page] tab"): drop any leading
+    // Gherkin keyword and a leading "User " so we can re-emit "When/And User <body>" cleanly.
+    const normalizeStep = (raw: string): string =>
+      raw
+        .trim()
+        .replace(/^(given|when|and|then|but)\s+/i, '')
+        .replace(/^user\s+/i, '')
+        .trim();
+
+    const steps = (reach || '')
+      .split('>')
+      .map(normalizeStep)
+      .filter(Boolean);
+
+    if (steps.length === 0) {
+      // No recipe → guided stub. Keep the anchor (correct as-is when this IS the launcher
+      // screen); the comments tell create-test / capture-mobile how to fill the nav steps.
+      return [
+        '  Background:',
+        '    # Navigation recipe — how to reach THIS screen from app launch (the in-app',
+        '    # web-path analog). Line 1 is the launcher/landing screen the app opens on;',
+        '    # add a `When/And User tap [...]` per hop to reach this screen. capture-mobile',
+        '    # replays these so Appium lands here (not the launcher) before scanning. Leave',
+        '    # only the anchor if this IS the launcher screen. Prefill with',
+        '    # --reach "tap [Tab] > tap [Row]" at add-screen time.',
+        '    Given User is on [Home] screen',
+        '    # When User tap [<tab or button that leads to this screen>]',
+        '',
+      ].join('\n');
+    }
+
+    const navLines = steps.map(
+      (body, i) => `    ${i === 0 ? 'When' : 'And'} User ${body}`,
+    );
+    return [
+      '  Background:',
+      '    # Navigation recipe — replayed by capture-mobile to land on this screen before scanning.',
+      '    Given User is on [Home] screen',
+      ...navLines,
+      '',
+    ].join('\n');
+  }
 }