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

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

@@ -71,12 +71,29 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    Summarize what you found in requirements and present to the user.
 
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **Viewpoint loading discipline:** `sungen-viewpoint` is a **router** — from the page-type (form / list / detail / auth / dashboard …) read **only the matching group file(s)** (e.g. a login screen → group-e-identity; a product list → group-c-data-explore), never all five groups. This keeps the generation context lean. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections.
-5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag.
+5. Generate `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation`. **Partition the work into shards and generate them in parallel** when there are ≥2.
+
+   **5a. Decide the shards.** A shard is one **coverage unit** sized for parallelism — NOT the 5 coarse viewpoint-router groups (a screen loads only 1–2 of those). Use **either**:
+   - one **viewpoint theme** per shard — a `VP-` prefix from the viewpoint overview (`VP-SEC`, `VP-ERROR-EMPTY-STATE`, `VP-CAROUSEL`, …) — preferred when the viewpoint overview is rich (test-2/home had 47 items across many themes); **or**
+   - one **`spec.md` section** per shard (the Mapping Contract walk, Table 1) — preferred when generating from spec.
+   Each shard owns a disjoint `VP-` prefix ⇒ ids never collide. One shard → skip to 5c (no fan-out gain).
+
+   **5b. Parallel fan-out (Claude Code).** Spawn one **`sungen-generator`** sub-agent **per shard** (Task tool, `subagent_type: sungen-generator`) — issue all the Task calls **in a single message** so they run concurrently. Pass each: its shard (theme/section) + viewpoint slice, the **`sungen-discovery` report** (Step 3), only the `spec.md` section(s) it maps to, which one `sungen-viewpoint` group file holds its patterns, the unit (screen/flow) + name + tier, and its fragment paths `.sungen/fragments/<name>/<shard>.{feature,test-data.yaml}`. Each writes a **headerless** fragment + a test-data fragment and returns a compact summary. Small fragments also keep every generator under the output-token cap (the reason the single-pass path writes incrementally).
+
+   **5c. Merge (orchestrator — barrier; only after all generators return).**
+   - Write the final `qa/<screens|flows>/<name>/features/<name>.feature`: one `Feature:` header (+ `@flow` for flows), then concatenate the fragments in **stable order** — spec-section order top-to-bottom (or theme order from the viewpoint overview) — so output is coherent and reproducible across runs.
+   - **Dedup** cross-shard scenarios with near-identical titles (a generic "navigation works" from two shards): keep the earlier shard's, drop the duplicate, note it. No id renumber needed — prefixes are disjoint by construction.
+   - **Union** the test-data fragments into `test-data.yaml`; dedup keys, and **flag** any key two shards define with different values.
+   - Delete `.sungen/fragments/<name>/` once merged.
+   - Guarantees a **coherent** suite (no dup, valid ids, passes `audit`), not a byte-identical one — generation is AI-authored; the determinism asset lives downstream in the Gherkin→`.spec.ts` compiler.
+
+   **5d. Sequential fallback.** Use the single-context incremental path (Step 2: tier-by-tier `Write`/`Edit` batches) when: only **one** shard applies, **Copilot / no sub-agents**, or a constrained setup. Same output, just no speedup. **For flows**: `[Screen:Element]` namespace refs, test-data namespaced by phase, `@flow` tag.
 
 5.5. **Quality gate & repair (harness — always run, do NOT skip).** Follow the `sungen-harness-audit` skill:
    - Run `sungen audit --screen <name>` (Bash) and read `gateStatus` + `findings` (deterministic, structural).
    - **Independent semantic review.** **Claude Code:** spawn the **`sungen-reviewer`** sub-agent (Task tool, `subagent_type: sungen-reviewer`) — it judges what the gate can't (does each scenario's steps PROVE its title/viewpoint, observable Thens, business-critical assertion depth) and returns `VERDICT` + `ISSUES` with concrete fixes. **Merge its NEEDS-REPAIR issues with the audit findings.** (Copilot / no sub-agents: run the same review inline using the `sungen-reviewer` criteria.)
    - Repair **both** the audit findings and the reviewer issues (budget 3 rounds), then re-audit:
