# Weavetab — Complete Documentation & Technical Knowledge Base (v2.6.0)

> This file is a complete, aggregated knowledge base containing all documentation, plugin authoring specs, research papers, API references, architecture guides, and CLI manuals for Weavetab MCP.

---

# Weavetab Plugin Authoring Specification (@weavetab/sdk v2.6.0)

> Standalone specification for AI coding agents (Cursor, Claude Code, Antigravity, Windsurf, ChatGPT) to create, test, and publish Weavetab MCP plugins without needing to read the SDK repository or source code.

## 1. Quickstart CLI
Scaffold a ready-to-publish TypeScript plugin in seconds:
```bash
npx @weavetab/sdk init my-weavetab-plugin
cd my-weavetab-plugin
npm install
npm run build
npm test
```

## 2. Minimal 20-Line Plugin (`src/index.ts`)
Every Weavetab plugin exports a default plugin definition created with `definePlugin` from `@weavetab/sdk`:

```typescript
import { definePlugin, createTool, z } from "@weavetab/sdk";

const extractHeadings = createTool({
  name: "extract_headings",
  description: "Extracts all H1-H3 headings from the active browser tab.",
  inputSchema: z.object({
    maxItems: z.number().int().min(1).max(100).default(25),
  }),
  handler: async (args, ctx) => {
    const headings = await ctx.cdp.evaluate<string[]>(`
      Array.from(document.querySelectorAll('h1, h2, h3'))
        .slice(0, ${args.maxItems})
        .map(el => el.textContent?.trim() || '')
        .filter(Boolean)
    `);
    return { count: headings.length, headings };
  },
});

export default definePlugin({
  name: "weavetab-plugin-headings",
  version: "1.0.0",
  description: "Fast heading extraction tool for Weavetab MCP.",
  permissions: {
    cdp: { evaluate: true, reason: "Reads H1-H3 text nodes from the active tab." },
  },
  tools: [extractHeadings],
});
```

## 3. Plugin Context API (`ctx` passed to `handler(args, ctx)`)
- `ctx.cdp.evaluate<T>(expression: string): Promise<T>` — Evaluates JavaScript in the active browser tab.
- `ctx.cdp.send<T>(method: string, params?: Record<string, unknown>): Promise<T>` — Sends a raw Chrome DevTools Protocol command (e.g. `Page.captureScreenshot`, `DOM.getDocument`, `Network.enable`).
- `ctx.cdp.navigate(url: string): Promise<void>` — Navigates the active tab.
- `ctx.storage.get<T>(key: string): Promise<T | null>` — Reads plugin-scoped persistent JSON state (`~/.weavetab/plugin-storage/`).
- `ctx.storage.set<T>(key: string, value: T): Promise<void>` — Writes plugin-scoped persistent JSON state.
- `ctx.storage.delete(key: string): Promise<void>` — Deletes a key from plugin storage.
- `ctx.logger.info(msg)` / `ctx.logger.warn(msg)` / `ctx.logger.error(msg)` — Structured diagnostic logging.

## 4. Required `weavetab.json` Manifest (at package root)
Auto-generate from your TypeScript entry with `npx weavetab-sdk manifest`, or create `weavetab.json` at the package root:
```json
{
  "$schema": "https://weavetab.dev/schema/plugin.json",
  "name": "weavetab-plugin-headings",
  "displayName": "Heading Extractor",
  "version": "1.0.0",
  "description": "Fast heading extraction tool for Weavetab MCP.",
  "main": "dist/index.js",
  "engines": {
    "weavetab": ">=2.5.0",
    "node": ">=20.0.0"
  },
  "permissions": {
    "cdp": {
      "evaluate": true,
      "reason": "Reads H1-H3 text nodes from the active tab."
    }
  },
  "tools": [
    {
      "name": "extract_headings",
      "description": "Extracts all H1-H3 headings from the active browser tab."
    }
  ]
}
```

## 5. Required `package.json` Fields for Marketplace Discovery
To appear automatically on `https://weavetab.dev/discover`:
1. Include `"weavetab-plugin"` in `keywords`.
2. Include `"weavetab.json"` and `"dist"` in `files`.
3. Declare `"@weavetab/sdk": "^2.6.0"` in `dependencies` or `peerDependencies`.

## 6. Unit Testing with `PluginTestHarness` (`test/plugin.test.mjs`)
```javascript
import test from "node:test";
import assert from "node:assert/strict";
import { PluginTestHarness } from "@weavetab/sdk";
import plugin from "../dist/index.js";

test("extract_headings returns headings from mocked CDP", async () => {
  const harness = new PluginTestHarness(plugin, {
    evaluateHandler: async () => ["Welcome", "Features"],
  });
  const res = await harness.invokeTool("extract_headings", { maxItems: 10 });
  assert.equal(res.count, 2);
  assert.deepEqual(res.headings, ["Welcome", "Features"]);
});
```


---

# SECTION 2: DOCUMENTATION PAGES


## DOC: Weavetab MCP Documentation (Slug: documentation)

> Weavetab documentation guide for Documentation.

# Weavetab MCP Documentation

> **Package:** `@weavetab/mcp` | **Version:** 2.6.0 | **License:** AGPLv3 | **Author:** fy2ne

---

## Overview

Weavetab is a production-grade, in-process MCP (Model Context Protocol) server providing AI agents with direct control across Chromium browsers and Electron desktop applications. It communicates directly over the Chrome DevTools Protocol (CDP) WebSocket — no WebDriver process, no browser binary download, no cloud middleware.

### Core Capabilities

- **41 Built-in MCP Tools** across functional categories (Vision, Navigation, Input, Tabs, Mission Execution, Dialog, Wait, Storage, Device, Network, Canvas, Output, Evaluation, Office Documents)
- **Direct CDP WebSocket** — Local in-process transport, zero external driver overhead
- **Semantic Delta Engine** — 5-10x token reduction via per-tab snapshot diffing
- **Ghost Cursor** — Bézier curve click engine with human acceleration and jitter
- **Human Typing Engine** — burst-pattern profiling, per-character jitter, natural pauses
- **Blind Injection** — enterprise-grade credential injection via `secrets.json` with domain scoping, Shadow DOM isolation, and JS property hardening
- **Self-Learning** — per-domain session memory, knowledge hints, automatic framework detection
- **Security Stack** — domain blacklist, RBAC (5 roles), rate limiter, loop detection, input filter, root guard
- **Burst Mode** — chain N actions in 1 MCP call via `browser_burst`
- **Plugin System** — Extensible plugin ecosystem supporting tool additions, overrides (with originalHandler wrapping), and tool removals across 3 trust tiers (Official, Verified, Unverified)
- **GitHub Automation (Plugin)** — Repo analysis, file reading, issues, and PRs are provided by the official `@weavetab/plugin-github` plugin, not built in

### Weavetab Skills

**Weavetab Skills** is an optional companion package (`@weavetab/skills`) that provides pre-built workflow patterns and mission templates for AI agents. These skills help agents understand complex Weavetab workflows and execute multi-step missions more effectively.

**Installation:**
```bash
npm install -g @weavetab/skills
```

**Available Skills:**
- **Multi-step Form Automation** — Complex form filling with validation handling
- **E-commerce Checkout** — Shopping cart navigation and payment processing
- **Data Extraction Pipelines** — Structured data scraping and export
- **Content Management Systems** — WordPress, Drupal, and CMS-specific workflows
- **API Testing & Validation** — Endpoint testing and response verification

Skills are automatically discovered by compatible MCP clients and provide context-aware guidance for mission planning.

---

## Architecture

```
MCP Client → stdio/WebSocket → WithSecurity Pipeline → CDP WebSocket → Chromium
                                 (RateLimit → DomainPolicy → RBAC)
```

### Five Architectural Layers

| Layer | Components | Responsibility |
|-------|-----------|----------------|
| **Transport** | stdio (JSON-RPC), WebSocket (port 3000) | MCP client communication |
| **Security & Governance** | Domain blacklist, Rate limiter, RBAC, Root guard, Storage blocker | Pre-flight checks |
| **Intelligence** | Session memory, Delta engine, DOM pruner, Trail/loop detection, Knowledge hints, Vision fallback | Token optimization, self-learning |
| **Sensor Systems** | Network telemetry, DOM mutations, Human pacing, Agent state machine, Thought HUD | Runtime awareness |
| **CDP Bridge** | DOM walker, Ghost cursor, Keystroke engine, Pruner, Shadow DOM injector, Tab manager, Browser launcher | Browser control |

---

## Tool Reference (41 Tools)

All tools share: Zod schema validation, `withSecurity()` pipeline (rate limiting + domain policy + RBAC), structured audit logging.

### Vision & Reading (8 tools)

| Tool | Description |
|------|-------------|
| `browser_map` | DOM enumeration with volatile `w:NN` ref IDs, Set-of-Marks visual grounding (`visual: true` / `"auto"`), entity & card container binding (`┌ Heading`), active modal hoisting (`╔═ ACTIVE DIALOG ═╗`), nav cluster collapsing, delta diffing, and scope filtering (`modal`, `form`, `main`). |
| `browser_find` | Native CDP text search with single and multi-match (`all: true`, `limit: N`) returning bounding rects and selectors — ~10x cheaper than map |
| `browser_scrape` | CSS/XPath structured data extraction in 1 CDP call |
| `browser_inspect` | Computed CSS styles + inline styles + event listener types |
| `browser_snapshot` | MHTML capture/restore of DOM state + resources |
| `browser_screenshot` | PNG/JPEG capture via CDP, full-page + clip region, returns base64 data URL (no file pollution) |
| `browser_console` | Read/clear buffered console logs and exceptions |
| `browser_extract_design` | Extract design tokens, typography, colors, and clean CSS with pixel fidelity |

### Navigation (1 tool)

| Tool | Description |
|------|-------------|
| `browser_navigate` | Ultra-low latency navigation (~150-300ms) with non-blocking readyState polling, parallelized metadata, domain blocklist enforcement, and `weavetab://` protocol |

### Input (9 tools)

| Tool | Description |
|------|-------------|
| `browser_click` | Ghost Cursor (Bézier) click with direct visual mark targeting (`mark: N`), intent memory, occlusion detection, and stuck-loop detection |
| `browser_type` | Human keystroke engine with zero-target `document.activeElement` typing, anti-unfocus click avoidance, jitter, and burst patterns |
| `browser_type_secret` | Blind Injection from `secrets.json` — domain check before value load, Shadow DOM isolation, JS property hardening |
| `browser_key` | Native keyboard dispatch with combo hotkeys (`"Ctrl+A"`, `"Cmd+K"`, `"Alt+Tab"`) and zero arbitrary delay |
| `browser_pointer` | Hover, double-click, drag-and-drop, and multi-level flyout menu traversal via `hover_chain: ["File", "Export As", "PNG"]` |
| `browser_select` | Native `<select>` dropdown selection — React/Vue safe (prototype setter + events) |
| `browser_fill` | Smart multi-field form batch completion with input discovery scanner (`scan: true`), flexible field selectors, and Google Sheets `grid_data` |
| `browser_upload` | Bypass file dialogs via CDP `DOM.setFileInputFiles` |
| `browser_scroll` | Fast non-blocking directional + element-relative scroll without redundant action map rebuilds |

### Tabs & Windows (2 tools)

| Tool | Description |
|------|-------------|
| `browser_tabs` | Open/switch/close/list/consolidate (dedup)/heal (recover crash). Also list/focus windows |
| `browser_detect` | Detect installed browsers + CDP feature coverage per engine (Chromium, Firefox, WebKit) |

### Mission Execution (2 tools)

| Tool | Description |
|------|-------------|
| `browser_burst` | Chain N actions in 1 MCP call. Supports 4 macro steps: `type_and_send`, `navigate_and_read`, `click_and_wait`, `scroll_and_read` |
| `browser_automation` | Inject persistent self-running scripts — monitoring, polling, background extraction |

### Dialog & User Interaction (3 tools)

| Tool | Description |
|------|-------------|
| `browser_dialog` | Accept/dismiss JavaScript alert/confirm/prompt dialogs |
| `browser_thoughts` | Green thought bubbles: feedback (one-way) or question with input (sentence/paragraph modes) |
| `browser_clipboard` | System clipboard R/W (text, images, or both in one write) |

### Wait & Timing (2 tools)

| Tool | Description |
|------|-------------|
| `browser_wait` | Wait for element/text/URL/stable/network/auto — timeout configurable, optional loop counter reset (`reset_loop: true`) |
| `browser_captcha` | Autonomous zero-API detection and solving for Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha via CDP mouse physics |

### Storage & Cookies (2 tools)

| Tool | Description |
|------|-------------|
| `browser_storage` | localStorage & sessionStorage get/set/clear |
| `browser_cookies` | Cookies get/set/delete |

### Device & Environment (2 tools)

| Tool | Description |
|------|-------------|
| `browser_viewport` | Viewport, device emulation, geolocation, timezone override |
| `browser_emulate` | Network throttling (3G/4G/offline), CPU slowdown, geolocation, timezone, and User-Agent override |

### Network (1 tool)

| Tool | Description |
|------|-------------|
| `browser_network_intercept` | Mock API responses, block tracking, and retrieve raw protocol network telemetry (TLS/SSL certificate metadata, microsecond timing breakdown, OS-level failure reasons) |

### Canvas & Visual (2 tools)

| Tool | Description |
|------|-------------|
| `browser_canvas` | Get image data (base64 PNG) or draw points on canvas |
| `browser_highlight` | Visual CDP overlay highlight — zero token cost |

### Output (2 tools)

| Tool | Description |
|------|-------------|
| `browser_pdf` | Print page to PDF — landscape, scale, page ranges |
| `browser_recording` | Compile browser screencast frames into video (.webp, .gif, .mp4, .webm) |

### Evaluation (1 tool)

| Tool | Description |
|------|-------------|
| `browser_eval` | Run arbitrary JS via CDP Runtime.evaluate. On `weavetab://` pages, supports building UIs via `wt-dashboard-command` events |

### Performance (1 tool)

| Tool | Description |
|------|-------------|
| `browser_performance` | Core Web Vitals, memory, navigation timing, and resource timings |

### GitHub Automation (Plugin)

GitHub support is no longer a built-in tool. It is provided by the official `@weavetab/plugin-github` plugin, which registers a single `github` tool (actions: `analyze`, `read`, `issues`, `pr`). Install it with `weavetab plugin add @weavetab/plugin-github`.

### Utility (3 tools)

| Tool | Description |
|------|-------------|
| `browser_checkpoint` | Snapshot and restore browser state (cookies, storage, scroll/URL) into named checkpoints for time-travel and rollback |
| `browser_pattern_learn` | Read, register, and update named workflow patterns and site quirks per origin |
| `browser_office` | Parse Word (`.docx`), Excel (`.xlsx`), PDF, and CSV files into structured data |

---

## Secrets Management

Secrets are stored in structured `secrets.json` files with `chmod 600` enforcement and atomic file writes (temp file + rename).

### Resolution Order

1. `./.weavetab/secrets.json` (project-scoped, opt-in via `weavetab secrets init --project`)
2. `~/.weavetab/secrets.json` (global default)

> **Note:** The legacy `.env`-based `EnvSecretProvider` is **deprecated and no longer supported**. All secrets must use `secrets.json`.

### CLI Commands

```bash
weavetab secrets set MY_KEY          # Prompts for value securely
weavetab secrets list                # Shows keys + domains only (never values)
weavetab secrets rm MY_KEY           # Remove a secret
weavetab secrets init --project      # Create project-scoped secrets + config
```

### Secrets File Format

```json
{
  "API_KEY": {
    "value": "sk-...",
    "domains": ["api.example.com"],
    "description": "Production API key"
  }
}
```

### Blind Injection

Use `browser_type_secret` to inject credentials without exposing them to the LLM:

```typescript
browser_type_secret({ 
  id: "w:1", 
  envKey: "API_KEY" 
})
```

The value is permanently masked as `[REDACTED]` in all subsequent DOM reads and audit logs.

---

## Configuration

### Config File Locations

- **Global:** `~/.weavetab/config.json`
- **Project:** `./.weavetab/config.json` (if exists, takes precedence)

### Config Structure

