@sun-asterisk/sungen 2.4.6 → 2.5.1

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

@@ -151,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
 
@@ -175,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
@@ -211,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-tc-generation.md

@@ -6,14 +6,25 @@ user-invocable: false
 
 ## Goal
 
-Generate **focused test cases per screen section** with **20+ scenarios per viewpoint**. Output `.feature` + `test-data.yaml` only — selectors are deferred to `/sungen:run-test`.
+Generate **focused test cases per screen section** using a **tier-based approach** for faster results. Output `.feature` + `test-data.yaml` only — selectors are deferred to `/sungen:run-test`.
+
+### Tier System
+
+| Tier | Priority | What to generate | When |
+|---|---|---|---|
+| **Tier 1** (default) | `@critical` + `@high` | Happy paths, required validation, core business rules, security basics | First run of `create-test` |
+| **Tier 2** (expand) | `@normal` + `@low` | UI presence, optional validation, edge cases, cosmetic checks | User runs `create-test` again with "Add viewpoints" mode |
+
+**Round 1 (Tier 1)** targets **~10-15 scenarios per section** — enough to cover critical flows and catch real bugs. This is the default behavior.
+
+**Round 2 (Tier 2)** expands to full coverage when the user explicitly chooses "Add viewpoints" or "Add new sections" update mode. Only then generate `@normal` + `@low` scenarios to fill coverage gaps.
 
 ## Update Mode
 
 When `.feature` already has scenarios, summarize and ask:
-1. **Add new sections** — append, continue numbering
-2. **Add viewpoints** — add to existing sections
-3. **Replace all** — overwrite
+1. **Add new sections** — append new sections with Tier 2 (`@normal` + `@low`) scenarios, continue numbering
+2. **Add viewpoints** — expand existing sections with Tier 2 (`@normal` + `@low`) scenarios
+3. **Replace all** — overwrite with fresh Tier 1 (`@critical` + `@high`) generation
 
 For append: read highest `VP-<CAT>-<NNN>`, continue from next number. Never modify existing scenarios.
 
@@ -30,12 +41,13 @@ If also exploring live page: verify spec vs actual, flag mismatches, capture exa
 
 ## Screen Input Sources
 
-**Recommended** (in priority order):
-1. **Figma designs** — use Figma MCP to read design context, screenshots, and component metadata
-2. **UI images** — screenshots or mockups in `qa/screens/<screen>/requirements/ui/`
-3. **`spec.md`** — written specification with sections, fields, validation rules
+**Auto-detect** — the parent command (`create-test`) resolves visual sources before invoking this skill. By the time generation starts, the available sources are already determined:
+- `spec.md` — primary, always read if present
+- `spec_figma.md` — Figma supplement, read if present (PAT flow already completed)
+- `ui/*.png` — visual context, read if present
+- `test-viewpoint.md` — edge cases and known issues, read if present
 
-**Optional**: **Live page scan** via Playwright MCP — useful to verify specs vs actual UI, capture real data (error messages, labels). If auth needed → ask user to log in manually via MCP browser.
+**IMPORTANT:** If `spec_figma.md` exists, do NOT call any `mcp__figma__*` tool. The PAT flow is complete — just read the file.
 
 **Single screen focus**: one URL = one screen. Don't explore sibling paths. Modals on same page = part of this screen.
 
@@ -76,7 +88,9 @@ Apply `sungen-test-design-techniques` to spec-extracted conditions:
 
 Use `sungen-viewpoint` skill for per-pattern checklists across 4 viewpoints: UI/UX, Data & Validate, Logic, Security.
 
-Add scenarios for generic UI coverage that spec didn't explicitly state (empty states, loading states, keyboard nav, hover effects). Skip viewpoints truly N/A.
+**Tier-aware gap filling:**
+- **Tier 1 (first run)**: only add `@critical` and `@high` items from the checklists — core security checks (VP-SEC), required field validation (VP-VAL), key state transitions (VP-LOGIC). Skip `@normal`/`@low` items like hover states, empty states, tooltips.
+- **Tier 2 (expand run)**: add `@normal` + `@low` scenarios — UI presence, optional validation, edge cases, cosmetic checks, keyboard nav, hover effects.
 
 **Validation rule**: capture actual error messages from live page or spec.md. Use `User see {{error_var}}` — never assert just "is visible".
 
