web-agent-bridge 1.0.0 → 1.1.0

package/README.ar.md

@@ -276,7 +276,7 @@ docker compose up -d
 
 # أو البناء يدوياً
 docker build -t web-agent-bridge .
-docker run -p 3000:3000 -e JWT_SECRET=your-secret web-agent-bridge
+docker run -p 3000:3000 -e JWT_SECRET=your-secret -e JWT_SECRET_ADMIN=your-admin-secret web-agent-bridge
 ```
 
 ---

package/README.md

@@ -1,38 +1,117 @@
 # Web Agent Bridge (WAB)
 
+[![npm](https://img.shields.io/npm/v/web-agent-bridge)](https://www.npmjs.com/package/web-agent-bridge)
 [![CI](https://github.com/abokenan444/web-agent-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/abokenan444/web-agent-bridge/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
 [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://hub.docker.com/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![Socket](https://img.shields.io/badge/Socket-Verified-brightgreen.svg)](https://socket.dev/npm/package/web-agent-bridge)
 
-**Open-source middleware that bridges AI agents and websites — providing a standardized command interface for intelligent automation.**
+> **robots.txt told bots what NOT to do. WAB tells AI agents what they CAN do.**
 
-**English** | **[العربية](README.ar.md)**
+**English** | **[العربية](README.ar.md)** | **[Protocol Spec](docs/SPEC.md)** | **[Socket Report](https://socket.dev/npm/package/web-agent-bridge)**
 
-WAB gives website owners a script they embed in their pages that exposes a `window.AICommands` interface. AI agents read this interface to discover available actions, execute commands, and interact with sites accurately — without parsing raw DOM.
+WAB is an **open protocol + runtime** for AI agents to interact with websites — the **OpenAPI for human-facing pages**. It provides a standardized discovery format (`agent-bridge.json`), a command protocol, and a fairness layer that ensures small businesses get equal visibility alongside large platforms.
+
+WAB transforms websites from opaque HTML into **agent-readable endpoints** with declared capabilities, permissions, and actions. AI agents discover what a site offers, authenticate, and execute commands through a uniform protocol — no DOM scraping, no guesswork, no bias toward big brands.
+
+### Architecture: Protocol + Runtime + Ecosystem
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    WAB Protocol (Spec)                    │
+│  agent-bridge.json · Commands · Lifecycle · Fairness     │
+├────────────┬───────────────────┬─────────────────────────┤
+│ JS Runtime │  HTTP Transport   │  MCP Adapter            │
+│ AICommands │  REST + WebSocket │  WAB → MCP Tools        │
+├────────────┴───────────────────┴─────────────────────────┤
+│               Discovery Registry + Fairness Engine       │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Three Paths to WAB
+
+| Path | For | How |
+|---|---|---|
+| **🏢 Website Owner** | Control how AI interacts with your site | Embed the script, publish `agent-bridge.json` |
+| **🤖 Agent Developer** | Build reliable agents that work on any WAB-enabled site | Use `window.AICommands`, the Agent SDK, or the MCP Adapter |
+| **🔧 Self-Hosting** | Run the full WAB platform for your organization | Clone, deploy, manage licenses & analytics |
+| **🔌 MCP Integration** | Connect WAB to Claude, GPT, or any MCP-compatible agent | Use `wab-mcp-adapter` |
+| **WordPress** | Sites powered by WP | Use the **[Web Agent Bridge WordPress plugin](web-agent-bridge-wordpress/README.md)** |
+
+---
+
+## What's New in v1.1.0
+
+- **WAB Protocol Specification v1.0** — Formal protocol spec (`docs/SPEC.md`) with discovery format, command protocol, lifecycle, and fairness layer
+- **Discovery Protocol** — Sites publish `agent-bridge.json` or `/.well-known/wab.json` for agent discovery
+- **MCP Adapter** — `wab-mcp-adapter` converts WAB actions into MCP tools for Claude/GPT integration
+- **Fairness Engine** — Neutrality layer ensures equal visibility for small businesses and independent sites
+- **Discovery Registry** — Public searchable directory of WAB-enabled sites with fairness-weighted results
+- **9 Protocol Commands** — `wab.discover`, `wab.getContext`, `wab.getActions`, `wab.executeAction`, `wab.readContent`, `wab.getPageInfo`, `wab.authenticate`, `wab.subscribe`, `wab.ping`
 
 ---
 
 ## Features
 
+### Protocol Layer
+- **WAB Specification v1.0** — Formal protocol spec defining discovery, commands, lifecycle, and fairness ([docs/SPEC.md](docs/SPEC.md))
+- **Discovery Protocol** — Sites declare capabilities via `agent-bridge.json` or `/.well-known/wab.json`
+- **Command Protocol** — 9 standard methods with request/response format (transport-agnostic)
+- **Lifecycle Protocol** — Discover → Authenticate → Plan → Execute → Confirm
+- **MCP Compatibility** — Full adapter for Model Context Protocol (Claude, GPT, LangChain)
+
+### Fairness & Neutrality
+- **Fairness Engine** — Neutrality scoring ensures small businesses get equal agent visibility
+- **Discovery Registry** — Public directory of WAB-enabled sites with anti-bias ranking
+- **Commission Transparency** — Sites declare commission rates; agents can favor direct providers
+- **Independent Business Priority** — Self-declared independent sites get fairness scoring boost
+
+### Runtime
 - **Auto-Discovery** — Automatically detects buttons, forms, and navigation on the page
 - **Permission System** — Granular control over what AI agents can do (click, fill forms, API access, etc.)
 - **Standardized Interface** — Unified `window.AICommands` object any agent can consume
-- **Rate Limiting** — Built-in abuse protection with configurable limits
+- **Self-Healing Selectors** — Resilient element resolution with 7-strategy fuzzy matching for SPAs
+- **Security Sandbox** — Origin validation, session tokens, command signing, audit logging, auto-lockdown
+- **Stealth Mode** — Human-like interaction patterns (requires explicit consent)
+- **NoJS Fallback** — CSS tracking, pixel tracking, and SSR bridge for JavaScript-disabled environments
+
+### Infrastructure
+- **Secure License Exchange** — Embed uses `siteId` + token exchange; keys stay in the dashboard
+- **Rate Limiting** — Multi-dimensional abuse protection (IP + license key + site)
 - **Analytics Dashboard** — Track how AI agents interact with your site
-- **Real-Time Analytics** — WebSocket-based live event streaming for Enterprise users
+- **Real-Time Analytics** — WebSocket-based live event streaming with auto-reconnection
 - **WebDriver BiDi Compatible** — Standard protocol support via `window.__wab_bidi`
 - **CDN Versioning** — Serve scripts via versioned URLs (`/v1/ai-agent-bridge.js`, `/latest/ai-agent-bridge.js`)
 - **Docker Ready** — One-command deployment with Docker Compose
-- **Custom Actions** — Register your own actions with custom handlers
-- **Subscription Tiers** — Free core + paid premium features (API access, analytics, automated login)
-- **Event System** — Subscribe to bridge events for monitoring
-- **Security Sandbox** — Origin validation, session tokens, command signing, audit logging, auto-lockdown
-- **Self-Healing Selectors** — Resilient element resolution with fuzzy matching for dynamic SPAs
-- **Stealth Mode** — Human-like interaction patterns (mouse events, typing delays, natural scrolling)
 - **Multi-Database** — SQLite (default), PostgreSQL, MySQL via pluggable adapters
 - **Agent SDK** — Built-in SDK for building AI agents with Puppeteer/Playwright
+- **Admin Dashboard** — User management, tier grants, system analytics
+- **Stripe Integration** — Payment processing with customer portal
+
+---
+
+## Premium Services (webagentbridge.com)
+
+The open-source core is free forever. For teams and businesses that need more, **[webagentbridge.com](https://webagentbridge.com/premium)** offers paid add-ons and higher-tier plans:
+
+| # | Service | Plans |
+|---|---------|-------|
+| 1 | **Agent Traffic Intelligence** — Deep analytics: agent type, platform, country, behavioral classification, anomaly alerts | Starter+ |
+| 2 | **Advanced Exploit Shield** — Behavioral fingerprint blocking, unauthorized command detection, periodic security reports | Pro+ |
+| 3 | **Pre-built Smart Actions Library** — Ready-made action packs for WooCommerce, Shopify, WordPress, Salesforce with auto-updates | Starter+ |
+| 4 | **Custom AI Agents as a Service** — Visual agent builder, task scheduling, cloud-based execution | Pro+ |
+| 5 | **CRM & Cloud Integrations** — Salesforce, HubSpot, Zoho; export to BigQuery/Snowflake/Datadog; custom webhooks | Pro+ |
+| 6 | **Multi-Tenant Permission Management** — Sub-users, per-user quotas, central control panel for agencies | Enterprise |
+| 7 | **AI-Powered Priority Support** — Smart chatbot, live video sessions, SLA from 15 min (Enterprise) to same-day (Starter) | Starter+ |
+| 8 | **Custom Bridge Script** — Plugin-based custom actions, performance optimization, automatic zero-day patches | Pro+ |
+| 9 | **Stealth Mode Pro** — Customizable human-like behavior profiles, anti-detection bypass, monthly fingerprint updates | Pro+ |
+| 10 | **Private CDN** — Global edge network, custom domain (`bridge.yoursite.com`), geo performance stats | Pro+ |
+| 11 | **Extended Audit Logs & Compliance** — 7-year retention, HIPAA/GDPR/SOC2 settings, signed PDF/CSV exports | Enterprise |
+| 12 | **Virtual Sandbox Environment** — Isolated test environment, simulated agent traffic, before/after benchmarks | Enterprise |
+
+Plans: **Free** (open source) → **Starter $9/mo** → **Pro $29/mo** → **Enterprise (custom)**. Visit [webagentbridge.com/premium](https://webagentbridge.com/premium) for details.
 
 ---
 
@@ -62,9 +141,11 @@ Visit `http://localhost:3000/register` and create an account, then add your site
 ### 3. Add the Script to Your Website
 
 ```html
+<!-- Recommended: copy the snippet from your dashboard (uses siteId only) -->
 <script>
 window.AIBridgeConfig = {
-  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
+  siteId: "your-site-uuid-from-dashboard",
+  configEndpoint: "https://yourserver.com/api/license/token",
   agentPermissions: {
     readContent: true,
     click: true,
@@ -73,9 +154,11 @@ window.AIBridgeConfig = {
   }
 };
 </script>
-<script src="http://localhost:3000/script/ai-agent-bridge.js"></script>
+<script src="https://yourserver.com/script/ai-agent-bridge.js"></script>
 ```
 
