@wirecat/cli-base 0.75.2 → 0.76.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ 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

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/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 |
+| [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

@@ -392,19 +392,42 @@ 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. 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

@@ -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/package.json

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