@wirecat/cli-core 0.344.0 → 0.345.0

package/dist/cli/help/command-help.js

@@ -0,0 +1,218 @@
+import { metaOf } from "@wirecat/cli-base/commands";
+import { writes } from "@wirecat/cli-base/standards";
+import { commandPathOf, outputOf } from "../command-contract.js";
+import { commandAt } from "../steps.js";
+import { short } from "./commands-text.js";
+/** Argument names onto the kinds `domain/references.ts` names; a plural takes the same kind. */
+const ARGUMENT_KINDS = {
+    chat: "chat",
+    chats: "chat",
+    message: "message",
+    messages: "message",
+    post: "message",
+    person: "person",
+    people: "person",
+    task: "task",
+    meeting: "meeting",
+    folder: "folder",
+    folders: "folder",
+    topic: "topic",
+    note: "note",
+    document: "document",
+    model: "model",
+};
+/** What a command answers with, by its declared entity, onto the same kinds. */
+const ENTITY_KINDS = {
+    message: "message",
+    message_link: "message",
+    chat: "chat",
+    contact: "person",
+    member: "person",
+    person: "person",
+    task: "task",
+    meeting: "meeting",
+    meeting_details: "meeting",
+    meeting_hit: "meeting",
+    meeting_summary: "meeting",
+    folder: "folder",
+    topic: "topic",
+    note: "note",
+    document: "document",
+    model: "model",
+};
+/** The group a kind lives in, whose commands come first among the ones that take it. */
+const HOME = {
+    chat: "chats",
+    message: "messages",
+    person: "contacts",
+    task: "tasks",
+    meeting: "meetings",
+    folder: "folders",
+    topic: "topics",
+    note: "notes",
+    document: "documents",
+    model: "models",
+};
+const SAMPLES = {
+    chat: "Team",
+    message: "1234",
+    post: "1234",
+    person: "Anna",
+    people: "Anna",
+    task: "12",
+    meeting: "123",
+    folder: "Work",
+    topic: "General",
+    model: "default",
+    query: '"invoice"',
+    text: '"on my way"',
+    title: '"Weekly sync"',
+    name: "daily",
+    id: "1",
+    file: "./report.pdf",
+    link: "https://example.com/join/abc",
+    url: "https://example.com",
+    since: "1d",
+    duration: "1d",
+    limit: "20",
+};
+const MAX_NEXT = 3;
+const choices = new WeakMap();
+/** Overrides the "Next usually" a command's help derives from types. Kept off `annotate`, like its section. */
+export const nextUsually = (command, choice) => {
+    choices.set(command, choice);
+    return command;
+};
+const kindOfArgument = (argument) => ARGUMENT_KINDS[argument.name()];
+const leaves = (command) => command.commands
+    .filter((child) => !child._hidden)
+    .flatMap((child) => (child.commands.length === 0 ? [child] : leaves(child)));
+const rootOf = (command) => {
+    let at = command;
+    while (at.parent)
+        at = at.parent;
+    return at;
+};
+const call = (command) => [
+    rootOf(command).name(),
+    ...commandPathOf(command),
+    ...command.registeredArguments.map((one) => (one.required ? `<${one.name()}>` : `[${one.name()}]`)),
+].join(" ");
+const returnsOf = (command) => {
+    const output = metaOf(command).output;
+    const { item, coverage } = outputOf(command);
+    if (!output || coverage !== "declared-entity")
+        return short(command.summary() || command.description()) || "not declared";
+    const required = item.required ?? [];
+    const fields = [
+        ...required,
+        ...Object.keys(item.properties ?? {}).filter((name) => !required.includes(name)),
+    ];
+    const noun = (output.view ? `${output.entity} ${output.view}` : output.entity).replaceAll("_", " ");
+    const more = fields.length > 8 ? `, and ${fields.length - 8} more` : "";
+    const root = rootOf(command);
+    const schema = commandAt(root, "commands schema")
+        ? `; every field: ${root.name()} commands schema ${commandPathOf(command).join(" ")}`
+        : "";
+    return `${noun} — ${fields.slice(0, 8).join(", ")}${more}${schema}`;
+};
+const nextOf = (command) => {
+    const root = rootOf(command);
+    const choice = choices.get(command) ?? {};
+    const drop = new Set(choice.drop ?? []);
+    const pinned = (choice.pin ?? []).flatMap((path) => commandAt(root, path) ?? []);
+    const output = metaOf(command).output;
+    const kind = output ? ENTITY_KINDS[output.entity] : undefined;
+    const all = leaves(root);
+    const derived = kind
+        ? all
+            .filter((other) => other !== command && !pinned.includes(other))
+            .filter((other) => other.registeredArguments.some((argument) => kindOfArgument(argument) === kind))
+            .map((other, order) => ({ other, order }))
+            .sort((a, b) => {
+            const rank = (other) => [
+                Number(writes(metaOf(other).effects)),
+                Number(!other.registeredArguments.some((one) => one.required && kindOfArgument(one) === kind)),
+                Number(commandPathOf(other)[0] !== HOME[kind]),
+                Number(other.parent !== command.parent),
+            ];
+            const [left, right] = [rank(a.other), rank(b.other)];
+            return left.reduce((found, value, at) => found || value - (right[at] ?? 0), 0) || a.order - b.order;
+        })
+            .map(({ other }) => other)
+        : [];
+    return [...pinned, ...derived].filter((other) => !drop.has(commandPathOf(other).join(" "))).slice(0, MAX_NEXT);
+};
+const sample = (name) => SAMPLES[name] ?? `<${name}>`;
+const generatedExample = (command) => {
+    const { query } = metaOf(command);
+    const words = command.registeredArguments.flatMap((argument) => {
+        const name = argument.name();
+        // A list's `[query...]` is its field filters, not text; a search's is the text.
+        if (name === "query" && query)
+            return [];
+        if (!argument.required && SAMPLES[name] === undefined)
+            return [];
+        return [argument.argChoices?.[0] ?? sample(name)];
+    });
+    const options = command.options
+        .filter((option) => option.mandatory)
+        .flatMap((option) => {
+        const flag = option.long ?? option.short ?? option.flags;
+        const placeholder = /[<[]([^>\]]+)[>\]]/.exec(option.flags)?.[1];
+        if (!(option.required || option.optional))
+            return [flag];
+        return [flag, option.argChoices?.[0] ?? sample(placeholder ?? option.attributeName())];
+    });
+    // No profile word, as on the first screen and in written examples: the Usage line already shows `<profile>`.
+    return [rootOf(command).name(), ...commandPathOf(command), ...words, ...options].join(" ");
+};
+/** Returns, Next usually and Example for one command, from its definition alone. */
+export const commandHelp = (command) => {
+    const written = metaOf(command).examples ?? [];
+    return {
+        returns: returnsOf(command),
+        next: nextOf(command).map(call),
+        examples: written.length > 0 ? written : [generatedExample(command)],
+        origin: written.length > 0 ? "written" : "generated",
+    };
+};
+const LABEL = 15;
+/** The lines `--help` prints after a command's options. */
+export const commandHelpText = (command) => {
+    const { returns, next, examples } = commandHelp(command);
+    const rows = (label, values) => values.map((value, at) => `${(at === 0 ? label : "").padEnd(LABEL)}${value}`);
+    return ["", ...rows("Returns:", [returns]), ...rows("Next usually:", next), ...rows("Example:", examples), ""].join("\n");
+};
+/** The same, as Markdown lines for `docs/commands.md`: hand it to cli-base's `commandsPage` per command. */
+export const commandHelpMarkdown = (root, path) => {
+    const command = commandAt(root, path.join(" "));
+    if (!command || command.commands.length > 0)
+        return [];
+    const { returns, next, examples } = commandHelp(command);
+    const code = (values) => values.map((value) => `\`${value}\``).join(", ");
+    return [
+        `**Returns:** ${returns}`,
+        ...(next.length > 0 ? [`**Next usually:** ${code(next)}`] : []),
+        `**Example:** ${code(examples)}`,
+    ];
+};
+/** Puts Returns, Next usually and Example on every leaf command's `--help`, worked out when the help is shown. */
+export const installCommandHelp = (program) => {
+    for (const command of leaves(program))
+        command.addHelpText("after", () => commandHelpText(command));
+};
+/** Which leaf commands still show a generated example, so the important ones get a written one. Report only. */
+export const exampleReport = (program) => {
+    const written = [];
+    const generated = [];
+    for (const command of leaves(program))
+        (commandHelp(command).origin === "written" ? written : generated).push(commandPathOf(command).join(" "));
+    const total = written.length + generated.length;
+    const text = [
+        `${program.name()}: ${written.length} of ${total} commands have a written example; ${generated.length} show a generated one:`,
+        ...generated.map((path) => `  ${program.name()} ${path}`),
+        "",
+    ].join("\n");
+    return { written, generated, text };
+};

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

