@wirecat/cli-core 0.398.0 → 0.399.0

package/CHANGELOG.md

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

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

@@ -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)

package/dist/cli/bot/setup.js

@@ -7,6 +7,7 @@ import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { wholeList } from "../messenger/chat-answers.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog } from "./updates.js";
@@ -30,7 +31,7 @@ const botWrite = (context, key, write) => guardedWrite(context.guard(), { operat
 /** `bot commands`: the menu people see when they type `/`. */
 export const botMenuCommand = (bot) => {
     const command = new Command("commands").description("the bot's command menu — what people see after /");
-    annotate(command.command("list"), { effects: REMOTE_READ })
+    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "commands list") })
         .description("the commands in the menu now")
         .action(async function () {
         const context = online(botContext(this, bot), this);
@@ -48,13 +49,19 @@ export const botMenuCommand = (bot) => {
             renderAnswer(command, context, wholeList("bot commands list", entries));
         });
     };
-    annotate(command.command("set"), { effects: REMOTE_WRITE })
+    annotate(command.command("set"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, 'commands set "start=Begin here" "help=What I can do"'),
+    })
         .description("replace the whole menu: each command as name=description, e.g. start=Begin")
         .argument("<commands...>", "name=description, one per command")
         .action(async function (typed) {
         await replace(this, typed.map(entryOf), "bot.commands.set");
     });
-    annotate(command.command("clear"), { effects: REMOTE_WRITE })
+    annotate(command.command("clear"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "commands clear"),
+    })
         .description("empty the menu")
         .action(async function () {
         await replace(this, [], "bot.commands.clear");
@@ -62,9 +69,13 @@ export const botMenuCommand = (bot) => {
     return command;
 };
 /** `bot callbacks`: answers to the buttons people press under the bot's messages. */
-export const botCallbacksCommand = (bot) => new Command("callbacks").description("answers to the buttons people press under the bot's messages").addCommand(annotate(new Command("answer"), { effects: REMOTE_WRITE })
+export const botCallbacksCommand = (bot) => new Command("callbacks").description("answers to the buttons people press under the bot's messages").addCommand(annotate(new Command("answer"), {
+    effects: REMOTE_WRITE,
+    examples: botExamples(bot, 'callbacks answer 4385 --notification "Saved"'),
+})
     .description("answer a pressed button by its callback id: --notification shows the person a one-time note, " +
     "--text replaces the message the button was on")
+    .summary("answer a pressed button: a note to that person, or new message text")
     .argument("<callback>", "the callback id `bot watch` printed")
     .option("--text <text>", "the message's new text")
     .option("--notification <text>", "a note only the person who pressed sees")
@@ -97,8 +108,10 @@ export const botCallbacksCommand = (bot) => new Command("callbacks").description
 }));
 /** `bot webhooks`: where the messenger pushes this bot's updates instead of being polled. */
 export const botWebhooksCommand = (bot) => {
-    const command = new Command("webhooks").description("where the messenger pushes this bot's updates — while one is set, `bot watch` gets nothing");
-    annotate(command.command("list"), { effects: REMOTE_READ })
+    const command = new Command("webhooks")
+        .description("where the messenger pushes this bot's updates — while one is set, `bot watch` gets nothing")
+        .summary("where the messenger pushes this bot's updates");
+    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "webhooks list") })
         .description("the webhooks this bot has")
         .action(async function () {
         const context = online(botContext(this, bot), this);
@@ -107,7 +120,10 @@ export const botWebhooksCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot webhooks list", (await botCan(adapter, "webhooks", bot, "list its webhooks")()).map(snakeKeys)));
         });
     });
-    const set = annotate(command.command("set"), { effects: REMOTE_WRITE })
+    const set = annotate(command.command("set"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "webhooks set https://bot.example.ts.net/"),
+    })
         .description("send this bot's updates to an HTTPS address; refused while another is set")
         .argument("<url>", "the HTTPS address")
         .option("--types <types>", "only these update types, comma-separated, in the messenger's words")
@@ -138,7 +154,10 @@ export const botWebhooksCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot webhooks list", (await list()).map(snakeKeys)));
         });
     });
-    annotate(command.command("delete"), { effects: REMOTE_WRITE })
+    annotate(command.command("delete"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "webhooks delete https://bot.example.ts.net/"),
+    })
         .description("stop sending updates to this address; with none left, `bot watch` works again")
         .argument("<url>", "the address")
         .action(async function (url) {

package/dist/cli/bot/watch.js

@@ -7,6 +7,7 @@ import { environmentOf } from "../context.js";
 import { REMOTE_WRITE } from "../effects.js";
 import { withoutProviderRefs } from "../provider-refs.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan, botIdOf } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog, UpdatesCursor } from "./updates.js";
@@ -83,8 +84,13 @@ const keep = async (command, context, bot, botId, events, senders) => {
  * With `--public-url` the messenger pushes each batch to a local receiver behind the owner's tunnel
  * instead, and a batch is acknowledged only once kept, so the messenger sends again what was not.
  */
-export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects: REMOTE_WRITE, lifetime: "persistent" })
+export const botWatchCommand = (bot) => annotate(new Command("watch"), {
+    effects: REMOTE_WRITE,
+    lifetime: "persistent",
+    examples: botExamples(bot, "watch --jsonl", "watch --events"),
+})
     .description("print new messages as they arrive and keep them, until Ctrl-C or --timeout (either ends it normally)")
+    .summary("print new messages as they arrive and keep them, until Ctrl-C")
     .option("--events", "also edits, deletions, buttons pressed and people coming and going; every line names its event")
     .option("--types <types>", "only these update types, comma-separated, in the messenger's words")
     .option("--public-url <url>", "receive by webhook at your tunnel's https address instead of polling, e.g. https://<name>.ts.net")

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

@@ -3,6 +3,7 @@ import { type AISettings } from "../analysis/settings.js";
 import { type AppIdentity } from "../ports/app.js";
 import type { ModelChoice } from "../services/embeddings.js";
 export interface ModelOptions {
+    embeddingProvider?: string;
     model?: string;
     provider?: string;
     baseUrl?: string;
@@ -10,7 +11,7 @@ export interface ModelOptions {
     concurrency?: number;
 }
 /** A local model id, or a remote model with its key from `models text key set`. */
-export declare const embeddingChoice: ({ model, provider, baseUrl, dims, concurrency }: ModelOptions, app: AppIdentity, settings: AISettings, env: NodeJS.ProcessEnv, { needKey, keyring }?: {
+export declare const embeddingChoice: ({ model, provider, embeddingProvider, baseUrl, dims, concurrency }: ModelOptions, app: AppIdentity, settings: AISettings, env: NodeJS.ProcessEnv, { needKey, keyring }?: {
     needKey?: boolean;
     keyring?: KeyringStore | undefined;
 }) => ModelChoice;