@wirecat/cli-core 0.396.0 → 0.398.0

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

@@ -58,6 +58,7 @@ export const readProfilePhoto = (messenger, path, env) => readUpload("photo", pa
 const updateCommand = (messenger) => {
     const keys = messenger.groupSettings ?? GROUP_SETTINGS;
     const update = annotate(new Command("update"), { effects: REMOTE_WRITE })
+        .summary("change a group or channel's profile and settings")
         .description("rename a group or channel, change its description, or turn one of its settings on or off")
         .argument("<chat>", messenger.chatArgument)
         .option("--title <title>", "the new name")

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

@@ -10,11 +10,16 @@ const PERSON = "person id — `contacts lookup` finds one — or part of a known
 /** The address book's writes, in max-cli's words. */
 export const contactWriteCommands = (messenger) => {
     const simple = [
-        ["add", "add a person to your contacts — `contacts list` still shows only people you have a dialog with"],
+        [
+            "add",
+            "add a person to your contacts — `contacts list` still shows only people you have a dialog with",
+            "add a person to your contacts",
+        ],
         ["remove", "remove a person from your contacts; the chat stays, a name you gave them may not"],
         ["block", "stop a person from writing to you — they need not be a contact"],
         ["unblock", "let a blocked person write to you again"],
-    ].map(([name, description]) => annotate(new Command(name), { effects: REMOTE_WRITE })
+    ].map(([name, description, summary]) => annotate(new Command(name), { effects: REMOTE_WRITE })
+        .summary(summary ?? description)
         .description(description)
         .argument("<person>", PERSON)
         .action(async function (person) {
@@ -23,10 +28,11 @@ export const contactWriteCommands = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(done)));
     }));
     const rename = annotate(new Command("rename"), { effects: REMOTE_WRITE })
+        .summary("change a contact's name in the messenger address book")
         .description("rename the contact in the messenger address book; use contacts alias for a private local name")
         .argument("<person>", PERSON)
         .argument("<first-name>", "the name you want to see for them")
-        .argument("[last-name]")
+        .argument("[last-name]", "the last name you want to see for them")
         .action(async function (person, firstName, lastName) {
         const context = messengerContext(this, messenger);
         const renamed = await context.withServices((services) => services.people.rename(person, firstName, lastName));

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

@@ -64,7 +64,8 @@ export const storeCommand = (messenger) => {
  * What the local store holds, per chat — read from the store alone. Whether a fetch reached a
  * chat's very first message is not recorded, so it is not claimed: the stretches held are shown.
  */
-const statusCommand = (messenger) => annotate(new Command("status"), { effects: LOCAL_READ, mcp: false })
+const statusCommand = (messenger) => annotate(new Command("status"), { effects: LOCAL_READ })
+    .summary("what the local archive holds and what is missing")
     .description("per chat: messages stored, the oldest and newest, and the stretches held completely")
     .argument("[chat]", messenger.chatArgument)
     .action(async function (chat) {
@@ -131,9 +132,10 @@ const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LO
  * `--format markdown` for a transcript a person reads. With `--output-dir`, any number of chats into a
  * folder, and each later run into the same folder adds only what changed.
  */
-const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { effects: LOCAL_WRITE, mcp: false }))
+const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { effects: LOCAL_WRITE }))
+    .summary("export stored messages to files")
     .description("a chat's stored messages, oldest first: --jsonl one message per line, --json the list envelope of messages; never asks the messenger")
-    .argument("[chats...]", `${messenger.chatArgument}; several with --output-dir`)
+    .argument("[chat...]", `${messenger.chatArgument}; several with --output-dir`)
     .option("--format <format>", "jsonl: one message per line, the default with --output; markdown: a transcript with a heading per day, replies and forwards quoted")
     .option("--since-time <time>", "only from this ISO 8601 time, or 30m / 2h / 1d ago, on")
     .option("--output <file>", "write JSON lines, or the transcript, to this new file, readable only by you")

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

@@ -15,6 +15,7 @@ import { withPaging } from "../paging.js";
 import { readsStdin } from "../stdin-field.js";
 import { nextStep } from "../steps.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
+import { addMediaArchiveCommands } from "./media-archive-command.js";
 import { stopOnSignal } from "./patience.js";
 import { readAll } from "./stdin.js";
 const count = (value) => {
@@ -38,6 +39,7 @@ const extractCommand = (messenger) => annotate(new Command("extract"), {
     effects: FETCH,
     examples: [`${messenger.app.command} personal attachments extract --chat "Book club" --limit 10`],
 })
+    .summary("extract text from retained message files")
     .description("read the text of downloaded files — text, PDF/DOCX text layers, ODT/ODS/XLSX/PPTX/EPUB — into the local store, where search finds them")
     .option("--chat <chat>", `only this chat's files; ${messenger.chatArgument}`)
     .option("--from-dir <dir>", "match files in this nonrecursive directory; needs --chat")
@@ -127,7 +129,9 @@ const row = ({ message, position, name, local_path, extraction }) => `${message}
 const listCommand = (messenger) => withQuery(withPaging(annotate(new Command("list"), {
     effects: REMOTE_READ,
     examples: [`${messenger.app.command} personal attachments list --limit 10`],
-}).description("files of stored messages, newest first: where each was saved and whether its text is held — never the text")), ATTACHMENT_QUERY).action(async function (words) {
+})
+    .summary("stored message files, saved paths and text status")
+    .description("files of stored messages, newest first: where each was saved and whether its text is held — never the text")), ATTACHMENT_QUERY).action(async function (words) {
     const context = messengerContext(this, messenger);
     const query = listQuery(typedQuery(words), ATTACHMENT_QUERY, "attachments list");
     const found = await context.withServices((services) => services.attachments.list({ ...pageOf(context.settings), ...(query ? { query } : {}) }));
@@ -175,6 +179,7 @@ const textCommand = (messenger) => {
         name: "text",
         description: "the text of the file",
     })
+        .summary("save the text read from one message file")
         .description("keep the text an agent read from a file — a scan, a photo — so search finds it; nothing is sent")
         .argument("<chat>", `${messenger.chatArgument}; or a msg: locator, with no message id after it`)
         .argument("[message]", "the message id")
@@ -196,9 +201,14 @@ const textCommand = (messenger) => {
     return text;
 };
 /** Files of stored messages: what is in them, for `content:` in a search. Nothing here is sent. */
-export const attachmentsCommand = (messenger) => new Command("attachments")
-    .description("the files of stored messages: their text in the local store, where search finds it")
-    .addCommand(extractCommand(messenger))
-    .addCommand(listCommand(messenger))
-    .addCommand(showCommand(messenger))
-    .addCommand(textCommand(messenger));
+export const attachmentsCommand = (messenger) => {
+    const attachments = new Command("attachments")
+        .summary("stored message files and their retained text")
+        .description("the files of stored messages: their text in the local store, where search finds it")
+        .addCommand(extractCommand(messenger))
+        .addCommand(listCommand(messenger))
+        .addCommand(showCommand(messenger))
+        .addCommand(textCommand(messenger));
+    addMediaArchiveCommands(attachments, messenger);
+    return attachments;
+};

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

@@ -39,6 +39,7 @@ export const syncCommand = (messenger) => {
         effects: FETCH,
         cooperative: true,
     })
+        .summary("fetch and save a chat's message history")
         .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat")
         .argument("[chat]", messenger.chatArgument)
         .option("--all", `every chat, most recently active first — what search needs; the last ${ALL_SINCE} unless --since-time or --last`)
@@ -224,6 +225,7 @@ export const jobsCommand = (messenger) => {
             context.renderer.note(`no ${query ? "matching " : ""}background sync jobs for this profile`);
     });
     annotate(command.command("show"), { effects: LOCAL_READ })
+        .summary("one archive job's status and log")
         .description("one background job — the newest when none is named — and what the store now holds of its chat")
         .argument("[job]", "the job id `messages sync --background` printed")
         .action(async function (id) {
@@ -235,7 +237,8 @@ export const jobsCommand = (messenger) => {
             : await context.withServices((services) => services.archive.held(chatId)).catch(() => undefined);
         renderAnswer(this, context, itemOf(snakeKeys({ ...jobDetails(job), ...(held ? { held } : {}), log: job.log })));
     });
-    destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE }))
+        .summary("cancel a queued or running archive job")
         .description("stop a running background job after its current page; a later sync resumes where it stopped")
         .argument("<job>", "the job id")
         .action(function (id) {
@@ -248,7 +251,8 @@ export const jobsCommand = (messenger) => {
         process.kill(job.pid, "SIGTERM");
         renderAnswer(this, context, itemOf({ job: job.id, cancelled: true }));
     });
-    destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE }))
+        .summary("retry an archive job")
         .description("start a partial, failed or died job again, as a new job; the sync resumes where the store stopped")
         .argument("[job]", "the job id")
         .option("--failed", "every chat whose newest job partial, failed or died")
@@ -288,7 +292,7 @@ export const jobsCommand = (messenger) => {
         if (items.length === 0 && context.format === "pretty")
             context.renderer.note("no partial, failed or died jobs to retry");
     });
-    destroysNothing(annotate(command.command("clear"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(command.command("clear"), { effects: LOCAL_WRITE }))
         .description("forget finished jobs and remove their logs; a running job is kept")
         .action(function () {
         const context = messengerContext(this, messenger);

package/dist/cli/messenger/catch-up-answers.d.ts

@@ -49,6 +49,8 @@ export declare const inboxAnswer: (inbox: Inbox, hearing: Hearing | undefined, r
         }[][] | undefined;
     }[];
 }>;
+/** What `review --offline` cannot see. */
+export declare const OFFLINE_REVIEW = "offline: only what was already synced to the local store; run review without --offline for the rest";
 /**
  * A review the next one goes on from: from `until` when nothing was left out, else from the same start again.
  * Saved points (`--new`) carry this themselves, and an `--unanswered` look is not a review to continue.

package/dist/cli/messenger/catch-up-answers.js

@@ -48,7 +48,7 @@ const nameOf = (chat) => chat.title ?? chat.id;
  * What every catch-up answer shares: the messages, oldest first, each naming its chat; what was left out as
  * `missing`; and a chat cut short as a `messages.list` step, after the steps the command puts first.
  */
-const catchUpList = (command, found, hearing, reader, { transcribe, first = [], meta = {} }) => {
+const catchUpList = (command, found, hearing, reader, { transcribe, first = [], meta = {}, left = [], }) => {
     const read = found.chats
         .flatMap((chat) => heard(chat.messages, hearing).map((message) => ({ ...message, chatTitle: chat.title })))
         .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
@@ -70,6 +70,7 @@ const catchUpList = (command, found, hearing, reader, { transcribe, first = [],
             ? [{ field: "items", why: `${found.quiet} muted or archived chats left out`, step: `${command}.all` }]
             : []),
         ...hearingMissing(hearing, transcribe),
+        ...left,
     ];
     return listOf(command, {
         items: read.map((message) => summaryOf(message, reader)),
@@ -81,6 +82,8 @@ const catchUpList = (command, found, hearing, reader, { transcribe, first = [],
     });
 };
 export const inboxAnswer = (inbox, hearing, reader, transcribe, meta = {}) => catchUpList("inbox", inbox, hearing, reader, { transcribe, meta });
+/** What `review --offline` cannot see. */
+export const OFFLINE_REVIEW = "offline: only what was already synced to the local store; run review without --offline for the rest";
 const quoted = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 /**
  * A review the next one goes on from: from `until` when nothing was left out, else from the same start again.
@@ -95,6 +98,7 @@ export const reviewAnswer = (found, hearing, reader, { transcribe, fresh, chat,
     return catchUpList("review", found, hearing, reader, {
         transcribe,
         first: continues ? [nextStep("review.next", { args: { query: query.join(" ") } })] : [],
+        ...(found.offline ? { left: [{ field: "items", why: OFFLINE_REVIEW }] } : {}),
         ...(meta === undefined ? {} : { meta }),
     });
 };

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

@@ -19,6 +19,7 @@ import { membersCommand } from "./chats-members-command.js";
 import { markReadCommand } from "./chats-read-command.js";
 import { trackingCommand } from "./chats-tracking-command.js";
 import { messengerContext } from "./context.js";
+import { hideNever } from "./lacks.js";
 import { archiveCommands, chatDeletionCommands, chatPinCommands, markUnreadCommand, mediaCommand, muteCommands, } from "./records-command.js";
 export const chatsCommand = (messenger) => {
     const chats = new Command("chats").description("the account's chats");
@@ -37,6 +38,7 @@ export const chatsCommand = (messenger) => {
         // Where the history is pushed, the store answers, --offline too.
         ...(messenger.history === "store" ? {} : { offline: false }),
     })
+        .summary("stored membership and title changes")
         .description("who joined, left, was added or removed, and by whom — from the chat's service messages; " +
         `the last ${EVENTS_DAYS} days unless the query names time`)
         .argument("<chat>", messenger.chatArgument), { output: { entity: "chat_event" } }), EVENTS_QUERY).action(async function (chat, words) {
@@ -152,7 +154,7 @@ export const chatsCommand = (messenger) => {
         if (command)
             annotate(command, { examples: [`${messenger.app.command} personal chats ${path} ${args}`.trimEnd()] });
     }
-    return chats;
+    return hideNever(messenger, chats);
 };
 /** Where the history is pushed, the chat list and a chat's card answer from the store and never connect. */
 const storedRead = (messenger) => (messenger.history === "store" ? LOCAL_READ : REMOTE_READ);

package/dist/cli/messenger/chats-members-command.js

@@ -15,6 +15,7 @@ import { messengerContext } from "./context.js";
 export const membersCommand = (messenger) => {
     const members = new Command("members").description("who is in a group");
     members.addCommand(annotate(withQuery(withPaging(annotate(new Command("list"), { effects: REMOTE_READ })
+        .summary("group members and their roles")
         .description("everyone in a group, a page at a time, with their role and when they were last seen")
         .argument("<chat>", messenger.chatArgument)), MEMBERS_QUERY), { output: { entity: "member" } }).action(async function (chat, words) {
         const context = messengerContext(this, messenger);
@@ -23,6 +24,7 @@ export const membersCommand = (messenger) => {
         renderAnswer(this, context, body, lines(({ id, name, username, role }) => [id, name ?? "", username ? `@${username}` : "", role ?? ""].join("  ")));
     }));
     members.addCommand(withQuery(annotate(annotate(new Command("audit"), { effects: REMOTE_READ, offline: false })
+        .summary("members that look like bots, with reasons")
         .description("members that look like bots, each with its reasons — read from the member list and the local store; " +
         "never one request per person, and it removes nobody")
         .argument("<chat>", messenger.chatArgument)
@@ -54,6 +56,7 @@ export const membersCommand = (messenger) => {
         ].join("  ")));
     }));
     members.addCommand(withQuery(annotate(annotate(new Command("history"), { effects: LOCAL_READ })
+        .summary("stored membership changes")
         .description("who joined, who left and whose profile changed, oldest first — what chats members fetch recorded in the " +
         "local store; never asks the messenger")
         .argument("<chat>", messenger.chatArgument), { output: { entity: "chat_event" } }), HISTORY_QUERY).action(async function (chat, words) {
@@ -69,6 +72,7 @@ export const membersCommand = (messenger) => {
         ].join("  ")));
     }));
     const fetch = annotate(new Command("fetch"), { effects: FETCH, offline: false })
+        .summary("save the group's current membership")
         .description("read a group's whole member list into the local store's member history: who joined, who left, daily " +
         "counts and profile changes; someone is recorded as gone only when every member was read")
         .argument("<chat>", messenger.chatArgument);

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

@@ -9,6 +9,7 @@ import { messengerContext } from "./context.js";
 import { chatStatsAnswer, MEMBERS_UNRECORDED, refuseJsonl } from "./stats-answers.js";
 const PERIODS = ["day", "week"];
 export const statsCommand = (messenger) => annotate(new Command("show"), { effects: REMOTE_READ, output: { entity: "chat_stats" } })
+    .summary("activity and participation in one chat")
     .description("a group's or channel's numbers for a period: messages, active members, replies, reactions, questions answered, " +
     `joins and leaves — counted from the local store; ${messenger.history === "store" ? "joins and leaves too" : "joins and leaves are asked of the messenger"}`)
     .argument("<chat>", messenger.chatArgument)

package/dist/cli/messenger/chats-tracking-command.js

@@ -7,7 +7,9 @@ import { lines, wholeList } from "./chat-answers.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 /** The chats whose member lists `serve` fetches daily; kept in the local store, never sent. */
 export const trackingCommand = (messenger) => {
-    const tracking = new Command("tracking").description("the chats whose member lists serve fetches daily into the local store — chats members fetch --track adds one");
+    const tracking = new Command("tracking")
+        .summary("chats whose member lists are fetched daily")
+        .description("the chats whose member lists serve fetches daily into the local store — chats members fetch --track adds one");
     annotate(tracking.command("list"), { effects: LOCAL_READ })
         .description("every tracked chat: since when, and its last member count")
         .action(async function () {
@@ -22,6 +24,7 @@ export const trackingCommand = (messenger) => {
         ].join("  ")));
     });
     annotate(tracking.command("show"), { effects: LOCAL_READ })
+        .summary("one chat's member tracking and daily counts")
         .description(`one chat: whether it is tracked, and its member count per day for the last ${TRACKED_DAYS} days`)
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {

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

@@ -19,9 +19,13 @@ const SHELLS = ["zsh", "bash", "fish", "powershell"];
  * ⚠ **A Tab never connects and never creates anything.** Names come from the message store if it
  * exists — no store, no names — and nothing goes to stderr: a shell shows whatever it is given.
  */
-export const completeCommand = (messenger, config, options = {}) => annotate(new Command("complete"), { effects: LOCAL_READ, mcp: false })
+export const completeCommand = (messenger, config, options = {}) => annotate(new Command("complete"), {
+    effects: LOCAL_READ,
+    mcp: false,
+    examples: [`${messenger.app.command} complete zsh`],
+})
     .description(`shell completion: \`${messenger.app.command} complete zsh\` prints the script to source`)
-    .argument("[words...]")
+    .argument("[words...]", "zsh for the shell script, or command words to complete")
     .allowUnknownOption()
     .helpOption(false)
     .action(async function (words) {

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

@@ -19,6 +19,7 @@ import { commandAt, nextStep } from "../steps.js";
 import { contactWriteCommands } from "./admin-contacts-command.js";
 import { contactAnswer, lines, pageOf } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
+import { hideNever } from "./lacks.js";
 import { CONTACTS_QUERY, notesAllowed } from "./people-queries.js";
 import { privatePeopleCommands } from "./private-people-command.js";
 import { syncsFirst } from "./search-sync-options.js";
@@ -68,7 +69,8 @@ export const contactsCommand = (messenger) => {
         }));
         renderAnswer(this, context, itemOf(contactAnswer(account, card)));
     }));
