@wirecat/cli-core 0.421.0 → 0.423.0

package/CHANGELOG.md

@@ -5,7 +5,35 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.423.0 — 25.10.2026
+
+### Added
+
+- **`doctor --json` lists every problem in the config file as `config.issues`.** Each issue is `{ kind, file, profile?, key?, line?, column?, what, fix? }`, with `kind` one of `invalid_json`, `unknown_setting`, `unknown_permission`, `missing_setting` or `invalid_value`. `what` is one sentence that says what a value has to be and never quotes the saved value. `fix` is a `config unset` command that runs exactly as written, and is left out for invalid JSON (`line` and `column` say where parsing stopped). Doctor checks every section of the file (`defaults`, each profile, and the `personal` and `bot` sections) and every profile in it, and lists all the problems. A permission key that a nearer section hides is reported too. Doctor still exits 0, with no top-level `error`, when it finds problems; with no profile named it answers too, with `profile: null`. The shared schema marks no setting as required, so `missing_setting` appears only with an app's own schema.
+- **`config show`, `config set` and `config unset` run on a file with problems.** `show` lists each problem with its fix. `set` is refused only when the change would add a problem or leave the setting it writes invalid. `unset` removes the setting it names even when no schema knows it. With no profile typed, `config unset <key>` removes a top-level key that has a problem (`tg config unset default_profile`). Every command other than `config` and `doctor` still refuses a file with problems. The refusal now names the first problem, how to remove it, and how many more `doctor` lists.
+
+### Changed — may break callers
+
+- **`doctor`'s `config.error` is replaced by `config.issues`.** A caller that read the string reads the list. When a profile lock, a flag or an environment variable stops the settings, the message is in `settings.error`.
+- **Old setting names and old option spellings are no longer recognised.** `default_profile` and `catch_up_marks_read` are unknown settings like any other: the file is refused with `<file>: setting default_profile is not a setting of <tool> — remove it with \`<tool> config unset default_profile\``, and nothing points to the profile word or to `chats mark-read`. `config set|unset` no longer list `default_profile`. A camelCase key gets no "rename it to" hint from `loadSnakeCaseConfig`. The dead code behind the old `--provider`, `--kind` and `--file` spellings and the old `--provider` of `conversations consents remove` is gone. `AnalysisOptions.provider` and `ModelOptions.provider` are removed; pass `analysisProvider` and `embeddingProvider`.
+- **`analysis_provider`, `analysis_model` and `analysis_base_url` are no longer read**, nor their `<PREFIX>_ANALYSIS_*` environment variables. A file that still has one is refused like any unknown setting, and `doctor` reports it with its `config unset`. Use `models.analysis.provider`, `models.analysis.model` and `models.analysis.base_url` (`<PREFIX>_MODELS_ANALYSIS_*`); the old `analysis_provider: agent` is `models.analysis.provider: off`, or the provider left unset. `AISettings` loses `analysisProvider`, `analysisModel` and `analysisBaseUrl`, `AI_DEFAULTS` loses `analysisProvider`, `resolveModelSettings` drops its fourth argument, and `modelTarget` reads `models` only.
+- **An unknown permission key in any section of the file is refused**, not only one in the sections a command reads. The refusal names the file and the exact `config unset` (with `--defaults`, `--personal` or `--bot` as the section needs). A `--permission` key that names no command is refused as a `validation_error`.
+- **`changeSetting` works on the file as written.** An unset that empties a section also removes that section. `Settings` gains the optional `configIssues` and `savedPermissions` (an app that builds `Settings` itself can leave them out; its keys in force are then checked), and `ResolveOptions` gains `withIssues`. `preview` takes the resolved settings and the tool's command, not a permission map and an unset prefix. `refuseUnknownPermissionKeys` takes the settings and the tool's command.
+
+### Fixed
+
+- **`--source obsidian:<id>` and `local:<id>` name one notes folder** (store version 32 gave folders these providers, and the list reader found no account under them). The id is the folder's id its hits show, its stored ulid or its name; `obsidian:` finds vaults only and `local:` plain folders only, so a folder of the other provider is "no obsidian account". The entry still lists as `notes:<id>`. `folder:<id>` stays refused in `--source`, as before.
+
+## 0.422.0 — 25.10.2026
+
+### Added
+
+- **`AppIdentity.messenger`: set it to `false` in a CLI that is not a messenger** (a notes, files or calendar CLI from cli-template). The shared program, `commands`, `config` and MCP text then stop speaking of chats and messages: the profile example in the program description names the CLI's own first command, `commands info`'s example is `<cmd> commands info commands`, `--brief` and `--full` describe "found items", `--trace` and `--record` say "never content", and `config show` and the `config set`/`unset` list leave out `sender_colors`. Unset means a messenger: tg, max and wa print exactly what they did. A CLI that sets it refreshes its contract snapshots once.
+- **The MCP `_tools_search`, `_read` and `_write` tools speak neutrally when the catalogue has no `messages` commands**: task words "list", "show", "change a setting", one of the CLI's own reading commands as the example, and "creates, edits, deletes" for writes. No setting is needed; a messenger's catalogue is unchanged.
+
+### Changed — may break callers
+
+- **The languages search stems are one table, `LANGUAGES`, and each entry now names its Hunspell dictionary** (`dictionary: "dictionary-ru"`). `LANGUAGES` from `/cli` keeps its other fields. `LATIN_STEMMERS` is now `english, spanish, none`, in the order the error for an unknown stemmer already printed, so the `allowed` list of a `stemmer.invalid` error comes in that order too. A caller that compared that list in order sorts it first.
 
 ## 0.421.0 — 25.10.2026
 

