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

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

@@ -1,30 +1,50 @@
 ---
 name: sungen-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>]'
 agent: 'agent'
-tools: [vscode, execute, read, agent, edit, search, todo]
+tools: [vscode, execute, read, agent, edit, search, todo, 'appium-mcp/*']
 ---
 
 **Input**: Flow name and optional starting URL (e.g., `/sungen-add-flow award-submission --path /login`).
+For mobile: `/sungen-add-flow my-flow --reach "tap [My Page] tab"`.
 
 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
 
 - **flow** — ${input: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)
 
 ## Steps
 
 ### 1. Scaffold the flow
 
+**Web:**
+
 Run with #tool:terminal:
 ```bash
 sungen add-flow --flow ${input:flow} --path ${input:path}
 ```
 
+**Mobile (when `platform: mobile` in `qa/capabilities.yaml`):**
+
+Run with #tool:terminal:
+```bash
+sungen add-flow --flow ${input:flow} [--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/${input:flow}/
@@ -47,6 +67,16 @@ Record the screen list — you will need it for:
 
 ### 2. Capture visual source
 
+**Mobile path (when `platform: mobile` in `qa/capabilities.yaml`):**
+
+Ask: *"Capture a live screen via Appium MCP now?"*
+- **1) Yes, capture now (Recommended)** — invoke the `sungen-capture-mobile` skill (Appium MCP) for the first screen of the flow. Repeat for each screen in the flow as needed.
+- **2) 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:**
+
 Ask: *"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/copilot-cmd-add-screen.md

@@ -1,23 +1,33 @@
 ---
 name: sungen-add-screen
-description: 'Add a new Sungen screen or a sub-feature to an existing one — scaffolds directories, helps fill spec.md, and can auto-capture a live-page screenshot via Playwright MCP'
-argument-hint: '[screen-name] [url-path] [--feature <name>] [--figma <url>]'
+description: 'Add a new Sungen screen or a sub-feature to an existing one — scaffolds directories, helps fill spec.md, and can capture visuals via Playwright MCP (web) or Appium MCP (mobile)'
+argument-hint: '[screen-name] [url-path] [--feature <name>] [--figma <url>] [--reach <steps>] [--platform android|ios]'
 agent: 'agent'
-tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
+tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*', 'appium-mcp/*']
 ---
 
 **Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
 Optionally include a Figma URL: `/sungen-add-screen login /login --figma https://www.figma.com/design/...`.
 To add a sub-feature file to an existing screen: `/sungen-add-screen awards --feature modal`.
+For mobile: `/sungen-add-screen home --reach "tap [My Page] tab > tap [Settings] row"`.
 
 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
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
-- **path** — ${input:path:URL path (e.g., /login, /dashboard)} — optional when --figma is provided or when adding a sub-feature
+- **path** — ${input:path:URL path (web) or app entry (mobile, e.g., com.example.app)} — 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. Ignored (with warning) on web projects.
+- **`--platform android|ios`** — (mobile only, optional) emit `@platform:android/ios` tag for OS-specific screens. 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.
-- **`--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)
@@ -31,13 +41,29 @@ You are adding a new Sungen screen for test generation, or extending an existing
 
 ### 1. Scaffold the screen (or sub-feature)
 
-**Standard path (no --figma, no --feature):**
+**Web — standard path (no --figma, no --feature):**
 
 Run with #tool:terminal:
 ```bash
 sungen add --screen ${input:screen} --path ${input:path}
 ```
 
+**Mobile path (when `platform: mobile` in `qa/capabilities.yaml`):**
+
+`--path` is the app entry — the Android **package** alone (launch activity auto-detected; append `/<appActivity>` only to pin a non-standard launcher), an iOS bundleId, or the dual-id `"<pkg> | <bundleId>"` for cross-platform. After confirming the app entry, ask the user *"After the app launches, what taps reach this screen? e.g. `tap [My Page] tab > tap [Settings] row` — leave blank if this IS the launcher screen"* and pass it as `--reach`.
+
+Run with #tool:terminal:
+```bash
+sungen add --screen ${input:screen} \
+  --path "<appPackage>[ | <iosBundleId>]" \
+  [--reach "tap [My Page] tab > tap [Settings] row"] \
+  [--platform android|ios]
+# --reach is scaffolded into the Background so capture-mobile / the test run land on THIS screen.
+# 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):**
 
 Run with #tool:terminal:
@@ -87,6 +113,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`):**
+
+Ask: *"Capture a live screen via Appium MCP now?"*
+- **1) 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/`.
+- **2) 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. Offer:
 - **1) Continue** — Figma visuals are enough (Recommended)
 - **2) Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture` skill (mode live))
@@ -119,12 +155,17 @@ Then offer next steps:
 
 ```
 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/copilot-cmd-create-test.md

