@wirecat/cli-core 0.401.0 → 0.403.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ shape of this file.
 
 ## Unreleased
 
+## 0.403.0 — 24.10.2026
+
+### Added
+
+- **`setupAtStart` runs the shared first-run questions for a tool with its own program** (zm, memo, drive): it asks only a person at a terminal, and the command runs whatever happens to the questions.
+
+- **The first command at a terminal asks three questions once for every WireCat tool.** Which languages you write and speak (English and the system's language ticked on a new store; a store in use keeps its own, so Enter changes nothing), which other WireCat tools to install (installed ones are marked), and whether commands and agents may only read. The answers sit in the `setup` section of `~/.config/WireCat/config.json`; "read only" caps every profile of every tool, over MCP too. Agents, pipes, `--json`, `--no-input` and `CI` are never asked. `askSetupQuestions` lets a tool's `setup` ask them again.
+
+## 0.402.0 — 24.10.2026
+
+### Changed — may break callers
+
+- **MCP offers `bot api`, behind `bot.api`.** The generated `bot api <operation>` commands (raw calls to Bot API methods, which skip the send guard and the bot's recipient list) are bot MCP tools again, offered only where the profile sets `permissions.bot.api` to `allow`; it is `deny` by default for an MCP server, so nothing changes until the owner turns it on, and a broader `bot: allow` does not lift it. A call made after the owner turned it off is refused naming the key and the terminal command; an agent cannot set the key through `config set` (the guard on `permissions.mcp…` covers `permissions.bot.api`). Breaking for a CLI: `generatedApiCommand` no longer marks the group `mcp: false`, and each operation now declares effects (`remote: read` or `write`), so `commands --json` shows them and a catalogue built with `toolsFromCommands` without `levels` lists the operations; update a pinned bot catalogue and a document that lists what MCP leaves out. Under `<PREFIX>_READ_ONLY` a write operation now refuses on the command line too. The command line's `bot api` is otherwise unchanged.
+
+### Fixed
+
+- **Voice-note search no longer turns an English word into another real English word.** A word in a transcript widens to the spellings speech recognition garbles only past a dictionary of its language: Russian as before, and now English and Spanish, following the store's word-form languages (`search_stemmers`). Before, «cost» also found «cast». A Latin word with no dictionary for its language, and English and Spanish number words, no longer widen.
+
+### Added
+
+- **`watchMirrors` keeps folder mirrors in step.** One cycle per local save (after a quiet period, and only when the
+  files differ from the last sync), per remote change the CLI reports, per periodic local check and per full run;
+  each cycle syncs only the mirrors that need it, and a failed one is retried at the next poll.
+
 ## 0.401.0 — 24.10.2026
 
 ### Changed — may break callers

package/dist/cli/bot/api.js

@@ -1,15 +1,18 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command, Option } from "commander";
+import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { apiFlagOf, apiOptionKey, readApiBody } from "./api-input.js";
 export const generatedApiCommand = (api) => {
-    const group = annotate(new Command("api"), { mcp: false }).description(api.description ?? "every operation of the official Bot API, generated from its schema");
+    const group = new Command("api").description(api.description ?? "every operation of the official Bot API, generated from its schema");
     group.option("--store-token <profile>", "keep a returned authentication token only in this bot profile's OS keyring; never print it");
     for (const operation of api.operations) {
         const binding = operation.binding.kind === "http"
             ? `${operation.binding.method} ${operation.binding.path}`
             : operation.binding.name;
-        const command = new Command(operation.command).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`);
+        const command = annotate(new Command(operation.command), {
+            effects: operation.effect === "read" ? REMOTE_READ : REMOTE_WRITE,
+        }).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`);
         for (const parameter of operation.parameters) {
             if (parameter.sensitive)
                 continue;

package/dist/cli/config-command.js

@@ -2,7 +2,7 @@ import { CliError, pathsAreOverridden } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { envName } from "../ports/app.js";
-import { AUTHORITY_KEY } from "../sends/permissions.js";
+import { AUTHORITY_KEY, BOT_API_KEY } from "../sends/permissions.js";
 import { loadSnakeCaseConfig } from "./config-keys.js";
 import { baseContext, environmentOf } from "./context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "./effects.js";
@@ -96,7 +96,7 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
                 throw new CliError("permission_error", `this process is locked to profile ${settings.profile} (${lock}) — ${setting === "default_profile" ? setting : "--defaults"} changes other profiles`);
             }
             if (environmentOf(this).agent)
-                refuseAuthorityKey(setting, action === "set" ? String(given) : undefined);
+                refuseGuardedKey(setting, action === "set" ? String(given) : undefined);
             if (action === "set")
                 refuseUnknownKey(this, setting, String(given), permissionKey);
             const saved = config.changeSetting(settings.configPath, {
@@ -137,10 +137,11 @@ export const refuseUnknownKey = (command, setting, value, permissionKey) => {
     }
 };
 /**
- * An agent may hold `mcp.authority` and change other settings, but never the key that let it in: on any profile, in
- * the defaults, or by replacing `permissions` whole. Only the owner, in a terminal, turns it on or off (NEED-1662).
+ * An agent may hold `mcp.authority` or `bot.api` and change other settings, but never the key that let it in: on any
+ * profile, in the defaults, or by replacing `permissions` whole. Only the owner, in a terminal, turns it on or off
+ * (NEED-1662, NEED-1679).
  */
-const refuseAuthorityKey = (setting, value) => {
+const refuseGuardedKey = (setting, value) => {
     const keys = setting.startsWith("permissions.")
         ? [setting.slice("permissions.".length)]
         : setting === "permissions"
@@ -148,9 +149,14 @@ const refuseAuthorityKey = (setting, value) => {
                 ? ["mcp"]
                 : objectKeys(value)
             : [];
-    if (!keys.some((key) => key === "mcp" || key.startsWith("mcp.")))
+    const guarded = keys.some((key) => key === BOT_API_KEY || key.startsWith(`${BOT_API_KEY}.`))
+        ? BOT_API_KEY
+        : keys.some((key) => key === "mcp" || key.startsWith("mcp."))
+            ? AUTHORITY_KEY
+            : undefined;
+    if (!guarded)
         return;
-    throw new CliError("permission_error", `an agent cannot change permissions.${AUTHORITY_KEY} — the owner sets it in a terminal`, { permission: AUTHORITY_KEY });
+    throw new CliError("permission_error", `an agent cannot change permissions.${guarded} — the owner sets it in a terminal`, { permission: guarded });
 };
 /** The keys of a `permissions` object given whole; anything else is left to the schema to refuse. */
 const objectKeys = (value) => {

package/dist/cli/context.d.ts

@@ -87,6 +87,8 @@ export interface AgentRun {
     overrides?: readonly string[];
     /** The server's levels allow `mcp.authority`: a command that changes what a later run may do may run. */
     authority?: boolean;
+    /** The server's levels allow `bot.api`: a raw Bot API call, past the send guard, may run. */
+    botApi?: boolean;
 }
 export interface RelayedRun {
     /** The profile serve holds; a command for another is refused before it touches the connection. */

package/dist/cli/first-run.d.ts

@@ -0,0 +1,68 @@
+import { type Installer } from "@wirecat/cli-base/update";
+import { type Question } from "./setup-answers.js";
+/** The languages cli-core stems and has a dictionary for; each is one stemmer of its alphabet. */
+export declare const LANGUAGES: readonly [{
+    readonly name: "russian";
+    readonly code: "ru";
+    readonly label: "Russian";
+    readonly script: "cyrillic";
+}, {
+    readonly name: "english";
+    readonly code: "en";
+    readonly label: "English";
+    readonly script: "latin";
+}, {
+    readonly name: "spanish";
+    readonly code: "es";
+    readonly label: "Spanish";
+    readonly script: "latin";
+}];
+export interface FirstRunIo {
+    ask: (prompt: string) => Promise<string>;
+    say: (text: string) => void;
+}
+export interface FirstRun {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    io: FirstRunIo;
+    /** Every question, as `setup` asks them; otherwise only those no WireCat tool asked yet. */
+    all?: boolean;
+    /** Where tools are looked for and how one is installed; injected by tests. */
+    installed?: (command: string) => boolean;
+    installer?: Installer;
+    install?: (argv: string[]) => boolean;
+}
+/**
+ * Only a person at a terminal is asked. An agent in a real terminal passes every terminal check and would wait on
+ * the question forever; a process locked read-only must write nothing, and every answer writes something.
+ */
+export declare const asksAtStart: (start: {
+    headless: boolean;
+    terminal: boolean;
+    env: NodeJS.ProcessEnv;
+    readOnlyLock: string | undefined;
+    path: readonly string[];
+}) => boolean;
+/** The system's language, as the first locale variable set names it: `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`. */
+export declare const systemLanguage: (env: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * The questions every WireCat tool shares, asked once for all of them: the answers go to the shared config
+ * file, the languages to the store. Only this, at a terminal, writes the permission answer.
+ */
+export declare const askSetupQuestions: (run: FirstRun) => Promise<Question[]>;
+/**
+ * The first-run step a tool runs before each command: asks when `asksAtStart` says so, and lets the command run
+ * whatever happens to the questions. `setup` asks all three again, since a refusal sends the owner there.
+ * A tool that builds its own program (zm, memo, drive) calls this with its command path.
+ */
+export declare const setupAtStart: (start: {
+    command: string;
+    env: NodeJS.ProcessEnv;
+    path: readonly string[];
+    headless: boolean;
+    readOnlyLock?: string | undefined;
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    terminal?: boolean;
+}) => Promise<void>;

package/dist/cli/first-run.js

@@ -0,0 +1,224 @@
+import { spawnSync } from "node:child_process";
+import { accessSync, constants, realpathSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { installerOf, updateCommand } from "@wirecat/cli-base/update";
+import { DEFAULT_STEMMERS } from "../search/stem.js";
+import { openCache } from "../store/open.js";
+import { storePath } from "../store/path.js";
+import { sharedConfigPath } from "../store/shared-config.js";
+import { openStore } from "../store/store.js";
+import { readSecret } from "../terminal/prompt.js";
+import { WIRECAT_TOOLS } from "./help/first-screen.js";
+import { buildStems } from "./messenger/store-maintenance-command.js";
+import { QUESTIONS, readSetupAnswers, unanswered, writeSetupAnswers, } from "./setup-answers.js";
+/** The languages cli-core stems and has a dictionary for; each is one stemmer of its alphabet. */
+export const LANGUAGES = [
+    { name: "russian", code: "ru", label: "Russian", script: "cyrillic" },
+    { name: "english", code: "en", label: "English", script: "latin" },
+    { name: "spanish", code: "es", label: "Spanish", script: "latin" },
+];
+/** Commands that run without first-run questions: they serve agents, help, or open the store themselves. */
+const SKIPPED = new Set(["help", "guide", "completion", "mcp", "serve", "server", "update", "store"]);
+/**
+ * Only a person at a terminal is asked. An agent in a real terminal passes every terminal check and would wait on
+ * the question forever; a process locked read-only must write nothing, and every answer writes something.
+ */
+export const asksAtStart = (start) => !start.headless &&
+    start.terminal &&
+    !start.env.AI_AGENT &&
+    !start.env.CLAUDECODE &&
+    start.readOnlyLock === undefined &&
+    !SKIPPED.has(start.path[0] ?? "");
+/** The system's language, as the first locale variable set names it: `LC_ALL`, `LC_MESSAGES`, `LANG`, `LANGUAGE`. */
+export const systemLanguage = (env) => {
+    const named = [env.LC_ALL, env.LC_MESSAGES, env.LANG, ...(env.LANGUAGE ?? "").split(":")]
+        .map((value) => value?.trim())
+        .find((value) => value && value !== "C" && value !== "POSIX" && !value.startsWith("C."));
+    return (named ?? Intl.DateTimeFormat().resolvedOptions().locale).slice(0, 2).toLowerCase();
+};
+const stemmersOf = (languages) => {
+    const latin = LANGUAGES.filter(({ name, script }) => script === "latin" && languages.includes(name));
+    return {
+        cyrillic: languages.includes("russian") ? "russian" : "none",
+        latin: latin.length ? latin.map(({ name }) => name).join(",") : "none",
+    };
+};
+const languagesOf = (stemmers) => LANGUAGES.filter(({ name }) => stemmers.cyrillic === name || stemmers.latin.split(",").includes(name)).map(({ name }) => name);
+/** Numbers from a list, as `1,3` or `1 3`; Enter keeps `chosen`. A wrong answer is asked again, then left as it was. */
+const choose = async (io, prompt, count, chosen) => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const answer = (await io.ask(prompt)).trim();
+        if (!answer)
+            return chosen;
+        if (/^(none|-)$/i.test(answer))
+            return [];
+        const numbers = answer
+            .split(/[\s,]+/)
+            .filter(Boolean)
+            .map(Number);
+        if (numbers.every((number) => Number.isInteger(number) && number >= 1 && number <= count))
+            return [...new Set(numbers)].sort((a, b) => a - b);
+        io.say(`Choose numbers from 1 to ${count}, separated by commas.`);
+    }
+    return chosen;
+};
+const yes = async (io, prompt) => /^y(es)?$/i.test((await io.ask(prompt)).trim());
+const onPath = (command, env) => {
+    const names = process.platform === "win32" ? [".cmd", ".exe", ""].map((ending) => command + ending) : [command];
+    return (env.PATH ?? env.Path ?? "").split(delimiter).some((folder) => names.some((name) => {
+        try {
+            accessSync(join(folder, name), process.platform === "win32" ? constants.F_OK : constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+};
+/** With the installer that installed this tool, its output on stderr so stdout stays data. */
+const installWith = (argv) => spawnSync(argv[0], argv.slice(1), { stdio: ["inherit", 2, 2] }).status === 0;
+const installerHere = () => {
+    try {
+        return installerOf(realpathSync(process.argv[1] ?? ""));
+    }
+    catch {
+        return "unknown";
+    }
+};
+const askLanguages = async ({ command, env, io }) => {
+    const store = await openStore({ env });
+    let rebuild = false;
+    try {
+        const saved = (await store.searchIndex.stemmers()) ?? undefined;
+        // A store already in use keeps the languages it was built with, so Enter changes nothing (RISK-1612).
+        const inUse = saved !== undefined || (await store.accounts.accounts()).length > 0;
+        const system = systemLanguage(env);
+        const ticked = inUse
+            ? languagesOf(saved ?? DEFAULT_STEMMERS)
+            : LANGUAGES.filter(({ code }) => code === "en" || code === system).map(({ name }) => name);
+        const numbers = ticked.map((name) => LANGUAGES.findIndex((one) => one.name === name) + 1);
+        io.say("Languages you write and speak — search finds every form of their words, and spellings speech mangles:");
+        LANGUAGES.forEach(({ name, label }, at) => {
+            io.say(`  ${at + 1}. ${label}${ticked.includes(name) ? " ✓" : ""}`);
+        });
+        const chosen = await choose(io, `Numbers (${numbers.join(",")}): `, LANGUAGES.length, numbers);
+        const next = stemmersOf(chosen.map((number) => LANGUAGES[number - 1].name));
+        const before = saved ?? DEFAULT_STEMMERS;
+        if (inUse && before.cyrillic === next.cyrillic && before.latin === next.latin)
+            return;
+        // Word search refuses until stems built by the old choice are rebuilt, so the change and the rebuild go together.
+        if (inUse &&
+            !(await yes(io, "Rebuild the word forms of every stored message now? Word search waits for it; a large store takes minutes. [y/N] "))) {
+            io.say(`Languages kept as they were; \`${command} setup\` asks again.`);
+            return;
+        }
+        await store.searchIndex.saveStemmers(next);
+        rebuild = inUse;
+    }
+    finally {
+        await store.close();
+    }
+    if (!rebuild)
+        return;
+    const database = await openCache(storePath(env));
+    try {
+        buildStems(database, (note) => io.say(`  ${note}`), { force: true });
+    }
+    finally {
+        database.close();
+    }
+};
+const askTools = async (run) => {
+    const { command, env, io } = run;
+    const installed = run.installed ?? ((name) => onPath(name, env));
+    const others = WIRECAT_TOOLS.filter((tool) => tool.command !== command);
+    const missing = others.filter((tool) => !installed(tool.command));
+    io.say("Other WireCat tools — they share this store, so one search finds everything:");
+    for (const tool of others) {
+        const at = missing.indexOf(tool);
+        io.say(`  ${at < 0 ? "✓ " : `${at + 1}.`} ${tool.command} — ${tool.does}`);
+    }
+    if (!missing.length)
+        return;
+    const chosen = await choose(io, "Numbers to install (none): ", missing.length, []);
+    const installer = run.installer ?? installerHere();
+    for (const number of chosen) {
+        const tool = missing[number - 1];
+        const argv = updateCommand(installer, tool.package);
+        if (!argv) {
+            io.say(`Install ${tool.command} with \`npm install -g ${tool.package}\`.`);
+            continue;
+        }
+        io.say(`Installing ${tool.command}: ${argv.join(" ")}`);
+        if (!(run.install ?? installWith)(argv))
+            io.say(`${tool.command} was not installed; run \`${argv.join(" ")}\`.`);
+    }
+};
+const PERMISSION_CHOICES = [
+    { answer: "readonly", text: "read only — search and read; nothing sends or changes, bots and agents included" },
+    { answer: "allow", text: "as now — each profile's own permissions" },
+];
+const askPermissions = async ({ io }, answers) => {
+    const now = answers.permissions ?? "allow";
+    const current = Math.max(1, PERMISSION_CHOICES.findIndex(({ answer }) => answer === now) + 1);
+    io.say("What may commands and agents do, in every WireCat tool?");
+    PERMISSION_CHOICES.forEach(({ text }, at) => {
+        io.say(`  ${at + 1}. ${text}`);
+    });
+    const [chosen = current] = await choose(io, `Number (${current}): `, PERMISSION_CHOICES.length, [current]);
+    return PERMISSION_CHOICES[chosen - 1].answer;
+};
+/** A section another tool wrote wrongly is asked again and written over, rather than stopping the command. */
+const answersAt = (path) => {
+    try {
+        return readSetupAnswers(path);
+    }
+    catch {
+        return {};
+    }
+};
+/**
+ * The questions every WireCat tool shares, asked once for all of them: the answers go to the shared config
+ * file, the languages to the store. Only this, at a terminal, writes the permission answer.
+ */
+export const askSetupQuestions = async (run) => {
+    const path = sharedConfigPath(storePath(run.env), run.env);
+    const answers = answersAt(path);
+    const asking = run.all ? [...QUESTIONS] : unanswered(answers);
+    for (const question of asking) {
+        run.io.say("");
+        if (question === "languages") {
+            await askLanguages(run);
+            writeSetupAnswers(path, { languages: true });
+        }
+        else if (question === "tools") {
+            await askTools(run);
+            writeSetupAnswers(path, { tools: true });
+        }
+        else
+            writeSetupAnswers(path, { permissions: await askPermissions(run, answers) });
+    }
+    return asking;
+};
+/**
+ * The first-run step a tool runs before each command: asks when `asksAtStart` says so, and lets the command run
+ * whatever happens to the questions. `setup` asks all three again, since a refusal sends the owner there.
+ * A tool that builds its own program (zm, memo, drive) calls this with its command path.
+ */
+export const setupAtStart = async (start) => {
+    const input = start.input ?? process.stdin;
+    const terminal = start.terminal ?? (input.isTTY === true && process.stderr.isTTY === true);
+    if (!asksAtStart({ ...start, terminal, readOnlyLock: start.readOnlyLock }))
+        return;
+    await askSetupQuestions({
+        command: start.command,
+        env: start.env,
+        all: start.path[0] === "setup",
+        io: {
+            ask: (prompt) => readSecret(prompt, { input, echo: true }),
+            say: (text) => process.stderr.write(`${text}\n`),
+        },
+    }).catch((error) => {
+        process.stderr.write(`setup questions skipped: ${error instanceof Error ? error.message : String(error)} — \`${start.command} setup\` asks them again\n`);
+    });
+};

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

@@ -17,6 +17,8 @@ export interface FirstScreen {
 }
 interface Tool {
     command: string;
+    /** The npm package `setup` installs it from. */
+    package: string;
     shown?: string;
     does: string;
 }

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

@@ -7,12 +7,37 @@ import { commandAt } from "../steps.js";
 import { EXAMPLE_PROFILE, 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" },
-    { 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" },
+    {
+        command: "tg",
+        package: "@wirecat/tg-cli",
+        does: "Telegram in the same local store: search, review and tasks offline",
+    },
+    {
+        command: "max",
+        package: "@wirecat/max-cli",
+        does: "MAX in the same local store: search, review and tasks offline",
+    },
+    {
+        command: "wa",
+        package: "@wirecat/whatsapp-cli",
+        does: "WhatsApp in the same local store: search, review and tasks offline",
+    },
+    {
+        command: "zm",
+        package: "@wirecat/zoom-cli",
+        does: "Zoom meetings: transcripts and summaries, searchable with your messages",
+    },
+    {
+        command: "drive",
+        package: "@wirecat/drive-cli",
+        does: "Google Drive and Docs as local text, searchable with your messages",
+    },
+    {
+        command: "memo",
+        package: "@wirecat/cli-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);

package/dist/cli/index.d.ts

@@ -56,6 +56,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, changesAuthorityAt, 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 { askSetupQuestions, asksAtStart, type FirstRun, type FirstRunIo, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
@@ -128,6 +129,7 @@ export { createProgram, type ProgramDefinition, type ProgramOptions, type RunOpt
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { type Config, type Configuration, count, first, flag, fromFile, type GlobalFlags, NONE_NAMED, type ProfileKind, plain, type ResolveOptions, type Settings, type SettingsExtension, type SettingsExtensionContext, type Source, settingsFor, } from "./settings.js";
+export { type PermissionAnswer, readSetupAnswers, type SetupAnswers } from "./setup-answers.js";
 export { AGENTS, type Agent, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";

package/dist/cli/index.js

@@ -51,6 +51,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, changesAuthorityAt, 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 { askSetupQuestions, asksAtStart, LANGUAGES, setupAtStart, systemLanguage, } from "./first-run.js";
 export { checkGuide, checkStep, guideCommand, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
@@ -123,6 +124,7 @@ export { createProgram, run } from "./program.js";
 export { fieldsOf, projectFields } from "./result-fields.js";
 export { runsCommand } from "./runs/command.js";
 export { count, first, flag, fromFile, NONE_NAMED, plain, settingsFor, } from "./settings.js";
+export { readSetupAnswers } from "./setup-answers.js";
 export { AGENTS, agentFor, screenFor } from "./setup-screen.js";
 export { skillCommand } from "./skill-command.js";
 export { runnable, withSafety } from "./steps.js";

package/dist/cli/messenger/context.js

@@ -1,9 +1,9 @@
 import { CliError } from "@wirecat/cli-base";
 import { servingProfiles } from "../../background/lock.js";
 import { FloodMemory, floodPathFor } from "../../sends/flood.js";
-import { guardFor } from "../../sends/guard.js";
+import { ceilingRefusal, guardFor } from "../../sends/guard.js";
 import { DEFAULT_PACE, Pacer, pacePathFor } from "../../sends/pace.js";
-import { assertStatsPermissionsCurrent, levelFor, readKeysForCommand, } from "../../sends/permissions.js";
+import { assertStatsPermissionsCurrent, CEILING_KEY, levelFor, readKeysForCommand, } from "../../sends/permissions.js";
 import { RecipientList, recipientsPathFor } from "../../sends/recipients.js";
 import { OFFLINE, servicesFor } from "../../services/index.js";
 import { openStore } from "../../store/store.js";
@@ -338,6 +338,8 @@ export const refuseLocalWrite = (context, command, permission) => {
     const { level, key } = levelFor(settings.permissions, permission);
     if (level === "allow" || (level === "ask" && context.agent))
         return;
+    if (key === CEILING_KEY)
+        throw ceilingRefusal(permission, command);
     throw new CliError(level === "ask" ? "confirmation_required" : "permission_error", `profile ${settings.profile} does not let ${permission} write (permissions.${key} is ${level}, from the ` +
         `${settings.permissionSources[key ?? ""] ?? "default"}); to allow it: ` +
         `${command} ${settings.profile} config set permissions.${permission} allow`, { permission });

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

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import type { CacheDatabase } from "../../store/driver.js";
 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<{
@@ -19,3 +20,12 @@ export declare const storeSummary: (env: NodeJS.ProcessEnv) => Promise<{
     error: string;
 }>;
 export declare const storeMaintenanceCommands: (messenger: Messenger) => Command[];
+/**
+ * Stems what is left, after rebuilding stems made by other stemmer choices than the store's setting —
+ * only here and in `store reindex`, never in a search's quick fill.
+ */
+export declare const buildStems: (database: CacheDatabase, note: (text: string) => void, { force }?: {
+    force?: boolean | undefined;
+}) => {
+    stemmed: number;
+};

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

@@ -409,7 +409,7 @@ const buildWordIndex = (database, note) => {
  * Stems what is left, after rebuilding stems made by other stemmer choices than the store's setting —
  * only here and in `store reindex`, never in a search's quick fill.
  */
-const buildStems = (database, note, { force = false } = {}) => {
+export const buildStems = (database, note, { force = false } = {}) => {
     const before = stemsState(database);
     if (!before)
         return { stemmed: 0 };

package/dist/cli/permission-keys.js

@@ -1,4 +1,4 @@
-import { keyForCommand, WRITE_KEYS } from "../sends/permissions.js";
+import { CEILING_KEY, keyForCommand, WRITE_KEYS } from "../sends/permissions.js";
 const pathOf = (command) => {
     const words = [];
     for (let at = command; at?.parent; at = at.parent)
@@ -39,4 +39,4 @@ export const knownBeside = (key, known) => {
         .filter((one) => one.split(".").length === depth && (parent === "" || one.startsWith(`${parent}.`)))
         .sort();
 };
-export const unknownPermissionKeys = (levels, known) => Object.keys(levels).filter((key) => !known.has(key));
+export const unknownPermissionKeys = (levels, known) => Object.keys(levels).filter((key) => key !== CEILING_KEY && !known.has(key));

package/dist/cli/program.js

@@ -11,7 +11,7 @@ import { failureContext } from "../errors/reasons.js";
 import { envName, readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { recorded, wasSettled } from "../runs/recording.js";
 import { processRun, useAsProcessRun } from "../runs/scope.js";
-import { AUTHORITY_KEY, keyForCommand } from "../sends/permissions.js";
+import { AUTHORITY_KEY, BOT_API_KEY, isBotApi, keyForCommand } from "../sends/permissions.js";
 import { logParsedArgv, logVersion } from "./argv-log.js";
 import { commandPathOf } from "./command-contract.js";
 import { outputFor, provide } from "./context.js";
@@ -19,6 +19,7 @@ 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 { setupAtStart } from "./first-run.js";
 import { installHelp } from "./help/first-screen.js";
 import { showInputFields } from "./input-fields.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
@@ -237,6 +238,16 @@ const runOnce = async (argv, definition, options) => {
             action.setOptionValue("dryRun", true);
         const path = commandPathOf(action);
         const lock = readOnlyLockOf(definition.app, commandEnv);
+        const input = options.stdin ?? process.stdin;
+        await setupAtStart({
+            command,
+            env: commandEnv,
+            path,
+            headless,
+            readOnlyLock: lock,
+            input,
+            terminal: !options.streams && input.isTTY === true && process.stderr.isTTY === true,
+        });
         if (lock && isLogin(action) && !flags.dryRun)
             throw readOnlyRefusal(lock, "log in or out");
         if (lock && isStoreChange(action) && !flags.dryRun)
@@ -258,6 +269,10 @@ const runOnce = async (argv, definition, options) => {
             throw new CliError("permission_error", `\`${command} ${path.join(" ")}\` changes what a later run may do, and this profile keeps that from agents ` +
                 `(${AUTHORITY_KEY}) — the owner turns it on in a terminal: ` +
                 `\`${command} <profile> config set${path[0] === "bot" ? " --bot" : ""} permissions.${AUTHORITY_KEY} allow\``, { permission: AUTHORITY_KEY, sent: false });
+        if (options.agent && options.agent.botApi !== true && isBotApi(path))
+            throw new CliError("permission_error", `\`${command} ${path.join(" ")}\` calls the Bot API directly, past the send guard and the recipient list, ` +
+                `and this profile keeps that from agents (${BOT_API_KEY}) — the owner turns it on in a terminal: ` +
+                `\`${command} <profile> config set --bot permissions.${BOT_API_KEY} allow\``, { permission: BOT_API_KEY, sent: false });
         const { lifetime, cooperative: stopsAtItsPace } = metaOf(action);
         const persistent = lifetime === "persistent";
         listens = persistent;

package/dist/cli/settings.js

@@ -4,15 +4,28 @@ import * as v from "valibot";
 import { AI_ENTRIES, resolveAISettings } from "../analysis/settings.js";
 import { parseDuration } from "../domain/duration.js";
 import { envName, readOnlyLockOf } from "../ports/app.js";
-import { assertOverridesTighten, LEVELS, layerPermissions, permissionOverrides, RESOURCES, } from "../sends/permissions.js";
+import { assertOverridesTighten, CEILING_KEY, LEVELS, layerPermissions, permissionOverrides, RESOURCES, } from "../sends/permissions.js";
+import { storePath } from "../store/path.js";
+import { sharedConfigPath } from "../store/shared-config.js";
 import { loadSnakeCaseConfig } from "./config-keys.js";
 import { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 import { profilesHere } from "./messenger/accounts.js";
 import { usableProfileName } from "./profile.js";
+import { permissionCeiling } from "./setup-answers.js";
 const DEFAULT_LIMIT = DEFAULT_CONFIG.defaults.limit;
 const DEFAULT_KEEP_RUNS_FOR_DAYS = DEFAULT_CONFIG.defaults.keep_runs_for_days;
 /** On by default: a limit that is off protects nobody from a loop. */
 const DEFAULT_SENDS_PER_HOUR = DEFAULT_CONFIG.defaults.sends_per_hour;
+/** The first-run answer caps every profile; a config file cannot name its key, so only `setup` writes it. */
+const withCeiling = (permissions, env) => {
+    const ceiling = permissionCeiling(sharedConfigPath(storePath(env), env));
+    return ceiling
+        ? {
+            levels: { ...permissions.levels, [CEILING_KEY]: ceiling },
+            sources: { ...permissions.sources, [CEILING_KEY]: "setup answer" },
+        }
+        : permissions;
+};
 export const plain = (rule) => (issue) => `${rule}, not ${issue.received}`;
 const wholeNumber = plain("has to be a whole number, 1 or more");
 export const count = v.pipe(v.number(wholeNumber), v.integer(wholeNumber), v.minValue(1, wholeNumber));
@@ -221,7 +234,7 @@ export const settingsFor = (app, extension = {}) => {
         ]);
         const overrides = permissionOverrides(flags.permission);
         assertOverridesTighten(overrides, layerPermissions(fileLayers).levels);
-        const permissions = layerPermissions([["flag", overrides], ...fileLayers]);
+        const permissions = withCeiling(layerPermissions([["flag", overrides], ...fileLayers]), env);
         const updateCheck = first([
             [
                 extension.sourcePaths ? "config file: defaults" : "config defaults",