@sun-asterisk/sungen 1.0.17 → 1.0.19

package/README.md

@@ -1,671 +1,171 @@
 # Sungen - AI-Native E2E Test Generator
 
-**Version**: 3.2.0 (Unreleased)
-**Priority-Based E2E Test Generation with Deterministic Selector Mapping**
+**Version**: 1.0.17
+**Deterministic-first E2E test generation**: Gherkin → Playwright tests
 
 ---
 
-## 🎯 What is Sungen?
+## What is Sungen?
 
-Sungen is a **deterministic-first** E2E test automation framework that generates Playwright tests from Gherkin features using a **priority-based approach**:
+Sungen generates Playwright tests from Gherkin features using **priority-based selector mapping**:
 
-1. **Strict UI Scanning** - Filters only interactive elements (input, button, a, select, textarea)
-2. **Priority-Based Selector Mapping**:
-   - **1️⃣ Direct ID Match** - Exact `data-testid` matching (instant, free, deterministic)
-   - **2️⃣ Accessibility Match** - Semantic `role` + `aria-label` matching
-   - **3️⃣ AI Fallback** - Claude Sonnet as last resort (not primary solution)
-3. **Auto-Tagging Tool** - Inject stable `data-testid` into source code proactively
-4. **Authentication Support** - Built-in Playwright storage states via `@auth:{role}` tags
-5. **Test Generation** - Create production-ready Playwright test code
+1. **Direct ID** (`data-testid`) - instant, free, deterministic
+2. **Accessibility** (`role` + `aria-label`) - semantic fallback
+3. **AI Fallback** (Claude) - last resort only
 
-**Key Achievement**: **90%+ Direct ID match rate** with minimal AI dependency!
+Goal: **90%+ Direct ID match** with minimal AI dependency.
 
 ---
 
-## 🚀 Quick Start
-
-### Installation
+## Quick Start
 
 ```bash
+# Install
 npm install -g @sun-asterisk/sungen@latest
-```
-
-Or use locally in your project:
-
-```bash
-npm install --save-dev @sun-asterisk/sungen
-```
-
-### Setup
-
-1. Initialize your Sungen project:
 
-```bash
+# Initialize project
 sungen init
-```
 
-This creates:
-- `qa/screens/` - Screen definitions directory (use `sungen add --screen` to create)
-- `spec/generated/` - Generated test code output directory
-- `playwright.config.ts` - Playwright configuration
-- `.gitignore` - Updated with Sungen patterns
-
-**Note:** Use `sungen add --screen <name>` to create screen definitions with proper structure.
-
-2. Create your first screen definition:
-
-```bash
+# Create a screen, map selectors, generate tests
 sungen add --screen login --path /auth/login
-```
-
-This creates a screen definition with:
-- `qa/screens/login/features/login.feature` - Gherkin scenarios
-- `qa/screens/login/selectors/login.override.yaml` - User override file (empty with guidelines)
-- `qa/screens/login/test-data/login.override.yaml` - User override file (empty with guidelines)
-
-**Note**: Override files will **NEVER** be modified by `sungen map`. Edit these to customize selectors and test data.
-
-3. Run `sungen map` to generate base files:
-
-```bash
 sungen map --screen login
-```
-
-This generates:
-- `qa/screens/login/selectors/login.yaml` - Auto-generated base selectors
-- `qa/screens/login/test-data/login.yaml` - Auto-generated base test data
-
-At runtime, values from `.override.yaml` take precedence over base files.
-
-### Usage
-
-```bash
-# Create a new screen definition
-sungen add --screen login --path /auth/login
-
-# Step by step:
-sungen map --screen login          # 2. Map selectors with AI
-sungen generate --screen login     # 3. Generate Playwright tests
+sungen generate --screen login
 
-# Clear cache
-sungen cache-clear
+# Run tests
+npx playwright test
 ```
 
 ---
 
-## 📁 Project Structure
+## Gherkin Syntax
 