-    annotate(contacts.command("profile"), { effects: REMOTE_READ })
+    annotate(contacts.command("profile"), { effects: REMOTE_READ, output: { entity: "contact_profile" } })
+        .summary("a person's profile from the messenger")
         .description("everything the messenger says about one person — handles, flags, last seen, when they registered — and " +
         "how many of their messages the store holds in each chat you share, the first and the last, and the " +
         "earlier names and usernames the store saw them with")
@@ -86,6 +88,7 @@ export const contactsCommand = (messenger) => {
         }));
     });
     const contextCommand = annotate(contacts.command("context"), { effects: REMOTE_READ })
+        .summary("what the local archive knows about a person")
         .description("what the store holds about one person, in every messenger linked to them: shared chats, the last " +
         "messages each way, their recent messages, where others mentioned them — never connects")
         .argument("<person>", "their id, @username, or part of their name")
@@ -167,6 +170,7 @@ export const contactsCommand = (messenger) => {
         }));
     });
     annotate(contacts.command("timeline"), { effects: REMOTE_READ })
+        .summary("one person's activity across their linked identities")
         .description("everything one person took part in, in every messenger linked to them — messages they wrote or were " +
         "mentioned in, chats, mail, meetings, tasks — newest first, from the store; never connects")
         .argument("<person>", "their id, @username, or part of their name")
