@wirecat/cli-core 0.396.0 → 0.397.0

package/CHANGELOG.md

@@ -5,7 +5,39 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.397.0 — 23.10.2026
+
+### Changed — may break callers
+
+- MCP argument names follow singular CLI placeholders: `messages delete` takes `message`, chat export takes `chat`, and duplicate-task operations take `task` (with `other_task` for a pair). Update saved MCP requests using `messages`, `chats` or `dup`. CLI positional values and their order are unchanged.
+
+### Fixed
+
+- The option catalogue records WhatsApp's JPEG-only profile photos. Wording differences can be justified for one command without exempting that option everywhere or hiding a missing option.
+
+- **Short command summaries and argument help.** Messenger commands keep their detailed descriptions while help and discovery show concise summaries. Contact notes, aliases, contact surnames and shell completion explain their positional arguments.
+
+- Message deletion, chat export and duplicate-task commands use singular argument names in help and discovery. Variadic arguments still accept several values, and task argument help identifies each side of a pair.
+
+- Contact profiles, phone lookups and address-book sync summaries declare their existing answer fields. Profile schemas retain masked phones, incomplete activity counts, partial provider flags and the source and precision of account-age estimates.
+
+### Added
+
+- Reaction commands include concrete examples in help and command discovery.
+
+- Recipient-list commands include concrete examples in help and command discovery.
+
+- Saved-search commands include concrete examples in help and command discovery.
+
+- **Independent media archives for messenger CLIs.** `attachments download <dir>` saves files by account,
+  chat, message and position, verifies size and SHA-256 on reruns, and preserves completed downloads after
+  interruption. `attachments check <dir>` verifies copies offline. `attachments jobs` installs and manages
+  opt-in Linux daily timers. Archive files stay independent of message-store deletion; interrupted streams
+  restart from byte zero because messenger downloads expose no range validators.
+  Download help clarifies that receiving messages saves no media copies and names the command to stop a daily timer.
+  `attachments move <dir> <archive-dir> --before-time <time>` moves older images to verified cold storage;
+  `--dry-run` previews counts and bytes. Relocation records preserve offline verification and prevent duplicate
+  downloads. New manifests retain message dates and image MIME types; undated draft images are left in place.
 
 ## 0.396.0 — 23.10.2026
 

package/README.md

@@ -25,6 +25,7 @@ write. A messenger plugs in as one adapter and gets all of it.
 |---|---|
 | [Architecture](docs/dev/ARCHITECTURE.md) | The layers, the module map, the store internals and migrations, who consumes what |
 | [Document workflows](docs/dev/DOCUMENTS.md) | Shared file ingestion, sync, scoped knowledge and extraction; the ports a file provider supplies |
+| [Media archives](docs/dev/MEDIA-ARCHIVE.md) | Independent verified file copies, interruption recovery and opt-in daily timers |
 | [Write an adapter](docs/dev/ADAPTERS.md) | How to add a messenger: the port, the `Messenger` description, the contract cases |
 | [Messenger rules](docs/dev/STANDARD.md) | What binds tg, max and wa beyond the [CLI standards handbook](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/README.md): parity, the option catalogue, `bot` |
 | [Glossary](docs/dev/GLOSSARY.md) | One word, one meaning across the tools |

package/dist/background/daily-archive-timer.d.ts

