@wirecat/cli-core 0.396.0 → 0.397.0

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/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

@@ -15,6 +15,7 @@ export const floodCommand = (messenger) => {
     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 }))
+        .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);

package/dist/cli/messenger/inbox.js

@@ -33,6 +33,7 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     output: { entity: "message", view: "summary" },
     query: INBOX_QUERY,
 })
+    .summary("unread chats and their newest messages")
     .description("other people's unread messages in every chat; --new for what arrived since the last check")
     .addHelpText("after", queryHelp(INBOX_QUERY))
     .argument("[query...]", "from when: date>2h, date>2026-10-01; the saved point stays put")

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

@@ -21,7 +21,9 @@ export const httpTokenFile = (app, profile, env) => join(resolvePaths({ appName:
 const withFlags = (command) => command.option("--permission <key=level>", "make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys", (value, previous = []) => [...previous, value]);
 export const mcpCommand = (messenger) => {
     const { app } = messenger;
-    const command = withFlags(annotate(new Command("mcp"), { effects: REMOTE_WRITE, lifetime: "persistent", mcp: false }).description(`serve this profile to an agent over MCP, on stdin and stdout — \`claude mcp add ${app.command} -- ${app.command} <profile> mcp\``))
+    const command = withFlags(annotate(new Command("mcp"), { effects: REMOTE_WRITE, lifetime: "persistent", mcp: false })
+        .summary("serve this profile's commands to an AI agent")
+        .description(`serve this profile to an agent over MCP, on stdin and stdout — \`claude mcp add ${app.command} -- ${app.command} <profile> mcp\``))
         .option("--http", "serve over HTTP on 127.0.0.1 for ChatGPT and Claude in the browser, behind your tunnel; the profile's permissions decide")
         .option("--port <port>", `the local port for --http (default ${DEFAULT_PORT})`)
         .option("--public-url <url>", "the tunnel's https address the browser apps use, e.g. https://<name>.ts.net")
@@ -55,7 +57,9 @@ export const mcpCommand = (messenger) => {
     command.addCommand(withFlags(annotate(new Command("config"), {
         effects: LOCAL_READ,
         examples: [`${app.command} personal mcp config`],
-    }).description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")).action(async function () {
+    })
+        .summary("print this profile's local MCP configuration")
+        .description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")).action(async function () {
         const flags = this.optsWithGlobals();
         const context = messengerContext(this, messenger);
         const { settings, env } = context;

package/dist/cli/messenger/media-archive-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Messenger } from "./context.js";
+export declare const addMediaArchiveCommands: (archive: Command, messenger: Messenger) => void;

package/dist/cli/messenger/media-archive-command.js

@@ -0,0 +1,72 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { parseDuration } from "../../domain/duration.js";
+import { refusedPlace } from "../../sends/upload.js";
+import { FETCHING } from "../../services/archive.js";
+import { archiveMedia, checkMediaArchive, validateMediaSince } from "../../services/media-archive.js";
+import { environmentOf, setExitCode } from "../context.js";
+import { FETCH, LOCAL_READ } from "../effects.js";
+import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { messengerContext } from "./context.js";
+import { addMediaArchiveMove } from "./media-archive-move-command.js";
+import { addMediaArchiveTimers } from "./media-archive-timer-command.js";
+import { stopOnSignal } from "./patience.js";
+export const addMediaArchiveCommands = (archive, messenger) => {
+    annotate(archive.command("download"), {
+        effects: FETCH,
+        examples: [`${messenger.app.command} attachments download ./media-archive`],
+    })
+        .description("archive media from selected chats; verify and keep existing copies")
+        .addHelpText("after", `\nMedia is saved only when you request a download; serve does not save these copies.\nTo disable an installed daily backup: ${messenger.app.command} <profile> attachments jobs stop <dir>.`)
+        .argument("<dir>", "archive directory; created if missing")
+        .option("--chat <chat>", `only this chat; repeat for more; ${messenger.chatArgument}`, (value, previous) => [...previous, value], [])
+        .option("--since-time <time>", "include messages from this ISO timestamp with a time zone")
+        .option("--pause <duration>", "pause between history pages", messenger.fetching?.pause ?? FETCHING.pause)
+        .action(async function (directory) {
+        const context = messengerContext(this, messenger);
+        const options = this.opts();
+        validateMediaSince(options.sinceTime);
+        const pauseMs = parseDuration(options.pause, "--pause");
+        if (context.settings.offline)
+            throw new CliError("validation_error", "archiving media needs online mode");
+        if (refusedPlace(directory, messenger.app, context.env))
+            throw new CliError("validation_error", "the archive cannot write credential, application or message-store folders");
+        const stop = stopOnSignal(this);
+        const environment = environmentOf(this);
+        const signal = AbortSignal.any([
+            stop.signal,
+            ...[environment.signal, environment.commandSignal].filter((one) => one !== undefined),
+        ]);
+        try {
+            const result = await context.withServices((services) => archiveMedia(services, {
+                directory,
+                chats: options.chat,
+                sinceTime: options.sinceTime,
+                pauseMs,
+                signal,
+                pageSize: messenger.history === "store" ? 100 : (messenger.fetching ?? FETCHING).page,
+                orderByTime: messenger.history !== "store" && messenger.fetching?.orderBy === "time",
+            }));
+            renderAnswer(this, context, itemOf(snakeKeys(result)), () => `${result.saved} saved, ${result.existing} verified copies already present; ${result.chats} chats\n`);
+        }
+        finally {
+            stop.release();
+        }
+    });
+    annotate(archive.command("check"), {
+        effects: LOCAL_READ,
+        examples: [`${messenger.app.command} attachments check ./media-archive`],
+    })
+        .description("rehash all archived files without connecting to the messenger")
+        .argument("<dir>", "archive directory")
+        .action(async function (directory) {
+        const context = messengerContext(this, messenger);
+        const environment = environmentOf(this);
+        const result = await checkMediaArchive(directory, environment.commandSignal ?? environment.signal);
+        if (!result.valid)
+            setExitCode(this, 1);
+        renderAnswer(this, context, itemOf(snakeKeys(result)), () => `${result.checked} files checked; ${result.files.filter((one) => !one.valid).length} missing or changed\n`);
+    });
+    addMediaArchiveTimers(archive, messenger);
+    addMediaArchiveMove(archive, messenger);
+};

package/dist/cli/messenger/media-archive-move-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Messenger } from "./context.js";
+export declare const addMediaArchiveMove: (attachments: Command, messenger: Messenger) => void;

package/dist/cli/messenger/media-archive-move-command.js

@@ -0,0 +1,40 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { refusedPlace } from "../../sends/upload.js";
+import { moveMediaArchive } from "../../services/media-archive-move.js";
+import { environmentOf } from "../context.js";
+import { LOCAL_WRITE } from "../effects.js";
+import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { messengerContext, refuseLocalWrite } from "./context.js";
+export const addMediaArchiveMove = (attachments, messenger) => {
+    annotate(attachments.command("move"), {
+        effects: LOCAL_WRITE,
+        mcp: false,
+        examples: [
+            `${messenger.app.command} attachments move ./media-archive ./older-images --before-time 2026-10-01T00:00:00Z --dry-run`,
+        ],
+    })
+        .description("move older images into another verified archive; remember their new locations")
+        .argument("<dir>", "source media archive directory")
+        .argument("<archive-dir>", "destination archive directory; created if needed")
+        .requiredOption("--before-time <time>", "move images whose message date is before this ISO timestamp with zone")
+        .option("--dry-run", "show counts and bytes without moving files or creating the destination")
+        .addHelpText("after", "\nCopies are verified at the destination before local image bytes are removed.\nSource manifests retain relocation records; checks follow them and downloads do not fetch them again.\nImages without a recorded message date are left in place and counted as undated.")
+        .action(async function (directory, archiveDirectory) {
+        const context = messengerContext(this, messenger);
+        const options = this.opts();
+        if (!options.dryRun)
+            refuseLocalWrite(context, messenger.app.command, "attachments.move");
+        if ([directory, archiveDirectory].some((folder) => refusedPlace(folder, messenger.app, context.env)))
+            throw new CliError("validation_error", "media archives cannot use credential, application or message-store folders");
+        const environment = environmentOf(this);
+        const result = await moveMediaArchive({
+            directory,
+            archiveDirectory,
+            beforeTime: options.beforeTime,
+            dryRun: options.dryRun,
+            signal: environment.commandSignal ?? environment.signal,
+        });
+        renderAnswer(this, context, itemOf(snakeKeys(result)), () => `${result.dryRun ? `${result.selected} images selected (${result.selectedBytes} bytes)` : `${result.moved} images moved (${result.movedBytes} bytes)`}; ${result.undated} undated images left in place\n`);
+    });
+};

package/dist/cli/messenger/media-archive-timer-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type Messenger } from "./context.js";
+export declare const addMediaArchiveTimers: (attachments: Command, messenger: Messenger) => void;

package/dist/cli/messenger/media-archive-timer-command.js

@@ -0,0 +1,70 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { dailyArchiveTimer, manageDailyArchiveTimer, runArchiveTimerCommand, } from "../../background/daily-archive-timer.js";
+import { thisMachine } from "../../background/system.js";
+import { refusedPlace } from "../../sends/upload.js";
+import { validateMediaSince } from "../../services/media-archive.js";
+import { environmentOf } from "../context.js";
+import { grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
+import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { messengerContext } from "./context.js";
+export const addMediaArchiveTimers = (attachments, messenger) => {
+    const archive = annotate(attachments.command("jobs"), { mcp: false }).description("daily media archive timers for this profile");
+    for (const action of ["install", "start", "stop", "status", "uninstall"]) {
+        const command = annotate(archive.command(action), {
+            effects: action === "status" ? LOCAL_READ : LOCAL_WRITE,
+            mcp: false,
+            examples: [`${messenger.app.command} attachments jobs ${action} ./media-archive`],
+        })
+            .description({
+            install: "install a Linux daily archive timer for this directory; starts nothing",
+            start: "enable the installed archive timer at login and start its daily schedule",
+            stop: "disable the archive timer; a download already running finishes",
+            status: "show whether this directory's archive timer is installed and active",
+            uninstall: "remove this directory's stopped archive timer; keep archived files",
+        }[action])
+            .argument("<dir>", "archive directory, used with the same profile as install");
+        if (action !== "status")
+            grantsAuthority(command);
+        if (action === "install")
+            command
+                .option("--at <HH:mm>", "daily start time", "03:00")
+                .option("--timezone <zone>", "IANA time zone of the daily start time", "UTC")
+                .option("--chat <chat>", `only this chat; repeat for more; ${messenger.chatArgument}`, (value, previous) => [...previous, value], [])
+                .option("--since-time <time>", "include messages from this ISO timestamp with a time zone");
+        command.action(async function (directory) {
+            const context = messengerContext(this, messenger);
+            const environment = environmentOf(this);
+            const signal = environment.commandSignal ?? environment.signal;
+            const system = environment.system ?? {
+                ...thisMachine(),
+                run: (args, env) => runArchiveTimerCommand(args, env, signal),
+            };
+            const options = this.opts();
+            validateMediaSince(options.sinceTime);
+            if (action === "install" && refusedPlace(directory, messenger.app, context.env))
+                throw new CliError("validation_error", "the archive cannot write credential, application or message-store folders");
+            // Canonicalize existing destinations so a symlink alias addresses the same timer.
+            const root = await realpath(directory).catch((error) => {
+                if (error.code !== "ENOENT")
+                    throw error;
+                return resolve(directory);
+            });
+            const plan = dailyArchiveTimer({
+                app: messenger.app,
+                profile: context.profile,
+                directory: root,
+                entry: system.entry,
+                env: context.env,
+                chats: options.chat,
+                sinceTime: options.sinceTime,
+                at: options.at,
+                timeZone: options.timezone,
+            });
+            const result = await manageDailyArchiveTimer(plan, action, system, context.env, environment.commandSignal ?? environment.signal);
+            renderAnswer(this, context, itemOf(snakeKeys(result)), () => `${result.name}: ${action}\n`);
+        });
+    }
+};

package/dist/cli/messenger/messages-comments-command.js

@@ -14,6 +14,7 @@ export const commentsCommand = (messenger) => {
         examples: [`${messenger.app.command} personal messages comments "News channel" 101 --limit 20`],
         effects: REMOTE_READ,
     })
+        .summary("comments on a channel post")
         .description("the comments under a channel post, oldest to newest; they live in its discussion group")
         .addHelpText("after", queryHelp(COMMENTS_QUERY))
         .argument("<chat>", `the channel: ${messenger.chatArgument}`)

package/dist/cli/messenger/messages-delete-command.js

@@ -17,7 +17,7 @@ export const deleteCommand = (messenger) => annotate(new Command("delete"), {
 })
     .description("delete messages for you only; with --for-everyone, for everyone in the chat")
     .argument("<chat>", messenger.chatArgument)
-    .argument("<messages...>", `the message ids, by spaces or commas, at most ${DELETE_AT_ONCE}`)
+    .argument("<message...>", `the message ids, by spaces or commas, at most ${DELETE_AT_ONCE}`)
     .addOption(ownerOnlyOption("--for-everyone", "delete for everyone in the chat, not only for you — they cannot get it back"))
     .addOption(ownerOnlyOption("--allow-dangerous", "go ahead without the question an ask level puts before a deletion"))
     .action(async function (chat, messages) {

package/dist/cli/messenger/messages-search-command.js

@@ -26,6 +26,7 @@ export const messagesSearchCommand = (messenger) => {
     });
     const syncing = syncsFirst(messenger) ? "; optionally fetches new messages with --sync-first" : "";
     return command
+        .summary("find messages by words and filters")
         .description(messenger.serverSearch
         ? `search messenger messages in the local store and on the messenger's server (--backend)${syncing}; --discover searches the archive only`
         : `search messenger messages in the local store — what was read, fetched or kept by serve${syncing}; --discover searches the archive only`)

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

@@ -9,6 +9,7 @@ import { syncOptions, syncRequest, syncsFirst } from "./search-sync-options.js";
 import { countsAnswer, refuseJsonl } from "./stats-answers.js";
 const GROUPINGS = ["chat", "sender", "day", "hour"];
 export const messagesStatsCommand = (messenger) => syncOptions(annotate(new Command("show"), { effects: REMOTE_READ, output: { entity: "message_counts" } }), messenger)
+    .summary("count stored messages by chat, sender, day or hour")
     .description(`how many stored messages match, by chat, sender, day or hour — the local store only${syncsFirst(messenger) ? "; optionally fetches new messages with --sync-first" : ""}`)
     .argument("[query...]", "a strict Lucene query, as for search messages; none counts every stored message; with --saved, more words AND-ed to it")
     .option("--by <chat|sender|day|hour>", "what to count by (default: chat)", groupingOf)

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

@@ -61,6 +61,7 @@ export const modelsCommand = (messenger) => {
     const models = annotate(new Command("models"), { mcp: false }).description("models that run on this machine");
     const audio = models.command("audio").description("speech models for transcribing voice messages");
     withQuery(annotate(audio.command("list"), { effects: LOCAL_READ, examples: [`${tool} models audio list`] }), MODELS_QUERY)
+        .summary("speech models and their download status")
         .description("the speech models, most suitable first, which are downloaded, and which one is the default")
         .action(async function (words) {
         const context = baseContext(this, messenger.resolveSettings);
@@ -107,6 +108,7 @@ export const modelsCommand = (messenger) => {
     });
     const text = models.command("text").description("embedding models for searching conversations by meaning");
     withQuery(annotate(text.command("list"), { effects: LOCAL_READ, examples: [`${tool} models text list`] }), MODELS_QUERY)
+        .summary("embedding models and their download status")
         .description("the embedding models, most suitable first, which are downloaded, and which one is the default")
         .action(async function (words) {
         const context = baseContext(this, messenger.resolveSettings);
@@ -127,6 +129,7 @@ export const modelsCommand = (messenger) => {
     }))
         .argument("<model>", "a model id from `models text list`")
         .addOption(new Option("--accept-terms", "accept the model's licence terms, for a model that has its own"))
+        .summary("download and verify an embedding model")
         .description("download an embedding model once, checked against the sha256 this version expects")
         .action(async function (id, options) {
         const context = baseContext(this, messenger.resolveSettings);

package/dist/cli/messenger/private-people-command.js

@@ -16,8 +16,8 @@ export const privatePeopleCommands = (messenger) => {
     const alias = new Command("alias").description("a private local display name in the selected account");
     annotate(alias.command("set"), { effects: LOCAL_WRITE })
         .description("your own name for a person in this account; kept on this machine, never sent")
-        .argument("<person>")
-        .argument("<alias>")
+        .argument("<person>", "the person's id, reference or known name")
+        .argument("<alias>", "the private name to use for this person")
         .action(async function (person, value) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "contacts.alias.set");
@@ -25,7 +25,7 @@ export const privatePeopleCommands = (messenger) => {
     });
     annotate(alias.command("rm"), { effects: LOCAL_WRITE })
         .description("drop your local name for a person; their own name shows again")
-        .argument("<person>")
+        .argument("<person>", "the person's id, reference or known name")
         .action(async function (person) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "contacts.alias.rm");
@@ -34,7 +34,7 @@ export const privatePeopleCommands = (messenger) => {
     const notes = new Command("notes").description("your private notes on a stored contact, the same in every account that sees them");
     withQuery(annotate(notes.command("list"), { effects: LOCAL_READ })
         .description("every private note you keep on a person, oldest first")
-        .argument("<person>"), NOTES_QUERY).action(async function (person, words) {
+        .argument("<person>", "the person's id, reference or known name"), NOTES_QUERY).action(async function (person, words) {
         const context = messengerContext(this, messenger);
         listQuery(typedQuery(words), NOTES_QUERY, "contacts notes list");
         const items = await context.withServices((services) => services.privatePeople.notes(person));
@@ -42,8 +42,8 @@ export const privatePeopleCommands = (messenger) => {
     });
     annotate(notes.command("show"), { effects: LOCAL_READ, output: { entity: "contact_note" } })
         .description("one private note on a person, with its revision for edit")
-        .argument("<person>")
-        .argument("<id>")
+        .argument("<person>", "the person's id, reference or known name")
+        .argument("<id>", "the note id from contacts notes list")
         .action(async function (person, id) {
         const context = messengerContext(this, messenger);
         renderAnswer(this, context, itemOf(await context.withServices((services) => services.privatePeople.note(person, id))));
@@ -56,10 +56,12 @@ export const privatePeopleCommands = (messenger) => {
             .description(name === "add"
             ? "add a private note on a person from stdin or --file; never sent"
             : "replace a note's text; --revision must match the one you read")
-            .argument("<person>")
+            .argument("<person>", "the person's id, reference or known name")
             .addOption(ownerOnlyOption("--file <path>", "read note text from a file; omitted or - reads stdin"));
         if (name === "edit")
-            command.argument("<id>").requiredOption("--revision <n>", "the revision you read before editing");
+            command
+                .argument("<id>", "the note id from contacts notes list")
+                .requiredOption("--revision <n>", "the revision you read before editing");
         command.action(async function (person, id) {
             const context = messengerContext(this, messenger);
             refuseLocalWrite(context, messenger.app.command, `contacts.notes.${name}`);
@@ -76,8 +78,8 @@ export const privatePeopleCommands = (messenger) => {
     }
     annotate(notes.command("remove"), { effects: LOCAL_WRITE })
         .description("delete one private note on a person")
-        .argument("<person>")
-        .argument("<id>")
+        .argument("<person>", "the person's id, reference or known name")
+        .argument("<id>", "the note id from contacts notes list")
         .action(async function (person, id) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "contacts.notes.remove");

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

@@ -25,6 +25,7 @@ const selectionOf = (value) => {
 };
 export const rankingsTopCommand = (messenger, target) => {
     const command = syncOptions(annotate(new Command("top"), { effects: REMOTE_READ, output: { entity: "ranking" } }), messenger)
+        .summary("rank messages or people by a measure or score")
         .description(`rank ${target === "messages" ? "stored messages" : "the human authors of stored messages"} by a measure or explainable score; counters are snapshots with per-field observation freshness`)
         .argument("[query...]", "a strict Lucene query; none selects every stored message")
         .addOption(new Option("--measure <name>", "the ranking metric; not with score or weights").choices(target === "messages" ? [...MESSAGE_MEASURES] : [...AUTHOR_MEASURES]))
@@ -86,6 +87,7 @@ const emojiSplit = (reactions) => [
     ...(reactions.length > SHOWN_REACTIONS ? [`+${reactions.length - SHOWN_REACTIONS}`] : []),
 ].join(" · ");
 export const rankingEvidenceCommand = (messenger, target) => annotate(new Command("evidence"), { effects: LOCAL_READ, output: { entity: "evidence" } })
+    .summary("evidence for an exact statistics selection")
     .description("bounded messages, answer pairs or retention members from an exact drilldown selection")
     .argument(target === "messages" ? "<message>" : "<person>", target === "messages"
     ? "the canonical message locator, or retention cohort reference, from drilldown"

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

@@ -6,7 +6,10 @@ import { messengerContext } from "./context.js";
 /** `reactions add|remove`: the owner's own reaction on a message. */
 export const reactionsCommand = (messenger) => {
     const reactions = new Command("reactions").description("react to messages");
-    annotate(reactions.command("add"), { effects: REMOTE_WRITE })
+    annotate(reactions.command("add"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal reactions add "Book club" 101 👍`],
+    })
         .description("put your reaction on a message; it replaces the one you had")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the message id")
@@ -16,7 +19,10 @@ export const reactionsCommand = (messenger) => {
         const reacted = await context.withServices((services) => services.messages.react({ chat, message: message.trim(), emoji: emoji.trim() }));
         renderAnswer(this, context, itemOf(snakeKeys(reacted)));
     });
-    annotate(reactions.command("remove"), { effects: REMOTE_WRITE })
+    annotate(reactions.command("remove"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal reactions remove "Book club" 101`],
+    })
         .description("take your reaction off a message")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the message id")

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

@@ -6,6 +6,7 @@ import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
 import { refuseJsonl, retentionAnswer } from "./stats-answers.js";
 export const retentionCommand = (messenger) => annotate(new Command("retention"), { effects: REMOTE_READ, output: { entity: "retention" } })
+    .summary("joining cohorts and observed membership checkpoints")
     .description("joining cohorts and observed checkpoint membership from saved roster observations")
     .argument("<chat>", messenger.chatArgument)
     .option("--since-time <time>", "joining period starts at ISO 8601 or a relative time; last 90 days by default")

package/dist/cli/messenger/review.js

@@ -29,6 +29,7 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
     output: { entity: "message", view: "summary" },
     query: REVIEW_QUERY,
 })
+    .summary("chats with new activity or unanswered messages")
     .description("every message, yours too, in chats that changed since a point — for reviewing who owes what")
     .addHelpText("after", queryHelp(REVIEW_QUERY))
     .argument("[query...]", `where the last review ended and which chat: date>2h, chat:"Book club"; ${REVIEW_DAYS} days ago if no date`)