@weavetab/mcp 2.5.0 → 2.5.1

package/docs/architecture/transport.md

@@ -1,37 +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 [--port N]` | JSON-RPC 2.0 / WebSocket | Custom agents, Python/Go backends, remote daemons, n8n |
-
-## stdio (Default)
-
-The MCP client spawns Weavetab as a child process and pipes messages over stdin/stdout. No network port is opened:
-
-```json
-{
-  "mcpServers": {
-    "weavetab": {
-      "command": "weavetab"
-    }
-  }
-}
-```
-
-## WebSocket
-
-```bash
-weavetab --ws --port 3000
-```
-
-Starts the daemon on `127.0.0.1:3000` (override with `--port <n>` / `--port=<n>`). The daemon binds strictly to loopback for local security — front it with your own TLS/auth layer if exposing across a private network.
+---
+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 [--port N]` | JSON-RPC 2.0 / WebSocket | Custom agents, Python/Go backends, remote daemons, n8n |
+
+## stdio (Default)
+
+The MCP client spawns Weavetab as a child process and pipes messages over stdin/stdout. No network port is opened:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "weavetab"
+    }
+  }
+}
+```
+
+## WebSocket
+
+```bash
+weavetab --ws --port 3000
+```
+
+Starts the daemon on `127.0.0.1:3000` (override with `--port <n>` / `--port=<n>`). The daemon binds strictly to loopback for local security — front it with your own TLS/auth layer if exposing across a private network.

package/docs/cli/cli-commands.md

@@ -1,50 +1,50 @@
----
-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 --ws [--port N]` | Start the WebSocket daemon on `127.0.0.1` (default port `3000`). |
-| `weavetab --version` | Print version and exit. |
-| `weavetab config` | Launch the 6-phase interactive configuration wizard. |
-| `weavetab view` | Display the current active configuration report. Press **[R]** to view raw JSON, **[Q]** to quit. |
-| `weavetab reset` | Purge browser profiles, lockfiles, mutexes, session registries, and kill orphan browser processes. Accepts `--yes`/`-y` to skip confirmation prompts. |
-| `weavetab reload-ext` | Send a reload signal to the Weavetab browser extension via CDP `Runtime.evaluate`. |
-| `weavetab plugin <add\|browse\|search\|list\|remove\|verify>` | Manage plugins — see `weavetab plugin --help`. |
-| `weavetab skills [options]` | Install or update AI agent skills (passthrough to `@weavetab/skills`). |
-| `weavetab help` / `--help` | Show full CLI help message with all commands, flags, and environment variables. |
-
-## Secrets Management
-
-Credentials are stored in `~/.weavetab/secrets.json` (global) or `.weavetab/secrets.json` (project-scoped). Values are never echoed to the terminal.
-
-| Command | Description |
-|---|---|
-| `weavetab secrets set <KEY>` | Store a new encrypted secret. Prompts for value (hidden input) and allowed domains (comma-separated). |
-| `weavetab secrets list` | List all stored secrets (key names only, values hidden). Shows domains and last-updated timestamps. |
-| `weavetab secrets rm <KEY>` | Remove a secret by key name. |
-| `weavetab secrets init --project` | Initialize a project-scoped `.weavetab/secrets.json` file. |
-
-## Interactive TTY Menu
-
-When run without arguments in a TTY terminal, Weavetab opens an interactive keyboard-driven menu:
-
-| Key | Action |
-|---|---|
-| `[C]` | Launch the configuration wizard |
-| `[V]` | View current active configuration |
-| `[P]` | List installed Weavetab plugins |
-| `[R]` | Purge browser profiles and lockfiles |
-| `[H]` | Show help information |
-| `[G]` / `[N]` / `[W]` | Open GitHub / npm / website links |
-| `[Q]` | Exit Weavetab |
+---
+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 --ws [--port N]` | Start the WebSocket daemon on `127.0.0.1` (default port `3000`). |
+| `weavetab --version` | Print version and exit. |
+| `weavetab config` | Launch the 6-phase interactive configuration wizard. |
+| `weavetab view` | Display the current active configuration report. Press **[R]** to view raw JSON, **[Q]** to quit. |
+| `weavetab reset` | Purge browser profiles, lockfiles, mutexes, session registries, and kill orphan browser processes. Accepts `--yes`/`-y` to skip confirmation prompts. |
+| `weavetab reload-ext` | Send a reload signal to the Weavetab browser extension via CDP `Runtime.evaluate`. |
+| `weavetab plugin <add\|browse\|search\|list\|remove\|verify>` | Manage plugins — see `weavetab plugin --help`. |
+| `weavetab skills [options]` | Install or update AI agent skills (passthrough to `@weavetab/skills`). |
+| `weavetab help` / `--help` | Show full CLI help message with all commands, flags, and environment variables. |
+
+## Secrets Management
+
+Credentials are stored in `~/.weavetab/secrets.json` (global) or `.weavetab/secrets.json` (project-scoped). Values are never echoed to the terminal.
+
+| Command | Description |
+|---|---|
+| `weavetab secrets set <KEY>` | Store a new encrypted secret. Prompts for value (hidden input) and allowed domains (comma-separated). |
+| `weavetab secrets list` | List all stored secrets (key names only, values hidden). Shows domains and last-updated timestamps. |
+| `weavetab secrets rm <KEY>` | Remove a secret by key name. |
+| `weavetab secrets init --project` | Initialize a project-scoped `.weavetab/secrets.json` file. |
+
+## Interactive TTY Menu
+
+When run without arguments in a TTY terminal, Weavetab opens an interactive keyboard-driven menu:
+
+| Key | Action |
+|---|---|
+| `[C]` | Launch the configuration wizard |
+| `[V]` | View current active configuration |
+| `[P]` | List installed Weavetab plugins |
+| `[R]` | Purge browser profiles and lockfiles |
+| `[H]` | Show help information |
+| `[G]` / `[N]` / `[W]` | Open GitHub / npm / website links |
+| `[Q]` | Exit Weavetab |

package/docs/cli/cli-flags.md

@@ -1,28 +1,28 @@
----
-title: "Flags"
-description: "Global flags accepted by the CLI."
-product: mcp
-section: cli
-icon: Flag
-slug: cli-flags
----
-
-# Flags
-
-Only these flags are parsed by the CLI (`MCP/src/index.ts`). Anything else is ignored.
-
-| Flag | Type | Description |
-|---|---|---|
-| `--help` / `-h` | boolean | Show help message and exit |
-| `help` | command | Show help message and exit |
-| `--version` / `-v` | boolean | Print version and exit |
-| `--ws` | boolean | Start the WebSocket daemon instead of stdio |
-| `--port <port>` / `--port=<port>` | number | Port for the WebSocket daemon (default `3000`) |
-| `--yes` / `-y` | boolean | Skip confirmation prompt when running `weavetab reset` / `reload` |
-| `--official` / `-O` | boolean | Prefer the official `@weavetab/plugin-<name>` candidate (`plugin add`) |
-| `--community` / `-C` | boolean | Prefer the community package candidate (`plugin add`) |
-| `--refresh` | boolean | Invalidate and refresh the verified plugin cache (`plugin`) |
-| `--project` | boolean | Project-scoped secrets file (`secrets init --project`) |
-
-Notes:
-- There are no `--headless` / `--role` CLI flags. Browser headless mode and RBAC role come from `~/.weavetab/config.json` (`weavetab config` / `weavetab view`). The wizard offers `admin` / `operator` / `viewer` / `automation`.
+---
+title: "Flags"
+description: "Global flags accepted by the CLI."
+product: mcp
+section: cli
+icon: Flag
+slug: cli-flags
+---
+
+# Flags
+
+Only these flags are parsed by the CLI (`MCP/src/index.ts`). Anything else is ignored.
+
+| Flag | Type | Description |
+|---|---|---|
+| `--help` / `-h` | boolean | Show help message and exit |
+| `help` | command | Show help message and exit |
+| `--version` / `-v` | boolean | Print version and exit |
+| `--ws` | boolean | Start the WebSocket daemon instead of stdio |
+| `--port <port>` / `--port=<port>` | number | Port for the WebSocket daemon (default `3000`) |
+| `--yes` / `-y` | boolean | Skip confirmation prompt when running `weavetab reset` / `reload` |
+| `--official` / `-O` | boolean | Prefer the official `@weavetab/plugin-<name>` candidate (`plugin add`) |
+| `--community` / `-C` | boolean | Prefer the community package candidate (`plugin add`) |
+| `--refresh` | boolean | Invalidate and refresh the verified plugin cache (`plugin`) |
+| `--project` | boolean | Project-scoped secrets file (`secrets init --project`) |
+
+Notes:
+- There are no `--headless` / `--role` CLI flags. Browser headless mode and RBAC role come from `~/.weavetab/config.json` (`weavetab config` / `weavetab view`). The wizard offers `admin` / `operator` / `viewer` / `automation`.

package/docs/cli/cli-scripting.md

@@ -1,35 +1,35 @@
----
-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
-
-# List installed plugins
-weavetab plugin list
-
-# Start the MCP server in WebSocket daemon mode for custom scripts
-weavetab --ws --port 3000 &
-```
-
-## CI/CD Pipeline
-
-```bash
-# In GitHub Actions or Docker CI
-npm install -g @weavetab/mcp
-weavetab reset --yes
-weavetab --ws --port 3000 &
-```
+---
+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
+
+# List installed plugins
+weavetab plugin list
+
+# Start the MCP server in WebSocket daemon mode for custom scripts
+weavetab --ws --port 3000 &
+```
+
+## CI/CD Pipeline
+
+```bash
+# In GitHub Actions or Docker CI
+npm install -g @weavetab/mcp
+weavetab reset --yes
+weavetab --ws --port 3000 &
+```

package/docs/configuration/config-locations.md

@@ -1,23 +1,23 @@
----
-title: "Locations & Merge"
-description: "Two-tier merge: global config → built-in defaults."
-product: mcp
-section: configuration
-icon: FolderTree
-slug: config-locations
----
-
-# Config Locations & Merge Priority
-
-## Priority Tiers
-
-1. **Global** — `~/.weavetab/config.json` (the only config file Weavetab reads)
-2. **Built-in defaults** — defined in `DEFAULT_CONFIG`
-
-## Live Reload
-
-A debounced file watcher (150 ms) reloads the in-memory configuration on change. In-flight tool executions complete on the existing configuration; subsequent calls automatically pick up the new values.
-
-## Corrupt File Quarantine
-
-If a configuration file contains invalid JSON, Weavetab automatically quarantines the file to `config.broken.<timestamp>.json` and safely falls back to the next tier without crashing.
+---
+title: "Locations & Merge"
+description: "Two-tier merge: global config → built-in defaults."
+product: mcp
+section: configuration
+icon: FolderTree
+slug: config-locations
+---
+
+# Config Locations & Merge Priority
+
+## Priority Tiers
+
+1. **Global** — `~/.weavetab/config.json` (the only config file Weavetab reads)
+2. **Built-in defaults** — defined in `DEFAULT_CONFIG`
+
+## Live Reload
+
+A debounced file watcher (150 ms) reloads the in-memory configuration on change. In-flight tool executions complete on the existing configuration; subsequent calls automatically pick up the new values.
+
+## Corrupt File Quarantine
+
+If a configuration file contains invalid JSON, Weavetab automatically quarantines the file to `config.broken.<timestamp>.json` and safely falls back to the next tier without crashing.

package/docs/configuration/configuration.md

@@ -12,9 +12,15 @@ slug: configuration
 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 type DevModeConfig  = boolean;
+export type PolicyMode     = "allow" | "deny" | "audit-only" | "read-only";
+export type Role           = "admin" | "operator" | "viewer" | "automation" | "system";
+export type BrowserEngine  = "chromium" | "firefox" | "webkit";
+
+export interface PolicyEntry {
+  pattern: string;
+  mode: PolicyMode;
+}
 
 export interface ElectronAppConfig {
   path?: string;               // Absolute path to Electron app executable
@@ -25,49 +31,55 @@ export interface ElectronAppConfig {
 }
 
 export interface Config {
-  // Mode & Port
+  // Identity & Transport
   mode: "session" | "attach";
   session: string;
-  attachPort: number;
+  attachPort: number;           // 0-65535, 0 = dynamic
+  agentId: string;              // Auto-generated UUID (WT_AGENT_ID to override)
+  telemetry: boolean;
 
   // Browser Settings
-  browser: string;              // Executable path or "auto"
+  browserPath: string;          // Executable path or "auto"
   browserType: BrowserEngine;
-  profileDir: string;
   headless: boolean;
   extension: boolean;           // Enable Weavetab Chrome extension
   browserFlags: string[];
+  profileDir: string;
+  cookies: boolean;
+  syncDataAcrossBrowsers: boolean;
 
   // Desktop & Electron Applications
-  electron?: Record<string, string | number | ElectronAppConfig>;
+  apps?: Record<string, ElectronAppConfig>;
+  electron?: Record<string, ElectronAppConfig>;
 
   // Security & Policy
-  block: string[];              // Domain blocklist
+  role: Role;                   // RBAC role
+  block: string[];              // Domain blocklist (default: ["*.bank.*", "paypal.com"])
   allow: string[];              // Domain allowlist
   policies: PolicyEntry[];      // Per-domain policy modes
-  role: Role;                   // RBAC role
-  cookies: boolean;             // Allow storage & cookies
-  proxy?: string;               // Outbound proxy URL
+  proxy?: string;               // Outbound proxy URL (WT_PROXY_URL to override)
 
   // Rate Limiting & Resource Caps
-  maxActionsPerMinute: number;  // 1-600 (default 60)
+  sessionTimeout: number;       // Seconds, 60-86400 (default 3600)
+  navigationTimeout: number;    // Milliseconds, 1000-120000 (default 30000)
+  idleTimeout: number;          // Milliseconds, >= 5000 (default 60000)
+  actionabilityTimeoutMs: number; // Milliseconds, 50-15000 (default 300)
   maxTabs: number;              // 1-100 (default 10)
+  maxActionsPerMinute: number;  // 1-600 (default 60)
+  githubCacheTtlMs: number;     // Milliseconds (default 1800000)
+  refCacheTtlMs: number;        // Milliseconds (default 30000)
 
-  // Timing & Thresholds
-  sessionTimeout: number;       // Seconds (default 3600)
-  navigationTimeout: number;    // Milliseconds (default 30000)
-  idleTimeout: number;          // Milliseconds (default 15000)
-  actionabilityTimeoutMs: number; // Milliseconds (default 500)
+  // Output Directories
+  downloadDir: string;
+  pdfDir: string;
+  snapshotDir: string;
+  recordingDir: string;
+  designDir: string;
 
   // UI & Overlay
-  devMode: boolean | DevModeConfig;
-  persona: "concise" | "friendly";
-
-  // Telemetry & GitHub
-  telemetry: boolean;
-  githubCacheTtlMs: number;
-
-  // Agent Identity
-  agentId: string;              // Auto-generated UUID
+  devMode: DevModeConfig;
 }
 ```