package/dist/analysis/settings.d.ts

@@ -5,9 +5,6 @@ declare const AI_FIELDS: {
     embeddingModel: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
     embeddingBaseUrl: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "use an HTTP/S endpoint without credentials, query or fragment">]>, undefined>;
     embeddingDims: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 65536, undefined>]>, undefined>;
-    analysisProvider: v.OptionalSchema<v.PicklistSchema<["agent", "openai", "anthropic"], undefined>, undefined>;
-    analysisModel: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
-    analysisBaseUrl: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "use an HTTP/S endpoint without credentials, query or fragment">]>, undefined>;
     models: v.OptionalSchema<v.RecordSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, v.StrictObjectSchema<{
         readonly provider: v.OptionalSchema<v.PicklistSchema<["off", "openai", "anthropic"], undefined>, undefined>;
         readonly model: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 200, undefined>]>, undefined>;
@@ -20,9 +17,6 @@ export declare const AI_ENTRIES: {
     embedding_model: (typeof AI_FIELDS)["embeddingModel"];
     embedding_base_url: (typeof AI_FIELDS)["embeddingBaseUrl"];
     embedding_dims: (typeof AI_FIELDS)["embeddingDims"];
-    analysis_provider: (typeof AI_FIELDS)["analysisProvider"];
-    analysis_model: (typeof AI_FIELDS)["analysisModel"];
-    analysis_base_url: (typeof AI_FIELDS)["analysisBaseUrl"];
     models: (typeof AI_FIELDS)["models"];
 };
 export type AISettings = v.InferOutput<v.ObjectSchema<typeof AI_FIELDS, undefined>>;

package/dist/analysis/settings.js

@@ -10,15 +10,12 @@ const AI_FIELDS = {
     embeddingModel: v.optional(model),
     embeddingBaseUrl: v.optional(url),
     embeddingDims: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1), v.maxValue(65536))),
-    analysisProvider: v.optional(v.picklist(["agent", "openai", "anthropic"])),
-    analysisModel: v.optional(model),
-    analysisBaseUrl: v.optional(url),
     models: v.optional(modelSettingsShape),
 };
 const fileKey = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 /** The AI settings as the config file names them, in snake_case; `AISettings` is what the code reads. */
 export const AI_ENTRIES = Object.fromEntries(Object.entries(AI_FIELDS).map(([key, schema]) => [fileKey(key), schema]));
-export const AI_DEFAULTS = { embeddingProvider: "local", analysisProvider: "agent" };
+export const AI_DEFAULTS = { embeddingProvider: "local" };
 export const AI_SETTING_KEYS = Object.keys(AI_FIELDS);
 export const resolveAISettings = (prefix, layers, env) => {
     const resolved = Object.entries(AI_FIELDS)
@@ -41,7 +38,7 @@ export const resolveAISettings = (prefix, layers, env) => {
     });
     const values = Object.fromEntries(resolved.map(({ key, value }) => [key, value]));
     const sources = Object.fromEntries(resolved.map(({ key, from }) => [key, from]));
