cbrowser 16.7.0 → 16.7.1

package/README.md

@@ -21,11 +21,11 @@
 | Capability | Status | Why It Matters |
 |------------|--------|----------------|
 | **Natural Language Tests** | ⭐ Best-in-class | Write tests in plain English. 10-step E2E flows run 100% stable. |
-| **Cognitive User Simulation** | 🔬 Novel | 12 research-backed traits model real human behavior—not just clicks. |
+| **Cognitive User Simulation** | 🔬 Novel | 25 research-backed traits model real human behavior—not just clicks. |
 | **Empathy Accessibility Audits** | 🔬 Novel | Simulate users with tremors, low vision, ADHD. No competitor offers this. |
 | **Self-Healing Selectors** | ✅ Production-ready | ARIA-first with 0.8+ confidence gating. Handles DOM changes automatically. |
 | **Constitutional AI Safety** | 🔬 Novel | Risk-classified actions prevent autonomous agents from doing damage. |
-| **45 MCP Tools** | ✅ Production-ready | Full Claude integration—local and remote servers. |
+| **48 MCP Tools** | ✅ Production-ready | Full Claude integration—local and remote servers. |
 
 ---
 
@@ -271,7 +271,7 @@ Deploy your own: see [Remote MCP Server Guide](docs/REMOTE-MCP-SERVER.md)
 }
 ```
 
-### 45 MCP Tools
+### 48 MCP Tools
 
 | Category | Tools |
 |----------|-------|

package/docs/GETTING-STARTED.md

@@ -0,0 +1,226 @@
+# Getting Started with CBrowser
+
+CBrowser (Cognitive Browser) is the browser automation that thinks like your users. This guide will get you up and running quickly.
+
+## Installation
+
+```bash
+npm install cbrowser
+npx playwright install chromium
+```
+
+## Your First Commands
+
+### Navigate to a Page
+
+```bash
+npx cbrowser navigate "https://example.com"
+```
+
+### Click with Self-Healing Selectors
+
+```bash
+npx cbrowser smart-click "Add to Cart"
+```
+
+CBrowser uses AI to find elements by description, not brittle CSS selectors. If the DOM changes, the self-healing system adapts automatically.
+
+### Natural Language Assertions
+
+```bash
+npx cbrowser assert "page contains 'Order Confirmed'"
+```
+
+### Take a Screenshot
+
+```bash
+npx cbrowser screenshot --path order-confirmation.png
+```
+
+## Cognitive User Simulation
+
+This is what makes CBrowser unique. Instead of just clicking buttons, it simulates how real users think:
+
+```bash
+npx cbrowser cognitive-journey \
+  --persona first-timer \
+  --start "https://example.com" \
+  --goal "complete checkout"
+```
+
+The simulation tracks:
+- **Patience** - Will they wait for slow pages?
+- **Confusion** - Are they getting lost?
+- **Frustration** - Are errors piling up?
+- **Abandonment** - When will they give up?
+
+### Output Example
+
+```
+=== Cognitive Journey: first-timer ===
+Goal: complete checkout
+Start: https://example.com
+
+Step 1: Looking for product catalog
+  Action: click "Shop Now"
+  Patience: 95% | Confusion: 5%
+
+Step 2: Found products, browsing
+  Action: click first product
+  Patience: 90% | Confusion: 10%
+
+...
+
+Step 8: ABANDONED
+  Reason: Patience depleted (8%)
+  Thought: "This password form is too confusing..."
+  Friction points:
+    - Password requirements unclear (step 6)
+    - Form validation error not visible (step 7)
+```
+
+## Built-in Personas
+
+| Persona | Description |
+|---------|-------------|
+| `power-user` | Tech-savvy, expects efficiency |
+| `first-timer` | New user, explores carefully |
+| `mobile-user` | Smartphone, touch interface |
+| `elderly-user` | Patient, careful, vision/motor considerations |
+| `impatient-user` | Quick to abandon on friction |
+| `screen-reader-user` | Uses assistive technology |
+
+## Create Custom Personas
+
+Use the questionnaire system to create research-backed custom personas:
+
+```bash
+# Interactive questionnaire
+npx cbrowser persona-questionnaire start --name "anxious-newbie"
+
+# The system asks behavioral questions and derives trait values
+# with proper research-backed correlations
+```
+
+## Natural Language Tests
+
+Write tests in plain English:
+
+```txt
+# checkout-test.txt
+go to https://example.com/products
+click "Add to Cart" button
+verify page contains "1 item in cart"
+click checkout
+fill email with "test@example.com"
+click "Place Order"
+verify url contains "/confirmation"
+```
+
+Run them:
+
+```bash
+npx cbrowser test-suite checkout-test.txt --html
+```
+
+## Visual Testing
+
+### Capture Baseline
+
+```bash
+npx cbrowser ai-visual capture "https://example.com" --name homepage
+```
+
+### Test Against Baseline
+
+```bash
+npx cbrowser ai-visual test "https://staging.example.com" homepage --html
+```
+
+### Cross-Browser Comparison
+
+```bash
+npx cbrowser cross-browser "https://example.com" --html
+```
+
+### Responsive Testing
+
+```bash
+npx cbrowser responsive "https://example.com" --html
+```
+
+## Constitutional AI Safety
+
+CBrowser classifies every action by risk level:
+
+| Zone | Examples | 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 prevents AI agents from accidentally submitting forms, deleting data, or making purchases.
+
+## API Key for Cognitive Features
+
+Some features require an Anthropic API key:
+
+```bash
+npx cbrowser config set-api-key
+```
+
+## MCP Integration
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cbrowser": {
+      "command": "npx",
+      "args": ["cbrowser", "mcp-server"]
+    }
+  }
+}
+```
+
+### claude.ai (Remote)
+
+Use the public demo server:
+```
+https://cbrowser-mcp-demo.wyldfyre.ai/mcp
+```
+
+Or deploy your own: see [MCP Integration](./MCP-INTEGRATION.md).
+
+## Next Steps
+
+- [Cognitive Simulation](./COGNITIVE-SIMULATION.md) - Deep dive into user simulation
+- [Persona Questionnaire](./PERSONA-QUESTIONNAIRE.md) - Create custom personas
+- [Natural Language Tests](./NATURAL-LANGUAGE-TESTS.md) - Write tests in English
+- [Visual Testing](./VISUAL-TESTING.md) - Screenshot-based regression testing
+- [MCP Integration](./MCP-INTEGRATION.md) - Full Claude integration guide
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `npx cbrowser navigate <url>` | Navigate to URL |
+| `npx cbrowser click <selector>` | Click element |
+| `npx cbrowser smart-click <text>` | AI-powered click |
+| `npx cbrowser fill <selector> <value>` | Fill input |
+| `npx cbrowser screenshot` | Capture screenshot |
+| `npx cbrowser assert <assertion>` | Verify condition |
+| `npx cbrowser cognitive-journey` | Run user simulation |
+| `npx cbrowser test-suite <file>` | Run NL tests |
+| `npx cbrowser ai-visual capture` | Capture baseline |
+| `npx cbrowser ai-visual test` | Run visual test |
+| `npx cbrowser cross-browser` | Cross-browser test |
+| `npx cbrowser responsive` | Responsive test |
+| `npx cbrowser agent-ready-audit` | Audit for AI agents |
+| `npx cbrowser empathy-audit` | Disability simulation |
+| `npx cbrowser persona-questionnaire` | Create custom persona |
+| `npx cbrowser status` | Check environment |

