@sun-asterisk/sungen 2.6.12 → 2.6.15

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

@@ -0,0 +1,316 @@
+---
+name: sungen-locale
+description: 'Bootstrap i18n for a screen/flow — audit hardcoded selector text, detect locale-switch mechanism via live Playwright, generate test-data overlay file. Auto-loaded by /sungen:locale command.'
+user-invocable: false
+---
+
+## Goal
+
+Take a screen/flow whose `selectors/*.yaml` and `.feature` files were authored against the default locale (usually Vietnamese) and prepare it to run against a second locale. Output:
+
+1. `selectors/<feature>.yaml` — hardcoded `name`/`value` replaced with `{{var}}`
+2. `test-data/<feature>.yaml` — base locale, complete with all new keys
+3. `test-data/<feature>.<locale>.yaml` — overlay with only the keys that change
+4. (Optional) `selectors/<feature>.yaml` Pages block updated when locale uses URL prefix or query param
+
+After this skill finishes, `sungen run-test <name> --env <locale>` Just Works.
+
+## Run mode — Live (preferred) vs Offline (fallback)
+
+Pick mode **once at start**, based on whether MCP Playwright can reach the page.
+
+```
+Try: browser_navigate(baseURL)
+  → succeeds + page renders content → LIVE MODE (all 6 phases)
+  → fails (auth blocked, network down, app broken) → OFFLINE MODE
+    (audit + scaffold template + ask user to fill, skip detection phases)
+```
+
+**Live mode is the value-add** — it auto-detects locale switch mechanism and auto-fills translations. Offline mode just makes the file structure right; user fills in text manually.
+
+Announce which mode is being used before Phase 1.
+
+## Phase 1 — Audit selectors (always, no MCP)
+
+For each `.feature` file under the screen, read the matching `selectors/<feature>.yaml`. List every entry whose `name` or `value` field contains literal text WITHOUT `{{…}}` AND is not a CSS/href selector.
+
+Classify each candidate:
+- **`name` field of `role`-type selector** → very likely locale-dependent
+- **`value` field of `text`-type selector** → very likely locale-dependent
+- **`value` of `locator`-type selector** that contains `:has-text("…")` → check if the text is in target language
+- **`value` of `page`-type selector** → URL — handled separately in Phase 3
+- **CSS / href / attribute selectors** (e.g. `a[href="/awards"]`) → skip, locale-invariant
+
+Print the candidate list as a table:
+
+```
+selector key       | field | hardcoded value           | classification
+-------------------+-------+---------------------------+------------------
+nav about          | name  | Giới thiệu SAA 2025       | locale-dependent
+nav awards         | name  | Thông tin giải thưởng     | locale-dependent
+event date         | name  | 26/12/2025                | maybe (date format)
+nav kudos          | name  | Sun* Kudos                | brand — skip
+```
+
+If there are zero candidates and no `{{var}}` either, the screen has no localizable text → tell user and stop.
+
+## Phase 2 — Capture base locale (LIVE only)
+
+1. Read `playwright.config.ts` for `baseURL`. Read `Path:` from `.feature` for the entry-point path.
+2. If the screen has `@auth:<role>` tags, load `specs/.auth/<role>.json` via `browser_set_storage_state` first.
+3. `browser_navigate(baseURL + entryPath)` then `browser_wait_for` something stable.
+4. Capture:
+   - `browser_snapshot()` — DOM accessibility tree
+   - `browser_evaluate(() => location.href)` — full URL
+   - `browser_evaluate(() => ({ localStorage: {...localStorage}, cookies: document.cookie }))` — storage state hash
+5. For each candidate from Phase 1: verify the hardcoded text actually appears on the page (string contains check against snapshot text). Drop candidates that don't appear (probably stale selectors or false positives).
+
+Save state to memory as `baseLocale = { url, snapshot, storage }`.
+
+If page redirects to `/login` (auth blocker) → stop. Print: *"Auth blocked — cannot capture live page. Fall back to OFFLINE mode by re-running once auth works, or pick `Offline-only` next time."*
+
+## Phase 3 — Switch locale (LIVE only) — detect mechanism + storage delta
+
+Goal: identify (a) HOW to switch the app to the target locale, and (b) WHAT app-side storage state ends up holding the locale preference so a fresh BrowserContext can be primed identically without driving the UI.
+
+Before triggering the switch, capture full storage baseline:
+
+```js
+const before = await browser_evaluate(() => ({
+  sessionStorage: { ...sessionStorage },
+  localStorage:   { ...localStorage },
+  cookies:        document.cookie,
+  url:            location.href,
+}));
+```
+
+Then try mechanisms in order. First one that produces visibly different text wins. For EACH attempt, capture `after` state and diff against `before`.
+
+**3a. URL prefix**
+- `browser_navigate(baseURL + '/' + locale + entryPath)` (e.g. `https://saa-2025.../en/`)
+- Wait, snapshot
+- Compare text content with baseLocale snapshot for a known-changed element
+- If text differs and page didn't 404 → **URL prefix mechanism**. Save `localePrefix = '/' + locale`.
+
+**3b. Query param** (only if 3a failed)
+- `browser_navigate(baseURL + entryPath + '?lang=' + locale)` (also try `?locale=`, `?lng=`, `?l=`, `?language=`)
+- Same diff check
+- If text differs → **Query param mechanism**. Save `localeQuery = '?lang=' + locale` (or whichever variant worked).
+
+**3c. Language switcher UI** (only if 3a + 3b failed)
+- Look in base-locale snapshot for buttons/links matching: `'Select language'`, `'Language'`, `'言語'`, `'Ngôn ngữ'`, role=combobox
+- If found, ask user: *"Detected possible language switcher: [X]. Click it and proceed?"*
+- On confirm: `browser_click` the switcher, then `browser_click` the locale option
+- Verify text changed
+- If yes → **UI switcher mechanism**. Save selector + option details.
+
+**3d. None detected**
+- AskUserQuestion: *"Couldn't auto-detect locale switching. Either (a) demo it for me in browser then I'll snapshot, (b) provide locale URL manually, (c) skip — assume URL prefix `/<locale>`."*
+
+### Phase 3.5 — Storage diff (always run after Phase 3 succeeds)
+
+After locale text confirmed switched, capture `after` state and diff:
+
+```js
+const after = await browser_evaluate(() => ({
+  sessionStorage: { ...sessionStorage },
+  localStorage:   { ...localStorage },
+  cookies:        document.cookie,
+  url:            location.href,
+}));
+
+// Diff each storage area:
+const sessionDiff = diffEntries(before.sessionStorage, after.sessionStorage);
+const localDiff   = diffEntries(before.localStorage,   after.localStorage);
+const cookieDiff  = diffCookies(before.cookies, after.cookies);
+```
+
+**Filter noise** — only keep entries where:
+- Key name contains `lang|locale|language|i18n|intl` (case-insensitive), OR
+- Value matches a locale code pattern: `^[a-z]{2}(-[A-Z]{2})?$` or matches the target locale code exactly
+
+Drop known noise:
+- Auth tokens: `sb-*`, `*-token`, `*-jwt`, `*-session-id`
+- Analytics: `_ga*`, `_gid`, `_fbp`
+- App state: `csrf*`, `last-*`, `visit-*`
+
+**Auto-confidence scoring** per remaining entry:
+- High confidence: key name contains locale-related word AND value is a locale code matching target → KEEP, no user prompt
+- Medium: only one signal matches → present to user for confirmation
+- Low: neither matches but key changed → present to user, default to skip
+
+### Phase 3.6 — Verification (always run after Phase 3.5)
+
+For each high/medium-confidence storage entry, verify by replaying in a FRESH context:
+
+```js
+// 1. Capture current page state (have JWT in memory) — note: can't replay JWT separately
+// 2. Open new browser_navigate to baseURL but pre-set the detected key via addInitScript
+// 3. Snapshot new page and confirm a known target-locale string appears
+
+// Pseudo-code — real impl uses Playwright MCP `browser_evaluate` with init pattern
+```
+
+Actually since MCP browser sessions don't expose `addInitScript` directly, use a softer verification:
+- Manually set the candidate key via `browser_evaluate(() => sessionStorage.setItem('key', 'value'))`
+- Hard reload the page: `browser_navigate(baseURL)` to force re-init
+- Snapshot, look for known target-locale text
+- Caveat: hard reload kills any in-memory JWT — auth blocker amplifies failure surface. Skip verification if the screen has `@auth:*` tags and the staging app has known JWT-persistence issues.
+
+If verification fails / can't run → drop confidence by one tier, ask user.
+
+Save mechanism + verified storage delta to memory for use in Phase 6.
+
+## Phase 4 — Diff base ↔ target (LIVE only)
+
+For each candidate from Phase 1 that survived Phase 2:
+- Find the SAME element in the target-locale snapshot (match by `role`+position, by `aria-label` if available, by neighbor structure)
+- Extract its text → `targetText`
+- Pair: `(selectorKey, hardcoded baseText, observed targetText)`
+
+If matching fails for a candidate → mark as "needs manual" — flag for user input rather than skip.
+
+Result: list of triples `{ selectorKey, baseText, targetText, confidence }`.
+
+## Phase 5 — Confirm + edit (always)
+
+Present the proposal table:
+
+```
+selector key       | base text                | target text          | proposed var     | apply?
+-------------------+--------------------------+----------------------+------------------+-------
+nav about          | Giới thiệu SAA 2025      | About SAA 2025       | nav_about        | [✓]
+nav awards         | Thông tin giải thưởng    | Awards Info          | nav_awards       | [✓]
+event location     | Au Co Arts Centre, Hanoi | Au Co Arts Centre…   | event_location   | (already has {{}})
+nav kudos          | Sun* Kudos               | Sun* Kudos           | —                | [skip — same]
+event date         | 26/12/2025               | 26/12/2025           | —                | [skip — same]
+```
+
+Propose **var names** by snake_casing the selector key. Avoid collisions with existing test-data keys.
+
+Auto-skip rows where `baseText === targetText` (brand names, dates that don't change between locales).
+
+Ask user via AskUserQuestion: *"Review the table above. Confirm to apply / edit individual rows / re-run capture / cancel."*
+
+If user wants to edit a row → fall through to a per-row prompt asking for `var name` or `targetText` correction.
+
+In OFFLINE mode this phase is the same table but `target text` column is blank — user fills via subsequent prompts or by editing the overlay file after the skill finishes.
+
+## Phase 6 — Apply changes (always, after confirmation)
+
+For each confirmed row:
+
+**6a. Update `selectors/<feature>.yaml`**
+
+Replace `name: '<baseText>'` with `name: '{{<varName>}}'`. Preserve quoting style.
+
+**6b. Update `test-data/<feature>.yaml`** (base locale, complete dictionary)
+
+Append new keys at the end, grouped under a `# === i18n: <screen> ===` comment. Example:
+
+```yaml
+# === i18n: home ===
+nav_about: 'Giới thiệu SAA 2025'
+nav_awards: 'Thông tin giải thưởng'
+```
+
+**6c. Create `test-data/<feature>.<locale>.yaml`** (overlay, only diffs)
+
+```yaml
+# home — <locale> overlay. Only keys that change vs base.
+# Run with: SUNGEN_ENV=<locale> npx playwright test ...
+
+nav_about: 'About SAA 2025'
+nav_awards: 'Awards Info'
+```
+
+**6d. (URL/query mechanism only) Update Pages selectors**
+
+If Phase 3 detected URL prefix:
+
+```yaml
+# selectors/<feature>.yaml — Pages block becomes locale-aware
+home:
+  type: 'page'
+  value: '{{base_path}}/'
+awards:
+  type: 'page'
+  value: '{{base_path}}/awards'
+```
+
+And add to test-data:
+```yaml
+# test-data/<feature>.yaml (base)
+base_path: ''
+
+# test-data/<feature>.<locale>.yaml (overlay)
+base_path: '/en'
+```
+
+If Phase 3 detected query param: similar but with `query_suffix: ''` / `query_suffix: '?lang=en'` appended to each page value.
+
+If Phase 3 detected UI switcher: do NOT modify Pages. Instead, write the storage delta from Phase 3.5 into `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) (see 6f below).
+
+**6f. Storage injection config — `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`)**
+
+Always write `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) with the verified storage delta from Phase 3.5/3.6. This file is consumed by `specs/locale-fixture.ts` (auto-generated alongside `specs/base.ts`) — the fixture wraps Playwright's context, calls `addInitScript` to seed sessionStorage / localStorage, and `addCookies` for any cookies, BEFORE the first page navigation. Without this file, `SUNGEN_ENV=<locale>` only swaps test-data overlay — the browser would still boot in base locale.
+
+Schema (only include areas that actually changed):
+
+```json
+{
+  "$schema": "sungen-locale-config-v1",
+  "sessionStorage": {
+    "saa-language-preference": "${SUNGEN_ENV}"
+  },
+  "localStorage": {},
+  "cookies": [],
+  "notes": "Detected by /sungen:locale on YYYY-MM-DD. App persists locale in sessionStorage; initial trigger uses ?language=<code> query param."
+}
+```
+
+Notes on the schema:
+- Use the literal placeholder `"${SUNGEN_ENV}"` (or `"{{SUNGEN_ENV}}"`) when the stored value equals the locale code itself. The fixture substitutes `process.env.SUNGEN_ENV` at runtime, so the same file works for `en`, `ja`, etc.
+- Use a hardcoded literal (e.g. `"en_US"`) when the stored value is fixed regardless of which locale runs.
+- `cookies[]` entries need either `domain` or `url`. Other fields (`path`, `httpOnly`, `secure`, `sameSite`) are optional and pass through to `context.addCookies()`.
+- Do not commit auth tokens / session IDs into this file even if they showed up in the Phase 3.5 diff — they are noise. The skill's Phase 3.5 filter must drop them; if one slipped through, edit it out before applying.
+- `notes` is free-form, informational; the fixture ignores it.
+
+Multi-locale projects: the same `locale-config.json` works for every locale because the value templating uses `${SUNGEN_ENV}`. No per-locale file needed.
+
+The file lives at `specs/generated/locale-config.json` (sibling of `specs/generated/base.ts` + `specs/generated/locale-fixture.ts`) (sibling of `specs/base.ts`). If a different output directory is used, mirror the existing `specs/base.ts` location.
+
+**6e. Compile**
+
+Run `sungen generate --screen <name>` (or `--flow`) and report any compile errors back to the user. The selectors changed so compile must succeed before run-test.
+
+## Phase 7 — Hand off
+
+Print summary:
+- N selectors converted to `{{var}}`
+- M base keys added to `test-data/<feature>.yaml`
+- K overlay keys written to `test-data/<feature>.<locale>.yaml`
+- Pages selectors updated: yes/no
+- Locale-switching mechanism: URL prefix `/en` / query `?lang=en` / UI switcher / manual
+
+Suggest:
+
+```
+/sungen:run-test <name> --env <locale>
+```
+
+## Multi-feature screens
+
+If the screen has multiple `.feature` files (e.g. `home.feature` + `home-modal.feature`), repeat Phase 1 → Phase 6 for each feature file with its own selectors + test-data pair. Phase 2 + 3 (live capture + locale switch detection) run **once per screen** — the mechanism is the same. Phase 4 (text diff) runs per feature because each has its own scope of UI.
+
+## What NOT to do
+
+- Do not edit `.feature` files. The i18n shape is already correct there (`{{var}}` was the convention from the start). Only selectors + test-data need surgery.
+- Do not write a separate selectors file per locale (`home.en.yaml`). One selectors file with `{{var}}` works across all locales — that's the whole point.
+- Do not delete keys from the base `test-data/<feature>.yaml`. Always append. Existing tests rely on base values being complete.
+- Do not run tests in this skill. Hand off to `/sungen:run-test` for execution.
+- Do not commit. Hand off to user.
+
+## Memory link
+
+Related: [[saa-auth-blocker]] — Live mode will not work on SAA staging while the upstream Supabase `persistSession: false` issue is open. Default to Offline mode on SAA until that ships.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-add-screen.md