@@ -1,5 +1,7 @@
 import type { CommandInfo } from "@wirecat/cli-base/commands";
 import type { Command } from "commander";
+/** The first clause that fits: a line per command is the point, the whole text is in `--help`. */
+export declare const short: (text: string) => string;
 /**
  * `<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.

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

@@ -4,7 +4,7 @@ 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) => {
+export const short = (text) => {
     const line = text.replace(/\s+/g, " ").trim();
     if (line.length <= DESCRIPTION)
         return line;

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

@@ -28,9 +28,10 @@ export declare const WIRECAT_TOOLS: readonly Tool[];
  */
 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.
+ * Puts the first screen on `--help`, a bare run and `help`, and Returns, Next usually and Example on every leaf
+ * command's `--help`. `help options` prints the options for every command, `--help-all` the full commander help;
+ * both 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

@@ -4,6 +4,7 @@ import { Command, Help, Option } from "commander";
 import wrapAnsi from "wrap-ansi";
 import { NO_EFFECTS } from "../effects.js";
 import { commandAt } from "../steps.js";
+import { installCommandHelp } from "./command-help.js";
 /** 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" },
@@ -67,9 +68,10 @@ const optionsScreen = (program) => {
     ].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.
+ * Puts the first screen on `--help`, a bare run and `help`, and Returns, Next usually and Example on every leaf
+ * command's `--help`. `help options` prints the options for every command, `--help-all` the full commander help;
+ * both 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;
@@ -81,6 +83,7 @@ export const installHelp = (program, screen = {}) => {
             ? firstScreen(program, screen)
             : (own.formatHelp ?? Help.prototype.formatHelp).call(helper, command, helper),
     });
+    installCommandHelp(program);
     program.addOption(new Option("--help-all", "the full help: every command and option").hideHelp());
     program.on("option:help-all", () => {
         full = true;

package/dist/cli/help/sections.js

@@ -61,6 +61,7 @@ const CORE_SECTIONS = {
     complete: "setup",
     config: "setup",
     doctor: "setup",
+    guide: "setup",
     models: "setup",
     skill: "setup",
     store: "setup",

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 { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, type Scenario, } from "./guide.js";
+export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.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";

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 { checkGuide, checkStep, guideCommand, loadScenarios, } from "./guide.js";
+export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.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";

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

@@ -335,7 +335,9 @@ export const conversationsCommand = (messenger) => {
     const consents = conversations
         .command("consents")
         .description("remembered analysis permissions for this account's chats and provider endpoints");
-    annotate(consents.command("list"), { effects: LOCAL_READ }).action(async function () {
+    annotate(consents.command("list"), { effects: LOCAL_READ })
+        .description("which chats and provider endpoints you allowed to analyse, and when")
+        .action(async function () {
         const context = messengerContext(this, messenger);
         const items = await context.withStore((store, account) => analysisConsents(store, account).list());
         renderAnswer(this, context, listOf("conversations consents list", {
@@ -345,6 +347,7 @@ export const conversationsCommand = (messenger) => {
         }));
     });
     annotate(consents.command("revoke"), { effects: LOCAL_WRITE })
+        .description("forget analysis permissions so the next analysis asks again")
         .option("--chat <chat>", "revoke only this chat's consents; defaults to every chat")
         .option("--provider <identity>", "exact provider identity from consents list; defaults to every provider")
         .action(async function () {

package/dist/cli/messenger/inbox.js

@@ -30,7 +30,7 @@ export const PARTIAL_NOTE = "the messenger did not list every chat, and did not
  */
 export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     effects: REMOTE_READ,