@@ -8,6 +8,13 @@ tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwri
 
 **Input**: Screen or flow name (e.g., `/sungen-create-test admin-users`).
 
+## 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**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Tier 1 (critical+high) first** — expand coverage later. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-run-test`.
@@ -66,11 +73,12 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections. Present sections as a numbered list and let user pick.
 5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. Generate **group-by-group** (one viewpoint group at a time, tier-by-tier `Write`/`Edit` batches) to stay under the output-token cap. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag.
    > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
+   > **Load lazily (budget, S4).** Per group, load **only** the one matching `sungen-viewpoint` group file + the relevant `spec.md` section(s) — never all five groups or the whole spec. On a tight (~200k) budget, write smaller tier-by-tier batches and keep prior batches on disk; this is what keeps generation inside a non-1M context.
 5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
 5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
 5.5b. **Phase gate (boundary — do NOT skip).** Run `sungen gate --screen ${input:name} --phase create` (exit 2 = HALT): every required obligation (spec · coverage · depth · trace) must be **satisfied or explicitly waived**. On **HALT**, keep repairing within budget; a genuinely-accepted gap → `sungen journey --screen ${input:name} --waive <OB> --reason "..."` (reason mandatory). Do **not** converge (step 6) past a HALT without a fix or a reasoned waiver.
 5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.
-6. **Converge — show the trace.** Run `sungen trace --screen ${input:name}` and present: process map (phases + repair rounds), bottlenecks, **HUMAN-LOOP FOCUS** (@manual to verify), audit score + gate + residual gaps. Then offer next steps based on which tier was just generated:
+6. **Converge — show the journey board first, then the trace.** First run `sungen journey --screen ${input:name}` and present the board: **📍 you-are-here**, the **obligation checklist** (what must still be true), and **especially the 🔎 Review queue** — each item carries an IDE-jumpable anchor 〔`VP-id · file:line`〕 that tells the user *what to review and where*. End with the board's **→ Next**. Then run `sungen trace --screen ${input:name}` for the process map (phases + repair rounds), bottlenecks, audit score + gate + residual gaps. Then offer next steps based on which tier was just generated:
 
    > The harness gate + reviewer already ran above — `/sungen-review` is the independent checkpoint (hand/prompt-authored or pre-delivery), not a needed next step here.
 

package/src/orchestrator/templates/ai-instructions/copilot-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, run `sungen gate --screen <name> --phase deliver` (exit 2 = HALT). On **HALT** the screen is **not signed off yet**: present `sungen journey --screen <name>` (the **🔎 Review queue** + anchors 〔`VP-id · file:line`〕) so the user reviews *what / where*, then resolve the items or sign off with `sungen journey --screen <name> --signoff --by "<name>"`. Do **not** export past a deliver HALT without a sign-off (skip only for an explicit draft/preview export).
+
 ### 1. Invoke the CLI
 
 Run via Bash (single command, no extra parsing):
@@ -42,6 +46,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 target.

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

@@ -1,8 +1,8 @@
 ---
 name: sungen-locale
