@sun-asterisk/sungen 2.1.1 → 2.2.1

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

@@ -0,0 +1,256 @@
+---
+name: sungen-tc-generation
+description: 'Exhaustive test case generation strategy — section-focused, 20+ scenarios per viewpoint per section, Gherkin + test-data only, no selectors. Auto-loaded by make-tc command.'
+user-invocable: false
+---
+
+## Test Case Generation Strategy
+
+### Goal
+
+Generate **focused, high-quality test cases per screen section** with **at least 20 scenarios per viewpoint category**. Output only `.feature` and `test-data.yaml` — selectors are deferred to `/sungen:make-test`.
+
+### Update Mode (existing test cases)
+
+When the `.feature` file already has scenarios, read it first and summarize what exists:
+
+> This screen already has **57 scenarios**:
+> - Section: Filters & Search — 22 scenarios (UI: 7, VAL: 8, LOGIC: 5, SEC: 2)
+> - Section: User Table — 23 scenarios (UI: 13, LOGIC: 11, SEC: 3)
+> - Section: Pagination — 12 scenarios (UI: 4, LOGIC: 6, SEC: 2)
+>
+> What would you like to do?
+> 1. **Add new sections** — keep existing, add tests for uncovered sections
+> 2. **Add viewpoints to existing sections** — e.g., more edge cases, more security tests
+> 3. **Replace all** — start fresh
+
+For options 1 and 2:
+- Read the existing scenarios to understand current coverage and the highest `VP-<CAT>-<NNN>` number
+- Continue numbering from the next available number (e.g., if last is `VP-UI-024`, start at `VP-UI-025`)
+- **Append** new scenarios to the end of the relevant section — never modify or delete existing scenarios
+- Merge new test-data variables into `test-data.yaml` without overwriting existing ones
+
+For option 3:
+- Overwrite both `.feature` and `test-data.yaml` completely
+
+### Page Exploration & Auth
+
+Use Playwright MCP to explore the live page. If the page requires authentication:
+1. `browser_navigate` to `baseURL` (from `playwright.config.ts`)
+2. If redirected to login, ask the user to log in manually:
+   > "This page requires login. Please log in using the browser. Confirm when you're done."
+3. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
+
+### Single Screen Focus
+
+**One screen = one URL path.** Only generate test cases for elements visible on the target page.
+
+- Navigate to the target screen path — do NOT explore sibling paths (e.g., testing `/admin/users` should not scan `/admin/review`)
+- Take ONE snapshot of the target page — do not click links to navigate away
+- If a link goes to a different path, test only that the link is visible and clickable — the destination page is a SEPARATE screen
+- If a modal/dialog opens on the same page, that IS part of this screen
+- Each screen gets its own `qa/screens/<name>/` directory — never mix screens
+
+#### Detail screens with dynamic IDs
+
+For screens like `/admin/users/:id` or `/products/:slug`:
+1. Navigate to the **list page** first via MCP browser to find a real record ID
+2. Use that ID in the page selector value
+3. Use `User is on [X] page` — sungen resolves the path from the selector
+
+```yaml
+# selectors.yaml — full path with real ID (generated during make-test)
+user detail:
+  type: 'page'
+  value: '/admin/users/de42d800-0f5a-490e-9dcf-344fedbd34a5'
+```
+
+```gherkin
+Scenario: VP-UI-001 User detail displays name
+  Given User is on [User Detail] page
+  And User wait for [User Name] heading is visible
+  Then User see [User Name] heading with {{user_name}}
+```
+
+Note: the selector uses a hardcoded ID from the live page. If the record is deleted, update the ID in `selectors.yaml`.
+
+### Section-Focused Approach
+
+After exploring the page, identify distinct **sections** based on common UI patterns. Present them as a numbered list and ask the user which to focus on.
+
+#### Common Section Patterns
+
+Identify which patterns exist on the screen:
+
+| Pattern | Elements to look for |
+|---|---|
+| **Header / Navigation** | Logo, nav links, breadcrumbs, user menu, notifications, language selector |
+| **Form** | Input fields, dropdowns, checkboxes, radio buttons, date pickers, file uploads, submit/cancel buttons |
+| **Data Table** | Column headers, sortable columns, row data, row actions, bulk actions, column filters |
+| **Search & Filters** | Search input, filter dropdowns, clear/reset, active filter tags |
+| **Card Grid / List** | Cards with title/image/description, load more, infinite scroll |
+| **Pagination** | Previous/next buttons, page numbers, page size selector, total count |
+| **Tabs / Accordion** | Tab headers, tab panels, expand/collapse |
+| **Modal / Dialog** | Open trigger, close button, form inside modal, confirmation dialog |
+| **Sidebar** | Stats, quick actions, related links, mini widgets |
+| **File Upload** | Drop zone, file picker, progress bar, file list, delete |
+| **Rich Text Editor** | Toolbar, content area, formatting buttons, preview |
+| **Carousel / Slider** | Prev/next arrows, dots/indicators, auto-play, swipe |
+
+Example output:
+
+> This screen has the following sections:
+> 1. Header (logo, navigation tabs, user menu)
+> 2. Create Form (name, email, role dropdown, department, submit)
+> 3. User Table (columns: name, email, status, actions; sortable, filterable)
+> 4. Pagination (previous/next, page indicator)
+>
+> Which sections do you want to create test cases for? (e.g., "2, 3" or "all")
+
+For each selected section, generate **20+ scenarios per applicable viewpoint**. Skip viewpoint categories that don't apply.
+
+Present a test plan summary and wait for user confirmation before generating files.
+
+### Viewpoint Categories
+
+| VP Category | Description |
+|---|---|
+| **UI/UX** | Default appearance, element visibility, default states |
+| **Validation** | Input validation, error messages, edge cases. **Must explore live page via MCP to capture actual error messages before writing tests. Use `User see {{error_var}}` pattern — never assert just "is visible".** |
+| **Logic** | Business logic, interactions, state changes |
+| **Security** | Auth guards, injection, permission checks |
+
+### Coverage Checklist per Section Pattern
+
+Apply the relevant checklist based on the section pattern:
+
+#### Form sections
+- **UI/UX**: All fields visible, labels correct, default values, placeholder text, required indicators
+- **Validation**: Empty submit, each required field empty, invalid format (email, phone, URL), min/max length, special chars, unicode, XSS, SQL injection, whitespace-only, boundary values — **assert exact error messages via `User see {{error_var}}`**, store texts in test-data.yaml
+- **Logic**: Successful submit, submit with all optional fields, edit existing record, cancel resets form, field dependencies (show/hide), auto-complete, date range validation
+- **Security**: CSRF protection, unauthorized submit, role-based field visibility, input sanitization
+
+#### Data Table sections
+- **UI/UX**: All columns visible, column headers, row data displays correctly, empty state, loading state, action buttons visible
+- **Validation**: N/A (read-only) or inline edit validation
+- **Logic**: Sort ascending/descending per sortable column, filter by each column, search within table, row action menu (edit/delete/view), bulk select, bulk action, row click navigation, column resize
+- **Security**: Cannot access other users' data, action permissions per role, data not exposed in DOM
+
+#### Search & Filter sections
+- **UI/UX**: Search field visible, filter buttons visible, clear button state
+- **Validation**: Empty search, special chars, SQL injection, XSS, very long text, unicode/emoji, whitespace, partial match, case insensitive
+- **Logic**: Apply single filter, combine multiple filters, clear single filter, clear all filters, search + filter combined, filter persists across pagination, no results state
+- **Security**: Injection via search, injection via filter params
+
+#### Pagination sections
+- **UI/UX**: Page indicator visible, previous disabled on page 1, next enabled
+- **Logic**: Next page, previous page, navigate to last page, boundary (first/last), page indicator updates, data refreshes on navigation
+- **Security**: Filters persist across pages, search persists, cannot access page beyond max
+
+#### Modal / Dialog sections
+- **UI/UX**: Modal opens, close button visible, overlay visible, form fields inside modal
+- **Validation**: Submit empty form in modal, field validation inside modal
+- **Logic**: Open modal, close with X, close with Escape, close with overlay click, submit success closes modal, submit error keeps modal open
+- **Security**: Cannot open unauthorized modals, CSRF on modal submit
+
+#### Card Grid / List sections
+- **UI/UX**: Cards display all expected fields (title, image, description, metadata), empty state, loading state
+- **Logic**: Click card navigates to detail, load more / infinite scroll, card action buttons (like, share, delete), responsive layout
+- **Security**: User-generated content sanitized, cannot access other users' cards
+
+#### Carousel / Slider sections
+- **UI/UX**: Arrows visible, indicators visible, current slide highlighted
+- **Logic**: Next slide, previous slide, wrap at end, auto-play, indicator click navigates, swipe gesture
+- **Security**: N/A
+
+#### Tabs / Accordion sections
+- **UI/UX**: All tabs visible, active tab highlighted, default tab selected
+- **Logic**: Switch tabs, content updates per tab, deep link to tab, accordion expand/collapse, only one accordion open at a time
+- **Security**: Tab content respects permissions
+
+### General Coverage Dimensions (aim for 20+ total per viewpoint)
+
+**Happy paths (3-5):** Standard flow, all optional fields, minimum required
+**Edge cases (5-8):** Empty, max length, special chars, unicode/CJK/emoji, whitespace, leading/trailing spaces, overflow
+**Boundary values (3-5):** At min/max limit, one above/below, zero/null
+**Negative cases (3-5):** Invalid format, missing required, wrong type, injection attempts
+**State transitions (2-4):** Before/after action, undo, cancel mid-flow
+**Combinatorial (2-4):** Multiple invalid fields, valid+invalid combos, different roles
+
+### SPA Wait-For Steps
+
+If the page is an SPA (Next.js, Nuxt, React Router, etc.), add a `wait for` step after navigation:
+
+```gherkin
+Given User is on [Screen] page
+And User wait for [Page Title] heading is visible
+```
+
+For scenarios needing dynamic data, add a second wait:
+
+```gherkin
+And User wait for [Data Element] button is visible
+```
+
+### Output Files
+
+**1. Feature file** — `qa/screens/<screen>/features/<screen>.feature`
+
+Group by section, then by viewpoint within each section:
+
+```gherkin
+@auth:role
+Feature: <Screen> Screen
+
+  # ============================================================
+  # Section: Create User Form
+  # ============================================================
+
+  # --- UI/UX (20+) ---
+
+  Scenario: VP-UI-001 Name field is visible
+    ...
+
+  # --- Validation (20+) ---
+
+  Scenario: VP-VAL-001 Submit with empty name
+    ...
+
+  # ============================================================
+  # Section: User Table
+  # ============================================================
+
+  # --- UI/UX (20+) ---
+
+  Scenario: VP-UI-025 Table displays all columns
+    ...
+```
+
+**Naming convention:** `VP-<CATEGORY>-<NNN>` prefix in Scenario name.
+
+**2. Test data file** — `qa/screens/<screen>/test-data/<screen>.yaml`
+
+Group variables by section:
+
+```yaml
+# ============================================================
+# Create User Form
+# ============================================================
+valid_name: 'John Doe'
+valid_email: 'john@example.com'
+empty_input: ''
+special_chars: '!@#$%^&*()'
+
+# ============================================================
+# User Table
+# ============================================================
+sort_column: 'Name'
+search_term: 'John'
+```
+
+### Do NOT Generate
+
+- `selectors.yaml` — this is created during `/sungen:make-test`
+- Playwright code — sungen compiles Gherkin to Playwright

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