-    output: { entity: "message", view: "message.summary" },
+    output: { entity: "message", view: "summary" },
     query: INBOX_QUERY,
 })
     .description("other people's unread messages in every chat; --new for what arrived since the last check")

package/dist/cli/messenger/observed.js

@@ -32,8 +32,15 @@ export const observed = (messenger, events) => {
             throw error;
         }
     };
+    const counted = async (operation, onEvent, work) => {
+        const counts = {};
+        await timed(operation, {}, () => work((event) => {
+            counts[event.event] = (counts[event.event] ?? 0) + 1;
+            onEvent(event);
+        }), () => ({ counts }));
+    };
     const mint = messenger.newSendId;
-    const { chats, history, contact, around } = messenger;
+    const { chats, history, contact, around, watch, listen } = messenger;
     // A method not listed here is timed under its own name, with no ids until a line here names them.
     return throughWrapper(messenger, {
         self: () => messenger.self(),
@@ -75,15 +82,14 @@ export const observed = (messenger, events) => {
                 ...(options.threadId ? { thread: options.threadId } : {}),
             },
         }, () => messenger.send(chatId, text, options), (sent) => ({ ids: { message_id: sent.message.id } })),
-        ...(messenger.watch
+        ...(watch
+            ? {
+                watch: (onEvent, signal, onReady) => counted("messages.watch", onEvent, (counting) => watch.call(messenger, counting, signal, onReady)),
+            }
+            : {}),
+        ...(listen
             ? {
-                watch: async (onEvent, signal, onReady) => {
-                    const counts = {};
-                    await timed("messages.watch", {}, () => messenger.watch?.((event) => {
-                        counts[event.event] = (counts[event.event] ?? 0) + 1;
-                        onEvent(event);
-                    }, signal, onReady) ?? Promise.resolve(), () => ({ counts }));
-                },
+                listen: (onEvent, signal) => counted("adapter.listen", onEvent, (counting) => listen.call(messenger, counting, signal)),
             }
             : {}),
         logout: () => timed("session.logout", {}, () => messenger.logout()),

package/dist/cli/messenger/private-people-command.js

@@ -15,6 +15,7 @@ const everyNote = (command, items) => listOf(command, { items, limit: Math.max(1
 export const privatePeopleCommands = (messenger) => {
     const alias = new Command("alias").description("a private local display name in the selected account");
     annotate(alias.command("set"), { effects: LOCAL_WRITE })
+        .description("your own name for a person in this account; kept on this machine, never sent")
         .argument("<person>")
         .argument("<alias>")
         .action(async function (person, value) {
@@ -23,6 +24,7 @@ export const privatePeopleCommands = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.privatePeople.alias(person, value)))));
     });
     annotate(alias.command("rm"), { effects: LOCAL_WRITE })
+        .description("drop your local name for a person; their own name shows again")
         .argument("<person>")
         .action(async function (person) {
         const context = messengerContext(this, messenger);
@@ -30,13 +32,16 @@ export const privatePeopleCommands = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.privatePeople.alias(person, null)))));
     });
     const notes = new Command("notes").description("your private notes on a stored contact, the same in every account that sees them");
