@wirecat/cli-core 0.397.0 → 0.399.0

package/CHANGELOG.md

@@ -5,6 +5,71 @@ 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.
 
+## 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
+
+- Top-level summaries, listeners and shell completion include examples in help and command discovery.
+
+- Clearing a remembered flood hold includes an example in help and command discovery.
+
+- **`Messenger.never`**: the adapter methods a messenger can never have, as opposed to `lacks`, what it does not have
+  yet. Their commands refuse as before and are also left out of help, `commands --json` and MCP. A command a
+  messenger only `lacks` stays in sight. For WhatsApp: `endOtherSessions` (only the phone ends other devices) and
+  `removeContact`.
+
+- **`review --offline` reads the local store** instead of refusing, for every messenger. It shows only what was
+  already synced and says so (`missing` in JSON, a warning on the terminal); its next step starts from the same
+  point, and `--new` keeps its saved point, so an online review still sees what was never synced.
+
+- **MCP offers more commands**, each limited by the profile's permissions: `runs list|show|path`, `store status|info|check|export|reindex`,
+  `store jobs cancel|retry|clear`, `attachments move`, `attachments jobs status`, `config show`, `commands schema`, `guide`,
+  `skill show`, `doctor report`, the `models` lists, `replies status|test|consents show`, `schedule list`,
+  `server status|logs`, and on the bot server `list`, `chats leave`, `chats admins add|remove`, `commands set|clear` and
+  `webhooks list|set|delete`. What stays off and why is in [the messenger rules](docs/dev/STANDARD.md#mcp).
+
+### Security
+
+- `@modelcontextprotocol/server` 2.3.0 clears the three high-severity advisories `npm audit` reported for every
+  WireCat CLI.
+
+### Fixed
+
+- **A pasted help example runs.** The `Example:` line of an account command's `--help`, generated or written, names
+  the profile `personal` (`tg personal messages list Team`), so it no longer fails with "name a profile".
+
+- `search mail` with no mail in the store points at `memo sync --only mail`; it named a `--mail` option memo does not have.
+
+- `parity.json` matches tg and max: `guide`, `mentions`, `runs search`, `tasks reject` and `--brief`/`--full` are in
+  both, and each gap planned for tg names its tg-cli backlog id.
+
+- `search all --help` says the messenger's server is asked by default and names `--backend archive` and `--offline`
+  to keep it to the local store.
+
 ## 0.397.0 — 23.10.2026
 
 ### Changed — may break callers

package/README.md

@@ -4,7 +4,8 @@
 
 # @wirecat/cli-core
 
-The engine behind the WireCat command-line tools for Telegram, MAX, mail, notes and meetings. Everything that
+The engine behind the WireCat command-line tools for Telegram, MAX, WhatsApp, mail, notes, meetings and Google
+Drive. Everything that
 does not depend on one messenger lives here: the data model, a local SQLite store with full-text and semantic
 search, a Lucene query language, the shared commands, an MCP server for AI agents, and the guard around every
 write. A messenger plugs in as one adapter and gets all of it.
@@ -36,6 +37,7 @@ write. A messenger plugs in as one adapter and gets all of it.
 | [Testing](docs/dev/TESTING.md) · [Parity audit](docs/dev/PARITY-AUDIT.md) | The sandbox, the coverage floor, the checks across tg and max |
 | [Tool boundaries](docs/dev/TOOL-BOUNDARIES.md) | Which tool owns which command |
 | [API reference](docs/REFERENCE.md) | Every entry point and the detailed contract of each feature |
+| [Roadmap](docs/roadmap.md) | What is being built next for developers on this package |
 | [Changelog](CHANGELOG.md) | What each version changed, and what may break callers |
 
 ## What it is
@@ -72,7 +74,7 @@ It runs on Node 22.16+ and 24+, and on Bun.
 
 ```mermaid
 flowchart TB
-  tools["tg · max · memo · zm · drive"] --> interface
+  tools["tg · max · wa · memo · zm · drive"] --> interface
   subgraph core ["@wirecat/cli-core"]
     interface["Interface: CLI commands and MCP tools"] --> services["Services: one use case each"]
     services --> ports["Ports: MessengerAdapter · MeetingSource · TaskStore"]
@@ -88,7 +90,7 @@ Five layers, and each calls only the layers below it: domain, adapters behind a
 
 - **The CLI and the MCP server are two adapters over the same services.** A command and its MCP tool answer with
   the same data, because one service produces it.
-- **A port with one required core and optional groups.** `MessengerCore` is what every messenger must do. Seventeen
+- **A port with one required core and optional groups.** `MessengerCore` is what every messenger must do. The other
   groups — server reads, polls, forums, reactions and the rest — are optional and reached through `capability()`.
   A messenger without a group refuses the command before connecting; it never crashes and never silently drops an
   option.
@@ -116,8 +118,9 @@ code and its document must agree. A search plan that reads an index once per mes
 - **One query language for every list and every source.** A TypeScript port of the Apache Lucene 9.12.3 parsers,
   with no runtime parser dependency. Phrases, `AND` / `OR` / `NOT`, `+required`, grouping, field groups like
   `from:(alice OR bob)`, ranges `date:[2026-01-01 TO 2026-02-01}`, comparisons `size>10MB`, wildcards and regular
-  expressions. 27 fields: sender, chat, date, file name, MIME type, transcript, subject, label and more. Fuzzy
-  and proximity operators are refused with an error that names the alternative.
+  expressions. 27 fields: sender, chat, date, file name, MIME type, transcript, subject, label and more.
+  Proximity `"invoice paid"~3` finds the words close together in one message; the fuzzy operator `word~1` is
+  refused with an error that names the alternative.
   [Syntax](docs/search/query-language.md) · [grammar](docs/search/query-language-spec.md)
 - **Any three letters inside a word.** An FTS5 trigram index finds `port` inside `report`. A
   second, word index ranks by BM25.
@@ -211,8 +214,9 @@ they deliberately differ. A rule changes in its own pull request, before the cod
 - **Built for agents.** `--no-input` never prompts. Input and output are bounded (16 MiB in, 4 MiB out) and fail
   visibly instead of truncating. One-shot commands time out after 30 seconds and close what they hold. `--dry-run`
   previews any write.
-- **The tool never picks an account.** The profile is the first word of every account command; without one, the
-  command stops and lists the choices — even when there is only one.
+- **The tool never picks an account.** Every account command names its profile — the first word in tg, max and
+  wa, an option such as `--account` or `--profile` in the others; without one, the command stops and lists the
+  choices — even when there is only one.
 - **Run records keep ids and timings, never content.** A failure is kept by default, so `runs show` can explain it
   without anyone sending a log full of messages.
 - **Tests that cannot touch real data.** A sandbox keeps every test away from the owner's store, and no test may
@@ -253,8 +257,7 @@ describe("the adapter keeps the port's promises", () => {
 **Before 1.0, any release may break a caller.** Releases are frequent, sometimes several a day, and any of them
 may change any entry point. Every such change is listed in the [changelog](CHANGELOG.md) under "Changed — may break
 callers", with what to change. tg-cli and max-cli pin an exact version and move to a new one in their own pull request.
-Pin an exact version too: as of 18.10.2026, 132 of the 321 versions in the changelog break callers, and no patch
-release has.
+Pin an exact version too.
 The full list of entry points and what each holds is in the [API reference](docs/REFERENCE.md).
 
 ⚠ **Errors are recognised by shape, not by class** (`isCliFailure`). A package linked during development brings its

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, mcp: false })
+    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, mcp: false })
+    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, mcp: false })
+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, mcp: false })
+    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

@@ -8,11 +8,13 @@ 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()) {
@@ -33,8 +35,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")

package/dist/cli/bot/people.js

@@ -11,6 +11,7 @@ import { messageItem } from "../messenger/message-items.js";
 import { positiveCount } from "../paging.js";
 import { asFirstWord } from "../profile.js";
 import { botContext } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan } from "./messages.js";
 import { ChatRegistry, registryProfiles } from "./registry.js";
 /** What "common chats" rests on: who has written where in this copy, not who is a member. */
@@ -122,13 +123,16 @@ const cardOf = async (store, context, bot, who, across, limit) => {
 };
 /** `bot contacts show`: one person this bot has seen write, from the local copy. */
 export const botContactsCommand = (bot) => {
-    const command = new Command("contacts").description(`people this bot has seen write — from the local copy on this machine, never asking ${bot.name ?? "the messenger"} unless told to`);
-    acrossOptions(annotate(command.command("show"), { effects: REMOTE_READ }))
+    const command = new Command("contacts")
+        .description(`people this bot has seen write — from the local copy on this machine, never asking ${bot.name ?? "the messenger"} unless told to`)
+        .summary("the people this bot has seen write, from the local copy");
+    acrossOptions(annotate(command.command("show"), { effects: REMOTE_READ, examples: botExamples(bot, "contacts show @ann") }))
         .argument("<who>", "an id, @username or part of a name")
         .option("--limit <n>", "how many messages from the private chat", positiveCount("--limit"))
         .option("--sync-first", "read the private chat with them again from the messenger first — one request")
         .description("one person: the chats they wrote in (with their last message there) and the latest messages of their " +
         "private chat with the bot")
+        .summary("one person: the chats they wrote in and their chat with the bot")
         .action(async function (who, options) {
         const context = botContext(this, bot);
         const across = { allBots: options.allBots === true, bots: options.bots ?? [] };
@@ -186,7 +190,10 @@ const search = (context, bot, text, from, options) => {
 /** `bot search messages`: the messages this bot's local copy holds. */
 export const botSearchCommand = (bot) => {
     const group = new Command("search").description("find what this bot's local copy holds, by text");
-    acrossOptions(annotate(group.command("messages"), { effects: REMOTE_READ }))
+    acrossOptions(annotate(group.command("messages"), {
+        effects: REMOTE_READ,
+        examples: botExamples(bot, "search messages refund", "search messages invoice --from @ann"),
+    }))
         .argument("[query...]", "the words to find")
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
@@ -195,6 +202,7 @@ export const botSearchCommand = (bot) => {
         .description("search the messages this bot has read, sent or received on this machine — the local copy only, best " +
         'match first; a Lucene query: every word must appear; "a phrase", -word, a OR b, from: chat: date: has:; ' +
         "by text, by --from, or both")
+        .summary("search the messages this bot has seen, in the local copy, by text")
         .action(async function (query, options) {
         const context = botContext(this, bot);
         const limit = options.limit ?? context.settings.limit;
@@ -222,12 +230,16 @@ export const botSearchCommand = (bot) => {
 };
 /** `bot messages between`, over the local copy, added to the shared `messages` group. */
 export const addBotCopyReads = (messages, bot) => {
-    acrossOptions(annotate(messages.command("between"), { effects: REMOTE_READ }))
+    acrossOptions(annotate(messages.command("between"), {
+        effects: REMOTE_READ,
+        examples: botExamples(bot, "messages between @ann @bob"),
+    }))
         .argument("<people...>", "two or more people — an id, @username or part of a name each")
         .option("--limit <n>", "how many of the latest messages from each chat", positiveCount("--limit"))
         .description("what two or more people wrote in the chats they have all written in — from the local copy, grouped by " +
         "chat, oldest first; --limit counts per chat. Common chats are the ones this copy saw each of them " +
         `write in, not a member list from ${bot.name ?? "the messenger"}`)
+        .summary("what two or more people wrote in the chats they share, from the local copy")
         .action(async function (references, options) {
         const context = botContext(this, bot);
         if (references.length < 2)