+The server matches **Origin** to your registered site domain, then returns a short-lived **session token**. Analytics (`/api/license/track`) require that session — not the long-lived license key. Keep the license key in the dashboard only.
+
 ### 4. AI Agents Can Now Interact
 
 ```javascript
@@ -88,29 +171,173 @@ const info = bridge.getPageInfo();          // get page metadata
 
 ---
 
+## Discovery Protocol (`agent-bridge.json`)
+
+Any website can declare its WAB capabilities by serving a discovery document at `/agent-bridge.json` or `/.well-known/wab.json`. AI agents fetch this file to understand what a site offers before interacting.
+
+```json
+{
+  "wab_version": "1.0",
+  "provider": {
+    "name": "Local Bookshop",
+    "domain": "localbookshop.com",
+    "category": "e-commerce",
+    "description": "Independent bookshop"
+  },
+  "capabilities": {
+    "commands": ["readContent", "click", "fillForms"],
+    "permissions": { "readContent": true, "click": true, "fillForms": true },
+    "tier": "starter",
+    "transport": ["js_global", "http"]
+  },
+  "agent_access": {
+    "bridge_script": "/script/ai-agent-bridge.js",
+    "api_base": "/api/license",
+    "selectors": { "search": "#search-input", "cart": ".add-to-cart" }
+  },
+  "fairness": {
+    "is_independent": true,
+    "commission_rate": 0,
+    "direct_benefit": "Owner is the producer",
+    "neutrality_score": 85
+  },
+  "security": {
+    "session_required": true,
+    "origin_validation": true,
+    "rate_limit": 60,
+    "sandbox": true
+  }
+}
+```
+
+WAB servers auto-generate this document from each site's configuration. No manual file creation needed — register your site and the discovery endpoint is live.
+
+### Discovery API Endpoints
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/.well-known/wab.json` | GET | Discovery document (domain-matched) |
+| `/agent-bridge.json` | GET | Alternative discovery location |
+| `/api/discovery/:siteId` | GET | Discovery document for a specific site |
+| `/api/discovery/registry` | GET | Public directory of WAB-enabled sites |
+| `/api/discovery/search` | GET | Fairness-weighted site search |
+| `/api/discovery/register` | POST | Register site in directory (authenticated) |
+
+---
+
+## MCP Adapter (Model Context Protocol)
+
+The `wab-mcp-adapter` converts WAB capabilities into MCP tools, so Claude, GPT, LangChain, or any MCP-compatible agent can interact with WAB-enabled sites.
+
+```javascript
+const { WABMCPAdapter } = require('web-agent-bridge/wab-mcp-adapter');
+
+const adapter = new WABMCPAdapter({
+  siteUrl: 'https://example.com',
+  transport: 'http'
+});
+
+// Discover site capabilities
+const discovery = await adapter.discover();
+
+// Get all available MCP tools
+const tools = await adapter.getTools();
+// → [{ name: 'wab_discover', ... }, { name: 'wab_click_signup', ... }, ...]
+
+// Execute a tool (just like any MCP tool call)
+const result = await adapter.executeTool('wab_execute_action', {
+  name: 'signup',
+  data: { email: 'user@test.com' }
+});
+```
+
+### Built-in MCP Tools
+
+| Tool | Description |
+|---|---|
+| `wab_discover` | Discover site capabilities and fairness data |
+| `wab_get_actions` | List all available actions |
+| `wab_execute_action` | Execute any action by name |
+| `wab_read_content` | Read page content by CSS selector |
+| `wab_get_page_info` | Get page metadata and bridge status |
+| `wab_fairness_search` | Search WAB registry with fairness-weighted results |
+| `wab_authenticate` | Authenticate with a WAB site |
+
+See [`wab-mcp-adapter/README.md`](wab-mcp-adapter/README.md) for the full API reference.
+
+---
+
+## Fairness Engine
+
+WAB includes a **Neutrality Layer** — a fairness engine that prevents AI agents from systematically favoring large platforms over small businesses.
+
+### How It Works
+
+1. **Neutrality Scoring** — Each site gets a score (0-100) based on config quality, trust signatures, and commission transparency — not brand recognition
+2. **Anti-Bias Ranking** — Search results are fairness-weighted: independent businesses get +15%, transparent commission sites get +10%
+3. **Position Rotation** — Top results are shuffled to prevent position lock-in
+4. **Monopoly Prevention** — No single provider can dominate more than 30% of top results
+
+### Register Your Site
+
+```bash
+# Register in the WAB discovery directory
+curl -X POST https://yourserver.com/api/discovery/register \
+  -H "Authorization: Bearer YOUR_JWT" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "siteId": "your-site-uuid",
+    "category": "e-commerce",
+    "is_independent": true,
+    "commission_rate": 0,
+    "direct_benefit": "Products from local artisans",
+    "tags": ["handmade", "local", "organic"]
+  }'
+```
+
+---
+
 ## Project Structure
 
 ```
 web-agent-bridge/
+├── docs/
+│   └── SPEC.md             # WAB Protocol Specification v1.0
 ├── server/                 # Express.js backend
 │   ├── index.js            # Server entry point
 │   ├── routes/
 │   │   ├── auth.js         # Authentication (register/login)
 │   │   ├── api.js          # Sites, config, analytics API
-│   │   └── license.js      # License verification & tracking
+│   │   ├── license.js      # License verification & token exchange
+│   │   ├── discovery.js    # Discovery protocol endpoints
+│   │   ├── noscript.js     # NoJS fallback (pixel, CSS, SSR)
+│   │   ├── admin.js        # Admin dashboard API
+│   │   └── billing.js      # Stripe billing integration
+│   ├── services/
+│   │   └── fairness.js     # Fairness engine & neutrality layer
 │   ├── middleware/
 │   │   └── auth.js         # JWT authentication middleware
-│   └── models/
-│       └── db.js           # SQLite database & operations
+│   ├── models/
+│   │   └── db.js           # SQLite database & operations
+│   ├── migrations/         # Numbered SQL migrations
+│   └── utils/
+│       ├── cache.js        # In-memory cache + analytics queue
+│       └── migrate.js      # Migration runner
+├── wab-mcp-adapter/        # MCP adapter for WAB → Claude/GPT
+│   ├── index.js            # WABMCPAdapter class
+│   ├── package.json
+│   └── README.md
 ├── public/                 # Frontend
 │   ├── index.html          # Landing page
 │   ├── dashboard.html      # Management dashboard
 │   ├── docs.html           # Documentation
-│   ├── login.html          # Sign in
-│   ├── register.html       # Sign up
+│   ├── admin/              # Admin panel
+│   ├── js/                 # Client-side utilities
 │   └── css/styles.css      # Design system
 ├── script/
 │   └── ai-agent-bridge.js  # The bridge script (embed in websites)
+├── examples/               # Agent examples (Puppeteer, BiDi, MCP, Vision)
+├── sdk/                    # Agent SDK for Puppeteer/Playwright
 ├── .env                    # Environment variables
 └── package.json
 ```
