discoclaw 0.1.0

package/.context/README.md

@@ -0,0 +1,42 @@
+# Context Modules
+
+Modular context files loaded on-demand based on the task at hand.
+Core instructions live in `CLAUDE.md` at the repo root.
+
+## Loading Patterns
+
+| When doing... | Read this first |
+|---------------|-----------------|
+| **PA behavior / formatting / memory** | `pa.md` |
+| **PA safety / injection defense** | `pa-safety.md` |
+| **Discord behavior + routing** | `discord.md` |
+| **Discord bot setup (invite + env)** | `bot-setup.md` |
+| **Development / build / test** | `dev.md` |
+| **Runtime adapters (Claude CLI, OpenAI/Gemini later)** | `runtime.md` |
+| **Ops / systemd service** | `ops.md` |
+| **Memory system** | `memory.md` |
+| **Task tracking / bd CLI** | `tasks.md` |
+| **Architecture / system overview** | `architecture.md` |
+| **Tool capabilities / browser automation** | `tools.md` |
+| **Forge/plan standing constraints** | `project.md` *(auto-loaded by forge)* |
+| **Plan & Forge commands** | `plan-and-forge.md` *(in docs/, not .context/)* |
+
+## Context Hygiene (Strict)
+- Read the minimum necessary modules for the task.
+- Do not load modules "just in case."
+- Some reference docs live in `docs/` rather than `.context/` — these are human/developer references and are **not** auto-loaded into agent context. The `.context/project.md` file remains the only `.context` module for plan/forge constraints.
+
+## Quick Reference
+- **pa.md** — PA behavioral rules, Discord formatting, memory, group chat etiquette, autonomy tiers
+- **pa-safety.md** — Indirect prompt injection defense, golden rules, red flags
+- **dev.md** — Commands, env, local dev loops, build/test
+- **discord.md** — Allowlist gating, session keys, threading rules, output constraints
+- **runtime.md** — Runtime adapter interface, Claude CLI flags, capability routing
+- **ops.md** — systemd service notes, logs, restart workflow
+- **memory.md** — Memory layers, user-facing examples, config reference, concurrency
+- **tasks.md** — Task tracker: data model, bd CLI, hooks, Discord sync, auto-tagging
+- **architecture.md** — System overview, data flow, directory layout, key concepts
+- **bot-setup.md** — One-time bot creation and invite guide
+- **tools.md** — Available tools: browser automation (agent-browser), escalation ladder, CDP connect, security guardrails
+- **project.md** — Standing constraints auto-loaded by forge drafter and auditor
+- **docs/plan-and-forge.md** — Canonical reference for `!plan` and `!forge` commands (lives in `docs/`, not `.context/` — human/developer reference, not auto-loaded into agent context)

package/.context/architecture.md

