kimaki 0.18.0 → 0.20.0

package/dist/markdown.test.js

@@ -36,6 +36,18 @@ function createMatchers() {
             ],
         },
     };
+    const toolCallMatcher = {
+        id: 'tool-call-reply',
+        priority: 90,
+        when: { latestUserTextIncludes: 'use a tool please' },
+        then: {
+            parts: [
+                { type: 'stream-start', warnings: [] },
+                { type: 'tool-call', toolCallId: 'tc1', toolName: 'bash', input: JSON.stringify({ command: 'echo hello world', description: 'Print greeting' }) },
+                { type: 'finish', finishReason: 'tool-calls', usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 } },
+            ],
+        },
+    };
     const defaultMatcher = {
         id: 'default-reply',
         priority: 1,
@@ -49,12 +61,13 @@ function createMatchers() {
             ],
         },
     };
-    return [helloMatcher, defaultMatcher];
+    return [helloMatcher, toolCallMatcher, defaultMatcher];
 }
 let client;
 let directories;
 let testStartTime;
 let sessionID;
+let toolSessionID;
 beforeAll(async () => {
     testStartTime = Date.now();
     directories = createRunDirectories();
@@ -117,7 +130,34 @@ beforeAll(async () => {
             setTimeout(resolve, 200);
         });
     }
-}, 20_000);
+    // Create a second session that triggers a tool call (bash echo)
+    const toolCreateResult = await client.session.create({
+        directory: directories.projectDirectory,
+        title: 'Tool Call Session',
+    });
+    toolSessionID = toolCreateResult.data.id;
+    await client.session.promptAsync({
+        sessionID: toolSessionID,
+        directory: directories.projectDirectory,
+        parts: [{ type: 'text', text: 'use a tool please' }],
+    });
+    // Wait for tool execution to complete
+    const toolMaxWait = 15_000;
+    const toolPollStart = Date.now();
+    while (Date.now() - toolPollStart < toolMaxWait) {
+        const msgs = await client.session.messages({
+            sessionID: toolSessionID,
+            directory: directories.projectDirectory,
+        });
+        const messages = msgs.data || [];
+        const hasToolPart = messages.some((m) => m.parts.some((p) => p.type === 'tool' && p.state?.status === 'completed'));
+        if (hasToolPart) {
+            await new Promise((resolve) => { setTimeout(resolve, 500); });
+            break;
+        }
+        await new Promise((resolve) => { setTimeout(resolve, 200); });
+    }
+}, 30_000);
 afterAll(async () => {
     if (directories) {
         await cleanupTestSessions({
@@ -262,3 +302,34 @@ test('generate markdown with lastAssistantOnly', async () => {
     // Should contain the assistant response
     expect(markdown).toContain('Hello! This is a deterministic markdown test response.');
 });
+test('compact tools: tool calls show one-liner with line count', async () => {
+    const exporter = new ShareMarkdown(client);
+    const result = await exporter.generate({
+        sessionID: toolSessionID,
+        compactTools: true,
+    });
+    expect(errore.isOk(result)).toBe(true);
+    const md = errore.unwrap(result);
+    // Compact mode: exact one-liner format with params and line count
+    expect(md).toContain('> 🛠️ **bash** command=echo hello world, description=Print greeting');
+    expect(md).toMatch(/\(\d+ lines?\)/);
+    // Should NOT contain full output code blocks or input YAML
+    expect(md).not.toContain('**Output:**');
+    expect(md).not.toContain('**Input:**');
+    expect(md).not.toContain('```yaml');
+});
+test('verbose tools: tool calls show full input and output', async () => {
+    const exporter = new ShareMarkdown(client);
+    const result = await exporter.generate({
+        sessionID: toolSessionID,
+        compactTools: false,
+    });
+    expect(errore.isOk(result)).toBe(true);
+    const md = errore.unwrap(result);
+    // Verbose mode: full tool rendering with input YAML and output code block
+    expect(md).toContain('#### 🛠️ Tool: bash');
+    expect(md).toContain('**Input:**');
+    expect(md).toContain('```yaml');
+    expect(md).toContain('**Output:**');
+    expect(md).toContain('hello world');
+});

package/dist/message-formatting.js

@@ -266,6 +266,42 @@ export async function getFileAttachments(message) {
     return results.filter((r) => r !== null);
 }
 const MAX_BASH_COMMAND_INLINE_LENGTH = 100;
+/**
+ * Format the inline title for a bash tool part. Handles three cases:
+ * 1. Short single-line command → show full command
+ * 2. Long/multiline command with description → show description
+ * 3. Long/multiline command without description → truncate first line of command
+ *
+ * The description field was removed from the bash tool schema in newer opencode
+ * versions, so case 3 is the common path now. Without this fallback, long commands
+ * would render as just "┣ bash" with no context.
+ */
+export function formatBashToolTitle({ command, description, stateTitle, }) {
+    if (!command && !description && !stateTitle)
+        return '';
+    const isSingleLine = !command.includes('\n');
+    // Find first non-empty line to handle commands with leading blank lines
+    const firstMeaningfulLine = command
+        .split('\n')
+        .find((line) => line.trim().length > 0)
+        ?.trimStart() ?? '';
+    if (command && isSingleLine && command.length <= MAX_BASH_COMMAND_INLINE_LENGTH) {
+        return ` _${escapeInlineMarkdown(command)}_`;
+    }
+    if (description) {
+        return ` _${escapeInlineMarkdown(description)}_`;
+    }
+    if (firstMeaningfulLine.length > 0) {
+        const truncated = firstMeaningfulLine.length > MAX_BASH_COMMAND_INLINE_LENGTH
+            ? firstMeaningfulLine.slice(0, MAX_BASH_COMMAND_INLINE_LENGTH) + '…'
+            : firstMeaningfulLine;
+        return ` _${escapeInlineMarkdown(truncated)}_`;
+    }
+    if (stateTitle) {
+        return ` _${escapeInlineMarkdown(stateTitle)}_`;
+    }
+    return '';
+}
 export function getToolSummaryText(part) {
     if (part.type !== 'tool')
         return '';
@@ -449,12 +485,10 @@ export function formatPart(part, prefix) {
             }
             const command = part.state.input?.command || '';
             const description = part.state.input?.description || '';
-            const isSingleLine = !command.includes('\n');
-            const toolTitle = isSingleLine && command.length <= MAX_BASH_COMMAND_INLINE_LENGTH
-                ? ` _${escapeInlineMarkdown(command)}_`
-                : description
-                    ? ` _${escapeInlineMarkdown(description)}_`
-                    : '';
+            const toolTitle = formatBashToolTitle({
+                command,
+                description,
+            });
             return `┣ ${pfx}bash${toolTitle}`;
         }
         const summaryText = getToolSummaryText(part);
@@ -466,16 +500,12 @@ export function formatPart(part, prefix) {
         else if (part.tool === 'bash') {
             const command = part.state.input?.command || '';
             const description = part.state.input?.description || '';
-            const isSingleLine = !command.includes('\n');
-            if (isSingleLine && command.length <= MAX_BASH_COMMAND_INLINE_LENGTH) {
-                toolTitle = `_${escapeInlineMarkdown(command)}_`;
-            }
-            else if (description) {
-                toolTitle = `_${escapeInlineMarkdown(description)}_`;
-            }
-            else if (stateTitle) {
-                toolTitle = `_${escapeInlineMarkdown(stateTitle)}_`;
-            }
+            const formatted = formatBashToolTitle({
+                command,
+                description,
+                stateTitle,
+            });
+            toolTitle = formatted.startsWith(' ') ? formatted.slice(1) : formatted;
         }
         else if (stateTitle) {
             toolTitle = `_${escapeInlineMarkdown(stateTitle)}_`;

package/dist/message-formatting.test.js

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'vitest';
-import { formatPart, formatTodoList, serializeEmbeds, serializePoll, serializeMessageSnapshots } from './message-formatting.js';
+import { formatBashToolTitle, formatPart, formatTodoList, serializeEmbeds, serializePoll, serializeMessageSnapshots } from './message-formatting.js';
 describe('formatPart', () => {
     test('callout text does not get ⬥ prefix', () => {
         const part = {
@@ -42,6 +42,44 @@ describe('formatPart', () => {
     `);
     });
 });
+describe('formatBashToolTitle', () => {
+    test('short single-line command shown in full', () => {
+        expect(formatBashToolTitle({ command: 'echo hello' })).toMatchInlineSnapshot(`" _echo hello_"`);
+    });
+    test('multiline command without description truncates to first line', () => {
+        expect(formatBashToolTitle({ command: 'echo hello\necho world\necho done' })).toMatchInlineSnapshot(`" _echo hello_"`);
+    });
+    test('long single-line command is truncated with ellipsis', () => {
+        const longCommand = 'a'.repeat(150);
+        const result = formatBashToolTitle({ command: longCommand });
+        expect(result).toContain('…');
+        expect(result.length).toBeLessThan(150);
+    });
+    test('description is preferred over truncated command when present', () => {
+        expect(formatBashToolTitle({
+            command: 'echo hello\necho world',
+            description: 'Print greeting',
+        })).toMatchInlineSnapshot(`" _Print greeting_"`);
+    });
+    test('stateTitle used as last resort', () => {
+        expect(formatBashToolTitle({ command: '', stateTitle: 'Running tests' })).toMatchInlineSnapshot(`" _Running tests_"`);
+    });
+    test('empty inputs return empty string', () => {
+        expect(formatBashToolTitle({ command: '' })).toBe('');
+    });
+    test('leading blank line skipped, uses first meaningful line', () => {
+        expect(formatBashToolTitle({ command: '\npnpm test\npnpm build' })).toMatchInlineSnapshot(`" _pnpm test_"`);
+    });
+    test('whitespace-only first line skipped', () => {
+        expect(formatBashToolTitle({ command: '   \npnpm test' })).toMatchInlineSnapshot(`" _pnpm test_"`);
+    });
+    test('no description field (new opencode) with multiline command', () => {
+        // This is the exact scenario that was broken: opencode removed `description`
+        // from the bash tool schema, so multiline commands rendered as just "┣ bash"
+        const command = 'git diff HEAD~1 --stat && git log --oneline -5';
+        expect(formatBashToolTitle({ command: command + '\n' + 'echo done' })).toMatchInlineSnapshot(`" _git diff HEAD\\~1 --stat && git log --oneline -5_"`);
+    });
+});
 describe('formatTodoList', () => {
     test('formats active todo with monospace numbers', () => {
         const part = {

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/package.json

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

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

@@ -199,6 +199,40 @@ After setup, `sigillo run` in any subdirectory uses that project + environment a
 
 Avoid `sigillo secrets download` unless a specific tool requires a file. Prefer injecting directly via `sigillo run --` so values never touch the filesystem.
 
+## Placeholder secrets (user fills in later)
+
+When the user asks to add a secret but will provide the actual value later via the dashboard, set it with an empty value:
+
+```bash
+sigillo secrets set DATABASE_URL ""
+```
+
+This creates the secret as a placeholder. The CLI shows `empty: true` when listing secrets so empty placeholders are visible. After setting the placeholder, always print the dashboard URL so the user can fill it in:
+
+```
+https://sigillo.dev/dash/projects/<PROJECT_ID>/envs/<ENV_SLUG>
+```
+
+Replace `<PROJECT_ID>` and `<ENV_SLUG>` with the actual values from the current setup. To find them:
+
+```bash
+sigillo secrets
+```
+
+The `environment_id` in the output is the env ID. The project ID is from `sigillo setup` or `sigillo projects`.
+
+To set placeholders across all environments at once:
+
+```bash
+sigillo secrets set DATABASE_URL "" -c dev -c preview -c prod
+```
+
+For secrets that need real random values immediately (auth secrets, encryption keys), generate them instead of leaving empty:
+
+```bash
+sigillo secrets set AUTH_SECRET "$(openssl rand -base64 32)" -c dev -c preview -c prod
+```
+
 ## Bootstrapping a project for a new codebase
 
 When a codebase needs Sigillo for the first time, the agent creates the org, project, and placeholder secrets. The user fills in real values later via the web UI.

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.