@sun-asterisk/sungen 2.2.2 → 2.2.3

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

@@ -4,13 +4,34 @@ description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Auto-
 user-invocable: false
 ---
 
-## Step Patterns (65 patterns)
+## Standard Syntax
+
+```
+[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
+```
+
+- **Actor**: Always `User`, always active voice.
+- **Value**: `with {{snake_case}}` — never hardcode static data.
+- **State**: `is <keyword>` — never use `{{}}` for states.
+
+## Keyword → Action Rules
+
+```
+GIVEN  →  is on
+WHEN   →  click · fill · select · press · clear · check · uncheck · hover
+         [⚠️ wait for — only for Spinner/Modal, minimize usage]
+THEN   →  see
+AND    →  inherits from preceding keyword
+```
+
+## Step Patterns (70 patterns)
 
 ### Setup
 
 ```
 User is on [T] page                              # navigate to page
 User is on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
+User is on [T] dialog                            # enter dialog scope
 User is logged in | is not logged in              # auth state
 ```
 
@@ -18,31 +39,57 @@ User is logged in | is not logged in              # auth state
 
 ```
 User fill [T] field with {{v}}                   # text input
+User fill [T] textarea with {{v}}                # multiline input
+User fill [T] search with {{v}}                  # search input
+User fill [T] slider with {{v}}                  # set slider value
+User fill [T] date picker with {{v}}             # date input
 User clear [T] field                             # clear input
 User check [T] checkbox                          # check
+User check [T] toggle                            # toggle on (same as check)
+User check [T] radio                             # select radio
 User uncheck [T] checkbox                        # uncheck
+User uncheck [T] toggle                          # toggle off
 User select [T] dropdown with {{v}}              # select option
-User toggle [T] switch                           # toggle switch/checkbox
-User upload [T] file with {{f}}                  # file upload
+User upload [T] uploader with {{f}}              # file upload
 ```
 
 ### Interaction
 
 ```
-User click [T] button                            # click
-User click [T] button with {{v}}                 # click with text match
+User click [T] button                            # click (static element, no value)
+User click [T] row with {{v}}                    # click dynamic list item (row/item/card/option)
+User click [T] tab                               # switch tab
+User click [T] column                            # sort column
+User click [T] breadcrumb                        # navigate breadcrumb
 User double click [T] element                    # double click
-User hover [T] icon                              # hover
+User hover [T] icon                              # hover (must have see/click after)
+User hover [T] row                               # hover row for hidden actions
 User drag [T] to [T2]                            # drag and drop
 User expand [T] row                              # expand (aria-expanded)
 User collapse [T] row                            # collapse (aria-expanded)
 ```
 
+#### click + with {{Value}} rule
+
+- **NO value** for static elements: `button`, `link`, `icon`, `tab`, `toggle`
+- **WITH value** only for dynamic lists: `row`, `item`, `card`, `option`
+
+### Browser Alert (system dialog)
+
+```
+User click [OK] alert                            # accept (OK/Accept/Yes/Confirm)
+User click [Cancel] alert                        # dismiss (Cancel/Dismiss/No)
+User fill [T] alert with {{v}}                   # fill prompt + accept
+User see [message text] alert                    # assert dialog message
+```
+
+> Alert steps must appear BEFORE the action that triggers the dialog.
+
 ### Keyboard
 
 ```
-User press Escape key                            # global key press
-User press Enter on [T] field                    # key on element
+User press [Escape] key                          # global key press
+User press [Enter] on [T] field                  # key on element
 ```
 
 ### Wait
@@ -53,26 +100,51 @@ User wait for [T] dialog                         # wait for element
 User wait for [T] dialog is STATE                # wait for state
 User wait for [T] dialog with {{v}}              # wait for element with text
 User wait for [T] page                           # wait for navigation
+User wait for [T] message                        # wait for toast/feedback
+User wait for [T] button                         # wait for button to appear
 ```
 
 ### Scroll & Frame
 
 ```
 User scroll to [T] section                       # scroll into view
-User switch to [T] frame                         # enter/exit iframe
+User switch to [T] frame                         # enter iframe
+User switch to [main] frame                      # exit iframe
 ```
 
-### Assertions
+### Assertions (6 verify patterns)
 
 ```
