@sun-asterisk/sungen 2.4.5 → 2.5.0

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

@@ -109,6 +109,8 @@ Row scope: `see [Ref] row in [Table] table with {{v}}` enters scope. Subsequent
 
 Most elements auto-infer from `[Label] type` → `getByRole(type, { name: 'Label' })`. Only add YAML when the accessible name differs, needs `nth`, or needs `testid`. Full auto-infer table → see `sungen-selector-keys` skill.
 
+**Types requiring YAML entry:** `date-picker`, `uploader`, `overlay`, `frame`, `step` - these have no standard ARIA role and need explicit selectors.
+
 ## YAML Keys
 
 `[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
@@ -149,6 +151,14 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | `@no-auth` | Disable inherited auth |
 | `@steps:name` | Define reusable step block (base scenario) |
 | `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+| `@cleanup:overlay` | Auto-cleanup: dismiss dialogs/overlays after each test (base.ts fixture) |
+| `@cleanup:forms` | Auto-cleanup: clear form fields after each test (base.ts fixture) |
+| `@cleanup:scroll` | Auto-cleanup: scroll to top after each test (base.ts fixture) |
+| `@cleanup:storage` | Auto-cleanup: clear sessionStorage after each test (base.ts fixture) |
+| `@screenshot:on-failure` | Auto-capture screenshot when test fails (base.ts fixture) |
+| `@beforeAll` | Hook: runs once before all tests → `test.beforeAll()` |
+| `@afterEach` | Hook: runs after each test → `test.afterEach()` (custom cleanup) |
+| `@afterAll` | Hook: runs once after all tests → `test.afterAll()` |
 
 ### @extend behavior
 
@@ -173,30 +183,28 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 | Missing `is` for state | `with {{text}} hidden` | `with {{text}} is hidden` |
 | State as value | `with {{disabled}}` | `is disabled` |
 | Missing target type | `fill [email] with {{v}}` | `fill [email] field with {{v}}` |
-| Using Background | `Background: Given User is on...` | Use `@steps` + `@extend` instead |
+| Background with scope | `Background: ... And User is on [X] dialog` | Use `@steps` + `@extend` for scope-dependent flows |
 | `is on` after When | `When ... And User is on [X] dialog` | `And User see [X] dialog` or separate Given |
 
 ## Background vs @steps/@extend
 
-**Do NOT use `Background:` block.** Use `@steps` + `@extend` instead.
+Both `Background` and `@steps`/`@extend` are valid — they serve different purposes.
 
-**Why:**
-- `Background` runs before EVERY scenario but cannot set dialog/frame scope correctly
-- `Background` with `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When)
-- `@steps` + `@extend` gives explicit control: base steps run Given→When, extending scenario starts with `Given User is on [X] dialog` (correct scope setup)
+| Pattern | Use when | Generates |
+|---|---|---|
+| `Background` | Simple shared setup (navigate to page) | `test.beforeEach()` |
+| `@steps`/`@extend` | Complex reusable flows with scope (dialog, frame) | Inline merged steps in `test()` |
 
-**Wrong:**
+**Use `Background` for simple navigation:**
 ```gherkin
 Background:
-  Given User is on [Kudos] page
-  When User click [Open] button
-  And User is on [Modal] dialog    ← keyword mismatch
+  Given User is on [Dashboard] page
 
-Scenario: VP-UI-001 Title visible
-  Then User see [Title] heading
+Scenario: View stats
+  Then User see [Revenue Chart] section
 ```
 
-**Correct:**
+**Use `@steps`/`@extend` when scope matters (dialog, frame):**
 ```gherkin
 @steps:open_modal
 Scenario: Open modal