```json
{
  "browserType": "chromium",
  "headless": false,
  "devMode": true,
  "maxActionsPerMinute": 60,
  "role": "admin",
  "telemetry": false,
  "attachPort": 0,
  "extension": true,
  "cookies": false,
  "browserFlags": [],
  "policies": [],
  "electron": {
    "discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\app-<version>\\Discord.exe",
    "antigravity": "C:\\Users\\<user>\\AppData\\Local\\Programs\\antigravity\\Antigravity.exe",
    "vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe"
  }
}
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `browserType` | string | "chromium" | Browser to use (chromium, firefox, webkit) |
| `headless` | boolean | false | Run browser in headless mode |
| `devMode` | boolean | false | Enable HUD overlay and verbose logging |
| `maxActionsPerMinute` | number | 60 | Rate limit for tool executions |
| `role` | string | "admin" | RBAC role (admin, operator, viewer, automation, system) |
| `telemetry` | boolean | false | Enable anonymous usage telemetry |
| `attachPort` | number | 0 | Chrome DevTools Protocol port |
| `extension` | boolean | true | Enable Weavetab extension integration |
| `cookies` | boolean | false | Persist cookies/storage across sessions. When `false`, `document.cookie`, `localStorage`, and `sessionStorage` are all neutered at the browser level (returns empty/null for everything) + a fresh isolated profile is used each session. When `true`, cookies/storage work normally and persist via the profile directory. |
| `browserFlags` | string[] | `[]` | Extra Chromium command-line flags to append on launch (e.g., `["--disable-web-security"]`). The `--disable-sync` flag is mandatory and cannot be overridden — any conflicting flag is automatically dropped. |
| `policies` | PolicyEntry[] | `[]` | Domain-level access control policies (see [Domain Policy](#domain-policy) below). Supersedes the legacy `block`/`allow` lists. |
| `electron` | Record<string, string> | `{}` | Map of registered Electron desktop applications (e.g. Discord, VS Code, Figma, Antigravity, local dev apps) to executable paths or startup commands. |

---

## Domain Policy

The `policies` config option provides **fine-grained domain-level access control** that supersedes the legacy `block`/`allow` lists. Policies are checked **in array order** before every tool execution — the first matching pattern wins. If no policy matches, the legacy `block`/`allow` lists are checked as fallback, then access is allowed by default.

Configure policies in your `config.json` under the top-level `policies` array:

```json
{
  "policies": [
    {
      "pattern": "*.banking.com",
      "mode": "deny"
    },
    {
      "pattern": "banking.com",
      "mode": "allow"
    },
    {
      "pattern": "*.internal.com",
      "mode": "read-only"
    },
    {
      "pattern": "*.trusted.com",
      "mode": "allow"
    },
    {
      "pattern": "*.audit-logs.com",
      "mode": "audit-only"
    }
  ]
}
```

### Policy Modes

| Mode | Description |
|------|-------------|
| `allow` | Full access to all tools. Explicitly whitelists a domain. |
| `read-only` | Only observation tools allowed: map, find, scrape, console, eval, inspect, snapshot, pdf, cookies. Blocks write tools (click, type, navigate, etc.). |
| `deny` | Complete block of all interactions on that domain. |
| `audit-only` | All tools allowed, but every action is logged for audit trails. |

### Key Differences from `block`/`allow` Lists

| Feature | Legacy `block`/`allow` | `policies` |
|---------|----------------------|------------|
| Modes | Only allow or deny | 4 modes: allow, deny, read-only, audit-only |
| Wildcards | Supported | Supported (`*` wildcard) |
| Order | No ordering | **First match wins** — order matters |
| Granularity | Domain only | Domain + per-tool enforcement (read-only blocks writes) |
| Check timing | At navigation | Every tool execution |

---

## RBAC Roles

### Role Definitions

| Role | Permissions |
|------|-------------|
| `admin` | Full access to all tools |
| `operator` | Full access to all tools (standard agent role) |
| `viewer` | Read-only observation tools only (`browser_map`, `browser_find`, `browser_scrape`, `browser_console`, `browser_eval`, `browser_inspect`, `browser_extract_design`, `browser_snapshot`, `browser_screenshot`, `browser_pdf`, `browser_cookies`, `browser_tabs`, `browser_wait`, `browser_pattern_learn`) |
| `automation` | Full access except `browser_thoughts` (non-interactive CI/CD mode) |
| `system` | Internal tools only (`browser_thoughts`, `browser_detect`, `browser_performance`, `browser_checkpoint`, `browser_pattern_learn`) |

### Setting Role

```json
{
  "role": "viewer"
}
```

---

## Performance Optimization

### Token Efficiency

Use `browser_map` with delta and pruning for maximum efficiency:

```typescript
// First call: full map
browser_map({ prune: true })

// Subsequent calls: only changes
browser_map({ delta: true, prune: true })
```

### Latency Optimization

- Use `speed: "fast"` on `browser_scroll` and `profile: "fast"` on `browser_type` for faster execution
- Enable `prune: true` to reduce DOM processing time
- Use cached ref IDs instead of label-based lookups
- Avoid unnecessary DOM walks with `browser_find` for text search

### Memory Optimization

- Clear cache periodically: `weavetab reset`
- Use `limit` parameter in `browser_map` to reduce cache size
- Enable `prune: true` to reduce memory footprint
- Restart Weavetab for long-running sessions

---

## Plugin System

### Creating a Plugin

Create any npm package with a `weavetab.json` manifest at its root:

```json
// my-plugin/package.json
{
  "name": "wt-my-tool",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module"
}
```

```json
// my-plugin/weavetab.json
{
  "name": "My Custom Tool",
  "version": "1.0.0",
  "description": "Custom MCP tool for Weavetab",
  "tools": [
    {
      "name": "my_custom_tool",
      "description": "My custom tool description"
    }
  ]
}
```

```typescript
// my-plugin/index.ts
import { definePlugin, type PluginContext } from "@weavetab/sdk";

export default definePlugin({
  name: "wt-my-tool",

  async onLoad(ctx: PluginContext) {
    ctx.mcp.registerTool({
      name: "my_custom_tool",
      description: "My custom tool description",
      schema: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"]
      },
      handler: async (args, session) => {
        return { content: [{ type: "text", text: "result" }] };
      }
    });
  }
});
```

### Installing Plugins

```bash
# Official plugins
weavetab plugin add @weavetab/plugin-sample

# Community plugins (any npm name)
weavetab plugin add wt-my-tool
# or via npm
npm install wt-my-tool
```

Plugins with a valid `weavetab.json` are automatically discovered on Weavetab startup.

---

## Weavetab Skills

### Using Skills

Skills provide pre-built workflow patterns that help agents understand complex multi-step operations:

```bash
npm install -g @weavetab/skills
```

### Available Skills

- **Form Automation** — Handles complex forms with validation, multi-page flows, and error recovery
- **E-commerce** — Shopping cart navigation, product selection, checkout processes
- **Data Extraction** — Structured scraping, pagination handling, data export
- **CMS Workflows** — WordPress, Drupal, and other CMS-specific operations
- **API Testing** — Endpoint discovery, request/response validation, test automation

### Skill Integration

Skills are automatically discovered by MCP clients and provide:

- Context-aware workflow guidance
- Step-by-step mission templates
- Error handling patterns
- Best practice recommendations

---

## Electron & Desktop Application Automation

Weavetab natively supports **generic automation of any Electron or Chromium-based desktop application** (e.g. Discord, Slack, VS Code, Antigravity IDE, Figma, Obsidian, Postman, or local developer applications running from source).

### How It Works Under the Hood
Electron desktop applications run a bundled Chromium/Blink engine under the hood. When started with Chrome DevTools Protocol debugging enabled (either automatically via Weavetab or via `--remote-debugging-port`), Weavetab connects directly to the desktop app's internal WebSockets and exposes all 41 built-in MCP tools without requiring external drivers or wrappers.

### Registering Applications
In `~/.weavetab/config.json` or project-scoped `.weavetab/config.json`:

```json
{
  "electron": {
    "discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\app-<version>\\Discord.exe",
    "antigravity": "C:\\Users\\<user>\\AppData\\Local\\Programs\\antigravity\\Antigravity.exe",
    "vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
    "figma": "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe",
    "obsidian": "C:\\Users\\<user>\\AppData\\Local\\Obsidian\\Obsidian.exe",
    "my-app": "C:\\path\\to\\my-project\\node_modules\\electron\\dist\\electron.exe"
  }
}
```

### Automating Local / Source-Hosted Projects
When developing an Electron app locally (e.g. `localhost:3000` or running via Vite/Webpack/Electron forge):

1. **Launch with remote debugging enabled:**
   ```bash
   npx electron . --remote-debugging-port=9222
   # or with npm scripts:
   npm run dev -- --remote-debugging-port=9222
   ```

2. **Automate via MCP tools:**
   Set `"attachPort": 9222` or register the dev script in `"electron"` config.

### Tool Execution Flow with Desktop Apps
Every Weavetab tool supports the optional `app` parameter:

| Tool Call | Desktop Behavior |
| :--- | :--- |
| `browser_navigate({ app: "antigravity" })` | Launches or connects to Antigravity's CDP session |
| `browser_tabs({ action: "list", app: "antigravity" })` | Lists all windows, webviews, and workbench tabs in the app |
| `browser_tabs({ action: "switch", tabId: "<id>", app: "antigravity" })` | Switches active focus to the specified workbench or window |
| `browser_map({ app: "antigravity" })` | Generates semantic Ref IDs (`w:NN`) for the desktop app's active window |
| `browser_click({ ref: "w:12", app: "antigravity" })` | Sends Ghost Cursor click to the desktop app element |
| `browser_type({ ref: "w:15", text: "...", app: "discord" })` | Types text directly into the desktop app input field |
| `browser_eval({ expression: "...", app: "vscode" })` | Evaluates JavaScript inside the desktop app frame context |

---

## Troubleshooting

### Common Issues

1. **CDP connection failed** — Ensure Chrome is running with `--remote-debugging-port=9222`
2. **Extension not loading** — Use headed mode or `--headless=new` Chrome flag
3. **High memory usage** — Clear cache with `weavetab reset` or enable pruning
4. **Token usage high** — Use `delta: true` and `prune: true` in `browser_map`
5. **Clicks failing** — Use ref IDs from `browser_map` instead of labels

### Debug Mode

Enable `devMode: true` in config for:

- Real-time tool execution timing
- Token usage estimates
- Detailed error messages
- HUD overlay in browser

### Audit Logs

Review the latest `~/.weavetab-system/logs/mission_<timestamp>.log` for:

- Tool invocation history
- Error messages and stack traces
- Domain policy violations
- Security events

For detailed troubleshooting, see [TROUBLESHOOTING.md](../TROUBLESHOOTING.md).

---

## Additional Resources

- [Tool Reference](tools/tools.md)
- [Plugin System Guide](PLUGINS.md)
- [Architecture Documentation](../ARCHITECTURE.md)
- [Support & Community](../SUPPORT.md)
- [Security Policy](../SECURITY.md)
- [Contributing Guidelines](../CONTRIBUTING.md)
- [Troubleshooting Guide](../TROUBLESHOOTING.md)


---

## DOC: Weavetab Plugin System & SDK Specification (Slug: plugins)

> Weavetab documentation guide for Plugins.

# Weavetab Plugin System & SDK Specification

> **Version:** 2.6.0 | **SDK:** @weavetab/sdk (MIT) | **Runtime:** AGPL-3.0-only

The **Weavetab Plugin System** allows developers to extend the MCP runtime with custom tools, visual HUD overlays, thought bubbles, lifecycle hooks, and tool overrides.

---

## 1. Quick Start

### Scaffold a New Plugin

```bash
npx @weavetab/sdk init my-custom-plugin
cd my-custom-plugin
npm install
```

### Build & Compile

```bash
npm run build
```

---

## 2. Plugin Architecture

Every Weavetab plugin exports a plugin definition created with `definePlugin`:

```typescript
// src/index.ts
import { definePlugin, type PluginContext } from "@weavetab/sdk";

export default definePlugin({
  name: "weavetab-plugin-sample",
  version: "1.0.0",
  description: "Sample custom tool plugin for Weavetab",

  defaultConfig: {
    enableHud: true,
  },

  async onLoad(ctx: PluginContext) {
    // Register a custom MCP tool
    ctx.mcp.registerTool({
      name: "custom_analyzer",
      description: "Performs custom DOM analysis",
      schema: {
        type: "object",
        properties: {
          selector: { type: "string", description: "Target CSS selector" }
        },
        required: ["selector"]
      },
      handler: async (args: { selector: string }, session: any) => {
        // Show thought bubble on the browser tab
        if (ctx.config.enableHud && session) {
          await ctx.extension.showThought(session, `Analyzing ${args.selector}`);
        }

        return {
          content: [
            { type: "text", text: `Analysis complete for ${args.selector}` }
          ]
        };
      }
    });
  },

  async onUnload(ctx: PluginContext) {
    // Cleanup resources
  }
});
```

---

## 3. Manifest Specification (weavetab.json)

Plugins require a `weavetab.json` manifest in their package root:

```json
{
  "$schema": "https://weavetab.dev/schema/plugin.json",
  "name": "weavetab-plugin-sample",
  "version": "1.0.0",
  "entry": "dist/index.js",
  "engines": {
    "weavetab": ">=2.6.0",
    "node": ">=18.0.0"
  },
  "permissions": {
    "extension": { "hud": true, "reason": "Displays HUD thoughts" },
    "cdp": { "evaluate": true, "reason": "Runs DOM analysis" },
    "tools": { "add": true, "reason": "Registers the custom_analyzer tool" }
  },
  "tools": [
    {
      "name": "custom_analyzer",
      "description": "Performs custom DOM analysis"
    }
  ]
}
```

> Registering tools at runtime via `ctx.mcp.registerTool()` requires the `permissions.tools.add` permission.

---

## 4. Plugin Capabilities

| Capability | API | Description |
| :--- | :--- | :--- |
| **Sandboxed Storage** | `ctx.storage.get()`, `ctx.storage.set()` | Isolated key-value storage in `~/.weavetab/plugins/<name>/`. |
| **Thought Bubbles** | `ctx.extension.showThought(session, text)` | Floating green thoughts on the live browser tab. |
| **HUD Badges** | `ctx.extension.setHudState(session, state)` | Real-time status in the Weavetab overlay. |
| **Tool Overrides** | `ctx.mcp.overrideTool(name, wrapperFn)` | Wrap or intercept built-in MCP tools with custom pre/post logic. |
| **Lifecycle Hooks** | `ctx.hooks.beforeToolCall`, `ctx.hooks.afterToolCall` | Global auditing and security filters. |

---

## 5. Installing Plugins

Plugins are installed directly from npm into `~/.weavetab/plugins/` using the Weavetab CLI:

```bash
# Install a plugin by package name (or official short alias):
weavetab plugin add <plugin-name>

# Install from a local directory during plugin development:
weavetab plugin add ./path/to/plugin

# List all active installed plugins:
weavetab plugin list

# Remove an installed plugin:
weavetab plugin rm <plugin-name>
```

---

## 6. Preflight & Testing

Before publishing to npm, verify your plugin with the official SDK preflight audit and testing harness:

```bash
# Run SDK preflight audit (manifest, licenses, permissions, naming anti-squatting):
npx @weavetab/sdk preflight

