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

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,55 @@
+---
+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 (selector cache)
+│   └── sites/                 # Persistent site profiles: workflows, quirks & reliability scores
+├── 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
+```