@wirecat/cli-core 0.394.0 → 0.395.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ 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

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/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/tasks-command.js

@@ -130,7 +130,10 @@ export const tasksCommand = (messenger) => {
         ? "agent"
         : "owner";
     const tasks = new Command("tasks").description("what waits on you — unanswered questions, mentions, requests, promises — kept in the local store; review and serve add them");
-    withQuery(annotate(tasks.command("list"), { effects: LOCAL_READ }).description("tasks, oldest first, with their message or note source"), TASK_QUERY)
+    withQuery(annotate(tasks.command("list"), {
+        effects: LOCAL_READ,
+        examples: [`${tool} personal tasks list --limit 10`],
+    }).description("tasks, oldest first, with their message or note source"), TASK_QUERY)
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .action(async function (words) {
         const context = messengerContext(this, messenger);
@@ -146,7 +149,10 @@ export const tasksCommand = (messenger) => {
         if (found.items.length === 0 && context.format === "pretty")
             context.renderer.note("no tasks — review, inbox and messages sync add them as questions arrive");
     });
-    planOptions(destroysNothing(annotate(tasks.command("add"), { effects: LOCAL_WRITE }))
+    planOptions(destroysNothing(annotate(tasks.command("add"), {
+        effects: LOCAL_WRITE,
+        examples: [`${tool} personal tasks add note:101 --type promise --category documents --title "Review draft"`],
+    }))
         .description("add a task for a stored message or note — a promise, a request")
         .argument("<message>", "a message locator, msg:<provider>/<account>/<chat>/<message>, or note:<id>")
         .requiredOption("--type <type>", "the task's type: question, request, mention or promise", taskTypeOf)
@@ -176,7 +182,10 @@ export const tasksCommand = (messenger) => {
         else if (followUpOf && context.format === "pretty")
             context.renderer.note(`${task.key ?? task.id} follows up ${followUpOf.key} (${followUpOf.status}), which stays closed: linked follow-up-of`);
     });
-    planOptions(destroysNothing(annotate(tasks.command("plan"), { effects: LOCAL_WRITE }))
+    planOptions(destroysNothing(annotate(tasks.command("plan"), {
+        effects: LOCAL_WRITE,
+        examples: [`${tool} personal tasks plan DOC-12 --title "Review draft"`],
+    }))
         .summary("set a task's title, description, due date, next check, category and assignee")
         .description("set a task's title, description, due date, next check, category and assignee; nothing reaches the messenger")
         .argument("<task>", "the task's id or key, as tasks list shows it")
@@ -189,7 +198,10 @@ export const tasksCommand = (messenger) => {
         const planned = await context.withServices((services) => services.tasks.plan(id, plan, writerOf(this)));
         renderAnswer(this, context, itemOf(snakeKeys(planned)), () => `${card(planned)}\n`);
     });
-    destroysNothing(annotate(tasks.command("link"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(tasks.command("link"), {
+        effects: LOCAL_WRITE,
+        examples: [`${tool} personal tasks link DOC-12 https://example.com/draft`],
+    }))
         .description("link a task to messages, chats, people or URLs — or to another task: task:<id>")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .argument("[targets...]", "msg: locators, person:<id>, document:<id>, note:<id>, a URL; or task:<id>, which links two project tasks")
@@ -209,7 +221,7 @@ export const tasksCommand = (messenger) => {
         if (!("relations" in linked) && linked.review && context.format === "pretty")
             context.renderer.note(`${linked.review} possible duplicate pair(s) went to tasks duplicates`);
     });
-    annotate(tasks.command("show"), { effects: LOCAL_READ })
+    annotate(tasks.command("show"), { effects: LOCAL_READ, examples: [`${tool} personal tasks show DOC-12`] })
         .description("one task: its plan and everything linked to it")
         .argument("<task>", "the task's id or key, as tasks list shows it")
         .action(async function (id) {
@@ -307,7 +319,7 @@ export const tasksCommand = (messenger) => {
         const unmerged = await context.withServices((services) => services.tasks.unmerge(dup, writerOf(this)));
         renderAnswer(this, context, itemOf(snakeKeys(unmerged)), () => `${card(unmerged.task)}\n`);
     });
-    withQuery(annotate(tasks.command("agenda"), { effects: LOCAL_READ })
+    withQuery(annotate(tasks.command("agenda"), { effects: LOCAL_READ, examples: [`${tool} personal tasks agenda`] })
         .summary("what needs a look today: tasks due, chats you owe or wait on, what you are owed")
         .description("what needs a look today, from the local store and without message text: tasks overdue, due or to check, " +
         "chats where you owe an answer, chats where you wait for one, open tasks someone else does"), AGENDA_QUERY)

package/dist/cli/runs/command.js

@@ -18,7 +18,11 @@ export const runsCommand = (app) => {
             throw new CliError("not_found", `no recorded run "${id}" — \`${lineOf(from, "runs list")}\` shows them`);
         return found;
     };
-    annotate(command.command("list"), { effects: LOCAL_READ, mcp: false })
+    annotate(command.command("list"), {
+        effects: LOCAL_READ,
+        mcp: false,
+        examples: [`${app.command} runs list --limit 10`],
+    })
         .description("recorded runs, newest first")
         .option("--limit <n>", "how many to show", positiveCount("--limit"), 20)
         .option("--page <n>", "which page, starting at 1", positiveCount("--page"), 1)
@@ -32,7 +36,7 @@ export const runsCommand = (app) => {
         if (runs.length === 0)
             renderer.note("nothing recorded — a run is kept with `--record`, or when it fails");
     });
-    annotate(command.command("show"), { effects: LOCAL_READ, mcp: false })
+    annotate(command.command("show"), { effects: LOCAL_READ, mcp: false, examples: [`${app.command} runs show run-101`] })
         .argument("<run-id>", `an id from \`${app.command} runs list\``)
         .description("one run: what it was, how it ended, and every event it logged")
         .option("--problems", "only failed responses, warnings and crashes")
@@ -53,7 +57,10 @@ export const runsCommand = (app) => {
         if (shown.length < events.length)
             renderer.note(`${events.length - shown.length} other events — \`${lineOf(this, `runs show ${id}`)}\` shows them all`);
     });
-    annotate(command.command("search"), { effects: LOCAL_READ })
+    annotate(command.command("search"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} runs search timeout --limit 10`],
+    })
         .description("search recorded diagnostic metadata and events; no message contents")
         .argument("[query]", "case-insensitive literal diagnostic text")
         .addOption(new Option("--status <status>", "run outcome").choices(["success", "failed", "partial", "running"]))
@@ -79,7 +86,7 @@ export const runsCommand = (app) => {
             since_time: options.sinceTime,
         }));
     });
-    annotate(command.command("path"), { effects: NO_EFFECTS, mcp: false })
+    annotate(command.command("path"), { effects: NO_EFFECTS, mcp: false, examples: [`${app.command} runs path run-101`] })
         .argument("<run-id>", `an id from \`${app.command} runs list\``)
         .description("the directory holding one run")
         .action(function (id) {

package/dist/cli/skill-command.js

@@ -13,8 +13,13 @@ export const skillCommand = (app, skill) => {
     }, SHARED_SKILLS);
     // An installed skill is instructions every later agent follows.
     const install = command.commands.find((sub) => sub.name() === "install");
-    if (install)
+    if (install) {
         grantsAuthority(install);
+        annotate(install, { examples: [`${app.command} skill install --for agents`] });
+    }
+    const show = command.commands.find((sub) => sub.name() === "show");
+    if (show)
+        annotate(show, { examples: [`${app.command} skill show`, `${app.command} skill show follow-ups`] });
     return annotate(command, { mcp: false });
 };
 /** Skills this package ships for every CLI on it, printed by `skill show <name>`: `skills/` beside `dist/` and `src/`. */

package/dist/entities/index.d.ts

@@ -2857,7 +2857,7 @@ export declare const ENTITIES: {
     readonly saved_search: v.StrictObjectSchema<{
         readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
         readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
-        readonly command: v.PicklistSchema<["search", "stats", "message-top", "author-top", "admin-statistics"], undefined>;
+        readonly command: v.PicklistSchema<["search", "stats", "message-top", "author-top", "admin-statistics", "meetings-search"], undefined>;
         readonly params: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>;
         readonly language: v.StringSchema<undefined>;
         readonly version: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;

package/dist/entities/saved-search.d.ts

@@ -4,7 +4,7 @@ export declare const savedSearch: v.StrictObjectSchema<{
     readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
     /** `null` for a run in the history. */
     readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
-    readonly command: v.PicklistSchema<["search", "stats", "message-top", "author-top", "admin-statistics"], undefined>;
+    readonly command: v.PicklistSchema<["search", "stats", "message-top", "author-top", "admin-statistics", "meetings-search"], undefined>;
     /** The query and the options it runs with, as the command took them. */
     readonly params: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>;
     readonly language: v.StringSchema<undefined>;

package/dist/entities/saved-search.js

@@ -5,7 +5,7 @@ export const savedSearch = v.strictObject({
     id,
     /** `null` for a run in the history. */
     name: v.nullable(text),
-    command: v.picklist(["search", "stats", "message-top", "author-top", "admin-statistics"]),
+    command: v.picklist(["search", "stats", "message-top", "author-top", "admin-statistics", "meetings-search"]),
     /** The query and the options it runs with, as the command took them. */
     params: v.record(v.string(), v.unknown()),
     language: text,

package/dist/errors/reasons.js

@@ -51,6 +51,7 @@ const OTHERS = [
     validation("ranking.invalid", "the ranking is not valid"),
     validation("selection.changed", "the stored selection changed meanwhile"),
     validation("selection.invalid", "the selection is not valid"),
+    validation("search.kind", "the saved search belongs to another kind of search: messages or meetings"),
     ["selection.out-of-scope", "permission_error", "the selection reaches outside what this profile may read"],
     validation("stemmer.invalid", "the stemmer is not valid for that script"),
     validation("stemmer.newer", "the stems were built by a newer tool"),