@weavetab/mcp 2.5.0-beta.1 → 2.5.0-beta.4

package/docs/TOOLS.md

@@ -1,104 +1,56 @@
 # Weavetab MCP Tool Reference
 
-> **Version:** 2.5.0 | **Total Registered Tools:** 45 | **Architecture:** Layer 0 Direct CDP & Extension Bridge
-
-Weavetab provides 45 production-grade MCP tools engineered for browser automation, GitHub repository analysis, Office document parsing, and deep web inspection.
-
----
-
-## Tool Directory
-
-| # | Tool Name | Category | Description | Key Capabilities & Parameters |
-| :--- | :--- | :--- | :--- | :--- |
-| 1 | `browser_map` | `vision` | DOM tree snapshotter with volatile ref IDs (`w:NN`). For complex SPAs, supports delta diffing, semantic pruning, and AX tree fallback. | `delta: boolean` (up to 97% token reduction), `scope: string`, `query: string`, `force: boolean` |
-| 2 | `browser_navigate` | `navigation` | Navigates to a URL with blocklist checks, network idle wait, and `weavetab://` scheme support. | `url: string`, `timeoutMs?: number` |
-| 3 | `browser_click` | `input` | Physical click engine using Bézier curve kinematics (Ghost Cursor) and multi-stage fallback targeting (`ref` -> `selector` -> `label` -> `intent` -> `coords`). | `ref?: string`, `selector?: string`, `label?: string`, `coords?: [number, number]` |
-| 4 | `browser_type` | `input` | Keystroke dispatch with humanized temporal jitter, stuck-input monitoring, and `clearFirst` support. | `ref?: string`, `text: string`, `clearFirst?: boolean` |
-| 5 | `browser_type_secret` | `input` | Blind credential injection from environment variables or secrets store without exposing values to LLM context (`[REDACTED]`). | `envVar: string`, `ref?: string`, `selector?: string` |
-| 6 | `browser_key` | `input` | Presses native key combinations (Ctrl, Alt, Shift, Meta, Enter, Tab, Escape, etc.). | `key: string`, `modifiers?: string[]` |
-| 7 | `browser_scroll` | `input` | Smooth directional scrolling or scroll-to-element centering via CDP wheel events. | `direction?: "down" \| "up" \| "left" \| "right"`, `amount?: number`, `ref?: string` |
-| 8 | `browser_dialog` | `dialog` | Accepts, dismisses, or responds to JS `alert`, `confirm`, and `prompt` dialogs. | `action: "accept" \| "dismiss"`, `promptText?: string` |
-| 9 | `browser_burst` | `execution` | Atomic multi-step action pipeline execution in a single JSON-RPC round-trip. | `steps: Array<MacroStep>` (`navigate_and_read`, `type_and_send`, `click_and_wait`, etc.) |
-| 10 | `browser_tabs` | `tabs` | Full tab and window CRUD lifecycle management (open, switch, close, list, consolidate, heal). | `action: "list" \| "open" \| "switch" \| "close" \| "consolidate" \| "heal" \| "list_windows" \| "focus_window"`, `url?: string`, `tabId?: number` |
-| 11 | `browser_wait` | `navigation` | Pause until DOM element, text, URL, network idle, or DOM stability condition is met. | `condition: "element" \| "text" \| "url" \| "stable" \| "network" \| "auto"`, `target?: string`, `timeoutMs?: number` |
-| 12 | `browser_captcha` | `security` | Autonomous detection and solving of turnstile, reCAPTCHA, and hCaptcha challenges. | `action: "detect" \| "solve" \| "status"`, `timeoutMs?: number` |
-| 13 | `browser_thoughts` | `overlay` | Visual agent-to-user status HUD overlay (feedback banner or interactive question box). | `mode: "feedback" \| "question"`, `message: string`, `options?: string[]` |
-| 14 | `browser_pointer` | `input` | Precision mouse pointer control including hover flyout triggers and drag-and-drop. | `action: "hover" \| "click" \| "double_click" \| "drag_and_drop"`, `ref?: string`, `targetRef?: string`, `waitForChild?: boolean` |
-| 15 | `browser_select` | `input` | Selects native dropdown options by text or value, firing framework-safe synthetic events. | `ref?: string`, `value?: string`, `label?: string` |
-| 16 | `browser_fill` | `input` | Smart multi-field form completion across text inputs, radios, checkboxes, and dropdowns. | `fields: Array<{ ref?: string, selector?: string, value: string }>` |
-| 17 | `browser_plan` | `overlay` | Real-time task dashboard HUD panel rendered inside isolated Shadow DOM overlay. | `action: "create" \| "update" \| "clear"`, `tasks?: Array<{ id: string, title: string, status: "pending" \| "in_progress" \| "done" \| "failed" }>` |
-| 18 | `browser_highlight` | `overlay` | Temporary visual CDP overlay highlights over target elements without DOM mutations. | `ref?: string`, `selector?: string`, `color?: string`, `durationMs?: number` |
-| 19 | `browser_upload` | `input` | Direct file input upload bypassing OS file pickers via CDP `DOM.setFileInputFiles`. | `ref?: string`, `selector?: string`, `files: string[]` |
-| 20 | `browser_find` | `vision` | Sub-5ms CDP text search without full DOM walk overhead. Zero token waste. | `query: string`, `caseSensitive?: boolean` |
-| 21 | `browser_storage` | `storage` | Key-value store management for `localStorage` and `sessionStorage`. | `action: "get" \| "set" \| "clear" \| "remove"`, `type: "local" \| "session"`, `key?: string`, `value?: string` |
-| 22 | `browser_network_intercept` | `network` | Request mocking, URL pattern blocking, and network timing/TLS diagnostic extraction. | `action: "mock" \| "block" \| "clear" \| "get_logs"`, `pattern?: string`, `response?: object` |
-| 23 | `browser_console` | `inspection` | Sub-5ms access to buffered console API outputs, exceptions, and network errors. | `action: "get" \| "clear"`, `minLevel?: "log" \| "warn" \| "error"` |
-| 24 | `browser_pdf` | `output` | Generates a PDF printout of the active page with layout and page range controls. | `landscape?: boolean`, `printBackground?: boolean`, `pageRanges?: string`, `outputPath?: string` |
-| 25 | `browser_eval` | `evaluation` | Evaluates arbitrary JavaScript expressions directly in the main frame JS context. | `expression: string`, `awaitPromise?: boolean` |
-| 26 | `browser_cookies` | `storage` | Full CRUD operations for browser cookies via CDP Network domain. | `action: "get" \| "set" \| "clear" \| "remove"`, `name?: string`, `value?: string`, `domain?: string` |
-| 27 | `browser_canvas` | `vision` | Export canvas pixel data as Base64 PNG or execute coordinate gesture paths on charts/games. | `action: "get_image" \| "draw"`, `ref?: string`, `path?: Array<[number, number]>` |
-| 28 | `browser_scrape` | `vision` | High-speed structured data extraction via CSS or XPath selectors in a single evaluation step. | `selector: string`, `attributes?: string[]`, `isXpath?: boolean` |
-| 29 | `browser_snapshot` | `vision` | Capture or restore an MHTML snapshot (DOM + inline assets) for offline archival or verification. | `action: "capture" \| "restore"`, `filePath?: string` |
-| 30 | `browser_screenshot` | `vision` | Visual screenshot capture in PNG or JPEG format with full-page and bounding box support. | `fullPage?: boolean`, `format?: "png" \| "jpeg"`, `quality?: number`, `clip?: object` |
-| 31 | `browser_viewport` | `emulation` | Viewport dimensions, device scale factor, touch support, geolocation, and locale overrides. | `width?: number`, `height?: number`, `deviceScaleFactor?: number`, `isMobile?: boolean` |
-| 32 | `browser_clipboard` | `interaction` | Plaintext and Base64 image reading/writing to the system clipboard. | `action: "read" \| "write"`, `text?: string` |
-| 33 | `browser_inspect` | `inspection` | Deep DOM element inspection returning computed styles, box model, and attached event listeners. | `ref?: string`, `selector?: string` |
-| 34 | `browser_automation` | `execution` | Injects self-running background tracking scripts into the page context. | `action: "inject" \| "remove" \| "list"`, `scriptName: string`, `code?: string` |
-| 35 | `browser_recording` | `output` | Records browser session video screencasts into `.webp`, `.gif`, `.webm`, or `.mp4`. | `action: "start" \| "stop" \| "status"`, `fps?: number`, `format?: "webp" \| "gif" \| "webm" \| "mp4"` |
-| 36 | `browser_reset_loop_counter` | `safety` | Resets the repetitive action strike counter to zero for long-running workflows. | `reason: string` |
-| 37 | `browser_detect` | `system` | Detects installed local browsers and reports CDP feature support matrices across engines. | `target?: "chromium" \| "firefox" \| "webkit" \| "all"` |
-| 38 | `browser_performance` | `performance` | Retrieves Core Web Vitals (FCP, LCP, CLS) and network resource timing breakdowns. | `includeResourceTimings?: boolean` |
-| 39 | `browser_macro_compile` | `macro` | Compiles recent action trails into reusable `browser_burst` macro sequences. | `maxSteps?: number`, `macroName?: string` |
-| 40 | `github_analyze` | `github` | Analyzes GitHub repository structure, file trees, and README content without API rate limits. | `owner: string`, `repo: string`, `branch?: string` |
-| 41 | `github_read` | `github` | Reads raw file contents from public or private GitHub repositories. | `owner: string`, `repo: string`, `path: string`, `ref?: string` |
-| 42 | `github_issues` | `github` | Lists, searches, and fetches GitHub issue details and discussion threads. | `owner: string`, `repo: string`, `action: "list" \| "get" \| "search"`, `issueNumber?: number` |
-| 43 | `github_get_pr` | `github` | Inspects GitHub Pull Requests including changed files, diffs, and review comments. | `owner: string`, `repo: string`, `prNumber: number` |
-| 44 | `browser_office` | `office` | Parses and extracts structured content/tables from Word (`.docx`), Excel (`.xlsx`), and PDF documents. | `action: "parse" \| "list" \| "search"`, `filePath: string` |
-| 45 | `browser_emulate` | `emulation` | Advanced network throttling, offline mode, user-agent spoofing, and CPU throttling. | `networkProfile?: "offline" \| "3g_slow" \| "3g_fast" \| "4g"`, `cpuThrottlingRate?: number`, `userAgent?: string` |
-
----
-
-## Detailed Tool Guidance & Examples
-
-### 1. High-Efficiency Data Extraction
-When extracting tabular data or structured text from a webpage, prefer **`browser_scrape`** or **`browser_find`** over `browser_map` to save 95%+ context tokens:
-```json
-{
-  "name": "browser_scrape",
-  "arguments": {
-    "selector": "table.pricing-table tr",
-    "attributes": ["innerText", "data-plan-id"]
-  }
-}
-```
-
-### 2. Multi-Action Pipeline Chaining
-To reduce JSON-RPC transport overhead, chain repetitive form inputs and navigations into a single **`browser_burst`** request:
-```json
-{
-  "name": "browser_burst",
-  "arguments": {
-    "steps": [
-      { "action": "navigate_and_read", "url": "https://example.com/login" },
-      { "action": "type_and_send", "ref": "w:12", "text": "user@example.com" },
-      { "action": "click_and_wait", "ref": "w:15" }
-    ]
-  }
-}
-```
-
-### 3. Blind Credential Injection
-For enterprise security, inject secrets without exposing raw password text to the AI model logs or context stream:
-```json
-{
-  "name": "browser_type_secret",
-  "arguments": {
-    "envVar": "WORKFLOW_AUTH_TOKEN",
-    "selector": "#api-key-input"
-  }
-}
-```
+> **Version:** 2.5.0-beta.4 | **Total Tools:** 44 | **Architecture:** Layer 0 Direct CDP
+
+Weavetab provides 44 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` | Sub-5ms CDP text search. Zero token waste. Best for locating specific keywords/text on page without a full DOM walk. | Native CDP search (zero DOM walk overhead), Sub-5ms execution latency, 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` | Sub-5ms latency, zero waste 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_github` | `github` | Interact with GitHub repositories without burning browser turns. Analyze repo trees, read raw source files, search/inspect issues, and examine PR diffs and review comments. | Action-based repo analysis, file reading, issues, and PR review, Zero GitHub API token requirement for raw reads, Automated active tab repository context resolution |
+| `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 |
+| `list_plugins` | `plugins` | Inspect installed Weavetab SDK plugins, available unloadable plugins, tool overrides, custom schemas, and capability manifests. | Installed plugin discovery, Manifest and schema introspection, Ecosystem capability listing |
+| `load_plugin` | `plugins` | Dynamically load any published Weavetab plugin by npm package name into the active runtime with isolated sandboxing and hot tool registration. | Dynamic npm package loading, Hot tool registration with client notification, Isolated plugin execution context |
 
 ---
 
