@wirecat/cli-core 0.394.0 → 0.396.0

package/CHANGELOG.md

@@ -5,6 +5,83 @@ 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.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
+
+### Changed — may break callers
+
+- `searches list`, `searches history` and `searches clear` cover only message searches. The table is shared by
+  every CLI on the store; a saved meeting search shown, run or deleted from a messenger is refused with
+  `details.reason: "search.kind"`. `SearchesStore.savedSearches`, `searchHistory` and `clearSearchHistory` take an
+  optional list of kinds.
+
+### Added
+
+- `search meetings` takes `date:`, `project:`, `tag:` and `topic:` in the query: `budget project:RES date>=30d`. They
+  choose meetings as `--since-time`/`--until-time`, `--project`, `--tag` and `--topic` do, join the words with AND,
+  and are refused inside OR, NOT and groups (`query.unsupported-field`) or when the same filter is also an option.
+  Search by meaning embeds only the words. `liftMeetingFields` (`@wirecat/cli-core/meetings`) does the split.
+
+- `meetingSearchesService` (`@wirecat/cli-core/services`): saved meeting searches, kind `meetings-search`, in the
+  same table: create, list, show, delete and `run`, which counts the run.
+
+- MCP setup and diagnostic commands include examples in help and command discovery.
+
+- Account commands include concrete examples in help and command discovery.
+
+- Search commands include concrete examples in help and command discovery.
+
+- Configuration commands include concrete examples in help and command discovery.
+
+- Skill commands include concrete examples in help and command discovery.
+
+- Task commands include concrete examples in help and command discovery.
+
+- Chat deletion and history clearing include examples in help and command discovery.
+
+- Poll commands include concrete examples in help and command discovery.
+
+- Listing poll voters includes an example in help and command discovery.
+
+- Model commands include concrete examples in help and command discovery.
+
+- Recorded-run commands include concrete examples in help and command discovery.
+
+- Conversation commands include examples in help and command discovery, with guidance for submitting a batch answer.
+
+- Server commands include concrete examples in help and command discovery.
+
 ## 0.394.0 — 23.10.2026
 
 ### Added

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/config-command.js

@@ -16,7 +16,7 @@ import { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } fro
  */
 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");
-    annotate(command.command("show"), { effects: LOCAL_READ })
+    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")
         .action(async function () {
@@ -42,7 +42,10 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
         }
     });
     for (const action of ["set", "unset"]) {
-        const sub = grantsAuthority(annotate(command.command(action), { effects: LOCAL_WRITE }))
+        const sub = grantsAuthority(annotate(command.command(action), {
+            effects: LOCAL_WRITE,
+            examples: [`${app.command} personal config ${action} limit${action === "set" ? " 20" : ""}`],
+        }))
             .argument("<setting>", 
         // default_profile is only removed now: `config unset` still takes it, `config set` refuses it.
         `one of: ${[...config.allSettings.filter((one) => action === "unset" || one !== "default_profile"), ...STORE_SETTINGS, "account_groups.<name>"].join(", ")}`)

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

@@ -14,9 +14,10 @@ import { accountAnswer, renderItem, wholeList } from "./chat-answers.js";
 import { messengerContext } from "./context.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 })
+        .addCommand(annotate(new Command("list"), { effects: REMOTE_READ, examples: [`${tool} account list`] })
         .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 });
@@ -45,7 +46,11 @@ export const accountCommand = (messenger) => {
             await store?.close();
         }
     }))
-        .addCommand(annotate(new Command("show"), { effects: REMOTE_READ, output: { entity: "account" } })
+        .addCommand(annotate(new Command("show"), {
+        effects: REMOTE_READ,
+        output: { entity: "account" },
+        examples: [`${tool} account show`],
+    })
         .description("who this profile is logged in as; the phone number shows its last four digits")
         .option("--show-phone", "print the whole phone number")
         .action(async function () {
@@ -54,7 +59,7 @@ export const accountCommand = (messenger) => {
         const account = await context.withMessenger((connection) => connection.me());
         renderAnswer(this, context, itemOf(accountAnswer(messenger.provider, whole ? account : maskedAccount(account))));
     }))
-        .addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE })
+        .addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE, examples: [`${tool} account update --first-name Alex`] })
         .description("change the name, the description or the photo everyone sees on your profile")
         .option("--first-name <name>", "your first name")
         .option("--last-name <name>", "your last name")

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