@@ -209,3 +217,50 @@ Scenario: VP-UI-001 Title visible
   Given User is on [Modal] dialog
   Then User see [Title] heading
 ```
+
+**Avoid `Background` with scope-dependent steps** — `When` + `And User is on [X] dialog` creates keyword mismatch (`is on` = Given, not When). Use `@steps`/`@extend` instead.
+
+## Hooks & Cleanup
+
+Two layers for test lifecycle management. Prefer `@cleanup:*` tags (Layer 1) — they work with base.ts automatically. Use hook scenarios (Layer 2) only for custom logic.
+
+### Layer 1: `@cleanup:*` tags (automatic via base.ts)
+
+Feature-level tags that activate cleanup fixtures in base.ts. No Gherkin steps needed.
+
+```gherkin
+@auth:admin
+@cleanup:overlay
+@cleanup:forms
+Feature: User Management
+  Path: /users
+
+  Background:
+    Given User is on [User Management] page
+
+  Scenario: Create user shows form
+    When User click [Add User] button
+    Then User see [Create User] dialog
+
+  Scenario: Search user by name
+    When User fill [Search] field with {{search_name}}
+    Then User see [User Row] row
+```
+
+| Tag | What base.ts does after each test |
+|---|---|
+| `@cleanup:overlay` | Press Escape, click body, dismiss fixed overlays |
+| `@cleanup:forms` | Clear all input/textarea fields, reset selects |
+| `@cleanup:scroll` | Scroll to top of page |
+| `@cleanup:storage` | Clear sessionStorage |
+
+### Layer 2: `@afterEach` scenario (custom cleanup)
+
+Only when `@cleanup:*` tags aren't enough — feature-specific logic.
+
+### Layer 3: `@beforeAll` / `@afterAll` (optional)
+
+For one-time setup/teardown.
+
+**Rendering order in `.spec.ts`:**
+`test.describe` → `test.use(storageState)` → `test.use(autoCleanup)` → `test.beforeAll` → `test.beforeEach` → `test.afterEach` → `test.afterAll` → `test()` blocks

package/dist/orchestrator/templates/ai-instructions/claude-skill-selector-keys.md

@@ -102,5 +102,27 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 | `[X] list` | `getByRole('list', { name: 'X' })` |
 | `[X] column` | `getByRole('columnheader', { name: 'X' })` |
 | `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
+| `[X] dropdown` / `select` | `getByRole('combobox', { name: 'X' })` |
+| `[X] menuitem` | `getByRole('menuitem', { name: 'X' })` |
+| `[X] progressbar` | `getByRole('progressbar', { name: 'X' })` |
+| `[X] section` | `getByRole('region', { name: 'X' })` |
+| `[X] card` | `getByRole('article', { name: 'X' })` |
+| `[X] item` | `getByRole('listitem', { name: 'X' })` |
+| `[X] cell` | `getByRole('cell', { name: 'X' })` |
+| `[X] spinner` | `getByRole('status', { name: 'X' })` |
+| `[X] breadcrumb` | `getByRole('navigation', { name: 'X' })` |
+| `[X] badge` / `tooltip` / `tag` | `getByText('X')` |
 
 **Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).
+
+### Types requiring YAML entry (no auto-infer)
+
+These types need explicit `selectors.yaml` entries:
+
+| Type | Reason |
+|------|--------|
+| `date-picker` | Custom component, needs testid or CSS |
+| `uploader` | File input, needs upload type selector |
+| `overlay` | No standard ARIA role, needs CSS/testid |
+| `frame` | Needs iframe selector |
+| `step` | Custom stepper component, needs testid |

package/dist/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -112,20 +112,59 @@ Given User is on [Screen] page
 And User wait for [Page Title] heading is visible
 ```
 
+## Cleanup & Hooks
+
+### Auto-assign `@cleanup:*` tags based on screen sections
+
+After identifying screen sections, add appropriate `@cleanup:*` feature-level tags. These activate base.ts fixtures that auto-clean state between tests.
+
+| Screen has | Add tag | Why |
+|---|---|---|
+| Modal / Dialog / Drawer | `@cleanup:overlay` | Dismiss leftover overlays between tests |
+| Form & Inputs / Search / Filter | `@cleanup:forms` | Clear form fields, reset selects |
+| Long scrollable content | `@cleanup:scroll` | Scroll to top for consistent assertions |
+| Auth tokens / session data in tests | `@cleanup:storage` | Clear sessionStorage |
+| CI/CD or debug-heavy screens | `@screenshot:on-failure` | Auto-capture screenshot on test failure |
+
+**Always add `@cleanup:overlay`** if ANY section opens a dialog (Create/Add, Update/Edit, Delete confirmation). Most CRUD screens need it.
+
+**Always add `@cleanup:forms`** if the screen has inline search, filter dropdowns, or editable forms that persist between tests.
+
+### When to add `@afterEach` hook scenario
+
+Only when `@cleanup:*` tags aren't enough — feature-specific cleanup logic:
+- Reset a dropdown filter to default value (not just clear)
+- Navigate away from a sub-tab back to the main tab
+- Close a specific sidebar panel
+
+```gherkin
+@afterEach
+Scenario: Reset filters to default
+  When User select [Status Filter] dropdown with {{default_status}}
+```
+
+### `@beforeAll` / `@afterAll` — optional, low priority
+
+For one-time setup/teardown. Most screens don't need these.
+
 ## Output Format
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
 
-**Never use `Background:`.** Use `@steps` + `@extend` for shared setup (see `sungen-gherkin-syntax` skill).
+`Background` is valid for simple shared setup (navigate to page). Use `@steps`/`@extend` for complex flows with scope (dialog, frame).
 
 ```gherkin
 @auth:role
