@wirecat/cli-core 0.397.0 → 0.399.0

package/dist/cli/bot/setup.js

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

package/dist/cli/bot/watch.js

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

package/dist/cli/commands-command.js

@@ -50,7 +50,7 @@ export const commandsCommand = (app) => {
             exit_codes: { ok: 0, [CRASH_CODE]: GENERIC_FAILURE, ...EXIT_CODES },
         });
     });
-    command.addCommand(annotate(new Command("schema"), { effects: NO_EFFECTS, mcp: false })
+    command.addCommand(annotate(new Command("schema"), { effects: NO_EFFECTS })
         .description("one command's argv and result schemas, effects, permissions and retry guidance")
         .argument("<path...>", "one command path, for example: stats messages show")
         .action(function (path) {

package/dist/cli/config-command.js

@@ -15,7 +15,7 @@ import { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } fro
  * configuration accepts can hold a secret — the schema has nowhere to put one.
  */
 export const configCommand = (app, config, { permissionKey } = {}) => {
-    const command = annotate(new Command("config"), { mcp: false }).description("the settings in force, and where each one came from");
+    const command = new Command("config").description("the settings in force, and where each one came from");
     annotate(command.command("show"), { effects: LOCAL_READ, examples: [`${app.command} personal config show`] })
         .description("the profile, the profiles that exist, and each setting with where it came from")
         .option("--bot", "the settings a bot command on this profile gets, rather than the personal account's")

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

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

package/dist/cli/embedding-choice.js

@@ -6,7 +6,10 @@ import { isLocal, remoteModel } from "../embeddings/remote.js";
 import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { typedCommand } from "../runs/scope.js";
 /** A local model id, or a remote model with its key from `models text key set`. */
-export const embeddingChoice = ({ model, provider, baseUrl, dims, concurrency }, app, settings, env, { needKey = true, keyring } = {}) => {
+export const embeddingChoice = ({ model, provider, embeddingProvider, baseUrl, dims, concurrency }, app, settings, env, { needKey = true, keyring } = {}) => {
+    if (embeddingProvider !== undefined && provider !== undefined)
+        throw new CliError("validation_error", "give --embedding-provider or its legacy --provider spelling, not both");
+    provider = embeddingProvider ?? provider;
     const flagsChooseProvider = (provider !== undefined && provider !== (settings.embeddingProvider ?? "local")) ||
         (baseUrl !== undefined && baseUrl.replace(/\/+$/, "") !== settings.embeddingBaseUrl?.replace(/\/+$/, ""));
     provider ??= flagsChooseProvider ? "openai" : (settings.embeddingProvider ?? "local");

package/dist/cli/guide.js

@@ -116,7 +116,6 @@ const scenarioText = (cli, scenario, profile) => [
 export const guideCommand = (app, options) => {
     const command = annotate(new Command("guide"), {
         effects: NO_EFFECTS,
-        mcp: false,
         examples: [`${app.command} guide`, `${app.command} guide <name> --json`],
     })
         .description("scenarios: the commands for a common task, in order, and why each")

package/dist/cli/help/command-help.d.ts

@@ -7,6 +7,8 @@ export interface NextChoice {
 }
 /** Overrides the "Next usually" a command's help derives from types. Kept off `annotate`, like its section. */
 export declare const nextUsually: <T extends Command>(command: T, choice: NextChoice) => T;
+/** The profile an example names, so a pasted one runs; the name the first screen's "Start here" uses. */
+export declare const EXAMPLE_PROFILE = "personal";
 export interface CommandHelp {
     returns: string;
     next: readonly string[];
@@ -20,8 +22,13 @@ export declare const commandHelp: (command: Command) => CommandHelp;
 export declare const commandHelpText: (command: Command) => string;
 /** The same, as Markdown lines for `docs/commands.md`: hand it to cli-base's `commandsPage` per command. */
 export declare const commandHelpMarkdown: (root: Command, path: readonly string[]) => string[];
-/** Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown. */
-export declare const installCommandHelp: (program: Command) => void;
+/**
+ * Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown.
+ * With `profile`, an example of an account command gets the profile word it would fail without.
+ */
+export declare const installCommandHelp: (program: Command, { profile }?: {
+    profile?: boolean;
+}) => void;
 /** Which leaf commands still show a generated example, so the important ones get a written one. Report only. */
 export declare const exampleReport: (program: Command) => {
     written: string[];

package/dist/cli/help/command-help.js

@@ -1,6 +1,7 @@
 import { metaOf } from "@wirecat/cli-base/commands";
 import { writes } from "@wirecat/cli-base/standards";
 import { commandPathOf, outputOf } from "../command-contract.js";
+import { PROFILE_FREE } from "../profile.js";
 import { commandAt } from "../steps.js";
 import { short } from "./commands-text.js";
 /** Argument names onto the kinds `domain/references.ts` names; a plural takes the same kind. */
@@ -164,16 +165,28 @@ const generatedExample = (command) => {
             return [flag];
         return [flag, option.argChoices?.[0] ?? sample(placeholder ?? option.attributeName())];
     });
-    // No profile word, as on the first screen and in written examples: the Usage line already shows `<profile>`.
     return [rootOf(command).name(), ...commandPathOf(command), ...words, ...options].join(" ");
 };
+const profiled = new WeakSet();
+/** The profile an example names, so a pasted one runs; the name the first screen's "Start here" uses. */
+export const EXAMPLE_PROFILE = "personal";
+const withProfile = (command, example) => {
+    const root = rootOf(command);
+    const top = commandPathOf(command)[0];
+    if (!profiled.has(root) || top === undefined || PROFILE_FREE.has(top))
+        return example;
+    const prefix = `${root.name()} ${top}`;
+    return example === prefix || example.startsWith(`${prefix} `)
+        ? `${root.name()} ${EXAMPLE_PROFILE} ${example.slice(root.name().length + 1)}`
+        : example;
+};
 /** Returns, Next usually and Example for one command, from its definition alone. */
 export const commandHelp = (command) => {
     const written = metaOf(command).examples ?? [];
     return {
         returns: returnsOf(command),
         next: nextOf(command).map(call),
-        examples: written.length > 0 ? written : [generatedExample(command)],
+        examples: (written.length > 0 ? written : [generatedExample(command)]).map((one) => withProfile(command, one)),
         origin: written.length > 0 ? "written" : "generated",
     };
 };
@@ -197,8 +210,13 @@ export const commandHelpMarkdown = (root, path) => {
         `**Example:** ${code(examples)}`,
     ];
 };
-/** Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown. */
-export const installCommandHelp = (program) => {
+/**
+ * Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown.
+ * With `profile`, an example of an account command gets the profile word it would fail without.
+ */
+export const installCommandHelp = (program, { profile = true } = {}) => {
+    if (profile)
+        profiled.add(program);
     for (const command of leaves(program))
         command.addHelpText("after", () => commandHelpText(command));
 };

package/dist/cli/help/first-screen.js

@@ -4,7 +4,7 @@ import { Command, Help, Option } from "commander";
 import wrapAnsi from "wrap-ansi";
 import { NO_EFFECTS } from "../effects.js";
 import { commandAt } from "../steps.js";
-import { installCommandHelp } from "./command-help.js";
+import { EXAMPLE_PROFILE, installCommandHelp } from "./command-help.js";
 /** Every WireCat tool, as "Works with" names it; a tool's own entry is left out of its screen. */
 export const WIRECAT_TOOLS = [
     { command: "tg", does: "Telegram in the same local store: search, review and tasks offline" },
@@ -56,7 +56,7 @@ export const firstScreen = (program, screen = {}) => {
     const can = (screen.can ?? []).map(({ command, does }) => [command, does]);
     const works = WIRECAT_TOOLS.filter((tool) => tool.command !== cli).map(({ command, shown, does }) => [shown ?? command, does]);
     const column = Math.max(22, widest([...can, ...works].map(([left]) => left))) + 2;
-    const start = screen.start ?? (commandAt(program, "setup") ? `${cli} personal setup` : undefined);
+    const start = screen.start ?? (commandAt(program, "setup") ? `${cli} ${EXAMPLE_PROFILE} setup` : undefined);
     return [
         wrapAnsi(`${cli} — ${pitch}`, WIDTH),
         "",
@@ -95,7 +95,7 @@ export const installHelp = (program, screen = {}) => {
             ? firstScreen(program, screen)
             : (own.formatHelp ?? Help.prototype.formatHelp).call(helper, command, helper),
     });
-    installCommandHelp(program);
+    installCommandHelp(program, { profile: screen.profile !== false });
     program.addOption(new Option("--help-all", "the full help: every command and option").hideHelp());
     program.on("option:help-all", () => {
         full = true;

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

@@ -12,6 +12,7 @@ import { recalledAccount } from "./accounts.js";
 import { photoHelp, readProfilePhoto } from "./admin-commands.js";
 import { accountAnswer, renderItem, wholeList } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
+import { hideNever } from "./lacks.js";
 import { privacyCommand } from "./records-command.js";
 export const accountCommand = (messenger) => {
     const tool = `${messenger.app.command} personal`;
@@ -80,5 +81,5 @@ export const accountCommand = (messenger) => {
         .addCommand(accountSessionsCommand(messenger));
     if (messenger.privacy === true)
         account.addCommand(privacyCommand(messenger));
-    return account;
+    return hideNever(messenger, account);
 };

package/dist/cli/messenger/admin-commands.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 { ADMIN_RIGHTS, GROUP_SETTINGS, } from "../../domain/models.js";
 import { readUpload, typesText } from "../../sends/upload.js";
@@ -22,19 +22,19 @@ const SETTING_FLAGS = {
     onlyAdminsSend: ["only-admins-send <on|off>", "only admins may send messages"],
     onlyAdminsEditInfo: ["only-admins-edit-info <on|off>", "only admins may change the name, photo and description"],
     disappearingSeconds: [
-        "disappear-time <duration|off>",
+        "disappear-after <duration|off>",
         "new messages disappear this long after sending: 24h, 7d, 90d; off keeps them",
     ],
 };
 const flagOf = (key) => `--${SETTING_FLAGS[key][0].split(" ")[0]}`;
-/** Where commander puts the flag's value: `--disappear-time` is `disappearTime`, not the setting's own name. */
+/** Where commander puts the flag's value: `--disappear-after` is `disappearAfter`, not the setting's own name. */
 const optionKey = (key) => flagOf(key)
     .slice(2)
     .replace(/-(\w)/g, (_, letter) => letter.toUpperCase());
 const settingsOf = (keys, options) => {
     const changes = {};
     for (const key of keys) {
-        const value = options[optionKey(key)];
+        const value = options[optionKey(key)] ?? (key === "disappearingSeconds" ? options.disappearTime : undefined);
         if (value === undefined)
             continue;
         if (key === "disappearingSeconds") {
@@ -67,8 +67,16 @@ const updateCommand = (messenger) => {
         update.option("--photo <file>", `a new photo for it — ${photoHelp(messenger)}`);
     if (messenger.groupPhotoRemoval === true)
         update.option("--remove-photo", "take its photo away; not with --photo");
-    for (const key of keys)
-        update.option(`--${SETTING_FLAGS[key][0]}`, SETTING_FLAGS[key][1]);
+    for (const key of keys) {
+        const option = new Option(`--${SETTING_FLAGS[key][0]}`, SETTING_FLAGS[key][1]);
+        if (key === "disappearingSeconds")
+            option.conflicts("disappearTime");
+        update.addOption(option);
+    }
+    if (keys.includes("disappearingSeconds"))
+        update.addOption(new Option("--disappear-time <duration|off>", "compatibility alias for --disappear-after")
+            .hideHelp()
+            .conflicts("disappearAfter"));
     return update.action(async function (chat) {
         const context = messengerContext(this, messenger);
         const { title, description, photo, removePhoto, ...rest } = this.opts();
@@ -210,6 +218,7 @@ const requestsCommand = (messenger) => {
         renderAnswer(this, context, body, lines(({ person_id, name, username, requested_at }) => [person_id, name ?? "", username ? `@${username}` : "", requested_at ?? ""].join("  ")));
     }));
     const everyone = messenger.joinRequestsAll !== false;
+    const byLink = everyone && messenger.joinRequestsByLink !== false;
     for (const [verb, accept, help] of [
         ["accept", true, "let them in; the group sees them join"],
         ["decline", false, "turn the request away"],
@@ -219,9 +228,9 @@ const requestsCommand = (messenger) => {
             .argument("<chat>", messenger.chatArgument)
             .argument(everyone ? "[person]" : "<person>", "who asked: an id from `chats requests list`");
         if (everyone)
-            answer
-                .option("--all", "every pending request, counted against the hourly limit first")
-                .option("--link <link>", "with --all: only the requests made by this invite link");
+            answer.option("--all", "every pending request, counted against the hourly limit first");
+        if (byLink)
+            answer.option("--link <link>", "with --all: only the requests made by this invite link");
         requests.addCommand(answer.action(async function (chat, person) {
             const context = messengerContext(this, messenger);
             const { all, link } = this.opts();

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

@@ -64,7 +64,7 @@ export const storeCommand = (messenger) => {
  * What the local store holds, per chat — read from the store alone. Whether a fetch reached a
  * chat's very first message is not recorded, so it is not claimed: the stretches held are shown.
  */
-const statusCommand = (messenger) => annotate(new Command("status"), { effects: LOCAL_READ, mcp: false })
+const statusCommand = (messenger) => annotate(new Command("status"), { effects: LOCAL_READ })
     .summary("what the local archive holds and what is missing")
     .description("per chat: messages stored, the oldest and newest, and the stretches held completely")
     .argument("[chat]", messenger.chatArgument)
@@ -132,7 +132,7 @@ const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LO
  * `--format markdown` for a transcript a person reads. With `--output-dir`, any number of chats into a
  * folder, and each later run into the same folder adds only what changed.
  */
-const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { effects: LOCAL_WRITE, mcp: false }))
+const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { effects: LOCAL_WRITE }))
     .summary("export stored messages to files")
     .description("a chat's stored messages, oldest first: --jsonl one message per line, --json the list envelope of messages; never asks the messenger")
     .argument("[chat...]", `${messenger.chatArgument}; several with --output-dir`)

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

@@ -237,7 +237,7 @@ export const jobsCommand = (messenger) => {
             : await context.withServices((services) => services.archive.held(chatId)).catch(() => undefined);
         renderAnswer(this, context, itemOf(snakeKeys({ ...jobDetails(job), ...(held ? { held } : {}), log: job.log })));
     });
-    destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE }))
         .summary("cancel a queued or running archive job")
         .description("stop a running background job after its current page; a later sync resumes where it stopped")
         .argument("<job>", "the job id")
@@ -251,7 +251,7 @@ export const jobsCommand = (messenger) => {
         process.kill(job.pid, "SIGTERM");
         renderAnswer(this, context, itemOf({ job: job.id, cancelled: true }));
     });
-    destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE }))
         .summary("retry an archive job")
         .description("start a partial, failed or died job again, as a new job; the sync resumes where the store stopped")
         .argument("[job]", "the job id")
@@ -292,7 +292,7 @@ export const jobsCommand = (messenger) => {
         if (items.length === 0 && context.format === "pretty")
             context.renderer.note("no partial, failed or died jobs to retry");
     });
-    destroysNothing(annotate(command.command("clear"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(command.command("clear"), { effects: LOCAL_WRITE }))
         .description("forget finished jobs and remove their logs; a running job is kept")
         .action(function () {
         const context = messengerContext(this, messenger);

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

@@ -1,5 +1,5 @@
 import type { Meta } from "@wirecat/cli-base/standards";
-import type { Inbox, Review } from "../../domain/models.js";
+import type { ChatKind, Inbox, Review } from "../../domain/models.js";
 import { type Hearing } from "../../speech/hearing.js";
 import type { AccountKey } from "../../store/store.js";
 import { type QueryWords } from "../list-query.js";
@@ -11,6 +11,7 @@ export declare const REVIEW_QUERY: import("@wirecat/cli-base/query").QueryRegist
 export declare const catchUpQuery: (words: QueryWords, registry: typeof INBOX_QUERY, command: string) => {
     since?: number;
     chat?: string;
+    kinds?: ChatKind[];
     meta?: Partial<Meta>;
 };
 export declare const inboxAnswer: (inbox: Inbox, hearing: Hearing | undefined, reader: AccountKey, transcribe: boolean, meta?: Partial<Meta>) => import("../envelope.js").ListBody<{
@@ -49,6 +50,8 @@ export declare const inboxAnswer: (inbox: Inbox, hearing: Hearing | undefined, r
         }[][] | undefined;
     }[];
 }>;
+/** What `review --offline` cannot see. */
+export declare const OFFLINE_REVIEW = "offline: only what was already synced to the local store; run review without --offline for the rest";
 /**
  * A review the next one goes on from: from `until` when nothing was left out, else from the same start again.
  * Saved points (`--new`) carry this themselves, and an `--unanswered` look is not a review to continue.

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

@@ -1,17 +1,19 @@
 import { defineQuery, queryError } from "@wirecat/cli-base/query";
+import { kindsOf } from "../../services/inbox.js";
 import { heard, hearingMissing } from "../../speech/hearing.js";
 import { listOf } from "../envelope.js";
 import { listQuery, nativeField, nativeTerms, timeBounds, typedQuery } from "../list-query.js";
 import { nextStep } from "../steps.js";
 import { messageItem } from "./message-items.js";
 const date = nativeField({ name: "date", type: "time", operators: ["range"], example: "date>2h" });
+const kind = nativeField({ name: "kind", type: "kw", operators: ["term", "phrase"], example: "kind:group,channel" });
 /** Where `inbox` starts reading: everything after a time. */
-export const INBOX_QUERY = defineQuery({ entity: "message", backend: "native", fields: [date] });
+export const INBOX_QUERY = defineQuery({ entity: "message", backend: "native", fields: [date, kind] });
 /** Where `review` starts, and the one chat it reads. */
 export const REVIEW_QUERY = defineQuery({
     entity: "message",
     backend: "native",
-    fields: [date, nativeField({ name: "chat", type: "kw", operators: ["term", "phrase"], example: "chat:7" })],
+    fields: [date, kind, nativeField({ name: "chat", type: "kw", operators: ["term", "phrase"], example: "chat:7" })],
 });
 /** The query's start and chat. A catch-up reads forward from one point, so an end is refused. */
 export const catchUpQuery = (words, registry, command) => {
@@ -23,9 +25,11 @@ export const catchUpQuery = (words, registry, command) => {
             command,
         });
     const chat = terms.get("chat")?.value;
+    const kinds = terms.get("kind")?.value;
     return {
         ...(since === undefined ? {} : { since }),
         ...(chat === undefined ? {} : { chat }),
+        ...(kinds === undefined ? {} : { kinds: kindsOf(kinds, "kind:") }),
         ...(meta === undefined ? {} : { meta }),
     };
 };
@@ -48,7 +52,7 @@ const nameOf = (chat) => chat.title ?? chat.id;
  * What every catch-up answer shares: the messages, oldest first, each naming its chat; what was left out as
  * `missing`; and a chat cut short as a `messages.list` step, after the steps the command puts first.
  */
-const catchUpList = (command, found, hearing, reader, { transcribe, first = [], meta = {} }) => {
+const catchUpList = (command, found, hearing, reader, { transcribe, first = [], meta = {}, left = [], }) => {
     const read = found.chats
         .flatMap((chat) => heard(chat.messages, hearing).map((message) => ({ ...message, chatTitle: chat.title })))
         .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
@@ -70,6 +74,7 @@ const catchUpList = (command, found, hearing, reader, { transcribe, first = [],
             ? [{ field: "items", why: `${found.quiet} muted or archived chats left out`, step: `${command}.all` }]
             : []),
         ...hearingMissing(hearing, transcribe),
+        ...left,
     ];
     return listOf(command, {
         items: read.map((message) => summaryOf(message, reader)),
@@ -81,6 +86,8 @@ const catchUpList = (command, found, hearing, reader, { transcribe, first = [],
     });
 };
 export const inboxAnswer = (inbox, hearing, reader, transcribe, meta = {}) => catchUpList("inbox", inbox, hearing, reader, { transcribe, meta });
+/** What `review --offline` cannot see. */
+export const OFFLINE_REVIEW = "offline: only what was already synced to the local store; run review without --offline for the rest";
 const quoted = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
 /**
  * A review the next one goes on from: from `until` when nothing was left out, else from the same start again.
@@ -95,6 +102,7 @@ export const reviewAnswer = (found, hearing, reader, { transcribe, fresh, chat,
     return catchUpList("review", found, hearing, reader, {
         transcribe,
         first: continues ? [nextStep("review.next", { args: { query: query.join(" ") } })] : [],
+        ...(found.offline ? { left: [{ field: "items", why: OFFLINE_REVIEW }] } : {}),
         ...(meta === undefined ? {} : { meta }),
     });
 };

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

@@ -19,6 +19,7 @@ import { membersCommand } from "./chats-members-command.js";
 import { markReadCommand } from "./chats-read-command.js";
 import { trackingCommand } from "./chats-tracking-command.js";
 import { messengerContext } from "./context.js";
+import { hideNever } from "./lacks.js";
 import { archiveCommands, chatDeletionCommands, chatPinCommands, markUnreadCommand, mediaCommand, muteCommands, } from "./records-command.js";
 export const chatsCommand = (messenger) => {
     const chats = new Command("chats").description("the account's chats");
@@ -153,7 +154,7 @@ export const chatsCommand = (messenger) => {
         if (command)
             annotate(command, { examples: [`${messenger.app.command} personal chats ${path} ${args}`.trimEnd()] });
     }
-    return chats;
+    return hideNever(messenger, chats);
 };
 /** Where the history is pushed, the chat list and a chat's card answer from the store and never connect. */
 const storedRead = (messenger) => (messenger.history === "store" ? LOCAL_READ : REMOTE_READ);

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

@@ -14,7 +14,7 @@ export const statsCommand = (messenger) => annotate(new Command("show"), { effec
     `joins and leaves — counted from the local store; ${messenger.history === "store" ? "joins and leaves too" : "joins and leaves are asked of the messenger"}`)
     .argument("<chat>", messenger.chatArgument)
     .option("--since-time <time>", `ISO 8601, or 2h / 1d ago; ${EVENTS_DAYS} days ago if not given`)
-    .option("--by <day|week>", "also one row per calendar day or week (weeks start on Monday)", periodOf)
+    .option("--by <group>", "also one row per calendar day or week (weeks start on Monday)", periodOf)
     .option("--timezone <zone>", "the IANA timezone for calendar days")
     .action(async function (chat) {
     const context = messengerContext(this, messenger);

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

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

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

@@ -19,6 +19,7 @@ import { commandAt, nextStep } from "../steps.js";
 import { contactWriteCommands } from "./admin-contacts-command.js";
 import { contactAnswer, lines, pageOf } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
+import { hideNever } from "./lacks.js";
 import { CONTACTS_QUERY, notesAllowed } from "./people-queries.js";
 import { privatePeopleCommands } from "./private-people-command.js";
 import { syncsFirst } from "./search-sync-options.js";
@@ -296,8 +297,8 @@ export const contactsCommand = (messenger) => {
         link: '"Alex Example" zoom:101',
         list: "--limit 10",
         lookup: "",
-        "notes add": '"Alex Example" --file ./note.txt',
-        "notes edit": '"Alex Example" 1 --revision 1 --file ./note.txt',
+        "notes add": '"Alex Example" --text-file ./note.txt',
+        "notes edit": '"Alex Example" 1 --revision 1 --text-file ./note.txt',
         "notes list": '"Alex Example"',
         "notes remove": '"Alex Example" 1',
         "notes show": '"Alex Example" 1',
@@ -315,5 +316,5 @@ export const contactsCommand = (messenger) => {
         if (command)
             annotate(command, { examples: [`${messenger.app.command} personal contacts ${path} ${args}`.trimEnd()] });
     }
-    return contacts;
+    return hideNever(messenger, contacts);
 };

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

@@ -95,6 +95,11 @@ export interface Messenger extends ServiceMessenger {
      * connecting, as the adapter would refuse after; one connection per device makes that connection a cost.
      */
     lacks?: readonly (keyof MessengerAdapter)[];
+    /**
+     * Adapter methods this messenger can never have, where `lacks` is what it does not have yet: their commands refuse
+     * the same way and are also hidden from help, `commands` and MCP. WhatsApp: only the phone ends other sessions.
+     */
+    never?: readonly (keyof MessengerAdapter)[];
     /** Whether a message can be deleted for the owner alone; yes when unset. No: every delete is for everyone (WhatsApp). */
     deleteForMe?: boolean;
     /** Whether the messenger has forum topics: `--topic`, `topic:` in `messages list` and the `topics_*` tools; yes when unset. */
@@ -153,6 +158,8 @@ export interface Messenger extends ServiceMessenger {
     inviteLinkUpdate?: boolean;
     /** Whether every pending join request is answered at once — `chats requests accept --all`; yes when unset. */
     joinRequestsAll?: boolean;
+    /** Whether `--all` can take only the requests made by one invite link — `--link`; yes when unset. */
+    joinRequestsByLink?: boolean;
     /** Whether a channel post can be commented on — `messages send --comment-to`; yes when unset. */
     channelComments?: boolean;
     /** Whether people added can be shown the messages from before they came — `members add --history`; yes when unset. */