@sun-asterisk/sungen 2.4.5 → 2.5.0

package/src/orchestrator/templates/ai-instructions/claude-skill-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 the user's `.mcp.json` — `sungen init` scaffolds this automatically. On first use, Claude Code 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 `.mcp.json`. Then sign in when Claude 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 → `AskUserQuestion`: *"Paste the Figma frame URL"* (free text)
+
+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)

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

@@ -0,0 +1,100 @@
+---
+name: sungen-capture-live
+description: 'Capture a live running page via Playwright MCP — snapshot + screenshot for visual context. Auto-loaded by create-test when user picks Live page scan.'
+user-invocable: false
+---
+
+## Purpose
+
+Navigate a running application, take **one accessibility snapshot** and **one screenshot**, and save them as visual context for test generation. Use when the app is live (dev, staging, or production with read-only access) and you want the tests grounded in the actual rendered UI.
+
+This skill handles auth gracefully: if the page redirects to login, it asks the user to sign in manually rather than injecting cookies.
+
+---
+
+## Prerequisites
+
+- Playwright MCP connected.
+- Dev/staging server reachable (or a public URL).
+- `playwright.config.ts` exists at the project root (for `baseURL` fallback).
+
+---
+
+## Steps
+
+### 1. Resolve target URL
+
+Resolve in this order:
+
+1. `Live URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
+2. `baseURL` from `playwright.config.ts` + `URL Path` from `spec.md`
+3. If neither works → `AskUserQuestion`: *"Paste the full URL for the page to scan"*
+
+### 2. Navigate
+
+`browser_navigate` to the resolved URL.
+
+### 3. Handle auth redirect
+
+If the page redirects to a login route (URL contains `/login`, `/signin`, `/auth`, or the page title/content indicates a login screen):
+
+1. Tell the user which login URL they landed on.
+2. `AskUserQuestion`:
+   - **I'll log in manually** — wait for user confirmation, then re-navigate to the target URL
+   - **Skip live scan** — tell caller to invoke `sungen-capture-local` instead
+   - **Cancel**
+3. **Never** inject cookies or localStorage via `browser_evaluate` or `browser_run_code`. Auth belongs to the user.
+
+### 4. Snapshot
+
+Take **ONE** `browser_snapshot`. This accessibility tree is the primary AI context — it contains roles, names, text, and structure that the tc-generation skill uses to identify sections and fields.
+
+### 5. Screenshot (optional but recommended)
+
+Take **ONE** `browser_take_screenshot` with `fullPage: true`. Save to:
+
+```
+qa/screens/<screen>/requirements/ui/live-<timestamp>.png
+```
+
+Where `<timestamp>` is `YYYYMMDD-HHMM` in local time (e.g. `live-20260421-1430.png`).
+
+This gives users a visual record they can reference later without re-scanning.
+
+### 6. Detect discrepancies vs spec
+
+If `spec.md` exists, briefly cross-check the snapshot against spec sections:
+
+- Fields listed in spec but not in snapshot → flag as *missing in UI*
+- Elements visible in snapshot but not in spec → flag as *missing in spec*
+
+Report findings but **do not** auto-edit `spec.md` — let the user decide.
+
+### 7. Report back
+
+> Captured live page `<URL>`:
+> - Snapshot: <N> interactive elements detected
+> - Screenshot: `requirements/ui/live-<timestamp>.png`
+> - Discrepancies vs spec: <count, or "none">
+
+Hand back to the calling command.
+
+---
+
+## What this skill does NOT do
+
+- Does not run tests
+- Does not generate `selectors.yaml` (that's `/sungen:run-test`)
+- Does not inject auth state (user logs in manually)
+- Does not crawl — scans **exactly one** page per invocation
+- Does not generate Gherkin — that's `sungen-tc-generation`
+
+---
+
+## Relationship to other capture skills
+
+- `sungen-capture-figma` — design source of truth (pre-launch)
+- `sungen-capture-local` — any image the user dropped in `requirements/ui/`
+- `sungen-capture-live` — this skill, verifies/supplements against the running app
+
+All three write to `requirements/ui/` and report back to the caller. They are mutually exclusive per create-test run, but a user can run create-test multiple times with different sources to layer context.

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

@@ -0,0 +1,73 @@
+---
+name: sungen-capture-local
+description: 'Load existing UI assets (screenshots, Figma exports, hand-drawn mockups) from requirements/ui/. Auto-loaded by create-test when user picks UI images as the visual source.'
+user-invocable: false
+---
+
+## Purpose
+
+Use **pre-existing images** in `qa/screens/<screen>/requirements/ui/` as visual context for test generation. No network, no MCP, no live site required — works for any design tool (Figma export, Sketch, Penpot, Zeplin, hand-drawn, screenshots of a staging env).
+
+This is the **baseline fallback**: if live domain is down and Figma MCP isn't configured, this always works as long as the user drops images in the folder.
+
+---
+
+## Steps
+
+### 1. List available images
+
+Glob `qa/screens/<screen>/requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames.
+
+Filter out metadata files (e.g. `figma-meta.md` written by `sungen-capture-figma`) — those are read by `tc-generation` separately, not treated as images here.
+
+### 2. Handle empty folder
+
+If no images found:
+
+1. Tell the user the folder is empty, with the full path so they can navigate there in Finder.
+2. `AskUserQuestion`:
+   - **I'll drop images now** — wait for user to confirm, then re-glob
+   - **Switch to Figma URL** — tell caller to invoke `sungen-capture-figma` instead
+   - **Switch to live page scan** — tell caller to invoke `sungen-capture-live` instead
+   - **Cancel** — abort create-test
+3. If user picks "drop images now", wait for their confirmation message (e.g. "done") then re-run step 1.
+
+### 3. Read images for context
+
+Use the `Read` tool on each image file — Claude Code can read PNG/JPG/WebP directly as visual context.
+
+For large sets (>10 images), ask the user which are primary and which are states/variants, to avoid loading too much visual context at once.
+
+### 4. Summarize
+
+Output a short summary:
+
+> Loaded N image(s) from `qa/screens/<screen>/requirements/ui/`:
+> - `<filename-1>` — <one-line description of what's visible>
+> - `<filename-2>` — <one-line description>
+> ...
+
+Hand back to the calling command.
+
+---
+
+## File naming hints for users
+
+When this skill reports back, nudge users toward consistent filenames so future runs are self-documenting:
+
+- `<section>-default.png` — baseline state of a section
+- `<section>-error.png` — error state
+- `<section>-loading.png` — loading state
+- `<section>-empty.png` — empty state
+- `full-page.png` / `viewport.png` — whole screen (auto-generated by `sungen add --capture`)
+
+Don't enforce — just suggest if filenames are ambiguous.
+
+---
+
+## What this skill does NOT do
+
+- Does not download images from external URLs
+- Does not generate images (no AI image generation)
+- Does not modify existing images (no crop/resize)
+- Does not generate Gherkin — that's `sungen-tc-generation`

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

