cbrowser 17.6.1 → 18.1.0

package/docs/Tools-Browser-Automation.md

@@ -0,0 +1,305 @@
+# Browser Automation Tools
+
+**Tell the browser what you want. Let AI figure out how.**
+
+These 12 tools handle navigation, clicking, form filling, data extraction, and page analysis. They replace brittle CSS selectors with natural language descriptions that survive DOM changes.
+
+---
+
+## When to Use These Tools
+
+- **You're automating a workflow** and tired of tests breaking when developers change class names
+- **You need to extract data** from pages without writing custom scrapers for each site
+- **You're building an AI agent** that needs to interact with arbitrary websites
+- **Your selectors keep failing** and you want something that self-heals
+
+---
+
+## Tools
+
+### `navigate`
+
+**What it does**: Opens a URL and takes a screenshot of the loaded page.
+
+**Why you'd use it**: Start any browser automation session or move between pages.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | The URL to navigate to |
+
+**Example**:
+```json
+{
+  "url": "https://example.com/products"
+}
+```
+
+---
+
+### `click`
+
+**What it does**: Clicks an element using text content, CSS selector, or natural language description.
+
+**Why you'd use it**: Interact with buttons, links, or any clickable element without fragile selectors.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | Yes | What to click — text, CSS selector, or description like "the blue submit button" |
+| `force` | boolean | No | Bypass constitutional safety checks for destructive actions |
+| `verbose` | boolean | No | Return available elements and AI suggestions on failure |
+
+**Example**:
+```json
+{
+  "selector": "Add to Cart"
+}
+```
+
+Or with natural language:
+```json
+{
+  "selector": "the primary call-to-action button in the hero section"
+}
+```
+
+---
+
+### `smart_click`
+
+**What it does**: Clicks with automatic retry and self-healing selectors. If the original selector fails, it finds the element by intent.
+
+**Why you'd use it**: When elements might not be immediately available or when you want resilience against DOM changes.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | Yes | Element to click |
+| `maxRetries` | number | No | Maximum retry attempts. Default: 3 |
+| `dismissOverlays` | boolean | No | Automatically dismiss popups before clicking. Default: false |
+
+**Example**:
+```json
+{
+  "selector": "Submit Order",
+  "dismissOverlays": true
+}
+```
+
+**Note**: v11.8.0 added confidence gating — only reports success if the healed selector has ≥60% confidence.
+
+---
+
+### `fill`
+
+**What it does**: Types text into a form field identified by name, label, or description.
+
+**Why you'd use it**: Fill out forms without knowing the exact input names or IDs.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `selector` | string | Yes | The field to fill — label text, name attribute, or description |
+| `value` | string | Yes | Text to type into the field |
+| `clear` | boolean | No | Clear existing content before typing. Default: true |
+
+**Example**:
+```json
+{
+  "selector": "Email address",
+  "value": "user@example.com"
+}
+```
+
+---
+
+### `scroll`
+
+**What it does**: Scrolls the page in a specified direction or to a specific position.
+
+**Why you'd use it**: Reveal content below the fold, trigger lazy loading, or reach elements not yet visible.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `direction` | string | Yes | `up`, `down`, `top`, `bottom`, or pixel amount like `500px` |
+
+**Example**:
+```json
+{
+  "direction": "down"
+}
+```
+
+---
+
+### `screenshot`
+
+**What it does**: Captures the current page as an image.
+
+**Why you'd use it**: Document state, debug failures, or feed visual information to AI.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `fullPage` | boolean | No | Capture entire scrollable page. Default: false (viewport only) |
+| `path` | string | No | Save to file path instead of returning base64 |
+
+**Example**:
+```json
+{
+  "fullPage": true
+}
+```
+
+---
+
+### `extract`
+
+**What it does**: Pulls structured data from the page — links, headings, forms, images, or arbitrary text.
+
+**Why you'd use it**: Scrape content, analyze page structure, or gather data for further processing.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | Yes | What to extract: `links`, `headings`, `forms`, `images`, `text`, or `all` |
+| `selector` | string | No | Limit extraction to elements matching this selector |
+
+**Example**:
+```json
+{
+  "type": "links"
+}
+```
+
+Returns structured JSON with all links, their text, and href values.
+
+---
+
+### `find_element_by_intent`
+
+**What it does**: Uses AI to find elements by semantic description. Returns the best match with confidence score and accessibility information.
+
+**Why you'd use it**: When you need to find something but don't know exactly how it's implemented — "the navigation menu" or "the search box in the header".
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `intent` | string | Yes | Natural language description of the element |
+| `context` | string | No | Additional context to narrow the search |
+
+**Example**:
+```json
+{
+  "intent": "the main call-to-action button",
+  "context": "in the pricing section"
+}
+```
+
+**Returns**: Selector, confidence score (0-1), accessibility score, and alternative matches.
+
+**Note**: v7.4.17 added ARIA-first strategy — prioritizes `aria-label`, `role`, semantic HTML before falling back to classes/IDs.
+
+---
+
+### `analyze_page`
+
+**What it does**: Examines page structure and returns inventory of interactive elements — forms, buttons, links, inputs.
+
+**Why you'd use it**: Understand what's on a page before deciding what to interact with. Essential for building adaptive agents.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `detailed` | boolean | No | Include element attributes and positions. Default: false |
+
+**Example**:
+```json
+{
+  "detailed": true
+}
+```
+
+---
+
+### `assert`
+
+**What it does**: Verifies a condition using natural language and returns pass/fail with explanation.
+
+**Why you'd use it**: Validate that actions had the expected result without writing complex assertion logic.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `condition` | string | Yes | What to check, in plain English |
+
+**Example**:
+```json
+{
+  "condition": "the shopping cart shows 2 items"
+}
+```
+
+**Returns**: `{ "passed": true/false, "reason": "explanation" }`
+
+---
+
+### `dismiss_overlay`
+
+**What it does**: Detects and closes modal overlays — cookie consent banners, newsletter popups, age verification gates.
+
+**Why you'd use it**: Clear blocking UI before interacting with the actual page content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `type` | string | No | Overlay type: `auto`, `cookie`, `age-verify`, `newsletter`, `custom`. Default: `auto` |
+| `customSelector` | string | No | Selector for custom overlay close button |
+
+**Example**:
+```json
+{
+  "type": "auto"
+}
+```
+
+**Note**: Constitutional Yellow zone — logged but proceeds automatically.
+
+---
+
+### `ask_user`
+
+**What it does**: Creates a structured prompt to ask the human operator a question with predefined options.
+
+**Why you'd use it**: When the automation needs human input to proceed — confirmation, selection, or decision that can't be automated.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `question` | string | Yes | The question to ask |
+| `options` | array | No | Predefined answer options |
+| `allowFreeform` | boolean | No | Allow typed response. Default: true |
+
+**Example**:
+```json
+{
+  "question": "Which shipping method should I select?",
+  "options": ["Standard (5-7 days)", "Express (2-3 days)", "Overnight"]
+}
+```
+
+---
+
+## How Self-Healing Works
+
+When a selector fails, CBrowser:
+
+1. **Checks the healing cache** for previously learned mappings
+2. **Analyzes the page** for elements matching the semantic intent
+3. **Scores candidates** by text similarity, position, and accessibility attributes
+4. **Returns the best match** if confidence exceeds 60%
+5. **Caches the mapping** for faster future lookups
+
+This means your automation adapts to site changes automatically. A redesign that moves the "Add to Cart" button? CBrowser finds it by intent, not by its old CSS class.
+
+---
+
+## Related Documentation
+
+- [Constitutional Safety](/docs/Constitutional-Safety/) — How CBrowser classifies action risk
+- [Tools Overview](/docs/Tools-Overview/) — All tools by category
+- [Examples](/docs/Examples/) — Real-world automation patterns
+
+---
+
+*Last updated: v17.6.0*

