@sun-asterisk/sungen 2.0.2 → 2.1.0

package/src/generators/test-generator/patterns/assertion-patterns.ts

@@ -109,7 +109,7 @@ export const assertionPatterns: StepPattern[] = [
 
       if (resolved.strategy === 'locator') {
         const code = context.templateEngine.renderStep('hidden-with-filter-assertion', {
-          ...resolved, dataValue, nth: resolved.nth || 0,
+          ...resolved, dataValue, nth: resolved.nth,
         });
         return { code, comment: `Assert ${step.selectorRef} hidden with ${step.dataRef}` };
       }
@@ -127,7 +127,7 @@ export const assertionPatterns: StepPattern[] = [
           role: resolved.role,
           name: resolved.name && resolved.name.trim() ? resolved.name : undefined,
           dataValue,
-          nth: resolved.nth || 0,
+          nth: resolved.nth,
         });
         return { code, comment: `Assert ${step.selectorRef} hidden with ${step.dataRef}` };
       }
@@ -135,7 +135,7 @@ export const assertionPatterns: StepPattern[] = [
       const selectorValue = resolved.value || '';
       if (selectorValue && selectorValue.trim()) {
         const code = context.templateEngine.renderStep('hidden-with-filter-assertion', {
-          ...resolved, dataValue, nth: resolved.nth || 0,
+          ...resolved, dataValue, nth: resolved.nth,
         });
         return { code, comment: `Assert ${step.selectorRef} hidden with ${step.dataRef}` };
       }
@@ -144,7 +144,7 @@ export const assertionPatterns: StepPattern[] = [
         selectorRef: step.selectorRef,
         selectorValue: resolved.value || '',
         dataValue,
-        nth: resolved.nth || 0,
+        nth: resolved.nth,
       });
       return { code, comment: `Assert ${step.selectorRef} hidden with ${step.dataRef}` };
     },
@@ -181,7 +181,7 @@ export const assertionPatterns: StepPattern[] = [
 
       if (resolved.strategy === 'locator') {
         const code = context.templateEngine.renderStep('disabled-with-filter-assertion', {
-          ...resolved, dataValue, nth: resolved.nth || 0,
+          ...resolved, dataValue, nth: resolved.nth,
         });
         return { code, comment: `Assert ${step.selectorRef} disabled with ${step.dataRef}` };
       }
@@ -191,7 +191,7 @@ export const assertionPatterns: StepPattern[] = [
           role: resolved.role,
           name: resolved.name && resolved.name.trim() ? resolved.name : undefined,
           dataValue,
-          nth: resolved.nth || 0,
+          nth: resolved.nth,
         });
         return { code, comment: `Assert ${step.selectorRef} disabled with ${step.dataRef}` };
       }
@@ -199,7 +199,7 @@ export const assertionPatterns: StepPattern[] = [
       const selectorValue = resolved.value || '';
       if (selectorValue && selectorValue.trim()) {
         const code = context.templateEngine.renderStep('disabled-with-filter-assertion', {
-          ...resolved, dataValue, nth: resolved.nth || 0,
+          ...resolved, dataValue, nth: resolved.nth,
         });
         return { code, comment: `Assert ${step.selectorRef} disabled with ${step.dataRef}` };
       }
@@ -208,7 +208,7 @@ export const assertionPatterns: StepPattern[] = [
         selectorRef: step.selectorRef,
         selectorValue: resolved.value || '',
         dataValue,
-        nth: resolved.nth || 0,
+        nth: resolved.nth,
       });
       return { code, comment: `Assert ${step.selectorRef} disabled with ${step.dataRef}` };
     },