@@ -141,8 +368,20 @@ web-agent-bridge/
 ### License (Public)
 | Endpoint | Method | Description |
 |---|---|---|
-| `/api/license/verify` | POST | Verify license key for domain |
-| `/api/license/track` | POST | Record analytics event |
+| `/api/license/verify` | POST | Verify license key for domain (cached) |
+| `/api/license/token` | POST | Exchange `siteId` (Origin must match domain) or `licenseKey` for session token |
+| `/api/license/session` | POST | Validate session token (domain-locked) |
+| `/api/license/track` | POST | Record analytics (`sessionToken` + Origin; legacy `licenseKey` only if `ALLOW_LEGACY_LICENSE_TRACK`) |
+
+### Discovery Protocol (Public)
+| Endpoint | Method | Description |
+|---|---|---|
+| `/.well-known/wab.json` | GET | Discovery document for the requesting domain |
+| `/agent-bridge.json` | GET | Alternative discovery location |
+| `/api/discovery/:siteId` | GET | Discovery document for a specific site |
+| `/api/discovery/registry` | GET | Public directory of WAB-enabled sites |
+| `/api/discovery/search?q=&category=` | GET | Fairness-weighted site search |
+| `/api/discovery/register` | POST | Register site in directory (authenticated) |
 
 ---
 