@@ -1,41 +1,38 @@
 ---
-description: 'Add a new Sungen screen — scaffolds directories and delegates to make-tc for test case creation'
-mode: 'agent'
+name: sungen-add-screen
+description: 'Add a new Sungen screen — scaffolds directories and delegates to /sungen-make-tc for test case creation'
+argument-hint: '[screen-name] [url-path]'
+agent: 'agent'
 tools: ['terminal']
 ---
 
+**Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
+
 You are adding a new Sungen screen for test generation.
 
 ## Parameters
 
-Parse from user input:
-- **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
-- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`)
-
-If **screen** is missing, ask: "What is the screen name? (e.g., `login`, `dashboard`)"
-If **path** is missing, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+- **path** — ${input:path:URL path (e.g., /login, /dashboard)}
 
 ## Steps
 
 ### 1. Scaffold the screen
 
-Run in terminal:
+Run with #tool:terminal:
 ```bash
-sungen add --screen <screen> --path <path>
+sungen add --screen ${input:screen} --path ${input:path}
 ```
 
 ### 2. Create test cases
 
 Ask the user: "Would you like to create test cases now?"
 
-If yes, delegate to the `sungen-make-tc` prompt to handle:
-- Exploring the live page or analyzing static designs
-- Gathering test viewpoints (UI/UX, Validation, Logic, Security)
-- Generating the 3 files (feature, selectors, test-data)
+If yes, tell the user to run `/sungen-make-tc ${input:screen}`.
 
 ### 3. Confirm
 
 Tell the user what was created and next steps:
-- If the page requires authentication before exploring via browser, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>` (e.g., `sungen makeauth admin --url http://localhost:3000`). **Do NOT execute this command yourself.**
-- Edit the generated files as needed
-- Run `sungen generate --screen <screen>` to compile to Playwright `.spec.ts`
+- If the page requires authentication, the user will be asked to log in via the MCP browser during `/sungen-make-tc`
+- Run `/sungen-make-tc` to create test cases
+- Run `/sungen-make-test` to generate selectors, compile, and run tests

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

