@sun-asterisk/sungen 2.6.12 → 2.6.15

package/src/orchestrator/ai-rules-updater.ts

@@ -22,6 +22,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-cmd-review.md', '.claude/commands/sungen/review.md'],
   ['claude-cmd-delivery.md', '.claude/commands/sungen/delivery.md'],
   ['claude-cmd-dashboard.md', '.claude/commands/sungen/dashboard.md'],
+  ['claude-cmd-locale.md', '.claude/commands/sungen/locale.md'],
 
   // Commands — GitHub Copilot
   ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
@@ -31,6 +32,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['copilot-cmd-review.md', '.github/prompts/sungen-review.prompt.md'],
   ['copilot-cmd-delivery.md', '.github/prompts/sungen-delivery.prompt.md'],
   ['copilot-cmd-dashboard.md', '.github/prompts/sungen-dashboard.prompt.md'],
+  ['copilot-cmd-locale.md', '.github/prompts/sungen-locale.prompt.md'],
 
   // Skills — Claude Code
   ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
@@ -47,6 +49,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-capture-local.md', '.claude/skills/sungen-capture-local/SKILL.md'],
   ['claude-skill-capture-live.md', '.claude/skills/sungen-capture-live/SKILL.md'],
   ['claude-skill-figma-source.md', '.claude/skills/sungen-figma-source/SKILL.md'],
+  ['claude-skill-locale.md', '.claude/skills/sungen-locale/SKILL.md'],
 
   // Skills — Copilot (prompt-based)
   ['copilot-skill-figma-source.md', '.github/prompts/sungen-figma-source.prompt.md'],
@@ -66,6 +69,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-capture-local.md', '.github/skills/sungen-capture-local/SKILL.md'],
   ['github-skill-sungen-capture-live.md', '.github/skills/sungen-capture-live/SKILL.md'],
   ['github-skill-sungen-figma-source.md', '.github/skills/sungen-figma-source/SKILL.md'],
+  ['github-skill-sungen-locale.md', '.github/skills/sungen-locale/SKILL.md'],
 ];
 
 export class AIRulesUpdater {

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

@@ -1,40 +1,55 @@
 ---
 name: add-screen
-description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can capture visuals from Figma (pre-launch) or live page via the capture skills'
-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 capture visuals from Figma (pre-launch) or live page via the capture skills'
+argument-hint: "[screen-name] [url-path] [--feature <name>] [--figma <url>]"
 allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__figma__get_screenshot
 ---
 
-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
 
 Parse from `$ARGUMENTS`:
 - **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
-- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`) - 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** — URL path (e.g., `/login`, `/dashboard`, `/settings`) - optional when `--figma` is provided or when adding a sub-feature to an existing screen
+- **`--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 (e.g. main listing + modal + filter panel).
+- **`--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)
 
 If **screen** is missing, ask: "What is the screen name? (e.g., `login`, `dashboard`)"
-If **path** is missing and `--figma` was NOT provided, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+If **path** is missing and **`--feature`** is NOT used and `--figma` was NOT provided, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+
+**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`):**
 ```bash
 sungen add --screen <screen> --path <path>
 ```
 
+**Sub-feature mode (`--feature <name>` provided):**
+```bash
+sungen add --screen <screen> --feature <name> [--path <path>]
+# Generates qa/screens/<screen>/{features,selectors,test-data}/<screen>-<name>.{feature,yaml,yaml}
+# Existing screen files (awards.feature, spec.md, …) are untouched.
+# --path is optional — defaults to /<screen> when omitted. Pass --path only if the sub-feature lives at a different URL.
+```
+
 **Figma branch (when `--figma <url>` is in `$ARGUMENTS`):**
 
 Invoke the `sungen-figma-source` skill by running:
 ```bash
-sungen add --screen <screen> --figma '<url>' [--path <path>] [--refresh] [--scale <n>]
+sungen add --screen <screen> --figma '<url>' [--path <path>] [--feature <name>] [--refresh] [--scale <n>]
 # Single-quote the URL — Figma links contain `&` which bash otherwise treats as a background operator.
+# --feature can be combined with --figma when the new sub-feature has its own Figma frame.
 ```
 
 This CLI command automatically:
@@ -84,15 +99,34 @@ Each capture skill writes outputs into `qa/screens/<screen>/requirements/ui/` an
 
 ### 3. Fill spec.md
 
