discoclaw 0.1.0

package/.context/runtime.md

@@ -0,0 +1,253 @@
+# runtime.md — Runtimes & Adapters
+
+## Model Names & IDs
+
+**Always research official documentation** when referencing model names, IDs, or parameters — never guess or rely on training data alone. Model names change frequently across providers.
+
+Sources to check:
+- **Anthropic:** https://platform.claude.com/docs/en/about-claude/models/overview
+- **OpenAI/Codex:** https://developers.openai.com/codex/models/
+- **Claude Code CLI shorthand:** `sonnet`, `opus`, `haiku` resolve to the latest version of each model family
+
+Current model IDs (as of 2026-02-17):
+| Provider | Model | API/CLI ID |
+|----------|-------|-----------|
+| Anthropic | Claude Opus 4.6 | `claude-opus-4-6` (CLI shorthand: `opus`) |
+| Anthropic | Claude Sonnet 4.6 | `claude-sonnet-4-6` (CLI shorthand: `sonnet`) |
+| Anthropic | Claude Haiku 4.5 | `claude-haiku-4-5-20251001` (CLI shorthand: `haiku`) |
+| OpenAI | GPT-5.3-Codex | `gpt-5.3-codex` |
+| OpenAI | GPT-5.3-Codex-Spark | `gpt-5.3-codex-spark` |
+| OpenAI | GPT-5-Codex-Mini | `gpt-5-codex-mini` |
+
+## Runtime Adapter Interface
+- The orchestrator consumes a provider-agnostic event stream (`EngineEvent`) from any adapter.
+- Each runtime adapter implements `RuntimeAdapter.invoke()` and declares capabilities.
+- The orchestrator routes to adapters based on context: message handling, forge drafting/auditing, cron execution.
+
+See: `src/runtime/types.ts`
+
+## Strategy Pattern (CLI Adapters)
+
+All CLI-based runtime adapters share a universal factory (`src/runtime/cli-adapter.ts`) parameterized by a thin strategy object. New models only need ~40-80 lines of model-specific logic.
+
+```
+createCliRuntime(strategy, opts) → RuntimeAdapter
+```
+
+The strategy provides: arg building, stdin formatting, output parsing, error handling.
+The factory provides: subprocess tracking, process pool, stall detection, session scanning, JSONL parsing, image dedup, event queue.
+
+| Strategy | File | Multi-turn | Notes |
+|----------|------|------------|-------|
+| Claude Code | `strategies/claude-strategy.ts` | process-pool | Default JSONL parsing, image support |
+| Codex CLI | `strategies/codex-strategy.ts` | session-resume | Custom JSONL (thread.started, item.completed), error sanitization; reasoning items surface in the Discord preview during streaming but are excluded from the final reply |
+| Template | `strategies/template-strategy.ts` | — | Commented starting point for new models |
+
+Thin wrappers (`claude-code-cli.ts`, `codex-cli.ts`) map legacy opts and re-export for backward compatibility. Shared utilities live in `cli-shared.ts` and `cli-output-parsers.ts`. Strategy types are in `cli-strategy.ts`.
+
+Shutdown: `killAllSubprocesses()` from `cli-adapter.ts` kills all tracked subprocesses across all adapters.
+
+## Claude Code CLI Runtime (Current)
+- Adapter: `src/runtime/claude-code-cli.ts` (thin wrapper around `cli-adapter.ts` + `strategies/claude-strategy.ts`)
+- Invocation shape (full):
+  ```
+  claude -p --model <id|alias>
+    [--dangerously-skip-permissions]          # when CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1
+    [--strict-mcp-config]                     # when CLAUDE_STRICT_MCP_CONFIG=1
+    [--fallback-model <alias>]               # when RUNTIME_FALLBACK_MODEL is set
+    [--max-budget-usd <number>]              # when RUNTIME_MAX_BUDGET_USD is set
+    [--append-system-prompt <text>]          # when CLAUDE_APPEND_SYSTEM_PROMPT is set
+    [--debug-file <path>]                     # when CLAUDE_DEBUG_FILE is set
+    [--session-id <uuid>]                     # when sessions are enabled
+    [--add-dir <dir> ...]                     # group CWD mode
+    [--output-format text|stream-json]        # always passed
+    [--include-partial-messages]              # when format is stream-json
+    [--tools <comma-list>]                    # configurable tool surface
+    -- <prompt>                               # POSIX terminator before prompt
+  ```
+- The `--` terminator prevents variadic flags (e.g. `--tools`, `--add-dir`) from consuming the positional prompt argument.
+- Output modes:
+  - `CLAUDE_OUTPUT_FORMAT=stream-json` (preferred; DiscoClaw parses JSONL and streams text)
+  - `CLAUDE_OUTPUT_FORMAT=text` (fallback if your local CLI doesn't support stream-json)
+
+## Tool Surface
+- Default tools: `Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch` (8 tools).
+- `Glob` + `Grep` are purpose-built for file search — faster than `find`/`grep` via Bash.
+- `Write` enables proper file creation (previously required Bash echo/cat workarounds).
+- Non-Claude adapters use a **capability gate** (`tools_fs`) to determine tool access:
+  - Codex CLI adapter: declares `tools_fs` — receives read-only tools (Read, Glob, Grep) in auditor role.
+  - OpenAI HTTP adapter: text-only (`streaming_text` only) — no tool execution.
+  - Future adapters (Gemini, etc.): declare capabilities as appropriate.
+
+## Per-Workspace Permissions
+- `workspace/PERMISSIONS.json` controls the tool surface per workspace.
+- Loaded per-invocation from `src/workspace-permissions.ts`.
+- If the file doesn't exist, falls back to the `RUNTIME_TOOLS` env var (fully backward compatible).
+
+Tiers:
+| Tier | Tools |
+|------|-------|
+| `readonly` | `Read, Glob, Grep, WebSearch, WebFetch` |
+| `standard` | `Read, Edit, Glob, Grep, WebSearch, WebFetch` |
+| `full` | `Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch` |
+| `custom` | User-specified `tools` array in the JSON |
+
+Note: `Write` is excluded from `standard` tier (non-destructive). Included in `full` alongside Bash.
+
+Example: `{ "tier": "standard", "note": "Never modify files outside workspace." }`
+
+The optional `note` field is injected into the prompt as a soft behavioral constraint.
+Custom tier example: `{ "tier": "custom", "tools": ["Read", "Edit", "Bash"] }`
+
+## Streaming & Reply Pacing (Discord)
+
+Key settings for block streaming:
+- `blockStreaming: true` — chunks output so user sees progress instead of silence then wall of text
+- `blockStreamingCoalesce: {minChars:100, maxChars:600, idleMs:800}` — merges tiny fragments; 800ms idle = natural paragraph breaks
+- `blockStreamingBreak: text_end` — flushes after each text block (between paragraphs, before/after tool calls)
+- `toolStatusUpdates: true` — shows "Running tool..." during tool calls
+- `reasoningStreaming: false` — reasoning tokens stay hidden for casual use
+
+Tuning: too chattery? increase `minChars` or `idleMs`. Too slow? decrease `maxChars` or `idleMs`.
+
+## Stream Stall Detection
+
+Two-layer protection against hung Claude Code processes:
+
+| Env Var | Default | Purpose |
+|---------|---------|---------|
+| `DISCOCLAW_STREAM_STALL_TIMEOUT_MS` | `120000` | Kill one-shot process if no stdout/stderr for this long. `0` disables. |
+| `DISCOCLAW_STREAM_STALL_WARNING_MS` | `60000` | Show user-visible warning in Discord after this many ms of no events. `0` disables. |
+
+**Runtime layer** (`src/runtime/cli-adapter.ts`): resets a timer on every stdout/stderr `data` event. On timeout, emits a `stream stall: no output for ${ms}ms` error and kills the process. Applies to both `text` and `stream-json` output formats.
+
+**Discord layer** (`src/discord.ts`, `src/discord/reaction-handler.ts`): both message and reaction handlers track `lastEventAt` and `activeToolCount` in their streaming loops. When stall threshold is exceeded and no tools are active, appends a warning to `deltaText`. Enable `DISCOCLAW_SESSION_SCANNING=1` for tool-aware stall suppression (warnings suppressed during tool execution).
+
+## Session Scanning & Tool-Aware Streaming
+
+Two opt-in features for better Discord UX during tool-heavy invocations:
+
+| Env Var | Default | Purpose |
+|---------|---------|---------|
+| `DISCOCLAW_SESSION_SCANNING` | `0` | Tail Claude Code's JSONL session log to emit `tool_start`/`tool_end` events |
+| `DISCOCLAW_TOOL_AWARE_STREAMING` | `0` | Buffer text during tool execution, show activity indicators, stream final answer cleanly |
+
+Both require `CLAUDE_OUTPUT_FORMAT=stream-json` for structured events.
+
+## Resilience & Cost Controls
+
+| Env Var | Default | Purpose |
+|---------|---------|---------|
+| `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 text to Claude's system prompt (max 4000 chars) |
+
+**Budget semantics:** For multi-turn sessions, budget accumulates across turns and cannot be reset mid-session. Recommend $5-10 for multi-turn.
+
+**Append system prompt:** When set, workspace PA files (SOUL.md, IDENTITY.md, USER.md, TOOLS.md) are skipped from the context file list (their content is already in the system prompt). PA context modules (`.context/pa.md`, `.context/pa-safety.md`) and channel-specific context are unaffected. **Note:** Do not set this on first run before `workspace/BOOTSTRAP.md` has been consumed — the skip logic also bypasses BOOTSTRAP.md loading.
+
+- **Session scanner** (`src/runtime/session-scanner.ts`): watches `~/.claude/projects/<escaped-cwd>/<session-id>.jsonl`, skips pre-existing content, degrades gracefully if the file never appears.
+- **Tool-aware queue** (`src/discord/tool-aware-queue.ts`): state machine that suppresses narration text before tools, shows human-readable activity labels (from `src/runtime/tool-labels.ts`), and streams the final answer after all tool use completes.
+- **Tool labels** (`src/runtime/tool-labels.ts`): maps tool names to labels like "Reading .../file.ts", "Running command...", etc.
+
+## Multi-Turn (Long-Running Process)
+
+Opt-in feature that keeps a long-running Claude Code subprocess alive per Discord session key using `--input-format stream-json`. Follow-up messages are pushed to the same process via stdin NDJSON, giving Claude Code native multi-turn context (tool results, file reads, edits persist across turns).
+
+| Env Var | Default | Purpose |
+|---------|---------|---------|
+| `DISCOCLAW_MULTI_TURN` | `1` | Enable long-running process pool |
+| `DISCOCLAW_MULTI_TURN_HANG_TIMEOUT_MS` | `60000` | Kill process if no stdout output for this long |
+| `DISCOCLAW_MULTI_TURN_IDLE_TIMEOUT_MS` | `300000` | Kill idle process after 5 min of no messages |
+| `DISCOCLAW_MULTI_TURN_MAX_PROCESSES` | `5` | Max concurrent long-running processes |
+
+Key files:
+- **Long-running process** (`src/runtime/long-running-process.ts`): manages a single subprocess with state machine (`idle` -> `busy` -> `idle` or `dead`), hang detection, idle timeout.
+- **Process pool** (`src/runtime/process-pool.ts`): pool of `LongRunningProcess` instances keyed by session key, with LRU eviction.
+
+Behavior:
+- When enabled, `invoke()` tries the long-running process first for any call with a `sessionKey`.
+- On hang detection or process crash, automatically falls back to the existing one-shot mode (unchanged).
+- On shutdown, `killAllSubprocesses()` cleans up the pool.
+
+Known limitations:
+- GitHub issue #3187 reports that multi-turn stdin can hang after the first message. Mitigated by automatic hang detection + fallback.
+- Prompt construction is unchanged (full context sent every turn). Optimizing to skip redundant context is a follow-up.
+
+## Image Input (Discord → Claude)
+
+When a Discord message or reaction target has image attachments (PNG, JPEG, WebP, GIF), they are downloaded and sent to Claude Code as base64-encoded image content blocks via `--input-format stream-json` stdin.
+
+### How it works
+
+1. **Filtering** — `resolveMediaType()` checks the attachment's `contentType` (lowercased) or falls back to file extension. Non-image attachments are surfaced as plain URLs in the prompt text.
+2. **Validation** — Host allowlist (`cdn.discordapp.com`, `media.discordapp.net`), HTTPS-only, redirect rejection (`redirect: 'error'`), per-image and total size caps.
+3. **Download** — `downloadAttachment()` fetches the image with a 10 s timeout, post-checks actual size, and returns base64.
+4. **Delivery** — The runtime adapter writes a `stream-json` stdin message containing `[{ type: 'text', text: prompt }, { type: 'image', source: { type: 'base64', ... } }, ...]`. When images are present, `--output-format` is forced to `stream-json` regardless of the configured format.
+
+### Security controls
+
+| Control | Detail |
+|---------|--------|
+| Host allowlist | Only Discord CDN hosts are permitted (SSRF protection) |
+| HTTPS only | HTTP URLs are rejected |
+| Redirect rejection | `fetch()` uses `redirect: 'error'` — no following redirects to internal hosts |
+| Per-image size cap | 20 MB (`MAX_IMAGE_BYTES`), checked from metadata pre-download and from buffer post-download |
+| Total size cap | 50 MB across all images in one message (`MAX_TOTAL_BYTES`) |
+| Per-invocation cap | 10 images (`MAX_IMAGES_PER_INVOCATION`) |
+| Download timeout | 10 s per image (`DOWNLOAD_TIMEOUT_MS`) |
+| Filename sanitization | Control chars stripped, truncated to 100 chars in error messages |
+
+### Key files
+
+| File | Role |
+|------|------|
+| `src/discord/image-download.ts` | Download, validate, base64-encode Discord attachments |
+| `src/runtime/claude-code-cli.ts` | Stdin pipe construction, `effectiveOutputFormat` override |
+| `src/discord.ts` | Message handler: download images, pass to runtime, images only on initial turn |
+| `src/discord/reaction-handler.ts` | Reaction handler: same download flow, also surfaces non-image attachment URLs |
+
+### Follow-up depth gating
+
+Images are only sent on the initial invocation (`followUpDepth === 0`). Auto-follow-up turns (triggered by query actions) are text-only — re-downloading images would waste time and bandwidth.
+
+## Image Output (Claude → Discord)
+
+Any `image` content block in Claude Code's stream-json output is automatically captured and delivered as a Discord file attachment. Claude models don't natively generate images — images only appear when an MCP tool returns image content blocks.
+
+### How it works
+
+1. **Extraction** — `extractImageFromUnknownEvent()` in `claude-code-cli.ts` recognizes direct `{ type: 'image', source: { type: 'base64', media_type, data } }` blocks and `content_block_start` wrappers. `extractResultContentBlocks()` handles result events containing mixed text + image arrays.
+2. **Dedup** — `imageDedupeKey()` builds a key from media type + base64 length + 64-char prefix. Each consumer tracks a `Set<string>` of seen keys so duplicates (common with multi-turn mirrors) are dropped.
+3. **Delivery** — `buildAttachments()` in `output-common.ts` converts each `ImageData` to a Discord `AttachmentBuilder` (named `image-1.png`, etc.). The three consumer paths — message (`discord.ts`), reaction (`reaction-handler.ts`), and cron (`executor.ts`) — all collect images into an `ImageData[]` during streaming and pass them to the shared send helpers.
+
+### Key files
+
+| File | Role |
+|------|------|
+| `src/runtime/types.ts` | `ImageData` type, `image_data` EngineEvent variant |
+| `src/runtime/cli-output-parsers.ts` | Extraction, dedup key functions |
+| `src/runtime/cli-adapter.ts` | Per-invocation image counting, dedup via strategy |
+| `src/runtime/long-running-process.ts` | Multi-turn mirror: dedup + emit for long-running sessions |
+| `src/discord/output-common.ts` | `buildAttachments()`, attachment slicing across message chunks |
+| `src/discord.ts` | Message path consumer |
+| `src/discord/reaction-handler.ts` | Reaction path consumer |
+| `src/cron/executor.ts` | Cron path consumer |
+
+### Limits
+
+| Limit | Value | Source |
+|-------|-------|--------|
+| Max base64 size per image | 25 MB | `MAX_IMAGE_BASE64_LEN` |
+| Max images per invocation | 10 | `MAX_IMAGES_PER_INVOCATION` |
+| Max attachments per Discord message | 10 | Discord API limit |
+
+### Enabling image generation
+
+Since Claude can't generate images directly, you need an MCP server that wraps an external image API (DALL-E, Replicate, Stability, etc.).
+
+1. **Set up an MCP server** that exposes a tool (e.g. `generate_image`) returning an `image` content block with `{ type: 'base64', media_type, data }`. Any MCP server that returns image content blocks will work — the pipeline is format-driven, not tool-name-driven.
+2. **Register it** in the workspace `.mcp.json` so Claude Code loads it on invocation.
+3. **Add workspace instructions** (in `workspace/SOUL.md` or system prompt) telling the bot it can generate images and when to use the tool.
+
+The rest is automatic: the runtime adapter extracts the image blocks, deduplicates them, and the Discord layer attaches them to the reply.

package/.context/tasks.md

@@ -0,0 +1,71 @@
+# tasks.md — Task Tracking
+
+Tasks are backed by an in-process `TaskStore` and synced to Discord forum threads.
+
+Ground-zero post-hard-cut refactor tracker: `docs/tasks-ground-zero-post-hard-cut-plan.md`
+Ground-zero task architecture refactor status: COMPLETE (FROZEN), verified on 2026-02-21.
+
+## Data Model
+
+Canonical type: `TaskData` in `src/tasks/types.ts`.
+
+Statuses: `open` | `in_progress` | `blocked` | `closed`
+
+## Task Store
+
+Implementation: `src/tasks/store.ts`
+
+Architecture contract: `src/tasks/architecture-contract.ts`
+Mutation entrypoint service: `src/tasks/service.ts`
+
+- Synchronous in-memory writes
+- Event emission on mutations (`created`, `updated`, `closed`, `labeled`)
+- Optional JSONL persistence (`tasks.jsonl`)
+
+## Discord Sync
+
+Canonical runtime sync implementation lives in `src/tasks/*`:
+
+- `src/tasks/task-sync-engine.ts`
+- `src/tasks/task-sync-pipeline.ts`
+- `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`
+- `src/tasks/thread-cache.ts`
+- `src/tasks/forum-guard.ts`
+
+Legacy runtime compatibility shims under `src/beads/` have been removed.
+
+Primary action trigger is `taskSync` via `src/tasks/task-action-executor.ts`.
+
+## Auto-Tagging
+
+Auto-tagging runs through `src/tasks/auto-tag.ts` and is controlled by the tasks env surface:
+
+- `DISCOCLAW_TASKS_AUTO_TAG`
+- `DISCOCLAW_TASKS_AUTO_TAG_MODEL`
+
+## Config Surface
+
+Primary names:
+
+- `DISCOCLAW_TASKS_ENABLED`
+- `DISCOCLAW_TASKS_FORUM`
+- `DISCOCLAW_TASKS_CWD`
+- `DISCOCLAW_TASKS_TAG_MAP`
+- `DISCOCLAW_TASKS_MENTION_USER`
+- `DISCOCLAW_TASKS_SIDEBAR`
+- `DISCOCLAW_TASKS_AUTO_TAG`
+- `DISCOCLAW_TASKS_AUTO_TAG_MODEL`
+- `DISCOCLAW_TASKS_SYNC_SKIP_PHASE5`
+- `DISCOCLAW_TASKS_PREFIX`

package/.context/tools.md

@@ -0,0 +1,75 @@
+# tools.md — Tool Capabilities
+
+Canonical reference for tools available to the discoclaw agent.
+`agent-browser` is optional — it requires a separate `npm install -g @anthropic/agent-browser` and is not bundled with discoclaw.
+
+## WebFetch / Browser Escalation Ladder
+
+Use the lightest tool that works. Escalate only when a lighter level fails.
+
+1. **WebFetch (read-only)** — Built-in. Fetches raw page content. No JS rendering, no interaction. Try this first for any URL.
+2. **Playwright headless** — `agent-browser` launches a fresh, isolated browser with no saved state. Good for JS-rendered pages, simple form fills, screenshots. No extensions, no cookies from real sessions.
+3. **Playwright headed** — Same as above but with a visible browser window. Useful for debugging or when a site blocks headless user agents.
+4. **CDP headless (connect)** — Connects to an already-running Chrome instance via Chrome DevTools Protocol. Persistent state: logged-in sessions, cookies, extensions. Use when Playwright can't get past auth walls or bot detection.
+5. **CDP headed (connect)** — Same as CDP headless but with a visible window. Use for initial login flows where you need to watch what's happening, then switch to CDP headless for ongoing automation.
+
+Key distinction: Playwright = fresh/isolated (no persistent state). CDP = persistent (real browser session with real cookies and extensions).
+
+## agent-browser Commands
+
+These are `agent-browser`-specific commands, not generic browser automation.
+
+| Command | Purpose |
+|---------|---------|
+| `navigate` | Go to a URL |
+| `snapshot` | Get an accessibility snapshot of the current page |
+| `interact` | Click, fill, select, check/uncheck elements |
+| `keyboard` | Type text, press keys, keyboard shortcuts |
+| `scroll` | Scroll the page or a specific element |
+| `read` | Extract text content from elements |
+| `wait` | Wait for elements, navigation, or a timeout |
+| `capture` | Take a screenshot of the page or an element |
+
+## Playwright Modes
+
+- **Headless (default):** No visible browser window. Faster, works on servers without a display.
+- **Headed:** Visible browser window. Requires a display (or Xvfb). Use when debugging or when headless is detected/blocked.
+
+## CDP Connect
+
+Use CDP when you need persistent browser state that Playwright can't provide.
+
+**When to use:**
+- Auth walls that require a real logged-in session
+- Bot detection that blocks Playwright's browser fingerprint
+- Sites that require specific extensions
+- Reusing an existing session (e.g., already logged into a service)
+
+**Setup — headed (for initial login):**
+
+Launch Chrome with remote debugging enabled. The binary name varies by platform (`google-chrome`, `chromium`, `chrome`, `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`, etc.).
+
+```bash
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-cdp-profile
+```
+
+Use a dedicated profile directory (`--user-data-dir`) to avoid clobbering your daily browser profile.
+
+**Setup — headless (for automation after login):**
+
+```bash
+google-chrome --headless --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-cdp-profile
+```
+
+**Workflow:**
+1. Launch Chrome headed with `--remote-debugging-port=9222`
+2. Log in manually or let the agent navigate the login flow
+3. Verify the connection: `agent-browser` connects to `http://localhost:9222`
+4. For ongoing automation, relaunch headless with the same `--user-data-dir`
+5. Shut down Chrome when done — don't leave debug ports open
+
+## Security Guardrails
+
+- **CDP is ask-first.** Never connect to a real browser session without explicit user consent. CDP exposes the user's live cookies, passwords, and session tokens.
+- **No browsing internal networks.** Don't navigate to `localhost`, `127.0.0.1`, `::1`, or RFC 1918 addresses (`10.*`, `172.16-31.*`, `192.168.*`) — except the CDP connect port itself (`localhost:9222`).
+- **No saving auth state to tracked locations.** Cookies, tokens, screenshots with sensitive data, and browser profiles must not be saved anywhere that gets committed or pushed. Use `/tmp/` or the workspace's gitignored directories.

package/.env.example

@@ -0,0 +1,88 @@
+# ============================================================
+# Discoclaw — Quick Start Configuration
+# ============================================================
+# Copy this file to .env and fill in the REQUIRED values.
+# Primary guided setup: run `discoclaw init` (global install).
+# From source: run `pnpm setup` for guided interactive configuration.
+# For all ~90 options, see .env.example.full
+# ============================================================
+
+# ----------------------------------------------------------
+# REQUIRED — the bot won't start without these
+# ----------------------------------------------------------
+
+# Your Discord bot token (from https://discord.com/developers/applications)
+# Important: Enable Message Content Intent in Developer Portal
+# (Bot → Privileged Gateway Intents) or the bot receives empty messages.
+DISCORD_TOKEN=
+
+# Comma-separated Discord user IDs allowed to talk to the bot.
+# Empty = nobody can use it (fail-closed).
+DISCORD_ALLOW_USER_IDS=
+
+# Tasks forum channel ID (required when DISCOCLAW_TASKS_ENABLED=1; default on).
+DISCOCLAW_TASKS_FORUM=
+
+# Automations forum channel ID (cron subsystem; required when DISCOCLAW_CRON_ENABLED=1; default on).
+DISCOCLAW_CRON_FORUM=
+
+# ----------------------------------------------------------
+# CORE — most users will want to review these
+# ----------------------------------------------------------
+
+# Guild (server) ID — used for task sync and system channel bootstrap.
+DISCORD_GUILD_ID=
+
+# Where the Claude CLI runs (its working directory).
+# Default: ./workspace (or $DISCOCLAW_DATA_DIR/workspace if DATA_DIR is set)
+#WORKSPACE_CWD=
+
+# Primary runtime adapter: claude | gemini | codex | openai | openrouter
+# Notes:
+# - openai requires OPENAI_API_KEY
+# - claude requires a working Claude CLI
+# - gemini requires the Gemini CLI (GEMINI_BIN)
+#PRIMARY_RUNTIME=claude
+# If PRIMARY_RUNTIME=codex and you want full-access mode (no approvals/sandbox):
+#CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1
+# Optional: isolate Codex state/sessions from ~/.codex (helps avoid stale rollout DB issues):
+#CODEX_HOME=/absolute/path/to/.codex-home-discoclaw
+# Disable Codex session persistence/resume (workaround for session DB issues):
+#CODEX_DISABLE_SESSIONS=1
+
+# Model tier: fast | capable (provider-agnostic).
+# Concrete model names (e.g. opus, sonnet, gpt-4o) are still accepted as passthrough.
+#RUNTIME_MODEL=capable
+
+# Output format for the Claude CLI. stream-json gives smoother streaming.
+#CLAUDE_OUTPUT_FORMAT=stream-json
+
+# Allow Claude to run without permission prompts. This is what makes
+# headless/Discord operation possible — the Discord allowlist above
+# is the security boundary instead.
+#CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1
+
+# Gemini CLI adapter
+# Path to the Gemini CLI binary (default: gemini).
+#GEMINI_BIN=gemini
+# Default model for the Gemini CLI adapter.
+#GEMINI_MODEL=gemini-2.5-pro
+
+# --- OpenRouter adapter ---
+#OPENROUTER_API_KEY=
+#OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+#OPENROUTER_MODEL=anthropic/claude-sonnet-4
+
+# Log level: trace | debug | info | warn | error | fatal
+#LOG_LEVEL=info
+
+# Override the default platform-detected restart command used by !restart and
+# !update apply. Useful for custom setups (e.g. Docker, non-standard service
+# managers, or running under a different user). If unset, the command is
+# auto-selected: systemctl --user on Linux, launchctl on macOS.
+#DC_RESTART_CMD=
+
+# ----------------------------------------------------------
+# For all ~90 options (subsystems, actions, memory, identity,
+# observability, advanced/debug), see .env.example.full
+# ----------------------------------------------------------