discoclaw 0.1.4 → 0.1.8

package/.context/discord.md

@@ -85,11 +85,13 @@ Each action category has its own flag (only active when the master switch is `1`
 | `DISCOCLAW_DISCORD_ACTIONS_PLAN` | `1` | planList, planShow, planApprove, planClose, planCreate, planRun |
 | `DISCOCLAW_DISCORD_ACTIONS_MEMORY` | `1` | memoryRemember, memoryForget, memoryShow |
 | `DISCOCLAW_DISCORD_ACTIONS_DEFER` | `1` | defer |
+| `DISCOCLAW_DISCORD_ACTIONS_IMAGEGEN` | `0` | generateImage |
 | _(config — always on)_ | — | modelSet, modelShow |
 
 Notes:
 - `reactionPrompt` is gated by the MESSAGING flag — it is registered via `REACTION_PROMPT_ACTION_TYPES` only when `flags.messaging` is true (`src/discord/actions.ts:113`).
 - Config actions (`modelSet`, `modelShow`) have no separate env flag. They are always enabled when the master switch is on, hardcoded in `src/index.ts`.
+- `generateImage` supports two providers: **OpenAI** (models: `dall-e-3`, `gpt-image-1`) and **Gemini** (models: `imagen-4.0-generate-001`, `imagen-4.0-fast-generate-001`, `imagen-4.0-ultra-generate-001`). Provider is auto-detected from the model prefix (`dall-e-*`/`gpt-image-*` → openai, `imagen-*` → gemini) or set explicitly via the `provider` field. OpenAI provider uses `OPENAI_API_KEY` (required) and optional `OPENAI_BASE_URL`. Gemini provider uses `IMAGEGEN_GEMINI_API_KEY`. At least one key must be set when `DISCOCLAW_DISCORD_ACTIONS_IMAGEGEN=1`. Default model is auto-detected: if only `IMAGEGEN_GEMINI_API_KEY` is set, defaults to `imagen-4.0-generate-001`; otherwise defaults to `dall-e-3`. Override with `IMAGEGEN_DEFAULT_MODEL`.
 
 Auto-follow-up: When query actions (channelList, channelInfo, threadListArchived, forumTagList, readMessages, fetchMessage, listPins, memberInfo, roleInfo, searchMessages, eventList, taskList, taskShow, cronList, cronShow, planList, planShow, memoryShow, modelShow, forgeStatus) 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.
 

package/.context/pa.md

@@ -14,7 +14,7 @@ For architecture details, see `.context/architecture.md`.
 | `SOUL.md` | Core personality and values | Every prompt |
 | `IDENTITY.md` | Name and vibe | Every prompt |
 | `USER.md` | Who you're helping | Every prompt |
-| `AGENTS.md` | Your personal rules and conventions | Scaffolded on setup; accessible via Read tool |
+| `AGENTS.md` | Your personal rules and conventions | Every prompt |
 | `TOOLS.md` | Available tools and integrations | Every prompt |
 | `HEARTBEAT.md` | Periodic self-check template | By cron |
 | `MEMORY.md` | Curated long-term memory | DM prompts |

package/.context/runtime.md

@@ -194,7 +194,7 @@ Both require `CLAUDE_OUTPUT_FORMAT=stream-json` for structured events.
 
 **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.
+**Append system prompt:** When set, workspace PA files (SOUL.md, IDENTITY.md, USER.md, AGENTS.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.

package/.env.example

@@ -20,11 +20,17 @@ DISCORD_TOKEN=
 # 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=
+# ----------------------------------------------------------
+# AUTO-DETECTED — written by the bot on first connect; only override if needed
+# ----------------------------------------------------------
+
+# Tasks forum channel ID. Auto-created by the bot on first guild connect and
+# persisted to system-scaffold.json. Only set this to override the auto-created channel.
+#DISCOCLAW_TASKS_FORUM=
 
-# Automations forum channel ID (cron subsystem; required when DISCOCLAW_CRON_ENABLED=1; default on).
-DISCOCLAW_CRON_FORUM=
+# Automations (cron) forum channel ID. Auto-created by the bot on first guild
+# connect and persisted to system-scaffold.json. Only set this to override the auto-created channel.
+#DISCOCLAW_CRON_FORUM=
 
 # ----------------------------------------------------------
 # CORE — most users will want to review these

package/.env.example.full

@@ -20,11 +20,17 @@ DISCORD_TOKEN=
 # 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=
+# ----------------------------------------------------------
+# AUTO-DETECTED — written by the bot on first connect; only override if needed
+# ----------------------------------------------------------
 
-# Automations forum channel ID (cron subsystem; required when DISCOCLAW_CRON_ENABLED=1; default on).
-DISCOCLAW_CRON_FORUM=
+# Tasks forum channel ID. Auto-created by the bot on first guild connect and
+# persisted to system-scaffold.json. Only set this to override the auto-created channel.
+#DISCOCLAW_TASKS_FORUM=
+
+# Automations (cron) forum channel ID. Auto-created by the bot on first guild
+# connect and persisted to system-scaffold.json. Only set this to override the auto-created channel.
+#DISCOCLAW_CRON_FORUM=
 
 # ----------------------------------------------------------
 # CORE — most users will want to review these
@@ -52,6 +58,28 @@ DISCOCLAW_CRON_FORUM=
 # Individual overrides (DISCOCLAW_SUMMARY_MODEL, etc.) still win when set.
 #DISCOCLAW_FAST_MODEL=fast
 
+# --- Tier model overrides ---
+# Override the concrete model resolved for any runtime × tier combination.
+# Format: DISCOCLAW_TIER_<RUNTIME>_<FAST|CAPABLE>=<model>
+# Unset = use the built-in default shown in the comments.
+# Concrete model names (e.g. sonnet, gpt-4o-mini) are passed through unchanged.
+#
+# Claude Code adapter (default: fast=haiku, capable=opus):
+#DISCOCLAW_TIER_CLAUDE_CODE_FAST=haiku
+#DISCOCLAW_TIER_CLAUDE_CODE_CAPABLE=opus
+#
+# Gemini CLI adapter (default: fast=gemini-2.5-flash, capable=gemini-2.5-pro):
+#DISCOCLAW_TIER_GEMINI_FAST=gemini-2.5-flash
+#DISCOCLAW_TIER_GEMINI_CAPABLE=gemini-2.5-pro
+#
+# OpenAI-compatible adapter (default: adapter-default for both tiers):
+#DISCOCLAW_TIER_OPENAI_FAST=gpt-4o-mini
+#DISCOCLAW_TIER_OPENAI_CAPABLE=gpt-4o
+#
+# Codex CLI adapter (default: adapter-default for both tiers):
+#DISCOCLAW_TIER_CODEX_FAST=
+#DISCOCLAW_TIER_CODEX_CAPABLE=
+
 # Output format for the Claude CLI. stream-json gives smoother streaming.
 #CLAUDE_OUTPUT_FORMAT=stream-json
 
@@ -76,7 +104,7 @@ DISCOCLAW_CRON_FORUM=
 # ----------------------------------------------------------
 # Cron — forum-based scheduled tasks (enabled by default)
 # ----------------------------------------------------------
-# Forum channel ID is configured above in REQUIRED.
+# Forum channel ID is auto-created on first connect (see AUTO-DETECTED above).
 # Model tier for cron execution: fast | capable (concrete names accepted as passthrough).
 #DISCOCLAW_CRON_MODEL=fast
 # Enable cron Discord actions (CRUD via Discord action blocks).
@@ -97,7 +125,7 @@ DISCOCLAW_CRON_FORUM=
 # ----------------------------------------------------------
 # Tasks — task tracking (enabled by default)
 # ----------------------------------------------------------
-# Forum channel ID is configured above in REQUIRED.
+# Forum channel ID is auto-created on first connect (see AUTO-DETECTED above).
 # Guild ID — used for task sync bootstrap and system channel bootstrap.
 # Also used for System channel bootstrap when the bot is in multiple servers.
 DISCORD_GUILD_ID=
@@ -308,12 +336,19 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 #DISCOCLAW_SESSION_SCANNING=1
 # Parse tool-use events during streaming for better progress reporting and stall suppression.
 #DISCOCLAW_TOOL_AWARE_STREAMING=1
-# Stream stall detection: kill one-shot process if no stdout/stderr for this long (ms). 0 = disabled.
+# Stream stall detection: kill one-shot process if no stdout/stderr for this long (ms). 0 = disabled. (default: 600000)
 #DISCOCLAW_STREAM_STALL_TIMEOUT_MS=120000
 # Progress stall timeout: alert after this many ms with no progress event (ms). 0 = disabled.
 #DISCOCLAW_PROGRESS_STALL_TIMEOUT_MS=300000
-# Stream stall warning: show user-visible warning in Discord after this many ms of no events. 0 = disabled.
+# Stream stall warning: show user-visible warning in Discord after this many ms of no events. 0 = disabled. (default: 300000)
 #DISCOCLAW_STREAM_STALL_WARNING_MS=60000
+# Post a brief "Done (Xm Ys)" completion notice as a new message after long-running runs finish.
+# Discord's unread indicator fires on new messages but not edits, so users who left the channel
+# while the bot was working will see an unread badge. Set to 0 to disable.
+#DISCOCLAW_COMPLETION_NOTIFY=1
+# Minimum elapsed time (ms) before a completion notice is sent. Runs shorter than this are
+# considered "fast" and don't need a notification. Default: 30000 (30 seconds).
+#DISCOCLAW_COMPLETION_NOTIFY_THRESHOLD_MS=30000
 
 # ----------------------------------------------------------
 # Plan & Forge — AI-assisted planning and implementation
@@ -405,3 +440,21 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # Chromium path for agent-browser. Only needed if the bundled browser
 # (from `agent-browser install`) doesn't work.
 #AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+
+# ----------------------------------------------------------
+# Image generation
+# ----------------------------------------------------------
+# Master switch — enables the imagegen Discord action category (default: off).
+# When enabled, the AI can generate images via action blocks using OpenAI or Gemini Imagen.
+DISCOCLAW_DISCORD_ACTIONS_IMAGEGEN=0
+# API key for Gemini Imagen models (imagen-4.0-generate-001 and similar).
+# Leave unset to use OpenAI only.
+#IMAGEGEN_GEMINI_API_KEY=
+# Override the default image generation model. If unset, auto-detected:
+# only IMAGEGEN_GEMINI_API_KEY set → imagen-4.0-generate-001; otherwise → dall-e-3.
+# OpenAI models: dall-e-3, gpt-image-1
+# Gemini models: imagen-4.0-generate-001, imagen-4.0-fast-generate-001, imagen-4.0-ultra-generate-001
+#IMAGEGEN_DEFAULT_MODEL=
+# Note: OpenAI image generation reuses OPENAI_API_KEY (documented above in the
+# OpenAI-compatible HTTP adapter section). When DISCOCLAW_DISCORD_ACTIONS_IMAGEGEN=1,
+# at least one of OPENAI_API_KEY or IMAGEGEN_GEMINI_API_KEY must be set.

package/README.md

@@ -4,7 +4,7 @@
 
 # DiscoClaw
 
-A personal AI orchestrator that turns Discord into a persistent workspace — built on three pillars: **Memory**, **Tasks**, and **Crons**.
+A personal AI orchestrator that turns Discord into a persistent workspace — built on three pillars: **Memory**, **Tasks**, and **Automations**.
 
 DiscoClaw is an orchestrator: it coordinates between a user interface (Discord), one or more AI runtimes (Claude Code, OpenAI, Codex), and local system resources — managing conversation state, task routing, scheduling, and tool access. The intelligence is rented; the coordination is owned.
 
@@ -39,11 +39,11 @@ A lightweight in-process task store that syncs bidirectionally with Discord foru
 - **Create from either side** — Ask your assistant in chat or use task commands
 - **Bidirectional sync** — Status, priority, and tags stay in sync between the task store and Discord threads
 - **Status emoji and auto-tagging** — Thread names show live status at a glance
-- **Discord actions** — Your assistant manages tasks through conversation: create channels, send messages, search history, run polls, and more
+- **Discord actions** — Your assistant manages tasks through conversation: create channels, send messages, search history, run polls, and more (see [docs/discord-actions.md](docs/discord-actions.md))
 
 **Why Discord fits:** forum threads = task cards, archive = done, thread names show live status.
 
-## Crons — the bot acts on its own
+## Automations — the bot acts on its own
 
 Recurring tasks defined as forum threads in plain language — no crontab, no separate scheduler UI.
 
@@ -56,7 +56,7 @@ Recurring tasks defined as forum threads in plain language — no crontab, no se
 
 ## How it works
 
-DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
+DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with Gemini, OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
 
 1. Checks the user allowlist (fail-closed — empty list means respond to nobody)
 2. Assembles context: per-channel rules, conversation history, rolling summary, and durable memory
@@ -93,10 +93,11 @@ Author one recipe file for an integration, share it, then let another user's Dis
 - **Node.js >=20** — check with `node --version`
 - One primary runtime:
   - **Claude CLI** on your `PATH` — check with `claude --version` (see [Claude CLI docs](https://docs.anthropic.com/en/docs/claude-code) to install), or
+  - **Gemini CLI** on your `PATH` — check with `gemini --version`, or
   - **Codex CLI** on your `PATH` — check with `codex --version`, or
   - **OpenAI-compatible API key** via `OPENAI_API_KEY`, or
   - **OpenRouter API key** via `OPENROUTER_API_KEY` (access to many providers)
-- Runtime-specific access for your chosen provider (Anthropic plan/API credits for Claude, OpenAI access for Codex/OpenAI models)
+- Runtime-specific access for your chosen provider (Anthropic plan/API credits for Claude, Google account for Gemini, OpenAI access for Codex/OpenAI models)
 
 **Contributors (from source):**
 - Everything above, plus **pnpm** — enable via Corepack (`corepack enable`) or install separately
@@ -158,6 +159,14 @@ pnpm dev
 
 **Global install:**
 
+If DiscoClaw is running, update from Discord:
+
+```
+!update apply
+```
+
+Or from the command line:
+
 ```bash
 npm update -g discoclaw
 discoclaw install-daemon   # re-register the service after updating

package/dist/cli/index.js

@@ -16,6 +16,49 @@ switch (command) {
     case 'install-daemon':
         await runDaemonInstaller();
         break;
+    case 'update': {
+        const subcommand = process.argv[3];
+        const { isNpmManaged, getLocalVersion, getLatestNpmVersion, npmGlobalUpgrade } = await import('../npm-managed.js');
+        const npmMode = await isNpmManaged();
+        if (subcommand === 'apply') {
+            if (!npmMode) {
+                console.error('This instance is not npm-managed. Use the git-based workflow to update.');
+                process.exit(1);
+            }
+            console.log('Installing latest version from npm...');
+            const result = await npmGlobalUpgrade();
+            if (result.exitCode !== 0) {
+                const detail = (result.stderr || result.stdout).trim().slice(0, 500);
+                console.error(`npm install -g discoclaw failed:\n${detail}`);
+                process.exit(1);
+            }
+            console.log('Update complete. Restart discoclaw to run the new version.');
+        }
+        else if (subcommand === undefined) {
+            if (!npmMode) {
+                console.log('This instance is not npm-managed; update checking is not supported in this mode.');
+                break;
+            }
+            const installed = getLocalVersion();
+            const latest = await getLatestNpmVersion();
+            if (latest === null) {
+                console.error('Failed to fetch latest version from npm registry.');
+                process.exit(1);
+            }
+            if (installed === latest) {
+                console.log(`Already on latest version (${installed}).`);
+            }
+            else {
+                console.log(`Update available: ${installed} → ${latest}. Run \`discoclaw update apply\` to upgrade.`);
+            }
+        }
+        else {
+            console.error(`Unknown update subcommand: ${subcommand}\n`);
+            printHelp(version);
+            process.exit(1);
+        }
+        break;
+    }
     case '--version':
     case '-v':
         console.log(version);