+
+The on-disk `config.json` may also use the legacy sectioned shape (`general`, `browser`,
+`security`, `performance`); the loader migrates it to this flat interface automatically.

package/docs/configuration/env-variables.md

@@ -1,19 +1,19 @@
----
-title: "Environment Variables"
-description: "Runtime environment variables that override config."
-product: mcp
-section: configuration
-icon: Variable
-slug: env-variables
----
-
-# Environment Variables
-
-Only these two are read at runtime (`MCP/src/config/loader.ts`). Everything else
-(browser path, role, headless, dev mode) lives in `~/.weavetab/config.json`
-— run `weavetab config` to change it.
-
-| Variable | Description |
-|---|---|
-| `WT_AGENT_ID` | Override the auto-generated agent UUID |
-| `WT_PROXY_URL` | Set outbound HTTP/SOCKS proxy server URL |
+---
+title: "Environment Variables"
+description: "Runtime environment variables that override config."
+product: mcp
+section: configuration
+icon: Variable
+slug: env-variables
+---
+
+# Environment Variables
+
+Only these two are read at runtime (`MCP/src/config/loader.ts`). Everything else
+(browser path, role, headless, dev mode) lives in `~/.weavetab/config.json`
+— run `weavetab config` to change it.
+
+| Variable | Description |
+|---|---|
+| `WT_AGENT_ID` | Override the auto-generated agent UUID |
+| `WT_PROXY_URL` | Set outbound HTTP/SOCKS proxy server URL |