# Offline unit testing without launching Chrome:
npm test
```

Installed plugins mount automatically on server startup. Tool results returned as strings, markdown, or JSON objects are normalized directly into MCP standard content format.


---

## DOC: Weavetab MCP Tool Reference (Slug: tools)

> Weavetab documentation guide for Tools.

# Weavetab MCP Tool Reference

> **Version:** 2.6.0 | **Total Tools:** 41 | **Architecture:** Direct CDP WebSocket

Weavetab provides 41 production-grade MCP tools organized into functional categories.

| Tool Name | Category | Description | Key Features |
| :--- | :--- | :--- | :--- |
| `browser_map` | `vision` | Snapshot interactive DOM with stable ref IDs (w:NN). For complex SPAs, use scope or query to constrain tokens. Supports delta temporal diffing (up to 97% token reduction), semantic pruning (dropping hidden elements), Set-of-Marks visual grounding (visual: true / "auto" for canvas/WebGL pages), AX tree fallback (Shadow DOM traversal), scope filtering, query filtering, and forced rebuilds with automatic loop strike reset (force: true). | Semantic DOM pruning (up to 97% token reduction with delta), Set-of-Marks visual grounding (visual: true / "auto"), Per-tab snapshot temporal diffing (delta mode) |
| `browser_navigate` | `navigation` | Navigate to a URL. Enforces domain security policies and rate limits prior to navigation. Waits for network idle and DOM readiness. Supports internal protocol schemes (e.g. weavetab://). | Domain policy engine and blocklist enforcement, Deterministic DOM stability and network idle waiting, weavetab:// internal protocol support |
| `browser_click` | `input` | Click a DOM element. Physical click engine incorporating Bézier curve trajectory kinematics (Ghost Cursor). Multi-stage targeting fallback: mark number (SoM visual grounding) -> ref ID -> selector -> label -> intent -> coordinates -> backendNodeId. | Direct mark number targeting (mark: N) from visual mode, Bézier curve trajectory kinematics, Humanized acceleration and velocity curves |
| `browser_type` | `input` | Type text into a single input field. Keystroke dispatch engine with per-character temporal jitter and burst profiling. Real-time DOM-diffing monitors stuck input state. Supports atomic clearFirst and clipboard paste modes. | Per-character temporal jitter simulation, Burst keystroke profiling, Stuck-typing loop detection via DOM diffing |
| `browser_type_secret` | `input` | Inject a secret from an environment variable / secrets.json. Blind Injection: securely injects credentials without exposing sensitive values to the LLM context. Permanently masked as [REDACTED] in DOM maps and logs. | Zero LLM context exposure for credentials, Domain-scoped authorization checks, Shadow DOM input isolation |
| `browser_key` | `input` | Press a keyboard key. Dispatches native hardware key events with modifier key support (Ctrl, Shift, Alt, Meta) to focused elements. | Native key code and key identifier mapping, Modifier key combination handling, Per-tab keyboard focus targeting |
| `browser_scroll` | `input` | Scroll the page or targeted element. Smooth scrolling engine via CDP Input.dispatchMouseEvent wheel events. Supports directional delta scrolling and element-relative scroll centering. | Directional scrolling (up, down, left, right), Configurable pixel scroll distance, Element-relative scroll targeting via ref ID or label |
| `browser_dialog` | `dialog_and_interaction` | Accept or dismiss JS dialogs (alert, confirm, prompt) via CDP Page.handleJavaScriptDialog. | Handling of alert, confirm, and prompt modal types, Accept and dismiss actions, Prompt response text payload submission |
| `browser_burst` | `mission_execution` | HIGH-SPEED MULTI-ACTION PIPELINE: Executes 2 or more sequential browser actions in a single round-trip without waiting for LLM turns between steps. PREFER THIS over individual single-action calls to slash latency and token burn. Supports native primitives (browser_click, browser_fill, browser_type, browser_type_secret, browser_navigate, browser_key, browser_scroll, browser_wait, browser_map) plus compound macros (type_and_send, click_and_wait, navigate_and_read, scroll_and_read, fill_form). If compile_from_history: true is passed, automatically compiles and executes recent successful session trail actions into a burst macro. | Single-request multi-action pipeline execution with zero intermediate LLM round-trips, Compound macro abstractions (type_and_send, click_and_wait, navigate_and_read, scroll_and_read, fill_form, drag_and_drop, hover_and_read), Automatic session history compilation into replayable burst macros (compile_from_history: true) |
| `browser_tabs` | `tabs` | Manage browser and Electron app tabs/windows (open, switch, close, list). Specify 'app' when targeting desktop apps (e.g. app: 'discord') to avoid opening web browser. | Single and batch tab operations, Duplicate tab consolidation, Crash session recovery (heal) |
| `browser_wait` | `navigation` | Pause until a condition is met ('element', 'text', 'url', 'stable', 'network', 'auto'). Deterministic wait engine for asynchronous web state synchronization. | Element, text, URL, DOM stability, and network idle conditions, Configurable timeout thresholds, Per-tab asynchronous execution target |
| `browser_captcha` | `safety` | Autonomous zero-API detection and solving of Turnstile, reCAPTCHA, GeeTest, and hCaptcha bot challenges using local CDP behavioral solvers. | Zero-API autonomous solving, Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha support, Human oversight fallback via wait_for_user |
| `browser_thoughts` | `dialog_and_interaction` | Agent-to-user communication layer rendered in the middle down of the page. Supports question mode (interactive prompt with answer submission) and feedback mode (status, observation, decision, or warning update). Supports contextual element anchoring (anchor: 'w:NN') and visual styles ('observation', 'decision', 'warning', 'question'). | Middle-down floating card HUD with precision dark styling, Contextual element anchoring (anchor: 'w:NN') with auto-highlighting, Feedback mode (observation, decision, warning updates) |
| `browser_pointer` | `input` | Advanced pointer control (hover, click, double_click, drag_and_drop) with Bézier curve kinematics. Supports waitForChild pattern for dynamic flyout menus. | Hover, click, double_click, and drag_and_drop actions, Bézier curve cursor motion, waitForChild trigger menu resolution |
| `browser_select` | `input` | Select an option from a native dropdown by visible text or value. Uses native property setters and dispatches input/change events for framework compatibility (React, Vue, Angular). | Option matching by visible text or value, Framework-safe prototype property setter invocation, Synthetic input and change event dispatch |
| `browser_fill` | `input` | Smart multi-field form-filling. Evaluates field control types (text, select, checkbox, radio, contenteditable) and processes inputs sequentially with atomic verification. | Multi-field batch input execution, Automatic control type classification, Per-field post-input verification |
| `browser_highlight` | `canvas_and_visual` | Highlight elements on page. Renders temporary visual overlays over target elements without DOM tree mutations. Supports multi-element consideration overlays (refs: ['w:12', 'w:15']), presentation styles ('consideration', 'target', 'danger', 'success', 'shimmer'), floating badges, and configurable durations. | Multi-candidate consideration overlay (refs array), Five visual styles: consideration, target lock, danger, success, shimmer, Floating label badge display above highlighted elements |
| `browser_upload` | `input` | Upload files to a file input. Bypasses OS native file pickers via CDP DOM.setFileInputFiles directly targeting file input node IDs using absolute file paths. | Direct CDP file payload injection, Multi-file payload support, Zero OS file picker interaction required |
| `browser_find` | `vision` | Fast in-page text search via a leaf-optimized TreeWalker. Best for locating specific keywords/text on page without a full DOM map. | Leaf-optimized TreeWalker text search, Low-overhead in-page matching, Exact keyword matching and match indexing |
| `browser_storage` | `storage_and_cookies` | Manage localStorage and sessionStorage. Reads, writes, and clears key-value pairs for the active origin. | localStorage and sessionStorage scope targeting, Atomic key-value retrieval and mutation, Origin storage purging |
| `browser_checkpoint` | `storage_and_cookies` | Snapshot and restore browser state (cookies, localStorage, sessionStorage, and scroll/URL) into named checkpoints to time-travel and rollback failed automation branches. | Session state time-travel and rollback, Cookies backup and restoration (HttpOnly and Secure via CDP), LocalStorage and SessionStorage snapshotting |
| `browser_network_intercept` | `network` | Intercept/stub network responses (mock APIs, block tracking) and capture raw protocol network telemetry (TLS/SSL certificate metadata, microsecond timing breakdown, and OS-level network failure reasons). | URL glob pattern matching and response mocking, TLS/SSL Certificate security metadata (issuer, protocol, validity, cipher), Microsecond Network Timing breakdown (DNS, TCP, SSL, send, TTFB, download) |
| `browser_console` | `vision` | 1-5ms latency access to buffered browser console messages, JS exceptions, and network errors tracked via CDP Runtime.consoleAPICalled. | Buffered console output stream retrieval, Buffer clearance actions, Runtime exception stack capture |
| `browser_pdf` | `output` | Print the current page to a PDF file via CDP Page.printToPDF with configurable orientation, scale, and page ranges. | Landscape and portrait orientation options, Print scale factor adjustment, Page range subset printing |
| `browser_eval` | `evaluation` | Run arbitrary JS via CDP in page context via CDP Runtime.evaluate. Supports asynchronous evaluation and structured JSON serialization. | Page JS context execution, Async/await promise resolution, Structured JSON return serialization |
| `browser_cookies` | `storage_and_cookies` | Manage browser cookies. Full CRUD management for HTTP and document cookies via CDP Network domain. | Cookie property retrieval, setting, and deletion, Domain and path attribute scoping |
| `browser_canvas` | `canvas_and_visual` | For ALL canvas content (charts, games, graphs). Use get_image to read pixel data as Base64 PNG, draw to simulate programmatic coordinate gesture paths. | Base64 PNG pixel buffer export, Programmatic gesture path drawing, Canvas node targeting via ref ID or selector |
| `browser_scrape` | `vision` | Structured data extraction via CSS or XPath selectors in a single CDP evaluation step. Returns structured text/attribute arrays. | CSS and XPath query evaluation, Targeted attribute extraction, Single-step execution (high throughput) |
| `browser_snapshot` | `vision` | Capture or restore an MHTML snapshot (DOM + inline assets). Facilitates offline state serialization, replay verification, and compliance auditing. | Full DOM and asset stream serialization, Atomic capture and restore operations, Offline state audit capability |
| `browser_screenshot` | `vision` | 95-135ms capture latency via CDP Page.captureScreenshot. Supports PNG and JPEG formats, full-page rendering, and clip region bounding boxes. | Full-page and viewport bounding box capture, PNG and JPEG format encoding, Custom clip region bounding box support |
| `browser_viewport` | `device_and_environment` | Set viewport dimensions and device emulation (width, height, DPR, mobile, geolocation, timezone, locale, color scheme). | Viewport width, height, and DPR emulation, Mobile viewport and touch event emulation, Geolocation coordinate override |
| `browser_clipboard` | `dialog_and_interaction` | Read or write to the system clipboard (plaintext or Base64 image payload data). | Read and write data operations, Plaintext and Base64 image payload format support |
| `browser_inspect` | `vision` | 15-35ms latency, zero waste. Deep DOM inspection returning computed styles, inline styles, box model dimensions, and attached event listener types. | Computed CSS style property inspection, Event listener type registration enumeration, Box model geometry verification |
| `browser_extract_design` | `vision` | Extract design tokens (colors, typography, spacing, shadows, CSS variables), semantic HTML layouts, and clean CSS into structured files and an LLM design blueprint. Ideal for cloning websites, UI components, and design systems with 100% pixel fidelity. | CSS custom properties and design token harvesting, Palette extraction and typography hierarchy mapping, Semantic clean DOM extraction with inline SVGs preserved |
| `browser_automation` | `mission_execution` | Inject self-running background script for monitoring/polling. Inject persistent scripts into the page context for continuous event tracking. | Background script context injection, Named automation script management, Decoupled event monitoring lifecycle |
| `browser_recording` | `output` | Record video screencasts of browser sessions. Automatically compiles captured frames into animated video files (.webp, .gif, .webm, .mp4) using native Node processing or system ffmpeg. | Native WebP/GIF animation compilation in pure Node, Configurable FPS and frame limits, FFmpeg fallback for WebM/MP4 encoding |
| `browser_detect` | `tabs` | CRITICAL INITIALIZATION TOOL. Detect available browsers and configured desktop apps (Discord, Slack, etc.). Call this FIRST before interacting with the environment to know if apps are online/offline and what tabs they have open. | Local browser engine discovery, Engine CDP API coverage analysis, Tool compatibility reporting per browser engine |
| `browser_performance` | `performance` | Retrieve page performance metrics. Collects Core Web Vitals (FCP, LCP, CLS) and detailed network resource timing distributions. | First Contentful Paint (FCP) and Largest Contentful Paint (LCP) capture, Cumulative Layout Shift (CLS) tracking, Resource loading timing distributions |
| `browser_pattern_learn` | `memory` | Read (action=get), register (action=learn), update, or record execution outcome for a named workflow pattern on a given origin in ~/.weavetab-system/memory/sites/. Use action=get at session start to inspect site profiles and reliability scores. Use learn after completing a flow to persist it for future fast-path replay. | Site profile inspection via action=get (reads ~/.weavetab-system/memory/sites/), Named pattern creation and update (merge-on-write, no duplicates), Volatile selector stabilization before persistence |
| `browser_office` | `documents` | Read and extract structured content from office documents (Excel, Word, PDF, CSV) via live browser session cookies or local downloads directory. | In-session authenticated document fetching, Structured tabular extraction (.xlsx, .csv), Document text and metadata extraction (.docx, .pdf) |
| `browser_emulate` | `environment` | Emulate browser environmental conditions over CDP: network throttling profiles, CPU slowdown multipliers, geolocation overrides, timezone IDs, and custom User-Agent strings. | Network throttling (Offline, Slow 3G, Fast 3G, 4G), CPU throttling multipliers, Geolocation and timezone overrides |

---

*Auto-generated via `npm run docs:generate` on 2026-10-31.*


---

## DOC: Blind Injection (Slug: blind-injection)

> Enterprise-grade credential injection that never exposes secrets to the LLM.

# Blind Injection & Secret Containment

The `browser_type_secret` tool and automated secret detection engine resolve passwords, tokens, API keys, PINs, and credentials directly from encrypted storage on the local host — **ensuring sensitive values never cross into the AI agent's context stream or tool outputs**.

## Core Architecture

```
[Encrypted secrets.json]
         │
         ▼ (In-process resolution & domain validation)
[Weavetab Server]
         │
         ▼ (Atomic CDP Input.insertText / ghostType)
[Chromium Target Field]
         │
         ├─► DOM Property Hardening (getter override, symbol coercion, toJSON)
         ├─► In-Memory SessionSecretTracker (backendNodeId & text redaction)
         └─► Dynamic Visual Masking (screenshot, snapshot, PDF blanking)
```

## Multi-Layer Containment Mechanisms

### 1. Zero-Exposure Injection
- Secrets are stored encrypted with AES-256-GCM via `weavetab secrets set <KEY>`.
- The agent passes the key name (`envKey: "MY_KEY"`), never the plaintext value.
- Domain scoping validates that the active tab's hostname matches the secret's allowed domains before any value is read from disk.
- Injection bypasses standard paste or readback mechanisms and writes directly via atomic CDP events.

### 2. Universal Element Selector Resolution
`browser_type_secret` supports:
- Direct CSS Selectors (e.g. `id: "#password"`, `id: "input[type='password']"`, `id: ".pwd-field"`)
- Element ActionMap IDs (e.g. `id: "w:5"` or `id: "5"`)
- Focused Active Element (`target: "focused"`)

### 3. DOM Property & Coercion Hardening
Upon injection or typing into any sensitive input:
- `data-wt-secret="true"` is attached to the DOM node.
- The element's `.value` getter is overridden at the instance level to return `"[REDACTED]"`.
- `Symbol.iterator`, `Symbol.toPrimitive`, and `toJSON` are overridden to prevent leakages via array spreads, template literals, or JSON serialization.

### 4. Cross-Tool Containment Matrix

| Tool | Protection Mechanism |
|---|---|
| `browser_type_secret` | In-process secret resolution, domain check, atomic CDP typing. |
| `browser_type` | Broad secret detection (`type`, `name`, `id`, `autocomplete`, `aria-label`); disables value readbacks and redactions in action logging. |
| `browser_fill` | Auto-registers secret fields in both single and `blast_mode`; masks values as `[REDACTED]` in return results and scan discovery mode (`scan: true`). |
| `browser_map` | DOM and Accessibility (AX) tree walkers redact values, placeholders, and labels for all sensitive fields. |
| `browser_scrape` | Evaluates in-page attribute extraction with automatic `[REDACTED]` substitution; filters live properties. |
| `browser_screenshot` | Applies dynamic security masking (`webkitTextSecurity: disc` / blanking) during capture and restores safely in `finally`. |
| `browser_snapshot` | Pre-masks all secret fields before MHTML export. |
| `browser_pdf` | Masks sensitive inputs during PDF generation. |

## CLI Usage

```powershell
# Store an encrypted secret with domain scoping
weavetab secrets set GITHUB_TOKEN

# List stored keys (never prints values)
weavetab secrets list

