mercury-agent 0.4.5

package/container/Dockerfile.base

@@ -0,0 +1,109 @@
+# syntax=docker/dockerfile:1
+# Mercury Agent Container — Base tier
+# Base: Microsoft Playwright image (Ubuntu 24.04 noble + Node 22 + Chromium + X11/GL deps preinstalled).
+# Adds: Bun, poppler-utils, pandoc, imagemagick, pi-coding-agent, mercury (UID 1000) user.
+FROM oven/bun:1 AS bun-source
+FROM mcr.microsoft.com/playwright:v1.55.0-noble
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Document-processing tools. Wrapped in a retry loop — archive.ubuntu.com is periodically flaky
+# and a single apt miss shouldn't fail the whole image build.
+RUN set -eux; \
+    for i in 1 2 3 4 5; do \
+      apt-get update && apt-get install -y --no-install-recommends \
+        poppler-utils pandoc imagemagick wget \
+      && break \
+      || { echo "apt attempt $i/5 failed, sleeping 15s" >&2; apt-get clean; sleep 15; }; \
+    done; \
+    rm -rf /var/lib/apt/lists/*
+
+# Rename the built-in ubuntu user (UID 1000) to mercury.
+# Playwright's noble base inherits the ubuntu user at UID/GID 1000; useradd -u 1000
+# would fail. (pwuser is at UID 1001 — unused by us.)
+RUN usermod -l mercury -d /home/mercury -m ubuntu && groupmod -n mercury ubuntu
+
+# Copy Bun from official image
+COPY --from=bun-source /usr/local/bin/bun /usr/local/bin/bun
+COPY --from=bun-source /usr/local/bin/bunx /usr/local/bin/bunx
+
+ENV HOME="/home/mercury"
+ENV BUN_INSTALL="/home/mercury/.bun"
+ENV PATH="$BUN_INSTALL/bin:/usr/local/bin:$PATH"
+
+# Chromium lives in /ms-playwright/chromium-*/chrome-linux/chrome in the Playwright image.
+# Symlink to /usr/local/bin/chromium so puppeteer-using npm packages find it.
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+RUN ln -sf "$(find /ms-playwright -name chrome -type f -executable | head -1)" /usr/local/bin/chromium
+ENV PUPPETEER_EXECUTABLE_PATH=/usr/local/bin/chromium
+
+# --no-sandbox: Chromium can't use its user namespace sandbox inside a container
+RUN echo '{"args":["--no-sandbox"]}' > /home/mercury/.puppeteerrc.json
+ENV CHROMIUM_FLAGS="--no-sandbox"
+
+# Install CLIs
+RUN bun add -g @mariozechner/pi-coding-agent@^0.67.2
+
+WORKDIR /app
+
+COPY container/agent-package.json /app/package.json
+RUN bun install --production
+
+# Patch pi: skip thinkingConfig for Gemma models (Google API rejects thinkingBudget for them,
+# but pi marks gemma-4 as reasoning:true and sends thinkingBudget:0 to disable it)
+RUN node <<'EOF'
+const fs = require('fs'), path = require('path');
+function patch(dir) {
+  try {
+    for (const f of fs.readdirSync(dir)) {
+      const p = path.join(dir, f);
+      try {
+        if (fs.statSync(p).isDirectory()) patch(p);
+        else if (f === 'google.js' && p.includes('@mariozechner/pi-ai')) {
+          let c = fs.readFileSync(p, 'utf8');
+          const noThinking = '&& !model.id.startsWith("gemma")';
+          const p1 = 'if (options.thinking?.enabled && model.reasoning) {';
+          const p2 = 'else if (model.reasoning && options.thinking && !options.thinking.enabled) {';
+          if (!c.includes(noThinking)) {
+            c = c.replace(p1, 'if (options.thinking?.enabled && model.reasoning ' + noThinking + ') {');
+            c = c.replace(p2, 'else if (model.reasoning && options.thinking && !options.thinking.enabled ' + noThinking + ') {');
+            fs.writeFileSync(p, c);
+            console.log('Patched:', p);
+          }
+        }
+      } catch(e) {}
+    }
+  } catch(e) {}
+}
+patch('/home/mercury/.bun');
+patch('/app/node_modules');
+EOF
+
+COPY src/agent/container-entry.ts /app/src/agent/container-entry.ts
+COPY src/agent/model-capabilities-core.ts /app/src/agent/model-capabilities-core.ts
+COPY src/agent/pi-failure-class.ts /app/src/agent/pi-failure-class.ts
+COPY src/agent/pi-jsonl-parser.ts /app/src/agent/pi-jsonl-parser.ts
+COPY src/agent/preferences-prompt.ts /app/src/agent/preferences-prompt.ts
+COPY src/cli/mrctl.ts /app/src/cli/mrctl.ts
+COPY src/cli/mrctl-http.ts /app/src/cli/mrctl-http.ts
+COPY src/extensions/reserved.ts /app/src/extensions/reserved.ts
+COPY src/extensions/permission-guard.ts /app/src/extensions/permission-guard.ts
+COPY src/types.ts /app/src/types.ts
+COPY resources/ /app/resources/
+COPY examples/extensions/ /tmp/examples-extensions/
+RUN while IFS= read -r ext || [ -n "$ext" ]; do \
+      ext=$(echo "$ext" | xargs); \
+      [ -z "$ext" ] && continue; \
+      cp -r "/tmp/examples-extensions/$ext" "/app/resources/extensions/$ext"; \
+    done < /app/resources/builtin-extensions.txt && \
+    rm -rf /tmp/examples-extensions/
+
+RUN echo '#!/bin/sh\nbun run /app/src/cli/mrctl.ts "$@"' > /usr/local/bin/mrctl && \
+    chmod +x /usr/local/bin/mrctl
+
+# Fix ownership of all mercury home dir artifacts before switching user
+RUN chown -R mercury:mercury /home/mercury
+
+USER mercury
+
+ENTRYPOINT ["bun", "run", "/app/src/agent/container-entry.ts"]