@@ -152,18 +391,22 @@ Once loaded, `window.AICommands` exposes:
 
 | Method | Description |
 |---|---|
+| `discover()` | Get full discovery document with protocol info and fairness data |
+| `ping()` | Health check — returns version, protocol, ready state |
 | `getActions(category?)` | List available actions |
 | `getAction(name)` | Get a specific action |
 | `execute(name, params?)` | Execute an action |
 | `readContent(selector)` | Read element content |
 | `getPageInfo()` | Get page and bridge metadata |
+| `subscribe(event, callback)` | Subscribe to events with subscription ID |
+| `unsubscribe(subscriptionId)` | Unsubscribe from events |
 | `waitForElement(selector, timeout?)` | Wait for DOM element |
 | `waitForNavigation(timeout?)` | Wait for URL change |
 | `registerAction(def)` | Register a custom action |
 | `authenticate(key, meta?)` | Authenticate an agent |
 | `refresh()` | Re-scan the page |
 | `onReady(callback)` | Callback when bridge is ready |
-| `events.on(event, cb)` | Subscribe to events |
+| `events.on(event, cb)` | Subscribe to raw events |
 
 ---
 
@@ -171,7 +414,13 @@ Once loaded, `window.AICommands` exposes:
 
 ```javascript
 window.AIBridgeConfig = {
-  licenseKey: "WAB-XXXXX-XXXXX-XXXXX-XXXXX",
+  // Recommended — copy siteId from dashboard snippet (no license key in HTML)
+  siteId: "uuid-from-dashboard",
+  configEndpoint: "/api/license/token",
+
+  // Legacy: token exchange via license key (avoid embedding in public pages)
+  // licenseKey: "WAB-...",
+
   agentPermissions: {
     readContent: true,      // Read page text
     click: true,            // Click elements
@@ -213,12 +462,19 @@ window.AIBridgeConfig = {
 
 ## Tech Stack
 
+- **Protocol**: WAB Specification v1.0 with RFC 2119 conformance levels
 - **Backend**: Node.js + Express + WebSocket (ws)
-- **Database**: SQLite (via better-sqlite3)
-- **Auth**: JWT + bcrypt
+- **Database**: SQLite (via better-sqlite3) with migration runner
+- **Auth**: JWT + bcrypt + session tokens (domain-locked)
+- **MCP**: WAB-to-MCP adapter for Claude, GPT, LangChain integration
+- **Fairness**: Neutrality engine with anti-bias ranking and monopoly prevention
+- **Discovery**: Auto-generated `agent-bridge.json` + public registry
+- **Caching**: In-memory TTL cache + batched analytics queue
+- **Payments**: Stripe integration with billing portal
 - **Frontend**: Vanilla HTML/CSS/JS (no framework dependencies)
-- **Security**: Helmet, CORS, CSP, rate limiting
+- **Security**: Helmet, CORS, CSP, multi-layer rate limiting, sandbox
 - **Containers**: Docker + Docker Compose
+- **CI/CD**: GitHub Actions (test + auto-publish to npm)
 - **Testing**: Jest + Supertest
 
 ---
@@ -239,16 +495,28 @@ const result = await window.__wab_bidi.send({
 });
 
 // Supported methods:
-// wab.getContext, wab.getActions, wab.executeAction, wab.readContent, wab.getPageInfo
+// wab.discover, wab.getContext, wab.getActions, wab.executeAction,
+// wab.readContent, wab.getPageInfo, wab.authenticate, wab.subscribe, wab.ping
 ```
 
 ---
 
 ## Real-Time Analytics (WebSocket)
 