# Remove a stored key
weavetab secrets rm GITHUB_TOKEN
```

## Agent Tool Invocation

```json
{
  "id": "#password",
  "envKey": "GITHUB_TOKEN"
}
```

---

## DOC: Dual Injection (Slug: dual-injection)

> CDP early-script + Manifest V3 extension working in tandem.

# Dual Injection Strategy

Weavetab delivers overlay UI and stealth capabilities through **two complementary channels** that cover each other's blind spots.

## 1. CDP Early-Script Injection

```typescript
await session.Page.addScriptToEvaluateOnNewDocument({ source: STEALTH_SCRIPT });
await session.Runtime.evaluate({ expression: STEALTH_SCRIPT }).catch(() => {});
```

Runs **before any page JavaScript executes**. Handles:
- **Stealth patches**: `navigator.webdriver` → `undefined`, fake plugin arrays, WebGL/Canvas fingerprint noise
- **Shadow DOM bootstrap**: `#weavetab-root` host container created in every page
- **Config binding**: `window.__wt_setConfig`, `window.__wt_config` for live runtime updates

## 2. Manifest V3 Extension

Loaded dynamically with `--load-extension=${extPath}`. Owns:
- **Ghost Cursor animation** (Bézier curve path rendering via canvas overlay)
- **Thought bubble HUD** (agent status messages during tool execution)
- **Interactive Ask Modal** (user interaction with response queue)
- **SPA navigation persistence** — survives framework router transitions without flashing

---

## DOC: Architecture Overview (Slug: overview)

> Five layers, deterministic pipeline, zero cloud.

# Architecture Overview

Weavetab is decomposed into **five functional layers**, all running in-process without external daemon dependencies.

## Layer Map

| # | Layer | Responsibility |
|---|---|---|
| 1 | **Transport** | JSON-RPC 2.0 over stdio (default) or WebSocket (`--ws --port 3000`) |
| 2 | **Security & Governance** | Domain blacklist, rate limiter (mutex), RBAC roles, policy engine, root guard |
| 3 | **Intelligence Engine** | Session memory, semantic delta diffing, DOM pruner, loop detection, intent intercept |
| 4 | **Sensor Systems** | Network telemetry, DOM mutation observer, human pacing, agent state machine |
| 5 | **CDP Bridge** | DOM walker, Ghost Cursor (Bézier trajectories), keystroke engine, shadow-DOM injector |

## Tool Execution Pipeline

```text
Agent → withSecurity()
        ├── Rate limiter (mutex)
        ├── Domain policy check (allow/deny/audit/read-only)
        ├── RBAC role verification
        ├── User-stop polling
        ├── Chat queue draining
        ├── Agent state transition (idle → weaving → reading)
        └── Tool handler → CDP Bridge → Browser / Desktop App
```

Any validation or security failure short-circuits the pipeline immediately and returns a structured `WeaveError` — no partial side-effects are left on the browser.

## Why Direct CDP

| Feature | Weavetab | Playwright | Puppeteer | Selenium |
|---|---|---|---|---|
| **Architecture** | Direct CDP WebSocket | Node bridge abstraction | CDP wrapper | WebDriver |
| **Execution model** | **In-process local socket** | IPC binary bridge | IPC binary bridge | HTTP WebDriver relay |
| **Token efficiency** | **Semantic Deltas (97% reduction)** | Full DOM dumps | Full DOM dumps | Full DOM dumps |
| **Desktop Electron Apps** | **Native (any Electron app)** | Experimental | Limited | Third-party driver |
| **CAPTCHA Solver** | **Autonomous Zero-API** | None | None | None |
| **MCP native** | **Yes (41 Tools)** | No | No | No |
| **Cloud dependency** | **Zero** | Optional | Optional | Grid required |

---

## DOC: Security Model (Slug: security)

> Layered defenses that gate every tool invocation.

# Security Model

Weavetab executes direct CDP commands — security is layered and **deny-by-default for risky surfaces**.

## Defense-in-Depth Mechanisms

| Mechanism | Description |
|---|---|
| **Domain Blacklist** | Hard-blocked high-risk domains (banking, IAM consoles, internal infrastructure). |
| **Domain Policy Engine** | Per-domain enforcement modes: `allow`, `read-only`, `deny`, `audit`. |
| **Localhost Binding** | WebSocket server and CDP endpoints strictly bound to `127.0.0.1`. |
| **Rate Limiting** | Mutex-enforced actions-per-minute rate limiter. |
| **RBAC Roles** | 5 roles gating tool access (`admin`, `operator`, `viewer`, `automation`, `system`). |
| **Root Guard** | Prevents execution as root/superuser on Unix systems. |
| **Blind Injection** | Credential injection from `secrets.json` without exposing raw text to LLM context. |
| **Shadow DOM Isolation** | All injected HUD and modal overlays run in isolated Shadow DOM trees. |
| **Path Traversal Guard** | File upload and download paths strictly validated against path traversal. |

## RBAC Role Matrix

| Tool Category | admin | operator | viewer | automation | system |
|---|:---:|:---:|:---:|:---:|:---:|
| Mutation tools (`click`, `type`, `fill`, etc.) | yes | yes | no | yes | no |
| Read-only tools (`map`, `find`, `scrape`, `screenshot`) | yes | yes | yes | yes | no |
| High-level orchestration (`burst`, `automation`, `wait`) | yes | yes | no | yes | no |
| Interactive HUD (`thoughts`) | yes | yes | no | no | yes |
| System introspection (`detect`, `performance`, `checkpoint`) | yes | yes | no | yes | yes |

---

## DOC: Transport Modes (Slug: transport)

> stdio vs WebSocket — pick the right wire for your client.

# Transport Modes

| Mode | Flag | Protocol | Use Case |
|---|---|---|---|
| **stdio** | *(default)* | JSON-RPC 2.0 / stdio | Claude Desktop, Cursor, VS Code Copilot, Antigravity |
| **WebSocket** | `--ws [--port N]` | JSON-RPC 2.0 / WebSocket | Custom agents, Python/Go backends, remote daemons, n8n |

## stdio (Default)

The MCP client spawns Weavetab as a child process and pipes messages over stdin/stdout. No network port is opened:

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

## WebSocket

```bash
weavetab --ws --port 3000
```

Starts the daemon on `127.0.0.1:3000` (override with `--port <n>` / `--port=<n>`). The daemon binds strictly to loopback for local security — front it with your own TLS/auth layer if exposing across a private network.

---

## DOC: CAPTCHA Solver (Slug: captcha-solver)

> Autonomous zero-API solver for Turnstile, GeeTest, and reCAPTCHA.

# Autonomous Zero-API CAPTCHA Solver

Weavetab features a built-in **Autonomous Zero-API CAPTCHA Solver** via the `browser_captcha` tool. It solves complex challenges locally using real CDP pointer physics, Bézier kinematics, and DOM heuristics — requiring **$0 external solver API costs** and zero third-party subscription keys (no 2Captcha, Anti-Captcha, or CapSolver needed).

```typescript
// Detect and solve active challenge automatically
browser_captcha({ action: "solve", timeout: 60000 })
```

---

## Supported Challenge Matrix

| Challenge Type | Target Systems | Solving Technique | Zero API Cost |
|---|---|---|:---:|
| **Cloudflare Turnstile** | Cloudflare protected surfaces | Sustained mousedown + micro-jitter physics | Yes |
| **GeeTest Slider** | GeeTest v3 / v4 puzzle sliders | Bézier velocity drag + momentum overshoot correction | Yes |
| **Google reCAPTCHA v2** | Checkbox & iframe challenges | Nested cross-origin iframe pointer penetration | Yes |
| **Google reCAPTCHA v3** | Invisible score-based barriers | High-entropy behavioral simulation bursts | Yes |
| **Arkose Labs / FunCAPTCHA** | Interactive verification | Synthetic CDP pointer kinematics + rotation solver | Yes |
| **hCaptcha** | Checkbox challenges | Cross-domain iframe dispatch + heuristic click | Yes |
| **Math / Text Challenges** | Inline security prompts | DOM arithmetic evaluation + synthetic input | Yes |

---

## How It Works

### 1. Cloudflare Turnstile & Interactive Checkboxes
Cloudflare Turnstile evaluates the physical trajectory and hold duration of the click. Weavetab:
- Calculates a randomized human Bézier path from current cursor coordinates to the checkbox center.
- Dispatches CDP `Input.dispatchMouseEvent` with `mousePressed` event.
- Applies **micro-jitter displacement** (1–3 pixel variations) for 120–280 ms simulating organic finger tremor.
- Releases `mouseReleased` event and monitors CDP DOM mutations for success tokens.

### 2. GeeTest & Slider Puzzles
For slider challenges, Weavetab calculates the drag distance, applies variable velocity profiling (rapid acceleration, mid-flight coasting, deceleration), and introduces subtle overshoot correction:

```text
Start (0px) ──[Fast Accel]──► Mid (70%) ──[Decel]──► Target (100%) ──[Overshoot +2px]──► Final Lock
```

### 3. reCAPTCHA v2 & Cross-Origin Iframes
reCAPTCHA isolates the checkbox inside cross-origin iframes (`anchor` frame). Weavetab penetrates the isolated iframe context via CDP `DOM.describeNode` and dispatches synthetic pointer events directly to the inner target.

---

## Tool API Reference: `browser_captcha`

**Parameters:**
| Parameter | Type | Description |
|---|---|---|
| `action` | `"detect" | "solve" | "wait_for_user" | "status"` *(required)* | Operation to perform. |
| `timeout` | `number?` | Maximum timeout in milliseconds (default `120000`). |

### Example Usage

```typescript
// Step 1: Detect if a CAPTCHA exists on page
const detection = await browser_captcha({ action: "detect" });
if (detection.detected) {
  // Step 2: Solve autonomously
  const result = await browser_captcha({ action: "solve", timeout: 45000 });
  console.log("Solved:", result.success);
}
```

---

## DOC: Stealth & Physics (Slug: stealth-physics)

> Ghost Cursor Bézier kinematics, typing jitter, and anti-fingerprinting.

# Stealth & Kinematic Physics

Weavetab is built from the ground up to make AI automation indistinguishable from human input at the browser and DOM event levels.

## 1. Ghost Cursor Bézier Kinematics

Standard automation tools warp cursor coordinates instantaneously (`x: 0` → `x: 500` in 0ms), which triggers modern anti-bot heuristics.

Weavetab's **Ghost Cursor** engine generates dynamic **cubic Bézier curves** with randomized control points for every movement:

```text
P0 (Current Pos) ──────► P1 (Control Pt 1) ──────► P2 (Control Pt 2) ──────► P3 (Target)
```

- **Acceleration Profiling**: Gaussian velocity distribution with natural ramp-up and ramp-down.
- **Micro-Jitter**: Per-frame sub-pixel deviations mimicking human muscle tremor.
- **Overshoot & Correction**: Intentional minor overshoots past the target element followed by corrective micro-adjustments.
- **Visual Overlay**: Real-time canvas overlay rendering the glowing Ghost Cursor path in the browser window.

---

## 2. Human Keystroke Synthesis

The `browser_type` engine dispatches native CDP `Input.dispatchKeyEvent` calls with realistic human timing profiles:

- **Temporal Jitter**: Per-character delays sampled between 35 ms and 95 ms.
- **Burst Profiling**: Common character digraphs (e.g., `th`, `er`, `ing`) are typed faster in bursts.
- **Word Boundary Pauses**: Natural pauses (120–250 ms) after spaces and punctuation marks.
- **Stuck-Input Breaking**: DOM diffing detects if keystrokes are failing to register and breaks out of deadlocks.

---

## 3. Early-Script Fingerprint Spoofing

Weavetab's early-script CDP injection guarantees that the following patches execute **before any page JavaScript runs**:

```typescript
// navigator.webdriver is permanently undefined
Object.defineProperty(navigator, 'webdriver', { get: () => undefined });

// Native plugin and mime-type arrays spoofed
Object.defineProperty(navigator, 'plugins', { get: () => [1, 2, 3, 4, 5] });

// WebGL vendor and renderer noise injection
const getParameter = WebGLRenderingContext.prototype.getParameter;
WebGLRenderingContext.prototype.getParameter = function(parameter) {
  if (parameter === 37445) return 'Google Inc. (Intel)';
  if (parameter === 37446) return 'ANGLE (Intel, Intel(R) UHD Graphics Direct3D11)';
  return getParameter.apply(this, arguments);
};
```

---

## DOC: Commands (Slug: cli-commands)

> Reference for every top-level subcommand.

# Commands

## Server Commands

| Command | Description |
|---|---|
| `weavetab` | Start the MCP server (stdio mode — default for MCP clients). When run in a TTY without arguments, launches the interactive UI menu. |
| `weavetab --ws [--port N]` | Start the WebSocket daemon on `127.0.0.1` (default port `3000`). |
| `weavetab --version` | Print version and exit. |
| `weavetab config` | Launch the 6-phase interactive configuration wizard. |
| `weavetab view` | Display the current active configuration report. Press **[R]** to view raw JSON, **[Q]** to quit. |
| `weavetab reset` | Purge browser profiles, lockfiles, mutexes, session registries, and kill orphan browser processes. Accepts `--yes`/`-y` to skip confirmation prompts. |
| `weavetab reload-ext` | Send a reload signal to the Weavetab browser extension via CDP `Runtime.evaluate`. |
| `weavetab plugin <add\|browse\|search\|list\|remove\|verify>` | Manage plugins — see `weavetab plugin --help`. |
| `weavetab skills [options]` | Install or update AI agent skills (passthrough to `@weavetab/skills`). |
| `weavetab help` / `--help` | Show full CLI help message with all commands, flags, and environment variables. |

## Secrets Management

Credentials are stored in `~/.weavetab/secrets.json` (global) or `.weavetab/secrets.json` (project-scoped). Values are never echoed to the terminal.

| Command | Description |
|---|---|
| `weavetab secrets set <KEY>` | Store a new encrypted secret. Prompts for value (hidden input) and allowed domains (comma-separated). |
| `weavetab secrets list` | List all stored secrets (key names only, values hidden). Shows domains and last-updated timestamps. |
| `weavetab secrets rm <KEY>` | Remove a secret by key name. |
| `weavetab secrets init --project` | Initialize a project-scoped `.weavetab/secrets.json` file. |

## Interactive TTY Menu

When run without arguments in a TTY terminal, Weavetab opens an interactive keyboard-driven menu:

| Key | Action |
|---|---|
| `[C]` | Launch the configuration wizard |
| `[V]` | View current active configuration |
| `[P]` | List installed Weavetab plugins |
| `[R]` | Purge browser profiles and lockfiles |
| `[H]` | Show help information |
| `[G]` / `[N]` / `[W]` | Open GitHub / npm / website links |
| `[Q]` | Exit Weavetab |

---

## DOC: Flags (Slug: cli-flags)

> Global flags accepted by the CLI.

# Flags

Only these flags are parsed by the CLI (`MCP/src/index.ts`). Anything else is ignored.

| Flag | Type | Description |
|---|---|---|
| `--help` / `-h` | boolean | Show help message and exit |
| `help` | command | Show help message and exit |
| `--version` / `-v` | boolean | Print version and exit |
| `--ws` | boolean | Start the WebSocket daemon instead of stdio |
| `--port <port>` / `--port=<port>` | number | Port for the WebSocket daemon (default `3000`) |
| `--yes` / `-y` | boolean | Skip confirmation prompt when running `weavetab reset` / `reload` |
| `--official` / `-O` | boolean | Prefer the official `@weavetab/plugin-<name>` candidate (`plugin add`) |
| `--community` / `-C` | boolean | Prefer the community package candidate (`plugin add`) |
| `--refresh` | boolean | Invalidate and refresh the verified plugin cache (`plugin`) |
| `--project` | boolean | Project-scoped secrets file (`secrets init --project`) |

Notes:
- There are no `--headless` / `--role` CLI flags. Browser headless mode and RBAC role come from `~/.weavetab/config.json` (`weavetab config` / `weavetab view`). The wizard offers `admin` / `operator` / `viewer` / `automation`.

---

## DOC: Introduction (Slug: cli-introduction)

> Drive Weavetab from the command line — no client required.

# CLI Reference

The `weavetab` binary provides server management, secrets handling, diagnostics, and interactive terminal menus.

