@wirecat/cli-core 0.398.0 → 0.400.0

package/CHANGELOG.md

@@ -5,6 +5,112 @@ 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.400.0 — 24.10.2026
+
+### Fixed
+
+- **Downloads skip service events and keyboards.** A message whose only attachment is a group event (`control`) or an inline keyboard no longer makes a media archive or `attachments download` fail with `provider.invalid-response`; both count as non-files like polls and links.
+
+- Account lists accept profile and current-profile query terms, and declare their answer fields for discovery and projection.
+
+- **Account change and privacy schemas.** Profile updates, ended sessions and privacy reads and writes declare their existing answers for field discovery and projection. Privacy fields remain optional where a messenger does not expose a setting.
+
+- **`contacts timeline` stays in its account for tasks.** A task assigned to the person now shows only when its project belongs to the asked account or to no account; before, tasks from another account of the same messenger showed too. Task rows now also name the account of their project.
+
+### Added
+
+- **Meeting answer schemas.** `review`, `mentions list`, `stats meetings show` and `top`, `meetings people`, `meetings passage` and `meetings task-proposal` declare their answer entities (`meeting_review`, `meeting_link`, `meeting_stats`, `meeting_speaker`, `meeting_participants`, `meeting_passage`, `meeting_task_proposal`) for field discovery and projection. `meetings/` exports the item builders the meeting CLIs share: `meetingReviewItem`, `meetingLinkItem`, `meetingStatsItem`, `meetingSpeakerItem`.
+
+- **Listener answers declare their fields.** Live messages and events, and the final serve summary, expose exact schemas for discovery and cross-CLI output contracts. Provider-only attachment references stay private.
+
+- **Poll answer schemas.** Poll reads, vote and close receipts, and newly sent poll messages declare their answer entities for field discovery and projection.
+
+- **Image embedding progress has declared fields.** Discovery and projection describe the bounded batch’s model, embedded, skipped and failed counts, and whether more pictures remain. The existing receipt and processing behavior stay unchanged.
+
+- **Model key receipt schemas.** Storing or removing a model-provider key declares its provider and storage sources for field discovery and projection. No credential value appears in either schema or answer.
+
+- Recipient lists accept ID and title queries without changing the allowlist state. Recipient commands declare their answer schemas for discovery and field projection.
+
+- **Cached chat metadata declares its answers.** Cached reads describe absent or populated metadata; refresh receipts describe each successful chat or failure and whether more chats remain. Existing keys and cached-read behavior stay unchanged.
+
+- **Contact answers have declared fields.** Address-book writes, private aliases and note removal, activity, bot checks, identity links, context and preparation expose their exact answer schemas. Context describes both the cross-account report and selected-chat message windows at every detail level. Field projection recognizes both shapes and refuses unknown fields before reading contact data. CLI, SDK and MCP receipts keep their existing shapes.
+
+- **Mention answers have declared fields.** Mentions, details, linked domains, confirmed places, decisions and rebuild receipts expose their existing schemas for discovery, JSON field projection and MCP. Numeric local IDs and cross-account decision behavior stay unchanged.
+
+- **Reaction answer schemas.** Add and remove declare the same reaction-change entity, including the operation id and a null reaction when removed. Field discovery and projection now describe these write receipts.
+
+- **Tag changes declare their results.** Add and remove expose precise chat, contact, message and task target shapes. Automatic tagging describes each classification or failed chat, including preview status and remaining work; existing receipts and ownership claims stay unchanged.
+
+- Send history includes a concrete example in help and command discovery.
+
+- Chat document lists accept a source-message reference query, filtered in the store before link pagination, and declare their document-link answer fields.
+
+- Doctor reports include a concrete creation example in help and command discovery.
+
+- Send-attempt lists accept queries over their stored metadata before pagination. Continuation steps keep the query, and discovery declares the answer fields.
+
+- **Clearing search history declares its receipt.** Discovery and JSON projection expose the existing cleared count; saved searches remain untouched.
+
+- Recorded-run lists accept metadata queries before pagination, and recorded-run commands declare their answer schemas. Continuation steps keep the query.
+
+- **Message read and write schemas.** Showing a message, sending, editing, forwarding, pinning, starring and deleting declare their existing answer entities for field discovery and projection. Write receipts retain their operation id.
+
+- **Chat-state write schemas.** Muting, archiving, pinning, marking unread, deleting a chat and clearing its history declare their existing write receipts for field discovery and projection, including their operation ids.
+
+- **Chat administration declares its answers.** Invite inspection, posting identities, read receipts, roster fetches, membership and group changes, invitations, join requests, administrators, folder writes and moderation expose their exact existing result fields, including operation identifiers and partial outcomes.
+
+- **Message read schemas.** Evidence packets, voice transcripts and conversation links declare separate answer entities for field discovery and projection, preserving existing response keys.
+
+- **Conversation results have declared schemas.** Builds, analysis, message batches, link changes, embedding progress, readiness, related conversations and search hits describe their existing answer fields for discovery and projection, including bounded preparation and empty batches.
+
+- **Message context, downloads and sync have declared answers.** Context describes both message windows and bounded thread reports. Downloads retain file paths and partial extraction results; sync describes estimates, chat and all-chat progress, preparation and background jobs. General chat evidence packets and exact statistics evidence now explain their separate purposes in help and the guide.
+
+- Analysis-consent lists accept chat and provider-identity queries, and consent commands declare their answer fields. Reading a filtered list leaves remembered permissions unchanged.
+
+- **Attachment and media archive results have declared fields.** Extraction reports and streamed file rows, retained-file transfers, saved text, archive downloads, integrity checks, relocations and timer management describe their existing receipts. MCP resource/image transfers keep byte metadata in the same shape while carrying bytes separately.
+
+- Tracked-chat lists accept a query over chat IDs and titles, filtered in the store. Tracking commands declare their answer schemas for field projection and discovery.
+
+- **Task actions declare their answers.** Task cards, source previews, creation and close receipts, relationships, similarity and duplicate decisions, merges, categories and rule scans expose their exact existing fields for discovery and projection. Stored tasks and actions keep their behavior.
+
+- **Store commands declare their answers.** Archive coverage, exports, selected-chat clearing, gap plans and repairs, background jobs, health checks, maintenance and backup/restore receipts describe their existing result fields. Missing-file and partial-result variants remain explicit; stored data and command behavior stay unchanged.
+
+### Changed — may break callers
+
+- **Watch uses the shared JSONL contract.** Read each message or event from `{ type: "item", data }` and wait for the final `type: "end"` record. Message and event fields are snake_case, message values use the canonical read shape with references, and live counter observations remain available. Normal stops and timeouts finish complete; a source failure finishes incomplete and returns its failure code. Update readers of the old raw lines.
+
+- **MCP offers the commands that change what a later run may do, behind `mcp.authority`.** `config set|unset`, `schedule command|agent|remove`, auto-reply rules and consents, recipients, chat rules, `server install`, `skill install`, model keys, media archive timers and `flood clear` are MCP tools again, offered only where the profile sets `permissions.mcp.authority` to `allow`; it is `deny` by default, so nothing changes until the owner turns it on. An agent cannot change that key through `config set`. What to change in a CLI: `grantsAuthority` no longer adds `mcp: false`, so `commands --json` no longer marks these commands, and a catalogue built with `toolsFromCommands` without `levels` lists them; update a pinned catalogue and a document that lists what MCP leaves out. A command of the CLI's own marked `grantsAuthority` (max `recipients add`) is gated the same way. A caller of `createBotServer` passes `authority: changesAuthorityAt(root)` to hide them; without it they are listed and refuse when called.
+
+- **Diagnostic search is `search runs`.** Replace `runs search`; saved MCP requests use the new command path. Filters are query terms: `status:failed`, `error_code:timeout`, `operation:messages.download` and `profile:work`, alongside literal diagnostic words. Unsupported operators are refused; time bounds and paging remain options. The local search still needs no linked messenger profile, filters before pagination and returns diagnostic fields without message contents. No alias remains for the retired path.
+
+- **Statistics select rows through their query.** Rankings use `message_kind:` with `posts`, `comments` or `all`, and author rankings `min_messages:5`; discussion uses `min_views:10` and `max_replies:0`; unanswered questions use `older_than:24h`. These predicates replace the corresponding filter flags and reach the existing SQL selection before aggregation or row limits. The same reports select chats with `chat:` and exact words with `exact:` instead of `--chat` and `--exact`; source and timezone remain options. Saved CLI/MCP requests must migrate. Stored selections and SDK parameters retain their meanings.
+
+## 0.399.0 — 23.10.2026
+
+### Changed — may break callers
+
+- **Flags have one meaning.** Use `--analysis-provider` for analysis, `--embedding-provider` for vector computation, `--consent-provider` for revoking a recorded provider identity, `--claim` for tag ownership, `--answer-model` for removing stored answers and `--template-mode` for reply templates. `inbox` and `review` take `kind:group,channel` in their query. Group message lifetime is `--disappear-after`, a duration or `off`. Legacy CLI spellings remain hidden for one release and cannot be combined with their replacements. MCP callers use the canonical argument names and `query` for chat kinds; update saved MCP requests.
+
+- cli-core requires cli-base 0.50.2 or newer within the 0.50 line for the approved option roles and messenger vocabulary.
+
+- **Private contact notes use `--text-file`.** `--file` continues to work as a hidden compatibility alias; giving both is refused before any note is changed. New help and discovery reserve `--file` for message attachments.
+
+### Fixed
+
+- **Count and grouping placeholders match the shared vocabulary.** Processing limits use `<n>` and statistics grouping uses `<group>` across supported fields and calendar units; accepted values and defaults stay the same.
+
+### Added
+
+- **The shared `bot` commands have help examples and short summaries.** Each leaf under `bot` shows one to three
+  examples in the calling CLI's own words, and every summary fits 80 characters; `bot recipients add|remove` describe
+  their `<chat>`. A CLI that baselined these for `command-example-count`, `command-help-too-long` or
+  `missing-argument-help` sees "stale baseline entry" and removes the lines; tg, max and wa grow no baseline for them.
+- **`Messenger.joinRequestsByLink`**: whether `chats requests accept|decline --all` can be narrowed with `--link`;
+  yes when unset. `joinRequestsAll` now turns on `--all` alone, so a messenger that answers every request at once
+  but does not say which invite link each came by (MAX) offers `--all` without `--link`.
+
 ## 0.398.0 — 23.10.2026
 
 ### Added