package/docs/MCP-INTEGRATION.md

@@ -0,0 +1,295 @@
+# MCP Server Integration
+
+CBrowser provides full Model Context Protocol (MCP) integration for Claude Desktop and claude.ai.
+
+## Quick Setup
+
+### Local MCP (Claude Desktop)
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cbrowser": {
+      "command": "npx",
+      "args": ["cbrowser", "mcp-server"]
+    }
+  }
+}
+```
+
+### Remote MCP (claude.ai)
+
+**Public Demo Server** (rate-limited, for evaluation):
+```
+URL: https://cbrowser-mcp-demo.wyldfyre.ai/mcp
+Rate limit: 5 requests/minute, burst of 10
+```
+
+**Deploy Your Own:**
+```bash
+# Default (no auth)
+npx cbrowser mcp-remote
+
+# With API key
+MCP_API_KEY=your-secret npx cbrowser mcp-remote
+
+# With Auth0 OAuth
+AUTH0_DOMAIN=your-tenant.auth0.com \
+AUTH0_AUDIENCE=https://your-server/ \
+npx cbrowser mcp-remote
+
+# Custom port
+PORT=8080 npx cbrowser mcp-remote
+```
+
+## All 48 MCP Tools
+
+### Navigation (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `navigate` | Navigate to URL with intelligent wait detection |
+| `screenshot` | Capture page screenshot |
+| `extract` | Extract structured data (links, headings, forms, images, text) |
+| `cloudflare_detect` | Detect Cloudflare protection |
+| `cloudflare_wait` | Wait for Cloudflare challenge completion |
+
+### Interaction (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `click` | Click element by selector or description |
+| `smart_click` | Self-healing click with retry and selector recovery |
+| `fill` | Fill form input with value |
+| `scroll` | Scroll page or element |
+
+### Testing (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `nl_test_file` | Run natural language test suite from file |
+| `nl_test_inline` | Run natural language tests from inline content |
+| `repair_test` | AI-powered test repair for broken tests |
+| `detect_flaky_tests` | Identify unreliable tests by running multiple times |
+
+### Visual Testing (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `visual_baseline` | Capture visual baseline for URL |
+| `visual_regression` | Compare current page against baseline |
+| `cross_browser_test` | Test across Chrome, Firefox, Safari |
+| `cross_browser_diff` | Quick metrics comparison across browsers |
+| `responsive_test` | Test across viewport sizes |
+| `ab_comparison` | Compare two URLs visually |
+
+### Cognitive Simulation (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `cognitive_journey_init` | Initialize cognitive user simulation |
+| `cognitive_journey_update_state` | Update mental state during journey |
+| `compare_personas` | Compare experience across personas |
+
+### Persona Questionnaire (3 tools) - *New in v16.6.0*
+
+| Tool | Description |
+|------|-------------|
+| `persona_questionnaire_get` | Generate questionnaire questions for custom persona |
+| `persona_questionnaire_build` | Build trait profile from questionnaire answers |
+| `persona_trait_lookup` | Look up behaviors for specific trait value |
+
+### Analysis (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `hunt_bugs` | Autonomous bug hunting and issue discovery |
+| `chaos_test` | Inject failures and test resilience |
+| `agent_ready_audit` | Analyze site for AI-agent friendliness |
+| `competitive_benchmark` | Compare UX across competitor sites |
+| `empathy_audit` | Simulate users with disabilities |
+
+### Performance (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `perf_baseline` | Capture performance baseline |
+| `perf_regression` | Detect performance regression |
+| `list_baselines` | List all saved baselines |
+
+### Stealth (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `stealth_enable` | Enable stealth mode |
+| `stealth_disable` | Disable stealth mode |
+| `stealth_status` | Check current stealth status |
+| `stealth_check` | Check for bot detection |
+| `stealth_diagnose` | Diagnose detection issues |
+
+### Utility (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `save_session` | Save browser session (cookies, storage) |
+| `load_session` | Load saved session |
+| `list_sessions` | List saved sessions |
+| `delete_session` | Delete saved session |
+
+### Persona (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_cognitive_personas` | List all available personas |
+| `find_element_by_intent` | AI-powered semantic element finding |
+| `dismiss_overlay` | Dismiss modal overlays (cookies, popups) |
+| `status` | Get CBrowser environment status |
+
+## Tool Usage Examples
+
+### Cognitive Journey with Custom Persona
+
+```
+// Step 1: Get questionnaire
+persona_questionnaire_get({ comprehensive: false })
+
+// Step 2: Build traits from answers
+persona_questionnaire_build({
+  answers: { patience: 0.25, curiosity: 0.75 },
+  name: "anxious-explorer"
+})
+
+// Step 3: Run journey with custom persona
+cognitive_journey_init({
+  persona: "anxious-explorer",
+  startUrl: "https://example.com",
+  goal: "complete checkout"
+})
+```
+
+### Agent-Ready Audit
+
+```
+agent_ready_audit({ url: "https://example.com" })
+
+// Returns:
+// - Overall score (0-100)
+// - Grade (A-F)
+// - Findability, stability, accessibility scores
+// - Issues with remediation suggestions
+```
+
+### Visual Regression
+
+```
+// Capture baseline
+visual_baseline({ url: "https://example.com", name: "homepage" })
+
+// Later, compare against baseline
+visual_regression({ url: "https://staging.example.com", baselineName: "homepage" })
+```
+
+### Competitive Benchmark
+
+```
+competitive_benchmark({
+  sites: [
+    "https://yoursite.com",
+    "https://competitor-a.com",
+    "https://competitor-b.com"
+  ],
+  goal: "sign up for free trial",
+  persona: "first-timer"
+})
+```
+
+## Authentication Methods
+
+### API Key Authentication
+
+For Claude Code CLI and scripts:
+
+```bash
+# Bearer token
+curl -H "Authorization: Bearer your-api-key" https://your-server/mcp
+
+# X-API-Key header
+curl -H "X-API-Key: your-api-key" https://your-server/mcp
+```
+
+Configure multiple keys:
+```bash
+MCP_API_KEYS=key1,key2,key3 npx cbrowser mcp-remote
+```
+
+### Auth0 OAuth
+
+For claude.ai web interface:
+
+1. Set up Auth0 tenant
+2. Configure environment:
+   ```bash
+   AUTH0_DOMAIN=your-tenant.auth0.com
+   AUTH0_AUDIENCE=https://your-server/
+   ```
+3. In claude.ai: Settings > Integrations > Custom Connectors
+4. Add connector URL and complete OAuth flow
+
+Features:
+- OAuth 2.1 with PKCE
+- JWT and opaque token validation
+- 30-minute token caching
+- Protected Resource Metadata via `/.well-known/oauth-protected-resource`
+
+### Dual Authentication
+
+Both OAuth and API keys can be enabled simultaneously for maximum flexibility.
+
+## Server Endpoints
+
+| Endpoint | Description | Auth |
+|----------|-------------|------|
+| `/mcp` | MCP protocol endpoint | Required if configured |
+| `/health` | Health check | Always open |
+| `/info` | Server info | Always open |
+| `/.well-known/oauth-protected-resource` | OAuth metadata | If Auth0 configured |
+
+## Docker Deployment
+
+```yaml
+# docker-compose.yml
+version: "3.8"
+services:
+  cbrowser-mcp:
+    image: ghcr.io/alexandriashai/cbrowser:latest
+    command: ["mcp-remote"]
+    ports:
+      - "3000:3000"
+    environment:
+      - MCP_API_KEY=${MCP_API_KEY}
+      - PORT=3000
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+1. Verify server is running: `curl http://localhost:3000/health`
+2. Check authentication: `curl -H "Authorization: Bearer key" http://localhost:3000/info`
+3. Verify MCP endpoint: `curl -X POST http://localhost:3000/mcp`
+
+### Claude Desktop Not Detecting Tools
+
+1. Restart Claude Desktop after config changes
+2. Verify config path: `~/.config/claude/claude_desktop_config.json`
+3. Check npx is in PATH
+4. Verify cbrowser is installed: `npx cbrowser --version`
+
+### Rate Limiting on Demo Server
+
+The demo server is rate-limited for evaluation. For production use:
+1. Deploy your own server
+2. Use API key authentication
+3. Configure appropriate rate limits