@@ -0,0 +1,58 @@
+# Architecture
+
+DiscoClaw is a personal AI orchestrator that coordinates between Discord, AI runtimes
+(Claude Code, OpenAI, Codex), and local system resources — managing conversation state,
+task routing, scheduling, and tool access. It emphasizes small, explicit, auditable code.
+
+## Data Flow
+
+```
+Discord message
+  → allowlist gate (DISCORD_ALLOW_USER_IDS)
+  → session lookup/create (keyed by user+channel)
+  → context assembly (PA files + PA modules + channel context + durable memory)
+  → runtime adapter invocation (streaming)
+  → streaming response → Discord message edits (chunked, code-block-aware)
+  → optional: parse & execute discord actions from response
+```
+
+## Directory Layout
+
+| Path | Purpose |
+|------|---------|
+| `src/index.ts` | Entry point — config, wiring, bot startup |
+| `src/discord.ts` | Discord client, message handler, prompt assembly |
+| `src/discord/` | Discord subsystems: actions, allowlist, channel context, memory, output |
+| `src/runtime/` | Runtime adapters (Claude CLI), concurrency, process pool |
+| `src/tasks/` | In-process task data model + store + migration helpers |
+| `src/beads/` | Retired legacy shim namespace (runtime shims removed in hard-cut) |
+| `src/cron/` | Cron scheduler, executor, forum sync, run stats |
+| `src/observability/` | Metrics registry |
+| `src/sessions.ts` | Session manager (maps session keys to runtime session IDs) |
+| `content/discord/channels/` | Per-channel context files |
+| `workspace/` | Identity files (SOUL.md, IDENTITY.md, USER.md) — gitignored |
+| `.context/` | Developer context modules (you are here) |
+
+## Key Concepts
+
+- **Channel context** — per-channel `.md` files injected into the prompt. PA modules
+  apply to all channels; channel-specific files add overrides.
+- **PA context modules** — `.context/pa.md` and `.context/pa-safety.md`, loaded for
+  every invocation. Fail-closed: missing modules crash the bot at startup.
+- **Session keys** — `user:channel` composites that map to runtime sessions, giving
+  each user+channel pair its own conversation continuity.
+- **Runtime adapters** — pluggable interface (`src/runtime/types.ts`) that wraps an AI
+  CLI/API. The orchestrator routes to the appropriate adapter based on context (message
+  handling, forge drafting, auditing). Available: Claude Code CLI, OpenAI HTTP, Codex CLI.
+- **Discord actions** — structured JSON actions the AI can emit in its response
+  (send messages, create channels, manage tasks, etc.), parsed and executed post-response.
+- **Tasks** — built-in task tracker backed by in-process `TaskStore`, synced to Discord forum threads.
+- **Cron** — forum-based scheduled tasks. Each forum thread defines a job;
+  archive to pause, unarchive to resume. Enabled by default.
+
+## Entry Points
+
+- `src/index.ts` — loads config, wires up runtime adapters + session manager + channel
+  context, starts the orchestrator.
+- `src/discord.ts` — Discord interface layer: event handlers, context assembly, prompt
+  routing, response streaming.

package/.context/bot-setup.md

@@ -0,0 +1,24 @@
+# bot-setup.md — Discord Bot Setup (Agent Context)
+
+> For the full human-facing setup guide, see `docs/discord-bot-setup.md`. This file is a brief reference for Claude when helping with bot setup tasks.
+
+## 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.
+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).
+4. **Validate**:
+   - *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.
+
+## Getting IDs
+
+Discord client: Settings → Advanced → Developer Mode, then right-click a user/channel → Copy ID.
+
+## Common issues
+
+- **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.

package/.context/dev.md