package/dist/analysis/consents.d.ts

@@ -4,9 +4,14 @@ export interface AnalysisConsent {
     provider: string;
     at: string;
 }
-export declare const analysisConsents: (store: MessageStore, account: AccountKey) => {
-    list: () => Promise<AnalysisConsent[]>;
-    has: (chat: string, provider: string) => Promise<boolean>;
-    remember: (chat: string, provider: string) => Promise<void>;
-    revoke: (chat?: string, provider?: string) => Promise<void>;
-};
+export interface AnalysisConsentFilter {
+    chat?: string;
+    provider?: string;
+}
+export interface AnalysisConsents {
+    list(filter?: AnalysisConsentFilter): Promise<AnalysisConsent[]>;
+    has(chat: string, provider: string): Promise<boolean>;
+    remember(chat: string, provider: string): Promise<void>;
+    revoke(chat?: string, provider?: string): Promise<void>;
+}
+export declare const analysisConsents: (store: MessageStore, account: AccountKey) => AnalysisConsents;

package/dist/analysis/consents.js

@@ -1,7 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 const KEY = "analysis-consents-v1";
 export const analysisConsents = (store, account) => {
-    const list = async () => {
+    const list = async (filter) => {
         const state = await store.sync.syncState(account, KEY);
         if (!state)
             return [];
@@ -10,7 +10,10 @@ export const analysisConsents = (store, account) => {
             if (!Array.isArray(items) ||
                 items.some((item) => !item || typeof item.chat !== "string" || typeof item.provider !== "string" || typeof item.at !== "string"))
                 throw new Error("invalid");
-            return items;
+            return filter === undefined
+                ? items
+                : items.filter((item) => (filter.chat === undefined || item.chat === filter.chat) &&
+                    (filter.provider === undefined || item.provider === filter.provider));
         }
         catch {
             throw new CliError("configuration_error", "stored analysis consent is invalid; revoke it before running analysis");

package/dist/cli/analysis-choice.d.ts

@@ -3,6 +3,7 @@ import type { AnalysisProvider } from "../analysis/provider.js";
 import type { AppIdentity } from "../ports/app.js";
 import type { Settings } from "./settings.js";
 export interface AnalysisOptions {
+    analysisProvider?: string;
     provider?: string;
     model?: string;
     baseUrl?: string;

package/dist/cli/analysis-choice.js

@@ -2,6 +2,9 @@ import { CliError } from "@wirecat/cli-base";
 import { endpoint } from "../analysis/settings.js";
 import { embeddingKeys, endpointKeyName } from "../embeddings/keys.js";
 export const analysisChoice = (options, app, settings, env, keyring) => {
+    if (options.analysisProvider !== undefined && options.provider !== undefined)
+        throw new CliError("validation_error", "give --analysis-provider or its legacy --provider spelling, not both");
+    options = { ...options, provider: options.analysisProvider ?? options.provider };
     const configured = { ...settings.models?.default, ...settings.models?.analysis };
     settings = {
         ...settings,

package/dist/cli/bot/admins.js

@@ -9,6 +9,7 @@ import { renderAnswer, snakeKeys } from "../envelope.js";
 import { rightsOf } from "../messenger/admin-commands.js";
 import { renderItem, wholeList } from "../messenger/chat-answers.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan } from "./messages.js";
 const CHAT = "a chat id, or the title of a chat this bot has seen";
 const PERSON = "the person's user id";
@@ -23,7 +24,7 @@ const personOf = (typed) => {
 export const botAdminsCommand = (bot) => {
     const offered = bot.adminRights ?? ADMIN_RIGHTS;
     const command = new Command("admins").description("the admins of a chat the bot is an admin in");
-    annotate(command.command("list"), { effects: REMOTE_READ })
+    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "chats admins list Team") })
         .description("the chat's admins and what each may do")
         .argument("<chat>", CHAT)
         .action(async function (chat) {
@@ -35,7 +36,10 @@ export const botAdminsCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot chats admins list", admins.map(snakeKeys)));
         });
     });
-    annotate(command.command("add"), { effects: REMOTE_WRITE })
+    annotate(command.command("add"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "chats admins add Team 42 --title Helper"),
+    })
         .description("make a member an admin with these rights")
         .argument("<chat>", CHAT)
         .argument("<person>", PERSON)
@@ -61,7 +65,10 @@ export const botAdminsCommand = (bot) => {
             });
         });
     });
