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

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-flow.md

@@ -1,30 +1,48 @@
 ---
 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>]
-allowed-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
+argument-hint: "[flow-name] [--path <start-url>] [--reach <steps>]"
+allowed-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
 ---
 
 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
 
 Parse from `$ARGUMENTS`:
 - **flow** — flow name (e.g., `award-submission`, `user-onboarding`)
-- **--path \<url\>** — starting page URL path (default: `/login`)
+- **--path \<url\>** — starting page URL path for web (default: `/login`); or app entry for mobile (`<appPackage>`)
+- **--reach \<steps\>** — (mobile only) navigation recipe for the flow's first screen: `>`-separated nav steps from app launch. Ignored (with warning) on web projects.
 - **--description \<text\>** — flow description (optional)
 
 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** → ask: "What is the starting URL path? (e.g., `/login`)"
+- **Mobile** → read `wdio.conf.ts` and propose the app entry (package alone). Use `AskUserQuestion` to confirm before scaffolding.
 
 ## Steps
 
 ### 1. Scaffold the flow
 
+**Web:**
 ```bash
 sungen add-flow --flow <name> --path <path>
 ```
 
+**Mobile (when `platform: mobile` in `qa/capabilities.yaml`):**
+```bash
+sungen add-flow --flow <name> [--reach "tap [My Page] tab > tap [Settings] row"]
+# --reach is the navigation recipe for the flow's first screen → scaffolded into the Background.
+# Directories are always qa/flows/<name>/ (never qa/mobile/).
+```
+
 This creates:
 ```
 qa/flows/<name>/
@@ -47,6 +65,16 @@ Record the screen list — you will need it for:
 
 ### 2. Capture visual source
 
+**Mobile path (when `platform: mobile` in `qa/capabilities.yaml`):**
+
+Use `AskUserQuestion`: *"Capture a live screen via Appium MCP now?"*
+- **Yes, capture now (Recommended)** — invoke the `sungen-capture-mobile` skill (Appium MCP) for the first screen of the flow. It replays the Background nav recipe, scans the locator tree, and saves a screenshot to `requirements/ui/`. Repeat for each screen in the flow as needed.
+- **Skip** — user will capture later via `/sungen:run-test` or manually.
+
+Do NOT invoke `sungen-capture` (web/Figma) for a mobile project. Use `sungen-capture-mobile` only.
+
+**Web path:**
+
 Use `AskUserQuestion`: *"Pick a visual source for this flow's screens:"*
 - **Figma designs** (Recommended for pre-launch) — invoke `sungen-capture` skill (mode figma-mcp) for each screen
 - **Live page scan** (dev/staging is up) — invoke `sungen-capture` skill (mode live) for each screen URL

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -1,25 +1,38 @@
 ---
 name: add-screen
 description: 'Add a new Sungen screen or a sub-feature to an existing one — scaffolds directories, helps fill spec.md, and can capture visuals from Figma (pre-launch) or live page via the capture skills'
-argument-hint: "[screen-name] [url-path] [--feature <name>] [--figma <url>]"
-allowed-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
+argument-hint: "[screen-name] [url-path] [--feature <name>] [--figma <url>] [--reach <steps>] [--platform android|ios]"
+allowed-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
 ---
 
 You are adding a new Sungen screen for test generation, or extending an existing screen with an additional `.feature` file (sub-feature).
 
+## 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
 
 Parse from `$ARGUMENTS`:
 - **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
-- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`) - optional when `--figma` is provided or when adding a sub-feature to an existing screen
+- **path** — URL path for web (e.g., `/login`), or app entry for mobile (`<appPackage>` / `<iosBundleId>` / dual-id `"<pkg> | <bundleId>"`). Optional when `--figma` is provided or when adding a sub-feature.
+- **`--reach <steps>`** — (mobile only) navigation recipe: `>`-separated nav steps from app launch to this screen, e.g. `"tap [My Page] tab > tap [Settings] row"`. Scaffolded into the Background. Ignored (with a warning) on web projects.
+- **`--platform android|ios`** — (mobile only, optional) emit `@platform:android` or `@platform:ios` on the stub for OS-specific screens. Omit for cross-platform mobile. Does NOT affect directory routing.
 - **`--feature <name>`** — sub-feature name to add to an existing screen (e.g., `modal`, `filter`, `create-flow`). Creates `<screen>-<feature>.feature` + matching `selectors/<screen>-<feature>.yaml` + `test-data/<screen>-<feature>.yaml` without touching the screen's other files. Use this when one screen has multiple `.feature` files (e.g. main listing + modal + filter panel).
-- **`--figma <url>`** — Figma share URL (optional)
+- **`--figma <url>`** — Figma share URL (optional, web only)
 - **`--refresh`** — bypass Figma cache and re-fetch (optional, use with `--figma`)
 - **`--scale <n>`** — PNG export scale factor, default 2 (optional)
 - **`--hi-res`** — export at 4× scale, shorthand for `--scale 4` (optional)
 
 If **screen** is missing, ask: "What is the screen name? (e.g., `login`, `dashboard`)"
