@wirecat/cli-base 0.75.1 → 0.76.0

package/CHANGELOG.md

@@ -8,6 +8,79 @@ 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.76.0 — 04.11.2026
+
+### Changed — may break callers
+
+- **A new error code, `conflict`, exit 15: a write refused because what it would change moved on since the caller
+  read it** (a stale `--revision`). Until now such a refusal had to borrow `configuration_error` (exit 3), which says
+  the setup is wrong and leaves an agent to read `details.reason` to tell them apart. `errorCodes` now has 15 codes,
+  `EXIT_CODES.conflict` is 15, the fallback reason is `write.conflict`, and `retry.safe` is always false: read the
+  record again and decide on the new copy. A CLI keeps its own reason (`task.stale`) and details. What to watch for:
+  anything that lists the codes itself, or maps every code or exit number, must add this one. Every CLI's
+  `contracts/mcp-tools.json` names the codes and is regenerated at its bump; braze-cli keeps its own copy of the list;
+  the desktop app branches on codes for sync failures. cli-core moves `task.stale` (and later the other `*.stale`
+  reasons) to this code after a release.
+
+### Added
+
+- **`loadConstants(layers, schema)`: one way to ship values inside the packages.** Each layer (cli-base, cli-core,
+  the tool) keeps a `constants.json` at its package root; `loadConstants([BASE_CONSTANTS, core, tool], schema)` merges
+  them in that order (objects key by key, a later layer winning; arrays and scalars replaced), treats a missing file as
+  empty, validates against the caller's schema built on `baseConstantsSchema`, names the dotted path and file of a bad
+  value, and freezes the result. cli-base's own layer is `{}`. Rule
+  [WC-ARCH-23](docs/standards/architecture.md#wc-arch-23--a-value-that-ships-with-the-package-lives-in-the-layers-constantsjson):
+  such a value is never a scattered constant or a file CI writes from a secret. cli-core builds the OAuth apps on it.
+- **A query value takes a ref unquoted: `about:project:1` and `about:chat:max/1/2` are one value.** Every WireCat
+  CLI prints refs this way, and a list refused them unless the caller quoted them. A field value made of a lower-case
+  word, a colon and more text with no space now reads as one term, so `url:https://example.com` works unquoted too.
+  `about:project` alone and `project:1` as a field and value read as before. A CLI gets it by updating cli-base.
+- **Rule WC-CMD-31: accept every ref any WireCat CLI prints, and never ask the caller to translate it**
+  ([WC-CMD-31](docs/standards/commands.md#wc-cmd-31--accept-every-ref-any-wirecat-cli-prints-and-never-ask-the-caller-to-translate-it)).
+  Arguments, options and query values take a stored thing's ref as printed; a ref for another account or provider
+  fails with an error that names the right one.
+- **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 known
+  gaps now name what cli-core's shared settings cover (tg, max, wa, mail, gcal after their cli-core bump) and what is
+  left: those CLIs' own settings, drive's own `config` (no `migrate`, writes do not fill) and zm.
+
+## 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

package/constants.json

@@ -0,0 +1 @@
+{}

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+import * as v from "valibot";
+/** cli-base's own layer, the first one every program passes to `loadConstants`. */
+export declare const BASE_CONSTANTS: import("url").URL;
+/** What cli-base's layer holds; a layer above extends it with `v.object({ ...baseConstantsSchema.entries, … })`. */
+export declare const baseConstantsSchema: v.ObjectSchema<{}, undefined>;
+/**
+ * Values that ship inside the packages — never the owner's settings. Each layer is a JSON file, base first; a file
+ * that does not exist is an empty layer, so a tool without constants of its own passes its URL anyway. Plain objects
+ * merge key by key and a later layer wins; an array or a scalar replaces what was below it. The result is checked
+ * against the caller's schema and frozen.
+ */
+export declare const loadConstants: <TSchema extends v.GenericSchema>(layers: readonly URL[], schema: TSchema) => v.InferOutput<TSchema>;

package/dist/constants.js

@@ -0,0 +1,63 @@
+import { fileURLToPath } from "node:url";
+import * as v from "valibot";
+import { loadConfigFile } from "./config.js";
+/** cli-base's own layer, the first one every program passes to `loadConstants`. */
+export const BASE_CONSTANTS = new URL("../constants.json", import.meta.url);
+/** What cli-base's layer holds; a layer above extends it with `v.object({ ...baseConstantsSchema.entries, … })`. */
+export const baseConstantsSchema = v.object({});
+const LayerSchema = v.record(v.string(), v.unknown());
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const merge = (into, from, file, setBy, prefix = "") => {
+    const out = { ...into };
+    for (const [key, value] of Object.entries(from)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        const current = out[key];
+        if (isPlainObject(current) && isPlainObject(value)) {
+            out[key] = merge(current, value, file, setBy, path);
+        }
+        else {
+            out[key] = value;
+            setBy.set(path, file);
+        }
+    }
+    return out;
+};
+const deepFreeze = (value) => {
+    if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+};
+const fileOf = (path, setBy, files) => {
+    for (let at = path.split("."); at.length > 0; at = at.slice(0, -1)) {
+        const file = setBy.get(at.join("."));
+        if (file)
+            return `set in ${file}`;
+    }
+    return `not set in ${files.join(", ")}`;
+};
+/**
+ * Values that ship inside the packages — never the owner's settings. Each layer is a JSON file, base first; a file
+ * that does not exist is an empty layer, so a tool without constants of its own passes its URL anyway. Plain objects
+ * merge key by key and a later layer wins; an array or a scalar replaces what was below it. The result is checked
+ * against the caller's schema and frozen.
+ */
+export const loadConstants = (layers, schema) => {
+    const files = layers.map((layer) => fileURLToPath(layer));
+    const setBy = new Map();
+    let merged = {};
+    for (const file of files) {
+        merged = merge(merged, loadConfigFile(file, LayerSchema, () => ({})), file, setBy);
+    }
+    const result = v.safeParse(schema, merged);
+    if (!result.success) {
+        const problems = result.issues.map((issue) => {
+            const path = v.getDotPath(issue) ?? "(root)";
+            return `${path}: ${issue.message} (${fileOf(path, setBy, files)})`;
+        });
+        throw new Error(`the packaged constants are not valid:\n  ${problems.join("\n  ")}`);
+    }
+    return deepFreeze(result.output);
+};

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/errors.d.ts

@@ -2,11 +2,14 @@
  * Every failure a CLI built on this package, and anything consuming its output, can see. The list
  * is closed on purpose: an agent branches on `code`, and a new code is a contract change.
  *
+ * `conflict` is a write refused because what it would change moved on since the caller read it (a stale revision):
+ * nothing is wrong with the input or the setup, and the same write on a fresh copy may work.
+ *
  * "provider" is whatever the CLI talks to — an HTTP API, a socket, a messenger. The word is
  * deliberately not "server": a provider that answered with a refusal is not the same as one that
  * never answered.
  */
-export declare const errorCodes: readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"];
+export declare const errorCodes: readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"];
 export type ErrorCode = (typeof errorCodes)[number];
 /**
  * Anything a caller may attach. Everything is optional because these are diagnostics, not a

package/dist/errors.js

@@ -2,6 +2,9 @@
  * Every failure a CLI built on this package, and anything consuming its output, can see. The list
  * is closed on purpose: an agent branches on `code`, and a new code is a contract change.
  *
+ * `conflict` is a write refused because what it would change moved on since the caller read it (a stale revision):
+ * nothing is wrong with the input or the setup, and the same write on a fresh copy may work.
+ *
  * "provider" is whatever the CLI talks to — an HTTP API, a socket, a messenger. The word is
  * deliberately not "server": a provider that answered with a refusal is not the same as one that
  * never answered.
@@ -20,6 +23,7 @@ export const errorCodes = [
     "provider_unavailable",
     "invalid_response",
     "outcome_unknown",
+    "conflict",
     "cancelled",
 ];
 // Symbol.for, so two copies of this package — one CLI's and one dependency's, during a pin bump —

package/dist/exit-codes.js

@@ -18,6 +18,7 @@ export const EXIT_CODES = {
     provider_unavailable: 12,
     invalid_response: 13,
     outcome_unknown: 14,
+    conflict: 15,
     cancelled: 130,
 };
 export const exitCodeFor = (code) => EXIT_CODES[code];

package/dist/failure.d.ts

@@ -58,7 +58,7 @@ export declare const mcpErrorResult: (object: ErrorObject) => {
     }[];
     structuredContent: {
         error: {
-            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+            code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
             reason: string;
             message: string;
             param?: string | undefined;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { BATCH_LIMITS, type BatchContext, type BatchHandler, type BatchOperation, type BatchReport, type BatchResult, type PreparedBatchRequest, prepareBatch, projectBatchAnswers, readBatchInput, runBatch, } from "./batch.js";
 export { loadConfigFile, saveConfigFile, writeSecurely } from "./config.js";
+export { BASE_CONSTANTS, baseConstantsSchema, loadConstants } from "./constants.js";
 export type { CredentialSource, CredentialStorage, CredentialsOptions, StoredCredential, WriteOptions, } from "./credentials.js";
 export { CREDENTIAL_STORAGE, Credentials, keyringService, movedRunService } from "./credentials.js";
 export { createDeadline, type Deadline, type DeadlineOptions } from "./deadline.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { BATCH_LIMITS, prepareBatch, projectBatchAnswers, readBatchInput, runBatch, } from "./batch.js";
 export { loadConfigFile, saveConfigFile, writeSecurely } from "./config.js";
+export { BASE_CONSTANTS, baseConstantsSchema, loadConstants } from "./constants.js";
 export { CREDENTIAL_STORAGE, Credentials, keyringService, movedRunService } from "./credentials.js";
 export { createDeadline } from "./deadline.js";
 export { CliError, errorCodes, isCliError } from "./errors.js";

package/dist/query/parser.js

@@ -115,6 +115,17 @@ const tokensOf = (text, fail = queryError) => {
                     break;
                 at++;
             }
+            // A ref after a field (`about:project:1`, `about:chat:max/1/2`) is one value: every WireCat CLI prints refs
+            // unquoted, and Lucene would read the second colon as a stray field.
+            const [field, colon] = tokens.slice(-2);
+            if (field?.kind === "term" &&
+                colon?.kind === ":" &&
+                colon.span.end === start &&
+                text[at] === ":" &&
+                /^[a-z][a-z_-]*$/u.test(text.slice(start, at)) &&
+                /^:[^\s()"]/u.test(text.slice(at)))
+                while (at < text.length && !whitespace(text[at] ?? "") && !["(", ")", '"'].includes(text[at] ?? ""))
+                    at++;
             const raw = text.slice(start, at);
             kind =
                 { AND: "AND", OR: "OR", NOT: "NOT", "&&": "AND", "||": "OR" }[raw] ??

package/dist/query/registry.d.ts

@@ -15,7 +15,7 @@ export declare const defineQuery: (registry: QueryRegistry) => QueryRegistry;
 /** The query reasons every CLI shares; a CLI adds its own (`query.invalid-tag`) with `defineReasons`. */
 export declare const QUERY_REASONS: {
     reason: string;
-    code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
+    code: "authentication_error" | "cancelled" | "configuration_error" | "confirmation_required" | "conflict" | "internal_error" | "invalid_response" | "network_error" | "not_found" | "outcome_unknown" | "permission_error" | "provider_error" | "provider_unavailable" | "rate_limited" | "timeout" | "validation_error";
     message: string;
     details: string[];
     step?: string | undefined;

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/errors.d.ts

@@ -8,7 +8,7 @@ export declare const CRASH_REASON = "command.crashed";
 /** The one error object, on stderr in machine mode and as MCP's `isError` content alike. */
 export declare const errorObjectSchema: v.StrictObjectSchema<{
     readonly error: v.StrictObjectSchema<{
-        readonly code: v.PicklistSchema<["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled", "internal_error"], undefined>;
+        readonly code: v.PicklistSchema<["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled", "internal_error"], undefined>;
         readonly reason: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>;
         readonly message: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         /** The option or argument at fault. */
@@ -55,7 +55,7 @@ export declare const errorObjectSchema: v.StrictObjectSchema<{
 export type ErrorObject = v.InferOutput<typeof errorObjectSchema>;
 declare const reasonSchema: v.StrictObjectSchema<{
     readonly reason: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>;
-    readonly code: v.PicklistSchema<["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled", "internal_error"], undefined>;
+    readonly code: v.PicklistSchema<["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled", "internal_error"], undefined>;
     /** `{name}` placeholders, each one of `details`. */
     readonly message: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, v.MaxLengthAction<string, 120, undefined>]>;
     readonly details: v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a snake_case key">]>, undefined>;

package/dist/standards/errors.js

@@ -97,6 +97,12 @@ export const BASE_REASONS = defineReasons([
         details: [],
     },
     { reason: "outcome.unknown", code: "outcome_unknown", message: "it is not known whether it worked", details: [] },
+    {
+        reason: "write.conflict",
+        code: "conflict",
+        message: "it changed since it was read; read it again",
+        details: [],
+    },
     { reason: "command.cancelled", code: "cancelled", message: "the command was cancelled", details: [] },
     { reason: CRASH_REASON, code: CRASH_CODE, message: "the command failed; this is a bug", details: [] },
 ]);

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/standards/output.d.ts

@@ -65,7 +65,7 @@ export declare const pageSchema: v.VariantSchema<"mode", [v.StrictObjectSchema<{
 export type Total = v.InferOutput<typeof totalSchema>;
 /** A source that failed or was skipped: the answer holds what the others gave. */
 export declare const issueSchema: v.StrictObjectSchema<{
-    readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+    readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
     readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
     /** The account, provider or source that is missing from the answer. */
     readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
@@ -80,7 +80,7 @@ export declare const metaSchema: v.StrictObjectSchema<{
     readonly accounts: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>, undefined>;
     readonly complete: v.BooleanSchema<undefined>;
     readonly issues: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-        readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+        readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
         readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
         /** The account, provider or source that is missing from the answer. */
         readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
@@ -172,7 +172,7 @@ export declare const listEnvelopeSchema: <T extends v.GenericSchema>(item: T) =>
         readonly accounts: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>, undefined>;
         readonly complete: v.BooleanSchema<undefined>;
         readonly issues: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
             readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
             /** The account, provider or source that is missing from the answer. */
             readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
@@ -237,7 +237,7 @@ export declare const itemEnvelopeSchema: <T extends v.GenericSchema>(item: T) =>
         readonly accounts: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>, undefined>;
         readonly complete: v.BooleanSchema<undefined>;
         readonly issues: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+            readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
             readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
             /** The account, provider or source that is missing from the answer. */
             readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
@@ -280,7 +280,7 @@ export declare const jsonlEndSchema: v.StrictObjectSchema<{
     readonly type: v.LiteralSchema<"end", undefined>;
     readonly complete: v.BooleanSchema<undefined>;
     readonly issues: v.OptionalSchema<v.ArraySchema<v.StrictObjectSchema<{
-        readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "cancelled"], undefined>;
+        readonly code: v.PicklistSchema<readonly ["validation_error", "configuration_error", "authentication_error", "permission_error", "not_found", "confirmation_required", "rate_limited", "timeout", "network_error", "provider_error", "provider_unavailable", "invalid_response", "outcome_unknown", "conflict", "cancelled"], undefined>;
         readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "dotted lower-case words, such as `page.next`">]>, undefined>;
         /** The account, provider or source that is missing from the answer. */
         readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;

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,18 +29,18 @@ 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` | 31 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references, joining `wcat`, settings in the config file, refs |
 | [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 |
 | [Permissions](permissions.md) | `PERM` | 22 | Levels, keys, defaults, hard limits, the write guard and its journal |
-| [Architecture](architecture.md) | `ARCH` | 18 | Layers, dependency direction, vendor types, what goes in which package, the command tree built once |
+| [Architecture](architecture.md) | `ARCH` | 19 | Layers, dependency direction, vendor types, what goes in which package, the command tree built once |
 | [Lifecycle](lifecycle.md) | `LIFE` | 15 | Opening late, who closes, deadlines, long-running commands, the `serve` relay, resumable syncs and their request budget, the run log |
 | [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
 | [Data model](data-model.md) | `DATA` | 9 | Core entities, entities and source records, `external_id`, field names, links and duplicates, files, calendar entries |
 | [Testing](testing.md) | `TEST` | 17 | Sandbox, no network, no real waits, leak tests, coverage, contracts, test matrix, parity |
 | [Security](security.md) | `SECR` | 23 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting, OAuth sign-in, meeting secrets, keyring in moved-folder runs |
-| [Documents](docs.md) | `DOC` | 20 | User pages and developer pages, generated pages, current facts, changelog |
+| [Documents](docs.md) | `DOC` | 21 | User pages and developer pages, generated pages, current facts, changelog, repository page |
 | [Comparisons](comparisons.md) | `CMP` | 11 | Which tools a comparison page lists, rows as user tasks, agents and safety, where others are better, proof of marks |
 | [Releases](releases.md) | `REL` | 15 | `bin/release`, the release lock, versions, the owner's yes, trusted publishing |
 | [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |

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.
@@ -249,6 +249,20 @@ options, its hooks) lives in a per-call context that the action receives, never
   [CORE-41](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/BACKLOG_LATER.md). New code does not add to it.
 - **Applies to:** cli-core's command skeleton and every CLI built on it. **Since:** cli-base 0.65.3. **Rulings:** none.
 
+### WC-ARCH-23 · A value that ships with the package lives in the layer's constants.json
+
+A value that ships inside a package and is the same for every owner — an OAuth app's client id, a fixed URL — lives
+in that layer's `constants.json` and is read through `loadConstants` (cli-base, then cli-core, then the tool). It is
+never a constant scattered through the source, and never a file CI writes from a secret.
+
+- **Why:** a CI-written file goes missing when the secret does, and the release then cannot sign in (gcal 0.19.0);
+  scattered constants are copied between CLIs and drift apart.
+- **Enforced by:** review only.
+- **Example:** cli-core's `constants.json` holds the WireCat Google desktop app's `google.app.client_id`; drive and
+  gcal read it through cli-core instead of each keeping a copy. The owner's own choices stay in `config.json`.
+- **Exceptions:** none.
+- **Applies to:** cli-base, cli-core and every CLI. **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/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,54 @@ 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. It may create
+the top-level `defaults` section, which needs no field of its own, so every key shows; it creates no other 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. A setting whose absence means
+  something no value says (no timeout, the terminal decides colour) is not declared either. Known gaps, as of
+  2026-11-03: cli-core's shared settings declare every shared scalar setting and give `config migrate`, so tg, max,
+  wa, mail and gcal follow once they take the cli-core release after 0.561.0; their own settings (max's `serve` and
+  `transcribe_model`, for example) are not declared yet. drive's first-run file holds them all, but drive's own
+  `config` has no `migrate` and its writes do not fill the file. zm declares nothing yet.
+- **Applies to:** all CLIs. **Since:** cli-base 0.76.0. **Rulings:** none.
+
+## References
+
+### WC-CMD-31 · Accept every ref any WireCat CLI prints, and never ask the caller to translate it
+
+A command argument, an option and a query value that take a stored thing accept its ref exactly as any WireCat CLI
+prints it ([WC-OUT-13](output.md#wc-out-13--write-times-durations-references-and-empty-values-one-way)), unquoted.
+The CLI that owns the thing opens it; a ref for another account or provider fails with an error that names the
+right one, never `not_found`.
+
+- **Why:** agents copy refs from one CLI's output into the next command. Each ref that fails costs a retry, a guess
+  or a correction from the owner: memo printed `chat:max/…`, and max read it as a chat title.
+- **Enforced by:** `src/query/parser.test.ts` · `cli-core: src/domain/references.test.ts`.
+- **Example:** `memo relationships list about:project:1` and `about:chat:max/1/2` read the ref as one value;
+  `max work messages list chat:max/<account>/<id>` answers as the bare id does.
+- **Exceptions:** none. Known gaps, as of 2026-11-03: the query value works from cli-base 0.75.3 in each CLI that
+  takes it; chat and message arguments in tg, max and wa, and `document:N` in drive's `knowledge` commands, follow
+  cli-core's reference slices.
+- **Applies to:** all CLIs. **Since:** cli-base 0.75.3. **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
@@ -216,6 +217,21 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
   Sections that already differed from their tag on 25.10.2026 stay as they are, and nothing reports them.
 - **Applies to:** every repository that calls the changelog guard. **Since:** cli-base 0.41.0. **Rulings:** none.
 
+### WC-DOC-21 · A public repository has a banner, a link preview, a homepage and topics
+
+- **Why:** the GitHub page and a shared link are often the first thing a person sees. A tool without them looks
+  unfinished next to the others, and one without topics is not found in GitHub search.
+- **Enforced by:** review only.
+- **Example:** `docs/images/social-preview.png` is 1280×640 in the shared style: the command name in the
+  cyan-violet-magenta gradient, a one-line tagline and the "part of WireCat · wirecat.dev" footer. `README.md` opens
+  with it through an absolute `raw.githubusercontent.com` URL, so it also renders on npmjs.com, with the tagline as
+  its alt text. The same file is the repository's social preview (Settings → Social preview; GitHub has no API for
+  it). The homepage is the tool's wirecat.dev docs page, and the topics name the service, `cli`, `ai-agents`, `mcp`
+  where it serves MCP, and `wirecat`.
+- **Exceptions:** private repositories, and repositories that only support the tools (`.github`, `community`,
+  `cli-docs`, `cli-testing`).
+- **Applies to:** every public WireCat repository. **Since:** cli-base 0.75.3. **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/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/output.md

@@ -216,7 +216,8 @@ whole or partial.
 - **Enforced by:** `src/exit-codes.test.ts`.
 - **Example:** 0 ok · 1 internal error · 2 validation error · 3 configuration error · 4 authentication error ·
   5 permission error · 6 not found · 7 confirmation required · 8 rate limited · 9 timeout · 10 network error ·
-  11 provider error · 12 provider unavailable · 13 invalid response · 14 outcome unknown · 130 cancelled.
+  11 provider error · 12 provider unavailable · 13 invalid response · 14 outcome unknown · 15 conflict ·
+  130 cancelled.
 - **Exceptions:** on cli-core's `run()`, a one-shot command stopped by SIGTERM exits 143. A `persistent` command
   stopped by Ctrl-C or SIGTERM exits 0. A closed pipe exits 0. See the [lifecycle](lifecycle.md) page.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
@@ -237,7 +238,8 @@ whole or partial.
 - **Example:** every error has `retry: { safe, after_ms? }`. A transient failure (`timeout`, `rate_limited`,
   `network_error`, `provider_unavailable`) is safe for a command that writes nothing on the service, or for a write
   that never left (`sent: false`). A sync that only writes the local store is safe to repeat. `outcome_unknown` is
-  never safe: repeat that write only with its `--operation-id`.
+  never safe: repeat that write only with its `--operation-id`. `conflict` (the record changed since the caller read
+  it, as a `--revision` check finds) is never safe either: read the record again and decide on the new copy.
 - **Exceptions:** cli-base's `retryOf`, used on its own, also counts a local write as a write, so it is stricter
   than cli-core's runner.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.

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.1",
+  "version": "0.76.0",
   "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",
@@ -20,6 +20,7 @@
   "files": [
     "dist",
     "config",
+    "constants.json",
     "docs/standards",
     "README.md",
     "CHANGELOG.md",