cbrowser 17.6.1 → 18.1.0

package/docs/Tool-Hunt-Bugs.md

@@ -0,0 +1,299 @@
+# Hunt Bugs
+
+**Turn AI loose on your site. See what's broken.**
+
+`hunt_bugs` is autonomous exploratory testing. You give it a URL, it crawls your site looking for bugs — broken links, JavaScript errors, accessibility issues, visual glitches, and security problems. No test cases required.
+
+---
+
+## Quick Start
+
+```json
+{
+  "url": "https://example.com",
+  "scope": "all",
+  "depth": 4,
+  "maxPages": 50
+}
+```
+
+**What happens**:
+1. AI starts at your URL and begins exploring
+2. On each page, it checks for functional, visual, accessibility, and security issues
+3. It follows links, fills forms, clicks buttons — looking for things that break
+4. You get a report of everything found, with reproduction steps and screenshots
+
+---
+
+## Parameters
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `url` | string | Yes | — | Starting URL |
+| `scope` | string | No | `all` | Bug types: `all`, `functional`, `visual`, `accessibility`, `security` |
+| `depth` | number | No | 3 | How deep to crawl |
+| `maxPages` | number | No | 20 | Maximum pages to visit |
+| `focus` | string | No | — | Focus area (e.g., "forms", "checkout", "navigation") |
+| `exclude` | array | No | — | URL patterns to skip |
+
+---
+
+## What It Finds
+
+### Functional Bugs
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Broken links | Links that return 4xx/5xx errors |
+| Dead ends | Pages with no way to navigate away |
+| Form errors | Submissions that fail silently |
+| JavaScript exceptions | Console errors during interaction |
+| Failed network requests | XHR/fetch that error |
+| Infinite loops | Redirect chains, infinite scrolls |
+| Missing content | Empty states, placeholder text |
+
+### Visual Bugs
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Overlapping elements | Content that covers other content |
+| Horizontal overflow | Content breaking viewport |
+| Missing images | Broken `src` attributes |
+| Layout breaks | Elements far from expected position |
+| Z-index issues | Content hidden behind other layers |
+| Responsive failures | Elements that break at viewport edges |
+
+### Accessibility Bugs
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Missing alt text | Images without descriptions |
+| Low contrast | Text that fails WCAG contrast |
+| Keyboard traps | Can't escape a component with keyboard |
+| Missing labels | Form fields without associated labels |
+| Focus issues | Interactive elements without focus styles |
+| ARIA violations | Invalid ARIA attributes |
+
+### Security Issues
+
+| Bug Type | How It's Detected |
+|----------|-------------------|
+| Exposed credentials | Visible API keys, passwords |
+| Insecure forms | HTTP forms on HTTPS pages |
+| Data in URLs | Sensitive info in query strings |
+| Missing HTTPS | Insecure resource loading |
+| Open redirects | Redirects to external domains |
+| Debug endpoints | Exposed dev/debug routes |
+
+---
+
+## Output
+
+```json
+{
+  "url": "https://example.com",
+  "pagesVisited": 34,
+  "timeElapsed": 187,
+  "bugs": [
+    {
+      "severity": "critical",
+      "type": "functional",
+      "category": "form-error",
+      "url": "https://example.com/checkout",
+      "description": "Payment form silently fails when CVV is left empty",
+      "reproduction": [
+        "Navigate to /checkout",
+        "Fill all fields except CVV",
+        "Click 'Pay Now'",
+        "Form shows loading spinner but never completes"
+      ],
+      "screenshot": "base64...",
+      "consoleErrors": [
+        "Uncaught TypeError: Cannot read property 'value' of null at payment.js:142"
+      ]
+    },
+    {
+      "severity": "serious",
+      "type": "accessibility",
+      "category": "missing-label",
+      "url": "https://example.com/contact",
+      "description": "Phone number field has no associated label",
+      "wcag": "1.3.1",
+      "element": "<input type='tel' name='phone' placeholder='Phone'>",
+      "remediation": "Add <label for='phone'>Phone Number</label>"
+    },
+    {
+      "severity": "moderate",
+      "type": "visual",
+      "category": "overflow",
+      "url": "https://example.com/pricing",
+      "description": "Pricing table overflows viewport on mobile",
+      "viewport": "375x667",
+      "screenshot": "base64..."
+    },
+    {
+      "severity": "serious",
+      "type": "security",
+      "category": "exposed-credentials",
+      "url": "https://example.com/config",
+      "description": "API key visible in page source",
+      "evidence": "const API_KEY = 'sk-...'",
+      "recommendation": "Move API key to environment variable"
+    }
+  ],
+  "summary": {
+    "critical": 1,
+    "serious": 4,
+    "moderate": 7,
+    "minor": 12,
+    "byType": {
+      "functional": 6,
+      "visual": 8,
+      "accessibility": 5,
+      "security": 5
+    }
+  }
+}
+```
+
+---
+
+## Use Cases
+
+### 1. Pre-Release Smoke Test
+
+Before deploying, run a quick bug hunt:
+
+```json
+{
+  "url": "https://staging.example.com",
+  "scope": "functional",
+  "depth": 3,
+  "maxPages": 30
+}
+```
+
+Catches obvious breaks before they reach production.
+
+---
+
+### 2. Security Reconnaissance
+
+Find exposed secrets and vulnerabilities:
+
+```json
+{
+  "url": "https://example.com",
+  "scope": "security",
+  "depth": 5,
+  "maxPages": 100
+}
+```
+
+---
+
+### 3. Accessibility Sweep
+
+Find accessibility issues across the entire site:
+
+```json
+{
+  "url": "https://example.com",
+  "scope": "accessibility",
+  "depth": 5
+}
+```
+
+For deeper analysis of specific issues, follow up with [empathy_audit](/docs/Tool-Empathy-Audit/).
+
+---
+
+### 4. Focused Testing
+
+Hunt bugs only in a specific area:
+
+```json
+{
+  "url": "https://example.com/checkout",
+  "focus": "checkout",
+  "exclude": ["/blog/*", "/docs/*"]
+}
+```
+
+---
+
+## How It Explores
+
+1. **Starts at your URL** and analyzes the page
+2. **Identifies interactive elements** — links, buttons, forms
+3. **Executes interactions** — clicks, fills, submits
+4. **Records everything** — console logs, network, screenshots
+5. **Follows promising paths** — prioritizes unexplored areas
+6. **Avoids traps** — detects infinite loops, skips logout/delete
+7. **Moves to next page** and repeats
+
+The AI uses constitutional safety rules to avoid destructive actions — it won't click "Delete Account" or "Cancel Subscription".
+
+---
+
+## CI/CD Integration
+
+```bash
+# Run in CI, fail if critical bugs found
+npx cbrowser hunt-bugs https://staging.example.com \
+  --scope all \
+  --depth 3 \
+  --fail-on critical \
+  --output bugs.json
+
+# Generate HTML report
+npx cbrowser hunt-bugs https://example.com \
+  --output report.html
+```
+
+---
+
+## Tips
+
+### Start Shallow, Go Deep
+
+```json
+// First run: quick sweep
+{ "depth": 2, "maxPages": 20 }
+
+// Second run: deep dive on problem areas
+{ "url": "https://example.com/checkout", "depth": 5 }
+```
+
+### Exclude Known Issues
+
+```json
+{
+  "exclude": [
+    "/legacy/*",  // Old pages being deprecated
+    "/admin/*"    // Requires auth
+  ]
+}
+```
+
+### Focus on What Matters
+
+```json
+// Only care about checkout working?
+{ "focus": "checkout", "scope": "functional" }
+
+// Preparing for accessibility audit?
+{ "scope": "accessibility", "depth": 10 }
+```
+
+---
+
+## Related Tools
+
+- [`nl_test_file`](/docs/Tools-Testing-Quality/) — Run specific test scenarios
+- [`empathy_audit`](/docs/Tool-Empathy-Audit/) — Deep accessibility testing
+- [`competitive_benchmark`](/docs/Tool-Competitive-Benchmark/) — Compare against competitors
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tool-Marketing-Campaign.md