@@ -38,6 +81,8 @@ function printHelp(ver) {
         `  install-daemon [--service-name <name>]  Register discoclaw as a persistent background service\n` +
         `                                          Use --service-name to run multiple instances side-by-side.\n` +
         `                                          Defaults to "discoclaw".\n` +
+        `  update                                Check for available updates (npm-managed installs only)\n` +
+        `  update apply                          Install the latest version from npm and print restart reminder\n` +
         `\nOptions:\n` +
         `  -v, --version   Print version\n` +
         `  -h, --help      Print this help\n`);

package/dist/cli/init-wizard.js

@@ -35,8 +35,9 @@ export function buildEnvContent(vals, now = new Date()) {
     lines.push('# REQUIRED');
     lines.push(`DISCORD_TOKEN=${vals.DISCORD_TOKEN ?? ''}`);
     lines.push(`DISCORD_ALLOW_USER_IDS=${vals.DISCORD_ALLOW_USER_IDS ?? ''}`);
-    lines.push(`DISCOCLAW_TASKS_FORUM=${vals.DISCOCLAW_TASKS_FORUM ?? ''}`);
-    lines.push(`DISCOCLAW_CRON_FORUM=${vals.DISCOCLAW_CRON_FORUM ?? ''}`);
+    if (vals.DISCOCLAW_DATA_DIR) {
+        lines.push(`DISCOCLAW_DATA_DIR=${vals.DISCOCLAW_DATA_DIR}`);
+    }
     lines.push('');
     if (vals.PRIMARY_RUNTIME) {
         const providerSpecificKeys = [
@@ -75,6 +76,16 @@ export function buildEnvContent(vals, now = new Date()) {
         }
         lines.push('');
     }
+    const autoDetectedKeys = ['DISCOCLAW_TASKS_FORUM', 'DISCOCLAW_CRON_FORUM'];
+    const hasAutoDetected = autoDetectedKeys.some((k) => vals[k]);
+    if (hasAutoDetected) {
+        lines.push('# AUTO-DETECTED');
+        for (const k of autoDetectedKeys) {
+            if (vals[k])
+                lines.push(`${k}=${vals[k]}`);
+        }
+        lines.push('');
+    }
     lines.push('# For all options, see .env.example.full');
     lines.push('');
     return lines.join('\n');
@@ -94,8 +105,7 @@ export async function runInitWizard() {
         console.error('discoclaw init requires an interactive terminal.\n');
         process.exit(1);
     }
-    const cwd = process.cwd();
-    const envPath = path.join(cwd, '.env');
+    let cwd = process.cwd();
     let rl = null;
     let canceled = false;
     let completed = false;
@@ -152,8 +162,15 @@ export async function runInitWizard() {
         }
     }
     // ── Welcome ──────────────────────────────────────────────────────────────
-    console.log(`\nDiscoclaw Init\n==============\n` +
-        `This wizard creates a .env file and workspace/ directory in:\n  ${cwd}\n`);
+    console.log(`\nDiscoclaw Init\n==============`);
+    const installDirInput = await ask(`Install directory [${cwd}]: `);
+    if (installDirInput.trim()) {
+        cwd = path.resolve(installDirInput.trim());
+        if (!fs.existsSync(cwd)) {
+            fs.mkdirSync(cwd, { recursive: true });
+        }
+    }
+    console.log(`This wizard creates a .env file and workspace/ directory in:\n  ${cwd}\n`);
     // ── Discord bot guidance ──────────────────────────────────────────────────
     console.log(`Discord Bot Setup\n-----------------\n` +
         `If you haven't created a Discord bot yet, follow these steps:\n\n` +
@@ -163,11 +180,21 @@ export async function runInitWizard() {
         `  4. Enable "Message Content Intent" under Privileged Gateway Intents.\n` +
         `  5. Click "Reset Token", copy it — you'll enter it below.\n` +
         `  6. Invite your bot: Bot tab → OAuth2 → URL Generator\n` +
-        `     Scopes: bot   Permissions: Send Messages, Read Message History\n` +
+        `     Scopes: bot   Permissions: View Channels, Send Messages,\n` +
+        `     Read Message History, Manage Channels, Manage Threads,\n` +
+        `     Send Messages in Threads\n` +
         `     Open the generated URL and select your server.\n\n` +
         `Already have a bot? Just press Enter.\n`);
     await ask('Press Enter to continue... ');
+    // ── Data directory ────────────────────────────────────────────────────────
+    const defaultDataDir = path.join(cwd, 'data');
+    const dataDirInput = await ask(`Data directory [${defaultDataDir}]: `);
+    const dataDir = dataDirInput.trim() || defaultDataDir;
+    // ── Collected values ──────────────────────────────────────────────────────
+    const values = {};
+    values.DISCOCLAW_DATA_DIR = dataDir;
     // ── Check existing .env ───────────────────────────────────────────────────
+    const envPath = path.join(cwd, '.env');
     if (fs.existsSync(envPath)) {
         const existing = fs.readFileSync(envPath, 'utf8');
         const tokenMatch = existing.match(/^DISCORD_TOKEN=(.*)$/m);
@@ -200,13 +227,23 @@ export async function runInitWizard() {
         const backupPath = path.join(cwd, bkName);
         fs.copyFileSync(envPath, backupPath);
         console.log(`  Backed up to ${bkName}\n`);
+        // Carry forward auto-detected forum channel IDs so explicit overrides survive re-runs
+        const tasksMatch = existing.match(/^DISCOCLAW_TASKS_FORUM=(.*)$/m);
+        const cronMatch = existing.match(/^DISCOCLAW_CRON_FORUM=(.*)$/m);
+        if (tasksMatch?.[1]?.trim())
+            values.DISCOCLAW_TASKS_FORUM = tasksMatch[1].trim();
+        if (cronMatch?.[1]?.trim())
+            values.DISCOCLAW_CRON_FORUM = cronMatch[1].trim();
     }
     // ── Required values ───────────────────────────────────────────────────────
-    const values = {};
     values.DISCORD_TOKEN = await askValidated('Discord bot token: ', (val) => {
         const r = validateDiscordToken(val);
         return r.valid ? null : (r.reason ?? 'Invalid token format');
     });
+    console.log(`\nDiscord User ID\n` +
+        `  A Discord user ID is an 18-19 digit number uniquely identifying your account.\n` +
+        `  To find yours: Settings → Advanced → enable Developer Mode,\n` +
+        `  then right-click your username anywhere and choose "Copy User ID".\n`);
     values.DISCORD_ALLOW_USER_IDS = await askValidated('Allowed user IDs (comma-separated): ', (val) => {
         if (!val.trim())
             return 'At least one user ID is required';
@@ -217,8 +254,7 @@ export async function runInitWizard() {
             return 'At least one valid snowflake ID is required';
         return null;
     });
-    values.DISCOCLAW_TASKS_FORUM = await askValidated('Tasks forum channel ID (required): ', (val) => (validateSnowflake(val) ? null : 'Must be a 17-20 digit number'));
-    values.DISCOCLAW_CRON_FORUM = await askValidated('Automations forum channel ID (required): ', (val) => (validateSnowflake(val) ? null : 'Must be a 17-20 digit number'));
+    // (DISCOCLAW_TASKS_FORUM and DISCOCLAW_CRON_FORUM are auto-created on first connect)
     // ── Runtime detection ─────────────────────────────────────────────────────
     const detected = [];
     if (which('claude'))
@@ -349,6 +385,7 @@ export async function runInitWizard() {
     }
     console.log('Configuration complete!\n');
     console.log('Next steps:');
+    console.log('  Note: The bot will auto-create its forum channels on first connect.');
     if (values.PRIMARY_RUNTIME === 'claude') {
         console.log(`  ${daemonHint}`);
     }

package/dist/cli/init-wizard.test.js

@@ -55,6 +55,16 @@ describe('init wizard helpers', () => {
         expect(content).toContain('DISCORD_GUILD_ID=1000000000000000004');
         expect(content).toContain('# OPTIONAL');
         expect(content).toContain('DISCOCLAW_DISCORD_ACTIONS=1');
+        // Forum IDs are auto-detected, not in REQUIRED
+        expect(content).toContain('# AUTO-DETECTED');
+        expect(content).toContain('DISCOCLAW_TASKS_FORUM=1000000000000000002');
+        expect(content).toContain('DISCOCLAW_CRON_FORUM=1000000000000000003');
+        // Forum IDs must not appear before the AUTO-DETECTED header
+        const requiredIdx = content.indexOf('# REQUIRED');
+        const autoDetectedIdx = content.indexOf('# AUTO-DETECTED');
+        const tasksIdx = content.indexOf('DISCOCLAW_TASKS_FORUM=');
+        expect(tasksIdx).toBeGreaterThan(autoDetectedIdx);
+        expect(autoDetectedIdx).toBeGreaterThan(requiredIdx);
     });
     it('selects provider defaults in expected precedence order', () => {
         expect(selectDefaultProvider(['codex'])).toBe('4');
@@ -82,6 +92,32 @@ describe('init wizard helpers', () => {
         expect(content).toContain('OPENROUTER_API_KEY=sk-or-test-key');
         expect(content).toContain('OPENROUTER_BASE_URL=https://openrouter.ai/api/v1');
         expect(content).toContain('OPENROUTER_MODEL=anthropic/claude-sonnet-4');
+        expect(content).toContain('# AUTO-DETECTED');
+        expect(content).toContain('DISCOCLAW_TASKS_FORUM=1000000000000000002');
+        expect(content).toContain('DISCOCLAW_CRON_FORUM=1000000000000000003');
+    });
+    it('writes DISCOCLAW_DATA_DIR in required section when provided', () => {
+        const content = buildEnvContent({
+            DISCORD_TOKEN: 'a.b.c',
+            DISCORD_ALLOW_USER_IDS: '1000000000000000001',
+            DISCOCLAW_DATA_DIR: '/home/user/discoclaw-data',
+        }, new Date('2026-02-23T00:00:00.000Z'));
+        expect(content).toContain('DISCOCLAW_DATA_DIR=/home/user/discoclaw-data');
+        // Must appear inside the REQUIRED section (before any PROVIDER or AUTO-DETECTED section)
+        const requiredIdx = content.indexOf('# REQUIRED');
+        const dataDirIdx = content.indexOf('DISCOCLAW_DATA_DIR=');
+        expect(dataDirIdx).toBeGreaterThan(requiredIdx);
+        // No AUTO-DETECTED section when no forum IDs are present
+        expect(content).not.toContain('# AUTO-DETECTED');
+    });
+    it('omits auto-detected section when no forum IDs are present', () => {
+        const content = buildEnvContent({
+            DISCORD_TOKEN: 'a.b.c',
+            DISCORD_ALLOW_USER_IDS: '1000000000000000001',
+        }, new Date('2026-02-23T00:00:00.000Z'));
+        expect(content).not.toContain('# AUTO-DETECTED');
+        expect(content).not.toContain('DISCOCLAW_TASKS_FORUM');
+        expect(content).not.toContain('DISCOCLAW_CRON_FORUM');
     });
 });
 describe('runInitWizard', () => {
@@ -117,12 +153,12 @@ describe('runInitWizard', () => {
         const previousCwd = process.cwd();
         const oldEnv = 'DISCORD_TOKEN=old.token.value\nDISCORD_ALLOW_USER_IDS=111111111111111111\n';
         const answers = [
+            '', // install directory (default)
             '', // Press Enter to continue
+            '', // data directory (default cwd/data)
             'y', // Overwrite existing .env
             'a.b.c', // DISCORD_TOKEN
             '1000000000000000001', // DISCORD_ALLOW_USER_IDS
-            '1000000000000000002', // DISCOCLAW_TASKS_FORUM
-            '1000000000000000003', // DISCOCLAW_CRON_FORUM
             '', // provider selection -> default (Claude)
             '', // enable skip permissions
             '', // enable stream-json
@@ -151,18 +187,19 @@ describe('runInitWizard', () => {
         expect(newEnv).toContain('PRIMARY_RUNTIME=claude');
         expect(newEnv).toContain('CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1');
         expect(newEnv).toContain('CLAUDE_OUTPUT_FORMAT=stream-json');
+        expect(newEnv).toContain(`DISCOCLAW_DATA_DIR=${path.join(tmpDir, 'data')}`);
         expect(ensureWorkspaceBootstrapFiles).toHaveBeenCalledWith(path.join(tmpDir, 'workspace'));
     });
     it('writes openrouter config when provider 5 is selected', async () => {
         const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discoclaw-init-test-'));
         const previousCwd = process.cwd();
         const answers = [
+            '', // install directory (default)
             '', // Press Enter to continue
+            '', // data directory (default cwd/data)
             // no existing .env
             'a.b.c', // DISCORD_TOKEN
             '1000000000000000001', // DISCORD_ALLOW_USER_IDS
-            '1000000000000000002', // DISCOCLAW_TASKS_FORUM
-            '1000000000000000003', // DISCOCLAW_CRON_FORUM
             '5', // provider selection -> OpenRouter
             'sk-or-test-key', // OPENROUTER_API_KEY
             '', // OPENROUTER_BASE_URL (optional, skip)
@@ -187,5 +224,133 @@ describe('runInitWizard', () => {
         expect(newEnv).toContain('PRIMARY_RUNTIME=openrouter');
         expect(newEnv).toContain('OPENROUTER_API_KEY=sk-or-test-key');
         expect(newEnv).toContain('OPENROUTER_MODEL=anthropic/claude-sonnet-4');
+        expect(newEnv).toContain(`DISCOCLAW_DATA_DIR=${path.join(tmpDir, 'data')}`);
+    });
+    it('always writes DISCOCLAW_DATA_DIR when a custom path is given', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discoclaw-init-test-'));
+        const previousCwd = process.cwd();
+        const customDataDir = path.join(tmpDir, 'my-data');
+        const answers = [
+            '', // install directory (default)
+            '', // Press Enter to continue
+            customDataDir, // data directory (custom path)
+            'a.b.c', // DISCORD_TOKEN
+            '1000000000000000001', // DISCORD_ALLOW_USER_IDS
+            '', // provider selection -> default (Claude)
+            '', // enable skip permissions
+            '', // enable stream-json
+            'n', // configure recommended settings
+            'n', // configure optional features
+        ];
+        process.chdir(tmpDir);
+        vi.mocked(createInterface).mockReturnValue(makeReadline(answers));
+        vi.mocked(execFileSync).mockImplementation(() => {
+            throw new Error('binary not found');
+        });
+        vi.mocked(ensureWorkspaceBootstrapFiles).mockResolvedValue([]);
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        try {
+            await runInitWizard();
+        }
+        finally {
+            process.chdir(previousCwd);
+        }
+        const newEnv = fs.readFileSync(path.join(tmpDir, '.env'), 'utf8');
+        expect(newEnv).toContain(`DISCOCLAW_DATA_DIR=${customDataDir}`);
+    });
+    it('carries forward DISCOCLAW_TASKS_FORUM and DISCOCLAW_CRON_FORUM from existing .env on overwrite', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discoclaw-init-test-'));
+        const previousCwd = process.cwd();
+        const oldEnv = [
+            'DISCORD_TOKEN=old.token.value',
+            'DISCORD_ALLOW_USER_IDS=111111111111111111',
+            'DISCOCLAW_TASKS_FORUM=9000000000000000001',
+            'DISCOCLAW_CRON_FORUM=9000000000000000002',
+        ].join('\n') + '\n';
+        const answers = [
+            '', // install directory (default)
+            '', // Press Enter to continue
+            '', // data directory (default cwd/data)
+            'y', // Overwrite existing .env
+            'a.b.c', // DISCORD_TOKEN
+            '1000000000000000001', // DISCORD_ALLOW_USER_IDS
+            '', // provider selection -> default (Claude)
+            '', // enable skip permissions
+            '', // enable stream-json
+            'n', // configure recommended settings
+            'n', // configure optional features
+        ];
+        fs.writeFileSync(path.join(tmpDir, '.env'), oldEnv, 'utf8');
+        process.chdir(tmpDir);
+        vi.mocked(createInterface).mockReturnValue(makeReadline(answers));
+        vi.mocked(execFileSync).mockImplementation(() => {
+            throw new Error('binary not found');
+        });
+        vi.mocked(ensureWorkspaceBootstrapFiles).mockResolvedValue([]);
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        try {
+            await runInitWizard();
+        }
+        finally {
+            process.chdir(previousCwd);
+        }
+        const newEnv = fs.readFileSync(path.join(tmpDir, '.env'), 'utf8');
+        expect(newEnv).toContain('# AUTO-DETECTED');
+        expect(newEnv).toContain('DISCOCLAW_TASKS_FORUM=9000000000000000001');
+        expect(newEnv).toContain('DISCOCLAW_CRON_FORUM=9000000000000000002');
+        // Must appear under AUTO-DETECTED, not REQUIRED
+        const autoDetectedIdx = newEnv.indexOf('# AUTO-DETECTED');
+        const tasksIdx = newEnv.indexOf('DISCOCLAW_TASKS_FORUM=');
+        expect(tasksIdx).toBeGreaterThan(autoDetectedIdx);
+    });
+    it('uses a custom install directory when a path is provided', async () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discoclaw-init-test-'));
+        const answers = [
+            tmpDir, // install directory (custom path)
+            '', // Press Enter to continue
+            '', // data directory (default)
+            'a.b.c', // DISCORD_TOKEN
+            '1000000000000000001', // DISCORD_ALLOW_USER_IDS
+            '', // provider selection -> default (Claude)
+            '', // enable skip permissions
+            '', // enable stream-json
+            'n', // configure recommended settings
+            'n', // configure optional features
+        ];
+        vi.mocked(createInterface).mockReturnValue(makeReadline(answers));
+        vi.mocked(execFileSync).mockImplementation(() => {
+            throw new Error('binary not found');
+        });
+        vi.mocked(ensureWorkspaceBootstrapFiles).mockResolvedValue([]);
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        await runInitWizard();
+        expect(fs.existsSync(path.join(tmpDir, '.env'))).toBe(true);
+        expect(ensureWorkspaceBootstrapFiles).toHaveBeenCalledWith(path.join(tmpDir, 'workspace'));
+    });
+    it('creates the install directory if it does not exist', async () => {
+        const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'discoclaw-init-test-'));
+        const newDir = path.join(baseDir, 'new-subdir');
+        const answers = [
+            newDir, // install directory (non-existent path)
+            '', // Press Enter to continue
+            '', // data directory (default)
+            'a.b.c', // DISCORD_TOKEN
+            '1000000000000000001', // DISCORD_ALLOW_USER_IDS
+            '', // provider selection -> default (Claude)
+            '', // enable skip permissions
+            '', // enable stream-json
+            'n', // configure recommended settings
+            'n', // configure optional features
+        ];
+        vi.mocked(createInterface).mockReturnValue(makeReadline(answers));
+        vi.mocked(execFileSync).mockImplementation(() => {
+            throw new Error('binary not found');
+        });
+        vi.mocked(ensureWorkspaceBootstrapFiles).mockResolvedValue([]);
+        vi.spyOn(console, 'log').mockImplementation(() => { });
+        await runInitWizard();
+        expect(fs.existsSync(newDir)).toBe(true);
+        expect(fs.existsSync(path.join(newDir, '.env'))).toBe(true);
+        expect(ensureWorkspaceBootstrapFiles).toHaveBeenCalledWith(path.join(newDir, 'workspace'));
     });
 });