discoclaw 0.9.0 → 1.0.0

package/.context/automations.md

@@ -85,3 +85,154 @@ creating forum threads.
 | Gated actions | `allowedActions` for least-privilege |
 
 See [docs/cron-patterns.md](../docs/cron-patterns.md) for full examples of each.
+
+## Data Directory
+
+Cron data lives in `data/cron/`:
+
+| File/Dir | Contents |
+|----------|----------|
+| `cron-run-stats.json` | Per-job run statistics: run count, last run time/status, schedule, model, channel, projection state. Rewritten on every run completion. |
+| `tag-map.json` | Maps tag names (e.g. `report`, `monitor`) to Discord forum tag snowflake IDs. Used for auto-tagging cron threads. |
+| `locks/` | Per-job lock directories. Each active job gets `<sanitized-id>.<hash>.lock/meta.json`. Prevents overlap (concurrent execution of the same job). |
+
+### Lock directory format
+Each lock dir contains a `meta.json`:
+```json
+{"pid":12345,"token":"a1b2c3...","acquiredAt":"2026-03-24T15:00:00.009Z","startTime":45779798}
+```
+- `pid` — PID of the process holding the lock
+- `token` — random token for safe release (prevents cross-process release)
+- `startTime` — Linux `/proc/<pid>/stat` field 22 (jiffies); detects PID reuse
+
+### Exact commands for data inspection
+```bash
+# View all job stats
+jq . data/cron/cron-run-stats.json
+
+# List jobs and their last run status
+jq '.jobs | to_entries[] | {id: .key, status: .value.lastRunStatus, lastRun: .value.lastRunAt}' data/cron/cron-run-stats.json
+
+# Check for stuck locks
+ls -la data/cron/locks/
+
+# Inspect a specific lock
+cat data/cron/locks/*.lock/meta.json 2>/dev/null
+
+# Check if a locked PID is still alive
+for meta in data/cron/locks/*.lock/meta.json; do
+  pid=$(jq -r .pid "$meta" 2>/dev/null)
+  kill -0 "$pid" 2>/dev/null && echo "$meta: PID $pid alive" || echo "$meta: PID $pid STALE"
+done
+
+# View the tag map
+jq . data/cron/tag-map.json
+
+# Check run stats file size (large = many jobs or accumulating history)
+ls -lh data/cron/cron-run-stats.json
+```
+
+## Known Footguns
+
+- **`<cron-state>` replaces, does not merge:** If a job's state is `{"cursor": "abc", "count": 5}` and the AI outputs `<cron-state>{"cursor": "def"}</cron-state>`, the `count` key is lost. The AI must echo back all keys it wants to keep.
+- **Manual thread creation is ignored:** Jobs must be created via the `cronCreate` action. Manually creating a forum thread will not register a job — the thread will sit inert. Use `cronCreate` or ask the bot to create it.
+- **Archiving ≠ deleting:** The `cronDelete` action archives the thread (reversible). The job stops, but history is preserved. Actual thread deletion is permanent and removes all messages.
+- **Chain depth silently caps at 10:** If a chain exceeds 10 hops, execution stops with no visible error in the target channel. Check the bot logs for `chain depth limit reached`.
+- **Webhook jobs require `DISCOCLAW_WEBHOOK_ENABLED=true`:** Defining a webhook-triggered job without enabling the webhook server means the job exists but can never fire. No warning is logged at startup.
+- **Timezone defaults to system timezone:** If `DEFAULT_TIMEZONE` is unset and the server's system timezone is UTC, all cron schedules without explicit timezones run in UTC. This catches people who expect local time.
+- **Cron config changes in `.env` require restart:** Changing `DISCOCLAW_CRON_ENABLED`, `DISCOCLAW_CRON_FORUM`, or `DEFAULT_TIMEZONE` in `.env` has no effect until the service is restarted (`systemctl --user restart discoclaw.service`). The cron subsystem reads config once at startup.
+- **`dist/` must be rebuilt for cron code changes:** Cron executor, parser, and scheduler code lives in `src/cron/`. After modifying these files, `pnpm build` must be run and the service restarted — the systemd service runs `dist/index.js`, not `src/`.
+
+## Common Failure Modes
+
+### Cron job not firing on schedule
+**Symptom:** Job was created and confirmed, schedule looks correct, but no output appears at the expected time.
+**Cause (in order of likelihood):**
+1. Thread is archived (job is paused).
+2. Timezone mismatch — job runs in UTC but user expects local time.
+3. Previous run is still active (overlap guard skipped this tick).
+4. `DISCOCLAW_CRON_ENABLED` is `0` or `DISCOCLAW_CRON_FORUM` is unset.
+5. Service is in `failed` state after crash loop — cron timers are not running.
+**Recovery:**
+```bash
+# First: is the service even running?
+systemctl --user status discoclaw.service
+# If "failed (Result: start-limit-hit)":
+systemctl --user reset-failed discoclaw.service
+systemctl --user start discoclaw.service
+
+# Check if the thread is archived (in Discord, archived threads are hidden by default)
+# Use the cronList action to see all jobs and their states
+
+# Check bot logs for skip reasons
+journalctl --user -u discoclaw.service --since "1 hour ago" --no-pager | grep -i "cron\|skip\|overlap"
+
+# Verify cron config
+grep -E 'DISCOCLAW_CRON_ENABLED|DISCOCLAW_CRON_FORUM|DEFAULT_TIMEZONE' .env
+
+# Verify timezone
+timedatectl | grep "Time zone"
+```
+
+### Cron job fires but output goes to wrong channel
+**Symptom:** Job runs successfully but posts to the wrong Discord channel or to no channel.
+**Cause:** The AI parsed the target channel incorrectly from the natural-language definition, or the channel ID in the parsed config is stale (channel was deleted/renamed).
+**Recovery:**
+```bash
+# Use cronShow to inspect the parsed config
+# Ask the bot: "show cron <job-name>"
+# Check the targetChannel field
+
+# Update by editing the starter message in the forum thread, then:
+# Ask the bot: "trigger cron <job-name>" to test the new config
+```
+
+### State corruption — job keeps repeating or skipping work
+**Symptom:** A stateful polling job re-processes old items, or skips new ones.
+**Cause:** The AI's `<cron-state>` output replaced state instead of merging, or the state hit the 4000-char injection cap and was truncated.
+**Recovery:**
+```bash
+# Check current state via cronShow
+# Reset state by asking the bot:
+# "update cron <job-name> with state {}"
+
+# Or reset to a specific cursor:
+# "update cron <job-name> with state {\"cursor\": \"known-good-value\"}"
+```
+
+### Cron job stuck — overlap guard never releases
+**Symptom:** A job ran once and now never fires again. Logs show `Lock held by PID XXXXX` on every tick.
+**Cause:** The previous execution crashed without releasing its lock in `data/cron/locks/`. The lock dir persists with a `meta.json` pointing to a dead (or reused) PID. Stale-lock detection usually catches this, but can fail if `/proc/<pid>/stat` is unreadable or the PID was reused by a long-lived process.
+**Recovery:**
+```bash
+# List all lock dirs
+ls -la data/cron/locks/
+
+# Find the stuck lock (match the cron ID from the log message)
+# Lock dirs are named <sanitized-id>.<hash>.lock
+cat data/cron/locks/*.lock/meta.json 2>/dev/null
+
+# Check if the PID is alive
+kill -0 <pid> 2>/dev/null && echo "alive" || echo "stale"
+
+# If stale: remove the lock dir, the next tick will acquire fresh
+rm -rf data/cron/locks/<lock-dir-name>.lock
+
+# If the PID is alive but belongs to a different process (PID reuse):
+# compare the startTime in meta.json with /proc/<pid>/stat field 22
+cat /proc/<pid>/stat | awk '{print $22}'
+# If they differ, the lock is stale — safe to remove
+```
+
+### Chain cascade — downstream jobs keep firing
+**Symptom:** A chained pipeline fires repeatedly or produces unexpected output.
+**Cause:** Cycle in the chain graph (should be caught at write time, but can occur if jobs were edited after initial creation without re-validation).
+**Recovery:**
+```bash
+# Check logs for chain-related entries
+journalctl --user -u discoclaw.service --since "30 min ago" --no-pager | grep -i "chain"
+
+# Break the cycle by removing the chain field from the looping job:
+# "update cron <job-name> with chain: none"
+# Then re-architect the chain graph
+```

