@wirecat/cli-core 0.397.0 → 0.399.0

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

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { analysisConsents } from "../../analysis/consents.js";
 import { openAnalysis, providerIdentity } from "../../analysis/provider.js";
 import { runAnalysis } from "../../analysis/runner.js";
@@ -39,7 +39,10 @@ export const conversationsCommand = (messenger) => {
         "chat that changed since its build and every group never built; never asks the messenger")
         .option("--chat <chat>", messenger.chatArgument)
         .option("--analyze", "link batches using the configured analysis provider; requires --chat and remembers consent for this chat/provider")
-        .option("--provider <provider>", "analysis: agent, openai or anthropic")
+        .addOption(new Option("--analysis-provider <provider>", "analysis: agent, openai or anthropic").conflicts("provider"))
+        .addOption(new Option("--provider <provider>", "compatibility alias for --analysis-provider")
+        .hideHelp()
+        .conflicts("analysisProvider"))
         .option("--model <model>", "analysis model; overrides analysis_model")
         .option("--base-url <url>", "analysis API endpoint; overrides analysis_base_url")
         .option("--size <n>", "analysis answer messages per batch, 10–200; default 50", positiveCount("--size"))
@@ -95,7 +98,8 @@ export const conversationsCommand = (messenger) => {
             renderAnswer(this, context, itemOf(snakeKeys(result)));
             return;
         }
