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

package/dist/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/dist/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/dist/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/dist/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/dist/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.2-beta.11",
+  "version": "3.2.2-beta.14",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
-    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts && tsx tests/journey/run.ts",
+    "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/exporter/feature-parser-category.run.ts && tsx tests/exporter/api-detail-sheet.run.ts && tsx tests/exporter/mobile-app-id.run.ts && tsx tests/api-runtime/base-path-url-join.run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts && tsx tests/generate-hint/run.ts && tsx tests/template-assertion/run.ts && tsx tests/journey/run.ts",
     "test:update": "tsx tests/golden/run.ts --update && tsx tests/audit/run.ts --update && tsx tests/ingest/run.ts --update",
     "prepublishOnly": "npm run build:dashboard && npm run build"
   },
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.2.2-beta.11",
+    "@sungen/driver-ui": "3.2.2-beta.14",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",

package/src/capabilities/discover.ts

@@ -10,8 +10,12 @@
  * load first, then `LOCAL_DRIVERS` (db → api), then `core` — i.e. the historical ui → db → api → core
  * composition order, so pattern composition / compiled output is byte-identical.
  *
- * A driver that isn't installed is simply skipped (capabilities are opt-in). Errors thrown *inside* a
- * present driver propagate — only a genuinely absent package is swallowed (resolve-then-require).
+ * An OPT-IN driver that isn't installed is simply skipped (capabilities are opt-in). A BUNDLED
+ * driver (a core dependency, e.g. `@sungen/driver-ui`) that fails to resolve is NOT opt-in — it
+ * signals a broken/incomplete install, so it warns LOUDLY instead of degrading silently to
+ * "Unrecognized step pattern". Errors thrown *inside* a present driver propagate — only a genuinely
+ * absent package is swallowed (resolve-then-require). Nothing here throws: the CLI must keep working
+ * (`--version`, `capability remove`) even when a driver is missing/broken.
  */
 import { createRequire } from 'module';
 import * as path from 'path';
@@ -25,6 +29,15 @@ import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
  */
 const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api', '@sungen/driver-mobile'];
 
+/**
+ * Bundled (non-opt-in) drivers: shipped as a core dependency (`drivers.yaml` `bundled: true`), so the
+ * project gets them without `sungen capability add`. If one fails to resolve it is NOT a declined
+ * opt-in — it is a broken install (e.g. a dev workspace that skipped `npm install`, so the workspace
+ * symlink for the package is missing). Surface it LOUDLY: otherwise the entire UI step vocabulary is
+ * absent and every step silently compiles to "Unrecognized step pattern" with no clue why.
+ */
+const BUNDLED_DRIVERS = new Set(['@sungen/driver-ui']);
+
 function loadExternalDriver(name: string): void {
   // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers
   // (`sungen capability add db|api`) install into the PROJECT's node_modules — a globally-installed
@@ -51,7 +64,20 @@ function loadExternalDriver(name: string): void {
     }
     return; // found at this anchor (loaded or warned) — don't fall through to other anchors
   }