@@ -11,8 +11,9 @@ import { messengerContext } from "./context.js";
 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`);
-    withQuery(annotate(sessions.command("list"), { effects: REMOTE_READ }), SESSIONS_QUERY)
+    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) {
         const context = messengerContext(this, messenger);
@@ -21,7 +22,11 @@ export const accountSessionsCommand = (messenger) => {
         renderAnswer(this, context, wholeList("account sessions list", found.map(sessionAnswer)));
     });
     // No MCP tool, at any permission level: it logs the owner out of the phone.
-    sessions.addCommand(annotate(new Command("end"), { effects: REMOTE_WRITE, mcp: false })
+    sessions.addCommand(annotate(new Command("end"), {
+        effects: REMOTE_WRITE,
+        mcp: false,
+        examples: [`${tool} account sessions end --others`],
+    })
         .description("log out every other device, your phone included; this one stays")
         .option("--others", "every session but this one")
         .action(async function () {

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

@@ -34,7 +34,10 @@ 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`],
+})
     .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 +124,19 @@ 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`],
+}).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,7 +168,10 @@ 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",
     })

package/dist/cli/messenger/conversation-answers.d.ts

@@ -54,6 +54,11 @@ export declare const conversationShown: (account: AccountKey, { summary, message
         excerpt?: string | undefined;
         matched_in?: "context" | "file" | "filename" | "picture" | "text" | "transcript" | undefined;
         score?: number | undefined;
+        match?: "beginnings" | "corrected" | "words" | undefined;
+        corrections?: {
+            from: string;
+            to: string[];
+        }[] | undefined;
         found_in?: "archive" | "both" | "server" | undefined;
         discovery?: {
             coverage: number;

package/dist/cli/messenger/conversation-examples.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare const conversationExamples: (root: Command, tool: string) => void;

package/dist/cli/messenger/conversation-examples.js

@@ -0,0 +1,25 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { commandAt } from "../steps.js";
+export const conversationExamples = (root, tool) => {
+    const examples = {
+        "batches next": '--chat "Book club"',
+        "batches status": '--chat "Book club"',
+        build: '--chat "Book club"',
+        "consents list": "",
+        "consents revoke": '--chat "Book club"',
+        "embed clear": '--chat "Book club"',
+        "embed status": '--chat "Book club"',
+        "links add": '--batch "$batch"',
+        "links clear": '--chat "Book club"',
+        list: '"Book club"',
+        related: '"Book club" 101',
+        show: '"Book club" 101',
+        status: "",
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(root, path);
+        if (command)
+            annotate(command, { examples: [`${tool} personal conversations ${path} ${args}`.trimEnd()] });
+    }
+    commandAt(root, "links add")?.addHelpText("after", "\nSet batch to the id from conversations batches next; supply the JSON answer to that batch on stdin.\n");
+};

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

@@ -21,6 +21,7 @@ import { nextStep, rootOf, runnable, stepLine } from "../steps.js";
 import { answerOf as askOwner } from "./ask.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 import { conversationShown, foundConversations, readinessList, refreshedAnswer } from "./conversation-answers.js";
+import { conversationExamples } from "./conversation-examples.js";
 import { messageItems } from "./message-items.js";
 import { syncOptions, syncRequest } from "./search-sync-options.js";
 import { readAll } from "./stdin.js";
@@ -363,6 +364,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf({ revoked: true }));
     });
     conversations.addCommand(embed);
+    conversationExamples(conversations, messenger.app.command);
     return conversations;
 };
 /**

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

@@ -52,7 +52,10 @@ export const mcpCommand = (messenger) => {
         const { serveOverStdio } = await import("../../mcp/server.js");
         await serveOverStdio(this, context, messenger, {});
     });
-    command.addCommand(withFlags(annotate(new Command("config"), { effects: LOCAL_READ }).description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")).action(async function () {
+    command.addCommand(withFlags(annotate(new Command("config"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} personal mcp config`],
+    }).description("print the mcpServers entry for Claude Desktop, Cursor and others, with full paths; writes nothing")).action(async function () {
         const flags = this.optsWithGlobals();
         const context = messengerContext(this, messenger);
         const { settings, env } = context;
@@ -67,7 +70,10 @@ export const mcpCommand = (messenger) => {
         // Pasted into a file, so a person gets the client's own JSON, indented; a script finds it under `config`.
         renderAnswer(this, context, itemOf({ config: entry.config }, { next: entry.nodeBound ? [nextStep("mcp.config", { args: {} })] : [] }), () => JSON.stringify(entry.config, null, 2));
     }));