-        if (options.provider !== undefined ||
+        if (options.analysisProvider !== undefined ||
+            options.provider !== undefined ||
             options.model !== undefined ||
             options.baseUrl !== undefined ||
             options.size !== undefined ||
@@ -247,18 +251,19 @@ export const conversationsCommand = (messenger) => {
         .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")
+        .addOption(new Option("--answer-model <model>", "only the stored answers this model gave").conflicts("model"))
+        .addOption(new Option("--model <model>", "compatibility alias for --answer-model").hideHelp().conflicts("answerModel"))
         .action(async function () {
-        const { chat, model } = this.opts();
+        const { chat, model, answerModel } = this.opts();
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, LINKS_KEY);
-        const cleared = await context.withServices((services) => services.conversations.clearAnswers(chat, model));
+        const cleared = await context.withServices((services) => services.conversations.clearAnswers(chat, answerModel ?? model));
         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 " +
+        "with --embedding-provider through a service and your key; resumes where it stopped; without --chat, every " +
         "built chat with chunks left, on this machine only")
         .option("--chat <chat>", messenger.chatArgument))
         .option("--threads <n>", "local: threads in all (default: min(8, cores))", positiveCount("--threads"))
@@ -324,7 +329,10 @@ export const conversationsCommand = (messenger) => {
         const chat = chatOf(options);
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, EMBED_KEY);
-        const given = options.model !== undefined || options.provider !== undefined || options.baseUrl !== undefined;
+        const given = options.model !== undefined ||
+            options.embeddingProvider !== undefined ||
+            options.provider !== undefined ||
+            options.baseUrl !== undefined;
         const model = given ? choiceOf(options, messenger, context, { needKey: false }) : undefined;
         const cleared = await context.withServices((services) => services.embeddings.clear(chat, model));
         renderAnswer(this, context, itemOf(cleared), () => `${cleared.cleared} vectors dropped\n`);
@@ -365,16 +373,19 @@ export const conversationsCommand = (messenger) => {
     annotate(consents.command("revoke"), { effects: LOCAL_WRITE })
         .description("forget analysis permissions so the next analysis asks again")
         .option("--chat <chat>", "revoke only this chat's consents; defaults to every chat")
-        .option("--provider <identity>", "exact provider identity from consents list; defaults to every provider")
+        .addOption(new Option("--consent-provider <identity>", "exact provider identity from consents list; defaults to every provider").conflicts("provider"))
+        .addOption(new Option("--provider <identity>", "compatibility alias for --consent-provider")
+        .hideHelp()
+        .conflicts("consentProvider"))
         .action(async function () {
-        const { chat, provider } = this.opts();
+        const { chat, provider, consentProvider } = this.opts();
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, LINKS_KEY);
         await context.withStore(async (store, account) => {
             const chatId = chat === undefined
                 ? undefined
                 : (await servicesFor(storedDeps(messenger, store, account, context.guard)).conversations.batchStatus(chat, BATCH_SIZE.default)).chat;
-            await analysisConsents(store, account).revoke(chatId, provider);
+            await analysisConsents(store, account).revoke(chatId, consentProvider ?? provider);
         });
         renderAnswer(this, context, itemOf({ revoked: true }));
     });
@@ -393,7 +404,10 @@ const chatOf = ({ chat }) => {
 };
 const withModelOptions = (command) => command
     .option("--model <model>", "local: a model id from `models text list` (default: e5-small); remote: the provider's model")
-    .option("--provider <provider>", "embedding provider: local or openai; flags override profile settings")
+    .addOption(new Option("--embedding-provider <provider>", "embedding provider: local or openai; flags override profile settings").conflicts("provider"))
+    .addOption(new Option("--provider <provider>", "compatibility alias for --embedding-provider")
+    .hideHelp()
+    .conflicts("embeddingProvider"))
     .option("--base-url <url>", "a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine")
     .option("--dims <n>", "remote: the vector size — needed with --base-url; shortens an OpenAI model's", positiveCount("--dims"));
 /** How much one run over many chats may do: the owner's machine, not a background job, pays for it. */
@@ -412,7 +426,7 @@ const bounds = ({ maxChats, maxChunks }) => ({
 /** Work nobody named chat by chat never sends chat text off the machine. */
 const localOnly = (model, what) => {
     if (typeof model !== "string") {
-        throw new CliError("validation_error", `${what} uses the model on this machine only — drop --provider and --base-url, or embed one chat with --chat`);
+        throw new CliError("validation_error", `${what} uses the model on this machine only — drop --embedding-provider and --base-url, or embed one chat with --chat`);
     }
 };
 const renderRefreshed = (command, context, refreshed) => {

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

@@ -14,7 +14,7 @@ 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 () {

package/dist/cli/messenger/hearing-command.d.ts

@@ -2,7 +2,7 @@ import type { Message } from "../../domain/models.js";
 import { type Hearing } from "../../speech/hearing.js";
 import type { Messenger, MessengerContext, ReadConnection } from "./context.js";
 export declare const TRANSCRIBE_OPTION: readonly ["--transcribe", "turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes"];
-export declare const MODEL_OPTION: readonly ["--model <id>", "which downloaded speech model hears them, with --transcribe; `models audio list` shows them"];
+export declare const MODEL_OPTION: readonly ["--model <model>", "which downloaded speech model hears them, with --transcribe; `models audio list` shows them"];
 /**
  * Kept transcripts on every read; new ones with `--transcribe`, using the read's connection when
  * supplied. It is released before local recognition. `undefined` when there is no voice message, and then no file is opened.

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

@@ -5,7 +5,7 @@ export const TRANSCRIBE_OPTION = [
     "turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes",
 ];
 export const MODEL_OPTION = [
-    "--model <id>",
+    "--model <model>",
     "which downloaded speech model hears them, with --transcribe; `models audio list` shows them",
 ];
 /**

package/dist/cli/messenger/inbox.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { renderMessages } from "../../render/messages.js";
 import { CHAT_KINDS } from "../../services/chats.js";
 import { kindsOf } from "../../services/inbox.js";
@@ -29,6 +29,7 @@ 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,
@@ -40,7 +41,7 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     .option("--new", "what arrived since the last check, each message once — for scheduled runs")
     .option("--limit <n>", "at most this many per chat, the newest", positiveCount("--limit"))
     .option("--all", "muted and archived chats too — left out unless they mention you or reply to you")
-    .option("--kind <kinds>", `only chats of these kinds, comma-separated: ${CHAT_KINDS.join(", ")}`)
+    .addOption(new Option("--kind <kinds>", `compatibility spelling for kind:; ${CHAT_KINDS.join(", ")}`).hideHelp())
     .option(...TRANSCRIBE_OPTION)
     .option(...MODEL_OPTION)
     .addHelpText("after", "To mark a chat read, use `chats mark-read <chat>`. The other side sees it.")
@@ -50,8 +51,10 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     const context = messengerContext(this, messenger);
     const { app } = messenger;
     const { settings, renderer, format, env } = context;
-    const kinds = kind === undefined ? undefined : kindsOf(kind);
-    const { since, meta } = catchUpQuery(query, INBOX_QUERY, "inbox");
+    const { since, meta, kinds: queriedKinds } = catchUpQuery(query, INBOX_QUERY, "inbox");
+    if (kind !== undefined && queriedKinds !== undefined)
+        throw new CliError("validation_error", "give kind: or its legacy --kind spelling, not both");
+    const kinds = queriedKinds ?? (kind === undefined ? undefined : kindsOf(kind));
     if (fresh && since !== undefined)
         throw new CliError("validation_error", "--new keeps its own point — not with a date in the query");
     const saved = fresh && since === undefined

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/media-archive-move-command.js

@@ -9,7 +9,6 @@ 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`,
         ],

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

@@ -11,11 +11,11 @@ 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");
+    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,
-            mcp: false,
+            ...(action === "status" ? {} : { mcp: false }),
             examples: [`${messenger.app.command} attachments jobs ${action} ./media-archive`],
         })
             .description({

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-stats-command.js

@@ -12,7 +12,7 @@ export const messagesStatsCommand = (messenger) => syncOptions(annotate(new Comm
     .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)
+    .option("--by <group>", "count by chat, sender, day or hour (default: chat)", groupingOf)
     .option("--chat <chat>", `only this chat — the same as chat: in the query; ${messenger.chatArgument}`)
     .option("--source <accounts>", "every account of this messenger held in the store; personal, bots or all — the same as in: in the query")
     .option("--limit <n>", "how many rows", positiveCount("--limit"))

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

@@ -23,7 +23,7 @@ export const metadataCommand = (messenger) => {
         .description("fetch group and channel descriptions again and cache them")
         .option("--chat <chat>", "stored group/channel; repeat for several", (value, previous) => [...previous, value], [])
         .option("--only-missing", "only chats with no metadata yet; without --chat, every stored group/channel")
-        .option("--limit <number>", "process at most 1–500 chats", positiveCount("--limit"), 50)
+        .option("--limit <n>", "process at most 1–500 chats", positiveCount("--limit"), 50)
         .action(async function () {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "metadata.refresh");

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

@@ -58,7 +58,7 @@ 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")
@@ -76,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`],
@@ -123,6 +124,7 @@ export const modelsCommand = (messenger) => {
         });
     });
     reachesOtherService(annotate(text.command("download"), {
+        mcp: false,
         effects: FETCH,
         output: { entity: "model" },
         examples: [`${tool} models text download ${DEFAULT_TEXT_MODEL}`],
@@ -171,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) {
@@ -187,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

@@ -54,10 +54,11 @@ export const privatePeopleCommands = (messenger) => {
             output: { entity: "contact_note" },
         }), { name: "text", description: "the note's text" })
             .description(name === "add"
-            ? "add a private note on a person from stdin or --file; never sent"
+            ? "add a private note on a person from stdin or --text-file; never sent"
             : "replace a note's text; --revision must match the one you read")
             .argument("<person>", "the person's id, reference or known name")
-            .addOption(ownerOnlyOption("--file <path>", "read note text from a file; omitted or - reads stdin"));
+            .addOption(ownerOnlyOption("--text-file <path>", "read note text from a file; omitted or - reads stdin").conflicts("file"))
+            .addOption(ownerOnlyOption("--file <path>", "compatibility alias for --text-file").hideHelp().conflicts("textFile"));
         if (name === "edit")
             command
                 .argument("<id>", "the note id from contacts notes list")
@@ -65,7 +66,8 @@ export const privatePeopleCommands = (messenger) => {
         command.action(async function (person, id) {
             const context = messengerContext(this, messenger);
             refuseLocalWrite(context, messenger.app.command, `contacts.notes.${name}`);
-            const { file, revision } = this.opts();
+            const { textFile, file: legacyFile, revision, } = this.opts();
+            const file = textFile ?? legacyFile;
             const text = file === undefined || file === "-" ? await readAll(context.stdin) : await readFile(file, "utf8");
             const version = Number(revision);
             if (name === "edit" && (!Number.isSafeInteger(version) || version < 1))

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/replies-edit-command.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
 import { type Messenger } from "./context.js";
-export declare const REPLY_EDIT_OPTIONS: readonly [readonly ["--do <actions>", "actions: reply, task, or both, comma-separated"], readonly ["--kinds <kinds>", "chat kinds: dialog, group; comma-separated, empty for any"], readonly ["--allow-chats <ids>", "only these chat ids, comma-separated; empty for any"], readonly ["--deny-chats <ids>", "leave these chat ids out, comma-separated; empty clears"], readonly ["--words <words>", "match any of these whole words, comma-separated; empty clears"], readonly ["--question", "match only questions"], readonly ["--no-question", "do not require a question"], readonly ["--mentions-me", "require a mention of you or a reply to you"], readonly ["--no-mentions-me", "do not require a mention of you or a reply to you"], readonly ["--allow-people <ids>", "only these sender ids, comma-separated; empty for any"], readonly ["--deny-people <ids>", "leave these sender ids out, comma-separated; empty clears"], readonly ["--contacts-only", "match only contacts"], readonly ["--no-contacts-only", "do not require a contact"], readonly ["--template <text>", "the reply template"], readonly ["--model <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"], readonly ["--as-reply", "send as a reply to the matched message"], readonly ["--no-as-reply", "send without linking to the matched message"], readonly ["--per-chat <limit>", "at most this many per chat, such as 1/12h"], readonly ["--per-person <limit>", "at most this many per person, such as 1/1d"], readonly ["--outside <hours>", "answer outside this 24-hour window, such as 09:00-19:00"], readonly ["--days <days>", "days of the working window, such as mon-fri or sat,sun"], readonly ["--timezone <zone>", "the IANA timezone for the working window"], readonly ["--no-hours", "clear the working window"]];
+export declare const REPLY_EDIT_OPTIONS: readonly [readonly ["--do <actions>", "actions: reply, task, or both, comma-separated"], readonly ["--kinds <kinds>", "chat kinds: dialog, group; comma-separated, empty for any"], readonly ["--allow-chats <ids>", "only these chat ids, comma-separated; empty for any"], readonly ["--deny-chats <ids>", "leave these chat ids out, comma-separated; empty clears"], readonly ["--words <words>", "match any of these whole words, comma-separated; empty clears"], readonly ["--question", "match only questions"], readonly ["--no-question", "do not require a question"], readonly ["--mentions-me", "require a mention of you or a reply to you"], readonly ["--no-mentions-me", "do not require a mention of you or a reply to you"], readonly ["--allow-people <ids>", "only these sender ids, comma-separated; empty for any"], readonly ["--deny-people <ids>", "leave these sender ids out, comma-separated; empty clears"], readonly ["--contacts-only", "match only contacts"], readonly ["--no-contacts-only", "do not require a contact"], readonly ["--template <text>", "the reply template"], readonly ["--template-mode <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"], readonly ["--as-reply", "send as a reply to the matched message"], readonly ["--no-as-reply", "send without linking to the matched message"], readonly ["--per-chat <limit>", "at most this many per chat, such as 1/12h"], readonly ["--per-person <limit>", "at most this many per person, such as 1/1d"], readonly ["--outside <hours>", "answer outside this 24-hour window, such as 09:00-19:00"], readonly ["--days <days>", "days of the working window, such as mon-fri or sat,sun"], readonly ["--timezone <zone>", "the IANA timezone for the working window"], readonly ["--no-hours", "clear the working window"]];
 export declare const REPLY_AUDIENCE_OPTIONS: readonly [readonly ["--reply <mode>", "answer all or only listed senders and chats: all, listed"], readonly ["--allow-people <ids>", "replace allowed sender ids, comma-separated; empty clears"], readonly ["--allow-chats <ids>", "replace allowed chat ids, comma-separated; empty clears"], readonly ["--deny-people <ids>", "replace denied sender ids, comma-separated; empty clears; deny wins"], readonly ["--deny-chats <ids>", "replace denied chat ids, comma-separated; empty clears; deny wins"]];
 export declare const addReplyEditors: (replies: Command, messenger: Messenger) => void;

package/dist/cli/messenger/replies-edit-command.js

@@ -1,5 +1,5 @@
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { addRule, editAudience, editRule, switchRule } from "../../replies/edit.js";
 import { audienceWarnings, repliesPathFor } from "../../replies/rules.js";
 import { grantsAuthority, LOCAL_WRITE } from "../effects.js";
@@ -20,7 +20,7 @@ export const REPLY_EDIT_OPTIONS = [
     ["--contacts-only", "match only contacts"],
     ["--no-contacts-only", "do not require a contact"],
     ["--template <text>", "the reply template"],
-    ["--model <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"],
+    ["--template-mode <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"],
     ["--as-reply", "send as a reply to the matched message"],
     ["--no-as-reply", "send without linking to the matched message"],
     ["--per-chat <limit>", "at most this many per chat, such as 1/12h"],
@@ -59,8 +59,13 @@ export const addReplyEditors = (replies, messenger) => {
     const edit = grantsAuthority(annotate(new Command("edit"), { effects: LOCAL_WRITE }))
         .description("change only the named fields of a reply rule; lists replace the whole list")
         .argument("<id>", "the rule's id");
-    for (const [flag, help] of REPLY_EDIT_OPTIONS)
-        edit.option(flag, help);
+    for (const [flag, help] of REPLY_EDIT_OPTIONS) {
+        const option = new Option(flag, help);
+        if (flag === "--template-mode <mode>")
+            option.conflicts("model");
+        edit.addOption(option);
+    }
+    edit.addOption(new Option("--model <mode>", "compatibility alias for --template-mode").hideHelp().conflicts("templateMode"));
     // Commander gives negated-only flags a true default; omission must preserve the saved field.
     edit.action(function (id) {
         const options = this.opts();
@@ -68,7 +73,10 @@ export const addReplyEditors = (replies, messenger) => {
             delete options.hours;
         const context = messengerContext(this, messenger);
         const { settings, env } = context;
-        renderItem(this, context, editRule(repliesPathFor(messenger.app, settings.profile, env), messenger.provider, id, options));
+        renderItem(this, context, editRule(repliesPathFor(messenger.app, settings.profile, env), messenger.provider, id, {
+            ...options,
+            model: options.templateMode ?? options.model,
+        }));
     });
     replies.addCommand(edit);
     const audience = grantsAuthority(annotate(new Command("audience"), { effects: LOCAL_WRITE })).description("show the reply audience, who the rules may answer, or replace its named fields; a new file answers everyone a rule matches");

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

@@ -13,7 +13,7 @@ export const retentionCommand = (messenger) => annotate(new Command("retention")
     .option("--until-time <time>", "joining period ends at this time; now by default")
     .option("--checkpoints <durations>", "up to 10 increasing joining ages, comma separated; 1d,7d,30d by default")
     .option("--within <duration>", "activity and early departure window after joining; 7d by default")
-    .addOption(new Option("--by <day|week>", "group joining dates by calendar day or Monday week").choices(["day", "week"]))
+    .addOption(new Option("--by <group>", "group joining dates by calendar day or Monday week").choices(["day", "week"]))
     .option("--timezone <zone>", "IANA timezone for joining cohorts")
     .option("--limit <n>", "cohorts and member evidence, 1–100", positiveCount("--limit"))
     .action(async function (chat) {

package/dist/cli/messenger/review.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { parseDuration } from "../../domain/duration.js";
 import { renderMessages } from "../../render/messages.js";
 import { CHAT_KINDS } from "../../services/chats.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,6 +25,7 @@ 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,
@@ -33,19 +34,22 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
     .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`)
-    .option("--kind <kinds>", `only chats of these kinds, comma-separated: ${CHAT_KINDS.join(", ")}`)
+    .addOption(new Option("--kind <kinds>", `compatibility spelling for kind:; ${CHAT_KINDS.join(", ")}`).hideHelp())
     .option("--unanswered [duration]", `only questions to you or a group's admins that nobody answered, asked at least this long ago — 4h, 1d; ${UNANSWERED_HOURS}h if not given`)
     .option("--all", "muted and archived chats too — left out unless they mention you or reply to you")
     .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();
     const hearWith = modelWith(options.transcribe, options.model);
     const context = messengerContext(this, messenger);
     const { settings, renderer, format, env } = context;
-    const { since: from, chat, meta } = catchUpQuery(query, REVIEW_QUERY, "review");
+    const { since: from, chat, meta, kinds: queriedKinds } = catchUpQuery(query, REVIEW_QUERY, "review");
+    if (options.kind !== undefined && queriedKinds !== undefined)
+        throw new CliError("validation_error", "give kind: or its legacy --kind spelling, not both");
     if (options.new && (from !== undefined || options.unanswered !== undefined)) {
         // An open question stays open: moving past it would drop it from the next review.
         throw new CliError("validation_error", "--new keeps its own point — not with a date or --unanswered");
@@ -60,7 +64,7 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
         : undefined;
     const since = from ?? saved?.first ?? reviewStart();
     const hours = options.unanswered === undefined ? undefined : unansweredHours(options.unanswered);
-    const kinds = options.kind === undefined ? undefined : kindsOf(options.kind);
+    const kinds = queriedKinds ?? (options.kind === undefined ? undefined : kindsOf(options.kind));
     let hearing;
     const transcribe = options.transcribe === true;
     const { found, reader } = await context.withServices(async (services, connect) => {
@@ -99,7 +103,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) => {
@@ -111,6 +116,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) {

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

@@ -36,8 +36,8 @@ const allCommand = (messenger) => {
     const command = annotate(new Command("all"), { effects: REMOTE_READ, partial: true })
         .summary("search stored messages, notes and selected meeting transcripts")
         .description((messenger.serverSearch
-        ? "search messenger messages and notes in the local store, and the messenger's server for messages " +
-            "(--backend; notes are local only)"
+        ? "search messenger messages and notes in the local store, and by default the messenger's server for " +
+            "messages too (notes are local only; --backend archive or --offline keeps it to the local store)"
         : "search messenger messages and notes in the local store") +
         ", and a meeting account's transcripts when --source names one — best match first; not mail (the separate memo CLI searches it: memo search mail), " +
         "tasks, people, memories or projects. Use it when you do not know where something was written; search messages " +

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

@@ -45,7 +45,7 @@ export const searchesCommand = (messenger) => {
         .option("--exact", "bare words and quotes match their exact form only, as exact:word does; text: still matches every form")
         .option("--context <n>", "messages before and after each hit", wholeCount)
         .option("--timezone <zone>", "the IANA timezone for calendar date boundaries")
-        .option("--by <chat|sender|day|hour>", "what stats messages show --saved counts by", groupingOf)
+        .option("--by <group>", "count by chat, sender, day or hour for stats messages show --saved", groupingOf)
         .option("--selection <json>", "save the resolved parent ranking query and options from a drilldown")
         .option("--replace", "overwrite a saved search of the same name")
         .action(async function (name, words) {

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

@@ -30,7 +30,11 @@ export { lockPath, readLock, servingProfiles } from "../../background/lock.js";
  * taken over. Started by a person, a service unit or `server start` — never by itself (NEED-9).
  */
 export const serveCommand = (messenger) => {
-    const command = annotate(new Command("serve"), { effects: REMOTE_WRITE, lifetime: "persistent" }).description("keep the local store current until stopped — what a systemd or launchd unit runs");
+    const command = annotate(new Command("serve"), {
+        effects: REMOTE_WRITE,
+        lifetime: "persistent",
+        examples: [`${messenger.app.command} personal serve`],
+    }).description("keep the local store current until stopped — what a systemd or launchd unit runs");
     command.action(async function () {
         const relay = messenger.connection === "exclusive" && process.platform !== "win32" ? serveRelay(this, messenger) : undefined;
         const context = recordDiagnostics(messengerContext(this, relay?.messenger ?? messenger), messenger.app);