```bash
weavetab          # Start the MCP server (stdio mode)
weavetab config   # Interactive configuration wizard
weavetab view     # Inspect active configuration
weavetab reset    # Purge profiles, lockfiles, and stale sessions
weavetab help     # Command index
```

---

## DOC: Scripting & CI/CD (Slug: cli-scripting)

> Chain CLI calls in shell scripts and CI.

# Scripting & CI/CD

## Shell Scripting

```bash
# Reset before a fresh test run
weavetab reset --yes

# List stored secrets
weavetab secrets list

# List installed plugins
weavetab plugin list

# Start the MCP server in WebSocket daemon mode for custom scripts
weavetab --ws --port 3000 &
```

## CI/CD Pipeline

```bash
# In GitHub Actions or Docker CI
npm install -g @weavetab/mcp
weavetab reset --yes
weavetab --ws --port 3000 &
```

---

## DOC: Antigravity IDE (Slug: ide-antigravity)

> Configure Weavetab for Google Antigravity IDE.

# Antigravity IDE Integration

Add to `~/.antigravity/mcp.json` or workspace `mcp.json`:

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

---

## DOC: Claude Code (Slug: ide-claude-code)

> Configure Weavetab for Claude Code CLI agent.

# Claude Code Integration

Add to project `.claude/settings.json` or global configuration:

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

Or add directly via Claude Code CLI:

```bash
claude mcp add weavetab -- npx -y @weavetab/mcp
```

---

## DOC: Claude Desktop (Slug: ide-claude-desktop)

> Configure Weavetab as an MCP server for Claude Desktop.

# Claude Desktop Integration

## Config File Location

| OS | Path |
|---|---|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |

## Configuration

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

---

## DOC: Cursor (Slug: ide-cursor)

> Configure Weavetab as an MCP server for Cursor IDE.

# Cursor Integration

## Config File Location

| Scope | Path |
|---|---|
| **Global** | `~/.cursor/mcp_config.json` |
| **Project** | `.cursor/mcp.json` (in project root) |

## Configuration

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

---

## DOC: Generic / WebSocket (Slug: ide-generic)

> Connect any MCP-compatible client via WebSocket or stdio.

# Generic Client Integration

Any client speaking MCP JSON-RPC 2.0 can connect to Weavetab.

## stdio Transport (Default)

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

## WebSocket Transport

```bash
weavetab --ws --port 3000
```

Connect your client over WebSocket to `ws://127.0.0.1:3000`.

---

## DOC: OpenCode (Slug: ide-opencode)

> Configure Weavetab for OpenCode CLI agent.

# OpenCode Integration

Add to `.opencode/config.json` or `opencode.json`:

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

---

## DOC: VS Code + Copilot (Slug: ide-vscode-copilot)

> Configure Weavetab for VS Code with GitHub Copilot.

# VS Code + GitHub Copilot Integration

Create `.vscode/mcp.json` in your workspace root:

```json
{
  "servers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

---

## DOC: Windsurf (Slug: ide-windsurf)

> Configure Weavetab as an MCP server for Windsurf IDE.

# Windsurf Integration

Add to `~/.windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

---

## DOC: Locations & Merge (Slug: config-locations)

> Two-tier merge: global config → built-in defaults.

# Config Locations & Merge Priority

## Priority Tiers

1. **Global** — `~/.weavetab/config.json` (the only config file Weavetab reads)
2. **Built-in defaults** — defined in `DEFAULT_CONFIG`

## Live Reload

A debounced file watcher (150 ms) reloads the in-memory configuration on change. In-flight tool executions complete on the existing configuration; subsequent calls automatically pick up the new values.

## Corrupt File Quarantine

If a configuration file contains invalid JSON, Weavetab automatically quarantines the file to `config.broken.<timestamp>.json` and safely falls back to the next tier without crashing.

---

## DOC: Schema (Slug: configuration)

> Every field on the runtime config object.

# Configuration Schema

The full `Config` interface lives in `src/config/loader.ts`.

```typescript
export type DevModeConfig  = boolean;
export type PolicyMode     = "allow" | "deny" | "audit-only" | "read-only";
export type Role           = "admin" | "operator" | "viewer" | "automation" | "system";
export type BrowserEngine  = "chromium" | "firefox" | "webkit";

export interface PolicyEntry {
  pattern: string;
  mode: PolicyMode;
}

export interface ElectronAppConfig {
  path?: string;               // Absolute path to Electron app executable
  port?: number;               // Remote debugging port (default 9222)
  url?: string;                // Initial launch URL / deep-link
  args?: string[];             // Custom CLI arguments
  profileDir?: string;         // Dedicated isolated user profile directory
}

export interface Config {
  // Identity & Transport
  mode: "session" | "attach";
  session: string;
  attachPort: number;           // 0-65535, 0 = dynamic
  agentId: string;              // Auto-generated UUID (WT_AGENT_ID to override)
  telemetry: boolean;

  // Browser Settings
  browserPath: string;          // Executable path or "auto"
  browserType: BrowserEngine;
  headless: boolean;
  extension: boolean;           // Enable Weavetab Chrome extension
  browserFlags: string[];
  profileDir: string;
  cookies: boolean;
  syncDataAcrossBrowsers: boolean;

  // Desktop & Electron Applications
  apps?: Record<string, ElectronAppConfig>;
  electron?: Record<string, ElectronAppConfig>;

  // Security & Policy
  role: Role;                   // RBAC role
  block: string[];              // Domain blocklist (default: ["*.bank.*", "paypal.com"])
  allow: string[];              // Domain allowlist
  policies: PolicyEntry[];      // Per-domain policy modes
  proxy?: string;               // Outbound proxy URL (WT_PROXY_URL to override)

  // Rate Limiting & Resource Caps
  sessionTimeout: number;       // Seconds, 60-86400 (default 3600)
  navigationTimeout: number;    // Milliseconds, 1000-120000 (default 30000)
  idleTimeout: number;          // Milliseconds, >= 5000 (default 60000)
  actionabilityTimeoutMs: number; // Milliseconds, 50-15000 (default 300)
  maxTabs: number;              // 1-100 (default 10)
  maxActionsPerMinute: number;  // 1-600 (default 60)
  githubCacheTtlMs: number;     // Milliseconds (default 1800000)
  refCacheTtlMs: number;        // Milliseconds (default 30000)

  // Output Directories
  downloadDir: string;
  pdfDir: string;
  snapshotDir: string;
  recordingDir: string;
  designDir: string;

  // UI & Overlay
  devMode: DevModeConfig;
}
```

The on-disk `config.json` may also use the legacy sectioned shape (`general`, `browser`,
`security`, `performance`); the loader migrates it to this flat interface automatically.

---

## DOC: Environment Variables (Slug: env-variables)

> Runtime environment variables that override config.

# Environment Variables

Only these two are read at runtime (`MCP/src/config/loader.ts`). Everything else
(browser path, role, headless, dev mode) lives in `~/.weavetab/config.json`
— run `weavetab config` to change it.

| Variable | Description |
|---|---|
| `WT_AGENT_ID` | Override the auto-generated agent UUID |
| `WT_PROXY_URL` | Set outbound HTTP/SOCKS proxy server URL |

---

## DOC: Folder Hierarchy (Slug: folders)

> .weavetab and .weavetab-system directory structure.

# Workspace & System Directories

Weavetab strictly partitions project-scoped credentials, global user configuration, and machine-managed system intelligence into dedicated directory structures.

## 1. Project-Scoped Directory: `./.weavetab/`

Optional, created in your current working directory to carry project-scoped credentials alongside a checkout:

```
./.weavetab/
└── secrets.json         # Project-scoped credentials for Blind Injection (override the global file)
```

Keys in a project `secrets.json` take precedence over `~/.weavetab/secrets.json` when Weavetab runs from that directory. All other configuration and output paths are global (see below) unless overridden via config fields.

## 2. Global User Directory: `~/.weavetab/`

Global, user-authored configuration and default output directories:

```
~/.weavetab/
├── config.json          # Global configuration (domain policies, roles, output paths)
├── secrets.json         # Global secrets for Blind Injection
├── knowledge/           # Domain-specific markdown knowledge hints
├── plugins/             # Isolated storage directories for installed plugins
├── downloads/           # Downloaded files (default output dir)
├── pdfs/                # Exported PDF documents
├── snapshots/           # Screenshots and MHTML snapshots
├── recordings/          # Screen recordings (webp / gif / webm / mp4)
└── designs/             # Extracted design tokens and Tailwind themes
```

Each output directory (`downloads`, `pdfs`, `snapshots`, `recordings`, `designs`) is overridable via its matching config path field.

## 3. System Intelligence Directory: `~/.weavetab-system/`

Machine-managed, cross-session state. Strictly separate from user configuration:

```
~/.weavetab-system/
├── memory/                    # Per-domain selector confidence cache
│   └── sites/                 # Persistent site profiles: workflows, quirks & reliability scores
├── sessions/
│   └── context.json           # Rolling action trail for loop detection
├── checkpoints/               # Named browser-state checkpoints
├── missions/                  # Mission state files
├── apps/                      # Dedicated isolated profiles for Electron apps
├── extension/                 # Installed browser extension build
├── logs/                      # Mission logs: mission_<timestamp>.log / .jsonl (devMode only)
├── locks/                     # Process lockfiles (PID + TCP port validation)
├── secrets-key                # Local key used to encrypt stored secrets
└── session-profile*/          # Isolated Chromium browser profiles (never your real profile)
```

---

## DOC: Desktop & Electron Apps (Slug: electron-apps)

> Native CDP automation for VS Code, Discord, Figma, Slack, and any Electron app.

# Desktop & Electron Application Automation

Weavetab is a **universal browser and desktop agent runtime**. In addition to standard Chromium web browsing, Weavetab gives AI agents direct, native CDP control over **any desktop Electron application** — including Discord, VS Code, Figma, Slack, Obsidian, Postman, Notion, Spotify, and custom internal tools.

## How It Works

Because modern desktop applications are built on the Chromium/Electron framework, Weavetab can communicate with them directly over CDP WebSocket without requiring separate drivers or UI automation bridges.

```text
AI Agent (MCP) ──► withSecurity()
                     ├── (Default) ─────────► CDP:9222 ──► Google Chrome / Chromium
                     ├── (app: "discord") ──► CDP:9223 ──► Discord Desktop
                     ├── (app: "figma")   ──► CDP:9224 ──► Figma Desktop
                     └── (app: "vscode")  ──► CDP:9225 ──► VS Code Desktop
```

### Dual-Port Concurrency & Multi-Target Sessions
- **Concurrent Execution**: Web browser sessions and Electron desktop app sessions run side-by-side on independent CDP ports (e.g. port `9222` for Chrome, `9223` for Discord, `9224` for Figma).
- **Zero Session Clobbering**: Switching between a browser tab and a desktop app does not close, disconnect, or reload either target.
- **Unified Tool Interface**: Pass `"app": "<appName>"` to any Weavetab tool to target that desktop application. Omit `app` to target the active web browser.

---

## Interactive App Configurator

Build your `electron` block in the [Desktop app configurator](/mcp/desktop) — presets for Discord, VS Code, Figma, Slack and more, path / port / advanced formats, plus a copy-ready agent setup prompt. Then paste the block into your global `~/.weavetab/config.json`.

---

## 1. Configuring Desktop Apps in `config.json`

Add an `"electron"` object to your global `~/.weavetab/config.json` (the only config file Weavetab reads):

```json
{
  "electron": {
    "discord": "C:\\Users\\username\\AppData\\Local\\Discord\\app-<version>\\Discord.exe",
    "vscode": 9222,
    "figma": {
      "path": "C:\\Users\\username\\AppData\\Local\\Figma\\Figma.exe",
      "port": 9224,
      "url": "https://www.figma.com",
      "args": ["--enable-features=WebRTCPipeWireCapturer"]
    },
    "slack": "/Applications/Slack.app/Contents/MacOS/Slack",
    "obsidian": "/usr/bin/obsidian"
  }
}
```

### Configuration Formats Supported

| Format | Example | Description |
|---|---|---|
| **Executable Path String** | `"discord": "C:\\path\\to\\Discord.exe"` | Automatically launches the binary on an isolated port and dedicated profile. |
| **Port Number** | `"vscode": 9222` | Attaches directly to an already-running instance started with `--remote-debugging-port=9222`. |
| **Full Configuration Object** | `"figma": { "path": "...", "port": 9224, "url": "..." }` | Custom control over binary path, debug port, initial launch URL, custom profile directory, and startup CLI args. |

---

## 2. Security & Profile Isolation

Weavetab enforces enterprise-grade sandbox separation for all desktop applications:

1. **Dedicated User Profiles**: Automated sessions are assigned isolated data profiles under `~/.weavetab-system/apps/<appName>/`.
2. **Real AppData Protection**: Weavetab strictly enforces `assertNotRealElectronProfile` — attempting to target your primary OS user data directories (`%APPDATA%`, `~/Library/Application Support`, or `~/.config`) is blocked to protect your personal logins and local databases from accidental automation corruption.
3. **Lock & Mutex Isolation**: Dedicated lockfiles (`~/.weavetab-system/locks/<appName>.lock`) ensure concurrent agent operations never conflict.

---

## 3. Supported Desktop Schemes & Protocols

Weavetab automatically allows and whitelist-bypasses desktop internal protocols:
- `app://` (Electron internal resources)
- `vscode-webview://` / `vscode-file://` (VS Code extensions and webviews)
- `discord://` / `slack://` (Deep-links)
- `devtools://` / `chrome://` / `about:`
- `file:///` (Local files)

---

## 4. How Agents Interact with Desktop Apps

To target an Electron application, simply pass the `app` argument to any Weavetab tool:

### A. Inspect Desktop DOM Tree
```json
{
  "name": "browser_map",
  "arguments": {
    "app": "discord",
    "scope": "main_content"
  }
}
```

### B. Click & Type in Desktop Apps
```json
{
  "name": "browser_click",
  "arguments": {
    "ref": "w:42",
    "app": "discord"
  }
}
```

```json
{
  "name": "browser_type",
  "arguments": {
    "ref": "w:45",
    "text": "Automated build passed successfully! 🚀",
    "app": "discord"
  }
}
```

### C. Multi-Target Burst Orchestration
```json
{
  "name": "browser_burst",
  "arguments": {
    "app": "vscode",
    "steps": [
      { "tool": "click_and_wait", "selector": ".monaco-editor" },
      { "tool": "type_and_send", "text": "npm test" }
    ]
  }
}
```

---

## 5. Launching Existing Desktop Apps in Debug Mode

If you prefer to attach Weavetab to your existing desktop app instance:

```bash
# Launch VS Code with CDP debugging enabled
code --remote-debugging-port=9222

# Launch Obsidian with CDP debugging enabled
obsidian --remote-debugging-port=9225

# Launch Discord with CDP debugging enabled
discord --remote-debugging-port=9223
```
Then in your `config.json`, simply map `"vscode": 9222` or `"obsidian": 9225`.

---

## 6. Environment Discovery Handshake (`browser_detect`)

`browser_detect` is the foundational tool agents invoke upon initial engagement. It inspects local browsers and configured desktop applications, returning their real-time state:

```json
{
  "available": [
    { "engine": "chromium", "name": "Google Chrome", "path": "C:\\Program Files\\...\\chrome.exe" }
  ],
  "current": "chromium",
  "configuredApps": [
    {
      "name": "discord",
      "status": "running_no_debug",
      "configuredPath": "%LOCALAPPDATA%\\Discord\\app-<version>\\Discord.exe"
    },
    {
      "name": "slack",
      "status": "connected",
      "port": 9222,
      "configuredPath": "%LOCALAPPDATA%\\slack\\app-<version>\\slack.exe",
      "activeTabs": [
        { "id": "PAGE_1", "title": "general - Slack", "url": "https://app.slack.com/client/..." }
      ]
    },
    {
      "name": "vscode",
      "status": "offline",
      "configuredPath": "%LOCALAPPDATA%\\Programs\\Microsoft VS Code\\Code.exe"
    }
  ]
}
```