-```
-your-project/
-├── app/                          # Your React source
-│   ├── auth/
-│   │   └── page.tsx
-│   └── chat/
-│       └── page.tsx
-│
-├── qa/                           # Input artifacts
-│   └── screens/                  # Screen definitions (NEW structure)
-│       └── auth/
-│           ├── features/         # Gherkin scenarios
-│           │   └── login.feature
-│           │   └── logout.feature
-│           ├── selectors/        # Element mappings
-│           │   └── login.yaml
-│           │   └── logout.yaml
-│           └── test-data/        # Test variables
-│               └── login.yaml
-│               └── logout.yaml
-│
-├── specs/                        # Output artifacts (sibling to qa/)
-│   ├── .auth/                    # Authentication storage states (gitignored)
-│   │   ├── .gitignore
-│   │   ├── admin.json
-│   │   └── user.json
-│   ├── auth.setup.ts             # Playwright auth setup (auto-generated)
-│   └── generated/                # Generated Playwright tests
-│       └── auth
-│           ├── login.spec.ts
-│           └── logout.spec.ts
-│
-└── sungen.config.yaml            # Framework configuration
-```
+**Pattern**: `User + action + [element] type + with {{data}}`
 
+**[Complete Gherkin Standard (English)](docs/gherkin%20standards/gherkin-core-standard.md)** | **[Tiếng Việt](docs/gherkin%20standards/gherkin-core-standard.vi.md)**
 
