cbrowser 18.63.0 → 18.63.1

package/docs/Tools-Browser-Automation.md

@@ -1,311 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Browser Automation Tools](https://cbrowser.ai/docs/Tools-Browser-Automation)**
-
----
-
-# 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

@@ -1,233 +0,0 @@
-> **This documentation is no longer maintained here.**
->
-> For the latest version, please visit: **[Cognitive Journey Tools](https://cbrowser.ai/docs/Tools-Cognitive-Journeys)**
-
----
-
-# 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*