-  // not installed at any anchor — capabilities are opt-in, so skip silently
+  // Not resolvable at ANY anchor.
+  if (BUNDLED_DRIVERS.has(name)) {
+    // A bundled default is missing → broken install, not a declined opt-in. Warn loudly so the user
+    // sees the real cause instead of a wall of "Unrecognized step pattern".
+    console.warn(
+      `⚠ sungen: the bundled driver "${name}" could not be resolved — its step patterns are MISSING, ` +
+      `so steps will compile to "// Unrecognized step pattern".\n` +
+      `  This means the install is incomplete. Fix:\n` +
+      `    • in an app project:   run \`npm install\`\n` +
+      `    • in the sungen monorepo: run \`npm install\` at the repo ROOT (bootstraps the workspace symlink for ${name})`,
+    );
+    return;
+  }
+  // Opt-in driver not installed — capabilities are opt-in, so skip silently.
 }
 
 export function discoverAndRegisterCapabilities(): void {

package/src/cli/commands/add-flow.ts

@@ -7,6 +7,7 @@ export function registerAddFlowCommand(program: Command): void {
     .requiredOption('--flow <name>', 'Flow name')
     .option('-p, --path <path>', 'Starting page route path (e.g. /login)')
     .option('-d, --description <text>', 'Flow description')
+    .option('--reach <steps>', 'Mobile navigation recipe for the flow\'s starting screen: a ">"-separated list of nav steps from app launch, e.g. "tap [My Page] tab > tap [Settings] row". Scaffolded into the Background. Ignored (with a warning) on web projects.')
     .action(async (options) => {
       try {
         const { FlowManager } = require('../../orchestrator/flow-manager');
@@ -16,6 +17,7 @@ export function registerAddFlowCommand(program: Command): void {
           name: options.flow,
           path: options.path,
           description: options.description,
+          reach: options.reach,
         });
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);

package/src/cli/commands/add.ts

@@ -11,6 +11,8 @@ export function registerAddCommand(program: Command): void {
     .option('-c, --capture', 'Auto-capture a live-page screenshot to requirements/ui/ (requires --path)')
     .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
+    .option('--platform <platform>', 'Optional per-OS tag: android | ios. Emits @platform:android/ios on the stub for OS-specific screens. Does NOT affect directory routing (always qa/screens/). Omit for cross-platform mobile or web.')
+    .option('--reach <steps>', 'Mobile navigation recipe (in-app web-path analog): a ">"-separated list of nav steps from app launch to this screen, e.g. "tap [My Page] tab > tap [Settings] row". Scaffolded into the Background; capture-mobile replays it. Ignored (with a warning) on web projects.')
     .option('--figma <url>', "Figma share URL — fetch design node and generate spec_figma.md + ui/*.png. QUOTE the URL ('...'): the '&' in Figma links backgrounds the shell otherwise.")
     .option('--refresh', 'Bypass Figma cache and re-fetch from API (use with --figma)')
     .option('--scale <n>', 'PNG export scale factor (default: 2)', parseFloat, 2)
@@ -38,6 +40,8 @@ export function registerAddCommand(program: Command): void {
             capture: options.capture,
             feature: options.feature,
             description: options.description,
+            platform: options.platform,
+            reach: options.reach,
           });
         } else {
           console.log(`Screen "${options.screen}" already exists — refreshing Figma assets only.`);

package/src/cli/commands/capability.ts

@@ -8,12 +8,34 @@ import {
 } from '../../harness/capability';
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
+import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
 
 /** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
 function coreVersion(): string {
   try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
 }
 
+/**
+ * Add `test:mobile` to the project's package.json scripts (if absent).
+ * Idempotent — skips if the script is already set.
+ * Returns true if the script was added, false if already present or no package.json.
+ */
+function addMobileScript(cwd: string): boolean {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+  let pkg: Record<string, any>;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  if (!pkg.scripts || typeof pkg.scripts !== 'object') pkg.scripts = {};
+  if (pkg.scripts['test:mobile']) return false;
+  pkg.scripts['test:mobile'] = 'wdio run wdio.conf.ts';
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+  return true;
+}
+
 /**
  * Verify a capability driver (db/api/…) installed into the PROJECT exposes the capability SPI entry
  * (`sungenDriver.register`). Resolved from the project's node_modules so it works with a globally
@@ -137,13 +159,33 @@ export function registerCapabilityCommand(program: Command): void {
     .command('add <driver>')
     .description('Enable a driver: install its package (if external) + record it in qa/capabilities.yaml')
     .option('--skip-install', 'Only record in the profile; do not run npm install')
-    .action((driver: string, o: { skipInstall?: boolean }) => {
+    .option('--force', 'Switch the project platform even if a different one is already set (sungen is one platform per project)')
+    .action((driver: string, o: { skipInstall?: boolean; force?: boolean }) => {
       try {
         const cwd = process.cwd();
         const meta = driverMeta(driver);
         if (!meta) {
           throw new Error(`Unknown driver "${driver}". Known: ${Object.keys(loadDriverCatalog()).join(', ')}`);
         }
+
+        // Guard: a platform driver (web/mobile) sets the project's SINGLE platform. If a DIFFERENT
+        // platform is already set, adding this one would silently FLIP it (e.g. web → mobile) and make
+        // the existing feature files compile for the wrong runtime. Refuse unless --force, and point at
+        // the correct path for a web+mobile repo (two separate project folders).
+        const current = readCapabilities(cwd);
+        if (meta.kind === 'platform' && current.platform && current.platform !== driver && !o.force) {
+          const initHint = driver === 'mobile' ? ' --mobile --app-package <pkg>' : ' --base-url <url>';
+          console.error(
+            `✗ This project's platform is already "${current.platform}". Adding "${driver}" would SWITCH it to "${driver}".\n` +
+            `  sungen is ONE platform per project — this is NOT "${current.platform} + ${driver}" together.\n` +
+            `  • Want BOTH web and mobile? Keep this project and create a SEPARATE folder for ${driver}:\n` +
+            `      sungen init ${driver}-tests${initHint}\n` +
+            `  • Really converting ${current.platform} → ${driver}? Re-run with --force\n` +
+            `      (your existing ${current.platform} feature files would then compile for ${driver}).`,
+          );
+          process.exit(1);
+        }
+
         const adapterName = meta.adapter || meta.id;
         const bundled = adapterRegistry.hasAdapter(adapterName); // e.g. `web` is bundled in Phase 2a
 
@@ -176,6 +218,27 @@ export function registerCapabilityCommand(program: Command): void {
         const platform = meta.kind === 'platform' ? driver : profile.platform;
         writeCapabilities(cwd, { platform, enabled });
         console.log(`✓ capability "${driver}" enabled${meta.kind === 'platform' ? ` (platform=${driver})` : ''}.`);
+
+        // Emit the mobile runtime harness when the mobile platform driver is added.
+        // Idempotent: emitMobileRuntime skips files that already exist.
+        if (platform === 'mobile') {
+          console.log('');
+          console.log('🔧 Emitting mobile runtime harness...');
+          const result = emitMobileRuntime(cwd, { enabled: true });
+          for (const f of result.created) console.log(`  ✓ created  ${f}`);
+          for (const f of result.skipped) console.log(`  – skipped  ${f} (already exists)`);
+
+          // Add test:mobile script to package.json (idempotent)
+          if (addMobileScript(cwd)) {
+            console.log('  ✓ created  package.json scripts[test:mobile]');
+          } else {
+            console.log('  – skipped  package.json scripts[test:mobile] (already exists)');
+          }
+
+          // Best-effort driver install — non-fatal so capability add still succeeds offline.
+          installMobileDriver(cwd);
+        }
+
         console.log('');
       } catch (e) {
         console.error('Error:', e instanceof Error ? e.message : e);