@@ -208,6 +212,7 @@ export const contactsCommand = (messenger) => {
         }));
     });
     annotate(contacts.command("check"), { effects: REMOTE_READ })
+        .summary("check a person's profile and messages for signs of abuse")
         .description(registriesCover(messenger.provider)
         ? "whether one person looks like a bot, a fake or a spammer: their profile, what they wrote in the store, " +
             `and the public ban lists (${Object.values(REGISTRIES)
@@ -235,6 +240,7 @@ export const contactsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(answer)));
     });
     annotate(contacts.command("link"), { effects: LOCAL_WRITE })
+        .summary("link identities that belong to one person")
         .description("record that two people in the store are one person — the same name is never enough")
         .argument("<person>", "their id, @username, or part of their name")
         .argument("<other>", "the same in another messenger of the store, as <messenger>:<person> — max:Ana; me: it is you, as zoom:<id> me")
@@ -255,7 +261,8 @@ export const contactsCommand = (messenger) => {
      * ⚠ **The number is asked for or piped, never an argument**: argv is read by `ps` and kept by shell
      * history, and a phone number is personal data.
      */
-    annotate(contacts.command("lookup"), { effects: REMOTE_READ })
+    annotate(contacts.command("lookup"), { effects: REMOTE_READ, output: { entity: "contact_lookup" } })
+        .summary("find an account by a phone number")
         .description("who has this phone number — asks for it, or reads it from stdin; never an argument")
         // Commander's own refusal would repeat the number on stderr.
         .allowExcessArguments()
@@ -267,7 +274,7 @@ export const contactsCommand = (messenger) => {
         const phone = phoneOf(await readSecret("phone number: ", { ...secretInputOf(this), echo: true }));
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.people.lookup(phone)))));
     });
-    annotate(contacts.command("sync"), { effects: FETCH })
+    annotate(contacts.command("sync"), { effects: FETCH, output: { entity: "contact_sync" } })
         .description("take the whole contact list from the messenger into the local store")
         .action(async function () {
         const context = messengerContext(this, messenger);
@@ -309,5 +316,5 @@ export const contactsCommand = (messenger) => {
         if (command)
             annotate(command, { examples: [`${messenger.app.command} personal contacts ${path} ${args}`.trimEnd()] });
     }
-    return contacts;
+    return hideNever(messenger, contacts);
 };

package/dist/cli/messenger/context.d.ts

@@ -95,6 +95,11 @@ export interface Messenger extends ServiceMessenger {
      * connecting, as the adapter would refuse after; one connection per device makes that connection a cost.
      */
     lacks?: readonly (keyof MessengerAdapter)[];
+    /**
+     * Adapter methods this messenger can never have, where `lacks` is what it does not have yet: their commands refuse
+     * the same way and are also hidden from help, `commands` and MCP. WhatsApp: only the phone ends other sessions.
+     */
+    never?: readonly (keyof MessengerAdapter)[];
     /** Whether a message can be deleted for the owner alone; yes when unset. No: every delete is for everyone (WhatsApp). */
     deleteForMe?: boolean;
     /** Whether the messenger has forum topics: `--topic`, `topic:` in `messages list` and the `topics_*` tools; yes when unset. */

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

@@ -30,8 +30,11 @@ import { readAll } from "./stdin.js";
  * mentions, one sender's messages in a row. From the store alone; nothing is built until asked (phase 3).
  */
 export const conversationsCommand = (messenger) => {
-    const conversations = new Command("conversations").description("the conversations inside a chat, found in the stored messages by replies, mentions and who wrote next");
+    const conversations = new Command("conversations")
+        .summary("group stored messages into conversations")
+        .description("the conversations inside a chat, found in the stored messages by replies, mentions and who wrote next");
     boundOptions(reachesOtherService(annotate(conversations.command("build"), { effects: REMOTE_WRITE }))
+        .summary("build conversation links from stored messages")
         .description("find a chat's conversations in what the store holds, replacing the last build; without --chat, every " +
         "chat that changed since its build and every group never built; never asks the messenger")
         .option("--chat <chat>", messenger.chatArgument)
@@ -111,6 +114,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(built)), () => `${built.messages} messages → ${built.conversations} conversations, ${built.links} links (rules v${built.rulesVersion})\n`);
     });
     withQuery(annotate(conversations.command("list"), { effects: LOCAL_READ })
+        .summary("stored conversations in one chat")
         .description("a chat's conversations, the newest first: when, how many messages, how many people")
         .argument("<chat>", messenger.chatArgument), CONVERSATION_QUERY)
         .option("--limit <n>", "how many", positiveCount("--limit"))
@@ -123,6 +127,7 @@ export const conversationsCommand = (messenger) => {
             context.renderer.note("no conversations match");
     });
     annotate(conversations.command("show"), { effects: LOCAL_READ })
+        .summary("one conversation and its messages")
         .description("one conversation's messages, oldest first — by its id, or the one a message is in")
         .argument("<conversation>", `a conversation id from \`conversations list\`; or ${messenger.chatArgument}, with a message`)
         .argument("[message]", "a message id in that chat: show the conversation it is in")