@@ -0,0 +1,103 @@
+---
+name: sungen-delivery
+description: 'Export Gherkin scenarios + Playwright results → CSV test case deliverable. Auto-loaded by delivery command.'
+user-invocable: false
+---
+
+## Purpose
+
+Export test cases from Sungen screens to a standardized CSV file (format BM-2-901-13) for QA delivery.
+
+**This skill delegates all heavy work to the `sungen delivery` CLI.** The CLI is the single source of truth for parsing logic — do NOT re-parse files in AI. Your role is only to:
+
+1. Invoke the CLI
+2. Show its output verbatim
+3. Help the user react to pre-flight failures
+
+---
+
+## Architecture
+
+```
+User → /sungen:delivery [screen...]
+       │
+       ▼
+  sungen delivery CLI  (deterministic — no AI tokens)
+  ├─ Scope detection (no-arg = all screens)
+  ├─ Pre-flight source checks per screen
+  ├─ Parse .feature (metadata)
+  ├─ Parse .spec.ts (resolved Playwright code — source of truth)
+  ├─ Parse test-data.yaml (resolve {{vars}})
+  ├─ Parse test-results/results.json (match test titles)
+  ├─ Merge sources + generate CSV rows
+  └─ Write qa/deliverables/<screen>-testcases.csv
+```
+
+Source modules: `src/exporters/*.ts`
+
+---
+
+## Required sources (CLI pre-flight checks these)
+
+| # | Source | Path | Created by |
+|---|--------|------|------------|
+| 1 | Feature file | `qa/screens/<screen>/features/<screen>.feature` | `/sungen:add-screen` + `/sungen:create-test` |
+| 2 | Test data | `qa/screens/<screen>/test-data/<screen>.yaml` | `/sungen:create-test` |
+| 3 | Selectors | `qa/screens/<screen>/selectors/<screen>.yaml` | `/sungen:run-test` |
+| 4 | Compiled spec | `specs/generated/<screen>/<screen>.spec.ts` | `sungen generate` (during `/sungen:run-test`) |
+| 5 | Test results | `specs/generated/<screen>/<screen>-test-result.json` (per-screen) or `test-results/results.json` (global fallback) | `/sungen:run-test` |
+
+**Sources 1-4 are blocking** — CLI aborts if any is missing.
+**Source 5 is optional** — CSV is still generated but Test Result/Date/Executor/Env columns are empty (all tests show as Pending).
+
+The CLI reads the **per-screen result file first** (co-located with `.spec.ts`), then falls back to the global `test-results/results.json`. Per-screen is preferred because the global file gets OVERWRITTEN each time Playwright runs, losing results from earlier screens.
+
+---
+
+## Column mapping (handled by CLI)
+
+| CSV Column | Source |
+|------------|--------|
+| TC ID | Generated: `<SCREEN_UPPER>-<VP>-<NNN>` |
+| Category 1 | Scenario name with VP prefix stripped |
+| Category 2 | VP group: `VP-SEC`→Accessing, `VP-UI`→GUI, `VP-VAL`/`VP-LOGIC`→Function |
+| Category 3 | Feature name (first line of `.feature`) |
+| Category 4 | Screen name |
+| Pre-condition | Auth tag → "Logged in as X" / "Not authenticated" + Given steps (natural language) |
+| Test Data | `{{vars}}` from scenario resolved via test-data.yaml → `key: value; key2: value2` |
+| Steps | `.spec.ts` code comments for interactions (numbered) |
+| Expected results | `.spec.ts` `expect(...)` comments (numbered) |
+| Priority | Tag: `@critical`/`@high`/`@normal`/`@low` (default: Normal) |
+| Testcase type | `@manual` → Manual, else Auto. Not compiled → "Not compiled" |
+| Test Result | results.json status: passed→Passed, failed/timedOut→Failed, skipped→N/A, else Pending |
+| Executed Date | results.json startTime formatted as `dd/mm/yyyy` |
+| Test Executor | `git config user.name` |
+| Test Environment | `playwright.config.ts` baseURL + project name |
+| Note | Error message + trace path (for failed tests) |
+
+---
+
+## Excluded from CSV
+
+- `@steps:<name>` **base** scenarios — these are setup-only, inlined into `@extend:...` scenarios at compile time
+- Default scaffold `Sample scenario for <screen>` — not a real test
+
+---
+
+## CLI command reference
+
+```bash
+# Export all screens
+sungen delivery
+
+# Export specific screens
+sungen delivery kudos awards
+
+# Skip pre-flight (CI only)
+sungen delivery --skip-preflight
+
+# Skip screens with blocking misses
+sungen delivery --continue-on-missing
+```
+
+Output: `qa/deliverables/<screen>-testcases.csv` (UTF-8 with BOM)

package/src/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/src/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/src/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).