package/.context/bot-setup.md

@@ -5,7 +5,7 @@
 ## Quick reference
 
 1. **Developer Portal** → create application → Bot → enable **Message Content Intent** → copy token to `.env` (`DISCORD_TOKEN`).
-2. **OAuth2 → URL Generator** → scope `bot` → pick permissions (see permission profiles in `docs/discord-bot-setup.md`) → invite to server.
+2. **Invite** — quickest: `https://discord.com/oauth2/authorize?client_id=CLIENT_ID&scope=bot&permissions=0` (replace `CLIENT_ID`). For a permanent link with pre-set permissions, use the **Installation page** → set Install Link to "Discord Provided Link" → Default Install Settings → add scope `bot` and pick permissions (see profiles in `docs/discord-bot-setup.md`). The `bot` scope is required — `applications.commands` alone won't add the bot to a server.
 3. **Configure `.env`**:
    - *Global install:* `discoclaw init` — wizard creates `.env` with `DISCORD_TOKEN`, `DISCORD_ALLOW_USER_IDS`, and `DISCORD_CHANNEL_IDS`.
    - *From source:* `pnpm setup` for guided configuration, or copy `.env.example` → `.env` and set `DISCORD_TOKEN`, `DISCORD_ALLOW_USER_IDS` (fail-closed if empty), `DISCORD_CHANNEL_IDS` (recommended).
