@weavetab/mcp 2.5.0 → 2.5.1

package/docs/DOCUMENTATION.md

@@ -1,585 +1,583 @@
-# Weavetab MCP Documentation
-
-> **Package:** `@weavetab/mcp` | **Version:** 2.5.0 | **License:** AGPLv3 | **Author:** fy2ne
-
----
-
-## Overview
-
-Weavetab is a production-grade, in-process MCP (Model Context Protocol) server providing AI agents with direct, physical Layer 0 control across Chromium browsers and Electron desktop applications. It communicates directly over the Chrome DevTools Protocol (CDP) WebSocket at Layer 0 — no WebDriver process, no browser binary download, no cloud middleware.
-
-### Core Capabilities
-
-- **44 Built-in MCP Tools** across functional categories (Vision, Navigation, Input, Tabs, Mission Execution, Dialog, Wait, Storage, Device, Network, Canvas, Output, Evaluation, GitHub, Office Documents)
-- **Direct CDP WebSocket** — 3-8ms mean latency, zero process 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 (4 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 Integration** — Unified `browser_github` tool for repo analysis, file reading, issues, and PRs
-
-### 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 (44 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 (v3.0) 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) |
-
-### 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` | FCP, LCP, TTI metrics, resource timings |
-
-### GitHub (1 tool)
-
-| Tool | Description |
-|------|-------------|
-| `browser_github` | Action-based repo metadata analysis, raw source file reading, issue triage, and PR inspection |
-
-### Utility (5 tools)
-
-| Tool | Description |
-|------|-------------|
-| `list_plugins` | Inspect installed SDK plugins, loaded tool overrides, and capability manifests |
-| `load_plugin` | Dynamically load a Weavetab plugin by npm package name with isolated sandboxing |
-| `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 | true | Enable HUD overlay and verbose logging |
-| `maxActionsPerMinute` | number | 60 | Rate limit for tool executions |
-| `role` | string | "admin" | RBAC role (admin, system, viewer, automation) |
-| `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 directly in your config file (or via `~/.Weavetab/policy.json`):
-
-```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`, `browser_github`) |
-| `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 `fast: true` in click operations 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": "browser_my_custom_tool",
-      "description": "My custom tool description"
-    }
-  ]
-}
-```
-
-```typescript
-// my-plugin/index.ts
-import type { WeavetabPlugin } from "@weavetab/mcp";
-
-const plugin: WeavetabPlugin = {
-  name: "wt-my-tool",
-  version: "1.0.0",
-  tools: [
-    {
-      name: "browser_my_custom_tool",
-      description: "My custom tool description",
-      handler: async (args, session, config) => {
-        // Your tool implementation
-        return { success: true, data: "result" };
-      }
-    }
-  ]
-};
-
-export default plugin;
-```
-
-### 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).
-
-### Why It Works at Layer 0
-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 50 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-1.0.9183\\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 `~/.Weavetab/logs/audit.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)
+# Weavetab MCP Documentation
+
+> **Package:** `@weavetab/mcp` | **Version:** 2.5.1 | **License:** AGPLv3 | **Author:** fy2ne
+
+---
+
+## Overview
+
+Weavetab is a production-grade, in-process MCP (Model Context Protocol) server providing AI agents with direct, physical Layer 0 control across Chromium browsers and Electron desktop applications. It communicates directly over the Chrome DevTools Protocol (CDP) WebSocket at Layer 0 — 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** — 3-8ms mean latency, zero process 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).
+
+### Why It Works at Layer 0
+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-1.0.9183\\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)