+@cleanup:overlay
+@cleanup:forms
 Feature: <Screen> Screen
 
+  Background:
+    Given User is on [Screen] page
+
   # Shared setup — NO priority tag on @steps
   @steps:open_form
   Scenario: Open form
-    Given User is on [Screen] page
     When User click [Create] button
     Then User see [Form] dialog
 
@@ -165,6 +204,18 @@ Feature: <Screen> Screen
 
 **Naming**: `VP-<CATEGORY>-<NNN>` prefix. Scenario name must use the **same element type** as the steps — e.g., if the step uses `dialog`, write "dialog opens" not "modal opens".
 
-**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section.
+**Test data** — `qa/screens/<screen>/test-data/<screen>.yaml`, grouped by section. Data is loaded **at runtime** — keys become runtime lookups, not hardcoded strings. The same compiled test works across environments.
+
+**Environment-specific data**: For values that differ per environment (credentials, URLs, test users), create `<screen>.<env>.yaml` alongside the base file. Users run `SUNGEN_ENV=staging npx playwright test` to merge overrides. Structure env YAML with the same keys, only including values that change:
+
+```yaml
+# login.yaml (base)
+valid_email: admin@dev.example.com
+valid_password: DevPass123
+
+# login.staging.yaml (override for staging)
+valid_email: admin@staging.example.com
+valid_password: StagingPass456
+```
 
 **Do NOT generate**: `selectors.yaml` (created during run-test), Playwright code (sungen compiles).

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

@@ -24,27 +24,25 @@ Run with #tool:terminal:
 sungen add --screen ${input:screen} --path ${input:path}
 ```
 
-### 2. Prepare requirements
+### 2. Fill spec.md
 
-Ask the user to choose how to prepare requirements — this is the foundation for high-quality test generation:
+Ask: *"Fill `spec.md` now?"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
 
-- **Fill `spec.md` + capture live-page screenshot** (Recommended) — best test quality
-- **Fill `spec.md` only** — app not live yet, or no need for visuals
-- **Capture live-page screenshot only** — spec will come later
-- **Skip requirements prep** — proceed to `/sungen-create-test` immediately
+If yes → open `qa/screens/${input:screen}/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
 
