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

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`.
@@ -25,7 +32,7 @@ You are an **independent QA Reviewer** — you did not author these tests. You d
 1. **Enumerate** `<base>/${input:name}/features/*.feature`. If none → `/sungen-create-test` first.
 2. **Run the harness (source of truth) — no separate rubric:**
    - `sungen audit --screen ${input:name}` → gate, business-weighted score, findings, gaps.
-   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?).
+   - Apply the **`sungen-reviewer` criteria inline** → semantic verdict (do steps prove the title? observable Then? business-critical depth? @manual justified?). Walk the **lenses sequentially** (#410) — `correctness`, `depth`, `traceability`, `manual` (+ `api`) — deeper per lens than one pass, then merge + dedupe by `[scenario id]` + problem.
    - `sungen script-check --screen ${input:name}` → spec is 1:1 with the Gherkin (flags hand-edit / stale drift; only if a spec exists).
 3. **Unified scorecard** per feature, anchored on harness signals (the `sungen-tc-review` 7 dimensions are a presentation layer, not a competing score):
    ```

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.