@@ -0,0 +1,40 @@
+import type { AppIdentity } from "../ports/app.js";
+import type { ServerSystem } from "./system.js";
+export declare const runArchiveTimerCommand: (args: string[], env: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export interface DailyArchiveTimer {
+    name: string;
+    unitDirectory: string;
+    service: string;
+    timer: string;
+}
+export interface DailyArchiveTimerInput {
+    app: AppIdentity;
+    profile: string;
+    directory: string;
+    entry: readonly string[];
+    env: NodeJS.ProcessEnv;
+    chats?: readonly string[];
+    sinceTime?: string;
+    at?: string;
+    timeZone?: string;
+}
+export declare const dailyArchiveTimer: (input: DailyArchiveTimerInput) => DailyArchiveTimer;
+export declare const manageDailyArchiveTimer: (plan: DailyArchiveTimer, action: "install" | "start" | "stop" | "status" | "uninstall", system: Pick<ServerSystem, "platform" | "run">, env: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<{
+    name: string;
+    installed: boolean;
+    active: boolean;
+    servicePath: string;
+    timerPath: string;
+    action?: undefined;
+} | {
+    active?: undefined;
+    name: string;
+    installed: boolean;
+    action: "install" | "start" | "stop" | "uninstall";
+    servicePath: string;
+    timerPath: string;
+}>;

package/dist/background/daily-archive-timer.js

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import { mkdir, realpath, unlink } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { CliError } from "@wirecat/cli-base";
+import { acquireLock, readBoundedUtf8File, syncDirectory, writeFileAtomic } from "../files/index.js";
+import { locationVariables } from "./units.js";
+export const runArchiveTimerCommand = (args, env, signal) => new Promise((resolve, reject) => {
+    execFile(args[0] ?? "systemctl", args.slice(1), {
+        env,
+        signal,
+        timeout: 30000,
+        maxBuffer: 65536,
+        encoding: "utf8",
+        shell: false,
+    }, (error, stdout, stderr) => {
+        if (!error)
+            return resolve({ code: 0, stdout, stderr });
+        if (typeof error.code === "number")
+            return resolve({ code: error.code, stdout, stderr });
+        reject(new CliError("configuration_error", "archive timer command did not complete; inspect its systemctl status"));
+    });
+});
+const missingMediaFile = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+const digest = (value) => createHash("sha256").update(value).digest("hex");
+const quote = (value, expandDollar) => `"${value
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("%", "%%")
+    .replaceAll("$", () => (expandDollar ? "$$" : "$"))}"`;
+const unitFolder = (env) => {
+    const folder = env.XDG_CONFIG_HOME ?? (env.HOME ? join(env.HOME, ".config") : "");
+    if (!isAbsolute(folder) || /[\p{Cc}]/u.test(folder))
+        throw new CliError("configuration_error", "a timer needs an absolute HOME or XDG_CONFIG_HOME");
+    return join(folder, "systemd", "user");
+};
+export const dailyArchiveTimer = (input) => {
+    const at = input.at ?? "03:00";
+    const timeZone = input.timeZone ?? "UTC";
+    const environment = locationVariables(input.app, input.env);
+    let zone;
+    try {
+        zone = new Intl.DateTimeFormat("en", { timeZone }).resolvedOptions().timeZone;
+    }
+    catch {
+        throw new CliError("validation_error", "--timezone needs an IANA time zone");
+    }
+    if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(at) ||
+        !/^[A-Za-z0-9_+/-]+$/.test(zone) ||
+        !/^[a-z][a-z0-9-]*$/.test(input.app.command) ||
+        !input.profile ||
+        !isAbsolute(input.directory) ||
+        input.entry.length < 1 ||
+        input.entry.some((one) => !isAbsolute(one)) ||
+        [
+            input.profile,
+            input.directory,
+            ...input.entry,
+            ...Object.values(environment),
+            ...(input.chats ?? []),
+            input.sinceTime ?? "",
+        ].some((one) => /[\p{Cc}]/u.test(one)))
+        throw new CliError("validation_error", "invalid daily archive timer arguments");
+    const scope = digest(JSON.stringify([
+        input.app.command,
+        input.profile,
+        input.directory,
+        Object.entries(environment).sort(([a], [b]) => a.localeCompare(b)),
+    ]));
+    const name = `${input.app.command}-media-archive-${scope.slice(0, 32)}`;
+    const owner = `# WireCat daily media archive ${scope}`;
+    const command = [
+        ...input.entry,
+        input.profile,
+        "attachments",
+        "download",
+        input.directory,
+        "--json",
+        "--no-input",
+        "--timeout",
+        "6h",
+        ...(input.sinceTime ? ["--since-time", input.sinceTime] : []),
+        ...(input.chats ?? []).flatMap((chat) => ["--chat", chat]),
+    ];
+    const seal = (text) => `${text}# SHA-256 ${digest(text)}\n`;
+    return {
+        name,
+        unitDirectory: unitFolder(input.env),
+        service: seal(`${owner}\n[Unit]\nDescription=WireCat media archive\n\n[Service]\nType=oneshot\nUMask=0077\nTimeoutStartSec=6h\n${Object.entries(environment)
+            .map(([key, value]) => `Environment=${quote(`${key}=${value}`, false)}\n`)
+            .join("")}ExecStart=${command.map((one) => quote(one, true)).join(" ")}\n`),
+        timer: seal(`${owner}\n[Unit]\nDescription=WireCat daily media archive\n\n[Timer]\nOnCalendar=*-*-* ${at}:00 ${zone}\nPersistent=true\nUnit=${name}.service\n\n[Install]\nWantedBy=timers.target\n`),
+    };
+};
+const ownedUnit = async (path, expectedOwner) => {
+    let text;
+    try {
+        text = await readBoundedUtf8File(path, { maxBytes: 65536 });
+    }
+    catch (error) {
+        if (missingMediaFile(error))
+            return null;
+        throw error;
+    }
+    const sealAt = text.lastIndexOf("# SHA-256 ");
+    if (!text.startsWith(`${expectedOwner}\n`) ||
+        sealAt < 0 ||
+        text.slice(sealAt) !== `# SHA-256 ${digest(text.slice(0, sealAt))}\n`)
+        throw new CliError("validation_error", "archive timer unit is foreign or edited; it was preserved");
+    return text;
+};
+export const manageDailyArchiveTimer = async (plan, action, system, env, signal) => {
+    if (system.platform !== "linux")
+        throw new CliError("configuration_error", "daily media archive timers require Linux systemd user services");
+    if (!isAbsolute(plan.unitDirectory) || !/^[a-z][a-z0-9-]*-media-archive-[a-f0-9]{32}$/.test(plan.name))
+        throw new CliError("validation_error", "invalid archive timer paths");
+    signal?.throwIfAborted();
+    await mkdir(plan.unitDirectory, { recursive: true, mode: 0o700 });
+    const folder = await realpath(plan.unitDirectory);
+    const lease = await acquireLock(join(folder, `.${plan.name}.lock`), { signal });
+    const beforeWrite = async () => {
+        signal?.throwIfAborted();
+        if (!(await lease.held()))
+            throw new CliError("validation_error", "archive timer lost its writer lock");
+    };
+    const servicePath = resolve(folder, `${plan.name}.service`);
+    const timerPath = resolve(folder, `${plan.name}.timer`);
+    const owner = plan.service.split("\n")[0] ?? "";
+    const run = async (...args) => {
+        await beforeWrite();
+        const result = await system.run(["systemctl", "--user", ...args], env);
+        if (result.code !== 0)
+            throw new CliError("configuration_error", "systemctl could not change the archive timer; inspect its status");
+    };
+    try {
+        const service = await ownedUnit(servicePath, owner);
+        const timer = await ownedUnit(timerPath, owner);
+        const installed = service !== null && timer !== null;
+        if (action === "status") {
+            const active = installed
+                ? await system.run(["systemctl", "--user", "is-active", `${plan.name}.timer`], env)
+                : undefined;
+            return { name: plan.name, installed, active: active?.code === 0, servicePath, timerPath };
+        }
+        if (action === "install") {
+            if ((service !== null && service !== plan.service) || (timer !== null && timer !== plan.timer))
+                throw new CliError("validation_error", "this destination already has a different schedule; stop and uninstall it first");
+            await beforeWrite();
+            if (service === null)
+                await writeFileAtomic(servicePath, plan.service, { overwrite: false, beforePublish: beforeWrite });
+            if (timer === null)
+                await writeFileAtomic(timerPath, plan.timer, { overwrite: false, beforePublish: beforeWrite });
+            await run("daemon-reload");
+        }
+        else {
+            if (!installed)
+                throw new CliError("not_found", "archive timer is not installed");
+            if (action === "start")
+                await run("enable", "--now", `${plan.name}.timer`);
+            if (action === "stop")
+                await run("disable", "--now", `${plan.name}.timer`);
+            if (action === "uninstall") {
+                await beforeWrite();
+                const active = await system.run(["systemctl", "--user", "is-active", `${plan.name}.timer`], env);
+                const enabled = await system.run(["systemctl", "--user", "is-enabled", `${plan.name}.timer`], env);
+                const running = await system.run(["systemctl", "--user", "is-active", `${plan.name}.service`], env);
+                if (active.code !== 3 || enabled.code !== 1 || running.code !== 3)
+                    throw new CliError("validation_error", "stop the archive timer and wait for its service to finish before uninstalling");
+                await beforeWrite();
+                await unlink(servicePath);
+                await unlink(timerPath);
+                await syncDirectory(folder);
+                await run("daemon-reload");
+            }
+        }
+        return { name: plan.name, installed: action !== "uninstall", action, servicePath, timerPath };
+    }
+    finally {
+        await lease.release();
+    }
+};
+import { execFile } from "node:child_process";

package/dist/background/index.d.ts

@@ -1,4 +1,6 @@
 export { type Checkpoint, checkpointPath, clearCheckpoint, type Progress, progressLine, progressOf, readCheckpoint, saveCheckpoint, } from "./checkpoints.js";
+export type { DailyArchiveTimer, DailyArchiveTimerInput } from "./daily-archive-timer.js";
+export { dailyArchiveTimer, manageDailyArchiveTimer } from "./daily-archive-timer.js";
 export { holdLock, type Lock, lockPath, readLock, releaseLock, servingProfiles, takeLock } from "./lock.js";
 export { alive, carries, holdersOf } from "./processes.js";
 export { listenRelay, RELAY_PROTOCOL, type RelayAddress, type RelayIo, type RelayRequest, relayCommand, relayPath, } from "./relay.js";

package/dist/background/index.js

@@ -1,4 +1,5 @@
 export { checkpointPath, clearCheckpoint, progressLine, progressOf, readCheckpoint, saveCheckpoint, } from "./checkpoints.js";
+export { dailyArchiveTimer, manageDailyArchiveTimer } from "./daily-archive-timer.js";
 export { holdLock, lockPath, readLock, releaseLock, servingProfiles, takeLock } from "./lock.js";
 export { alive, carries, holdersOf } from "./processes.js";
 export { listenRelay, RELAY_PROTOCOL, relayCommand, relayPath, } from "./relay.js";

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

@@ -18,6 +18,7 @@ export const accountCommand = (messenger) => {
     const account = new Command("account")
         .description("the logged-in account")
         .addCommand(annotate(new Command("list"), { effects: REMOTE_READ, examples: [`${tool} account list`] })
+        .summary("profiles on this computer and their signed-in accounts")
         .description("every profile on this computer, and the account each is logged in as; asks the messenger nothing")
         .action(async function () {
         const context = messengerContext(this, messenger, { needsProfile: false });

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

@@ -12,7 +12,9 @@ const SESSIONS_QUERY = unfilteredQuery("account_session", accountSession);
 /** `account sessions …` — where else the account is logged in, not this tool's own `session`. */
 export const accountSessionsCommand = (messenger) => {
     const tool = `${messenger.app.command} personal`;
-    const sessions = new Command("sessions").description(`where else this account is logged in — not \`${messenger.app.command} session\`, which is this tool's own login`);
+    const sessions = new Command("sessions")
+        .summary("devices and apps signed in to this account")
+        .description(`where else this account is logged in — not \`${messenger.app.command} session\`, which is this tool's own login`);
     withQuery(annotate(sessions.command("list"), { effects: REMOTE_READ, examples: [`${tool} account sessions list`] }), SESSIONS_QUERY)
         .description("every device and app logged in to this account; nothing is ended")
         .action(async function (words) {

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

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

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

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

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

@@ -65,6 +65,7 @@ export const storeCommand = (messenger) => {
  * 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 })
+    .summary("what the local archive holds and what is missing")
     .description("per chat: messages stored, the oldest and newest, and the stretches held completely")
     .argument("[chat]", messenger.chatArgument)
     .action(async function (chat) {
@@ -132,8 +133,9 @@ const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LO
  * 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 }))
+    .summary("export stored messages to files")
     .description("a chat's stored messages, oldest first: --jsonl one message per line, --json the list envelope of messages; never asks the messenger")
-    .argument("[chats...]", `${messenger.chatArgument}; several with --output-dir`)
+    .argument("[chat...]", `${messenger.chatArgument}; several with --output-dir`)
     .option("--format <format>", "jsonl: one message per line, the default with --output; markdown: a transcript with a heading per day, replies and forwards quoted")
     .option("--since-time <time>", "only from this ISO 8601 time, or 30m / 2h / 1d ago, on")
     .option("--output <file>", "write JSON lines, or the transcript, to this new file, readable only by you")

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

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

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

@@ -39,6 +39,7 @@ export const syncCommand = (messenger) => {
         effects: FETCH,
         cooperative: true,
     })
+        .summary("fetch and save a chat's message history")
         .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat")
         .argument("[chat]", messenger.chatArgument)
         .option("--all", `every chat, most recently active first — what search needs; the last ${ALL_SINCE} unless --since-time or --last`)
@@ -224,6 +225,7 @@ export const jobsCommand = (messenger) => {
             context.renderer.note(`no ${query ? "matching " : ""}background sync jobs for this profile`);
     });
     annotate(command.command("show"), { effects: LOCAL_READ })
+        .summary("one archive job's status and log")
         .description("one background job — the newest when none is named — and what the store now holds of its chat")
         .argument("[job]", "the job id `messages sync --background` printed")
         .action(async function (id) {
@@ -236,6 +238,7 @@ export const jobsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys({ ...jobDetails(job), ...(held ? { held } : {}), log: job.log })));
     });
     destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE, mcp: false }))