-User see [T] page                                # URL assertion
-User see [T] heading                             # visibility
-User see [T] heading with {{v}}                  # visibility + text
+# 1. Visibility
+User see [T] message                             # visible (default)
+User see [T] modal is hidden                     # hidden
+
+# 2. Text Content (exact full match — toHaveText)
+User see [T] message with {{v}}                  # exact text match
+User see [T] header with {{v}}                   # heading text
+User see [T] label with {{v}}                    # label text
+
+# 3. Partial Text Match (toContainText)
 User see [T] text contains {{v}}                 # partial text match
-User see [T] text has text {{v}}                 # exact text match
-User see [T] button is STATE                     # state assertion
-User see [T] dialog with {{v}} is STATE          # text + state
-User see {{v}}                                   # see data text
+
+# 4. Input Value (toHaveValue)
+User see [T] field with {{v}}                    # input value
+User see [T] dropdown with {{v}}                 # selected value
+User see [T] date picker with {{v}}              # date value
+User see [T] search with {{v}}                   # search input value
+User see [T] slider with {{v}}                   # slider value
+
+# 5. Component State
+User see [T] button is disabled                  # state assertion
+User see [T] checkbox is checked                 # checked state
+User see [T] toggle is unchecked                 # unchecked state
+User see [T] dialog with {{v}} is hidden         # text + state combined
+
+# 6. Count
+User see [T] row with {{count}}                  # element count
+
+# 7. Page Context
+User see [T] page                                # URL assertion
 ```
 
 ### Table
@@ -94,12 +166,45 @@ User click [Act] in [Table] table row with {{f}}             # action in row
 
 ### Element Types
 
-`page` `button` `link` `field` `textarea` `heading` `text` `checkbox` `radio` `switch` `dropdown` `dialog` `modal` `menu` `menuitem` `tab` `tabpanel` `table` `row` `cell` `list` `listitem` `icon` `image` `alert` `spinner` `progressbar` `section` `region` `nav` `frame` `uploader` `file` `columnheader` `tooltip` `slider` `treeitem`
+| Group | Types |
+|---|---|
+| **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` |
+| **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` |
+| **Trigger** | `button` `link` `icon` `menuitem` `tag` |
+| **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` |
+| **Feedback** | `message` `header` `label` `text` `tooltip` `badge` `breadcrumb` `image` |
+| **System** | `key` `frame` `spinner` `progressbar` |
+
+### Auto-infer (no YAML entry needed)
+
+| Gherkin | Playwright locator |
+|---|---|
+| `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
+| `[Home] link` | `getByRole('link', { name: 'Home' })` |
+| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Email] field` | `getByPlaceholder('Email')` |
+| `[Success] text` / `message` / `label` | `getByText('Success')` |
+| `[Terms] checkbox` | `getByRole('checkbox', { name: 'Terms' })` |
+| `[Male] radio` | `getByRole('radio', { name: 'Male' })` |
+| `[Global] search` | `getByRole('searchbox', { name: 'Global' })` |
+| `[Vietnam] option` | `getByRole('option', { name: 'Vietnam' })` |
+| `[Price] slider` | `getByRole('slider', { name: 'Price' })` |
+| `[Notification] toggle` | `getByRole('switch', { name: 'Notification' })` |
+| `[Profile] tab` | `getByRole('tab', { name: 'Profile' })` |
+| `[Orders] table` | `getByRole('table', { name: 'Orders' })` |
+| `[Products] list` | `getByRole('list', { name: 'Products' })` |
+| `[Name] column` | `getByRole('columnheader', { name: 'Name' })` |
+| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
 
 ## YAML Keys
 
 `[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
 
+- Keys use **spaces** (not dots) as word separators
+- Same label, different element types → add `--type` suffix
+- Same label, nth occurrence → add `--N` suffix
+- Target Name > 30 chars → shorten to 1–3 meaningful words
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -120,8 +225,30 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@auto` | Standard scenario, ready for automation |
+| `@manual` | Skip in generation |
+| `@smoke` / `@regression` | Test suite grouping |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
-| `@steps:name` | Define reusable step block |
-| `@extend:name` | Prepend steps from @steps block |
-| `@manual` | Skip in generation |
+| `@steps:name` | Define reusable step block (base scenario) |
+| `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+
+### @extend behavior
+
+- Tool executes **only Given→When** of `@steps` scenario (skips Then)
+- The `Given` in `@extend` scenario is the **entry assertion** (confirms state after base steps)
+- If `@steps` scenario fails, `@extend` scenario is **skipped**
+- Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`
+
+## Common Syntax Errors
+
+| Error | Wrong | Correct |
+|---|---|---|
+| Wrong keyword | `Given User click [T] button` | `When User click [T] button` |
+| Wrong action for type | `When User click [T] checkbox` | `When User check [T] checkbox` |
+| press wrong target | `When User press [Submit] button` | `When User press [Enter] key` |
+| uncheck radio | `When User uncheck [Male] radio` | `When User check [Female] radio` |
+| Hardcode data | `with {{admin@mail.com}}` | `with {{invalid_email}}` |
+| 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}}` |

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

@@ -168,9 +168,16 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 |---|---|
 | `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
 | `[Home] link` | `getByRole('link', { name: 'Home' })` |