@@ -112,30 +126,70 @@ 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
 
-  # --- Section: Create User Form ---
+  # --- Section: Create User Form (Tier 1: @critical + @high) ---
 
-  @normal @extend:open_form
-  Scenario: VP-UI-001 Form displays all fields with correct defaults
+  @critical @extend:open_form
+  Scenario: VP-LOGIC-001 Submit form with valid data creates record
     Given User is on [Form] dialog
-    Then User see [Name] field
-    And User see [Submit] button is disabled
+    When User fill [Name] field with {{valid_name}}
+    And User click [Submit] button
+    Then User see {{success_message}} message
 
   @high @extend:open_form
   Scenario: VP-VAL-001 Submit with all empty fields shows errors
@@ -143,19 +197,23 @@ Feature: <Screen> Screen
     When User click [Submit] button
     Then User see [Name error] message with {{name_required_error}}
 
-  # --- Section: User Table ---
-
-  @normal
-  Scenario: VP-UI-010 Table displays all columns
-    Then User see [Name] column in [Users] table
+  # --- Section: User Table (Tier 1: @critical + @high) ---
 
   @high
   Scenario: VP-VAL-010 Table displays correct data
     Then User see [Users] table match data:
       | Name       | Email        |
       | {{name_1}} | {{email_1}}  |
+
+  @critical
+  Scenario: VP-SEC-010 Unauthorized user cannot access page
+    Given User is not logged in
+    When User navigate to [Screen] page
+    Then User is on [Login] page
 ```
 
+**Tier 2 (expand run)** adds `@normal` + `@low` scenarios like UI field presence, hover states, tooltips, empty states.
+
 ### When to use DataTable vs Row Scope
 
 | Pattern | Use when |
@@ -165,6 +223,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/claude-skill-tc-review.md

@@ -43,6 +43,8 @@ Score: `(dimensions_covered / 6) * 40`. Validate technique application with `sun
 
 **Classification**: UI = static/always-same appearance. VAL = input validation/errors. LOGIC = behavior/state changes (includes persisted state without When). SEC = auth/permissions.
 
+**Tier-aware scoring**: If the feature file only contains `@critical` + `@high` scenarios (Tier 1), do NOT penalize for missing VP-UI viewpoint — UI scenarios are intentionally deferred to Tier 2. Score "All applicable VP present" based on Tier 1-relevant viewpoints only (VAL, LOGIC, SEC). Note in the review output: *"VP-UI deferred to Tier 2 — run `/sungen:create-test` with 'Add viewpoints' to expand."*
+
 ---
 
 ## Quality Rules

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

@@ -1,46 +1,90 @@
 ---
 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]'
+argument-hint: '[screen-name] [url-path] [--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/...`.
 
 You are adding a new Sungen screen for test generation.
 
 ## Parameters
 
 - **screen** — ${input:screen:screen name (e.g., login, dashboard)}