@@ -284,7 +284,7 @@ export const assertionPatterns: StepPattern[] = [
         const code = context.templateEngine.renderStep('visible-with-locator-variable-assertion', {
           ...resolved,
           dataValue,
-          nth: resolved.nth || 0,
+          nth: resolved.nth,
         });
         return {
           code,
@@ -313,7 +313,7 @@ export const assertionPatterns: StepPattern[] = [
           name: isImgRole ? (hasName ? resolved.name : dataValue) : (hasName ? resolved.name : undefined),
           dataValue: isImgRole ? undefined : dataValue,
           exact: resolved.exact || false,
-          nth: resolved.nth || 0,
+          nth: resolved.nth,
         });
         return {
           code,
@@ -331,7 +331,7 @@ export const assertionPatterns: StepPattern[] = [
           value: selectorValue,
           dataValue,
           dataRef: step.dataRef,
-          nth: resolved.nth || 0,
+          nth: resolved.nth,
           exact: resolved.exact || false,
         });
         return {
@@ -344,7 +344,7 @@ export const assertionPatterns: StepPattern[] = [
           selectorRef: step.selectorRef,
           selectorValue: resolved.value || '',
           dataValue,
-          nth: resolved.nth || 0,
+          nth: resolved.nth,
         });
         return {
           code,
@@ -523,7 +523,6 @@ export const assertionPatterns: StepPattern[] = [
         data: {
           strategy: 'text',
           value: dataValue,
-          nth: 0,
         },
         comment: `Assert ${step.dataRef} is visible`,
       };

package/src/generators/test-generator/patterns/interaction-patterns.ts

@@ -39,16 +39,16 @@ export const interactionPatterns: StepPattern[] = [
     },
     resolver: (step, context) => {
       let selectorValue = '';
-      let nth = 0;
+      let nth: number | undefined;
       try {
         const resolved = context.selectorResolver.resolveSelector(
           step.selectorRef!, context.featureName, step.elementType, step.nth
         );
         selectorValue = resolved.value || '';
-        nth = resolved.nth || 0;
+        nth = resolved.nth;
       } catch (error) {
         selectorValue = '';
-        nth = 0;
+        nth = undefined;
       }
 
       let dataValue: string;
@@ -174,7 +174,7 @@ export const interactionPatterns: StepPattern[] = [
 
       return {
         templateName: 'click-action',
-        data: { strategy: 'text', value, nth: 0 },
+        data: { strategy: 'text', value },
         comment: `Click ${step.dataRef}`,
       };
     },

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -196,7 +196,7 @@ interface SelectorEntry {
   type?: SelectorType;    // Locator strategy
   value?: string;         // Natural language value for the locator (e.g., 'button', 'link' for role)
   name?: string;          // Accessible name for role-based selectors (e.g., 'Login', 'Submit')
-  nth?: number;           // Element index (0 = no index, 1+ = append .nth())
+  nth?: number;           // Element index (undefined = no .nth(), 0+ = .nth(N))
   exact?: boolean;        // Whether to use exact matching (default: false)
   inputMethod?: string;   // 'pressSequentially' for contenteditable/rich-text elements
 
@@ -375,19 +375,19 @@ export class SelectorResolver {
     const normalized = SelectorResolver.normalizeElementType(elementType);
 
     const strategyMap: Record<string, () => ResolvedSelector> = {
-      'img': () => ({ strategy: 'role', role: 'img', name: label, value: 'img', nth: 0 }),
-      'button': () => ({ strategy: 'role', role: 'button', name: label, value: 'button', nth: 0 }),
-      'link': () => ({ strategy: 'role', role: 'link', name: label, value: 'link', nth: 0 }),
-      'text': () => ({ strategy: 'text', value: label, nth: 0 }),
-      'field': () => ({ strategy: 'placeholder', value: label, nth: 0 }),
-      'checkbox': () => ({ strategy: 'role', role: 'checkbox', name: label, value: 'checkbox', nth: 0 }),
-      'radio': () => ({ strategy: 'role', role: 'radio', name: label, value: 'radio', nth: 0 }),
-      'row': () => ({ strategy: 'role', role: 'row', name: label, value: 'row', nth: 0 }),
-      'table': () => ({ strategy: 'role', role: 'table', name: label, value: 'table', nth: 0 }),
-      'columnheader': () => ({ strategy: 'role', role: 'columnheader', name: label, value: 'columnheader', nth: 0 }),
-      'heading': () => ({ strategy: 'role', role: 'heading', name: label, value: 'heading', nth: 0 }),
-      'list': () => ({ strategy: 'role', role: 'list', name: label, value: 'list', nth: 0 }),
-      'listitem': () => ({ strategy: 'role', role: 'listitem', value: 'listitem', nth: 0 }),
+      'img': () => ({ strategy: 'role', role: 'img', name: label, value: 'img' }),
+      'button': () => ({ strategy: 'role', role: 'button', name: label, value: 'button' }),
+      'link': () => ({ strategy: 'role', role: 'link', name: label, value: 'link' }),
+      'text': () => ({ strategy: 'text', value: label }),
+      'field': () => ({ strategy: 'placeholder', value: label }),
+      'checkbox': () => ({ strategy: 'role', role: 'checkbox', name: label, value: 'checkbox' }),
+      'radio': () => ({ strategy: 'role', role: 'radio', name: label, value: 'radio' }),
+      'row': () => ({ strategy: 'role', role: 'row', name: label, value: 'row' }),
+      'table': () => ({ strategy: 'role', role: 'table', name: label, value: 'table' }),
+      'columnheader': () => ({ strategy: 'role', role: 'columnheader', name: label, value: 'columnheader' }),
+      'heading': () => ({ strategy: 'role', role: 'heading', name: label, value: 'heading' }),
+      'list': () => ({ strategy: 'role', role: 'list', name: label, value: 'list' }),
+      'listitem': () => ({ strategy: 'role', role: 'listitem', value: 'listitem' }),
     };
 
     const factory = strategyMap[normalized];
@@ -549,7 +549,7 @@ export class SelectorResolver {
     const value = entry.value !== undefined && entry.value !== null ? entry.value : originalLabel;
     // Check if name exists in entry (even if empty string), use it; otherwise use originalLabel
     const name = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
-    const nth = entry.nth || 0;
+    const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
     const exact = entry.exact === true || entry.match === 'exact';
     const inputMethod = entry.inputMethod;
 

package/src/orchestrator/project-initializer.ts

@@ -5,6 +5,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { execSync } from 'child_process';
 
 export class ProjectInitializer {
   private baseCwd: string;
@@ -12,7 +13,7 @@ export class ProjectInitializer {
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
 
-  constructor() {
+  constructor(private baseUrl: string) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
   }
@@ -37,6 +38,9 @@ export class ProjectInitializer {
     // Create directories
     this.createDirectories();
 
+    // Ensure package.json and install Playwright
+    await this.setupDependencies();
+
     // Create playwright config if doesn't exist
     this.createPlaywrightConfig();
 
@@ -99,7 +103,8 @@ export class ProjectInitializer {
       return;
     }
 
-    const configContent = this.getPlaywrightConfigTemplate();
+    const configContent = this.getPlaywrightConfigTemplate()
+      .replace('https://example.com', this.baseUrl);
     fs.writeFileSync(configPath, configContent, 'utf-8');
     this.createdItems.push('playwright.config.ts');
   }
@@ -174,9 +179,6 @@ export class ProjectInitializer {
       });
     }
 
-    // Check for Playwright installation
-    this.checkDependencies();
-
     console.log('\nNext steps:');
     let stepIndex = 1;
     if (projectName) {
@@ -192,48 +194,54 @@ export class ProjectInitializer {
    * Create AI rules files for GitHub Copilot and Claude Code
    */
   private createAIRules(): void {
-    const rulesContent = this.getAIRulesContent();
-
-    // GitHub Copilot: .github/copilot-instructions.md
-    const githubDir = path.join(this.cwd, '.github');
-    const copilotPath = path.join(githubDir, 'copilot-instructions.md');
-    if (!fs.existsSync(copilotPath)) {
-      if (!fs.existsSync(githubDir)) {
-        fs.mkdirSync(githubDir, { recursive: true });
-      }
-      fs.writeFileSync(copilotPath, rulesContent, 'utf-8');
-      this.createdItems.push('.github/copilot-instructions.md');
-    } else {
-      this.skippedItems.push('.github/copilot-instructions.md');
-    }
+    const aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
+
+    // File mapping: [templateFile, outputPath]
+    const fileMapping: [string, string][] = [
+      // Config
+      ['claude-config.md', 'CLAUDE.md'],
+      ['copilot-config.md', '.github/copilot-instructions.md'],
+
+      // Commands — Claude Code
+      ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
+      ['claude-cmd-make-tc.md', '.claude/commands/sungen/make-tc.md'],
+      ['claude-cmd-make-test.md', '.claude/commands/sungen/make-test.md'],
+
+      // Commands — GitHub Copilot
+      ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
+      ['copilot-cmd-make-tc.md', '.github/prompts/sungen-make-tc.prompt.md'],
+      ['copilot-cmd-make-test.md', '.github/prompts/sungen-make-test.prompt.md'],
+
+      // Skills — Claude Code
+      ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
+      ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
+      ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
+
+      // Skills — GitHub Copilot
+      ['copilot-skill-gherkin-syntax.md', '.github/prompts/sungen-gherkin-syntax.prompt.md'],
+      ['copilot-skill-selector-keys.md', '.github/prompts/sungen-selector-keys.prompt.md'],
+      ['copilot-skill-error-mapping.md', '.github/prompts/sungen-error-mapping.prompt.md'],
+    ];
 
-    // Claude Code: CLAUDE.md
-    const claudePath = path.join(this.cwd, 'CLAUDE.md');
-    if (!fs.existsSync(claudePath)) {
-      fs.writeFileSync(claudePath, rulesContent, 'utf-8');
-      this.createdItems.push('CLAUDE.md');
-    } else {
-      this.skippedItems.push('CLAUDE.md');
-    }
+    for (const [templateFile, outputRelPath] of fileMapping) {
+      const outputPath = path.join(this.cwd, outputRelPath);
 
-    // Gherkin Dictionary: docs/gherkin-dictionary.md
-    const docsDir = path.join(this.cwd, 'docs');
-    const dictPath = path.join(docsDir, 'gherkin-dictionary.md');
-    if (!fs.existsSync(dictPath)) {
-      // Copy from sungen package if available, otherwise generate stub
-      const packageDictPath = path.join(__dirname, '..', '..', 'docs', 'gherkin-dictionary.md');
-      if (!fs.existsSync(docsDir)) {
-        fs.mkdirSync(docsDir, { recursive: true });
+      if (fs.existsSync(outputPath)) {
+        this.skippedItems.push(outputRelPath);
+        continue;
       }
-      if (fs.existsSync(packageDictPath)) {
-        fs.copyFileSync(packageDictPath, dictPath);
-      } else {
-        fs.writeFileSync(dictPath, '# Sungen Gherkin Dictionary\n\nSee https://github.com/sun-asterisk/sungen for the full dictionary.\n', 'utf-8');
+
+      const outputDir = path.dirname(outputPath);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
       }
-      this.createdItems.push('docs/gherkin-dictionary.md');
-    } else {
-      this.skippedItems.push('docs/gherkin-dictionary.md');
+
+      const templatePath = path.join(aiTemplateDir, templateFile);
+      const content = fs.readFileSync(templatePath, 'utf-8');
+      fs.writeFileSync(outputPath, content, 'utf-8');
+      this.createdItems.push(outputRelPath);
     }
+
   }
 
   /**
@@ -244,30 +252,38 @@ export class ProjectInitializer {
     return fs.readFileSync(templatePath, 'utf-8');
   }
 
-  /**
-   * Get AI rules content (shared between Copilot and Claude)
-   */
-  private getAIRulesContent(): string {
-    return this.readTemplate('ai-rules.md');
-  }
-
   /**
    * Check for required dependencies
    */
-  private checkDependencies(): void {
+  private async setupDependencies(): Promise<void> {
+    const packageJsonPath = path.join(this.cwd, 'package.json');
+    const execOpts = { cwd: this.cwd, stdio: 'inherit' as const };
+
+    // Initialize package.json if it doesn't exist
+    if (!fs.existsSync(packageJsonPath)) {
+      console.log('📦 No package.json found. Initializing...\n');
+      execSync('npm init -y', execOpts);
+      this.createdItems.push('package.json');
+    }
+
+    // Check if @playwright/test is already installed
     try {
-      const packageJsonPath = path.join(this.cwd, 'package.json');
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
-
-      if (!deps['@playwright/test']) {
-        console.log('\n⚠️  Playwright not detected. Install with:');
-        console.log('   npm install -D @playwright/test');
-        console.log('   npx playwright install');
+      if (deps['@playwright/test']) {
+        console.log('✓ @playwright/test already installed\n');
+        return;
       }
-    } catch (error) {
-      // Ignore if can't read package.json
+    } catch {
+      // package.json just created, proceed with install
     }
+
+    // Install Playwright
+    console.log('📦 Installing @playwright/test...\n');
+    execSync('npm install -D @playwright/test', execOpts);
+
+    console.log('\n🎭 Installing Playwright browsers...\n');
+    execSync('npx playwright install', execOpts);
   }
 
   /**

package/src/orchestrator/screen-manager.ts

@@ -97,7 +97,6 @@ export class ScreenManager {
         `${screenName}:`,
         `  type: 'page'`,
         `  value: '${pagePath}'`,
-        `  nth: 0`,
         ``,
       ].join('\n'), 'utf-8');
     }

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -0,0 +1,42 @@
+---
+name: add-screen
+description: 'Add a new Sungen screen — scaffolds directories and delegates to make-tc for test case creation'
+argument-hint: [screen-name] [url-path]
+allowed-tools: Read, Grep, Bash, Glob
+---
+
+You are adding a new Sungen screen for test generation.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **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`)"
+
+## Steps
+
+### 1. Scaffold the screen
+
+Run:
+```bash
+sungen add --screen <screen> --path <path>
+```
+
+### 2. Create test cases
+
+Ask the user: "Would you like to create test cases now?"
+
+If yes, delegate to `/sungen:make-tc <screen>` 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)
+
+### 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`

package/src/orchestrator/templates/ai-instructions/claude-cmd-make-tc.md

@@ -0,0 +1,60 @@
+---
+name: make-tc
+description: 'Create test cases for a Sungen screen — gathers viewpoints, explores live page or static designs, generates feature/selectors/test-data files'
+argument-hint: [screen-name]
+allowed-tools: Read, Grep, Bash, Glob
+---
+
+## 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` skills.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`)
+
+If missing, ask the user.
+
+## Steps
+
+### 1. Verify screen exists
+
+Check `qa/screens/<screen>/` exists. If not, tell user to run `/sungen:add-screen` first.
+
+### 2. Determine source mode
+
+Ask: "Do you have a **live page** or **static designs** (screenshots, Figma, images)?"
+
+**Live page →** explore via browser (see CLAUDE.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` skill 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
+
+Show what was generated. Next: `sungen generate --screen <screen>`

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

@@ -0,0 +1,59 @@
+---
+name: make-test
+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'
+argument-hint: [screen-name]
+allowed-tools: Read, Grep, Bash, Glob, Edit
+---
+
+## 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` skills for error diagnosis and key fixes.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`)
+
+If missing, ask the user.
+
+## 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` first.
+
+### 2. Compile
+
+```bash
+sungen generate --screen <screen>
+```
+
+If fails, fix source files per `sungen-error-mapping` skill 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` skill
+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.

package/src/orchestrator/templates/ai-instructions/claude-config.md

@@ -0,0 +1,90 @@
+# Sungen AI Rules
+
+You generate 3 files for sungen — a Gherkin compiler that produces Playwright tests.
+**You do NOT write Playwright code.** You only write `.feature`, `selectors.yaml`, and `test-data.yaml`.
+
+For Gherkin syntax, selector types, and YAML rules, the `sungen-gherkin-syntax` skill is auto-loaded when needed.
+For error diagnosis, the `sungen-error-mapping` skill is auto-loaded when needed.
+
+## Complete Example
+
+Given a login page, here are the 3 files you generate:
+
+**qa/screens/login/features/login.feature**
+```gherkin
+@auth:admin
+Feature: Login Screen
+
+  Scenario: Successful login
+    Given User is on [login] page
+    When User fill [Email] field with {{email}}
+    And User fill [Password] field with {{password}}
+    And User click [Submit] button
+    Then User see [Welcome] heading with {{welcome_text}}
+    And User see [Dashboard] link is visible
+```
+
+**qa/screens/login/selectors/login.yaml**
+```yaml
+login:
+  type: 'page'
+  value: '/login'
+
+email:
+  type: 'placeholder'
+  value: 'Enter your email'
+
+password:
+  type: 'placeholder'
+  value: 'Enter your password'
+
+submit:
+  type: 'role'
+  value: 'button'
+  name: 'Submit'
+
+welcome:
+  type: 'role'
+  value: 'heading'
+  name: 'Welcome'
+
+dashboard:
+  type: 'role'
+  value: 'link'
+  name: 'Dashboard'
+```
+
+**qa/screens/login/test-data/login.yaml**
+```yaml
+email: 'admin@example.com'
+password: 'password123'
+welcome_text: 'Welcome back'
+```
+
+## Using Playwright MCP to explore pages
+
+When exploring a page to generate test files:
+1. Read `playwright.config.ts` for `baseURL`
+2. Use `browser_navigate` to open `baseURL + /path`
+3. Use `browser_snapshot` to see all elements
+4. Generate the 3 files from the snapshot
+
+**NEVER use `browser_run_code`.** It fails with `require is not defined`.
+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
+
+## Commands
+
+```bash
+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
+```