Integration tests and clean up of zed and parsing (#366)

* copy over integration tests

* integration tests and clean up

* demos

* videos in docs

* fix: address PR review comments

- Fix memory leak: clear seenMessageIds Set in stop() method
- Fix channel message ID collisions: use randomUUID() instead of Date.now()
- Fix default export in utils/index.js: use direct imports instead of await import
- Fix template literal issues in mcp/06-mcp-connect.js
- Disable task-queue.test.js which imports non-existent modules

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use bounded CircularDedupeCache for message deduplication

Replace unbounded Set with CircularDedupeCache (capacity 2000) to prevent
memory leak in long-running ACP bridge sessions. The cache automatically
evicts oldest entries when capacity is reached, matching the SDK behavior.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: prevent message misrouting and bound pending queue

- Drop threaded messages when target session is closed instead of
  misrouting them to all sessions
- Bound the __pending__ queue to 500 messages to prevent unbounded
  memory growth before first ACP session is created

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: use template literals for CLI variable interpolation in 08-mcp-receive.js

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: prevent pending message loss and race conditions

- Stream existing buffered messages to user before clearing in bridgeToRelay()
  to prevent pending messages from being discarded
- Remove duplicate __pending__ drain from prompt() to avoid race conditions
  in multi-session scenarios (e.g., multiple Zed windows)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: only drop threaded messages for known closed sessions

Track closed session IDs separately so we can distinguish between:
- Threads that match closed ACP sessions (should be dropped)
- Arbitrary thread names like "code-review" (should be broadcast)

This prevents silently dropping legitimate threaded messages that
use relay's general thread feature rather than ACP session IDs.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Agent Relay <agent@agent-relay.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

README.md

@@ -45,7 +45,7 @@ Navigate to **http://localhost:3888** to:
 | `agent-relay up` | Start daemon + dashboard |
 | `agent-relay down` | Stop daemon |
 | `agent-relay status` | Check daemon status |
-| `agent-relay create-agent -n Name <cmd>` | Create a named agent |
+| `agent-relay spawn <name> <cli> "task"` | Spawn a worker agent |
 | `agent-relay bridge <projects...>` | Bridge multiple projects |
 | `agent-relay doctor` | Diagnose issues |
 
@@ -63,11 +63,19 @@ Define roles by adding markdown files to your project:
 └── designer.md      # UI/UX
 ```
 
-Names automatically match roles (case-insensitive):
+Names automatically match roles (case-insensitive). Create agents using either method:
+
+**Option A: Dashboard (recommended for interactive use)**
+1. Open http://localhost:3888
+2. Click "Spawn Agent"
+3. Enter name "Lead" and select CLI "claude"
+
+**Option B: CLI (for scripting/automation)**
 ```bash
-agent-relay create-agent -n Lead claude    # Uses lead.md
+agent-relay spawn Lead claude "Your task instructions"
 ```
-Agents spawned by that name in the dashboard automatically assume that role.
+
+Agents with matching names automatically assume the corresponding role from your `.claude/agents/` directory.
 
 ## MCP Server
 

docs/architecture/storage.md

@@ -4,9 +4,9 @@ This describes the adapter stack, fallback behavior, and data policies.
 
 ## Components
 - **createStorageAdapter**: Factory that selects an adapter based on config/env and handles fallbacks.
-- **SQLite adapter**: Primary durable store (WAL-enabled, 7d retention default); tries `better-sqlite3` first, then `node:sqlite` (Node 22+).
+- **JSONL adapter**: Default durable store; file-based append-only log (`.agent-relay/messages/YYYY-MM-DD.jsonl`, sessions in `.agent-relay/sessions.jsonl`). Zero native dependencies.
+- **SQLite adapter**: Optional durable store (WAL-enabled, 7d retention default); tries `better-sqlite3` first, then `node:sqlite` (Node 22+).
 - **Batched SQLite adapter**: Wraps SQLite for higher write throughput via buffered flushes.
-- **JSONL adapter**: File-based append-only log (`.agent-relay/messages/YYYY-MM-DD.jsonl`, sessions in `.agent-relay/sessions.jsonl`) used when SQLite native modules fail or are blocked.
 - **Memory adapter**: Volatile fallback to keep the daemon running when persistence fails.
 
 ## Fallback Chain
@@ -16,32 +16,28 @@ Config/env ──┐
       createStorageAdapter
              |
              v
-    SQLite (default)
-      ├─ better-sqlite3
-      └─ node:sqlite (Node 22+)
+    JSONL (default)
+      └─ .agent-relay/messages/*.jsonl
              |
      (failure to init)
              v
- SQLite (batched) [opt-in]
+ SQLite [opt-in via AGENT_RELAY_STORAGE_TYPE=sqlite]
       ├─ better-sqlite3
-      └─ node:sqlite
-             |
-     (failure to init)
-             v
- JSONL (append-only)
+      └─ node:sqlite (Node 22+)
              |
      (failure to init)
              v
        Memory (volatile)
 ```
 Notes:
-- Current behavior: SQLite (better-sqlite3 → node:sqlite) → JSONL → Memory if native modules or permissions break persistence.
-- Each fallback logs the failure reason and a fix hint (upgrade Node or rebuild native deps).
+- Current behavior: JSONL (default) → Memory if filesystem write fails.
+- SQLite available via `AGENT_RELAY_STORAGE_TYPE=sqlite` for low-latency query needs.
+- Each fallback logs the failure reason and a fix hint.
 
 ## When to Use Each Adapter
-- **SQLite**: Default for durability and low latency; use whenever native modules are available.
+- **JSONL**: Default for durability with zero native dependencies; append-only per-day files.
+- **SQLite**: Low-latency queries; use when you need faster reads or complex queries.
 - **SQLite (batched)**: High-volume message bursts; tolerates small window of risk during batch flush.
-- **JSONL**: Environments where native builds are blocked but disk is available; append-only per-day files.
 - **Memory**: Tests, ephemeral runs, or emergency operation when persistence is broken.
 
 ## Performance Characteristics

docs/concepts.mdx

@@ -46,7 +46,10 @@ Agent names are case-insensitive identifiers used for routing messages:
 
 ```bash
 # These all refer to the same agent
-agent-relay create-agent -n Alice claude
+# Via dashboard: Spawn Agent → Name: "Alice", CLI: "claude"
+# Or via CLI: agent-relay spawn Alice claude "Task description"
+
+# All these message targets are equivalent:
 ->relay:alice Hello!
 ->relay:ALICE Hello!
 ```
@@ -152,7 +155,7 @@ The daemon is the central message broker that routes all communication between a
 
 - **Agent Registry** - Tracks connected agents and their connections
 - **Message Routing** - Delivers messages to the correct recipients
-- **Storage** - Persists message history to SQLite
+- **Storage** - Persists message history (JSONL by default, SQLite available)
 - **Dashboard API** - Provides real-time data to the web dashboard
 
 ### Architecture
@@ -166,7 +169,7 @@ The daemon is the central message broker that routes all communication between a
          |                   |                   |
 +--------v--------+ +--------v--------+ +--------v--------+
 |     Router      | |     Storage     | |   Dashboard     |
-| (Message        | | (SQLite         | | (WebSocket +    |
+| (Message        | | (JSONL/SQLite   | | (WebSocket +    |
 |  routing)       | |  persistence)   | |  REST API)      |
 +-----------------+ +-----------------+ +-----------------+
 ```
@@ -219,7 +222,7 @@ Projects are identified by looking for markers in the directory tree:
 Each project gets its own:
 
 - Unix socket
-- SQLite database
+- Storage (JSONL files or SQLite database)
 - Message history
 - Agent registry
 

docs/features/cloud.mdx

@@ -7,6 +7,14 @@ description: "Connect to Agent Relay Cloud for persistent workspaces, cross-mach
 
 Agent Relay Cloud extends your local relay with persistent workspaces, cross-machine messaging, and team collaboration features. Link your local daemon to access cloud capabilities.
 
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="/videos/agent-relay-cloud.mp4"
+>
+  Your browser does not support the video tag.
+</video>
+
 ## Overview
 
 <CardGroup cols={2}>

docs/features/dashboard.mdx

@@ -5,37 +5,17 @@ description: "Monitor and manage your agent network through the browser-based da
 
 # Web Dashboard
 
-<Note>
-  **The dashboard is now an external component.** Install it from
-  [relay-dashboard on GitHub](https://github.com/AgentWorkforce/relay-dashboard).
-  For a lightweight alternative, the TUI client provides relay communication directly in your terminal.
-</Note>
-
-The relay-dashboard provides a web interface for real-time monitoring of your agent network. View agent presence, message history, and coordinate your team from a central interface.
-
-## Installation
-
-Install the dashboard from the external package:
-
-```bash
-npm install -g relay-dashboard
-```
-
-For full setup and configuration details, see the [relay-dashboard repository](https://github.com/AgentWorkforce/relay-dashboard).
+The web dashboard provides a real-time interface for monitoring your agent network. View agent presence, message history, spawn agents, and coordinate your team from a central interface.
 
 ## Starting the Dashboard
 
-After installing the external package, start the dashboard alongside the daemon:
+Start the daemon with the `--dashboard` flag:
 
 ```bash
-# Start the daemon
-agent-relay up
-
-# In another terminal, start the dashboard
-relay-dashboard --port 3888
+agent-relay up --dashboard
 ```
 
-By default, the dashboard runs on port **3888**:
+This starts both the relay daemon and the dashboard. By default, the dashboard runs on port **3888**:
 
 ```
 Dashboard: http://localhost:3888
@@ -46,14 +26,14 @@ Dashboard: http://localhost:3888
 Specify a different port:
 
 ```bash
-relay-dashboard --port 3889
+agent-relay up --dashboard --port 3889
 ```
 
 Or set the environment variable:
 
 ```bash
 export AGENT_RELAY_DASHBOARD_PORT=3889
-relay-dashboard
+agent-relay up --dashboard
 ```
 
 ## Dashboard Features

docs/guide/agent-setup.md

@@ -447,9 +447,16 @@ Define roles by adding markdown files to your project:
 └── designer.md      # UI/UX
 ```
 
-Names automatically match roles (case-insensitive):
+Names automatically match roles (case-insensitive). Create agents using either method:
+
+**Option A: Dashboard (recommended for interactive use)**
+1. Open http://localhost:3888
+2. Click "Spawn Agent"
+3. Enter name "Lead" and select CLI "claude"
+
+**Option B: CLI (for scripting/automation)**
 ```bash
-agent-relay create-agent -n Lead claude    # Uses lead.md
+agent-relay spawn Lead claude "Your task instructions"
 ```
 
 ---

docs/guides/editor-integration.mdx

@@ -49,6 +49,14 @@ When you send a prompt from your editor:
 
 ## Quick Start (Zed)
 
+<video
+  controls
+  className="w-full aspect-video rounded-xl"
+  src="/videos/zed-acp-agent-relay.mp4"
+>
+  Your browser does not support the video tag.
+</video>
+
 ### 1. Start the Daemon and Configure Zed
 
 ```bash

docs/introduction.mdx

@@ -95,7 +95,7 @@ Agent Relay consists of three main components:
 |            +----------------+----------------+                       |
 |            |                                 |                       |
 |   +--------+--------+               +--------+--------+              |
-|   | SQLite Storage  |               |    Dashboard    |              |
+|   | JSONL Storage   |               |    Dashboard    |              |
 |   | (Message        |               |   localhost:    |              |
 |   |  History)       |               |      3888       |              |
 |   +-----------------+               +-----------------+              |