-Connect to `ws://localhost:3000/ws/analytics` for live analytics:
+Connect to `ws://localhost:3000/ws/analytics` for live analytics. Use the built-in `WABWebSocket` client for automatic reconnection with exponential backoff:
+
+```javascript
+// Recommended: use the auto-reconnecting client
+import { WABWebSocket } from './js/ws-client.js';
+
+const ws = new WABWebSocket('jwt-token', 'site-id');
+ws.on('analytic', (data) => console.log(data));
+ws.on('reconnecting', ({ attempt, delay }) => console.log(`Reconnecting #${attempt}...`));
+ws.connect();
+```
 
 ```javascript
+// Or connect manually
 const ws = new WebSocket('ws://localhost:3000/ws/analytics');
 ws.onopen = () => ws.send(JSON.stringify({ type: 'auth', token: 'jwt-token', siteId: 'site-id' }));
 ws.onmessage = (e) => console.log(JSON.parse(e.data));
@@ -321,7 +589,7 @@ docker compose up -d
 
 # Or build manually
 docker build -t web-agent-bridge .
-docker run -p 3000:3000 -e JWT_SECRET=your-secret web-agent-bridge
+docker run -p 3000:3000 -e JWT_SECRET=your-secret -e JWT_SECRET_ADMIN=your-admin-secret web-agent-bridge
 ```
 
 ---
@@ -364,11 +632,13 @@ Ready-to-run agent examples in the [`examples/`](examples/) directory:
 |---|---|
 | `puppeteer-agent.js` | Basic agent using Puppeteer + `window.AICommands` |
 | `bidi-agent.js` | Agent using WebDriver BiDi protocol via `window.__wab_bidi` |
-| `vision-agent.js` | Vision/NLP agent — resolves natural language intents to actions |
+| `mcp-agent.js` | MCP adapter demo — WAB actions as MCP tools for Claude/GPT |
+| `vision-agent.js` | Vision/NLP agent — resolves natural language intents to actions using a local keyword-based resolver (no external API) |
 
 ```bash
 node examples/puppeteer-agent.js http://localhost:3000
 node examples/bidi-agent.js http://localhost:3000