-    annotate(command.command("remove"), { effects: REMOTE_WRITE })
+    annotate(command.command("remove"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "chats admins remove Team 42"),
+    })
         .description("take an admin's rights back; they stay a member")
         .argument("<chat>", CHAT)
         .argument("<person>", PERSON)
@@ -85,7 +92,10 @@ export const botAdminsCommand = (bot) => {
  */
 export const botMembersCommand = (bot) => {
     const command = new Command("members").description("the people in a chat the bot is an admin in");
-    annotate(command.command("remove"), { effects: REMOTE_WRITE })
+    annotate(command.command("remove"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "chats members remove Team 42 --block"),
+    })
         .description("take a person out of a chat; their messages stay")
         .argument("<chat>", CHAT)
         .argument("<person>", PERSON)

package/dist/cli/bot/command.js

@@ -9,6 +9,7 @@ import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { renderItem, wholeList } from "../messenger/chat-answers.js";
 import { botAdminsCommand, botMembersCommand } from "./admins.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botMcpCommand } from "./mcp.js";
 import { botCan, botIdOf, botMessagesCommand } from "./messages.js";
 import { botModerateCommand, botRulesCommand } from "./moderation.js";
@@ -25,7 +26,9 @@ const secretSources = (bot, tokens) => bot.secrets?.length
     : {};
 const authCommand = (bot, tokenVariable) => {
     const auth = annotate(new Command("auth"), { mcp: false }).description("the bot token this profile uses");
-    const set = grantsAuthority(annotate(auth.command("set"), { effects: LOCAL_WRITE })).description(`check a bot token with ${bot.name ?? "the messenger"}, then keep it — typed at a hidden prompt or piped on stdin`);
+    const set = grantsAuthority(annotate(auth.command("set"), { effects: LOCAL_WRITE, examples: botExamples(bot, "auth set") }))
+        .description(`check a bot token with ${bot.name ?? "the messenger"}, then keep it — typed at a hidden prompt or piped on stdin`)
+        .summary("check a bot token, then keep it; or keep a named secret beside it");
     const secrets = bot.secrets ?? [];
     if (secrets.length > 0)
         set.option("--secret <name>", `keep this secret instead of the token, the same way: ${secrets.map((one) => `${one.name} (${one.description})`).join("; ")}`);
@@ -68,7 +71,7 @@ const authCommand = (bot, tokenVariable) => {
             });
         });
     });
