@wirecat/cli-base 0.75.0 → 0.75.2

package/CHANGELOG.md

@@ -8,6 +8,50 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.75.2 — 03.11.2026
+
+### Added
+
+- **Rule WC-CMD-30: every setting is in the config file with its default, and `config show` lists them all**
+  ([WC-CMD-30](docs/standards/commands.md#wc-cmd-30--write-every-setting-into-the-config-file-with-its-default-and-list-them-all-in-config-show)).
+  A CLI declares each scalar setting with its default and a description through cli-core's `DeclaredSetting`. It
+  fills the missing ones whenever it writes the file anyway, and on `config migrate`. A plain read never rewrites the
+  file. The owner then finds and edits every setting in the file without the docs. memo follows it first; the
+  messenger CLIs and zm are listed as known gaps.
+
+### Fixed
+
+- **A test that reaches the real keyring now fails, even when it falls back to a file.** The shared test setup's
+  keyring stand-in threw, but `Credentials` in `auto` mode catches that, warns and saves to a file, so the test
+  passed with only a warning on the console. The stand-in now records the reach, and the setup fails the test after it
+  with the stack of the call. Pass `memoryKeyring()` to fix such a test. mail-cli's and drive-cli's suites pass
+  under it.
+- **One bad entry in `lint/overrides.json` no longer turns off all the others.** `cli-dev lint` and `cli-dev audit`
+  dropped the whole file when one entry did not fit its shape, so every violation the good entries covered came back
+  as new, and the cause was one line among them. Now the bad entry fails the run as `entry <n> (<rule>) does not apply
+  — <why>`, and the other entries still apply.
+- **The `wcat-bin-name` and `wcat-describe` warnings can be overridden.** An entry for them was refused as "no lint
+  rule" and the warning stayed. Now an override with its reason silences the warning, counts against the budget, and
+  fails as stale once the warning is gone. A CLI that keeps its short command name says why this way.
+- **`docs:check` refuses an entry under no `###` heading in the top changelog section.** It passed one, so a release
+  could ship notes with an entry outside the five headings
+  ([the changelog rule](docs/standards/docs.md#wc-doc-15--changelog-entries-go-under-five-fixed-headings-each-at-most-once-per-section)).
+  Older sections are not checked: they are frozen, and several CLIs have such entries in them.
+- **The handbook's lines about gcal match gcal again:** `store status` (not `status`), a calendar sync's 15-minute
+  terminal deadline, all-day events matched by local date, `mcp serve --profiles` built, gcal's own Node 22 job and
+  Windows/macOS runs, its fixed package list, its generated `api` among the generated-command exceptions, and its
+  `api` writes no longer listed as all `ask`.
+
+## 0.75.1 — 02.11.2026
+
+### Fixed
+
+- **A list's help and MCP `query` description no longer offer `word*` or ranges that none of its fields takes.**
+  `fieldsHelp`'s `Syntax:` line on a `backend: "sql"` list now lists the phrase, `word*` and `[a TO b] · > >= < <=`
+  forms only when one of its shown fields takes them, as a native list's line already did; `AND OR NOT` and `( )`
+  stay. A list of whole values only (enum, bool) said it took both, and refused them. `queryDescription` drops
+  `[a TO b], > <` the same way. A list whose fields take every form prints the same line as before.
+
 ## 0.75.0 — 02.11.2026
 
 ### Fixed

package/dist/dev/main.js

@@ -15,7 +15,7 @@ import { taggedSection } from "../release/fold.js";
 import { changelogProblems, docsProblems, JOURNAL_IDS, markdownFiles, packageVersion, structureProblems, versionScript, } from "../release/index.js";
 import { AUDIT_BLOCKS, defineParityGroups, PARITY_GROUPS, REQUIRED_ROOTS } from "../standards/audit.js";
 import { defineReasons } from "../standards/errors.js";
-import { baselineProblems, baselineSchema, LINT_RULES, OVERRIDE_BUDGET, OVERRIDE_RULE_REVIEW, overridesProblems, overridesSchema, rulesForReview, } from "../standards/lint.js";
+import { baselineProblems, baselineSchema, LINT_RULES, OVERRIDE_BUDGET, OVERRIDE_RULE_REVIEW, overrideSchema, overridesProblems, rulesForReview, } from "../standards/lint.js";
 import { issuesOf, RegistryError } from "../standards/registry.js";
 import { VOCABULARY } from "../standards/vocabulary.js";
 import { auditClis, scorecardTable, snakeKeys } from "./audit.js";
@@ -25,7 +25,7 @@ import { baselineOf, judge, lintCommands, RUN_LOG_COMMANDS, walk } from "./lint.
 import { nextVersion } from "./next-version.js";
 import { slowTests } from "./slow-tests.js";
 import { matrixPage, matrixRows, parseArgvLog } from "./test-matrix.js";
-import { binNameWarnings, describeWarnings } from "./wcat-lint.js";
+import { binNameWarnings, describeWarnings, WCAT_RULES } from "./wcat-lint.js";
 const USAGE = `usage: cli-dev <command> [options]
 
   slow-tests [report] [count]          the slowest tests and files (report: coverage/tests.json, count: 20)
@@ -314,6 +314,30 @@ const readBaseline = (dir, label, problems) => {
         }
     return baseline;
 };
+/**
+ * Each entry on its own: one bad entry is named and ignored, and the others still apply. Dropping the whole file hid
+ * the bad entry behind every violation the good ones had covered.
+ */
+const readOverrides = (path, label, today, problems) => {
+    if (!existsSync(path))
+        return [];
+    const raw = readJson(path);
+    if (!Array.isArray(raw)) {
+        problems.push(`${label}: a JSON array of overrides, so none of it applies`);
+        return [];
+    }
+    const overrides = raw.flatMap((entry, index) => {
+        const read = v.safeParse(overrideSchema, entry);
+        if (read.success)
+            return [read.output];
+        const rule = typeof entry === "object" && entry !== null && "rule" in entry ? ` (${String(entry.rule)})` : "";
+        problems.push(`${label}: entry ${index}${rule} does not apply — ${issuesOf(read.issues).join("; ")}`);
+        return [];
+    });
+    for (const issue of overridesProblems(overrides, today))
+        problems.push(`${label}: ${issue}`);
+    return overrides;
+};
 const lint = (args, io) => {
     try {
         return lintRun(args, io);
@@ -364,15 +388,9 @@ const lintRun = (args, io) => {
         return 2;
     }
     const problems = [];
-    const overridesPath = join(io.cwd, values.overrides);
-    let overrides = [];
-    if (existsSync(overridesPath)) {
-        const read = v.safeParse(overridesSchema, readJson(overridesPath));
-        const found = read.success ? overridesProblems(read.output, today(io)) : issuesOf(read.issues);
-        if (read.success)
-            overrides = read.output;
-        problems.push(...found.map((issue) => `${values.overrides}: ${issue}`));
-    }
+    const overrides = readOverrides(join(io.cwd, values.overrides), values.overrides, today(io), problems);
+    const isWcat = (entry) => WCAT_RULES.includes(entry.rule);
+    const ruleOverrides = overrides.filter((entry) => !isWcat(entry));
     const baselineDir = join(io.cwd, values.baseline);
     const baseline = readBaseline(baselineDir, values.baseline, problems);
     const schemas = values.schemas === undefined ? undefined : readJson(join(io.cwd, values.schemas));
@@ -390,7 +408,7 @@ const lintRun = (args, io) => {
     const severity = new Map(LINT_RULES.map((rule) => [rule.id, rule.severity]));
     if (values["write-baseline"]) {
         mkdirSync(baselineDir, { recursive: true });
-        for (const [rule, targets] of Object.entries(baselineOf(violations, overrides))) {
+        for (const [rule, targets] of Object.entries(baselineOf(violations, ruleOverrides))) {
             const path = join(baselineDir, `${rule}.json`);
             if (targets.length > 0)
                 writeFileSync(path, `${JSON.stringify(targets, null, 2)}\n`);
@@ -399,7 +417,7 @@ const lintRun = (args, io) => {
             baseline[rule] = targets;
         }
     }
-    const verdict = judge(violations, baseline, overrides, budget);
+    const verdict = judge(violations, baseline, ruleOverrides, budget);
     for (const id of verdict.unknownRules)
         problems.push(`no lint rule "${id}" (named in ${values.baseline} or ${values.overrides})`);
     for (const found of verdict.fresh)
@@ -408,11 +426,19 @@ const lintRun = (args, io) => {
         problems.push(entry.in === "baseline"
             ? `stale baseline entry, fixed or overridden — remove it: ${values.baseline}/${entry.rule}.json "${entry.target}"`
             : `stale override, no such violation — remove it: ${entry.rule} "${entry.target}"`);
-    if (verdict.overBudget)
+    const warnings = wcatWarnings(io.cwd, values.cli);
+    const warned = new Set(warnings.map((warning) => `${warning.rule} ${warning.target}`));
+    const wcatOverridden = new Set(overrides.filter(isWcat).map((entry) => `${entry.rule} ${entry.target}`));
+    // wcat-describe is checked only with --cli, so without it an override of it is neither used nor stale.
+    for (const entry of overrides.filter(isWcat))
+        if (!warned.has(`${entry.rule} ${entry.target}`) && (values.cli || entry.rule !== "wcat-describe"))
+            problems.push(`stale override, no such warning — remove it: ${entry.rule} "${entry.target}"`);
+    if (overrides.length > budget)
         problems.push(`${overrides.length} overrides; the budget is ${budget}`);
     io.err(`lint: ${violations.length} violations — ${verdict.baselined} in the baseline, ${verdict.overridden} overridden (budget ${budget}), ${verdict.fresh.length} new`);
-    for (const warning of wcatWarnings(io.cwd, values.cli))
-        io.err(`warning  ${warning.rule}  ${warning.target}: ${warning.message}`);
+    for (const warning of warnings)
+        if (!wcatOverridden.has(`${warning.rule} ${warning.target}`))
+            io.err(`warning  ${warning.rule}  ${warning.target}: ${warning.message}`);
     return report(io, problems, "lint: ok");
 };
 const wcatWarnings = (cwd, cli) => {
@@ -527,15 +553,7 @@ const auditRun = (args, io) => {
         }
         const dir = lintDirs.get(cli);
         if (dir) {
-            const overridesPath = join(at(dir), "overrides.json");
-            let overrides = [];
-            if (existsSync(overridesPath)) {
-                const read = v.safeParse(overridesSchema, readJson(overridesPath));
-                const found = read.success ? overridesProblems(read.output, today(io)) : issuesOf(read.issues);
-                if (read.success)
-                    overrides = read.output;
-                problems.push(...found.map((issue) => `${dir}/overrides.json: ${issue}`));
-            }
+            const overrides = readOverrides(join(at(dir), "overrides.json"), `${dir}/overrides.json`, today(io), problems);
             input.lint = {
                 baseline: readBaseline(join(at(dir), "baseline"), `${dir}/baseline`, problems),
                 overrides,

package/dist/dev/wcat-lint.d.ts

@@ -1,5 +1,7 @@
+/** Warnings, not lint rules: an entry in `lint/overrides.json` silences one, with its reason, like any override. */
+export declare const WCAT_RULES: readonly ["wcat-bin-name", "wcat-describe"];
 export interface WcatWarning {
-    rule: "wcat-bin-name" | "wcat-describe";
+    rule: (typeof WCAT_RULES)[number];
     target: string;
     message: string;
 }

package/dist/dev/wcat-lint.js

@@ -4,6 +4,8 @@
  */
 import { parseDescribe } from "../wcat/describe.js";
 import { DESCRIBE_FLAG, PROGRAM_PREFIX, RESERVED_NAMES, TOOL_NAME } from "../wcat/names.js";
+/** Warnings, not lint rules: an entry in `lint/overrides.json` silences one, with its reason, like any override. */
+export const WCAT_RULES = ["wcat-bin-name", "wcat-describe"];
 const WIRECAT_SCOPE = "@wirecat/";
 /** The commands a `package.json` installs: its `"bin"` keys, or the package's own name for a `"bin"` string. */
 const binNames = (pkg) => {

package/dist/query/help.js

@@ -2,18 +2,14 @@ export const QUERY_SYNTAX = 'field:value · "a phrase" · word* · AND OR NOT ·
 const shownOf = (registry) => registry.backend === "native" ? registry.fields.filter((field) => field.native) : registry.fields;
 const leftOut = (fields) => fields.filter((field) => field.negatable).map((field) => field.name);
 const has = (fields, operator) => fields.some((field) => field.operators.includes(operator));
-// A provider takes only field:value joined by AND, so a native list advertises no OR and no grouping.
-const syntaxOf = (shown, backend) => {
-    if (backend !== "native")
-        return QUERY_SYNTAX;
-    return [
-        "field:value",
-        ...(has(shown, "phrase") ? ['"a phrase"'] : []),
-        ...(has(shown, "wildcard") ? ["word*"] : []),
-        "terms joined by AND",
-        ...(has(shown, "range") ? ["[a TO b] · > >= < <="] : []),
-    ].join(" · ");
-};
+// Each form is offered only when a shown field takes it, and a provider takes no OR and no grouping.
+const syntaxOf = (shown, backend) => [
+    "field:value",
+    ...(has(shown, "phrase") ? ['"a phrase"'] : []),
+    ...(has(shown, "wildcard") ? ["word*"] : []),
+    ...(backend === "native" ? ["terms joined by AND"] : ["AND OR NOT", "( )"]),
+    ...(has(shown, "range") ? ["[a TO b] · > >= < <="] : []),
+].join(" · ");
 const kindOf = (field) => field.values ? `${field.type}: ${field.values.join("|")}` : `${field.type}: ${field.operators.join(", ")}`;
 /** The Fields section of a list's help: one line per field it filters by, its defaults, the syntax and the guide. */
 export const fieldsHelp = (registry, guide) => {
@@ -47,7 +43,7 @@ export const queryDescription = (registry) => {
         ? `field:value terms joined by AND that narrow the list${negatable.length > 0
             ? `; -field:value or NOT field:value leaves out what matches, for ${negatable.join(", ")} only`
             : ""}`
-        : "field:value terms that narrow the list (Lucene: AND OR NOT, -field:value, [a TO b], > <)";
+        : `field:value terms that narrow the list (Lucene: AND OR NOT, -field:value${has(shown, "range") ? ", [a TO b], > <" : ""})`;
     const fields = shown.map((field) => (field.values ? `${field.name} (${field.values.join("|")})` : field.name));
     const defaults = registry.defaults?.length ? `; unless named: ${registry.defaults.join(" ")}` : "";
     return `${terms}; fields: ${fields.join(", ")}; e.g. ${shown[0]?.example ?? ""}${defaults}`;

package/dist/release/markdown.js

@@ -27,6 +27,7 @@ export const changelogProblems = (text, { version, release, headings, unreleased
     let section;
     let subheadings = new Set();
     let first = true;
+    let top = false;
     let legacy = false;
     if (legacyHeadingsThrough !== undefined && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(legacyHeadingsThrough))
         problems.push(`legacyHeadingsThrough: "${legacyHeadingsThrough}" is not a version`);
@@ -35,6 +36,7 @@ export const changelogProblems = (text, { version, release, headings, unreleased
         if (line.startsWith("## ")) {
             section = line.slice(3);
             subheadings = new Set();
+            top = first;
             legacy = false;
             if (section === unreleased) {
                 if (release)
@@ -66,6 +68,9 @@ export const changelogProblems = (text, { version, release, headings, unreleased
                 problems.push(`${where}: "${heading}" twice in "${section}"`);
             subheadings.add(heading);
         }
+        // Only the top section: released ones are frozen, and older ones in several CLIs still have such entries.
+        if (top && !legacy && subheadings.size === 0 && /^[-*] /.test(line))
+            problems.push(`${where}: an entry under no "###" heading in "${section}" — put it under one of: ${headings.join(", ")}`);
         for (const found of line.match(id) ?? [])
             problems.push(`${where}: internal id ${found} — say what changed instead`);
     });

package/dist/standards/lint.d.ts

@@ -14,6 +14,15 @@ export declare const defineLintRules: (input: unknown) => LintRule[];
 export declare const LINT_RULES: LintRule[];
 /** `lint/baseline/<rule-id>.json`: today's violations of one rule, by target. It may only shrink. */
 export declare const baselineSchema: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+/** One `lint/overrides.json` entry: the exception, its reason, who keeps it and when to look again. */
+export declare const overrideSchema: v.StrictObjectSchema<{
+    readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a lower-case word, words joined by -">]>;
+    readonly target: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
+    readonly reason: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, v.MinLengthAction<string, 10, "say why, in a sentence">]>;
+    /** A GitHub handle or a team, `@octocat`. */
+    readonly owner: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a GitHub handle or team, such as @octocat">]>;
+    readonly review_after: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoDateAction<string, "a date, YYYY-MM-DD">]>;
+}, undefined>;
 /** `lint/overrides.json`: exceptions, each with its reason, who keeps it and when to look again; counted against a budget. */
 export declare const overridesSchema: v.ArraySchema<v.StrictObjectSchema<{
     readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a lower-case word, words joined by -">]>;

package/dist/standards/lint.js

@@ -119,15 +119,17 @@ export const LINT_RULES = defineLintRules([
 ]);
 /** `lint/baseline/<rule-id>.json`: today's violations of one rule, by target. It may only shrink. */
 export const baselineSchema = v.array(text);
-/** `lint/overrides.json`: exceptions, each with its reason, who keeps it and when to look again; counted against a budget. */
-export const overridesSchema = v.array(v.strictObject({
+/** One `lint/overrides.json` entry: the exception, its reason, who keeps it and when to look again. */
+export const overrideSchema = v.strictObject({
     rule: word,
     target: text,
     reason: v.pipe(text, v.minLength(10, "say why, in a sentence")),
     /** A GitHub handle or a team, `@octocat`. */
     owner: v.pipe(v.string(), v.regex(/^@[\w.-]+(\/[\w.-]+)?$/, "a GitHub handle or team, such as @octocat")),
     review_after: v.pipe(v.string(), v.isoDate("a date, YYYY-MM-DD")),
-}));
+});
+/** `lint/overrides.json`: exceptions, each with its reason, who keeps it and when to look again; counted against a budget. */
+export const overridesSchema = v.array(overrideSchema);
 /** What the schemas cannot say, so they stay convertible to JSON Schema: no entry twice. */
 export const baselineProblems = (targets) => duplicates(targets).map((target) => `"${target}" is listed twice`);
 /** No entry twice, and none past its `review_after` on `today` (YYYY-MM-DD, the caller's clock). */

package/dist/testing/sandbox.d.ts

@@ -15,6 +15,8 @@ export interface Sandbox {
 export declare const enterSandbox: (env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform) => Sandbox;
 export declare const removed: (path: string, maxRetries: number, rm?: typeof rmSync) => boolean;
 export declare const REAL_KEYRING_REACHED = "a test reached the real OS keyring \u2014 pass memoryKeyring() instead";
+/** The stack of the first reach of the keyring stand-in since the last call, and forgets it. */
+export declare const takeKeyringReach: () => string | undefined;
 /**
  * `systemKeyring` loads `@napi-rs/keyring` through `createRequire`, which `vi.mock` does not
  * intercept, so the stand-in goes into the CommonJS require cache. Resolved from here (the copy

package/dist/testing/sandbox.js

@@ -99,11 +99,24 @@ export const removed = (path, maxRetries, rm = rmSync) => {
     }
 };
 export const REAL_KEYRING_REACHED = "a test reached the real OS keyring — pass memoryKeyring() instead";
+let reached;
+/**
+ * Its throw alone is not enough: `Credentials` in `auto` mode catches it, warns and falls back to a file, so a test
+ * that reached the keyring still passed. The first reach is kept for `takeKeyringReach`.
+ */
 class ThrowingEntry {
     constructor() {
-        throw new Error(REAL_KEYRING_REACHED);
+        const error = new Error(REAL_KEYRING_REACHED);
+        reached ??= error.stack ?? error.message;
+        throw error;
     }
 }
+/** The stack of the first reach of the keyring stand-in since the last call, and forgets it. */
+export const takeKeyringReach = () => {
+    const stack = reached;
+    reached = undefined;
+    return stack;
+};
 /**
  * `systemKeyring` loads `@napi-rs/keyring` through `createRequire`, which `vi.mock` does not
  * intercept, so the stand-in goes into the CommonJS require cache. Resolved from here (the copy

package/dist/testing/setup.js

@@ -1,6 +1,6 @@
-import { afterAll } from "vitest";
+import { afterAll, afterEach } from "vitest";
 import { installNetworkGuard } from "./network.js";
-import { enterSandbox, installThrowingKeyring } from "./sandbox.js";
+import { enterSandbox, installThrowingKeyring, takeKeyringReach } from "./sandbox.js";
 /**
  * One vitest `setupFiles` entry for every WireCat CLI: `setupFiles: ["@wirecat/cli-base/testing/setup"]`.
  * Each test file gets its own sandbox directory, removed when the file is done; the real keyring and
@@ -9,4 +9,9 @@ import { enterSandbox, installThrowingKeyring } from "./sandbox.js";
 const sandbox = enterSandbox();
 installThrowingKeyring();
 installNetworkGuard();
+afterEach(() => {
+    const stack = takeKeyringReach();
+    if (stack)
+        throw new Error(`the test passed only because the keyring fell back to a file:\n${stack}`);
+});
 afterAll(() => sandbox.restore());

package/docs/standards/README.md

@@ -29,7 +29,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 |---|---|---:|---|
 | [Toolchain](toolchain.md) | `TOOL` | 20 | TypeScript, Biome, grit plugins, size caps, import cycles, spelling, Markdown, Go |
 | [Layout](layout.md) | `LAY` | 10 | Repository layout, entry points, exports, file size, one job per file, splitting a unit, the bundled bin |
-| [Commands](commands.md) | `CMD` | 29 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references, joining `wcat` |
+| [Commands](commands.md) | `CMD` | 30 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references, joining `wcat`, settings in the config file |
 | [Output](output.md) | `OUT` | 24 | Data on stdout only, envelopes, errors, exit codes, partial answers, projection |
 | [MCP](mcp.md) | `MCP` | 13 | The MCP tools, how they come from commands, what each permission shows |
 | [Accounts](accounts.md) | `ACCT` | 12 | The explicit profile, reads across accounts, scope flags, linked identities, sign-in commands |

package/docs/standards/architecture.md

@@ -86,7 +86,7 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Example:** topics and polls are port groups and shared commands in cli-core. A messenger that lacks a capability
   refuses the command; it does not silently do less. A bot is another messenger with fewer capabilities, and tg and
   max share the bot code. Calendars have the same shape: cli-core's `addCalendarCommands` builds `calendars`,
-  `sync`, `status`, `events` and `search` over the `CalendarSource` and `CalendarWriter` ports, and mounts
+  `sync`, `store status`, `events` and `search` over the `CalendarSource` and `CalendarWriter` ports, and mounts
   `calendars busy` or the event writes only when the provider has them.
 - **Exceptions:** a feature stays in one CLI only when the other providers cannot have it, such as MAX's socket server,
   Telegram's app registration, or gcal's generated `api` commands.

package/docs/standards/commands.md

@@ -127,7 +127,7 @@ catalogue and parity manifest stay in cli-core
   before the create, so a retry finds it at the provider. A CLI whose provider takes such an id may offer both. gcal
   offers only `--operation-id` (from gcal 0.9.0): its `operation_id` is also the event's id at Google, so one value
   serves both.
-- **Exceptions:** generated commands (`bot api`) are exempt from the naming rules.
+- **Exceptions:** generated commands (`bot api`, and gcal's and drive's `api`) are exempt from the naming rules.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CMD-11 · Name an option in plain words, with the kind of value in the name
@@ -291,7 +291,7 @@ store or files without reading the service first (`remote: "none"`, `local: "wri
 - **Enforced by:** `command-example-count` · `faulty-help-example-parameters`.
 - **Example:** `annotate(list, { examples: ["max chats list --limit 20"] })`. Each example starts with the tool, runs
   its own command, and gives only arguments and options that command takes.
-- **Exceptions:** generated commands (`bot api`) need no examples.
+- **Exceptions:** generated commands (`bot api`, and gcal's and drive's `api`) need no examples.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CMD-25 · Give a shared command and a shared option the same sentence in every CLI of its group
@@ -380,10 +380,31 @@ The references, each for its own part:
   `help`, `version`, `shortcuts`, `doctor`, `update`, `upgrade`, `app`), and, with `--cli`, when the built CLI does not
   answer `--wcat-describe`.
 - **Exceptions:** a CLI keeps its short `"bin"` name beside `wcat-<name>` until callers have moved to the new name; the
-  warning stays until then.
+  warning stays until then. A CLI that keeps the short name for good says why in `lint/overrides.json` (`"rule":
+  "wcat-bin-name"`, the target as the warning prints it), which silences the warning and counts against the budget.
 - **Applies to:** all CLIs, and third-party CLIs that join `wcat`. **Since:** cli-base 0.66.0. **Rulings:** NEED-149,
   NEED-153, NEED-154.
 
+## Settings
+
+### WC-CMD-30 · Write every setting into the config file with its default, and list them all in `config show`
+
+A CLI declares each scalar setting once, with its default and one line that says what it does, through cli-core's
+`DeclaredSetting`. `config show` lists every declared setting with its value, its default and whether the file sets
+it. Whenever the CLI writes its config file anyway, and on an explicit `config migrate`, it adds each missing setting
+at its default with `withSettingDefaults`. It keeps the owner's values, their order and unknown keys, and creates no
+section. A plain read never rewrites the file.
+
+- **Why:** the owner finds and edits every setting in the file, without reading the docs to learn that it exists.
+- **Enforced by:** review only.
+- **Example:** `memo config migrate` adds `"agent_decisions": false` to a file that lacks it; `memo config show` lists
+  it as `false (default)`.
+- **Exceptions:** lists and sections that need fields no default can give (accounts, folders, permissions) get no
+  placeholder. A secret is never declared, since `config show` prints every value. Known gaps, as of 2026-11-03:
+  tg, max, wa, mail, gcal and drive list every setting with its source in `config show`, but their starter file holds
+  only five of them and nothing fills it later; zm declares nothing yet.
+- **Applies to:** all CLIs. **Since:** cli-base 0.76.0. **Rulings:** none.
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page

package/docs/standards/docs.md

@@ -153,7 +153,8 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
 - **Enforced by:** `pnpm docs:check` · `changelog-guard.yml`.
 - **Example:** `### Added`, `### Changed — may break callers`, `### Fixed`, `### Security`, `### Removed`. max-cli
   uses this fixed Russian rendering: `Что нового`, `Изменено — может сломать скрипты`, `Исправлено`, `Безопасность`,
-  `Удалено`.
+  `Удалено`. Every entry sits under one of them: `docs:check` refuses an entry under no heading in the top
+  section.
 - **Exceptions:** a released section keeps the headings it was released with, because it is never edited
   ([WC-DOC-20](#wc-doc-20--a-released-section-is-frozen-and-a-new-entry-goes-under-an-existing-heading)). A CLI that
   moves to this set puts its last version with the old headings in its changelog rules as

package/docs/standards/lifecycle.md

@@ -82,6 +82,7 @@ and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and
 |---|---|---|
 | one-shot | 30 s | 30 s |
 | `cooperative` ([WC-LIFE-10](#wc-life-10--mark-a-long-command-cooperative-when-it-should-stop-at-its-own-pace-and-keep-its-work)) | 5 min | 45 s |
+| `cooperative` that also declares `partial` (a resumable sync) | 15 min | 45 s |
 
 `--timeout 2m` or the `<PREFIX>_TIMEOUT` variable sets the deadline, higher or lower. Past the deadline a one-shot
 command fails with `timeout` (exit 9).
@@ -93,10 +94,10 @@ command fails with `timeout` (exit 9).
   a cut call. Claude Code waits longer ([its MCP page](https://code.claude.com/docs/en/mcp)), but a CLI does not know
   its client, so it takes the shortest.
 - **Enforced by:** `cli-core: src/cli/deadline.test.ts` · `cli-core: src/cli/program.test.ts`.
-- **Example:** from cli-core 0.464.0, a calendar `sync` in a terminal may run 5 minutes; the same command called over
-  MCP stops at 45 seconds with what it saved. cli-core's `DEFAULT_COMMAND_MS`, `DEFAULT_COOPERATIVE_MS` and
-  `DEFAULT_AGENT_COOPERATIVE_MS` (`src/cli/execution.ts`) hold the three values, and `run()` picks one when it starts
-  the command.
+- **Example:** from cli-core 0.473.0, a calendar `sync` in a terminal may run 15 minutes; the same command called over
+  MCP stops at 45 seconds with what it saved. cli-core's `DEFAULT_COMMAND_MS`, `DEFAULT_COOPERATIVE_MS`,
+  `DEFAULT_SYNC_MS` and `DEFAULT_AGENT_COOPERATIVE_MS` (`src/cli/execution.ts`) hold the four values, and `run()` picks
+  one when it starts the command.
 - **Exceptions:** a `persistent` command has no deadline and ignores `--timeout`. An `interactive` command has none
   while a person is at the terminal; run headless, it keeps the deadline. `--help` and `--version` need none. A
   background fetch started with `<PREFIX>_BACKFILL_JOB` is bounded only by an explicit `--timeout`.
@@ -274,7 +275,7 @@ status command answers how far it is
 - **Enforced by:** `cli-core: src/background/budget.test.ts` · `cli-core: src/calendar/testing/sync-contract.ts`.
 - **Example:** `gcal personal sync` over MCP has 45 s: margin 6.75 s, so with gcal's 1.5 s about 25 requests. It
   answers `state: "partial"`, `stopped: "requests"`, `progress: { calendars, calendarsDone, requests, saved }`, and
-  `next` with `gcal personal sync`; `gcal personal status` shows each calendar's progress. cli-core builds the budget
+  `next` with `gcal personal sync`; `gcal personal store status` shows each calendar's progress. cli-core builds the budget
   with `runBudgetOf(command, maxPages)` from `@wirecat/cli-core/cli` over `runBudget` in
   `@wirecat/cli-core/background`.
 - **Exceptions:** known gaps, as of 2026-10-27: only the calendar sync spends a budget (see "Who follows"). The

package/docs/standards/mcp.md

@@ -16,8 +16,9 @@ Rule ids on this page are `WC-MCP-<n>`. How to read a rule, how ids work and whi
 ### Who follows these rules today
 
 tg, max and wa serve cli-core's personal server (`<cli> <profile> mcp serve`) and bot server (`<cli> <profile> bot mcp serve`).
-`mcp serve --profiles` ([WC-MCP-9](#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each)) is not
-built yet: cli-core serves one named profile.
+cli-core serves `mcp serve --profiles`
+([WC-MCP-9](#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each)) from 0.470.0, for the
+messengers and for the CLIs below that use its shared server.
 zoom serves the three shared tools over its own commands from zoom-cli 0.35.0 (`zm <profile> mcp serve`, cli-core's
 `toolsFromCommands` and `runCommandForAgent`), and gcal does the same (`gcal <profile> mcp serve`). memo and drive have their own servers: memo has hand-written
 tools, and drive builds one tool per command from its command tree and skips commands through its own list. Those two are known

package/docs/standards/permissions.md

@@ -358,10 +358,9 @@ A messenger's keys come from its resources (`messages`, `chats`). Any other CLI
   `ask` runs without a question, and each reaches people other than the owner. gcal adds its own keys for its generated
   `api <method>` commands: sharing a calendar is `ask` (NEED-1857), and emptying the main calendar
   (`api.calendar.calendars.clear`) is `deny`.
-- **Exceptions:** known gaps, as of 2026-10-31:
-  - gcal's generated `api` commands default every write to `ask`, ordinary changes included.
-  - drive keeps its own policy and `--read-only` flag, zoom reads its own `remote-meetings` key with `levelFor`, and
-    memo uses cli-core's permissions for the shared commands only. None of them declares `commandPermissions` yet.
+- **Exceptions:** known gaps, as of 2026-11-03: drive keeps its own policy and `--read-only` flag, zoom reads its own
+  `remote-meetings` key with `levelFor`, and memo uses cli-core's permissions for the shared commands only. None of
+  them declares `commandPermissions` yet.
 - **Applies to:** every CLI that writes and is not a messenger. **Since:** cli-base 0.64.0 (the levels and the shared
   keys on every path: cli-base 0.65.0). **Rulings:** NEED-1857, NEED-1883.
 

package/docs/standards/releases.md

@@ -199,7 +199,7 @@ fixtures, `scripts/`, `.github/`, `bin/release`, `config/`, `lint/`, `contracts/
   `scripts/smoke.ts` does, checks only that npm packs what `files` says, and cannot fail on a wrong `files` list.
   `npm pack --dry-run` in gcal-cli packed 256 files on 2026-10-27, `src/`, `scripts/`, `.github/`, `config/`,
   `contracts/`, `lint/` and `template.json` among them, because its `files` list named them; its check could not see
-  it. On 2026-10-31 (gcal-cli 0.2.0) it packs 144. The check this rule needs
+  it. gcal's check now uses a fixed list of its own (`scripts/smoke.ts`). The check this rule needs
   refuses the forbidden paths above whatever `files` says: cli-template's `scripts/smoke.ts` does since
   [cli-template#85](https://github.com/WireCatLabs/cli-template/pull/85). `scripts/` is a seed that `upgrade` never
   changes, so a CLI made before it copies the check by hand.

package/docs/standards/time.md

@@ -80,10 +80,8 @@ local midnight. The answer gives the window it used, in UTC.
   not included), matches by comparing local dates, never UTC moments: it is in the window when its dates overlap the
   local dates the window covers. So in `Europe/Madrid` a filter for 1 September returns the all-day event of
   1 September and not the one of 31 August, whatever zone the event's calendar is in.
-- **Exceptions:** none. Known gap, as of 2026-10-27, read from the code and not run: cli-core's event filter
-  (`src/store/sqlite/calendar.ts`, the `events` query) compares `starts_at` and `ends_at` with the UTC window for
-  all-day events too, and gcal stores an all-day event's start as midnight in its calendar's zone. The two agree
-  when the calendar's zone is the zone in use, and miss by a day at the edges when it is not.
+- **Exceptions:** none. cli-core's event filter matches an all-day event by its local dates
+  (`src/store/sqlite/calendar-events.ts`), and `events list` answers the window in `meta.window`.
 - **Applies to:** all CLIs. **Since:** cli-base 0.48.0. **Rulings:** none.
 
 ### WC-TIME-6 · Run the tests in a zone that is not UTC, and prove stored values do not depend on it

package/docs/standards/toolchain.md

@@ -90,11 +90,13 @@ plus community itself. cli-template follows every rule here as a CLI does
   `scripts/smoke.ts` runs the built exports with plain assertions, and the Bun job runs it
   (`pnpm build && pnpm smoke:bun`). A new entry point gets a line there. Node 22 runs in the Windows install matrix of
   tg, max and wa, in zoom's full validation, in cli-core's old-Node job and in cli-template's `node-22` job (Node
-  22.16.0, from cli-template 0.11.0), which a CLI made from the template gets with `upgrade`.
+  22.16.0, from cli-template 0.11.0), which a CLI made from the template gets with `upgrade`; gcal has its own
+  `node-22` job.
 - **Exceptions:** cli-docs and community publish no runtime package. tg needs `^22.19.0`. memo, drive, cli-base and
-  the CLIs made from a template before 0.11.0 do not run Node 22 in any workflow yet; gcal is adding its own job.
+  the CLIs made from a template before 0.11.0 do not run Node 22 in any workflow yet.
   cli-base's own `engines` is still `>=22`. The unit suite runs on Windows and macOS for tg, max and drive
-  (`platforms: true`); zoom and memo still fail tests there, so theirs is off.
+  (`platforms: true`), and for gcal at release, monthly and on a manual run; zoom and memo still fail tests there,
+  so theirs is off.
 - **Applies to:** the CLIs, cli-core and cli-base. **Since:** cli-base 0.41.0. **Rulings:** NEED-11.
 
 ### WC-TOOL-7 · Let Biome format the code, and do not format by hand

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.75.0",
+  "version": "0.75.2",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",