-| `[Welcome] heading` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
 | `[Email] field` | `getByPlaceholder('Email')` |
-| `[Success] text` | `getByText('Success')` |
+| `[Success] text` / `message` / `label` | `getByText('Success')` |
+| `[Terms] checkbox` | `getByRole('checkbox', { name: 'Terms' })` |
+| `[Global] search` | `getByRole('searchbox', { name: 'Global' })` |
+| `[Vietnam] option` | `getByRole('option', { name: 'Vietnam' })` |
+| `[Price] slider` | `getByRole('slider', { name: 'Price' })` |
+| `[Notification] toggle` | `getByRole('switch', { name: 'Notification' })` |
+| `[Profile] tab` | `getByRole('tab', { name: 'Profile' })` |
+| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
 
 **Only add a YAML entry when auto-infer won't work:**
 - The accessible name differs from the Gherkin label
@@ -181,19 +188,52 @@ Many elements don't need a YAML entry — sungen auto-infers from the Gherkin la
 
 ---
 
-### Fix Loop on Test Failure
+### Fix Loop on Test Failure (Batched Strategy)
 
+Running all tests every iteration is slow. Use a batched approach to fix faster:
+
+```
+1. INITIAL RUN — run ALL tests, collect full failure list
+     npx playwright test <spec> --reporter=line
+
+2. BATCHED FIX LOOP (max 5 attempts):
+     a. Read test output → group failures by root cause:
+        - Same selector broken → 1 fix covers many tests
+        - Same error type (strict mode, timeout, text mismatch)
+     b. Fix selectors.yaml or test-data.yaml for current batch
+     c. Recompile: sungen generate --screen <screen>
+     d. Re-run ONLY previously-failing tests (max 20):
+        npx playwright test <spec> --grep "VP-UI-001|VP-UI-002|VP-VAL-001" --reporter=line
+     e. If batch passes → pick next batch of remaining failures
+     f. If batch still fails → fix and retry (counts toward max 5)
+
+3. FINAL CONFIRMATION — run ALL tests once:
+     npx playwright test <spec> --reporter=line
+     This catches regressions from selector changes.
+
+4. If still failing after 5 fix attempts → ask user about direct .spec.ts fix
 ```
-attempt = 0
-while attempt < 5:
-    compile → run test
-    if pass → done
-    read error-context.md in test-results/ → check exact snapshot state at failure time
-    fix selectors.yaml or test-data.yaml
-    recompile → attempt++
-if still failing → ask user about direct .spec.ts fix
+
+#### Building the `--grep` pattern
+
+Extract scenario names from the failure output and join with `|`:
+```bash
+# Example: re-run only 3 failing tests
+npx playwright test <spec> --grep "VP-VAL-001|VP-VAL-002|VP-VAL-003" --reporter=line
 ```
 
+- Max 20 test names per `--grep` to keep the pattern manageable
+- If >20 failures share the same root cause, fix the cause and run the first 20 to verify
+
+#### Grouping failures by root cause
+
+Common patterns where 1 fix resolves many failures:
+- **Same selector** — e.g., all `[Email Error]` tests fail → fix `email error` in selectors.yaml once
+- **Same error type** — e.g., all `strict mode violation` → add `exact: true` or `nth`
+- **Same assertion** — e.g., all `toHaveText` on inputs fail → change Gherkin pattern (inputs have no text)
+
+Fix the root cause first, verify with the batch, then move on.
+
 **Always read the error context snapshot first** — it shows the exact page state when the test failed, which is more reliable than re-navigating with MCP.
 
 ---

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