+        .summary("cancel a queued or running archive job")
         .description("stop a running background job after its current page; a later sync resumes where it stopped")
         .argument("<job>", "the job id")
         .action(function (id) {
@@ -249,6 +252,7 @@ export const jobsCommand = (messenger) => {
         renderAnswer(this, context, itemOf({ job: job.id, cancelled: true }));
     });
     destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE, mcp: false }))
+        .summary("retry an archive job")
         .description("start a partial, failed or died job again, as a new job; the sync resumes where the store stopped")
         .argument("[job]", "the job id")
         .option("--failed", "every chat whose newest job partial, failed or died")

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

@@ -37,6 +37,7 @@ export const chatsCommand = (messenger) => {
         // Where the history is pushed, the store answers, --offline too.
         ...(messenger.history === "store" ? {} : { offline: false }),
     })
+        .summary("stored membership and title changes")
         .description("who joined, left, was added or removed, and by whom — from the chat's service messages; " +
         `the last ${EVENTS_DAYS} days unless the query names time`)
         .argument("<chat>", messenger.chatArgument), { output: { entity: "chat_event" } }), EVENTS_QUERY).action(async function (chat, words) {

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

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

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

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

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

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

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

@@ -21,7 +21,7 @@ const SHELLS = ["zsh", "bash", "fish", "powershell"];
  */
 export const completeCommand = (messenger, config, options = {}) => annotate(new Command("complete"), { effects: LOCAL_READ, mcp: false })
     .description(`shell completion: \`${messenger.app.command} complete zsh\` prints the script to source`)
-    .argument("[words...]")
+    .argument("[words...]", "zsh for the shell script, or command words to complete")
     .allowUnknownOption()
     .helpOption(false)
     .action(async function (words) {

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

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