-    annotate(auth.command("show"), { effects: LOCAL_READ })
+    annotate(auth.command("show"), { effects: LOCAL_READ, examples: botExamples(bot, "auth show") })
         .description("where this profile's bot token comes from, and which bot it is")
         .action(async function () {
         const context = online(botContext(this, bot), this);
@@ -85,7 +88,7 @@ const authCommand = (bot, tokenVariable) => {
             });
         });
     });
-    grantsAuthority(annotate(auth.command("remove"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(auth.command("remove"), { effects: LOCAL_WRITE, examples: botExamples(bot, "auth remove") }))
         .description("forget this profile's bot token")
         .action(async function () {
         const context = botContext(this, bot);
@@ -97,7 +100,7 @@ const authCommand = (bot, tokenVariable) => {
     });
     return auth;
 };
-const meCommand = (bot) => annotate(new Command("me"), { effects: REMOTE_READ })
+const meCommand = (bot) => annotate(new Command("me"), { effects: REMOTE_READ, examples: botExamples(bot, "me") })
     .description("the bot this profile's token belongs to: id, name and username")
     .action(async function () {
     const context = online(botContext(this, bot), this);
@@ -111,8 +114,9 @@ const meCommand = (bot) => annotate(new Command("me"), { effects: REMOTE_READ })
         }
     });
 });