-If **path** is missing and **`--feature`** is NOT used and `--figma` was NOT provided, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+If **path** is missing and **`--feature`** is NOT used and `--figma` was NOT provided:
+- **Web** → ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+- **Mobile** → read `wdio.conf.ts` at the repo root and derive a proposal from `APP_PACKAGE` (Android) and `IOS_BUNDLE_ID` (iOS). Propose the package alone for mobile-android/mobile-ios, or the dual-id `"<pkg> | <bundleId>"` for cross-platform. Use `AskUserQuestion` to confirm before scaffolding.
+
+After confirming the app entry for a mobile project, ask: "After the app launches, what taps reach this screen? e.g. `tap [My Page] tab > tap [Account Settings] row` — leave blank if this IS the launcher/home screen." Pass the answer as `--reach "..."`.
 
 **Mode detection** — before invoking the CLI, check whether `qa/screens/<screen>/` already exists:
 - Screen does NOT exist → fresh screen creation (need `--path` unless `--figma` provided)
@@ -30,11 +43,24 @@ If **path** is missing and **`--feature`** is NOT used and `--figma` was NOT pro
 
 ### 1. Scaffold the screen (or sub-feature)
 
-**Standard path (no `--figma`, no `--feature`):**
+**Web — standard path (no `--figma`, no `--feature`):**
 ```bash
 sungen add --screen <screen> --path <path>
 ```
 
+**Mobile path (when `platform: mobile` in `qa/capabilities.yaml`):**
+```bash
+sungen add --screen <screen> \
+  --path "<appPackage>[ | <iosBundleId>]" \
+  [--reach "tap [My Page] tab > tap [Account Settings] row"] \
+  [--platform android|ios]
+# --path is the app entry (package alone; launch activity auto-detected).
+# --reach is the navigation recipe → scaffolded into the Background.
+# Omit --reach when the screen IS the launcher/home screen.
+# --platform android|ios is optional: emits @platform:android/ios for OS-specific screens only.
+# Directories are always qa/screens/<screen>/ (never qa/mobile/).
+```
+
 **Sub-feature mode (`--feature <name>` provided):**
 ```bash
 sungen add --screen <screen> --feature <name> [--path <path>]
@@ -43,7 +69,7 @@ sungen add --screen <screen> --feature <name> [--path <path>]
 # --path is optional — defaults to /<screen> when omitted. Pass --path only if the sub-feature lives at a different URL.
 ```
 
-**Figma branch (when `--figma <url>` is in `$ARGUMENTS`):**
+**Figma branch (when `--figma <url>` is in `$ARGUMENTS`, web only):**
 
 Invoke the `sungen-capture` skill (mode figma-pat) by running:
 ```bash
@@ -86,6 +112,16 @@ After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is determin
 
 ### 2. Capture visual source
 
+**Mobile path (when `platform: mobile` in `qa/capabilities.yaml`):**
+
+Use `AskUserQuestion`: *"Capture a live screen via Appium MCP now?"*
+- **Yes, capture now (Recommended)** — invoke the `sungen-capture-mobile` skill (Appium MCP). It replays the Background nav recipe to reach this screen, scans the locator tree, and saves a screenshot to `requirements/ui/`.
+- **Skip** — user will capture later via `/sungen:run-test` or manually.
+
+Do NOT invoke `sungen-capture` (web/Figma) for a mobile project. Use `sungen-capture-mobile` only.
+
+**Web path:**
+
 **If Figma branch (Step 1) already downloaded PNGs** → visuals already exist. Use `AskUserQuestion` to offer:
 - **Continue** — Figma visuals are enough (Recommended)
 - **Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture` skill (mode live))