### Application Lifecycle States:
- **`connected`**: The app is running with CDP remote debugging active and Weavetab is attached. Agents can immediately operate tabs/windows using `"app": "<name>"`.
- **`running_no_debug`**: The app process is currently running on the OS, but was opened by the user without `--remote-debugging-port`. Weavetab alerts the agent that DOM interactions are blocked until the app is launched or restarted with debugging flags.
- **`offline`**: The process is not running. Calling `browser_navigate(app: "<name>")` launches and connects the app automatically.

### Windows Squirrel Auto-Path Resolution:
On Windows, applications like Discord and Slack install inside versioned folders (e.g. `Discord\app-1.0.9256\Discord.exe`) that change on every background update. Weavetab dynamically resolves the newest `app-1.0.xxxx` version at launch time, eliminating broken path errors after silent background updates.

---

## 7. Smart Domain Routing & Sticky Context

To ensure external AI agents do not accidentally trigger a web browser launch when intending to control an Electron application:

1. **Automatic Domain Routing**: When `browser_navigate` or `browser_tabs(action: "open")` receives an app domain (e.g. `discord.com`, `slack.com`, `linear.app`, `notion.so`), Weavetab automatically routes the target to the configured desktop application.
2. **Sticky App Sessions**: When an agent operates inside an Electron app, the target session context remains sticky. Subsequent DOM calls stick to that active desktop app without spawning an unwanted Chrome window. The sticky Electron app is only used while **no web-browser session is active**; once a web-browser session is running, a plain `browser_tabs(action: "open")` (no `app`) targets the browser.
3. **Explicit Browser Targeting**: When the agent specifically intends to use the web browser, passing `"app": "browser"` overrides desktop routing and directs operations to the web browser.

---

## 8. Opening Tabs Inside Electron Apps

Electron apps do **not** implement the CDP `Target.createTarget` command, so a brand-new tab or window cannot be created inside a desktop app from the outside. `browser_tabs(action: "open")` therefore:

- **Reuses** the existing tab/window when the requested URL is already loaded (focuses it) — the default `reuse: true` behavior.
- **Fails fast with an actionable error** when a genuinely new tab is required in an Electron app, e.g. `[!] Electron app "slack" does not support opening new tabs or windows via CDP ... Use browser_navigate with { app: "slack", url: "..." } ...` — instead of surfacing a raw `Not supported` CDP message.

To load a URL inside an Electron app, navigate its existing window with `browser_navigate({ app: "<name>", url: "..." })`.

---

## DOC: Docker & Production (Slug: docker)

> Run Weavetab in Docker with headless Chromium.

# Docker & Production Deployment

Run the Weavetab MCP server headlessly inside Docker:

```dockerfile
FROM node:20-slim

# Install Chromium dependencies
RUN apt-get update && apt-get install -y \
    chromium \
    --no-install-recommends && rm -rf /var/lib/apt/lists/*

# Install Weavetab MCP globally
RUN npm install -g @weavetab/mcp@latest

# Chromium is auto-detected at /usr/bin/chromium (browserPath: "auto").
# To pin a custom binary, mount a config.json with browserPath set.

# stdio transport: no ports are opened, no EXPOSE needed.
# The MCP client spawns `weavetab` and speaks JSON-RPC over stdin/stdout.
CMD ["weavetab"]
```

```bash
docker build -t weavetab-server .
docker run -v ~/.weavetab:/root/.weavetab weavetab-server
```

---

## DOC: Installation (Slug: installation)

> Install Weavetab globally or run it ad-hoc with npx.

# Installation

```bash
# Global installation (recommended)
npm install -g @weavetab/mcp@latest

# Or run directly without installation
npx -y @weavetab/mcp@latest

# Install Developer SDK as dev dependency in a project
npm install -D @weavetab/sdk@latest

# Verify installation
weavetab --version
# → @weavetab/mcp 2.6.0
```

## System Requirements

- **Node.js** >= 18.0.0 (Node 20 or 22 LTS recommended)
- **Chromium-based browser** (Google Chrome, Microsoft Edge, Brave, or Chromium)
- *Optional:* Firefox or Safari Technology Preview via `browserType` config
- *Optional for Desktop Automation:* Any Electron application (Discord, VS Code, Figma, Obsidian, Postman, etc.)

## CLI Binary Aliases

```bash
weavetab          # standard binary
Weavetab          # case-insensitive alias
```

## What Gets Configured

Weavetab ships as a single, self-contained Node package. On first run it:

1. Auto-detects an installed Chromium binary on `$PATH`
2. Creates `~/.weavetab/` for global configuration, secrets, and policy rules
3. Registers a local MCP entry point that clients launch over stdio or WebSocket

---

## DOC: Introduction (Slug: introduction)

> What Weavetab is, direct CDP architecture, and design tenets.

# Introduction

Weavetab is a production-grade, local **Model Context Protocol (MCP) server** that grants AI agents human-like control over Chromium browsers and native **Electron desktop applications** (VS Code, Discord, Slack, Figma, Obsidian, Postman, Antigravity IDE, etc.) — communicating directly over the **Chrome DevTools Protocol (CDP)**.

No WebDriver. No browser binary downloads. No Playwright or Puppeteer abstraction layer. No cloud dependency. Tool invocations execute directly over local CDP sockets.

## Synchronized Ecosystem Releases

Both **`@weavetab/mcp`** and the **`@weavetab/sdk`** share synchronized release lines. Every capability introduced in the core runtime is immediately available in the developer SDK with 100% type safety and zero version mismatch.

```bash
# Install core Weavetab MCP server globally
npm install -g @weavetab/mcp@latest

# Or run directly via npx
npx -y @weavetab/mcp@latest

# Install Weavetab Developer SDK as a dev dependency
npm install -D @weavetab/sdk@latest
```

## Design Tenets

| Tenet | Implementation |
|---|---|
| **Direct Execution** | In-process tool execution via direct CDP WebSocket connections |
| **Universal Control** | Native orchestration across Chromium web tabs and any Electron desktop app |
| **Autonomous CAPTCHA** | Zero-API solving (Cloudflare Turnstile, GeeTest, reCAPTCHA) via human Bézier mouse physics |
| **Security & RBAC** | 5-tier RBAC + domain policies + Blind Credential Injection + profile isolation |
| **Token Efficiency** | Semantic Delta diffing (up to 97% reduction) + intelligent DOM pruning |
| **Stealth & Physics** | Ghost Cursor (Bézier curves), human typing jitter, and CDP early-script fingerprint spoofing |
| **Self-Learning** | Per-domain session memory, framework detection, and automated loop recovery |
| **Zero Cloud** | Pure local computation. No external telemetry or cloud tracking unless explicitly opted in |

## What You Get

- **41 built-in MCP tools** covering DOM vision, input synthesis, desktop apps, tabs, network interception, office files, design extraction, and plugin lifecycle
- **Universal Desktop App Runtime** — control Chrome and native Electron apps (Discord, Figma, VS Code) side-by-side without port conflicts
- **Autonomous Zero-API CAPTCHA Solver** — solve Cloudflare Turnstile, GeeTest, and reCAPTCHA locally via CDP mouse physics with $0 API costs
- **Two transport modes** — stdio (Claude Desktop, Cursor, VS Code, Windsurf, Antigravity) and WebSocket (`weavetab --ws --port 3000`)
- **Five RBAC roles** — `admin`, `operator`, `viewer`, `automation`, and `system`
- **Per-domain policies** — ring-fences sensitive banking, internal, and production surfaces
- **Blind Injection** — credentials resolved server-side from `secrets.json` and never exposed to the LLM
- **Extensible Plugin System** — auto-discovers and mounts custom MCP tools from `node_modules`

## Next Steps

- **[Quickstart](quickstart.md)** — install and run a first mission in 60 seconds
- **[Desktop & Electron Apps](../desktop-automation/electron-apps.md)** — configure and control desktop apps
- **[Autonomous CAPTCHA Solver](../captcha-stealth/captcha-solver.md)** — zero-API anti-bot solving
- **[MCP Tools Reference](../tools/tools.md)** — full reference for all 41 built-in automation tools

---

## DOC: Quickstart (Slug: quickstart)

> Install, configure, and run a first mission in under a minute.

# Quickstart

Get Weavetab attached to your agent and running a real browser mission in three simple steps.

## 1. Install Weavetab

```bash
# Global installation (recommended)
npm install -g @weavetab/mcp@latest

# Or run directly with npx
npx -y @weavetab/mcp@latest
```

## 2. Wire to your MCP Client

Point any MCP-compatible client (Claude Desktop, Cursor, Windsurf, VS Code, Antigravity) at the server:

```json
{
  "mcpServers": {
    "weavetab": {
      "command": "npx",
      "args": [
        "-y",
        "@weavetab/mcp"
      ]
    }
  }
}
```

## 3. Run a First Mission

Use `browser_burst` to chain multiple actions in a single round-trip:

```json
{
  "name": "browser_burst",
  "arguments": {
    "steps": [
      { "tool": "navigate_and_read", "url": "https://example.com" },
      { "tool": "click_and_wait", "selector": "#login-btn" }
    ]
  }
}
```

You will see the browser launch, the Ghost Cursor glide across the page along human Bézier curves, and the agent complete the task via direct CDP execution.

---

## DOC: Setup Wizard (Slug: setup-wizard)

> Interactive wizard that writes a clean config.json.

# Setup Wizard

Run the interactive CLI configuration wizard:

```bash
weavetab config
```

The wizard walks through every option across 6 interactive phases. Re-run it at any time to update your saved config.

## Wizard Phases

1. **Phase 1 — Essentials:** Browser path, RBAC role (`admin`, `operator`, `viewer`, `automation`), headless mode, dev mode, max tabs, actionability timeout, domain block/allow lists.
2. **Phase 2 — Advanced (optional):** Browser engine selection, timeouts and rate limits, telemetry opt-in, download/proxy directories, domain policy entries.
3. **Phase 3 — Save Location:** Global (`~/.weavetab/config.json`).
4. **Phase 4 — MCP Auto-Config:** Auto-detects installed IDEs (Claude Desktop, Cursor, Windsurf) and merges Weavetab into their MCP configuration.
5. **Phase 5 — Agent Skills:** Optionally installs `@weavetab/skills` for your agent framework.
6. **Phase 6 — Summary:** Displays full configuration validation report.

---

## DOC: Site Profiles and Intelligent Memory (Slug: site-profiles)

> Persistent cross-session workflow memory, pattern compilation, and quirk bypass in ~/.weavetab-system/memory/sites/.

# Site Profiles and Intelligent Memory Engine

Every browser automation session normally starts from zero context. The agent re-inspects DOM trees, re-triggers cookie banners, and re-discovers login fields.

Weavetab solves this with a **Two-Tier Persistent Memory System** that accumulates knowledge about domains and workflows across sessions.

---

## Directory Hierarchy: System vs. User Space

| Directory | Purpose | Managed By |
| :--- | :--- | :--- |
| `~/.weavetab-system/memory/sites/` | **Persistent Site Profiles**: named workflow patterns, quirks, reliability scores | Weavetab Engine (autonomous) |
| `~/.weavetab-system/memory/` | **Selector Confidence Cache**: per-domain element selectors and strike counters | Weavetab Engine (autonomous) |
| `~/.weavetab-system/sessions/` | **Rolling Action Trails**: 50-step window for loop detection | Weavetab Engine (autonomous) |
| `~/.weavetab/` | **User Configuration**: `config.json`, `secrets.json`, `knowledge/`, plugins | User / Developer (manual) |

> **Directory Law**: Machine-compiled memory profiles are strictly located in `~/.weavetab-system/memory/sites/`. User configuration in `~/.weavetab/` is never polluted by machine learning trails or dynamic decay counters.

---

## Site Profile Schema

Profiles are stored as `<sanitized-hostname>.json` under `~/.weavetab-system/memory/sites/`:

```json
{
  "origin": "https://github.com",
  "framework": "react",
  "shadowDom": false,
  "captcha_frequency": "rare",
  "quirks": {
    "cookie_banner": {
      "selector": "#cookie-consent",
      "action": "click .accept-all",
      "appears": "first_visit"
    },
    "rate_limit": {
      "threshold": "60req/min",
      "recovery": "wait 30s"
    }
  },
  "patterns": {
    "login_flow": {
      "name": "login_flow",
      "steps": [
        { "tool": "browser_navigate", "target": "https://github.com/login" },
        { "tool": "browser_fill", "target": "#login_field", "value": "{{username}}" },
        { "tool": "browser_fill", "target": "#password", "value": "{{password}}" },
        { "tool": "browser_click", "target": "[type=submit]" }
      ],
      "success_indicator": "a[aria-label='Homepage']",
      "entry": "/login",
      "avg_duration_ms": 3200,
      "reliability": 0.96,
      "strikes": 0,
      "last_verified": "2026-09-16T08:00:00.000Z",
      "total_executions": 12,
      "successful_executions": 12
    }
  },
  "visitCount": 15,
  "updatedAt": "2026-09-16T08:00:00.000Z"
}
```

---

## The Pattern Compiler

When an agent executes an automation flow:
1. **Trail Capture**: Steps are tracked via the lightweight action trail.
2. **Selector Stabilization**: Volatile CSS hash classes (`[class*="hash-"]`), positional pseudos (`:nth-child`), and deep anonymous structural chains are filtered out. Only semantic selectors (`id`, `data-testid`, semantic attributes, roles) are persisted.
3. **Merge-on-Write**: Calling `browser_pattern_learn` updates existing patterns in place. Duplicate calls never create duplicate files or duplicate entries.
4. **Anti-Spam Guard**: If an incoming pattern is identical to stored disk state, the disk write is skipped entirely.

---

## Reliability Scoring and 3-Strike Degradation

Each pattern tracks a reliability score (`0.0` to `1.0`) computed via Exponentially Weighted Moving Average (EWMA with $\alpha = 0.15$):

$$\text{Reliability}_{t} = 0.85 \times \text{Reliability}_{t-1} + 0.15 \times (\text{Success} ? 1 : 0)$$

### Decision Thresholds

- **Fast-Path ($\ge 0.80$)**: Replay stored steps directly via `browser_burst` — skips exploratory DOM navigation entirely.
- **Cautious Replay ($0.50 - 0.79$)**: Replay steps, but verify `success_indicator` after critical steps.
- **Re-Learn ($< 0.50$ or $\ge 3$ consecutive strikes)**: Pattern is flagged `[RE-LEARN NEEDED]`. The agent falls back to fresh DOM exploration, then calls `browser_pattern_learn` to teach the updated steps.

---

## MCP Tools

### `browser_pattern_learn`
All site memory operations use a single tool. Use `action: "get"` to read a site profile, `action: "learn"` to register a workflow, `action: "record_execution"` to update reliability scores, and `action: "record_quirk"` to store site quirks:

```json
{ "tool": "get", "origin": "https://github.com" }
```

```json
{
  "origin": "https://github.com",
  "action": "learn",
  "name": "login_flow",
  "steps": [
    { "tool": "browser_click", "target": ".btn-login" },
    { "tool": "browser_fill", "target": "#login_field", "value": "{{username}}" }
  ],
  "success_indicator": "a[aria-label='Homepage']"
}
```

---

## SDK Plugin Integration (`ctx.memory`)

Plugin authors can interact with persistent site memory directly via the SDK:

```typescript
import { definePlugin } from "@weavetab/sdk";

export default definePlugin({
  name: "custom-site-automator",
  async onLoad(ctx) {
    // Read current profile
    const profile = await ctx.memory?.getSiteProfile("https://github.com");

    // Check reliability
    const reliability = await ctx.memory?.getReliability("https://github.com", "login_flow");
    if (reliability && reliability >= 0.8) {
      ctx.logger.info("Fast-path ready for login_flow");
    }

    // Teach a new pattern
    await ctx.memory?.learnPattern("https://github.com", "quick_search", {
      steps: [{ tool: "browser_fill", target: "input.header-search-input", value: "test" }]
    });
  }
});
```

---

## DOC: Skills Ecosystem (Slug: skills-overview)

> Drop-in agent skills and recipes from @weavetab/skills.

# Weavetab Skills Ecosystem

The **`@weavetab/skills`** package provides drop-in operational directives and behavior skills for AI agents (Claude, Cursor, Windsurf, Copilot, Antigravity).

## Interactive Skills Installer

```bash
npx -y @weavetab/skills@latest
```

