@wirecat/cli-core 0.404.0 → 0.406.0

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

@@ -2,13 +2,14 @@ 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 show": '--chat "Book club"',
         "batches status": '--chat "Book club"',
-        build: '--chat "Book club"',
+        "links rebuild": '--chat "Book club"',
         "consents list": "",
-        "consents revoke": '--chat "Book club"',
-        "embed clear": '--chat "Book club"',
-        "embed status": '--chat "Book club"',
+        "consents remove": '--chat "Book club"',
+        embed: '--chat "Book club"',
+        "embeddings clear": '--chat "Book club"',
+        "embeddings status": '--chat "Book club"',
         "links add": '--batch "$batch"',
         "links clear": '--chat "Book club"',
         list: '"Book club"',
@@ -21,5 +22,5 @@ export const conversationExamples = (root, tool) => {
         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");
+    commandAt(root, "links add")?.addHelpText("after", "\nSet batch to the id from conversations batches show; supply the JSON answer to that batch on stdin.\n");
 };

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

@@ -1,9 +1,5 @@
 import { Command } from "commander";
 import { type Messenger } from "./context.js";
-/**
- * `conversations`: the threads inside a group chat, found by rules over the stored messages — replies,
- * mentions, one sender's messages in a row. From the store alone; nothing is built until asked (phase 3).
- */
 export declare const conversationsCommand: (messenger: Messenger) => Command;
 /** `messages links`: why a message sits where it does in its conversation. */
 export declare const linksCommand: (messenger: Messenger) => Command;

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

@@ -30,94 +30,121 @@ import { readAll } from "./stdin.js";
  * `conversations`: the threads inside a group chat, found by rules over the stored messages — replies,
  * mentions, one sender's messages in a row. From the store alone; nothing is built until asked (phase 3).
  */
