@wirecat/cli-core 0.395.0 → 0.397.0

package/CHANGELOG.md

@@ -5,7 +5,69 @@ 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
+
+### Changed — may break callers
+
+- **Command discovery uses `--json`.** `commands`, scoped discovery and `commands schema` refuse `--jsonl` with `output.one-object`, instead of printing a line with no stream end record. Use `--json` for the discovery document.
+
+- cli-core requires cli-base 0.50.1 or newer within the 0.50 line for profile-preserving command corrections and concise skill summaries.
+
+### Fixed
+
+- **Unknown-command explanations are separated.** The explanation of a word read as a profile follows the command error with a dash, keeping both parts readable on one line.
+
+- **Input-field errors name the command's flags.** Adapters can report unsupported or conflicting domain fields through `input.field-unsupported` or `input.field-conflict`. The CLI maps declared fields to flags in the human message and structured parameter, while SDK errors stay independent of command syntax. Unknown fields are kept without guessing.
+
+- **Joined command hints keep the chosen profile.** A command path passed as one argument is refused with a correction that preserves a separate explicit profile, including when global options come first.
+
+### Added
+
+- `SEARCHES_QUERY` (`@wirecat/cli-core/cli`): the query `searches list` takes, for another CLI's own saved searches.
+
+- **A voice note's transcript is found in any form of a word, and widened to the spellings speech recognition
+  garbles (store version 29).** «риелтор» finds a transcript saying «риелтору», and «реелтора»: always, not only when
+  nothing matched, by meeting search's rules — one stem edit from a word the Russian dictionary does not know, never
+  a number word, never a phrase or under `exact:`. A hit found only through a garbled spelling has `match:
+  "corrected"` and `corrections`, and the answer's `corrections` lists them. New tables `transcript_words`, its
+  vocabulary, `transcript_stems` and `transcript_index_pending`, filled before each search; existing transcripts are
+  queued on upgrade.
+
+- Attachment commands include concrete examples in help and command discovery.
 
 ## 0.395.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/commands-command.js

