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

package/docs/cli/cli-commands.md

@@ -0,0 +1,44 @@
+---
+title: "Commands"
+description: "Reference for every top-level subcommand."
+product: mcp
+section: cli
+icon: ListTree
+slug: cli-commands
+---
+
+# 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 config` | Launch the 5-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 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 |
+| `[R]` | Purge browser profiles and lockfiles |
+| `[H]` | Show help information |
+| `[Q]` | Exit Weavetab |

package/docs/cli/cli-flags.md

@@ -0,0 +1,20 @@
+---
+title: "Flags"
+description: "Global flags accepted by the server."
+product: mcp
+section: cli
+icon: Flag
+slug: cli-flags
+---
+
+# Flags
+
+| Flag | Type | Description |
+|---|---|---|
+| `--version` | boolean | Print CLI version and exit |
+| `--help` / `-h` | boolean | Show help message and exit |
+| `--ws` | boolean | Start server in WebSocket mode instead of stdio |
+| `--port <port>` | number | Port for WebSocket server (default `3000`) |
+| `--headless` | boolean | Run browser in headless mode |
+| `--role <role>` | enum | Override RBAC role (`admin`, `operator`, `viewer`, `automation`) |
+| `--yes` / `-y` | boolean | Skip confirmation prompt when running `weavetab reset` |

package/docs/cli/cli-introduction.md

@@ -0,0 +1,20 @@
+---
+title: "Introduction"
+description: "Drive Weavetab from the command line — no client required."
+product: mcp
+section: cli
+icon: Terminal
+slug: cli-introduction
+---
+
+# 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
+```

package/docs/cli/cli-scripting.md

@@ -0,0 +1,32 @@
+---
+title: "Scripting & CI/CD"
+description: "Chain CLI calls in shell scripts and CI."
+product: mcp
+section: cli
+icon: FileCode
+slug: cli-scripting
+---
+
+# Scripting & CI/CD
+
+## Shell Scripting
+
+```bash
+# Reset before a fresh test run
+weavetab reset --yes
+
+# List stored secrets
+weavetab secrets list
+
+# Start the MCP server in WebSocket mode for custom scripts
+weavetab --ws --port 3000 --headless &
+```
+
+## CI/CD Pipeline
+
+```bash
+# In GitHub Actions or Docker CI
+npm install -g @weavetab/mcp
+weavetab reset --yes
+weavetab --ws --port 3000 --headless &
+```

package/docs/cli/g-ide/ide-antigravity.md

@@ -0,0 +1,24 @@
+---
+title: "Antigravity IDE"
+description: "Configure Weavetab for Google Antigravity IDE."
+product: mcp
+section: cli
+group: g-ide
+icon: Rocket
+slug: ide-antigravity
+---
+
+# Antigravity IDE Integration
+
+Add to `~/.antigravity/mcp.json` or workspace `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/cli/g-ide/ide-claude-code.md

@@ -0,0 +1,24 @@
+---
+title: "Claude Code"
+description: "Configure Weavetab for Claude Code CLI agent."
+product: mcp
+section: cli
+group: g-ide
+icon: MessageSquare
+slug: ide-claude-code
+---
+
+# Claude Code Integration
+
+Add to project `.claude/settings.json` or global configuration:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/cli/g-ide/ide-claude-desktop.md

@@ -0,0 +1,32 @@
+---
+title: "Claude Desktop"
+description: "Configure Weavetab as an MCP server for Claude Desktop."
+product: mcp
+section: cli
+group: g-ide
+icon: Bot
+slug: ide-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": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/cli/g-ide/ide-cursor.md

@@ -0,0 +1,31 @@
+---
+title: "Cursor"
+description: "Configure Weavetab as an MCP server for Cursor IDE."
+product: mcp
+section: cli
+group: g-ide
+icon: MousePointer2
+slug: ide-cursor
+---
+
+# Cursor Integration
+
+## Config File Location
+
+| Scope | Path |
+|---|---|
+| **Global** | `~/.cursor/mcp_config.json` |
+| **Project** | `.cursor/mcp.json` (in project root) |
+
+## Configuration
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/cli/g-ide/ide-generic.md

