@wirecat/cli-core 0.343.0 → 0.344.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ shape of this file.
 
 ## Unreleased
 
+## 0.344.0 — 18.10.2026
+
+### Changed — may break callers
+
+- **`<tool> --help` and a bare `<tool>` show a short first screen instead of commander's full help**: the tool's
+  pitch, the usage line, one sentence that account commands start with the profile, what the tool can do, the other
+  WireCat tools, and where to go next (`commands`, `help options`, `skill show`, and `setup` or `guide` when the tool
+  has them). It no longer lists every command or the options for every command, so a test that looks for a command
+  or a global option in the root `--help` must read `--help-all`, which prints the old help, or `help options`.
+  Exit codes are unchanged: `--help` exits 0, a bare run exits 2.
+- **`<tool> commands` without `--json` prints a text list, by section, even when piped.** It printed the whole JSON
+  document (hundreds of kilobytes) to any reader that was not a terminal, and a table in one. Now every command that
+  runs is one line — its usage and the first clause of its description, `(writes)` when it changes something —
+  under Read, Write, Organise, Automate, Set up or Other. `commands <path>` narrows it. `--json` and `--jsonl` print
+  the same document as before; only the `commands` command's own description changed. A script that parsed the
+  output of a bare `commands` must pass `--json`.
+
+### Added
+
+- **`registerCommands(server, prefix, commands)` and the `McpCommand` type** (`@wirecat/cli-core/mcp`): the three
+  tools `<prefix>_tools_search`, `<prefix>_read` and `<prefix>_write` that tg and max serve in place of one tool per
+  command. A CLI without the messenger `mcpCommand`, such as drive, can now serve its own commands the same way.
+- **`ProgramDefinition.firstScreen` and `installHelp(program, screen)`** (`@wirecat/cli-core/cli`): a tool
+  supplies its `pitch` and 6–8 `can` lines (`{ command, does }`, the command without the profile);
+  `installHelp` puts the same screen on a program the tool builds itself, with `profile: false` for a tool
+  whose commands take no leading profile and `start` for its first command. A tool that supplies nothing gets its
+  description and no "What you can do" block.
+- **`<tool> help options`** prints the options for every command; `help <command>` prints that command's help.
+  `help` and `--help-all` are hidden, so `commands --json` and the MCP tools are unchanged.
+- **`inSection(command, section)` and `SECTIONS`** (`@wirecat/cli-core/cli`): where `commands` lists a group and
+  everything under it — `read`, `write`, `organise`, `automate` or `setup`; a command without one, or under none,
+  is listed under Other. `createProgram` puts cli-core's own groups (`chats`, `messages`, `tags`, `schedule`,
+  `config`…) in theirs; a tool sets its own groups (`session`, `setup`). The section is kept off the commands
+  document.
+
 ## 0.343.0 — 18.10.2026
 
 ### Added
@@ -54,6 +89,20 @@ shape of this file.
   permission governs those commands. Commands that a profile's permissions govern still need one.
 - **`serve`'s relay socket fits on macOS with a deep `TMPDIR`.** When the temporary folder is too deep for a socket
   path too, the socket goes under `/tmp` (still in an owner-only folder). It made tg's macOS release check fail.
