cbrowser 7.4.19 → 7.9.1

package/README.md

@@ -1,171 +1,23 @@
 # CBrowser (Cognitive Browser)
 
-**The browser automation built for AI agents, not human developers.**
-
-*CBrowser = Cognitive Browser — browser automation that thinks.*
-
-Most browser automation tools are built for humans writing scripts. CBrowser is built from the ground up as an MCP server for AI agents—natural language is the primary interface, not an afterthought.
+AI-powered browser automation designed for MCP-based AI agents. Built on Playwright with session persistence, self-healing selectors, constitutional safety boundaries, and natural language as the primary interface.
 
 [![npm version](https://badge.fury.io/js/cbrowser.svg)](https://www.npmjs.com/package/cbrowser)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP Ready](https://img.shields.io/badge/MCP-Remote%20%2B%20Local-blue)](https://modelcontextprotocol.io)
 
-## The AI-Native Difference
+## Why CBrowser?
 
-Traditional automation tools were built for developers writing scripts. CBrowser was built for **AI agents operating autonomously**. This fundamental difference shapes everything:
+Most browser automation libraries assume a human developer is writing and maintaining test scripts. When an AI agent needs to operate a browser autonomously across multiple calls, several problems arise:
 
-| Traditional Tools | CBrowser (AI-Native) |
-|-------------------|----------------------|
-| Scripts written by humans | Natural language as primary interface |
-| Stateless between calls | **Session persistence across calls** |
-| Manual test maintenance | **Self-healing selectors + AI test repair** |
-| Only does what you script | **Autonomous discovery (hunt_bugs)** |
-| Breaks when sites change | **Multi-dimensional baselines track drift** |
-| Single execution path | **Persona-based testing for real users** |
-| Fails silently | **Built-in chaos engineering for resilience** |
-| Developer perspective | **Constitutional safety for AI autonomy** |
+- **State is lost between calls.** Standard Playwright/Puppeteer sessions are ephemeral. An agent that logs in during one call loses that session on the next call. CBrowser persists cookies, localStorage, and session state across invocations.
+- **Selectors break silently.** When a site updates its DOM, CSS selectors stop working. CBrowser maintains a self-healing selector cache and generates alternative selectors automatically, so agents don't stall on stale selectors.
+- **There's no safety boundary.** An autonomous agent with unrestricted browser access can submit forms, make purchases, or delete data. CBrowser classifies actions by risk level and enforces verification requirements for destructive operations.
+- **Test maintenance is manual.** When tests break, someone has to figure out what changed and fix them. CBrowser can analyze failures, suggest repairs, and apply fixes automatically.
+- **Natural language is bolted on.** Most tools accept CSS selectors natively and treat natural language as a convenience layer. CBrowser treats natural language as the primary input, which is what AI agents actually produce.
 
 ---
 
-## 8 Things Only CBrowser Does
-
-### 1. 🤖 AI-Native Architecture
-
-Built from the ground up as an MCP server for AI agents. Every tool is designed to be called by Claude, not scripted by developers. Natural language is the primary interface—not a wrapper around CSS selectors.
-
-```bash
-# Remote MCP for Claude.ai
-https://cbrowser-mcp.wyldfyre.ai/mcp
-
-# Local MCP for Claude Desktop
-npx cbrowser mcp-server
-```
-
-### 2. 💬 Natural Language as First-Class Input
-
-Not just "convenience" natural language on top of selectors. The entire API is natural language native:
-
-```bash
-npx cbrowser smart-click "the blue submit button in the checkout form"
-npx cbrowser fill "email field" "user@example.com"
-npx cbrowser assert "page shows order confirmation with total over $50"
-```
-
-### 3. 🔍 Autonomous Discovery (hunt_bugs)
-
-Most tools wait for you to tell them what to test. CBrowser proactively hunts for bugs:
-
-```bash
-npx cbrowser hunt-bugs "https://your-site.com" --depth 3
-```
-
-It explores your site autonomously, finding broken links, console errors, accessibility violations, and UX issues you didn't know to look for.
-
-### 4. 💥 Built-in Chaos Engineering
-
-Inject failures to see how your site handles them:
-
-```bash
-npx cbrowser chaos-test "https://your-site.com" \
-  --inject network-slowdown,random-timeouts,failed-assets
-```
-
-### 5. 🔄 Self-Healing Selectors + AI Test Repair
-
-When elements change, CBrowser adapts automatically. When tests break, it repairs them:
-
-```bash
-# Auto-repair broken tests
-npx cbrowser repair-tests broken-test.txt --auto-apply --verify
-```
-
-### 6. 📊 Multi-Dimensional Baselines
-
-Not just visual diffs—CBrowser tracks visual appearance AND performance metrics together:
-
-```bash
-npx cbrowser visual-baseline "https://your-site.com" --with-performance
-npx cbrowser visual-compare --check-perf-regression
-```
-
-### 7. 👥 Persona-Based Testing
-
-Test as different user types with realistic human behavior:
-
-```bash
-npx cbrowser compare-personas \
-  --start "https://your-site.com" \
-  --goal "Complete checkout" \
-  --personas power-user,elderly-user,mobile-user,first-timer
-```
-
-Each persona has realistic timing, error rates, and attention patterns.
-
-### 8. 🗂️ Session Persistence Across Calls
-
-The killer feature for AI agents: state persists between invocations. Your AI agent can log in, do work across multiple calls, and maintain context—solving the statelessness problem that makes other tools impractical for agents.
-
-```bash
-npx cbrowser session save "logged-in"
-# ... later, in a new session ...
-npx cbrowser session load "logged-in"
-```
-
----
-
-## Constitutional AI Safety
-
-CBrowser is the only browser automation with built-in ethical boundaries—critical when AI agents operate autonomously:
-
-| Zone | Actions | Behavior |
-|------|---------|----------|
-| 🟢 **Green** | Navigate, read, screenshot | Auto-execute |
-| 🟡 **Yellow** | Click buttons, fill forms | Log and proceed |
-| 🔴 **Red** | Submit, delete, purchase | **Requires verification** |
-| ⬛ **Black** | Bypass auth, inject scripts | **Never executes** |
-
-This isn't optional safety theater—it's how you give AI agents browser access without risking catastrophic actions.
-
----
-
-## Feature Comparison
-
-### AI-Native Capabilities (Only CBrowser)
-
-| Capability | CBrowser | Skyvern | Browser-Use | Playwright |
-|------------|:--------:|:-------:|:-----------:|:----------:|
-| **Built as MCP Server** | ✅ Native | ❌ | ❌ | ❌ |
-| **Remote MCP (claude.ai)** | ✅ | ❌ | ❌ | ❌ |
-| **Session persistence** | ✅ | ❌ | ❌ | Manual |
-| **Autonomous bug hunting** | ✅ | ❌ | ❌ | ❌ |
-| **Chaos engineering** | ✅ | ❌ | ❌ | ❌ |
-| **Constitutional safety** | ✅ | ❌ | ❌ | ❌ |
-| **Multi-persona testing** | ✅ | ❌ | ❌ | ❌ |
-| **AI test repair** | ✅ | ❌ | ❌ | ❌ |
-| **Visual + perf baselines** | ✅ | ❌ | ❌ | ❌ |
-
-### Table Stakes (Everyone Has)
-
-| Feature | CBrowser | Others |
-|---------|:--------:|:------:|
-| Natural language selectors | ✅ | ✅ |
-| Self-healing selectors | ✅ | ✅ |
-| Screenshot capture | ✅ | ✅ |
-| Form filling | ✅ | ✅ |
-
----
-
-## Also Included
-
-| Traditional Automation | CBrowser |
-|------------------------|----------|
-| Brittle CSS selectors | AI vision: "click the blue login button" |
-| Breaks when DOM changes | **Self-healing selectors** adapt automatically |
-| Crashes on element not found | **Smart retry** finds alternatives |
-| Manual test assertions | **Natural language assertions** |
-| Scripted tests only | **AI test generation** from page analysis |
-| Stateless between runs | **Persistent sessions, cookies, localStorage** |
-
 ## Quick Start
 
 ### Option 1: PAI Skill Installation (Claude Code Users)
@@ -240,128 +92,264 @@ npx cbrowser assert "page contains 'Welcome'"
 npx cbrowser generate-tests "https://example.com"
 ```
 
-## v7.x Features
+---
+
+## Core Capabilities
 
-### AI Visual Regression (v7.0)
+### Natural Language Interface
 
-Semantic screenshot comparison using AI—not just pixel diffs:
+CBrowser accepts natural language descriptions for element selection, assertions, and test definitions. This is useful when AI agents need to interact with pages they haven't seen before, since they can describe what they want rather than knowing exact selectors.
 
 ```bash
-# Capture a baseline
-npx cbrowser ai-visual capture "https://example.com" --name homepage
+npx cbrowser smart-click "the blue submit button in the checkout form"
+npx cbrowser fill "email field" "user@example.com"
+npx cbrowser assert "page shows order confirmation with total over $50"
+```
 
-# Compare against baseline
-npx cbrowser ai-visual test "https://staging.example.com" homepage --html
+Element selection supports multiple strategies, tried in priority order:
 
-# List baselines
-npx cbrowser ai-visual list
+```bash
+# Natural language (default)
+cbrowser click "the main navigation menu"
+
+# Accessibility-based (ARIA selectors)
+cbrowser click "aria:button/Submit"
+
+# Visual description
+cbrowser click "visual:red button in header"
+
+# Semantic type
+cbrowser fill "semantic:email" "user@example.com"
+
+# Fallback to CSS when needed
+cbrowser click "css:#login-btn"
+```
+
+### Session Persistence
+
+AI agents typically need multiple calls to complete a task (log in, navigate, fill a form, submit). CBrowser saves and restores browser state so agents can pick up where they left off.
+
+```bash
+# Save session (cookies, localStorage, sessionStorage)
+cbrowser session save "logged-in" --url "https://example.com"
+
+# Load session in a later invocation
+cbrowser session load "logged-in"
+
+# List saved sessions with metadata
+cbrowser session list
+
+# Show detailed session info
+cbrowser session show "logged-in"
+
+# Manage sessions
+cbrowser session cleanup --older-than 30
+cbrowser session export "logged-in" --output session.json
+cbrowser session import session.json --name "restored"
 ```
 
-The AI understands what changed semantically (button moved, text changed, new section added) rather than flagging every pixel difference.
+### Self-Healing Selectors
 
-### Cross-Browser Visual Testing (v7.1)
+When an element isn't found, CBrowser automatically:
+1. Checks its selector cache for known alternatives on that domain
+2. Generates alternative selectors (text variants, ARIA roles, attributes)
+3. Tries each alternative with configurable retry logic
+4. Caches working selectors for future use
 
-Compare rendering across Chrome, Firefox, and Safari:
+This is particularly useful in CI/CD pipelines where site updates would otherwise break every test run.
 
 ```bash
-npx cbrowser cross-browser "https://example.com" --html
-npx cbrowser cross-browser "https://example.com" --browsers chromium,firefox,webkit
+# Smart click with retry
+npx cbrowser smart-click "Submit" --max-retries 5
+
+# Navigate then click
+npx cbrowser smart-click "Login" --url "https://example.com"
 ```
 
-### Responsive Visual Testing (v7.2)
+```typescript
+import { CBrowser } from 'cbrowser';
 
-Test across viewport sizes (mobile, tablet, desktop):
+const browser = new CBrowser();
+const result = await browser.smartClick("Submit Button", { maxRetries: 3 });
+
+console.log(result.success);        // true/false
+console.log(result.finalSelector);  // The selector that worked
+console.log(result.attempts);       // Array of all attempts
+console.log(result.aiSuggestion);   // AI suggestion if failed
+```
 
 ```bash
-npx cbrowser responsive "https://example.com" --html
-npx cbrowser responsive "https://example.com" --viewports mobile,tablet,desktop-lg
-npx cbrowser responsive viewports  # list available presets
+# View cache statistics
+npx cbrowser heal-stats
+
+# Clear the cache
+npx cbrowser heal-clear
 ```
 
-### A/B Visual Comparison (v7.3)
+### Constitutional Safety
+
+When AI agents operate browsers autonomously, they need guardrails to prevent destructive actions. CBrowser classifies every action by risk level:
+
+| Zone | Actions | Behavior |
+|------|---------|----------|
+| **Green** | Navigate, read, screenshot | Auto-execute |
+| **Yellow** | Click buttons, fill forms | Log and proceed |
+| **Red** | Submit, delete, purchase | Requires verification |
+| **Black** | Bypass auth, inject scripts | Never executes |
 
-Compare two different URLs (staging vs production, old vs new design):
+This means an AI agent can freely browse and gather information, but cannot accidentally submit a form or delete data without explicit verification. For testing scenarios where you need to override this:
 
 ```bash
-npx cbrowser ab "https://staging.example.com" "https://example.com" --html
-npx cbrowser ab "https://old.site.com" "https://new.site.com" --label-a "Old" --label-b "New"
+cbrowser click "Delete Account" --force
 ```
 
-### Modular Architecture (v7.4.1)
+---
 
-Tree-shakeable imports for smaller bundles:
+## Testing
 
-```typescript
-// Import everything (unchanged)
-import { CBrowser, runVisualRegression, detectFlakyTests } from 'cbrowser';
+### Natural Language Test Suites
 
-// Import only what you need (modular)
-import { runVisualRegression, runCrossBrowserTest } from 'cbrowser/visual';
-import { runNLTestSuite, detectFlakyTests, repairTest } from 'cbrowser/testing';
-import { huntBugs, runChaosTest, findElementByIntent } from 'cbrowser/analysis';
-import { capturePerformanceBaseline, detectPerformanceRegression } from 'cbrowser/performance';
+Write tests in plain English instead of code. Useful for QA teams or AI agents that need to define and run tests without writing Playwright scripts.
+
+```bash
+# Run tests from a file
+npx cbrowser test-suite login-test.txt --html
+
+# Run inline tests
+npx cbrowser test-suite --inline "go to https://example.com ; click login ; verify url contains /dashboard"
+
+# Dry run (parse without executing)
+npx cbrowser test-suite tests.txt --dry-run
+
+# Fuzzy matching for assertions
+npx cbrowser test-suite tests.txt --fuzzy-match
 ```
 
-| Module | Purpose |
-|--------|---------|
-| `cbrowser/visual` | Visual testing (regression, cross-browser, responsive, A/B) |
-| `cbrowser/testing` | Test automation (NL suites, repair, flaky detection, coverage) |
-| `cbrowser/analysis` | AI analysis (bug hunting, chaos testing, persona comparison) |
-| `cbrowser/performance` | Performance (baselines, regression detection) |
+**Test file format:**
 
----
+```txt
+# Test: Login Flow
+go to https://example.com
+click the login button
+type "user@example.com" in email field
+type "password123" in password field
+click submit
+verify url contains "/dashboard"
 
-## v6.0.0 Features
+# Test: Search Functionality
+go to https://example.com/search
+type "test query" in search box
+click search button
+verify page contains "results"
+take screenshot
+```
+
+**Supported instructions:**
 
-### Multi-Persona Comparison
+| Instruction | Examples |
+|-------------|----------|
+| **Navigate** | `go to https://...`, `navigate to https://...`, `open https://...` |
+| **Click** | `click the login button`, `click submit`, `press Enter` |
+| **Fill** | `type "value" in email field`, `fill username with "john"` |
+| **Select** | `select "Option A" from dropdown` |
+| **Scroll** | `scroll down`, `scroll up 5 times` |
+| **Wait** | `wait 2 seconds`, `wait for "Loading" appears` |
+| **Assert** | `verify page contains "Welcome"`, `verify url contains "/home"`, `verify title is "Dashboard"` |
+| **Screenshot** | `take screenshot` |
 
-Run the same journey with multiple personas in parallel and compare results:
+**Output options:**
 
 ```bash
-# Compare how different user types experience your site
-npx cbrowser compare-personas \
-  --start "https://example.com" \
-  --goal "Complete checkout" \
-  --personas power-user,first-timer,elderly-user,mobile-user
+# Continue after failures
+npx cbrowser test-suite tests.txt --continue-on-failure
+
+# Save JSON report
+npx cbrowser test-suite tests.txt --output results.json
+
+# Generate HTML report
+npx cbrowser test-suite tests.txt --html
+```
+
+**API usage:**
+
+```typescript
+import { parseNLTestSuite, runNLTestSuite, formatNLTestReport } from 'cbrowser';
 
-# Output:
-# ┌─────────────────┬──────────┬──────────┬──────────┬─────────────────┐
-# │ Persona         │ Success  │ Time     │ Friction │ Key Issues      │
-# ├─────────────────┼──────────┼──────────┼──────────┼─────────────────┤
-# │ power-user      │ ✓        │ 12.5s    │ 0        │ -               │
-# │ first-timer     │ ✓        │ 45.2s    │ 2        │ Confusing CTA   │
-# │ elderly-user    │ ✗        │ 120.3s   │ 5        │ Small buttons   │
-# │ mobile-user     │ ✓        │ 28.1s    │ 1        │ Scroll issue    │
-# └─────────────────┴──────────┴──────────┴──────────┴─────────────────┘
+const suite = parseNLTestSuite(`
+  # Test: Homepage
+  go to https://example.com
+  verify title contains "Example"
+  click the about link
+  verify url contains "/about"
+`, "My Test Suite");
+
+const result = await runNLTestSuite(suite, {
+  continueOnFailure: true,
+  screenshotOnFailure: true,
+});
+
+console.log(formatNLTestReport(result));
 ```
 
-**Generate reports:**
+### Natural Language Assertions
+
+Write assertions in plain English for use in scripts or standalone:
 
 ```bash
-# JSON report
-npx cbrowser compare-personas --start "..." --goal "..." --output report.json
+# Title assertions
+npx cbrowser assert "title contains 'Dashboard'"
+npx cbrowser assert "title is 'Home Page'"
 
-# HTML report (visual dashboard)
-npx cbrowser compare-personas --start "..." --goal "..." --html
+# URL assertions
+npx cbrowser assert "url contains '/login'"
+
+# Content assertions
+npx cbrowser assert "page contains 'Welcome back'"
+
+# Element assertions
+npx cbrowser assert "'#submit-btn' exists"
+
+# Count assertions
+npx cbrowser assert "5 buttons"
+npx cbrowser assert "3 links"
 ```
 
-**What you learn:**
-- Which personas struggle most (friction points)
-- Time differences between expert and beginner users
-- Mobile vs desktop experience gaps
-- Accessibility issues affecting specific user types
-- Actionable recommendations for improvement
+```typescript
+const result = await browser.assert("page contains 'Success'");
+console.log(result.passed);   // true/false
+console.log(result.message);  // Human-readable result
+console.log(result.actual);   // What was found
+console.log(result.expected); // What was expected
+```
+
+### AI Test Generation
 
-**Automatic recommendations:**
-- "Beginners take 3.5x longer than experts - consider adding more guidance"
-- "Mobile users experience 2x more friction - review mobile UX"
-- "Common friction: 'Button too small for touch', 'Form validation unclear'"
+Analyze any page and generate test scenarios automatically. Useful for bootstrapping test coverage on existing sites.
 
-## v6.2.0 Features
+```bash
+# Generate tests for a page
+npx cbrowser generate-tests "https://example.com"
+
+# Output specific format
+npx cbrowser generate-tests "https://example.com" --format playwright
+npx cbrowser generate-tests "https://example.com" --format cbrowser
+
+# Save to file
+npx cbrowser generate-tests "https://example.com" --output tests.ts
+```
+
+```typescript
+const result = await browser.generateTests("https://example.com");
+
+console.log(result.analysis);       // Page structure analysis
+console.log(result.tests);          // Generated test scenarios
+console.log(result.playwrightCode); // Playwright test code
+console.log(result.cbrowserScript); // CBrowser CLI script
+```
 
 ### AI Test Repair
 
-Automatically analyze failing tests and suggest or apply repairs:
+When tests break due to site changes, CBrowser can analyze the failures and suggest or apply repairs automatically. This reduces the maintenance burden of large test suites.
 
 ```bash
 # Analyze a broken test and see repair suggestions
@@ -377,7 +365,7 @@ npx cbrowser repair-tests tests.txt --auto-apply --verify
 npx cbrowser repair-tests tests.txt --auto-apply --output fixed-tests.txt
 ```
 
-**What it analyzes:**
+**Failure types and repair strategies:**
 
 | Failure Type | Detection | Repair Strategy |
 |--------------|-----------|-----------------|
@@ -386,24 +374,6 @@ npx cbrowser repair-tests tests.txt --auto-apply --output fixed-tests.txt
 | `timeout` | Step took too long | Add wait statements |
 | `element_not_interactable` | Element hidden/disabled | Add scroll/wait before interaction |
 
-**Example output:**
-
-```
-🔧 Analyzing test: Login Flow
-
-   → click the signin button
-     ✗ Failed: Failed to click: signin button
-     💡 Suggestions:
-        - Update selector to "Login" (70%)
-          → click "Login"
-        - Add wait before this step (50%)
-          → wait 2 seconds
-
-📊 SUMMARY
-  Total Failed Steps: 1
-  Repair Success Rate: 100%
-```
-
 **API usage:**
 
 ```typescript
@@ -416,17 +386,14 @@ const result = await repairTestSuite(suite, {
 
 console.log(formatRepairReport(result));
 
-// Export repaired test to file format
 for (const testResult of result.testResults) {
   console.log(exportRepairedTest(testResult));
 }
 ```
 
-## v6.3.0 Features
-
 ### Flaky Test Detection
 
-Identify unreliable tests by running them multiple times and analyzing consistency:
+Identify unreliable tests by running them multiple times and analyzing consistency. Useful for catching timing-sensitive tests before they cause CI failures.
 
 ```bash
 # Run tests 5 times (default) and detect flakiness
@@ -451,46 +418,6 @@ npx cbrowser flaky-check tests.txt --output flaky-report.json
 | **Per-Step Analysis** | Identifies which specific steps are unreliable |
 | **Duration Variance** | Detects timing-sensitive tests |
 
-**Example output:**
-
-```
-🔍 FLAKY TEST DETECTION REPORT
-══════════════════════════════════════════════════════════════
-
-📋 Suite: Login Tests
-   Runs per test: 5
-   Total duration: 45.2s
-
-──────────────────────────────────────────────────────────────
-TEST RESULTS
-──────────────────────────────────────────────────────────────
-
-✅ STABLE_PASS (5/5 passed, flakiness: 0%)
-   Login Flow
-   └─ Avg duration: 2.1s (±0.1s)
-
-⚠️  FLAKY (3/5 passed, flakiness: 80%)
-   Search Functionality
-   └─ Avg duration: 3.5s (±1.2s)
-   └─ Flaky steps:
-      • wait for "Loading" appears (60% flaky)
-      • verify page contains "results" (40% flaky)
-
-══════════════════════════════════════════════════════════════
-📊 SUMMARY
-══════════════════════════════════════════════════════════════
-
-✅ Overall Flakiness: 40%
-   Stable tests: 1 | Flaky tests: 1
-
-⚠️  Most flaky test: Search Functionality (80%)
-⚠️  Most flaky step: wait for "Loading" appears (60%)
-
-💡 RECOMMENDATIONS
-• Search Functionality: Add explicit waits, increase timeout
-• wait for "Loading" appears: Use more specific selector
-```
-
 **API usage:**
 
 ```typescript
@@ -506,220 +433,88 @@ const result = await detectFlakyTests(suite, {
 
 console.log(formatFlakyTestReport(result));
 
-// Access detailed analysis
 for (const test of result.testAnalyses) {
   if (test.isFlaky) {
     console.log(`${test.testName}: ${test.flakinessScore}% flaky`);
     for (const step of test.stepAnalysis) {
       if (step.isFlaky) {
-        console.log(`  └─ ${step.instruction}: ${step.flakinessScore}% flaky`);
+        console.log(`  - ${step.instruction}: ${step.flakinessScore}% flaky`);
       }
     }
   }
 }
 ```
 
-## v6.1.0 Features
-
-### Natural Language Test Suites
-
-Write tests in plain English - CBrowser parses and executes them:
-
-```bash
-# Run tests from a file
-npx cbrowser test-suite login-test.txt --html
-
-# Run inline tests (steps separated by semicolons)
-npx cbrowser test-suite --inline "go to https://example.com ; click login ; verify url contains /dashboard"
-```
-
-**Test file format:**
-
-```txt
-# Test: Login Flow
-go to https://example.com
-click the login button
-type "user@example.com" in email field
-type "password123" in password field
-click submit
-verify url contains "/dashboard"
-
-# Test: Search Functionality
-go to https://example.com/search
-type "test query" in search box
-click search button
-verify page contains "results"
-take screenshot
-```
+---
 
-**Supported instructions:**
+## Visual Testing
 
-| Instruction | Examples |
-|-------------|----------|
-| **Navigate** | `go to https://...`, `navigate to https://...`, `open https://...` |
-| **Click** | `click the login button`, `click submit`, `press Enter` |
-| **Fill** | `type "value" in email field`, `fill username with "john"` |
-| **Select** | `select "Option A" from dropdown` |
-| **Scroll** | `scroll down`, `scroll up 5 times` |
-| **Wait** | `wait 2 seconds`, `wait for "Loading" appears` |
-| **Assert** | `verify page contains "Welcome"`, `verify url contains "/home"`, `verify title is "Dashboard"` |
-| **Screenshot** | `take screenshot` |
+### AI Visual Regression
 
-**Output options:**
+Compare screenshots semantically rather than pixel-by-pixel. Traditional pixel diffing flags every minor rendering difference (anti-aliasing, font hinting). AI-based comparison understands what actually changed: a button moved, text was updated, a new section was added.
 
 ```bash
-# Continue after failures
-npx cbrowser test-suite tests.txt --continue-on-failure
-
-# Save JSON report
-npx cbrowser test-suite tests.txt --output results.json
-
-# Generate HTML report
-npx cbrowser test-suite tests.txt --html
-
-# Combined
-npx cbrowser test-suite tests.txt --output results.json --html
-```
-
-**API usage:**
-
-```typescript
-import { parseNLTestSuite, runNLTestSuite, formatNLTestReport } from 'cbrowser';
-
-const suite = parseNLTestSuite(`
-  # Test: Homepage
-  go to https://example.com
-  verify title contains "Example"
-  click the about link
-  verify url contains "/about"
-`, "My Test Suite");
+# Capture a baseline
+npx cbrowser ai-visual capture "https://example.com" --name homepage
 
-const result = await runNLTestSuite(suite, {
-  continueOnFailure: true,
-  screenshotOnFailure: true,
-});
+# Compare against baseline
+npx cbrowser ai-visual test "https://staging.example.com" homepage --html
 
-console.log(formatNLTestReport(result));
-// Pass rate: 100%
-// Tests: 1 passed, 0 failed
+# List baselines
+npx cbrowser ai-visual list
 ```
 
-## v5.0.0 Features
-
-### Smart Click with Auto-Retry
+### Cross-Browser Visual Testing
 
-When an element isn't found, CBrowser automatically:
-1. Checks the self-healing cache for known alternatives
-2. Generates alternative selectors (text variants, ARIA roles, attributes)
-3. Tries each alternative with configurable retry logic
-4. Caches working selectors for future use
+Compare how a page renders across Chrome, Firefox, and Safari to catch browser-specific layout issues:
 
 ```bash
-# Smart click with retry
-npx cbrowser smart-click "Submit" --max-retries 5
-
-# Navigate then click
-npx cbrowser smart-click "Login" --url "https://example.com"
+npx cbrowser cross-browser "https://example.com" --html
+npx cbrowser cross-browser "https://example.com" --browsers chromium,firefox,webkit
 ```
 
-```typescript
-import { CBrowser } from 'cbrowser';
+### Responsive Visual Testing
 
-const browser = new CBrowser();
-const result = await browser.smartClick("Submit Button", { maxRetries: 3 });
-
-console.log(result.success);        // true/false
-console.log(result.finalSelector);  // The selector that worked
-console.log(result.attempts);       // Array of all attempts
-console.log(result.aiSuggestion);   // AI suggestion if failed
-```
-
-### Natural Language Assertions
-
-Write assertions in plain English:
+Test across viewport sizes (mobile, tablet, desktop) to verify responsive layouts:
 
 ```bash
-# Title assertions
-npx cbrowser assert "title contains 'Dashboard'"
-npx cbrowser assert "title is 'Home Page'"
-
-# URL assertions
-npx cbrowser assert "url contains '/login'"
-
-# Content assertions
-npx cbrowser assert "page contains 'Welcome back'"
-
-# Element assertions
-npx cbrowser assert "'#submit-btn' exists"
-
-# Count assertions
-npx cbrowser assert "5 buttons"
-npx cbrowser assert "3 links"
-```
-
-```typescript
-const result = await browser.assert("page contains 'Success'");
-console.log(result.passed);   // true/false
-console.log(result.message);  // Human-readable result
-console.log(result.actual);   // What was found
-console.log(result.expected); // What was expected
+npx cbrowser responsive "https://example.com" --html
+npx cbrowser responsive "https://example.com" --viewports mobile,tablet,desktop-lg
+npx cbrowser responsive viewports  # list available presets
 ```
 
-### Self-Healing Selector Cache
+### A/B Visual Comparison
 
-CBrowser remembers which selectors work on each domain:
+Compare two different URLs side by side (e.g., staging vs production, old design vs new):
 
 ```bash
-# View cache statistics
-npx cbrowser heal-stats
-
-# Clear the cache
-npx cbrowser heal-clear
-```
-
-```typescript
-const stats = browser.getSelectorCacheStats();
-console.log(stats.totalEntries);    // 42
-console.log(stats.totalSuccesses);  // 156
-console.log(stats.topDomains);      // [{ domain: 'example.com', count: 15 }, ...]
+npx cbrowser ab "https://staging.example.com" "https://example.com" --html
+npx cbrowser ab "https://old.site.com" "https://new.site.com" --label-a "Old" --label-b "New"
 ```
 
-### AI Test Generation
+---
 
-Analyze any page and generate test scenarios automatically:
+## Analysis
 
-```bash
-# Generate tests for a page
-npx cbrowser generate-tests "https://example.com"
+### Autonomous Bug Hunting
 
-# Output specific format
-npx cbrowser generate-tests "https://example.com" --format playwright
-npx cbrowser generate-tests "https://example.com" --format cbrowser
+Rather than waiting for you to specify what to test, `hunt_bugs` explores a site autonomously and reports issues it finds: broken links, console errors, accessibility violations, and UX problems.
 
-# Save to file
-npx cbrowser generate-tests "https://example.com" --output tests.ts
+```bash
+npx cbrowser hunt-bugs "https://your-site.com" --depth 3
 ```
 
-```typescript
-const result = await browser.generateTests("https://example.com");
+### Chaos Engineering
 
-console.log(result.analysis);       // Page structure analysis
-console.log(result.tests);          // Generated test scenarios
-console.log(result.playwrightCode); // Playwright test code
-console.log(result.cbrowserScript); // CBrowser CLI script
-```
+Inject controlled failures to verify how your site handles degraded conditions:
 
-**Example generated test:**
-```typescript
-test('Login - Valid Credentials', async ({ page }) => {
-  await page.goto('https://example.com');
-  await page.locator('[name="email"]').fill('test@example.com');
-  await page.locator('[name="password"]').fill('password123');
-  await page.locator('button[type="submit"]').click();
-  await expect(page).toHaveURL(/dashboard/);
-});
+```bash
+npx cbrowser chaos-test "https://your-site.com" \
+  --inject network-slowdown,random-timeouts,failed-assets
 ```
 
+This is useful for verifying error states, loading indicators, and graceful degradation before they happen in production.
+
 ### Page Analysis
 
 Understand any page's structure:
@@ -730,206 +525,202 @@ npx cbrowser analyze "https://example.com"
 
 Output:
 ```
-📊 Page Analysis:
+Page Analysis:
    Title: Example Domain
    Forms: 1
      - form#login (3 fields)
-       🔐 Login form detected
+       Login form detected
    Buttons: 5
    Links: 12
-   Has Login: ✅
-   Has Search: ❌
-   Has Navigation: ✅
+   Has Login: yes
+   Has Search: no
+   Has Navigation: yes
 ```
 
-### MCP Server Integration
-
-CBrowser can run as an MCP server for both Claude Desktop (local) and claude.ai (remote).
+---
 
-#### Option 1: Remote MCP (claude.ai)
+## Persona-Based Testing
 
-Connect claude.ai directly to a remote CBrowser server:
+Test your site from different user perspectives. Each persona has realistic timing, error rates, and attention patterns that simulate how different types of users actually interact with interfaces.
 
-1. Deploy CBrowser on your server ([full guide](docs/REMOTE-MCP-SERVER.md))
-2. In claude.ai: Settings → Connectors → Add Custom Connector
-3. Add URL: `https://your-cbrowser-domain.com/mcp`
-4. Configure OAuth with Auth0 ([setup guide](docs/AUTH0-SETUP.md))
+```bash
+# Run an autonomous journey as a persona
+cbrowser journey "first-timer" \
+  --start "https://mysite.com" \
+  --goal "Complete signup"
 
-**Public Demo (rate-limited):** `https://cbrowser-mcp-demo.wyldfyre.ai/mcp`
-- No authentication required
-- Rate limit: 5 requests/minute, burst of 10
-- For evaluation purposes only
+# Compare how different user types experience the same flow
+npx cbrowser compare-personas \
+  --start "https://example.com" \
+  --goal "Complete checkout" \
+  --personas power-user,first-timer,elderly-user,mobile-user
+```
 
-**Authenticated Server:** `https://cbrowser-mcp.wyldfyre.ai/mcp`
-- **OAuth 2.1 via Auth0** - For claude.ai web interface ([setup guide](docs/AUTH0-SETUP.md))
-- **API Key** - For Claude Code CLI and programmatic access
-- No rate limits for authenticated users
+**Built-in Personas:**
 
-#### Option 2: Local MCP (Claude Desktop)
+| Persona | Description |
+|---------|-------------|
+| `power-user` | Fast, efficient, uses keyboard shortcuts |
+| `first-timer` | Slow, exploratory, reads everything |
+| `mobile-user` | Touch interface, small screen |
+| `elderly-user` | Larger text needs, slower interactions |
+| `impatient-user` | Quick to abandon on friction |
 
-Run CBrowser locally for Claude Desktop:
+**Example comparison output:**
 
-```bash
-npx cbrowser mcp-server
+```
+Persona          | Success | Time    | Friction | Key Issues
+-----------------+---------+---------+----------+------------------
+power-user       | pass    | 12.5s   | 0        | -
+first-timer      | pass    | 45.2s   | 2        | Confusing CTA
+elderly-user     | fail    | 120.3s  | 5        | Small buttons
+mobile-user      | pass    | 28.1s   | 1        | Scroll issue
 ```
 
-Add to Claude Desktop config (`~/.config/claude-desktop/config.json`):
+This helps identify which user groups struggle with your interface and where the friction points are, so you can prioritize UX improvements based on data rather than assumptions.
 
-```json
-{
-  "mcpServers": {
-    "cbrowser": {
-      "command": "npx",
-      "args": ["cbrowser", "mcp-server"]
-    }
-  }
-}
-```
+**Custom persona creation:**
 
-#### Available MCP Tools (31 total)
+```bash
+# Describe the user - AI generates appropriate parameters
+npx cbrowser persona create "impatient developer who hates slow UIs" --name speed-demon
+npx cbrowser persona create "elderly grandmother new to computers" --name grandma
 
-| Category | Tools |
-|----------|-------|
-| **Navigation** | `navigate`, `screenshot`, `extract` |
-| **Interaction** | `click`, `smart_click`, `fill`, `scroll`, `press_key` |
-| **Assertions** | `assert`, `analyze_page` |
-| **Testing** | `generate_tests`, `test_suite`, `repair_tests`, `flaky_check` |
-| **Visual** | `visual_baseline`, `visual_compare`, `responsive_test`, `cross_browser_test`, `ab_compare` |
-| **Personas** | `journey`, `compare_personas`, `create_persona`, `list_personas` |
-| **Sessions** | `save_session`, `load_session`, `list_sessions` |
-| **Analysis** | `hunt_bugs`, `chaos_test`, `performance_audit` |
-| **Utilities** | `heal_stats`, `list_baselines` |
+# List all personas (built-in + custom)
+npx cbrowser persona list
 
-See [Remote MCP Server Guide](docs/REMOTE-MCP-SERVER.md) for full deployment instructions.
+# View, export, import, delete
+npx cbrowser persona show speed-demon
+npx cbrowser persona export speed-demon
+npx cbrowser persona import custom-persona.json
+npx cbrowser persona delete speed-demon
+```
 
-## Core Features
+The AI generates appropriate timing, error rates, mouse behavior, attention patterns, and viewport based on your description.
 
-### AI-Powered Element Selection
+**Generate reports:**
 
 ```bash
-# Natural language
-cbrowser click "the main navigation menu"
-cbrowser fill "password field" "secret123"
-
-# Accessibility-based
-cbrowser click "aria:button/Submit"
+# JSON report
+npx cbrowser compare-personas --start "..." --goal "..." --output report.json
 
-# Visual description
-cbrowser click "visual:red button in header"
+# HTML report
+npx cbrowser compare-personas --start "..." --goal "..." --html
+```
 
-# Semantic type
-cbrowser fill "semantic:email" "user@example.com"
+---
 
-# Fallback to CSS
-cbrowser click "css:#login-btn"
-```
+## Performance
 
-### Session Persistence
+### Performance Metrics
 
 ```bash
-# Save session (cookies, localStorage, sessionStorage)
-cbrowser session save "logged-in" --url "https://example.com"
-
-# Load session
-cbrowser session load "logged-in"
+# Core Web Vitals
+npx cbrowser perf "https://example.com"
 
-# List sessions
-cbrowser session list
+# With budget
+npx cbrowser perf audit "https://example.com" --budget-lcp 2500
 ```
 
-### Persistent Browser Context
+### Performance Regression Detection
 
-Enable persistent mode to keep cookies and localStorage between CLI calls:
+Track performance baselines and detect regressions with configurable sensitivity to avoid false positives:
 
 ```bash
-npx cbrowser navigate "https://example.com" --persistent
-```
+npx cbrowser visual-baseline "https://your-site.com" --with-performance
+npx cbrowser visual-compare --check-perf-regression
 
-### Persona-Driven Testing
+# Sensitivity profiles: strict (CI/CD), normal (default), lenient (development)
+npx cbrowser perf-regression "https://example.com" baseline.json --sensitivity strict
+```
 
-```bash
-# Run autonomous journey as a persona
-cbrowser journey "first-timer" \
-  --start "https://mysite.com" \
-  --goal "Complete signup"
+---
 
-# List personas
-cbrowser persona list
-```
+## Modular Architecture
 
-**Built-in Personas:**
+CBrowser is split into tree-shakeable modules so you can import only what you need:
 
-| Persona | Description |
-|---------|-------------|
-| `power-user` | Tech-savvy, expects efficiency |
-| `first-timer` | New user, slow and exploratory |
-| `mobile-user` | Touch interface, small screen |
-| `elderly-user` | Vision/motor limitations |
-| `impatient-user` | Quick to abandon |
+```typescript
+// Import everything
+import { CBrowser, runVisualRegression, detectFlakyTests } from 'cbrowser';
 
-**AI Persona Creation (v5.3.0):**
+// Import specific modules
+import { runVisualRegression, runCrossBrowserTest } from 'cbrowser/visual';
+import { runNLTestSuite, detectFlakyTests, repairTest } from 'cbrowser/testing';
+import { huntBugs, runChaosTest, findElementByIntent } from 'cbrowser/analysis';
+import { capturePerformanceBaseline, detectPerformanceRegression } from 'cbrowser/performance';
+```
 
-Create custom personas from natural language descriptions:
+| Module | Purpose |
+|--------|---------|
+| `cbrowser/visual` | Visual testing (regression, cross-browser, responsive, A/B) |
+| `cbrowser/testing` | Test automation (NL suites, repair, flaky detection, coverage) |
+| `cbrowser/analysis` | AI analysis (bug hunting, chaos testing, persona comparison) |
+| `cbrowser/performance` | Performance (baselines, regression detection) |
 
-```bash
-# Describe the user - AI generates all parameters
-npx cbrowser persona create "impatient developer who hates slow UIs" --name speed-demon
-npx cbrowser persona create "elderly grandmother new to computers with tremors" --name grandma
-npx cbrowser persona create "distracted teenager on their phone"
+---
 
-# List all personas (built-in + custom)
-npx cbrowser persona list
+## MCP Server Integration
 
-# View full persona config
-npx cbrowser persona show speed-demon
+CBrowser runs as an MCP server for both Claude Desktop (local) and claude.ai (remote).
 
-# Export/import for sharing
-npx cbrowser persona export speed-demon
-npx cbrowser persona import custom-persona.json
+### Remote MCP (claude.ai)
 
-# Delete custom persona
-npx cbrowser persona delete speed-demon
-```
+Connect claude.ai directly to a remote CBrowser server:
 
-The AI analyzes your description and generates appropriate:
-- **Timing**: reaction times, click delays, typing speed
-- **Error rates**: misclicks, typos, accidental double-clicks
-- **Mouse behavior**: movement speed, jitter, overshoot
-- **Attention patterns**: reading style, scroll behavior, focus areas
-- **Viewport**: device-appropriate screen size
+1. Deploy CBrowser on your server ([full guide](docs/REMOTE-MCP-SERVER.md))
+2. In claude.ai: Settings > Connectors > Add Custom Connector
+3. Add URL: `https://your-cbrowser-domain.com/mcp`
+4. Configure OAuth with Auth0 ([setup guide](docs/AUTH0-SETUP.md))
 
-### Multi-Browser Support
+**Public Demo (rate-limited):** `https://cbrowser-mcp-demo.wyldfyre.ai/mcp`
+- No authentication required
+- Rate limit: 5 requests/minute, burst of 10
+- For evaluation purposes only
 
-```bash
-# Firefox
-npx cbrowser navigate "https://example.com" --browser firefox
+**Authenticated Server:** `https://cbrowser-mcp.wyldfyre.ai/mcp`
+- **OAuth 2.1 via Auth0** - For claude.ai web interface ([setup guide](docs/AUTH0-SETUP.md))
+- **API Key** - For Claude Code CLI and programmatic access
+- No rate limits for authenticated users
 
-# WebKit (Safari)
-npx cbrowser navigate "https://example.com" --browser webkit
-```
+### Local MCP (Claude Desktop)
 
-### Device Emulation
+Run CBrowser locally for Claude Desktop:
 
 ```bash
-# Mobile
-npx cbrowser navigate "https://example.com" --device iphone-15
+npx cbrowser mcp-server
+```
 
-# Tablet
-npx cbrowser navigate "https://example.com" --device ipad-pro-12
+Add to Claude Desktop config (`~/.config/claude-desktop/config.json`):
 
-# List devices
-npx cbrowser device list
+```json
+{
+  "mcpServers": {
+    "cbrowser": {
+      "command": "npx",
+      "args": ["cbrowser", "mcp-server"]
+    }
+  }
+}
 ```
 
-### Performance Metrics
+### Available MCP Tools (33 total)
 
-```bash
-# Core Web Vitals
-npx cbrowser perf "https://example.com"
+| Category | Tools |
+|----------|-------|
+| **Navigation** | `navigate`, `screenshot`, `extract` |
+| **Interaction** | `click`, `smart_click`, `fill`, `scroll`, `press_key` |
+| **Assertions** | `assert`, `analyze_page` |
+| **Testing** | `generate_tests`, `test_suite`, `repair_tests`, `flaky_check` |
+| **Visual** | `visual_baseline`, `visual_compare`, `responsive_test`, `cross_browser_test`, `ab_compare` |
+| **Personas** | `journey`, `compare_personas`, `create_persona`, `list_personas` |
+| **Sessions** | `save_session`, `load_session`, `list_sessions`, `delete_session` |
+| **Analysis** | `hunt_bugs`, `chaos_test`, `performance_audit`, `dismiss_overlay` |
+| **Utilities** | `heal_stats`, `list_baselines`, `status` |
 
-# With budget
-npx cbrowser perf audit "https://example.com" --budget-lcp 2500
-```
+See [Remote MCP Server Guide](docs/REMOTE-MCP-SERVER.md) for full deployment instructions.
+
+---
 
 ## API Usage
 
@@ -964,6 +755,8 @@ console.log(tests.playwrightCode);
 await browser.close();
 ```
 
+---
+
 ## Configuration
 
 ### Environment Variables
@@ -991,40 +784,83 @@ Create `.cbrowserrc.json`:
 }
 ```
 
-## Constitutional Safety
+---
 
-CBrowser classifies actions by risk level:
+## Multi-Browser Support
 
-| Zone | Actions | Behavior |
-|------|---------|----------|
-| **Green** | Navigate, read, screenshot | Auto-execute |
-| **Yellow** | Click, fill forms | Log and proceed |
-| **Red** | Submit, delete, purchase | Requires `--force` |
-| **Black** | Bypass auth, inject scripts | Never execute |
+```bash
+# Firefox
+npx cbrowser navigate "https://example.com" --browser firefox
+
+# WebKit (Safari)
+npx cbrowser navigate "https://example.com" --browser webkit
+```
+
+### Device Emulation
 
 ```bash
-# Bypass safety for testing
-cbrowser click "Delete Account" --force
+# Mobile
+npx cbrowser navigate "https://example.com" --device iphone-15
+
+# Tablet
+npx cbrowser navigate "https://example.com" --device ipad-pro-12
+
+# List devices
+npx cbrowser device list
+```
+
+### Persistent Browser Context
+
+Enable persistent mode to keep cookies and localStorage between CLI calls:
+
+```bash
+npx cbrowser navigate "https://example.com" --persistent
 ```
 
+---
+
 ## Performance
 
 CBrowser uses optimized Chromium launch flags for fast startup:
 
-- **~1 second** browser cold start (vs 3-5s default)
-- **Persistent context** keeps cookies between calls
-- **Self-healing cache** reduces retry overhead
+- ~1 second browser cold start (vs 3-5s default)
+- Persistent context keeps cookies between calls
+- Self-healing cache reduces retry overhead
+
+---
 
 ## Examples
 
 See the [`examples/`](examples/) directory:
 
-- `basic-usage.ts` - Navigation, extraction, sessions
-- `smart-automation.ts` - Smart click, assertions, test generation
-- `visual-testing.ts` - AI visual regression, cross-browser, responsive, A/B comparison
-- `remote-mcp.ts` - Remote MCP server, Auth0 OAuth, demo server setup
-- `journeys/checkout-flow.json` - Persona journey definition
-- `personas/custom-persona.json` - Custom persona template
+### TypeScript Examples
+- [`basic-usage.ts`](examples/basic-usage.ts) - Navigation, extraction, sessions
+- [`smart-automation.ts`](examples/smart-automation.ts) - Smart click, assertions, test generation
+- [`visual-testing.ts`](examples/visual-testing.ts) - AI visual regression, cross-browser, responsive, A/B comparison
+- [`remote-mcp.ts`](examples/remote-mcp.ts) - Remote MCP server, Auth0 OAuth, demo server setup
+
+### Workflow Recipes
+- [`workflows/e2e-login-checkout.md`](examples/workflows/e2e-login-checkout.md) - End-to-end login and checkout flow with session persistence
+- [`workflows/visual-regression-ci.md`](examples/workflows/visual-regression-ci.md) - Visual regression testing with baselines, cross-browser, and responsive checks
+- [`workflows/accessibility-audit.md`](examples/workflows/accessibility-audit.md) - Accessibility bug hunting with persona-based a11y testing
+- [`workflows/chaos-resilience-testing.md`](examples/workflows/chaos-resilience-testing.md) - Chaos engineering: network failures, slow responses, element removal
+- [`workflows/persona-comparison-report.md`](examples/workflows/persona-comparison-report.md) - Multi-persona comparison with heatmaps and prioritized recommendations
+
+### CI/CD Integration
+- [`ci-cd/github-actions.yml`](examples/ci-cd/github-actions.yml) - GitHub Actions workflow for NL tests, visual and perf regression
+- [`ci-cd/gitlab-ci.yml`](examples/ci-cd/gitlab-ci.yml) - GitLab CI pipeline with staged checks
+- [`ci-cd/README.md`](examples/ci-cd/README.md) - Setup guide and baseline management
+
+### Natural Language Tests
+- [`natural-language-tests/e-commerce-suite.txt`](examples/natural-language-tests/e-commerce-suite.txt) - E-commerce guest checkout, search, and mobile tests
+- [`natural-language-tests/auth-flow-suite.txt`](examples/natural-language-tests/auth-flow-suite.txt) - Login, invalid credentials, and password reset flows
+- [`natural-language-tests/README.md`](examples/natural-language-tests/README.md) - NL test syntax reference and tips
+
+### Configuration Templates
+- [`journeys/checkout-flow.json`](examples/journeys/checkout-flow.json) - Checkout journey definition
+- [`journeys/signup-flow.json`](examples/journeys/signup-flow.json) - User registration journey
+- [`personas/custom-persona.json`](examples/personas/custom-persona.json) - QA tester persona template
+- [`personas/accessibility-tester.json`](examples/personas/accessibility-tester.json) - Visual impairment persona with screen magnification
 
 ## Troubleshooting