@@ -1,41 +1,59 @@
 ---
 name: sungen-add-screen
-description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can auto-capture a live-page screenshot via Playwright MCP'
-argument-hint: '[screen-name] [url-path] [--figma <url>]'
+description: 'Add a new Sungen screen or a sub-feature to an existing one — scaffolds directories, helps fill spec.md, and can auto-capture a live-page screenshot via Playwright MCP'
+argument-hint: '[screen-name] [url-path] [--feature <name>] [--figma <url>]'
 agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
 ---
 
 **Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
 Optionally include a Figma URL: `/sungen-add-screen login /login --figma https://www.figma.com/design/...`.
+To add a sub-feature file to an existing screen: `/sungen-add-screen awards --feature modal`.
 
-You are adding a new Sungen screen for test generation.
+You are adding a new Sungen screen for test generation, or extending an existing screen with an additional `.feature` file (sub-feature).
 
 ## Parameters
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
-- **path** — ${input:path:URL path (e.g., /login, /dashboard)} — optional when --figma is provided
-- **--figma \<url\>** — Figma share URL (optional)
-- **--refresh** — bypass Figma cache and re-fetch (optional, use with --figma)
-- **--scale \<n\>** — PNG export scale factor, default 2 (optional)
-- **--hi-res** — export at 4× scale, shorthand for --scale 4 (optional)
+- **path** — ${input:path:URL path (e.g., /login, /dashboard)} — optional when --figma is provided or when adding a sub-feature
+- **`--feature <name>`** — sub-feature name to add to an existing screen (e.g., `modal`, `filter`, `create-flow`). Creates `<screen>-<feature>.feature` + matching `selectors/<screen>-<feature>.yaml` + `test-data/<screen>-<feature>.yaml` without touching the screen's other files. Use this when one screen has multiple `.feature` files.
+- **`--figma <url>`** — Figma share URL (optional)
+- **`--refresh`** — bypass Figma cache and re-fetch (optional, use with --figma)
+- **`--scale <n>`** — PNG export scale factor, default 2 (optional)
+- **`--hi-res`** — export at 4× scale, shorthand for --scale 4 (optional)
+
+**Mode detection** — before invoking the CLI, check whether `qa/screens/<screen>/` already exists:
+- Screen does NOT exist → fresh screen creation (need `--path` unless `--figma` provided)
+- Screen exists AND `--feature <name>` provided → sub-feature mode (skip spec.md, only generate the 3 new files)
+- Screen exists AND no `--feature` → ask the user whether they meant to add a sub-feature (offer `--feature <suggested-name>`) or refresh visuals only (with `--figma`)
 
 ## Steps
 
