@wirecat/cli-core 0.393.0 → 0.395.0

package/CHANGELOG.md

@@ -5,6 +5,69 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.395.0 — 23.10.2026
+
+### Changed — may break callers
+
+- `searches list`, `searches history` and `searches clear` cover only message searches. The table is shared by
+  every CLI on the store; a saved meeting search shown, run or deleted from a messenger is refused with
+  `details.reason: "search.kind"`. `SearchesStore.savedSearches`, `searchHistory` and `clearSearchHistory` take an
+  optional list of kinds.
+
+### Added
+
+- `search meetings` takes `date:`, `project:`, `tag:` and `topic:` in the query: `budget project:RES date>=30d`. They
+  choose meetings as `--since-time`/`--until-time`, `--project`, `--tag` and `--topic` do, join the words with AND,
+  and are refused inside OR, NOT and groups (`query.unsupported-field`) or when the same filter is also an option.
+  Search by meaning embeds only the words. `liftMeetingFields` (`@wirecat/cli-core/meetings`) does the split.
+
+- `meetingSearchesService` (`@wirecat/cli-core/services`): saved meeting searches, kind `meetings-search`, in the
+  same table: create, list, show, delete and `run`, which counts the run.
+
+- MCP setup and diagnostic commands include examples in help and command discovery.
+
+- Account commands include concrete examples in help and command discovery.
+
+- Search commands include concrete examples in help and command discovery.
+
+- Configuration commands include concrete examples in help and command discovery.
+
+- Skill commands include concrete examples in help and command discovery.
+
+- Task commands include concrete examples in help and command discovery.
+
+- Chat deletion and history clearing include examples in help and command discovery.
+
+- Poll commands include concrete examples in help and command discovery.
+
+- Listing poll voters includes an example in help and command discovery.
+
+- Model commands include concrete examples in help and command discovery.
+
+- Recorded-run commands include concrete examples in help and command discovery.
+
+- Conversation commands include examples in help and command discovery, with guidance for submitting a batch answer.
+
+- Server commands include concrete examples in help and command discovery.
+
+## 0.394.0 — 23.10.2026
+
+### Added
+
+- Statistics commands include examples in help and command discovery, with guidance for reusing an exact evidence selection.
+
+- Store commands include concrete examples in help and command discovery.
+
+- **`contacts prepare <person>`: what to know before talking to someone.** What `contacts context` gives, plus the
+  one-to-one chats where their message is the newest the store holds, open tasks assigned to them, accepted facts
+  about them and their projects, your notes about them (withheld when the profile denies `contacts.notes.list`), and
+  their recent meetings — each with its reference, under one byte budget, with `prepare.coverage` saying what each
+  section left out and why. Tasks of another account of the same messenger, and facts on a project bound to one, stay
+  out. It reads messages, so `messages: deny` refuses it, as it does `contacts context`. `personPreparation` in
+  services and `people.preparation` on the store.
+
 ## 0.393.0 — 23.10.2026
 
 ### Added

package/dist/cli/config-command.js