@@ -13,12 +13,275 @@
    - *Global install:* `discoclaw install-daemon` to register the systemd service, then DM the bot to confirm it responds.
    - *From source:* `pnpm dev`, DM the bot, post in allowed/disallowed channels.
 
+## Exact Command Reference
+
+### From source — setup and validation
+
+```bash
+# Guided interactive setup (creates .env)
+pnpm setup
+
+# Manual .env creation (essentials only)
+cp .env.example .env
+
+# Preflight check — validates env, token format, snowflake IDs, config doctor
+pnpm preflight
+
+# Preflight for a fresh clone (ignores shell env, reads only checkout .env)
+pnpm preflight:blank-machine
+
+# Discord smoke test — verifies bot token and gateway connection
+pnpm discord:smoke-test
+
+# Discord smoke test with guild membership check
+pnpm discord:smoke-test -- --guild-id 123456789012345678
+
+# Claude runtime auth check
+pnpm claude:auth-smoke
+
+# Start the bot in dev mode
+pnpm dev
+```
+
+### Global install — setup and validation
+
+```bash
+# Interactive wizard — creates .env and workspace
+discoclaw init
+
+# Register as a user-level systemd service
+discoclaw install-daemon
+
+# Multi-instance: unique service name per instance
+discoclaw install-daemon --service-name discoclaw-work
+
+# Config/health check
+discoclaw doctor
+
+# Claude auth smoke test (npm-managed path)
+discoclaw claude auth-smoke
+```
+
+### Discord smoke test arguments
+
+```bash
+# Print guild IDs the bot is in (useful for debugging guild-id mismatches)
+pnpm discord:smoke-test -- --print-guilds
+
+# Override timeout (default 12s)
+DISCORD_SMOKE_TEST_TIMEOUT_MS=30000 pnpm discord:smoke-test
+```
+
 ## Getting IDs
 
 Discord client: Settings → Advanced → Developer Mode, then right-click a user/channel → Copy ID.
 