@@ -51,6 +51,10 @@ Type aliases (normalized automatically):
 | logo, image, icon | `img` |
 | btn | `button` |
 | input, textbox, textarea, editor | `field` |
+| search | `searchbox` |
+| toggle | `switch` |
+| alert | `alertdialog` |
+| modal, drawer | `dialog` |
 | column | `columnheader` |
 | list-item | `listitem` |
 
@@ -83,10 +87,20 @@ If no YAML key exists, the resolver infers from the Gherkin element type:
 |---|---|
 | `[X] button` | `getByRole('button', { name: 'X' })` |
 | `[X] link` | `getByRole('link', { name: 'X' })` |
-| `[X] heading` | `getByRole('heading', { name: 'X' })` |
+| `[X] heading` / `header` | `getByRole('heading', { name: 'X' })` |
 | `[X] checkbox` | `getByRole('checkbox', { name: 'X' })` |
+| `[X] radio` | `getByRole('radio', { name: 'X' })` |
 | `[X] field` | `getByPlaceholder('X')` |
-| `[X] text` | `getByText('X')` |
+| `[X] text` / `message` / `label` | `getByText('X')` |
 | `[X] logo/image/icon` | `getByRole('img', { name: 'X' })` |
+| `[X] search` | `getByRole('searchbox', { name: 'X' })` |
+| `[X] option` | `getByRole('option', { name: 'X' })` |
+| `[X] slider` | `getByRole('slider', { name: 'X' })` |
+| `[X] toggle` | `getByRole('switch', { name: 'X' })` |
+| `[X] tab` | `getByRole('tab', { name: 'X' })` |
+| `[X] table` | `getByRole('table', { name: 'X' })` |
+| `[X] list` | `getByRole('list', { name: 'X' })` |
+| `[X] column` | `getByRole('columnheader', { name: 'X' })` |
+| `[X] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'X' })` |
 
 **Only add a YAML entry when** the auto-inferred locator won't work (wrong name, need testid, need nth, etc.).

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

@@ -21,7 +21,14 @@ You are a **Senior Developer** specialized in Playwright test debugging. You gen
 1. Verify `qa/screens/${input:screen}/` has `.feature` + `test-data.yaml`. If not → run `/sungen-make-tc` first.
 2. Explore live page via #tool:playwright to generate `selectors.yaml` (per `sungen-selector-fix` skill).
 3. Compile with #tool:terminal: `sungen generate --screen ${input:screen}`
-4. Run with #tool:terminal: `npx playwright test specs/generated/${input:screen}/*.spec.ts`
-5. If fail → fix selectors/test-data per `sungen-selector-fix` + `sungen-error-mapping` skills, retry (max 5).
-6. After 5 fails → ask user about direct `.spec.ts` fix.
-7. Show: pass/fail, attempt count, files changed.
+4. **Initial run** — run ALL tests to get the full failure picture:
+   `npx playwright test specs/generated/${input:screen}/*.spec.ts --reporter=line`
+5. **Batched fix loop** (max 5 attempts) — see `sungen-selector-fix` skill for details:
+   - Group failures by root cause (same selector, same error type)
+   - Fix selectors/test-data for the current batch
+   - Recompile, then re-run ONLY the previously-failing tests (max 20 at a time via `--grep`)
+   - If the batch passes, pick the next batch of remaining failures
+   - Repeat until no failures remain or max attempts reached
+6. **Final confirmation** — run ALL tests once to ensure no regressions.
+7. After 5 fix attempts still failing → ask user about direct `.spec.ts` fix.
+8. Show: pass/fail, attempt count, files changed.

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-error-mapping.md

@@ -6,16 +6,29 @@ user-invocable: false
 
 ## Playwright Errors → Fix
 
-| Error | Fix in `selectors.yaml` |
+| Error | Fix |
 |---|---|