-### 1. Scaffold the screen
+### 1. Scaffold the screen (or sub-feature)
 
-**Standard path (no --figma):**
+**Standard path (no --figma, no --feature):**
 
 Run with #tool:terminal:
 ```bash
 sungen add --screen ${input:screen} --path ${input:path}
 ```
 
+**Sub-feature mode (`--feature <name>` provided):**
+
+Run with #tool:terminal:
+```bash
+sungen add --screen ${input:screen} --feature <name> [--path ${input:path}]
+# Generates qa/screens/${input:screen}/{features,selectors,test-data}/${input:screen}-<name>.{feature,yaml,yaml}
+# Existing screen files (spec.md, awards.feature, …) are untouched.
+# --path is optional — defaults to /${input:screen} when omitted.
+```
+
 **Figma branch (when --figma \<url\> is provided):**
 
 Run with #tool:terminal:
 ```bash
-sungen add --screen ${input:screen} --figma <figma-url> [--path ${input:path}] [--refresh] [--scale <n>]
+sungen add --screen ${input:screen} --figma <figma-url> [--path ${input:path}] [--feature <name>] [--refresh] [--scale <n>]
+# --feature can be combined with --figma when the new sub-feature has its own Figma frame.
 ```
 
 This CLI command automatically:
@@ -82,13 +100,32 @@ Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/
 
 ### 3. Fill spec.md
 