@@ -1,59 +1,28 @@
 ---
-description: 'Create test cases for a Sungen screen — gathers viewpoints, explores live page or static designs, generates feature/selectors/test-data files'
-mode: 'agent'
-tools: ['terminal', 'playwright']
+name: sungen-make-tc
+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.'
+argument-hint: '[screen-name]'
+agent: 'agent'
+tools: ['terminal', 'playwright/*']
 ---
 
+**Input**: Screen name (e.g., `/sungen-make-tc admin-users`).
+
 ## Role
 
-You are a **Senior QA Engineer** specialized in test case design. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-selector-keys` prompt rules.
+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-make-test`.
 
 ## Parameters
 
-Parse from user input:
-- **screen** — screen name (e.g., `login`, `dashboard`)
-
-If missing, ask the user.
+- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
 ## Steps
 
-### 1. Verify screen exists
-
-Check `qa/screens/<screen>/` exists. If not, tell user to run `sungen add --screen <screen> --path <path>` first.
-
-### 2. Determine source mode
-
-Ask: "Do you have a **live page** or **static designs** (screenshots, Figma, images)?"
-
-**Live page →** explore via browser (see `.github/copilot-instructions.md` for Playwright MCP rules). If auth needed, check `specs/.auth/<role>.json` exists — if not, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>` (e.g., `sungen makeauth admin --url http://localhost:3000`). **Do NOT execute `sungen makeauth` yourself.** Wait for the user to confirm auth is ready before proceeding.
-
-**Static designs →** ask user to provide screenshot paths, Figma exports, or UI descriptions. Note: selectors will be best-guess until live page is available.
-
-Present discovered elements to user, then proceed.
-
-### 3. Gather test viewpoints
-
-| VP Category | Description |
-|---|---|
-| **UI/UX** | Default screen appearance, static elements, default states |
-| **Validation** | Field/form validation, error messages |
-| **Logic** | Business logic, happy paths, redirects |
-| **Security** | Auth guards, permission checks |
-
-For each viewpoint, gather: **UI Target**, **Test Viewpoint**, **Expected Result**.
-
-User can provide all at once as a table:
-```
-| VP Category | UI Target | Test Viewpoint | Expected Result |
-```
-
-### 4. Generate files
-
-Generate the 3 files following `sungen-gherkin-syntax` and `sungen-selector-keys` prompt rules:
-- `qa/screens/<screen>/features/<screen>.feature` — one Scenario per viewpoint
-- `qa/screens/<screen>/selectors/<screen>.yaml`
-- `qa/screens/<screen>/test-data/<screen>.yaml`
-
-### 5. Confirm
+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. Ask the user: "How should I explore the page? **1) Live page** (via Playwright MCP) or **2) Static designs** (screenshots, Figma)?". If live page, explore via #tool:playwright (see [copilot-instructions.md](../../copilot-instructions.md) for MCP rules). If auth needed, ask user to log in manually.
+4. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). 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 → next: `/sungen-make-test ${input:screen}`
 