@@ -151,6 +156,7 @@ export const conversationsCommand = (messenger) => {
             renderAnswer(this, context, conversationShown(account, { summary, messages }));
     });
     withModelOptions(annotate(conversations.command("related"), { effects: LOCAL_READ })
+        .summary("conversations nearest in meaning to a message's conversation")
         .description("the conversations nearest in meaning to the one a message is in, in every built chat, best first — " +
         "from the vectors `conversations embed` stored; runs no model")
         .argument("<chat>", messenger.chatArgument)
@@ -166,6 +172,7 @@ export const conversationsCommand = (messenger) => {
             context.renderer.note(`no other conversation has vectors of ${found.model}`);
     });
     withModelOptions(annotate(conversations.command("status"), { effects: LOCAL_READ })
+        .summary("which chats are ready for conversation search")
         .description("how fresh each built chat's conversations and vectors are: messages the build has not seen, chunks " +
         "with a current, stale or missing vector")
         .option("--chat <chat>", `only this chat: ${messenger.chatArgument}`)).action(async function () {
@@ -179,9 +186,11 @@ export const conversationsCommand = (messenger) => {
     });
     const batches = conversations
         .command("batches")
+        .summary("batches waiting for an agent's conversation links")
         .description("windows of a chat for your own AI agent to link: which earlier message each one answers");
     const sizeOption = (command) => command.option("--size <n>", `messages to answer per batch, ${BATCH_SIZE.min}–${BATCH_SIZE.max}; ${BATCH_SIZE.default} by default`, positiveCount("--size"));
     sizeOption(annotate(batches.command("status"), { effects: LOCAL_READ })
+        .summary("progress of conversation-link batches")
         .description("how many messages still wait for an answer, in how many batches, and how much text")
         .requiredOption("--chat <chat>", messenger.chatArgument)).action(async function () {
         const { chat, size = BATCH_SIZE.default } = this.opts();
@@ -191,6 +200,7 @@ export const conversationsCommand = (messenger) => {
             `${status.characters} characters (about ${status.tokensEstimate} tokens)\n`);
     });
     sizeOption(annotate(batches.command("next"), { effects: LOCAL_READ })
+        .summary("get the next batch of messages to link")
         .description("the next window to answer, with the messages before it; message text goes to stdout only")
         .requiredOption("--chat <chat>", messenger.chatArgument)).action(async function () {
         const { chat, size = BATCH_SIZE.default } = this.opts();
@@ -221,6 +231,7 @@ export const conversationsCommand = (messenger) => {
         description: '{ "model", "skill"?, "answers": [{ "message", "parent", "confidence" }] }',
         json: true,
     })
+        .summary("save an agent's conversation-link answers")
         .description('store your agent\'s answer to a batch, read as JSON from stdin: { "model", "answers": [{ "message", ' +
         '"parent", "confidence" }] }; all or nothing')
         .requiredOption("--batch <id>", "the batch id `conversations batches next` printed")
@@ -233,6 +244,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(stored, { next: [nextStep("conversations.build", { args: { chat: stored.chat } })] }), () => `${stored.stored} answers stored\n`);
     });
     annotate(links.command("clear"), { effects: LOCAL_WRITE })