+const conversationBuildCommand = (messenger) => boundOptions(reachesOtherService(annotate(new Command("rebuild"), { output: { entity: "conversation_build" }, effects: REMOTE_WRITE }))
+    .summary("build conversation links from stored messages")
+    .description("find a chat's conversations in what the store holds, replacing the last build; without --chat, every " +
+    "chat that changed since its build and every group never built; never asks the messenger")
+    .option("--chat <chat>", messenger.chatArgument)
+    .option("--analyze", "link batches using the configured analysis provider; requires --chat and remembers consent for this chat/provider")
+    .addOption(new Option("--analysis-provider <provider>", "analysis: agent, openai or anthropic"))
+    .option("--model <model>", "analysis model; overrides analysis_model")
+    .option("--base-url <url>", "analysis API endpoint; overrides analysis_base_url")
+    .option("--size <n>", "analysis answer messages per batch, 10–200; default 50", positiveCount("--size"))
+    .option("--max-tokens <n>", "analysis input/output reservation cap per run; default 100000", positiveCount("--max-tokens")), { chunks: false }).action(async function () {
+    const options = this.optsWithGlobals();
+    const { chat, maxChats } = options;
+    const context = messengerContext(this, messenger);
+    if (options.analyze) {
+        if (!chat)
+            throw new CliError("validation_error", "--analyze requires --chat");
+        refuseLocalWrite(context, messenger.app.command, LINKS_KEY);
+        refuseLocalWrite(context, messenger.app.command, "conversations.links.rebuild");
+        const target = analysisChoice(options, messenger.app, context.settings, context.env, context.keyring);
+        if (!isLocal(target.baseUrl))
+            refuseUnderReadOnly(this, `send chat text to ${new URL(target.baseUrl).host}`);
+        const controller = new AbortController();
+        context.track({ close: async () => controller.abort() });
+        const maxTokens = options.maxTokens ?? 100_000;
+        const size = options.size ?? BATCH_SIZE.default;
+        const result = await context.withStore(async (store, account) => {
+            const services = servicesFor({
+                ...storedDeps(messenger, store, account, context.guard),
+                env: context.env,
+                profile: context.profile,
+            });
+            const status = await services.conversations.batchStatus(chat, size);
+            const consents = analysisConsents(store, account);
+            const identity = providerIdentity(target);
+            if (status.messages && !(await consents.has(status.chat, identity))) {
+                const what = `${status.messages} messages, ${status.characters} characters (about ${status.tokensEstimate} message tokens, plus prompt and batch context), go to ${target.model} at ${target.baseUrl}; this run reserves at most ${maxTokens} input/output tokens. Consent is remembered for this chat and provider until revoked`;
+                if (!options.yes) {
+                    const answer = await askOwner(this, `${what}. Allow analysis? [y/N] `);
+                    if (answer === null)
+                        throw new CliError("confirmation_required", `${what} — add --yes`);
+                    if (!/^y(es)?$/i.test(answer.trim()))
+                        throw new CliError("cancelled", "cancelled — nothing was sent");
+                }
+                await consents.remember(status.chat, identity);
+            }
+            await services.conversations.build(chat);
+            const request = openAnalysis(target, controller.signal);
+            return runAnalysis(services.conversations, chat, async (...args) => {
+                if (!(await consents.has(status.chat, identity)))
+                    throw new CliError("permission_error", "analysis consent was revoked; no further batch was sent");
+                return request(...args);
+            }, {
+                model: target.model,
+                command: messenger.app.command,
+                size,
+                maxTokens,
+            });
+        });
+        renderAnswer(this, context, itemOf(snakeKeys(result)));
+        return;
+    }
+    if (options.analysisProvider !== undefined ||
+        options.provider !== undefined ||
+        options.model !== undefined ||
+        options.baseUrl !== undefined ||
+        options.size !== undefined ||
+        options.maxTokens !== undefined)
+        throw new CliError("validation_error", "analysis options require --analyze");
+    if (chat === undefined) {
+        const refreshed = await context.withServices((services) => services.embeddings.refresh({
+            embed: false,
+            ...(maxChats ? { maxChats } : {}),
+            progress: (note) => context.renderer.note(note),
+        }));
+        renderRefreshed(this, context, refreshed);
+        return;
+    }
+    const built = await context.withServices((services) => services.conversations.build(chat));
+    renderAnswer(this, context, itemOf(snakeKeys(built)), () => `${built.messages} messages → ${built.conversations} conversations, ${built.links} links (rules v${built.rulesVersion})\n`);
+});
+const embeddingStatusCommand = (messenger) => withModelOptions(annotate(new Command("status"), { output: { entity: "conversation_embedding_status" }, effects: LOCAL_READ })
+    .summary("which conversation vectors are ready or stale")
+    .description("how many chunks of a chat have a vector of the model, how many are left, and what is left costs")
+    .option("--chat <chat>", messenger.chatArgument)).action(async function () {
+    const options = this.optsWithGlobals();
+    const chat = chatOf(options);
+    const context = messengerContext(this, messenger);
+    const model = choiceOf(options, messenger, context, { needKey: false });
+    const status = await context.withServices((services) => services.embeddings.status(chat, model));
+    renderAnswer(this, context, itemOf(snakeKeys(status)), () => `${status.embedded} of ${status.chunks} chunks embedded with ${status.model}; ${status.left} left` +
+        (status.estimateSeconds === null ? "" : `, ${minutes(status.estimateSeconds)}`) +
+        (status.priceAtMost ? `, at most ${dollars(status.priceAtMost.usd)}` : "") +
+        "\n");
+});
+const embeddingClearCommand = (messenger) => withModelOptions(destroysNothing(annotate(new Command("clear"), { output: { entity: "conversation_change" }, effects: LOCAL_WRITE }))
+    .summary("remove stored conversation vectors")
+    .description("drop a chat's vectors, or only one model's; messages and conversations are never touched")
+    .option("--chat <chat>", messenger.chatArgument)).action(async function () {
+    const options = this.optsWithGlobals();
+    const chat = chatOf(options);
+    const context = messengerContext(this, messenger);
+    refuseLocalWrite(context, messenger.app.command, EMBED_KEY);
+    const given = options.model !== undefined ||
+        options.embeddingProvider !== undefined ||
+        options.provider !== undefined ||
+        options.baseUrl !== undefined;
+    const model = given ? choiceOf(options, messenger, context, { needKey: false }) : undefined;
+    const cleared = await context.withServices((services) => services.embeddings.clear(chat, model));
+    renderAnswer(this, context, itemOf(cleared), () => `${cleared.cleared} vectors dropped\n`);
+});
 export const conversationsCommand = (messenger) => {
     const conversations = new Command("conversations")
         .summary("group stored messages into conversations")
         .description("the conversations inside a chat, found in the stored messages by replies, mentions and who wrote next");
-    boundOptions(reachesOtherService(annotate(conversations.command("build"), { output: { entity: "conversation_build" }, effects: REMOTE_WRITE }))
-        .summary("build conversation links from stored messages")
-        .description("find a chat's conversations in what the store holds, replacing the last build; without --chat, every " +
-        "chat that changed since its build and every group never built; never asks the messenger")
-        .option("--chat <chat>", messenger.chatArgument)
-        .option("--analyze", "link batches using the configured analysis provider; requires --chat and remembers consent for this chat/provider")
-        .addOption(new Option("--analysis-provider <provider>", "analysis: agent, openai or anthropic").conflicts("provider"))
-        .addOption(new Option("--provider <provider>", "compatibility alias for --analysis-provider")
-        .hideHelp()
-        .conflicts("analysisProvider"))
-        .option("--model <model>", "analysis model; overrides analysis_model")
-        .option("--base-url <url>", "analysis API endpoint; overrides analysis_base_url")
-        .option("--size <n>", "analysis answer messages per batch, 10–200; default 50", positiveCount("--size"))
-        .option("--max-tokens <n>", "analysis input/output reservation cap per run; default 100000", positiveCount("--max-tokens")), { chunks: false }).action(async function () {
-        const options = this.optsWithGlobals();
-        const { chat, maxChats } = options;
-        const context = messengerContext(this, messenger);
-        if (options.analyze) {
-            if (!chat)
-                throw new CliError("validation_error", "--analyze requires --chat");
-            refuseLocalWrite(context, messenger.app.command, LINKS_KEY);
-            refuseLocalWrite(context, messenger.app.command, "conversations.build");
-            const target = analysisChoice(options, messenger.app, context.settings, context.env, context.keyring);
-            if (!isLocal(target.baseUrl))
-                refuseUnderReadOnly(this, `send chat text to ${new URL(target.baseUrl).host}`);
-            const controller = new AbortController();
-            context.track({ close: async () => controller.abort() });
-            const maxTokens = options.maxTokens ?? 100_000;
-            const size = options.size ?? BATCH_SIZE.default;
-            const result = await context.withStore(async (store, account) => {
-                const services = servicesFor({
-                    ...storedDeps(messenger, store, account, context.guard),
-                    env: context.env,
-                    profile: context.profile,
-                });
-                const status = await services.conversations.batchStatus(chat, size);
-                const consents = analysisConsents(store, account);
-                const identity = providerIdentity(target);
-                if (status.messages && !(await consents.has(status.chat, identity))) {
-                    const what = `${status.messages} messages, ${status.characters} characters (about ${status.tokensEstimate} message tokens, plus prompt and batch context), go to ${target.model} at ${target.baseUrl}; this run reserves at most ${maxTokens} input/output tokens. Consent is remembered for this chat and provider until revoked`;
-                    if (!options.yes) {
-                        const answer = await askOwner(this, `${what}. Allow analysis? [y/N] `);
-                        if (answer === null)
-                            throw new CliError("confirmation_required", `${what} — add --yes`);
-                        if (!/^y(es)?$/i.test(answer.trim()))
-                            throw new CliError("cancelled", "cancelled — nothing was sent");
-                    }
-                    await consents.remember(status.chat, identity);
-                }
-                await services.conversations.build(chat);
-                const request = openAnalysis(target, controller.signal);
-                return runAnalysis(services.conversations, chat, async (...args) => {
-                    if (!(await consents.has(status.chat, identity)))
-                        throw new CliError("permission_error", "analysis consent was revoked; no further batch was sent");
-                    return request(...args);
-                }, {
-                    model: target.model,
-                    command: messenger.app.command,
-                    size,
-                    maxTokens,
-                });
-            });
-            renderAnswer(this, context, itemOf(snakeKeys(result)));
-            return;
-        }
-        if (options.analysisProvider !== undefined ||
-            options.provider !== undefined ||
-            options.model !== undefined ||
-            options.baseUrl !== undefined ||
-            options.size !== undefined ||
-            options.maxTokens !== undefined)
-            throw new CliError("validation_error", "analysis options require --analyze");
-        if (chat === undefined) {
-            const refreshed = await context.withServices((services) => services.embeddings.refresh({
-                embed: false,
-                ...(maxChats ? { maxChats } : {}),
-                progress: (note) => context.renderer.note(note),
-            }));
-            renderRefreshed(this, context, refreshed);
-            return;
-        }
-        const built = await context.withServices((services) => services.conversations.build(chat));
-        renderAnswer(this, context, itemOf(snakeKeys(built)), () => `${built.messages} messages → ${built.conversations} conversations, ${built.links} links (rules v${built.rulesVersion})\n`);
-    });
     withQuery(annotate(conversations.command("list"), { effects: LOCAL_READ })
         .summary("stored conversations in one chat")
         .description("a chat's conversations, the newest first: when, how many messages, how many people")
@@ -187,7 +214,7 @@ export const conversationsCommand = (messenger) => {
         const { model: id, chats, unbuiltGroups, } = await context.withServices((services) => services.embeddings.readiness({ ...(options.chat === undefined ? {} : { chat: options.chat }), model }));
         renderAnswer(this, context, readinessList({ model: id, chats, ...(unbuiltGroups === undefined ? {} : { unbuiltGroups }) }), () => chats.map((one) => `${readinessLine(one, id)}\n`).join(""));
         if (chats.length === 0 && !unbuiltGroups && context.format === "pretty")
-            context.renderer.note("no chat has conversations yet — `conversations build --chat <chat>`");
+            context.renderer.note("no chat has conversations yet — `conversations links rebuild --chat <chat>`");
     });
     const batches = conversations
         .command("batches")
@@ -204,7 +231,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(status)), () => `${status.messages} messages to answer, about ${status.batches} batches, ` +
             `${status.characters} characters (about ${status.tokensEstimate} tokens)\n`);
     });