-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]"
-tools: [read, execute, edit, vscode/askQuestions, playwright/*]
+tools: [read, execute, edit, vscode/askQuestions, playwright/*, appium/*]
 ---
 
 ## Role
@@ -15,10 +15,31 @@ Parse from `$ARGUMENTS`:
 - **name** — screen or flow name (e.g. `home`, `awards`). If missing, ask the user.
 - **locale** — target locale code (e.g. `en`, `ja`, `en-US`, `staging-ja`). If missing, ask. This becomes the suffix in `test-data/<feature>.<locale>.yaml` and `SUNGEN_ENV=<locale>` at run time.
 - **`--base-locale <code>`** — optional. Locale of the existing `test-data/<feature>.yaml`. Default `vi`. Reporting only — files are never renamed.
-- **`--offline`** — force OFFLINE mode (skip Playwright capture). Useful when you know the live page can't be reached.
+- **`--offline`** — force OFFLINE mode (skip live capture). Useful when you know the live page/device can't be reached.
 
 Reject if name == locale.
 
+## 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.
+- **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`:
@@ -26,7 +47,7 @@ Same as `/sungen:run-test`:
 - Else `qa/screens/<name>/` exists → screen mode (base path: `qa/screens/<name>/`)
 - Neither → tell user and stop
 
-## Steps
+## Steps (web)
 
 The `sungen-locale` skill defines 7 phases. Execute them in order:
 

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

@@ -8,6 +8,13 @@ tools: [vscode, execute, read, edit, search, todo]
 
 **Input**: Screen or flow name (e.g., `/sungen-review admin-users`).
 
+## 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** — 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/copilot-cmd-run-test.md

@@ -1,13 +1,47 @@
 ---
 name: sungen-run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: "[name] [--env <locale>]"
-tools: [read, execute, edit, vscode/askQuestions, playwright/*]
+argument-hint: "[name] [--env <locale>] [--ios|--android|--both]"
+tools: [read, execute, edit, vscode/askQuestions, playwright/*, appium/*]
 ---
 
 ## 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**: `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.)
 
@@ -94,7 +128,7 @@ If the unit is **api-first**, skip every selector/capture phase (an API test has
 6. **Phase 2 — Priority Wave**: Run all `@high` scenarios. Fix only failures from this wave. Max 2 attempts. Shared selectors fixed here cascade to later phases.
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
-9. **Integrity & trace (always run after the final run).** `sungen script-check --screen <name>` — verify the spec is a **1:1** of the Gherkin; if **DRIFT**, re-run `sungen generate --screen <name>` (never hand-edit the `.spec.ts` — auto-fix edits `selectors.yaml`). Then `sungen ledger record --screen <name> --step run --ms <elapsed>` and `sungen trace --screen <name>` to show the process map + bottlenecks + **HUMAN-LOOP FOCUS**.
+9. **Integrity & trace (always run after the final run).** `sungen script-check --screen <name>` — verify the spec is a **1:1** of the Gherkin; if **DRIFT**, re-run `sungen generate --screen <name>` (never hand-edit the `.spec.ts` — auto-fix edits `selectors.yaml`). Then `sungen ledger record --screen <name> --step run --ms <elapsed>` and **present the journey board** — `sungen journey --screen <name>` — as the human-facing close-out: **📍 you-are-here**, the **obligation checklist**, and **especially the 🔎 Review queue** with 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** says whether to sign off & deliver.
 9b. **Phase gate (boundary — do NOT skip).** `sungen gate --screen <name> --phase run` (exit 2 = HALT): run-boundary obligations (incl. automation) must be **satisfied or explicitly waived**. On HALT, classify per `sungen-error-mapping` § Source of truth (#387): selector-resolution failure → fix `selectors.yaml` + re-run; assertion-vs-spec failure → **report as a candidate bug / leave it FAIL** (never weaken to pass); accepted gap → `sungen journey --screen <name> --waive <OB> --reason "..."`. Don't declare "done" past a HALT without a fix, a reported bug, or a reasoned waiver.
 10. **Capability-pending offer (consent-gated).** If `sungen audit` reports `AUTOMATION-READY-PENDING` (or `@requires:<cap>` tests are skipped "requires …"), 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>` + re-run; on no, leave skipped (not failures, not manual). **Never auto-install.**
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-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/github-skill-sungen-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.
+
+### 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 it 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 zero candidates and zero `{{var}}` already in place → screen has no localizable text. Tell user, 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 entry path.
 2. If screen has `@auth:<role>` tags, load `specs/.auth/<role>.json` via `browser_set_storage_state` first.
@@ -69,7 +152,9 @@ Save state in memory as `baseLocale = { url, snapshot, storage }`.
 
 If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Re-run with `--offline` flag, or unblock auth first."*
 
-## 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.
 
@@ -149,7 +234,9 @@ If verification fails → drop confidence one tier, ask user.
 
 Save mechanism + verified storage delta to memory for 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 target-locale snapshot (match by `role`+position, by `aria-label`, by neighbor structure)
@@ -183,7 +270,9 @@ If user wants to edit a row → fall through to a per-row prompt for `var name`
 
 OFFLINE mode: same table but `target text` column 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:
 
@@ -211,7 +300,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**
 
 URL prefix:
 
@@ -237,7 +326,9 @@ Query param mechanism: append `query_suffix` similarly.
 
 UI switcher: do NOT modify Pages. Write storage delta into `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`) (6f).
 
-**6f. Storage injection config — `specs/generated/locale-config.json` (sibling of generated `base.ts` + `locale-fixture.ts`)**
+**6f. (web-only) Storage injection config — `specs/generated/locale-config.json` (sibling of generated `base.ts` + `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 generated `base.ts` + `locale-fixture.ts`) with the verified storage delta from Phase 3.5/3.6. Consumed by `specs/locale-fixture.ts` (auto-generated alongside `specs/base.ts`), which wraps Playwright's context and calls `addInitScript` + `addCookies` BEFORE the first navigation.
 
@@ -269,15 +360,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 run **once per screen** — mechanism is the same. Phase 4 runs per feature because UI scope differs.