-- **path** — ${input:path:URL path (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)
 
 ## Steps
 
 ### 1. Scaffold the screen
 
+**Standard path (no --figma):**
+
 Run with #tool:terminal:
 ```bash
 sungen add --screen ${input:screen} --path ${input:path}
 ```
 
-### 2. Fill spec.md
+**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>]
+```
+
+This CLI command automatically:
+1. Parses the Figma URL and fetches the design node.
+2. Downloads frame + variant PNGs to `qa/screens/${input:screen}/requirements/ui/`.
+3. Writes `qa/screens/${input:screen}/requirements/spec_figma.md` (auto-generated, always overwritten on re-run).
+4. Creates `qa/screens/${input:screen}/requirements/spec.md` stub **only if the file does not already exist** — never overwrites existing human content.
+
+**Important coexistence rules:**
+- `--figma` and `--path` can be passed together.
+- `spec.md` is the human-authored source of truth — never modify it automatically.
+- `spec_figma.md` is auto-generated — tell the user to copy useful sections into `spec.md`.
+- `--capture` (Playwright screenshot) and `--figma` can be used simultaneously.
 
-Ask: *"Fill `spec.md` now?"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
+**If Figma auth is missing**, guide the user to run `sungen figma auth set` and retry.
 
-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.
+### 1a. Synthesize narrative sections (Figma branch only)
 
-### 3. Capture visual source
+After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is deterministic but the narrative below the `<!-- SYNTHESIS-BELOW -->` marker is empty. Invoke the `sungen-figma-source` skill:
 
-Ask the user to pick a visual source. Always offer all three so pre-launch projects work:
+1. Read `qa/screens/${input:screen}/requirements/spec_figma.md` frontmatter for `file_key`, `node_id`, `figma_version_id`.
+2. Read the cached raw node JSON at `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores).
+3. Follow the skill's 7-section template (Purpose / ASCII Layout / Regions / Actions / Form Fields / Data Columns / Navigation) and **replace** everything from the marker to EOF.
+4. Preserve the envelope above the marker byte-for-byte.
 
+**Review gate.** Before moving on, show the user the synthesized narrative and ask:
+
+- **1) Approve** — narrative looks right, continue to Step 2
+- **2) Edit** — user will tweak `spec_figma.md` now; wait for confirmation before continuing
+- **3) Cancel** — abort; advise the user that `spec.md` was NOT modified and they can re-run `sungen add --figma --refresh` later
+
+### 2. Capture visual source
+
+**If Figma branch (Step 1) already downloaded PNGs** → visuals already exist. Offer:
+- **1) Continue** — Figma visuals are enough (Recommended)
+- **2) Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture-live` skill)
+
+**If standard path (no --figma)** → go straight to source selection:
 - **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) Skip** — user will drop images manually into `requirements/ui/` later
 
 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`.
+### 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**.
+
+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
 

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

@@ -1,6 +1,6 @@
 ---
 name: sungen-create-test
-description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (20+ scenarios per viewpoint). Uses sungen-gherkin-syntax and sungen-tc-generation skills.'
+description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (tier-based: critical+high first, expand later). Uses sungen-gherkin-syntax and sungen-tc-generation skills.'
 argument-hint: '[screen-name]'
 agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
@@ -10,7 +10,7 @@ tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwri
 
 ## Role
 
-You are a **Senior QA Engineer**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-run-test`.
+You are a **Senior QA Engineer**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Tier 1 (critical+high) first** — expand coverage later. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-run-test`.
 
 ## Parameters
 
@@ -20,27 +20,32 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
 1. Verify `qa/screens/${input:screen}/` exists. If not → run `/sungen-add-screen` first.
 2. Check if `.feature` already has scenarios. If yes → summarize existing coverage and ask: **1) Add new sections**, **2) Add viewpoints to existing sections**, or **3) Replace all**. See `sungen-tc-generation` skill for update mode details.
-3. **Read requirements** — check `qa/screens/${input:screen}/requirements/`:
+3. **Read requirements & resolve visual source** — check `qa/screens/${input:screen}/requirements/`:
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
-   - If `ui/` has images → read them for visual context (layout, element positions, states).
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), ask:
      - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
      - **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 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:
+
+   **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
+   1. If `spec_figma.md` exists → read it as Figma supplement (PAT flow already completed during `add-screen`). Do NOT call any `mcp__figma__*` tool.
+   2. If `ui/` has images (`.png`, `.jpg`, etc.) → read them for visual context (layout, element positions, states).
+   3. If neither exists → ask: *"No visual source found. Pick one:"*
+      - **1) Figma PAT** — ask for URL, run `sungen add --screen ${input:screen} --figma '<url>'`, then invoke `sungen-figma-source` skill
+      - **2) Figma MCP** — invoke `sungen-capture-figma` skill
+      - **3) Live page scan** — invoke `sungen-capture-live` skill
+      - **4) Skip** — generate from spec.md only
+
+   **Cross-check**: if both `spec.md` and visual sources exist, flag any discrepancies (missing fields, different labels) before moving on. When `spec_figma.md` is present, follow the Figma supplement rules in `sungen-tc-generation` skill (reading order, Text Inventory, conflict handling).
+
+   Summarize what you found in requirements and present to the user.
+
+4. 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.
+5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
+6. Show summary and offer next steps:
 
 - **`/sungen-review ${input:screen}`** — Review syntax, coverage, viewpoint quality (Recommended)
 - **`/sungen-run-test ${input:screen}`** — Skip review, generate selectors and run tests now
