@wolpertingerlabs/drawlatch 1.0.0-alpha.3 → 1.0.0-alpha.35

package/README.md

@@ -1,686 +1,614 @@
 # Drawlatch
 
-> **Alpha Software:** This project is in alpha. Expect breaking changes between updates.
+> **Alpha Software:** Expect breaking changes between updates.
 
-A config-driven MCP (Model Context Protocol) proxy that lets Claude Code make authenticated HTTP requests to external APIs. Supports 22 pre-built API connections with endpoint allowlisting, per-caller access control, and real-time event ingestion — all configured through a single JSON file.
+Drawlatch is a config-driven proxy that gives AI agents authenticated access to external APIs. Define your connections and secrets in a single config file — agents get structured, allowlisted access to 23 pre-built APIs without ever seeing your credentials.
 
-Drawlatch can run in two modes:
+**Using [Callboard](https://github.com/WolpertingerLabs/callboard)?** Drawlatch is built in — Callboard manages connections, secrets, and agent identities through its UI. You don't need to set up drawlatch separately.
 
-- **Remote mode** — local proxy + remote server, with end-to-end encryption. Secrets never leave the remote server.
-- **Local mode** — imported as a library and called in-process (no server, no encryption). Secrets are on the same machine, but you get the same config-driven route resolution, endpoint allowlisting, and ingestor support.
+## Key Features
+
+- **23 pre-built connections** — GitHub, Slack, Discord, Stripe, Notion, Linear, OpenAI, and [more](CONNECTIONS.md)
+- **Endpoint allowlisting** — agents can only reach explicitly configured URL patterns
+- **Per-caller access control** — each agent identity sees only its assigned connections
+- **Real-time event ingestion** — WebSocket, webhook, and polling listeners for incoming events ([details](INGESTORS.md))
+- **Two operating modes** — remote (secrets on a separate server with E2EE) or local (in-process library)
 
 ## How It Works
 
-### Remote Mode (Two-Component)
+Drawlatch runs in two modes depending on your trust model:
 
-In remote mode, the system has two components:
+### Remote Mode — Secrets Never Leave the Server
 
-1. **Local MCP Proxy** — runs on your machine as a Claude Code MCP server (stdio transport). It holds **no secrets**. It encrypts requests and forwards them to the remote server.
-2. **Remote Secure Server** — holds all secrets (API keys, tokens, etc.) and only communicates through encrypted channels after mutual authentication. It injects secrets into outgoing HTTP requests on the proxy's behalf.
+The local MCP proxy holds no secrets. It encrypts requests and forwards them to a remote server that injects credentials and makes the actual API calls.
 
 ```
-┌──────────────┐     Encrypted Channel     ┌──────────────────┐     Authenticated     ┌──────────────┐
-│  Claude Code │ ◄──── stdio ────► MCP     │◄── HTTP + E2EE ──►│  Remote Server       │────  HTTPS ───►│  External API │
-│              │                   Proxy    │                   │  (holds secrets)     │               │               │
-└──────────────┘                            └──────────────────┘                       └──────────────┘
-                    No secrets here                                Injects API keys,
-                                                                  tokens, headers
+┌──────────────┐                          ┌──────────────────┐                    ┌──────────────┐
+│  Claude Code  │◄── stdio ──► MCP Proxy  │◄── HTTP + E2EE ──►  Remote Server    │── HTTPS ────►│  External API │
+│              │              (no secrets) │                   │  (holds secrets)  │              │               │
+└──────────────┘                          └──────────────────┘                    └──────────────┘
 ```
 
-The crypto layer uses **Ed25519** signatures for authentication and **X25519 ECDH** for key exchange, deriving **AES-256-GCM** session keys — all built on Node.js native `crypto` with zero external crypto dependencies.
+The crypto layer uses Ed25519 signatures for mutual authentication and X25519 ECDH to derive AES-256-GCM session keys — all built on Node.js native `crypto` with zero external dependencies.
 
-### Local Mode (In-Process Library)
+### Local Mode — In-Process Library
 
-In local mode, there is no separate server, no network port, and no encryption. Your application imports Drawlatch's core functions directly and calls them in-process:
+No server, no encryption. Your application imports drawlatch directly and calls the same `executeProxyRequest()` function the remote server uses. Secrets come from `process.env` on the same machine.
 
 ```
-┌──────────────────────────────────────────┐     Authenticated     ┌──────────────┐
-│  Your Application                        │────  HTTPS ───────────►│  External API │
-│  ┌──────────┐   in-process   ┌────────┐ │                        │               │
-│  │  Agent   │◄──  call  ────►│ drawl. │ │  Reads secrets from    └──────────────┘
-│  │          │                │ routes │ │  local env / config
+┌──────────────────────────────────────────┐                    ┌──────────────┐
+│  Your Application                        │── HTTPS ──────────►│  External API │
+│  ┌──────────┐   in-process   ┌────────┐ │                    │               │
+│  │  Agent   │◄── call ──────►│ drawl. │ │                    └──────────────┘
 │  └──────────┘                └────────┘ │
 └──────────────────────────────────────────┘
-         Secrets are on the same machine
 ```
 
-**What you get in local mode:** The same config-driven route resolution, endpoint allowlisting, per-caller access control, connection templates, ingestor support (WebSocket, webhook, polling), and the exact same `executeProxyRequest()` function the remote server uses — no behavioral drift.
-
-**What you don't get:** Secret isolation from the agent. When running locally, secrets live in `process.env` on the same machine. The value proposition shifts from cryptographic secret hiding to **convenience and structured access** — a single config file managing many API connections with consistent patterns.
+You still get config-driven route resolution, endpoint allowlisting, per-caller access control, and ingestor support — just without cryptographic secret isolation.
 
-> **When to use which mode:** Use remote mode when you need to hide secrets from the machine running the agent (e.g., shared CI servers, untrusted environments). Use local mode when running on your own machine and you want the convenience of config-driven API management without the overhead of running a separate server.
+> **When to use which:** Remote mode when secrets must be hidden from the agent's machine (shared servers, CI, untrusted environments). Local mode when running on your own machine and you want convenience without a separate server.
 
 ## Quick Start
 
-### Option 1: Install as a Claude Code Plugin (Recommended)
+Get from zero to working in three commands:
 
-This repo is structured as a **Claude Code plugin** with a marketplace. Install it directly:
+```bash
+# Install globally
+npm install -g @wolpertingerlabs/drawlatch
 
-```shell
-# Add the marketplace (from a local clone)
-/plugin marketplace add ./path/to/drawlatch
+# Set up keys, config, and .env in one step
+drawlatch init --connections github
 
-# Install the plugin
-/plugin install drawlatch@drawlatch
+# Set your API token (edit the file or run this)
+echo "GITHUB_TOKEN=ghp_your_token_here" >> ~/.drawlatch/.env
+
+# Start the remote server
+drawlatch start
 ```
 
-Or load it directly during development:
+Verify your setup:
 
-```shell
-claude --plugin-dir ./path/to/drawlatch
+```bash
+drawlatch doctor    # Validate full setup
+drawlatch status    # Check server is running
+drawlatch config    # View configuration and secret status
 ```
 
-Before using, set the `MCP_CONFIG_DIR` environment variable so the proxy can find its config and keys:
+The `init` command generates keys, creates configs, exchanges public keys, and scaffolds the `.env` file. All steps are idempotent — safe to re-run.
 
-```bash
-export MCP_CONFIG_DIR=~/.drawlatch
+### Connect to Claude Code
+
+**Option 1: Claude Code Plugin (Recommended)**
+
+```shell
+# Install the plugin
+/plugin install drawlatch@drawlatch
 ```
 
-The plugin's MCP server starts automatically when enabled. The `secure_request` and `list_routes` tools become available immediately.
+The plugin's MCP server starts automatically. The proxy uses `~/.drawlatch/` by default — see [Advanced Configuration](#advanced-configuration) to use a custom path.
 
-### Option 2: Auto-Discovery (opening this repo directly)
+**Option 2: Auto-Discovery**
 
-This repo includes a `.mcp.json` file at the root, so Claude Code **automatically discovers** the MCP proxy server when you open the project. On first launch, Claude Code will prompt you to approve the server — accept, and the `secure_request` and `list_routes` tools become available immediately.
+This repo includes a `.mcp.json` file, so Claude Code automatically discovers the MCP proxy when you open the project. Approve the server when prompted.
 
-Before approving, set the `MCP_CONFIG_DIR` environment variable:
+**Option 3: Manual Registration**
 
 ```bash
-export MCP_CONFIG_DIR=~/.drawlatch
+claude mcp add drawlatch \
+  -e MCP_CONFIG_DIR=~/.drawlatch \
+  -- node /path/to/drawlatch/dist/mcp/server.js
 ```
 
-The `.mcp.json` passes this through to the MCP server process. You also need a working setup (keys generated, public keys exchanged, configs in place, remote server running). See [Setup](#setup) below for the full walkthrough.
+> **Note:** Auto-discovery and manual registration use `dist/mcp/server.js`. The `dist/` directory is built automatically via `npm install` (prepare script). Rebuild manually with `npm run build` if needed.
 
-> **Note:** Auto-discovery uses the `dist/mcp/server.js` entrypoint. The `dist/` directory is built automatically when you run `npm install` (via the `prepare` script). If you need to rebuild manually, run `npm run build`.
+### Manual Setup
 
-## Setup
+For custom setups (different aliases, multiple callers, different machines), you can configure everything manually instead of using `drawlatch init`.
 
-### Prerequisites
+**1. Generate keys:**
 
 ```bash
-git clone <repo-url>
-cd drawlatch
-npm install
-npm run build
-```
-
-### Directory Structure
-
-All config and key files live inside `~/.drawlatch/` in the user's home directory by default. You can override this by setting the `MCP_CONFIG_DIR` environment variable.
-
-```
-~/.drawlatch/
-├── proxy.config.json                          # Local proxy config
-├── remote.config.json                         # Remote server config
-└── keys/
-    ├── local/                                 # MCP proxy keypairs (one per alias)
-    │   └── my-laptop/                         # Alias-named subdirectory
-    │       ├── signing.pub.pem                # Ed25519 public key (share this)
-    │       ├── signing.key.pem                # Ed25519 private key (keep secret)
-    │       ├── exchange.pub.pem               # X25519 public key (share this)
-    │       └── exchange.key.pem               # X25519 private key (keep secret)
-    ├── remote/                                # Remote server keypair
-    │   ├── signing.pub.pem
-    │   ├── signing.key.pem
-    │   ├── exchange.pub.pem
-    │   └── exchange.key.pem
-    └── peers/
-        ├── alice/                             # One subdirectory per caller
-        │   ├── signing.pub.pem               # Caller's public signing key
-        │   └── exchange.pub.pem              # Caller's public exchange key
-        ├── bob/                               # Another caller
-        │   ├── signing.pub.pem
-        │   └── exchange.pub.pem
-        └── remote-server/                     # Remote server's public keys (for proxy)
-            ├── signing.pub.pem
-            └── exchange.pub.pem
-```
-
-### Step 1: Generate Keys
-
-Generate keypairs for both the local proxy and the remote server:
+drawlatch generate-keys caller my-laptop
+drawlatch generate-keys server
+```
 
-```bash
-# Generate local MCP proxy keypair (with alias)
-npm run generate-keys -- local my-laptop
+**2. Exchange public keys** — on separate machines, copy `*.pub.pem` files to the matching `keys/callers/<alias>/` or `keys/server/` directory on the other machine. See [Key Exchange](#key-exchange) for details.
 
-# Or use the default alias
-npm run generate-keys -- local
+**3. Create configs** — copy the example files and edit:
 
-# Generate remote server keypair
-npm run generate-keys -- remote
+```bash
+cp remote.config.example.json ~/.drawlatch/remote.config.json
+cp proxy.config.example.json ~/.drawlatch/proxy.config.json
 ```
 
-Each command creates four PEM files (Ed25519 signing + X25519 exchange, public + private) in the appropriate directory under `~/.drawlatch/keys/`. Local keys are stored under `keys/local/<alias>/` — the alias defaults to `"default"` if omitted.
-
-> **Multiple identities:** Generate multiple local keypairs using different aliases (e.g., `my-laptop`, `ci-server`). Set `MCP_KEY_ALIAS` per agent at spawn time or use `localKeyAlias` in `proxy.config.json` to select which identity the proxy uses. The alias directory name should match the caller alias in the remote server's config.
-
-You can also generate keys to a custom directory:
+**4. Create a `.env` file** with your API secrets:
 
 ```bash
-npm run generate-keys -- --dir /path/to/custom/keys
+cat > ~/.drawlatch/.env << 'EOF'
+# GITHUB_TOKEN=ghp_your_token_here
+# DISCORD_BOT_TOKEN=your_bot_token_here
+EOF
 ```
 
-Or inspect the fingerprint of an existing keypair:
+**5. Start the server:**
 
 ```bash
-npm run generate-keys -- show ~/.drawlatch/keys/local/my-laptop
+drawlatch start
+drawlatch doctor    # Validate full setup
 ```
 
-### Step 2: Exchange Public Keys
+## Admin Dashboard
 
-The local proxy and remote server need each other's public keys for mutual authentication. Copy the **public** key files (`.pub.pem` only — never share private keys):
+`drawlatch start` serves a built-in web dashboard — a React single-page app — that **fully manages** your running daemon: enable/disable connections per caller, set and clear secrets, create and delete callers, configure and control event listeners (start/stop/restart, multi-instance management), and watch the live event/log feed — all from the browser, no config-file editing required. Every change is applied with a **live reload** (the daemon re-resolves routes and ingestors in place), so there is no "restart to apply" step. drawlatch owns 100% of its own state through this password-gated surface; nothing external writes its config.
 
-**From local to remote** — copy the proxy's public keys into a caller directory on the remote server. Since local keys are now stored per-alias, the alias directory name naturally matches the peer directory:
+### Architecture
 
-```bash
-mkdir -p ~/.drawlatch/keys/peers/my-laptop
+There is no separate UI service to run. The React app, the `/api/admin/*` API, and the MCP protocol endpoints (`/handshake`, `/request`, `/events`, `/webhooks`, …) are all served by the **same Express process on the same port** as the daemon (default `http://127.0.0.1:9999/`):
 
-cp ~/.drawlatch/keys/local/my-laptop/signing.pub.pem \
-   ~/.drawlatch/keys/peers/my-laptop/signing.pub.pem
-
-cp ~/.drawlatch/keys/local/my-laptop/exchange.pub.pem \
-   ~/.drawlatch/keys/peers/my-laptop/exchange.pub.pem
+```
+┌────────────────────────────── drawlatch daemon (one process, port 9999) ──────────────────────────────┐
+│                                                                                                        │
+│   GET /                 →  React SPA (served from frontend/dist in production)                          │
+│   /api/admin/*          →  read + mutating JSON API  ──┐                                                │
+│   POST /api/auth/*      →  login / logout / check       ├─ password-gated (session cookie)              │
+│   /handshake /request … →  MCP protocol (E2EE)         ─┘  ← unaffected by dashboard auth               │
+│                                                                                                        │
+└────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-**From remote to local** — copy the remote server's public keys into the proxy's peer directory:
+Any unmatched non-API GET falls back to `index.html` so client-side routing works. The MCP protocol endpoints are independent of the dashboard — they keep serving agents even when the dashboard is locked (see below).
 
-```bash
-mkdir -p ~/.drawlatch/keys/peers/remote-server
+### Setup
 
-cp ~/.drawlatch/keys/remote/signing.pub.pem \
-   ~/.drawlatch/keys/peers/remote-server/signing.pub.pem
+**1. Set a password** (required — the dashboard is locked until one is set):
 
-cp ~/.drawlatch/keys/remote/exchange.pub.pem \
-   ~/.drawlatch/keys/peers/remote-server/exchange.pub.pem
+```bash
+drawlatch set-password          # prompts on a TTY, or reads a password piped on stdin
+# echo 'my-strong-password' | drawlatch set-password   # non-interactive
 ```
 
-> **Tip:** If the proxy and remote server are on different machines, securely transfer only the `*.pub.pem` files (e.g., via `scp`). Each caller gets its own subdirectory under the peers directory — the directory name becomes the caller's alias used in the remote config and audit logs.
+The password is hashed with **scrypt** (random 16-byte salt, verified with a constant-time compare); the hash + salt are written to `~/.drawlatch/.env` (`AUTH_PASSWORD_HASH` / `AUTH_PASSWORD_SALT`, mode `0600`). Your plaintext password is never stored. Use `drawlatch change-password` (an alias of the same command) to rotate it later — rotating signs out every other session.
 
-### Step 3: Create the Local Proxy Config
+**2. Open the dashboard** at `http://127.0.0.1:9999/` and log in. `drawlatch status` prints the dashboard URL and whether a password is configured.
 
-Copy the example and edit the paths to match your setup:
+### Pages
 
-```bash
-cp proxy.config.example.json ~/.drawlatch/proxy.config.json
-```
+| Page | Route | What it shows | Refresh |
+|------|-------|---------------|---------|
+| **Overview** | `/` | Daemon health at a glance: status, PID, port, version, uptime, active session count, ingestor state breakdown, and secrets-configured progress. | on load |
+| **Connections** | `/connections` | Full management: connections grouped by category with search + a stable/beta/dev filter; a caller selector with create/delete-caller; per-connection enable toggle, secrets modal, test connection/listener, listener config panel (all field types + multi-instance), and quick start/stop/restart — with live ingestor state dots and secret-status badges. | live (5s) |
+| **Logs** | `/logs` | Live event/log feed per caller — ingestor status cards, source filter pills, and expandable event rows (eventType, ids, timestamps, pretty-printed JSON payload). | every 5s |
+| **Callers** | `/callers` | Registered MCP callers — alias, name, connection count, key fingerprint, and whether their keys directory exists. Click through for a caller's connections and secret status. | on load |
+| **Ingestors** | `/ingestors` | Live table of every running ingestor (WebSocket / webhook / poll) — state, buffered event count, total events received, last activity, and any error. | every 2s |
+| **Sessions** | `/sessions` | Active MCP proxy sessions — caller alias, created/last-active times, request count, and current per-window request rate. | every 5s |
+| **Secrets** | `/secrets` | A (caller × connection × secret) matrix showing required/optional and present/missing — with a "only missing" filter. **Never shows secret values**, only whether each is set. | every 10s |
 
-Edit `~/.drawlatch/proxy.config.json`:
+### The `/api/admin/*` API
 
-```json
-{
-  "remoteUrl": "http://127.0.0.1:9999",
-  "localKeyAlias": "my-laptop",
-  "remotePublicKeysDir": "~/.drawlatch/keys/peers/remote-server",
-  "connectTimeout": 10000,
-  "requestTimeout": 30000
-}
-```
+The pages are views over the `/api/admin/*` JSON API. **Read** endpoints (`/meta`, `/health`, `/connections`, `/callers`, `/callers/:alias/connection-status`, `/callers/:alias/connections`, `/callers/:alias/ingestors`, `/callers/:alias/events`, `/ingestors`, `/sessions`, `/secrets`) **never return a secret value** — caller `env` maps are reduced to key *names*, secret state is reported as booleans, and session crypto material is never serialized.
+
+**Mutating** endpoints (all behind the password gate) let the dashboard own management end-to-end:
 
-| Field                 | Description                                                                                     | Default                               |
-| --------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------- |
-| `remoteUrl`           | URL of the remote secure server                                                                 | `http://localhost:9999`               |
-| `localKeyAlias`       | Key alias — resolved to `keys/local/<alias>/`. Overridden by `MCP_KEY_ALIAS` env var at runtime | _(none)_                              |
-| `localKeysDir`        | Absolute path to the proxy's own keypair directory. Ignored when `localKeyAlias` is set         | `~/.drawlatch/keys/local/default`       |
-| `remotePublicKeysDir` | Absolute path to the remote server's public keys                                                | `~/.drawlatch/keys/peers/remote-server` |
-| `connectTimeout`      | Handshake timeout in milliseconds                                                               | `10000` (10s)                         |
-| `requestTimeout`      | Request timeout in milliseconds                                                                 | `30000` (30s)                         |
+| Method + path | Action |
+|---|---|
+| `POST /callers` | Create a caller **with a fresh keypair** (no interactive sync) |
+| `DELETE /callers/:alias` | Delete a caller (its keys + prefixed env vars); `default` is protected |
+| `POST /callers/:alias/connections/:connection` `{enabled}` | Enable/disable a connection |
+| `PUT  /callers/:alias/connections/:connection/secrets` `{secrets}` | Set/clear secrets (empty string = delete) — **write-only**, read back as booleans |
+| `POST /callers/:alias/connections/:connection/test` · `/test-ingestor` | Run a connection / listener test |
+| `POST /callers/:alias/connections/:connection/listener/control` `{action,instance_id?}` | Start/stop/restart a listener |
+| `GET/PUT /…/listener/params`, `GET/POST/DELETE /…/listener/instances[/:id]`, `POST /…/listener/resolve-options` | Listener params + multi-instance management |
 
-**Alias resolution priority:**
+Secrets are **write-only** through this API: you `PUT` values, and every read path reports only booleans. After any mutation the daemon live-reloads routes/ingestors for the affected caller. The same logic powers the encrypted MCP tools and the admin API through a single shared `tool-dispatch` module, so the two surfaces can never drift.
 
-1. `MCP_KEY_ALIAS` env var (highest — set per agent at spawn time)
-2. `localKeyAlias` in `proxy.config.json`
-3. `localKeysDir` in `proxy.config.json` (explicit full path for custom deployments)
-4. Default: `keys/local/default`
+A loopback-only `POST /sync/auto-enroll` lets a **co-located** client (one that shares drawlatch's filesystem) provision a caller with zero interaction by presenting the one-time token drawlatch writes to `~/.drawlatch/enroll.token` at startup.
 
-### Step 4: Create the Remote Server Config
+### Security model
 
-Copy the example and edit it to match your setup:
+The **password is the trust boundary** for the dashboard and `/api/admin/*` — not loopback. That lets you expose the dashboard to a LAN by binding a non-loopback host:
 
 ```bash
-cp remote.config.example.json ~/.drawlatch/remote.config.json
+DRAWLATCH_HOST=0.0.0.0 drawlatch start    # or: drawlatch start --host 0.0.0.0
 ```
 
-Edit `~/.drawlatch/remote.config.json`. This is where you define your callers, their connections, custom connectors, and secrets.
+Auth uses a `drawlatch_session` cookie that is `httpOnly` and `sameSite=strict`, with a **7-day rolling expiry** (every authenticated request extends it). Login, password-change, and auth-check endpoints are rate-limited per IP (5/min for login & change-password, 20/min for checks). If **no** password is configured, the daemon still starts and serves MCP normally — only the dashboard is locked: `/api/auth/*` and `/api/admin/*` return `503` and the SPA shows a locked state prompting `drawlatch set-password`. The daemon never exits just because the dashboard is unconfigured.
 
-The config is **caller-centric** — each caller is identified by their public key and explicitly declares which connections they can access.
+> **Cookies run over plain HTTP** on loopback/LAN (no `secure` flag). Put the daemon behind a TLS-terminating reverse proxy if you expose it beyond a trusted network.
 
-#### Example: Single caller with a built-in connection
+> **Migrating from `drawlatch-ui`?** The standalone `drawlatch-ui` service and its `~/.drawlatch-ui/` config directory are abandoned — its dashboard, auth gate, and password now live inside drawlatch. There is no automatic migration: just run `drawlatch set-password` once to set the password in `~/.drawlatch/.env`.
+
+## MCP Tools
+
+Once connected, agents get these tools:
+
+| Tool | Description |
+|------|-------------|
+| `secure_request` | Make authenticated HTTP requests. Route-level headers (auth tokens, API keys) are injected automatically — the agent never sees secret values. Supports JSON and multipart/form-data file uploads. |
+| `list_routes` | Discover available APIs with metadata, docs links, allowed endpoints, and available secret placeholders. |
+| `poll_events` | Retrieve buffered events from ingestors (Discord messages, GitHub webhooks, etc.) with cursor-based pagination. |
+| `ingestor_status` | Get connection state, buffer sizes, event counts, and errors for all active ingestors. |
+| `test_connection` | Verify API credentials with a pre-configured read-only request. |
+| `control_listener` | Start, stop, or restart an event listener. |
+| `list_listener_configs` | Get configurable fields for event listeners. |
+| `set_listener_params` | Configure listener parameters (filters, buffer sizes, etc.). |
+| `get_listener_params` | Read current listener parameter overrides. |
+| `resolve_listener_options` | Fetch dynamic options for listener config fields (e.g., list of Trello boards). |
+| `list_listener_instances` | List instances of a multi-instance listener. |
+| `delete_listener_instance` | Remove a multi-instance listener instance. |
+| `test_ingestor` | Test event listener configuration and credentials. |
+
+## Configuration Reference
+
+### Remote Server Config (`remote.config.json`)
 
 ```json
 {
   "host": "0.0.0.0",
   "port": 9999,
-  "localKeysDir": "~/.drawlatch/keys/remote",
-  "callers": {
-    "my-laptop": {
-      "name": "Personal Laptop",
-      "peerKeyDir": "~/.drawlatch/keys/peers/my-laptop",
-      "connections": ["github"]
-    }
-  },
+  "connectors": [],
+  "callers": {},
   "rateLimitPerMinute": 60
 }
 ```
 
-Set the `GITHUB_TOKEN` environment variable on the remote server and the built-in `github` connection template handles everything else — endpoint patterns, auth headers, docs URLs, and OpenAPI specs.
+| Field | Description | Default |
+|-------|-------------|---------|
+| `host` | Network interface to bind | `127.0.0.1` |
+| `port` | Listen port | `9999` |
+| `connectors` | Custom connector definitions (see below) | `[]` |
+| `callers` | Per-caller access control (see below) | `{}` |
+| `rateLimitPerMinute` | Max requests per minute per session | `60` |
+
+Server keys are always loaded from `keys/server/` inside the config directory.
+
+### Callers
 
-#### Example: Multiple callers with different access levels
+Each caller is identified by their public key and declares which connections they can access:
 
 ```json
 {
-  "host": "0.0.0.0",
-  "port": 9999,
-  "localKeysDir": "~/.drawlatch/keys/remote",
-  "connectors": [
-    {
-      "alias": "internal-api",
-      "name": "Internal Admin API",
-      "headers": { "Authorization": "Bearer ${ADMIN_KEY}" },
-      "secrets": { "ADMIN_KEY": "${INTERNAL_ADMIN_KEY}" },
-      "allowedEndpoints": ["https://admin.internal.com/**"]
-    }
-  ],
   "callers": {
     "alice": {
       "name": "Alice (senior engineer)",
-      "peerKeyDir": "/keys/peers/alice",
-      "connections": ["github", "stripe", "internal-api"]
+      "connections": ["github", "stripe", "internal-api"],
+      "env": {
+        "GITHUB_TOKEN": "${ALICE_GITHUB_TOKEN}"
+      }
     },
     "ci-server": {
       "name": "GitHub Actions CI",
-      "peerKeyDir": "/keys/peers/ci-server",
       "connections": ["github"]
     }
-  },
-  "rateLimitPerMinute": 60
+  }
 }
 ```
 
-Alice gets access to GitHub, Stripe, and the internal API. The CI server only gets GitHub. Each caller is isolated — they only see the routes for their declared connections.
+Caller public keys are loaded automatically from `keys/callers/<alias>/` — no path configuration needed.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `connections` | Yes | Array of connection names (built-in or custom connector aliases) |
+| `name` | No | Human-readable name for audit logs |
+| `env` | No | Per-caller env var overrides — redirect secret resolution per caller |
+| `ingestorOverrides` | No | Per-caller ingestor config overrides ([details](INGESTORS.md#caller-level-ingestor-overrides)) |
+
+The `env` map lets multiple callers share the same connection with different credentials:
+- Keys are the env var names connectors reference (e.g., `GITHUB_TOKEN`)
+- Values are `"${REAL_ENV_VAR}"` (redirect) or literal strings (direct injection)
+- Checked before prefixed env vars during secret resolution
 
-#### Example: Per-caller env overrides (shared connector, different credentials)
+Without an explicit `env` mapping, secrets resolve via prefixed env vars (e.g., caller "alice" + `GITHUB_TOKEN` → `ALICE_GITHUB_TOKEN`).
 
-When multiple callers use the same connection but need different credentials, use the `env` field to redirect environment variable resolution per caller:
+### Custom Connectors
+
+Define reusable route templates for APIs not covered by built-in connections:
 
 ```json
 {
-  "host": "0.0.0.0",
-  "port": 9999,
-  "localKeysDir": "/keys/server",
-  "callers": {
-    "alice": {
-      "name": "Alice",
-      "peerKeyDir": "/keys/peers/alice",
-      "connections": ["github"],
-      "env": {
-        "GITHUB_TOKEN": "${ALICE_GITHUB_TOKEN}"
-      }
-    },
-    "bob": {
-      "name": "Bob",
-      "peerKeyDir": "/keys/peers/bob",
-      "connections": ["github", "stripe"],
-      "env": {
-        "GITHUB_TOKEN": "${BOB_GITHUB_TOKEN}",
-        "STRIPE_SECRET_KEY": "sk_test_bob_dev_key"
-      }
+  "connectors": [
+    {
+      "alias": "internal-api",
+      "name": "Internal Admin API",
+      "allowedEndpoints": ["https://admin.internal.com/**"],
+      "headers": { "Authorization": "Bearer ${ADMIN_KEY}" },
+      "secrets": { "ADMIN_KEY": "${INTERNAL_ADMIN_KEY}" }
     }
-  },
-  "rateLimitPerMinute": 60
+  ]
 }
 ```
 
-The `env` map works as follows:
-
-- **Keys** are the env var names that connectors reference (e.g., `GITHUB_TOKEN`)
-- **Values** are either `"${REAL_ENV_VAR}"` (redirect to a different env var) or a literal string (direct injection)
-- When resolving secrets, the caller's `env` is checked **before** `process.env`
+| Field | Required | Description |
+|-------|----------|-------------|
+| `alias` | Yes | Unique name for referencing from caller `connections` lists |
+| `allowedEndpoints` | Yes | Glob patterns for allowed URLs |
+| `name` | No | Human-readable name |
+| `description` | No | Short description |
+| `docsUrl` | No | URL to API documentation |
+| `headers` | No | Headers to auto-inject (`${VAR}` placeholders resolved from `secrets`) |
+| `secrets` | No | Key-value pairs — literal strings or `${ENV_VAR}` references |
+| `resolveSecretsInBody` | No | Resolve `${VAR}` in request bodies (default: `false`) |
 
-In this example, both Alice and Bob use the same built-in `github` connection, but Alice's requests use `process.env.ALICE_GITHUB_TOKEN` while Bob's use `process.env.BOB_GITHUB_TOKEN`. Bob also gets a hardcoded Stripe test key without needing an env var.
+Custom connectors with an `alias` matching a built-in connection name take precedence.
 
-#### Remote Config Reference
+### Proxy Config (`proxy.config.json`)
 
-| Field                | Description                                                                                                                                  | Default                  |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| `host`               | Network interface to bind to. Use `0.0.0.0` for all interfaces or `127.0.0.1` for local only                                                 | `127.0.0.1`              |
-| `port`               | Port to listen on                                                                                                                            | `9999`                   |
-| `localKeysDir`       | Absolute path to the remote server's own keypair                                                                                             | `~/.drawlatch/keys/remote` |
-| `connectors`         | Array of custom connector definitions, each with an `alias` for referencing from callers (see [Connector Definition](#connector-definition)) | `[]`                     |
-| `callers`            | Per-caller access control. Keys are caller aliases used in audit logs (see [Caller Definition](#caller-definition))                          | `{}`                     |
-| `rateLimitPerMinute` | Max requests per minute per session                                                                                                          | `60`                     |
+Used by the local MCP proxy to connect to the remote server:
 
-#### Connector Definition
-
-Custom connectors define reusable route templates referenced by `alias` from caller connection lists. They follow the same structure as routes:
+```json
+{
+  "remoteUrl": "http://127.0.0.1:9999",
+  "connectTimeout": 10000,
+  "requestTimeout": 30000
+}
+```
 
-| Field                  | Required | Description                                                                                                              |
-| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `alias`                | Yes      | Unique name for referencing this connector from caller `connections` lists                                               |
-| `allowedEndpoints`     | Yes      | Array of glob patterns for allowed URLs (e.g., `https://api.example.com/**`)                                             |
-| `name`                 | No       | Human-readable name (e.g., `"Internal Admin API"`)                                                                       |
-| `description`          | No       | Short description of what the connector provides                                                                         |
-| `docsUrl`              | No       | URL to API documentation                                                                                                 |
-| `openApiUrl`           | No       | URL to OpenAPI/Swagger spec                                                                                              |
-| `headers`              | No       | Headers to auto-inject. Values may contain `${VAR}` placeholders resolved from `secrets`                                 |
-| `secrets`              | No       | Key-value pairs. Values can be literal strings or `${ENV_VAR}` references resolved from environment variables at startup |
-| `resolveSecretsInBody` | No       | Whether to resolve `${VAR}` placeholders in request bodies. Default: `false`                                             |
+| Field | Description | Default |
+|-------|-------------|---------|
+| `remoteUrl` | URL of the remote server | `http://localhost:9999` |
+| `connectTimeout` | Handshake timeout (ms) | `10000` |
+| `requestTimeout` | Request timeout (ms) | `30000` |
 
-#### Caller Definition
+Key paths are derived automatically — no configuration needed:
+- Caller keys: `keys/callers/{MCP_KEY_ALIAS || "default"}/`
+- Server public keys: `keys/server/`
 
-| Field               | Required | Description                                                                                                                                       |
-| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `peerKeyDir`        | Yes      | Path to this caller's public key files (`signing.pub.pem` + `exchange.pub.pem`)                                                                   |
-| `connections`       | Yes      | Array of connection names — references built-in templates (e.g., `"github"`) or custom connector aliases                                          |
-| `name`              | No       | Human-readable name for audit logs                                                                                                                |
-| `env`               | No       | Per-caller environment variable overrides (see [env overrides example](#example-per-caller-env-overrides-shared-connector-different-credentials)) |
-| `ingestorOverrides` | No       | Per-caller ingestor config overrides keyed by connection alias. Override event filters, buffer sizes, intents, or disable ingestors entirely. See **[INGESTORS.md](INGESTORS.md#caller-level-ingestor-overrides)** for full reference |
+### Advanced Configuration
 
-#### How Secrets Work
+#### `MCP_CONFIG_DIR` — the config-dir contract
 
-Secret values in the `secrets` map are resolved at session establishment time (per-caller):
+By default, all config and key files live in `~/.drawlatch/`. Override with:
 
-- **Literal values** — used as-is: `"API_TOKEN": "sk_live_abc123"`
-- **Environment variable references** — resolved from the server's environment: `"API_TOKEN": "${API_TOKEN}"`
-- **Per-caller overrides** — when a caller has an `env` entry for a variable name, that value is used instead of `process.env`
+```bash
+export MCP_CONFIG_DIR=/custom/path/to/config
+```
 
-Header values can reference secrets using `${VAR}` placeholders:
+Useful for CI environments or running multiple independent setups on the same machine. drawlatch **owns this layout as a stable contract** (and migrates legacy key layouts into it automatically on startup):
 
-```json
-"headers": {
-  "Authorization": "Bearer ${API_TOKEN}"
-}
+```
+$MCP_CONFIG_DIR/                 (default: ~/.drawlatch)
+  remote.config.json    — RemoteServerConfig (callers, connectors, port, tunnel flag)
+  proxy.config.json     — ProxyConfig (local MCP proxy → remote URL)
+  .env                  — secret values, prefixed per caller (mode 0600)
+  enroll.token          — one-time loopback auto-enroll token (mode 0600)
+  keys/
+    server/             — the daemon's own Ed25519 + X25519 keypair
+    callers/<alias>/    — one keypair per caller alias
 ```
 
-The placeholder `${API_TOKEN}` is resolved against the route's resolved `secrets` map. This means the actual secret value is never exposed to the local proxy or Claude Code — it only exists on the remote server.
+Legacy `keys/local`, `keys/remote`, and `keys/peers/*` directories are migrated to `keys/callers` / `keys/server` on first start — idempotent and safe to re-run.
 
-### Connections (Pre-built Route Templates)
+#### Self-managed tunnel
 
-Instead of manually configuring connectors for popular APIs, you can use **connections** — pre-built route templates that ship with the package (`github`, `stripe`, `openai`, etc.). Reference them by name in a caller's `connections` list:
+Set `"tunnel": true` in `remote.config.json` (or `DRAWLATCH_TUNNEL=1` / `drawlatch start --tunnel`) and drawlatch brings up and supervises its own Cloudflare quick tunnel on startup: it learns the public URL, injects it into callback-dependent connection configs (e.g. `TRELLO_CALLBACK_URL`) **before** secret resolution and ingestor start, and surfaces it in `drawlatch status`, the Overview page, and `/api/admin/meta`. It is a config flag, not a runtime control surface.
 
-```json
-{
-  "callers": {
-    "my-laptop": {
-      "peerKeyDir": "/keys/peers/my-laptop",
-      "connections": ["github", "stripe"]
-    }
-  }
-}
-```
-
-Set the required environment variables (e.g., `GITHUB_TOKEN`, `STRIPE_SECRET_KEY`) and the connection templates handle endpoint patterns, auth headers, docs URLs, and OpenAPI specs automatically. Custom connectors with a matching `alias` take precedence over built-in templates.
+#### Daemon lifecycle
 
-See **[CONNECTIONS.md](CONNECTIONS.md)** for the full list of available connections, required environment variables, and usage examples.
+`drawlatch start` runs the **whole** daemon in one process (MCP protocol + admin API + dashboard UI + optional tunnel). It is daemon-first and cleanly supervisable: a PID file, a deterministic `start` / `stop` / `restart` / `status`, an unauthenticated `/health` endpoint, and `drawlatch start --foreground` for running under a process manager. Local and remote deployments differ only by host binding (`DRAWLATCH_HOST`) and the dashboard password.
 
-### Step 5: Start the Servers
+## Connections
 
-**Start the remote server:**
-
-```bash
-# Development (with hot reload via tsx)
-npm run dev:remote
+23 pre-built connection templates ship with drawlatch. Reference them by name in a caller's `connections` list:
 
-# Production (requires `npm run build` first)
-npm run start:remote
-```
+| Connection | API | Required Env Var(s) |
+|------------|-----|---------------------|
+| `anthropic` | Anthropic Claude API | `ANTHROPIC_API_KEY` |
+| `bluesky` | Bluesky (AT Protocol) | `BLUESKY_ACCESS_TOKEN` |
+| `devin` | Devin AI API | `DEVIN_API_KEY` |
+| `discord-bot` | Discord Bot API | `DISCORD_BOT_TOKEN` |
+| `discord-oauth` | Discord OAuth2 API | `DISCORD_OAUTH_TOKEN` |
+| `github` | GitHub REST API | `GITHUB_TOKEN` |
+| `google` | Google Workspace APIs | `GOOGLE_API_TOKEN` |
+| `google-ai` | Google AI (Gemini) | `GOOGLE_AI_API_KEY` |
+| `hex` | Hex API | `HEX_TOKEN` |
+| `lichess` | Lichess API | `LICHESS_API_TOKEN` |
+| `linear` | Linear GraphQL API | `LINEAR_API_KEY` |
+| `mastodon` | Mastodon API | `MASTODON_ACCESS_TOKEN` |
+| `notion` | Notion API | `NOTION_API_KEY` |
+| `openai` | OpenAI API | `OPENAI_API_KEY` |
+| `openrouter` | OpenRouter API | `OPENROUTER_API_KEY` |
+| `reddit` | Reddit API | `REDDIT_ACCESS_TOKEN` |
+| `slack` | Slack Web API | `SLACK_BOT_TOKEN` |
+| `stripe` | Stripe Payments API | `STRIPE_SECRET_KEY` |
+| `telegram` | Telegram Bot API | `TELEGRAM_BOT_TOKEN` |
+| `trello` | Trello API | `TRELLO_API_KEY`, `TRELLO_TOKEN` |
+| `twitch` | Twitch Helix API | `TWITCH_ACCESS_TOKEN`, `TWITCH_CLIENT_ID` |
+| `x` | X (Twitter) API v2 | `X_BEARER_TOKEN` |
 
-**Connect the local MCP proxy to Claude Code:**
+See **[CONNECTIONS.md](CONNECTIONS.md)** for auth details, optional env vars, and usage notes per connection.
 
-The repo includes a `.mcp.json` at the root, so Claude Code auto-discovers the proxy when you open the project directory. Just approve the server when prompted — no manual registration needed.
+## Event Ingestion
 
-The `.mcp.json` requires the `MCP_CONFIG_DIR` environment variable to be set so the proxy can locate its config and keys. Set it to the absolute path of your `~/.drawlatch/` directory:
+Drawlatch can collect real-time events from external services and buffer them for agents to poll. Three ingestor types are supported:
 
-```bash
-export MCP_CONFIG_DIR=~/.drawlatch
-```
+| Type | How It Works | Connections |
+|------|-------------|-------------|
+| **WebSocket** | Persistent connections to event gateways | Discord Gateway, Slack Socket Mode |
+| **Webhook** | HTTP receivers with signature verification | GitHub, Stripe, Trello |
+| **Poll** | Interval-based HTTP requests | Notion, Linear, Reddit, X, Bluesky, Mastodon, Telegram, Twitch |
 
-**Alternative: manual registration**
+Events are stored in per-caller ring buffers (default 200, max 1000) with monotonic IDs for cursor-based pagination. Agents retrieve events via `poll_events` and check status via `ingestor_status`.
 
-If you prefer not to use auto-discovery, register the MCP server directly:
+For webhook ingestors, the remote server must be publicly accessible (or behind a tunnel). Use `drawlatch start --tunnel` to automatically start a Cloudflare tunnel.
 
-```bash
-claude mcp add secure-proxy \
-  --transport stdio --scope local \
-  -e MCP_CONFIG_DIR=~/.drawlatch \
-  -- node /absolute/path/to/drawlatch/dist/mcp/server.js
-```
+See **[INGESTORS.md](INGESTORS.md)** for full configuration reference.
 
-After connecting (either via auto-discovery or manual registration), the proxy will automatically perform the encrypted handshake with the remote server on first use.
+## Key Exchange
 
-### Step 6: Webhook Endpoints (Optional)
+Remote mode requires mutual authentication via Ed25519/X25519 keypairs. Each identity gets four PEM files (signing + exchange, public + private). The `drawlatch init` command handles this automatically for single-machine setups.
 
-If any of your connections use webhook ingestors (e.g., GitHub, Stripe, Trello), the remote server automatically exposes `POST /webhooks/:path` routes on the same port. External services send webhook POSTs to these endpoints, and the server verifies signatures, buffers events in per-caller ring buffers, and makes them available via `poll_events`.
+**Directory structure:**
 
-**Setup:**
+```
+~/.drawlatch/keys/
+├── callers/
+│   ├── default/           # Default caller keypair
+│   └── alice/             # Additional caller keypair
+└── server/                # Server keypair
+```
 
-1. The remote server must be **publicly accessible** for webhook delivery (or behind a tunnel like [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/))
-2. Point the external service's webhook URL to `https://<your-server>/webhooks/<path>` (e.g., `https://example.com/webhooks/github`)
-3. Set the webhook signing secret as an environment variable on the remote server (e.g., `GITHUB_WEBHOOK_SECRET`, `STRIPE_WEBHOOK_SECRET`)
+Both sides (caller and server) store their keys in the same directory tree. On a single machine, `drawlatch init` generates both and they can authenticate immediately. On separate machines, copy the `*.pub.pem` files to the corresponding directory on the other machine.
 
-The webhook path is configured in each connection template's `ingestor.webhook.path` field. See **[INGESTORS.md](INGESTORS.md)** for full details on webhook, WebSocket, and poll ingestors.
+**Using [Callboard](https://github.com/WolpertingerLabs/callboard)?** Use `drawlatch sync` to exchange keys automatically via a double-code approval flow — no manual file copying needed.
 
-### Multiple Agents (Multi-Identity)
+### Multiple Agent Identities
 
-When multiple agents share the same machine, each needs its own key identity. Generate a keypair per agent:
+Generate a keypair per agent and set `MCP_KEY_ALIAS` at spawn time:
 
 ```bash
-npm run generate-keys -- local alice
-npm run generate-keys -- local bob
+drawlatch generate-keys caller alice
+drawlatch generate-keys caller bob
 ```
 
-Each agent's MCP server config specifies its alias via the `MCP_KEY_ALIAS` env var:
-
 ```json
 {
   "mcpServers": {
-    "secure-proxy": {
+    "drawlatch": {
       "command": "node",
       "args": ["dist/mcp/server.js"],
-      "env": {
-        "MCP_CONFIG_DIR": "~/.drawlatch",
-        "MCP_KEY_ALIAS": "alice"
-      }
+      "env": { "MCP_CONFIG_DIR": "~/.drawlatch", "MCP_KEY_ALIAS": "alice" }
     }
   }
 }
 ```
 
-The proxy auto-resolves `MCP_KEY_ALIAS=alice` to `keys/local/alice/`. On the remote server, register each agent as a separate caller with matching alias directories under `keys/peers/`.
-
-## MCP Tools
-
-Once connected, Claude Code gets access to four tools:
-
-### `secure_request`
+Register each agent as a separate caller in `remote.config.json`.
 
-Make an authenticated HTTP request through the proxy. Route-level headers (e.g., `Authorization`) are injected automatically — the agent never sees the secret values.
+## CLI Reference
 
 ```
-method: GET | POST | PUT | PATCH | DELETE
-url: Full URL (may contain ${VAR} placeholders)
-headers: Optional additional headers
-body: Optional request body
-```
-
-### `list_routes`
-
-List all available routes for the current caller. Returns metadata (name, description, docs link), allowed endpoint patterns, available secret placeholder names (not values), and auto-injected header names. Different callers may see different routes based on their `connections` configuration.
-
-### `poll_events`
-
-Poll for new events from ingestors (Discord messages, GitHub webhooks, Notion updates, etc.). Returns events received since the given cursor.
-
-```
-connection: Optional — filter by connection alias (e.g., "discord-bot"), omit for all
-after_id: Optional — cursor; returns events with id > after_id
-```
-
-Pass `after_id` from the last event you received to get only new events. Omit to get all buffered events. See **[INGESTORS.md](INGESTORS.md)** for details on configuring event sources.
-
-### `ingestor_status`
+drawlatch [command] [options]
 
-Get the status of all active ingestors for the current caller. Returns connection state, buffer sizes, event counts, and any errors. Takes no parameters.
+Commands:
+  init               Set up drawlatch (keys, config, .env) in one step
+  start              Start the remote server (background daemon)
+  stop               Stop the remote server
+  restart            Restart the remote server
+  status             Show server status (PID, port, uptime, health, sessions, dashboard URL)
+  logs               View server logs
+  config             Show effective configuration and secret status
+  doctor             Validate setup and diagnose issues
+  set-password       Set/change the dashboard password (alias: change-password)
+  generate-keys      Generate Ed25519 + X25519 keypairs
+  sync               Exchange keys with a callboard instance
 
-## Library Usage (Local Mode)
+Options:
+  -h, --help         Show help
+  -v, --version      Show version
 
-Drawlatch can be imported as a library for in-process use — no separate server, no encryption overhead. The `package.json` exports map provides clean entry points:
+Init options:
+  --connections <list>  Comma-separated connections to enable (e.g., github,slack)
+  --alias <name>        Caller alias (default: "default")
 
-```typescript
-// Core request execution (same function the remote server uses)
-import { executeProxyRequest } from "drawlatch/remote/server";
+Start options:
+  -f, --foreground   Run in foreground
+  -t, --tunnel       Start a Cloudflare tunnel for webhooks
+  --port <number>    Override configured port
+  --host <address>   Override configured host
 
-// Config loading and route resolution
-import {
-  loadRemoteConfig,
-  resolveCallerRoutes,
-  resolveRoutes,
-  resolveSecrets,
-} from "drawlatch/shared/config";
+Logs options:
+  -n, --lines <num>  Number of lines (default: 50)
+  --follow           Tail the log output
 
-// Ingestor management (WebSocket, webhook, poll)
-import { IngestorManager } from "drawlatch/remote/ingestors";
+Generate-keys subcommands:
+  caller [alias]     Generate caller keypair (default alias: "default")
+  server             Generate server keypair
+  show <path>        Show fingerprint of existing keypair
+  --dir <path>       Generate to custom directory
 
-// Crypto primitives (if building custom transport)
-import { loadKeyBundle, loadPublicKeys, EncryptedChannel } from "drawlatch/shared/crypto";
+Sync options:
+  --ttl <seconds>    Session timeout (default: 300)
 ```
 
-### Available Exports
-
-| Export Path                  | Description                                                        |
-| ---------------------------- | ------------------------------------------------------------------ |
-| `drawlatch`                  | MCP proxy server (stdio transport) — the default entry point       |
-| `drawlatch/remote/server`    | Remote server functions including `executeProxyRequest()`          |
-| `drawlatch/remote/ingestors` | `IngestorManager` and all ingestor types                           |
-| `drawlatch/shared/config`    | Config loading, caller/route resolution, secret resolution         |
-| `drawlatch/shared/connections`| Connection template loading                                       |
-| `drawlatch/shared/crypto`    | Key generation, encrypted channel, key serialization               |
-| `drawlatch/shared/protocol`  | Handshake protocol, message types                                  |
+## Library Usage (Local Mode)
 
-### Example: In-Process Proxy
+Import drawlatch directly for in-process use — no server, no encryption:
 
 ```typescript
 import { loadRemoteConfig, resolveCallerRoutes, resolveRoutes, resolveSecrets } from "drawlatch/shared/config";
 import { executeProxyRequest } from "drawlatch/remote/server";
 
-// Load config and resolve routes for a specific caller
 const config = loadRemoteConfig();
 const callerRoutes = resolveCallerRoutes(config, "my-laptop");
 const callerEnv = resolveSecrets(config.callers["my-laptop"]?.env ?? {});
 const routes = resolveRoutes(callerRoutes, callerEnv);
 
-// Make a request — same function the remote server uses
 const result = await executeProxyRequest(
   { method: "GET", url: "https://api.github.com/user" },
   routes,
 );
 ```
 
-> **Note:** In local mode, secrets are resolved from `process.env` on the same machine. The encryption layer is not used. See [How It Works → Local Mode](#local-mode-in-process-library) for the security tradeoff.
-
-## Development
+### Available Exports
 
-```bash
-# Run tests
-npm test
+| Export Path | Description |
+|-------------|-------------|
+| `drawlatch` | MCP proxy server (stdio transport) |
+| `drawlatch/remote/server` | `executeProxyRequest()` and server functions |
+| `drawlatch/remote/ingestors` | `IngestorManager` and ingestor types |
+| `drawlatch/shared/config` | Config loading, route/secret resolution |
+| `drawlatch/shared/connections` | Connection template loading |
+| `drawlatch/shared/env-utils` | Environment variable and secret utilities |
+| `drawlatch/shared/crypto` | Key generation, encrypted channel |
+| `drawlatch/shared/protocol` | Handshake protocol, message types |
 
-# Run tests in watch mode
-npm run test:watch
+## Security Model
 
-# Run tests with coverage
-npm run test:coverage
+### Both Modes
 
-# Lint
-npm run lint
-npm run lint:fix
+- **Endpoint allowlisting** — requests only proxied to explicitly configured URL patterns
+- **Per-caller access control** — each caller only sees their assigned connections
+- **Per-caller credential isolation** — same connector, different credentials via `env` overrides
+- **Rate limiting** — configurable per-session (default: 60/min)
+- **Audit logging** — all operations logged with caller identity, session ID, timestamps
 
-# Format
-npm run format
-npm run format:check
-```
+### Remote Mode Only
 
-## Architecture
+- **Zero secrets on the client** — the MCP proxy never sees API keys or tokens
+- **Mutual authentication** — Ed25519 signatures before any data exchange
+- **End-to-end encryption** — AES-256-GCM with X25519 ECDH session keys
+- **Replay protection** — monotonic counters on all encrypted messages
+- **Session isolation** — unique session keys per handshake, 30-minute TTL
+- **File permissions** — private keys `0600`, key directories `0700`
 
-### Plugin Structure
+## Development
 
-This repo is structured as a Claude Code plugin:
+```bash
+npm test                  # Run tests
+npm run test:watch        # Watch mode
+npm run test:coverage     # Coverage report
+npm run lint              # Lint
+npm run format            # Format
 
-```
-drawlatch/
-├── .claude-plugin/              # Plugin metadata
-│   ├── plugin.json              # Plugin manifest (name, version, description)
-│   └── marketplace.json         # Marketplace catalog for distribution
-├── .mcp.json                    # MCP server config (used by plugin system + auto-discovery)
-├── dist/                        # Compiled JavaScript (built via `npm run build` or `prepare`)
-│   └── mcp/server.js            # MCP proxy entrypoint
-└── src/                         # TypeScript source
+npm run dev:remote        # Remote server with hot reload
+npm run dev:mcp           # MCP proxy with hot reload
 ```
 
-### Source Code
+### Source Structure
 
 ```
 src/
-├── cli/                        # Key generation CLI
-│   └── generate-keys.ts        # Ed25519 + X25519 keypair generation
-├── connections/                 # Pre-built route templates (JSON)
-│   ├── github.json             # GitHub REST API
-│   ├── stripe.json             # Stripe Payments API
-│   └── ...                     # 22 templates total
-├── mcp/
-│   └── server.ts               # Local MCP proxy server (stdio transport)
+├── cli/                     # Key generation CLI
+├── connections/             # 23 pre-built route templates (JSON)
+├── auth/                    # Dashboard auth (scrypt password, session cookies)
+├── mcp/server.ts            # Local MCP proxy (stdio transport)
 ├── remote/
-│   ├── server.ts               # Remote secure server (Express HTTP)
-│   ├── server.test.ts          # Unit tests
-│   ├── server.e2e.test.ts      # End-to-end tests
-│   └── ingestors/              # Real-time event ingestion system
-│       ├── base-ingestor.ts    # Abstract base class (state machine, ring buffer)
-│       ├── ring-buffer.ts      # Generic bounded circular buffer
-│       ├── manager.ts          # Lifecycle management, per-caller routing
-│       ├── registry.ts         # Factory registry for ingestor types
-│       ├── types.ts            # Shared types and config interfaces
-│       ├── discord/            # Discord Gateway WebSocket (v10)
-│       ├── slack/              # Slack Socket Mode WebSocket
-│       ├── webhook/            # Webhook receivers (GitHub, Stripe, Trello)
-│       └── poll/               # Interval-based HTTP polling (Notion, Linear, etc.)
+│   ├── server.ts            # Remote secure server (Express) — also serves the dashboard
+│   ├── admin.ts             # Read-only /api/admin/* API
+│   └── ingestors/           # Event ingestion system
+│       ├── discord/         # Discord Gateway WebSocket
+│       ├── slack/           # Slack Socket Mode WebSocket
+│       ├── webhook/         # GitHub, Stripe, Trello webhooks
+│       └── poll/            # Interval-based HTTP polling
 └── shared/
-    ├── config.ts               # Config loading/saving, caller & route resolution
-    ├── connections.ts           # Connection template loading
-    ├── logger.ts               # Structured logging
-    ├── crypto/
-    │   ├── keys.ts             # Ed25519 + X25519 key generation/serialization
-    │   ├── channel.ts          # AES-256-GCM encrypted channel
-    │   └── index.ts            # Re-exports
-    └── protocol/
-        ├── handshake.ts        # Mutual auth (Noise NK-inspired)
-        ├── messages.ts         # Application-layer message types
-        └── index.ts            # Re-exports
-```
-
-## Security Model
+    ├── config.ts            # Config loading, route resolution
+    ├── connections.ts       # Connection template loading
+    ├── env-utils.ts         # Environment variable utilities
+    ├── crypto/              # Ed25519/X25519 keys, AES-256-GCM channel
+    └── protocol/            # Handshake, message types
 
-### Both Modes
-
-These protections apply regardless of whether you use remote or local mode:
-
-- **Per-caller access control** — each caller only sees and can use the connections explicitly assigned to them
-- **Per-caller credential isolation** — callers sharing the same connector can have different credentials via `env` overrides
-- **Endpoint allowlisting** — requests are only proxied to explicitly configured URL patterns
-- **Rate limiting** — configurable per-session request rate limiting (default: 60/min)
-- **Audit logging** — all operations are logged with caller identity, session ID, and timestamps
-
-### Remote Mode Only
-
-These additional protections apply when running the two-component remote architecture:
-
-- **Zero secrets on the client** — the local MCP proxy never sees API keys or tokens
-- **Mutual authentication** — both sides prove their identity using Ed25519 signatures before any data is exchanged
-- **End-to-end encryption** — all requests/responses are encrypted with AES-256-GCM session keys derived via X25519 ECDH
-- **Replay protection** — monotonic counters prevent replay attacks
-- **Session isolation** — each handshake produces unique session keys with a 30-minute TTL
-- **File permissions** — private keys are saved with `0600`, directories with `0700`
-
-### Local Mode Caveat
-
-When using Drawlatch as an in-process library (local mode), secrets are resolved from `process.env` on the same machine as the agent. The encryption and mutual authentication layers are not used. The security value in local mode comes from **structured access control** (endpoint allowlisting, per-caller route isolation) rather than cryptographic secret isolation.
+frontend/                    # React + Vite dashboard SPA (built to frontend/dist)
+└── src/pages/               # Overview, Connections, Callers, Ingestors, Sessions, Secrets
+```
 
 ## License