@@ -120,12 +156,17 @@ If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke i
 
 ```
 sungen add --screen <name>
-  [-p, --path <path>]            URL route (e.g., /awards). Required for capture; defaults to /<screen> when omitted.
+  [-p, --path <path>]            Web: URL route (e.g., /awards). Mobile: app entry (<appPackage> or dual-id).
+                                 Required for capture; defaults to /<screen> when omitted on web.
   [-f, --feature <name>]         Add a sub-feature .feature file to an existing screen.
                                  Output filename = <screen>-<feature>.{feature,yaml,yaml}.
-  [-c, --capture]                Auto-capture a live screenshot to requirements/ui/ (needs --path).
+  [-c, --capture]                Auto-capture a live screenshot to requirements/ui/ (web only, needs --path).
   [-d, --description <text>]     Screen description (used in spec.md stub).
-  [--figma <url>]                Figma share URL — generates spec_figma.md + ui/*.png.
+  [--reach <steps>]              Mobile navigation recipe: ">"-separated steps from app launch to this screen.
+                                 Scaffolded into the Background. Ignored (with warning) on web projects.
+  [--platform android|ios]       Mobile only: emit @platform:android/ios tag for OS-specific screens.
+                                 Does NOT affect directory routing.
+  [--figma <url>]                Figma share URL — generates spec_figma.md + ui/*.png (web only).
   [--refresh]                    Bypass Figma cache (use with --figma).
   [--scale <n>]                  PNG export scale (default 2).
   [--hi-res]                     Shorthand for --scale 4.

package/src/orchestrator/templates/ai-instructions/claude-cmd-create-test.md

@@ -13,6 +13,13 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 
 ---
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → this is a **mobile project**. When generating scenarios, use mobile gesture vocabulary and selector patterns from the `sungen-mobile-gestures` and `sungen-capture-mobile` skills (tap, swipe, long-press, etc. instead of click/hover; `[accessibility-id]` selectors instead of CSS/role). Mobile-specific steps (permission dialogs, clipboard, geolocation) are valid — do not flag them as invalid Gherkin. The `@platform` tag is not required on individual scenarios (one project = one platform). Visual capture via the `sungen-capture-mobile` skill (Appium MCP live capture) is preferred over web-based capture.
+- If `platform: web` or field absent → **web path**, proceed as normal below.
+
 ## Role
 
 You are a **Senior QA Engineer** specialized in test case design. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Tier 1 (critical+high) first** — expand coverage later. Focus on **Gherkin scenarios and test data only** — selectors are handled during `/sungen:run-test`.
@@ -112,7 +119,10 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    - `sungen manifest --screen <name>` — fingerprints for next-run change detection. On a **re-run**, start the whole command by `sungen manifest --screen <name> --diff` and only regenerate scenarios whose spec section changed (keep/regenerate/retire).
    - **Ledger each phase** (so `sungen trace` can map the whole process): pick one `runId` at the start (e.g. a timestamp) and append `sungen ledger record --screen <name> --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>` (add `--tokens-in/--tokens-out` if known). The `--run` id groups this invocation so `trace`/`ledger report` show THIS run, not a mix of past runs. Do this for **every** phase, not just repair.
 
-6. **Converge — show the trace.** Run `sungen trace --screen <name>` and present to the user: the process map (phases + repair rounds), bottlenecks, and the **HUMAN-LOOP FOCUS** (@manual scenarios they must verify) + audit score & gate status & residual/cross-screen gaps. Then use `AskUserQuestion` to offer next steps based on which tier was just generated:
+6. **Converge — show the journey board first, then the trace.**
+   - **Board (the human-facing review surface — do this first).** Run `sungen journey --screen <name>` and present the board to the user verbatim-in-spirit: **📍 you-are-here** (current phase), the **obligation checklist** ("what must still be true" — each ✅ satisfied / ⏳ needs-work / 🚫 waived), and **especially the 🔎 Review queue** — every item carries an IDE-jumpable **anchor** 〔`VP-id · file:line`〕. This is what answers *"review what, review where, what's doubtful"*: read each queued item aloud with its anchor so the user knows exactly which scenario/line to look at. End with the board's **→ Next**.
+   - **Trace (the process detail).** Then run `sungen trace --screen <name>` for the process map (phases + repair rounds), bottlenecks, and audit score & gate status & residual/cross-screen gaps.
+   - Then use `AskUserQuestion` to offer next steps based on which tier was just generated:
 
    > The harness gate + reviewer already ran above — you do **not** need `/sungen:review` as a next step (it's the independent checkpoint for hand/prompt-authored or pre-delivery cases). Recommend `run-test` or expanding coverage.
 

package/src/orchestrator/templates/ai-instructions/claude-cmd-delivery.md

@@ -19,6 +19,10 @@ If `--env` is passed but no value follows, ask the user which locale to use.
 
 ## Steps
 
+### 0. Sign-off gate (per screen — the deliver boundary)
+
+Delivery is the **last phase**, and its boundary requires a human sign-off (S5). For each screen/flow being delivered, run `sungen gate --screen <name> --phase deliver` (exit 2 = HALT). On **HALT** it means the screen is **not signed off yet** (or an obligation is still open): present `sungen journey --screen <name>` — the **🔎 Review queue** with its anchors 〔`VP-id · file:line`〕 — so the user can review *what / where*, then either resolve the items or, when satisfied, sign off with `sungen journey --screen <name> --signoff --by "<name>"`. Do **not** export a screen past a deliver HALT without a sign-off. (Skip this gate only if the user explicitly asks for a draft/preview export.)
+
 ### 1. Invoke the CLI
 
 Run via Bash (single command, no extra parsing). Prefer the local `./bin/sungen.js` when it exists — the sungen monorepo ships local-only features the global npm package doesn't have yet (multi-sheet locale aggregation, `.<env>` filename suffix, locale-aware step rendering). Fall back to `npx sungen` in downstream projects.
@@ -41,6 +45,8 @@ The CLI handles:
 - Generating CSV/XLSX at `qa/deliverables/<name>-testcases[.<env>].csv` / `.xlsx`
 - Printing summary table
 
+**Mobile projects (`platform: mobile`):** a plain `delivery <name>` (no `SUNGEN_ENV`) auto-emits one deliverable PER OS — `<name>-testcases.android.{csv,xlsx}` + `<name>-testcases.ios.{csv,xlsx}` (from each `<name>-test-result.<os>.json`) — and writes **NO** base `<name>-testcases.{csv,xlsx}` (a stale base pair is removed). The **Test Environment** column shows only that OS's app id (Android package vs iOS bundle id), never the combined dual-id `Path:`. `SUNGEN_ENV=android|ios` still targets a single OS.
+
 ### 2. Handle pre-flight failures (if CLI exits non-zero)
 
 If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per screen.

package/src/orchestrator/templates/ai-instructions/claude-cmd-locale.md

@@ -1,7 +1,7 @@
 ---
-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]"
-allowed-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
+allowed-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
 ---
 
 ## Role
@@ -14,10 +14,31 @@ Parse from `$ARGUMENTS`:
 - **name** — screen or flow name (e.g. `home`, `awards`, `kudo-to-display-on-kudos`). If missing → AskUserQuestion.
 - **locale** — target locale code (e.g. `en`, `ja`, `en-US`, `staging-ja`). If missing → AskUserQuestion. This becomes the suffix in `test-data/<feature>.<locale>.yaml` and `SUNGEN_ENV=<locale>` at run time.
 - **`--base-locale <code>`** — optional. The locale of existing `test-data/<feature>.yaml`. Default `vi`. Used only for reporting/UX — files never get renamed.
-- **`--offline`** — force OFFLINE mode (skip Playwright capture). Useful when you know the live page can't be reached or when prepping a test-only template.
+- **`--offline`** — force OFFLINE mode (skip live capture). Useful when you know the live page/device can't be reached or when prepping a test-only template.
 
 Reject if name == locale (common typo).
 
+## 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, unchanged).
+
+### Mobile path
+
+When `platform: mobile`:
+
+- **Live capture**: use **Appium MCP** (`select_device` → `appium_session_management(create)` with device at base locale → `appium_get_page_source` / `appium_screenshot`) — NOT Playwright browser tools.
+- **Locale-switch mechanism**: **device locale** — `appium:language` / `appium:locale` caps + `noReset:false` (set by wdio `resolveLocaleCaps` at runtime). There is no URL prefix, query param, or browser-storage injection on mobile.
+- **Phases skipped for mobile**: 3.5 (browser storage diff), 3.6 (storage verification), 6d (Pages URL update), 6f (locale-config.json / locale-fixture). These are web-only; wdio `resolveLocaleCaps` handles runtime locale on mobile automatically — no fixture files needed.
+- **OFFLINE mode** (when device unreachable or `--offline` flag): scaffold overlay template + let user fill manually. Same as web offline mode.
+- **Hand-off**: print `SUNGEN_ENV=<locale> npm run test:mobile`. Include note: "If the device locale code differs from the overlay env name, set `SUNGEN_LOCALE=<code>` — wdio `resolveLocaleCaps` reads it as an override."
+- **Phase 6 (mobile) writes only**: 6a selectors `{{var}}`, 6b base `test-data/<feature>.yaml`, 6c overlay `test-data/<feature>.<locale>.yaml`. No 6d or 6f.
+- **Compile**: `sungen generate --screen <name>` (appium adapter auto-selected in a mobile project).
+
+Stop here for mobile — do not continue to the web path.
+
 ## Auto-detect context
 
 Same as `/sungen:run-test`:
@@ -25,7 +46,7 @@ Same as `/sungen:run-test`:
 - Else `qa/screens/<name>/` exists → screen mode (base path: `qa/screens/<name>/`)
 - Neither exists → tell user and stop
 
-## Steps
+## Steps (web)
 
 The `sungen-locale` skill defines 7 phases. Execute them in order:
 

package/src/orchestrator/templates/ai-instructions/claude-cmd-review.md

@@ -5,6 +5,13 @@ argument-hint: [screen-name]
 allowed-tools: Read, Grep, Glob, Bash, Edit, Write, AskUserQuestion
 ---
 
+## Platform detection (do this FIRST)
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → this is a **mobile project**. When reviewing scenarios, apply the **mobile viewpoint**: mobile-specific steps (tap, swipe, long-press, permission dialogs, clipboard, geolocation) are valid — do not flag them as incorrect or web-incompatible. Judge selector references against mobile accessibility patterns (`[accessibility-id]`, content-desc, etc.), not CSS/role. Load `sungen-mobile-gestures` for the canonical mobile step vocabulary. All other harness steps (audit, script-check, scorecard) run unchanged.
+- If `platform: web` or field absent → **web path**, proceed as normal below.
+
 ## Role
 
 You are an **independent QA Reviewer** running in a **fresh context** — you did not author these tests. You do **not** invent a parallel score; you run the **harness** and present its signals as a human scorecard. Skills: `sungen-tc-review` (presentation rubric), `sungen-viewpoint`, `sungen-gherkin-syntax`.

package/src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md

@@ -1,13 +1,47 @@
 ---
 name: run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: "[screen-name] [--env <locale>]"
-allowed-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_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state
+argument-hint: "[screen-name] [--env <locale>] [--ios|--android|--both]"
+allowed-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_run_code, 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__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, mcp__appium-mcp__appium_set_value
 ---
 
 ## Role
 
-You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
+You are a **Senior Developer**.
+- **Web screens/flows** → use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills (Playwright MCP + `npx playwright test`).
+- **Mobile screens** (`platform: mobile` in `qa/capabilities.yaml`) → use `sungen-selector-fix-mobile`, `sungen-capture-mobile`, `sungen-mobile-gestures`, `sungen-selector-keys` (Appium MCP + `npm run test:mobile`).
+
+## 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** (all steps below, unchanged).
+
+### Mobile path
+
+When `platform: mobile`:
+
+- **Selectors**: use **Appium MCP** (`select_device` → `appium_session_management(create)` → `generate_locators`), per the `sungen-selector-fix-mobile` skill. Also load `sungen-capture-mobile` and `sungen-mobile-gestures`.
+- **Auth**: web Phase 0.5 (`storageState`) does not exist on mobile. When the feature has `@auth:<role>`, check `specs/.auth-mobile/<role>.json`; if missing, run the guided auth-contract builder (Phase 0.5 in `sungen-selector-fix-mobile`) BEFORE Phase 1.
+- **Compile**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --screen <name> --framework appium || npx sungen generate --screen <name> --framework appium`
+- **OS selection**: parse the target OS from `$ARGUMENTS` — `--ios`, `--android`, or `--both`
+  (alias: `--platform <android|ios|both>`) → set `MOBILE_PLATFORM=<value>`. Default to `android` when no flag is given.
+- **Run**: WebdriverIO, not Playwright. Scope one spec with `SUNGEN_SPECS`; prefix the parsed `MOBILE_PLATFORM`:
+  ```bash
+  # Android (default — no flag, or --android)
+  SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' npm run test:mobile
+  # iOS only (--ios)
+  SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' MOBILE_PLATFORM=ios npm run test:mobile
+  # both OSes (--both)
+  SUNGEN_SPECS='./specs/generated/<name>/<name>.spec.ts' MOBILE_PLATFORM=both npm run test:mobile
+  ```
+  `wdio.conf.ts` auto-selects `@wdio/globals` specs and auto-starts Appium. iOS needs a booted Simulator and `IOS_BUNDLE_ID`/`IOS_UDID` env vars.
+- **Results**: the wdio reporter writes `<name>-test-result.<android|ios>[.<env>].json` — one file per capability, so a both-OS run keeps both outcomes.
+- **Skip** the "Playwright command guidelines" section below — it applies to web only.
+- The phased waves (smoke → priority → full → regression), attempt budgets, and next-steps mirror the web flow — follow the `sungen-selector-fix-mobile` skill for the mobile equivalents.
+
+Stop here for mobile — do not continue to the web path.
 
 > ⛔ **Source of truth — the live page is NOT the oracle; `.feature`/`test-data`/`spec.md` are.** Auto-fix is for **selector-resolution** failures (wrong locator → fix `selectors.yaml`). An **assertion-value** failure where the app contradicts the spec is a **CANDIDATE BUG → report it, let it FAIL** — never loosen the rule, weaken the assertion, edit the expected value/`.feature`, or hand-edit the generated `.spec.ts` to make it pass. See `sungen-error-mapping` § "Source of truth". (A `password > 8` test that fails on 6 chars is a bug to report, not a `>= 6` edit.)
 
