@sun-asterisk/sungen 3.2.3 → 3.2.5

package/src/generators/test-generator/adapters/appium/templates/steps/partials/locator.hbs

@@ -4,5 +4,12 @@
       YAML) is the fallback parent. Note: a child xpath beginning with `//` is ABSOLUTE in Appium even
       when chained — use accessibility-id / -android uiautomator children for true scoping, or `.//`.
       The selector argument comes from appium-selector-expr (it carries its OWN quotes, or a per-platform
-      `driver.isIOS ? … : …` ternary), so it is NOT wrapped in quotes here. --}}
-{{~#if parentLocator~}}{{parentLocator}}.{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{~else~}}{{#if scope}}$('~{{escapeQuotes scope}}').{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{else}}{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{/if}}{{~/if~}}
+      `driver.isIOS ? … : …` ternary), so it is NOT wrapped in quotes here.
+      Simple case (no parent/scope/nth) resolves via `__ensureVisible(...)` — Playwright-style implicit
+      scroll-into-view, so a below-fold / nav-occluded element is scrolled into the safe band before any
+      find/tap/assert (Appium has no auto-scroll). Parent/scope/nth chains keep the plain `$()` — those
+      resolve within a container / by index where a blind scroll doesn't apply.
+      `plain=true` (passed by is-hidden-assertion) also forces the bare `$()`: an element asserted HIDDEN
+      is expected to be absent, so scroll-hunting for it is both pointless and harmful — the 12x down-scroll
+      would drag the screen to the bottom and strand later same-scenario steps that sit above. --}}
+{{~#if parentLocator~}}{{parentLocator}}.{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{~else~}}{{#if scope}}$('~{{escapeQuotes scope}}').{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}$({{> appium-selector-expr}}){{/if}}{{else}}{{#if nth}}$$({{> appium-selector-expr}})[{{nth}}]{{else}}{{#if plain}}$({{> appium-selector-expr}}){{else}}(await __ensureVisible({{> appium-selector-expr}})){{/if}}{{/if}}{{/if}}{{~/if~}}

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -5,6 +5,117 @@
 
 const testData = TestDataLoader.load('{{screenName}}', '{{featureFileName}}');
 {{/if}}
+
+// Auto scroll-into-view before EVERY element access — the mobile analogue of Playwright's implicit
+// scrollIntoView (Appium/WDIO has none). Fixes two Flutter/native failure modes at once:
+//   (A) lazy-render / zero-rect: an item below the fold is NOT usable (absent from the Android a11y
+//       tree; present-but-0x0 on iOS), so find/tap/assert fail even though scrolling would reveal it;
+//   (B) floating bottom-nav occlusion (Android): a row near the fold is "displayed" but its tap point
+//       sits behind the nav bar, so a coordinate tap misses.
+// Already-visible elements return immediately (no scroll, no cost). Returns $(selector) even when
+// never found so the caller's own step surfaces the real failure. The `selector` is re-queried each
+// iteration (post-scroll elements go stale). The readiness gate and gesture differ per OS — each
+// runtime lies differently (see the per-branch notes below).
+//
+// Android gates on isDisplayed() (reliable on UiAutomator2) + rect clearing the 0.82·H nav band,
+// and scrolls with mobile: scrollGesture — NOT UiScrollable, which no-ops on Flutter (no native
+// ScrollView).
+//
+// iOS gates on GEOMETRY, and scrolls with small drags. XCUITest reports a below-fold Flutter
+// element as rect 0x0 + displayed:false while keeping it in the tree, and isDisplayed() also
+// false-negatives on genuinely visible elements (snapshot artifact) — so visibility booleans are
+// unusable as a scroll gate on iOS. An element is "usable" iff its rect is REAL (width/height > 0)
+// with the top edge on screen; the width/height check is essential — a 0x0 rect has y=0, which a
+// naive `y >= 0` gate mistakes for "at the top of the screen" (that exact bug shipped once: it
+// skipped the scroll AND returned a stale 0x0 handle whose click went nowhere). Scrolling uses
+// `mobile: scroll {direction}` — native XCTest paged scroll, the only primitive that worked in a
+// live probe matrix on Flutter: `mobile: scroll {toVisible}` throws (WDA needs a scrollable
+// ancestor with visible children, but Flutter exposes content as SIBLINGS of the ScrollView),
+// `mobile: swipe` flings with momentum past the target, and dragFromToForDuration / W3C pointer
+// drags corrupt the a11y tree (targets vanish from it entirely).
+async function __ensureVisible(selector: string): Promise<WebdriverIO.Element> {
+  let winH = 2000;
+  try { const s = await driver.getWindowSize(); winH = s.height; } catch { /* keep default */ }
+  if (driver.isIOS) {
+    // Phase 1 — wait for the element to ENTER the tree WITHOUT gesturing. Right after the
+    // relaunch-per-scenario beforeEach nothing is rendered yet, and dragging a still-launching
+    // app makes XCUITest block on quiescence per gesture — enough to blow the mocha hook
+    // timeout (seen live). A below-fold Flutter element is IN the tree from the start (just
+    // 0x0), so in the genuine scroll case this wait returns instantly.
+    try { await (await $(selector)).waitForExist({ timeout: 15000 }); } catch { /* virtualized far item or missing → still try scrolling below */ }
+    for (let __i = 0; __i < 8; __i++) {
+      let existed = false;
+      try {
+        const el = await $(selector);
+        if (await el.isExisting()) {
+          existed = true;
+          const r = await driver.getElementRect(el.elementId);
+          if (r.width > 0 && r.height > 0 && r.y >= 0 && r.y < winH) return el; // real rect, on screen → usable
+        }
+      } catch { /* not in the tree yet → keep scrolling */ }
+      // Render grace — do NOT scroll on the first two passes when the element is in the tree but
+      // still 0x0: right after a relaunch Flutter briefly reports even TOP-OF-SCREEN elements as
+      // 0x0 while it renders, and a paged scroll fired in that window scrolls them clean off the
+      // top, where a down-only loop can never recover them (seen live as a random ~2-cases-per-run
+      // flake: "APP PREFERENCES rect 0x0"). A genuinely below-fold element just costs ~1s extra.
+      if (existed && __i < 2) { await driver.pause(500); continue; }
+      // `mobile: scroll {direction}` = native XCTest paged scroll — the ONLY primitive that moves
+      // this Flutter list deterministically (probed live): `mobile: swipe` flings past the target
+      // (momentum), and dragFromToForDuration / W3C pointer drags corrupt the a11y tree (targets
+      // vanish entirely). The page step is ~0.9 viewport with built-in overlap, so a below-fold
+      // element can never be jumped over — it lands near the top of the next page.
+      await driver.execute('mobile: scroll', { direction: 'down' })
+        .catch(() => driver.execute('mobile: swipe', { direction: 'up' }));
+      await driver.pause(400); // settle: let Flutter render the newly-exposed band
+    }
+    return $(selector);
+  }
+  const safeBottom = Math.round(winH * 0.82); // above the floating bottom-nav band
+  let lastY: number | null = null;
+  for (let __i = 0; __i < 12; __i++) {
+    let y: number | null = null;
+    try {
+      const el = await $(selector);
+      if (await el.isDisplayed()) {
+        const r = await driver.getElementRect(el.elementId);
+        if (r.y + r.height <= safeBottom) return el; // rendered AND fully above the floating bottom nav → done
+        y = r.y;
+      }
+    } catch { /* off-screen / not in tree yet → keep scrolling */ }
+    // No-progress break: the element is on screen but a prior scroll didn't move it — it's a FIXED
+    // element (e.g. a bottom-nav tab, intentionally in the nav band) or we've hit the end of the
+    // scrollable. Stop rather than burn the whole budget; the caller acts on it where it is.
+    if (y !== null && lastY !== null && Math.abs(y - lastY) < 2) return $(selector);
+    lastY = y;
+    await driver.execute('mobile: scrollGesture', { left: 60, top: 420, width: 960, height: 1320, direction: 'down', percent: 0.5 });
+    await driver.pause(300);
+  }
+  return $(selector);
+}
+
+// Visibility oracle for simple-case `see [X]` assertions. Android: WDIO's toBeDisplayed()
+// (reliable on UiAutomator2). iOS: XCUITest's `visible` attribute false-negatives on real,
+// on-screen elements (snapshot artifact — seen live even on a screen title every prior run
+// passed), so assert GEOMETRY instead: after __ensureVisible has scrolled the target toward
+// view, the element must exist with a real rect (w,h > 0) whose top edge is on screen. On
+// Flutter an off-screen element keeps a 0x0 rect, so this is exactly the "user can see it"
+// boundary. Re-queries fresh + retries briefly to absorb render lag.
+async function __assertVisible(selector: string): Promise<void> {
+  const el = await __ensureVisible(selector);
+  if (!driver.isIOS) { await expect(el).toBeDisplayed(); return; }
+  let winH = 2000;
+  try { const s = await driver.getWindowSize(); winH = s.height; } catch { /* keep default */ }
+  let r = { x: 0, y: 0, width: 0, height: 0 };
+  for (let __i = 0; __i < 3; __i++) {
+    try {
+      const e2 = await $(selector);
+      if (await e2.isExisting()) r = await driver.getElementRect(e2.elementId);
+    } catch { /* not in the tree */ }
+    if (r.width > 0 && r.height > 0 && r.y >= 0 && r.y < winH) return;
+    await driver.pause(500);
+  }
+  throw new Error(`Expect ${JSON.stringify(selector)} to be displayed — iOS geometry oracle: rect=${JSON.stringify(r)} is not on screen (0x0 = not rendered / scrolled out)`);
+}
 {{#if singleAuthRole}}
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -151,6 +262,10 @@ describe('{{featureName}}', () => {
   beforeEach(async () => {
     const __APP_PKG__ = __resolveAppId();
     try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
+    // Let the termination fully land before relaunching — activateApp racing a still-dying
+    // process can RESUME the old instance (prior scenario's scroll position and all) instead
+    // of cold-starting, which strands top-of-screen elements above the viewport.
+    await driver.pause(500);
     await driver.activateApp(__APP_PKG__);
     // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
     // app relaunch above resets in-app state, but device orientation is OS-level and persists.

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/table-action-in-row.hbs

@@ -1,2 +1,2 @@
 { const tableRow = {{> locator}}.getByRole('row').filter({ hasText: '{{escapeQuotes filterValue}}' });
-await tableRow.getByRole('{{elementRole}}', { name: '{{escapeQuotes elementName}}' }).{{action}}(); }
+await {{{actionLocator}}}.{{action}}(); }

package/src/generators/test-generator/patterns/index.ts

@@ -4,6 +4,23 @@ import { StepPattern, PatternContext } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
+/**
+ * Mask the CONTENT of selector refs `[...]` and data placeholders `{{...}}` before verb matching,
+ * keeping the delimiters. A step's verb/keywords come from the SENTENCE — never from a selector or
+ * variable NAME — but matchers scan `step.text` with substring checks (e.g. `includes('click')`),
+ * so a data ref like `{{double_click_guard_account.email}}` would spuriously satisfy the click
+ * matcher and pre-empt fill. The content is replaced with an inert placeholder (`~` — carries no
+ * verb/keyword/digit substring) rather than emptied, so structural matchers that require a NON-EMPTY
+ * ref survive too — e.g. `expect {{a}} is {{b}}` matches `\{\{[^}]+\}\}`, and `in [X] table` /
+ * `/\bto\s+\[/` keep their delimiters. The resolver/generator always receives the ORIGINAL step, so
+ * value extraction and codegen are unaffected.
+ */
+export function maskRefsForMatching(text: string): string {
+  return text
+    .replace(/\{\{[^}]*\}\}/g, '{{~}}')
+    .replace(/\[[^\]]*\]/g, '[~]');
+}
+
 /**
  * Pattern Registry - manages all step patterns
  */
@@ -40,8 +57,11 @@ export class PatternRegistry {
    * Find matching pattern for a step
    */
   findPattern(step: ParsedStep): StepPattern | null {
+    // Match against text with ref CONTENTS masked, so a verb substring inside a selector/data name
+    // (e.g. "click" in `{{double_click_guard_account.email}}`) can't hijack the verb classification.
+    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
     for (const pattern of this.patterns) {
-      if (this.matchesPattern(step, pattern.matcher)) {
+      if (this.matchesPattern(matchStep, pattern.matcher)) {
         return pattern;
       }
     }

package/src/harness/script-check.ts

@@ -92,10 +92,11 @@ export function analyzeFaithfulness(specSrc: string, automatedTitles: Set<string
 }
 
 function extractTestTitles(specSrc: string): string[] {
-  // Count real test cases only: test(...), test.only/.skip/.fixme(...).
-  // Exclude test.describe / test.beforeAll / hooks (not test cases).
+  // Count real test cases only. Web/Playwright specs use test(...) (+ .only/.skip/.fixme);
+  // mobile/Appium specs use mocha it(...) (#429 — matching only test() reported EVERY mobile
+  // scenario as MISSING). Exclude describe / hooks (not test cases).
   const titles: string[] = [];
-  const re = /\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/g;
+  const re = /\b(?:test|it)(?:\.(?:only|skip|fixme))?\(\s*(['"`])([^'"`]+)\1/g;
   let m: RegExpExecArray | null;
   while ((m = re.exec(specSrc))) titles.push(m[2].trim());
   return titles;
@@ -183,9 +184,13 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
       const qaSourceDir = path.join(process.cwd(), 'qa', kind === 'flow' ? 'flows' : kind === 'api' ? 'api' : 'screens');
       // api units derive their unit id (api/<area>) from the feature path — like `generate --api`;
       // screen/flow pass screenName + flowMode explicitly (unchanged → byte-identical regenerate).
+      // Regenerate with the SAME framework the committed spec was compiled with — a mobile spec
+      // (imports '@wdio/globals') was generated by the appium adapter; regenerating it with the
+      // playwright adapter guaranteed a false DRIFT on every mobile screen (#429).
+      const framework = specSrc.includes('@wdio/globals') ? 'appium' : 'playwright';
       const gen = kind === 'api'
-        ? new CodeGenerator({ framework: 'playwright', runtimeData: true })
-        : new CodeGenerator({ framework: 'playwright', screenName, runtimeData: true, flowMode: kind === 'flow' });
+        ? new CodeGenerator({ framework, runtimeData: true })
+        : new CodeGenerator({ framework, screenName, runtimeData: true, flowMode: kind === 'flow' });
       await gen.generateAllTests(qaSourceDir, tmp, [featurePath]);
       const fresh = findSpec(tmp, screenName, kind);
       if (fresh) {

package/src/orchestrator/ai-skills/writer.ts

@@ -3,8 +3,9 @@
  *
  *   managed (skills/commands): ALWAYS overwritten (version-managed, no rollback)
  *   config  (CLAUDE.md/AGENTS.md/copilot-instructions): skip-if-exists unless `force`
- *   orphans: managed files written last run but not this run are DELETED (manifest-derived,
- *            replaces the hand-curated STALE list — decision T2)
+ *   orphans: managed files written last run but not this run are DELETED — but ONLY within the
+ *            assistants built THIS run (scoped by namespace), so building one assistant never wipes
+ *            another's files (manifest-derived; replaces the hand-curated STALE list — decision T2)
  *   detect-and-warn: if a managed file on disk was hand-edited since we wrote it, warn
  *   dry-run: report adds/overwrites/skips/deletes/warnings without touching disk
  *
@@ -14,6 +15,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { BuiltFile } from './build';
+import { AdapterKey } from './adapters';
 
 export interface ApplyOptions { force?: boolean; dryRun?: boolean; version: string }
 export interface ApplyReport {
@@ -26,6 +28,20 @@ const sha = (s: string) => crypto.createHash('sha256').update(s).digest('hex');
 
 interface Manifest { version: string; managed: Record<string, string> }
 
+/**
+ * Which assistant a managed/config output path belongs to, by namespace prefix. Scopes orphan
+ * cleanup + manifest retention to the assistants built THIS run, so `sungen init --assistant codex`
+ * never deletes a previously-installed `.claude/` (and vice versa). Returns null for a path we
+ * can't attribute — treated as out-of-scope, so it is never auto-deleted.
+ */
+function adapterOf(relPath: string): AdapterKey | null {
+  const p = relPath.replace(/\\/g, '/');
+  if (p === 'CLAUDE.md' || p.startsWith('.claude/')) return 'claude';
+  if (p === 'AGENTS.md' || p.startsWith('.agents/')) return 'codex';
+  if (p === '.github/copilot-instructions.md' || p.startsWith('.github/')) return 'copilot';
+  return null;
+}
+
 function readManifest(cwd: string): Manifest {
   const p = path.join(cwd, MANIFEST_REL);
   if (!fs.existsSync(p)) return { version: '', managed: {} };
@@ -70,9 +86,19 @@ export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptio
     newManaged[f.outputPath] = sha(f.content);
   }
 
-  // Orphan cleanup: managed files we wrote last time but not now.
+  // Assistants this run actually produced output for. Orphan cleanup is scoped to THESE namespaces
+  // only — a path belonging to an assistant we did NOT build this run (e.g. `.claude/*` while running
+  // `--assistant codex`) is not ours to touch, so init/update is ADDITIVE across assistants instead
+  // of wiping the previously-installed one.
+  const scoped = new Set<AdapterKey>();
+  for (const f of outputs) { const a = adapterOf(f.outputPath); if (a) scoped.add(a); }
+  const inScope = (p: string): boolean => { const a = adapterOf(p); return a !== null && scoped.has(a); };
+
+  // Orphan cleanup: managed files we wrote last time but not now — but ONLY within the assistants
+  // built this run. Other assistants' managed files are preserved (this is the cross-assistant fix).
   for (const oldPath of Object.keys(prev.managed)) {
     if (newManaged[oldPath]) continue;
+    if (!inScope(oldPath)) continue; // belongs to an assistant not built this run → keep it
     r.deletedOrphans.push(oldPath);
     if (!opts.dryRun) {
       const abs = path.join(cwd, oldPath);
@@ -84,9 +110,18 @@ export function applyOutputs(cwd: string, outputs: BuiltFile[], opts: ApplyOptio
   }
 
   if (!opts.dryRun) {
+    // Retain manifest entries for assistants NOT built this run so their files stay tracked (and get
+    // orphan-cleaned correctly on a later run that DOES target them); merge this run's entries on top.
+    const mergedManaged: Record<string, string> = {};
+    for (const [p, h] of Object.entries(prev.managed)) {
+      if (newManaged[p]) continue;   // rewritten this run → newManaged carries the fresh hash
+      if (inScope(p)) continue;      // orphan within a built assistant → dropped (deleted above)
+      mergedManaged[p] = h;          // other assistant (or unclassified) → keep tracking
+    }
+    Object.assign(mergedManaged, newManaged);
     const mPath = path.join(cwd, MANIFEST_REL);
     fs.mkdirSync(path.dirname(mPath), { recursive: true });
-    fs.writeFileSync(mPath, JSON.stringify({ version: opts.version, managed: newManaged }, null, 2));
+    fs.writeFileSync(mPath, JSON.stringify({ version: opts.version, managed: mergedManaged }, null, 2));
   }
   return r;
 }

package/src/orchestrator/project-initializer.ts

@@ -23,6 +23,37 @@ function sungenVersion(): string {
   catch { return '0.0.0'; }
 }
 
+/**
+ * Header written atop a NEW `.codex/config.toml`. Codex loads a PROJECT-scoped config.toml only
+ * for TRUSTED projects — without trust the MCP server silently never loads — so the note tells the
+ * user how to enable it. (Claude reads `.mcp.json` and Copilot `.vscode/mcp.json` with no such gate.)
+ */
+const CODEX_MCP_HEADER = [
+  '# Sungen — Codex MCP config (project-scoped, gives run-test the same live browser as Claude/Copilot).',
+  '# NOTE: Codex loads a project .codex/config.toml ONLY for TRUSTED projects. If the browser tools',
+  '# never appear, trust this project (open it with `codex` and approve, or set trust_level = "trusted"',
+  '# for this path in ~/.codex/config.toml). To add Figma too, see https://mcp.figma.com/mcp.',
+  '',
+  '',
+].join('\n');
+
+/**
+ * Append-if-absent merge for Codex's TOML MCP config. Mirrors `mergeMCPConfig`'s "user edits win"
+ * contract: preserves the existing file and any user-defined `[mcp_servers.*]`, and only appends the
+ * sungen server table when it is missing. Returns `null` when the target server is already present
+ * (nothing to write). TOML by hand (no toml dep) — the block is a fixed, simple table.
+ */
+export function mergeCodexMcpToml(existing: string, mobileOnly: boolean): string | null {
+  const serverKey = mobileOnly ? 'appium-mcp' : 'playwright';
+  // Already configured (by the user or a previous run) → preserve, do nothing.
+  if (new RegExp(String.raw`^\s*\[mcp_servers\.(?:"?${serverKey}"?)\]`, 'm').test(existing)) return null;
+  const block = mobileOnly
+    ? '[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n'
+    : '[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n';
+  if (existing.trim() === '') return CODEX_MCP_HEADER + block;
+  return existing + (existing.endsWith('\n') ? '\n' : '\n\n') + block;
+}
+
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
@@ -116,6 +147,12 @@ export class ProjectInitializer {
     // Create root .mcp.json for Claude Code
     this.createClaudeMCPConfig();
 
+    // Create .codex/config.toml for Codex CLI — only when Codex is a selected assistant
+    // (`sungen init --assistant codex`), since it is Codex-specific config.
+    if (this.agents.includes('codex')) {
+      this.createCodexMCPConfig();
+    }
+
     // Display summary
     this.displaySummary(normalizedProjectName);
   }
@@ -309,6 +346,28 @@ export class ProjectInitializer {
     );
   }
 
+  /**
+   * Create `.codex/config.toml` for Codex CLI — the Codex analog of `.mcp.json` (Claude) and
+   * `.vscode/mcp.json` (Copilot), so `sungen run-test` under Codex drives the same live Playwright
+   * MCP browser instead of Codex's own (headless) fallback. Mobile-only → appium-mcp. Append-only:
+   * preserves an existing file + any user server table (via `mergeCodexMcpToml`).
+   */
+  private createCodexMCPConfig(): void {
+    const filePath = path.join(this.cwd, '.codex', 'config.toml');
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const existed = fs.existsSync(filePath);
+    const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
+    const merged = mergeCodexMcpToml(existing, this.mobileOnly);
+    if (merged === null) {
+      this.skippedItems.push('.codex/config.toml');
+      return;
+    }
+    fs.writeFileSync(filePath, merged, 'utf-8');
+    this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+  }
+
   /**
    * Add MCP server entries without overwriting user config.
    * Preserves existing entries with the same key — user edits always win.

package/src/orchestrator/templates/ai-src/commands/add-flow.md

@@ -1,9 +1,9 @@
 ---
 name: add-flow
 description: "Add a new Sungen flow — scaffolds directories for E2E cross-screen testing, helps fill spec.md, and can capture visuals via the capture skills"
-argument-hint: [flow-name] [--path <start-url>]
+argument-hint: "[flow-name] [--path <start-url>] [--reach <steps>]"
 order: 10
-claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__figma__get_screenshot"
+claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__figma__get_screenshot, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__generate_locators, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_find_element, mcp__appium-mcp__appium_gesture, mcp__appium-mcp__appium_screenshot"
 copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
 codex-trigger: "Run when the user asks to add a NEW cross-screen end-to-end flow. Step 1 (flow variant). Do NOT use for a single screen, creating test cases, or running tests."
 ---
@@ -13,6 +13,13 @@ codex-trigger: "Run when the user asks to add a NEW cross-screen end-to-end flow
 {{/cap}}
 You are adding a new Sungen flow for E2E cross-screen test generation.
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → follow the **mobile path** in each step below.
+- If `platform: web` or field absent → follow the **web path** (all steps unchanged).
+
 ## Parameters
 
 {{#cap parallel-subagents}}
@@ -22,12 +29,13 @@ Parse from `$ARGUMENTS`:
 {{^cap parallel-subagents}}
 - **flow** — ${input:flow:flow name (e.g., award-submission, user-onboarding)}
 {{/cap}}
-- **--path \<url\>** — starting page URL path (default: `/login`)
+- **--path \<url\>** — starting page URL path for web (default: `/login`). Not used on mobile.
+- **--reach \<steps\>** — (mobile only) navigation recipe for the flow's first screen: a `>`-separated list of nav steps from app launch, e.g. `"tap [My Page] tab > tap [Settings] row"`. Scaffolded into the `Background:`. Ignored (with a warning) on web projects.
 - **--description \<text\>** — flow description (optional)
 
 {{#cap parallel-subagents}}
 If **flow** is missing, ask: "What is the flow name? (e.g., `award-submission`, `user-onboarding`)"
-If **path** is missing, ask: "What is the starting URL path? (e.g., `/login`)"
+If **path** is missing (web) or **--reach** is missing (mobile), ask for it accordingly — e.g. "What is the starting URL path? (e.g., `/login`)" for web, or "How do you reach the first screen from app launch? (e.g., `tap [My Page] tab > tap [Settings] row`)" for mobile.
 
 {{/cap}}
 ## Steps
@@ -37,6 +45,7 @@ If **path** is missing, ask: "What is the starting URL path? (e.g., `/login`)"
 {{^cap parallel-subagents}}
 Run with #tool:terminal:
 {{/cap}}
+**Web:**
 ```bash
 {{#cap parallel-subagents}}
 sungen add-flow --flow <name> --path <path>
@@ -46,6 +55,18 @@ sungen add-flow --flow ${input:flow} --path ${input:path}
 {{/cap}}
 ```
 
+**Mobile** (`platform: mobile` in `qa/capabilities.yaml`):
+```bash
+{{#cap parallel-subagents}}
+sungen add-flow --flow <name> [--reach "tap [My Page] tab > tap [Settings] row"]
+# Directories are always qa/flows/<name>/ — there is no qa/mobile/ tree.
+{{/cap}}
+{{^cap parallel-subagents}}
+sungen add-flow --flow ${input:flow} [--reach "tap [My Page] tab > tap [Settings] row"]
+# Directories are always qa/flows/${input:flow}/ — there is no qa/mobile/ tree.
+{{/cap}}
+```
+
 This creates:
 ```
 {{#cap parallel-subagents}}
@@ -76,6 +97,26 @@ Record the screen list — you will need it for:
 
 ### 2. Capture visual source
 
+**Mobile path** (`platform: mobile`):
+
+{{#cap parallel-subagents}}
+Use `AskUserQuestion`: *"Capture a live screen via Appium MCP now?"*
+{{/cap}}
+{{^cap parallel-subagents}}
+Ask: *"Capture a live screen via Appium MCP now?"*
+{{/cap}}
+- **Yes, capture now** (Recommended) — invoke the `sungen-capture-mobile` skill (Appium MCP) for the first screen of the flow. It replays the `--reach` nav recipe from the `Background:`, scans the locator tree, and saves a screenshot to `requirements/ui/`. Repeat for each screen in the flow as needed.
+{{#cap parallel-subagents}}
+- **Skip** — user will capture later via `/sungen:run-test` or manually.
+{{/cap}}
+{{^cap parallel-subagents}}
+- **Skip** — user will capture later via `/sungen-run-test` or manually.
+{{/cap}}
+
+Do NOT invoke `sungen-capture` (web/Figma) for a mobile project — use `sungen-capture-mobile` only.
+
+**Web path:**
+
 {{#cap parallel-subagents}}
 Use `AskUserQuestion`: *"Pick a visual source for this flow's screens:"*
 {{/cap}}
@@ -145,5 +186,11 @@ If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke i
 - YAML keys must be **quoted** due to colon: `"login:submit":`
 - Test data namespaced by phase: `login.email`, `submission.nominee`
 - `@flow` tag required at feature level
-- `Background:` should only contain the starting page navigation
+- `Background:` should only contain the starting navigation — the URL path (web) or the `--reach` nav recipe (mobile)
 - Each scenario = one phase of the journey
+{{#cap parallel-subagents}}
+- Mobile flows are tagged `@platform:mobile` and run via `/sungen:run-test <flow>` (WebdriverIO, not Playwright)
+{{/cap}}
+{{^cap parallel-subagents}}
+- Mobile flows are tagged `@platform:mobile` and run via `/sungen-run-test <flow>` (WebdriverIO, not Playwright)
+{{/cap}}

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -20,6 +20,13 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 **Input**: Screen or flow name (e.g., `/sungen-create-test admin-users`).
 {{/cap}}
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → the visual-capture step (Step 3, "Auto-detect visual source") uses the **`sungen-capture-mobile`** skill (Appium MCP live capture) **instead of** the web `sungen-capture` (figma/live). Scenarios use mobile gesture vocabulary from `sungen-mobile-gestures` (tap, swipe, long-press — not click/hover) and `accessibility-id`-first selectors; mobile-specific steps (permission dialogs, clipboard, geolocation) are valid Gherkin, not errors. The `Background:` is a **navigation recipe** (see `add-screen --reach`), not a URL path. Everything else — viewpoints, `sungen-tc-generation`, the harness/audit loop — is platform-agnostic and unchanged.
+- If `platform: web` or field absent → follow the **web path** (all steps below, unchanged) — Figma/live capture via `sungen-capture` as documented in Step 3.
+
 ## Role
 
 {{#cap parallel-subagents}}

package/src/orchestrator/templates/ai-src/commands/feedback.md

@@ -10,10 +10,10 @@ codex-trigger: "Run when the user wants to send FEEDBACK about sungen itself."
 ## Role
 {{#cap parallel-subagents}}
 
-You capture QA feedback and store it **locally** (no server) via `sungen feedback record`. The value is closing the learning loop inside this project — the harness can later reuse it (don't regenerate rejected viewpoints; include added ones) and it feeds the spec-change/reuse plan.
+You capture QA feedback and store it **locally** (no server) via `sungen qa-feedback record`. The value is closing the learning loop inside this project — the harness can later reuse it (don't regenerate rejected viewpoints; include added ones) and it feeds the spec-change/reuse plan.
 {{/cap}}
 {{^cap parallel-subagents}}
-Capture QA feedback and store it **locally** (no server) via `sungen feedback record`. Closes the learning loop inside the project; the harness can reuse it later.
+Capture QA feedback and store it **locally** (no server) via `sungen qa-feedback record`. Closes the learning loop inside the project; the harness can reuse it later.
 {{/cap}}
 
 ## Steps
@@ -39,12 +39,12 @@ Capture QA feedback and store it **locally** (no server) via `sungen feedback re
 {{/cap}}
    ```bash
 {{#cap parallel-subagents}}
-   sungen feedback record --type test-design --screen <name> \
+   sungen qa-feedback record --type test-design --screen <name> \
      --target "VP-DATA-CONSISTENCY" --decision add \
      --message "<message>" --reason "<why>"
 {{/cap}}
 {{^cap parallel-subagents}}
-   sungen feedback record --type <type> --screen <name> --target "<ref>" --decision <d> --message "<msg>" --reason "<why>"
+   sungen qa-feedback record --type <type> --screen <name> --target "<ref>" --decision <d> --message "<msg>" --reason "<why>"
 {{/cap}}
    ```
 {{#cap parallel-subagents}}
@@ -60,8 +60,8 @@ Capture QA feedback and store it **locally** (no server) via `sungen feedback re
 {{#cap parallel-subagents}}
 - **Never send anywhere** — this only writes a local file.
 - Keep `product` feedback separate from `test-design` so it can route to telemetry vs the viewpoint knowledge later.
-- View history: `sungen feedback list [--screen <name>] [--type <t>]`.
+- View history: `sungen qa-feedback list [--screen <name>] [--type <t>]`.
 {{/cap}}
 {{^cap parallel-subagents}}
-- Never send anywhere — local file only. Keep `product` vs `test-design` distinct. View: `sungen feedback list`.
+- Never send anywhere — local file only. Keep `product` vs `test-design` distinct. View: `sungen qa-feedback list`.
 {{/cap}}

package/src/orchestrator/templates/ai-src/commands/locale.md

@@ -1,8 +1,8 @@
 ---
-description: "Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright, generate test-data overlay so `sungen:run-test --env <locale>` works."
+description: "Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright (web) or device locale (mobile), generate test-data overlay so `sungen:run-test --env <locale>` works."
 argument-hint: "<name> <locale> [--base-locale <code>] [--offline]"
 order: 45
-claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state"
+claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state, mcp__appium-mcp__select_device, mcp__appium-mcp__appium_session_management, mcp__appium-mcp__appium_get_page_source, mcp__appium-mcp__appium_screenshot, mcp__appium-mcp__generate_locators"
 copilot-tools: "[read, execute, edit, vscode/askQuestions, playwright/*]"
 codex-trigger: "Run when the user asks to bootstrap i18n/localization for a screen. Runs before run-test --env <locale>."
 ---
@@ -33,6 +33,27 @@ Reject if name == locale (common typo).
 Reject if name == locale.
 {{/cap}}
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → switch to the **mobile path** (below).
+- If `platform: web` or field absent → follow the **web path** (existing behavior below, unchanged).
+
+### Mobile path
+
+When `platform: mobile`, mobile follows the **device locale** — there is no URL prefix, query param, or browser-storage mechanism to detect. Key differences from web (full detail in the `sungen-locale` skill):
+
+- **Live capture**: use **Appium MCP** (`select_device` → `appium_session_management(create)` with the device at base locale → `appium_get_page_source` / `appium_screenshot`) — not Playwright browser tools.
+- **Locale-switch mechanism**: `appium:language` / `appium:locale` capabilities + `noReset:false`, resolved automatically at runtime by `wdio.conf.ts`'s `resolveLocaleCaps()`. No fixture files needed.
+- **Phases skipped**: 3.5/3.6 (browser storage diff/verify) and 6d/6f (Pages URL update, locale-config.json) are web-only — skip them. Phase 6 (mobile) writes only selectors `{{var}}`, the base `test-data/<feature>.yaml`, and the overlay `test-data/<feature>.<locale>.yaml`.
+- **Compile**: `sungen generate --screen <name>` (the Appium adapter auto-selects for a mobile project).
+- **Hand-off**: after a locale run, print `SUNGEN_ENV=<locale> npm run test:mobile` (or the `--flow` equivalent). If the device's locale code differs from the overlay's env name, set `SUNGEN_LOCALE=<code>` — `resolveLocaleCaps()` reads it as an override.
+- **Reset after a locale run**: run once with `SUNGEN_LOCALE=en npm run test:mobile` to bring the device/app back to the base language before the next non-locale run.
+- **iOS data-wipe**: `wdio.conf.ts`'s `beforeSession` hook already wipes the app's data container on iOS before any locale run (XCUITest's `noReset:false` alone doesn't clear a persisted in-app language). If an older mobile project's `wdio.conf.ts` predates this hook and iOS keeps the previous language, re-run `sungen init --mobile` to refresh it.
+
+Stop here for mobile — do not continue to the web path below. Everything else (the 7-phase strategy, selector/test-data output shape, `{{var}}` overlay pattern) matches web; see the `sungen-locale` skill for the full mobile phase table.
+
 ## Auto-detect context
 
 Same as `/sungen:run-test`:
@@ -114,10 +135,11 @@ Offer the user:
 {{#cap parallel-subagents}}
 - Do NOT run tests yourself. `/sungen:run-test` is the executor. This command only PREPS files.
 - Do NOT modify `.feature` files. Localization happens entirely through `selectors/*.yaml` + `test-data/*.yaml`.
-- Auth blocker on SAA staging? Use `--offline`. See [[saa-auth-blocker]] memory.
+- Auth blocker on SAA staging (web)? Use `--offline`. See [[saa-auth-blocker]] memory.
+- Mobile device/emulator unreachable? Use `--offline` — same fallback as web.
 {{/cap}}
 {{^cap parallel-subagents}}
 - Do NOT run tests yourself. `/sungen:run-test` is the executor; this command only PREPS files.
 - Do NOT modify `.feature` files. Localization lives in `selectors/*.yaml` + `test-data/*.yaml` only.
-- Auth blocked? Use `--offline`.
+- Auth blocked (web)? Use `--offline`. Mobile device unreachable? Same fallback.
 {{/cap}}

package/src/orchestrator/templates/ai-src/skills/sungen-delivery/SKILL.md

@@ -78,19 +78,20 @@ The CLI reads the **per-target result file first** (co-located with `.spec.ts`),
 
 ---
 
-## XLSX sheets — Auto / Manual split
+## XLSX sheets — Overview + Auto / Manual split
 
-The `.xlsx` is split into two sheets so QA manages the sets separately:
+The `.xlsx` leads with an **`Overview`** roll-up sheet, then splits the test cases into detail sheets so QA manages the sets separately:
+- **`Overview`** — first sheet. Same masthead (Sun\* logo, `<SCREEN> TESTCASE` title, No/Version/Issue-Date, ISO band) as the others, then a summary table: one row per following sheet with `# · Sheet name · Passed · Failed · Pending · N/A · Remain · Total`, plus a grand-total row. `Remain = Total − Passed − N/A` (i.e. Failed + Pending), reconciling with each detail sheet's own summary band.
 - **`Auto`** — automatable test cases (`Auto` + `Not compiled`).
 - **`Manual`** — `@manual` test cases (always present, header-only when there are none).
 
-Multi-locale (no `SUNGEN_ENV`): one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual.
+Multi-locale (no `SUNGEN_ENV`): `Overview` + one **`<LOCALE> Auto`** sheet per locale + a single shared **`Manual`** sheet (manual TCs are locale-invariant). The **CSV stays one file with every row** — the `Testcase type` column distinguishes Auto vs Manual. The Overview lists every detail sheet, so each locale's counts appear on its own row.
 
 ---
 
 ## API delivery — extra worksheet
 
-For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a third worksheet **`API detail`** (appended after Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
+For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a final worksheet **`API detail`** (appended after Overview/Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
 
 ### Required sources (API detail sheet only)