mercury-agent 0.16.0 → 0.16.2

package/docs/goals/whatsapp-bot-hardening/archive/setup-plan-2026-08-06.md

@@ -0,0 +1,1117 @@
+> **ARCHIVED 2026-08-10 — Phases 0–5 complete, the bot is live.**
+>
+> Kept for the traps and the config reference, which are still accurate and
+> still the only record of several live settings. **Parts of it are now stale:**
+>
+> | Section | Status |
+> |---|---|
+> | Decision C/D (Gemini API key, `gemini-*` models) | **Superseded** — the bot runs `claude-opus-5` over Claude-subscription OAuth. The whole "Free-tier rate limits" section is history, not current config. |
+> | Decision E (install via global npm) | **Superseded** by D-001 — the service runs from the `~/mercury-src` git checkout. `npm update -g` is no longer part of upgrades, so the "erases both patches" warning no longer applies. |
+> | "`mercury auth status` is cwd-sensitive" | **Fixed 2026-08-10** — see the roadmap's "The cwd trap" section. |
+> | `media.max_size_mb: 10` implications | **Superseded** — raised to 64 (D-004). |
+> | Phase 5 "Personality / tone → `AGENTS.md` … or `mrctl character set`" | **Incomplete** — there are five prompt layers, not two. See `open-threads.md` §A. |
+> | Risk register row on the `.dockerignore` build fix | **Fixed and committed** in the hardening branch. |
+>
+> Still live and unresolved from this file: **WSL does not auto-start** after
+> `wsl --shutdown` or a Windows reboot ("Keeping it running"). Tracked in
+> `docs/goals/whatsapp-bot-hardening/open-threads.md` §D.
+
+# WhatsApp Bot on Mercury — Setup Plan
+
+Personal WhatsApp assistant, running locally, built on
+[Mercury](https://github.com/Avishai-Tsabari/mercury) (v0.8.12).
+
+Project layout:
+
+```
+D:\Projects\whatsapp-bot\
+├── mercury\      # cloned source repo (reference + `mercury build` source)
+└── PLAN.md       # this file
+```
+
+The runtime project (`.env`, `mercury.yaml`, `.mercury/`) does **not** live here —
+see Phase 0, decision A.
+
+---
+
+## What Mercury actually is
+
+A host process (Bun) that runs platform adapters (WhatsApp via Baileys, Slack,
+Discord, Telegram), a router/queue, and a SQLite DB. Each incoming message is
+routed to a **space** (a memory boundary), and the agent for that space runs
+**inside a Docker container** using [pi](https://github.com/badlogic/pi) as the
+LLM runtime. There's also a web dashboard on port 8787.
+
+```
+WhatsApp adapter ─┐
+Scheduler ────────┼─→ Router/Queue → SQLite → Docker container (pi CLI)
+                  ┘                            /spaces/<space-id>
+```
+
+Consequences for us:
+
+- **Docker is mandatory.** No Docker, no agent. The base image is ~2.8 GB.
+- WhatsApp uses the **linked-devices** protocol (Baileys). **Corrected
+  2026-08-06:** there is *no* fixed re-scan interval. The 14-day clock is on the
+  **primary phone being offline** — linked devices are force-logged-out only if
+  the phone goes 14 days without connecting to WhatsApp at all. Keep the bot's
+  phone online (or open the app once a fortnight) and the link persists
+  indefinitely. See "Re-auth" under Ongoing operations.
+- Out of the box there is no web search, no browsing, no vault, no voice — those
+  are extensions (`mercury add web-browser`, `mercury add napkin`, …).
+
+---
+
+## Environment audit (2026-08-05)
+
+| Requirement | Status |
+|---|---|
+| Git 2.50.1 | OK |
+| Node v24.18.1 (≥18) | OK |
+| Bun 1.3.14 on Windows (≥1.2) | OK — but see below |
+| **WSL2** | **MISSING** — kernel not installed, zero distros |
+| **Docker** | **MISSING** — not on PATH at all |
+
+The Windows-side Bun does not help: Mercury's README states it "runs best under
+WSL2", and the agent sandbox uses **bubblewrap** inside the container, which is
+Linux-only. Everything must run inside WSL2, so Bun has to be installed *there*
+too.
+
+**These two gaps are the whole critical path.** Nothing else can be tested until
+they're closed.
+
+---
+
+## Phase 0 — Decisions (RESOLVED 2026-08-05)
+
+| # | Decision | Chosen |
+|---|---|---|
+| A | Runtime project location | **WSL ext4 — `~/whatsapp-bot`** (clone stays at `D:\Projects\whatsapp-bot\mercury`) |
+| B | Phone number | **Dedicated number** (second SIM / data-only eSIM) |
+| C | LLM auth | ~~OAuth via Claude subscription~~ → ~~Google AI Studio API key~~ → **re-revised 2026-08-06: OAuth via Claude subscription** (`mercury auth login anthropic`) — verified working |
+| D | Model | ~~`claude-sonnet-5`~~ → ~~`gemini-3.6-flash`~~ → **re-revised 2026-08-06: `claude-opus-5`** (provider `anthropic`) — verified serving, see "Opus 5 vs the google legs" |
+| E | Install method | Global npm — `npm i -g mercury-agent` |
+
+Rationale for each is retained below.
+
+### A. Where does the runtime project live? → WSL ext4
+
+Mercury bind-mounts each space's workspace (`.mercury/spaces/<id>/`) into a
+Docker container. Two options:
+
+| | `/mnt/d/Projects/whatsapp-bot` (Windows drive) | `~/whatsapp-bot` (WSL ext4) |
+|---|---|---|
+| File I/O | Slow (9p/drvfs translation) | Native |
+| Docker bind-mount perms | uid/gid mapping quirks, `chmod` is a no-op | Clean |
+| SQLite | Locking over drvfs is a known problem source | Fine |
+| Editing from Windows | Direct | Via `\\wsl$\Ubuntu\home\...` or VS Code Remote |
+
+**Recommendation:** put the *runtime* project at `~/whatsapp-bot` inside WSL, and
+keep this cloned repo at `D:\Projects\whatsapp-bot\mercury` for reference and for
+`mercury build`. If you'd rather keep everything on `D:`, it will probably work
+but expect slowness and permission friction.
+
+### B. Which phone number? → **dedicated** (reconfirmed 2026-08-05)
+
+Mercury's docs recommend a dedicated number, but the decisive reason is
+structural, not just caution:
+
+> **A personal-number bot cannot be talked to by its owner.** `handler.ts:158`
+> returns immediately on `message.author.isMe`, and the WhatsApp adapter sets
+> that from Baileys' `fromMe` flag (`whatsapp.ts:481`). Every message you send
+> from your own phone on that account is `fromMe: true`, so the bot would ignore
+> you and only ever reply to *other people* messaging your number.
+
+Secondary reasons:
+
+- **Blast radius.** `.mercury/whatsapp-auth/` is password-equivalent; on a
+  personal number a leak is a full takeover of your primary account.
+- **Ban asymmetry.** Baileys is an unofficial client. Losing a burner is an
+  annoyance; losing your primary number costs your history, groups, and contact
+  point.
+- **Keeping the link alive.** Not a fixed re-scan interval (see the corrected
+  note above) — but a *dedicated* SIM that normally sits powered off **will** trip
+  the 14-days-offline rule and force a re-scan. A dedicated number only stays
+  hands-off if its phone stays online.
+
+What a linked device actually exposes, precisely: every message arrives over the
+socket, but **unlinked conversations are dropped at `handler.ts:191`** before any
+storage or LLM call — nothing reaches Gemini. However `resolveConversation` calls
+`db.ensureConversation` *first*, so a metadata row (platform, external ID, kind,
+title) is recorded for every chat that messages the account.
+
+**Alternative considered:** Telegram ingress (`ingress.telegram`) uses the
+*official* Bot API — no number, no QR, no expiry, no ban risk. Worth revisiting
+if the WhatsApp session churn becomes tiresome.
+
+### C. Auth method for the LLM — **revised to Gemini free tier**
+
+Mercury supports four providers by API key (`src/cli/mercury.ts:747`):
+
+| Provider | `.env` key | Default model |
+|---|---|---|
+| `anthropic` | `MERCURY_ANTHROPIC_API_KEY` | `claude-opus-4-8` |
+| `openai` | `MERCURY_OPENAI_API_KEY` | `gpt-4o` |
+| `google` | `MERCURY_GEMINI_API_KEY` | `gemini-2.5-flash` |
+| `groq` | `MERCURY_GROQ_API_KEY` | `llama-3.3-70b-versatile` |
+
+> **Trap — OAuth only works for two of the five providers it offers.**
+> `mercury auth login` advertises `anthropic`, `github-copilot`,
+> `google-gemini-cli`, `antigravity`, and `openai-codex`. But
+> `src/storage/pi-auth.ts:23-25` maps only **`anthropic`** →
+> `ANTHROPIC_OAUTH_TOKEN` and **`github-copilot`** → `COPILOT_GITHUB_TOKEN` into
+> the agent container. The other three have no env var, so the login *succeeds*
+> and the model leg is then "dead on arrival" — logged, not thrown, so it fails
+> quietly at message time rather than at setup. **Gemini must be an API key, not
+> OAuth.**
+
+A **free** Claude account does not grant OAuth for external tools — that flow
+needs Pro or Max. Hence the switch to Google AI Studio's free tier
+(<https://aistudio.google.com/apikey>), which needs no subscription.
+
+Gemini over Groq's Llama because Mercury runs an **agentic loop** (pi, with tool
+use), not single-shot chat, and Llama is markedly weaker at multi-step tool
+calling.
+
+#### Two bugs hit while wiring this up — both cost a full debug cycle
+
+**1. `model.chain` alone is not enough — you must also set `model.provider`.**
+
+Setting only the chain leaves the legacy scalar `modelProvider` at its schema
+default `"anthropic"` (`config.ts:65`), because `config-file.ts:323` assigns it
+only from `model.provider`. The guard at `container-runner.ts:892` reads *that
+scalar*, not the resolved chain — so with a pure-Gemini chain every turn was
+refused with:
+
+```
+Refusing to start container: no Anthropic credential configured
+```
+
+which is actively misleading: nothing in the config mentions Anthropic. The
+working config sets **both** forms:
+
+```yaml
+model:
+  provider: google          # satisfies the container-runner guard
+  model: gemini-3.6-flash
+  chain:
+    - provider: google      # drives the actual request path
+      model: gemini-3.6-flash
+```
+
+**2. `gemini-2.5-flash` is retired for new API keys.** Mercury's own default for
+the `google` provider (`src/cli/mercury.ts:768`) now fails:
+
+```
+404 — This model models/gemini-2.5-flash is no longer available to new users.
+```
+
+It still appears in `GET /v1beta/models`, so *listing a model does not mean you
+can call it*. Probed each candidate with a real `generateContent` call:
+
+| Model | Result |
+|---|---|
+| `gemini-3.6-flash` | ✅ **chosen** |
+| `gemini-3.5-flash` | ✅ |
+| `gemini-flash-latest` | ✅ (alias — tracks newest, can shift under you) |
+| `gemini-3-flash-preview` | ✅ |
+| `gemini-2.0-flash` | ❌ 429 quota |
+
+To re-probe later, list with
+`curl "https://generativelanguage.googleapis.com/v1beta/models?key=$KEY"` and
+then actually POST to `:generateContent` — the list alone will mislead you.
+
+### D. Model
+
+`MERCURY_MODEL` is a free-form string handed to pi (`src/config.ts:66`), so it's
+not pinned to a list. Current options and list pricing per million tokens:
+
+| Model ID | Input | Output |
+|---|---|---|
+| `claude-opus-5` | $5 | $25 |
+| `claude-opus-4-8` (Mercury's default) | $5 | $25 |
+| `claude-sonnet-5` | $3 ($2 intro thru 2026-08-31) | $15 ($10 intro) |
+| `claude-haiku-4-5` | $1 | $5 |
+
+For a personal chat bot, **`claude-sonnet-5`** is the sensible default —
+near-Opus quality on agentic work at ~60% of the cost. Move to `claude-opus-5`
+if you want maximum capability.
+
+Two caveats, both only observable at runtime:
+
+1. pi (`@earendil-works/pi-ai ~0.79.10`) must recognise the ID. If it errors,
+   fall back to `claude-opus-4-8`.
+2. **We chose OAuth (decision C), so the model set is whatever the Claude
+   subscription grants** — that is not the same surface as a pay-per-token API
+   key, and the per-token prices above then don't apply (you're on plan limits
+   instead). If `claude-sonnet-5` isn't reachable over OAuth, either drop to
+   `claude-opus-4-8` or switch to an API key. Verify at Phase 4 with
+   `mercury chat "hello"` before wiring WhatsApp up.
+
+### E. Install method
+
+- **Global npm package** (`npm i -g mercury-agent`) — what the docs assume;
+  `npm update -g` to upgrade. Recommended.
+- **From this clone** (`bun link` in `mercury/`) — only if you intend to modify
+  Mercury itself.
+
+---
+
+## Phase 1 — Close the environment gaps ✅ COMPLETE
+
+### Status
+
+| Item | State |
+|---|---|
+| WSL2 + Ubuntu **26.04 LTS** (`resolute`), user `guysaha` | ✅ done |
+| systemd as PID 1 (`/etc/wsl.conf` already has `[boot] systemd=true`) | ✅ done — `mercury service install` will work |
+| Linux-native Node **v24.19.0** + npm **11.17.0** via nvm (`~/.nvm`) | ✅ done |
+| `unzip` | ✅ `/usr/bin/unzip` |
+| Bun **1.3.14** (Linux, `~/.bun/bin/bun`) | ✅ done |
+| Docker **29.1.3** + buildx **0.30.1**, daemon running, `guysaha` in `docker` group | ✅ done |
+
+### Trap: WSL PATH interop shadows Linux tooling
+
+Before nvm, `bun` and `npm` inside WSL resolved to **Windows** binaries
+(`/mnt/c/Users/.../npm/bun`, `/mnt/c/Program Files/nodejs/npm`). Running
+`npm install -g mercury-agent` in that state would have used the Windows npm and
+installed into the Windows prefix. nvm now prepends `~/.nvm/.../bin`, so Node and
+npm resolve correctly — verify with `which node npm` before any global install.
+
+nvm was chosen over `apt install nodejs npm` deliberately: global installs land in
+`~/.nvm`, so `npm install -g mercury-agent` and later `npm update -g` never need
+sudo.
+
+**Symptom to recognise.** A WSL shell opened *before* the `~/.bashrc` fix will
+still have the old PATH, and every `mercury` command in it dies with:
+
+```
+error: ELOOP reading "\\wsl.localhost\Ubuntu\home\guysaha\.nvm\...\bin\mercury"
+Bun v1.3.14 (Windows x64)
+```
+
+The `mercury` shim is `#!/usr/bin/env bun`, so a stale PATH resolves `bun` to
+`/mnt/c/.../npm/bun` — the **Windows** binary — which sees the Linux script path
+as a UNC share and can't follow npm's symlink chain across it. Fix:
+`exec bash -l`, or open a new terminal. Check with `command -v bun`; it must be
+`/home/guysaha/.bun/bin/bun`, never `/mnt/c/...`.
+
+### What was done
+
+`docker.io` and `docker-buildx` live in the **universe** component and the apt
+lists only indexed main/restricted, so `apt-get update` had to run first:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y unzip docker.io docker-buildx
+sudo usermod -aG docker "$USER"
+sudo systemctl enable --now docker
+```
+
+Followed by `wsl --shutdown` from Windows PowerShell to pick up the new `docker`
+group membership. Verified: `docker info` reports server **29.1.3**, default
+runtime `runc`, reachable as `guysaha` without sudo.
+
+Note this is Docker **Engine**, not Desktop — bubblewrap may not be able to
+create namespaces inside the agent container. Left
+`agent.container_bwrap_docker_compat: false` for now (stronger sandbox); flip it
+to `true` only if the logs show
+`bwrap: Creating new namespace failed: Operation not permitted`.
+
+---
+
+## Phase 2 — Create the assistant project ✅ COMPLETE
+
+Installed and scaffolded at `~/whatsapp-bot` inside WSL:
+
+```bash
+curl -fsSL https://bun.sh/install | bash          # bun 1.3.14 → ~/.bun/bin
+npm install -g --allow-scripts=@whiskeysockets/baileys,@google/genai,protobufjs mercury-agent
+mkdir ~/whatsapp-bot && cd ~/whatsapp-bot
+mercury init                                       # non-interactive twin of `mercury setup`
+```
+
+Three things worth remembering:
+
+1. **`mercury setup` is interactive**; `mercury init` is the scriptable
+   equivalent. It writes `.env`, `.mercury/`, and `mercury.example.yaml`.
+2. **npm 11 blocks postinstall scripts by default.** The first
+   `npm i -g mercury-agent` silently skipped Baileys' and protobufjs'
+   postinstalls — which WhatsApp needs. The `--allow-scripts=` form above fixes
+   it. If you ever reinstall or upgrade, use that flag again.
+3. **`~/.bashrc` now pins Linux tooling ahead of `/mnt/c` interop** (see the
+   PATH trap above) — without it `bun` resolved to the Windows binary.
+
+Configuration split, per Mercury's own convention: non-secrets in
+`mercury.yaml`, secrets in `.env` only.
+
+`mercury.yaml` sets `ingress.whatsapp: true`, the model chain
+(`anthropic` / `claude-sonnet-5`), `trigger.match: mention`, and the agent image.
+`.env` has the Anthropic API key line **commented out** — decision C is OAuth, so
+credentials come from `mercury auth login` instead. A `.gitignore` covering
+`.env`, `.mercury/`, and `node_modules/` was added up front.
+
+> **Trigger semantics, confirmed in `src/core/trigger.ts:65`:** in DMs the bot
+> replies to *everything* — the trigger pattern is optional and stripped if
+> present. `match: mention` only constrains **group** chats. So a DM to the bot
+> number just works.
+
+### Agent image: GHCR is private, so we build locally
+
+`docker pull ghcr.io/avishai-tsabari/mercury-agent:latest` fails with
+`unauthorized` — that package isn't publicly readable. Two ways out:
+
+| | |
+|---|---|
+| `docker login ghcr.io` with a GitHub PAT (`read:packages`) | Fast, but needs a token |
+| **Build from source** (chosen) | No credentials; ~2.8 GB build |
+
+Building from a WSL-side clone at `~/mercury-src` (not `/mnt/d`, which would drag
+the whole build context over drvfs):
+
+```bash
+git clone --depth 1 https://github.com/Avishai-Tsabari/mercury.git ~/mercury-src
+cd ~/mercury-src && bash ./container/build.sh      # → mercury-agent:latest
+```
+
+Built successfully: **`mercury-agent:latest`, 5.16 GB** (larger than the ~2.8 GB
+the docs quote — that figure predates the current Dockerfile). No `ghcr.io/`
+prefix, so `agent.image` in `mercury.yaml` is set to match.
+
+Contents verified inside the image: `bun`, `pi`, `mrctl`, `bwrap` all present.
+Note `.env.example` claims custom images need `agent-browser`, `napkin`, and
+`mercury-ctl` — that comment is **stale**. The real host-bridge binary is
+`mrctl` (`Dockerfile:126`), and `agent-browser`/`napkin` are extension CLIs baked
+into the *derived* image (`mercury-agent-ext:<hash>`) only after
+`mercury add web-browser` / `mercury add napkin`. Nothing is missing.
+
+### Bubblewrap needs compat mode — confirmed empirically
+
+Rather than wait to discover this at first message, both modes were tested
+directly against the built image:
+
+```bash
+docker run --rm --entrypoint sh mercury-agent:latest \
+  -c 'bwrap --dev-bind / / --proc /proc --tmpfs /tmp true'
+# → bwrap: No permissions to create new namespace
+
+docker run --rm --security-opt seccomp=unconfined --cap-add SYS_ADMIN \
+  --entrypoint sh mercury-agent:latest \
+  -c 'bwrap --dev-bind / / --proc /proc --tmpfs /tmp true'
+# → OK
+```
+
+So `agent.container_bwrap_docker_compat: true` is **required** on this host and
+is already set. Bubblewrap stays enabled — this loosens the outer Docker sandbox
+but keeps the inner one, which is the better trade than
+`MERCURY_DISABLE_BUBBLEWRAP=1`.
+
+### `mercury doctor` after Phase 2
+
+**5 passed, 2 warnings, 2 errors.** Both errors are the interactive steps below
+(AI credentials, WhatsApp auth); one warning clears when you set
+`permissions.admins`, the other when the DB is created on first run. Everything
+mechanical is green: Docker, agent image found, Bun 1.3.14, `.env`, port 8787.
+
+---
+
+## Phase 3 — Link WhatsApp ✅ COMPLETE
+
+### Model pipeline — ✅ verified end to end
+
+`mercury chat "Reply with exactly: it works"` → `it works`. That exercises HTTP →
+router → Docker container → pi → Gemini → reply, so the whole runtime is proven
+before WhatsApp is added.
+
+Two confirmations from that run:
+
+- **bwrap compat is working** — `Enabling bwrap Docker compat with --privileged
+  (containerBwrapDockerCompat=true)`, then `Container started`.
+- **`mercury chat` needs the service running.** It POSTs to
+  `http://localhost:8787/chat` (`src/cli/mercury.ts:2037`); with nothing
+  listening it fails with the unhelpful `Error: Unable to connect. Is the
+  computer able to access the url?`
+
+### Remaining: the QR scan
+
+`docs/setup-whatsapp.md` runs `mercury auth whatsapp` **before**
+`mercury service install`, and its re-auth procedure stops the service first —
+two processes must not contend for `.mercury/whatsapp-auth/`. The service was
+installed early here, so it has been **stopped**; start it again after auth.
+
+If Gemini's free tier proves too rate-limited in practice, uncomment the
+`anthropic` fallback leg in `mercury.yaml` — the chain falls through only when
+the earlier leg fails. Then:
+
+```bash
+mercury auth whatsapp            # prints a QR in the terminal
+```
+
+On the **dedicated** phone (decision B): **Settings → Linked Devices → Link a
+Device**, scan. If the QR expires too fast, use
+`mercury auth whatsapp --pairing-code --phone <number>`.
+
+The command prints the bot's WhatsApp ID on success. Put **your own** ID (the
+number you'll message the bot *from*) into `mercury.yaml` → `permissions.admins`.
+Mercury canonicalises WhatsApp's LID (`24417...@lid`) vs phone JID
+(`972...@s.whatsapp.net`) forms; the dashboard's Conversations page shows which
+form you have.
+
+**Result:** linked and connected (`WhatsApp connection open`).
+
+| | |
+|---|---|
+| Bot account | `972552538335:1@s.whatsapp.net` — "ויצ דה בוט" |
+| Bot LID | `136043810578453:1@lid` |
+| Admin (you) | `whatsapp:972503515999@s.whatsapp.net` |
+
+> **`mercury doctor`'s "No AI credentials configured" is a false positive on any
+> non-Anthropic provider.** `src/cli/mercury.ts:513-516` checks only
+> `MERCURY_ANTHROPIC_API_KEY`, `MERCURY_ANTHROPIC_OAUTH_TOKEN`, and `auth.json`
+> — it has no branch for `MERCURY_GEMINI_API_KEY`, `MERCURY_OPENAI_API_KEY`, or
+> `MERCURY_GROQ_API_KEY`, even though `mercury setup` offers all four. Ignore
+> that one error on this deployment; the "Port 8787 in use" warning is Mercury
+> itself.
+
+---
+
+## Phase 4 — First run and wiring conversations ✅ COMPLETE — **BOT IS LIVE**
+
+A WhatsApp DM to the bot number gets a reply. Confirmed round trip:
+
+```
+Message from: whatsapp:972503515999@s.whatsapp.net (סהר ויצמן)
+Container started spaceId=main
+Container exited exitCode=0 durationMs=6773
+WhatsApp outbound chatJid=972503515999@s.whatsapp.net
+```
+
+**~7 s per turn** — Mercury starts a fresh container for every message.
+
+### Gotcha: messages sent while the service is down are lost
+
+The first test message never arrived. Baileys drops anything delivered before
+`WhatsApp connection open`, and the service was stopped for the QR scan. Nothing
+was broken — the message simply predated the connection. Verify with
+`journalctl --user -u mercury | grep "connection open"` before concluding the
+adapter is at fault.
+
+Debug logging (`runtime.log_level: debug`) is what made this visible: `Incoming
+message ... isMe=false` and `Message ignored: conversation not linked to a space`
+are both DEBUG-level. It has since been set back to `info`.
+
+
+
+The systemd **user** unit is already installed at
+`~/.config/systemd/user/mercury.service`, so after the QR scan just start it:
+
+```bash
+systemctl --user start mercury
+mercury service status
+mercury service logs -f
+```
+
+> **Cosmetic upstream bug:** the generated unit writes
+> `Environment=PATH=<...>` unquoted, and the WSL-interop PATH is full of
+> `/mnt/c/Program Files/...` entries with spaces. systemd logs ~40
+> `Invalid environment assignment, ignoring: Files` warnings and truncates PATH
+> at the first space. Harmless here — `/usr/bin` (and therefore `docker`) comes
+> before the truncation point — but the warnings are noise, and on a differently
+> ordered PATH it would break container spawning. Fix upstream is quoting:
+> `Environment="PATH=<...>"`.
+
+Never use `mercury run` directly (per the repo's own `CLAUDE.md`): it blocks the
+terminal and won't auto-restart.
+
+Then, because conversations start **unlinked**:
+
+```bash
+mercury spaces create main
+# message the bot number from your phone, then:
+mercury conversations --unlinked
+mercury link <conversation-id> main
+```
+
+**Exit criteria:** a WhatsApp DM to the bot number gets a reply.
+
+### If the agent container fails to start
+
+The bwrap namespace failure was already found and fixed pre-emptively (see Phase
+2), so the most likely cause is gone. If containers still fail, check
+`mercury service logs -f` — and if you see a bwrap error anyway, the last resort
+is `MERCURY_DISABLE_BUBBLEWRAP=1`, which removes a security layer.
+
+---
+
+## Phase 5 — Make it actually useful
+
+Pick from these; each is optional.
+
+| Want | Do |
+|---|---|
+| Web search / browsing | `mercury add web-browser` (uses Brave, no API key) |
+| Obsidian-style knowledge vault | `mercury add napkin` |
+| Personality / tone | `AGENTS.md` in the space workspace, or bot-wide character via `mrctl character set` |
+| Scheduled prompts ("brief me at 8am") | `mrctl tasks create` — see `docs/scheduler.md` |
+| Web UI | Dashboard on `http://localhost:8787` — spaces, tasks, permissions, extensions |
+| Separate work/family/personal memory | More spaces + `mercury link` |
+| Voice notes, images, documents | Supported natively — `docs/media/overview.md` |
+
+Extensions with CLIs trigger a derived Docker image rebuild
+(`mercury-agent-ext:<hash>`) on next start. That's automatic; expect a slow first
+boot after adding one.
+
+---
+
+## Web browsing — installed, and why it was silently broken
+
+`Extensions loaded count=2` (`web-browser`, `voice-transcribe`) and the derived
+image `mercury-agent-ext:e2c502ed9498` (5.25 GB) builds in ~3.4 min. Despite
+that, the agent could not reach a single public URL.
+
+### Three separate traps, in the order they bite
+
+**1. `mercury add web-browser` does not work.** `README.md:169` and
+`docs/web-search.md` both say to run it; the CLI rejects it — `add` only accepts
+a path, `npm:`, `git:`, or `user/repo`. The name `web-browser` is a *dashboard
+catalog* label (`src/extensions/catalog.ts:29`) whose `sourceDir` is `pinchtab`.
+From the CLI the real command is:
+
+```bash
+mercury add ~/.nvm/versions/node/<ver>/lib/node_modules/mercury-agent/examples/extensions/pinchtab
+```
+
+…which installs it under the name `pinchtab`, **duplicating** a dashboard-installed
+`web-browser` (same CLI, skill, and permission). Prefer the dashboard's Features
+page, or remove the duplicate.
+
+**2. The real blocker: pinchtab's IDPI domain allowlist.** The extension pins
+`pinchtab@0.13.2`, which ships:
+
+```
+website whitelist    127.0.0.1, localhost, ::1
+IDPI strict mode     enforcing
+```
+
+Every public navigation is refused — `Error 403: navigation blocked by IDPI:
+Domain not in allowlist: search.brave.com` — including the Brave search the
+extension's own skill instructs the agent to perform. Infrastructure was never
+the problem: `pinchtab` CLI present, Chromium present, egress fine (`google:
+200`).
+
+Two ways out, and they are **not** equivalent:
+
+| | whitelist | IDPI strict | content guard |
+|---|---|---|---|
+| `pinchtab security down` | disabled | **disabled** | **disabled** |
+| `config set security.allowedDomains "*"` | wildcard | enforcing | **active** |
+
+The content guard is what wraps fetched pages in `<untrusted_web_content>` with
+an explicit prompt-injection warning. For an agent that browses *and* holds
+tools, keeping it is the whole point — so the allowlist route is correct and
+`security down` should be avoided.
+
+**3. Mercury silently reverts edits to installed extensions.** Patching
+`.mercury/extensions/web-browser/index.ts` looked like it worked, but the next
+start logged `Bundled extension source updated — reinstalling name=web-browser`
+and restored the original. The patch must go in the **bundled source** inside the
+npm package:
+
+```
+~/.nvm/versions/node/<ver>/lib/node_modules/mercury-agent/examples/extensions/pinchtab/index.ts
+```
+
+### The fix that actually works: bake it at image build time
+
+Setting the allowlist inside `pinchtab_ensure` is **not sufficient**. The agent
+usually runs `pinchtab nav` directly, and nav *auto-starts the server*
+(`server not running, starting automatically`) without ever calling the ensure
+function — so the config never ran. Verified: the bot still reported
+`403 ... Domain not in allowlist` after that patch.
+
+The durable fix appends to the extension's CLI `install` string, so the config
+file exists in the image before anything runs. The container runs as uid 1000
+(`mercury`), so `HOME` must be set explicitly during the root-run build:
+
+```
+&& HOME=/home/mercury pinchtab config set security.allowedDomains "*"
+&& chown -R mercury:mercury /home/mercury/.pinchtab
+```
+
+Changing `install` changes the image hash → one rebuild (~3.4 min) →
+`mercury-agent-ext:23ab9b6a1159`. Confirmed baked in, with guards intact:
+
+```
+allowedDomains: ['*']
+idpi: {enabled: True, strictMode: True, scanContent: True, wrapContent: True}
+allowEvaluate: False, allowDownload: False, allowClipboard: False
+```
+
+### Trap: the bash lives inside a TS template literal
+
+The first patch attempt put backticks in an explanatory comment
+(``  # ...use `pinchtab security down`...``). Those backticks **closed the
+enclosing template literal**, and the extension stopped loading entirely:
+
+```
+Failed to load extension "web-browser": BuildMessage: Expected ";" but found "pinchtab"
+```
+
+The symptom surfaced in the dashboard as *web-browser: uninstalled* — the
+Features page lists `registry.list()`, so a load failure reads as "not
+installed". **Never put a backtick in that bash block.** Check any edit with
+`mercury extensions validate web-browser` before restarting.
+
+> ⚠️ **`npm update -g mercury-agent` erases both patches**, and browsing stops
+> working again. Re-apply after every upgrade until fixed upstream.
+
+### Verifying honestly — plausible answers are not evidence
+
+Two false positives happened here, both worth remembering:
+
+1. *"What's the weather in Tel Aviv?"* → a confident **30 °C**, produced while
+   navigation was fully blocked. Pure training data.
+2. A live GitHub API check (`stargazers_count`, `pushed_at`) matched ground truth
+   **exactly** — but was run while the extension was failing to load. The agent
+   had simply used `curl`; container egress was never restricted, only pinchtab
+   navigation was.
+
+The test that actually proves the browser ran must be something `curl` **cannot**
+do. Brave Search returns `429` to plain curl from the container, so real Brave
+result titles are proof:
+
+| | |
+|---|---|
+| `curl https://search.brave.com/...` from container | **429** |
+| Bot, asked for the first two result titles | "Jerusalem, Israel 14 day weather forecast" (TimeAndDate), "Jerusalem — BBC Weather" |
+
+---
+
+## Voice transcription
+
+Configured to reuse the existing Gemini key, so no new provider or cost:
+
+```yaml
+extensions:
+  voice-transcribe:
+    provider: gemini          # local | api | openai | gemini
+    model: gemini-3.1-flash-lite
+    language: he              # empty = auto-detect
+```
+
+`.env` gains `MERCURY_STT_GEMINI_API_KEY` (same value as the chat key). The
+extension declares this var `hostOnly: true`, so it is consumed on the host in
+`before_container` and **never enters the agent container**.
+
+> **The model must be set explicitly.** The extension's built-in Gemini default
+> is `DEFAULT_GEMINI_MODEL = "gemini-2.5-flash"` — the model that now 404s for
+> new keys. Left alone, transcription fails silently.
+
+Audio-input support verified by posting a real WAV to `:generateContent`:
+
+| Model | Result |
+|---|---|
+| `gemini-3.1-flash-lite` | ✅ accepted (**chosen** — best measured availability) |
+| `gemini-3.5-flash` | ✅ accepted (better accuracy if it's reachable) |
+| `gemini-3.6-flash` | ✅ accepted |
+| `gemini-2.5-flash` | ❌ 404 retired |
+
+Other providers: `openai` (`MERCURY_STT_API_KEY`, also serves Groq via
+`base_url`), `api` (Hugging Face, `MERCURY_HF_TOKEN`), `local` (Python +
+transformers on the host, `MERCURY_VOICE_PYTHON`).
+
+---
+
+## Configuration reference
+
+### Triggers — how the bot decides to answer
+
+`trigger.match` takes three values (`src/core/trigger.ts:9`):
+
+| Mode | Behaviour |
+|---|---|
+| `prefix` | Pattern must start the message |
+| `mention` | Pattern anywhere, word-boundary aware — `@Mercury, hi` works, `Pi` inside `Pixel` does not (**default**) |
+| `always` | No trigger needed at all |
+
+**DMs ignore this entirely** — `trigger.ts:65` always matches in a DM and strips
+the pattern if present. `match` only constrains **group** chats.
+
+`server.bot_username` does double duty: `router.ts:90` auto-appends
+`@<bot_username>` to the trigger patterns, so renaming the bot changes what it
+answers to in groups.
+
+### Applied identity
+
+**Revised 2026-08-06** — bare `ויצ` was too short and false-triggered, so the
+mention name moved to `ויציבוט`:
+
+```yaml
+server:
+  bot_username: ויציבוט      # was ויצ
+trigger:
+  patterns: "ויצ דה בוט,@Mercury,Mercury"   # bare ויצ removed
+  match: mention
+```
+
+`bot_username` is kept to **one word** on purpose: `router.ts:95` auto-appends
+`@<bot_username>`, and `@ויצ דה בוט` would be awkward to type in a group. The
+full name is listed as a pattern instead, and patterns are sorted longest-first
+at match time so the full name is stripped before the short one.
+
+`bot_username` is *not* cosmetic. It is what the WhatsApp adapter rewrites a real
+@-mention of the bot's number into (`adapters/setup.ts:69` → `whatsapp.ts:592`)
+before trigger matching runs. Change it and the tap-to-mention path changes with
+it.
+
+The Hebrew word for "bot" was deliberately **left out** of the *global* list — it
+is a common word and would false-trigger in groups. `Mercury` is kept as a
+fallback.
+
+> **Trap — a per-space `trigger.patterns` override replaces the auto-appended
+> `@<bot_username>`, it does not merge with it.** `trigger.ts:29-34` uses the
+> space's list *instead of* the defaults, and the `@bot` form is only ever pushed
+> onto the defaults (`router.ts:95-98`). Worse, `mention` matching anchors on
+> start-of-string or whitespace (`trigger.ts:110`), so a bare `ויציבוט` pattern
+> does **not** match the text `@ויציבוט` — the `@` blocks the lookbehind.
+>
+> Net effect: a space with custom patterns silently stops responding to
+> tap-to-mention unless the `@` form is listed explicitly. Every per-space
+> pattern list must include both forms:
+>
+> ```
+> @ויציבוט,ויציבוט,ויצ דה בוט,ווצבוט,ווצ דה בוט
+> ```
+
+Persona lives in `.mercury/spaces/main/AGENTS.md` (was empty until now). It sets
+Hebrew-first replies, short mobile-friendly answers, and — prompted by the two
+false positives above — an explicit rule never to claim a capability it has not
+just used, plus a reminder that `<untrusted_web_content>` is data, not
+instructions.
+
+### Per-space overrides
+
+These live in the DB (dashboard, or space config), not `mercury.yaml`, and beat
+the global values for that space: `trigger.match`, `trigger.patterns`,
+`trigger.case_sensitive`, `trigger.media_in_groups`.
+
+### Main `mercury.yaml` sections
+
+`server` (port, bot_username) · `model` · `ingress` · `runtime` (log level, rate
+limits, concurrency) · `trigger` · `context` (mode, window_size,
+reply_chain_depth) · `compaction` · `agent` (image, timeout, bwrap compat,
+env_passthrough) · `media` · `permissions.admins` · `dm_auto_space` ·
+`scheduling.default_timezone` · `extensions`
+
+Personality/instructions are **not** YAML — they go in
+`.mercury/spaces/<space>/AGENTS.md`.
+
+### Groups: adding the number is not enough
+
+A new group creates an **unlinked** conversation, and unlinked messages are
+dropped at `handler.ts:191` before any model call. Every new group needs:
+
+```bash
+mercury conversations --unlinked
+mercury link <id> <space>
+```
+
+Then, in groups only, a message must match the trigger. Link a group to `main`
+to share memory with the DM, or to its own space to keep memory separate.
+
+`dm_auto_space.enabled: true` automates this for **DMs** only — never groups.
+
+---
+
+## Free-tier rate limits — the real constraint
+
+The bot replied *"I've reached my usage limit for now"* after a handful of
+messages. The underlying error:
+
+```
+429 Quota exceeded for metric: generate_content_free_tier_requests,
+    limit: 5, model: gemini-3.6-flash
+    Please retry in 10.817604931s
+```
+
+**That is 5 requests per _minute_, not a daily cap** — it resets in seconds. The
+newest models carry the smallest free allowances and the most congestion
+(`gemini-3.6-flash` also returned `503 UNAVAILABLE: high demand` on a direct
+probe minutes later). Newest ≠ best on a free key.
+
+Revised to a two-leg chain, which is exactly what `model.chain` exists for —
+a throttled leg falls through instead of failing the turn:
+
+```yaml
+model:
+  provider: google
+  model: gemini-3.5-flash
+  chain:
+    - provider: google
+      model: gemini-3.5-flash
+    - provider: google
+      model: gemini-3.1-flash-lite
+  max_retries_per_leg: 3
+```
+
+`-lite` variants generally carry the most generous free quotas, which makes leg 2
+a genuine safety net rather than a second way to hit the same wall.
+
+### Measured, not assumed: pick legs by availability
+
+Version number is a terrible proxy for usability on a free key. Measured with a
+12-request burst plus a two-function tool-calling probe:
+
+| Model | 12 rapid requests | Parallel tool calls |
+|---|---|---|
+| `gemini-3.1-flash-lite` | **12 × 200, 0 × 429** | ✅ both, correct args |
+| `gemini-3.5-flash` | **0 × 200** (503/429) | ✅ both, correct args |
+| `gemini-3.6-flash` | 5 rpm cap, also 503 | — |
+| `gemini-2.5-flash-lite` | 404 — retired | — |
+
+The `-lite` model is far and away the most *available*, and it drives tools
+correctly — which is the only capability Mercury's skills actually need. Final
+order is availability-first:
+
+```yaml
+model:
+  provider: google
+  model: gemini-3.1-flash-lite
+  chain:
+    - provider: google
+      model: gemini-3.1-flash-lite   # measured 12/12
+    - provider: google
+      model: gemini-3.5-flash        # better reasoning when it's reachable
+  max_retries_per_leg: 3
+```
+
+Reproduce any time with a burst of `:generateContent` calls — the numbers move as
+Google shifts free-tier allocations, and today's best leg may not be next
+month's.
+
+### Do skills need anything beyond tool calling?
+
+No. `model-capabilities.ts:201` treats an unrecognised model as **permissive** —
+`DEFAULT_CAPABILITIES` is `tools: true`, and an unknown model is never denied a
+capability-gated skill on a guess. So any model that emits correct function calls
+runs Mercury's skills (recall, tasks, spaces, permissions, …).
+
+### Other free providers Mercury supports
+
+| Option | Free? | Notes |
+|---|---|---|
+| **Google Gemini** | Yes | In use. Best free tool-caller measured so far. |
+| **Groq** (`MERCURY_GROQ_API_KEY`) | Yes | Mercury-supported provider; hosts open models. Needs a key from console.groq.com to benchmark. |
+| **GitHub Copilot** (`mercury auth login github-copilot`) | Partly | One of only **two** OAuth providers Mercury can actually serve (`pi-auth.ts:24`). Reaches GPT/Claude-class models — the strongest tool users. Free for verified students/teachers/OSS maintainers; otherwise a limited free tier then paid. |
+| **OpenAI** | No | Key added but the account has **no credits** — every model 429s. Inert until topped up. |
+
+If throttling still bites: add more legs, raise `max_retries_per_leg`, or put a
+paid leg last so only overflow costs money.
+
+---
+
+## Switched to Claude Opus 5 (2026-08-06)
+
+OAuth against the Claude subscription now works (`mercury auth login anthropic`),
+so decision C flips back to OAuth and D to `claude-opus-5`.
+
+### The bot was "not working well" for a config reason, not a model reason
+
+`mercury auth status` reported **`Anthropic: not logged in`** — but only when run
+from outside the project. `auth.json` lives at `.mercury/global/auth.json`,
+resolved relative to the **data dir**, so the command is cwd-sensitive. From
+`~/whatsapp-bot` it correctly reports `✓ logged in`. Always `cd` first before
+believing it.
+
+The real fault was in `.env`, which had grown three lines that silently beat
+`mercury.yaml` (env wins — `config.ts:357`, and the file's own header says so):
+
+| Line | Effect |
+|---|---|
+| `MERCURY_MODEL_PROVIDER=google` | pinned the provider regardless of YAML |
+| `MERCURY_MODEL_CHAIN=[{"provider":"google","model":"gemma-4-31b-it"}]` | **replaced the tuned two-leg chain with a single Gemma leg — no fallback** |
+| `MERCURY_GEMINI_API_KEY=KEY` (2nd copy) | a 3-char placeholder duplicate |
+
+The Gemma line is what would have degraded answers — an open-weights model with
+no fallback leg, in place of the availability-ordered Gemini chain. It had not
+actually bitten yet: `.env` was edited at 13:05, after the last probe run at
+12:49, and the service had not been restarted since, so the running process was
+still on `gemini-3.1-flash-lite`. `token_usage` confirms this.
+
+The duplicate key was **inert** — bun's dotenv keeps the *first* occurrence, so
+the real 53-char key still won (verified by reading back
+`process.env.MERCURY_GEMINI_API_KEY.length`). Deleted anyway.
+
+All three are now commented out / removed, making `mercury.yaml` the single
+source of truth for the model.
+
+### Config applied
+
+```yaml
+model:
+  provider: anthropic          # container-runner.ts:892 reads this scalar
+  model: claude-opus-5
+  chain:
+    - provider: anthropic
+      model: claude-opus-5     # single leg on purpose — see caveat below
+  max_retries_per_leg: 3
+
+agent:
+  image: mercury-agent:latest
+  container_bwrap_docker_compat: true
+  container_timeout_ms: 1200000   # 20 min; schema max is 3_600_000
+  override_pi_system_prompt: true
+  env_passthrough: all            # kept — was not in the requested block
+```
+
+No Anthropic key is needed in `.env`: with `provider: anthropic` and no
+`ANTHROPIC_*` var, `container-runner.ts:892-903` falls back to
+`.mercury/global/auth.json` and injects `ANTHROPIC_OAUTH_TOKEN` into the
+container.
+
+**Single leg is deliberate.** A google fallback leg would answer whenever Opus
+failed, making a dead leg look like a pass. Add one back for resilience once the
+Opus leg has proven itself in daily use — but then always confirm *which* model
+answered:
+
+```sql
+SELECT id, space_id, model, provider FROM token_usage ORDER BY id DESC LIMIT 1;
+```
+
+### `claude-opus-5` is not in pi's capability registry
+
+Startup warned it was falling back to `DEFAULT_CAPABILITIES`
+(`tools=true, vision=false`). Nothing was silently disabled — capability *gating*
+treats an unknown model as permissive (`model-capabilities.ts:201`:
+`source === "default"` satisfies any requirement) — but with `media.enabled: true`
+the guess is wrong. Declared explicitly in `.mercury/model-capabilities.yaml`;
+the warning is gone.
+
+### Opus 5 vs the google legs
+
+Probes re-run from the previous session, plus a new one. Every row is attributed
+via `token_usage`, not assumed.
+
+| Probe | `gemini-3.1-flash-lite` | `claude-opus-5` |
+|---|---|---|
+| Smoke (`PROBE_OK`) | ✅ | ✅ |
+| Haifa weather + real titles | ✅ number; **claimed titles while saying it could not open the browser** (2 of 4 answers) | ✅ number + titles, and flagged the earlier fabrication unprompted |
+| Copper /tonne + real titles | ✅ ~14,000–14,200 | ✅ 14,100–14,200, cross-checked Kitco / LME / COMEX |
+| Silver /oz, **fresh space** | ✅ $62.15–62.98, both titles real | ✅ $61.80, both titles real, *and* stated the top-2 results carried no live number so it opened Trading Economics directly |
+| Latency | ~35 s | ~45–71 s |
+
+Independently verified with an outside search: copper really was ~$14,195/t and
+silver ~$62.8/oz on 2026-08-05. **Both models had the numbers right.** An earlier
+reading of the ~$14k copper figure as a hallucination was simply wrong — copper
+had rallied ~53% year-on-year.
+
+So the difference is not accuracy, it is **honesty about tool use**. Gemini's
+failure mode in the `main` space was asserting search-result titles in the same
+breath as admitting the browser never opened. Opus reported provenance
+accurately, including the inconvenient parts.
+
+Two caveats, stated so the table is not over-read:
+
+1. **The `main`-space probes are contaminated.** All models share one history, so
+   Opus could read Gemini's earlier titles before answering. That is why the
+   silver probe was run in fresh spaces (`cmp-opus`, `cmp-gemini`) with a
+   question never asked before — and there Gemini browsed cleanly and returned
+   the same real titles. Its earlier fabrication is a *sometimes*, not an always.
+2. **Cost figures for the Opus rows are junk.** `token_usage` recorded
+   `input_tokens` of 2, 10, 16 for full agentic turns, so the derived `cost`
+   column is meaningless on the OAuth path. Billing is subscription plan limits,
+   not per-token, so ignore that column for anthropic legs.
+
+### Reproducing
+
+```bash
+cd ~/whatsapp-bot                     # cwd matters for auth status
+mercury spaces create cmp-<model>     # fresh space = no shared history
+mercury chat --space cmp-<model> "…tell me the exact titles of the first two \
+  search results you actually saw. If you could not open the browser, say so \
+  explicitly and do not guess titles."
+```
+
+The "if you could not open the browser, say so" clause is what makes the probe
+diagnostic — without it a fabricated title is indistinguishable from a real one.
+
+---
+
+## Keeping it running
+
+### Trap: without lingering, closing your last terminal kills the bot
+
+`mercury service install` creates a systemd **user** unit. By default a user's
+systemd manager is torn down when their last login session ends — so closing the
+Ubuntu terminal stopped Mercury with a clean `status=0/SUCCESS` graceful
+shutdown. Not a crash, and `Restart=on-failure` deliberately does **not** cover
+it, because exit 0 is not a failure.
+
+Diagnosed with `loginctl show-user $USER --property=Linger` → `Linger=no`. Fixed:
+
+```bash
+loginctl enable-linger "$USER"     # no sudo needed
+```
+
+Now the user manager persists with no session open, and the bot survives closing
+every terminal.
+
+### Still open: WSL itself does not auto-start
+
+Lingering covers terminal closes, but not `wsl --shutdown` or a Windows reboot —
+WSL2 does not start a distro at boot. Until that's addressed, the bot is down
+after every restart until something touches the distro.
+
+Fix when wanted: a Windows Task Scheduler task at logon running
+
+```
+wsl.exe -d Ubuntu -u guysaha -e /bin/true
+```
+
+Booting the distro starts the user manager, which (with lingering on, and the
+unit already `enabled`) starts Mercury automatically.
+
+---
+
+## Ongoing operations
+
+- **Re-auth WhatsApp — on failure, not on a schedule.** There is no fixed expiry
+  (corrected 2026-08-06). The link drops only if the bot's phone goes **14 days
+  without connecting to WhatsApp**, or on an unrelated Baileys/server-side
+  logout. Keep the phone online and no routine action is needed; no calendar
+  reminder required. When it *does* drop: `mercury service uninstall` →
+  `rm -rf .mercury/whatsapp-auth/` → `mercury auth whatsapp` →
+  `mercury service install`.
+- **Upgrades:** stop the service → `npm update -g mercury-agent` →
+  `mercury build` → start. The derived image rebuilds itself.
+- **Backups:** `.mercury/` holds the SQLite DB, space workspaces, and WhatsApp
+  credentials. Back it up; never commit it.
+- **Secrets:** `.env` and `.mercury/whatsapp-auth/` are credentials. If you make
+  the runtime project a git repo, confirm both are gitignored before the first
+  commit.
+
+---
+
+## Risk register
+
+| Risk | Impact | Mitigation |
+|---|---|---|
+| WSL2 + Docker install fails or is blocked by policy | Total blocker | Try Docker Desktop first; it handles the WSL plumbing |
+| Personal WhatsApp number linked to the bot | Bot has access to all your chats; ban risk | Dedicated number |
+| WhatsApp bans/limits automated accounts | Loss of the number | Baileys is an unofficial client — this is inherent. Low volume, personal use only |
+| Session expiry surprises you | Bot silently stops | Calendar reminder + `mercury service logs -f` |
+| `claude-sonnet-5` unrecognised by pi, or not granted by the Claude subscription | Startup/runtime error | Fall back to `claude-opus-4-8`; verify with `mercury chat "hello"` before WhatsApp |
+| GHCR agent image is private (`unauthorized`) | Can't pull the preset | Build locally — but `.dockerignore` excludes `examples/` while `Dockerfile:118` copies it, so the build needs a one-line re-include |
+| npm 11 skips postinstall scripts | Baileys/protobufjs half-installed, WhatsApp breaks subtly | Always install with `--allow-scripts=@whiskeysockets/baileys,@google/genai,protobufjs` |
+| bubblewrap can't nest under Docker Engine | Agent container won't start | **Confirmed on this host and already fixed** — `agent.container_bwrap_docker_compat: true` |
+| Docker image churn | Disk usage | Base image ~2.8 GB + derived images; set `MERCURY_AGENT_ID` |
+| Running from `/mnt/d` | Slow, permission bugs | Decision A — use WSL ext4 |
+
+---
+
+## Reference
+
+Docs in the clone at `mercury/docs/`:
+`setup-whatsapp.md`, `configuration.md`, `pipeline.md`, `memory.md`,
+`scheduler.md`, `permissions.md`, `media/overview.md`, `dashboard.md`,
+`extensions.md`, `container-lifecycle.md`, `rate-limiting.md`.