@wirecat/cli-base 0.67.0 → 0.68.1

package/CHANGELOG.md

@@ -8,6 +8,49 @@ 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.68.1 — 31.10.2026
+
+### Added
+
+- **The audit accepts a flag that one CLI lacks by design, by name.** A parity difference may carry `absent: "<cli>"`
+  with a target of `<path> <flag>` and no CLI list; it covers every finding where only that CLI lacks the flag and the
+  others agree, so another CLI joining the group does not make it stale. `PARITY_GROUPS` uses it to declare that memo
+  has no profiles of its own (no `--profiles` on `mcp serve`, `mcp revoke`, `mcp server start|status|stop`); memo
+  selects other CLIs' accounts with `--source` and `--account`. A run without the absent CLI does not call it stale.
+  WC-MCP-9 and WC-ACCT-1 say so. See [#390](https://github.com/WireCatLabs/cli-base/issues/390).
+
+## 0.68.0 — 31.10.2026
+
+### Removed
+
+- **WC-REL-10: a messenger CLI is released after the owner's yes in the conversation, with no signed report.**
+  `bin/release` in max-cli and whatsapp-cli no longer reads a release report or a `Signed off:` line. The agent asks
+  the owner before it runs `bin/release`; one yes covers one version.
+
+### Changed — may break callers
+
+- **`Credentials` in `auto` does the whole file fallback itself (WC-SECR-4).** A secret the file holds is read from the
+  file before the keyring, so a locked keyring is not tried for it, and a refresh `write` keeps it there. A sign-in
+  passes `write(account, secret, { signIn: true })`: it tries the keyring and, once the keyring takes it, removes the
+  file copy. The "could not reach the OS keyring" warning comes once per run (per `env` object), not once per
+  `Credentials`. Watch for: a file copy left next to a newer keyring entry by an older CLI now wins the read; sign in
+  again to move it back. CLIs can drop their own file-first read, "remove the file copy" step and `warnOnce`.
+- **WC-SECR-4 is the one credential-storage standard.** The keyring by default; when it fails, the file without
+  asking, one warning on stderr, and the answer that saved the secret says where it went;
+  `--credential-storage file` on the sign-in command chooses the file and is discouraged; a secret in the file is
+  read from there until a sign-in reaches the keyring again. No CLI asks, none is keyring-only. `Credentials` already
+  falls back this way in `auto`; the rule now says every CLI must use it.
+
+### Fixed
+
+- **`Credentials.remove` with `storage: "keyring"` leaves the file alone.** It also deleted the account from the
+  credentials file, so a CLI that cleared the keyring copy after a file sign-in lost the sign-in it had just saved.
+
+### Added
+
+- **`--credential-storage <storage>` in the flag vocabulary** (role `mode`), so `cli-dev lint` accepts it on a sign-in
+  command without a per-CLI override.
+
 ## 0.67.0 — 31.10.2026
 
 ### Added

package/dist/credentials.d.ts

@@ -38,17 +38,25 @@ export declare const keyringService: (service: string, _configDir?: string, _iso
  * shape `bin/keyring-dedupe` already finds and removes.
  */
 export declare const movedRunService: (service: string, configDir: string) => string;
+export interface WriteOptions {
+    /**
+     * A new sign-in rather than a refresh: it tries the keyring even when the file holds the account, and once the
+     * keyring takes it, removes the file copy (WC-SECR-4).
+     */
+    signIn?: boolean;
+}
 /**
- * Environment first, then the OS keyring, then a file.
+ * Environment first, then the OS keyring, then a file. In `auto`, a file that holds the account is read before the
+ * keyring and keeps its refreshes, so a locked keyring is not tried again for it; a sign-in moves it back.
  *
  * `auto` does not probe whether a keyring exists: it attempts the operation, and on failure warns
- * once and falls through. A probe would touch the user's keychain for nothing and could still
+ * once per run and falls through. A probe would touch the user's keychain for nothing and could still
  * succeed where the real operation fails.
  */
 export declare class Credentials {
     #private;
     constructor(options: CredentialsOptions);
     read(account: string): StoredCredential | undefined;
-    write(account: string, secret: string): CredentialSource;
+    write(account: string, secret: string, options?: WriteOptions): CredentialSource;
     remove(account: string): CredentialSource[];
 }

package/dist/credentials.js

@@ -15,11 +15,14 @@ export const keyringService = (service, _configDir, _isolated) => service;
  * shape `bin/keyring-dedupe` already finds and removes.
  */
 export const movedRunService = (service, configDir) => `${service}:${resolve(configDir)}`;
+// One warning per run, not per instance: a run over several profiles builds one Credentials for each.
+const warnedRuns = new WeakSet();
 /**
- * Environment first, then the OS keyring, then a file.
+ * Environment first, then the OS keyring, then a file. In `auto`, a file that holds the account is read before the
+ * keyring and keeps its refreshes, so a locked keyring is not tried again for it; a sign-in moves it back.
  *
  * `auto` does not probe whether a keyring exists: it attempts the operation, and on failure warns
- * once and falls through. A probe would touch the user's keychain for nothing and could still
+ * once per run and falls through. A probe would touch the user's keychain for nothing and could still
  * succeed where the real operation fails.
  */
 export class Credentials {
@@ -33,7 +36,6 @@ export class Credentials {
     #warn;
     /** Set only for a moved run with the system keyring. */
     #temporaryService;
-    #warned = false;
     constructor(options) {
         this.#configDir = options.configDir;
         this.#storage = options.storage ?? "auto";
@@ -50,23 +52,29 @@ export class Credentials {
         const fromEnv = this.#envVar ? this.#env[this.#envVar]?.trim() : undefined;
         if (fromEnv)
             return { secret: fromEnv, source: "environment" };
+        const fromFile = this.#storage === "keyring" ? undefined : this.#readFile()?.[account]?.secret;
+        if (fromFile)
+            return { secret: fromFile, source: "file" };
         if (this.#storage !== "file") {
             const temporary = this.#temporaryService;
             const fromKeyring = this.#tryKeyring(() => (temporary && this.#keyring.get(temporary, account)) || this.#keyring.get(this.#service, account));
             if (fromKeyring)
                 return { secret: fromKeyring, source: "keyring" };
         }
-        const secret = this.#readFile()?.[account]?.secret;
-        return secret ? { secret, source: "file" } : undefined;
+        return undefined;
     }
-    write(account, secret) {
-        if (this.#storage !== "file") {
+    write(account, secret, options = {}) {
+        const inFile = this.#storage === "auto" && this.#readFile()?.[account] !== undefined;
+        if (this.#storage === "keyring" || (this.#storage === "auto" && (options.signIn || !inFile))) {
             const stored = this.#tryKeyring(() => {
                 this.#keyring.set(this.#temporaryService ?? this.#service, account, secret);
                 return true;
             });
-            if (stored)
+            if (stored) {
+                if (inFile)
+                    this.#removeFromFile(account);
                 return "keyring";
+            }
         }
         const store = this.#readFile();
         if (!store) {
@@ -91,14 +99,18 @@ export class Credentials {
                         "moved folders never removes it");
             }
         }
-        const store = this.#readFile();
-        if (store?.[account] !== undefined) {
-            delete store[account];
-            this.#writeFile(store);
+        if (this.#storage !== "keyring" && this.#removeFromFile(account))
             removed.push("file");
-        }
         return removed;
     }
+    #removeFromFile(account) {
+        const store = this.#readFile();
+        if (store?.[account] === undefined)
+            return false;
+        delete store[account];
+        this.#writeFile(store);
+        return true;
+    }
     /** Only for the warning: a keyring that fails here must not fail a removal that already happened. */
     #ownersEntryExists(account) {
         try {
@@ -141,8 +153,8 @@ export class Credentials {
             return operation();
         }
         catch (error) {
-            if (!this.#warned) {
-                this.#warned = true;
+            if (!warnedRuns.has(this.#env)) {
+                warnedRuns.add(this.#env);
                 this.#warn(`could not reach the OS keyring — it may be locked, or no keyring service is running ` +
                     `(${error instanceof Error ? error.message : String(error)}); ` +
                     `using ${this.#path()} instead, readable only by you`);

package/dist/dev/audit.d.ts

@@ -26,6 +26,8 @@ export interface Finding {
     /** `<clis> <what>`: `max+tg chats list --limit`, `zm upgrade`, `tg: chats grab` for a lint violation. */
     target: string;
     message: string;
+    /** What each CLI showed, for a finding about one flag or output; `absent` when it lacks the flag. */
+    values?: Record<string, string>;
 }
 export interface ScoreRow {
     cli: string;

package/dist/dev/audit.js

@@ -74,6 +74,7 @@ const samePathContract = (inputs, groups) => {
                     clis: having,
                     target: `${named(having)} ${path}${what}`,
                     message: describe(values),
+                    values: Object.fromEntries(values),
                 });
         };
         const kinds = new Map([...commands].map(([cli, command]) => [
@@ -253,18 +254,35 @@ export const auditClis = (inputs, options, rules = AUDIT_RULES) => {
         options.capabilities &&
         capabilityDifference(finding.target, finding.clis, inputs.map((input) => input.document), options.capabilities))
         .map((finding) => `${finding.rule} ${finding.target}`));
-    const declared = new Map(options.groups.flatMap((group) => group.differences.map((entry) => [`${entry.rule} ${entry.target}`, group.name])));
+    // An `absent` difference names no CLI list: it stands for every finding where only that CLI lacks the flag.
+    const differences = options.groups.flatMap((group) => group.differences.flatMap((entry) => {
+        if (!entry.absent)
+            return [{ group: group.name, ...entry }];
+        const matching = findings.filter((finding) => {
+            if (finding.rule !== entry.rule || finding.target !== `${named(finding.clis)} ${entry.target}`)
+                return false;
+            const others = Object.entries(finding.values ?? {}).filter(([cli]) => cli !== entry.absent);
+            return (finding.values?.[entry.absent] === "absent" && new Set(others.map(([, value]) => value)).size === 1);
+        });
+        if (matching.length === 0 && clis.includes(entry.absent))
+            problems.push(`stale difference in ${group.name}, no such divergence — remove it: ${entry.rule} ${entry.target} (absent in ${entry.absent})`);
+        return matching.map((finding) => ({
+            ...entry,
+            group: group.name,
+            target: finding.target,
+            expected: finding.message,
+        }));
+    }));
+    const declared = new Map(differences.map((entry) => [`${entry.rule} ${entry.target}`, entry.group]));
     const found = new Set(findings.map((finding) => `${finding.rule} ${finding.target}`));
     for (const [key, group] of declared)
         if (!found.has(key))
             problems.push(`stale difference in ${group}, no such divergence — remove it: ${key}`);
-    for (const group of options.groups) {
-        for (const difference of group.differences) {
-            const finding = findings.find((one) => one.rule === difference.rule && one.target === difference.target);
-            if (finding && difference.expected !== finding.message) {
-                declared.delete(`${difference.rule} ${difference.target}`);
-                problems.push(`difference in ${group.name} must match the exact current values: ${difference.rule} ${difference.target}`);
-            }
+    for (const difference of differences) {
+        const finding = findings.find((one) => one.rule === difference.rule && one.target === difference.target);
+        if (finding && difference.expected !== finding.message) {
+            declared.delete(`${difference.rule} ${difference.target}`);
+            problems.push(`difference in ${difference.group} must match the exact current values: ${difference.rule} ${difference.target}`);
         }
     }
     for (const group of options.groups)

package/dist/dev/main.js

@@ -575,7 +575,8 @@ const auditRun = (args, io) => {
             group: v.string(),
             rule: v.string(),
             target: v.string(),
-            expected: v.string(),
+            expected: v.optional(v.string()),
+            absent: v.optional(v.string()),
             reason: v.string(),
         }));
         const parsed = v.safeParse(schema, readJson(at(values.differences)));

package/dist/index.d.ts

@@ -1,6 +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 type { CredentialSource, CredentialStorage, CredentialsOptions, StoredCredential } from "./credentials.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";
 export { CliError, type CliErrorDetails, type ErrorCode, errorCodes, isCliError } from "./errors.js";

package/dist/standards/audit.d.ts

@@ -22,8 +22,11 @@ declare const parityGroupSchema: v.StrictObjectSchema<{
     /** Permanent differences, each with its reason; they count against the override budget of the group. */
     readonly differences: v.ArraySchema<v.StrictObjectSchema<{
         readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a lower-case word, words joined by -">]>;
+        /** `<clis> <path> <flag>`; with `absent`, only `<path> <flag>`: the CLI list is whoever else has it. */
         readonly target: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
         readonly expected: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        /** The CLI that lacks the path or flag by design; the rest must agree, so other CLIs joining do not stale it. */
+        readonly absent: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a lower-case word, words joined by -">]>, undefined>;
         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">]>;
     }, undefined>, undefined>;
 }, undefined>;

package/dist/standards/audit.js

@@ -51,14 +51,22 @@ const parityGroupSchema = v.strictObject({
     /** Permanent differences, each with its reason; they count against the override budget of the group. */
     differences: v.array(v.strictObject({
         rule: word,
+        /** `<clis> <path> <flag>`; with `absent`, only `<path> <flag>`: the CLI list is whoever else has it. */
         target: text,
         expected: v.optional(text),
+        /** The CLI that lacks the path or flag by design; the rest must agree, so other CLIs joining do not stale it. */
+        absent: v.optional(word),
         reason: v.pipe(text, v.minLength(10, "say why, in a sentence")),
     })),
 });
 export const defineParityGroups = (input) => parseRegistry("parity groups", v.array(parityGroupSchema), input, (groups) => [
     ...duplicates(groups.map((group) => group.name)).map((name) => `"${name}" is listed twice`),
-    ...groups.flatMap((group) => duplicates(group.differences.map((entry) => `${entry.rule} ${entry.target}`)).map((both) => `${group.name}: "${both}" is listed twice`)),
+    ...groups.flatMap((group) => [
+        ...duplicates(group.differences.map((entry) => `${entry.rule} ${entry.target}`)).map((both) => `${group.name}: "${both}" is listed twice`),
+        ...group.differences
+            .filter((entry) => entry.absent && entry.expected)
+            .map((entry) => `${group.name}: "${entry.target}" has \`absent\`, which measures the values itself; drop \`expected\``),
+    ]),
 ]);
 export const PARITY_GROUPS = defineParityGroups([
     { name: "messengers", members: ["tg", "max"], covers: "tree", differences: [] },
@@ -66,7 +74,13 @@ export const PARITY_GROUPS = defineParityGroups([
         name: "all",
         members: ["tg", "max", "memo", "drive", "zm", "wa", "mail"],
         covers: ["commands", "doctor", "skill", "mcp", "upgrade", "search", "notes", "meetings"],
-        differences: [],
+        differences: ["mcp serve", "mcp revoke", "mcp server start", "mcp server status", "mcp server stop"].map((path) => ({
+            rule: "same-path-contract",
+            target: `${path} --profiles`,
+            absent: "memo",
+            reason: "memo has no profiles: it reads other CLIs' stores and selects their accounts with --source and --account " +
+                "(https://github.com/WireCatLabs/cli-base/issues/390)",
+        })),
     },
     // gcal is compared on what it already shares with every CLI; doctor, mcp, search and skill wait until the published
     // CLIs agree there (https://github.com/WireCatLabs/cli-base/issues/390), then gcal moves back into "all".

package/dist/standards/flags-how.js

@@ -375,6 +375,13 @@ export const HOW_FLAGS = [
         type: "string",
         meaning: "the browser program to open for sign-in",
     },
+    {
+        name: "--credential-storage",
+        value: "<storage>",
+        role: "mode",
+        type: "choice",
+        meaning: "where a sign-in is kept: keyring, which falls back to a private file by itself, or file (WC-SECR-4)",
+    },
     { name: "--checkpoint", value: "<file>", role: "mode", type: "path", meaning: "keep resume progress in this file" },
     {
         name: "--expected-event-id",

package/docs/standards/README.md

@@ -42,7 +42,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 | [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 |
 | [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, release reports, trusted publishing |
+| [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 |
 | [Time](time.md) | `TIME` | 6 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone |
 | [Style](style.md) | `STYLE` | 10 | Comments, TypeScript habits, commit messages |

package/docs/standards/accounts.md

@@ -14,7 +14,9 @@ Rule ids on this page are `WC-ACCT-<n>`. How to read a rule, how ids work and wh
 ### Who follows these rules today
 
 cli-core resolves the profile for tg, max and wa. WC-ACCT-1 needs cli-core 0.319.0 or newer. memo has no messenger profile: its shared commands run without one, and they pick accounts with `--provider`
-and `--account` (WC-ACCT-7). zoom resolves its own profile word by the same rules (`zm <profile> …`, `ZM_PROFILE`,
+and `--account` (WC-ACCT-7). memo never creates profiles of its own: it reads the stores of other CLIs and selects
+their accounts with `--source email:<name>` or `--account telegram:1`, so it has no `--profiles` either
+([cli-base#390](https://github.com/WireCatLabs/cli-base/issues/390), owner decision 2026-10-31). zoom resolves its own profile word by the same rules (`zm <profile> …`, `ZM_PROFILE`,
 `ZM_PROFILE_LOCK`) from zoom-cli 0.35.0, with cli-core's `liftProfile` and `usableProfileName`. drive still has its own
 profile code: it registers its own profiles. That is a known gap, not an exception. gcal resolves the profile through
 cli-core's `run()`, like tg, max and wa. Which CLIs lack a sign-in command of WC-ACCT-12 is listed in that rule.
@@ -48,7 +50,8 @@ profile.
 - **Example:** `max work bot messages send …` uses the same first word as `max work chats list`. `tg --json chats list`
   still works, because `--json` is an option.
 - **Exceptions:** `mcp serve --profiles <names|all>` names the profiles one server serves ([WC-MCP-9](mcp.md#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each)). It is used in
-  place of the first word, never with it.
+  place of the first word, never with it. memo has no profiles of its own, so it has neither the first word nor
+  `--profiles`; it selects the accounts of other CLIs with `--source` and `--account`.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-84, NEED-294, NEED-1881.
 
 ### WC-ACCT-3 · A missing profile is an error that lists the choices

package/docs/standards/mcp.md

@@ -155,7 +155,11 @@ and lists the profiles served. Each call follows its own profile's permissions.
 - **Example:** `max work mcp serve`, `max mcp serve --profiles work,personal` or `max mcp serve --profiles all`.
   Under the last two, a call reads `max_read { "profile": "work", "command": "inbox", "arguments": {} }`.
   `max mcp serve` alone is refused, and its message lists `personal` and `work`.
-- **Exceptions:** the bot server needs no held connection: each Bot API call is plain HTTPS.
+- **Exceptions:** the bot server needs no held connection: each Bot API call is plain HTTPS. memo has no profiles of
+  its own, so `--profiles` stays absent on its `mcp serve`, `mcp revoke` and `mcp server start`, `status` and `stop`;
+  it reads other CLIs' stores and selects their accounts with `--source email:<name>` or `--account telegram:1`
+  ([cli-base#390](https://github.com/WireCatLabs/cli-base/issues/390), owner decision 2026-10-31). The audit declares
+  this once, as a difference of memo, not of the other CLIs.
 - **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1881.
 
 ### WC-MCP-10 · A tool and its command give the same answer and the same error

package/docs/standards/releases.md

@@ -4,7 +4,7 @@
 
 ## Scope
 
-How a CLI is released: `bin/release`, the release lock, version numbers, the release report and trusted publishing.
+How a CLI is released: `bin/release`, the release lock, version numbers, the owner's yes and trusted publishing.
 
 Rule ids on this page are `WC-REL-<n>`. How to read a rule, how ids work and which rule wins are in the
 [index](README.md). The changelog a release dates is on the [Documents](docs.md) page. The checks a release runs are
@@ -106,17 +106,16 @@ on the [CI](ci.md) page.
 
 ### WC-REL-9 · Merged into [WC-REL-8](#wc-rel-8--any-package-may-release-at-any-time)
 
-### WC-REL-10 · A messenger CLI is released only with a release report the owner signed for that commit
-
-- **Why:** the judgement half of a release (changelog wording, docs against the change, live checks) has no other
-  record that it ran for this exact commit.
-- **Enforced by:** `max-cli: bin/release` · `whatsapp-cli: bin/release`.
-- **Example:** max-cli's and whatsapp-cli's `bin/release` refuse unless the report has `Commit: <HEAD>` and
-  `Signed off: <date>`. When `bin/release` only renumbers or folds the changelog, it carries the report to the new
-  commit. A fork passes its own report with `bin/release --report <path>`.
-- **Exceptions:** none. max-cli and whatsapp-cli (from 0.1.0) check the report in `bin/release`. tg-cli has the
-  release skill, but its `bin/release` does not check a report yet.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+### WC-REL-10 · A messenger CLI is released only after the owner says yes in the conversation
+
+- **Why:** a messenger CLI acts on the owner's own accounts, so the owner decides when a new version ships. A signed
+  release report added a step without adding a check: the owner removed it on 2026-10-31 ("remove the signing
+  requirements instead just ask").
+- **Enforced by:** review only.
+- **Example:** the agent finishes the release skill, then asks "release max 0.91.0?". It runs `bin/release` only after
+  the owner says yes for that version. One yes covers one version.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** owner, 2026-10-31.
 
 ### WC-REL-11 · Publish from GitHub Actions with npm trusted publishing
 

package/docs/standards/security.md

@@ -67,19 +67,31 @@ name. Any other top-level key is written as `[not allowed]`. A key that names co
 ### WC-SECR-4 · Secrets come from the environment, then the OS keyring, then a private file
 
 cli-base's `Credentials` reads the environment variable first (for CI), then the OS keyring, then a file with mode
-`0600`. The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
+`0600` in the CLI's own folder. Storage is the keyring by default (`auto`): when the keyring fails (locked, not
+running, no D-Bus), the CLI uses the file without asking, warns once on stderr, and the answer that saved the secret
+says where it went (gcal: `credential_storage: "file"`). `--credential-storage file` on the sign-in command chooses
+the file outright; help and docs discourage it. Once the file holds a secret, it is read from the file, so a locked
+keyring is not tried again for it; the next sign-in that reaches the keyring moves it back and removes the file copy.
+`Credentials` in `auto` does all of this: the CLI passes `{ signIn: true }` to `write` for a new sign-in and nothing
+for a refresh.
+No CLI asks which store to use, and none is keyring-only.
+The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
 the command word people type (`max`, `gcal`). A run with moved folders reads the same entry, writes a temporary one,
 and never replaces or deletes the owner's
 ([WC-SECR-24](#wc-secr-24--a-run-with-moved-folders-shares-the-owners-keyring-entry-and-never-deletes-it)).
 
-- **Why:** the keyring is the safest store on the computer.
+- **Why:** the keyring is the safest store on the computer, and a sign-in that fails on a server or in a container
+  because no keyring runs there is a broken CLI, not a safe one.
 - **Enforced by:** `src/credentials.test.ts`.
 - **Example:** a bot token is read from `MAX_BOT_TOKEN`, then the keyring entry `bot:<profile>`, then the file.
-- **Exceptions:** `auto` storage tries the keyring and, when it fails, warns once on stderr and uses the file. A
-  messenger library's own device store, which the library opens as a file and which cannot live in the keyring
-  (WhatsApp's `private.db`), is an owner-only file under
-  [WC-SECR-10](#wc-secr-10--private-files-are-written-atomically-with-private-modes) instead.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-295.
+  `gcal personal session start` on a computer without a keyring signs in, warns once, and answers
+  `credential_storage: "file"`.
+- **Exceptions:** a messenger library's own device store, which the library opens as a file and which cannot live in
+  the keyring (WhatsApp's `private.db`, tg's session file), is an owner-only file under
+  [WC-SECR-10](#wc-secr-10--private-files-are-written-atomically-with-private-modes) instead. A copy between two
+  profiles that must land in the keyring (cli-core's bot transfer) may use `storage: "keyring"`.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-295; owner, 2026-10-31 (never ask, keyring
+  by default, fall back to a file on error, a discouraged flag for the file).
 
 ### WC-SECR-5 · A secret is never taken on the command line
 

package/package.json

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