-**If "Fill `spec.md`" is chosen**: open `qa/screens/${input:screen}/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states.
+### 3. Capture visual source
 
-**If "Capture live-page screenshot" is chosen**:
-1. Read `baseURL` from `playwright.config.ts` (fall back to `APP_BASE_URL` env, then ask the user).
-2. `browser_navigate` to `<baseURL>${input:path}`.
-3. If redirected to login → ask the user to log in manually in the MCP browser, wait for confirmation, then re-navigate. (No auth persistence needed here — that's handled by Phase 0.5 in `sungen-selector-fix` when tests run.)
-4. `browser_take_screenshot` with `filename: "qa/screens/${input:screen}/requirements/ui/${input:screen}.png"`.
-5. If the screen has multiple important states (empty, loaded, error, modal open), offer additional captures named `${input:screen}-<state>.png`.
+Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
 
-If the user has additional UI designs (Figma exports, mockups), suggest copying them to `requirements/ui/`.
+- **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
+- **2) Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+- **3) Skip** — user will drop images manually into `requirements/ui/` later, or rely on `/sungen-create-test` to prompt again
 
-### 3. Next steps
+Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — delegate to the skill so behavior stays consistent with `/sungen-create-test`.
+
+If the user has additional UI designs (mockups, hand-drawn sketches), suggest copying them to `requirements/ui/` — `sungen-capture-local` will pick them up during `/sungen-create-test`.
+
+### 4. Next steps
 
 Tell the user what was created and offer next steps:
 

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-create-test.md

@@ -28,10 +28,12 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
      - **2) Continue without it** — generate tests from spec and other sources only
    - Summarize what you found in requirements and present to the user.
 4. **Screen input** (supplements requirements, or is primary source if no requirements):
-   - Ask: "How should I get the screen design? **1) Figma design** (provide Figma URL — recommended), **2) UI images** (screenshots/mockups in `requirements/ui/`), or **3) Live page scan** (optional, via Playwright MCP)?"
-   - Recommend Figma or UI images first. Live page scan is optional — useful to verify specs vs actual UI or capture real data.
-   - If live page: `browser_navigate` → ONE `browser_snapshot`. If auth redirect → ask user to log in manually. Never use `browser_run_code` or `browser_evaluate` to inject cookies.
-   - If exploring, verify and supplement requirements — flag any discrepancies found.
+   - Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
+     - **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
+     - **2) UI images** (existing screenshots/mockups in `requirements/ui/`) — invoke `sungen-capture-local` skill
+     - **3) Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+   - Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — delegate to the skill so behavior stays consistent.
+   - After the capture skill returns, cross-check its output against `spec.md` and flag any discrepancies before moving on.
 5. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). When requirements exist, use the "Requirements-Driven Generation" strategy. Present sections as a numbered list and let user pick.
 6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
 7. Show summary and offer next steps:

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

@@ -0,0 +1,71 @@
+---
+name: delivery
+description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
+argument-hint: "[screen-name...] (omit for all screens)"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+## Role
+
+You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic `sungen delivery` CLI that performs all parsing and CSV export. Your role is minimal — just run the CLI and help the user if pre-flight checks fail.
+
+## Parameters
+
+Parse **screens** from `$ARGUMENTS`:
+- If empty → CLI will process **all** screens in `qa/screens/`
+- If provided → pass them through to the CLI
+
+## Steps
+
+### 1. Invoke the CLI
+
+Run via Bash (single command, no extra parsing):
+
+```bash
+npx sungen delivery <screens>
+```
+
+- If no screen args → just run `npx sungen delivery`
+- If screen args → pass them as positional arguments
+
+The CLI handles:
+- Scope detection (all screens 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`
+- Printing summary table
+
+### 2. Handle pre-flight failures (if CLI exits non-zero)
+
+If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per screen.
+
+Use `AskUserQuestion` to offer next steps:
+
+**Options:**
+- **Fix missing sources** (Recommended) — Print the suggested commands from CLI output and stop. User will run those commands manually, then re-invoke `/sungen:delivery`.
+- **Continue with available screens** — Re-run as `npx sungen delivery <screens> --continue-on-missing` to skip screens with blocking issues.
+- **Cancel** — Exit.
+
+### 3. Show summary + offer next steps (on success)
+
+Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`:
+
+- **Open a specific CSV** — Help user inspect one of the exported files with Read tool.
+- **Run tests to refresh results** — Suggest `/sungen:run-test <screen>` to update `test-results/results.json`, then re-run delivery.
+- **Export another screen** — User can run `/sungen:delivery <other-screen>`.
+- **Done** — Exit.
+
+## Important notes
+
+- **Do NOT parse files yourself** — the CLI is the source of truth for parsing logic. Your job is orchestration + user interaction.
+- **Do NOT modify feature/spec.ts/test-data files** — the delivery is read-only.
+- **The CLI already respects `@manual` tags, skips `@steps:` base scenarios, groups by Category 2, and generates UTF-8 BOM CSV for Excel compatibility with Vietnamese.**
+- **Pre-flight check is built into the CLI** — use `--skip-preflight` only in CI/automated pipelines where checks are done externally.
+
+## CLI Reference
+
+```
+sungen delivery [screens...]
+  [--skip-preflight]          Skip pre-flight checks (not recommended)
+  [--continue-on-missing]     Skip screens with blocking misses
+```

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -1,27 +1,24 @@
 ---
-name: sungen-run-test
-description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
-argument-hint: '[screen-name]'
-agent: 'agent'
-tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
+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]
+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
 ---
 
-**Input**: Screen name (e.g., `/sungen-run-test admin-users`).
-
 ## Role
 
 You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
-- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
-1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`.
+1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`.
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, run Phase 0 from `sungen-selector-fix` — confirm with user, `browser_navigate` → one `browser_snapshot` → merge YAML entries.
 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: `sungen generate --screen ${input:screen}`.
+4. Compile: `sungen generate --screen <screen>` (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)
 
@@ -30,15 +27,42 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
 
+## Playwright command guidelines
+
+**Per-screen 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 per screen:
+
+```bash
+# ✅ Correct — per-screen output file via env var
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<screen>/<screen>-test-result.json \
+  npx playwright test specs/generated/<screen>/<screen>.spec.ts
+```
+
+Output: `specs/generated/<screen>/<screen>-test-result.json`
+
+**DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
+
+```bash
+# ❌ Wrong — --reporter flag disables the config's JSON reporter
+npx playwright test specs/generated/<screen>/<screen>.spec.ts --reporter=list
+
+# ❌ Wrong — no env var → writes to default test-results/results.json
+# (overwritten on every screen run, loses per-screen tracking)
+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.
+
 ## Next steps
 