-const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effects: LOCAL_READ })
+const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "list", "list --check") })
     .description(`every name on this machine that has a bot token; --check asks ${bot.name ?? "the messenger"} which bot each is`)
+    .summary("every bot profile on this machine; --check asks which bot each is")
     .option("--check", "ask the messenger who each bot is, with its token")
     .action(async function () {
     const context = botContext(this, bot);
@@ -154,14 +158,20 @@ const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effe
     });
 });
 const recipientsCommand = (bot) => {
-    const command = new Command("recipients").description("the chats this bot may write to; with no list, every chat — `clear` removes the list");
-    annotate(command.command("list"), { effects: LOCAL_READ })
+    const command = new Command("recipients")
+        .description("the chats this bot may write to; with no list, every chat — `clear` removes the list")
+        .summary("the chats this bot may write to; with no list, every chat");
+    annotate(command.command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "recipients list") })
         .description("the chats on the list, or nothing when there is no list")
         .action(async function () {
         const context = botContext(this, bot);
         await context.run(async () => renderAnswer(this, context, wholeList("bot recipients list", (context.recipients().read() ?? []).map(snakeKeys))));
     });
-    grantsAuthority(annotate(command.command("add <chat>"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("add"), {
+        effects: LOCAL_WRITE,
+        examples: botExamples(bot, "recipients add Team"),
+    }))
+        .argument("<chat>", "a chat id, `user:<id>`, or the title of a chat this bot has seen")
         .description("allow a chat: its id, `user:<id>`, or the title of a chat this bot has seen")
         .action(async function (chat) {
         const context = botContext(this, bot);
@@ -172,13 +182,17 @@ const recipientsCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot recipients list", (context.recipients().read() ?? []).map(snakeKeys)));
         });
     });