-| strict mode violation | add `nth`, `exact: true`, or specific `name` |
-| Element is not an input | change `type` or `value` |
-| Timeout waiting for selector | fix `type`/`value`/`name` to match element |
-| toBeVisible Timeout | verify accessible name or use `testid` |
-| toHaveText mismatch | fix in `test-data.yaml` |
-| Navigation failed | fix page `value` path |
-| not a select | set `variant: 'custom'` |
-| Frame not found | fix `frame` value |
+| strict mode violation | add `nth`, `exact: true`, or specific `name` in selectors.yaml |
+| Element is not an input | change `type` or `value` in selectors.yaml |
+| Timeout waiting for selector | fix `type`/`value`/`name` to match element in selectors.yaml |
+| toBeVisible Timeout | verify accessible name or use `testid` in selectors.yaml |
+| toHaveText mismatch | fix expected text in `test-data.yaml` — OR if element is an input (field/textarea/search/dropdown), change Gherkin type so compiler uses `toHaveValue` instead |
+| toHaveValue mismatch | fix expected value in `test-data.yaml` — this is for input elements (field, textarea, search, dropdown, slider, date-picker) |
+| toContainText mismatch | fix expected partial text in `test-data.yaml` |
+| Navigation failed | fix page `value` path in selectors.yaml |
+| not a select | set `variant: 'custom'` in selectors.yaml |
+| Frame not found | fix `frame` value in selectors.yaml |
+| dialog was dismissed | alert step is AFTER the trigger — move `click [OK] alert` BEFORE the button click that opens the dialog |
+| page.once('dialog') never fired | no browser dialog appeared — check if the action actually triggers a `window.alert/confirm/prompt`, not a CSS modal |
+
+### Assertion type mismatch (toHaveText vs toHaveValue)
+
+Sungen picks the assertion based on element type:
+- **Input types** (`field`, `textarea`, `search`, `dropdown`, `slider`, `date-picker`) → `toHaveValue()`
+- **Text types** (everything else: `message`, `header`, `label`, `row`, etc.) → `toHaveText()`
+- **Partial match** (uses `contains` keyword) → `toContainText()`
+
+If you see `toHaveText` failing on an input element, the Gherkin step has the wrong target type. Fix: change the target type in the `.feature` file (e.g., `see [Email] message with {{v}}` → `see [Email] field with {{v}}`).
 
 ## Auth Errors → Fix
 

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md

@@ -4,13 +4,34 @@ description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use t
 user-invocable: false
 ---
 
-## Step Patterns (65 patterns)
+## Standard Syntax
+
+```
+[Keyword] User <Action> [Target Name] <Target Type> <with {{Value}}> <is State>
+```
+
+- **Actor**: Always `User`, always active voice.
+- **Value**: `with {{snake_case}}` — never hardcode static data.
+- **State**: `is <keyword>` — never use `{{}}` for states.
+
+## Keyword → Action Rules
+
+```
+GIVEN  →  is on
+WHEN   →  click · fill · select · press · clear · check · uncheck · hover
+         [⚠️ wait for — only for Spinner/Modal, minimize usage]
+THEN   →  see
+AND    →  inherits from preceding keyword
+```
+
+## Step Patterns (70 patterns)
 
 ### Setup
 
 ```
 User is on [T] page                              # navigate to page
 User is on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
+User is on [T] dialog                            # enter dialog scope
 User is logged in | is not logged in              # auth state
 ```
 
@@ -18,31 +39,57 @@ User is logged in | is not logged in              # auth state
 
 ```
 User fill [T] field with {{v}}                   # text input
+User fill [T] textarea with {{v}}                # multiline input
+User fill [T] search with {{v}}                  # search input
+User fill [T] slider with {{v}}                  # set slider value
+User fill [T] date picker with {{v}}             # date input
 User clear [T] field                             # clear input
 User check [T] checkbox                          # check
+User check [T] toggle                            # toggle on (same as check)
+User check [T] radio                             # select radio
 User uncheck [T] checkbox                        # uncheck
+User uncheck [T] toggle                          # toggle off
 User select [T] dropdown with {{v}}              # select option
-User toggle [T] switch                           # toggle switch/checkbox
-User upload [T] file with {{f}}                  # file upload
+User upload [T] uploader with {{f}}              # file upload
 ```
 
 ### Interaction
 
 ```
-User click [T] button                            # click
-User click [T] button with {{v}}                 # click with text match
+User click [T] button                            # click (static element, no value)
+User click [T] row with {{v}}                    # click dynamic list item (row/item/card/option)
+User click [T] tab                               # switch tab
+User click [T] column                            # sort column
+User click [T] breadcrumb                        # navigate breadcrumb
 User double click [T] element                    # double click
-User hover [T] icon                              # hover
+User hover [T] icon                              # hover (must have see/click after)
+User hover [T] row                               # hover row for hidden actions
 User drag [T] to [T2]                            # drag and drop
 User expand [T] row                              # expand (aria-expanded)
 User collapse [T] row                            # collapse (aria-expanded)
 ```
 