-Show what was generated. Next: `sungen generate --screen <screen>`
+**No selectors.yaml** — selectors are generated during `/sungen-make-test`.

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

@@ -1,58 +1,27 @@
 ---
-description: 'Compile and run Playwright tests for a Sungen screen — auto-fixes selectors on failure, falls back to AI .spec.ts fix after 5 attempts'
-mode: 'agent'
-tools: ['terminal']
+name: sungen-make-test
+description: 'Generate selectors, compile, and run Playwright tests — auto-fixes selectors on failure. Uses sungen-selector-fix, sungen-selector-keys, and sungen-error-mapping skills.'
+argument-hint: '[screen-name]'
+agent: 'agent'
+tools: ['terminal', 'playwright/*']
 ---
 
+**Input**: Screen name (e.g., `/sungen-make-test admin-users`).
+
 ## Role
 
-You are a **Senior Developer** specialized in Playwright test debugging. You diagnose test failures, fix selectors/test-data, and patch `.spec.ts` when needed. Use the `sungen-error-mapping` and `sungen-selector-keys` prompts for error diagnosis and key fixes.
+You are a **Senior Developer** specialized in Playwright test debugging. You generate selectors from live pages, diagnose test failures, and fix selectors/test-data using the `sungen-selector-fix`, `sungen-selector-keys`, and `sungen-error-mapping` skills.
 
 ## Parameters
 