+   - **Repair runs single-agent by default** (it edits the one `.feature` — concurrent edits to the same file conflict, and BALANCE/dedup needs whole-suite context). **Exception:** a finding that is purely **additive new coverage** (GATE missing-theme → generate scenarios for an uncovered theme) is just more shards — fan it out as `sungen-generator` sub-agent(s) (new disjoint `VP-` prefix) and merge, exactly like Step 5b. Findings that **edit existing** scenarios (DEPTH/BALANCE/TRACE) stay serial.
    - If the gate FAILs or there are findings, **repair** (budget 3 rounds), then re-audit:
      - **GATE** missing critical theme → generate scenarios for it. If it is **cross-screen** (cart-correctness, product-detail-consistency, filter-result-correctness): **automate it in the flow** (`/sungen:add-flow` if none exists) with observable data assertions (`... with {{value}}`, `see all ... contain {{v}}`) — a single home→target journey runs as one Playwright test. Do **not** write a full `@manual` duplicate of it on the screen (that is a non-running dead copy — `sungen audit` flags it `MANUAL-AUTOMATABLE`), and do **not** fake a shallow single-screen pass. Reserve `@manual` for true judgment / missing-capability, tagged `@manual:Mx`.
      - **DEPTH** → replace `see [X] page/section` on business-critical scenarios with data assertions.

package/src/orchestrator/templates/ai-instructions/claude-skill-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 → `AskUserQuestion`: *"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, `AskUserQuestion`),
+  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/claude-skill-delivery.md

@@ -88,6 +88,33 @@ Multi-locale (no `SUNGEN_ENV`): one **`<LOCALE> Auto`** sheet per locale + a sin
 
 ---
 
+## API delivery — extra worksheet
+
+For **api-kind units** (`qa/api/<area>/`), the `.xlsx` gains a third worksheet **`API detail`** (appended after Auto/Manual). The main BM-2-901-13 Testcases layout is unchanged. The CSV is unchanged (16-column, no extra sheet).
+
+### Required sources (API detail sheet only)
+
+| Source | Path | Created by |
+|--------|------|------------|
+| Endpoint catalog | `qa/api/<area>/api/apis.yaml` | `sungen add --api` or `sungen api import` |
+| Scenario annotations | `qa/api/<area>/features/<feature>.feature` | `create-test` |
+
+### API detail column mapping
+
+| Column | Source |
+|--------|--------|
+| Endpoint | `path` from `apis.yaml` catalog entry |
+| Method | `method` from catalog entry (uppercased) |
+| Auth / Datasource | catalog `datasource` + any `@auth:<role>` tag from scenarios calling this endpoint |
+| Request shape | catalog `body` + `params` fields composed as `body: {…}; params: [a, b]` |
+| Expected-status matrix | `@cases:<dataset>` label for data-driven scenarios; catalog `expect.status` as fallback |
+| Flow steps | Ordered `@api:<name>` call chain from multi-call scenarios (e.g. `register → count_users`) |
+| Concurrency invariant | `@concurrent:<N>` + `@query:<oracle>` from concurrent scenarios (e.g. `ok_count=2; @query user_count`) |
+
+**Sources are catalog + annotations only** — Field Metadata (FM) is not required for this sheet.
+
+---
+
 ## Excluded from CSV
 
 - `@steps:<name>` **base** scenarios — these are setup-only, inlined into `@extend:...` scenarios at compile time

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

@@ -214,6 +214,8 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@cases:dataset` | Data-driven: run the scenario once per row of the `dataset` LIST in test-data → one `test()` per row |
 | `@query:name` | Database: run the named query from `database/queries.yaml` (precondition) and bind its rows to `{{name}}`; assert with `expect {{name.count}} …` + path access. Override params `@query:name(p={{v}})`. Repeatable. (Optional Data Driver — see Database verification above) |
 | `@api:name` | API: run the named request from `api/apis.yaml` (precondition) and bind the response to `{{name}}`; assert with `expect {{name.status}} …` + path access (`{{name.body.<path>}}`). Override params `@api:name(p={{v}})`. Repeatable. (Optional API Driver) |
+| `@concurrent:N` | API idempotency: fire the bound `@api` request N times in parallel, then bind aggregates on the `@api` name — `{{name.ok_count}}` (2xx count) and `{{name.status_counts}}` (status→count map). Assert the exactly-once invariant (`expect {{name.ok_count}} is 1`); pair with `@query` as a DB oracle. Tag order = run order: `@api` (mutate) before `@query` (verify). (Optional API Driver) |
+| `@hybrid` | One unit, two capabilities: a signed-in browser session (UI) authorizes the `@api` call — the API request reuses the UI `storageState`. (Optional API + UI Drivers) |
 
 ### Data-driven scenarios (`@cases`)
 

package/src/orchestrator/templates/ai-instructions/claude-skill-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).