kimaki 0.19.0 → 0.20.1

package/dist/session-handler/thread-session-runtime.js

@@ -190,23 +190,23 @@ function getTokenTotal(tokens) {
         tokens.cache.read +
         tokens.cache.write);
 }
+/**
+ * Built-in read-only tools that are hidden in default verbosity mode.
+ * Any tool NOT in this list is considered "essential" and shown,
+ * which means custom tools, MCP tools, and plugin tools are visible by default.
+ */
+const HIDDEN_READONLY_TOOLS = [
+    'read',
+    'glob',
+    'grep',
+    'describe-media',
+    'todoread',
+];
 /** Check if a tool part is "essential" (shown in text-and-essential-tools mode). */
 export function isEssentialToolName(toolName) {
-    const essentialTools = [
-        'edit',
-        'write',
-        'apply_patch',
-        'bash',
-        'webfetch',
-        'websearch',
-        'googlesearch',
-        'codesearch',
-        'task',
-        'todowrite',
-        'skill',
-    ];
-    // Also match any MCP tool that contains these names
-    return essentialTools.some((name) => {
+    // Hide known read-only built-in tools; show everything else
+    // (custom tools, MCP tools, plugin tools are visible by default)
+    return !HIDDEN_READONLY_TOOLS.some((name) => {
         return toolName === name || toolName.endsWith(`_${name}`);
     });
 }
@@ -2062,6 +2062,15 @@ export class ThreadSessionRuntime {
                 skippedBySessionGuard = true;
                 return;
             }
+            // Context-only messages (noReply) should not create a new session.
+            // If there is no existing session, silently skip.
+            if (input.noReply) {
+                const existingSessionId = this.state?.sessionId || await getThreadSession(this.thread.id) || undefined;
+                if (!existingSessionId) {
+                    logger.log(`[INGRESS] Skipping noReply message for thread ${this.threadId}: no existing session`);
+                    return;
+                }
+            }
             // Helper: stop typing and drain queued local messages on error.
             const cleanupOnError = async (errorMessage) => {
                 this.stopTyping();
@@ -2269,6 +2278,7 @@ export class ThreadSessionRuntime {
                 ...(resolvedAgent ? { agent: resolvedAgent } : {}),
                 ...(modelField ? { model: modelField } : {}),
                 ...variantField,
+                ...(input.noReply ? { noReply: true } : {}),
             };
             const promptResult = await getClient().session.promptAsync(request)
                 .catch((e) => new OpenCodeSdkError({ operation: 'session.promptAsync', cause: e }));
@@ -2284,7 +2294,10 @@ export class ThreadSessionRuntime {
                 return;
             }
             logger.log(`[INGRESS] promptAsync accepted by opencode queue sessionId=${session.id} threadId=${this.threadId}`);
-            this.markQueueDispatchBusy(session.id);
+            // noReply messages don't trigger the agent loop, so don't mark as busy
+            if (!input.noReply) {
+                this.markQueueDispatchBusy(session.id);
+            }
         });
         if (skippedBySessionGuard) {
             return { queued: false };
@@ -2426,9 +2439,17 @@ export class ThreadSessionRuntime {
                 // Route with the resolved mode through normal paths.
                 // Await the enqueue so session state (ensureSession, setThreadSession)
                 // is persisted before the next message's preprocessing reads it.
-                const enqueueResult = resolvedInput.mode === 'local-queue' || resolvedInput.command
-                    ? await this.enqueueViaLocalQueue(resolvedInput)
-                    : await this.submitViaOpencodeQueue(resolvedInput);
+                // noReply messages always go through the opencode path so the flag
+                // reaches promptAsync; local queue doesn't support noReply.
+                const enqueueResult = resolvedInput.noReply
+                    ? await this.submitViaOpencodeQueue({
+                        ...resolvedInput,
+                        mode: 'opencode',
+                        command: undefined,
+                    })
+                    : (resolvedInput.mode === 'local-queue' || resolvedInput.command)
+                        ? await this.enqueueViaLocalQueue(resolvedInput)
+                        : await this.submitViaOpencodeQueue(resolvedInput);
                 resolveOuter(enqueueResult);
             }
             catch (err) {

package/dist/store.js

@@ -14,6 +14,7 @@ export const store = createStore(() => ({
     allowedMentions: ['users'],
     allowAllUsers: false,
     permissionTimeoutMs: 10 * 60 * 1000,
+    useWorktrees: false,
     autoUpgradeEnabled: true,
     syncEnabled: true,
     discordBaseUrl: 'https://discord.com',

package/dist/system-message.js

@@ -279,10 +279,22 @@ The user is reading your messages from inside Discord, via kimaki.dev
 
 ## bash tool
 
-When calling the bash tool, always include a boolean field \`hasSideEffect\`.
-Set \`hasSideEffect: true\` for any command that writes files, modifies repo state, installs packages, changes config, runs scripts that mutate state, or triggers external effects.
-Set \`hasSideEffect: false\` for read-only commands (e.g. ls, tree, cat, rg, grep, git status, git diff, pwd, whoami, etc).
-This is required to distinguish essential bash calls from read-only ones in low-verbosity mode.
+When calling the bash tool, always include these extra fields alongside \`command\`:
+
+\`\`\`ts
+interface BashToolInput {
+  command: string
+  /** Short 5-10 word summary of what this command does */
+  description: string
+  /** true if the command writes files, modifies state, installs packages, or triggers external effects */
+  hasSideEffect: boolean
+  workdir?: string
+  timeout?: number
+}
+\`\`\`
+
+\`description\` is shown to the user in Discord as a summary of the bash call.
+\`hasSideEffect\` distinguishes essential bash calls from read-only ones in low-verbosity mode.
 
 Your current OpenCode session ID is: ${sessionId}${channelId ? `\nYour current Discord channel ID is: ${channelId}` : ''}${threadId ? `\nYour current Discord thread ID is: ${threadId}` : ''}${guildId ? `\nYour current Discord guild ID is: ${guildId}` : ''}
 

package/dist/system-message.test.js

@@ -34,10 +34,22 @@ describe('system-message', () => {
 
       ## bash tool
 
-      When calling the bash tool, always include a boolean field \`hasSideEffect\`.
-      Set \`hasSideEffect: true\` for any command that writes files, modifies repo state, installs packages, changes config, runs scripts that mutate state, or triggers external effects.
-      Set \`hasSideEffect: false\` for read-only commands (e.g. ls, tree, cat, rg, grep, git status, git diff, pwd, whoami, etc).
-      This is required to distinguish essential bash calls from read-only ones in low-verbosity mode.
+      When calling the bash tool, always include these extra fields alongside \`command\`:
+
+      \`\`\`ts
+      interface BashToolInput {
+        command: string
+        /** Short 5-10 word summary of what this command does */
+        description: string
+        /** true if the command writes files, modifies state, installs packages, or triggers external effects */
+        hasSideEffect: boolean
+        workdir?: string
+        timeout?: number
+      }
+      \`\`\`
+
+      \`description\` is shown to the user in Discord as a summary of the bash call.
+      \`hasSideEffect\` distinguishes essential bash calls from read-only ones in low-verbosity mode.
 
       Your current OpenCode session ID is: ses_123
       Your current Discord channel ID is: chan_123

package/package.json

@@ -2,7 +2,7 @@
   "name": "kimaki",
   "module": "index.ts",
   "type": "module",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "repository": "https://github.com/remorses/kimaki",
   "bin": "bin.js",
   "files": [
@@ -25,8 +25,8 @@
     "tsx": "^4.20.5",
     "undici": "^8.0.2",
     "discord-digital-twin": "^0.1.0",
-    "opencode-cached-provider": "^0.0.1",
     "opencode-deterministic-provider": "^0.0.1",
+    "opencode-cached-provider": "^0.0.1",
     "db": "^0.0.0"
   },
   "dependencies": {
@@ -63,8 +63,8 @@
     "zod": "^4.3.6",
     "zustand": "^5.0.11",
     "errore": "^0.14.1",
-    "libsqlproxy": "^0.1.0",
     "opencode-injection-guard": "^0.2.1",
+    "libsqlproxy": "^0.1.0",
     "traforo": "^0.7.1"
   },
   "optionalDependencies": {

package/skills/egaki/SKILL.md

@@ -54,6 +54,23 @@ The `--model` / `-m` flag is **optional** on both `egaki image` and `egaki video
 
 Agents should always pass `-m` explicitly to avoid the interactive picker.
 
+### Preferred image models
+
+When the user does not specify a model, prefer these in order:
+
+1. **`gpt-image-1`** (or `gpt-image-2` / `chatgpt-image-latest` if available)
+2. **`grok-imagine-image`** (xAI Grok)
+3. **`nano-banana-pro-preview`**
+
+Always try the first available model. Fall back to the next if auth is missing
+for the preferred one.
+
+### Preferred video models
+
+When the user does not specify a video model, prefer:
+
+1. **`grok-imagine-video-1.5`** (xAI Grok)
+
 ## Example commands
 
 ```bash

package/skills/goke/SKILL.md

@@ -178,6 +178,23 @@ import { openInBrowser } from 'goke'
 await openInBrowser('https://example.com/dashboard')
 ```
 
+## Command Descriptions and Examples
+
+**Use backtick formatting in descriptions** for flags and command references (e.g. `` `--status` ``, `` `mycli deploy` ``). Plain text flag names won't render as code in generated docs.
+
+**Use `.example()` for usage examples, not the description string.** `generateDocs()` auto-wraps `.example()` strings in fenced `` ```sh `` code blocks. Examples in the description render as plain text without syntax highlighting.
+
+```ts
+cli.command(
+  'query <sql>',
+  dedent`
+    Run a SQL query. Add \`--json\` for the raw JSON envelope.
+  `,
+)
+  .example('mycli query "SELECT * FROM users" -p my-app')
+  .example('mycli query "SELECT * FROM users FORMAT CSV" > out.csv')
+```
+
 ## Command Naming Conventions
 
 **ALWAYS read existing commands before adding a new one.** Scan the CLI for option names, verbs, and noun patterns already in use. New commands must stay consistent with what exists.

package/skills/holocron/SKILL.md

@@ -43,6 +43,7 @@ When the user asks about a specific workflow, fetch the matching page directly:
 - **Node deploy**: https://holocron.so/docs/deploy/node.md
 - **Holocron deploy**: https://holocron.so/docs/deploy/holocron.md
 - **AI assistant docs**: https://holocron.so/docs/ai/assistant.md
+- **Bleed**: https://holocron.so/docs/customize/bleed.md
 
 ```bash
 curl -fsSL https://holocron.so/docs/quickstart.md
@@ -326,6 +327,36 @@ sidebarTitle: Auth Providers
 below the title and in search engine snippets. Write a single sentence that
 summarizes the page content. Longer descriptions get truncated with an ellipsis.
 
+## Page titles (MUST follow)
+
+Holocron renders the browser `<title>` as `{page title} — {site name}`. Two
+frontmatter fields control what appears where:
+
+- **`title`** — browser tab, Google results, OG image, page heading. Write for SEO.
+- **`sidebarTitle`** — sidebar navigation only. Write for scannability (short label).
+
+**Always set both.** `title` is the full descriptive phrase; `sidebarTitle` is
+the short sidebar label. Without `sidebarTitle`, the full title shows in the
+sidebar and often wraps or looks verbose.
+
+```mdx
+---
+title: Open-source browser automation for AI agents
+sidebarTitle: Home
+description: Automate any browser with a simple TypeScript API.
+---
+```
+
+Browser tab: `Open-source browser automation for AI agents — Playwriter`
+Sidebar: `Home`
+
+**Rules:**
+
+- **Never set `title` identical to the site name.** `Playwriter — Playwriter` is redundant.
+- **Every `title` MUST be descriptive, not a generic label.** `Introduction`, `Getting Started`, `Overview` say nothing in a browser tab. Write what the page covers.
+- **Every `title` MUST be unique across the site.**
+- **`index.mdx` MUST use `sidebarTitle: Home`** (or `Overview`) and a descriptive `title`.
+
 ## Custom entry (mounting docs inside a Spiceflow app)
 
 When the site mounts Holocron inside an existing **Spiceflow** app (the `entry`
@@ -416,6 +447,12 @@ below the main content to accommodate the aside height. Keep aside callouts
 short, and only place them in sections that have at least a few paragraphs of
 body text.
 
+## Moving or renaming a page
+
+When moving or renaming a page, **always add a redirect** from the old slug to
+the new one so existing links and bookmarks don't break. Update internal links
+in other pages and the slug in `docs.json` navigation to match.
+
 ## New pages and navigation
 
 After creating a new `.mdx` or `.md` page, add its slug to `docs.jsonc`
@@ -569,7 +606,7 @@ Use ASCII diagrams frequently in MDX pages. Always use the **`diagram`** languag
 - Never exceed 94 characters per line.
 - Prefer a **varied, organic layout**. Mix plain text labels, boxes for major components, and directional arrows.
 - All connections must use **directional arrows**. Never use plain lines without an arrowhead.
-- Verify alignment by counting characters precisely.
+- Verify alignment by running `npx -y @holocron.so/cli diagrams fix <file>` (see dedicated section below).
 
 ````mdx
 ```diagram
@@ -590,6 +627,23 @@ docs.jsonc ───►│  Vite Plugin  │──────► Build Output
 ```
 ````
 
+## Always run `diagrams fix` after editing diagrams
+
+LLMs cannot count characters reliably. Every time you create or edit a diagram in an MDX page, you **must** run the alignment fixer before committing. This is not optional.
+
+```bash
+npx -y @holocron.so/cli diagrams fix path/to/file.mdx
+```
+
+The command:
+- Fixes box alignment (padding, border widths, junctions) in-place
+- Reports how many lines were changed
+- Exits with code 1 if any lines exceed max width (94 cols by default)
+
+If the output says "No changes", the diagram was already correct. If it reports width violations, shorten the offending lines manually and re-run.
+
+**Do not skip this step.** Even if the diagram looks correct in your editor, run the command. Off-by-one padding errors are invisible to LLMs but obvious to humans in monospace fonts.
+
 ## OpenAPI summaries
 
 OpenAPI operation `summary` fields become sidebar titles. The sidebar is only
@@ -601,6 +655,15 @@ characters. Use the same concise style as page `sidebarTitle` fields.
 - Never repeat the tag/group name in the summary. If the tag is `Deploy`, the summary should not start with "Deploy".
 - If the summary reads well as a sidebar label at 230px, it is short enough.
 
+## Bleed — extending content past the prose column
+
+Always wrap **YouTube embeds, videos, and large images** in `<div className='bleed'>`
+so they extend into both page margins instead of sitting at narrow prose width.
+`<Frame>` also accepts `className='bleed'`. Containers like Callout, Card, and
+Accordion apply `no-bleed` automatically to keep descendants inside their frame.
+
+See https://holocron.so/docs/customize/bleed.md for the full reference.
+
 ## Agent rules
 
 - **Always place MDX pages inside the Holocron `pagesDir`.** Before creating or
@@ -614,5 +677,7 @@ characters. Use the same concise style as page `sidebarTitle` fields.
 - All ASCII diagrams in MDX pages must use the `diagram` language hint on the
   code fence (` ```diagram `). This renders them with proper styling on the
   website instead of plain monospace.
+- After creating or editing any diagram, run `npx -y @holocron.so/cli diagrams fix <file>`
+  to auto-fix alignment. LLMs cannot count characters reliably.
 - Never pipe curl or `--help` output through `head`, `tail`, or any truncation
   command. Always read the full output.

package/skills/sigillo/SKILL.md

@@ -25,6 +25,19 @@ sigillo --help
 
 **NEVER truncate this either.**
 
+If a flag or command documented here is missing from `--help`, the installed binary is likely outdated. Update before proceeding:
+
+```bash
+npm i -g sigillo@latest
+```
+
+If sigillo is symlinked to a local dev build (check with `which sigillo`), rebuild from source instead:
+
+```bash
+cd /path/to/sigillo/cli && zig build -Dtarget=aarch64-macos
+cp zig-out/bin/sigillo dist/darwin-arm64/sigillo
+```
+
 ## New project setup workflow
 
 This mirrors the Doppler workflow: check auth → link project → list secrets → run.
@@ -88,6 +101,16 @@ To read a specific value:
 sigillo secrets get DATABASE_URL
 ```
 
+`secrets get` returns YAML by default. Pass `--raw` to output only the raw value (no YAML wrapping). When stdout is piped, `--raw` is implied automatically:
+
+```bash
+# copy a secret between environments (piped stdout auto-enables raw mode)
+sigillo secrets get DATABASE_URL -c dev | sigillo secrets set DATABASE_URL -c preview
+
+# force raw output in a terminal (useful for scripting)
+sigillo secrets get DATABASE_URL --raw
+```
+
 **5. Run your app with secrets injected:**
 
 ```bash
@@ -113,11 +136,11 @@ Never read a secret value into the agent context window or pass it as plain text
 **Copying a secret from one env to another:**
 
 ```bash
-# value flows through stdin, never seen by the agent
+# piped stdout auto-enables raw mode, value never seen by the agent
 sigillo secrets get DATABASE_URL -c dev | sigillo secrets set DATABASE_URL -c preview
 ```
 
-The same pattern works for any secret copy — between environments, or when seeding a new environment from an existing one.
+The same pattern works for any secret copy, between environments, or when seeding a new environment from an existing one.
 
 ### Never read `.env` files or `~/.sigillo/*`
 
@@ -145,14 +168,22 @@ If a `package.json` script requires secrets, embed `sigillo run` directly in the
 {
   "scripts": {
     "dev": "sigillo run -c dev -- vite dev",
-    "deployment": "sigillo run -c preview -- pnpm db:migrate:preview && CLOUDFLARE_ENV=preview sigillo run -c preview --command 'vite build && wrangler deploy --env preview'",
-    "deployment:prod": "sigillo run -c prod -- pnpm db:migrate:prod && sigillo run -c prod --command 'vite build && wrangler deploy'"
+    "deploy": "pnpm db:migrate:preview && CLOUDFLARE_ENV=preview sigillo run -c preview --command 'tsc && vite build && wrangler deploy --env preview'",
+    "deploy:prod": "pnpm db:migrate:prod && sigillo run -c prod --command 'tsc && vite build && wrangler deploy'"
   }
 }
 ```
 
+These scripts work because pnpm adds `node_modules/.bin` to PATH before executing the script string, and sigillo inherits that PATH. Commands like `tsc`, `vite`, and `wrangler` resolve correctly inside `--command` as long as the entry point is `pnpm run deploy`.
+
 Use `-c dev` for local development, `-c preview` for staging or preview deployments, and `-c prod` or the repo's production slug for production.
 
+### Always run `sigillo run` via pnpm scripts, not directly
+
+`sigillo run --command` spawns `$SHELL -c '...'` and passes the inherited `PATH`. But pnpm only adds `node_modules/.bin` to `PATH` when it's running a `package.json` script. If you call `sigillo run --command 'tsc && vite build'` directly from the terminal, `tsc` and `vite` won't be found because `node_modules/.bin` is not in PATH.
+
+Always invoke deploy/build commands through `pnpm run <script>` so pnpm augments PATH before sigillo inherits it. If you must run sigillo directly, use `pnpm exec` to resolve binaries: `sigillo run --command 'pnpm exec tsc && pnpm exec vite build'`.
+
 ### Use `--command` for shell expansion
 
 Use direct argv mode when no shell syntax is needed:

package/skills/zele/SKILL.md

@@ -47,3 +47,16 @@ The README and `zele --help` output are the source of truth for commands, option
    ```
 5. **Google-only features** (labels, Gmail filters, `zele cal *`, full profile) fail on IMAP accounts with a clear error. Check `zele whoami` output for account type before using them.
 6. **Headless Google login** requires a tmux wrapper because `zele login` is interactive. See the README "Remote / headless login" section for the exact pattern.
+7. **Waiting for emails** with `zele mail watch`. It polls for new emails matching a filter and exits as soon as one arrives. Use this to wait for replies, verification codes, or any expected email:
+   ```bash
+   # wait for a reply from alice (no timeout, blocks until match)
+   zele mail watch --filter "is:unread from:alice@example.com"
+
+   # wait for a verification code with a 5-minute timeout
+   zele mail watch --filter "is:unread subject:verification" --timeout 300
+
+   # send an email then wait for the reply
+   zele mail send --to bob@example.com --subject "Question" --body "Hey, can you check this?"
+   zele mail watch --filter "is:unread from:bob@example.com subject:Re:Question" --timeout 600
+   ```
+   If the matched email wasn't the expected one, call `zele mail watch` again with a more specific filter. Exit code 0 means a match was found, exit code 1 means timeout.

package/src/cli-commands/project.ts

@@ -5,7 +5,7 @@ import { note } from '@clack/prompts'
 import YAML from 'yaml'
 import * as errore from 'errore'
 import type { OpencodeClient, Event as OpenCodeEvent } from '@opencode-ai/sdk/v2'
-import { Events, ActivityType, type PresenceStatusData, type Guild, Routes } from 'discord.js'
+import { Events, ActivityType, type PresenceStatusData, type Guild, type Client, Routes } from 'discord.js'
 import path from 'node:path'
 import fs from 'node:fs'
 import { fileURLToPath } from 'node:url'
@@ -98,74 +98,7 @@ cli
 
       cliLogger.log('Finding guild...')
 
-      // Find guild
-      let guild: Guild
-      if (options.guild) {
-        const guildId = String(options.guild)
-        const foundGuild = client.guilds.cache.get(guildId)
-        if (!foundGuild) {
-          cliLogger.log('Guild not found')
-          cliLogger.error(`Guild not found: ${guildId}`)
-          void client.destroy()
-          process.exit(EXIT_NO_RESTART)
-        }
-        guild = foundGuild
-      } else {
-        const existingChannelId = await (await getDb()).query.channel_directories.findFirst({
-          where: { channel_type: 'text' },
-          orderBy: { created_at: 'desc' },
-          columns: { channel_id: true },
-        }).then((row) => row?.channel_id)
-
-        if (existingChannelId) {
-          try {
-            const ch = await client.channels.fetch(existingChannelId)
-            if (ch && !ch.isDMBased()) {
-              guild = ch.guild
-            } else {
-              throw new Error('Channel has no guild')
-            }
-          } catch (error) {
-            cliLogger.debug(
-              'Failed to fetch existing channel while selecting guild:',
-              error instanceof Error ? error.stack : String(error),
-            )
-            let firstGuild = client.guilds.cache.first()
-            if (!firstGuild) {
-              // Cache might be empty, try fetching guilds from API
-              const fetched = await client.guilds.fetch()
-              const firstOAuth2Guild = fetched.first()
-              if (firstOAuth2Guild) {
-                firstGuild = await client.guilds.fetch(firstOAuth2Guild.id)
-              }
-            }
-            if (!firstGuild) {
-              cliLogger.log('No guild found')
-              cliLogger.error('No guild found. Add the bot to a server first.')
-              void client.destroy()
-              process.exit(EXIT_NO_RESTART)
-            }
-            guild = firstGuild
-          }
-        } else {
-          let firstGuild = client.guilds.cache.first()
-          if (!firstGuild) {
-            // Cache might be empty, try fetching guilds from API
-            const fetched = await client.guilds.fetch()
-            const firstOAuth2Guild = fetched.first()
-            if (firstOAuth2Guild) {
-              firstGuild = await client.guilds.fetch(firstOAuth2Guild.id)
-            }
-          }
-          if (!firstGuild) {
-            cliLogger.log('No guild found')
-            cliLogger.error('No guild found. Add the bot to a server first.')
-            void client.destroy()
-            process.exit(EXIT_NO_RESTART)
-          }
-          guild = firstGuild
-        }
-      }
+      const guild = await resolveGuildForProjectCommand({ client, guildIdOverride: options.guild })
 
       // Check if channel already exists in this guild
       cliLogger.log('Checking for existing channel...')
@@ -466,24 +399,7 @@ cli
       client.login(botToken).catch(reject)
     })
 
-    let guild: Guild
-    if (options.guild) {
-      const found = client.guilds.cache.get(options.guild)
-      if (!found) {
-        cliLogger.error(`Guild not found: ${options.guild}`)
-        void client.destroy()
-        process.exit(EXIT_NO_RESTART)
-      }
-      guild = found
-    } else {
-      const first = client.guilds.cache.first()
-      if (!first) {
-        cliLogger.error('No guild found. Add the bot to a server first.')
-        void client.destroy()
-        process.exit(EXIT_NO_RESTART)
-      }
-      guild = first
-    }
+    const guild = await resolveGuildForProjectCommand({ client, guildIdOverride: options.guild })
 
     const { textChannelId, channelName } = await createProjectChannels({
       guild,
@@ -505,4 +421,100 @@ cli
   })
 
 
+// Resolve the guild for project add/create commands. In gateway mode the
+// guild cache only contains authorized guilds, so picking from cache is safe.
+// The old approach fetched an existing channel to infer the guild, but that
+// breaks when the channel belongs to a different guild (e.g. old self-hosted
+// bot channels) and the gateway proxy rejects the REST call. This led to a
+// non-deterministic fallback that picked the wrong guild.
+async function resolveGuildForProjectCommand({ client, guildIdOverride }: { client: Client; guildIdOverride?: string }): Promise<Guild> {
+  if (guildIdOverride) {
+    const found = client.guilds.cache.get(guildIdOverride)
+    if (!found) {
+      cliLogger.error(`Guild not found: ${guildIdOverride}`)
+      void client.destroy()
+      process.exit(EXIT_NO_RESTART)
+    }
+    return found
+  }
+
+  // Try existing channel lookup to find the guild the user already has channels in.
+  // This handles multi-guild setups where we want to add to the same guild.
+  const db = await getDb()
+  const existingChannels = await db.query.channel_directories.findMany({
+    where: { channel_type: 'text' },
+    orderBy: { created_at: 'desc' },
+    columns: { channel_id: true },
+    limit: 20,
+  })
+
+  // Log available guilds for debugging guild selection issues
+  const cachedGuilds = Array.from(client.guilds.cache.values())
+  cliLogger.debug(`Guilds in cache (${cachedGuilds.length}): ${cachedGuilds.map((g) => `${g.name} (${g.id})`).join(', ')}`)
+
+  // When multiple guilds are available, find which guild has the most
+  // existing channels. The user's main guild will have far more channels
+  // than a test/demo guild.
+  const guildHits = new Map<string, { guild: Guild; count: number }>()
+  for (const row of existingChannels) {
+    try {
+      const ch = await client.channels.fetch(row.channel_id)
+      if (ch && !ch.isDMBased()) {
+        const entry = guildHits.get(ch.guild.id)
+        if (entry) {
+          entry.count++
+        } else {
+          guildHits.set(ch.guild.id, { guild: ch.guild, count: 1 })
+        }
+      }
+    } catch {
+      // Channel might be in a different guild (gateway proxy rejects) or deleted, skip
+    }
+  }
+
+  if (guildHits.size > 0) {
+    // Pick the guild with the most channels
+    const best = Array.from(guildHits.values()).sort((a, b) => b.count - a.count)[0]!
+    cliLogger.debug(
+      `Guild channel counts: ${Array.from(guildHits.values()).map((e) => `${e.guild.name} (${e.guild.id}): ${e.count}`).join(', ')}`,
+    )
+    cliLogger.debug(`Selected guild: ${best.guild.name} (${best.guild.id}) with ${best.count} channels`)
+    return best.guild
+  }
+
+  cliLogger.debug('Could not resolve guild from existing channels, falling back to cache')
+
+  // If only one guild in cache, use it directly (common case).
+  // If multiple guilds, error out and ask the user to specify --guild
+  // since we can't determine which one to use.
+  if (cachedGuilds.length === 1) {
+    return cachedGuilds[0]!
+  }
+  if (cachedGuilds.length > 1) {
+    cliLogger.error(
+      `Multiple guilds found. Use --guild to specify which one:\n${cachedGuilds.map((g) => `  ${g.id}  ${g.name}`).join('\n')}`,
+    )
+    void client.destroy()
+    process.exit(EXIT_NO_RESTART)
+  }
+
+  // Cache empty, try fetching
+  const fetched = await client.guilds.fetch()
+  if (fetched.size === 1) {
+    const firstOAuth2Guild = fetched.first()!
+    return await client.guilds.fetch(firstOAuth2Guild.id)
+  }
+  if (fetched.size > 1) {
+    cliLogger.error(
+      `Multiple guilds found. Use --guild to specify which one:\n${Array.from(fetched.values()).map((g) => `  ${g.id}  ${g.name}`).join('\n')}`,
+    )
+    void client.destroy()
+    process.exit(EXIT_NO_RESTART)
+  }
+
+  cliLogger.error('No guild found. Add the bot to a server first.')
+  void client.destroy()
+  process.exit(EXIT_NO_RESTART)
+}
+
 export default cli