-    sizeOption(annotate(batches.command("next"), { output: { entity: "conversation_batch" }, effects: LOCAL_READ })
+    sizeOption(annotate(batches.command("show"), { output: { entity: "conversation_batch" }, effects: LOCAL_READ })
         .summary("get the next batch of messages to link")
         .description("the next window to answer, with the messages before it; message text goes to stdout only")
         .requiredOption("--chat <chat>", messenger.chatArgument)).action(async function () {
@@ -228,9 +255,8 @@ export const conversationsCommand = (messenger) => {
             .join("")}`);
         context.renderer.note(`${batch.remaining.messages} messages left after this batch`);
     });
-    const links = conversations
-        .command("links")
-        .description("your agent's answers: which earlier message each message of a batch answers");
+    const links = conversations.command("links").description("message links and the conversations derived from them");
+    links.addCommand(conversationBuildCommand(messenger));
     readsStdin(annotate(links.command("add"), { output: { entity: "conversation_change" }, effects: LOCAL_WRITE }), {
         name: "answer",
         description: '{ "model", "skill"?, "answers": [{ "message", "parent", "confidence" }] }',
@@ -239,7 +265,7 @@ export const conversationsCommand = (messenger) => {
         .summary("save an agent's conversation-link answers")
         .description('store your agent\'s answer to a batch, read as JSON from stdin: { "model", "answers": [{ "message", ' +
         '"parent", "confidence" }] }; all or nothing')
-        .requiredOption("--batch <id>", "the batch id `conversations batches next` printed")
+        .requiredOption("--batch <id>", "the batch id `conversations batches show` printed")
         .action(async function () {
         const { batch } = this.opts();
         const context = messengerContext(this, messenger);
@@ -252,8 +278,7 @@ export const conversationsCommand = (messenger) => {
         .summary("remove an agent's saved conversation-link answers")
         .description("drop your agent's answers for a chat, or only one model's; messages are never touched")
         .requiredOption("--chat <chat>", messenger.chatArgument)
-        .addOption(new Option("--answer-model <model>", "only the stored answers this model gave").conflicts("model"))
-        .addOption(new Option("--model <model>", "compatibility alias for --answer-model").hideHelp().conflicts("answerModel"))
+        .addOption(new Option("--answer-model <model>", "only the stored answers this model gave"))
         .action(async function () {
         const { chat, model, answerModel } = this.opts();
         const context = messengerContext(this, messenger);
@@ -308,36 +333,9 @@ export const conversationsCommand = (messenger) => {
             next: done.skipped ? [nextStep("conversations.build", { args: { chat } })] : [],
         }), () => `${done.embedded} chunks embedded with ${done.model}${done.skipped ? `, ${done.skipped} changed since the build` : ""}\n`);
     });
-    withModelOptions(annotate(embed.command("status"), { output: { entity: "conversation_embedding_status" }, effects: LOCAL_READ })
-        .summary("which conversation vectors are ready or stale")
-        .description("how many chunks of a chat have a vector of the model, how many are left, and what is left costs")
-        .option("--chat <chat>", messenger.chatArgument)).action(async function () {
-        const options = this.optsWithGlobals();
-        const chat = chatOf(options);
-        const context = messengerContext(this, messenger);
-        const model = choiceOf(options, messenger, context, { needKey: false });
-        const status = await context.withServices((services) => services.embeddings.status(chat, model));
-        renderAnswer(this, context, itemOf(snakeKeys(status)), () => `${status.embedded} of ${status.chunks} chunks embedded with ${status.model}; ${status.left} left` +
-            (status.estimateSeconds === null ? "" : `, ${minutes(status.estimateSeconds)}`) +
-            (status.priceAtMost ? `, at most ${dollars(status.priceAtMost.usd)}` : "") +
-            "\n");
-    });
-    withModelOptions(destroysNothing(annotate(embed.command("clear"), { output: { entity: "conversation_change" }, effects: LOCAL_WRITE }))
-        .summary("remove stored conversation vectors")
-        .description("drop a chat's vectors, or only one model's; messages and conversations are never touched")
-        .option("--chat <chat>", messenger.chatArgument)).action(async function () {
-        const options = this.optsWithGlobals();
-        const chat = chatOf(options);
-        const context = messengerContext(this, messenger);
-        refuseLocalWrite(context, messenger.app.command, EMBED_KEY);
-        const given = options.model !== undefined ||
-            options.embeddingProvider !== undefined ||
-            options.provider !== undefined ||
-            options.baseUrl !== undefined;
-        const model = given ? choiceOf(options, messenger, context, { needKey: false }) : undefined;
-        const cleared = await context.withServices((services) => services.embeddings.clear(chat, model));
-        renderAnswer(this, context, itemOf(cleared), () => `${cleared.cleared} vectors dropped\n`);
-    });
+    const embeddings = new Command("embeddings").description("stored conversation vectors");
+    embeddings.addCommand(embeddingStatusCommand(messenger)).addCommand(embeddingClearCommand(messenger));
+    conversations.addCommand(embeddings);
     boundOptions(destroysNothing(annotate(conversations.command("rebuild"), {
         output: { entity: "conversation_preparation" },
         effects: LOCAL_WRITE,
@@ -373,13 +371,13 @@ export const conversationsCommand = (messenger) => {
             has_more: false,
         }));
     });
-    annotate(consents.command("revoke"), { effects: LOCAL_WRITE, output: { entity: "analysis_consent_revocation" } })
+    annotate(consents.command("remove"), {
+        effects: LOCAL_WRITE,
+        output: { entity: "analysis_consent_revocation" },
+    })
         .description("forget analysis permissions so the next analysis asks again")
         .option("--chat <chat>", "revoke only this chat's consents; defaults to every chat")
-        .addOption(new Option("--consent-provider <identity>", "exact provider identity from consents list; defaults to every provider").conflicts("provider"))
-        .addOption(new Option("--provider <identity>", "compatibility alias for --consent-provider")
-        .hideHelp()
-        .conflicts("consentProvider"))
+        .addOption(new Option("--consent-provider <identity>", "exact provider identity from consents list; defaults to every provider"))
         .action(async function () {
         const { chat, provider, consentProvider } = this.opts();
         const context = messengerContext(this, messenger);
@@ -406,11 +404,8 @@ const chatOf = ({ chat }) => {
     return chat;
 };
 const withModelOptions = (command) => command
-    .option("--model <model>", "local: a model id from `models text list` (default: e5-small); remote: the provider's model")
-    .addOption(new Option("--embedding-provider <provider>", "embedding provider: local or openai; flags override profile settings").conflicts("provider"))
-    .addOption(new Option("--provider <provider>", "compatibility alias for --embedding-provider")
-    .hideHelp()
-    .conflicts("embeddingProvider"))
+    .option("--model <model>", "local: a model id from `models list` (default: e5-small); remote: the provider's model")
+    .addOption(new Option("--embedding-provider <provider>", "embedding provider: local or openai; flags override profile settings"))
     .option("--base-url <url>", "a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine")
     .option("--dims <n>", "remote: the vector size — needed with --base-url; shortens an OpenAI model's", positiveCount("--dims"));
 /** How much one run over many chats may do: the owner's machine, not a background job, pays for it. */
@@ -488,7 +483,7 @@ const consent = async (command, status, baseUrl, { yes, maxTokens }) => {
         throw new CliError("cancelled", "cancelled — nothing was sent");
 };
 const LINKS_KEY = "conversations.links";
-const EMBED_KEY = "conversations.embed";
+const EMBED_KEY = "conversations.embeddings";
 const dollars = (usd) => (usd < 0.0001 ? "under $0.0001" : `$${usd.toFixed(4)}`);
 const minutes = (seconds) => (seconds < 90 ? `about ${seconds} s` : `about ${Math.round(seconds / 60)} min`);
 /** The agent's JSON, shaped enough for the store to check the rest against the batch. */
@@ -524,7 +519,7 @@ export const linksCommand = (messenger) => annotate(new Command("links"), {
         return;
     }
     if (found.links.length === 0) {
-        context.renderer.note("no links: it starts a conversation, or the chat is not built — `conversations build`");
+        context.renderer.note("no links: it starts a conversation, or the chat is not built — `conversations links rebuild`");
     }
     context.streams.data(found.links
         .map((link) => `${link.chosen ? "→" : " "} ${link.parentId ?? "(starts)"}  ${link.source} ${link.kind} ` +
@@ -538,7 +533,7 @@ const itemLine = (one) => `${one.id}  ${one.started_at.slice(0, 16).replace("T",
 const hitLine = ({ summary, chunk, score, stale, locator }) => `${score === null ? "  —  " : score.toFixed(3)}  ${line(summary)}  ` +
     `(messages ${chunk.firstMessageId}–${chunk.lastMessageId})${locator ? `  ${locator}` : ""}${stale ? "  stale" : ""}`;
 const readinessLine = ({ chat, state, graph, pending, vectors }, model) => graph === null
-    ? `${chat}  ${state} — \`conversations build --chat ${chat}\``
+    ? `${chat}  ${state} — \`conversations links rebuild --chat ${chat}\``
     : `${chat}  ${state}  built ${graph.builtAt.slice(0, 16).replace("T", " ")}, rules v${graph.rulesVersion}` +
         `${graph.outdatedRules ? " (outdated)" : ""} · not in the build: ${pending.new} new, ${pending.edited} edited, ` +
         `${pending.deleted} deleted · ${model}: ${vectors.current} current, ${vectors.stale} stale, ` +

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

@@ -9,7 +9,7 @@ import { countersAnswer, refreshAnswer, refuseJsonl } from "./stats-answers.js";
 export const countersCommand = (messenger) => {
     const parent = new Command("counters").description("per-counter observations and bounded remote refresh");
     for (const operation of ["show", "refresh"]) {
-        const command = new Command(operation)
+        const command = new Command(operation === "refresh" ? "sync" : operation)
             .summary("refresh message counters from the messenger")
             .description(operation === "show"
             ? "show saved counter values and their observation freshness"
@@ -22,6 +22,8 @@ export const countersCommand = (messenger) => {
             .option("--selection <json>", "pinned counter-targets selection from counters show; conflicts with query and scope")
             .option("--counters <names>", "distinct views,reactions,comments fields; all three by default")
             .option("--limit <n>", "messages, 1–100; 20 by default", positiveCount("--limit"));
+        if (operation === "refresh")
+            command;
         if (operation === "show")
             command.option("--max-age <duration>", "maximum fresh observation age; 24h by default");
         annotate(command, operation === "refresh"
@@ -36,7 +38,7 @@ export const countersCommand = (messenger) => {
             const context = messengerContext(this, messenger), options = this.opts();
             refuseJsonl(context.format);
             if (operation === "refresh" && !options.dryRun)
-                refuseLocalWrite(context, messenger.app.command, "stats.messages.counters.refresh");
+                refuseLocalWrite(context, messenger.app.command, "stats.messages.counters.sync");
             const query = {
                 ...options,
                 limit: options.limit ?? 20,

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

@@ -9,7 +9,7 @@ import { FloodMemory, floodPathFor } from "../../sends/flood.js";
 import { SendJournal, sendsPathFor } from "../../sends/journal.js";
 import { storePath } from "../../store/path.js";
 import { baseContext, environmentOf, outputFor } from "../context.js";
-import { destroysNothing, LOCAL_WRITE, REMOTE_READ } from "../effects.js";
+import { destroysNothing, LOCAL_WRITE, NO_EFFECTS, REMOTE_READ } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { lineOf, nextStep } from "../steps.js";
 import { recalledAccount } from "./accounts.js";
@@ -57,11 +57,15 @@ const INCLUDES = [
 const EXCLUDES = ["message text", "chat titles", "names", "phone numbers", "the session", "the app credentials"];
 const reportCommand = (messenger) => {
     const { app } = messenger;
-    const report = annotate(new Command("report"), { effects: REMOTE_READ })
+    const report = new Command("reports").description("problem reports");
+    annotate(report.command("show"), {
+        effects: NO_EFFECTS,
+        examples: [`${app.command} doctor reports show`],
+    })
         .description("what a problem report holds; writes nothing")
         .action(function () {
         const output = outputFor(this);
-        const create = lineOf(this, "doctor report create");
+        const create = lineOf(this, "doctor reports create");
         renderAnswer(this, output, itemOf({ includes: INCLUDES, excludes: EXCLUDES, ...(app.issues ? { send_to: app.issues } : {}) }, { next: [nextStep("doctor.report-create", { args: {} })] }), () => [
             `A problem report is one file for the author of ${app.command}.`,
             "",
@@ -76,7 +80,7 @@ const reportCommand = (messenger) => {
     });
     destroysNothing(annotate(report.command("create"), {
         effects: LOCAL_WRITE,
-        examples: [`${app.command} personal doctor report create --output ./problem-report.json`],
+        examples: [`${app.command} personal doctor reports create --output ./problem-report.json`],
     }))
         .description("write a problem report to a file, and say where to send it")
         .option("--run <id>", "the run the report is about; the newest failed one if not given")

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

@@ -21,7 +21,7 @@ const count = (value) => {
 };
 export const gapsCommand = (messenger) => {
     const group = new Command("gaps").description("inspect recorded interior coverage gaps and explicitly fetch them");
-    annotate(group.command("plan"), { output: { entity: "store_gap_plan" }, effects: LOCAL_READ })
+    annotate(group.command("show"), { output: { entity: "store_gap_plan" }, effects: LOCAL_READ })
         .description("local coverage plan; missing message ids alone do not imply missing history")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
@@ -71,7 +71,7 @@ export const gapsCommand = (messenger) => {
         if (prepare) {
             validateCatchUpBounds(preparation);
             refuseLocalWrite(context, messenger.app.command, "conversations.links");
-            refuseLocalWrite(context, messenger.app.command, "conversations.embed");
+            refuseLocalWrite(context, messenger.app.command, "conversations.embeddings");
         }
         if (args.background) {
             const planned = await context.withServices((services) => services.gaps.plan(chat));

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

@@ -2,7 +2,7 @@ import type { Message } from "../../domain/models.js";
 import { type Hearing } from "../../speech/hearing.js";
 import type { Messenger, MessengerContext, ReadConnection } from "./context.js";
 export declare const TRANSCRIBE_OPTION: readonly ["--transcribe", "turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes"];
-export declare const MODEL_OPTION: readonly ["--model <model>", "which downloaded speech model hears them, with --transcribe; `models audio list` shows them"];
+export declare const MODEL_OPTION: readonly ["--model <model>", "which downloaded speech model hears them, with --transcribe; `models list` shows them"];
 /**
  * Kept transcripts on every read; new ones with `--transcribe`, using the read's connection when
  * supplied. It is released before local recognition. `undefined` when there is no voice message, and then no file is opened.

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

@@ -6,7 +6,7 @@ export const TRANSCRIBE_OPTION = [
 ];
 export const MODEL_OPTION = [
     "--model <model>",
-    "which downloaded speech model hears them, with --transcribe; `models audio list` shows them",
+    "which downloaded speech model hears them, with --transcribe; `models list` shows them",
 ];
 /**
  * Kept transcripts on every read; new ones with `--transcribe`, using the read's connection when

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

@@ -27,7 +27,7 @@ export const imagesCommand = (messenger) => {
         .action(async function () {
         const { chat, limit = DEFAULT_LIMIT } = this.opts();
         const context = messengerContext(this, messenger);
-        refuseLocalWrite(context, messenger.app.command, "conversations.embed");
+        refuseLocalWrite(context, messenger.app.command, "conversations.embeddings");
         const controller = new AbortController();
         context.track({ close: async () => controller.abort() });
         const done = await context.withServices((services) => services.pictures.embed({ ...(chat === undefined ? {} : { chat }), limit, signal: controller.signal }));

package/dist/cli/messenger/inbox.js

@@ -1,8 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command, Option } from "commander";
+import { Command } from "commander";
 import { renderMessages } from "../../render/messages.js";
-import { CHAT_KINDS } from "../../services/chats.js";
 import { kindsOf } from "../../services/inbox.js";
 import { modelWith } from "../../speech/hearing.js";
 import { REMOTE_READ } from "../effects.js";
@@ -41,7 +40,6 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     .option("--new", "what arrived since the last check, each message once — for scheduled runs")
     .option("--limit <n>", "at most this many per chat, the newest", positiveCount("--limit"))
     .option("--all", "muted and archived chats too — left out unless they mention you or reply to you")
-    .addOption(new Option("--kind <kinds>", `compatibility spelling for kind:; ${CHAT_KINDS.join(", ")}`).hideHelp())
     .option(...TRANSCRIBE_OPTION)
     .option(...MODEL_OPTION)
     .addHelpText("after", "To mark a chat read, use `chats mark-read <chat>`. The other side sees it.")

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

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

package/dist/cli/messenger/lacks.js

@@ -30,7 +30,7 @@ export const lackedNeed = (messenger, path) => {
     const need = COMMAND_NEEDS[path];
     if (!need)
         return undefined;
-    if (path === "messages comments" && messenger?.channelComments === false)
+    if (path === "messages comments" && (messenger?.readsComments ?? messenger?.channelComments) === false)
         return need;
     if (!messenger?.lacks?.includes(need[0]) && !messenger?.never?.includes(need[0]))
         return undefined;

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

@@ -74,9 +74,9 @@ 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"), {
+    command.addCommand(withFlags(grantsAuthority(annotate(new Command("add"), {
         effects: LOCAL_WRITE,
-        examples: [`${app.command} personal mcp setup codex --allow-writes`],
+        examples: [`${app.command} personal mcp add codex --allow-writes`],
     }))
         .description("add this profile's local MCP server to Codex or Claude Code")
         .argument("<client>", "codex or claude-code")
@@ -108,9 +108,9 @@ export const mcpCommand = (messenger) => {
             throw new CliError("validation_error", error instanceof Error ? error.message : "MCP setup failed");
         }
     }));
-    command.addCommand(withFlags(annotate(new Command("doctor"), {
+    command.addCommand(withFlags(annotate(new Command("check"), {
         effects: LOCAL_READ,
-        examples: [`${app.command} personal mcp doctor`],
+        examples: [`${app.command} personal mcp check`],
     }).description("check this profile's local MCP handshake and tool list")).action(async function () {
         const context = messengerContext(this, messenger);
         const { settings, env } = context;

package/dist/cli/messenger/messages-comments-command.js

@@ -10,15 +10,20 @@ import { messengerContext } from "./context.js";
 import { COMMENTS_QUERY, cursorOf, historyWindow } from "./history-query.js";
 import { messageItems, viewOf } from "./message-items.js";
 export const commentsCommand = (messenger) => {
+    const otherPosts = messenger.readsComments === true && messenger.channelComments === false;
     const command = annotate(new Command("comments"), {
-        examples: [`${messenger.app.command} personal messages comments "News channel" 101 --limit 20`],
+        examples: [
+            `${messenger.app.command} personal messages comments "${otherPosts ? "Announcements" : "News channel"}" 101 --limit 20`,
+        ],
         effects: REMOTE_READ,
     })
-        .summary("comments on a channel post")
-        .description("the comments under a channel post, oldest to newest; they live in its discussion group")
+        .summary(otherPosts ? "comments on a post" : "comments on a channel post")
+        .description(otherPosts
+        ? "the comments received under a post, oldest to newest"
+        : "the comments under a channel post, oldest to newest; they live in its discussion group")
         .addHelpText("after", queryHelp(COMMENTS_QUERY))
-        .argument("<chat>", `the channel: ${messenger.chatArgument}`)
-        .argument("<post>", "the post's message id in the channel")
+        .argument("<chat>", `the ${otherPosts ? "chat" : "channel"}: ${messenger.chatArgument}`)
+        .argument("<post>", otherPosts ? "the post's message id in the chat" : "the post's message id in the channel")
         .argument("[query...]", "where to start: id<42")
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .option("--cursor <cursor>", "go on from where the last page stopped; page.next gives it")