package/docs/Tools-Cognitive-Journeys.md

@@ -0,0 +1,227 @@
+# Cognitive Journey Tools
+
+**Find out where users give up before they actually do.**
+
+Cognitive journeys simulate real humans navigating your site — complete with patience that depletes, frustration that builds, and the moment they decide "this isn't worth it" and leave. These 6 tools let you experience your product through the minds of different user types.
+
+---
+
+## When to Use These Tools
+
+- **Your conversion rate is mysteriously low** and analytics can't tell you why people abandon
+- **You're launching a new feature** and want to know if real users can figure it out
+- **You need to compare experiences** across different audience segments
+- **You want to find friction** before your users feel it
+
+---
+
+## Tools
+
+### `cognitive_journey_init`
+
+**What it does**: Starts a cognitive journey session with a specific persona, goal, and starting point. Returns the persona's cognitive profile and initial state.
+
+**Why you'd use it**: Begin simulating how a specific user type would approach your site.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `persona` | string | Yes | Persona ID (e.g., `first-timer`, `elderly-user`, `cognitive-adhd`) |
+| `startUrl` | string | Yes | URL where the journey begins |
+| `goal` | string | Yes | What the persona is trying to accomplish |
+| `maxSteps` | number | No | Maximum actions before forcing stop. Default: 50 |
+
+**Example**:
+```json
+{
+  "persona": "first-timer",
+  "startUrl": "https://example.com",
+  "goal": "Create an account and make a purchase"
+}
+```
+
+**Returns**: Session ID, persona profile (25 traits), initial cognitive state (patience, confusion, frustration at starting values).
+
+---
+
+### `cognitive_journey_update_state`
+
+**What it does**: Updates the persona's cognitive state after each action. Tracks mood changes, calculates whether they would abandon, and generates inner monologue.
+
+**Why you'd use it**: After each navigation step, report what happened and get the persona's reaction.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sessionId` | string | Yes | Session ID from `cognitive_journey_init` |
+| `action` | string | Yes | What action was just taken |
+| `result` | string | Yes | What happened — success, failure, unexpected |
+| `patienceChange` | number | No | How much patience changed (-1 to 1) |
+| `confusionChange` | number | No | How much confusion changed (-1 to 1) |
+| `frustrationChange` | number | No | How much frustration changed (-1 to 1) |
+| `currentUrl` | string | No | Current page URL |
+
+**Example**:
+```json
+{
+  "sessionId": "journey_abc123",
+  "action": "Clicked 'Sign Up' button",
+  "result": "Page showed loading spinner for 8 seconds before form appeared",
+  "patienceChange": -0.15,
+  "confusionChange": 0.05,
+  "frustrationChange": 0.10,
+  "currentUrl": "https://example.com/signup"
+}
+```
+
+**Returns**:
+- `shouldAbandon`: boolean — would this persona leave?
+- `abandonmentReason`: why they'd leave (if applicable)
+- `innerMonologue`: what they're thinking ("This is taking forever...")
+- `currentState`: updated patience/confusion/frustration values
+
+---
+
+### `cognitive_journey_autonomous` 🔒 Enterprise
+
+**What it does**: Runs a complete journey autonomously with AI making all navigation decisions. No orchestration needed — just set the goal and watch.
+
+**Why you'd use it**: Hands-off user simulation that generates complete friction reports and abandonment analysis.
+
+> **Enterprise Feature** — Requires CBrowser Enterprise.
+> Autonomous execution consumes Anthropic API credits for decision-making.
+> [Learn about Enterprise →](/docs/Marketing-Suite/)
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `persona` | string | Yes | Persona ID |
+| `startUrl` | string | Yes | Starting URL |
+| `goal` | string | Yes | What to accomplish |
+| `maxSteps` | number | No | Max actions. Default: 50 |
+| `maxTime` | number | No | Max seconds. Default: 300 |
+| `vision` | boolean | No | Use screenshot analysis for decisions. Default: false |
+| `headless` | boolean | No | Run without visible browser. Default: false |
+
+**Example**:
+```json
+{
+  "persona": "elderly-user",
+  "startUrl": "https://bank.example.com",
+  "goal": "Transfer $100 to savings account",
+  "vision": true,
+  "maxSteps": 30
+}
+```
+
+**Returns**: Complete journey trace with every decision, friction points, screenshots, and final outcome.
+
+---
+
+### `compare_personas`
+
+**What it does**: Run the same journey with multiple personas and compare their experiences side-by-side.
+
+**Why you'd use it**: Understand how different user segments experience the same flow differently.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `personas` | array | Yes | List of persona IDs to compare |
+| `startUrl` | string | Yes | Starting URL |
+| `goal` | string | Yes | What to accomplish |
+| `parallel` | boolean | No | Run journeys simultaneously. Default: false |
+
+**Example**:
+```json
+{
+  "personas": ["power-user", "first-timer", "elderly-user"],
+  "startUrl": "https://example.com/checkout",
+  "goal": "Complete purchase"
+}
+```
+
+**Returns**: Comparison matrix showing success/failure, time taken, abandonment points, and friction experienced by each persona.
+
+---
+
+### `compare_personas_init`
+
+**What it does**: Initialize a multi-persona comparison using the bridge workflow (no API key needed). Returns profiles for all personas ready for manual orchestration.
+
+**Why you'd use it**: Run persona comparisons when you want Claude to orchestrate each step rather than autonomous execution.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `personas` | array | Yes | List of persona IDs |
+| `startUrl` | string | Yes | Starting URL |
+| `goal` | string | Yes | Goal to accomplish |
+
+**Example**:
+```json
+{
+  "personas": ["mobile-user", "impatient-user"],
+  "startUrl": "https://example.com",
+  "goal": "Find pricing information"
+}
+```
+
+---
+
+### `compare_personas_complete`
+
+**What it does**: Finalize a persona comparison by aggregating all journey results and generating the comparison report.
+
+**Why you'd use it**: After running individual journeys for each persona, compile the results.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `comparisonId` | string | Yes | Comparison ID from `compare_personas_init` |
+| `results` | array | Yes | Array of journey results for each persona |
+
+---
+
+## Understanding Cognitive State
+
+Every persona has three dynamic metrics that change throughout their journey:
+
+| Metric | Range | What It Means |
+|--------|-------|---------------|
+| **Patience** | 0.0 - 1.0 | Willingness to keep trying. Depletes with delays, errors, confusion. |
+| **Confusion** | 0.0 - 1.0 | How lost they feel. Increases with unclear UI, unexpected behavior. |
+| **Frustration** | 0.0 - 1.0 | Emotional response to friction. Increases with repeated failures, dead ends. |
+
+### Abandonment Triggers
+
+A persona abandons when any of these occur:
+- **Patience < 0.1** — "This is taking too long, I'm done"
+- **Confusion > 0.8 for 30+ seconds** — "I have no idea what to do"
+- **Frustration > 0.85** — "This is ridiculous"
+- **No progress after 10+ steps** — "I'm not getting anywhere"
+- **Same page visited 3+ times** — "I keep ending up here"
+
+Different personas have different starting values and depletion rates. An impatient-user starts with 0.4 patience and loses it twice as fast as a power-user.
+
+---
+
+## Persona Quick Reference
+
+| Persona | Patience | Confusion Tolerance | Key Trait |
+|---------|----------|---------------------|-----------|
+| `power-user` | High | Low (expects clarity) | Fast decisions, low reading |
+| `first-timer` | Medium | Medium | Explores, reads more |
+| `elderly-user` | High | High | Slow, thorough, easily confused by jargon |
+| `impatient-user` | Very Low | Low | Abandons fast on any friction |
+| `mobile-user` | Low | Medium | Fat-finger issues, small viewport |
+| `cognitive-adhd` | Low | High | Skims, clicks fast, distracted easily |
+
+See [Persona Index](/docs/Persona-Index/) for complete profiles.
+
+---
+
+## Related Documentation
+
+- [Cognitive User Simulation](/docs/Cognitive-User-Simulation/) — Deep dive on how cognitive simulation works
+- [Persona Index](/docs/Persona-Index/) — All 9 built-in personas
+- [Multi-Persona Comparison](/docs/Multi-Persona-Comparison/) — Comparison workflows
+- [Trait Index](/docs/Trait-Index/) — The 25 cognitive traits
+
+---
+
+*Last updated: v17.6.0*