@sun-asterisk/sungen 3.2.0 → 3.2.1-beta.1

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-fix-mobile.md

@@ -0,0 +1,316 @@
+---
+name: sungen-selector-fix-mobile
+description: 'Mobile selector fixing — Appium MCP exploration, accessibility-id-first strategy, run via wdio. Auto-loaded by run-test for @platform:mobile/android/ios screens.'
+user-invocable: false
+---
+
+## Strategy: Phased Execution (mobile)
+
+Mobile analogue of `sungen-selector-fix`. Same philosophy — pre-generate selectors, smoke-check, fix
+in priority waves — but using **Appium MCP** for exploration and **WebdriverIO** (`npm run test:mobile`)
+to run, instead of Playwright MCP / `playwright test`.
+
+**Never run blindly.** Pre-generate selectors → smoke check → widen.
+
+---
+
+## Phase 0: Pre-run Selector Generation (Appium MCP)
+
+Populate `selectors.yaml` from the live app before compiling so tests don't fail on missing keys.
+
+### When to run
+- `selectors.yaml` missing/empty, or `[Reference]` keys lack entries and aren't auto-inferable.
+- User re-scans after a UI change.
+
+### Steps
+1. **Confirm** via `AskUserQuestion`: *"Generate selectors from the live app via Appium MCP now?"* —
+   **Yes, scan device** / **Skip (use existing)** / **Cancel**.
+2. **Collect references**: parse the `.feature` for every `[Reference]` + type. Deduplicate.
+3. **Launch the app** (delegate to `sungen-capture-mobile` or inline):
+   `select_device` → `appium_session_management(create)` with appPackage/appActivity from the feature `Path:`.
+4. **⚠️ Wait for render** before capturing — a Flutter/RN splash exposes zero elements. Screenshot first;
+   if blank, wait and re-check.
+5. **Capture**: `generate_locators` (priority-ranked locators) for the current screen. Navigate
+   (`appium_gesture tap` / `back`) to reach each screen referenced in the feature, capturing per screen.
+6. **Generate YAML entries**:
+   - Keys: follow `sungen-selector-keys` (lowercase, Unicode preserved, `--N` suffix for duplicates).
+   - **Selector priority (mobile)** — see Step 3 table: `accessibility-id` > `id` > platform-native > `xpath`.
+   - Copy `content-desc`/`accessibility id` **character-for-character** from `generate_locators`. Never
+     infer from the Gherkin label.
+   - **i18n / Flutter**: `content-desc` often equals the visible text and is locale-dependent. Use
+     `{{variable}}` in `value` and add `lbl_*` keys to test-data + locale overlays (see `sungen-locale`).
+7. **Duplicate check**: if a `content-desc` appears more than once in the tree, add `nth`.
+8. **Merge, don't overwrite**: keep user-authored entries; add only missing keys.
+9. **Confirm + write**, then **compile**: `sungen generate --screen <screen> --framework appium`.
+10. **End session** (`action=delete`) when done exploring.
+
+---
+
+## Phase 0.5: Mobile auth — the auth contract (guided builder)
+
+Mobile has **no `storageState`** like web. Instead, `@auth:<role>` features authenticate at runtime
+through an **auth contract** at `specs/.auth-mobile/<role>.json` (gitignored): the generated spec's
+`before(all)` hook (`__ensureAuth`) reaches the logged-in state — **idempotent** (skips login when the
+authed marker is already present thanks to `noReset:true`) and **fail-loud** (throws when the contract
+is missing or login fails, so @auth scenarios are blocked instead of silently running logged-out).
+
+**Pre-flight (BEFORE Phase 1):** when the feature carries `@auth:<role>`, check the contract exists:
+
+```bash
+ls specs/.auth-mobile/<role>.json 2>/dev/null || echo MISSING
+```
+
+Present → continue to Phase 1 (the hook handles everything). Missing → run the **guided builder**:
+
+### Guided contract builder
+
+1. `AskUserQuestion`:
+   - **Build the contract now (Recommended)** — AI drives the app via Appium MCP and writes the file
+   - **I'll write it by hand** — print the schema below and stop
+   - **Skip** — @auth scenarios will fail loud with instructions
+2. **Logged-out baseline**: Appium session (`select_device` → `appium_session_management(create)`,
+   `noReset:true`) → activate the app → `appium_get_page_source` → keep the element list.
+3. **Reach the login form**: ask the user how to navigate there (typical: account/profile tab → login
+   entry). Record EVERY tap on the way as a `loginSteps` entry, in order.
+4. **Credentials**: never echo passwords into chat. Reference them as `{{email}}` / `{{password}}` in
+   `loginSteps` and have the user fill the `credentials` map in the file themselves (it is gitignored).
+5. **Log in once** — either AI drives (`appium_gesture(tap)` + `appium_set_value`) with values the user
+   provides, or the user logs in by hand on the device. Both are fine; what matters is the end state.
+6. **Derive the `authedMarker`**: fresh `appium_get_page_source` → DIFF against the step-2 baseline.
+   Candidates = elements present ONLY after login (member-only menu item, avatar, logout). Prefer
+   accessibility-id; verify with `appium_find_element`. Never pick an element guests also have.
+7. **Write the contract** (schema below) and **validate**: terminate + relaunch the app → the marker is
+   still present (session persisted). Full loop: run one @auth scenario via
+   `SUNGEN_SPECS=<spec> npm run test:mobile`.
+
+### Contract schema — `specs/.auth-mobile/<role>.json` (gitignored)
+
+```jsonc
+{
+  "authedMarker": { "type": "accessibility-id", "value": "<element only present when logged in>" },
+  "credentials": { "email": "...", "password": "..." },          // keys are free-form per auth method
+  "loginSteps": [
+    { "action": "tap",  "selector": { "type": "accessibility-id", "value": "<account tab>" } },
+    { "action": "tap",  "selector": { "type": "accessibility-id", "value": "<login entry>" } },
+    { "action": "fill", "selector": { "type": "accessibility-id", "value": "<email field>" }, "value": "{{email}}" },
+    { "action": "fill", "selector": { "type": "accessibility-id", "value": "<password field>" }, "value": "{{password}}" },
+    { "action": "tap",  "selector": { "type": "accessibility-id", "value": "<submit>" } }
+    // app shows a launch interstitial/ad? add its dismiss tap as the FIRST step
+  ]
+}
+```
+
+- `selector.type`: `accessibility-id` | `xpath` | `android-uiautomator` | `ios-predicate` | `id` | `text`/`label`/`placeholder`
+- `action`: `tap` | `fill` (robust fill: type → read back → retry) | `wait`
+- Session model: `noReset:true` keeps the login alive across scenarios. i18n runs flip `noReset:false`
+  (device-locale re-detect) which wipes the session — re-login in the contract or keep @auth suites on
+  the base locale.
+- The non-automatable parts (OTP, captcha, biometrics) stay manual: have the user complete them once in
+  step 5; the persisted session + `authedMarker` check carries every later run.
+---
+
+## Phases 1–4: Run waves via WebdriverIO
+
+Mobile runs go through the wdio runner (auto-selects `@wdio/globals` specs — the mobile ones):
+
+```bash
+# Smoke: a single scenario / spec
+SUNGEN_SPECS='./specs/generated/<screen>/<feature>.spec.ts' npm run test:mobile
+
+# Full mobile suite
+npm run test:mobile
+```
+
+- **Phase 1 (smoke)**: run the one screen's spec. Max 2 fix attempts.
+- **Phase 2 (priority)**: run the screen/feature suite. Max 2 fix attempts.
+- **Phase 3 (full)**: `npm run test:mobile`. Max 1 fix attempt.
+- **Phase 4 (regression)**: one final `npm run test:mobile`. No fix loop.
+
+> wdio/mocha tag-grep differs from Playwright. For a subset, scope with `SUNGEN_SPECS` or
+> `--mochaOpts.grep '<scenario name>'`.
+
+---
+
+## Diagnosis & Fix (mobile)
+
+### Step 1: Parse failures — and distinguish selector vs. state
+
+| Error pattern | Likely root cause | Fix target |
+|---|---|---|
+| `element wasn't found` / `can't call click on "~X"` | **selector mismatch** *or* **app on the wrong screen** | selectors.yaml **or** scenario state (see ⚠️ below) |
+| `waitForDisplayed` timeout | wrong locator, or element not yet rendered | selectors.yaml / add wait |
+| `toHaveText` mismatch | wrong expected data (or locale) | test-data.yaml |
+| `session not created` / `app not installed` | capability / install issue | wdio.conf capabilities / `adb install` |
+
+**⚠️ State, not selector.** The most common mobile false alarm: a selector "not found" because the app
+is **on a different screen than the scenario assumed** (e.g. a prior scenario left it deep in a sub-page;
+`appium:noReset=true` keeps state across the whole run). Before "fixing" a selector, **verify the app's
+current screen** with `appium_screenshot`. If the app is simply on the wrong screen, the fix is in the
+**scenario/navigation** (ensure each scenario starts from a known state — e.g. an explicit "navigate to
+Home" step, `back`, or relaunch), not in `selectors.yaml`.
+
+### Step 2: Targeted MCP exploration
+1. `select_device` + `appium_session_management(create)` (or reuse an open session).
+2. Navigate to the failing screen (`appium_gesture`), **wait for render**.
+3. `generate_locators` (or `appium_find_element` to test one candidate). Fix all broken selectors from
+   this snapshot. Use `appium_ai` (vision) only as a last resort for low-accessibility screens.
+
+### Step 3: Fix broken selectors — mobile priority
+
+| Priority | type | When |
+|---|---|---|
+| 1 | `accessibility-id` | element has `content-desc` / accessibilityIdentifier (most stable) |
+| 2 | `id` | Android resource-id present |
+| 3 | `android-uiautomator` / `ios-predicate` | platform-native, when 1–2 unavailable |
+| 4 | `xpath` | last resort — slow & brittle; prefer `contains(@content-desc,'…')` |
+
+Common fixes:
+- Name mismatch → copy exact `content-desc` from `generate_locators`.
+- Multiple matches → add `nth`.
+- Composite `\n` content-desc → `xpath` with `contains` on a unique substring.
+- No label (icon button, search field) → `xpath` / class, or ask devs to add a Semantics label / `Key`.
+- Locale-dependent text → `{{variable}}` + locale overlay (don't hardcode "English"/"Good afternoon!").
+
+### Step 4: Recompile after fix
+```bash
+sungen generate --screen <screen> --framework appium
+```
+Then re-run only the current phase.
+
+---
+
+## Cross-platform selectors (`@platform:mobile` — write once, run both)
+
+A `@platform:mobile` feature runs on **both** the Android and iOS capability sets in one
+`MOBILE_PLATFORM=both` run, so **every selector must resolve on both OSes**. Only `accessibility-id`
+is truly cross-platform: a Flutter `Semantics(label/identifier)` surfaces as Android `content-desc`
+**and** iOS `name`/`accessibilityIdentifier`, so a single `~Label` matches on each.
+
+**Rule for `@platform:mobile`: use `type: accessibility-id` for everything.** Avoid the platform-only
+strategies — a spec that uses them passes on the OS you tested and silently fails on the other:
+
+| Strategy | OK on | NOT on | Why it breaks cross-platform |
+|---|---|---|---|
+| `accessibility-id` (`~Label`) | Android + iOS | — | ✅ the one to use |
+| `//*[contains(@content-desc,'…')]` / `@text` xpath | Android | iOS | iOS has no `content-desc`/`text` attribute |
+| `android-uiautomator` (UiScrollable, UiSelector) | Android | iOS | UiAutomator2 only |
+| `id=` (resource-id) | Android | iOS | Android resource-id only |
+| `-ios predicate string:` / `-ios class chain` | iOS | Android | XCUITest only |
+
+When scanning a `@platform:mobile` screen with Appium MCP, **verify on both a booted Android device
+and an iOS simulator** and keep only selectors whose value matches on each (for Flutter the label is
+normally identical). If a required element is labeled on one OS but not the other (e.g. an icon button
+with no Semantics label on Android), either ask devs to add a matching `Semantics`/`accessibilityIdentifier`,
+or **split the feature** into `@platform:android` + `@platform:ios` files (each may then use its native
+strategy). Do NOT smuggle an Android-only xpath into a `@platform:mobile` selector set.
+
+> The app id may differ per OS (e.g. a Flutter `.dev` flavor on iOS). You don't handle that in
+> selectors — the generated spec resolves it at runtime (`driver.isIOS` → iOS bundle id from the
+> session caps, else the Android package from `Path:`). Selectors only need to be label-stable.
+
+For `@platform:android`-only or `@platform:ios`-only features, the **full** Step 3 priority table
+applies — platform-native strategies are fine because the spec runs on that one OS.
+
+---
+
+## Per-platform selector variants (`android:` / `ios:` in selectors.yaml)
+
+When a logical element can't be one cross-platform selector — **composite** content-desc, **partial/dynamic**
+text (greeting, substrings), or **per-OS-divergent** labels — give the key `android:` and `ios:` sub-selectors
+instead of a flat `type`/`value`. For a `@platform:mobile` feature the generated spec renders a runtime
+`driver.isIOS ? '<ios>' : '<android>'` per key (so ONE shared scenario resolves the right native selector on
+each OS); a `@platform:android` / `@platform:ios` feature picks that variant directly.
+
+```yaml
+# composite on Android (contains) / predicate on iOS — one shared scenario, both OSes
+"settings--title":
+  android: { type: xpath, value: "//*[contains(@content-desc,'{{settings_subtitle}}')]" }
+  ios:     { type: ios-predicate, value: "name CONTAINS '{{settings_subtitle}}' OR label CONTAINS '{{settings_subtitle}}'" }
+```
+
+- Define **both** variants for a `@platform:mobile` key (a missing side falls back to the bare entry).
+- `{{var}}` interpolation works inside each variant. **A shared `nth`/`scope`/`name` (at the key's top
+  level) applies to both OSes, but `nth`/`scope`/`name` CANNOT diverge per-platform** — the codegen ternary
+  swaps only strategy+value (`appium-selector-expr.hbs`). If Android and iOS need a DIFFERENT `nth`/`scope`,
+  that's a sub-feature, not a variant.
+- **Prefer a single exact `accessibility-id`** when the label is genuinely exact on both OSes (e.g. a clean
+  Flutter Semantics label) — only reach for variants when exact can't work. Verified example: "Output Format"
+  is exact → one `accessibility-id` passes both; "Select Image"/"Select Video" are composite → need variants.
+- This is the in-place alternative to splitting into per-OS sub-features: variants keep the scenario shared
+  and only the SELECTOR differs per OS (no scenario duplication). Use sub-features when the *scenario itself*
+  (steps/flow) differs per OS, variants when only the *locator* differs.
+
+> Below-fold on iOS: `scroll to` IS cross-platform (Android UiScrollable / iOS swipe-loop), and
+> `tap top of` on iOS taps the TOP-LEFT of the element — on short iOS viewports a bottom-row card may
+> peek only a few pt above a floating bottom nav whose raised centre FAB occludes the top-CENTRE
+> (verified live on the converter; top-left tap opens it). If a list genuinely cannot scroll further
+> and the element stays fully occluded, only then split that case to `@platform:android`.
+
+## Layered workflow & per-OS sub-features
+
+A screen's mobile coverage is **layered**. The shared file is the DEFAULT — exact accessibility-id OR
+`android:`/`ios:` selector variants (when only the locator differs). Push a case to a per-OS sub-feature
+ONLY on genuine SCENARIO divergence (different steps/flow, OS-only element, per-platform `nth`/`scope`):
+
+| File | Tag | Runs on | Selectors |
+|---|---|---|---|
+| `<screen>.feature` | `@platform:mobile` | Android **and** iOS | `accessibility-id` only |
+| `<screen>-android.feature` | `@platform:android` | Android only | full Android arsenal (`id`, `-android uiautomator`, `@content-desc` xpath, …) |
+| `<screen>-ios.feature` | `@platform:ios` | iOS only | full iOS arsenal (`-ios predicate`, …) |
+
+**Discovery order (explore one OS, run the other):**
+1. Explore the available OS (`sungen-capture-mobile`), write the **shared** cases into `<screen>.feature`
+   with accessibility-id selectors.
+2. Run them on the other OS: `MOBILE_PLATFORM=both npm run test:mobile`. Green ⇒ done, no second
+   exploration needed.
+3. For any element that **fails** on the 2nd OS, first add an `android:`/`ios:` selector VARIANT to its key
+   (the usual fix — composite content-desc / predicate / partial text) and re-run; the scenario stays
+   shared. Move the case into `<screen>-<os>.feature` ONLY if the FLOW itself diverges or a per-platform
+   `nth`/`scope` is required (a variant can't diverge those).
+
+**Running the layers** (each `.feature` compiles to its own spec, routed by its `// sungen:platform=` marker):
+```bash
+MOBILE_PLATFORM=both    npm run test:mobile   # shared specs on BOTH + each OS's own sub-feature specs
+MOBILE_PLATFORM=android npm run test:mobile   # shared + @platform:android only
+MOBILE_PLATFORM=ios     npm run test:mobile   # shared + @platform:ios only
+```
+(`wdio.conf` gives the Android cap the android+mobile specs and the iOS cap the ios+mobile specs, so a
+shared spec runs on each and a sub-feature spec runs only on its OS.)
+
+## Scrolling to off-screen elements (Flutter caveat)
+
+`scroll to [X]` compiles to `.scrollIntoView()`, which needs a native `android.widget.ScrollView`.
+Flutter/RN scrollables usually don't expose one → it errors ("Default scrollable element not found").
+For a **Flutter scrollable list**, prefer making the *target selector* auto-scroll via an
+`android-uiautomator` UiScrollable instead of a separate scroll step:
+
+```yaml
+"hindi option":
+  type: android-uiautomator
+  value: 'new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().descriptionContains("हिन्दी"))'
+```
+
+When `$()` resolves that selector, UiAutomator2 scrolls the list until the element is found — no
+separate `scroll to` needed. If the screen **isn't scrollable** (content fits the viewport) and an
+element is merely occluded by a floating bottom bar, neither scroll nor `element.click()` works → tag
+that scenario `@manual` until visible-point tapping lands.
+
+## Flutter / React-Native note
+
+These render to a canvas, but expose a **Semantics tree** to Appium as `content-desc` once a real screen
+is drawn — so UiAutomator2 + `accessibility-id` usually works (no flutter-driver needed) **provided** the
+app sets semantic labels. If `generate_locators` returns almost nothing on a populated screen, the app
+likely lacks semantics → escalate: ask devs to add `Semantics`/`Key`, or consider `appium-flutter-driver`
+(needs a debug/profile build). A blank result on a *loading* screen just means "wait for render".
+
+---
+
+## Attempt Budget Summary
+
+| Phase | What runs | Max fix attempts |
+|---|---|---|
+| 0. Pre-gen | Appium MCP `generate_locators` → selectors.yaml | 1 scan |
+| 1. Smoke | one screen spec via wdio | 2 |
+| 2. Priority | screen/feature suite | 2 |
+| 3. Full | `npm run test:mobile` | 1 |
+| 4. Regression | final `npm run test:mobile` | 0 |

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-capture-mobile.md

@@ -0,0 +1,184 @@
+---
+name: sungen-capture-mobile
+description: 'Capture a live mobile app screen via Appium MCP — locator tree + screenshot for visual context. Auto-loaded by create-test when the screen is @platform:mobile/android/ios.'
+user-invocable: false
+---
+
+## Purpose
+
+Launch a mobile app on a device/emulator, capture **one locator tree** (`generate_locators`) and **one screenshot**, and save them as visual context for test generation. The mobile analogue of `sungen-capture-live` — same job, Appium MCP instead of Playwright MCP.
+
+Use when the target is a native/Flutter/React-Native app (`@platform:android` or `@platform:ios`) running on a connected device or emulator.
+
+---
+
+## Prerequisites
+
+- `appium-mcp` connected (see `/mcp`). It runs Appium **embedded** — no separate server needed.
+- A device/emulator booted: `adb devices` shows one for Android; a Simulator for iOS.
+- The app **installed** on the device (`adb install -r <app>.apk` for Android).
+- The screen's `Path:` (in `<screen>/features/*.feature` or `spec.md`) gives the app entry as
+  `<appPackage>/<appActivity>` (Android) or bundleId (iOS), e.g. `com.kngroup.media.converter/.MainActivity`.
+
+---
+
+## Steps
+
+### 1. Resolve target app + entry
+
+Resolve in this order:
+1. `Path:` line in the feature / `App ID` in `spec.md` → split into `appPackage` + `appActivity`.
+   A dual-id Path (`<pkg>/<activity> | <iosBundleId>`) → take the part for the OS you are exploring
+   (left of `|` = Android pkg/activity, right = iOS bundle id).
+2. If missing → ask the user: *"What is the appPackage/appActivity (Android) or bundleId (iOS)?"*
+3. **Navigation recipe** — read the feature's `Background:` (the in-app web-path analog). Line 1
+   `Given User is on [Home] screen` is the launcher/landing screen the app opens on; each following
+   `When/And User tap [...]` (or gesture) is one hop toward the target screen. You will **replay**
+   these in step 4.5 so you scan the screen this feature targets — not the launcher. An anchor-only
+   Background (no nav steps) ⇒ the target IS the launcher screen ⇒ no navigation needed.
+
+### 2. Select device
+
+`select_device` with `platform: android` (or `ios`). If exactly one device, it auto-selects.
+If several, list them and ask the user which `deviceUdid`.
+
+### 3. Create the session
+
+`appium_session_management` `action=create`, `platform=android`, capabilities (JSON string):
+```
+appium:appPackage, appium:appActivity, appium:udid,
+appium:noReset=true, appium:autoGrantPermissions=true, appium:newCommandTimeout=300
+```
+For iOS, call `prepare_ios_simulator` first, then create with `appium:bundleId`.
+
+### 4. ⚠️ Wait for the screen to actually render
+
+**This is the #1 gotcha for Flutter / RN apps.** Right after launch the app often shows a blank
+splash — and the locator tree will contain **zero usable elements** (just an empty `FrameLayout`).
+Do **not** capture yet. Take a quick `appium_screenshot`; if it's blank/splash, wait and re-check
+until real content is drawn. Only then capture. (A Flutter app on a loading screen looks "invisible"
+to Appium; the same app on a rendered screen exposes its full Semantics tree.)
+
+### 4.5. ⚠️ Navigate to the target screen (replay the navigation recipe)
+
+**This is what makes capture land on the RIGHT screen** — the mobile equivalent of `page.goto(url)`
+on web. After the launcher screen has rendered, replay the `Background:` nav steps so Appium ends up
+on the screen this feature targets, *then* capture there.
+
+For each nav step **after** the `Given User is on [Home] screen` anchor, in order:
+1. `generate_locators` (or `appium_get_page_source`) on the CURRENT screen.
+2. Resolve the step's `[Label]` against the live tree — prefer `accessibility id`, then visible
+   `text`/`content-desc`, then an `xpath` on a distinctive substring. Gestures (`scroll to [X]`,
+   `swipe …`) follow `sungen-mobile-gestures`.
+3. Perform the tap/gesture, then **wait for the next screen to render** (same blank-splash guard as
+   step 4) before the next step.
+
+After the LAST step you are on the target screen — capture HERE (steps 5–6).
+
+- **Anchor-only Background** (no nav steps) ⇒ the target IS the launcher screen ⇒ skip this step.
+- **A step won't resolve** (its `[Label]` matches no element) ⇒ **STOP. Do not capture the wrong
+  screen.** Screenshot where you are and report: *"recipe step N: [Label] not found — fix the
+  Background nav path."* Fail loud (run-test would fail at the same step anyway).
+- **No recipe yet** (guided-stub Background, but the target is NOT the launcher) ⇒ drive to the
+  screen interactively off the live tree (if unsure which control leads there, ask the user), then
+  **report the exact nav steps you took** so create-test/add-screen can write them into the
+  Background. Do **not** edit the `.feature` yourself — Gherkin authorship stays with those commands.
+
+### 5. Capture the locator tree (primary AI context)
+
+Call **`generate_locators`** — this is the mobile equivalent of the web accessibility snapshot. It
+returns priority-ranked locators per interactable element: `accessibility id`, `id`, platform-native
+(`-android uiautomator` / `-ios predicate string`), and `xpath`, plus `content-desc`/`text`,
+`clickable`, `enabled`. This is what `sungen-tc-generation` and `sungen-selector-keys` consume.
+
+If the tree is huge, also `appium_get_page_source` (saved to a file) and grep it — never dump the
+full XML inline.
+
+### 6. Screenshot
+
+`appium_screenshot` → save to:
+```
+qa/screens/<screen>/requirements/ui/mobile-<timestamp>.png
+```
+`<timestamp>` = `YYYYMMDD-HHMM` local (e.g. `mobile-20260605-1645.png`).
+
+### 7. Detect discrepancies vs spec
+
+If `spec.md` exists, cross-check `generate_locators` labels against spec sections (fields in spec but
+not on screen, and vice-versa). Report; do **not** auto-edit `spec.md`.
+
+### 8. End the session
+
+`appium_session_management` `action=delete` to free the device. Always clean up.
+
+### 9. Report back
+
+> Captured mobile screen `<appPackage>`:
+> - Reached via: <N nav steps replayed from the Background recipe, or "launcher screen — no nav">
+> - Locators: <N> interactable elements (M with accessibility-id)
+> - Screenshot: `requirements/ui/mobile-<timestamp>.png`
+> - Discrepancies vs spec: <count, or "none">
+> - Discovered nav steps (only if the recipe was empty): <the taps you took, for create-test/add-screen to write into the Background>
+
+Hand back to the calling command.
+
+---
+
+## Cross-platform discovery (`@platform:mobile` — explore one OS, layer the rest)
+
+When the screen is **`@platform:mobile`** (write-once-run-both), discover the **shared** cases first,
+then peel off only what is genuinely OS-specific. You do **not** need to explore both OSes up front —
+Flutter/RN expose the same Semantics on each, so one exploration covers most of it.
+
+1. **Explore whichever OS has a device up** (Android or iOS — symmetric for Flutter). Capture the tree.
+2. **Classify each component** into THREE buckets (not two):
+   - **Shared-exact** → a stable `accessibility id` equal on both OSes (Flutter Semantics → same value on
+     Android `content-desc` AND iOS `name`) → flat `type: accessibility-id` key in `<screen>.feature`.
+   - **Shared-variant** → SAME step/assertion on both OSes but the LOCATOR differs (composite
+     `content-desc` vs `-ios predicate`; partial/dynamic text via `descriptionContains` vs predicate
+     `CONTAINS`; a different attribute) → STILL `<screen>.feature`, with `android:`/`ios:` variant keys in
+     selectors.yaml. **A native locator alone is NOT a reason to split** — default for composite/partial text.
+   - **Sub-feature** → ONLY for genuine SCENARIO divergence: an element on ONE OS only, divergent
+     steps/flow, an OS-exclusive gesture/permission/dialog flow, or a case needing a per-platform
+     `nth`/`scope` (a variant can't diverge those). → `<screen>-android.feature` / `<screen>-ios.feature`.
+3. **Report the classification** so create-test/run-test scaffolds the right thing:
+   - `<screen>.feature`         `@platform:mobile`  ← shared-exact AND shared-variant (the vast majority)
+   - `<screen>-android.feature` `@platform:android` ← ONLY scenario-divergent Android cases
+   - `<screen>-ios.feature`     `@platform:ios`     ← ONLY scenario-divergent iOS cases
+4. **Verifying the other OS needs no second exploration** — just running the shared spec there
+   (`MOBILE_PLATFORM=both`) IS the check. Re-capture on the 2nd OS only for components that fail, and
+   move those into that OS's sub-feature. (Asking devs to add a Semantics label to an unlabeled element
+   converts an OS-specific case back into a shared one — prefer that when feasible.)
+
+## Selector-quality notes (carry into selectors.yaml)
+
+- **Prefer `accessibility id`** (Android `content-desc` / iOS `accessibilityIdentifier`) — most stable.
+- For **Flutter**, the Semantics label surfaces as `content-desc` ⇒ it usually equals the **visible
+  text**, so it is **locale-dependent** ("Good afternoon!", "English"). Keep such values in test-data
+  and use `{{variable}}` + locale overlays (see `sungen-locale`).
+- **Composite nodes**: cards may concatenate child text into one `content-desc` with `\n` → prefer an
+  xpath `contains(@content-desc,'…')` on a distinctive substring.
+- **Duplicate labels** → use `nth`. **Unlabelled controls** (search fields, icon buttons) → fall back
+  to `xpath` / class.
+
+---
+
+## What this skill does NOT do
+
+- Does not run tests or generate `selectors.yaml` (that's `/sungen:run-test` + `sungen-selector-fix-mobile`)
+- Does not generate Gherkin (that's `sungen-tc-generation`) — it may *report* discovered nav steps,
+  but writing them into the Background is create-test/add-screen's job
+- Does not handle login/auth state (mobile auth is a separate concern — deep link / test build)
+- Captures **the feature's target screen** per invocation — reached by replaying the Background
+  navigation recipe (step 4.5), not just the launcher. For a *different* screen, give it its own
+  feature + recipe and re-invoke.
+
+---
+
+## Relationship to other capture skills
+
+- `sungen-capture-figma` / `sungen-capture-local` — design/image sources (platform-agnostic)
+- `sungen-capture-live` — web (Playwright MCP)
+- `sungen-capture-mobile` — this skill, mobile (Appium MCP)
+
+All write to `requirements/ui/` and report back to the caller.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-mobile-gestures.md

@@ -0,0 +1,109 @@
+---
+name: sungen-mobile-gestures
+description: 'Mobile gesture patterns (swipe, long-press, scroll-to, pinch, pull-to-refresh) — Gherkin syntax + Appium MCP mapping. Auto-loaded for @platform:mobile/android/ios screens.'
+user-invocable: false
+---
+
+## Purpose
+
+Document the **mobile-only interactions** that have no web equivalent, so the AI can (a) drive them
+during exploration via Appium MCP and (b) write Gherkin steps for them. These are gestures the web
+patterns (`click`, `hover`, `fill`) don't cover.
+
+> Codegen status (Phase 3): the Appium adapter now **compiles** these gesture steps to WebdriverIO:
+> - **`tap` / `taps`** — synonym for `click` (→ `.click()`); **`double-tap`** → double-click.
+> - **`scroll to [X]`** → `.scrollIntoView()` (shared `scroll-action` template).
+> - **`swipe <dir> on [X]`** → `mobile: swipeGesture`.
+> - **`long-press [X] [for N seconds]`** → `mobile: longClickGesture`.
+> - **`rotate to landscape|portrait`** → `driver.setOrientation(...)`.
+> - **`pull-to-refresh on [X]`** → fast `mobile: swipeGesture` (direction down).
+> - **`pinch-zoom in|out on [X]`** → `mobile: pinchOpenGesture` / `pinchCloseGesture`.
+> - **`send app to background for N seconds`** → `driver.background(N)`.
+> - **`open notification panel`** → `driver.openNotifications()`. **Android-only** — XCUITest has no
+>   notification-shade automation; on iOS the generated step throws loud. Keep such scenarios `@platform:android`.
+> - **`tap top of [X]`** / **`tap [X] at top`** → tap the element's **visible top edge** (`mobile: clickGesture`
+>   at top-centre from the element bounds) instead of its centre — use when the centre is occluded by a
+>   floating bottom bar so a normal centre tap would hit the bar.
+>
+> Still exploration-only (no codegen yet): grant/deny permissions, clipboard set/get, dismiss system
+> dialog — author with the `appium_*` tool calls below; templates land in a later phase.
+>
+> 📜 **`scroll to [X]` — two failure modes seen, with the real cause (measured):**
+> 1. *"Default scrollable element '//android.widget.ScrollView' not found"* — wdio's mobile scroll runs
+>    `$$('//android.widget.ScrollView')` and throws if 0 match. This is **state-dependent**: that node
+>    exists on a list/Home screen but NOT on every screen (tool/tab screens may lack it). If scroll runs
+>    while the app is on a screen without one → this error. Not "the screen can't scroll".
+> 2. **`.scrollIntoView()` is a NO-OP when the target is already inside the scroll viewport** — even if it's
+>    visually **occluded by a floating bottom nav**. scrollIntoView only scrolls things that are *off-screen*;
+>    it has no concept of z-order occlusion (verified: element bounds identical before/after, centre tap
+>    still hit the nav). So scroll **cannot** fix an occluded-by-overlay element → use **`tap top of [X]`**
+>    (visible-point tap), not scroll.
+>
+> `scroll to [X]` is still useful for genuinely **off-screen** items: it uses Android `UiScrollable`
+> (accessibility-id targets) or a `mobile: scrollGesture` fallback.
+>
+> ⚠️ **Flutter note:** `.scrollIntoView()` looks for a native `android.widget.ScrollView`. Flutter
+> (and some RN) scrollables don't expose one, and a screen whose content fits the viewport isn't
+> scrollable at all — there `scroll to` fails or no-ops. For an element merely **occluded by a floating
+> bottom nav** on a non-scrollable screen, neither scroll nor `element.click()` (taps the occluded
+> centre) works; that needs a visible-point/coordinate tap (not yet supported) → tag such a scenario
+> `@manual` for now.
+
+---
+
+## Gesture catalog
+
+All map to the `appium_gesture` MCP tool (action + params). Element-relative gestures pass `elementUUID`
+from `appium_find_element`; screen gestures pass `direction` or coordinates.
+
+| Intent | Proposed Gherkin | `appium_gesture` |
+|---|---|---|
+| Tap | `User tap [Settings]` | `action=tap, elementUUID` |
+| Double-tap | `User double-tap [Photo]` | `action=double_tap, elementUUID` |
+| Long-press | `User long-press [Item] for 2 seconds` | `action=long_press, elementUUID, duration=2000` |
+| Swipe (dismiss/switch/carousel) | `User swipe left on [Card]` | `action=swipe, elementUUID, direction=left` |
+| Pull-to-refresh | `User pull-to-refresh on [Feed]` | `action=swipe, direction=down, speed=fast` |
+| Scroll a list | `User scroll down on [Feed]` | `action=scroll, direction=down` |
+| Scroll until visible | `User scroll to [Footer]` | `action=scroll_to_element, strategy, selector, direction` |
+| Pinch zoom in/out | `User pinch-zoom in on [Map]` | `action=pinch_zoom, elementUUID, scale` (>1 in, <1 out) |
+| System back | `User go back` | `action=back` |
+| Drag & drop | `User drag [A] onto [B]` | `appium_drag_and_drop` (separate tool) |
+
+Other device-level actions (separate MCP tools, future Gherkin):
+- Rotate: `appium_orientation` — `User rotate to landscape`
+- Permission dialog: `appium_mobile_permissions` / `appium_alert` — `User grant [Location] permission`
+- Background/foreground: `appium_app_lifecycle` — `User send app to background for 5 seconds`
+- Clipboard: `appium_mobile_clipboard` — `User paste into [Field]`
+- Notifications: open panel via `appium_mobile_device_control`
+
+---
+
+## Authoring guidance
+
+- **Prefer `scroll_to_element` over blind scrolling.** When a target may be off-screen, use
+  `appium_gesture action=scroll_to_element` (same strategy+selector as the find) rather than repeated
+  `appium_find_element` — it stops when the element appears or the page stops scrolling.
+- **Direction semantics**: `swipe` = dismiss / switch screen / carousel / pull-to-refresh (use
+  `speed=fast`); `scroll` = browse content in a list/feed. Choose by intent, not interchangeably.
+- **Long-press duration**: default 2000ms; pass `duration` for context menus that need a longer hold.
+- **Element vs screen**: pass `elementUUID` to gesture relative to an element; omit it (+ `direction`)
+  to gesture on the whole screen.
+- **Gestures in the navigation recipe**: a `Background:` step like `When User scroll to [X]` or
+  `And User swipe up on [Feed]` is a valid nav hop — `sungen-capture-mobile` replays it to reach the
+  target screen before scanning (see "Background = the navigation recipe" in `sungen-gherkin-syntax`).
+
+---
+
+## Selectors for gestures
+
+Same rules as `sungen-selector-fix-mobile`: `accessibility-id` first, then `id`, platform-native, xpath.
+For `scroll_to_element`, the `strategy`+`selector` you pass are the target you're scrolling toward — keep
+them stable (accessibility-id) so the scroll terminates reliably.
+
+---
+
+## What this skill does NOT do
+
+- Does not implement gesture codegen (templates land in a later phase).
+- Does not replace `sungen-gherkin-syntax` — it supplements it with the mobile-only step vocabulary.
+- Does not cover tap/set-value/assertions (those are the shared Tier-1 patterns already supported).