@wirecat/cli-core 0.396.0 → 0.398.0

package/CHANGELOG.md

@@ -5,7 +5,80 @@ 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.398.0 — 23.10.2026
+
+### Added
+
+- Top-level summaries, listeners and shell completion include examples in help and command discovery.
+
+- Clearing a remembered flood hold includes an example in help and command discovery.
+
+- **`Messenger.never`**: the adapter methods a messenger can never have, as opposed to `lacks`, what it does not have
+  yet. Their commands refuse as before and are also left out of help, `commands --json` and MCP. A command a
+  messenger only `lacks` stays in sight. For WhatsApp: `endOtherSessions` (only the phone ends other devices) and
+  `removeContact`.
+
+- **`review --offline` reads the local store** instead of refusing, for every messenger. It shows only what was
+  already synced and says so (`missing` in JSON, a warning on the terminal); its next step starts from the same
+  point, and `--new` keeps its saved point, so an online review still sees what was never synced.
+
+- **MCP offers more commands**, each limited by the profile's permissions: `runs list|show|path`, `store status|info|check|export|reindex`,
+  `store jobs cancel|retry|clear`, `attachments move`, `attachments jobs status`, `config show`, `commands schema`, `guide`,
+  `skill show`, `doctor report`, the `models` lists, `replies status|test|consents show`, `schedule list`,
+  `server status|logs`, and on the bot server `list`, `chats leave`, `chats admins add|remove`, `commands set|clear` and
+  `webhooks list|set|delete`. What stays off and why is in [the messenger rules](docs/dev/STANDARD.md#mcp).
+
+### Security
+
+- `@modelcontextprotocol/server` 2.3.0 clears the three high-severity advisories `npm audit` reported for every
+  WireCat CLI.
+
+### Fixed
+
+- **A pasted help example runs.** The `Example:` line of an account command's `--help`, generated or written, names
+  the profile `personal` (`tg personal messages list Team`), so it no longer fails with "name a profile".
+
+- `search mail` with no mail in the store points at `memo sync --only mail`; it named a `--mail` option memo does not have.
+
+- `parity.json` matches tg and max: `guide`, `mentions`, `runs search`, `tasks reject` and `--brief`/`--full` are in
+  both, and each gap planned for tg names its tg-cli backlog id.
+
+- `search all --help` says the messenger's server is asked by default and names `--backend archive` and `--offline`
+  to keep it to the local store.
+
+## 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

@@ -4,7 +4,8 @@
 
 # @wirecat/cli-core
 
-The engine behind the WireCat command-line tools for Telegram, MAX, mail, notes and meetings. Everything that
+The engine behind the WireCat command-line tools for Telegram, MAX, WhatsApp, mail, notes, meetings and Google
+Drive. Everything that
 does not depend on one messenger lives here: the data model, a local SQLite store with full-text and semantic
 search, a Lucene query language, the shared commands, an MCP server for AI agents, and the guard around every
 write. A messenger plugs in as one adapter and gets all of it.
@@ -25,6 +26,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 |
@@ -35,6 +37,7 @@ write. A messenger plugs in as one adapter and gets all of it.
 | [Testing](docs/dev/TESTING.md) · [Parity audit](docs/dev/PARITY-AUDIT.md) | The sandbox, the coverage floor, the checks across tg and max |
 | [Tool boundaries](docs/dev/TOOL-BOUNDARIES.md) | Which tool owns which command |
 | [API reference](docs/REFERENCE.md) | Every entry point and the detailed contract of each feature |
+| [Roadmap](docs/roadmap.md) | What is being built next for developers on this package |
 | [Changelog](CHANGELOG.md) | What each version changed, and what may break callers |
 
 ## What it is
@@ -71,7 +74,7 @@ It runs on Node 22.16+ and 24+, and on Bun.
 
 ```mermaid
 flowchart TB
-  tools["tg · max · memo · zm · drive"] --> interface
+  tools["tg · max · wa · memo · zm · drive"] --> interface
   subgraph core ["@wirecat/cli-core"]
     interface["Interface: CLI commands and MCP tools"] --> services["Services: one use case each"]
     services --> ports["Ports: MessengerAdapter · MeetingSource · TaskStore"]
@@ -87,7 +90,7 @@ Five layers, and each calls only the layers below it: domain, adapters behind a
 
 - **The CLI and the MCP server are two adapters over the same services.** A command and its MCP tool answer with
   the same data, because one service produces it.
-- **A port with one required core and optional groups.** `MessengerCore` is what every messenger must do. Seventeen
+- **A port with one required core and optional groups.** `MessengerCore` is what every messenger must do. The other
   groups — server reads, polls, forums, reactions and the rest — are optional and reached through `capability()`.
   A messenger without a group refuses the command before connecting; it never crashes and never silently drops an
   option.
@@ -115,8 +118,9 @@ code and its document must agree. A search plan that reads an index once per mes
 - **One query language for every list and every source.** A TypeScript port of the Apache Lucene 9.12.3 parsers,
   with no runtime parser dependency. Phrases, `AND` / `OR` / `NOT`, `+required`, grouping, field groups like
   `from:(alice OR bob)`, ranges `date:[2026-01-01 TO 2026-02-01}`, comparisons `size>10MB`, wildcards and regular
-  expressions. 27 fields: sender, chat, date, file name, MIME type, transcript, subject, label and more. Fuzzy
-  and proximity operators are refused with an error that names the alternative.
+  expressions. 27 fields: sender, chat, date, file name, MIME type, transcript, subject, label and more.
+  Proximity `"invoice paid"~3` finds the words close together in one message; the fuzzy operator `word~1` is
+  refused with an error that names the alternative.
   [Syntax](docs/search/query-language.md) · [grammar](docs/search/query-language-spec.md)
 - **Any three letters inside a word.** An FTS5 trigram index finds `port` inside `report`. A
   second, word index ranks by BM25.
@@ -210,8 +214,9 @@ they deliberately differ. A rule changes in its own pull request, before the cod
 - **Built for agents.** `--no-input` never prompts. Input and output are bounded (16 MiB in, 4 MiB out) and fail
   visibly instead of truncating. One-shot commands time out after 30 seconds and close what they hold. `--dry-run`
   previews any write.
-- **The tool never picks an account.** The profile is the first word of every account command; without one, the
-  command stops and lists the choices — even when there is only one.
+- **The tool never picks an account.** Every account command names its profile — the first word in tg, max and
+  wa, an option such as `--account` or `--profile` in the others; without one, the command stops and lists the
+  choices — even when there is only one.
 - **Run records keep ids and timings, never content.** A failure is kept by default, so `runs show` can explain it
   without anyone sending a log full of messages.
 - **Tests that cannot touch real data.** A sandbox keeps every test away from the owner's store, and no test may
@@ -252,8 +257,7 @@ describe("the adapter keeps the port's promises", () => {
 **Before 1.0, any release may break a caller.** Releases are frequent, sometimes several a day, and any of them
 may change any entry point. Every such change is listed in the [changelog](CHANGELOG.md) under "Changed — may break
 callers", with what to change. tg-cli and max-cli pin an exact version and move to a new one in their own pull request.
-Pin an exact version too: as of 18.10.2026, 132 of the 321 versions in the changelog break callers, and no patch
-release has.
+Pin an exact version too.
 The full list of entry points and what each holds is in the [API reference](docs/REFERENCE.md).
 
 ⚠ **Errors are recognised by shape, not by class** (`isCliFailure`). A package linked during development brings its

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/bot/admins.js

@@ -35,7 +35,7 @@ export const botAdminsCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot chats admins list", admins.map(snakeKeys)));
         });
     });
-    annotate(command.command("add"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(command.command("add"), { effects: REMOTE_WRITE })
         .description("make a member an admin with these rights")
         .argument("<chat>", CHAT)
         .argument("<person>", PERSON)
@@ -61,7 +61,7 @@ export const botAdminsCommand = (bot) => {
             });
         });
     });
-    annotate(command.command("remove"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(command.command("remove"), { effects: REMOTE_WRITE })
         .description("take an admin's rights back; they stay a member")
         .argument("<chat>", CHAT)
         .argument("<person>", PERSON)

package/dist/cli/bot/command.js

@@ -111,7 +111,7 @@ const meCommand = (bot) => annotate(new Command("me"), { effects: REMOTE_READ })
         }
     });
 });
-const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effects: LOCAL_READ, mcp: false })
+const listCommand = (bot, tokenVariable) => annotate(new Command("list"), { effects: LOCAL_READ })
     .description(`every name on this machine that has a bot token; --check asks ${bot.name ?? "the messenger"} which bot each is`)
     .option("--check", "ask the messenger who each bot is, with its token")
     .action(async function () {
@@ -216,7 +216,7 @@ const chatsCommand = (bot) => {
             renderItem(this, context, found);
         });
     });
-    annotate(command.command("leave"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(command.command("leave"), { effects: REMOTE_WRITE })
         .description("take the bot out of a chat; only an admin of the chat can bring it back")
         .argument("<chat>", "a chat id, or the title of a chat this bot has seen")
         .action(async function (chat) {

package/dist/cli/bot/setup.js

@@ -48,13 +48,13 @@ 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 })
         .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 })
         .description("empty the menu")
         .action(async function () {
         await replace(this, [], "bot.commands.clear");
@@ -97,7 +97,7 @@ 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");
+    const command = new Command("webhooks").description("where the messenger pushes this bot's updates — while one is set, `bot watch` gets nothing");
     annotate(command.command("list"), { effects: REMOTE_READ })
         .description("the webhooks this bot has")
         .action(async function () {

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/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,12 +12,14 @@ 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`;
     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 });
@@ -79,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/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) {