+#### click + with {{Value}} rule
+
+- **NO value** for static elements: `button`, `link`, `icon`, `tab`, `toggle`
+- **WITH value** only for dynamic lists: `row`, `item`, `card`, `option`
+
+### Browser Alert (system dialog)
+
+```
+User click [OK] alert                            # accept (OK/Accept/Yes/Confirm)
+User click [Cancel] alert                        # dismiss (Cancel/Dismiss/No)
+User fill [T] alert with {{v}}                   # fill prompt + accept
+User see [message text] alert                    # assert dialog message
+```
+
+> Alert steps must appear BEFORE the action that triggers the dialog.
+
 ### Keyboard
 
 ```
-User press Escape key                            # global key press
-User press Enter on [T] field                    # key on element
+User press [Escape] key                          # global key press
+User press [Enter] on [T] field                  # key on element
 ```
 
 ### Wait
@@ -53,26 +100,51 @@ User wait for [T] dialog                         # wait for element
 User wait for [T] dialog is STATE                # wait for state
 User wait for [T] dialog with {{v}}              # wait for element with text
 User wait for [T] page                           # wait for navigation
+User wait for [T] message                        # wait for toast/feedback
+User wait for [T] button                         # wait for button to appear
 ```
 
 ### Scroll & Frame
 
 ```
 User scroll to [T] section                       # scroll into view
-User switch to [T] frame                         # enter/exit iframe
+User switch to [T] frame                         # enter iframe
+User switch to [main] frame                      # exit iframe
 ```
 
-### Assertions
+### Assertions (6 verify patterns)
 
 ```
-User see [T] page                                # URL assertion
-User see [T] heading                             # visibility
-User see [T] heading with {{v}}                  # visibility + text
+# 1. Visibility
+User see [T] message                             # visible (default)
+User see [T] modal is hidden                     # hidden
+
+# 2. Text Content (exact full match — toHaveText)
+User see [T] message with {{v}}                  # exact text match
+User see [T] header with {{v}}                   # heading text
+User see [T] label with {{v}}                    # label text
+
+# 3. Partial Text Match (toContainText)
 User see [T] text contains {{v}}                 # partial text match