-## Common issues
+IDs are "snowflakes" — 17–20 digit numbers. The preflight check validates format:
+```bash
+# Preflight reports invalid snowflakes explicitly
+pnpm preflight
+# Example output: "DISCORD_ALLOW_USER_IDS contains invalid IDs: abc123"
+```
+
+## Known Footguns
+
+- **Message Content Intent is invisible when missing.** If you skip enabling it in Developer Portal → Bot → Privileged Gateway Intents, the bot connects, appears online, and `msg.content` is silently empty in guild channels. No error is logged — the bot just ignores every guild message. DMs still work (they don't require the intent). This is the #1 setup failure mode.
+- **`applications.commands` scope is not `bot` scope.** Using `scope=applications.commands` in the invite URL registers slash commands but does not add the bot to the server. The bot cannot connect, read messages, or respond. You must include `scope=bot` (or both).
+- **Copying Application ID instead of Bot Token.** The Developer Portal shows the Application ID prominently on General Information. The Bot Token is on the Bot page. They look similar (long alphanumeric strings) but are not interchangeable. If you copy the Application ID into `DISCORD_TOKEN`, the bot fails at login with "An invalid token was provided."
+- **Token revealed once, then hidden.** After creating the bot, the token is shown once. If you navigate away without copying it, you must click "Reset Token" to generate a new one — the old one is gone. Resetting invalidates the previous token immediately.
+- **Empty `DISCORD_ALLOW_USER_IDS` = silent rejection.** The bot starts, connects, appears online, but responds to nobody. No error is logged. This is fail-closed by design, but it's surprising on first setup.
+- **`DISCORD_CHANNEL_IDS` restricts guild channels only.** DMs always work regardless of this setting. If you set channel IDs and then test in a channel not in the list, the bot silently ignores you. Test in a listed channel or via DM.
+- **`DISCORD_REQUIRE_CHANNEL_CONTEXT=1` (default) blocks unlisted channels.** Even if the channel is in `DISCORD_CHANNEL_IDS`, the bot won't respond in a guild channel without a matching context file under `content/discord/channels/`. Enable `DISCORD_AUTO_INDEX_CHANNEL_CONTEXT=1` (default) to auto-create stubs, or run `pnpm sync:discord-context` to scaffold them.
+- **Role hierarchy blocks moderation actions.** The bot can only manage roles below its own role in Server Settings → Roles. If the bot role is at the bottom, actions like role assignment, timeout, and kick will fail with "Missing Permissions" even if the permission bits are granted.
+- **Private threads require explicit addition.** The bot must be added to private threads manually regardless of its channel permissions. Public threads are auto-joined when `DISCORD_AUTO_JOIN_THREADS=1`.
+- **Editing `.env.example` instead of `.env`.** `.env.example` is tracked in git and has no runtime effect. Your actual config is in `.env` (gitignored). A common mistake — changes to `.env.example` appear to do nothing.
+- **`discoclaw install-daemon` PATH divergence.** The systemd service uses `/usr/bin/node` and a fixed `PATH`. The daemon may not find the same CLI binaries (e.g., `claude`, `codex`) that your interactive shell finds. Verify service logs after daemon install.
+- **Service stuck after repeated setup failures.** If the service crashes 3 times within 10 minutes during initial setup (bad token, missing env, etc.), systemd marks it as `failed` and refuses further starts. Run `systemctl --user reset-failed discoclaw.service` to clear the failure counter before retrying.
+- **Stale `dist/` after setup changes.** If you checked out a different branch or changed source files during setup, `dist/` may contain old compiled code. Run `rm -rf dist && pnpm build` before `pnpm dev` or service start to ensure fresh output.
+
+## Common Failure Modes
+
+### Bot token rejected at login
+**Symptom:** `pnpm dev` or the systemd service exits immediately. Logs show `Login failed: Error [TOKEN_INVALID]: An invalid token was provided.`
+**Cause:** Wrong value in `DISCORD_TOKEN` — usually the Application ID was copied instead of the Bot Token, or the token was reset in the Developer Portal.
+**Recovery:**
+```bash
+# Verify token is set and looks right (3 dot-separated base64url segments)
+pnpm preflight
+
+# If format is wrong: go to Developer Portal → Bot → Reset Token → copy new token
+# Update .env:
+#   DISCORD_TOKEN=<new-token>
+
+# Verify again
+pnpm preflight
+
+# Restart
+pnpm dev
+```
+
+### Bot online but ignores all guild messages (Message Content Intent)
+**Symptom:** Bot appears online in Discord. DMs work. Guild channel messages are completely ignored — no response, no error in logs.
+**Cause:** Message Content Intent not enabled in the Developer Portal. Without it, `msg.content` is empty for guild messages, so the bot sees every message as blank and drops it.
+**Recovery:**
+1. Go to Discord Developer Portal → your application → **Bot** → **Privileged Gateway Intents**
+2. Enable **Message Content Intent**
+3. Save Changes
+4. Restart the bot:
+```bash
+# From source
+pnpm dev
+
+# Or systemd
+systemctl --user restart discoclaw.service
+```
+No code or `.env` change is needed — this is purely a Developer Portal toggle.
+
+### Bot online but ignores all messages (empty allowlist)
+**Symptom:** Bot appears online. No response to DMs or guild messages. Logs show no errors.
+**Cause:** `DISCORD_ALLOW_USER_IDS` is empty, missing, or set to a wrong user ID.
+**Recovery:**
+```bash
+# Check what's configured
+grep DISCORD_ALLOW_USER_IDS .env
+
+# If empty or wrong: get your Discord user ID
+# (Discord → Settings → Advanced → Developer Mode → right-click yourself → Copy ID)
+# Update .env:
+#   DISCORD_ALLOW_USER_IDS=123456789012345678
+
+# Preflight validates the snowflake format
+pnpm preflight
+
+# Restart
+pnpm dev
+```
+
+### Discord smoke test fails: "Used disallowed intents"
+**Symptom:** `pnpm discord:smoke-test` exits with `Login failed: Error: Used disallowed intents`. Also appears in `journalctl` logs for the systemd service.
+**Cause:** The bot requests `GatewayIntentBits.MessageContent` (a privileged intent) but the Developer Portal has it disabled.
+**Recovery:** Same as "Bot online but ignores all guild messages" above — enable Message Content Intent in the Developer Portal. Then:
+```bash
+pnpm discord:smoke-test
+# Expected: "Discord bot ready (guilds: N)"
+```
+
+### Discord smoke test fails: "guild_not_in_cache"
+**Symptom:** `pnpm discord:smoke-test -- --guild-id <ID>` prints `Discord bot ready, but it does not appear to be in guild <ID>`.
+**Cause:** The bot is not in that guild, or the guild ID is wrong.
+**Recovery:**
+```bash
+# List guilds the bot is actually in
+pnpm discord:smoke-test -- --print-guilds
+
+# If the guild is missing: re-invite the bot to that server
+# Use the invite URL from step 2 of the quick reference above
+
+# If the guild ID is wrong: copy the correct one
+# (right-click server name → Copy Server ID)
+```
+
+### Discord smoke test hangs then times out
+**Symptom:** `pnpm discord:smoke-test` prints nothing for 12 seconds, then `Smoke test timed out after 12000ms`.
+**Cause:** Network issue, firewall blocking Discord WebSocket, or the token is valid but the bot cannot establish a gateway connection.
+**Recovery:**
+```bash
+# Increase timeout to rule out slow networks
+DISCORD_SMOKE_TEST_TIMEOUT_MS=30000 pnpm discord:smoke-test
+
+# If it still times out: check network/firewall
+# Discord WebSocket connects to gateway.discord.gg on port 443
+curl -s -o /dev/null -w "%{http_code}" https://discord.com/api/v10/gateway
+# Expected: 200
+```
+
+### Preflight fails: "DISCORD_TOKEN format invalid"
+**Symptom:** `pnpm preflight` reports `DISCORD_TOKEN format invalid: <reason>`.
+**Cause:** Token is malformed — not three dot-separated base64url segments. Common when the Application ID was pasted, or extra whitespace/quotes were included.
+**Recovery:**
+```bash
+# Check for accidental quotes or whitespace
+grep DISCORD_TOKEN .env
+# Must be: DISCORD_TOKEN=MTIz...abc (no quotes, no spaces)
+
+# If the value looks wrong: regenerate in Developer Portal → Bot → Reset Token
+# Paste the new token (no quotes around the value)
+```
+
+### Preflight fails: "DISCORD_ALLOW_USER_IDS contains invalid IDs"
+**Symptom:** `pnpm preflight` reports specific IDs that are not valid snowflakes.
+**Cause:** Non-numeric characters, a username instead of a numeric ID, or copy-paste artifacts (e.g., `<@123>` instead of `123`).
+**Recovery:**
+```bash
+# Discord snowflakes are 17-20 digit numbers
+# Get the correct ID: Discord → right-click user → Copy ID
+# IDs are comma or space separated in .env:
+#   DISCORD_ALLOW_USER_IDS=123456789012345678,987654321098765432
+```
+
+### Bot responds in DMs but not in guild channels
+**Symptom:** DMs work. Guild channel messages are ignored. Message Content Intent is confirmed enabled.
+**Cause:** `DISCORD_CHANNEL_IDS` is set but doesn't include the channel you're testing in, or `DISCORD_REQUIRE_CHANNEL_CONTEXT=1` and no context file exists for that channel.
+**Recovery:**
+```bash
+# Check channel restrictions
+grep DISCORD_CHANNEL_IDS .env
+# If set: add the channel ID, or clear it to allow all channels
+
+# Check channel context requirement
+grep DISCORD_REQUIRE_CHANNEL_CONTEXT .env
+# If 1: ensure a context file exists for the channel
+
+# Auto-scaffold missing context files
+pnpm sync:discord-context
+
+# Or disable the requirement (not recommended for production)
+#   DISCORD_REQUIRE_CHANNEL_CONTEXT=0
+```
+
+### Multi-instance: second instance uses wrong service name
+**Symptom:** `!restart` or `!update apply` targets the wrong systemd unit. Or `discoclaw install-daemon --service-name X` doesn't take effect.
+**Cause:** `DISCOCLAW_SERVICE_NAME` in `.env` doesn't match the name passed to `install-daemon`.
+**Recovery:**
+```bash
+# Check what's in .env
+grep DISCOCLAW_SERVICE_NAME .env
+
+# Re-run install-daemon (it replaces the line in-place, never duplicates)
+discoclaw install-daemon --service-name discoclaw-work
+
+# Verify
+grep DISCOCLAW_SERVICE_NAME .env
+# Expected: DISCOCLAW_SERVICE_NAME=discoclaw-work
+
+# Each instance needs its own working directory with its own .env
+```
+
+## Validation Checklist (quick)
+
+After setup, run through these in order. Each step should pass before moving on.
+
+```bash
+# 1. Preflight — validates .env, token format, snowflake IDs
+pnpm preflight               # from source
+discoclaw doctor              # global install
+
+# 2. Discord connection — verifies gateway login
+pnpm discord:smoke-test      # from source only
+
+# 3. Guild membership (optional)
+pnpm discord:smoke-test -- --guild-id <YOUR_SERVER_ID>
+
+# 4. Runtime auth (Claude path)
+pnpm claude:auth-smoke        # from source
+discoclaw claude auth-smoke   # global install
+
+# 5. Live test — start the bot and interact
+pnpm dev                      # from source
+systemctl --user start discoclaw.service  # systemd
 
-- **Bot ignores guild messages**: Message Content Intent not enabled in Developer Portal.
-- **"Missing Permissions"**: Bot role is below the target role in Server Settings → Roles. Drag it higher.
-- **Private threads**: Bot must be explicitly added to private threads regardless of permissions.
+# Then in Discord:
+# - DM the bot → should respond (if allowlisted)
+# - Post in an allowlisted channel → should respond
+# - Post in a non-allowlisted channel → should NOT respond
+```

package/.context/dev.md

@@ -194,7 +194,8 @@ Two setup paths:
 | `OPENAI_MODEL` | `gpt-4o` | Default model for the OpenAI adapter |
 | `OPENROUTER_API_KEY` | *(empty)* | OpenRouter API key; required when `PRIMARY_RUNTIME=openrouter` |
 | `OPENROUTER_BASE_URL` | *(empty — OpenRouter default)* | OpenRouter API base URL override |
-| `OPENROUTER_MODEL` | `anthropic/claude-sonnet-4` | Default model for the OpenRouter adapter |
+| `OPENROUTER_MODEL` | `anthropic/claude-sonnet-4.6` | Default model for the OpenRouter adapter |
+| `OPENROUTER_PROVIDER_PREFERENCES` | *(empty)* | Optional JSON string forwarded as OpenRouter's request `provider` object |
 | `GEMINI_BIN` | `gemini` | Path/name of the Gemini CLI binary |
 | `GEMINI_MODEL` | `gemini-2.5-pro` | Default model for the Gemini adapter |
 | `CODEX_BIN` | `codex` | Path/name of the Codex CLI binary |
@@ -288,7 +289,8 @@ This is especially useful for systemd, where env loading can differ from your sh
 - **Bot not responding:** Check allowlist (`DISCORD_ALLOW_USER_IDS`), channel restrictions (`DISCORD_CHANNEL_IDS`), and channel context requirement (`DISCORD_REQUIRE_CHANNEL_CONTEXT`).
 - **Claude CLI errors:** Look for `runtime` or `spawn` in logs. Use `CLAUDE_DEBUG_FILE` to capture full CLI output.
 - **Timeout issues:** Look for `timeout` in logs. Adjust `RUNTIME_TIMEOUT_MS` if needed.
-- **PID lock conflicts:** Look for `pidlock` in logs. See ops.md for stale lock handling.
+- **PID lock conflicts:** Look for `pidlock` or `pid lock` in logs. The lock is a directory at `data/discoclaw.pid.lock/` with `meta.json` inside. See ops.md for stale lock handling.
+- **`.env` not loaded:** If env vars appear unset, check that `.env` exists (not `.env.example`) and is in the project root. `pnpm dev` loads it via dotenv; `node dist/index.js` does not.
 
 ## Task Auto-Sync
 
@@ -340,6 +342,123 @@ SMOKE_TEST_TIERS=fast SMOKE_TEST_TIMEOUT_MS=120000 pnpm test
 
 The suite uses your real `.env` — the same config that runs the bot is sufficient. No separate test credentials are needed.
 
+## Known Footguns
+
+- **`pnpm build` caches stale output:** TypeScript's `tsc` writes to `dist/` incrementally. If you rename or delete a source file, the old `.js` remains in `dist/` and may be imported at runtime. **Symptoms:** mysterious `Cannot find module` errors for files that exist in source, or runtime behavior that doesn't match the code. **Fix:** `rm -rf dist && pnpm build`. Do this after any branch switch, file rename, or when `dist/` behavior doesn't match `src/`.
+- **`.env` not loaded in subshells:** `pnpm dev` loads `.env` via dotenv, but raw `node dist/index.js` does not. Always use `pnpm dev` or `pnpm start` for local runs.
+- **`pnpm i` after branch switch:** Switching branches that change `package.json` or `pnpm-lock.yaml` can leave `node_modules` in a stale state. Run `pnpm i` after checkout if you see unexpected import errors.
+- **Port conflicts with webhook server:** If `DISCOCLAW_WEBHOOK_ENABLED=1` and another process holds port `9400` (or your configured `DISCOCLAW_WEBHOOK_PORT`), the bot crashes on startup with `EADDRINUSE`. Check with `lsof -i :9400`.
+- **Editing `.env.example` vs `.env`:** `.env.example` is tracked in git and has no effect at runtime. Your actual config is in `.env` (gitignored). Editing the wrong file is a common mistake. **How to tell:** `git diff` shows changes → you edited the tracked `.env.example`. `.env` changes never appear in `git diff`.
+- **`.env` values with spaces or special characters:** Values with spaces must be quoted (`VAR="value with spaces"`). Values with `#` are truncated at the `#` (treated as inline comment by dotenv). Wrap in double quotes to include literal `#` characters.
+- **PID lock contention during rapid restarts:** If you `pnpm dev`, Ctrl-C, and immediately `pnpm dev` again, the lock directory (`data/discoclaw.pid.lock/`) may still exist from the previous process. The 2-second grace period can cause `PID lock initializing` errors. Wait 2 seconds or manually `rm -rf data/discoclaw.pid.lock` if it persists.
+
+## Common Failure Modes
+
+### `pnpm build` fails with type errors
+**Symptom:** `tsc` reports type errors in `src/`. Build exits non-zero.
+**Recovery:**
+```bash
+# Check for stale dist artifacts
+rm -rf dist
+pnpm build
+
+# If errors persist, check for missing deps
+pnpm i
+pnpm build
+
+# For type errors in unchanged files, your deps may have updated types
+# Check what changed:
+git diff pnpm-lock.yaml
+```
+
+### `pnpm dev` exits immediately with "Missing DISCORD_TOKEN"
+**Symptom:** Process exits within 1 second, logs `Missing required env: DISCORD_TOKEN`.
+**Cause:** `.env` file is missing, misnamed, or the variable is commented out.
+**Recovery:**
+```bash
+# Verify .env exists and has the token
+ls -la .env
+grep DISCORD_TOKEN .env
+
+# If missing, create from example
+cp .env.example .env
+# Then edit .env with your actual values
+```
+
+### `pnpm dev` starts but Claude CLI invocations fail
+**Symptom:** Bot responds to messages but replies with an error like "Runtime invocation failed" or "spawn claude ENOENT".
+**Cause:** Claude CLI binary not found on `PATH`, or wrong binary name in `CLAUDE_BIN`.
+**Recovery:**
+```bash
+# Verify the CLI is installed and reachable
+which claude
+claude --version
+
+# If installed but not found, check CLAUDE_BIN in .env
+grep CLAUDE_BIN .env
+
+# If using a non-standard path
+CLAUDE_BIN=/path/to/claude pnpm dev
+```
+
+### Tests fail with "Cannot find module" errors
+**Symptom:** `pnpm test` crashes before tests run, with Node module resolution errors.
+**Cause:** `dist/` is stale or `node_modules` is incomplete.
+**Recovery:**
+```bash
+rm -rf dist
+pnpm i
+pnpm build
+pnpm test
+```
+
+### `dist/` contains ghost files from deleted/renamed source
+**Symptom:** Runtime imports a module that no longer exists in `src/`, or old behavior persists after source changes. `pnpm build` succeeds (tsc only checks current source files — it doesn't clean up old output).
+**Cause:** `tsc` incremental compilation never deletes output files. Renamed `src/foo.ts` → `src/bar.ts` leaves `dist/foo.js` behind.
+**Recovery:**
+```bash
+# Clean and rebuild
+rm -rf dist
+pnpm build
+
+# Verify no ghosts: dist/ should only contain files corresponding to src/
+# Quick check — file count should roughly match
+ls src/**/*.ts | wc -l
+ls dist/**/*.js | wc -l
+```
+
+### PID lock error on `pnpm dev` — "PID lock initializing" or "another instance is already running"
+**Symptom:** `pnpm dev` exits immediately with `PID lock initializing (dir age: Xms)` or `Another discoclaw instance is already running (PID XXXXX)`.
+**Cause:** Previous `pnpm dev` was killed (Ctrl-C / SIGKILL) before the lock was released, or another instance is genuinely running.
+**Recovery:**
+```bash
+# Check if another instance is actually running
+cat data/discoclaw.pid.lock/meta.json 2>/dev/null
+# If it shows a PID, check if alive:
+kill -0 $(jq -r .pid data/discoclaw.pid.lock/meta.json) 2>/dev/null && echo "alive" || echo "stale"
+
+# If stale or "initializing" error: remove and retry
+rm -rf data/discoclaw.pid.lock
+pnpm dev
+
+# If alive: stop the other instance first, or use a different terminal
+```
+
+### `pnpm sync:discord-context` fails
+**Symptom:** Command exits with an error about missing `DISCORD.md` or content directory.
+**Cause:** `DISCOCLAW_CONTENT_DIR` or `DISCOCLAW_DATA_DIR` not set, or the content directory doesn't exist yet.
+**Recovery:**
+```bash
+# Check which content dir is configured
+grep -E 'DISCOCLAW_CONTENT_DIR|DISCOCLAW_DATA_DIR' .env
+
+# Create the directory structure if missing
+mkdir -p data/content/discord/channels
+
+# Re-run
+pnpm sync:discord-context
+```
+
 ## Notes
 - Runtime invocation defaults are configurable via env (`RUNTIME_MODEL`, `RUNTIME_TOOLS`, `RUNTIME_TIMEOUT_MS`).
 - If `pnpm dev` fails with "Missing DISCORD_TOKEN", your `.env` isn't loaded or the var is unset.