@wirecat/cli-core 0.396.0 → 0.398.0

package/dist/cli/messenger/inbox.js

@@ -29,10 +29,12 @@ export const PARTIAL_NOTE = "the messenger did not list every chat, and did not
  * `date>2h` is a one-off look from a time of your choosing and leaves the points where they were.
  */
 export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
+    examples: [`${messenger.app.command} personal inbox --limit 10`],
     effects: REMOTE_READ,
     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/lacks.d.ts

@@ -1,3 +1,4 @@
+import type { Command } from "commander";
 import type { MessengerAdapter } from "../../ports/messenger.js";
 type Need = readonly [method: keyof MessengerAdapter, what: string];
 /**
@@ -9,10 +10,16 @@ export declare const COMMAND_NEEDS: Readonly<Record<string, Need>>;
 interface Lacking {
     channelComments?: boolean;
     lacks?: readonly (keyof MessengerAdapter)[];
+    never?: readonly (keyof MessengerAdapter)[];
     history?: "server" | "store";
 }
 /** The one method this command needs and this messenger never has; none when it has it or the store answers. */
 export declare const lackedNeed: (messenger: Lacking | undefined, path: string) => Need | undefined;
 /** Refuses, before a connection, a command whose one method this messenger never has. */
 export declare const refuseLacking: (messenger: Lacking | undefined, path: readonly string[]) => void;
+/**
+ * Hides under `group` each command whose one method this messenger can `never` have, from help, `commands` and MCP;
+ * typed anyway, it still refuses. A method it only `lacks` keeps its command in sight, since it may come.
+ */
+export declare const hideNever: <T extends Command>(messenger: Lacking, group: T) => T;
 export {};

package/dist/cli/messenger/lacks.js

@@ -32,7 +32,7 @@ export const lackedNeed = (messenger, path) => {
         return undefined;
     if (path === "messages comments" && messenger?.channelComments === false)
         return need;
-    if (!messenger?.lacks?.includes(need[0]))
+    if (!messenger?.lacks?.includes(need[0]) && !messenger?.never?.includes(need[0]))
         return undefined;
     return messenger.history === "store" && STORE_ANSWERS.has(path) ? undefined : need;
 };
@@ -42,3 +42,20 @@ export const refuseLacking = (messenger, path) => {
     if (need)
         throw new CliError("validation_error", `this messenger cannot ${need[1]}`);
 };