package/container/Dockerfile.power

@@ -0,0 +1,17 @@
+# syntax=docker/dockerfile:1
+# Mercury Agent Container — Power tier
+# Extends Base with: python3 + pip + venv, build-essential, jq, ffmpeg, bubblewrap
+# The patch script, mrctl, and entrypoint are all inherited from Base — not duplicated here.
+ARG BASE_TAG
+FROM ghcr.io/michaelliv/mercury-agent:${BASE_TAG}-base
+
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 python3-pip python3-venv build-essential \
+    jq \
+    ffmpeg \
+    # Sandboxing: bubblewrap for defense-in-depth in runc mode.
+    # Not used when CONTAINER_RUNTIME=runsc (gVisor handles isolation at the syscall boundary).
+    bubblewrap \
+    && rm -rf /var/lib/apt/lists/*
+USER mercury

package/container/agent-package.json

@@ -0,0 +1,8 @@
+{
+  "name": "mercury-agent-app",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.67.2"
+  }
+}

package/container/build.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# Build the Mercury agent container images
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_ROOT"
+
+IMAGE_NAME="mercury-agent"
+
+# Parse arguments
+BUILD_ALL=false
+BUILD_LATEST=false
+BUILD_MINIMAL=false
+
+if [ $# -eq 0 ]; then
+    BUILD_LATEST=true
+elif [ "$1" = "all" ]; then
+    BUILD_ALL=true
+elif [ "$1" = "latest" ]; then
+    BUILD_LATEST=true
+elif [ "$1" = "minimal" ]; then
+    BUILD_MINIMAL=true
+else
+    echo "Usage: $0 [all|latest|minimal]"
+    echo ""
+    echo "Presets:"
+    echo "  latest   Full devcontainer with Node, Python, Go, git (~2.8GB)"
+    echo "  minimal  Bun + pi + browser only (~1.9GB)"
+    echo "  all      Build both presets"
+    echo ""
+    echo "Default: latest"
+    exit 1
+fi
+
+if [ "$BUILD_ALL" = true ] || [ "$BUILD_LATEST" = true ]; then
+    echo "Building ${IMAGE_NAME}:latest (full devcontainer)..."
+    docker build -f container/Dockerfile -t "${IMAGE_NAME}:latest" .
+    echo "✓ Built ${IMAGE_NAME}:latest"
+    echo ""
+fi
+
+if [ "$BUILD_ALL" = true ] || [ "$BUILD_MINIMAL" = true ]; then
+    echo "Building ${IMAGE_NAME}:minimal (bun-only)..."
+    docker build -f container/Dockerfile.minimal -t "${IMAGE_NAME}:minimal" .
+    echo "✓ Built ${IMAGE_NAME}:minimal"
+    echo ""
+fi
+
+echo "Build complete!"
+if [ "$BUILD_ALL" = true ]; then
+    echo "  ${IMAGE_NAME}:latest  - Full devcontainer (~2.8GB)"
+    echo "  ${IMAGE_NAME}:minimal - Bun + pi + browser (~1.9GB)"
+fi

package/docs/TODOS.md

@@ -0,0 +1,147 @@
+# Mercury — Remaining TODOs
+
+This document tracks gaps identified in the comprehensive code review that are not yet addressed. Items are ordered by priority (security first, then reliability, then polish).
+
+---
+
+## Security
+
+### TODO-1: Protect dashboard root routes
+
+**Status:** Open  
+**Priority:** Medium  
+**Files:** `src/server.ts`
+
+**Issue:** `GET /` and `GET /dashboard` serve the dashboard HTML without authentication. Only `/dashboard/*` (htmx partials, API, SSE) is protected. Users can load the HTML shell without a token.
+
+**Fix:** Apply the same auth middleware to `/` and `/dashboard`, or redirect unauthenticated requests to a login page. When `MERCURY_API_SECRET` is set, require Bearer token or `mercury_token` cookie for these routes.
+
+---
+
+### TODO-2: Harden permission guard
+
+**Status:** Open  
+**Priority:** Medium  
+**Files:** `src/extensions/permission-guard.ts`
+
+**Issue:** The permission guard blocks CLI names via regex on bash commands. It can be bypassed by:
+- `env napkin search "query"`
+- `` `which napkin` search "query" ``
+- `python3 -c "import subprocess; subprocess.run(['napkin', ...])"`
+- Path-based execution: `/root/.bun/bin/napkin`
+
+**Fix options:**
+1. Run denied CLIs through an allowlist/blocklist at the pi tool-call layer (if the pi API supports it)
+2. Use a wrapper script that validates the command before execution
+3. Document that this is defense-in-depth only; rely on extension trust model
+4. Consider seccomp or additional bwrap restrictions to limit subprocess execution
+
+**Note:** Bubblewrap limits filesystem access but does not prevent the agent from invoking allowed binaries. The permission guard remains the primary control for which CLIs run.
+
+---
+
+### TODO-3: Sanitize extension install commands
+
+**Status:** Open  
+**Priority:** Low  
+**Files:** `src/extensions/image-builder.ts`
+
+**Issue:** Extension `install` commands are interpolated directly into Dockerfile `RUN` statements. A malicious extension could inject shell commands that exfiltrate secrets or modify the image.
+
+**Fix options:**
+1. Validate install commands against an allowlist (e.g. `bun add -g X`, `npm install -g X`)
+2. Run install commands in a sandboxed build step
+3. Document that extensions are trusted by design (operator installs them); recommend auditing before `mercury add`
+
+---
+
+## Reliability
+
+### TODO-4: Database migration system
+
+**Status:** Open  
+**Priority:** Medium  
+**Files:** `src/storage/db.ts`, new `src/storage/migrations/`
+
+**Issue:** Schema evolution uses `CREATE TABLE IF NOT EXISTS` only. Adding columns, changing types, or renaming tables has no migration path.
+
+**Fix:** Implement a simple migration system:
+1. Create `migrations/` directory with sequential SQL files (`001_initial.sql`, `002_add_mutes.sql`, …)
+2. Add `schema_migrations` table to track applied migrations
+3. On startup, run any migrations not yet applied
+4. Document migration authoring in `docs/`
+
+---
+
+### TODO-5: Outbox scan race condition
+
+**Status:** Open  
+**Priority:** Low  
+**Files:** `src/core/outbox.ts`, `src/agent/container-runner.ts`
+
+**Issue:** Outbox scanning uses mtime comparison against `startTime`. Files written at exactly `startTime` or during clock skew could be missed or incorrectly included.
+
+**Fix:** Use a more robust approach (e.g. track written files explicitly, or use a small time buffer). Document the current behavior and edge cases.
+
+---
+
+## Operations
+
+### TODO-6: Run containers as non-root
+
+**Status:** Open  
+**Priority:** Low  
+**Files:** `container/Dockerfile`, `container/Dockerfile.minimal`, `src/agent/container-runner.ts`
+
+**Issue:** Containers run as root. Chromium uses `--no-sandbox` because it runs as root. This increases blast radius if the container is compromised.
+
+**Fix:**
+1. Create a non-root user in the Dockerfile
+2. Run the entrypoint as that user (`USER mercury` or similar)
+3. Ensure Chromium can run without `--no-sandbox` (may require `--user-data-dir` and other flags, or use a different approach)
+4. Update `container-runner.ts` if `docker run` needs `--user` override
+
+**Note:** Bubblewrap runs as the same user as the parent process. Moving the container to non-root would also make bwrap run as non-root, reducing privilege further.
+
+---
+
+### TODO-7: CORS configuration
+
+**Status:** Open  
+**Priority:** Low  
+**Files:** `src/server.ts`
+
+**Issue:** No CORS headers are set. When Mercury is behind a reverse proxy or accessed from a browser on another origin, cross-origin requests may fail or behave unexpectedly.
+
+**Fix:** Add configurable CORS middleware (e.g. `MERCURY_CORS_ORIGINS`). Default to restrictive (same-origin or empty) for security.
+
+---
+
+## In-Memory State (Deferred)
+
+### TODO-8: Crash-safe rate limiter and queue
+
+**Status:** Deferred  
+**Priority:** Low  
+**Files:** `src/core/rate-limiter.ts`, `src/core/space-queue.ts`
+
+**Issue:** Rate limiter and queue are in-memory. On crash, rate limit windows reset (allowing burst abuse) and queued work is lost.
+
+**Fix:** Persist rate limit state and queue to SQLite or Redis. Adds complexity; may be acceptable for single-node deployments. Revisit if multi-instance or high-availability is required.
+
+---
+
+## Bubblewrap — What It Mitigates
+
+Bubblewrap adds **defense-in-depth** inside the container:
+
+| Risk | Mitigated by bubblewrap? |
+|------|--------------------------|
+| **Cross-space data access** | Partially — with per-space mount, `/spaces` only has one space. Bwrap further restricts the pi process to a minimal mount set. |
+| **Arbitrary filesystem access** | Yes — pi only sees `/usr`, `/app`, `/etc`, `/docs`, `/spaces`, `/root`, `/proc`, `/dev`, `/tmp`. Cannot access other paths. |
+| **Process isolation** | Yes — `--unshare-pid`, `--new-session`, `--die-with-parent` limit process visibility and lifecycle. |
+| **Permission guard bypass** | No — bwrap limits *what* the agent can access, not *which commands* it runs. A bypassed guard could still invoke allowed binaries. |
+| **Extension install injection** | No — that happens at image build time, before bwrap runs. |
+| **Container non-root** | No — bwrap runs as the same user (root) as the container. Moving to non-root would improve both. |
+
+**Summary:** Bubblewrap reduces blast radius if the agent is compromised. It does not replace the permission guard, API auth, or other controls. It is a valuable additional layer.

package/docs/auth/dashboard.md

@@ -0,0 +1,28 @@
+# Dashboard Authentication
+
+The Mercury dashboard (`/dashboard/*`) is protected by `MERCURY_API_SECRET`. All htmx partial requests and the SSE events stream require a valid `mercury_token` session cookie.
+
+## How it works
+
+### Login route
+
+`GET /dashboard/login?token=<secret>` — the entry point for browser sessions.
+
+- Validates `token` against `MERCURY_API_SECRET` using `timingSafeEqual`
+- On success: sets `mercury_token` HttpOnly cookie and redirects to `/dashboard`
+- On failure: returns `401 Invalid or missing token`
+- Not protected by the dashboard auth middleware (it's the login endpoint itself)
+
+## Auth flow
+
+```
+User navigates to https://<host>:<port>/dashboard/login?token=<MERCURY_API_SECRET>
+  → agent sets mercury_token HttpOnly cookie
+  → 302 /dashboard
+  → dashboard loads, htmx requests include cookie ✅
+```
+
+## Key constraints
+
+- `MERCURY_API_SECRET` should be set to a long random string. `mercury setup` auto-generates one.
+- The cookie is HttpOnly — not accessible from JavaScript.

package/docs/auth/overview.md

@@ -0,0 +1,109 @@
+# Authentication
+
+Mercury needs credentials for two things:
+
+1. **AI model provider** — to call the LLM (Anthropic, OpenAI, etc.)
+2. **Chat platforms** — to connect to WhatsApp, Discord, Slack, Teams
+
+## Model Provider Auth
+
+### OAuth Login (Recommended)
+
+Mercury reuses [pi](https://github.com/badlogic/pi)'s OAuth providers. No API key needed — just login:
+
+```bash
+mercury auth login              # Interactive provider picker
+mercury auth login anthropic    # Or specify directly
+```
+
+Supported providers:
+
+| Provider | ID | What it gives you |
+|----------|----|-------------------|
+| Anthropic (Claude Pro/Max) | `anthropic` | Claude access via your subscription |
+| GitHub Copilot | `github-copilot` | Models via Copilot subscription |
+| Google Gemini CLI | `google-gemini-cli` | Gemini via Google Cloud |
+| Antigravity | `antigravity` | Gemini 3, Claude, GPT-OSS via Google Cloud |
+| ChatGPT Plus/Pro | `openai-codex` | OpenAI models via ChatGPT subscription |
+
+Credentials are saved to `.mercury/global/auth.json` and auto-refreshed when expired.
+
+### API Key
+
+Alternatively, set an API key in `.env`:
+
+```bash
+MERCURY_ANTHROPIC_API_KEY=sk-ant-...
+# or
+MERCURY_ANTHROPIC_OAUTH_TOKEN=sk-ant-oat01-...
+```
+
+### Resolution Order
+
+Mercury resolves credentials in this order:
+
+1. OAuth credentials from `auth.json` (via `mercury auth login`)
+2. `MERCURY_ANTHROPIC_OAUTH_TOKEN` from `.env`
+3. `MERCURY_ANTHROPIC_API_KEY` from `.env`
+
+> **OAuth always takes precedence over API keys.** If a provider has both an OAuth connection (in `auth.json` or `MERCURY_*_OAUTH_TOKEN`) and an API key (`MERCURY_*_API_KEY`), the OAuth token is used and the API key is ignored. This applies both to the CLI and to agents provisioned via the cloud console.
+
+### Managing Credentials
+
+```bash
+mercury auth status             # Show what's configured
+mercury auth logout anthropic   # Remove saved credentials
+mercury auth logout             # List what's logged in
+```
+
+## Chat Platform Auth
+
+### WhatsApp
+
+```bash
+mercury auth whatsapp                              # QR code (recommended)
+mercury auth whatsapp --pairing-code --phone 1234   # Pairing code (headless)
+```
+
+See [whatsapp.md](whatsapp.md) for details.
+
+### Discord
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_DISCORD=true
+MERCURY_DISCORD_BOT_TOKEN=your-bot-token
+```
+
+### Slack
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_SLACK=true
+MERCURY_SLACK_BOT_TOKEN=xoxb-...
+MERCURY_SLACK_SIGNING_SECRET=...
+```
+
+### Teams
+
+Set in `.env`:
+
+```bash
+MERCURY_ENABLE_TEAMS=true
+MERCURY_TEAMS_APP_ID=...
+MERCURY_TEAMS_APP_PASSWORD=...
+MERCURY_TEAMS_APP_TENANT_ID=...
+```
+
+## Dashboard Auth
+
+The web dashboard is protected by `MERCURY_API_SECRET`. Browser sessions are established via a login handshake managed by the cloud console — see [dashboard.md](dashboard.md).
+
+## Security
+
+- `auth.json` has `0600` permissions (owner read/write only)
+- WhatsApp credentials in `.mercury/whatsapp-auth/` are sensitive — treat like passwords
+- All `MERCURY_*` env vars are passed into containers with the prefix stripped
+- Never commit `.env` or `auth.json` to version control

package/docs/auth/whatsapp.md

@@ -0,0 +1,173 @@
+# WhatsApp Authentication
+
+Mercury connects to WhatsApp using the [Baileys](https://github.com/WhiskeySockets/Baileys) library, which implements the WhatsApp Web protocol. This means you need to link your WhatsApp account just like you would link WhatsApp Web.
+
+## Initial Setup
+
+### QR Code Mode (Recommended)
+
+The simplest way to authenticate:
+
+```bash
+mercury auth whatsapp
+```
+
+This will:
+1. Display a QR code in your terminal
+2. Wait for you to scan it with WhatsApp
+3. Save credentials to `.mercury/whatsapp-auth/`
+4. Exit when authentication is complete
+
+**To scan:**
+1. Open WhatsApp on your phone
+2. Tap **Settings → Linked Devices → Link a Device**
+3. Point your camera at the QR code
+
+### Pairing Code Mode
+
+If you can't scan QR codes (e.g., running on a remote server), use pairing code mode:
+
+```bash
+mercury auth whatsapp --pairing-code --phone 14155551234
+```
+
+Replace `14155551234` with your phone number (country code + number, no `+` or spaces).
+
+This will:
+1. Request a pairing code from WhatsApp
+2. Display an 8-character code
+3. Wait for you to enter it on your phone
+
+**To pair:**
+1. Open WhatsApp on your phone
+2. Tap **Settings → Linked Devices → Link a Device**
+3. Tap **"Link with phone number instead"**
+4. Enter the code shown in your terminal
+
+## Session Lifecycle
+
+### Session Duration
+
+WhatsApp linked device sessions typically last **~14-20 days** before requiring re-authentication. This is controlled by WhatsApp, not Mercury.
+
+Signs your session has expired:
+- WhatsApp stops receiving messages
+- Logs show `connection closed` with `loggedOut` reason
+- Status file shows `failed:logged_out`
+
+### Re-authentication
+
+If your session expires:
+
+1. **Stop Mercury** (if running):
+   ```bash
+   # Ctrl+C in the terminal running mercury, or
+   pkill -f "bun.*chat-sdk"
+   ```
+
+2. **Delete old credentials**:
+   ```bash
+   rm -rf .mercury/whatsapp-auth/
+   ```
+
+3. **Re-authenticate**:
+   ```bash
+   mercury auth whatsapp
+   ```
+
+4. **Restart Mercury**:
+   ```bash
+   mercury run
+   ```
+
+## Status Files
+
+The auth script writes status files for external monitoring (useful for headless deployments):
+
+| File | Description |
+|------|-------------|
+| `.mercury/whatsapp-status.txt` | Current status (`authenticated`, `waiting_qr`, `pairing_code:XXXX`, `failed:reason`) |
+| `.mercury/whatsapp-qr.txt` | Raw QR data for external rendering (deleted after successful auth) |
+
+### Status Values
+
+- `authenticated` — Successfully connected
+- `already_authenticated` — Existing valid session found
+- `waiting_qr` — Waiting for QR code scan
+- `pairing_code:XXXXXXXX` — Waiting for pairing code entry
+- `failed:logged_out` — Session was logged out by WhatsApp
+- `failed:qr_timeout` — QR code expired before scan
+- `failed:515` — Stream error (usually recovers automatically)
+- `failed:unknown` — Other connection failure
+
+## Auth Status API Endpoint
+
+When Mercury is running, you can check auth status via the API:
+
+```bash
+curl http://localhost:8787/auth/whatsapp
+```
+
+**Responses:**
+
+```json
+// Authenticated and connected
+{ "status": "authenticated" }
+
+// Waiting for QR scan (includes raw QR data)
+{ "status": "waiting", "qr": "2@AbCdEf123..." }
+
+// Disconnected or not yet connected
+{ "status": "disconnected" }
+```
+
+This endpoint requires no authentication, making it suitable for headless monitoring dashboards.
+
+## Troubleshooting
+
+### "Already authenticated"
+
+If you see this but WhatsApp isn't working:
+```bash
+rm -rf .mercury/whatsapp-auth/
+mercury auth whatsapp
+```
+
+### QR code times out too quickly
+
+WhatsApp QR codes expire after ~20 seconds. If you're having trouble:
+1. Have your phone ready before running the command
+2. Use `--pairing-code` mode instead
+
+### "Stream error (515)"
+
+This is usually transient and the auth script will automatically reconnect. If it persists:
+```bash
+rm -rf .mercury/whatsapp-auth/
+mercury auth whatsapp
+```
+
+### WhatsApp shows "Linked Device" but Mercury doesn't receive messages
+
+1. Check that `MERCURY_ENABLE_WHATSAPP=true` is set in `.env`
+2. Check logs for connection errors
+3. Try re-authenticating
+
+### Messages from before startup appear
+
+Mercury ignores messages that were sent before it connected to prevent processing old backlog. This is intentional.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MERCURY_ENABLE_WHATSAPP` | `false` | Enable WhatsApp adapter |
+| `MERCURY_WHATSAPP_AUTH_DIR` | `.mercury/whatsapp-auth` | Directory for auth credentials |
+| `MERCURY_DATA_DIR` | `.mercury` | Base data directory (auth dir is relative to this) |
+
+## Security Notes
+
+- Auth credentials in `.mercury/whatsapp-auth/` are sensitive — treat them like passwords
+- Anyone with access to these files can impersonate your WhatsApp account
+- The `/auth/whatsapp` endpoint is unauthenticated — only expose your API port to trusted networks
+- Consider using a dedicated WhatsApp number for your bot