@weavetab/mcp 2.5.0-beta.5 → 2.5.1

package/docs/PLUGINS.md

@@ -1,121 +1,139 @@
-# Weavetab Plugin System & SDK Specification
-
-> **Version:** 2.5.0-beta.5 | **SDK:** @weavetab/sdk (MIT) | **Runtime:** AGPL-3.0-only
-
-The **Weavetab Plugin System** allows developers to extend the MCP runtime with custom tools, visual HUD overlays, thought bubbles, lifecycle hooks, and tool overrides.
-
----
-
-## 1. Quick Start
-
-### Scaffold a New Plugin
-````bash
-npx @weavetab/sdk init my-custom-plugin
-cd my-custom-plugin
-npm install
-`
-
-### Build & Compile
-````bash
-npm run build
-`
-
----
-
-## 2. Plugin Architecture
-
-Every Weavetab plugin exports a plugin definition created with definePlugin:
-
-`	ypescript
-// src/index.ts
-import { definePlugin, type PluginContext } from @weavetab/sdk;
-
-export default definePlugin({
-  name: weavetab-plugin-sample,
-  version: 1.0.0,
-  description: Sample custom tool plugin for Weavetab,
-
-  defaultConfig: {
-    enableHud: true,
-  },
-
-  async onLoad(ctx: PluginContext) {
-    // Register a custom MCP tool
-    ctx.mcp.registerTool({
-      name: custom_analyzer,
-      description: Performs custom DOM analysis,
-      schema: {
-        type: object,
-        properties: {
-          selector: { type: string, description: Target CSS selector }
-        },
-        required: [selector]
-      },
-      handler: async (args: { selector: string }, session: any) => {
-        // Show thought bubble on browser tab
-        if (ctx.config.enableHud && session) {
-          await ctx.extension.showThought(session, Analyzing ...);
-        }
-
-        return {
-          content: [
-            { type: text, text: Analysis complete for  }
-          ]
-        };
-      }
-    });
-  },
-
-  async onUnload(ctx: PluginContext) {
-    // Cleanup resources
-  }
-});
-`
-
----
-
-## 3. Manifest Specification (weavetab.json)
-
-Plugins require a weavetab.json manifest in their package root:
-
-`json
-{
-  name: weavetab-plugin-sample,
-  version: 1.0.0,
-  entry: ./dist/index.js,
-  permissions: [storage, extension, cdp],
-  tools: [custom_analyzer]
-}
-`
-
----
-
-## 4. Plugin Capabilities
-
-| Capability | API | Description |
-| :--- | :--- | :--- |
-| **Sandboxed Storage** | ctx.storage.get(), ctx.storage.set() | Isolated key-value storage in ~/.weavetab/plugins/<name>/. |
-| **Thought Bubbles** | ctx.extension.showThought(session, text) | Floating green thoughts on the live browser tab. |
-| **HUD Badges** | ctx.extension.setHudState(session, state) | Real-time status in the Weavetab overlay. |
-| **Tool Overrides** | ctx.mcp.overrideTool(name, wrapperFn) | Wrap or intercept built-in MCP tools with custom pre/post logic. |
-| **Lifecycle Hooks** | ctx.hooks.beforeToolCall, ctx.hooks.afterToolCall | Global auditing and security filters. |
-
----
-
-## 5. Installing Plugins
-
-```bash
-# Install an official plugin
-weavetab plugin add @weavetab/plugin-youtube
-
-# Install community plugins (any npm package)
-weavetab plugin add my-custom-plugin
-
-# List installed plugins
-weavetab plugin list
-
-# Remove a plugin
-weavetab plugin rm my-custom-plugin
-`
-
-Restart weavetab to load the newly installed plugin tools into the MCP server.
+# Weavetab Plugin System & SDK Specification
+
+> **Version:** 2.5.1 | **SDK:** @weavetab/sdk (MIT) | **Runtime:** AGPL-3.0-only
+
+The **Weavetab Plugin System** allows developers to extend the MCP runtime with custom tools, visual HUD overlays, thought bubbles, lifecycle hooks, and tool overrides.
+
+---
+
+## 1. Quick Start
+
+### Scaffold a New Plugin
+
+```bash
+npx @weavetab/sdk init my-custom-plugin
+cd my-custom-plugin
+npm install
+```
+
+### Build & Compile
+
+```bash
+npm run build
+```
+
+---
+
+## 2. Plugin Architecture
+
+Every Weavetab plugin exports a plugin definition created with `definePlugin`:
+
+```typescript
+// src/index.ts
+import { definePlugin, type PluginContext } from "@weavetab/sdk";
+
+export default definePlugin({
+  name: "weavetab-plugin-sample",
+  version: "1.0.0",
+  description: "Sample custom tool plugin for Weavetab",
+
+  defaultConfig: {
+    enableHud: true,
+  },
+
+  async onLoad(ctx: PluginContext) {
+    // Register a custom MCP tool
+    ctx.mcp.registerTool({
+      name: "custom_analyzer",
+      description: "Performs custom DOM analysis",
+      schema: {
+        type: "object",
+        properties: {
+          selector: { type: "string", description: "Target CSS selector" }
+        },
+        required: ["selector"]
+      },
+      handler: async (args: { selector: string }, session: any) => {
+        // Show thought bubble on the browser tab
+        if (ctx.config.enableHud && session) {
+          await ctx.extension.showThought(session, `Analyzing ${args.selector}`);
+        }
+
+        return {
+          content: [
+            { type: "text", text: `Analysis complete for ${args.selector}` }
+          ]
+        };
+      }
+    });
+  },
+
+  async onUnload(ctx: PluginContext) {
+    // Cleanup resources
+  }
+});
+```
+
+---
+
+## 3. Manifest Specification (weavetab.json)
+
+Plugins require a `weavetab.json` manifest in their package root:
+
+```json
+{
+  "$schema": "https://weavetab.dev/schema/plugin.json",
+  "name": "weavetab-plugin-sample",
+  "version": "1.0.0",
+  "entry": "dist/index.js",
+  "engines": {
+    "weavetab": "^2.5.1",
+    "node": ">=18.0.0"
+  },
+  "permissions": {
+    "extension": { "hud": true, "reason": "Displays HUD thoughts" },
+    "cdp": { "evaluate": true, "reason": "Runs DOM analysis" },
+    "tools": { "add": true, "reason": "Registers the custom_analyzer tool" }
+  },
+  "tools": [
+    {
+      "name": "custom_analyzer",
+      "description": "Performs custom DOM analysis"
+    }
+  ]
+}
+```
+
+> Registering tools at runtime via `ctx.mcp.registerTool()` requires the `permissions.tools.add` permission.
+
+---
+
+## 4. Plugin Capabilities
+
+| Capability | API | Description |
+| :--- | :--- | :--- |
+| **Sandboxed Storage** | `ctx.storage.get()`, `ctx.storage.set()` | Isolated key-value storage in `~/.weavetab/plugins/<name>/`. |
+| **Thought Bubbles** | `ctx.extension.showThought(session, text)` | Floating green thoughts on the live browser tab. |
+| **HUD Badges** | `ctx.extension.setHudState(session, state)` | Real-time status in the Weavetab overlay. |
+| **Tool Overrides** | `ctx.mcp.overrideTool(name, wrapperFn)` | Wrap or intercept built-in MCP tools with custom pre/post logic. |
+| **Lifecycle Hooks** | `ctx.hooks.beforeToolCall`, `ctx.hooks.afterToolCall` | Global auditing and security filters. |
+
+---
+
+## 5. Installing Plugins
+
+```bash
+# Install a plugin by npm package name
+weavetab plugin add my-custom-plugin
+
+# Install from a local path
+weavetab plugin add ./my-plugin
+
+# List installed plugins
+weavetab plugin list
+
+# Remove a plugin
+weavetab plugin rm my-custom-plugin
+```
+
+Restart Weavetab to load the newly installed plugin tools into the MCP server.

package/docs/TOOLS.md

@@ -1,8 +1,8 @@
 # Weavetab MCP Tool Reference
 
-> **Version:** 2.5.0-beta.5 | **Total Tools:** 42 | **Architecture:** Layer 0 Direct CDP
+> **Version:** 2.5.1 | **Total Tools:** 41 | **Architecture:** Layer 0 Direct CDP
 
-Weavetab provides 42 production-grade MCP tools organized into functional categories.
+Weavetab provides 41 production-grade MCP tools organized into functional categories.
 
 | Tool Name | Category | Description | Key Features |
 | :--- | :--- | :--- | :--- |
@@ -45,10 +45,9 @@ Weavetab provides 42 production-grade MCP tools organized into functional catego
 | `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 |
 
 ---
 
-*Auto-generated via `npm run docs:generate` on 2026-10-17.*
+*Auto-generated via `npm run docs:generate` on 2026-10-18.*

package/docs/architecture/blind-injection.md

@@ -1,83 +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"
-}
-```
+---
+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/overview.md

@@ -1,49 +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 (default) 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 |
+---
+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 (default) 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 (41 Tools)** | No | No | No |
+| **Cloud dependency** | **Zero** | Optional | Optional | Grid required |

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.