@@ -16,7 +16,7 @@ import { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } fro
  */
 export const configCommand = (app, config, { permissionKey } = {}) => {
     const command = annotate(new Command("config"), { mcp: false }).description("the settings in force, and where each one came from");
-    annotate(command.command("show"), { effects: LOCAL_READ })
+    annotate(command.command("show"), { effects: LOCAL_READ, examples: [`${app.command} personal config show`] })
         .description("the profile, the profiles that exist, and each setting with where it came from")
         .option("--bot", "the settings a bot command on this profile gets, rather than the personal account's")
         .action(async function () {
@@ -42,7 +42,10 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
         }
     });
     for (const action of ["set", "unset"]) {
-        const sub = grantsAuthority(annotate(command.command(action), { effects: LOCAL_WRITE }))
+        const sub = grantsAuthority(annotate(command.command(action), {
+            effects: LOCAL_WRITE,
+            examples: [`${app.command} personal config ${action} limit${action === "set" ? " 20" : ""}`],
+        }))
             .argument("<setting>", 
         // default_profile is only removed now: `config unset` still takes it, `config set` refuses it.
         `one of: ${[...config.allSettings.filter((one) => action === "unset" || one !== "default_profile"), ...STORE_SETTINGS, "account_groups.<name>"].join(", ")}`)

package/dist/cli/messenger/account-command.js

@@ -14,9 +14,10 @@ import { accountAnswer, renderItem, wholeList } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
 import { privacyCommand } from "./records-command.js";
 export const accountCommand = (messenger) => {
+    const tool = `${messenger.app.command} personal`;
     const account = new Command("account")
         .description("the logged-in account")
-        .addCommand(annotate(new Command("list"), { effects: REMOTE_READ })
+        .addCommand(annotate(new Command("list"), { effects: REMOTE_READ, examples: [`${tool} account list`] })
         .description("every profile on this computer, and the account each is logged in as; asks the messenger nothing")
         .action(async function () {
         const context = messengerContext(this, messenger, { needsProfile: false });
@@ -45,7 +46,11 @@ export const accountCommand = (messenger) => {
             await store?.close();
         }
     }))
-        .addCommand(annotate(new Command("show"), { effects: REMOTE_READ, output: { entity: "account" } })
+        .addCommand(annotate(new Command("show"), {
+        effects: REMOTE_READ,
+        output: { entity: "account" },
+        examples: [`${tool} account show`],
+    })
         .description("who this profile is logged in as; the phone number shows its last four digits")
         .option("--show-phone", "print the whole phone number")
         .action(async function () {
@@ -54,7 +59,7 @@ export const accountCommand = (messenger) => {
         const account = await context.withMessenger((connection) => connection.me());
         renderAnswer(this, context, itemOf(accountAnswer(messenger.provider, whole ? account : maskedAccount(account))));
     }))
-        .addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE })
+        .addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE, examples: [`${tool} account update --first-name Alex`] })
         .description("change the name, the description or the photo everyone sees on your profile")
         .option("--first-name <name>", "your first name")
         .option("--last-name <name>", "your last name")

package/dist/cli/messenger/account-sessions-command.js

@@ -11,8 +11,9 @@ import { messengerContext } from "./context.js";
 const SESSIONS_QUERY = unfilteredQuery("account_session", accountSession);
 /** `account sessions …` — where else the account is logged in, not this tool's own `session`. */
 export const accountSessionsCommand = (messenger) => {
+    const tool = `${messenger.app.command} personal`;
     const sessions = new Command("sessions").description(`where else this account is logged in — not \`${messenger.app.command} session\`, which is this tool's own login`);
-    withQuery(annotate(sessions.command("list"), { effects: REMOTE_READ }), SESSIONS_QUERY)
+    withQuery(annotate(sessions.command("list"), { effects: REMOTE_READ, examples: [`${tool} account sessions list`] }), SESSIONS_QUERY)
         .description("every device and app logged in to this account; nothing is ended")
         .action(async function (words) {
         const context = messengerContext(this, messenger);
@@ -21,7 +22,11 @@ export const accountSessionsCommand = (messenger) => {
         renderAnswer(this, context, wholeList("account sessions list", found.map(sessionAnswer)));
     });
     // No MCP tool, at any permission level: it logs the owner out of the phone.
-    sessions.addCommand(annotate(new Command("end"), { effects: REMOTE_WRITE, mcp: false })
+    sessions.addCommand(annotate(new Command("end"), {
+        effects: REMOTE_WRITE,
+        mcp: false,
+        examples: [`${tool} account sessions end --others`],
+    })
         .description("log out every other device, your phone included; this one stays")
         .option("--others", "every session but this one")
         .action(async function () {

package/dist/cli/messenger/archive-commands.js

@@ -12,6 +12,7 @@ import { kindsOf } from "../../services/inbox.js";
 import { dateWindow } from "../../services/moment.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { commandAt } from "../steps.js";
 import { jobsCommand } from "./backfill-command.js";
 import { messengerContext } from "./context.js";
 import { admitPassword, linesOf, openFolder, runFileFor, saveManifest, sealRun, writeChanges } from "./export-folder.js";
@@ -30,6 +31,33 @@ export const storeCommand = (messenger) => {
         .addCommand(clearCommand(messenger));
     for (const command of storeMaintenanceCommands(messenger))
         store.addCommand(command);
+    const examples = {
+        backup: "./backup.db",
+        check: "",
+        clear: "--left --dry-run",
+        "copies delete": "messages_copy_1",
+        decrypt: "./backup.enc --output ./restored.db",
+        export: '"Book club" --output ./messages.jsonl',
+        "gaps plan": '"Book club"',
+        "gaps repair": '"Book club" --limit 100',
+        info: "",
+        "jobs cancel": "job-101",
+        "jobs clear": "",
+        "jobs list": "",
+        "jobs retry": "--failed",
+        "jobs show": "",
+        migrate: "",
+        reindex: "",
+        repair: "--dry-run",
+        reset: "",
+        restore: "./backup.db",
+        status: '"Book club"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(store, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal store ${path} ${args}`.trimEnd()] });
+    }
     return store;
 };
 /**

package/dist/cli/messenger/contacts-command.js

@@ -137,6 +137,35 @@ export const contactsCommand = (messenger) => {
         if (hasMore)
             context.renderer.note("cut at --limit; a larger one shows more");
     });
+    annotate(contacts.command("prepare"), {
+        effects: REMOTE_READ,
+        examples: [`${messenger.app.command} contacts prepare Ana`],
+    })
+        .summary("what to know before you talk to someone, each item with its reference")
+        .description("before you talk to someone: what contacts context gives, plus the one-to-one chats where they wrote last, " +
+        "open tasks, accepted facts, your notes and their recent meetings, each with its reference; never connects")
+        .argument("<person>", "their id, @username, or part of their name")
+        .option("--limit <n>", `at most this many messages, and items in each section; ${CONTEXT_MESSAGES} if not given`, positiveCount("--limit"))
+        .option("--since-time <time>", "no message or meeting older than this ISO 8601 time, or 2h / 1d ago")
+        .action(async function (person) {
+        const { limit, sinceTime } = this.opts();
+        const context = messengerContext(this, messenger);
+        const window = dateWindow(sinceTime === undefined ? {} : { sinceTime });
+        const found = await context.withServices((services) => services.people.prepare(person, {
+            messages: limit ?? CONTEXT_MESSAGES,
+            notes: levelFor(context.settings.permissions, "contacts.notes.list").level !== "deny",
+            ...(window.since === undefined ? {} : { since: window.since }),
+        }));
+        const { hasMore, ...rest } = found;
+        renderAnswer(this, context, itemOf(snakeKeys(rest), {
+            next: syncsFirst(messenger)
+                ? found.notRead
+                    .filter((chat) => chat.provider === messenger.provider)
+                    .map((chat) => nextStep("messages.sync", { args: { chat: chat.chatId } }))
+                : [],
+            meta: { ...window.meta, ...(hasMore ? { truncated: true } : {}) },
+        }));
+    });
     annotate(contacts.command("timeline"), { effects: REMOTE_READ })
         .description("everything one person took part in, in every messenger linked to them — messages they wrote or were " +
         "mentioned in, chats, mail, meetings, tasks — newest first, from the store; never connects")

package/dist/cli/messenger/conversation-examples.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare const conversationExamples: (root: Command, tool: string) => void;

package/dist/cli/messenger/conversation-examples.js

@@ -0,0 +1,25 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { commandAt } from "../steps.js";
+export const conversationExamples = (root, tool) => {
+    const examples = {
+        "batches next": '--chat "Book club"',
+        "batches status": '--chat "Book club"',
+        build: '--chat "Book club"',
+        "consents list": "",
+        "consents revoke": '--chat "Book club"',
+        "embed clear": '--chat "Book club"',
+        "embed status": '--chat "Book club"',
+        "links add": '--batch "$batch"',
+        "links clear": '--chat "Book club"',
+        list: '"Book club"',
+        related: '"Book club" 101',
+        show: '"Book club" 101',
+        status: "",
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(root, path);
+        if (command)
+            annotate(command, { examples: [`${tool} personal conversations ${path} ${args}`.trimEnd()] });
+    }
+    commandAt(root, "links add")?.addHelpText("after", "\nSet batch to the id from conversations batches next; supply the JSON answer to that batch on stdin.\n");
+};

package/dist/cli/messenger/conversations-command.js

@@ -21,6 +21,7 @@ import { nextStep, rootOf, runnable, stepLine } from "../steps.js";
 import { answerOf as askOwner } from "./ask.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 import { conversationShown, foundConversations, readinessList, refreshedAnswer } from "./conversation-answers.js";
+import { conversationExamples } from "./conversation-examples.js";
 import { messageItems } from "./message-items.js";
 import { syncOptions, syncRequest } from "./search-sync-options.js";
 import { readAll } from "./stdin.js";
@@ -363,6 +364,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf({ revoked: true }));
     });
     conversations.addCommand(embed);
+    conversationExamples(conversations, messenger.app.command);
     return conversations;
 };
 /**

package/dist/cli/messenger/mcp-command.js

@@ -52,7 +52,10 @@ export const mcpCommand = (messenger) => {
         const { serveOverStdio } = await import("../../mcp/server.js");
         await serveOverStdio(this, context, messenger, {});
     });
-    command.addCommand(withFlags(annotate(new Command("config"), { effects: LOCAL_READ }).description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")).action(async function () {
+    command.addCommand(withFlags(annotate(new Command("config"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} personal mcp config`],
+    }).description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")).action(async function () {
         const flags = this.optsWithGlobals();
         const context = messengerContext(this, messenger);
         const { settings, env } = context;
@@ -67,7 +70,10 @@ export const mcpCommand = (messenger) => {
         // Pasted into a file, so a person gets the client's own JSON, indented; a script finds it under `config`.
         renderAnswer(this, context, itemOf({ config: entry.config }, { next: entry.nodeBound ? [nextStep("mcp.config", { args: {} })] : [] }), () => JSON.stringify(entry.config, null, 2));
     }));
-    command.addCommand(withFlags(grantsAuthority(annotate(new Command("setup"), { effects: LOCAL_WRITE }))
+    command.addCommand(withFlags(grantsAuthority(annotate(new Command("setup"), {
+        effects: LOCAL_WRITE,
+        examples: [`${app.command} personal mcp setup codex --allow-writes`],
+    }))
         .description("add this profile's local MCP server to Codex or Claude Code")
         .argument("<client>", "codex or claude-code")
         .option("--allow-writes", "acknowledge that this profile offers writing tools")).action(async function (client) {
@@ -98,7 +104,10 @@ export const mcpCommand = (messenger) => {
             throw new CliError("validation_error", error instanceof Error ? error.message : "MCP setup failed");
         }
     }));
-    command.addCommand(withFlags(annotate(new Command("doctor"), { effects: LOCAL_READ }).description("check this profile's local MCP handshake and tool list")).action(async function () {
+    command.addCommand(withFlags(annotate(new Command("doctor"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} personal mcp doctor`],
+    }).description("check this profile's local MCP handshake and tool list")).action(async function () {
         const context = messengerContext(this, messenger);
         const { settings, env } = context;
         const given = environmentOf(this).mcp ?? {};

package/dist/cli/messenger/models-command.js

@@ -57,9 +57,10 @@ const downloaded = (body) => "item" in body ? `${body.item.id}: downloaded and w
 const modelLine = (item, width) => `${item.default ? "*" : " "} ${item.id.padEnd(width)} ${megabytes(item.size_bytes).padStart(7)}  ` +
     (item.downloaded ? "downloaded" : "—".padEnd(10));
 export const modelsCommand = (messenger) => {
+    const tool = `${messenger.app.command} personal`;
     const models = annotate(new Command("models"), { mcp: false }).description("models that run on this machine");
     const audio = models.command("audio").description("speech models for transcribing voice messages");
-    withQuery(annotate(audio.command("list"), { effects: LOCAL_READ }), MODELS_QUERY)
+    withQuery(annotate(audio.command("list"), { effects: LOCAL_READ, examples: [`${tool} models audio list`] }), MODELS_QUERY)
         .description("the speech models, most suitable first, which are downloaded, and which one is the default")
         .action(async function (words) {
         const context = baseContext(this, messenger.resolveSettings);
@@ -73,7 +74,11 @@ export const modelsCommand = (messenger) => {
                 context.renderer.note(`kept in ${directory}`);
         });
     });
-    reachesOtherService(annotate(audio.command("download"), { effects: FETCH, output: { entity: "model" } }))
+    reachesOtherService(annotate(audio.command("download"), {
+        effects: FETCH,
+        output: { entity: "model" },
+        examples: [`${tool} models audio download parakeet-v3`],
+    }))
         .argument("<model>", "a model id from `models audio list`")
         .description("download a speech model once, checked against the sha256 this version expects")
         .action(async function (id) {
@@ -101,7 +106,7 @@ export const modelsCommand = (messenger) => {
         }, { unbounded: true });
     });
     const text = models.command("text").description("embedding models for searching conversations by meaning");
-    withQuery(annotate(text.command("list"), { effects: LOCAL_READ }), MODELS_QUERY)
+    withQuery(annotate(text.command("list"), { effects: LOCAL_READ, examples: [`${tool} models text list`] }), MODELS_QUERY)
         .description("the embedding models, most suitable first, which are downloaded, and which one is the default")
         .action(async function (words) {
         const context = baseContext(this, messenger.resolveSettings);
@@ -115,7 +120,11 @@ export const modelsCommand = (messenger) => {
                 context.renderer.note(`kept in ${directory}`);
         });
     });
-    reachesOtherService(annotate(text.command("download"), { effects: FETCH, output: { entity: "model" } }))
+    reachesOtherService(annotate(text.command("download"), {
+        effects: FETCH,
+        output: { entity: "model" },
+        examples: [`${tool} models text download ${DEFAULT_TEXT_MODEL}`],
+    }))
         .argument("<model>", "a model id from `models text list`")
         .addOption(new Option("--accept-terms", "accept the model's licence terms, for a model that has its own"))
         .description("download an embedding model once, checked against the sha256 this version expects")
@@ -131,7 +140,7 @@ export const modelsCommand = (messenger) => {
         }, { unbounded: true });
     });
     const key = text.command("key").description("API keys for embedding and analysis providers");
-    grantsAuthority(annotate(key.command("set"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(key.command("set"), { effects: LOCAL_WRITE, examples: [`${tool} models text key set openai`] }))
         .argument("<provider>", "openai, anthropic, or the host of a --base-url server that wants a key")
         .description("store a key, typed at a hidden prompt or piped on stdin — never as an argument")
         .action(async function (provider) {
@@ -145,7 +154,7 @@ export const modelsCommand = (messenger) => {
             renderAnswer(this, context, itemOf({ provider, stored: source }));
         });
     });
-    grantsAuthority(annotate(key.command("remove"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(key.command("remove"), { effects: LOCAL_WRITE, examples: [`${tool} models text key remove openai`] }))
         .argument("<provider>", "openai, anthropic, or a server's host")
         .description("forget a stored key")
         .action(async function (provider) {

package/dist/cli/messenger/polls-command.js

@@ -22,7 +22,10 @@ export const pollsCommand = (messenger) => {
     const polls = new Command("polls").description(messenger.pollClose === false
         ? "read a poll, vote in it, create one"
         : "read a poll, vote in it, close your own, create one");
-    annotate(polls.command("show"), { effects: REMOTE_READ })
+    annotate(polls.command("show"), {
+        effects: REMOTE_READ,
+        examples: [`${messenger.app.command} personal polls show "Book club" 101`],
+    })
         .description("a poll and its answer ids, as the message carries it now")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the id of the message that carries the poll")
@@ -35,7 +38,10 @@ export const pollsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(poll)));
     });
     if (messenger.pollVoters)
-        polls.addCommand(withQuery(annotate(annotate(new Command("voters"), { effects: REMOTE_READ })
+        polls.addCommand(withQuery(annotate(annotate(new Command("voters"), {
+            effects: REMOTE_READ,
+            examples: [`${messenger.app.command} personal polls voters "Book club" 101 answers:0 --limit 10`],
+        })
             .description(messenger.pollAnonymous === false
             ? "who voted for what, newest first"
             : "who voted for what, newest first; not in an anonymous poll")
@@ -60,7 +66,10 @@ export const pollsCommand = (messenger) => {
                 args: { chat, message, ...(words.length > 0 ? { query: words.join(" ") } : {}) },
             }), lines(({ voted_at, person_id, name, answers }) => [voted_at, name ?? person_id, answers.join(",")].join("  ")));
         }));
-    annotate(polls.command("vote"), { effects: REMOTE_WRITE })
+    annotate(polls.command("vote"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal polls vote "Book club" 101 0`],
+    })
         .description(messenger.pollAnonymous === false
         ? "vote in a poll, or take your vote back; the others see it"
         : "vote in a poll, or take your vote back; the others see it unless the poll is anonymous")
@@ -85,7 +94,10 @@ export const pollsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(voted)));
     });
     if (messenger.pollClose !== false)
-        annotate(polls.command("close"), { effects: REMOTE_WRITE })
+        annotate(polls.command("close"), {
+            effects: REMOTE_WRITE,
+            examples: [`${messenger.app.command} personal polls close "Book club" 101`],
+        })
             .description("close your own poll; nobody can vote after that, and it cannot be reopened")
             .argument("<chat>", messenger.chatArgument)
             .argument("<message>", "the id of your own message that carries the poll")
@@ -94,7 +106,10 @@ export const pollsCommand = (messenger) => {
             const closed = await context.withMessenger((connection) => guardedClose(context.guard, connection, { chat, message: message.trim() }));
             renderAnswer(this, context, itemOf(snakeKeys(closed)));
         });
-    const create = annotate(polls.command("create"), { effects: REMOTE_WRITE })
+    const create = annotate(polls.command("create"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal polls create "Book club" "Which day?" Monday Tuesday`],
+    })
         .description(messenger.pollAnonymous === false
         ? "send a poll to a chat, as a message of its own; everyone sees who voted for what"
         : "send a poll to a chat, as a message of its own; public unless --anonymous")

package/dist/cli/messenger/records-command.js

@@ -82,7 +82,11 @@ export const callsCommand = (messenger) => {
 };
 /** `chats delete` and `chats clear` — for this account only; at the default level they ask first. */
 export const chatDeletionCommands = (messenger) => [
-    annotate(new Command("delete"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(new Command("delete"), {
+        effects: REMOTE_WRITE,
+        mcp: false,
+        examples: [`${messenger.app.command} personal chats delete "Book club"`],
+    })
         .description("delete a chat from this account; the others in it keep it and its messages")
         .argument("<chat>", messenger.chatArgument)
         .addOption(ownerOnlyOption("--allow-dangerous", "go ahead without the question an ask level puts before a deletion"))
@@ -90,7 +94,11 @@ export const chatDeletionCommands = (messenger) => [
         const context = messengerContext(this, messenger);
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.admin.deleteChat(chat)))));
     }),
-    annotate(new Command("clear"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(new Command("clear"), {
+        effects: REMOTE_WRITE,
+        mcp: false,
+        examples: [`${messenger.app.command} personal chats clear "Book club"`],
+    })
         .description("delete every message in a chat for this account; the others in it keep theirs")
         .argument("<chat>", messenger.chatArgument)
         .addOption(ownerOnlyOption("--allow-dangerous", "go ahead without the question an ask level puts before a deletion"))

package/dist/cli/messenger/search-command.js

@@ -6,6 +6,7 @@ import { searchNotesOf } from "../../services/notes-search.js";
 import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
+import { commandAt } from "../steps.js";
 import { messengerContext } from "./context.js";
 import { conversationsSearchCommand } from "./conversations-command.js";
 import { messagesSearchCommand } from "./messages-search-command.js";
@@ -157,5 +158,16 @@ export const searchCommand = (messenger, { topics = false } = {}) => {
         .addCommand(conversationsSearchCommand(messenger));
     if (topics)
         search.addCommand(topicsSearchCommand(messenger));
+    for (const [path, args] of Object.entries({
+        all: "draft",
+        conversations: '"Reviewing the project draft"',
+        messages: "draft --limit 10",
+        notes: "draft --limit 10",
+        topics: '"Book club" draft',
+    })) {
+        const command = commandAt(search, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal search ${path} ${args}`] });
+    }
     return search;
 };

package/dist/cli/messenger/server-command.js

@@ -181,21 +181,24 @@ export const serverCommand = (messenger, options = {}) => {
         return ["--idle", idle];
     };
     const withIdle = (sub) => options.idle ? sub.option("--idle <duration>", "stop after this long with nobody using it — 15m, 1h") : sub;
-    withIdle(destroysNothing(annotate(command.command("start"), { effects: LOCAL_WRITE })).description("start serve in the background — through the unit if one is installed — and answer once it connects")).action(async function () {
+    withIdle(destroysNothing(annotate(command.command("start"), { effects: LOCAL_WRITE, examples: [`${app.command} personal server start`] })).description("start serve in the background — through the unit if one is installed — and answer once it connects")).action(async function () {
         await start(prepare(this), idleArgs(this));
     });
-    destroysNothing(annotate(command.command("stop"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("stop"), { effects: LOCAL_WRITE, examples: [`${app.command} personal server stop`] }))
         .description("stop this profile's serve — through the unit if it runs under one")
         .action(async function () {
         await stop(prepare(this));
     });
-    withIdle(destroysNothing(annotate(command.command("restart"), { effects: LOCAL_WRITE })).description("stop it and start it again")).action(async function () {
+    withIdle(destroysNothing(annotate(command.command("restart"), {
+        effects: LOCAL_WRITE,
+        examples: [`${app.command} personal server restart`],
+    })).description("stop it and start it again")).action(async function () {
         const args = idleArgs(this);
         const prepared = prepare(this);
         await stop({ ...prepared, say: () => { } });
         await start(prepared, args);
     });
-    annotate(command.command("status"), { effects: LOCAL_READ })
+    annotate(command.command("status"), { effects: LOCAL_READ, examples: [`${app.command} personal server status`] })
         .description("whether serve runs for this profile, since when, who started it, and the unit if there is one")
         .action(async function () {
         const prepared = prepare(this);
@@ -261,7 +264,10 @@ export const serverCommand = (messenger, options = {}) => {
             ...flood.deadlines.map((one) => `Asked to wait before ${one.operation}${one.chatId ? ` in chat ${one.chatId}` : ""} until ${clock(one.until)}.`),
         ], outdated ? [nextStep("server.restart", { args: {} })] : []);
     });
-    annotate(command.command("logs"), { effects: LOCAL_READ })
+    annotate(command.command("logs"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} personal server logs --limit 20`],
+    })
         .description("serve's latest log lines — from the journal under systemd, else its log file")
         .option("-n, --limit <n>", "how many lines", (value) => wholeNumber(value), 50)
         .action(async function () {
@@ -272,7 +278,10 @@ export const serverCommand = (messenger, options = {}) => {
             context.renderer.note(`no log yet for profile ${unit.profile}`);
         renderAnswer(this, context, wholeList("server logs", text.split("\n").filter(Boolean)), () => text ? readableLog(text.replace(/\n$/, "")) : "");
     });
-    grantsAuthority(annotate(command.command("install"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("install"), {
+        effects: LOCAL_WRITE,
+        examples: [`${app.command} personal server install`],
+    }))
         .description("write a systemd user unit or a launchd agent for this profile; starts nothing")
         .action(function () {
         const { context, platform, unit, say } = prepare(this);
@@ -287,7 +296,10 @@ export const serverCommand = (messenger, options = {}) => {
             `A daily follow-up review is off. To turn it on: ${app.command} ${unit.profile} schedule agent follow-ups claude "${followUpsPrompt(app.command)}" --at 08:30`,
         ]);
     });
-    grantsAuthority(annotate(command.command("uninstall"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("uninstall"), {
+        effects: LOCAL_WRITE,
+        examples: [`${app.command} personal server uninstall`],
+    }))
         .description("remove this profile's unit; stop it first")
         .action(async function () {
         const { context, platform, unit, say } = prepare(this);

package/dist/cli/messenger/stats-command.js

@@ -12,6 +12,7 @@ import { EVENTS_DAYS } from "../../services/chats.js";
 import { dateWindow } from "../../services/moment.js";
 import { destroysNothing, LOCAL_WRITE } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
+import { commandAt } from "../steps.js";
 import { adminStatisticsCommand } from "./admin-statistics-command.js";
 import { statsCommand as chatStatsCommand } from "./chats-stats-command.js";
 import { messengerContext } from "./context.js";
@@ -84,5 +85,30 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
             context.renderer.note("partial data — the chart shows lower bounds");
         renderAnswer(this, context, chartAnswer(chart, chartFile, window.meta));
     });
+    const examples = {
+        charts: '"Book club" --output ./activity.svg',
+        "chats newcomers": '"Book club"',
+        "chats retention": '"Book club"',
+        "chats show": '"Book club"',
+        "contacts evidence": '101 --selection "$selection" --component messages',
+        "contacts responses": '--chat "Project room"',
+        "contacts top": '--chat "Book club" --limit 10',
+        "messages counters refresh": '--chat "Book club" --dry-run',
+        "messages counters show": '--chat "Book club" --limit 10',
+        "messages discussion": '--chat "Book club"',
+        "messages evidence": '"$message" --selection "$selection" --component reactions',
+        "messages show": '--chat "Book club" --by day',
+        "messages top": '--chat "Book club" --limit 10',
+        "messages unanswered": '--chat "Project room"',
+        "tasks show": '--chat "Project room"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(stats, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal stats ${path} ${args}`] });
+    }
+    for (const target of ["messages", "contacts"]) {
+        commandAt(stats, `${target} evidence`)?.addHelpText("after", `\nSet selection to drilldown.selection from stats ${target} top; copy the matching row's ${target === "messages" ? "message locator into message" : "person id"}.\n`);
+    }
     return stats;
 };