-User see [T] text has text {{v}}                 # exact text match
-User see [T] button is STATE                     # state assertion
-User see [T] dialog with {{v}} is STATE          # text + state
-User see {{v}}                                   # see data text
+
+# 4. Input Value (toHaveValue)
+User see [T] field with {{v}}                    # input value
+User see [T] dropdown with {{v}}                 # selected value
+User see [T] date picker with {{v}}              # date value
+User see [T] search with {{v}}                   # search input value
+User see [T] slider with {{v}}                   # slider value
+
+# 5. Component State
+User see [T] button is disabled                  # state assertion
+User see [T] checkbox is checked                 # checked state
+User see [T] toggle is unchecked                 # unchecked state
+User see [T] dialog with {{v}} is hidden         # text + state combined
+
+# 6. Count
+User see [T] row with {{count}}                  # element count
+
+# 7. Page Context
+User see [T] page                                # URL assertion
 ```
 
 ### Table
@@ -94,12 +166,45 @@ User click [Act] in [Table] table row with {{f}}             # action in row
 
 ### Element Types
 
-`page` `button` `link` `field` `textarea` `heading` `text` `checkbox` `radio` `switch` `dropdown` `dialog` `modal` `menu` `menuitem` `tab` `tabpanel` `table` `row` `cell` `list` `listitem` `icon` `image` `alert` `spinner` `progressbar` `section` `region` `nav` `frame` `uploader` `file` `columnheader` `tooltip` `slider` `treeitem`
+| Group | Types |
+|---|---|
+| **Context** | `page` `dialog` `modal` `drawer` `tab` `alert` `overlay` `step` |
+| **Input** | `field` `textarea` `search` `dropdown` `option` `checkbox` `radio` `toggle` `uploader` `slider` `date-picker` |
+| **Trigger** | `button` `link` `icon` `menuitem` `tag` |
+| **Data** | `table` `row` `column` `cell` `list` `item` `card` `section` |
+| **Feedback** | `message` `header` `label` `text` `tooltip` `badge` `breadcrumb` `image` |
+| **System** | `key` `frame` `spinner` `progressbar` |
+
+### Auto-infer (no YAML entry needed)
+
+| Gherkin | Playwright locator |
+|---|---|
+| `[Submit] button` | `getByRole('button', { name: 'Submit' })` |
+| `[Home] link` | `getByRole('link', { name: 'Home' })` |
+| `[Welcome] heading` / `header` | `getByRole('heading', { name: 'Welcome' })` |
+| `[Email] field` | `getByPlaceholder('Email')` |
+| `[Success] text` / `message` / `label` | `getByText('Success')` |
+| `[Terms] checkbox` | `getByRole('checkbox', { name: 'Terms' })` |
+| `[Male] radio` | `getByRole('radio', { name: 'Male' })` |
+| `[Global] search` | `getByRole('searchbox', { name: 'Global' })` |
+| `[Vietnam] option` | `getByRole('option', { name: 'Vietnam' })` |
+| `[Price] slider` | `getByRole('slider', { name: 'Price' })` |
+| `[Notification] toggle` | `getByRole('switch', { name: 'Notification' })` |
+| `[Profile] tab` | `getByRole('tab', { name: 'Profile' })` |
+| `[Orders] table` | `getByRole('table', { name: 'Orders' })` |
+| `[Products] list` | `getByRole('list', { name: 'Products' })` |
+| `[Name] column` | `getByRole('columnheader', { name: 'Name' })` |
+| `[Confirm] dialog` / `modal` / `drawer` | `getByRole('dialog', { name: 'Confirm' })` |
 
 ## YAML Keys
 
 `[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
 
+- Keys use **spaces** (not dots) as word separators
+- Same label, different element types → add `--type` suffix
+- Same label, nth occurrence → add `--N` suffix
+- Target Name > 30 chars → shorten to 1–3 meaningful words
+
 ## Selectors (priority order)
 
 | type | value | name | use |
@@ -120,8 +225,30 @@ Options: `nth` `exact` `scope` `match` `variant` `frame` `contenteditable` `colu
 
 | Tag | Effect |
 |---|---|
+| `@auto` | Standard scenario, ready for automation |
+| `@manual` | Skip in generation |
+| `@smoke` / `@regression` | Test suite grouping |
 | `@auth:role` | Use auth storage state for role |
 | `@no-auth` | Disable inherited auth |
-| `@steps:name` | Define reusable step block |
-| `@extend:name` | Prepend steps from @steps block |
-| `@manual` | Skip in generation |
+| `@steps:name` | Define reusable step block (base scenario) |
+| `@extend:name` | Prepend Given→When from @steps block (skip Then) |
+
+### @extend behavior
+
+- Tool executes **only Given→When** of `@steps` scenario (skips Then)
+- The `Given` in `@extend` scenario is the **entry assertion** (confirms state after base steps)
+- If `@steps` scenario fails, `@extend` scenario is **skipped**
+- Name format: `snake_case` or `kebab-case` with module prefix: `@steps:kudos__open_modal`
+
+## Common Syntax Errors
+
+| Error | Wrong | Correct |
+|---|---|---|
+| Wrong keyword | `Given User click [T] button` | `When User click [T] button` |
+| Wrong action for type | `When User click [T] checkbox` | `When User check [T] checkbox` |
+| press wrong target | `When User press [Submit] button` | `When User press [Enter] key` |
+| uncheck radio | `When User uncheck [Male] radio` | `When User check [Female] radio` |
+| Hardcode data | `with {{admin@mail.com}}` | `with {{invalid_email}}` |
+| 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}}` |