-After showing results, offer next steps:
+After showing results, use `AskUserQuestion` to offer next steps:
 
 If all tests **passed**:
-- **`/sungen-create-test ${input:screen}`** — Add more test cases (Recommended)
+- **`/sungen:create-test <screen>`** — Add more test cases (Recommended)
 - **Done** — All tests passed, I'm finished
 
 If tests **failed** (after retries):
-- **`/sungen-run-test ${input:screen}`** — Re-run after manual fixes
-- **`/sungen-create-test ${input:screen}`** — Revise test cases
+- **`/sungen:run-test <screen>`** — Re-run after manual fixes
+- **`/sungen:create-test <screen>`** — Revise test cases
 - **Done for now** — I'll fix manually later

package/dist/orchestrator/templates/ai-instructions/copilot-config.md

@@ -15,8 +15,12 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-viewpoint` | 10 UI patterns x 4 viewpoints — coverage checklists |
 | `sungen-selector-keys` | YAML key generation from `[Reference]` names, suffixes, lookup priority |
 | `sungen-selector-fix` | Selector generation from live page, auto-fix strategy |
+| `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
+| `sungen-capture-figma` | Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP |
+| `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) |
 
-## Workflow (4 AI commands)
+## Workflow (5 AI commands)
 
 | Command | What it does |
 |---|---|
@@ -24,8 +28,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `/sungen-create-test <name>` | Generate `.feature` + `test-data.yaml` (no selectors) |
 | `/sungen-review <name>` | Score syntax, coverage, viewpoint quality (60% threshold) |
 | `/sungen-run-test <name>` | Generate `selectors.yaml` from live page, compile, run, auto-fix |
+| `/sungen-delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
 
-**Order:** add-screen → create-test → review → run-test.
+**Order:** add-screen → create-test → review → run-test → delivery.
 
 After each command completes, present the next actions as selectable options. Never just print text — always give clickable choices so the user can continue the workflow seamlessly.
 
@@ -35,17 +40,31 @@ After each command completes, present the next actions as selectable options. Ne
 qa/screens/<screen-name>/
 ├── features/<screen>.feature      # Gherkin scenarios
 ├── selectors/<screen>.yaml        # Element locators (generated during run-test)
-├── test-data/<screen>.yaml        # Test data variables
+├── test-data/<screen>.yaml        # Test data variables (loaded at runtime)
+├── test-data/<screen>.staging.yaml    # Environment override (optional)
+├── test-data/<screen>.production.yaml # Environment override (optional)
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
+
+qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen-delivery)
+qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ```
 
+## Test Data
+
+`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
+
+**Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
+
 ## CLI Commands
 
 ```bash
 sungen add --screen <name> --path <url-path>               # Scaffold screen directories
 sungen add --screen <name> --path <path> --feature <name>   # Scaffold with sub-feature
-sungen generate --screen <name>                              # Compile .feature → .spec.ts
+sungen generate --screen <name>                              # Compile .feature → .spec.ts (runtime data)
+sungen generate --screen <name> --inline-data                # Compile with hardcoded data (legacy)
 sungen generate --all                                        # Compile all screens
+sungen delivery                                              # Export all screens → CSV + XLSX
+sungen delivery <screen>                                     # Export a single screen
 ```

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-capture-figma.md