-    grantsAuthority(annotate(command.command("remove <chat>"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("remove"), {
+        effects: LOCAL_WRITE,
+        examples: botExamples(bot, "recipients remove Team"),
+    }))
+        .argument("<chat>", "the chat id, or the title as the list shows it")
         .description("take a chat off the list")
         .action(async function (chat) {
         const context = botContext(this, bot);
         await context.run(async () => renderItem(this, context, { removed: context.recipients().remove(chat) ?? null }));
     });
-    grantsAuthority(annotate(command.command("clear"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("clear"), { effects: LOCAL_WRITE, examples: botExamples(bot, "recipients clear") }))
         .description("remove the list: the bot may write to any chat again")
         .action(async function () {
         const context = botContext(this, bot);
@@ -188,21 +202,24 @@ const recipientsCommand = (bot) => {
 };
 const sendsCommand = (bot) => new Command("sends")
     .description("what this bot sent, edited and deleted from this machine — ids and outcomes, never text")
-    .addCommand(annotate(new Command("list"), { effects: LOCAL_READ })
+    .summary("what this bot sent, edited and deleted from here — never the text")
+    .addCommand(annotate(new Command("list"), { effects: LOCAL_READ, examples: botExamples(bot, "sends list") })
     .description("every send, edit and delete this bot made from this machine, with its outcome")
     .action(async function () {
     const context = botContext(this, bot);
     await context.run(async () => renderAnswer(this, context, wholeList("bot sends list", context.journal().entries().map(snakeKeys))));
 }));
 const chatsCommand = (bot) => {
-    const command = new Command("chats").description(`the chats this bot is in — ${bot.name ?? "the messenger"} gives a bot no list of them, so \`list\` shows the ones it has seen`);
-    annotate(command.command("list"), { effects: REMOTE_READ })
+    const command = new Command("chats")
+        .description(`the chats this bot is in — ${bot.name ?? "the messenger"} gives a bot no list of them, so \`list\` shows the ones it has seen`)
+        .summary("the chats this bot is in, and what it does there");
+    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "chats list") })
         .description(`chats this bot has seen on this machine — not a complete list from ${bot.name ?? "the messenger"}`)
         .action(async function () {
         const context = botContext(this, bot);
         await context.run(async () => renderAnswer(this, context, wholeList("bot chats list", context.registry.list().map(snakeKeys))));
     });
-    annotate(command.command("show"), { effects: REMOTE_READ })
+    annotate(command.command("show"), { effects: REMOTE_READ, examples: botExamples(bot, "chats show Team") })
         .description(`one chat from ${bot.name ?? "the messenger"}, and remember it`)
         .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
         .action(async function (chat) {
@@ -216,7 +233,10 @@ const chatsCommand = (bot) => {
             renderItem(this, context, found);
         });
     });
-    annotate(command.command("leave"), { effects: REMOTE_WRITE })
+    annotate(command.command("leave"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "chats leave Team"),
+    })
         .description("take the bot out of a chat; only an admin of the chat can bring it back")
         .argument("<chat>", "a chat id, or the title of a chat this bot has seen")
         .action(async function (chat) {
@@ -230,8 +250,9 @@ const chatsCommand = (bot) => {
             renderAnswer(this, context, itemOf({ operation_id: operationId, chat_id: ref, left: true }));
         });
     });
-    annotate(command.command("action"), { effects: REMOTE_WRITE })
+    annotate(command.command("action"), { effects: REMOTE_WRITE, examples: botExamples(bot, "chats action Team typing") })
         .description("show what the bot is doing in a chat — typing, sending a photo — for a few seconds")