-    command.addCommand(withFlags(grantsAuthority(annotate(new Command("setup"), { effects: LOCAL_WRITE }))
+    command.addCommand(withFlags(grantsAuthority(annotate(new Command("setup"), {
+        effects: LOCAL_WRITE,
+        examples: [`${app.command} personal mcp setup codex --allow-writes`],
+    }))
         .description("add this profile's local MCP server to Codex or Claude Code")
         .argument("<client>", "codex or claude-code")
         .option("--allow-writes", "acknowledge that this profile offers writing tools")).action(async function (client) {
@@ -98,7 +104,10 @@ export const mcpCommand = (messenger) => {
             throw new CliError("validation_error", error instanceof Error ? error.message : "MCP setup failed");
         }
     }));
-    command.addCommand(withFlags(annotate(new Command("doctor"), { effects: LOCAL_READ }).description("check this profile's local MCP handshake and tool list")).action(async function () {
+    command.addCommand(withFlags(annotate(new Command("doctor"), {
+        effects: LOCAL_READ,
+        examples: [`${app.command} personal mcp doctor`],
+    }).description("check this profile's local MCP handshake and tool list")).action(async function () {
         const context = messengerContext(this, messenger);
         const { settings, env } = context;
         const given = environmentOf(this).mcp ?? {};

package/dist/cli/messenger/message-answers.d.ts

@@ -31,6 +31,11 @@ export declare const threadAnswer: ({ items, ...thread }: ThreadContext, reader:
         excerpt?: string | undefined;
         matched_in?: "context" | "file" | "filename" | "picture" | "text" | "transcript" | undefined;
         score?: number | undefined;
+        match?: "beginnings" | "corrected" | "words" | undefined;
+        corrections?: {
+            from: string;
+            to: string[];
+        }[] | undefined;
         found_in?: "archive" | "both" | "server" | undefined;
         discovery?: {
             coverage: number;

package/dist/cli/messenger/message-writes.d.ts

@@ -33,6 +33,11 @@ export declare const writtenAnswer: ({ operationId, sendId, message, scheduledFo
         excerpt?: string | undefined;
         matched_in?: "context" | "file" | "filename" | "picture" | "text" | "transcript" | undefined;
         score?: number | undefined;
+        match?: "beginnings" | "corrected" | "words" | undefined;
+        corrections?: {
+            from: string;
+            to: string[];
+        }[] | undefined;
         found_in?: "archive" | "both" | "server" | undefined;
         discovery?: {
             coverage: number;

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

@@ -57,9 +57,10 @@ const downloaded = (body) => "item" in body ? `${body.item.id}: downloaded and w
 const modelLine = (item, width) => `${item.default ? "*" : " "} ${item.id.padEnd(width)} ${megabytes(item.size_bytes).padStart(7)}  ` +
     (item.downloaded ? "downloaded" : "—".padEnd(10));
 export const modelsCommand = (messenger) => {
+    const tool = `${messenger.app.command} personal`;
     const models = annotate(new Command("models"), { mcp: false }).description("models that run on this machine");
     const audio = models.command("audio").description("speech models for transcribing voice messages");
-    withQuery(annotate(audio.command("list"), { effects: LOCAL_READ }), MODELS_QUERY)
+    withQuery(annotate(audio.command("list"), { effects: LOCAL_READ, examples: [`${tool} models audio list`] }), MODELS_QUERY)
         .description("the speech models, most suitable first, which are downloaded, and which one is the default")
         .action(async function (words) {
         const context = baseContext(this, messenger.resolveSettings);
@@ -73,7 +74,11 @@ export const modelsCommand = (messenger) => {
                 context.renderer.note(`kept in ${directory}`);
         });
     });
-    reachesOtherService(annotate(audio.command("download"), { effects: FETCH, output: { entity: "model" } }))
+    reachesOtherService(annotate(audio.command("download"), {
+        effects: FETCH,
+        output: { entity: "model" },
+        examples: [`${tool} models audio download parakeet-v3`],
+    }))
         .argument("<model>", "a model id from `models audio list`")
         .description("download a speech model once, checked against the sha256 this version expects")
         .action(async function (id) {
@@ -101,7 +106,7 @@ export const modelsCommand = (messenger) => {
         }, { unbounded: true });
     });
     const text = models.command("text").description("embedding models for searching conversations by meaning");
-    withQuery(annotate(text.command("list"), { effects: LOCAL_READ }), MODELS_QUERY)
+    withQuery(annotate(text.command("list"), { effects: LOCAL_READ, examples: [`${tool} models text list`] }), MODELS_QUERY)
         .description("the embedding models, most suitable first, which are downloaded, and which one is the default")
         .action(async function (words) {
         const context = baseContext(this, messenger.resolveSettings);
@@ -115,7 +120,11 @@ export const modelsCommand = (messenger) => {
                 context.renderer.note(`kept in ${directory}`);
         });
     });
-    reachesOtherService(annotate(text.command("download"), { effects: FETCH, output: { entity: "model" } }))
+    reachesOtherService(annotate(text.command("download"), {
+        effects: FETCH,
+        output: { entity: "model" },
+        examples: [`${tool} models text download ${DEFAULT_TEXT_MODEL}`],
+    }))
         .argument("<model>", "a model id from `models text list`")
         .addOption(new Option("--accept-terms", "accept the model's licence terms, for a model that has its own"))
         .description("download an embedding model once, checked against the sha256 this version expects")
@@ -131,7 +140,7 @@ export const modelsCommand = (messenger) => {
         }, { unbounded: true });
     });
     const key = text.command("key").description("API keys for embedding and analysis providers");
-    grantsAuthority(annotate(key.command("set"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(key.command("set"), { effects: LOCAL_WRITE, examples: [`${tool} models text key set openai`] }))
         .argument("<provider>", "openai, anthropic, or the host of a --base-url server that wants a key")
         .description("store a key, typed at a hidden prompt or piped on stdin — never as an argument")
         .action(async function (provider) {
@@ -145,7 +154,7 @@ export const modelsCommand = (messenger) => {
             renderAnswer(this, context, itemOf({ provider, stored: source }));
         });
     });
-    grantsAuthority(annotate(key.command("remove"), { effects: LOCAL_WRITE }))
+    grantsAuthority(annotate(key.command("remove"), { effects: LOCAL_WRITE, examples: [`${tool} models text key remove openai`] }))
         .argument("<provider>", "openai, anthropic, or a server's host")
         .description("forget a stored key")
         .action(async function (provider) {

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

@@ -22,7 +22,10 @@ export const pollsCommand = (messenger) => {
     const polls = new Command("polls").description(messenger.pollClose === false
         ? "read a poll, vote in it, create one"
         : "read a poll, vote in it, close your own, create one");
-    annotate(polls.command("show"), { effects: REMOTE_READ })
+    annotate(polls.command("show"), {
+        effects: REMOTE_READ,
+        examples: [`${messenger.app.command} personal polls show "Book club" 101`],
+    })
         .description("a poll and its answer ids, as the message carries it now")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the id of the message that carries the poll")
@@ -35,7 +38,10 @@ export const pollsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(poll)));
     });
     if (messenger.pollVoters)
-        polls.addCommand(withQuery(annotate(annotate(new Command("voters"), { effects: REMOTE_READ })
+        polls.addCommand(withQuery(annotate(annotate(new Command("voters"), {
+            effects: REMOTE_READ,
+            examples: [`${messenger.app.command} personal polls voters "Book club" 101 answers:0 --limit 10`],
+        })
             .description(messenger.pollAnonymous === false
             ? "who voted for what, newest first"
             : "who voted for what, newest first; not in an anonymous poll")
@@ -60,7 +66,10 @@ export const pollsCommand = (messenger) => {
                 args: { chat, message, ...(words.length > 0 ? { query: words.join(" ") } : {}) },
             }), lines(({ voted_at, person_id, name, answers }) => [voted_at, name ?? person_id, answers.join(",")].join("  ")));
         }));
-    annotate(polls.command("vote"), { effects: REMOTE_WRITE })
+    annotate(polls.command("vote"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal polls vote "Book club" 101 0`],
+    })
         .description(messenger.pollAnonymous === false
         ? "vote in a poll, or take your vote back; the others see it"
         : "vote in a poll, or take your vote back; the others see it unless the poll is anonymous")
@@ -85,7 +94,10 @@ export const pollsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(voted)));
     });
     if (messenger.pollClose !== false)
-        annotate(polls.command("close"), { effects: REMOTE_WRITE })
+        annotate(polls.command("close"), {
+            effects: REMOTE_WRITE,
+            examples: [`${messenger.app.command} personal polls close "Book club" 101`],
+        })
             .description("close your own poll; nobody can vote after that, and it cannot be reopened")
             .argument("<chat>", messenger.chatArgument)
             .argument("<message>", "the id of your own message that carries the poll")
@@ -94,7 +106,10 @@ export const pollsCommand = (messenger) => {
             const closed = await context.withMessenger((connection) => guardedClose(context.guard, connection, { chat, message: message.trim() }));
             renderAnswer(this, context, itemOf(snakeKeys(closed)));
         });
-    const create = annotate(polls.command("create"), { effects: REMOTE_WRITE })
+    const create = annotate(polls.command("create"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal polls create "Book club" "Which day?" Monday Tuesday`],
+    })
         .description(messenger.pollAnonymous === false
         ? "send a poll to a chat, as a message of its own; everyone sees who voted for what"
         : "send a poll to a chat, as a message of its own; public unless --anonymous")

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

@@ -82,7 +82,11 @@ export const callsCommand = (messenger) => {
 };
 /** `chats delete` and `chats clear` — for this account only; at the default level they ask first. */
 export const chatDeletionCommands = (messenger) => [
-    annotate(new Command("delete"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(new Command("delete"), {
+        effects: REMOTE_WRITE,
+        mcp: false,
+        examples: [`${messenger.app.command} personal chats delete "Book club"`],
+    })
         .description("delete a chat from this account; the others in it keep it and its messages")
         .argument("<chat>", messenger.chatArgument)
         .addOption(ownerOnlyOption("--allow-dangerous", "go ahead without the question an ask level puts before a deletion"))
@@ -90,7 +94,11 @@ export const chatDeletionCommands = (messenger) => [
         const context = messengerContext(this, messenger);
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.admin.deleteChat(chat)))));
     }),
-    annotate(new Command("clear"), { effects: REMOTE_WRITE, mcp: false })
+    annotate(new Command("clear"), {
+        effects: REMOTE_WRITE,
+        mcp: false,
+        examples: [`${messenger.app.command} personal chats clear "Book club"`],
+    })
         .description("delete every message in a chat for this account; the others in it keep theirs")
         .argument("<chat>", messenger.chatArgument)
         .addOption(ownerOnlyOption("--allow-dangerous", "go ahead without the question an ask level puts before a deletion"))

package/dist/cli/messenger/search-answers.js

@@ -21,6 +21,8 @@ export const messageHitItem = (hit, query = "") => {
         excerpt: hit.excerpt ?? excerpt(hit.text, query),
         matched_in: hit.matchedIn,
         score: hit.score ?? undefined,
+        match: hit.match,
+        corrections: hit.corrections,
         found_in: hit.source,
         discovery: hit.discovery
             ? defined({

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

@@ -6,6 +6,7 @@ import { searchNotesOf } from "../../services/notes-search.js";
 import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
+import { commandAt } from "../steps.js";
 import { messengerContext } from "./context.js";
 import { conversationsSearchCommand } from "./conversations-command.js";
 import { messagesSearchCommand } from "./messages-search-command.js";
@@ -157,5 +158,16 @@ export const searchCommand = (messenger, { topics = false } = {}) => {
         .addCommand(conversationsSearchCommand(messenger));
     if (topics)
         search.addCommand(topicsSearchCommand(messenger));
+    for (const [path, args] of Object.entries({
+        all: "draft",
+        conversations: '"Reviewing the project draft"',
+        messages: "draft --limit 10",
+        notes: "draft --limit 10",
+        topics: '"Book club" draft',
+    })) {
+        const command = commandAt(search, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal search ${path} ${args}`] });
+    }
     return search;
 };

package/dist/cli/messenger/searches-command.d.ts

@@ -1,4 +1,6 @@
 import { Command } from "commander";
 import { type Messenger } from "./context.js";
+/** `searches list` takes a query over the saved search fields, none of them a filter: the list is short and whole. */
+export declare const SEARCHES_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
 /** Saved searches and the history of `search messages` and `stats messages show`, in the local store only. */
 export declare const searchesCommand: (messenger: Messenger) => Command;

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

@@ -20,7 +20,8 @@ const line = ({ id, name, command, params, runs, lastRunAt }) => [
     `${runs} runs`,
     lastRunAt?.slice(0, 16).replace("T", " ") ?? "never run",
 ].join("  ");
-const SEARCHES_QUERY = unfilteredQuery("saved_search", savedSearch);
+/** `searches list` takes a query over the saved search fields, none of them a filter: the list is short and whole. */
+export const SEARCHES_QUERY = unfilteredQuery("saved_search", savedSearch);
 /** Saved searches and the history of `search messages` and `stats messages show`, in the local store only. */
 export const searchesCommand = (messenger) => {
     const searches = new Command("searches").description("saved searches and the history of search messages and stats messages show, kept in the local store; --saved runs one");