+/**
+ * Hides under `group` each command whose one method this messenger can `never` have, from help, `commands` and MCP;
+ * typed anyway, it still refuses. A method it only `lacks` keeps its command in sight, since it may come.
+ */
+export const hideNever = (messenger, group) => {
+    const walk = (command, path) => {
+        for (const child of command.commands) {
+            const at = [...path, child.name()];
+            const need = COMMAND_NEEDS[at.join(" ")];
+            if (need && messenger.never?.includes(need[0]))
+                child._hidden = true;
+            walk(child, at);
+        }
+    };
+    walk(group, [group.name()]);
+    return group;
+};

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,39 @@
+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,
+        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 = attachments.command("jobs").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,
+            ...(action === "status" ? {} : { 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-command.js

@@ -17,6 +17,7 @@ import { linksCommand } from "./conversations-command.js";
 import { downloadSubcommand } from "./download-command.js";
 import { heardItems, hearForCommand, hearingMissing, MODEL_OPTION, spokenItems, TRANSCRIBE_OPTION, } from "./hearing-command.js";
 import { cursorOf, historyQuery, historyWindow } from "./history-query.js";
+import { hideNever } from "./lacks.js";
 import { threadAnswer } from "./message-answers.js";
 import { messageItem, messageItems, viewOf } from "./message-items.js";
 import { commentsCommand } from "./messages-comments-command.js";
@@ -174,7 +175,7 @@ export const messagesCommand = (messenger) => {
     messages.addCommand(commentsCommand(messenger));
     messages.addCommand(linksCommand(messenger));
     messages.addCommand(syncCommand(messenger));
-    return messages;
+    return hideNever(messenger, messages);
 };
 /** Mail lives in the mail tables of the store, whichever messenger CLI reads it. */
 const isMailLocator = (chat, message) => message === undefined && isLocator(chat) && parseLocator(chat).provider === "email";

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

@@ -58,9 +58,10 @@ const modelLine = (item, width) => `${item.default ? "*" : " "} ${item.id.padEnd
     (item.downloaded ? "downloaded" : "—".padEnd(10));
 export const modelsCommand = (messenger) => {
     const tool = `${messenger.app.command} personal`;
-    const models = annotate(new Command("models"), { mcp: false }).description("models that run on this machine");
+    const models = new Command("models").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);
@@ -75,6 +76,7 @@ export const modelsCommand = (messenger) => {
         });
     });
     reachesOtherService(annotate(audio.command("download"), {
+        mcp: false,
         effects: FETCH,
         output: { entity: "model" },
         examples: [`${tool} models audio download parakeet-v3`],
@@ -107,6 +109,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);
@@ -121,12 +124,14 @@ export const modelsCommand = (messenger) => {
         });
     });
     reachesOtherService(annotate(text.command("download"), {
+        mcp: false,
         effects: FETCH,
         output: { entity: "model" },
         examples: [`${tool} models text download ${DEFAULT_TEXT_MODEL}`],
     }))
         .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);
@@ -168,7 +173,7 @@ export const modelsCommand = (messenger) => {
 /** `images models`: registered with picture search, the only thing these models serve. */
 export const imageModelsCommand = (messenger) => {
     const tool = messenger.app.command;
-    const image = annotate(new Command("models"), { mcp: false }).description("models that read pictures, for `images embed` and picture search");
+    const image = new Command("models").description("models that read pictures, for `images embed` and picture search");
     withQuery(annotate(image.command("list"), { effects: LOCAL_READ, examples: [`${tool} images models list`] }), MODELS_QUERY)
         .description("the picture models, which are downloaded, and which one is the default")
         .action(async function (words) {
@@ -184,6 +189,7 @@ export const imageModelsCommand = (messenger) => {
         });
     });
     reachesOtherService(annotate(image.command("download"), {
+        mcp: false,
         effects: FETCH,
         output: { entity: "model" },
         examples: [`${tool} images models download ${DEFAULT_IMAGE_MODEL}`],

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/replies-command.js

@@ -14,7 +14,7 @@ import { replyConsentsCommand } from "./replies-consents-command.js";
 import { addReplyEditors } from "./replies-edit-command.js";
 /** `replies`: rules that answer messages for the owner, from `serve`, and only to the people and chats the audience allows. */
 export const repliesCommand = (messenger) => {
-    const replies = annotate(new Command("replies"), { mcp: false }).description("rules that answer messages for you, kept in a file of this profile");
+    const replies = new Command("replies").description("rules that answer messages for you, kept in a file of this profile");
     if (messenger.autoReplies === false)
         replies.hook("preAction", () => {
             throw new CliError("validation_error", `${messenger.name ?? messenger.app.command} cannot send automatic replies`);

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

@@ -10,7 +10,7 @@ import { REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { queryHelp } from "../list-query.js";
 import { pointsOf } from "./catch-up.js";
-import { catchUpQuery, REVIEW_QUERY, reviewAnswer } from "./catch-up-answers.js";
+import { catchUpQuery, OFFLINE_REVIEW, REVIEW_QUERY, reviewAnswer } from "./catch-up-answers.js";
 import { messengerContext } from "./context.js";
 import { heardItems, hearForCommand, MODEL_OPTION, spokenItems, TRANSCRIBE_OPTION } from "./hearing-command.js";
 import { PARTIAL_NOTE } from "./inbox.js";
@@ -25,10 +25,12 @@ export const unansweredHours = (value, flag = "--unanswered") => value === true
  * tasks in the local store from what it read (`../../services/task-rules.ts`); nothing reaches the messenger.
  */
 export const reviewCommand = (messenger) => annotate(new Command("review"), {
+    examples: [`${messenger.app.command} personal review "date>2h"`],
     effects: REMOTE_READ,
     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`)
@@ -38,6 +40,7 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
     .option(...TRANSCRIBE_OPTION)
     .option(...MODEL_OPTION)
     .option("--new", "what changed since the last `review --new`, a point per chat — for scheduled runs")
+    .addHelpText("after", "With --offline it reads the local store: only what was already synced, and --new keeps its point.")
     .addHelpText("after", "To mark a chat read, use `chats mark-read <chat>`. The other side sees it.")
     .action(async function (query) {
     const options = this.opts();
@@ -98,7 +101,8 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
             .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
         return read.length === 0 ? "" : renderMessages(spokenItems(read, hearing), viewOf(context, messenger));
     });
-    saved?.save(found.checked ?? {});
+    if (!found.offline)
+        saved?.save(found.checked ?? {});
 });
 /** What the answer's steps do not say: a person's context for the review just shown. */
 const notes = (found, pretty, renderer) => {
@@ -110,6 +114,8 @@ const notes = (found, pretty, renderer) => {
             (found.tasks.review > 0 ? `, ${found.tasks.review} pair(s) to review — tasks duplicates` : ""));
     if (found.partial && pretty)
         renderer.warn(PARTIAL_NOTE);
+    if (found.offline && pretty)
+        renderer.warn(OFFLINE_REVIEW);
     if (found.unanswered)
         renderer.note(`questions from ${found.since} to ${found.until} still open after ${found.unanswered.olderThanHours} hours; ` +
             "an answer after the review's end is not seen");

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

@@ -61,7 +61,7 @@ const withWhen = (command) => command
  */
 export const scheduleCommand = (messenger) => {
     const { app } = messenger;
-    const command = annotate(new Command("schedule"), { mcp: false }).description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
+    const command = new Command("schedule").description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
     const prepare = (self) => {
         const context = messengerContext(self, messenger);
         const system = environmentOf(self).system ?? thisMachine();
@@ -192,7 +192,7 @@ export const scheduleCommand = (messenger) => {
                 .join("\n");
         });
     });
-    annotate(command.command("run"), { effects: REMOTE_WRITE })
+    annotate(command.command("run"), { effects: REMOTE_WRITE, mcp: false })
         .description("run a schedule now, as its timer would, and wait for it")
         .argument("<name>")
         .action(async function (name) {
@@ -216,7 +216,7 @@ export const scheduleCommand = (messenger) => {
         rmSync(file, { force: true });
         say({ name, removed: true }, [`Removed ${name}.`]);
     });
-    annotate(command.command("exec"), { effects: REMOTE_WRITE })
+    annotate(command.command("exec"), { effects: REMOTE_WRITE, mcp: false })
         .description("what a timer runs, given the schedule's file; to run one by hand, use run")
         .argument("<file>")
         .action(async function (file) {