-    const models = resolveModelSettings(prefix, layers, env, { values, sources });
+    const models = resolveModelSettings(prefix, layers, env);
     return {
         values: { ...values, models: models.models },
         sources: {

package/dist/cli/analysis-choice.d.ts

@@ -4,7 +4,6 @@ import type { AppIdentity } from "../ports/app.js";
 import type { Settings } from "./settings.js";
 export interface AnalysisOptions {
     analysisProvider?: string;
-    provider?: string;
     model?: string;
     baseUrl?: string;
 }

package/dist/cli/analysis-choice.js

@@ -2,33 +2,20 @@ import { CliError } from "@wirecat/cli-base";
 import { endpoint } from "../analysis/settings.js";
 import { embeddingKeys, endpointKeyName } from "../embeddings/keys.js";
 export const analysisChoice = (options, app, settings, env, keyring) => {
-    if (options.analysisProvider !== undefined && options.provider !== undefined)
-        throw new CliError("validation_error", "give --analysis-provider or its legacy --provider spelling, not both");
-    options = { ...options, provider: options.analysisProvider ?? options.provider };
     const configured = { ...settings.models?.default, ...settings.models?.analysis };
-    settings = {
-        ...settings,
-        analysisProvider: configured.provider === "off" ? "agent" : (configured.provider ?? settings.analysisProvider),
-        analysisModel: configured.model ?? settings.analysisModel,
-        analysisBaseUrl: configured.base_url ?? settings.analysisBaseUrl,
-    };
-    const override = (options.provider !== undefined && options.provider !== (settings.analysisProvider ?? "agent")) ||
-        (options.baseUrl !== undefined &&
-            options.baseUrl.replace(/\/+$/, "") !== settings.analysisBaseUrl?.replace(/\/+$/, ""));
-    const provider = options.provider ??
-        (settings.analysisProvider && settings.analysisProvider !== "agent"
-            ? settings.analysisProvider
-            : options.baseUrl
-                ? "openai"
-                : "agent");
+    // `off` and no provider both leave the linking to the agent.
+    const saved = configured.provider === undefined || configured.provider === "off" ? "agent" : configured.provider;
+    const override = (options.analysisProvider !== undefined && options.analysisProvider !== saved) ||
+        (options.baseUrl !== undefined && options.baseUrl.replace(/\/+$/, "") !== configured.base_url?.replace(/\/+$/, ""));
+    const provider = options.analysisProvider ?? (saved !== "agent" ? saved : options.baseUrl ? "openai" : "agent");
     if (provider === "agent")
-        throw new CliError("validation_error", "analysis_provider is agent; use your linking skill, or configure openai/anthropic to use --analyze");
+        throw new CliError("validation_error", "models.analysis.provider is off or not set, so the agent links the chat: use your linking skill, or set it to openai or anthropic to use --analyze");
     if (provider !== "openai" && provider !== "anthropic")
         throw new CliError("validation_error", "analysis provider must be agent, openai or anthropic");
-    const model = options.model ?? (override ? undefined : settings.analysisModel);
+    const model = options.model ?? (override ? undefined : configured.model);
     if (!model?.trim())
-        throw new CliError("validation_error", "set analysis_model or give --model before --analyze");
-    const customUrl = options.baseUrl ?? (override ? undefined : settings.analysisBaseUrl);
+        throw new CliError("validation_error", "set models.analysis.model or give --model before --analyze");
+    const customUrl = options.baseUrl ?? (override ? undefined : configured.base_url);
     const baseUrl = customUrl ?? (provider === "anthropic" ? "https://api.anthropic.com" : "https://api.openai.com/v1");
     if (!endpoint(baseUrl))
         throw new CliError("validation_error", "use an HTTP/S analysis endpoint without credentials, query or fragment");

package/dist/cli/bot/context.js

@@ -17,7 +17,7 @@ import { BotTokenStore } from "./token.js";
 export const botWords = (bot, profile) => `${bot.app.command} ${asFirstWord(profile)}bot`;
 /** What a messenger command refuses before it connects, for a bot: an unknown key, then a denied read. */
 const refuseBotPermissions = (command, bot, settings) => {
-    refuseUnknownPermissionKeys(command, settings.permissions, `${bot.app.command} ${asFirstWord(settings.profile)}config unset --bot`);
+    refuseUnknownPermissionKeys(command, settings, bot.app.command);
     for (const key of readKeysForCommand(commandPathOf(command))) {
         const { level, key: named } = levelFor(settings.permissions, key);
         if (level !== "deny")

package/dist/cli/commands-command.js

@@ -59,7 +59,7 @@ export const commandsCommand = (app) => {
     });
     command.addCommand(annotate(new Command("info"), {
         effects: NO_EFFECTS,
-        examples: [`${app.command} commands info messages list`],
+        examples: [`${app.command} commands info ${app.messenger === false ? "commands" : "messages list"}`],
     })
         .description(DISCOVERY_DESCRIPTIONS.info)
         .argument("[path...]", "one command path; without one, export schemas, error reasons and explicit overrides")

package/dist/cli/config-command.d.ts

@@ -2,10 +2,6 @@ import { Command } from "commander";
 import { type AppIdentity } from "../ports/app.js";
 import { type PermissionKeyOf } from "./permission-keys.js";
 import { type Configuration } from "./settings.js";
-/**
- * The settings in force and where each came from, and changing them. Printed whole: no field the
- * configuration accepts can hold a secret — the schema has nowhere to put one.
- */
 export declare const configCommand: (app: AppIdentity, config: Configuration, { permissionKey }?: {
     permissionKey?: PermissionKeyOf;
 }) => Command;

package/dist/cli/config-command.js

@@ -3,11 +3,10 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { envName } from "../ports/app.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";
 import { itemOf, renderAnswer } from "./envelope.js";
-import { knownBeside, knownPermissionKeys } from "./permission-keys.js";
+import { knownBeside, knownPermissionKeys, unknownPermissionIssues } from "./permission-keys.js";
 import { fromFile, NONE_NAMED } from "./settings.js";
 import { nextStep } from "./steps.js";
 import { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } from "./store-settings.js";
@@ -15,6 +14,8 @@ import { changeStoreSetting, isStoreSetting, STORE_SETTINGS, storeSettings } fro
  * The settings in force and where each came from, and changing them. Printed whole: no field the
  * configuration accepts can hold a secret — the schema has nowhere to put one.
  */
+/** `sender_colors` colours who wrote a message; a CLI without messages has nothing to colour. */
+const shownSettings = (app, config) => app.messenger === false ? config.allSettings.filter((setting) => setting !== "sender_colors") : config.allSettings;
 export const configCommand = (app, config, { permissionKey } = {}) => {
     const command = new Command("config").description("the settings in force, and where each one came from");
     annotate(command.command("show"), { effects: LOCAL_READ, examples: [`${app.command} personal config show`] })
@@ -22,7 +23,12 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
         .option("--bot", "the settings a bot command on this profile gets, rather than the personal account's")
         .action(async function () {
         const bot = this.opts().bot === true;
-        const context = baseContext(this, (flags, options) => config.resolveSettings(flags, { ...options, needsProfile: false, ...(bot ? { kind: "bot" } : {}) }));
+        const context = baseContext(this, (flags, options) => config.resolveSettings(flags, {
+            ...options,
+            needsProfile: false,
+            withIssues: true,
+            ...(bot ? { kind: "bot" } : {}),
+        }));
         const { settings, renderer, env } = context;
         const overridden = pathsAreOverridden({ appName: app.appName, prefix: app.envPrefix, env });
         renderAnswer(this, context, itemOf({
@@ -32,11 +38,16 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
             config_file: settings.configPath,
             config_found: settings.configFound,
             paths_overridden: overridden,
-            settings: [...config.allSettings, "command_timeout_ms"]
+            settings: [...shownSettings(app, config), "command_timeout_ms"]
                 .filter((setting) => bot || setting !== "read_other_bots")
-                .map((setting) => sourced(settings, setting, config.schema)),
+                .map((setting) => sourced(settings, setting)),
             store_settings: await storeSettings(env),
         }));
+        for (const issue of [
+            ...(settings.configIssues ?? []),
+            ...unknownPermissionIssues(this, settings, app.command, permissionKey),
+        ])
+            renderer.warn(`${issue.what}, so it is left out${issue.fix ? ` — \`${issue.fix}\` removes it` : ""}`);
         if (overridden) {
             renderer.note(`${envName(app, "CONFIG_DIR")}, ${envName(app, "STATE_DIR")} or ${envName(app, "CACHE_DIR")} is set — ` +
                 "a profile's keyring entry is not the usual one, so a session made without them reads as none");
@@ -47,9 +58,7 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
             effects: LOCAL_WRITE,
             examples: [`${app.command} personal config ${action} limit${action === "set" ? " 20" : ""}`],
         }))
-            .argument("<setting>", 
-        // default_profile is only removed now: `config unset` still takes it, `config set` refuses it.
-        `one of: ${[...config.allSettings.filter((one) => action === "unset" || one !== "default_profile"), ...STORE_SETTINGS, "account_groups.<name>"].join(", ")}`)
+            .argument("<setting>", `one of: ${[...shownSettings(app, config), ...STORE_SETTINGS, "account_groups.<name>"].join(", ")}`)
             .option("--defaults", "change what every profile gets, rather than this profile")
             .option("--personal", "only for personal accounts — the personal section of the file")
             .option("--bot", "only for bots — the bot section of the file");
@@ -61,10 +70,7 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
             sub.description("remove a setting from the configuration file");
         sub.action(async function (setting, given) {
             const { defaults: everyone, personal, bot, } = this.opts();
-            const context = baseContext(this, (flags, options) => config.resolveSettings(flags, {
-                ...options,
-                needsProfile: !everyone && setting !== "default_profile" && !isStoreSetting(setting),
-            }));
+            const context = baseContext(this, (flags, options) => config.resolveSettings(flags, { ...options, needsProfile: false, withIssues: true }));
             const { settings, renderer, env } = context;
             if (isStoreSetting(setting)) {
                 if (everyone || personal || bot)
@@ -85,29 +91,38 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
                 return;
             }
             const defaults = everyone === true;
-            if (setting === "default_profile" && (defaults || personal || bot))
-                throw new CliError("validation_error", "default_profile is one for the whole file — drop --defaults, --personal and --bot");
+            // The unset `doctor` gives for a problem outside any profile: one with no profile typed reaches it, whatever
+            // profile the environment names.
+            const root = action === "unset" &&
+                !defaults &&
+                !personal &&
+                !bot &&
+                settings.sources.profile !== "first word" &&
+                (settings.configIssues ?? []).some((issue) => issue.fix === `${app.command} config unset ${setting}`);
+            if (!root && !defaults && settings.sources.profile === NONE_NAMED)
+                config.resolveSettings(this.optsWithGlobals(), { env, withIssues: true });
             if (personal && bot)
                 throw new CliError("validation_error", "--personal and --bot name different sections; use one");
             const kind = bot ? "bot" : personal ? "personal" : undefined;
             const lock = envName(app, "PROFILE_LOCK");
-            if ((defaults || setting === "default_profile") && env[lock]) {
-                // The defaults are every other profile's settings too, and default_profile picks one of them.
-                throw new CliError("permission_error", `this process is locked to profile ${settings.profile} (${lock}) — ${setting === "default_profile" ? setting : "--defaults"} changes other profiles`);
+            if ((defaults || root) && env[lock]) {
+                // The defaults are every other profile's settings too, and the top of the file is everyone's.
+                throw new CliError("permission_error", `this process is locked to profile ${settings.profile} (${lock}) — ${root ? setting : "--defaults"} changes other profiles`);
             }
             if (environmentOf(this).agent)
                 refuseGuardedKey(setting, action === "set" ? String(given) : undefined);
             if (action === "set")
                 refuseUnknownKey(this, setting, String(given), permissionKey);
             const saved = config.changeSetting(settings.configPath, {
-                profile: defaults || setting === "default_profile" ? undefined : settings.profile,
+                profile: defaults || root ? undefined : settings.profile,
                 setting,
                 value: action === "set" ? String(given) : undefined,
                 kind,
+                root,
             });
             renderAnswer(this, context, itemOf({
                 config_file: settings.configPath,
-                scope: setting === "default_profile" ? "default_profile" : scopeOf(kind, defaults ? undefined : settings.profile),
+                scope: root ? "file" : scopeOf(kind, defaults ? undefined : settings.profile),
                 setting,
                 value: saved,
             }));
@@ -170,11 +185,7 @@ const objectKeys = (value) => {
 };
 const scopeOf = (kind, profile) => [kind, profile === undefined ? "defaults" : `profiles.${profile}`].filter(Boolean).join(".");
 /** A shared setting from what was resolved; a messenger's own from the file, where it lives. */
-const sourced = (settings, setting, schema) => {
-    if (setting === "default_profile") {
-        const named = loadSnakeCaseConfig(settings.configPath, schema, () => ({ profiles: {} })).default_profile;
-        return { setting, value: named ?? null, from: named === undefined ? "default" : "config file" };
-    }
+const sourced = (settings, setting) => {
     if (setting === "models") {
         return {
             setting,
@@ -192,8 +203,7 @@ const sourced = (settings, setting, schema) => {
     const field = setting.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
     if (field in settings.sources) {
         const value = settings[field];
-        // No list is every action, and `null` would read as none.
-        return { setting, value: setting === "allow" ? (value ?? "all") : (value ?? null), from: settings.sources[field] };
+        return { setting, value: value ?? null, from: settings.sources[field] };
     }
     const { value, from } = fromFile(settings, setting, UNLISTED_DEFAULTS[setting] ?? null);
     return { setting, value, from };

package/dist/cli/config-issues.d.ts

@@ -0,0 +1,52 @@
+import * as v from "valibot";
+export type ConfigIssueKind = "invalid_json" | "unknown_setting" | "unknown_permission" | "missing_setting" | "invalid_value";
+/** One problem in a config file, as `doctor` reports it. `what` never quotes a value: a secret may be pasted anywhere. */
+export interface ConfigIssue {
+    kind: ConfigIssueKind;
+    file: string;
+    profile?: string;
+    key?: string;
+    line?: number;
+    column?: number;
+    what: string;
+    fix?: string;
+}
+/** An issue with the path in the file that `config unset` removes, which the loader drops too. */
+export interface LocatedIssue extends ConfigIssue {
+    at: string[];
+}
+/** An issue at `at`, cut to the setting `config unset` removes, with that command as its fix. */
+export declare const locate: (kind: ConfigIssueKind, at: readonly string[], context: {
+    file: string;
+    tool: string;
+}, what: (key: string) => string) => LocatedIssue;
+/** The file's JSON, or the one issue that says where it stopped parsing. */
+export declare const parseConfigText: (text: string, file: string) => {
+    raw: unknown;
+} | {
+    issue: LocatedIssue;
+};
+/** Every problem the schema finds, never only the first, each cut to the setting that holds it. */
+export declare const schemaIssues: (raw: unknown, schema: v.GenericSchema, context: {
+    file: string;
+    tool: string;
+}) => LocatedIssue[];
+/** Every saved permission key, in every section and profile of the file — not only the ones that win. */
+export declare const savedPermissionKeys: (raw: unknown) => {
+    key: string;
+    at: string[];
+}[];
+/** A saved key no command checks would do nothing (BUG-137): one issue per key, wherever it is saved. */
+export declare const permissionIssues: (saved: readonly {
+    key: string;
+    at: readonly string[];
+}[], known: ReadonlySet<string>, context: {
+    file: string;
+    tool: string;
+}) => LocatedIssue[];
+/** The file without the settings the issues name: what still loads, and what `config unset` would leave. */
+export declare const withoutIssues: (raw: unknown, issues: readonly LocatedIssue[]) => unknown;
+/** The public shape: where in the file is the loader's own business. */
+export declare const publicIssue: ({ at: _, ...issue }: LocatedIssue) => ConfigIssue;
+/** One line for a command that refuses to run on the file: the first problem, how to fix it, and how many more. */
+export declare const issueMessage: (issues: readonly ConfigIssue[]) => string;

package/dist/cli/config-issues.js

@@ -0,0 +1,187 @@
+import * as v from "valibot";
+const isNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const SECTIONS = ["personal", "bot"];
+const SHELL_SAFE = /^[A-Za-z0-9_.:@-]*$/;
+/** Where a path of the file sits: the profile and the flags `config unset` needs, and the setting under it. */
+const scopeOf = (at) => {
+    const [first, second, third] = at;
+    if (first === "profiles" && second !== undefined && at.length > 2)
+        return { profile: second, flags: "", rest: at.slice(2) };
+    if (first === "defaults" && at.length > 1)
+        return { flags: " --defaults", rest: at.slice(1) };
+    if (SECTIONS.includes(first)) {
+        if (second === "profiles" && third !== undefined && at.length > 3)
+            return { profile: third, flags: ` --${first}`, rest: at.slice(3) };
+        if (second === "defaults" && at.length > 2)
+            return { flags: ` --defaults --${first}`, rest: at.slice(2) };
+    }
+    return { flags: "", rest: [...at] };
+};
+/** The part of a scope's path `config unset` takes as one setting: a permission key, a model field, or the setting. */
+const settingPath = (rest) => {
+    if (rest[0] === "permissions" && rest.length > 1)
+        return rest.slice(0, 2);
+    if (rest[0] === "models" && rest.length > 1)
+        return rest.slice(0, 3);
+    return rest.slice(0, 1);
+};
+const settingOf = (path) => path[0] === "permissions" && path.length > 1 ? `permissions.${path[1]}` : path.join(".");
+/** An issue at `at`, cut to the setting `config unset` removes, with that command as its fix. */
+export const locate = (kind, at, context, what) => {
+    const { profile, flags, rest } = scopeOf(at);
+    const inScope = rest.length < at.length;
+    // Outside a section the path itself is the key: `profiles.work` with the wrong type is removed alone.
+    const setting = inScope ? settingPath(rest) : [...rest];
+    const key = inScope ? settingOf(setting) : setting.join(".");
+    const prefix = at.slice(0, at.length - rest.length);
+    return {
+        kind,
+        file: context.file,
+        ...(profile === undefined ? {} : { profile }),
+        key,
+        what: what(key),
+        // A fix runs exactly as written; a name a shell would split or expand gets none.
+        ...([key, profile ?? ""].every((word) => SHELL_SAFE.test(word))
+            ? { fix: `${context.tool}${profile === undefined ? "" : ` ${profile}`} config unset${flags} ${key}` }
+            : {}),
+        at: [...prefix, ...setting],
+    };
+};
+/** Node prints `(line 3 column 5)`, older runtimes only `position 41`, and Bun neither. */
+const placeOf = (message, text) => {
+    const said = /line (\d+) column (\d+)/.exec(message);
+    if (said)
+        return { line: Number(said[1]), column: Number(said[2]) };
+    const position = /position (\d+)/.exec(message);
+    if (!position)
+        return {};
+    const before = text.slice(0, Number(position[1])).split("\n");
+    return { line: before.length, column: (before.at(-1)?.length ?? 0) + 1 };
+};
+/** The file's JSON, or the one issue that says where it stopped parsing. */
+export const parseConfigText = (text, file) => {
+    try {
+        return { raw: JSON.parse(text) };
+    }
+    catch (error) {
+        const place = placeOf(error instanceof Error ? error.message : "", text);
+        const where = place.line === undefined ? "" : ` at line ${place.line}, column ${place.column}`;
+        return { issue: { kind: "invalid_json", file, ...place, what: `the file is not valid JSON${where}`, at: [] } };
+    }
+};
+const keyOfPath = (issue) => (issue.path ?? []).map((item) => String(item.key));
+/** A key the schema does not know: valibot says it expected nothing there. */
+const isUnknownKey = (issue) => issue.expected === "never";
+/** A `permissions` key refused by its pattern, rather than its level. */
+const isPermissionKey = (issue, at) => {
+    const last = issue.path?.at(-1);
+    return at.at(-2) === "permissions" && last !== undefined && "origin" in last && last.origin === "key";
+};
+const isMissing = (issue) => {
+    const last = issue.path?.at(-1);
+    return last !== undefined && "origin" in last && last.origin === "key" && issue.input === undefined;
+};
+/**
+ * What a value has to be, never what it was: the schema's own "has to be …" without its ", not <value>", else
+ * the type or choices valibot expected.
+ */
+const ruleOf = (issue) => {
+    const own = /^(has to be [\s\S]*?)(, not [\s\S]*)?$/.exec(issue.message);
+    if (own?.[1])
+        return own[1];
+    if (issue.type === "picklist")
+        return `has to be one of ${issue.expected}`;
+    // valibot's own messages start "Invalid" and quote the value; a schema's own words do not.
+    if (!issue.message.startsWith("Invalid "))
+        return `is refused: ${issue.message}`;
+    if (issue.kind === "schema")
+        return `has to be of type ${issue.expected}`;
+    return issue.expected === null ? "has a value it does not take" : `has to be ${issue.expected}`;
+};
+/** One pass of the schema: valibot names only the first unknown key of each object. */
+const onePass = (raw, schema, context) => {
+    const result = v.safeParse(schema, raw);
+    if (result.success)
+        return [];
+    return result.issues.map((issue) => {
+        const at = keyOfPath(issue);
+        const located = isPermissionKey(issue, at)
+            ? locate("unknown_permission", at, context, (key) => `${key} names no command`)
+            : isUnknownKey(issue)
+                ? locate("unknown_setting", at, context, (key) => `setting ${key} is not a setting of ${context.tool}`)
+                : isMissing(issue)
+                    ? locate("missing_setting", at, context, (key) => `setting ${key} is missing`)
+                    : locate("invalid_value", at, context, (key) => at.length === 0 ? "the file has to be an object, in braces" : `setting ${key} ${ruleOf(issue)}`);
+        if (located.kind === "missing_setting" || at.length === 0)
+            delete located.fix;
+        return located;
+    });
+};
+/** Every problem the schema finds, never only the first, each cut to the setting that holds it. */
+export const schemaIssues = (raw, schema, context) => {
+    const found = new Map();
+    for (;;) {
+        const fresh = onePass(withoutIssues(raw, [...found.values()]), schema, context).filter((issue) => !found.has(issue.at.join("\u0000")));
+        if (fresh.length === 0)
+            return [...found.values()];
+        for (const issue of fresh)
+            found.set(issue.at.join("\u0000"), issue);
+        // A missing setting cannot be removed, so another pass would find it again.
+        if (fresh.every((issue) => issue.kind === "missing_setting" || issue.at.length === 0))
+            return [...found.values()];
+    }
+};
+/** Every section of the file that may hold `permissions`, with its path. */
+const scopes = (raw) => {
+    if (!isNode(raw))
+        return [];
+    const out = [];
+    const add = (path, node) => {
+        if (isNode(node))
+            out.push([path, node]);
+    };
+    const addSection = (path, section) => {
+        if (!isNode(section))
+            return;
+        add([...path, "defaults"], section.defaults);
+        if (isNode(section.profiles))
+            for (const [name, scope] of Object.entries(section.profiles))
+                add([...path, "profiles", name], scope);
+    };
+    addSection([], raw);
+    for (const name of SECTIONS)
+        addSection([name], raw[name]);
+    return out;
+};
+/** Every saved permission key, in every section and profile of the file — not only the ones that win. */
+export const savedPermissionKeys = (raw) => scopes(raw).flatMap(([path, scope]) => isNode(scope.permissions)
+    ? Object.keys(scope.permissions).map((key) => ({ key, at: [...path, "permissions", key] }))
+    : []);
+/** A saved key no command checks would do nothing (BUG-137): one issue per key, wherever it is saved. */
+export const permissionIssues = (saved, known, context) => saved
+    .filter(({ key }) => !known.has(key))
+    .map(({ at }) => locate("unknown_permission", at, context, (key) => `${key} names no command`));
+/** The file without the settings the issues name: what still loads, and what `config unset` would leave. */
+export const withoutIssues = (raw, issues) => {
+    if (issues.some((issue) => issue.at.length === 0))
+        return {};
+    const copy = structuredClone(raw);
+    for (const { at } of issues) {
+        const parent = at.slice(0, -1).reduce((node, key) => (isNode(node) ? node[key] : undefined), copy);
+        if (isNode(parent))
+            delete parent[at.at(-1)];
+    }
+    return copy;
+};
+/** The public shape: where in the file is the loader's own business. */
+export const publicIssue = ({ at: _, ...issue }) => issue;
+/** One line for a command that refuses to run on the file: the first problem, how to fix it, and how many more. */
+export const issueMessage = (issues) => {
+    const [first] = issues;
+    if (!first)
+        return "";
+    const more = issues.length - 1;
+    return (`${first.file}: ${first.what}` +
+        (first.fix ? ` — remove it with \`${first.fix}\`` : "") +
+        (more === 0 ? "" : ` (and ${more} more problem${more === 1 ? "" : "s"} — \`doctor\` lists them all)`));
+};

package/dist/cli/config-keys.js

@@ -1,20 +1,6 @@
 import { readFileSync } from "node:fs";
 import { CliError } from "@wirecat/cli-base";
 import * as v from "valibot";
-const isNode = (value) => typeof value === "object" && value !== null;
-const unwrap = (schema) => {
-    let current = schema;
-    while (isNode(current) && "wrapped" in current)
-        current = current.wrapped;
-    return isNode(current) ? current : undefined;
-};
-const child = (schema, key) => {
-    const node = unwrap(schema);
-    if (isNode(node?.entries))
-        return node.entries[key];
-    return node?.type === "record" ? node.value : undefined;
-};
-const snakeCase = (key) => key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 const reasonOf = (issue) => {
     if (issue.expected === "never")
         return "is an unknown setting";
@@ -25,25 +11,15 @@ const reasonOf = (issue) => {
         return "has an invalid value";
     return "has the wrong type";
 };
-const renameHint = (issue, schema) => {
-    if (issue.expected !== "never" || !issue.path)
-        return "";
-    const keys = issue.path.map((item) => String(item.key));
-    const key = keys.pop() ?? "";
-    const known = unwrap(keys.reduce(child, schema))?.entries;
-    const snake = snakeCase(key);
-    return snake !== key && isNode(known) && snake in known ? `; rename it to ${snake}` : "";
-};
 /**
  * The first problem only, by key and a fixed reason: valibot's own messages quote the value they got, and a
  * config value can be a secret pasted into the wrong place.
  */
-const problemOf = (issues, schema) => {
-    // A file from an older version is missing every new key; the rename is what tells the reader how to fix it.
-    const issue = issues.find((candidate) => renameHint(candidate, schema)) ?? issues[0];
+const problemOf = (issues) => {
+    const [issue] = issues;
     const more = issues.length - 1;
     const count = more === 0 ? "" : ` (and ${more} more problem${more === 1 ? "" : "s"})`;
-    return `${v.getDotPath(issue) ?? "the whole file"} ${reasonOf(issue)}${renameHint(issue, schema)}${count}`;
+    return `${v.getDotPath(issue) ?? "the whole file"} ${reasonOf(issue)}${count}`;
 };
 /** Reads and checks a config file; a missing one is the fallback, a broken one an error naming its first problem. */
 export const loadSnakeCaseConfig = (path, schema, fallback) => {
@@ -63,6 +39,6 @@ export const loadSnakeCaseConfig = (path, schema, fallback) => {
     }
     const result = v.safeParse(schema, parsed);
     if (!result.success)
-        throw new CliError("configuration_error", `${path}: ${problemOf(result.issues, schema)}`);
+        throw new CliError("configuration_error", `${path}: ${problemOf(result.issues)}`);
     return result.output;
 };

package/dist/cli/embedding-choice.d.ts

@@ -5,13 +5,12 @@ import type { ModelChoice } from "../services/embeddings.js";
 export interface ModelOptions {
     embeddingProvider?: string;
     model?: string;
-    provider?: string;
     baseUrl?: string;
     dims?: number;
     concurrency?: number;
 }
 /** A local model id, or a remote model with its key from `models keys set`. */
-export declare const embeddingChoice: ({ model, provider, embeddingProvider, baseUrl, dims, concurrency }: ModelOptions, app: AppIdentity, settings: AISettings, env: NodeJS.ProcessEnv, { needKey, keyring }?: {
+export declare const embeddingChoice: ({ model, embeddingProvider, baseUrl, dims, concurrency }: ModelOptions, app: AppIdentity, settings: AISettings, env: NodeJS.ProcessEnv, { needKey, keyring }?: {
     needKey?: boolean;
     keyring?: KeyringStore | undefined;
 }) => ModelChoice;