-Parse from user input:
-- **screen** — screen name (e.g., `login`, `dashboard`)
-
-If missing, ask the user.
+- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
 
 ## Steps
 
-### 1. Verify screen exists
-
-Check `qa/screens/<screen>/` has all 3 source files. If not, tell user to run `sungen-add-screen` and `sungen-make-tc` prompts first.
-
-### 2. Compile
-
-```bash
-sungen generate --screen <screen>
-```
-
-If fails, fix source files per `sungen-error-mapping` prompt and retry.
-
-### 3. Run tests
-
-```bash
-npx playwright test specs/screens/<screen>/<screen>.spec.ts
-```
-
-If pass → Step 5. If fail → Step 4.
-
-### 4. Fix and retry (max 5 attempts)
-
-Per attempt:
-1. Read Playwright error output
-2. Map error to fix using `sungen-error-mapping` prompt
-3. Fix `selectors.yaml` or `test-data.yaml`
-4. Recompile: `sungen generate --screen <screen>`
-5. Retest
-
-### 5. Fallback — AI fix .spec.ts
-
-After 5 failed attempts, ask user:
-> Tests still failing. Would you like me to directly fix the `.spec.ts` file?
-
-If yes: read `.spec.ts`, fix locators/assertions, mark with `// AI-fixed: <reason>`
-
-### 6. Confirm
-
-Show: pass/fail, attempt count, files changed.
+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.

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

@@ -73,12 +73,14 @@ When exploring a page to generate test files:
 Only use: `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill_form`, `browser_evaluate`.
 
 To browse authenticated pages via MCP:
-1. Check if `specs/.auth/<role>.json` exists
-2. If not, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>`. **Do NOT execute `sungen makeauth` yourself.** Wait for user confirmation.
-3. Read `specs/.auth/<role>.json`
-4. `browser_navigate` to the page
-5. `browser_evaluate` to inject localStorage and cookies from the JSON
-6. `browser_navigate` again to reload with auth
+1. `browser_navigate` to `baseURL`
+2. If redirected to login, ask the user to log in manually:
+   > "This page requires login. Please log in using the browser. Confirm when you're done."
+3. Once confirmed, `browser_navigate` to the target page and take `browser_snapshot`
+
+**Never use `sungen makeauth`.** Always let the user log in manually via the MCP browser.
+**NEVER use `browser_evaluate` to inject cookies or localStorage.** It causes size limit issues and server 500 errors.
+**Minimize navigations** — take one snapshot per page, do not navigate repeatedly.
 
 ## Commands
 
@@ -86,5 +88,4 @@ To browse authenticated pages via MCP:
 sungen add --screen <name> --path <url-path>  # Create screen
 sungen generate --screen <name>                # Compile to .spec.ts
 sungen generate --all                          # Compile all
-sungen makeauth <role>                         # Capture auth state
 ```

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