-Use `AskUserQuestion`: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **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, use `AskUserQuestion`: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
 
 If yes → open `qa/screens/<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, then use `AskUserQuestion` to offer next steps:
+Tell the user what was created. When `--feature` was used, list the 3 new files explicitly (`features/<screen>-<name>.feature`, `selectors/<screen>-<name>.yaml`, `test-data/<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 use `AskUserQuestion` to offer next steps:
 
 - **`/sungen:create-test <screen>`** — Create test cases from requirements/designs (Recommended)
 - **Done for now** — I'll come back later
 
 If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke it. Do NOT generate test cases yourself — the skill auto-loads `sungen-gherkin-syntax` and `sungen-tc-generation`.
+
+## 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/claude-cmd-dashboard.md

@@ -19,8 +19,11 @@ Parse **screens** from `$ARGUMENTS`:
 
 ### 1. Invoke the CLI
 
+Prefer the local `./bin/sungen.js` when it exists (this is the canonical entry point when developing sungen itself, and ships any unpublished features the global package doesn't have yet). Fall back to `npx sungen` for downstream projects that consume sungen as a dependency.
+
 ```bash
-npx sungen dashboard <screens>
+# Local-first dispatcher — works in both the sungen 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/claude-cmd-delivery.md

@@ -1,7 +1,7 @@
 ---
 name: delivery
 description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
-argument-hint: "[screen-name...] (omit for all screens)"
+argument-hint: "[screen-name...] [--env <locale>] (omit screens for all; --env for locale-specific export)"
 allowed-tools: Bash, Read, AskUserQuestion
 ---
 
@@ -11,28 +11,34 @@ You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic
 
 ## Parameters
 
-Parse **screens** from `$ARGUMENTS`:
-- If empty → CLI will process **all** screens in `qa/screens/`
-- If provided → pass them through to the CLI
+Parse from `$ARGUMENTS`:
+- **screens** — 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
 
 ### 1. Invoke the CLI
 
-Run via Bash (single command, no extra parsing):
+Run via Bash (single command, no extra parsing). Prefer the local `./bin/sungen.js` when it exists — the sungen monorepo ships local-only features the global npm package doesn't have yet (multi-sheet locale aggregation, `.<env>` filename suffix, locale-aware step rendering). Fall back to `npx sungen` in downstream projects.
 
 ```bash
-npx sungen delivery <screens>
+# No env — local-first dispatcher:
+[ -x ./bin/sungen.js ] && ./bin/sungen.js delivery <screens> || npx sungen delivery <screens>
+
+# Locale-specific:
+[ -x ./bin/sungen.js ] && SUNGEN_ENV=<locale> ./bin/sungen.js delivery <screens> || SUNGEN_ENV=<locale> npx sungen delivery <screens>
 ```
 
-- If no screen args → just run `npx sungen delivery`
-- If screen args → pass them as positional arguments
+- If no screen args → omit `<screens>` (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 vs specific)
+- Scope detection (all screens + flows vs specific)
 - Pre-flight source checks with colorful output
-- Parsing `.feature`, `.spec.ts`, `test-data.yaml`, `test-results/results.json`
-- Generating CSV at `qa/deliverables/<screen>-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)
@@ -68,4 +74,9 @@ Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`
 sungen delivery [screens...]
   [--skip-preflight]          Skip pre-flight checks (not recommended)
   [--continue-on-missing]     Skip screens with blocking misses
+
+# Locale-aware export (env var, not a CLI flag):
+SUNGEN_ENV=<locale> sungen delivery [screens...]
+  → reads <name>.<locale>.yaml overlay, picks <name>-test-result.<locale>.json,
+    writes <name>-testcases.<locale>.csv / .xlsx
 ```

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