package/docs/PERSONA-QUESTIONNAIRE.md

@@ -0,0 +1,322 @@
+# Persona Questionnaire System
+
+**Introduced in v16.6.0**
+
+The Persona Questionnaire system provides research-backed trait mapping for creating custom cognitive personas. Instead of defaulting traits to 0.5 (neutral baseline), this system uses behavioral questions to derive differentiated trait profiles.
+
+## The Problem
+
+When creating custom personas, AI-generated profiles often defaulted many traits to 0.5. This creates "average" personas that don't accurately represent real user diversity.
+
+## The Solution
+
+The questionnaire system:
+1. Maps behavioral answers to trait values (0-1 scale)
+2. Uses 5 distinct behavioral levels per trait (0, 0.25, 0.5, 0.75, 1.0)
+3. Applies research-backed correlations between traits
+4. Provides behavioral descriptions based on academic research
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Interactive 8-question questionnaire
+npx cbrowser persona-questionnaire start
+
+# Comprehensive 25-trait questionnaire
+npx cbrowser persona-questionnaire start --comprehensive --name "my-persona"
+
+# Look up trait behavior at specific value
+npx cbrowser persona-questionnaire lookup --trait patience --value 0.25
+
+# List all available traits
+npx cbrowser persona-questionnaire list-traits
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  generatePersonaQuestionnaire,
+  buildTraitsFromAnswers,
+  getTraitBehaviors,
+  getTraitLabel,
+} from 'cbrowser';
+
+// Generate questionnaire
+const questionnaire = generatePersonaQuestionnaire({ comprehensive: false });
+
+// Build traits from answers
+const traits = buildTraitsFromAnswers({
+  patience: 0.25,
+  riskTolerance: 0.75,
+  curiosity: 1.0,
+});
+
+// Look up specific trait behavior
+const behaviors = getTraitBehaviors('patience', 0.25);
+console.log(behaviors.label);       // "Low"
+console.log(behaviors.behaviors);   // ["Gets frustrated quickly", ...]
+```
+
+### MCP Tools
+
+Three MCP tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `persona_questionnaire_get` | Generate questionnaire questions |
+| `persona_questionnaire_build` | Build trait profile from answers |
+| `persona_trait_lookup` | Look up behaviors for trait value |
+
+## The 25 Cognitive Traits
+
+| Trait | Research Basis | What It Models |
+|-------|---------------|----------------|
+| **patience** | UX research | Time before abandoning on friction |
+| **riskTolerance** | Prospect theory | Willingness to try unfamiliar actions |
+| **comprehension** | Cognitive load theory | UI pattern understanding |
+| **persistence** | Motivation research | Retry behavior after failures |
+| **curiosity** | Exploration theory | Feature discovery tendency |
+| **workingMemory** | Cognitive psychology | Multi-step task handling |
+| **readingTendency** | Eye-tracking studies | Text consumption behavior |
+| **resilience** | Positive psychology | Bounce-back from errors |
+| **selfEfficacy** | Bandura (1977) | Belief in problem-solving ability |
+| **satisficing** | Simon (1956) | Accept "good enough" vs optimize |
+| **trustCalibration** | Fogg (2003) | Trust in unfamiliar interfaces |
+| **interruptRecovery** | Mark et al. (2005) | Resume after distractions |
+| **decisionFatigue** | Baumeister | Decision quality over time |
+| **internalAttribution** | Attribution theory | Self-blame for failures |
+| **externalAttribution** | Attribution theory | System-blame for failures |
+| **techSavviness** | Digital literacy | Familiarity with UI patterns |
+| **attentionSpan** | Attention research | Focus duration |
+| **impulsivity** | Behavioral psychology | Quick vs deliberate actions |
+| **errorRecovery** | Human factors | Speed of correcting mistakes |
+| **visualProcessing** | Cognitive science | Image vs text preference |
+| **spatialMemory** | Navigation research | UI layout recall |
+| **patternRecognition** | Expertise research | UI element identification |
+| **riskPerception** | Risk psychology | Danger assessment |
+| **socialProof** | Cialdini (1984) | Influence of others' actions |
+| **authorityTrust** | Trust research | Trust in official sources |
+
+## Trait Reference Matrix
+
+Each trait has 5 behavioral levels with specific descriptions:
+
+### Example: Patience Trait
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0 | Very Low | Abandons at first sign of friction, expects instant results |
+| 0.25 | Low | Gets frustrated quickly, skips slow-loading content |
+| 0.5 | Moderate | Waits reasonable time, tolerates some friction |
+| 0.75 | High | Patient with delays, reads loading messages |
+| 1.0 | Very High | Extremely patient, waits through any delay |
+
+### Example: Self-Efficacy Trait
+
+| Value | Label | Behaviors |
+|-------|-------|-----------|
+| 0 | Very Low | "I can't do this", gives up immediately on challenge |
+| 0.25 | Low | Doubts ability, abandons 40% faster than average |
+| 0.5 | Moderate | Normal confidence, persists through minor challenges |
+| 0.75 | High | Confident problem-solver, sees obstacles as puzzles |
+| 1.0 | Very High | "I'll figure this out", never attributes failure to self |
+
+## Trait Correlations
+
+The system automatically applies research-backed correlations:
+
+| Primary Trait | Correlated Trait | Relationship |
+|---------------|------------------|--------------|
+| Low selfEfficacy | High internalAttribution | Self-blame for failures |
+| Low selfEfficacy | Low resilience | Slower bounce-back |
+| Low patience | Low resilience | Less tolerance for errors |
+| High curiosity | Higher exploration | More feature discovery |
+| Low trustCalibration | Longer evaluation time | Scrutinizes CTAs |
+
+## Questionnaire Formats
+
+### Quick Questionnaire (8 traits)
+
+Core traits for basic persona differentiation:
+- patience, riskTolerance, comprehension, persistence
+- curiosity, workingMemory, readingTendency, resilience
+
+### Comprehensive Questionnaire (25 traits)
+
+All cognitive traits for detailed behavioral modeling.
+
+### Custom Selection
+
+Request specific traits:
+
+```typescript
+const questionnaire = generatePersonaQuestionnaire({
+  traits: ['patience', 'selfEfficacy', 'trustCalibration'],
+});
+```
+
+## AskUserQuestion Integration
+
+For Claude sessions, use the `formatForAskUserQuestion` function:
+
+```typescript
+import { formatForAskUserQuestion, generatePersonaQuestionnaire } from 'cbrowser';
+
+const questionnaire = generatePersonaQuestionnaire({ comprehensive: false });
+const askUserFormat = formatForAskUserQuestion(questionnaire.questions);
+
+// Returns format compatible with Claude's AskUserQuestion tool:
+// {
+//   questions: [
+//     {
+//       question: "How does this user handle waiting?",
+//       header: "patience",
+//       options: [
+//         { label: "Very impatient", description: "Abandons at first delay" },
+//         ...
+//       ],
+//       multiSelect: false
+//     },
+//     ...
+//   ]
+// }
+```
+
+## CLI Interactive Mode
+
+The CLI provides an interactive questionnaire experience:
+
+```bash
+$ npx cbrowser persona-questionnaire start --name "anxious-newbie"
+
+=== CBrowser Persona Questionnaire ===
+Creating persona: anxious-newbie (8 core traits)
+
+[1/8] Patience
+How does this user handle waiting for pages or actions?
+  1. Very impatient - abandons at first delay
+  2. Somewhat impatient - frustrated by normal load times
+  3. Average - tolerates reasonable waits
+  4. Patient - waits through delays calmly
+  5. Very patient - unlimited patience
+> 2
+
+[2/8] Risk Tolerance
+How willing is this user to try unfamiliar features?
+...
+
+=== Persona Created ===
+Saved to: ~/.cbrowser/personas/anxious-newbie.json
+```
+
+## Using Custom Personas
+
+After creating a persona via questionnaire:
+
+```typescript
+import { runCognitiveJourney } from 'cbrowser';
+
+const result = await runCognitiveJourney({
+  persona: 'anxious-newbie',  // Uses saved persona
+  startUrl: 'https://example.com',
+  goal: 'complete signup',
+});
+```
+
+Or with inline traits:
+
+```typescript
+const customTraits = buildTraitsFromAnswers({
+  patience: 0.25,
+  selfEfficacy: 0.25,
+  trustCalibration: 0.25,
+});
+
+const result = await runCognitiveJourney({
+  persona: 'custom',
+  customTraits,
+  startUrl: 'https://example.com',
+  goal: 'complete signup',
+});
+```
+
+## Research Citations
+
+The trait system is grounded in academic research:
+
+- **Bandura, A. (1977)** - Self-Efficacy: Toward a Unifying Theory of Behavioral Change
+- **Kahneman, D. & Tversky, A.** - Prospect Theory and Decision Making
+- **Simon, H. (1956)** - Satisficing and Administrative Behavior
+- **Fogg, B.J. (2003)** - Persuasive Technology and Trust
+- **Mark, G. et al. (2005)** - No Task Left Behind: Interrupt Recovery
+- **Baumeister, R.** - Ego Depletion and Decision Fatigue
+- **Nielsen, J.** - Usability Engineering and User Behavior
+- **Cialdini, R. (1984)** - Influence: The Psychology of Persuasion
+
+## API Reference
+
+### generatePersonaQuestionnaire(options)
+
+Generate questionnaire questions.
+
+```typescript
+interface QuestionnaireOptions {
+  comprehensive?: boolean;     // All 25 traits (default: false = 8 traits)
+  traits?: string[];           // Specific traits to include
+  includeResearch?: boolean;   // Include research citations
+}
+
+const questionnaire = generatePersonaQuestionnaire(options);
+// Returns: { questions: Question[], estimatedMinutes: number }
+```
+
+### buildTraitsFromAnswers(answers)
+
+Build complete trait profile from questionnaire answers.
+
+```typescript
+const traits = buildTraitsFromAnswers({
+  patience: 0.25,
+  curiosity: 0.75,
+});
+// Returns: CognitiveTraits with correlations applied
+```
+
+### getTraitBehaviors(trait, value)
+
+Get behavioral description for a trait value.
+
+```typescript
+const behaviors = getTraitBehaviors('patience', 0.25);
+// Returns: { label: string, description: string, behaviors: string[] }
+```
+
+### getTraitLabel(trait, value)
+
+Get short label for trait value.
+
+```typescript
+const label = getTraitLabel('patience', 0.25);
+// Returns: "Low"
+```
+
+### getTraitReference(trait)
+
+Get full research reference for a trait.
+
+```typescript
+const ref = getTraitReference('selfEfficacy');
+// Returns: { researchBasis: string, citations: string[], levels: Level[] }
+```
+
+### formatForAskUserQuestion(questions)
+
+Format questions for Claude's AskUserQuestion tool.
+
+```typescript
+const formatted = formatForAskUserQuestion(questions);
+// Returns: { questions: AskUserQuestion[] }
+```

package/docs/README.md

@@ -0,0 +1,74 @@
+# CBrowser Documentation
+
+Welcome to the CBrowser documentation. This directory contains comprehensive guides for all CBrowser features.
+
+## Quick Links
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./GETTING-STARTED.md) | Installation, first commands, basic usage |
+| [Cognitive Simulation](./COGNITIVE-SIMULATION.md) | User simulation, personas, trait system |
+| [Persona Questionnaire](./PERSONA-QUESTIONNAIRE.md) | Research-backed custom persona creation |
+| [Visual Testing](./VISUAL-TESTING.md) | AI visual regression, cross-browser, responsive |
+| [MCP Integration](./MCP-INTEGRATION.md) | Claude Desktop and remote MCP server setup |
+| [Natural Language Tests](./NATURAL-LANGUAGE-TESTS.md) | Writing tests in plain English |
+| [Constitutional Safety](./CONSTITUTIONAL-SAFETY.md) | Risk classification and safety zones |
+| [CLI Reference](./CLI-REFERENCE.md) | Complete command-line reference |
+| [API Reference](./API-REFERENCE.md) | TypeScript API documentation |
+
+## Feature Guides
+
+### Core Features
+- [Self-Healing Selectors](./SELF-HEALING-SELECTORS.md) - ARIA-first selector strategy
+- [Agent-Ready Audit](./AGENT-READY-AUDIT.md) - AI-agent friendliness analysis
+- [Competitive Benchmark](./COMPETITIVE-BENCHMARK.md) - UX comparison across sites
+- [Empathy Audit](./EMPATHY-AUDIT.md) - Disability simulation testing
+
+### Testing Features
+- [Test Suites](./TEST-SUITES.md) - Natural language test execution
+- [Test Repair](./TEST-REPAIR.md) - AI-powered test fixing
+- [Flaky Detection](./FLAKY-DETECTION.md) - Identify unreliable tests
+- [Coverage Mapping](./COVERAGE-MAPPING.md) - Find untested pages
+
+### Visual Features
+- [Visual Baselines](./VISUAL-BASELINES.md) - Capture and compare screenshots
+- [Cross-Browser Testing](./CROSS-BROWSER-TESTING.md) - Chrome, Firefox, Safari comparison
+- [Responsive Testing](./RESPONSIVE-TESTING.md) - Mobile, tablet, desktop viewports
+- [A/B Comparison](./AB-COMPARISON.md) - Compare two URLs visually
+
+### Advanced Features
+- [Chaos Testing](./CHAOS-TESTING.md) - Inject failures, test resilience
+- [Bug Hunting](./BUG-HUNTING.md) - Autonomous issue discovery
+- [Performance Testing](./PERFORMANCE-TESTING.md) - Regression detection
+- [Session Management](./SESSION-MANAGEMENT.md) - Save and restore browser state
+
+## MCP Tools Reference
+
+CBrowser provides 48 MCP tools organized by category:
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Navigation** | 5 | Navigate, screenshot, extract, cloudflare detection |
+| **Interaction** | 4 | Click, smart click, fill, scroll |
+| **Testing** | 3 | Test suites, repair, flaky detection |
+| **Visual** | 6 | Baselines, regression, cross-browser, responsive, A/B |
+| **Cognitive** | 3 | Journey init, state update, persona comparison |
+| **Persona** | 3 | Questionnaire, build, trait lookup |
+| **Analysis** | 5 | Bug hunt, chaos, agent audit, benchmark, empathy |
+| **Stealth** | 5 | Enable, disable, status, check, diagnose |
+
+See [MCP Integration](./MCP-INTEGRATION.md) for complete tool documentation.
+
+## Version History
+
+See [CHANGELOG.md](../CHANGELOG.md) for detailed release notes.
+
+### Current Version: 16.7.0
+
+Key features:
+- 48 MCP tools for Claude integration
+- Research-backed persona questionnaire system
+- 25 cognitive traits with behavioral mappings
+- Accessibility empathy testing
+- Competitive UX benchmarking
+- Agent-ready site auditing

package/examples/persona-questionnaire.ts

@@ -0,0 +1,219 @@
+/**
+ * Persona Questionnaire Example
+ *
+ * This example demonstrates the research-backed persona questionnaire system
+ * introduced in v16.6.0. The questionnaire maps behavioral answers to cognitive
+ * trait values (0-1 scale) with proper correlation adjustments.
+ *
+ * The questionnaire works across:
+ * - Claude sessions (via AskUserQuestion tool)
+ * - CLI (interactive terminal prompts)
+ * - Remote and Local MCP servers
+ */
+
+import {
+  generatePersonaQuestionnaire,
+  buildTraitsFromAnswers,
+  getTraitBehaviors,
+  getTraitLabel,
+  getTraitReference,
+  formatForAskUserQuestion,
+  TRAIT_REFERENCE_MATRIX,
+} from 'cbrowser';
+
+// Example 1: Generate the questionnaire for Claude's AskUserQuestion tool
+function claudeQuestionnaireExample() {
+  console.log('\n=== Claude AskUserQuestion Format ===\n');
+
+  // Generate a quick 8-trait questionnaire
+  const questionnaire = generatePersonaQuestionnaire({ comprehensive: false });
+
+  console.log(`Generated ${questionnaire.questions.length} questions:`);
+
+  for (const q of questionnaire.questions) {
+    console.log(`\nTrait: ${q.trait}`);
+    console.log(`Question: ${q.question}`);
+    console.log('Options:');
+    for (const opt of q.options) {
+      console.log(`  [${opt.value}] ${opt.label}`);
+    }
+  }
+
+  // Format for AskUserQuestion tool
+  const askUserFormat = formatForAskUserQuestion(questionnaire.questions.slice(0, 4));
+  console.log('\n=== AskUserQuestion Format (first 4 questions) ===');
+  console.log(JSON.stringify(askUserFormat, null, 2));
+}
+
+// Example 2: Build traits from questionnaire answers
+function buildTraitsExample() {
+  console.log('\n=== Building Traits from Answers ===\n');
+
+  // Simulate answers from questionnaire
+  const answers: Record<string, number> = {
+    patience: 0.25,           // Gets frustrated quickly
+    riskTolerance: 0.75,      // Willing to try new things
+    comprehension: 0.5,       // Average
+    persistence: 0.75,        // Keeps trying
+    curiosity: 1.0,           // Very curious, explores everything
+    workingMemory: 0.5,       // Average
+    readingTendency: 0.25,    // Skims, doesn't read carefully
+    resilience: 0.5,          // Average bounce-back
+  };
+
+  // Build full trait profile with correlations applied
+  const traits = buildTraitsFromAnswers(answers);
+
+  console.log('Input answers:', answers);
+  console.log('\nDerived trait profile (with correlations):');
+
+  for (const [trait, value] of Object.entries(traits)) {
+    const label = getTraitLabel(trait, value);
+    console.log(`  ${trait}: ${value.toFixed(2)} (${label})`);
+  }
+}
+
+// Example 3: Lookup trait behaviors
+function traitBehaviorLookup() {
+  console.log('\n=== Trait Behavior Lookup ===\n');
+
+  const trait = 'patience';
+  const value = 0.25;
+
+  const behaviors = getTraitBehaviors(trait, value);
+  const reference = getTraitReference(trait);
+
+  console.log(`Trait: ${trait}`);
+  console.log(`Value: ${value}`);
+  console.log(`Label: ${behaviors.label}`);
+  console.log(`Description: ${behaviors.description}`);
+  console.log(`\nBehaviors:`);
+  for (const behavior of behaviors.behaviors) {
+    console.log(`  - ${behavior}`);
+  }
+  console.log(`\nResearch basis: ${reference?.researchBasis || 'None'}`);
+  console.log(`Citations: ${reference?.citations?.join(', ') || 'None'}`);
+}
+
+// Example 4: List all available traits
+function listAllTraits() {
+  console.log('\n=== All 25 Cognitive Traits ===\n');
+
+  const traits = Object.keys(TRAIT_REFERENCE_MATRIX);
+
+  console.log(`Total traits: ${traits.length}\n`);
+
+  for (const trait of traits) {
+    const ref = getTraitReference(trait);
+    console.log(`${trait}:`);
+    console.log(`  Research: ${ref?.researchBasis || 'General'}`);
+    console.log(`  Range: 0 (${getTraitLabel(trait, 0)}) to 1 (${getTraitLabel(trait, 1)})`);
+    console.log('');
+  }
+}
+
+// Example 5: Comprehensive questionnaire (all 25 traits)
+function comprehensiveQuestionnaireExample() {
+  console.log('\n=== Comprehensive Questionnaire ===\n');
+
+  const questionnaire = generatePersonaQuestionnaire({
+    comprehensive: true,
+    includeResearch: true,
+  });
+
+  console.log(`Comprehensive questionnaire: ${questionnaire.questions.length} questions`);
+  console.log(`Estimated time: ${questionnaire.estimatedMinutes} minutes\n`);
+
+  // Show first 3 questions with research citations
+  for (const q of questionnaire.questions.slice(0, 3)) {
+    console.log(`[${q.trait}] ${q.question}`);
+    if (q.researchBasis) {
+      console.log(`  Research: ${q.researchBasis}`);
+    }
+    console.log('');
+  }
+}
+
+// Example 6: Custom trait selection
+function customTraitSelection() {
+  console.log('\n=== Custom Trait Selection ===\n');
+
+  // Only get questions for specific traits
+  const questionnaire = generatePersonaQuestionnaire({
+    traits: ['patience', 'riskTolerance', 'selfEfficacy', 'trustCalibration'],
+  });
+
+  console.log(`Custom questionnaire: ${questionnaire.questions.length} questions\n`);
+
+  for (const q of questionnaire.questions) {
+    console.log(`${q.trait}: ${q.question}`);
+  }
+}
+
+// Example 7: Trait correlation demonstration
+function correlationExample() {
+  console.log('\n=== Trait Correlations ===\n');
+
+  // Low self-efficacy should correlate with higher internal attribution
+  const lowEfficacyAnswers: Record<string, number> = {
+    selfEfficacy: 0.25, // "I probably can't figure this out"
+  };
+
+  const derived = buildTraitsFromAnswers(lowEfficacyAnswers);
+
+  console.log('Input: selfEfficacy = 0.25 (Low)');
+  console.log('\nCorrelated traits automatically adjusted:');
+  console.log(`  internalAttribution: ${derived.internalAttribution?.toFixed(2)} (blames self for failures)`);
+  console.log(`  resilience: ${derived.resilience?.toFixed(2)} (lower bounce-back ability)`);
+  console.log('\nResearch: Bandura (1977) - Self-efficacy affects attribution patterns');
+}
+
+// Example 8: Integration with cognitive journey
+async function journeyIntegrationExample() {
+  console.log('\n=== Integration with Cognitive Journey ===\n');
+
+  // Build traits from questionnaire answers
+  const answers: Record<string, number> = {
+    patience: 0.25,
+    riskTolerance: 0.5,
+    comprehension: 0.75,
+    selfEfficacy: 0.5,
+    curiosity: 0.75,
+  };
+
+  const traits = buildTraitsFromAnswers(answers);
+
+  console.log('Generated trait profile for cognitive journey:');
+  console.log(JSON.stringify(traits, null, 2));
+
+  console.log('\nUse with runCognitiveJourney:');
+  console.log(`
+const result = await runCognitiveJourney({
+  persona: 'custom',
+  startUrl: 'https://example.com',
+  goal: 'complete signup',
+  customTraits: ${JSON.stringify(traits, null, 2)},
+});
+`);
+}
+
+// Run examples
+async function main() {
+  console.log('╔════════════════════════════════════════════════════════════════╗');
+  console.log('║  CBrowser Persona Questionnaire Examples (v16.6.0)             ║');
+  console.log('║  Research-backed trait mapping for cognitive user simulation  ║');
+  console.log('╚════════════════════════════════════════════════════════════════╝');
+
+  claudeQuestionnaireExample();
+  buildTraitsExample();
+  traitBehaviorLookup();
+  // listAllTraits();              // Uncomment for full trait list
+  comprehensiveQuestionnaireExample();
+  customTraitSelection();
+  correlationExample();
+  await journeyIntegrationExample();
+
+  console.log('\n=== Example Complete ===');
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cbrowser",
-  "version": "16.7.0",
+  "version": "16.7.1",
   "type": "module",
   "description": "Cognitive browser automation that thinks like your users. Simulate real user cognition with abandonment detection, constitutional safety, chaos engineering, and UX friction discovery.",
   "main": "dist/index.js",