@@ -0,0 +1,56 @@
+---
+name: sungen-error-mapping
+description: 'Playwright and Sungen error to fix mapping. Use this when running Playwright tests or debugging test failures.'
+user-invocable: false
+---
+
+## Playwright Errors → Fix
+
+| Error | Fix in `selectors.yaml` |
+|---|---|
+| 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 |
+
+## Auth Errors → Fix
+
+| Symptom | Fix |
+|---|---|
+| Tests redirect to login page | `specs/.auth/<role>.json` missing or expired. Tell user: `sungen makeauth <role> --url <baseURL>` |
+| `storageState` file not found | Run `sungen makeauth <role> --url <baseURL>` to create auth state |
+| Most tests timeout on first step | Auth expired — re-run `sungen makeauth <role> --url <baseURL>` |
+| Page shows home/login instead of target | SPA routing + expired auth. Re-run `sungen makeauth`, add `wait for` step after navigation |
+
+**Never run `sungen makeauth` yourself.** Always tell the user to run it manually.
+
+## Performance Errors → Fix (specs/base.ts)
+
+All generated `.spec.ts` files import from `specs/base.ts`. This shared file handles context caching, navigation skip, and overlay cleanup.
+
+| Symptom | Fix in `specs/base.ts` |
+|---|---|
+| Server returns 429 (rate limited) | Context caching broken — check `contextCache` Map reuses sessions per `storageState` |
+| Tests slow even with `--workers=1` | Navigation skip not working — check `goto` patch compares `currentPath === url` |
+| Previous test's modal blocks next test | Overlay cleanup insufficient — improve Escape/click dismiss logic |
+| All tests fail on first navigation | `page.url()` is `about:blank` — check try/catch in goto patch |
+| Multiple session invalidation errors | Too many contexts created — ensure `contextCache.get(cacheKey)` returns existing context |
+
+**Rules:**
+- `base.ts` changes affect ALL tests — edit carefully
+- Small project-specific tweaks are OK (e.g., custom overlay dismiss, timeout tuning, extra wait logic)
+- Do NOT move individual selector/data fixes into `base.ts` — those belong in `selectors.yaml` / `test-data.yaml`
+- If unsure whether a fix belongs in `base.ts` or selectors, ask the user
+
+## Sungen Errors → Fix
+
+| Error | Fix |
+|---|---|
+| Unknown step pattern | rewrite `.feature` step to match supported pattern |
+| Missing selector | add key to `selectors.yaml` |
+| Missing variable | add key to `test-data.yaml` |
+| Invalid selector type | use: role/testid/placeholder/label/text/locator/page/upload/frame |

package/{src/orchestrator/templates/ai-instructions/copilot-skill-gherkin-syntax.md → dist/orchestrator/templates/ai-instructions/github-skill-sungen-gherkin-syntax.md}

@@ -1,7 +1,7 @@
 ---
-description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Referenced by other sungen prompts.'
-mode: 'agent'
-tools: []
+name: sungen-gherkin-syntax
+description: 'Sungen Gherkin patterns, selector types, and YAML key rules. Use this when writing or editing .feature, selectors.yaml, or test-data.yaml files.'
+user-invocable: false
 ---
 
 ## Step Patterns (65 patterns)
@@ -10,7 +10,7 @@ tools: []
 
 ```
 User is on [T] page                              # navigate to page
-User navigate to [T] page with {{v}}             # navigate with data
+User is on [T] page with {{v}}                   # navigate with data (e.g., detail page with ID)
 User is logged in | is not logged in              # auth state
 ```
 
@@ -98,7 +98,7 @@ User click [Act] in [Table] table row with {{f}}             # action in row
 
 ## YAML Keys
 
-`[Reference]` → **lowercase, spaces→dots**: `[Search Content]` → `search.content:`
+`[Reference]` → **lowercase, keep Unicode**: `[Search Content]` → `search content:`, `[Thời gian]` → `thời gian:`
 
 ## Selectors (priority order)