package/docs/configuration/folders.md

@@ -1,55 +1,62 @@
----
-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
-```
+---
+title: "Folder Hierarchy"
+description: ".weavetab and .weavetab-system directory structure."
+product: mcp
+section: configuration
+icon: FolderOpen
+slug: folders
+---
+
+# Workspace & System Directories
+
+Weavetab strictly partitions project-scoped credentials, global user configuration, and machine-managed system intelligence into dedicated directory structures.
+
+## 1. Project-Scoped Directory: `./.weavetab/`
+
+Optional, created in your current working directory to carry project-scoped credentials alongside a checkout:
+
+```
+./.weavetab/
+└── secrets.json         # Project-scoped credentials for Blind Injection (override the global file)
+```
+
+Keys in a project `secrets.json` take precedence over `~/.weavetab/secrets.json` when Weavetab runs from that directory. All other configuration and output paths are global (see below) unless overridden via config fields.
+
+## 2. Global User Directory: `~/.weavetab/`
+
+Global, user-authored configuration and default output directories:
+
+```
+~/.weavetab/
+├── config.json          # Global configuration (domain policies, roles, output paths)
+├── secrets.json         # Global secrets for Blind Injection
+├── knowledge/           # Domain-specific markdown knowledge hints
+├── plugins/             # Isolated storage directories for installed plugins
+├── downloads/           # Downloaded files (default output dir)
+├── pdfs/                # Exported PDF documents
+├── snapshots/           # Screenshots and MHTML snapshots
+├── recordings/          # Screen recordings (webp / gif / webm / mp4)
+└── designs/             # Extracted design tokens and Tailwind themes
+```
+
+Each output directory (`downloads`, `pdfs`, `snapshots`, `recordings`, `designs`) is overridable via its matching config path field.
+
+## 3. System Intelligence Directory: `~/.weavetab-system/`
+
+Machine-managed, cross-session state. Strictly separate from user configuration:
+
+```
+~/.weavetab-system/
+├── memory/                    # Per-domain selector confidence cache
+│   └── sites/                 # Persistent site profiles: workflows, quirks & reliability scores
+├── sessions/
+│   └── context.json           # Rolling action trail for loop detection
+├── checkpoints/               # Named browser-state checkpoints
+├── missions/                  # Mission state files
+├── apps/                      # Dedicated isolated profiles for Electron apps
+├── extension/                 # Installed browser extension build
+├── logs/                      # Mission logs: mission_<timestamp>.log / .jsonl (devMode only)
+├── locks/                     # Process lockfiles (PID + TCP port validation)
+├── secrets-key                # Local key used to encrypt stored secrets
+└── session-profile*/          # Isolated Chromium browser profiles (never your real profile)
+```