+- **Help and errors say what a person typed.** The usage line of every command that uses a profile now reads
+  `<tool> <profile> …` (`Usage: tg <profile> mcp`); `commands`, `complete`, `help`, `skill` and `upgrade` keep the bare
+  form. Consumers' help snapshots change with this version.
+- A command that takes a free query (`chats list`, `meetings list`, `meetings projects evidence`) refuses a word that
+  starts with `--` as an unknown option, with commander's suggestion (`unknown option '--limt' (Did you mean
+  --limit?)`), instead of reading it as query text; a negated term like `-kind:channel` is still query, and after `--`
+  every word is.
+- A commander error is one line: `unknown command 'chts' (Did you mean chats?) …`.
+- The profile may follow global options: `tg --json personal chats list` works.
+- `complete --help` prints the help and exits 0.
+- A bot with no token, given a chat by name, says to store a token (exit 4) instead of "no chat matches".
+- "nothing recorded for profile" says "run the command once without --offline" only when `--offline` was given, and
+  names the profile in `serve`/`watch`.
+- `mcp setup` says "1 tool that may write"; the search help calls memo "the separate memo CLI".
 
 ### Security
 

package/dist/cli/bot/context.js

@@ -29,6 +29,7 @@ export const botContext = (command, bot) => {
         base.track(adapter);
         return adapter;
     };
+    const noToken = () => new CliError("authentication_error", `no bot token for profile "${profile}" — run \`${words} auth set\``);
     return {
         ...base,
         profile,
@@ -64,7 +65,11 @@ export const botContext = (command, bot) => {
             const trimmed = typed.trim();
             if (/^-?\d+$/.test(trimmed) || /^user:\d+$/.test(trimmed))
                 return trimmed;
-            return pickChat(trimmed, registry.list()).id;
+            const known = registry.list();
+            // A bot that never had a token has seen no chat, and its missing token is what needs fixing.
+            if (known.length === 0 && !tokens.read())
+                throw noToken();
+            return pickChat(trimmed, known).id;
         },
         readSecret: (prompt) => {
             return bot.readSecret?.(command, prompt) ?? readSecret(prompt, secretInputOf(command));
@@ -74,9 +79,8 @@ export const botContext = (command, bot) => {
         /** A client for the stored token, or a refusal that says how to store one. */
         authenticated: (options = {}) => {
             const stored = tokens.read();
-            if (!stored) {
-                throw new CliError("authentication_error", `no bot token for profile "${profile}" — run \`${words} auth set\``);
-            }
+            if (!stored)
+                throw noToken();
             return connect(stored.token, options);
         },
     };

package/dist/cli/commands-command.js

@@ -1,11 +1,12 @@
 import { CliError, EXIT_CODES, GENERIC_FAILURE } from "@wirecat/cli-base";
-import { annotate, describeOptions, describeProgram, flatten } from "@wirecat/cli-base/commands";
-import { CRASH_CODE, writes } from "@wirecat/cli-base/standards";
+import { annotate, describeOptions, describeProgram } from "@wirecat/cli-base/commands";
+import { CRASH_CODE } from "@wirecat/cli-base/standards";
 import { Command } from "commander";
 import { commandContract, findCommand } from "./command-contract.js";
-import { outputFor } from "./context.js";
+import { environmentOf, outputFor } from "./context.js";
 import { NO_EFFECTS } from "./effects.js";
 import { renderDocument } from "./envelope.js";
+import { commandsText } from "./help/commands-text.js";
 import { rootOf } from "./profile.js";
 /**
  * The major version of the JSON every command prints. The output types live in this package, so the
@@ -18,22 +19,18 @@ export const CONTRACT = 3;
  */
 export const commandsCommand = (app) => {
     const command = annotate(new Command("commands"), { effects: NO_EFFECTS })
-        .description("commands, options and exit codes as JSON — inspect one command path per call")
+        .description("every command by section, one line each; --json: the contract, one path per call")
         .argument("[path...]", "one command path, for example: search messages; inspect other groups in separate calls")
         .action(function (path) {
         const root = rootOf(this);
         const output = outputFor(this);
-        const { renderer, format } = output;
         const all = describeProgram(root);
         const scoped = path.length > 0 ? scopeOf(root, all, path) : undefined;
         const commands = scoped ? [scoped.command] : all;
-        if (format === "pretty") {
-            renderer.result(flatten(commands).map(({ usage, summary, description, effects, state }) => ({
-                command: usage,
-                description: summary ?? description,
-                writes: effects !== undefined && writes(effects) ? "yes" : "",
-                ...(state ? { state } : {}),
-            })));
+        const { json, jsonl } = this.optsWithGlobals();
+        // Asked by format, not by terminal: piped, an agent got the whole JSON tree it never asked for.
+        if (json === undefined && !jsonl && !environmentOf(this).agent) {
+            output.streams.data(commandsText(root, commands, scoped?.command.path).replace(/\n$/, ""));
             return;
         }
         renderDocument(output, {

package/dist/cli/help/commands-text.d.ts

@@ -0,0 +1,7 @@
+import type { CommandInfo } from "@wirecat/cli-base/commands";
+import type { Command } from "commander";
+/**
+ * `<tool> commands` for a person or an agent reading text: every command that runs, one line each, under its
+ * section. `scope` is the group asked for (`commands messages`), whose commands are all listed.
+ */
+export declare const commandsText: (root: Command, commands: readonly CommandInfo[], scope?: readonly string[]) => string;

package/dist/cli/help/commands-text.js

@@ -0,0 +1,43 @@
+import { writes } from "@wirecat/cli-base/standards";
+import { findCommand } from "../command-contract.js";
+import { SECTIONS, sectionOf } from "./sections.js";
+const DESCRIPTION = 90;
+const COLUMN = 52;
+/** The first clause that fits: a line per command is the point, the whole text is in `--help`. */
+const short = (text) => {
+    const line = text.replace(/\s+/g, " ").trim();
+    if (line.length <= DESCRIPTION)
+        return line;
+    const cut = line.slice(0, DESCRIPTION);
+    return `${cut.slice(0, Math.max(cut.lastIndexOf(" "), DESCRIPTION / 2))}…`;
+};
+/**
+ * `<tool> commands` for a person or an agent reading text: every command that runs, one line each, under its
+ * section. `scope` is the group asked for (`commands messages`), whose commands are all listed.
+ */
+export const commandsText = (root, commands, scope) => {
+    const cli = root.name();
+    const runs = (info) => [
+        ...(info.commands.length === 0 || info.runnable ? [info] : []),
+        ...info.commands.flatMap(runs),
+    ];
+    const bySection = new Map(Object.keys(SECTIONS).map((key) => [key, []]));
+    for (const info of commands.flatMap(runs))
+        bySection.get(sectionOf(findCommand(root, info.path)))?.push(info);
+    const where = scope ? `${cli} ${scope.join(" ")}` : cli;
+    const lines = [
+        `${where} commands, by section. One command's arguments and options: ${cli} <command> --help.`,
+        `As JSON: ${cli} commands${scope ? ` ${scope.join(" ")}` : ""} --json. (writes) marks a command that changes something.`,
+    ];
+    for (const [section, infos] of bySection) {
+        if (infos.length === 0)
+            continue;
+        lines.push("", SECTIONS[section]);
+        for (const { usage, summary, description, effects } of infos) {
+            const what = short(summary ?? description);
+            const mark = effects === undefined || writes(effects) ? " (writes)" : "";
+            lines.push(`  ${usage.padEnd(COLUMN)}  ${what}${mark}`.trimEnd());
+        }
+    }
+    return `${lines.join("\n")}\n`;
+};

package/dist/cli/help/first-screen.d.ts

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+export interface FirstScreenLine {
+    /** The command without the tool's name or the profile: `review --since 1d`. */
+    command: string;
+    does: string;
+}
+/** What a tool says on its first screen; the rest of the screen is the same for every WireCat tool. */
+export interface FirstScreen {
+    /** One sentence after `tg —`. Unset, the program's description. */
+    pitch?: string;
+    /** 6–8 lines, the ones a plain API client would not give. Unset, the block is left out. */
+    can?: readonly FirstScreenLine[];
+    /** `false` for a tool whose commands take no leading profile: no profile sentence, no `<profile>` in the usage. */
+    profile?: boolean;
+    /** The first command to run. Unset, `<tool> personal setup` when the tool has `setup`. */
+    start?: string;
+}
+interface Tool {
+    command: string;
+    shown?: string;
+    does: string;
+}
+/** Every WireCat tool, as "Works with" names it; a tool's own entry is left out of its screen. */
+export declare const WIRECAT_TOOLS: readonly Tool[];
+/**
+ * The screen `<tool> --help` and a bare `<tool>` show: what the tool is for, what it does that a client would not,
+ * the other tools, and where the full list, the scenarios and the options are. It never lists every command.
+ */
+export declare const firstScreen: (program: Command, screen?: FirstScreen) => string;
+/**
+ * Puts the first screen on `--help`, a bare run and `help`; `help options` prints the options for every command and
+ * `--help-all` the full commander help. `help` and `--help-all` are hidden, so `commands --json` and MCP do not
+ * change. For a tool that builds its own program; `createProgram` calls it for tg, max and wa.
+ */
+export declare const installHelp: (program: Command, screen?: FirstScreen) => Command;
+export {};

package/dist/cli/help/first-screen.js

@@ -0,0 +1,106 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command, Help, Option } from "commander";
+import wrapAnsi from "wrap-ansi";
+import { NO_EFFECTS } from "../effects.js";
+import { commandAt } from "../steps.js";
+/** Every WireCat tool, as "Works with" names it; a tool's own entry is left out of its screen. */
+export const WIRECAT_TOOLS = [
+    { command: "tg", does: "Telegram in the same local store: search, review and tasks offline" },
+    { command: "max", does: "MAX in the same local store: search, review and tasks offline" },
+    { command: "wa", does: "WhatsApp in the same local store: search, review and tasks offline" },
+    { command: "zm", does: "Zoom meetings: transcripts and summaries, searchable with your messages" },
+    { command: "drive", does: "Google Drive and Docs as local text, searchable with your messages" },
+    { command: "memo", shown: "memo context <person>", does: "one person across messengers, mail, notes and meetings" },
+];
+const WIDTH = 100;
+const widest = (texts) => texts.reduce((most, text) => Math.max(most, text.length), 0);
+const block = (title, rows, column) => rows.length === 0 ? [] : ["", `${title}:`, ...rows.map(([left, right]) => `  ${left.padEnd(column)}${right}`)];
+/** Only commands the tool has: `guide` and `setup` are not in every tool. */
+const pointers = (program, cli, start, profile) => {
+    const has = (path) => commandAt(program, path) !== undefined;
+    const next = [
+        has("commands") ? [`${cli} commands`, "every command, by section"] : undefined,
+        has("guide") ? [`${cli} guide`, "scenarios: command sequences for common tasks"] : undefined,
+        [`${cli} help options`, "output, offline, timeouts, dry run"],
+    ].filter((row) => row !== undefined);
+    const rows = [
+        ...(start ? [["Start here:", start, profile ? "(any profile name works)" : ""]] : []),
+        ...next.map(([command = "", does = ""], at) => [at === 0 ? "Next:" : "", command, does]),
+        ...(has("skill show") ? [["For agents:", `${cli} skill show`, "rules and the discovery loop"]] : []),
+    ];
+    const width = widest(rows.map(([, command]) => command)) + 2;
+    return ["", ...rows.map(([label, command, does]) => `${label.padEnd(14)}${command.padEnd(width)}${does}`.trimEnd())];
+};
+/**
+ * The screen `<tool> --help` and a bare `<tool>` show: what the tool is for, what it does that a client would not,
+ * the other tools, and where the full list, the scenarios and the options are. It never lists every command.
+ */
+export const firstScreen = (program, screen = {}) => {
+    const cli = program.name();
+    const profile = screen.profile !== false;
+    const pitch = screen.pitch ?? program.description().split("\n")[0] ?? "";
+    const can = (screen.can ?? []).map(({ command, does }) => [command, does]);
+    const works = WIRECAT_TOOLS.filter((tool) => tool.command !== cli).map(({ command, shown, does }) => [shown ?? command, does]);
+    const column = Math.max(22, widest([...can, ...works].map(([left]) => left))) + 2;
+    const start = screen.start ?? (commandAt(program, "setup") ? `${cli} personal setup` : undefined);
+    return [
+        wrapAnsi(`${cli} — ${pitch}`, WIDTH),
+        "",
+        `Usage: ${cli} ${profile ? "<profile> " : ""}<command> [options]`,
+        ...(profile ? ["Account commands start with your profile, a name you choose; none is ever assumed."] : []),
+        ...block("What you can do", can, column),
+        ...block("Works with", works, column),
+        ...pointers(program, cli, start, profile),
+        "",
+    ].join("\n");
+};
+const optionsScreen = (program) => {
+    const helper = program.createHelp();
+    const width = helper.longestOptionTermLength(program, helper);
+    return [
+        `Options for every ${program.name()} command:`,
+        ...helper
+            .visibleOptions(program)
+            .map((option) => helper.formatItem(helper.optionTerm(option), width, helper.optionDescription(option), helper)),
+        "",
+    ].join("\n");
+};
+/**
+ * Puts the first screen on `--help`, a bare run and `help`; `help options` prints the options for every command and
+ * `--help-all` the full commander help. `help` and `--help-all` are hidden, so `commands --json` and MCP do not
+ * change. For a tool that builds its own program; `createProgram` calls it for tg, max and wa.
+ */
+export const installHelp = (program, screen = {}) => {
+    let full = false;
+    const own = program.configureHelp();
+    program.configureHelp({
+        ...own,
+        // Commander copies this configuration to children made with `.command()`, so only the root gets the screen.
+        formatHelp: (command, helper) => command === program && !full
+            ? firstScreen(program, screen)
+            : (own.formatHelp ?? Help.prototype.formatHelp).call(helper, command, helper),
+    });
+    program.addOption(new Option("--help-all", "the full help: every command and option").hideHelp());
+    program.on("option:help-all", () => {
+        full = true;
+        program.help();
+    });
+    if (program.commands.some((command) => command.name() === "help"))
+        return program;
+    const help = annotate(new Command("help"), { effects: NO_EFFECTS, mcp: false })
+        .description("this screen; help options: the options for every command; help <command>: that command's help")
+        .argument("[topic...]", "options, or a command path")
+        .action((topic) => {
+        if (topic.length === 0)
+            return program.outputHelp();
+        if (topic.length === 1 && topic[0] === "options")
+            return program.configureOutput().writeOut?.(optionsScreen(program));
+        const command = commandAt(program, topic.join(" "));
+        if (!command)
+            throw new CliError("validation_error", `no command "${topic.join(" ")}" — run \`${program.name()} help\`, or \`${program.name()} help options\``, { available: program.commands.map((one) => one.name()).filter((name) => name !== "help") });
+        command.outputHelp();
+    });
+    program.addCommand(help, { hidden: true });
+    return program;
+};

package/dist/cli/help/sections.d.ts

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+export declare const SECTIONS: {
+    readonly read: "Read";
+    readonly write: "Write";
+    readonly organise: "Organise";
+    readonly automate: "Automate";
+    readonly setup: "Set up";
+    readonly other: "Other";
+};
+export type HelpSection = Exclude<keyof typeof SECTIONS, "other">;
+/**
+ * Where `<tool> commands` lists the command and everything under it. Kept off `annotate`, whose metadata becomes
+ * fields of `commands --json`, which must not change.
+ */
+export declare const inSection: <T extends Command>(command: T, section: HelpSection) => T;
+/** The nearest section on the command or above it; `other` when none is set. */
+export declare const sectionOf: (command: Command) => keyof typeof SECTIONS;
+/** Puts each of cli-core's groups mounted on `program` in its section, unless the tool already chose one. */
+export declare const sectionCoreGroups: (program: Command) => void;

package/dist/cli/help/sections.js

@@ -0,0 +1,76 @@
+export const SECTIONS = {
+    read: "Read",
+    write: "Write",
+    organise: "Organise",
+    automate: "Automate",
+    setup: "Set up",
+    other: "Other",
+};
+const sections = new WeakMap();
+/**
+ * Where `<tool> commands` lists the command and everything under it. Kept off `annotate`, whose metadata becomes
+ * fields of `commands --json`, which must not change.
+ */
+export const inSection = (command, section) => {
+    sections.set(command, section);
+    return command;
+};
+/** The nearest section on the command or above it; `other` when none is set. */
+export const sectionOf = (command) => {
+    for (let at = command; at; at = at.parent) {
+        const section = sections.get(at);
+        if (section)
+            return section;
+    }
+    return "other";
+};
+/** The groups cli-core builds, by name; a tool sets its own with `inSection`. */
+const CORE_SECTIONS = {
+    attachments: "read",
+    chats: "read",
+    contacts: "read",
+    conversations: "read",
+    images: "read",
+    inbox: "read",
+    meetings: "read",
+    mentions: "read",
+    messages: "read",
+    review: "read",
+    search: "read",
+    stats: "read",
+    topics: "read",
+    watch: "read",
+    flood: "write",
+    polls: "write",
+    reactions: "write",
+    recipients: "write",
+    sends: "write",
+    metadata: "organise",
+    searches: "organise",
+    tags: "organise",
+    tasks: "organise",
+    bot: "automate",
+    mcp: "automate",
+    replies: "automate",
+    runs: "automate",
+    schedule: "automate",
+    serve: "automate",
+    server: "automate",
+    account: "setup",
+    commands: "setup",
+    complete: "setup",
+    config: "setup",
+    doctor: "setup",
+    models: "setup",
+    skill: "setup",
+    store: "setup",
+    upgrade: "setup",
+};
+/** Puts each of cli-core's groups mounted on `program` in its section, unless the tool already chose one. */
+export const sectionCoreGroups = (program) => {
+    for (const command of program.commands) {
+        const section = CORE_SECTIONS[command.name()];
+        if (section && !sections.has(command))
+            inSection(command, section);
+    }
+};

package/dist/cli/index.d.ts

@@ -56,6 +56,8 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";
+export { type HelpSection, inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, type InputPolicy, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, type EntityFields, entityFields, type JsonFieldsResolver, type JsonRequest, liftJson, } from "./json-fields.js";
 export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, type QueryWords, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";

package/dist/cli/index.js

@@ -51,6 +51,8 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
+export { firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";
+export { inSection, SECTIONS } from "./help/sections.js";
 export { bufferedInput, inputPolicy, MAX_BUFFERED_INPUT, MAX_SECRET_INPUT, provideInputPolicy, } from "./input-policy.js";
 export { answerFields, checkJson, entityFields, liftJson, } from "./json-fields.js";
 export { commandPath, LIST_QUERY_GUIDE, listQuery, nativeField, nativeTerms, pagedList, pageOf, queryArgument, queryHelp, queryTerms, searchText, termField, timeBounds, typedQuery, unfilteredQuery, withQuery, } from "./list-query.js";

package/dist/cli/list-query.js

@@ -1,6 +1,7 @@
 import { annotate } from "@wirecat/cli-base/commands";
 import { dateRange, defineQuery, fieldsHelp, fieldsNamed, OPERATORS_BY_TYPE, parseLucene, QUERY_LIMITS, queryError, queryFieldsOf, validateQuery, } from "@wirecat/cli-base/query";
 import * as v from "valibot";
+import { queryWordsAfterOptions } from "../meetings/cli/index.js";
 import { listOf } from "./envelope.js";
 export const LIST_QUERY_GUIDE = "https://github.com/WireCatLabs/cli-core/blob/main/docs/search/query-language.md";
 /**
@@ -11,10 +12,7 @@ export const withQuery = (command, registry) => {
     const query = defineQuery(registry);
     annotate(command, { query, output: { entity: registry.entity } });
     const shown = askable(query);
-    // `-kind:channel` is a negated term, not an option; a mistyped option still fails, as a query word.
-    command
-        .allowUnknownOption()
-        .argument("[query...]", shown.length > 0
+    queryWordsAfterOptions(command).argument("[query...]", shown.length > 0
         ? "field:value terms that narrow the list — the fields are below"
         : "field:value terms; this list filters by none yet");
     if (shown.length > 0)

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

@@ -32,6 +32,8 @@ export const completeCommand = (messenger, config, options = {}) => annotate(new
     // Commander drops the `--` from the operands, so only the raw words tell a request from a shell name.
     const raw = root.rawArgs;
     if (!raw.includes("--")) {
+        if (words.includes("--help") || words.includes("-h"))
+            this.help();
         const [shell] = words;
         if (!shell || !SHELLS.includes(shell)) {
             throw new CliError("validation_error", `name a shell: ${app.command} complete ${SHELLS.join(" | ")}`);

package/dist/cli/messenger/context.js

@@ -230,16 +230,17 @@ export const connectedFor = async (command, messenger, base, options) => {
         ...connected(connection, messenger, base, options.events, store, options.listen ? { listen: true } : {}),
     };
 };
-const unrecorded = (command, messenger, profile) => {
-    const tool = messenger.app.command;
-    const setup = rootOf(command).commands.some((one) => one.name() === "setup")
-        ? `\`${tool} ${asFirstWord(profile)}setup\``
-        : undefined;
-    return new CliError("not_found", messenger.history === "store"
-        ? `nothing recorded for profile "${profile}" yet — ${setup ? `link it with ${setup}, then ` : ""}run ` +
-            `\`${tool} serve\` or \`${tool} watch\` once to fill the local store`
-        : `nothing recorded for profile "${profile}" yet — ${setup ? `log in with ${setup}, or ` : ""}run the ` +
-            "command once without --offline");
+const unrecorded = (command, messenger, profile, offline) => {
+    const words = `${messenger.app.command} ${asFirstWord(profile)}`;
+    const setup = rootOf(command).commands.some((one) => one.name() === "setup") ? `\`${words}setup\`` : undefined;
+    if (messenger.history === "store")
+        return new CliError("not_found", `nothing recorded for profile "${profile}" yet — ${setup ? `link it with ${setup}, then ` : ""}run ` +
+            `\`${words}serve\` or \`${words}watch\` once to fill the local store`);
+    const ways = [
+        ...(setup ? [`log in with ${setup}`] : []),
+        ...(offline ? ["run the command once without --offline"] : []),
+    ];
+    return new CliError("not_found", `nothing recorded for profile "${profile}" yet — ${ways.length > 0 ? ways.join(", or ") : "log in to it first"}`);
 };
 /** NEED-506 A: without it, an agent cannot tell a quiet chat from a store nothing keeps up to date. */
 const warnUnserved = async (messenger, profile, { env, renderer }, store) => {
@@ -300,7 +301,7 @@ export const messengerContext = (command, messenger, resolving = {}) => {
     const accountFor = () => {
         const account = messenger.accountOf?.(command) ?? recalledAccount(app, provider, profile, base.env);
         if (!account)
-            throw unrecorded(command, messenger, profile);
+            throw unrecorded(command, messenger, profile, base.settings.offline);
         return account;
     };
     const guard = messenger.guard?.(command, base.settings, warn) ??

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

@@ -113,7 +113,7 @@ export const mcpCommand = (messenger) => {
             const server = entry;
             const { potentialWrites } = await probeStdio(server);
             if (potentialWrites.length > 0 && this.opts().allowWrites !== true)
-                throw new Error(`this profile offers ${potentialWrites.length} tools that may write; review its permissions, then pass --allow-writes to install it`);
+                throw new Error(`this profile offers ${potentialWrites.length} ${potentialWrites.length === 1 ? "tool" : "tools"} that may write; review its permissions, then pass --allow-writes to install it`);
             renderAnswer(this, context, itemOf({ ...installStdioEntry(client, name, server), potential_writes: potentialWrites.length }));
         }
         catch (error) {

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

@@ -46,8 +46,8 @@ export const messagesSearchCommand = (messenger) => {
 coverage says what was searched and coverage.next what would improve it.`
         : `Search reads the local archive: what \`${messenger.app.command} serve\` has kept since the account was linked.
 Keep serve running so new messages are searchable.`} Notes are
-\`${messenger.app.command} search notes\`, messages and notes at once \`${messenger.app.command} search all\`; mail is memo's:
-\`memo search mail\`.
+\`${messenger.app.command} search notes\`, messages and notes at once \`${messenger.app.command} search all\`; for mail,
+the separate memo CLI: \`memo search mail\`.
 A bare word looks in message text, voice transcripts, file names and file text. text:, transcript:,
 content: (the text of files) and filename: (their names) narrow it to one —
 \`${messenger.app.command} search messages 'content:invoice'\`. chat: narrows it to one chat; has:voice, has:file and

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

@@ -15,7 +15,7 @@ import { topicsSearchCommand } from "./topics-command.js";
 const onlyOf = (value) => {
     const chosen = value.split(",").map((one) => one.trim());
     if (chosen.includes("mail"))
-        throw new CliError("validation_error", "mail is memo's: install @wirecat/cli-memo, then `memo search mail …`");
+        throw new CliError("validation_error", "mail is searched by the separate memo CLI: install @wirecat/cli-memo, then `memo search mail …`");
     const unknown = chosen.find((one) => !SOURCE_SEARCHED.includes(one));
     if (unknown !== undefined || chosen.length === 0)
         throw new CliError("validation_error", `--only takes ${SOURCE_SEARCHED.join(", ")}, separated by commas; meetings when --source names a meeting account`);
@@ -37,7 +37,7 @@ const allCommand = (messenger) => {
         ? "search messenger messages and notes in the local store, and the messenger's server for messages " +
             "(--backend; notes are local only)"
         : "search messenger messages and notes in the local store") +
-        ", and a meeting account's transcripts when --source names one — best match first; not mail (memo search mail), " +
+        ", and a meeting account's transcripts when --source names one — best match first; not mail (the separate memo CLI searches it: memo search mail), " +
         "tasks, people, memories or projects. Use it when you do not know where something was written; search messages " +
         "or notes reads one kind with all its fields")
         .argument("<query...>", 'strict Lucene query: words, "phrases", AND/OR/NOT, field groups and date ranges')
@@ -149,7 +149,7 @@ const notesCommand = (messenger) => annotate(new Command("notes"), { effects: LO
  * hierarchy"). `topics` only where the CLI has forum topics.
  */
 export const searchCommand = (messenger, { topics = false } = {}) => {
-    const search = new Command("search").description("find things by text: one resource when you know it (messages, notes), or search all across messages and notes; mail is memo search mail");
+    const search = new Command("search").description("find things by text: one resource when you know it (messages, notes), or search all across messages and notes; for mail, the separate memo CLI: memo search mail");
     search
         .addCommand(allCommand(messenger))
         .addCommand(messagesSearchCommand(messenger))

package/dist/cli/moved.js

@@ -4,7 +4,7 @@
  * "unknown command"; a path the program still mounts never reaches it.
  */
 export const MOVED_TO_MEMO = {
-    "search mail": { what: "mail is memo's", memo: "memo search mail …" },
+    "search mail": { what: "mail is searched by the separate memo CLI", memo: "memo search mail …" },
 };
 export const movedPointer = (path) => {
     const moved = MOVED_TO_MEMO[path];

package/dist/cli/profile.d.ts

@@ -2,6 +2,8 @@ import type { Command } from "commander";
 /** How the command line names this profile: always the first word, since none is assumed. */
 export declare const asFirstWord: (profile: string) => string;
 export declare const usableProfileName: (profile: string) => string;
+/** The top-level commands that never read a profile; every other one is `<tool> <profile> …`. */
+export declare const PROFILE_FREE: ReadonlySet<string>;
 /**
  * Every word that means a command at the top level. Taken off the built program rather than
  * written out, because a list written out goes stale the day a command is added — and `help` is in
@@ -13,10 +15,12 @@ export declare const commandWords: (program: Command) => Set<string>;
  * `TG_PROFILE=personal tg chats list`, with no flag in either. An option is never a profile, so
  * `tg --json chats list` still works.
  */
-export declare const liftProfile: (argv: string[], words: Set<string>) => {
+export declare const liftProfile: (argv: string[], words: Set<string>, valued?: ReadonlySet<string>) => {
     profile?: string;
     rest: string[];
 };
+/** The root's options that take the next word as their value: `--timeout 30s`. */
+export declare const valuedOptions: (program: Command) => Set<string>;
 /**
  * Refused at creation, which is the only moment it can still be explained: a profile named after a
  * command could never be selected, because `tg chats` has to mean the command.

package/dist/cli/profile.js

@@ -14,6 +14,8 @@ export const usableProfileName = (profile) => {
     }
     return profile;
 };
+/** The top-level commands that never read a profile; every other one is `<tool> <profile> …`. */
+export const PROFILE_FREE = new Set(["commands", "complete", "help", "skill", "upgrade"]);
 /**
  * Every word that means a command at the top level. Taken off the built program rather than
  * written out, because a list written out goes stale the day a command is added — and `help` is in
@@ -25,12 +27,20 @@ export const commandWords = (program) => new Set(["help", ...program.commands.fl
  * `TG_PROFILE=personal tg chats list`, with no flag in either. An option is never a profile, so
  * `tg --json chats list` still works.
  */
-export const liftProfile = (argv, words) => {
-    const [first, ...rest] = argv;
+export const liftProfile = (argv, words, valued = new Set()) => {
+    // `tg --json personal chats list`: options before the profile are skipped over, with the value an option takes.
+    let at = 0;
+    while (argv[at]?.startsWith("-") && argv[at] !== "--")
+        at += valued.has(argv[at]) ? 2 : 1;
+    const first = argv[at];
     if (first === undefined || first.startsWith("-") || words.has(first))
         return { rest: argv };
-    return { profile: first, rest };
+    return { profile: first, rest: [...argv.slice(0, at), ...argv.slice(at + 1)] };
 };
+/** The root's options that take the next word as their value: `--timeout 30s`. */
+export const valuedOptions = (program) => new Set(program.options
+    .filter((option) => option.required)
+    .flatMap((option) => [option.long, option.short].filter((flag) => flag !== undefined)));
 /**
  * Refused at creation, which is the only moment it can still be explained: a profile named after a
  * command could never be selected, because `tg chats` has to mean the command.

package/dist/cli/program.d.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { type AppIdentity } from "../ports/app.js";
 import { type BaseEnvironment } from "./context.js";
+import { type FirstScreen } from "./help/first-screen.js";
 import { type GlobalFlags, type ResolveOptions, type Settings } from "./settings.js";
 export interface ProgramDefinition {
     app: AppIdentity;
@@ -11,6 +12,8 @@ export interface ProgramDefinition {
         resolveSettings: (flags?: GlobalFlags, options?: ResolveOptions) => Pick<Settings, "profile" | "keepFailedRuns" | "keepRunsForDays" | "skillHint">;
     };
     configure?: (program: Command) => void;
+    /** The tool's pitch and "what you can do" lines on `--help` and a bare run. */
+    firstScreen?: FirstScreen;
     prepare?: (program: Command, environment: RunOptions) => void | Promise<void>;
     onFailure?: (error: unknown, program: Command) => void | Promise<void>;
 }
@@ -23,7 +26,7 @@ export interface ProgramOptions {
  * The command tree, built fresh on each call. Commander is global state by default —
  * `exitOverride` and the write hooks turn it into a value a test can drive.
  */
-export declare const createProgram: ({ app, commands, configure }: ProgramDefinition, { out, err }?: ProgramOptions) => Command;
+export declare const createProgram: ({ app, commands, configure, firstScreen }: ProgramDefinition, { out, err }?: ProgramOptions) => Command;
 export type RunOptions = BaseEnvironment & Record<string, unknown>;
 /**
  * An interactive command run without a terminal — an agent's `session start --qr-file` — waits on a person scanning a

package/dist/cli/program.js

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { CliError, errorObjectOf, errorRecordOf, exitCodeFor, exitCodeOfError, processStreams, renderError, resolvePaths, } from "@wirecat/cli-base";
 import { metaOf, refuseJoinedPath } from "@wirecat/cli-base/commands";
 import { skillHint } from "@wirecat/cli-base/skill";
-import { Command } from "commander";
+import { Command, Help } from "commander";
 import { relayCommand } from "../background/relay.js";
 import { failingNotice, scheduledRuns } from "../background/schedules.js";
 import { parseDuration } from "../domain/duration.js";
@@ -18,11 +18,13 @@ import { refuseWriteBeforeConnecting } from "./early-refusal.js";
 import { changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTargets, STORE_CHANGE_REFUSAL, } from "./effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
 import { byteCount, DEFAULT_COMMAND_MS, DEFAULT_OUTPUT_BYTES, execution } from "./execution.js";
+import { installHelp } from "./help/first-screen.js";
+import { sectionCoreGroups } from "./help/sections.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
 import { checkJson, liftJson } from "./json-fields.js";
 import { movedPath, movedPointer } from "./moved.js";
 import { PreviewComplete, preview } from "./preview.js";
-import { commandWords, liftProfile } from "./profile.js";
+import { commandWords, liftProfile, PROFILE_FREE, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
 import { settingsFor } from "./settings.js";
 import { commandAt } from "./steps.js";
@@ -30,7 +32,7 @@ import { commandAt } from "./steps.js";
  * The command tree, built fresh on each call. Commander is global state by default —
  * `exitOverride` and the write hooks turn it into a value a test can drive.
  */
-export const createProgram = ({ app, commands, configure }, { out, err } = {}) => {
+export const createProgram = ({ app, commands, configure, firstScreen }, { out, err } = {}) => {
     const program = new Command();
     program
         .name(app.command)
@@ -61,6 +63,16 @@ export const createProgram = ({ app, commands, configure }, { out, err } = {}) =
     for (const command of commands())
         program.addCommand(command);
     configure?.(program);
+    sectionCoreGroups(program);
+    installHelp(program, { pitch: app.description, ...firstScreen });
+    // Commander builds a usage line from the command tree, where the profile is not a word.
+    for (const top of program.commands) {
+        if (PROFILE_FREE.has(top.name()))
+            continue;
+        forEachCommand(top, (command) => command.configureHelp({
+            commandUsage: (shown) => `${app.command} <profile>${new Help().commandUsage(shown).slice(app.command.length)}`,
+        }));
+    }
     // Depth-first: Commander does not pass `configureOutput` down to a command added with
     // `addCommand`, so `tg messages --help` would write to the real terminal.
     if (out || err) {
@@ -327,7 +339,7 @@ export const run = async (argv, definition, options = {}) => {
     forEachCommand(program, (child) => child.exitOverride());
     // Before commander, not inside it: commander has no hook that runs before it decides which
     // subcommand it is looking at.
-    const { profile, rest: lifted } = liftProfile(argv, commandWords(program));
+    const { profile, rest: lifted } = liftProfile(argv, commandWords(program), valuedOptions(program));
     // `wa 'chats list' --help` reads "chats list" as a profile and prints the root help with exit 0.
     try {
         // Only before `--`: what follows is a positional, an agent's text among them, never a command word.
@@ -364,7 +376,9 @@ export const run = async (argv, definition, options = {}) => {
     try {
         await control.race(() => program.parseAsync(rest, { from: "user" }));
         const code = exit.code ?? (process.exitCode === undefined ? 0 : Number(process.exitCode));
-        const hint = code === 0 && rest[0] !== "commands" && !rest.includes("--quiet") ? hintFor(definition, rest, options) : undefined;
+        const hint = code === 0 && rest[0] !== "commands" && rest[0] !== "help" && !rest.includes("--quiet")
+            ? hintFor(definition, rest, options)
+            : undefined;
         if (hint)
             streams.diagnostic(hint);
         return code;
@@ -384,7 +398,8 @@ export const run = async (argv, definition, options = {}) => {
                 logVersion(argvLog);
             if (error.exitCode === 0)
                 return 0;
-            let message = error.message.replace(/^error: /, "");
+            // Commander puts its "(Did you mean …?)" on a line of its own; an error is one line.
+            let message = error.message.replace(/^error: /, "").replace(/\s*\n\s*/g, " ");
             if (error.code === "commander.help") {
                 if (reporting.tty ?? process.stdout.isTTY === true) {
                     streams.diagnostic(help.replace(/\n$/, ""));

package/dist/mcp/index.d.ts

@@ -2,3 +2,4 @@ export { type AgentAnswer, type AgentContext, type AgentProgram, type AgentTool,
 export { type BotServerOptions, createBotServer, type RunBotCommand } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";
 export { type HttpOptions, MCP_PATH, serveOverHttp } from "./http/serve.js";
+export { type McpCommand, registerCommands } from "./surface.js";

package/dist/mcp/index.js

@@ -3,3 +3,4 @@ export { runCommandForAgent, toolsFromCommands, } from "./agent.js";
 export { createBotServer } from "./bot/server.js";
 export { revokeAll } from "./http/oauth.js";
 export { MCP_PATH, serveOverHttp } from "./http/serve.js";
+export { registerCommands } from "./surface.js";

package/dist/meetings/cli/index.d.ts

@@ -14,4 +14,5 @@ export interface MeetingCommandDeps {
 export declare const addMeetingCommands: (program: Command, deps: MeetingCommandDeps) => void;
 export { addMeetingPassageCommand, createMeetingPassageCommand, type MeetingPassageFlags, meetingPassageRequest, } from "./passage.js";
 export { addMeetingProjectEvidenceCommand } from "./project-evidence.js";
+export { queryWordsAfterOptions } from "./query-options.js";
 export { addMeetingSearchCommand, createMeetingSearchCommand, type MeetingHitSearch, type MeetingHitSearchOptions, type MeetingSearchFlags, meetingHitSearchRequest, meetingSearchArguments, validateMeetingHitSearch, } from "./search.js";

package/dist/meetings/cli/index.js

@@ -7,6 +7,7 @@ import { MEETING_QUERY } from "../item.js";
 import { pull } from "../pull.js";
 import { listed, MEETING_QUERY_GUIDE, MeetingError, meetingDetailsAnswer, meetingPeople, meetingSummaryAnswer, meetingsList, meetingsQuery, meetingTranscriptAnswer, } from "../reads.js";
 import { SAVE_HELP } from "../save-hints.js";
+import { queryWordsAfterOptions } from "./query-options.js";
 const integer = (text) => {
     if (!/^[1-9]\d*$/.test(text) || !Number.isSafeInteger(Number(text)))
         throw new InvalidArgumentError("expected a positive integer");
@@ -39,10 +40,7 @@ export const addMeetingCommands = (program, deps) => {
         const opts = command.optsWithGlobals();
         deps.write(value, opts.json ? "json" : opts.jsonl ? "jsonl" : "text");
     };
-    const list = group
-        .command("list")
-        .description("stored meetings, newest first")
-        .allowUnknownOption()
+    const list = queryWordsAfterOptions(group.command("list").description("stored meetings, newest first"))
         .argument("[query...]", "field:value terms that narrow the list — the fields are below")
         .addHelpText("after", `\n${fieldsHelp(MEETING_QUERY, MEETING_QUERY_GUIDE)}`);
     annotate(list, { effects: LOCAL_READ, query: defineQuery(MEETING_QUERY), output: { entity: "meeting" } });
@@ -139,4 +137,5 @@ export const addMeetingCommands = (program, deps) => {
 };
 export { addMeetingPassageCommand, createMeetingPassageCommand, meetingPassageRequest, } from "./passage.js";
 export { addMeetingProjectEvidenceCommand } from "./project-evidence.js";
+export { queryWordsAfterOptions } from "./query-options.js";
 export { addMeetingSearchCommand, createMeetingSearchCommand, meetingHitSearchRequest, meetingSearchArguments, validateMeetingHitSearch, } from "./search.js";

package/dist/meetings/cli/project-evidence.js

@@ -3,6 +3,7 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { fieldsHelp } from "@wirecat/cli-base/query";
 import { readMeetingProjectEvidence } from "../project-evidence.js";
 import { MEETING_PROJECT_EVIDENCE_QUERY } from "../project-evidence-query.js";
+import { queryWordsAfterOptions } from "./query-options.js";
 const integer = (value) => {
     if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
         throw new CliError("validation_error", "expected a positive safe integer");
@@ -14,12 +15,11 @@ export const addMeetingProjectEvidenceCommand = (program, deps) => {
         throw new CliError("configuration_error", "meeting command group is unavailable");
     const projects = group.commands.find((command) => command.name() === "projects") ??
         group.command("projects").description("project-name evidence in stored meetings");
-    return annotate(projects
+    return annotate(queryWordsAfterOptions(projects
         .command("evidence")
-        .description("find cited project-name and alias evidence in the local meeting index; does not refresh it or confirm membership")
+        .description("find cited project-name and alias evidence in the local meeting index; does not refresh it or confirm membership"))
         .argument("<project>", "existing project name, key or explicit alias")
         .argument("[query...]", "exact ID fields and a UTC started_at range, joined by AND")
-        .allowUnknownOption()
         .addHelpText("after", `\n${fieldsHelp(MEETING_PROJECT_EVIDENCE_QUERY)}`)
         .option("--limit <n>", "hits in one name page, 1 through 1000 (default 100)", integer)
         .option("--cursor <cursor>", "continue with the same project and frozen selection from next")

package/dist/meetings/cli/query-options.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+/**
+ * Lets a query's `-kind:channel` through as a negated term while a mistyped `--limt` still fails as an unknown
+ * option, with commander's suggestion; after `--` every word is query.
+ */
+export declare const queryWordsAfterOptions: (command: Command) => Command;

package/dist/meetings/cli/query-options.js

@@ -0,0 +1,21 @@
+/**
+ * Lets a query's `-kind:channel` through as a negated term while a mistyped `--limt` still fails as an unknown
+ * option, with commander's suggestion; after `--` every word is query.
+ */
+export const queryWordsAfterOptions = (command) => {
+    command.allowUnknownOption();
+    const parse = command.parseOptions.bind(command);
+    command.parseOptions = (args) => {
+        const parsed = parse(args);
+        const end = parsed.unknown.indexOf("--");
+        const typo = parsed.unknown.slice(0, end < 0 ? undefined : end).find((word) => word.startsWith("--"));
+        if (typo !== undefined) {
+            command.allowUnknownOption(false);
+            command.unknownOption(typo);
+        }
+        if (end >= 0)
+            parsed.unknown.splice(end, 1);
+        return parsed;
+    };
+    return command;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.343.0",
+  "version": "0.344.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",