-*Updated & verified for Weavetab v2.5.0.*
+*Auto-generated via `npm run docs:generate` on 2026-09-24.*

package/docs/architecture/blind-injection.md

@@ -0,0 +1,83 @@
+---
+title: "Blind Injection"
+description: "Enterprise-grade credential injection that never exposes secrets to the LLM."
+product: mcp
+section: architecture
+icon: Lock
+slug: blind-injection
+---
+
+# 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"
+}
+```

package/docs/architecture/dual-injection.md

@@ -0,0 +1,32 @@
+---
+title: "Dual Injection"
+description: "CDP early-script + Manifest V3 extension working in tandem."
+product: mcp
+section: architecture
+icon: Combine
+slug: dual-injection
+---
+
+# 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

package/docs/architecture/overview.md

@@ -0,0 +1,49 @@
+---
+title: "Overview"
+description: "Five layers, deterministic pipeline, zero cloud."
+product: mcp
+section: architecture
+icon: Layers
+slug: overview
+---
+
+# 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 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 Layer 0 | Node bridge abstraction | CDP wrapper | WebDriver |
+| **Mean latency** | **3–8 ms** | 15–40 ms | 10–25 ms | 50–150 ms |
+| **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 (44 tools)** | No | No | No |
+| **Cloud dependency** | **Zero** | Optional | Optional | Grid required |

package/docs/architecture/security.md

@@ -0,0 +1,35 @@
+---
+title: "Security Model"
+description: "Layered defenses that gate every tool invocation."
+product: mcp
+section: architecture
+icon: ShieldCheck
+slug: security
+---
+
+# Security Model
+
+Weavetab executes direct Layer 0 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** | 4 strict roles gating tool access (`admin`, `operator`, `viewer`, `automation`). |
+| **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 |
+|---|:---:|:---:|:---:|:---:|
+| Mutation tools (`click`, `type`, `fill`, etc.) | yes | yes | no | yes |
+| Read-only tools (`map`, `find`, `scrape`, `screenshot`) | yes | yes | yes | yes |
+| High-level orchestration (`burst`, `plan`, `wait`) | yes | yes | no | yes |
+| System management (`detect`, `reset_loop_counter`) | yes | no | no | no |

package/docs/architecture/transport.md

@@ -0,0 +1,37 @@
+---
+title: "Transport Modes"
+description: "stdio vs WebSocket — pick the right wire for your client."
+product: mcp
+section: architecture
+icon: Cable
+slug: transport
+---
+
+# Transport Modes
+
+| Mode | Flag | Protocol | Use Case |
+|---|---|---|---|
+| **stdio** | *(default)* | JSON-RPC 2.0 / stdio | Claude Desktop, Cursor, VS Code Copilot, Antigravity |
+| **WebSocket** | `--ws` | 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": "weavetab"
+    }
+  }
+}
+```
+
+## WebSocket
+
+```bash
+weavetab --ws --port 3000
+```
+
+WebSocket mode binds strictly to `127.0.0.1` for local security. Front it with your own TLS/auth layer if exposing across a private network.

package/docs/captcha-stealth/captcha-solver.md

@@ -0,0 +1,75 @@
+---
+title: "CAPTCHA Solver"
+description: "Autonomous zero-API solver for Turnstile, GeeTest, and reCAPTCHA."
+product: mcp
+section: captcha-stealth
+badge: new
+icon: ShieldAlert
+slug: captcha-solver
+---
+
+# 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);
+}
+```

package/docs/captcha-stealth/stealth-physics.md

@@ -0,0 +1,60 @@
+---
+title: "Stealth & Physics"
+description: "Ghost Cursor Bézier kinematics, typing jitter, and anti-fingerprinting."
+product: mcp
+section: captcha-stealth
+icon: Sparkles
+slug: stealth-physics
+---
+
+# 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. Layer 0 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);
+};
+```