@@ -20,6 +20,12 @@ export const CONTRACT = 3;
 export const commandsCommand = (app) => {
     const command = annotate(new Command("commands"), { effects: NO_EFFECTS })
         .description("every command by section, one line each; --json: the contract, one path per call")
+        .hook("preAction", (_command, action) => {
+        if (action.optsWithGlobals().jsonl)
+            throw new CliError("validation_error", "command discovery is one JSON object — use --json", {
+                reason: "output.one-object",
+            });
+    })
         .argument("[path...]", "one command path, for example: search messages; inspect other groups in separate calls")
         .action(function (path) {
         const root = rootOf(this);

package/dist/cli/index.d.ts

@@ -108,7 +108,7 @@ export { reviewCommand } from "./messenger/review.js";
 export { scheduleCommand } from "./messenger/schedule-command.js";
 export { allHitItem, type HitItem, type MessageHitItem, messageHitItem, type NoteHitItem, noteHitItem, } from "./messenger/search-answers.js";
 export { searchCommand } from "./messenger/search-command.js";
-export { searchesCommand } from "./messenger/searches-command.js";
+export { SEARCHES_QUERY, searchesCommand } from "./messenger/searches-command.js";
 export { serveCommand, servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, type MemberFetches, memberFetches } from "./messenger/serve-members.js";
 export { STEMS_EVERY_MS, STEMS_SLICE_MS, type StemFills, stemFills } from "./messenger/serve-stems.js";

package/dist/cli/index.js

@@ -103,7 +103,7 @@ export { reviewCommand } from "./messenger/review.js";
 export { scheduleCommand } from "./messenger/schedule-command.js";
 export { allHitItem, messageHitItem, noteHitItem, } from "./messenger/search-answers.js";
 export { searchCommand } from "./messenger/search-command.js";
-export { searchesCommand } from "./messenger/searches-command.js";
+export { SEARCHES_QUERY, searchesCommand } from "./messenger/searches-command.js";
 export { serveCommand, servingProfiles } from "./messenger/serve-command.js";
 export { DAY_MS, FIRST_FETCH_MS, memberFetches } from "./messenger/serve-members.js";
 export { STEMS_EVERY_MS, STEMS_SLICE_MS, stemFills } from "./messenger/serve-stems.js";

package/dist/cli/input-fields.d.ts

@@ -0,0 +1,3 @@
+import type { errorObjectOf } from "@wirecat/cli-base";
+import type { Command } from "commander";
+export declare const showInputFields: (object: ReturnType<typeof errorObjectOf>, command: Command) => void;

package/dist/cli/input-fields.js

@@ -0,0 +1,27 @@
+import { INPUT_FIELD_REASONS } from "../errors/reasons.js";
+export const showInputFields = (object, command) => {
+    if (!INPUT_FIELD_REASONS.some((reason) => reason.reason === object.error.reason))
+        return;
+    const fields = object.error.details?.fields;
+    if (!Array.isArray(fields) || fields.length === 0 || !fields.every((field) => typeof field === "string"))
+        return;
+    const options = new Map();
+    for (let at = command; at; at = at.parent)
+        for (const option of at.options)
+            if (!option.hidden && option.long && !options.has(option.attributeName()))
+                options.set(option.attributeName(), option.long);
+    const flags = [];
+    for (const field of fields) {
+        const flag = options.get(field);
+        if (!flag)
+            return;
+        if (!flags.includes(flag))
+            flags.push(flag);
+    }
+    const first = flags[0];
+    if (first === undefined)
+        return;
+    object.error.message = `${flags.join(", ")}: ${object.error.message}`;
+    object.error.param = first;
+    object.error.details = { ...object.error.details, fields: flags };
+};

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) => {
@@ -34,7 +35,11 @@ const summary = (run) => [
 ]
     .filter(Boolean)
     .join(", ");
-const extractCommand = (messenger) => annotate(new Command("extract"), { effects: FETCH })
+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")
@@ -121,13 +126,21 @@ const extractCommand = (messenger) => annotate(new Command("extract"), { effects
 });
 const row = ({ message, position, name, local_path, extraction }) => `${message} #${position}  ${name ?? ""}  ${extraction ? `${extraction.origin} ${extraction.chars}` : "no text"}  ` +
     (local_path ?? "not downloaded");
-const listCommand = (messenger) => withQuery(withPaging(annotate(new Command("list"), { effects: REMOTE_READ }).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 listCommand = (messenger) => withQuery(withPaging(annotate(new Command("list"), {
+    effects: REMOTE_READ,
+    examples: [`${messenger.app.command} personal attachments list --limit 10`],
+})
+    .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 } : {}) }));
     renderAnswer(this, context, pagedList("attachments list", context.settings, found), () => found.items.length === 0 ? "" : `${found.items.map(row).join("\n")}\n`);
 });
-const showCommand = (messenger) => annotate(new Command("show"), { effects: REMOTE_READ })
+const showCommand = (messenger) => annotate(new Command("show"), {
+    effects: REMOTE_READ,
+    examples: [`${messenger.app.command} personal attachments show "Book club" 101 --attachment 1`],
+})
     .description("read a bounded chunk of one retained attachment; JSON includes base64 bytes")
     .argument("<chat>", `${messenger.chatArgument}; or a msg: locator alone`)
     .argument("[message]", "the message id")
@@ -159,10 +172,14 @@ const showCommand = (messenger) => annotate(new Command("show"), { effects: REMO
 });
 const textCommand = (messenger) => {
     const text = new Command("text").description("the text of one file, as an agent read it");
-    readsStdin(annotate(text.command("set"), { effects: LOCAL_WRITE }), {
+    readsStdin(annotate(text.command("set"), {
+        effects: LOCAL_WRITE,
+        examples: [`${messenger.app.command} personal attachments text set "Book club" 101 --text-file ./transcript.txt`],
+    }), {
         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")
@@ -184,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)