@@ -0,0 +1,230 @@
+# dev.md — Development
+
+## Install / Build / Run
+
+```bash
+cd /path/to/discoclaw
+pnpm i
+pnpm build
+pnpm dev
+```
+
+**Optional tools:** Install [`agent-browser`](https://github.com/anthropics/agent-browser) if browser automation is needed. It must be on `PATH` for Claude CLI to launch it. After installing, run `agent-browser install` to fetch a bundled Chromium (or set `AGENT_BROWSER_EXECUTABLE_PATH` to use a system browser).
+
+## One-Off: Sync Discord Content
+
+```bash
+pnpm sync:discord-context
+pnpm sync:discord-context -- --rewrite-index
+pnpm sync:discord-context -- --add-channel 123456789012345678:my-channel
+```
+
+## Environment
+
+Two setup paths:
+
+- **Global install (end users):** Run `discoclaw init` — interactive wizard creates and configures `.env`.
+- **From source (contributors):** Run `pnpm setup` for guided configuration, or copy `.env.example` → `.env` for essentials only. For all ~90 options, use `.env.example.full`. See those files for inline comments.
+
+### Discord
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DISCORD_TOKEN` | **(required)** | Bot token |
+| `DISCORD_ALLOW_USER_IDS` | **(required)** | Comma/space-separated Discord user IDs; fail-closed if empty |
+| `DISCORD_CHANNEL_IDS` | *(empty — all channels)* | Restrict the bot to specific guild channel IDs (DMs still allowed) |
+| `DISCORD_REQUIRE_CHANNEL_CONTEXT` | `1` | Require a per-channel context file before responding |
+| `DISCORD_AUTO_INDEX_CHANNEL_CONTEXT` | `1` | Auto-create stub context files for new channels |
+| `DISCORD_AUTO_JOIN_THREADS` | `0` | Best-effort auto-join threads so the bot can respond inside them |
+| `DISCOCLAW_DISCORD_ACTIONS` | `0` | Master switch for Discord server actions |
+| `DISCOCLAW_DISCORD_ACTIONS_CHANNELS` | `1` | Channel management (create/edit/delete/list/info, categoryCreate) |
+| `DISCOCLAW_DISCORD_ACTIONS_MESSAGING` | `0` | Messaging (send/edit/delete/read messages, react, threads, pins) |
+| `DISCOCLAW_DISCORD_ACTIONS_GUILD` | `0` | Guild info (memberInfo, roleInfo, roleAdd/Remove, events, search) |
+| `DISCOCLAW_DISCORD_ACTIONS_MODERATION` | `0` | Moderation (timeout, kick, ban) |
+| `DISCOCLAW_DISCORD_ACTIONS_POLLS` | `0` | Poll creation |
+| `DISCOCLAW_DISCORD_ACTIONS_TASKS` | `1` | Task tracking (create/update/close/show/list/sync) |
+
+### Claude CLI
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_BIN` | `claude` | Path/name of the Claude CLI binary |
+| `CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS` | `0` | Pass `--dangerously-skip-permissions` to the CLI |
+| `CLAUDE_OUTPUT_FORMAT` | `text` | `text` or `stream-json` (preferred for smoother streaming) |
+| `CLAUDE_ECHO_STDIO` | `0` | Forward raw CLI stdout/stderr lines into Discord output |
+| `CLAUDE_DEBUG_FILE` | *(empty)* | Write Claude CLI debug logs to this file path |
+| `CLAUDE_STRICT_MCP_CONFIG` | `1` | Pass `--strict-mcp-config` to skip slow MCP plugin init |
+
+### App
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DISCOCLAW_DATA_DIR` | *(empty)* | Optional data root; sets default `WORKSPACE_CWD` to `$DISCOCLAW_DATA_DIR/workspace` |
+| `DISCOCLAW_CONTENT_DIR` | *(empty)* | Channel-context content dir (per-channel files only; PA modules always load from `.context/` in repo root); defaults to `$DISCOCLAW_DATA_DIR/content` |
+| `WORKSPACE_CWD` | `./workspace` | Runtime working directory (overrides the data-dir default) |
+| `GROUPS_DIR` | `./groups` | Base directory for per-session working dirs |
+| `USE_GROUP_DIR_CWD` | `0` | Enable nanoclaw-style group CWD per session |
+| `LOG_LEVEL` | `info` | Pino log level |
+| `DISCOCLAW_DEBUG_RUNTIME` | `0` | Dump resolved runtime config at startup (debugging systemd env issues) |
+
+### Runtime Invocation
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RUNTIME_MODEL` | `capable` | Model tier (`fast`, `capable`) or concrete model name passed to the CLI |
+| `RUNTIME_TOOLS` | `Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch` | Comma-separated tool list |
+| `RUNTIME_TIMEOUT_MS` | `600000` | Per-invocation timeout in milliseconds |
+| `DISCOCLAW_RUNTIME_SESSIONS` | `1` | Persist Claude session IDs across messages |
+| `DISCOCLAW_MESSAGE_HISTORY_BUDGET` | `3000` | Char budget for recent conversation history in prompts (0 = disabled) |
+| `DISCOCLAW_SUMMARY_ENABLED` | `1` | Enable rolling conversation summaries |
+| `DISCOCLAW_SUMMARY_MODEL` | `fast` | Model tier or concrete name for summarization |
+| `DISCOCLAW_SUMMARY_MAX_CHARS` | `2000` | Max chars for the rolling summary text |
+| `DISCOCLAW_SUMMARY_EVERY_N_TURNS` | `5` | Re-summarize every N messages per session |
+| `DISCOCLAW_DURABLE_MEMORY_ENABLED` | `1` | Enable durable per-user memory (persistent facts/preferences) |
+| `DISCOCLAW_DURABLE_INJECT_MAX_CHARS` | `2000` | Max chars for durable memory injected into prompts |
+| `DISCOCLAW_DURABLE_MAX_ITEMS` | `200` | Max durable items per user |
+| `DISCOCLAW_MEMORY_COMMANDS_ENABLED` | `1` | Enable `!memory` commands (show/remember/forget/reset) |
+| `DISCOCLAW_STATUS_CHANNEL` | *(empty — disabled)* | Channel name or ID for status messages (bot online/offline, errors) |
+| `RUNTIME_FALLBACK_MODEL` | *(unset)* | Auto-fallback model when primary is overloaded (e.g. `sonnet`) |
+| `RUNTIME_MAX_BUDGET_USD` | *(unset)* | Max USD per CLI process; one-shot = per invocation, multi-turn = per session lifetime |
+| `CLAUDE_APPEND_SYSTEM_PROMPT` | *(unset)* | Append to system prompt (max 4000 chars); skips workspace PA file reads when set |
+| `DISCOCLAW_CRON_ENABLED` | `1` | Master switch for the cron subsystem (forum-based scheduled tasks) |
+| `DISCOCLAW_CRON_FORUM` | **(required when enabled)** | Automations forum channel ID (snowflake) for cron/automation definitions |
+| `DISCOCLAW_CRON_MODEL` | `fast` | Model tier or concrete name for parsing cron definitions |
+
+### Browser Automation
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_BROWSER_EXECUTABLE_PATH` | *(empty)* | Path to the browser binary for `agent-browser` (e.g. Chromium). If unset, agent-browser uses its bundled default. |
+
+### Tasks (Task Tracking)
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DISCOCLAW_TASKS_ENABLED` | `1` | Master switch — loads tasks subsystem |
+| `DISCOCLAW_TASKS_FORUM` | **(required when enabled)** | Forum channel ID (snowflake) for task threads |
+| `DISCOCLAW_TASKS_CWD` | `<WORKSPACE_CWD>` | Tasks workspace override (legacy import/migration path) |
+| `DISCOCLAW_TASKS_TAG_MAP` | `data/tasks/tag-map.json` | Path to task forum tag map |
+| `DISCOCLAW_TASKS_MENTION_USER` | *(empty)* | User ID to @mention in new task threads |
+| `DISCOCLAW_TASKS_SIDEBAR` | `0` | When `1` + `MENTION_USER` set, persists @mention in open task starters for sidebar visibility |
+| `DISCOCLAW_TASKS_AUTO_TAG` | `1` | Enable AI auto-tagging |
+| `DISCOCLAW_TASKS_AUTO_TAG_MODEL` | `fast` | Model tier or concrete name for auto-tagging |
+| `DISCOCLAW_TASKS_SYNC_SKIP_PHASE5` | `0` | Disable phase-5 reconciliation during sync |
+| `DISCOCLAW_TASKS_PREFIX` | `ws` | Prefix for generated task IDs (e.g. `ws-001`) |
+
+## Debugging
+
+### Where logs go
+
+| Mode | Log destination |
+|------|----------------|
+| `pnpm dev` | stdout/stderr in your terminal |
+| systemd service | journalctl (`journalctl --user -u discoclaw.service`) |
+
+DiscoClaw uses Pino for structured JSON logging. All app logs go to stdout.
+
+### Quick commands
+
+```bash
+# Local dev — logs stream to terminal automatically
+pnpm dev
+
+# Production — tail live logs
+journalctl --user -u discoclaw.service -f
+
+# Production — last 50 lines
+journalctl --user -u discoclaw.service -n 50
+
+# Production — logs since last boot
+journalctl --user -u discoclaw.service -b
+
+# Production — logs from the last 10 minutes
+journalctl --user -u discoclaw.service --since "10 min ago"
+```
+
+### Increasing verbosity
+
+Set `LOG_LEVEL` in `.env` to get more detail. Levels: `fatal`, `error`, `warn`, `info`, `debug`, `trace`.
+
+```bash
+LOG_LEVEL=debug pnpm dev
+```
+
+### Claude CLI debug output
+
+To capture raw Claude CLI stdin/stdout for diagnosing runtime issues:
+
+```bash
+# Write CLI debug logs to a file
+CLAUDE_DEBUG_FILE=/tmp/claude-debug.log pnpm dev
+
+# Echo raw CLI output into Discord (noisy, useful for live debugging)
+CLAUDE_ECHO_STDIO=1 pnpm dev
+```
+
+### Startup / env issues
+
+If the bot starts but behaves unexpectedly (wrong model, missing tools, wrong CWD):
+
+```bash
+# Dump resolved runtime config at startup
+DISCOCLAW_DEBUG_RUNTIME=1 pnpm dev
+```
+
+This is especially useful for systemd, where env loading can differ from your shell.
+
+### What to look for
+
+- **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.
+
+## Task Auto-Sync
+
+When the bot is running, task changes trigger Discord sync immediately via in-process events:
+
+- **Startup sync:** On boot, a fire-and-forget full sync runs to catch any drift that occurred while the bot was down.
+- **Synchronous events:** The in-process task store emits events on every write (`created`, `updated`, `closed`, `labeled`). Discord sync subscribers handle each event immediately — no file watcher, no debounce, no subprocess spawning.
+- **Coordinator:** All sync paths (event-driven, startup, manual `taskSync` action) share a `TaskSyncCoordinator` that prevents concurrent syncs and invalidates the thread cache. Auto-triggered syncs are silent; only manual sync posts to the status channel.
+
+No extra env vars are needed — auto-sync activates whenever `DISCOCLAW_TASKS_ENABLED=1` and a guild is available.
+
+## Smoke Tests
+
+The smoke-test suite validates each configured model tier end-to-end — verifying API keys, tier mappings, system prompts, and binary availability — before real users encounter a broken model path.
+
+It exercises `RuntimeAdapter.invoke()` → `EngineEvent` pipeline with a curated set of prompt categories (basic Q&A, tool use, streaming). Tests are **opt-in** and skipped by default in CI unless `SMOKE_TEST_TIERS` is set.
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SMOKE_TEST_TIERS` | *(unset — skips smoke tests)* | Comma-separated list of tier names (`fast`, `capable`) or literal model IDs to test for Claude Code (e.g. `fast,capable` or `claude-haiku-4-5-20251001`) |
+| `GEMINI_SMOKE_TEST_TIERS` | *(unset — skips Gemini smoke tests)* | Comma-separated tier names or model IDs for Gemini smoke tests (requires `GEMINI_API_KEY`) |
+| `OPENAI_SMOKE_TEST_TIERS` | *(unset — skips OpenAI smoke tests)* | Comma-separated tier names or model IDs for OpenAI smoke tests (requires `OPENAI_API_KEY`) |
+| `CODEX_SMOKE_TEST_TIERS` | *(unset — skips Codex smoke tests)* | Comma-separated tier names or model IDs for Codex smoke tests (requires `codex` binary on `PATH`) |
+| `SMOKE_TEST_TIMEOUT_MS` | `60000` | Per-invocation timeout for each smoke-test prompt, in milliseconds (applies to all providers) |
+
+### Usage
+
+```bash
+# Run Claude Code smoke tests against the fast and capable tiers
+SMOKE_TEST_TIERS=fast,capable pnpm test
+
+# Run against a specific Claude model ID
+SMOKE_TEST_TIERS=claude-sonnet-4-6 pnpm test
+
+# Run Gemini smoke tests for the fast tier
+GEMINI_SMOKE_TEST_TIERS=fast pnpm test
+
+# Run OpenAI smoke tests (requires OPENAI_API_KEY)
+OPENAI_SMOKE_TEST_TIERS=fast pnpm test
+
+# Run Codex smoke tests (requires codex binary on PATH)
+CODEX_SMOKE_TEST_TIERS=fast pnpm test
+
+# Adjust timeout (e.g. slower network)
+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.
+
+## 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.

package/.context/discord.md

@@ -0,0 +1,144 @@
+# discord.md — Discord Behavior & Routing
+
+## Access Control
+- `DISCORD_ALLOW_USER_IDS` is the primary gate.
+- Fail closed: if the allowlist is empty, DiscoClaw responds to nobody.
+- Optional: `DISCORD_CHANNEL_IDS` restricts the bot to specific guild channels (DMs are still allowed).
+
+## Base PA Context
+
+Base PA behavioral and safety context is loaded from `.context/pa.md` and `.context/pa-safety.md`
+in the repo root. These are required — the bot refuses to start if either is missing.
+
+## Channel Context (Token-Efficient)
+DiscoClaw inlines per-channel context files into the runtime prompt.
+
+Layout (under `$DISCOCLAW_CONTENT_DIR` or `$DISCOCLAW_DATA_DIR/content`):
+- `discord/DISCORD.md` (index: channel -> id -> context file)
+- `discord/channels/*.md` (per-channel context modules)
+- `discord/channels/_default.md` (fallback for unknown channels)
+- `discord/channels/dm.md` (DM fallback)
+
+Behavior:
+- For each message, DiscoClaw tells the runtime to `Read` the relevant channel context file before responding.
+- For threads, the parent channel context applies.
+
+Strict mode:
+- `DISCORD_REQUIRE_CHANNEL_CONTEXT=1` (default): the bot requires a per-channel context file.
+- `DISCORD_AUTO_INDEX_CHANNEL_CONTEXT=1` (default): when a message arrives for a new channel, DiscoClaw appends it to `discord/DISCORD.md` and creates a blank stub file.
+
+Thread auto-join:
+- `DISCORD_AUTO_JOIN_THREADS=0` (default): best-effort auto-join threads so the bot can respond inside them. Private threads still require adding the bot manually.
+
+## Conversation History & Memory
+When `DISCOCLAW_MESSAGE_HISTORY_BUDGET` > 0 (default: `3000`), DiscoClaw fetches recent messages from the Discord channel and includes them in the prompt as conversation context. This allows Claude to maintain conversational context across messages without relying on CLI session persistence. The char budget caps the total history size; messages are selected newest-first so the most relevant context is preserved. Bot responses are truncated when necessary to fit the budget.
+
+### Rolling Summaries
+When `DISCOCLAW_SUMMARY_ENABLED=1` (default), DiscoClaw maintains a rolling conversation summary per session key, generated by Haiku every N turns (`DISCOCLAW_SUMMARY_EVERY_N_TURNS`, default 5). The summary is a compressed narrative of earlier conversation — decisions, preferences, current focus — kept under `DISCOCLAW_SUMMARY_MAX_CHARS` characters.
+
+Summaries are stored on disk at `data/memory/rolling/<safe-session-key>.json` and injected into the prompt between context files and recent conversation as a "Conversation memory" section. When recent messages and the summary conflict, the recent messages take precedence (the summary is lossy). Summary generation is best-effort: failures are logged and do not block responding.
+
+### Durable Memory
+When `DISCOCLAW_DURABLE_MEMORY_ENABLED=1` (default), DiscoClaw maintains persistent per-user memory that survives across channels and sessions. Items are stored at `data/memory/durable/<user-id>.json` and include facts, preferences, projects, and other user-specific notes.
+
+Active durable items are injected into the prompt between context files and conversation memory, sorted by most recently updated, capped by `DISCOCLAW_DURABLE_INJECT_MAX_CHARS` (default 2000). Each user can store up to `DISCOCLAW_DURABLE_MAX_ITEMS` (default 200) items.
+
+When `DISCOCLAW_MEMORY_COMMANDS_ENABLED=1` (default), users can manage their durable memory via commands:
+- `!memory` or `!memory show` — display active durable items and rolling summary
+- `!memory remember <text>` — store a new fact
+- `!memory forget <text>` — deprecate matching items (requires 60% text-length match)
+- `!memory reset rolling` — clear the rolling summary for the current session
+
+Memory commands are intercepted before runtime invocation and do not consume API tokens.
+
+## Session Keys
+- DM: `discord:dm:<authorId>`
+- Thread: `discord:thread:<threadId>` (if the incoming channel is a thread)
+- Channel: `discord:channel:<channelId>`
+
+These session keys map to persisted UUIDs via `data/sessions.json`.
+
+## Concurrency (Single Flight)
+- DiscoClaw serializes processing per session key to avoid interleaving tool runs/context.
+- Implementation: `src/group-queue.ts`
+
+## Output Constraints
+- Discord has a ~2000 char limit per message.
+- DiscoClaw chunks long replies and attempts to keep fenced code blocks renderable across splits.
+
+## Discord Actions
+When `DISCOCLAW_DISCORD_ACTIONS=1` (master switch), Claude can perform Discord server actions by emitting `<discord-action>` blocks in its response. After the runtime completes, DiscoClaw parses these blocks, executes them via discord.js, strips the blocks from the displayed message, and appends results.
+
+Each action category has its own flag (only active when the master switch is `1`):
+
+| Flag | Default | Actions |
+|------|---------|---------|
+| `DISCOCLAW_DISCORD_ACTIONS_CHANNELS` | `1` | channelCreate, channelEdit, channelDelete, channelList, channelInfo, categoryCreate, threadListArchived |
+| `DISCOCLAW_DISCORD_ACTIONS_MESSAGING` | `0` | sendMessage, react, readMessages, fetchMessage, editMessage, deleteMessage, threadCreate, pinMessage, unpinMessage, listPins |
+| `DISCOCLAW_DISCORD_ACTIONS_GUILD` | `0` | memberInfo, roleInfo, roleAdd, roleRemove, searchMessages, eventList, eventCreate |
+| `DISCOCLAW_DISCORD_ACTIONS_MODERATION` | `0` | timeout, kick, ban |
+| `DISCOCLAW_DISCORD_ACTIONS_POLLS` | `0` | poll |
+| `DISCOCLAW_DISCORD_ACTIONS_TASKS` | `1` | taskCreate, taskUpdate, taskClose, taskShow, taskList, taskSync |
+
+Auto-follow-up: When query actions (channelList, channelInfo, threadListArchived, readMessages, fetchMessage, listPins, memberInfo, roleInfo, searchMessages, eventList, taskList, taskShow) succeed, DiscoClaw automatically re-invokes Claude with the results. This allows Claude to reason about query results without requiring the user to send a follow-up message. Controlled by `DISCOCLAW_ACTION_FOLLOWUP_DEPTH` (default `3`, `0` disables). Mutation-only responses do not trigger follow-ups. Trivially short follow-up responses (<50 chars with no actions) are suppressed.
+
+Requirements:
+- The bot needs appropriate permissions in the server (Manage Channels, Manage Roles, Moderate Members, etc.) depending on the actions used. These are server-level role permissions, not Developer Portal settings.
+- Only works in guild channels (not DMs).
+- Master switch defaults to off (`0`). Only allowlisted users can trigger actions.
+- Destructive actions (delete, kick, ban, timeout) prompt Claude to confirm with the user first.
+- If actions fail with "Missing Permissions", the bot's role lacks the required permission.
+
+## Status Channel
+When `DISCOCLAW_STATUS_CHANNEL` is set to a channel name or ID, DiscoClaw posts plain-text status messages on key events:
+- **Bot Online** — posted after the `ready` event fires
+- **Bot Offline** — posted on SIGTERM/SIGINT (best-effort)
+- **Runtime Error** — runtime invocation failed or timed out
+- **Handler Failure** — uncaught exception in message processing
+- **Action Failed** — a Discord action returned `{ ok: false }`
+
+Fail-open: if the channel is not found or the env var is unset, the bot works normally with no status posts. Errors posting to the status channel are caught and logged, never crashing the bot.
+
+Implementation: `src/discord/status-channel.ts`
+
+## Cron (Scheduled Tasks)
+When `DISCOCLAW_CRON_ENABLED=1` (default), `DISCOCLAW_CRON_FORUM` must be set to the "automations" forum channel ID (snowflake). DiscoClaw runs a forum-based cron subsystem. Each forum thread is a cron job: the thread name is the job name, and the starter message is a natural-language definition that gets parsed by AI into a schedule, timezone, target channel, and prompt.
+
+Creating a cron: create a thread in the forum. The starter message should describe the schedule, target channel, and what to do (e.g., "Every weekday at 7am Pacific, check the weather for Portland OR and post a brief summary to #general."). The bot reacts with a checkmark and replies with the parsed schedule.
+
+Managing crons:
+- **Disable:** Archive the thread. The bot stops scheduling.
+- **Enable:** Unarchive the thread. The bot re-parses and resumes.
+- **Edit:** Edit the starter message. The bot re-parses on the next `messageUpdate`.
+- **Delete:** Delete the thread. The bot removes the job.
+
+Archive vs delete: archiving a thread is reversible (sets the archived flag; thread still exists and can be unarchived). Deleting a thread is permanent (thread and its messages are gone). The `cronDelete` action archives the thread — it does not delete it — so history is preserved and the cron can be restored by unarchiving.
+
+Cron responses are posted to the target channel only (threads stay clean as config). Discord actions are supported in cron responses if the master switch is enabled. Failures are posted to the status channel.
+
+Overlap protection: if a previous run for the same job is still active, the next tick is skipped.
+
+Implementation: `src/cron/`
+
+## Tasks (Task Tracking)
+DiscoClaw includes a task tracker backed by in-process `TaskStore` data and synced to Discord forum threads.
+
+- Data model/store: `src/tasks/types.ts`, `src/tasks/store.ts`
+- Discord task action path: `src/tasks/task-action-executor.ts` (dispatch), `src/tasks/task-action-mutations.ts` (create/update/close), `src/tasks/task-action-thread-sync.ts` (thread lifecycle helpers), `src/tasks/task-action-mutation-helpers.ts` (shared mutation helpers), `src/tasks/task-action-read-ops.ts` (show/list/sync/reload), `src/tasks/task-action-contract.ts` (request types)
+- Canonical sync modules: `src/tasks/task-sync-engine.ts`, `src/tasks/task-sync-pipeline.ts` (facade), `src/tasks/task-sync-apply-plan.ts`, `src/tasks/task-sync-reconcile-plan.ts`, `src/tasks/task-sync-apply-types.ts`, `src/tasks/task-sync-phase-apply.ts`, `src/tasks/task-sync-reconcile.ts`, `src/tasks/sync-coordinator.ts`, `src/tasks/sync-coordinator-metrics.ts`, `src/tasks/sync-coordinator-retries.ts`, `src/tasks/thread-helpers.ts`, `src/tasks/thread-forum-ops.ts`, `src/tasks/thread-lifecycle-ops.ts`, `src/tasks/thread-ops.ts` (facade), `src/tasks/tag-map.ts`
+- Runtime shim status: `src/beads/*` compatibility modules removed in hard-cut phase
+
+Auto-sync is event-driven from the in-process store and runs a startup reconciliation pass.
+Auto-triggered syncs are silent; explicit `taskSync` can post status output.
+
+Primary env surface is `DISCOCLAW_TASKS_*`.
+
+## Discord API Quirks
+
+**Thread name + archive in one call:** When updating a thread's name AND archiving it in a single PATCH request, the name updates but the archive flag doesn't stick. Do them as separate API calls with a short delay between.
+
+## Group CWD Mode
+If `USE_GROUP_DIR_CWD=1`:
+- CWD becomes `groups/<sessionKey>/` for that Discord context.
+- The main workspace (`WORKSPACE_CWD`) is added via `--add-dir` so tools can still read/write it.
+- DiscoClaw bootstraps `groups/<sessionKey>/CLAUDE.md` on first use.