@@ -103,7 +137,7 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
 9. **Integrity check & trace (always run after the final run).**
    - `sungen script-check --screen <name>` — verify the generated spec is a **1:1** of the Gherkin (every non-@manual scenario ↔ one `test()`, no drift). If it reports **DRIFT** (spec hand-edited or stale), re-run `sungen generate --screen <name>` so the spec matches the feature, then re-run — **never hand-edit the generated spec** (auto-fix must edit `selectors.yaml`, not the `.spec.ts`).
-   - `sungen ledger record --screen <name> --step run --ms <elapsed>` (record this run), then `sungen trace --screen <name>` — show the process map + bottlenecks + **HUMAN-LOOP FOCUS** (the @manual scenarios the QA must verify) to the user.
+   - `sungen ledger record --screen <name> --step run --ms <elapsed>` (record this run), then **present the journey board** — `sungen journey --screen <name>` — as the human-facing close-out: **📍 you-are-here**, the **obligation checklist** (now including automation), and **especially the 🔎 Review queue** with its per-item anchors 〔`VP-id · file:line`〕 (*review what / where*) plus any **candidate bugs left FAILING by the source-of-truth rule** (#387). Then `sungen trace --screen <name>` for the process map + bottlenecks. The board's **→ Next** tells the user whether they can sign off & deliver.
    - **Phase gate (boundary — do NOT skip).** `sungen gate --screen <name> --phase run` (exit 2 = HALT): the run-boundary obligations (incl. automation) must be **satisfied or explicitly waived**. On **HALT**, classify per `sungen-error-mapping` § Source of truth (#387): a **selector-resolution** failure → fix `selectors.yaml` + re-run; an **assertion-vs-spec** failure → **report it as a candidate bug / leave it FAIL** (never weaken the assertion or edit the expected to pass); a genuinely-accepted gap → `sungen journey --screen <name> --waive <OB> --reason "..."`. Do **not** declare the run "done" past a HALT without a fix, a reported bug, or a reasoned waiver.
 10. **Capability-pending offer (consent-gated).** If `sungen audit --screen <name>` reports `AUTOMATION-READY-PENDING` (or the run shows `@requires:<cap>` tests skipped "requires …"), these are **automation-ready** scenarios waiting on an opt-in driver. Use `AskUserQuestion` to offer: *"N scenario(s) are automation-ready — enable `<cap>` to run them? (`sungen capability add <cap>`)"*. **Only on the user's yes** run `sungen capability add <cap>` then re-run those specs; on no, leave them skipped (they are NOT failures and NOT manual). **Never auto-install.**
 

package/src/orchestrator/templates/ai-instructions/claude-skill-delivery.md

@@ -53,6 +53,8 @@ Source modules: `src/exporters/*.ts`
 
 The CLI reads the **per-target result file first** (co-located with `.spec.ts`), then falls back to the global `test-results/results.json`. Per-target is preferred because the global file gets OVERWRITTEN each time Playwright runs, losing results from earlier targets.
 
+**Mobile (per-OS deliverables):** an Appium run writes one result file per capability — `<name>-test-result.<android|ios>[.<env>].json`. For a mobile project (`platform: mobile`), a plain `sungen delivery <name>` (no `SUNGEN_ENV`) **auto-emits one deliverable PER OS** — `<name>-testcases.android.{csv,xlsx}` + `<name>-testcases.ios.{csv,xlsx}` — and does **NOT** write a base `<name>-testcases.{csv,xlsx}` (android/ios are separate platform runs, not locales of one run, so a base aggregate would be empty/misleading; a stale base pair is removed). The Appium spec (mocha `describe()/it()`) is recognized as compiled (issue #391), so each per-OS CSV shows real Passed/Failed with `@manual` rows as N/A. `SUNGEN_ENV=android|ios sungen delivery <name>` still works to target a single OS. The **Test Environment** column is OS-precise: it shows only that OS's app id from the dual-id `Path:` — the Android **package** (`com.kngroup.media.converter`) on android, the iOS **bundle id** (`com.kngroup.media.converter.dev`) on ios — never the combined dual-id.
+
 ---
 
 ## Column mapping (handled by CLI)

package/src/orchestrator/templates/ai-instructions/claude-skill-locale.md

@@ -30,7 +30,88 @@ Try: browser_navigate(baseURL)
 
 Announce which mode is being used before Phase 1.
 
-## Phase 1 — Audit selectors (always, no MCP)
+---
+
+## Mobile (Appium) variant
+
+> **When to use:** `qa/capabilities.yaml` has `platform: mobile`. The command reads this file and dispatches here. The web phases below still apply for web projects.
+
+### Mechanism overview
+
+| Web | Mobile |
+|---|---|
+| Switch via URL prefix / query param / UI switcher; persist via cookie / localStorage | Switch via **device locale** (`appium:language` / `appium:locale` caps + `noReset:false`) — wdio `resolveLocaleCaps` drives this at runtime |
+| Capture via Playwright MCP `browser_snapshot` | Capture via **Appium MCP** (`select_device` → `appium_session_management` → `appium_get_page_source` / `appium_screenshot`) |
+| Phase 6 writes selectors + test-data + Pages `{{base_path}}` + `locale-config.json` + `locale-fixture.ts` | Phase 6 writes **only** selectors + test-data (6a/6b/6c). No 6d, no 6f. |
+| Handoff: `SUNGEN_ENV=<locale> npx playwright test` | Handoff: `SUNGEN_ENV=<locale> npm run test:mobile` |
+
+### Mobile Phase 1 — Audit selectors (same as web, no MCP)
+
+Identical to the web Phase 1 below. Read the screen's `selectors/<feature>.yaml` and list every entry with hardcoded `name` or `value` text. Multi-source text rules for mobile: Android elements expose text via `@text` first, then `@content-desc`; iOS exposes via `@label` first, then `@value`. Treat both as potential locale-dependent candidates.
+
+### Mobile Phase 2 — Capture base locale (LIVE only)
+
+1. `select_device` — choose the connected device (or emulator/simulator).
+2. `appium_session_management(create)` with the app at the **base locale** (do not set `appium:language` / `appium:locale` — use the device's current locale, which should match the base test-data locale).
+3. Navigate to the target screen using the Background navigation recipe from the `.feature` file (same as `sungen-capture-mobile` does).
+4. `appium_get_page_source` + `appium_screenshot` — capture the accessibility tree and visual state.
+5. For each Phase-1 candidate: verify the hardcoded text appears in the page source (check `@text`, `@content-desc`, `@label`, `@value` attributes). Drop stale candidates that don't appear.
+
+Save state as `baseLocale = { pageSource, screenshot }`.
+
+### Mobile Phase 3 — Switch locale (LIVE only) — device locale
+
+There is **no URL prefix, query param, or browser storage injection on mobile**. The locale switch mechanism is always **device locale**:
+
+1. Close the current Appium session: `appium_session_management(delete)`.
+2. Relaunch with `appium:language` set to the language code (e.g. `ja`) and `appium:locale` set to the region code (e.g. `JP`), plus `appium:noReset: false` — this forces the app to re-run its first-launch locale detection from the OS locale, clearing any cached in-app override.
+3. Navigate to the target screen again (same Background recipe).
+4. `appium_get_page_source` + `appium_screenshot` — capture target-locale state.
+5. Compare a known Phase-1 candidate text between base and target snapshots — confirm text differs.
+
+**Optional in-app language picker**: if the app has a Settings screen with a language selector, that can be used as an alternative to relaunching. Default is device locale (above). Only use in-app picker if the user confirms it or if `noReset: false` is known ineffective for this app (see risk note in phase spec).
+
+### Mobile Phases 3.5 / 3.6 — N/A on mobile (web-only)
+
+**Skip entirely.** Phases 3.5 (browser storage diff) and 3.6 (storage verification via `addInitScript`) are Playwright / browser-only. On mobile, runtime locale is driven by `wdio resolveLocaleCaps()` reading `SUNGEN_LOCALE || SUNGEN_ENV` and setting `appium:language` / `appium:locale` caps automatically — no fixture injection needed.
+
+### Mobile Phase 4 — Diff base ↔ target (LIVE only)
+
+Same logic as web Phase 4 — pair each surviving candidate with its translated text from the target-locale page source. Match by element type + position in the accessibility tree. Mark unmatched candidates as "needs manual".
+
+### Mobile Phase 5 — Confirm proposal
+
+Same as web Phase 5. Present the proposal table; ask user to confirm / edit / cancel.
+
+### Mobile Phase 6 — Apply files
+
+Write **only these three outputs**:
+
+**6a. Update `selectors/<feature>.yaml`** — replace hardcoded `name`/`value` with `{{varName}}`. (Same as web 6a.)
+
+**6b. Update `test-data/<feature>.yaml`** — append new keys under `# === i18n: <screen> ===`. (Same as web 6b.)
+
+**6c. Create `test-data/<feature>.<locale>.yaml`** — overlay with only changed keys. Comment header: `# Run with: SUNGEN_ENV=<locale> npm run test:mobile`. (Same as web 6c but different run command.)
+
+**6d — SKIP (web-only)**: no Pages `{{base_path}}` changes. Mobile has no URL prefix routing.
+
+**6f — SKIP (web-only)**: no `locale-config.json` / `locale-fixture.ts`. wdio `resolveLocaleCaps` handles device locale at runtime — no Playwright context fixture needed.
+
+**6e. Compile**: `sungen generate --screen <name>` (or `--flow`). The appium adapter is auto-selected in a mobile project.
+
+### Mobile Phase 7 — Hand off
+
+Print summary (same fields as web Phase 7), then suggest:
+
+```
+SUNGEN_ENV=<locale> npm run test:mobile
+```
+
+Add note: *"If the device locale code differs from the overlay env name (e.g. `SUNGEN_ENV=staging-ja` but the device needs `ja`), set `SUNGEN_LOCALE=ja` — wdio `resolveLocaleCaps` reads `SUNGEN_LOCALE` as an override."*
+
+---
+
+## Phase 1 — Audit selectors (web + mobile, always, no MCP)
 
 For each `.feature` file under the screen, read the matching `selectors/<feature>.yaml`. List every entry whose `name` or `value` field contains literal text WITHOUT `{{…}}` AND is not a CSS/href selector.
 
@@ -54,7 +135,9 @@ nav kudos          | name  | Sun* Kudos                | brand — skip
 
 If there are zero candidates and no `{{var}}` either, the screen has no localizable text → tell user and stop.
 
-## Phase 2 — Capture base locale (LIVE only)
+## Phase 2 — Capture base locale (web, LIVE only)
+
+> **Mobile**: see "Mobile Phase 2" in the Mobile (Appium) variant section above.
 
 1. Read `playwright.config.ts` for `baseURL`. Read `Path:` from `.feature` for the entry-point path.
 2. If the screen has `@auth:<role>` tags, load `specs/.auth/<role>.json` via `browser_set_storage_state` first.
@@ -69,7 +152,9 @@ Save state to memory as `baseLocale = { url, snapshot, storage }`.
 
 If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Fall back to OFFLINE mode by re-running once auth works, or pick `Offline-only` next time."*
 
-## Phase 3 — Switch locale (LIVE only) — detect mechanism + storage delta
+## Phase 3 — Switch locale (web, LIVE only) — detect mechanism + storage delta
+
+> **Mobile**: see "Mobile Phase 3" in the Mobile (Appium) variant section above. Phases 3.5 and 3.6 are web-only — skip on mobile.
 
 Goal: identify (a) HOW to switch the app to the target locale, and (b) WHAT app-side storage state ends up holding the locale preference so a fresh BrowserContext can be primed identically without driving the UI.
 
@@ -161,7 +246,9 @@ If verification fails / can't run → drop confidence by one tier, ask user.
 
 Save mechanism + verified storage delta to memory for use in Phase 6.
 
-## Phase 4 — Diff base ↔ target (LIVE only)
+## Phase 4 — Diff base ↔ target (LIVE only, web + mobile)
+
+> **Mobile**: use Appium page-source snapshots instead of Playwright snapshots. Logic is identical.
 
 For each candidate from Phase 1 that survived Phase 2:
 - Find the SAME element in the target-locale snapshot (match by `role`+position, by `aria-label` if available, by neighbor structure)
@@ -196,7 +283,9 @@ If user wants to edit a row → fall through to a per-row prompt asking for `var
 
 In OFFLINE mode this phase is the same table but `target text` column is blank — user fills via subsequent prompts or by editing the overlay file after the skill finishes.
 
-## Phase 6 — Apply changes (always, after confirmation)
+## Phase 6 — Apply changes (web, always, after confirmation)
+
+> **Mobile**: follow "Mobile Phase 6" in the Mobile (Appium) variant section — only 6a/6b/6c apply. Skip 6d and 6f entirely.
 
 For each confirmed row:
 
@@ -224,7 +313,7 @@ nav_about: 'About SAA 2025'
 nav_awards: 'Awards Info'
 ```
 
-**6d. (URL/query mechanism only) Update Pages selectors**
+**6d. (web, URL/query mechanism only) Update Pages selectors**
 
 If Phase 3 detected URL prefix:
 
@@ -251,7 +340,9 @@ If Phase 3 detected query param: similar but with `query_suffix: ''` / `query_su
 
 If Phase 3 detected UI switcher: do NOT modify Pages. Instead, write the storage delta from Phase 3.5 into `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) (see 6f below).
 
-**6f. Storage injection config — `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`)**
+**6f. (web-only) Storage injection config — `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`)**
+
+> **Mobile**: skip 6f entirely. wdio `resolveLocaleCaps` sets the device locale via Appium caps — no Playwright fixture needed.
 
 Always write `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) with the verified storage delta from Phase 3.5/3.6. This file is consumed by `specs/locale-fixture.ts` (auto-generated alongside `specs/base.ts`) — the fixture wraps Playwright's context, calls `addInitScript` to seed sessionStorage / localStorage, and `addCookies` for any cookies, BEFORE the first page navigation. Without this file, `SUNGEN_ENV=<locale>` only swaps test-data overlay — the browser would still boot in base locale.
 
@@ -290,15 +381,21 @@ Print summary:
 - N selectors converted to `{{var}}`
 - M base keys added to `test-data/<feature>.yaml`
 - K overlay keys written to `test-data/<feature>.<locale>.yaml`
-- Pages selectors updated: yes/no
-- Locale-switching mechanism: URL prefix `/en` / query `?lang=en` / UI switcher / manual
+- Pages selectors updated: yes/no (web only; N/A on mobile)
+- Locale-switching mechanism: URL prefix `/en` / query `?lang=en` / UI switcher / manual (web) | device locale via `appium:language`/`appium:locale` (mobile)
 
 Suggest:
 
 ```
+# web
 /sungen:run-test <name> --env <locale>
+
+# mobile
+SUNGEN_ENV=<locale> npm run test:mobile
 ```
 
+> **Mobile note**: if the device locale code differs from the overlay env name (e.g. `SUNGEN_ENV=staging-ja` but device needs `ja`), set `SUNGEN_LOCALE=ja` — wdio `resolveLocaleCaps` reads it as an override.
+
 ## Multi-feature screens
 
 If the screen has multiple `.feature` files (e.g. `home.feature` + `home-modal.feature`), repeat Phase 1 → Phase 6 for each feature file with its own selectors + test-data pair. Phase 2 + 3 (live capture + locale switch detection) run **once per screen** — the mechanism is the same. Phase 4 (text diff) runs per feature because each has its own scope of UI.