+node examples/mcp-agent.js http://localhost:3000
 node examples/vision-agent.js http://localhost:3000
 ```
 
@@ -409,6 +679,23 @@ See [`server/models/adapters/`](server/models/adapters/) for adapter implementat
 
 WAB implements defense-in-depth to protect the bridge from misuse:
 
+### Secure License Exchange
+
+1. **Dashboard snippet (recommended):** `siteId` + `configEndpoint`. The browser sends `POST /api/license/token` with `{ siteId }`; the server checks **Origin** against the site’s registered domain and issues a session token.
+2. **Legacy:** `licenseKey` + `configEndpoint` (or deprecated `_licenseKey`) still works for token exchange but should not be embedded in public HTML.
+3. **Session** is domain-locked (1h TTL); **analytics** use `sessionToken` on `POST /api/license/track` (not the license key).
+4. **WebSocket** `/ws/analytics`: user JWT must **own** the `siteId`; admin JWT may observe any site.
+
+```
+Client                          Server
+  │── POST /api/license/token ──→│  { siteId } + Origin header
+  │                              │  domain match → sessionToken
+  │←── { sessionToken, tier } ──│
+  │── POST /api/license/track ─→│  { sessionToken, actionName } + Origin
+```
+
+**Production:** set `JWT_SECRET`, `JWT_SECRET_ADMIN`, `STRIPE_WEBHOOK_SECRET`, `ALLOWED_ORIGINS`, and create the first admin via `BOOTSTRAP_ADMIN_*` or `node scripts/create-admin.js`.
+
 ### Security Sandbox
 
 Every bridge instance runs inside a `SecuritySandbox` that provides:
@@ -487,14 +774,19 @@ Add `data-wab-id` attributes to critical elements for maximum stability:
 
 ## Stealth Mode
 
-For sites with anti-bot protection, WAB can simulate human-like interaction patterns:
+For sites with anti-bot protection, WAB can simulate human-like interaction patterns. **Stealth mode requires explicit consent** to ensure ethical use.
 
 ```javascript
 window.AIBridgeConfig = {
-  stealth: { enabled: true }
+  stealth: {
+    enabled: true,
+    consent: true  // Required — confirms site owner authorizes human-like patterns
+  }
 };
 ```
 
+> **⚠️ Ethical Use Policy:** Stealth mode is designed for accessibility and testing on your own websites. Using it to bypass security controls on sites you do not own may violate terms of service and applicable laws.
+
 When enabled, all interactions use:
 
 | Feature | Description |
@@ -505,8 +797,8 @@ When enabled, all interactions use:
 | **Random delays** | 50-400ms natural pauses between actions |
 
 ```javascript