The interactive installer detects your IDE (`.agents`, `.cursorrules`, `.clinerules`, `.roocode`, etc.) and injects selected skills directly without workspace clutter.

---

## Available Skills Directory

- **CAPTCHA Evasion** (`general/captcha-evasion.md`) — Heuristics for resolving bot challenges and checkbox modals.
- **Context Awareness** (`general/context-awareness.md`) — Deep page analysis and landmark scoping.
- **Cookie Consent Banners** (`general/cookie-consent.md`) — Auto-dismissing GDPR and overlay modals.
- **Data Extraction** (`general/data-extraction.md`) — CSS & XPath tabular scraping.
- **Dynamic Interaction** (`general/dynamic-interaction.md`) — Precision hover, drag-and-drop, and flyout menus.
- **Error Recovery** (`general/error-recovery.md`) — Resolving 404s, stale elements, and network timeouts.
- **File Upload** (`general/file-upload.md`) — Direct CDP file attachments.
- **Form Filling** (`general/form-filling.md`) — Multi-field smart form batch completion.
- **Infinite Scroll** (`general/infinite-scroll.md`) — Pagination and dynamic lazy loading.
- **SPA Navigation** (`general/spa-navigation.md`) — Client-side route changes in React/Vue/Angular.

---

## DOC: Automation Recipes (Slug: skills-recipes)

> Step-by-step recipes for common browser automation challenges.

# Automation Skills Recipes

## Recipe 1: Handling Dynamic Cookie Consent Overlays

```markdown
1. Run browser_find({ query: "Accept all cookies" })
2. If found, call browser_click({ label: "Accept all" })
3. Wait for stability: browser_wait({ for: "stable", timeout: 2000 })
4. Read page with delta: browser_map({ delta: true, prune: true })
```

---

## Recipe 2: Autonomous Form Completion

```markdown
1. Map the form: browser_map({ scope: "form", query: "input" })
2. Batch fill fields in one round-trip:
   browser_fill({
     fields: [
       { ref: "w:12", value: "alex@company.com" },
       { ref: "w:14", value: "United States" }
     ],
     submit: "w:16"
   })
3. Wait for submission: browser_wait({ for: "network" })
```

---

## DOC: Browser Issues (Slug: trouble-browser)

> CDP connection failures, crashes, and extension problems.

# Browser Connection Issues

## "CDP connection failed" Error

**Causes:**
- Port 9222 is occupied by another process
- Chrome was launched without `--remote-debugging-port`

**Fixes:**
1. Run `weavetab reset --yes` to terminate orphaned browser processes
2. Verify port availability: `netstat -an | grep 9222`
3. Restart Weavetab

## Browser Crashes on Launch

**Fixes:**
1. Run `weavetab reset` to purge corrupted profiles
2. Run `weavetab config` and set the browser executable path (or `browserPath: "auto"` to detect)

---

## DOC: Config Errors (Slug: trouble-config)

> Configuration validation, secrets, and policy issues.

# Configuration Issues

## Secrets Not Injecting

1. Check that `~/.weavetab/secrets.json` or `./.weavetab/secrets.json` exists
2. Verify the secret key name matches exactly (case-sensitive)
3. Run `weavetab secrets list` to confirm keys are registered

## Configuration Quarantined

If a config file has syntax errors, Weavetab quarantines it to `config.broken.<timestamp>.json` and falls back to defaults. Run `weavetab config` to regenerate a valid file.

---

## DOC: Loop Detection (Slug: trouble-loop)

> When the agent gets stuck in an action loop.

# Loop Detection Diagnostics

## Symptoms

A tool call returns `stuck_warning: true` or `STUCK_LOOP_WARNING`.

## Cause

Weavetab tracks a rolling 50-action window in `~/.weavetab-system/sessions/context.json`. If repeated identical actions fail to produce DOM state changes, strikes are accumulated:

| Strikes | Severity | System Behavior |
|---|---|---|
| < 5 | Normal | Standard execution |
| 5–9 | Warning | Warning hint injected into agent context |
| 10+ | Critical | Agent marked as `stuck`; recovery strategy triggered |

## Resolution

1. Call `browser_map({ force: true })` or `browser_wait({ reset_loop: true })` to clear strikes
2. Call `browser_map({ delta: true })` to verify if DOM elements actually changed
3. Call `browser_inspect` to check if target element is hidden or occluded by modals
4. Use `browser_wait({ for: "stable" })` before triggering inputs

---

## DOC: Contributing Guide (Slug: contributing)

> Code standards, pull request workflow, and security disclosures.

# Contributing to Weavetab

We welcome contributions from the community!

## Contribution Workflow

1. Fork the repository on GitHub
2. Create a feature branch: `git checkout -b feature/my-enhancement`
3. Commit your changes: `git commit -m "feat: add support for new feature"`
4. Run tests: `npm test`
5. Open a Pull Request on GitHub

## Code Guidelines

- All tools must adhere to strict Zod runtime argument validation.
- Plugin manifests (`weavetab.json`) must explicitly declare required runtime permissions.
- Maintain zero-cloud computation: no remote data transmissions without explicit opt-in.

---

## DOC: Build Scripts (Slug: dev-build)

> Build, dev, and test commands.

# Build Scripts & Compilation

| Command | Purpose |
|---|---|
| `npm run build` | Full production build (TypeScript compilation of CLI and SDK core) |
| `npm test` | Run full test suite (`node --test`) |
| `npm run sync:schema` | Sync `sdk/schema/*.json` to `website/public/schema/` (+ `v1/` aliases) |

---

## DOC: Source Structure (Slug: dev-source)

> Codebase architecture across /MCP, /sdk, and /skills.

# Codebase Source Architecture

soon :)

---

## DOC: Testing Suites (Slug: dev-testing)

> SDK schema tests and MCP runtime test suites.

# Testing Suites

```
sdk/test/
└── schema.test.mjs     # Zod-to-JSON-Schema exporter & manifest validation tests

MCP/tests/
├── unit/               # Core engine unit tests (walker, delta, cache, plugins, security)
└── e2e/                # Live Chromium automation smoke tests
```

```bash
# Run SDK test suite (inside /sdk)
npm test

# Run MCP unit test suite (inside /MCP)
npm run test:unit
```

---

## DOC: SDK CLI Reference (Slug: sdk-cli)

> Developer commands: init, build, manifest, dev, validate, doctor, publish.

# SDK CLI Reference

The SDK developer CLI is available via `npx @weavetab/sdk <command>` or local `weavetab <command>`:

```bash
# Scaffold a new TypeScript plugin project
weavetab init <plugin-name>

# Compile TypeScript and sync weavetab.json
weavetab build

# Export weavetab.json manifest from definePlugin & defineTool definitions
weavetab manifest
# or alias:
weavetab schema

# Live TypeScript watch mode with manifest auto-sync
weavetab dev

# Run preflight audit before publishing (manifest, permissions, anti-squatting)
weavetab preflight

# Validate schema, permissions, and sandbox compliance (--offline skips network)
weavetab validate

# Run environment diagnostics and check plugin health
weavetab doctor

# npm publish + sync to registry
weavetab publish
# preview without publishing:
weavetab publish --dry-run

# Print current SDK version
weavetab version
```

---

## DOC: SDK Overview (Slug: sdk-overview)

> Official TypeScript SDK for Weavetab plugins and visual extensions.

# Weavetab SDK


The **`@weavetab/sdk`** is the official TypeScript developer toolkit for authoring custom MCP tools, modular plugins, in-browser HUD overlays, and tool overrides for the Weavetab automation ecosystem.

## Version Synchronization

> [!IMPORTANT]
> **`@weavetab/sdk`** and **`@weavetab/mcp`** are maintained in lockstep and share synchronized releases. All SDK types, tool interfaces, storage handlers, and extension bridges are guaranteed 100% binary-compatible with the runtime.

```bash
# Install SDK as a development dependency
npm install -D @weavetab/sdk@latest

# Or with pnpm / yarn / bun
pnpm add -D @weavetab/sdk@latest
yarn add -D @weavetab/sdk@latest
bun add -d @weavetab/sdk@latest
```

---

## SDK Core Architecture

The SDK gives developers first-class access to:
1. **Tool Registration & Interception**: Register new MCP tools or wrap/override existing built-in tools (`ctx.mcp.overrideTool`).
2. **Sandboxed Storage**: Private key-value store and JSON files at `~/.weavetab/plugins/<name>/`.
3. **In-Browser Visual Extensions**: Display animated thought bubbles (`showThought`), status badges (`setHudState`), and inject custom CSS/JS.
4. **Lifecycle Hooks**: Intercept actions before or after execution (`beforeToolCall`, `afterToolCall`, `onPageNavigate`).
5. **Developer CLI**: Full CLI toolset for scaffolding, building, watching, and validating plugins.

---

## SDK vs Core MCP Comparison

| Feature | Core MCP (`@weavetab/mcp`) | Developer SDK (`@weavetab/sdk`) |
|---|---|---|
| **Role** | Execution server & 41 built-in tools | Tool/Plugin authoring framework |
| **Target Audience** | AI agents, users, client IDEs | Developers & plugin creators |
| **Package** | `@weavetab/mcp@latest` | `@weavetab/sdk@latest` |
| **Entrypoint** | `weavetab` binary | `@weavetab/sdk` library + CLI |
| **Extension Engine** | Mounts `node_modules` plugins | Builds & validates `weavetab.json` plugins |

---

## DOC: SDK Quickstart (Slug: sdk-quickstart)

> Scaffold and build a TypeScript plugin in 60 seconds.

# SDK Quickstart

Scaffold a production-grade TypeScript plugin in seconds using the SDK CLI.

## 1. Scaffold a Plugin Project

```bash
npx -y @weavetab/sdk@latest init my-custom-plugin
cd my-custom-plugin
npm install
```

## 2. Project Layout

```
my-custom-plugin/
├── src/
│   └── index.ts        # Plugin implementation & tool definitions
├── weavetab.json       # Manifest declaring tools & permissions
├── package.json        # Dependencies & scripts
├── tsconfig.json       # TypeScript compiler options
└── README.md
```

## 3. Implement Your Tool

```typescript
import { definePlugin, defineTool, z, type PluginContext } from "@weavetab/sdk";

export default definePlugin({
  name: "my-custom-plugin",
  async onLoad(ctx: PluginContext) {
    ctx.mcp.registerTool(
      defineTool({
        name: "greet_page",
        description: "Greets the user and displays a thought bubble on the active tab",
        requiresSession: true,
        schema: {
          name: z.string().describe("Target name to greet"),
        },
        handler: async (args, session) => {
          if (session) {
            await ctx.extension.showThought(session, `Hello, ${args.name}! Welcome to Weavetab.`);
          }
          return {
            content: [{ type: "text", text: `Greeting dispatched to ${args.name}!` }],
          };
        },
      })
    );
  },
});
```

## 4. Build and Validate

```bash
# Build TypeScript and synchronize manifest
npm run build

# Validate schema compliance
npx @weavetab/sdk validate
```

## 5. Install into Weavetab

Install your plugin directly using the Weavetab CLI. Both local workspace directories and published npm packages are supported:

```bash
# Local development install:
weavetab plugin add ./my-custom-plugin

# Or after publishing to npm:
weavetab plugin add my-custom-plugin
```

Installed plugins are stored globally under `~/.weavetab/plugins/` and automatically loaded whenever your IDE or agent connects to Weavetab MCP.

---

## DOC: Plugin Middleware & Hooks (Slug: plugin-hooks)

> Interceptor hooks: onBeforeAction, onAfterAction, and onDOMMutation.

# Plugin Middleware & Interceptor Hooks

Weavetab plugins do not just register isolated tools. Through the interceptor pipeline, plugins act as **middleware** running beneath every MCP tool call executed by AI agents across web and desktop contexts.

Common use cases:
- **Automated Ad & Tracker Blocking**: Block navigations or clicks targeting known advertising or phishing domains.
- **Enterprise Auth Injection**: Automatically inject OAuth tokens, session cookies, or custom headers before actions execute.
- **Data Loss Prevention (DLP) & PII Scrubbing**: Inspect, mask, or redact sensitive fields (SSNs, credit cards, bearer tokens) in tool results before the agent receives them.
- **Live DOM Mutation Listening**: Stream element insertions, deletions, and attribute changes across page state transitions.

---

## 1. `onBeforeAction(tool, args, session)`

Runs immediately before any tool handler (built-in or plugin-provided) executes.

### Signature:
```typescript
type BeforeActionHook = (
  toolName: string,
  args: Record<string, any>,
  session: any
) => Promise<Record<string, any> | { __blocked: true; reason: string } | void | undefined>;
```

### Pattern A: Blocking Dangerous or Unauthorized Actions
If an action violates policy, return `{ __blocked: true, reason: string }`. The tool execution will be halted immediately, and the MCP agent will receive an error without touching the browser.

```typescript
import { definePlugin } from "@weavetab/sdk";

export default definePlugin({
  name: "enterprise-guard",
  version: "1.0.0",
  onBeforeAction: async (tool, args) => {
    // Block clicks on destructive or untrusted controls
    if (tool === "browser_click" && args.selector?.includes(".delete-account")) {
      return {
        __blocked: true,
        reason: "Account deletion actions are restricted by enterprise policy.",
      };
    }

    // Block navigation to known tracking or malicious domains
    if (tool === "browser_navigate" && args.url?.includes("tracking-service.com")) {
      return {
        __blocked: true,
        reason: "Navigation to tracking domains is prohibited.",
      };
    }
  },
});
```

### Pattern B: Mutating Arguments (Auth & Header Injection)
Return a modified `args` object to enrich or rewrite parameters before the tool receives them:

```typescript
import { definePlugin } from "@weavetab/sdk";

export default definePlugin({
  name: "auth-injector",
  version: "1.0.0",
  onBeforeAction: async (tool, args, session) => {
    if (tool === "browser_navigate" && args.url?.startsWith("https://api.internal/")) {
      return {
        ...args,
        headers: {
          ...args.headers,
          Authorization: `Bearer ${process.env.CORP_API_TOKEN}`,
        },
      };
    }
  },
});
```

---

## 2. `onAfterAction(tool, result, session, args)`

Runs immediately after a tool finishes execution. Receives the raw tool result and can transform, redact, or record telemetry.

### Signature:
```typescript
type AfterActionHook = (
  toolName: string,
  result: any,
  session: CDP.Client | null,
  args?: Record<string, any>
) => Promise<any | void | undefined>;
```

### Pattern: PII Redaction & Data Loss Prevention (DLP)
```typescript
import { definePlugin } from "@weavetab/sdk";

export default definePlugin({
  name: "pii-masker",
  version: "1.0.0",
  onAfterAction: async (tool, result) => {
    if (tool === "browser_map" || tool === "browser_scrape") {
      const sanitized = JSON.stringify(result)
        .replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[REDACTED-SSN]")
        .replace(/\b(?:\d{4}-){3}\d{4}\b/g, "[REDACTED-CC]");
      return JSON.parse(sanitized);
    }
    return result;
  },
});
```

---

## 3. `onDOMMutation(delta, session)`

Receives real-time DOM mutation events whenever page elements are added, removed, or modified.

### Signature:
```typescript
type DOMMutationHook = (
  delta: DOMMutationDelta,
  session: CDP.Client | null
) => Promise<void>;

interface DOMMutationDelta {
  type: "dom_diff" | "rich_delta" | "cdp_mutation";
  timestamp: number;
  url?: string;
  added?: Array<any>;
  removed?: Array<any>;
  changed?: Array<any>;
  stable_count?: number;
  iframes?: Array<{ frameUrl: string; status: "added" | "removed" | "changed"; elementCount: number }>;
  significantChange?: boolean;
}
```

### Pattern: Live Mutation Monitoring
```typescript
import { definePlugin } from "@weavetab/sdk";

export default definePlugin({
  name: "mutation-sentinel",
  version: "1.0.0",
  onDOMMutation: async (delta) => {
    if (delta.significantChange) {
      console.log(`[Sentinel] Major DOM change detected on ${delta.url}:`);
      console.log(` - Added elements: ${delta.added?.length ?? 0}`);
      console.log(` - Removed elements: ${delta.removed?.length ?? 0}`);
      console.log(` - Changed properties: ${delta.changed?.length ?? 0}`);
    }
  },
});
```