@@ -0,0 +1,34 @@
+---
+title: "Generic / WebSocket"
+description: "Connect any MCP-compatible client via WebSocket or stdio."
+product: mcp
+section: cli
+group: g-ide
+icon: Globe
+slug: ide-generic
+---
+
+# Generic Client Integration
+
+Any client speaking MCP JSON-RPC 2.0 can connect to Weavetab.
+
+## stdio Transport (Default)
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```
+
+## WebSocket Transport
+
+```bash
+weavetab --ws --port 3000
+```
+
+Connect your client over WebSocket to `ws://127.0.0.1:3000`.

package/docs/cli/g-ide/ide-opencode.md

@@ -0,0 +1,24 @@
+---
+title: "OpenCode"
+description: "Configure Weavetab for OpenCode CLI agent."
+product: mcp
+section: cli
+group: g-ide
+icon: Terminal
+slug: ide-opencode
+---
+
+# OpenCode Integration
+
+Add to `.opencode/config.json` or `opencode.json`:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/cli/g-ide/ide-vscode-copilot.md

@@ -0,0 +1,24 @@
+---
+title: "VS Code + Copilot"
+description: "Configure Weavetab for VS Code with GitHub Copilot."
+product: mcp
+section: cli
+group: g-ide
+icon: Code
+slug: ide-vscode-copilot
+---
+
+# VS Code + GitHub Copilot Integration
+
+Create `.vscode/mcp.json` in your workspace root:
+
+```json
+{
+  "servers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/cli/g-ide/ide-windsurf.md

@@ -0,0 +1,24 @@
+---
+title: "Windsurf"
+description: "Configure Weavetab as an MCP server for Windsurf IDE."
+product: mcp
+section: cli
+group: g-ide
+icon: Wind
+slug: ide-windsurf
+---
+
+# Windsurf Integration
+
+Add to `~/.windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab",
+      "args": []
+    }
+  }
+}
+```

package/docs/configuration/config-locations.md

@@ -0,0 +1,24 @@
+---
+title: "Locations & Merge"
+description: "Three-tier merge: local → global → built-in defaults."
+product: mcp
+section: configuration
+icon: FolderTree
+slug: config-locations
+---
+
+# Config Locations & Merge Priority
+
+## Priority Tiers
+
+1. **Local (Project-scoped)** — `./.weavetab/config.json` (takes top priority)
+2. **Global** — `~/.weavetab/config.json`
+3. **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.

package/docs/configuration/configuration.md

@@ -0,0 +1,73 @@
+---
+title: "Schema"
+description: "Every field on the runtime config object."
+product: mcp
+section: configuration
+icon: Settings2
+slug: configuration
+---
+
+# Configuration Schema
+
+The full `Config` interface lives in `src/config/loader.ts`.
+
+```typescript
+export type PolicyMode    = "allow" | "deny" | "audit-only" | "read-only";
+export type Role          = "admin" | "operator" | "viewer" | "automation";
+export type BrowserEngine = "chromium" | "firefox" | "webkit";
+
+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 {
+  // Mode & Port
+  mode: "session" | "attach";
+  session: string;
+  attachPort: number;
+
+  // Browser Settings
+  browser: string;              // Executable path or "auto"
+  browserType: BrowserEngine;
+  profileDir: string;
+  headless: boolean;
+  extension: boolean;           // Enable Weavetab Chrome extension
+  browserFlags: string[];
+
+  // Desktop & Electron Applications
+  electron?: Record<string, string | number | ElectronAppConfig>;
+
+  // Security & Policy
+  block: string[];              // Domain blocklist
+  allow: string[];              // Domain allowlist
+  policies: PolicyEntry[];      // Per-domain policy modes
+  role: Role;                   // RBAC role
+  cookies: boolean;             // Allow storage & cookies
+  proxy?: string;               // Outbound proxy URL
+
+  // Rate Limiting & Resource Caps
+  maxActionsPerMinute: number;  // 1-600 (default 60)
+  maxTabs: number;              // 1-100 (default 10)
+
+  // Timing & Thresholds
+  sessionTimeout: number;       // Seconds (default 3600)
+  navigationTimeout: number;    // Milliseconds (default 30000)
+  idleTimeout: number;          // Milliseconds (default 15000)
+  actionabilityTimeoutMs: number; // Milliseconds (default 500)
+
+  // UI & Overlay
+  devMode: boolean | DevModeConfig;
+  persona: "concise" | "friendly";
+
+  // Telemetry & GitHub
+  telemetry: boolean;
+  githubCacheTtlMs: number;
+
+  // Agent Identity
+  agentId: string;              // Auto-generated UUID
+}
+```

package/docs/configuration/env-variables.md

@@ -0,0 +1,19 @@
+---
+title: "Environment Variables"
+description: "Runtime environment variables that override config."
+product: mcp
+section: configuration
+icon: Variable
+slug: env-variables
+---
+
+# Environment Variables
+
+| Variable | Description |
+|---|---|
+| `CHROME_PATH` | Absolute path to Chromium/Chrome binary |
+| `WEAVETAB_CONFIG` | Path to a custom config file |
+| `WEAVETAB_ROLE` | Override RBAC role at runtime (`admin`, `operator`, `viewer`, `automation`) |
+| `WEAVETAB_DEV` | Set to `1` to enable verbose CDP dev logging |
+| `WT_AGENT_ID` | Override the auto-generated agent UUID |
+| `WT_PROXY_URL` | Set outbound HTTP/SOCKS proxy server URL |

package/docs/configuration/folders.md

@@ -0,0 +1,54 @@
+---
+title: "Folder Hierarchy"
+description: ".weavetab, .weavetab-system, and ~/.weavetab directory structure."
+product: mcp
+section: configuration
+icon: FolderOpen
+slug: folders
+---
+
+# Workspace & System Directories
+
+Weavetab strictly partitions project-scoped output, global configurations, and system-level intelligence data into dedicated directory structures.
+
+## 1. Project-Scoped Directory: `./.weavetab/`
+
+Created in your current working directory to store project-scoped settings and mission output:
+
+```
+./.weavetab/
+├── config.json          # Project-specific config overrides
+├── secrets.json         # Project-scoped credentials for Blind Injection
+├── pdfs/                # Exported PDF documents
+├── screenshots/         # Full-page and clipped PNG/JPEG screenshots
+├── downloads/           # Downloaded files during automated sessions
+├── designs/             # Extracted design tokens and Tailwind themes
+└── logs/                # Human-readable logs and JSONL audit trails
+```
+
+## 2. System Intelligence Directory: `~/.weavetab-system/`
+
+Global system directory holding cross-session learning and process locks:
+
+```
+~/.weavetab-system/
+├── memory/                    # Per-domain frontend framework & strategy profiles
+├── sessions/
+│   └── context.json           # Rolling 50-action trail for loop detection
+├── apps/                      # Dedicated user profiles for Electron apps
+├── locks/                     # Process lockfiles (PID + TCP port validation)
+└── knowledge/                 # Domain-specific markdown knowledge hints
+```
+
+## 3. Global User Directory: `~/.weavetab/`
+
+Global user directory storing default configurations and global secrets:
+
+```
+~/.weavetab/
+├── config.json          # Global default configuration
+├── secrets.json         # Global secrets for Blind Injection
+├── policy.json          # Domain whitelist / blacklist rules
+├── plugins/             # Isolated storage directories for installed plugins
+└── profile/             # Dedicated default Chromium browser profile
+```

package/docs/desktop-automation/electron-apps.md

@@ -0,0 +1,162 @@
+---
+title: "Desktop & Electron Apps"
+description: "Native Layer 0 automation for VS Code, Discord, Figma, Slack, and any Electron app."
+product: mcp
+section: desktop-automation
+badge: new
+icon: AppWindow
+slug: electron-apps
+---
+
+# Desktop & Electron Application Automation
+
+Weavetab is a **universal Layer 0 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 & Agent Generator
+
+Use the interactive configurator below to customize your desktop applications. Select presets or add custom apps, toggle between executable path strings, remote debug ports, or advanced objects, and copy the ready-to-use JSON or an automated setup prompt for your AI coding agent:
+
+```electron-configurator
+```
+
+---
+
+## 1. Configuring Desktop Apps in `config.json`
+
+Add an `"electron"` object to your local `./.weavetab/config.json` or global `~/.weavetab/config.json`:
+
+```json
+{
+  "electron": {
+    "discord": "C:\\Users\\username\\AppData\\Local\\Discord\\app-1.0.9175\\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": [
+      { "action": "click_and_wait", "selector": ".monaco-editor" },
+      { "action": "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`.