@wirecat/cli-core 0.391.0 → 0.393.0

package/CHANGELOG.md

@@ -5,7 +5,28 @@ 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.393.0 — 23.10.2026
+
+### Added
+
+- Tag commands include concrete examples in help and command discovery.
+
+- Chat commands include concrete examples in help and command discovery.
+- Contact commands include concrete examples in help and command discovery.
+- **`@wirecat/cli-base` 0.50.0 is accepted beside 0.49.** The peer range is now `>=0.49.0 <0.51.0`, so a CLI that
+  takes cli-base 0.50.0 for `adaptOpenApi` (whatsapp-cli's bot API) keeps one copy of cli-base instead of two.
+  Nothing in cli-core calls what 0.50.0 added.
+
+## 0.392.0 — 23.10.2026
+
+### Added
+
+- Message commands include concrete examples in help and command discovery.
+
+### Fixed
+
+- **Agents are no longer offered channel comments for a messenger that cannot read them.** Direct calls
+  fail before connecting when the messenger declares comments unsupported.
 
 ## 0.391.0 — 23.10.2026
 
@@ -18,6 +39,18 @@ shape of this file.
 
 ### Added
 
+- **`bot watch --public-url <url> [--port <n>]` receives a bot's updates by webhook.** For a messenger that pushes and
+  cannot be polled — WhatsApp's Cloud API — the command listens on 127.0.0.1 (port 8766 by default) behind the owner's
+  tunnel, answers the subscription handshake, refuses a delivery whose signature does not match (401) or that comes
+  for another host (403), and answers 200 only after the batch is kept, so the messenger sends again what was not.
+  The same copy, redelivery check and `keepUpdates` run as for polling. A messenger opts in with the new
+  `BotWebhookIntake` port piece (`webhookHandshake`, `webhookAuthentic`, `webhookEvents`); one without it refuses.
+- **`BotMessenger.secrets` and `bot auth set --secret <name>`** keep a secret beside the bot token, the same way
+  (keyring account `bot:<profile>:<name>`, `<PREFIX>_BOT_<NAME>`, then a 0600 file) — a webhook's signing key.
+  `BotTokenStore` gains `readSecret`, `writeSecret` and `removeSecret`; `bot auth show` says where each comes from and
+  `bot auth remove` forgets them too. Without `secrets` nothing changes.
+- **`--source` knows `whatsapp` (`wa`) and `whatsapp-bot` (`wa-bot`).**
+
 - `readMeetingReview` (`@wirecat/cli-core/services`) and `MeetingStore.meetingReview`: the newest meetings of a
   selection, each with its newest summary (overview, next steps), transcript lines and words, the three who talked
   longest and its confirmed projects. No transcript text is read out.
@@ -37,6 +70,13 @@ shape of this file.
   forms. Unlike Lucene, order costs nothing: `"a b"~0` finds "b a" too. `word~1` stays an error. A saved search may
   now hold `~N`. `QUERY_OPERATORS` splits the `fuzzy / proximity` row into `proximity` and `fuzzy`.
 
+### Fixed
+
+- **An agent's text on a voice note is its transcript.** `transcript:`, the transcripts-first ranking, `matched_in`
+  and a mention's `transcript` field counted only text speech recognition wrote (`speech:<model>`), so a voice note
+  an agent transcribed was found as file text. A transcript is now the text of a voice attachment (`voice`,
+  `video_note` or `audio/ogg`), whoever wrote it.
+
 ## 0.389.0 — 22.10.2026
 
 ### Added

package/dist/cli/bot/command.js

@@ -19,11 +19,35 @@ import { botCallbacksCommand, botMenuCommand, botWebhooksCommand } from "./setup
 import { botStoreCommand } from "./store.js";
 import { BotTokenStore } from "./token.js";
 import { botWatchCommand } from "./watch.js";
+/** Where each of the messenger's other secrets comes from, `null` when it is not set; never the value. */
+const secretSources = (bot, tokens) => bot.secrets?.length
+    ? { secrets: Object.fromEntries(bot.secrets.map((one) => [one.name, tokens.readSecret(one.name)?.source ?? null])) }
+    : {};
 const authCommand = (bot, tokenVariable) => {
     const auth = annotate(new Command("auth"), { mcp: false }).description("the bot token this profile uses");
-    grantsAuthority(annotate(auth.command("set"), { effects: LOCAL_WRITE }))
-        .description(`check a bot token with ${bot.name ?? "the messenger"}, then keep it — typed at a hidden prompt or piped on stdin`)
-        .action(async function () {
+    const set = grantsAuthority(annotate(auth.command("set"), { effects: LOCAL_WRITE })).description(`check a bot token with ${bot.name ?? "the messenger"}, then keep it — typed at a hidden prompt or piped on stdin`);
+    const secrets = bot.secrets ?? [];
+    if (secrets.length > 0)
+        set.option("--secret <name>", `keep this secret instead of the token, the same way: ${secrets.map((one) => `${one.name} (${one.description})`).join("; ")}`);
+    set.action(async function () {
+        const { secret: named } = this.opts();
+        if (named !== undefined) {
+            const secret = secrets.find((one) => one.name === named);
+            if (!secret)
+                throw new CliError("validation_error", `no secret called "${named}" — one of: ${secrets.map((one) => one.name).join(", ")}`);
+            const context = botContext(this, bot);
+            await context.run(async () => {
+                const value = (await context.readSecret(`${secret.description}: `)).trim();
+                if (!value)
+                    throw new CliError("validation_error", "no secret given");
+                renderItem(this, context, {
+                    profile: context.profile,
+                    secret: secret.name,
+                    stored: context.tokens.writeSecret(secret.name, value),
+                });
+            });
+            return;
+        }
         const context = online(botContext(this, bot), this);
         await context.run(async (events) => {
             const token = (await context.readSecret("Bot token: ")).trim();
@@ -57,6 +81,7 @@ const authCommand = (bot, tokenVariable) => {
                 bot: account.name,
                 id: account.id,
                 username: account.username,
+                ...secretSources(bot, context.tokens),
             });
         });
     });
@@ -64,7 +89,11 @@ const authCommand = (bot, tokenVariable) => {
         .description("forget this profile's bot token")
         .action(async function () {
         const context = botContext(this, bot);
-        await context.run(async () => renderAnswer(this, context, itemOf({ profile: context.profile, removed: context.tokens.remove() })));
+        await context.run(async () => {
+            const removed = context.tokens.remove();
+            const secrets = Object.fromEntries((bot.secrets ?? []).map((one) => [one.name, context.tokens.removeSecret(one.name)]));
+            renderAnswer(this, context, itemOf({ profile: context.profile, removed, ...(bot.secrets?.length ? { secrets } : {}) }));
+        });
     });
     return auth;
 };

package/dist/cli/bot/port.d.ts

@@ -183,6 +183,38 @@ export interface BotUpdateRef {
 export type BotEvent = (MessageEvent | BotNotice) & {
     update?: BotUpdateRef;
 };
+/** One request as it reached `bot watch --public-url`: the body exactly as sent, never parsed and written again. */
+export interface BotWebhookRequest {
+    method: string;
+    /** Path and query, against the local listener. */
+    url: URL;
+    headers: Headers;
+    body: Uint8Array;
+}
+/** What the receiver answers a request that is not a delivery. */
+export interface BotWebhookAnswer {
+    status: number;
+    body?: string;
+}
+/**
+ * Receiving the bot's updates on a public address the owner's tunnel forwards to this machine, for a
+ * messenger that pushes and cannot be polled.
+ */
+export interface BotWebhookIntake {
+    /** A request that is not a delivery — a subscription handshake — answered here; `undefined` for a delivery. */
+    webhookHandshake(request: BotWebhookRequest): BotWebhookAnswer | undefined;
+    /** Whether a delivery comes from the messenger: its signature over the raw body, compared in constant time. */
+    webhookAuthentic(request: BotWebhookRequest): boolean;
+    /** The delivery's events, each with the update it came in, so a redelivery is recognised. Throws on a body it cannot read. */
+    webhookEvents(request: BotWebhookRequest): BotEvent[];
+}
+/** A secret beside the token that the messenger's bot needs, kept the same way — a webhook's signing key. */
+export interface BotSecret {
+    /** In `--secret <name>` and the keyring account, lowercase with hyphens. */
+    name: string;
+    /** What it is and where the owner finds it, for the help and the prompt. */
+    description: string;
+}
 export interface BotUpdatesPage {
     events: BotEvent[];
     /** Where the next call starts; the same as given when nothing came. Opaque to the caller. */
@@ -200,7 +232,7 @@ export interface BotUpdates {
  * The part of the personal core a bot can do, and the groups its Bot API has. A bot never gets
  * `chats` from this type: neither Bot API lists a bot's chats.
  */
-export type BotAdapter = Pick<MessengerCore, "me" | "close"> & Partial<MarkdownFormatting> & Partial<BotNativeApi> & Partial<BotMessaging> & Partial<BotHistory> & Partial<MessagePins> & Partial<BotChatTools> & Partial<BotChatAdmins> & Partial<BotChatMembers> & Partial<BotMenu> & Partial<BotCallbacks> & Partial<BotWebhooks> & Partial<BotUpdates> & Partial<BotPeople>;
+export type BotAdapter = Pick<MessengerCore, "me" | "close"> & Partial<MarkdownFormatting> & Partial<BotNativeApi> & Partial<BotMessaging> & Partial<BotHistory> & Partial<MessagePins> & Partial<BotChatTools> & Partial<BotChatAdmins> & Partial<BotChatMembers> & Partial<BotMenu> & Partial<BotCallbacks> & Partial<BotWebhooks> & Partial<BotUpdates> & Partial<BotWebhookIntake> & Partial<BotPeople>;
 export interface BotNativeApi {
     api(method: string, input: {
         body?: string;
@@ -237,6 +269,8 @@ export interface BotMessenger {
     adminRights?: readonly AdminRight[];
     /** Whether `bot webhooks set --add` keeps the other addresses; a messenger with one address has no `--add`. */
     manyWebhooks?: boolean;
+    /** Secrets beside the token, each set with `bot auth set --secret <name>`; none when unset. */
+    secrets?: readonly BotSecret[];
     /** Mount shared bot me; consumers with an existing response migrate explicitly. */
     identity?: boolean;
     /**

package/dist/cli/bot/token.d.ts

@@ -9,7 +9,8 @@ export interface BotTokenStoreOptions {
 }
 /**
  * A bot token per profile, beside — never inside — the personal session: keyring account
- * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file.
+ * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file. A secret the
+ * messenger's bot needs beside it lives the same way: `bot:<profile>:<name>`, `<PREFIX>_BOT_<NAME>`.
  */
 export declare class BotTokenStore {
     #private;
@@ -27,4 +28,10 @@ export declare class BotTokenStore {
     } | undefined;
     writeKeyring(token: string): void;
     remove(): CredentialSource[];
+    readSecret(name: string): {
+        secret: string;
+        source: CredentialSource;
+    } | undefined;
+    writeSecret(name: string, secret: string): CredentialSource;
+    removeSecret(name: string): CredentialSource[];
 }

package/dist/cli/bot/token.js

@@ -2,26 +2,30 @@ import { CliError, Credentials, pathsAreOverridden, resolvePaths, } from "@wirec
 import { envName } from "../../ports/app.js";
 /**
  * A bot token per profile, beside — never inside — the personal session: keyring account
- * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file.
+ * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file. A secret the
+ * messenger's bot needs beside it lives the same way: `bot:<profile>:<name>`, `<PREFIX>_BOT_<NAME>`.
  */
 export class BotTokenStore {
     profile;
     #account;
     #credentials;
     #keyringCredentials;
+    #secretOf;
     constructor({ app, profile, env = process.env, keyring, configDir }) {
         const where = { appName: app.appName, prefix: app.envPrefix, env };
         this.profile = profile;
         this.#account = `bot:${profile}`;
-        this.#credentials = new Credentials({
+        const credentialsFor = (variable) => new Credentials({
             configDir: configDir ?? resolvePaths(where).config,
             service: app.appName,
-            envVar: envName(app, "BOT_TOKEN"),
+            envVar: envName(app, variable),
             isolated: pathsAreOverridden(where),
             ...(keyring ? { keyring } : {}),
             env,
             warn: (message) => process.stderr.write(`${message}\n`),
         });
+        this.#credentials = credentialsFor("BOT_TOKEN");
+        this.#secretOf = (name) => credentialsFor(`BOT_${name.toUpperCase().replaceAll("-", "_")}`);
         this.#keyringCredentials = new Credentials({
             configDir: configDir ?? resolvePaths(where).config,
             service: app.appName,
@@ -61,4 +65,13 @@ export class BotTokenStore {
     remove() {
         return this.#credentials.remove(this.#account);
     }
+    readSecret(name) {
+        return this.#secretOf(name).read(`${this.#account}:${name}`);
+    }
+    writeSecret(name, secret) {
+        return this.#secretOf(name).write(`${this.#account}:${name}`, secret);
+    }
+    removeSecret(name) {
+        return this.#secretOf(name).remove(`${this.#account}:${name}`);
+    }
 }

package/dist/cli/bot/watch.d.ts

@@ -5,5 +5,7 @@ import type { BotMessenger } from "./port.js";
  * normal end. Each batch is kept before it is printed, and the cursor moves only after that: an end
  * at any moment never loses a batch. An update the messenger names by id is recorded and skipped when it
  * comes again after being handled; one without an id may print twice. A read: it changes nothing anyone sees.
+ * With `--public-url` the messenger pushes each batch to a local receiver behind the owner's tunnel
+ * instead, and a batch is acknowledged only once kept, so the messenger sends again what was not.
  */
 export declare const botWatchCommand: (bot: BotMessenger) => Command;

package/dist/cli/bot/watch.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
+import { portOf, publicUrlOf } from "../../http/public-url.js";
 import { renderMessages } from "../../render/messages.js";
 import { environmentOf } from "../context.js";
 import { REMOTE_WRITE } from "../effects.js";
@@ -9,6 +10,7 @@ import { botContext, online } from "./context.js";
 import { botCan, botIdOf } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog, UpdatesCursor } from "./updates.js";
+import { receiveWebhooks, WEBHOOK_PORT } from "./webhook-receiver.js";
 /** Under Telegram's transport timeout of 30 s, so a quiet poll ends as an answer, not as a failure. */
 const WAIT_SECONDS = 25;
 const FIRST_RETRY_MS = 1_000;
@@ -78,17 +80,31 @@ const keep = async (command, context, bot, botId, events, senders) => {
  * normal end. Each batch is kept before it is printed, and the cursor moves only after that: an end
  * at any moment never loses a batch. An update the messenger names by id is recorded and skipped when it
  * comes again after being handled; one without an id may print twice. A read: it changes nothing anyone sees.
+ * With `--public-url` the messenger pushes each batch to a local receiver behind the owner's tunnel
+ * instead, and a batch is acknowledged only once kept, so the messenger sends again what was not.
  */
 export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects: REMOTE_WRITE, lifetime: "persistent" })
     .description("print new messages as they arrive and keep them, until Ctrl-C or --timeout (either ends it normally)")
     .option("--events", "also edits, deletions, buttons pressed and people coming and going; every line names its event")
     .option("--types <types>", "only these update types, comma-separated, in the messenger's words")
+    .option("--public-url <url>", "receive by webhook at your tunnel's https address instead of polling, e.g. https://<name>.ts.net")
+    .option("--port <port>", `the local port behind the tunnel for --public-url (default ${WEBHOOK_PORT})`)
     .action(async function () {
-    const { events: everything, types: typed } = this.opts();
+    const flags = this.opts();
+    const { events: everything, types: typed } = flags;
     const context = online(botContext(this, bot), this);
     if (context.format === "json") {
         throw new CliError("validation_error", "watch is a stream — use --jsonl for one update per line");
     }
+    if (flags.port !== undefined && flags.publicUrl === undefined)
+        throw new CliError("validation_error", "--port is the local port behind --public-url; give both");
+    const publicUrl = flags.publicUrl === undefined
+        ? undefined
+        : publicUrlOf(flags.publicUrl, {
+            missing: "--public-url",
+            reaches: `${bot.name ?? "the messenger"} delivers the bot's updates`,
+        });
+    const port = portOf(flags.port, WEBHOOK_PORT);
     const types = typed
         ?.split(",")
         .map((one) => one.trim())
@@ -152,6 +168,42 @@ export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects
     try {
         await context.run(async (events) => {
             const adapter = await context.authenticated({ events, stop: stop.signal });
+            const warn = context.renderer.warn;
+            /** Keeps, prints and settles one batch; `false` when it was not kept and must come again. */
+            const take = async (botId, batch) => {
+                const handled = await context.copy.received(botId, batch, warn);
+                const fresh = batch.filter((event) => !(event.update && handled.has(event.update.id)));
+                if (fresh.length > 0 && !(await keep(this, context, bot, botId, fresh, adapter.senders?.()))) {
+                    await context.copy.settle(botId, fresh, "not_kept", warn);
+                    return false;
+                }
+                for (const event of fresh)
+                    print(event);
+                await context.copy.settle(botId, fresh, null, warn);
+                const seen = [...new Set(batch.flatMap((event) => chatOf(event) ?? []))].filter((id) => CHAT_ID.test(id));
+                if (seen.length > 0)
+                    context.registry.observe(seen.map((id) => ({ id })));
+                return true;
+            };
+            if (publicUrl) {
+                const intake = {
+                    webhookHandshake: botCan(adapter, "webhookHandshake", bot, "receive its updates by webhook"),
+                    webhookAuthentic: botCan(adapter, "webhookAuthentic", bot, "receive its updates by webhook"),
+                    webhookEvents: botCan(adapter, "webhookEvents", bot, "receive its updates by webhook"),
+                };
+                const botId = await botIdOf(context, adapter);
+                const wanted = (event) => !types || (event.update !== undefined && types.includes(event.update.kind));
+                await receiveWebhooks({
+                    intake,
+                    publicUrl,
+                    port,
+                    take: (batch) => take(botId, batch.filter(wanted)),
+                    signal: stop.signal,
+                    warn,
+                    listening: (local) => context.renderer.note(`receiving at ${publicUrl.origin} through ${local.host} — the tunnel must forward there; Ctrl-C to stop`),
+                });
+                return;
+            }
             const poll = botCan(adapter, "updates", bot, "take updates");
             if (adapter.webhooks && (await adapter.webhooks()).length > 0) {
                 throw new CliError("validation_error", `this bot gets its updates by webhook, and ${bot.name ?? "the messenger"} gives polling nothing while one ` +
@@ -182,21 +234,11 @@ export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects
                     await retry(`${bot.name ?? "the messenger"} did not answer (${code ?? "unknown"})`);
                     continue;
                 }
-                const warn = context.renderer.warn;
-                const handled = await context.copy.received(botId, page.events, warn);
-                const fresh = page.events.filter((event) => !(event.update && handled.has(event.update.id)));
-                if (fresh.length > 0 && !(await keep(this, context, bot, botId, fresh, adapter.senders?.()))) {
-                    await context.copy.settle(botId, fresh, "not_kept", warn);
+                if (!(await take(botId, page.events))) {
                     await retry("the updates were not kept");
                     continue;
                 }
                 failures = 0;
-                for (const event of fresh)
-                    print(event);
-                await context.copy.settle(botId, fresh, null, warn);
-                const seen = [...new Set(page.events.flatMap((event) => chatOf(event) ?? []))].filter((id) => CHAT_ID.test(id));
-                if (seen.length > 0)
-                    context.registry.observe(seen.map((id) => ({ id })));
                 if (page.cursor !== undefined && page.cursor !== at) {
                     at = page.cursor;
                     cursor.write(at);

package/dist/cli/bot/webhook-receiver.d.ts

@@ -0,0 +1,22 @@
+import type { BotEvent, BotWebhookIntake } from "./port.js";
+/** The local port behind the tunnel; MCP's `--http` has 8765. */
+export declare const WEBHOOK_PORT = 8766;
+/** Meta sends at most 3 MB in one delivery; anything larger is refused unread. */
+export declare const WEBHOOK_BODY: number;
+export interface WebhookReceiver {
+    intake: BotWebhookIntake;
+    publicUrl: URL;
+    port: number;
+    /** Keeps a batch: `true` once it is safe to tell the messenger it arrived. */
+    take: (events: BotEvent[]) => Promise<boolean>;
+    signal: AbortSignal;
+    /** Where the receiver listens, said once it does. */
+    listening: (local: URL) => void;
+    warn: (message: string) => void;
+}
+/**
+ * Answers the messenger on 127.0.0.1 until `signal` ends it. A delivery is answered 200 only after
+ * `take` kept it: a messenger that pushes retries anything else, so a crash or a full disk loses
+ * nothing. Batches are kept one at a time, in the order they arrived.
+ */
+export declare const receiveWebhooks: (receiver: WebhookReceiver) => Promise<void>;

package/dist/cli/bot/webhook-receiver.js

@@ -0,0 +1,68 @@
+import { listen } from "../../http/listen.js";
+/** The local port behind the tunnel; MCP's `--http` has 8765. */
+export const WEBHOOK_PORT = 8766;
+/** Meta sends at most 3 MB in one delivery; anything larger is refused unread. */
+export const WEBHOOK_BODY = 3 * 1024 * 1024;
+const LOCAL = ["localhost", "127.0.0.1"];
+const answer = (status, body = "") => new Response(body, { status, headers: { "content-type": "text/plain; charset=utf-8" } });
+/**
+ * Answers the messenger on 127.0.0.1 until `signal` ends it. A delivery is answered 200 only after
+ * `take` kept it: a messenger that pushes retries anything else, so a crash or a full disk loses
+ * nothing. Batches are kept one at a time, in the order they arrived.
+ */
+export const receiveWebhooks = async (receiver) => {
+    const { intake, publicUrl, take, warn } = receiver;
+    const hosts = [publicUrl.host, ...LOCAL.map((host) => `${host}:${receiver.port}`), ...LOCAL];
+    let queue = Promise.resolve();
+    const inTurn = (events) => {
+        const turn = queue.then(() => take(events));
+        queue = turn.catch(() => undefined);
+        return turn;
+    };
+    const handle = async (incoming) => {
+        // A page in the owner's browser can reach 127.0.0.1 too; only the tunnel and the machine itself may.
+        if (!hosts.includes(incoming.headers.get("host") ?? ""))
+            return answer(403, "host not allowed");
+        const url = new URL(incoming.url);
+        if (url.pathname !== "/")
+            return answer(404, "not found");
+        const request = {
+            method: incoming.method,
+            url,
+            headers: incoming.headers,
+            body: new Uint8Array(await incoming.arrayBuffer()),
+        };
+        if (request.method === "GET") {
+            const reply = intake.webhookHandshake(request);
+            return reply ? answer(reply.status, reply.body) : answer(404, "not found");
+        }
+        if (request.method !== "POST")
+            return answer(405, "method not allowed");
+        if (!intake.webhookAuthentic(request))
+            return answer(401, "signature does not match");
+        let events;
+        try {
+            events = intake.webhookEvents(request);
+        }
+        catch {
+            return answer(400, "unreadable delivery");
+        }
+        try {
+            return (await inTurn(events)) ? answer(200) : answer(503, "not kept");
+        }
+        catch (error) {
+            warn(`a delivery was not kept: ${error instanceof Error ? error.message : String(error)}`);
+            return answer(503, "not kept");
+        }
+    };
+    const listening = await listen(handle, { host: "127.0.0.1", port: receiver.port, maxBody: WEBHOOK_BODY });
+    try {
+        receiver.listening(listening.url);
+        if (!receiver.signal.aborted)
+            await new Promise((resolve) => receiver.signal.addEventListener("abort", () => resolve(), { once: true }));
+        await queue;
+    }
+    finally {
+        await listening.close();
+    }
+};

package/dist/cli/index.d.ts

@@ -42,7 +42,7 @@ export { type BotContext, botContext, botWords } from "./bot/context.js";
 export { type BotCopy, botCopy } from "./bot/copy.js";
 export { botMcpCommand } from "./bot/mcp.js";
 export { botCan, botIdOf, botMessagesCommand } from "./bot/messages.js";
-export { BOT_ACTIONS, type BotAction, type BotAdapter, type BotCallbacks, type BotChatAdmin, type BotChatAdmins, type BotChatMembers, type BotChatRef, type BotChatTools, type BotConnectOptions, type BotEvent, type BotHistory, type BotMcp, type BotMenu, type BotMenuEntry, type BotMessaging, type BotMessenger, type BotNativeApi, type BotNotice, type BotPeople, type BotPress, type BotSendOptions, type BotUpdates, type BotUpdatesPage, type BotWebhook, type BotWebhooks, } from "./bot/port.js";
+export { BOT_ACTIONS, type BotAction, type BotAdapter, type BotCallbacks, type BotChatAdmin, type BotChatAdmins, type BotChatMembers, type BotChatRef, type BotChatTools, type BotConnectOptions, type BotEvent, type BotHistory, type BotMcp, type BotMenu, type BotMenuEntry, type BotMessaging, type BotMessenger, type BotNativeApi, type BotNotice, type BotPeople, type BotPress, type BotSecret, type BotSendOptions, type BotUpdates, type BotUpdatesPage, type BotWebhook, type BotWebhookAnswer, type BotWebhookIntake, type BotWebhookRequest, type BotWebhooks, } from "./bot/port.js";
 export { botFiles, botsDirectory, ChatRegistry, registryProfiles, type SeenChat } from "./bot/registry.js";
 export { BotTokenStore, type BotTokenStoreOptions } from "./bot/token.js";
 export { PressLog, UpdatesCursor } from "./bot/updates.js";

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

@@ -34,7 +34,11 @@ const ALL_SINCE = "90d";
 const ALL_CHATS = "--all";
 export const syncCommand = (messenger) => {
     const fetching = messenger.fetching ?? FETCHING;
-    return annotate(new Command("sync"), { effects: FETCH, cooperative: true })
+    return annotate(new Command("sync"), {
+        examples: [`${messenger.app.command} personal messages sync "Book club" --last 100`],
+        effects: FETCH,
+        cooperative: true,
+    })
         .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`)

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

@@ -6,6 +6,7 @@ import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { withQuery } from "../list-query.js";
 import { withPaging } from "../paging.js";
+import { commandAt } from "../steps.js";
 import { groupCommands } from "./admin-commands.js";
 import { foldersCommand } from "./admin-folders-command.js";
 import { moderateCommand, rulesCommand } from "./admin-moderation-command.js";
@@ -102,6 +103,55 @@ export const chatsCommand = (messenger) => {
     if (messenger.personalBots === true)
         for (const command of botChatCommands(messenger))
             chats.addCommand(command);
+    const examples = {
+        "admins add": `"Book club" "Alex Example"${messenger.pickAdminRights === false ? "" : ` --can ${messenger.adminRights?.[0] ?? "info"}`}`,
+        "admins remove": '"Book club" "Alex Example"',
+        create: '"Book club" "Alex Example"',
+        "documents list": '"Project room" --limit 10',
+        events: '"Book club"',
+        "folders create": '"Reading" --chat "Book club"',
+        "folders delete": '"Reading"',
+        "folders join": "https://t.me/addlist/example",
+        "folders list": "",
+        "folders order": '"Reading" "Work"',
+        "folders show": '"Reading"',
+        "folders update": '"Reading" --title "Books"',
+        inspect: "https://example.com/invite/book-club",
+        join: "https://example.com/invite/book-club",
+        leave: '"Book club"',
+        "link create": '"Book club"',
+        "link list": '"Book club"',
+        "link reset": '"Book club"',
+        "link revoke": '"Book club" https://example.com/invite/book-club',
+        "link show": '"Book club"',
+        list: "--limit 10",
+        "mark-read": '"Book club" --until-id 101',
+        "members add": '"Book club" "Alex Example"',
+        "members audit": '"Book club"',
+        "members fetch": '"Book club"',
+        "members history": '"Book club"',
+        "members list": '"Book club"',
+        "members remove": '"Book club" "Alex Example"',
+        moderate: '"Book club" --dry-run',
+        "requests accept": '"Book club" "Alex Example"',
+        "requests decline": '"Book club" "Alex Example"',
+        "requests list": '"Book club"',
+        "rules set": '"Book club" links report',
+        "rules show": '"Book club"',
+        "rules unset": '"Book club" links',
+        "send-as": '"Project room"',
+        show: '"Book club"',
+        "tracking add": '"Book club"',
+        "tracking list": "",
+        "tracking remove": '"Book club"',
+        "tracking show": '"Book club"',
+        update: '"Book club" --title "Reading group"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(chats, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal chats ${path} ${args}`.trimEnd()] });
+    }
     return chats;
 };
 /** Where the history is pushed, the chat list and a chat's card answer from the store and never connect. */

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

@@ -15,7 +15,7 @@ import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { listQuery, nativeTerms, typedQuery, withQuery } from "../list-query.js";
 import { positiveCount, window, withPaging } from "../paging.js";
 import { casKey } from "../registry-keys.js";
-import { nextStep } from "../steps.js";
+import { commandAt, nextStep } from "../steps.js";
 import { contactWriteCommands } from "./admin-contacts-command.js";
 import { contactAnswer, lines, pageOf } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
@@ -250,5 +250,35 @@ export const contactsCommand = (messenger) => {
         contacts.addCommand(command);
     for (const command of contactWriteCommands(messenger))
         contacts.addCommand(command);
+    const examples = {
+        add: '"Alex Example"',
+        "alias rm": '"Alex Example"',
+        "alias set": '"Alex Example" "Reading partner"',
+        block: '"Alex Example"',
+        check: '"Alex Example"',
+        context: '"Alex Example" --limit 10',
+        import: "./contacts.csv",
+        link: '"Alex Example" zoom:101',
+        list: "--limit 10",
+        lookup: "",
+        "notes add": '"Alex Example" --file ./note.txt',
+        "notes edit": '"Alex Example" 1 --revision 1 --file ./note.txt',
+        "notes list": '"Alex Example"',
+        "notes remove": '"Alex Example" 1',
+        "notes show": '"Alex Example" 1',
+        profile: '"Alex Example"',
+        remove: '"Alex Example"',
+        rename: '"Alex Example" Alex Example',
+        show: '"Alex Example"',
+        sync: "",
+        timeline: '"Alex Example" --limit 10',
+        unblock: '"Alex Example"',
+        unlink: '"Alex Example"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(contacts, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal contacts ${path} ${args}`.trimEnd()] });
+    }
     return contacts;
 };

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

@@ -473,7 +473,10 @@ const answerOf = (text) => {
     return answer;
 };
 /** `messages links`: why a message sits where it does in its conversation. */
-export const linksCommand = (messenger) => annotate(new Command("links"), { effects: LOCAL_READ })
+export const linksCommand = (messenger) => annotate(new Command("links"), {
+    examples: [`${messenger.app.command} personal messages links "Book club" 101`],
+    effects: LOCAL_READ,
+})
     .description("why a message is in its conversation: each link it has, and the chain of answers back to the start")
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the message id")

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

@@ -17,7 +17,10 @@ import { nextStep } from "../steps.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 import { stopOnSignal } from "./patience.js";
 /** `messages download`: every file of one message, or with `--all` of a whole chat, never over a file already there. */
-export const downloadSubcommand = (messages, messenger) => annotate(messages.command("download"), { effects: FETCH })
+export const downloadSubcommand = (messages, messenger) => annotate(messages.command("download"), {
+    examples: [`${messenger.app.command} personal messages download "Book club" 101 --output-dir ./downloads`],
+    effects: FETCH,
+})
     .description("save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all")
     .argument("<chat>", messenger.chatArgument)
     .argument("[message]", "the message id; left out with --all")

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

@@ -7,6 +7,7 @@ type Need = readonly [method: keyof MessengerAdapter, what: string];
  */
 export declare const COMMAND_NEEDS: Readonly<Record<string, Need>>;
 interface Lacking {
+    channelComments?: boolean;
     lacks?: readonly (keyof MessengerAdapter)[];
     history?: "server" | "store";
 }