@@ -0,0 +1,292 @@
+# Marketing Campaigns
+
+**Test which messages work for which audiences — with scientific rigor.**
+
+Marketing campaigns in CBrowser let you run structured A/B tests using cognitive personas. Instead of testing at the population level (where results average out), test at the *segment* level — find out that scarcity messaging works for impulse-shoppers but backfires with enterprise-buyers.
+
+---
+
+## Campaign Lifecycle
+
+### 1. Create Campaign
+
+Define variants and personas to test.
+
+```json
+{
+  "tool": "marketing_campaign_create",
+  "params": {
+    "name": "Pricing Page Optimization Q1 2026",
+    "variants": [
+      { "name": "Control", "url": "https://example.com/pricing" },
+      { "name": "Social Proof", "url": "https://example.com/pricing-v2" },
+      { "name": "Scarcity", "url": "https://example.com/pricing-v3" }
+    ],
+    "personas": [
+      "enterprise-buyer",
+      "startup-founder",
+      "impulse-shopper",
+      "price-researcher"
+    ],
+    "goal": "Click 'Start Free Trial'",
+    "metrics": ["time_to_goal", "friction_count", "abandonment_rate"]
+  }
+}
+```
+
+**Returns**: Campaign ID and test matrix (3 variants × 4 personas = 12 test cells)
+
+---
+
+### 2. Run Journeys
+
+Run cognitive journeys for each cell in the matrix.
+
+**With Enterprise** (automatic):
+```json
+{
+  "tool": "marketing_campaign_run",
+  "params": {
+    "campaignId": "camp_abc123"
+  }
+}
+```
+
+**With Demo** (manual orchestration):
+```json
+// For each variant × persona combination:
+{
+  "tool": "cognitive_journey_init",
+  "params": {
+    "persona": "enterprise-buyer",
+    "startUrl": "https://example.com/pricing",
+    "goal": "Click 'Start Free Trial'"
+  }
+}
+// ... orchestrate journey ...
+
+// Report result back
+{
+  "tool": "marketing_campaign_report_result",
+  "params": {
+    "campaignId": "camp_abc123",
+    "variantIndex": 0,
+    "persona": "enterprise-buyer",
+    "success": false,
+    "abandonmentReason": "No security certification visible",
+    "friction": ["Couldn't find SOC 2 badge", "Pricing unclear for enterprise"],
+    "timeToGoal": null
+  }
+}
+```
+
+---
+
+### 3. Analyze Results 🔒 Enterprise
+
+Generate insights from campaign data.
+
+```json
+// Influence effectiveness matrix
+{
+  "tool": "marketing_influence_matrix",
+  "params": { "campaignId": "camp_abc123" }
+}
+
+// Psychological lever analysis
+{
+  "tool": "marketing_lever_analysis",
+  "params": { "campaignId": "camp_abc123" }
+}
+
+// Funnel comparison
+{
+  "tool": "marketing_funnel_analyze",
+  "params": { "campaignId": "camp_abc123" }
+}
+```
+
+---
+
+## Campaign Results
+
+### Success Matrix
+
+| | Enterprise Buyer | Startup Founder | Impulse Shopper | Price Researcher |
+|---|:---:|:---:|:---:|:---:|
+| **Control** | ❌ | ✅ | ❌ | ❌ |
+| **Social Proof** | ✅ | ✅ | ✅ | ❌ |
+| **Scarcity** | ❌ | ✅ | ✅ | ❌ |
+
+### Influence Matrix 🔒 Enterprise
+
+Shows which influence patterns work for which personas:
+
+```json
+{
+  "matrix": {
+    "enterprise-buyer": {
+      "social_proof": { "effectiveness": 0.85, "evidence": "Converted after seeing Fortune 500 logos" },
+      "scarcity": { "effectiveness": 0.10, "evidence": "Dismissed 'Limited time' as marketing" },
+      "authority": { "effectiveness": 0.90, "evidence": "Sought SOC 2 badge before proceeding" }
+    },
+    "impulse-shopper": {
+      "social_proof": { "effectiveness": 0.75, "evidence": "Clicked after seeing 'Trusted by 10,000+'" },
+      "scarcity": { "effectiveness": 0.95, "evidence": "Converted immediately on countdown" },
+      "authority": { "effectiveness": 0.30, "evidence": "Didn't notice security badges" }
+    }
+  }
+}
+```
+
+### Lever Analysis 🔒 Enterprise
+
+Deep dive into *why* variants worked:
+
+```json
+{
+  "variant": "Social Proof",
+  "successRate": 0.75,
+  "leverBreakdown": {
+    "customer_logos": {
+      "impact": "high",
+      "evidence": "3 of 4 personas clicked CTAs near logos"
+    },
+    "testimonial_quotes": {
+      "impact": "medium",
+      "evidence": "Enterprise buyer read full testimonial before converting"
+    },
+    "user_count": {
+      "impact": "low",
+      "evidence": "Price researcher dismissed as vanity metric"
+    }
+  }
+}
+```
+
+### Funnel Analysis 🔒 Enterprise
+
+Where in the journey did each persona drop off?
+
+```json
+{
+  "variant": "Scarcity",
+  "persona": "enterprise-buyer",
+  "funnel": [
+    { "step": "Land on page", "reached": true, "time": 0 },
+    { "step": "Scroll to pricing", "reached": true, "time": 12 },
+    { "step": "See countdown timer", "reached": true, "time": 15 },
+    { "step": "Click 'Start Trial'", "reached": false, "time": null }
+  ],
+  "dropOffAnalysis": {
+    "step": "See countdown timer",
+    "innerMonologue": "This seems like a pressure tactic. I need to verify this with my team first.",
+    "frictionType": "trust_violation",
+    "recommendation": "Remove artificial urgency for enterprise audience"
+  }
+}
+```
+
+---
+
+## Designing Effective Campaigns
+
+### Choose Contrasting Variants
+
+Test different *strategies*, not minor copy changes:
+
+**Good**:
+- Control (baseline)
+- Social proof emphasis (testimonials, logos)
+- Scarcity emphasis (limited offer, countdown)
+- Authority emphasis (certifications, awards)
+
+**Bad**:
+- "Start Free Trial" button
+- "Begin Free Trial" button
+- "Get Started Free" button
+
+### Select Representative Personas
+
+Include personas that matter for your business:
+
+| Business Type | Key Personas |
+|---------------|--------------|
+| B2B SaaS | enterprise-buyer, startup-founder, technical-evaluator |
+| E-commerce | impulse-shopper, price-researcher, loyal-customer |
+| Consumer app | first-timer, power-user, mobile-user |
+| Accessibility | motor-tremor, low-vision, cognitive-adhd |
+
+### Define Clear Goals
+
+Specific, measurable goals:
+
+**Good**: "Click 'Start Free Trial' button"
+**Bad**: "Understand the product"
+
+---
+
+## Demo vs Enterprise
+
+| Capability | Demo | Enterprise |
+|------------|:----:|:----------:|
+| Create campaigns | ✅ | ✅ |
+| Report journey results | ✅ | ✅ |
+| List marketing personas | ✅ | ✅ |
+| Run campaigns automatically | ❌ | ✅ |
+| Influence matrix | ❌ | ✅ |
+| Lever analysis | ❌ | ✅ |
+| Funnel analysis | ❌ | ✅ |
+| Competitive comparison | ❌ | ✅ |
+| Audience discovery | ❌ | ✅ |
+
+**Demo** gives you the testing framework — create campaigns, run journeys manually with Claude orchestrating, report results.
+
+**Enterprise** gives you automation and insights — run all journeys automatically, get influence matrices and lever analysis.
+
+---
+
+## Example: Full Campaign
+
+### Setup
+
+```json
+{
+  "name": "Homepage CTA Test",
+  "variants": [
+    { "name": "Control", "url": "https://example.com" },
+    { "name": "Social Proof", "url": "https://example.com?v=social" },
+    { "name": "Feature Focus", "url": "https://example.com?v=features" }
+  ],
+  "personas": ["first-timer", "enterprise-buyer", "technical-evaluator"],
+  "goal": "Click primary CTA"
+}
+```
+
+### Results
+
+| | First-Timer | Enterprise Buyer | Technical Evaluator |
+|---|:---:|:---:|:---:|
+| Control | ✅ (23s) | ❌ | ❌ |
+| Social Proof | ✅ (18s) | ✅ (45s) | ❌ |
+| Feature Focus | ❌ | ❌ | ✅ (67s) |
+
+### Insights
+
+- **First-timers** convert fastest on Social Proof (18s vs 23s control)
+- **Enterprise buyers** need social proof (logos, testimonials) — don't convert without it
+- **Technical evaluators** need feature details — social proof feels like marketing fluff
+- **Recommendation**: Show different hero sections by referral source
+
+---
+
+## Related Documentation
+
+- [Marketing Suite](/docs/Marketing-Suite/) — Full marketing capabilities
+- [Marketing Intelligence Tools](/docs/Tools-Marketing-Intelligence/) — All marketing tools
+- [Cognitive Journeys](/docs/Tools-Cognitive-Journeys/) — Journey simulation
+- [Values Framework](/docs/Values-Framework/) — What motivates each persona
+
+---
+
+*Last updated: v17.6.0*