+        .summary("remove an agent's saved conversation-link answers")
         .description("drop your agent's answers for a chat, or only one model's; messages are never touched")
         .requiredOption("--chat <chat>", messenger.chatArgument)
         .option("--model <model>", "only the answers this model gave")
@@ -244,6 +256,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(cleared), () => `${cleared.cleared} answers dropped\n`);
     });
     const embed = withModelOptions(reachesOtherService(annotate(new Command("embed"), { effects: REMOTE_WRITE }))
+        .summary("prepare conversation vectors for meaning search")
         .description("compute a vector for each chunk of a chat's conversations for search by meaning — on this machine, or " +
         "with --provider through a service and your key; resumes where it stopped; without --chat, every " +
         "built chat with chunks left, on this machine only")
@@ -290,6 +303,7 @@ export const conversationsCommand = (messenger) => {
         }), () => `${done.embedded} chunks embedded with ${done.model}${done.skipped ? `, ${done.skipped} changed since the build` : ""}\n`);
     });
     withModelOptions(annotate(embed.command("status"), { effects: LOCAL_READ })
+        .summary("which conversation vectors are ready or stale")
         .description("how many chunks of a chat have a vector of the model, how many are left, and what is left costs")
         .option("--chat <chat>", messenger.chatArgument)).action(async function () {
         const options = this.optsWithGlobals();
@@ -303,6 +317,7 @@ export const conversationsCommand = (messenger) => {
             "\n");
     });
     withModelOptions(destroysNothing(annotate(embed.command("clear"), { effects: LOCAL_WRITE }))
+        .summary("remove stored conversation vectors")
         .description("drop a chat's vectors, or only one model's; messages and conversations are never touched")
         .option("--chat <chat>", messenger.chatArgument)).action(async function () {
         const options = this.optsWithGlobals();
@@ -479,6 +494,7 @@ export const linksCommand = (messenger) => annotate(new Command("links"), {
     examples: [`${messenger.app.command} personal messages links "Book club" 101`],
     effects: LOCAL_READ,
 })
+    .summary("why a message belongs to its conversation")
     .description("why a message is in its conversation: each link it has, and the chain of answers back to the start")
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the message id")
@@ -511,6 +527,7 @@ const readinessLine = ({ chat, state, graph, pending, vectors }, model) => graph
         `${vectors.missing} missing of ${vectors.chunks} chunks`;
 /** `search conversations`: the conversations nearest to a query, in meaning and in words. */
 export const conversationsSearchCommand = (messenger) => syncOptions(boundOptions(withModelOptions(reachesOtherService(annotate(new Command("conversations"), { effects: REMOTE_READ })))), messenger)
+    .summary("find conversations by words and meaning")
     .description("the conversations nearest to a query in meaning and in words, best first, in one chat or every one — " +
     "meaning after `conversations embed`; runs on this machine")
     .argument("<query>", "what to look for, in your own words, in any language the model reads")

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

@@ -10,6 +10,7 @@ export const countersCommand = (messenger) => {
     const parent = new Command("counters").description("per-counter observations and bounded remote refresh");
     for (const operation of ["show", "refresh"]) {
         const command = new Command(operation)
+            .summary("refresh message counters from the messenger")
             .description(operation === "show"
             ? "show saved counter values and their observation freshness"
             : "read authoritative counters for bounded messages and update their local observations")

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

@@ -57,7 +57,7 @@ const INCLUDES = [
 const EXCLUDES = ["message text", "chat titles", "names", "phone numbers", "the session", "the app credentials"];
 const reportCommand = (messenger) => {
     const { app } = messenger;
-    const report = annotate(new Command("report"), { effects: REMOTE_READ, mcp: false })
+    const report = annotate(new Command("report"), { effects: REMOTE_READ })
         .description("what a problem report holds; writes nothing")
         .action(function () {
         const output = outputFor(this);
@@ -74,7 +74,7 @@ const reportCommand = (messenger) => {
             `About a given run:   ${create} --run <id>   (ids: ${lineOf(this, "runs list")})`,
         ].join("\n"));
     });
-    destroysNothing(annotate(report.command("create"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(report.command("create"), { effects: LOCAL_WRITE, mcp: false }))
         .description("write a problem report to a file, and say where to send it")
         .option("--run <id>", "the run the report is about; the newest failed one if not given")
         .option("--output <file>", "where to write it; a new file in this directory if not given")

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

@@ -21,6 +21,7 @@ export const downloadSubcommand = (messages, messenger) => annotate(messages.com
     examples: [`${messenger.app.command} personal messages download "Book club" 101 --output-dir ./downloads`],
     effects: FETCH,
 })
+    .summary("download files attached to stored messages")
     .description("save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all")
     .argument("<chat>", messenger.chatArgument)
     .argument("[message]", "the message id; left out with --all")

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

@@ -14,7 +14,8 @@ export const floodCommand = (messenger) => {
     const name = messenger.name ?? app.command;
     return annotate(new Command("flood"), { mcp: false })
         .description(`the waits ${name} asked this profile to keep, and a hold on its writes`)
-        .addCommand(grantsAuthority(annotate(new Command("clear"), { effects: LOCAL_WRITE }))
+        .addCommand(grantsAuthority(annotate(new Command("clear"), { effects: LOCAL_WRITE, examples: [`${app.command} personal flood clear`] }))
+        .summary("clear a profile's stored rate-limit hold")
         .description(`forget them, lift the hold and the profile's pace, once ${name} no longer limits the account; changes nothing there`)
         .action(async function () {
         const context = messengerContext(this, messenger);

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

@@ -14,9 +14,10 @@ import { messengerContext } from "./context.js";
  * a model that a message talked into writing somewhere, not an agent set on getting around it.
  */
 export const recipientsCommand = (messenger) => {
+    const tool = `${messenger.app.command} personal`;
     const listFor = (profile, env) => new RecipientList(recipientsPathFor(messenger.app, profile, env), messenger.app.command);
     const command = new Command("recipients").description("the chats this profile may send to, when the list is on");
-    annotate(command.command("list"), { effects: LOCAL_READ })
+    annotate(command.command("list"), { effects: LOCAL_READ, examples: [`${tool} recipients list`] })
         .description("the chats on the list; empty and off until the first add")
         .action(async function () {
         const context = messengerContext(this, messenger);
@@ -28,7 +29,7 @@ export const recipientsCommand = (messenger) => {
         else if (chats.length === 0)
             renderer.note("the recipient list is on and empty — this profile may send nowhere");
     });
-    grantsAuthority(annotate(command.command("add"), { effects: FETCH }))
+    grantsAuthority(annotate(command.command("add"), { effects: FETCH, examples: [`${tool} recipients add "Book club"`] }))
         .argument("<chat>", messenger.chatArgument)
         .description("allow sending to this chat; the first add turns the list on")
         .action(async function (chat) {
@@ -43,7 +44,7 @@ export const recipientsCommand = (messenger) => {
         });
         renderAnswer(this, context, itemOf({ id: found.id, title: found.title, added }));
     });
-    grantsAuthority(annotate(command.command("remove"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("remove"), { effects: LOCAL_WRITE, examples: [`${tool} recipients remove "Book club"`] }))
         .argument("<chat>", "chat id, or the title as the list shows it")
         .description("stop allowing this chat; the list stays on")
         .action(async function (chat) {
@@ -54,7 +55,7 @@ export const recipientsCommand = (messenger) => {
             throw new CliError("not_found", `${chat.trim()} is not on the recipient list of ${settings.profile}`);
         renderAnswer(this, context, itemOf({ id: gone.id, title: gone.title, removed: true }));
     });
-    grantsAuthority(annotate(command.command("clear"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(command.command("clear"), { effects: LOCAL_WRITE, examples: [`${tool} recipients clear`] }))
         .description("delete the list, which turns it off: this profile may send to any chat again")
         .action(async function () {
         const context = messengerContext(this, messenger);