@wirecat/cli-base 0.75.2 → 0.77.0

package/CHANGELOG.md

@@ -8,6 +8,59 @@ 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.77.0 — 05.11.2026
+
+### Added
+
+- **The vocabulary has cli-core's schedule words and memo's `findings`, as the commands name them.** The resource
+  `schedule` (a profile's saved timers; the tool's own background work stays `jobs`), the verbs `agent` and `command`
+  (save a timer that starts an agent, or runs one of the tool's commands) and `exec` (what the timer itself starts;
+  a person uses `run`), and the collection `findings` (what an agent read in mail, staged for the owner; what it
+  proposes to do stays `actions`). The owner ruled to add the words as they are rather than rename the commands,
+  so the command lint checks them instead of skipping them. What to watch for: every CLI that mounts
+  `schedule` (tg, max, gcal, mail, memo, cli-core itself) and memo's `mail findings` has these in
+  `lint/baseline/unknown-verb.json` and `unknown-resource.json`; they are stale after the bump and fail the lint
+  until removed (WC-TOOL-16).
+
+## 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

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/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/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/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/standards/vocabulary.js

@@ -192,6 +192,10 @@ const verbs = [
     ["move", "move a thing to another place in the source: a file to a folder, an event to a calendar"],
     ["copy", "copy a file in the source"],
     ["run", "run a saved job once, now, as its timer would"],
+    ["exec", "what a timer itself starts: one saved schedule, from its file; a person uses run"],
+    // schedule's creators are named for what the timer starts; the owner kept these names over `create --kind`.
+    ["agent", "save a timer that starts an agent with a prompt, read-only; a verb under schedule, never a resource"],
+    ["command", "save a timer that runs one of this tool's own commands; a verb under schedule"],
     ["claim", "take a thing for a while so no other agent works it at once; the claim lapses by itself"],
     ["release", "give back what claim took, before it lapses"],
     ["merge", "fold a duplicate into the thing that stays; nothing is deleted"],
@@ -262,6 +266,10 @@ const collections = [
     ["recordings", "the files a provider recorded of a meeting"],
     ["jobs", "work this tool runs in the background or on a timer"],
     ["actions", "what an agent proposes to do; the owner confirms or rejects each"],
+    [
+        "findings",
+        "what an agent read in stored mail, staged in batches with citations; nothing is recorded until the owner confirms. What it proposes to do is actions",
+    ],
     ["agents", "the agents whose actions are recorded in the shared store"],
     ["reminders", "scheduled notices about stored work, claimed and acknowledged with delivery receipts"],
     ["key-documents", "selected source documents that a project keeps as its starting references"],
@@ -304,6 +312,10 @@ const singulars = [
     ["privacy", "who may find, see, call or add the account"],
     ["metadata", "a profile's cached source attributes"],
     ["auth", "the credentials a bot profile uses: its token and the secrets beside it"],
+    [
+        "schedule",
+        "a profile's timers the owner saved, each running a command of this tool or an agent; the tool's own background work is jobs",
+    ],
 ];
 const views = [
     ["tree", "the parent and child hierarchy of stored sources"],

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` | 30 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references, joining `wcat`, settings in the config file |
+| [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 |
+| [Security](security.md) | `SECR` | 24 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting, OAuth sign-in and which app it uses, meeting secrets, keyring in moved-folder runs |
+| [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

@@ -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

@@ -22,6 +22,13 @@ A "messenger CLI" below is one of the CLIs that share cli-core's messenger comma
 catalogue and parity manifest stay in cli-core
 [`docs/dev/STANDARD.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md).
 
+### Who follows these rules today
+
+WC-CMD-30: 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.
+
 ## Paths and words
 
 ### WC-CMD-1 · Build every path as resource first, then a verb or a view
@@ -392,19 +399,38 @@ The references, each for its own part:
 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.
+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. 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.
+  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.
 - **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

@@ -217,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/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

@@ -194,8 +194,12 @@ An agent never deletes a message for everyone, and never ends the owner's other
 ### WC-PERM-12 · `<PREFIX>_READ_ONLY` refuses every write
 
 When this variable is set, every write answers `permission_error`, whatever `permissions` or a flag say. So does a
-command that writes only on this machine, unless cli-core marks it `destroysNothing`; a new local write is refused
-until someone marks it. Logging in or out and a change to what a later run may do (a schedule, a setting, the
+command that writes only on this machine, unless cli-core marks it `destroysNothing` or it is of the propose tier; a
+new local write is refused until someone marks it. The propose tier is a closed list, cli-core's `PROPOSE_COMMANDS`:
+`messages acknowledge` and `mail findings add`. A command passes as a proposal only when it is marked `proposesOnly`
+and its path ends with a listed one; it stages something the owner decides, or moves its caller's own processing
+mark, and nothing else. Adding a path widens what a read-only agent can write, so each addition is reviewed on its
+own. Logging in or out and a change to what a later run may do (a schedule, a setting, the
 recipient list) are refused too. A `--dry-run` preview still runs.
 
 - **Why:** an unattended agent needs one switch that the config file and `--permission` cannot undo, and that also
@@ -209,7 +213,8 @@ recipient list) are refused too. A `--dry-run` preview still runs.
   other command, an MCP session included (cli-core 0.343.0). Local writes marked `destroysNothing` run: what the store
   rebuilds (`store reindex`, `mentions rebuild`), a new file (`store backup`, `store export`, `stats charts`), and the
   task writes the follow-ups skill makes on a timer, where `tasks close` only suggests the close to the owner.
-  Embedding and analysis on this machine run; sending text to an outside service for them is refused.
+  A read-only scheduled mail agent stages what it read with `mail findings add` and moves its mark with
+  `messages acknowledge`; nothing it staged is recorded until the owner confirms. Embedding and analysis on this machine run; sending text to an outside service for them is refused.
 - **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-PERM-13 · Every write passes the write guard before it leaves

package/docs/standards/security.md

@@ -373,6 +373,46 @@ store and runs no search. A CLI declares its provider and may replace any step.
   owner, 2026-10-30 (share the keyring entry, do not multiply it); owner, 2026-10-31 (do not replace it: a test of a
   new session writes a temporary entry and cleans it up).
 
+### WC-SECR-25 · Sign in with WireCat's app by default, and let the owner choose their own
+
+Every provider sign-in uses WireCat's OAuth app unless the owner names another. That app is read from
+`constants.json` ([WC-ARCH-23](architecture.md#wc-arch-23--a-value-that-ships-with-the-package-lives-in-the-layers-constantsjson)):
+cli-core's layer for Google and Microsoft, a tool's own layer for a provider only that tool uses, such as Zoom.
+
+- **Which app, first match wins:**
+  1. `session start --client-file <json>` or `--client-id <id>`;
+  2. `<TOOL>_<PROVIDER>_CLIENT_ID`, plus `<TOOL>_<PROVIDER>_CLIENT_SECRET` where the provider needs a secret. A
+     secret without an id is a `configuration_error`;
+  3. the account's config key `<provider>.client_id`;
+  4. WireCat's app.
+- **Stored with the account.** The app a sign-in used is saved with that account, so refresh and revoke use the same
+  app even after the default changes.
+- **Reported by `doctor`,** per provider: `oauth_client: { client: "wirecat" | "own" | null, source: "flag" | "env" |
+  "config" | "constants" | null }`. A null client comes with a one-line reason.
+- **Desktop.** A sign-in from wirecat-desktop offers WireCat's app, with a "Use my own app" choice that writes the same
+  override as step 2 or 3.
+- **A shipped secret** is allowed only where the provider documents the client as public, and the tool's gitleaks
+  allowlist names it by value ([WC-SECR-17](#wc-secr-17--a-gitleaks-rule-covers-each-secret-shape-a-cli-handles)).
+  Google's token endpoint refuses a Desktop app client without its secret (tested 2026-11-04), although
+  [Google's guide](https://developers.google.com/identity/protocols/oauth2/native-app) calls desktop apps public
+  clients that cannot keep secrets. So a Google app ships its id and secret; a Microsoft public client ships its id
+  only.
+- **A provider with no WireCat app yet** says so in `doctor` (a null client and its reason) and in its docs, and still
+  keeps the order, the stored app and the report above.
+
+- **Why:** an owner should sign in without creating an app first, and still be able to use their own; a token
+  refreshed with a different app than the one that issued it fails.
+- **Enforced by:** `cli-core: src/oauth/client-file.test.ts`.
+- **Example:** `gcal personal session start` uses WireCat's Google app and `doctor` reports
+  `{ client: "wirecat", source: "constants" }`; with `GCAL_GOOGLE_CLIENT_ID` and `GCAL_GOOGLE_CLIENT_SECRET` set it
+  reports `{ client: "own", source: "env" }`.
+- **Exceptions:** known gaps, as of 2026-11-04: mail has no WireCat default for Google; zoom has no WireCat app until
+  Zoom Marketplace approves one; no tool reads the per-account `google.client_id` key yet; mail's Microsoft key is
+  named `microsoft_client_id`; `doctor` reports no `source` yet. gcal's default came from a file CI wrote from a
+  secret; cli-core's `constants.json` replaces it from its next release.
+- **Applies to:** every CLI that signs in with OAuth, and wirecat-desktop. **Since:** cli-base 0.76.1.
+  **Rulings:** owner, 2026-11-04.
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.75.2",
+  "version": "0.77.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",