+        .summary("show what the bot is doing in a chat, for a few seconds")
         .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
         .addArgument(new Argument("<action>", "what the chat sees").choices(BOT_ACTIONS))
         .action(async function (chat, action) {
@@ -263,6 +284,7 @@ export const botCommand = (bot) => {
     const tokenVariable = envName(bot.app, "BOT_TOKEN");
     const command = new Command("bot")
         .description(`a ${bot.name ?? "messenger"} bot, through the official Bot API and a bot token — not your personal account`)
+        .summary("a bot account, through the official Bot API and a bot token")
         .addCommand(authCommand(bot, tokenVariable))
         .addCommand(listCommand(bot, tokenVariable))
         .addCommand(chatsCommand(bot))

package/dist/cli/bot/examples.d.ts

@@ -0,0 +1,3 @@
+import type { BotMessenger } from "./port.js";
+/** Help examples for a shared bot command, in the calling CLI's own words, for a bot profile named `sales`. */
+export declare const botExamples: (bot: BotMessenger, ...lines: string[]) => string[];

package/dist/cli/bot/examples.js

@@ -0,0 +1,2 @@
+/** Help examples for a shared bot command, in the calling CLI's own words, for a bot profile named `sales`. */
+export const botExamples = (bot, ...lines) => lines.map((line) => `${bot.app.command} sales bot ${line}`);

package/dist/cli/bot/mcp.js

@@ -3,16 +3,18 @@ import { CliError } from "@wirecat/cli-base";
 import { annotate, describeProgram } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { environmentOf } from "../context.js";
-import { LOCAL_READ, REMOTE_WRITE } from "../effects.js";
+import { changesAuthorityAt, LOCAL_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
 import { serverEntry } from "../messenger/mcp-command.js";
 import { nextStep, rootOf } from "../steps.js";
 import { botContext } from "./context.js";
+import { botExamples } from "./examples.js";
 /** `bot mcp`, mounted only for a messenger that hands in its `run` on `BotMessenger.mcp`. */
 export const botMcpCommand = (bot) => {
     const { app } = bot;
     const command = annotate(new Command("mcp"), { effects: REMOTE_WRITE, lifetime: "persistent", mcp: false })
         .description(`serve this bot to an agent over MCP, on stdin and stdout — \`claude mcp add sales-bot -- ${app.command} sales bot mcp\``)
+        .summary("serve this bot to an agent over MCP, on stdin and stdout")
         .action(async function () {
         const context = botContext(this, bot);
         if (!context.tokens.read()) {
@@ -26,6 +28,7 @@ export const botMcpCommand = (bot) => {
         await serveBotOverStdio({
             bot,
             program: { run, commands: describeProgram(rootOf(this)) },
+            authority: changesAuthorityAt(rootOf(this)),
             settings: context.settings,
             levels: () => bot.resolveSettings(this.optsWithGlobals(), { env: context.env, kind: "bot" }).permissions,
             env: context.env,
@@ -33,8 +36,9 @@ export const botMcpCommand = (bot) => {
             ...(mcp.skill ? { skill: mcp.skill } : {}),
         }, context.streams.diagnostic);
     });
-    command.addCommand(annotate(new Command("config"), { effects: LOCAL_READ })
+    command.addCommand(annotate(new Command("config"), { effects: LOCAL_READ, examples: botExamples(bot, "mcp config") })
         .description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")
+        .summary("print the mcpServers entry for an MCP client; writes nothing")
         .action(function () {
         const context = botContext(this, bot);
         const { settings, env } = context;

package/dist/cli/bot/messages.js

@@ -14,6 +14,7 @@ import { messageItem } from "../messenger/message-items.js";
 import { readAll } from "../messenger/stdin.js";
 import { positiveCount } from "../paging.js";
 import { botContext } from "./context.js";
+import { botExamples } from "./examples.js";
 /** The adapter's `method`, or a refusal naming what this messenger's bot cannot do. */
 export const botCan = (adapter, method, bot, what) => {
     const found = adapter[method];
@@ -59,7 +60,10 @@ const seen = (context, message) => {
     if (/^-?\d+$/.test(message.chatId))
         context.registry.observe([{ id: message.chatId }]);
 };
-const sendCommand = (bot) => annotate(new Command("send"), { effects: REMOTE_WRITE })
+const sendCommand = (bot) => annotate(new Command("send"), {
+    effects: REMOTE_WRITE,
+    examples: botExamples(bot, 'messages send Team "Doors open at 9"', 'messages send Team "Here it is" --file report.pdf'),
+})
     .description("send a message as the bot; without [text], the text is read from stdin")
     .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
     .argument("[text]", "the message")
@@ -120,9 +124,10 @@ const sendCommand = (bot) => annotate(new Command("send"), { effects: REMOTE_WRI
         renderAnswer(this, context, written(context, botId, { operationId }, message));
     });
 });
-const listCommand = (bot) => annotate(new Command("list"), { effects: REMOTE_READ })
+const listCommand = (bot) => annotate(new Command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "messages list Team --limit 20") })
     .description(`the latest messages in a chat; where ${bot.name ?? "the messenger"} gives a bot no history, and with --offline, ` +
     "the ones this bot has seen on this machine")
+    .summary("the latest messages in a chat")
     .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
     .option("--limit <n>", "how many, the newest", positiveCount("--limit"))
     .action(async function (chat) {
@@ -155,7 +160,7 @@ const listCommand = (bot) => annotate(new Command("list"), { effects: REMOTE_REA
         show(this, context, bot, botId, messages);
     });
 });
-const showCommand = (bot) => annotate(new Command("show"), { effects: REMOTE_READ })
+const showCommand = (bot) => annotate(new Command("show"), { effects: REMOTE_READ, examples: botExamples(bot, "messages show Team 101") })
     .description("one message by its id in a chat")
     .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
     .argument("<message>", "message id")
@@ -187,7 +192,10 @@ const showCommand = (bot) => annotate(new Command("show"), { effects: REMOTE_REA
         show(this, context, bot, botId, [found], true);
     });
 });
-const editCommand = (bot) => annotate(new Command("edit"), { effects: REMOTE_WRITE })
+const editCommand = (bot) => annotate(new Command("edit"), {
+    effects: REMOTE_WRITE,
+    examples: botExamples(bot, 'messages edit Team 101 "Doors open at 10"'),
+})
     .description("replace the text of a message the bot sent")
     .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
     .argument("<message>", "message id")
@@ -217,7 +225,7 @@ const editCommand = (bot) => annotate(new Command("edit"), { effects: REMOTE_WRI
         renderAnswer(this, context, written(context, botId, { operationId }, message));
     });
 });
-const deleteCommand = (bot) => annotate(new Command("delete"), { effects: REMOTE_WRITE })
+const deleteCommand = (bot) => annotate(new Command("delete"), { effects: REMOTE_WRITE, examples: botExamples(bot, "messages delete Team 101") })
     .description("delete messages in a chat the bot can delete in; it cannot be undone")
     .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
     .argument("<messages...>", "message ids")
@@ -235,7 +243,10 @@ const deleteCommand = (bot) => annotate(new Command("delete"), { effects: REMOTE
     });
 });
 const pinCommand = (bot, pin) => {
-    const command = annotate(new Command(pin ? "pin" : "unpin"), { effects: REMOTE_WRITE })
+    const command = annotate(new Command(pin ? "pin" : "unpin"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, `messages ${pin ? "pin" : "unpin"} Team 101`),
+    })
         .description(pin ? "pin a message in a chat; quietly unless --notify" : "unpin a message in a chat")
         .argument("<chat>", "a chat id, user:<id> for a person, or the title of a chat this bot has seen")
         .argument("<message>", "message id");

package/dist/cli/bot/moderation.js

@@ -13,6 +13,7 @@ import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, ownerOnlyOption, REMOTE_WRITE
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { answerOf } from "../messenger/ask.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan, botIdOf } from "./messages.js";
 import { botFiles } from "./registry.js";
 const CHAT = "a group's id, or the title of a group this bot has seen";
@@ -34,15 +35,19 @@ const shown = (context, chatId, rules) => {
 /** `bot chats rules show|set|unset`: kept on this machine, the chat named the bot's way. */
 export const botRulesCommand = (bot) => {
     const command = new Command("rules").description("a chat's moderation rules for this bot, kept on this machine");
-    annotate(command.command("show"), { effects: LOCAL_READ })
+    annotate(command.command("show"), { effects: LOCAL_READ, examples: botExamples(bot, "chats rules show Team") })
         .description("the chat's rules; the defaults, marked not saved, if it has none yet")
         .argument("<chat>", CHAT)
         .action(function (chat) {
         const context = botContext(this, bot);
         renderAnswer(this, context, shown(context, context.chatRef(chat), rulesOf(context, bot)));
     });
-    grantsAuthority(annotate(command.command("set"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("set"), {
+        effects: LOCAL_WRITE,
+        examples: botExamples(bot, "chats rules set Team links delete"),
+    }))
         .description(`change one rule — ${RULE_KEYS.join(", ")}`)
+        .summary("change one moderation rule of a chat")
         .argument("<chat>", CHAT)
         .argument("<key>", "the rule")
         .argument("<value>", "its new value")
@@ -56,7 +61,10 @@ export const botRulesCommand = (bot) => {
         rules.set(chatId, titleOf(context, chatId), key, value);
         renderAnswer(this, context, shown(context, chatId, rules));
     });
-    grantsAuthority(annotate(command.command("unset"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("unset"), {
+        effects: LOCAL_WRITE,
+        examples: botExamples(bot, "chats rules unset Team links"),
+    }))
         .description("put one rule back to its default")
         .argument("<chat>", CHAT)
         .argument("<key>", "the rule")
@@ -136,8 +144,12 @@ const yes = (answer) => /^\s*y(es)?\s*$/i.test(answer);
  * `bot chats moderate`: the personal `chats moderate`, done by the bot. Typing it is the consent for
  * what the rules name. A removal bans unless `--no-block`.
  */
-export const botModerateCommand = (bot) => annotate(new Command("moderate"), { effects: REMOTE_WRITE })
+export const botModerateCommand = (bot) => annotate(new Command("moderate"), {
+    effects: REMOTE_WRITE,
+    examples: botExamples(bot, "chats moderate Team --dry-run"),
+})
     .description("judge a group's new messages and joins by its rules, and act as they allow — as the bot")
+    .summary("act on a group's new messages and joins by its rules, as the bot")
     .argument("<chat>", CHAT)
     .option("--since-time <time>", "judge what came after this ISO 8601 time, or 2h / 1d ago; the saved point stays")
     .option("--dry-run", "judge and plan; do nothing")