-- **`/sungen-create-test ${input:screen}`** — Add more test cases for another section/viewpoint
+- **`/sungen-create-test ${input:screen}`** — Expand coverage: add @normal + @low scenarios
 - **Done for now** — I'll come back later
 
 **No selectors.yaml** — selectors are generated during `/sungen-run-test`.

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

@@ -20,9 +20,10 @@ You are a **Senior QA Reviewer**. You evaluate Gherkin test cases using the `sun
 
 1. Read `qa/screens/${input:screen}/features/${input:screen}.feature` and `qa/screens/${input:screen}/test-data/${input:screen}.yaml`. If missing → `/sungen-create-test` first.
 2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). Use `sungen-viewpoint` for pattern checklists.
-3. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
-4. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
-5. After PASS (or user decides to proceed), offer next steps:
+3. **Unverified Selectors check** — if `qa/screens/${input:screen}/selectors/${input:screen}.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric (see `sungen-tc-review` skill for report format). 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:screen}`** — Generate selectors, compile, and run tests (Recommended)
 - **`/sungen-create-test ${input:screen}`** — Add more test cases before running

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

@@ -16,9 +16,41 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
 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.
+2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
+
+   ```
+   Phase 0 — Selector Generation decision tree
+
+   Live page reachable? (URL provided and loads without error)
+     YES → existing flow: browser_navigate → one browser_snapshot → generate selectors.yaml (verified entries)
+     NO  → spec_figma.md exists in requirements/?
+             YES → provisional flow (sungen-figma-source + sungen-selector-fix skills):
+                   1. Read filtered Figma node data from spec_figma.md (## Components + ## Text Inventory)
+                   2. Apply selector heuristics from sungen-figma-source skill (testid > role+name > placeholder > label > locator > text)
+                   3. Write selectors.yaml — every provisional entry gets this comment on the line above:
+                          # @needs-live-verify source=figma node_id=<id>
+                   4. Compile: sungen generate --screen <screen> — must succeed
+                   5. Phase 1 smoke check runs; tests using unverified selectors may fail
+                      → auto-fix triggers on next run-test invocation when a live page is available
+             NO  → hard stop: print the following message and stop:
+                   "Cannot generate selectors: no live page URL and no spec_figma.md found.
+                    Options:
+                    • Provide the live URL so Playwright MCP can snapshot the page, OR
+                    • Run: sungen add --screen <screen> --figma <figma-url>  to generate spec_figma.md first"
+   ```
+
+   **Auto-fix on subsequent runs**: when `run-test` is invoked again with a reachable live page, Phase 0 compares the DOM snapshot against existing `selectors.yaml` entries. Entries tagged `# @needs-live-verify` are treated as candidates — if the actual selector differs, the entry is replaced and the comment removed (entry becomes verified). Entries that already match are also promoted to verified (comment removed).
+
+   **`@needs-live-verify` comment format** (one comment line, directly above the YAML key):
+   ```yaml
+   # @needs-live-verify source=figma node_id=<figma-node-id>
+   submit-button:
+     type: role
+     value: button
+     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: `sungen generate --screen <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)
 

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

@@ -19,6 +19,7 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `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) |
+| `sungen-figma-source` | Figma URL → spec_figma.md + ui/*.png + provisional selectors |
 
 ## Workflow (5 AI commands)
 
@@ -40,7 +41,9 @@ 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
@@ -49,12 +52,19 @@ qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen-deli
 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