@@ -0,0 +1,142 @@
+---
+name: sungen-capture-figma
+description: 'Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP. Auto-loaded by create-test when user picks Figma as the visual source.'
+user-invocable: false
+---
+
+## Purpose
+
+Pull **structured design data** (layout, typography, colors, component tree, design tokens) and a **PNG screenshot** from a Figma frame URL, so `sungen-tc-generation` can author Gherkin + test-data before a live domain exists.
+
+Use this when the project is pre-launch, or when Figma is the source of truth and the live build lags the design.
+
+---
+
+## Prerequisites
+
+- **Figma MCP server** (`https://mcp.figma.com/mcp`, HTTP transport) connected in `.vscode/mcp.json` — `sungen init` scaffolds this automatically. On first use, VS Code / Copilot opens a browser for Figma OAuth. Official tools: `get_design_context`, `get_variable_defs`, `get_screenshot`.
+- Figma account signed in with access to the file. **Dev/Full seats** get per-minute rate limits; **Starter/View seats** get monthly tool-call limits.
+- A Figma URL with both **fileKey** and **nodeId** in it.
+
+If the MCP is not connected, **do not fail silently** — tell the user:
+> "Figma MCP not detected. Run `sungen init` to scaffold the config, or manually add `figma` with `url: https://mcp.figma.com/mcp` to `.vscode/mcp.json`. Then sign in when VS Code prompts."
+
+Then stop.
+
+---
+
+## Steps
+
+### 1. Resolve Figma URL
+
+Prefer in this order:
+
+1. `Figma URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
+2. If empty or missing → ask the user: *"Paste the Figma frame URL"*
+
+Accept any of these URL shapes:
+
+```
+https://www.figma.com/file/<fileKey>/<title>?node-id=<nodeId>
+https://www.figma.com/design/<fileKey>/<title>?node-id=<nodeId>
+https://www.figma.com/proto/<fileKey>/<title>?node-id=<nodeId>
+```
+
+Parse:
+- `fileKey` = the segment after `/file/`, `/design/`, or `/proto/`
+- `nodeId` = the `node-id` query param (may use `-` or `:` — pass through as-is; MCP accepts both)
+
+If `node-id` is missing, ask the user to select a frame in Figma and copy the **frame URL** specifically (not the file root URL).
+
+### 2. Fetch design context
+
+Call **both** in parallel:
+
+```
+get_design_context({ fileKey, nodeId })
+get_variable_defs({ fileKey, nodeId })
+```
+
+`get_design_context` returns layout, typography, color values, component structure, spacing.
+`get_variable_defs` returns named design tokens (color/spacing/typography variables).
+
+### 3. Fetch screenshot
+
+```
+get_screenshot({ fileKey, nodeId })
+```
+
+Save the returned PNG to:
+
+```
+qa/screens/<screen>/requirements/ui/figma-<sanitized-nodeId>.png
+```
+
+Sanitize `nodeId` for filesystem: replace `:` and `-` with `_`. Example: `42-15` → `figma-42_15.png`.
+
+### 4. Write metadata dump
+
+Combine the design context + variables into a Markdown summary at:
+
+```
+qa/screens/<screen>/requirements/ui/figma-meta.md
+```
+
+Format:
+
+```markdown
+# Figma Capture — <nodeId>
+
+**Source:** <full Figma URL>
+**Captured:** <ISO date>
+
+## Components
+<hierarchical list of component names + variants from get_design_context>
+
+## Typography
+<font families, sizes, weights, line heights>
+
+## Colors
+<color tokens + raw hex values>
+
+## Spacing & Layout
+<spacing tokens, auto-layout specs>
+
+## Text Content
+<visible text strings from the frame — used by tc-generation to populate test-data>
+```
+
+This file is consumed by `sungen-tc-generation` as a secondary source alongside `spec.md`.
+
+### 5. Report back
+
+Output a short summary to the user:
+
+> Captured Figma frame `<nodeId>`:
+> - Components: N
+> - Text strings: M
+> - Design tokens: K
+> - Screenshot: `qa/screens/<screen>/requirements/ui/figma-<nodeId>.png`
+> - Metadata: `requirements/ui/figma-meta.md`
+
+Then hand back to the calling command.
+
+---
+
+## Error handling
+
+| Error | Action |
+|---|---|
+| MCP tool not available | Print setup instructions, stop, do not fall back silently |
+| `fileKey` missing from URL | Ask user to paste a valid frame URL |
+| `nodeId` missing from URL | Ask user to right-click a frame in Figma → *Copy link to selection* |
+| `get_design_context` 403 | Ask user to check Dev Mode seat on that file |
+| `get_screenshot` returns no image | Continue with metadata only; warn user no PNG was captured |
+
+---
+
+## What this skill does NOT do
+
+- Does not generate Gherkin (that's `sungen-tc-generation`)
+- Does not write `selectors.yaml` (that's `/sungen-run-test`)
+- Does not validate the design against live UI (future skill: `sungen-capture-live` can be run afterwards for cross-check)