-    withQuery(annotate(notes.command("list"), { effects: LOCAL_READ }).argument("<person>"), NOTES_QUERY).action(async function (person, words) {
+    withQuery(annotate(notes.command("list"), { effects: LOCAL_READ })
+        .description("every private note you keep on a person, oldest first")
+        .argument("<person>"), NOTES_QUERY).action(async function (person, words) {
         const context = messengerContext(this, messenger);
         listQuery(typedQuery(words), NOTES_QUERY, "contacts notes list");
         const items = await context.withServices((services) => services.privatePeople.notes(person));
         renderAnswer(this, context, everyNote("contacts notes list", items));
     });
     annotate(notes.command("show"), { effects: LOCAL_READ, output: { entity: "contact_note" } })
+        .description("one private note on a person, with its revision for edit")
         .argument("<person>")
         .argument("<id>")
         .action(async function (person, id) {
@@ -48,6 +53,9 @@ export const privatePeopleCommands = (messenger) => {
             effects: LOCAL_WRITE,
             output: { entity: "contact_note" },
         }), { name: "text", description: "the note's text" })
+            .description(name === "add"
+            ? "add a private note on a person from stdin or --file; never sent"
+            : "replace a note's text; --revision must match the one you read")
             .argument("<person>")
             .addOption(ownerOnlyOption("--file <path>", "read note text from a file; omitted or - reads stdin"));
         if (name === "edit")
@@ -67,6 +75,7 @@ export const privatePeopleCommands = (messenger) => {
         });
     }
     annotate(notes.command("remove"), { effects: LOCAL_WRITE })