-**Key Changes in v3.2:**
-- Organized by screens: Each screen has its own directory
-- Self-contained: Features, selectors, and test data grouped together
-- Use `sungen add --screen <name>` to create new screen definitions
-
----
-
-## 🎨 Gherkin Syntax
-
-Sungen uses a **simple, natural language grammar** for Gherkin:
-
-**Pattern**: `User + action + [element] + with {{data}}`
-
-📘 **[Complete Gherkin Standard (English)](docs//gherkin%20standards/gherkin-core-standard.md)** | **[Tiếng Việt](docs/gherkin%20standards/gherkin-core-standard.vi.md)**
-
-### Example Feature File
+### Example
 
 ```gherkin
 Feature: Login Screen
-
-  As a user
-  I want to interact with the Login screen
-  So that I can access my account
   Path: /auth/login
 
-  @high
   Scenario: User logs in successfully
-    Given User open page
+    Given User is on [Login] page
     When User fill [Email] field with {{valid_email}}
     And User fill [Password] field with {{valid_password}}
     And User click [Login] button
-    Then User see [Welcome message !] text with {{success_message}}
-```
-
-### Grammar Rules
-
-| Component | Syntax | Example |
-|-----------|--------|---------|
-| **Actor** | `User` | `User open page` |
-| **Action** | `click`, `fill`, `see` | `User click [button]` |
-| **Element** | `[element name]` | `[Email] field`, `[submit] button` |
-| **Data** | `{{variable}}` | `{{valid_email}}`, `{{success.message}}` |
-| **Path** | `Path: /route` | `Path: /auth/login` |
-
-### Common Actions
-
-```gherkin
-# Navigation
-Given User open page
-
-# Input
-When User fill [element] field with {{data}}
-
-# Click
-When User click [element] button
-
-# Verification
-Then User see [element] text with {{expected_text}}
-```
-
-### Test Data
-
-Define variables in `test-data/<screen>.yaml`:
-
-```yaml
-# test-data/login.yaml
-valid_email: "user@example.com"
-valid_password: "SecurePassword123"
-success:
-  message: "Welcome back!"
+    Then User see [Welcome] text with {{success_message}}
 ```
 
-### Authentication with Storage States ⭐ NEW
-
-Sungen supports Playwright's authentication storage states via `@auth:{role}` tags, allowing you to reuse authenticated browser contexts across tests.
+### Actions
 
-#### Basic Usage
+| Action | Example |
+|--------|---------|
+| Navigate | `Given User is on [Login] page` |
+| Open | `Given User open [Login] page` |
+| Fill | `When User fill [Email] field with {{email}}` |
+| Click | `When User click [Submit] button` |
+| Select | `When User select [Country] dropdown with {{country}}` |
+| See (visible) | `Then User see [Welcome] text` |
+| See (with value) | `Then User see [Welcome] text with {{message}}` |
+| See (hidden) | `Then User see [panel] dialog with {{title}} is hidden` |
+| Wait for hidden | `And User wait for dialog with {{title}} is hidden` |
 
-**Tag your features or scenarios:**
-
-```gherkin
-@auth:admin
-Feature: User Management
-  
-  Scenario: Delete user
-    Given User navigate to "/users"
-    When User click [delete-button]
-    Then User see [success-message]
-
-@auth:user
-Feature: Profile Settings
-  
-  Scenario: Update email
-    Given User navigate to "/profile"
-    When User fill [email] field with {{new_email}}
-```
+### Annotations
 
-**Generated Playwright code automatically includes storage state:**
+| Syntax | Description |
+|--------|-------------|
+| `[Element]` | Selector reference (mapped via selectors YAML) |
+| `{{variable}}` | Test data reference (mapped via test-data YAML) |
+| `Path: /route` | Page route in feature description |
 
-```typescript
-// user-management.spec.ts
-test.use({ storageState: 'specs/.auth/admin.json' });
+### Tags
 
-test('Delete user', async ({ page }) => {
-  // Already authenticated as admin!
-  await page.goto('/users');
-  // ...
-});
-```
+| Tag | Level | Description |
+|-----|-------|-------------|
+| `@auth:<role>` | Feature/Scenario | Use Playwright auth storage state |
+| `@no-auth` | Feature/Scenario | Disable inherited auth |
+| `@steps:<name>` | Scenario | Mark as reusable step block |
+| `@extend:<name>` | Scenario | Prepend steps from a `@steps` block |
+| `@ignore` | Step (comment) | Skip step in generation |
+| `@ignore-testcase` | Step (comment) | Skip entire scenario |
 
-#### Tag Inheritance
+**Auth precedence**: Scenario > Feature > None
+**@extend precedence**: Extending scenario `@auth` > Base scenario `@auth` > Feature `@auth`
 
-Tags can be applied at **feature level** (inherited by all scenarios) or **scenario level** (overrides feature):
+### Reusable Steps with @steps / @extend
 
 ```gherkin
-@auth:admin
-Feature: Admin Dashboard
-  
-  Scenario: View analytics
-    # Inherits @auth:admin from feature
-    
-  @auth:moderator
-  Scenario: Review flagged content
-    # Overrides with @auth:moderator
-    
-  @no-auth
-  Scenario: View public help page
-    # Explicitly disables authentication
-```
-
-**Precedence:** Scenario > Feature > None
-
-#### Setting Up Authentication
-
-On first `sungen generate` with `@auth` tags, an `auth.setup.ts` scaffold is auto-generated:
-
-```bash
-sungen generate --screen admin
-
-# Output:
-✓ Generated specs/auth.setup.ts - Update TODOs before running tests
-✓ Created specs/.auth/ directory for storage states
-  Detected roles: admin, user, moderator
-```
-
-**Customize the generated setup file:**
-
-```typescript
-// specs/auth.setup.ts
-import { test as setup } from '@playwright/test';
-
-const authFile = (role: string) => `specs/.auth/${role}.json`;
-
-setup('authenticate as admin', async ({ page }) => {
-  // TODO: Navigate to your login page
-  await page.goto('/login');
-  
-  // TODO: Fill in credentials for admin role
-  await page.getByLabel('Email').fill('admin@example.com');
-  await page.getByLabel('Password').fill('admin123');
-  
-  // TODO: Click login button
-  await page.getByRole('button', { name: 'Sign in' }).click();
-  
-  // TODO: Wait for authentication to complete
-  await page.waitForURL('/dashboard');
-  
-  // Save authentication state
-  await page.context().storageState({ path: authFile('admin') });
-});
-
-// Additional setup functions for other roles...
-```
-
-#### Features
-
-- ✅ **Feature-level tags** - All scenarios inherit authentication
-- ✅ **Scenario-level tags** - Override feature authentication
-- ✅ **@no-auth tag** - Explicitly disable inherited authentication  
-- ✅ **Auto-generation** - Setup scaffold created on first use
-- ✅ **Multiple roles** - Support unlimited authentication roles
-- ✅ **Storage reuse** - Fast tests by reusing authenticated contexts
-
-#### Notes
-
-- Storage state files (`specs/.auth/*.json`) are gitignored by default
-- Setup runs before tests via Playwright's global setup
-- New roles detected after initial setup trigger a warning with manual update instructions
-
-### Element Selectors
-
-Map elements in `selectors/<screen>.yaml`:
-
-```yaml
-# selectors/login.yaml
-email-input:
-  selector: ""
-  type: "testid"
-  
-submit-button:
-  selector: ""
-  type: "role"
-  value: "button"
-```
-
----
-
-## 🏗️ Architecture
-
+@auth:user @steps:open-dialog
+Scenario: Open kudos dialog
+  Given User is on [kudo] page
+  When User click [Notifications] button
+  And User click [Write Kudos] menuitem
+  Then User see [panel] dialog with {{kudo_title}}
+
+@auth:user @extend:open-dialog
+Scenario: User sends a thank you message
+  Given User is on [panel] dialog with {{kudo_title}}
+  When User fill [Search] field with {{teammate_name}}
+  And User click [teammate] row with {{teammate_name}}
+  And User fill [Message] textarea with {{message}}
+  And User click [Send] button
+  And User wait for dialog with {{kudo_title}} is hidden
+  Then User see [panel] modal with {{kudo_title}} is hidden
+```
+
+The `@extend:open-dialog` scenario automatically inherits all steps from `@steps:open-dialog` before its own steps.
 
 ---
 
-## 📖 CLI Commands
+## Project Structure
 
-### `sungen init`
-Initialize Sungen project structure
-
-```bash
-sungen init
-```
-
-Creates:
-- `qa/screens/` directory for screen definitions
-- `spec/generated/` directory for generated tests
-- `playwright.config.ts` if it doesn't exist
-- Updates `.gitignore` with Sungen patterns
-
-### `sungen add --screen` ⭐ NEW
-Create a new screen definition with scaffolded files. Supports multiple test scenarios per screen.
-
-```bash
-sungen add --screen <name> [options]
-
-Options:
-  --screen <name>        Screen name (required)
-  -p, --path <path>      Screen route path - also controls filename
-  -d, --description      Screen description
-
-Examples:
-  # Create screen with default file
-  sungen add --screen login
-  
-  # Create screen with custom path/filename
-  sungen add --screen login --path /login-valid --description "Valid login"
-  
-  # Add additional test scenarios to existing screen
-  sungen add --screen login --path /login-invalid
-  sungen add --screen login --path /login-mfa
-```
-
-**What it does:**
-- **First call**: Creates `qa/screens/<name>/` directory structure
-- **Subsequent calls**: Adds additional feature files to existing screen
-- Generates `features/<filename>.feature` with Gherkin template
-- Generates `selectors/<filename>.yaml` with selector structure
-- Generates `test-data/<filename>.yaml` for test variables
-- **Path option**: Controls both filename and Path metadata in feature file
-
-**Multi-file workflow** (organizing test scenarios):
-```bash
-# Create base screen
-sungen add --screen login
-
-# Add valid login scenario
-sungen add --screen login --path /login-valid
-
-# Add invalid credentials scenario
-sungen add --screen login --path /login-invalid
-
-# Add 2FA scenario
-sungen add --screen login --path /login-mfa
 ```
+qa/screens/<name>/
+├── features/         # Gherkin .feature files
+├── selectors/        # Element mappings (.yaml + .override.yaml)
+└── test-data/        # Test variables (.yaml + .override.yaml)
 
-Result:
+specs/generated/<name>/
+└── <feature>.spec.ts # Generated Playwright tests
 ```
-qa/screens/login/
-  ├── features/
-  │   ├── login.feature
-  │   ├── login-valid.feature
-  │   ├── login-invalid.feature
-  │   └── login-mfa.feature
-  ├── selectors/
-  │   ├── login.yaml
-  │   ├── login-valid.yaml
-  │   ├── login-invalid.yaml
-  │   └── login-mfa.yaml
-  └── test-data/
-      ├── login.yaml
-      ├── login-valid.yaml
-      ├── login-invalid.yaml
-      └── login-mfa.yaml
-```
-
-**Backward compatible**: Default behavior (no `--path`) creates single file named after screen.
-
-
-### `sungen map`
-Map Gherkin references to actual selectors using AI
-
-```bash
-sungen map --screen <screen-name> [options]
-
-Options:
-  --screen <name>   Screen name to map (required)
-  --all             Map all screens
-  --force           Force regeneration, bypass cache, overwrite existing files
-  --verbose         Detailed output
-```
-
-**Output:** Processes each feature file individually, generating separate YAML files for each:
-
-```
-Mapping screen: login
-
-✓ Mapped login.feature
-   → selectors/login.yaml (5 elements)
-   → test-data/login.yaml (3 variables)
-   
-✓ Mapped login-valid.feature
-   → selectors/login-valid.yaml (3 elements)
-   → test-data/login-valid.yaml (2 variables)
-
-Next step: sungen generate --screen login
-```
-
-**Multi-file support:** Each `.feature` file generates matching `.yaml` files, maintaining clean separation between test scenarios.
-
-### `sungen generate`
-Generate Playwright test code from features
-
-```bash
-sungen generate [options]
-
-Options:
-  --ai-mapper          Enable AI fallback for unknown Gherkin patterns
-  --framework <name>   Test framework (playwright, appium, integration) - default: playwright
-  -s, --screen <name>  Filter generation to specific screen (recommended)
-  -f, --force          Force regeneration, bypass cache
-
-Examples:
-  sungen generate --screen login     # Generate tests for login screen
-  sungen generate -s login --force   # Force regenerate login screen tests
-  sungen generate                    # Generate all tests (legacy)
-```
-
-**Output:** Shows per-file results with step counts:
-
-```
-Generating tests: login
-
-✓ Generated login.spec.ts
-   → spec/generated/login/login.spec.ts (8 steps)
-
-✓ Generated login-valid.spec.ts
-   → spec/generated/login/login-valid.spec.ts (5 steps)
 
-✓ Generated login-invalid.spec.ts
-   → spec/generated/login/login-invalid.spec.ts (3 steps)
-
-Next step: npx playwright test
-```
-
-**Selector Merging:** Supports optional base + feature-specific selector files:
-- **Base file**: `selectors/<screen>.yaml` - Shared selectors for all scenarios
-- **Feature file**: `selectors/<feature-name>.yaml` - Scenario-specific selectors (required)
-- Feature-specific selectors override base selectors when keys conflict
-
-**Validation:** Checks for missing selector files before generation and suggests running `map` command if needed.
-
-### `sungen full`
-Run complete pipeline (discover + map + generate)
-
-```bash
-sungen full [options]
-
-Options:
-  --screen <name>   Process specific screen (optional)
-  --depth <num>     Max component depth
-  --force           Force regeneration
-  --verbose         Detailed output
-```
-
-### `sungen cache-clear`
-Clear all cached data
-
-```bash
-sungen cache-clear
-```
-
-### `sungen makeauth` ⭐ NEW
-Generate authentication state for login sessions (supports SSO and manual login)
-
-```bash
-sungen makeauth <name> [options]
-
-Options:
-  -u, --url <url>          Base URL of the application (auto-detected from playwright.config.ts)
-  -p, --path <path>        Login page path (default: /login)
-  -o, --output <dir>       Output directory (default: specs/.auth)
-  -t, --timeout <ms>       Overall timeout in milliseconds (default: 180000)
-  --nav-timeout <ms>       Navigation timeout in milliseconds (default: 180000)
-  --stability-wait <ms>    URL stability wait in milliseconds (default: 5000)
-  --headless               Run browser in headless mode
-  --verify                 Verify existing auth state is still valid
-  --list                   List all existing auth states
-  --export                 Export auth state as base64 for CI
-
-Examples:
-  sungen makeauth user               # Create auth state for 'user' role
-  sungen makeauth admin --url http://localhost:3000
-  sungen makeauth admin --path /auth/signin
-  sungen makeauth admin --list       # List all auth states
-  sungen makeauth admin --verify     # Check if auth is still valid
-```
-
-**What it does:**
-- Opens a browser window for manual login (including SSO providers like Google, GitHub, etc.)
-- Saves authentication state (cookies, localStorage, sessionStorage) to `specs/.auth/<name>.json`
-- Can be used in Playwright tests to skip login process and maintain sessions
-- Supports multiple auth roles (admin, user, guest, etc.)
-
-**Using auth state in tests:**
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  projects: [
-    {
-      name: 'authenticated',
-      use: {
-        storageState: 'specs/.auth/user.json',
-      },
-    },
-  ],
-});
-```
-
-See [docs/makeauth.md](docs/makeauth.md) for complete documentation.
-
-### `sungen auto-tag` ⭐ NEW
-Auto-inject stable `data-testid` attributes into source code
-
-```bash
-sungen auto-tag [options]
-
-Options:
-  --screen <name>   Tag specific screen (optional, defaults to all)
-  --dry-run         Preview changes without modifying files
-  --force           Overwrite existing data-testid (use with caution)
-  --verbose         Show detailed changes
-
-Examples:
-  sungen auto-tag --screen login --dry-run   # Preview changes
-  sungen auto-tag --screen login             # Apply changes
-  sungen auto-tag                            # Tag all screens
-```
-
-**What it does:**
-- Scans React/Vue/HTML source code for interactive elements
-- Injects `data-testid="screen-element"` attributes
-- Idempotent (skips if `data-testid` already exists)
-- Preserves code formatting (Prettier/ESLint compatible)
-
-**Before:**
-```tsx
-<input type="email" name="email" />
-<button onClick={handleSubmit}>Login</button>
-```
-
-**After:**
-```tsx
-<input type="email" name="email" data-testid="login-email-input" />
-<button onClick={handleSubmit} data-testid="login-submit-btn">Login</button>
-```
+Override files (`.override.yaml`) are never overwritten by `sungen map` and take precedence at runtime.
 
 ---
 
-## 🎓 Examples
+## CLI Commands
 
-See the `/examples` folder for complete working examples:
+| Command | Description |
+|---------|-------------|
+| `sungen init` | Initialize project structure |
+| `sungen add --screen <name> [--path <path>]` | Create screen definition |
+| `sungen live-scan --screen <name> [--headed]` | Scan live site to detect real Playwright selectors |
+| `sungen map --screen <name> [--force] [--scan-live]` | Generate selector/test-data YAML from Gherkin |
+| `sungen generate --screen <name> [--force]` | Generate Playwright .spec.ts |
+| `sungen full --screen <name>` | Run all: discover → map → generate |
+| `sungen auto-tag --screen <name> [--dry-run]` | Inject `data-testid` into source code |
+| `sungen makeauth <role>` | Save browser auth state (supports SSO) |
+| `sungen validate --screen <name>` | Validate features and mappings |
+| `sungen cache-clear` | Clear cached data |
 
-- **ai-chat** - Chat application with authentication
-- More examples coming soon!
+Use `sungen <command> -h` for detailed options.
 
 ---
 
-## 📚 Documentation
-
-### Getting Started
-- **[Documentation Index](docs/README.md)** - Start here for all documentation
-- **[Implementation Guide](docs/IMPLEMENTATION_GUIDE.md)** ⭐ **Core reference**
-  - Kim chỉ nam (North Star Principles)
-  - Architecture overview
-  - Implementation roadmap
-  - Best practices
-
-### Core Guides
-- **[System Overview](docs/SYSTEM_OVERVIEW.md)** - High-level architecture
-- **[Gherkin Core Standard](docs/gherkin-core-standard.md)** ⭐ **Must Read** - Complete Gherkin syntax rules ([Tiếng Việt](docs/gherkin-core-standard.vi.md))
-- **[Gherkin Standards](docs/GHERKIN_STANDARDS.md)** - Extended conventions and examples
-- **[Selector Override Guide](docs/SELECTOR_OVERRIDE_GUIDE.md)** - How to fix AI mapping errors
-- **[Debugging Guide](docs/DEBUGGING_GUIDE.md)** - Troubleshooting common issues
-
-### Recent Updates
-- **[Improvement Summary](docs/IMPROVEMENT_SUMMARY.md)** - Latest fixes and improvements (Dec 2025)
-  - Test results: 1 → 6 passed (+500%)
-  - Selector override mechanism
-  - Heuristic mapper implementation
-  - Complete test-data structure
-
-### Quick Links
-- **For QA**: Start with [Gherkin Core Standard](docs/gherkin-core-standard.md) ([Vietnamese](docs/gherkin-core-standard.vi.md))
-- **For Developers**: Read [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md)
-- **Fix AI Errors**: Use [Selector Override](docs/SELECTOR_OVERRIDE_GUIDE.md)
+## Documentation
 
----
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our contributing guidelines and follow the **Kim chỉ nam (North Star Principles)** in the [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md).
+- **[Gherkin Core Standard](docs/gherkin%20standards/gherkin-core-standard.md)** - Complete syntax rules ([Tiếng Việt](docs/gherkin%20standards/gherkin-core-standard.vi.md))
+- **[Pattern Reference](docs/pattern-reference.md)** - All 31 supported step patterns
+- **[Selector Override Guide](docs/selector-override.md)** - Fix AI mapping errors
+- **[Auth Setup Guide](docs/makeauth.md)** - Configure authentication states
+- **[Validation Guide](docs/validate.md)** - Validate Gherkin files
+- **[Windows Setup Guide](WINDOWS-SETUP-GUIDE.md)** - Step-by-step for Windows users
 
 ---
 
-## 📝 License
+## License
 
-MIT License - see LICENSE file for details
-
----
-
-## 🙏 Credits
-
-- Built with [Claude Sonnet 4.5](https://www.anthropic.com/claude)
-- Uses [@anthropic-ai/sdk](https://github.com/anthropics/anthropic-sdk-typescript)
-- Powered by [Playwright](https://playwright.dev/)
-- Gherkin parsing by [@cucumber/gherkin](https://github.com/cucumber/gherkin)
-
----
+MIT License - see LICENSE file for details.
 
 **Made with ❤️ by Bach Ngoc Hoai**