-// Enable/disable at runtime
-bridge.stealth.enable();
+// Enable/disable at runtime (consent required)
+bridge.stealth.enable(true);   // true = consent granted
 bridge.stealth.disable();
 ```
 
@@ -529,14 +821,22 @@ npx web-agent-bridge init
 
 ## Environment Variables
 
+See `.env.example`. Important:
+
 ```
 PORT=3000
-JWT_SECRET=your-secret-here
 NODE_ENV=development
-DB_ADAPTER=sqlite          # sqlite | postgresql | mysql
-DATABASE_URL=              # Required for postgresql/mysql
+JWT_SECRET=long-random-user-signing-secret
+JWT_SECRET_ADMIN=long-random-admin-signing-secret   # required in production
+ALLOWED_ORIGINS=http://localhost:3000,https://your-app.com
+STRIPE_WEBHOOK_SECRET=whsec_...                     # Stripe webhook verify
+CREDENTIALS_ENCRYPTION_KEY=...                      # optional SMTP password encryption
+DB_ADAPTER=sqlite
+DATABASE_URL=
 ```
 
+First admin: set `BOOTSTRAP_ADMIN_EMAIL` / `BOOTSTRAP_ADMIN_PASSWORD` when the `admins` table is empty, or run `node scripts/create-admin.js <email> <password>`.
+
 ---
 
 ## License