diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c83717e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Run all tests
+source .venv/bin/activate && pytest tests/
+
+# Run a single test file
+pytest tests/test_router.py
+
+# Run a specific test
+pytest tests/test_router.py::test_clear_command -v
+
+# Start the bot (via systemd)
+systemctl --user start echo-core
+
+# Start manually (foreground)
+source .venv/bin/activate && python3 src/main.py
+
+# WhatsApp bridge
+systemctl --user start echo-whatsapp-bridge
+
+# CLI diagnostics
+./cli.py status
+./cli.py doctor
+
+# Install dependencies
+source .venv/bin/activate && pip install -r requirements.txt
+```
+
+## Architecture
+
+**Message flow:** Adapter → `router.py` → `claude_session.py` → Claude CLI subprocess → response split → Adapter sends reply.
+
+Three adapters run concurrently in one asyncio event loop via `asyncio.gather()` in `src/main.py`:
+
+- **Discord** (`src/adapters/discord_bot.py`): discord.py slash commands, 2000 char split
+- **Telegram** (`src/adapters/telegram_bot.py`): python-telegram-bot commands + inline keyboards, 4096 char split
+- **WhatsApp** (`src/adapters/whatsapp.py`): polls Node.js Baileys bridge (`bridge/whatsapp/index.js`) at `http://127.0.0.1:8098` every 2s, 4096 char split
+
+All adapters follow the same pattern: module-level `_config`, authorization helpers (`is_owner`, `is_admin`, `is_registered_channel`), `split_message()`, and routing through `route_message(channel_id, user_id, text, model)`.
+
+**Claude sessions** (`src/claude_session.py`): Each channel has one persistent session. `send_message()` auto-starts or resumes via `claude --resume <session_id>`. System prompt is built by concatenating `personality/*.md` files. External messages are wrapped in `[EXTERNAL CONTENT]` injection markers. Sensitive env vars are stripped before subprocess execution.
+
+**Session state** lives in `sessions/active.json` — maps channel IDs to `{session_id, model, message_count, ...}`.
+
+**Credentials** (`src/credential_store.py`): All tokens stored in system keyring under service `"echo-core"`. Required: `discord_token`. Optional: `telegram_token`. Never pass secrets as CLI arguments — use stdin.
+
+**Config** (`src/config.py`): Loads `config.json` with dot-notation access (`config.get("bot.name")`). Channel namespaces: `channels` (Discord), `telegram_channels`, `whatsapp_channels`.
+
+**Scheduler** (`src/scheduler.py`): APScheduler loading jobs from `cron/jobs.json`, runs Claude prompts in isolated sessions.
+
+**Heartbeat** (`src/heartbeat.py`): Periodic checks (email, calendar, KB, git), quiet hours 23-08.
+
+**Memory search** (`src/memory_search.py`): Ollama all-minilm embeddings (384 dim) + SQLite cosine similarity.
+
+## Import Convention
+
+All modules use absolute imports from project root via `sys.path.insert(0, PROJECT_ROOT)`. Import as `from src.config import ...`, `from src.adapters.discord_bot import ...`. No circular imports — adapters → router → claude_session.
+
+## Key Files
+
+| Path | Role |
+|------|------|
+| `src/main.py` | Entry point — starts all adapters + scheduler + heartbeat |
+| `src/router.py` | Dispatches commands vs Claude messages |
+| `src/claude_session.py` | Claude CLI wrapper with `--resume` |
+| `src/credential_store.py` | Keyring secrets (service: `echo-core`) |
+| `cli.py` | CLI tool (status, doctor, logs, secrets, cron, whatsapp) |
+| `config.json` | Runtime config (channels, admins, models, bridges) |
+| `setup.sh` | Interactive 10-step onboarding wizard |
+| `bridge/whatsapp/index.js` | Node.js Baileys + Express bridge on port 8098 |
+| `personality/*.md` | System prompt files concatenated in order |