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

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-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/dist/orchestrator/templates/ai-instructions/github-skill-sungen-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/dist/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).

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-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**: *"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/dist/orchestrator/templates/ai-instructions/github-skill-sungen-tc-generation.md

@@ -9,6 +9,8 @@ user-invocable: false
 - **Write incrementally — never emit the whole suite in one response.** Build the `.feature` in batches via successive `Write`/`Edit` (≈10–15 scenarios per call). For **Full coverage**, write tier-by-tier: `Write` Tier 1 → `Edit` append Tier 2 → `Edit` append Tier 3.
   → One huge `Write` can exceed the model's output-token cap → `API Error: Claude's response exceeded the N output token maximum`. Single-pass full coverage only fits when `CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`; otherwise batch. Batching also lets the audit/reviewer run per batch — higher quality.
 
+- **Generate group-by-group (sequential here).** Copilot has no sub-agents, so generate one viewpoint group/theme at a time, tier-by-tier, keeping each `VP-` theme in its own id prefix. (The Claude Code variant fans these out as parallel `sungen-generator` shards and merges — same output shape, just no speedup. Keep each theme self-contained so it would merge cleanly either way.)
+
 - `spec_figma.md` exists → read file only, **NEVER** call `mcp__figma__*`
   → PAT auth flow already done by `sungen-capture` (mode figma-pat); re-calling fails or duplicates work.
 

package/dist/orchestrator/templates/env.appium.example

@@ -0,0 +1,25 @@
+# .env.appium — env for `npm run test:mobile` (loaded by wdio.conf.ts). Copy to `.env.appium`
+# (gitignored) and fill. Shell exports win over this file. Most settings auto-detect / default in
+# wdio.conf — only the lines marked REQUIRED must be set. Full guide: docs → Mobile → Appium Setup.
+
+# ════════════ Android (default platform) ════════════
+# REQUIRED — local SDK + JDK (the uiautomator2 driver reads these). SDK_ROOT = same path as HOME:
+ANDROID_HOME=/Users/<you>/Library/Android/sdk
+ANDROID_SDK_ROOT=/Users/<you>/Library/Android/sdk
+JAVA_HOME=/opt/homebrew/opt/openjdk@21
+# App + device (override the defaults from `sungen init`):
+# APP_PACKAGE=com.example.app        # the app to test (launch activity is auto-detected)
+# ANDROID_UDID=<serial>              # a REAL phone (`adb devices`); emulator default = emulator-5554
+# APP_APK=/abs/path/app.apk          # alternative: install + launch from an .apk
+
+# ════════════ iOS — Simulator (quick path, no Apple account) ════════════
+# Set MOBILE_PLATFORM=ios and boot a sim — udid/version/name auto-detect.
+# IOS_APP=/abs/path/MyApp.app        # optional: install a Simulator .app build first
+
+# ════════════ iOS — real iPhone (only for a physical device) ════════════
+# A real iPhone must code-sign Appium's WebDriverAgent → IOS_TEAM_ID is REQUIRED (it signs WDA, not
+# your app — needed even when the app is already installed). Device prep + how-to: Appium Setup §3C.
+# MOBILE_PLATFORM=ios                # REQUIRED — turn iOS on (or 'both' = Android + iOS)
+# IOS_UDID=<device-udid>             # REQUIRED — physical device (`xcrun xctrace list devices`), not a sim
+# IOS_BUNDLE_ID=<ios bundle id>      # REQUIRED — the iOS bundle (⚠ NOT the Android package)
+# IOS_TEAM_ID=<Apple Team ID>        # REQUIRED — 10-char id (Xcode → Settings → Accounts)

package/dist/orchestrator/templates/specs-api.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Join a datasource base URL with a catalog path. Concatenate rather than rely on Playwright's
+ * baseURL resolution: an absolute path (`/user/1`) resolves against the base ORIGIN and would drop
+ * a base path component (`/api/v3`). Most APIs are mounted under such a prefix, so the full URL must
+ * be built explicitly.
+ */
+export declare function joinApiUrl(base: string, urlPath: string): string;
 declare class ApiClient {
     private configs;
     private cfg;

package/dist/orchestrator/templates/specs-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specs-api.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-api.ts"],"names":[],"mappings":"AAmDA,cAAM,SAAS;IACb,OAAO,CAAC,OAAO,CAA8C;IAE7D,OAAO,CAAC,GAAG;IAWX;;;;;OAKG;IACG,IAAI,CACR,KAAK,EAAE,MAAM,EACb,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EACtJ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EAChC,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IA6CvF;;;;;;OAMG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EACtJ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EAChC,CAAC,SAAI,EACL,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC;QACT,SAAS,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,GAAG,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAC,CAAC;QAC9F,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CAYH;AAED,eAAO,MAAM,GAAG,WAAkB,CAAC"}
+{"version":3,"file":"specs-api.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-api.ts"],"names":[],"mappings":"AAmDA;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED,cAAM,SAAS;IACb,OAAO,CAAC,OAAO,CAA8C;IAE7D,OAAO,CAAC,GAAG;IAWX;;;;;OAKG;IACG,IAAI,CACR,KAAK,EAAE,MAAM,EACb,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EACtJ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EAChC,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IA6CvF;;;;;;OAMG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,EACb,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EACtJ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EAChC,CAAC,SAAI,EACL,IAAI,GAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC;QACT,SAAS,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,OAAO,CAAC;YAAC,IAAI,EAAE,GAAG,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;SAAE,CAAC,CAAC;QAC9F,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CAYH;AAED,eAAO,MAAM,GAAG,WAAkB,CAAC"}

package/dist/orchestrator/templates/specs-api.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.api = void 0;
+exports.joinApiUrl = joinApiUrl;
 /* eslint-disable */
 /**
  * Sungen API Driver — runtime helper (auto-generated into specs/api.ts).
@@ -74,6 +75,16 @@ function loadConfig() {
 function substitute(text, params) {
     return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => encodeURIComponent(String(params[p] ?? '')));
 }
+/**
+ * Join a datasource base URL with a catalog path. Concatenate rather than rely on Playwright's
+ * baseURL resolution: an absolute path (`/user/1`) resolves against the base ORIGIN and would drop
+ * a base path component (`/api/v3`). Most APIs are mounted under such a prefix, so the full URL must
+ * be built explicitly.
+ */
+function joinApiUrl(base, urlPath) {
+    const b = base.replace(/\/$/, '');
+    return urlPath.startsWith('/') ? b + urlPath : `${b}/${urlPath}`;
+}
 class ApiClient {
     constructor() {
         this.configs = null;
@@ -127,13 +138,13 @@ class ApiClient {
         // `storageState` (the @auth role's saved session) so the request shares the browser's
         // authenticated cookies. Disposed per call so no request context lingers and hangs the process.
         const ctx = await test_1.request.newContext({
-            baseURL: base,
             extraHTTPHeaders: headers,
             timeout: conf.timeout_ms ?? 15000,
             ...(opts.storageState ? { storageState: opts.storageState } : {}),
         });
         try {
-            const res = await ctx.fetch(urlPath, { method: req.method, ...bodyOpt });
+            // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
+            const res = await ctx.fetch(joinApiUrl(base, urlPath), { method: req.method, ...bodyOpt });
             const text = await res.text();
             let parsed = text;
             try {

package/dist/orchestrator/templates/specs-api.js.map

@@ -1 +1 @@
-{"version":3,"file":"specs-api.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"specs-api.js","sourceRoot":"","sources":["../../../src/orchestrator/templates/specs-api.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/templates/specs-api.ts

@@ -49,6 +49,17 @@ function substitute(text: string, params: Record<string, any>): string {
   return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => encodeURIComponent(String(params[p] ?? '')));
 }
 
+/**
+ * Join a datasource base URL with a catalog path. Concatenate rather than rely on Playwright's
+ * baseURL resolution: an absolute path (`/user/1`) resolves against the base ORIGIN and would drop
+ * a base path component (`/api/v3`). Most APIs are mounted under such a prefix, so the full URL must
+ * be built explicitly.
+ */
+export function joinApiUrl(base: string, urlPath: string): string {
+  const b = base.replace(/\/$/, '');
+  return urlPath.startsWith('/') ? b + urlPath : `${b}/${urlPath}`;
+}
+
 class ApiClient {
   private configs: Record<string, ApiDataSource> | null = null;
 
@@ -103,13 +114,13 @@ class ApiClient {
     // `storageState` (the @auth role's saved session) so the request shares the browser's
     // authenticated cookies. Disposed per call so no request context lingers and hangs the process.
     const ctx: APIRequestContext = await request.newContext({
-      baseURL: base,
       extraHTTPHeaders: headers,
       timeout: conf.timeout_ms ?? 15000,
       ...(opts.storageState ? { storageState: opts.storageState } : {}),
     });
     try {
-      const res = await ctx.fetch(urlPath, { method: req.method, ...bodyOpt });
+      // Full URL (not a baseURL-relative path) so a base path component like /api/v3 is preserved.
+      const res = await ctx.fetch(joinApiUrl(base, urlPath), { method: req.method, ...bodyOpt });
       const text = await res.text();
       let parsed: any = text;
       try { parsed = text ? JSON.parse(text) : null; } catch { /* non-JSON → keep text */ }