+        .description("delete one private note on a person")
         .argument("<person>")
         .argument("<id>")
         .action(async function (person, id) {

package/dist/cli/messenger/review.js

@@ -26,7 +26,7 @@ export const unansweredHours = (value, flag = "--unanswered") => value === true
  */
 export const reviewCommand = (messenger) => annotate(new Command("review"), {
     effects: REMOTE_READ,
-    output: { entity: "message", view: "message.summary" },
+    output: { entity: "message", view: "summary" },
     query: REVIEW_QUERY,
 })
     .description("every message, yours too, in chats that changed since a point — for reviewing who owes what")

package/dist/cli/messenger/store-maintenance-command.d.ts

@@ -2,9 +2,9 @@ import { Command } from "commander";
 import type { Messenger } from "./context.js";
 /** `doctor`'s short summary of the store. Must answer for a broken file, so an error is a field. */
 export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
-    error?: undefined;
     path: string;
     exists: boolean;
+    error?: undefined;
 } | {
     path: string;
     exists: boolean;

package/dist/cli/messenger/store-maintenance-command.js

@@ -569,8 +569,10 @@ const restoreFrom = async (command, messenger, backup, given) => {
     const schema = await backupSchema(backup);
     const stamp = stampNow();
     const kept = existsSync(path) ? `${path}.before-restore-${stamp}` : null;
-    if (kept)
-        await quiesce(path, messenger, "restore", (message) => renderer.warn(message));
+    if (kept) {
+        const waitMs = environmentOf(command).storeLockWaitMs;
+        await quiesce(path, messenger, "restore", (message) => renderer.warn(message), waitMs);
+    }
     else
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     const incoming = `${path}.restoring-${stamp}`;
@@ -614,12 +616,13 @@ const backupSchema = async (backup) => {
     }
     return schema;
 };
+const STORE_LOCK_WAIT_MS = 1_000;
 /**
  * No other process has the file open, no write is under way, and the write-ahead log is folded in,
  * so the file set aside is whole on its own. In WAL mode SQLite cannot say who has the file open —
  * `EXCLUSIVE` behaves as `IMMEDIATE` — so that is asked of the system.
  */
-const quiesce = async (path, messenger, then, warn) => {
+const quiesce = async (path, messenger, then, warn, waitMs = STORE_LOCK_WAIT_MS) => {
     const { command } = messenger.app;
     const files = [path, `${path}-wal`, `${path}-shm`]
         .filter((file) => existsSync(file))
@@ -634,7 +637,7 @@ const quiesce = async (path, messenger, then, warn) => {
     }
     const database = await openCache(path);
     try {
-        database.exec("PRAGMA busy_timeout = 1000");
+        database.exec(`PRAGMA busy_timeout = ${waitMs}`);
         database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
         try {
             database.exec("BEGIN IMMEDIATE");
@@ -673,7 +676,7 @@ const resetCommand = (messenger) => annotate(new Command("reset"), { effects: LO
         if (!/^\s*y(es)?\s*$/i.test(answer))
             throw new CliError("cancelled", "cancelled — the store is unchanged");
     }
-    await quiesce(path, messenger, "reset", (message) => renderer.warn(message));
+    await quiesce(path, messenger, "reset", (message) => renderer.warn(message), environmentOf(this).storeLockWaitMs);
     const backup = keep ? `${path}.backup-${stampNow()}` : null;
     let backedUp = null;
     if (backup) {

package/dist/cli/profile.js

@@ -15,7 +15,7 @@ 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"]);
+export const PROFILE_FREE = new Set(["commands", "complete", "guide", "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

package/dist/cli/program.js

@@ -53,8 +53,8 @@ export const createProgram = ({ app, commands, configure, firstScreen }, { out,
         .option("--no-input", "never prompt or open interactive login; piped input remains available")
         .option("--max-input-bytes <bytes>", "maximum buffered input bytes (default: 16777216)")
         .option("--max-output-bytes <bytes>", "maximum machine output bytes (default: 4194304; 0 disables)")
-        .option("--brief", "found messages and mail as reference, title, time, sender and excerpt only")
-        .option("--full", "found messages and mail with their whole text and every provider field")
+        .option("--brief", "found messages as reference, title, time, sender and excerpt only")
+        .option("--full", "found messages with their whole text and every provider field")
         .option("--dry-run", "preview parsed arguments and permissions before running the action")
         .option("--yes", "go ahead without the question an ask level puts before a write")
         .option("--record", "keep this run — ids and timings, never message content")