---

## 4. Manifest Security Declaration

When using middleware hooks, declare the `hooks` permission in `weavetab.json`:

```json
{
  "permissions": {
    "hooks": {
      "onBeforeAction": true,
      "onAfterAction": true,
      "onDOMMutation": true,
      "reason": "Enforces enterprise ad-blocking, security policies, and PII masking"
    }
  },
  "middleware": {
    "onBeforeAction": true,
    "onAfterAction": true,
    "onDOMMutation": true
  }
}
```

The SDK CLI auto-generates the `middleware` block when you run `weavetab build` or `weavetab manifest`.

---

## DOC: Visual HUD & Thought Bubbles (Slug: plugin-hud)

> Render animated thoughts, status badges, and DOM styles in the browser.

# In-Browser Visual Extensions

Plugins can interact directly with the live browser session to render visual feedback, animated thought bubbles, and custom CSS overlays.

---

## 1. Floating Thought Bubbles (`showThought`)

Displays an animated status thought bubble on the active browser window:

```typescript
await ctx.extension.showThought(
  session,
  "🎨 Analyzing page typography and color palette...",
  { durationMs: 4000 }
);
```

---

## 2. Status Badges & HUD State (`setHudState`)

Updates the floating HUD badge in the browser header:

```typescript
await ctx.extension.setHudState(session, {
  badge: "Auditing",
  badgeColor: "#22c55e",
  action: "Scanning DOM hierarchy"
});
```

---

## 3. Style & Script Injection

```typescript
// Inject custom CSS into the page DOM
await ctx.extension.injectStyles(session, `
  .highlight-box {
    outline: 3px solid #8b5cf6 !important;
    background: rgba(139, 92, 246, 0.1) !important;
  }
`);

// Execute sandboxed script in page context
const result = await ctx.extension.injectScript(session, `
  document.querySelectorAll('.pricing-card').length
`);
```

---

## DOC: Plugin Architecture (Slug: plugin-interface)

> PluginBuilder, definePlugin, and the PluginContext interface.

# Plugin Architecture & APIs

The SDK supports two authoring paradigms: the declarative **`definePlugin`** function and the fluent **`PluginBuilder`** class, combined with **`defineTool`** for 100% type-safe Zod tool definitions.

---

## 1. Type-Safe Tool Definition with Zod (`defineTool`)

Plugin authors do not need to manually write JSON Schema draft-07. Use `defineTool` with `z` from `@weavetab/sdk`:

```typescript
import { defineTool, z } from "@weavetab/sdk";

export const scrapeTool = defineTool({
  name: "scrape_catalog",
  description: "Extracts structured product cards from an e-commerce page",
  schema: z.object({
    category: z.string().describe("Product category filter"),
    maxItems: z.number().default(20).describe("Maximum items to extract"),
    includeOutdated: z.boolean().optional().describe("Include out-of-stock items"),
  }),
  // args is automatically typed: { category: string; maxItems: number; includeOutdated?: boolean }
  handler: async (args, session) => {
    return {
      content: [{ type: "text", text: `Scraping category ${args.category} (limit: ${args.maxItems})` }],
    };
  },
});
```

---

### Browser-less tools (`requiresSession: false`)

By default the host establishes a browser/CDP session before invoking your tool, so the `session` argument is populated. API-only tools that never touch the browser (HTTP fetchers, formatters, pure compute) can opt out:

```typescript
import { defineTool, z } from "@weavetab/sdk";

export const repoInfo = defineTool({
  name: "repo_info",
  description: "Fetches repository metadata over HTTPS — no browser needed.",
  requiresSession: false, // handler receives session === undefined
  schema: z.object({ repo: z.string().describe("owner/repo slug") }),
  handler: async ({ repo }) => ({
    content: [{ type: "text", text: `fetched ${repo}` }],
  }),
});
```

With `requiresSession: false` the host skips launching/connecting Chrome entirely, so the call works headlessly and never mutates the user's tabs. RBAC and rate limiting are still enforced. The official `@weavetab/plugin-github` plugin uses this flag.

---

## 2. Fluent `PluginBuilder` API

```typescript
import { PluginBuilder, z } from "@weavetab/sdk";

export default new PluginBuilder("enterprise-auditor")
  .version("1.0.0")
  .description("Enterprise accessibility, security, and SEO auditing plugin")
  .defaultConfig({ autoInjectA11yBadges: true })
  .addTool({
    name: "audit_a11y",
    description: "Audits page elements for WCAG compliance",
    schema: z.object({
      selector: z.string().describe("Root container selector"),
      strictMode: z.boolean().default(false),
    }),
    handler: async (args, session) => {
      return { content: [{ type: "text", text: `Audit complete for ${args.selector}: 0 violations` }] };
    },
  })
  .onBeforeAction(async (tool, args, session) => {
    if (tool === "browser_navigate" && args.url?.includes("untrusted.local")) {
      return { __blocked: true, reason: "Navigation to untrusted intranet site is blocked." };
    }
  })
  .onAfterAction(async (tool, result) => {
    // Redact or scrub result data
    return result;
  })
  .onDOMMutation(async (delta) => {
    console.log(`[Auditor] Page mutated: ${delta.added?.length ?? 0} elements added.`);
  })
  .onLoad(async (ctx) => {
    ctx.logger.info("Enterprise auditor initialized!");
  })
  .build();
```

---

## 3. Declarative `definePlugin` API

```typescript
import { definePlugin, type PluginContext } from "@weavetab/sdk";
import { scrapeTool } from "./tools.js";

export default definePlugin({
  name: "custom-scraper",
  version: "1.0.0",
  defaultConfig: {
    maxItems: 50,
  },
  tools: [scrapeTool],

  // Enterprise middleware hooks
  onBeforeAction: async (tool, args) => {
    // Audit or modify arguments before any MCP tool executes
  },
  onAfterAction: async (tool, result) => {
    // Inspect or redact results after tool executes
  },
  onDOMMutation: async (delta) => {
    // Real-time DOM mutation stream
  },

  async onLoad(ctx: PluginContext) {
    ctx.logger.info("Custom scraper loaded!");
  },
});
```

---

## 4. The `PluginContext` Contract

Every plugin's `onLoad` handler receives a `PluginContext` instance containing:

| Property | Type | Description |
|---|---|---|
| `ctx.name` | `string` | Plugin unique name. |
| `ctx.config` | `Record<string, any>` | Configuration parsed from `~/.weavetab/plugins/<name>/config.json`. |
| `ctx.storage` | `PluginStorage` | Isolated persistent key-value and JSON file storage API. |
| `ctx.extension` | `PluginExtensionBridge` | Direct bridge to in-browser HUD overlays and styles. |
| `ctx.mcp` | `PluginMcpContext` | Tool registration, override, and unregistration API. |
| `ctx.hooks` | `PluginHooks` | Interceptors and lifecycle hooks (`onBeforeAction`, `onAfterAction`, `onDOMMutation`). |
| `ctx.logger` | `PluginLogger` | Scoped logger with info, warn, error, and debug levels. |

---

## DOC: weavetab.json Manifest (Slug: plugin-manifest)

> Specification for weavetab.json schema, permissions, and engines.

# `weavetab.json` Manifest Specification

Every Weavetab plugin includes a `weavetab.json` manifest at its root describing its metadata, engine requirements, permissions, and tools.

`name` must be the npm package id (lowercase, no spaces; the schema enforces this). To control the title shown on weavetab.dev, set the optional `displayName` (max 60 characters). Without it, the registry derives a title from `name`.

```json
{
  "$schema": "https://weavetab.dev/schema/plugin.json",
  "name": "weavetab-plugin-visual",
  "displayName": "Visual HUD",
  "version": "1.0.0",
  "description": "Visual HUD highlights and styling plugin",
  "entry": "dist/index.js",
  "engines": {
    "weavetab": ">=2.6.0",
    "node": ">=18.0.0"
  },
  "environments": ["mcp"],
  "defaultConfig": {
    "hudBadge": "Visual Mode",
    "badgeColor": "#8b5cf6"
  },
  "permissions": {
    "config": {
      "read": true,
      "write": true,
      "reason": "Manages visual HUD badge preferences"
    },
    "extension": {
      "hud": true,
      "overlay": true,
      "styles": true,
      "reason": "Renders floating thought bubbles and injects element highlight outlines"
    },
    "cdp": {
      "evaluate": true,
      "reason": "Applies visual DOM transforms in page"
    },
    "hooks": {
      "onBeforeAction": true,
      "onAfterAction": true,
      "onDOMMutation": true,
      "reason": "Intercepts tool calls for security inspection and listens to DOM deltas"
    }
  },
  "middleware": {
    "onBeforeAction": true,
    "onAfterAction": true,
    "onDOMMutation": true
  },
  "tools": [
    {
      "name": "highlight_elements",
      "description": "Highlights specific DOM elements on the active webpage with custom outline colors",
      "inputSchema": {
        "type": "object",
        "properties": {
          "selector": { "type": "string", "description": "CSS selector to highlight" },
          "color": { "type": "string", "description": "CSS outline color hex" }
        },
        "required": ["selector"]
      }
    }
  ]
}
```

---

## Permission Categories

| Permission | Description |
|---|---|
| `config` | Access to read/write plugin-specific configuration in `~/.weavetab/plugins/<name>/config.json`. |
| `extension` | Permission to render HUD thoughts, badges, and inject CSS/JS overlays. |
| `cdp` | Granular CDP capabilities (`evaluate`, `dom`, `click`, `navigate`, `network`, `screenshot`). |
| `network` | Specific allowed domain and host glob patterns. |
| `filesystem` | Restricted read/write path access outside the plugin's isolated folder. |
| `tools` | Tool authoring capabilities: `add` (register new MCP tools), `override` (wrap listed built-ins), `remove` (disable listed built-ins). |
| `hooks` | Permission to register enterprise middleware interceptors (`onBeforeAction`, `onAfterAction`, `onDOMMutation`). |

---

## DOC: Tool Overrides & Hooks (Slug: plugin-overrides)

> Intercept built-in tools and subscribe to global lifecycle events.

# Tool Overrides & Lifecycle Hooks

Plugins can wrap or intercept built-in tools (such as `browser_navigate`, `browser_click`, `browser_eval`) and subscribe to global lifecycle hooks.

---

## 1. Tool Overriding (`overrideTool`)

Intercept an existing tool to add validation, security guards, or logging:

```typescript
ctx.mcp.overrideTool("browser_navigate", async (args: { url: string }, session, config, original) => {
  // Check against custom security rules
  if (args.url.includes("untrusted-domain.com")) {
    if (session) {
      await ctx.extension.showThought(session, "🛡️ Blocked navigation to untrusted domain!");
    }
    return {
      content: [{ type: "text", text: "Navigation blocked by custom security plugin." }],
      isError: true
    };
  }

  // Forward to original built-in handler
  return original ? await original(args, session, config) : null;
});
```

---

## 2. Global Execution Hooks

```typescript
// Before any tool executes
ctx.hooks.beforeToolCall((toolName, args) => {
  ctx.logger.debug(`[Hook] Executing ${toolName}`, args);
});

// After any tool finishes
ctx.hooks.afterToolCall((toolName, args, result) => {
  ctx.logger.debug(`[Hook] Completed ${toolName}`);
});

// On page navigation
ctx.hooks.onPageNavigate?.(async (url, session) => {
  ctx.logger.info(`Navigated to: ${url}`);
});
```

---

## DOC: Sandboxed Storage (Slug: plugin-storage)

> Isolated key-value store, config, and file sandbox per plugin.

# Sandboxed Storage & Configuration

Weavetab strictly isolates every plugin into its own dedicated directory on the local filesystem:

```
~/.weavetab/plugins/<plugin-name>/
├── config.json          # Private configuration
├── storage.json         # Key-value store (get / set)
└── custom_data.json     # Custom JSON datasets
```

---

## `ctx.storage` API Reference

```typescript
// 1. Key-Value Storage
await ctx.storage.set("visitCount", 42);
const count = await ctx.storage.get<number>("visitCount", 0);
await ctx.storage.delete("visitCount");

// 2. Cached Memory with TTL Expiry
await ctx.storage.setWithExpiry("session_token", "val-xyz", 3600000);
const cached = await ctx.storage.getWithExpiry("session_token");

// Compute-and-cache memoization pattern
const profile = await ctx.storage.remember("site_profile", 600000, async () => {
  return await fetchProfileOverNetwork();
});

// 3. Structured JSON Files
await ctx.storage.setJSON("scraped_products.json", { items: [1, 2, 3] });
const data = await ctx.storage.getJSON("scraped_products.json");

// 4. Isolated Path Resolution (Path-Traversal Protected)
const filePath = ctx.storage.getPath("scraped_products.json");
// → "~/.weavetab/plugins/my-plugin/scraped_products.json"

// 5. File Listing
const files = await ctx.storage.list();
```

---

# SECTION 3: RESEARCH PAPERS & TECHNICAL ARTICLES


## RESEARCH ARTICLE: Weavetab 2.6: Direct CDP Ergonomics, Native Cache-Aside Storage, and Headless Agent Harnessing (Slug: weavetab-2-6-layer0-ergonomics-ttl-cache-testing)

Published: 2026-10-31
Abstract: Agent toolchains are plagued by two opposing failure modes: heavy out-of-process IPC wrappers that burn latency, and bare-metal CDP scripts that duplicate dozens of boilerplate turns. Weavetab 2.6 bridges this gap with typed direct CDP client bindings (TabClient & DesktopClient), native TTL cache-aside storage (storage.remember), offline mock harnesses, and automated preflight verification.

---

## RESEARCH ARTICLE: Browser Chaos Engineering: Direct CDP Fault Injection & Race Telemetry (Slug: browser-chaos-engineering-layer0-fault-injection)

Published: 2026-10-30
Abstract: Synthetic agent benchmarks assume clean networks and cooperative DOM trees. We built wt-choas to shatter that assumption: injecting socket timeouts, 4x CPU slowdowns, multi-click race bursts, and boundary fuzzing over raw CDP — forcing agent self-healing loops to prove their resilience before production.

---

## RESEARCH ARTICLE: Rethinking Agent Plugins: Auto-Loading, Zero-IPC, and Strict Capability Scoping (Slug: rethinking-agent-plugins-auto-load-zero-ipc)

Published: 2026-10-29
Abstract: Why dynamic runtime tool discovery degraded agent reasoning, and how Weavetab 2.5 replaced dynamic tool-loading with an in-process, statically-scoped plugin architecture that preserves context windows and eliminates IPC latency.

---

## RESEARCH ARTICLE: Architectural Deep Dive: Direct CDP vs. Playwright for Browser Agents (Slug: layer-0-cdp-vs-playwright-weavetab-mcp)

Published: 2026-08-28
Abstract: Testing frameworks like Playwright and raw Chrome DevTools Protocol were built for humans writing deterministic test suites. We compare the two as transport layers for probabilistic AI agents, focusing on architecture and context size rather than synthetic benchmark scores.

---

## RESEARCH ARTICLE: How Weavetab Represents a Page as a Spatial State (Slug: deterministic-spatial-state-engines-weavetab-mcp)

Published: 2026-08-27
Abstract: Browser agents rarely fail at clicking. They fail because they lack a compact, reliable picture of what exists on the page, where it is, and what changed. This note describes how Weavetab turns raw CDP into a normalized spatial state of interactive nodes.

---

## RESEARCH ARTICLE: Sending Only What Changed on the Page (Slug: semantic-delta-streaming)

Published: 2026-07-08
Abstract: Shipping a fresh accessibility tree or raw HTML on every turn is expensive. We describe the delta model Weavetab uses to send a language model only the meaningful changes between turns.

---

## RESEARCH ARTICLE: Why Weavetab Uses an In-Process CDP Client (Slug: cdp-latency-budget)

Published: 2026-06-19
Abstract: An engineering note on why the tool router and the CDP client share a process, and why we did not build on WebDriver, Playwright, or Puppeteer as a transport layer.

---

## RESEARCH ARTICLE: Why Weavetab MCP is AGPL (Slug: agpl-and-why)

Published: 2026-05-30
Abstract: A short note on why the core MCP server ships under AGPL-3.0-only, what that means in practice, and how the other Weavetab packages differ.

---