@@ -0,0 +1,71 @@
+---
+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]"
+allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_click, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state
+---
+
+## 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`, `kudo-to-display-on-kudos`). If missing → AskUserQuestion.
+- **locale** — target locale code (e.g. `en`, `ja`, `en-US`, `staging-ja`). If missing → AskUserQuestion. This becomes the suffix in `test-data/<feature>.<locale>.yaml` and `SUNGEN_ENV=<locale>` at run time.
+- **`--base-locale <code>`** — optional. The locale of existing `test-data/<feature>.yaml`. Default `vi`. Used only for reporting/UX — files never get renamed.
+- **`--offline`** — force OFFLINE mode (skip Playwright capture). Useful when you know the live page can't be reached or when prepping a test-only template.
+
+Reject if name == locale (common typo).
+
+## 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 exists → 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, Phase 5 shows empty `target text` column for user to fill manually).
+- Else try `browser_navigate(baseURL)` — if it succeeds and page renders content → LIVE mode.
+- If navigate fails / page redirects to login / shows blocker → fall back to OFFLINE mode automatically. Announce the fallback clearly so the user knows what they got.
+
+## Enumerate features
+
+For multi-feature screens (e.g. `home` has `home.feature` + `home-modal.feature`), run Phases 1, 4, 6 once **per feature file**; run Phases 2 & 3 (live capture + mechanism detection) **once per screen** — the mechanism doesn't change between features in the same screen.
+
+Discover features the same way delivery does:
+
+```bash
+ls qa/screens/<name>/features/*.feature
+# or
+ls qa/flows/<name>/features/*.feature
+```
+
+## After Phase 7
+
+Use `AskUserQuestion` to offer next steps:
+
+- **`/sungen:run-test <name> --env <locale>`** — Run the tests against the new locale (Recommended)
+- **`/sungen:locale <name> <other-locale>`** — Bootstrap another locale (e.g. add `ja` after `en`)
+- **Open the overlay file** — Show `test-data/<feature>.<locale>.yaml` so user can review / edit before running
+- **Done** — Stop
+
+## Notes
+
+- Do NOT run tests yourself. `/sungen:run-test` is the executor. This command only PREPS files.
+- Do NOT modify `.feature` files. Localization happens entirely through `selectors/*.yaml` + `test-data/*.yaml`.
+- Auth blocker on SAA staging? Use `--offline`. See [[saa-auth-blocker]] memory.

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

@@ -17,13 +17,28 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
 
 ## 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), use `AskUserQuestion` to offer next steps:
-
-- **`/sungen:run-test <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), use `AskUserQuestion` to offer next steps:
+
+- **`/sungen:run-test <name>`** — Generate selectors, compile, and run tests for **every feature** in this screen (Recommended)
 - **`/sungen:create-test <name>`** — Add more test cases before running
 - **Done for now** — I'll come back later

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

@@ -1,7 +1,7 @@
 ---
 name: run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: [screen-name]
+argument-hint: "[screen-name] [--env <locale>]"
 allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_evaluate, mcp__playwright__browser_run_code, mcp__playwright__browser_storage_state, mcp__playwright__browser_set_storage_state
 ---
 
@@ -11,7 +11,24 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 
 ## Parameters
 
-Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+Parse from `$ARGUMENTS`:
+- **name** — screen or flow name. If missing, ask the user.
+- **`--env <locale>`** — optional. Sets `SUNGEN_ENV=<locale>` for the test run so the runtime test-data resolver merges `<name>.<locale>.yaml` over the base, and `playwright.config.ts` writes results to `<name>-test-result.<locale>.json`. Accept `--locale <locale>` as an alias.
+
+If `--env` is passed but no value follows, ask the user which locale to use.
+
+**`--env <locale>` pre-flight**: when `--env` is passed AND the matching overlay file doesn't exist yet (`test-data/<feature>.<locale>.yaml` missing), tests will silently fall back to base locale values — the run will execute but won't actually exercise the locale. Before kicking off Phase 0.5, check:
+
+```bash
+ls qa/<screens|flows>/<name>/test-data/*.<locale>.yaml 2>/dev/null | wc -l
+```
+
+If the count is 0 → use `AskUserQuestion` to offer:
+- **Run `/sungen:locale <name> <locale>` first** (Recommended) — bootstrap the overlay before running tests
+- **Continue anyway** — run with empty overlay (tests will assert base-locale text, will likely fail on a real locale page)
+- **Cancel**
+
+Skip this pre-flight when `--env` matches the base locale (no overlay needed in that case).
 
 **Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
@@ -52,7 +69,11 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
      name: "Submit"
    ```
 3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
-4. Compile: **Screen**: `sungen generate --screen <name>`. **Flow**: `sungen generate --flow <name>`. Default: runtime data loading from YAML. Use `--inline-data` only if user requests compile-time hardcoded values.
+4. Compile via local-first dispatcher so the sungen monorepo's unpublished selector-resolver features (i18n `{{var}}` interpolation, namespaced selector lookup) are picked up:
+   - **Screen**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --screen <name> || npx sungen generate --screen <name>`
+   - **Flow**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --flow <name> || npx sungen generate --flow <name>`
+
+   Default: runtime data loading from YAML. Use `--inline-data` only if user requests compile-time hardcoded values.
 
 ## Run & Fix (phased — per `sungen-selector-fix` skill)
 
@@ -63,13 +84,31 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
 
 ## Playwright command guidelines
 
-**Per-screen/flow JSON results** — each run must write its JSON report to a dedicated path co-located with the `.spec.ts`, so `sungen delivery` can read the correct results:
+**Multi-feature screens** — `sungen generate --screen <name>` produces one `<basename>.spec.ts` per `.feature` file (e.g. `home.spec.ts` + `home-modal.spec.ts`). You must **invoke playwright once per spec file** so each gets its own JSON result that `sungen delivery` can pick up. Do NOT run a single command with the directory as the test argument — that bundles everything into one results file that delivery can't disambiguate.
+
+**Per-spec JSON results** — each invocation writes its JSON report to a path matching the spec basename. When `--env <locale>` was parsed from `$ARGUMENTS`, prepend `SUNGEN_ENV=<locale>` — `playwright.config.ts` auto-inserts `.<locale>` before `.json` in the output path:
 
 ```bash
-# ✅ Screen
+# ✅ Screen with 1 feature
 PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
   npx playwright test specs/generated/<name>/<name>.spec.ts
 
+# ✅ Screen with multiple features — loop in shell:
+for spec in specs/generated/<name>/*.spec.ts; do
+  base=$(basename "$spec" .spec.ts)
+  PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
+    npx playwright test "$spec"
+done
+
+# ✅ Locale 'vi' — same loop, just prepend SUNGEN_ENV=vi
+for spec in specs/generated/<name>/*.spec.ts; do
+  base=$(basename "$spec" .spec.ts)
+  SUNGEN_ENV=vi \
+  PLAYWRIGHT_JSON_OUTPUT_NAME="specs/generated/<name>/${base}-test-result.json" \
+    npx playwright test "$spec"
+done
+# → writes <basename>-test-result.vi.json for each feature
+
 # ✅ Flow
 PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json \
   npx playwright test specs/generated/flows/<name>/<name>.spec.ts
@@ -88,7 +127,7 @@ npx playwright test specs/generated/<screen>/<screen>.spec.ts
 
 If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
 
-`sungen delivery` reads the per-screen file first, falls back to the global `test-results/results.json` if missing.
+`sungen delivery` reads per-feature `<basename>-test-result[.env].json` files (one per feature in the screen) and writes one CSV/XLSX per feature (e.g. `home-testcases.csv` + `home-modal-testcases.csv`). When `--env <locale>` was used here, run delivery with the same locale (`/sungen:delivery <name> --env <locale>`) so it picks the matching `*-test-result.<locale>.json` files and produces `*-testcases.<locale>.csv` / `.xlsx`.
 
 ## Next steps
 

package/src/orchestrator/templates/ai-instructions/claude-config.md

@@ -20,8 +20,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-capture-local` | Load existing UI assets (screenshots, mockups, Figma exports) from `requirements/ui/` |
 | `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
 | `sungen-figma-source` | Figma URL → spec_figma.md + ui/*.png + provisional selectors |
+| `sungen-locale` | Bootstrap i18n — audit selectors, detect locale switch mechanism, generate test-data overlay |
 
-## Workflow (6 AI commands)
+## Workflow (7 AI commands)
 
 | Command | What it does |
 |---|---|
@@ -31,9 +32,11 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
 | `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
+| `/sungen:locale <name> <locale>` | Bootstrap i18n for a screen — audit selectors, detect locale switch, generate overlay (run before `/sungen:run-test --env <locale>`) |
 
 **Screen path:** add-screen → create-test → review → run-test → delivery.
 **Flow path:** add-flow → create-test → review → run-test → delivery.
+**i18n path:** (after run-test passes for base locale) → locale → run-test --env <locale> → delivery --env <locale>.
 
 `create-test`, `review`, and `run-test` auto-detect context: if `qa/flows/<name>/` exists → flow mode, else `qa/screens/<name>/` → screen mode.