-Ask: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
+**Skip this step when `--feature` was used** — the screen's existing `spec.md` is reused for all sub-features; only suggest the user append a new section for the sub-feature if useful (e.g. `## Modal — Confirm Withdrawal`).
+
+For fresh screen creation, ask: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
 
 If yes → open `qa/screens/${input:screen}/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Reference the captured visuals from Step 2 to suggest field names, form elements, and UI states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
 
 ### 4. Next steps
 
-Tell the user what was created and offer next steps:
+Tell the user what was created. When `--feature` was used, list the 3 new files explicitly (`features/${input:screen}-<name>.feature`, `selectors/${input:screen}-<name>.yaml`, `test-data/${input:screen}-<name>.yaml`) and remind that `/sungen-create-test` currently operates at the screen level — it will see both the parent feature and the new sub-feature and ask which one to update.
+
+Then offer next steps:
 
 - **`/sungen-create-test ${input:screen}`** — Create test cases from requirements/designs (Recommended)
 - **Done for now** — I'll come back later
+
+## CLI Reference
+
+```
+sungen add --screen <name>
+  [-p, --path <path>]            URL route (e.g., /awards). Required for capture; defaults to /<screen> when omitted.
+  [-f, --feature <name>]         Add a sub-feature .feature file to an existing screen.
+                                 Output filename = <screen>-<feature>.{feature,yaml,yaml}.
+  [-c, --capture]                Auto-capture a live screenshot to requirements/ui/ (needs --path).
+  [-d, --description <text>]     Screen description (used in spec.md stub).
+  [--figma <url>]                Figma share URL — generates spec_figma.md + ui/*.png.
+  [--refresh]                    Bypass Figma cache (use with --figma).
+  [--scale <n>]                  PNG export scale (default 2).
+  [--hi-res]                     Shorthand for --scale 4.
+```

package/src/orchestrator/templates/ai-instructions/copilot-cmd-dashboard.md

@@ -19,8 +19,11 @@ Parse **screens** from `$ARGUMENTS`:
 
 ### 1. Invoke the CLI
 
+Prefer the local `./bin/sungen.js` when it exists (sungen monorepo dev). Fall back to `npx sungen` for downstream projects.
+
 ```bash
-npx sungen dashboard <screens>
+# Local-first dispatcher — works in both monorepo and consumer projects:
+[ -x ./bin/sungen.js ] && ./bin/sungen.js dashboard <screens> || npx sungen dashboard <screens>
 ```
 
 - No args → all screens + flows.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-delivery.md

@@ -1,7 +1,7 @@
 ---
 name: sungen-delivery
 description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
-argument-hint: "[name...] (omit for all screens and flows)"
+argument-hint: "[name...] [--env <locale>] (omit names for all targets; --env for locale-specific export)"
 tools: [read, execute, edit, vscode/askQuestions]
 ---
 
@@ -11,9 +11,11 @@ You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic
 
 ## Parameters
 
-Parse **names** from `$ARGUMENTS`:
-- If empty → CLI will process **all** screens in `qa/screens/` and flows in `qa/flows/`
-- If provided → pass them through to the CLI (auto-detects screen vs flow per name)
+Parse from `$ARGUMENTS`:
+- **names** — zero or more screen/flow names. Empty → CLI processes all targets in `qa/screens/` + `qa/flows/`.
+- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the run so the CLI merges `<name>.<locale>.yaml` over the base test-data and writes `<name>-testcases.<locale>.csv` / `.xlsx`. Accept `--locale <locale>` as an alias.
+
+If `--env` is passed but no value follows, ask the user which locale to use.
 
 ## Steps
 
@@ -22,18 +24,22 @@ Parse **names** from `$ARGUMENTS`:
 Run via Bash (single command, no extra parsing):
 
 ```bash
-npx sungen delivery <names>
+# No env — local-first dispatcher:
+[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <names> || npx sungen delivery <names>
+
+# Locale-specific:
+[ -x ./bin/sungen.js ] && SUNGEN_ENV=<locale> ./bin/sungen.js delivery <names> || SUNGEN_ENV=<locale> npx sungen delivery <names>
 ```
 
-- If no args → just run `npx sungen delivery` (exports all screens + flows)
-- If args → pass them as positional arguments (auto-detects screen vs flow)
+- If no name args → omit `<names>` (CLI processes all targets).
+- If `--env <locale>` was provided → prepend `SUNGEN_ENV=<locale>` to the command. Do NOT pass `--env` to the CLI itself — it's not a CLI flag, only a slash-command convenience.
 
 The CLI handles:
 - Scope detection (all screens + flows vs specific names)
 - Auto-detect: `qa/flows/<name>/` → flow, `qa/screens/<name>/` → screen
 - Pre-flight source checks with colorful output
-- Parsing `.feature`, `.spec.ts`, `test-data.yaml`, `test-results/results.json`
-- Generating CSV at `qa/deliverables/<name>-testcases.csv`
+- Parsing `.feature`, `.spec.ts`, `test-data.yaml` (+ `<name>.<env>.yaml` overlay when `SUNGEN_ENV` is set), and per-target `<name>-test-result[.<env>].json`
+- Generating CSV/XLSX at `qa/deliverables/<name>-testcases[.<env>].csv` / `.xlsx`
 - Printing summary table
 
 ### 2. Handle pre-flight failures (if CLI exits non-zero)
@@ -69,4 +75,9 @@ Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`
 sungen delivery [names...]
   [--skip-preflight]          Skip pre-flight checks (not recommended)
   [--continue-on-missing]     Skip targets with blocking misses
+
+# Locale-aware export (env var, not a CLI flag):
+SUNGEN_ENV=<locale> sungen delivery [names...]
+  → reads <name>.<locale>.yaml overlay, picks <name>-test-result.<locale>.json,
+    writes <name>-testcases.<locale>.csv / .xlsx
 ```

package/src/orchestrator/templates/ai-instructions/copilot-cmd-locale.md

@@ -0,0 +1,70 @@
+---
+name: sungen-locale
+description: 'Bootstrap i18n for a screen/flow — audit selectors, detect locale switch mechanism via Playwright, generate test-data overlay so `sungen:run-test --env <locale>` works.'
+argument-hint: "<name> <locale> [--base-locale <code>] [--offline]"
+tools: [read, execute, edit, vscode/askQuestions, playwright/*]
+---
+
+## Role
+
+You are a **Senior QA Localization Engineer**. Use the `sungen-locale` skill — it contains the full phased strategy. Your job in this command is parameter parsing, context detection, and final hand-off.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **name** — screen or flow name (e.g. `home`, `awards`). If missing, ask the user.
+- **locale** — target locale code (e.g. `en`, `ja`, `en-US`, `staging-ja`). If missing, ask. This becomes the suffix in `test-data/<feature>.<locale>.yaml` and `SUNGEN_ENV=<locale>` at run time.
+- **`--base-locale <code>`** — optional. Locale of the existing `test-data/<feature>.yaml`. Default `vi`. Reporting only — files are never renamed.
+- **`--offline`** — force OFFLINE mode (skip Playwright capture). Useful when you know the live page can't be reached.
+
+Reject if name == locale.
+
+## Auto-detect context
+
+Same as `/sungen:run-test`:
+- `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`)
+- Else `qa/screens/<name>/` exists → screen mode (base path: `qa/screens/<name>/`)
+- Neither → tell user and stop
+
+## Steps
+
+The `sungen-locale` skill defines 7 phases. Execute them in order:
+
+1. **Phase 1 — Selector audit** (always, no MCP)
+2. **Phase 2 — Capture base locale** (Live mode only)
+3. **Phase 3 — Switch locale + detect mechanism** (Live mode only)
+4. **Phase 4 — Diff base ↔ target** (Live mode only)
+5. **Phase 5 — Confirm proposal** (always)
+6. **Phase 6 — Apply files** (always, after confirmation)
+7. **Phase 7 — Hand off** (always)
+
+**Mode selection** happens at the start of Phase 2:
+
+- If `--offline` flag → OFFLINE mode (skip Phases 2-4).
+- Else try `browser_navigate(baseURL)` — succeeds + page renders content → LIVE mode.
+- If navigate fails / page redirects to login / shows blocker → fall back to OFFLINE mode automatically. Announce the fallback clearly.
+
+## Enumerate features
+
+Multi-feature screens (e.g. `home` has `home.feature` + `home-modal.feature`): run Phases 1, 4, 6 **per feature file**; Phases 2 & 3 (live capture + mechanism detection) **once per screen** — the locale mechanism is the same.
+
+```bash
+ls qa/screens/<name>/features/*.feature
+# or
+ls qa/flows/<name>/features/*.feature
+```
+
+## After Phase 7
+
+Offer the user:
+
+- **`/sungen:run-test <name> --env <locale>`** — Run tests against the new locale (Recommended)
+- **`/sungen:locale <name> <other-locale>`** — Bootstrap another locale
+- **Open the overlay file** for review/edit
+- **Done**
+
+## Notes
+
+- Do NOT run tests yourself. `/sungen:run-test` is the executor; this command only PREPS files.
+- Do NOT modify `.feature` files. Localization lives in `selectors/*.yaml` + `test-data/*.yaml` only.
+- Auth blocked? Use `--offline`.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-review.md

@@ -20,13 +20,28 @@ You are a **Senior QA Reviewer**. You evaluate Gherkin test cases using the `sun
 
 ## Steps
 
-1. Read `<base>/<name>/features/<name>.feature` and `<base>/<name>/test-data/<name>.yaml`. If missing → `/sungen-create-test` first.
-2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). **For flows**, also apply the "Flow Review Additions" section. Use `sungen-viewpoint` for pattern checklists.
-3. **Unverified Selectors check** — if `<base>/<name>/selectors/<name>.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric. Does NOT affect the 60% threshold.
-4. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
-5. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
-6. After PASS (or user decides to proceed), offer next steps:
-
-- **`/sungen-run-test ${input:name}`** — Generate selectors, compile, and run tests (Recommended)
+1. **Enumerate feature files** — glob `<base>/<name>/features/*.feature`. A screen may have one main file (`<name>.feature`) plus sub-features (`<name>-<sub>.feature` like `awards-modal.feature`); a flow has a single `<name>.feature`. If zero `.feature` files found → `/sungen-create-test` first.
+2. **Review every feature file** — for each `<basename>.feature` discovered in step 1:
+   - Read `<basename>.feature` and the matching `test-data/<basename>.yaml`.
+   - Apply the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). **For flows**, also apply the "Flow Review Additions" section. Use `sungen-viewpoint` for pattern checklists.
+   - Apply the **Unverified Selectors check** — if `<base>/<name>/selectors/<basename>.yaml` exists, count lines matching `@needs-live-verify`. Include in the per-file report as a non-scoring metric. Does NOT affect the 60% threshold.
+3. **Aggregated output** — present scores in a per-feature table, then a screen-level rollup:
+
+   ```
+   Feature              Syntax  Coverage  Viewpoint  Total  Verdict
+   ──────────────────────────────────────────────────────────────────
+   home.feature           28/30    36/40      27/30   91%   PASS
+   home-modal.feature     26/30    24/40      22/30   72%   PASS
+   ──────────────────────────────────────────────────────────────────
+   Screen rollup (mean)   27/30    30/40      24.5/30 81.5% PASS
+   ```
+
+   - **>= 60% per file**: PASS that file.
+   - **< 60% per file**: FAIL that file with recommendations.
+   - Show the full per-file report (recommendations, top issues) **only for files that fail**, or when the user asks for the deep report.
+4. If any file is FAIL and user confirms → update that file's test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review **only the failing files** (skip already-passing ones to save time).
+5. After all files PASS (or user decides to proceed), offer next steps:
+
+- **`/sungen-run-test ${input:name}`** — Generate selectors, compile, and run tests for **every feature** in this screen (Recommended)
 - **`/sungen-create-test ${input:name}`** — Add more test cases before running
 - **Done for now** — I'll come back later