@wirecat/cli-base 0.55.1 → 0.56.0

package/CHANGELOG.md

@@ -8,6 +8,44 @@ 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.56.0 — 25.10.2026
+
+### Added
+
+- **`<cli> skill show --for claude|agents` prints the copy installed for that agent** instead of this version's
+  SKILL.md, as text or `{ name, target, path, installed, content }` with `--json`. A host could show only the bundled
+  copy and `skill status`'s version numbers, so it could not show what `skill install` would change; now it reads
+  both and compares them. It reads only, fails with `not_found` and the install command when the agent has no copy,
+  and refuses a shipped skill by name, which is never installed.
+
+- **`removeStdioEntry` and `stdioEntryStatus` in `@wirecat/cli-base/mcp`** undo and read what `installStdioEntry`
+  writes. A CLI could add itself to Codex or Claude Code, but not take itself out or say whether it is there, so a
+  host such as WireCat Desktop had to read each client's configuration on its own. `removeStdioEntry(client, name)`
+  runs the client's own `mcp remove`, for Claude Code with `--scope user` (the scope `add` uses), so a project's entry
+  with the same name stays; a name the client does not have returns `removed: false`. `stdioEntryStatus(client,
+  name)` returns `registered`, `missing`, or `unavailable` when the client is not installed. Both go through the
+  client's `mcp get` first and refuse a name that is not letters, digits, `_` or `-`.
+
+- **Every CLI keeps a run log: `WC-LIFE-15` and the `missing-run-log` lint rule**
+  ([Lifecycle](docs/standards/lifecycle.md#wc-life-15--keep-a-run-log-through-cli-core-and-read-it-back-with-runs)).
+  The handbook described what a log may hold but never required one, and drive, memo and zm shipped without a run
+  log. `cli-dev lint` now fails a CLI whose command tree has no `runs list` or `runs show`, or no global `--record` or
+  `--no-record`. With `--cli`, it also runs the built CLI once with an unknown flag, in a new empty home with none of
+  the caller's environment but `PATH`, and fails when `runs list --json` then shows no failed run. A CLI without
+  `runs` gets the finding on its next cli-base bump: register cli-core's `runsCommand(app)`, or baseline the
+  finding with `cli-dev lint --write-baseline` until it does. The weekly cross-CLI audit lists it too.
+
+- **`<cli> skill status` says whether the installed SKILL.md is current, for each agent.** It reads
+  `~/.claude/skills/<appName>/SKILL.md` and `~/.agents/skills/<appName>/SKILL.md` and prints, per place, the absolute
+  path, the version installed there (`null` when there is none) and a `state`: `current`, `stale` (older than the
+  CLI), `missing` or `unversioned`. It writes nothing. A desktop app or a setup script could tell this only by reading
+  the files itself. `skillStatus(app, env)` returns the same list, and the daily skill hint now decides from it, with
+  the same outcome as before. A CLI on cli-core gets the command when cli-core picks up this release.
+
+- **The collection noun `tables`: "the tables of the local store, with their kind, row count and size".** cli-core's
+  `store tables list` uses it to answer which tables the shared archive holds, so a desktop app or an agent can see
+  them without opening the file. `copies` keeps its narrower meaning, the tables a repair kept aside.
+
 ## 0.55.1 — 25.10.2026
 
 ### Fixed

package/README.md

@@ -180,7 +180,8 @@ operation and never falls back to `any`. 64-bit integers stay exact.
 
 ### Built for agents and for keeping installs current
 
-- **`skill show` and `skill install`** give a coding agent the CLI's own guide, versioned with the CLI.
+- **`skill show` and `skill install`** give a coding agent the CLI's own guide, versioned with the CLI; `skill status`
+  says whether each installed copy matches it.
 - **MCP setup** for Codex and Claude Code, with a read-only handshake probe.
 - **Shell completion** from the command tree, answered from local data only — a shell asks on every Tab.
 - **Update checks that never update unasked.** Which package manager installed the CLI, the command that updates it,

package/dist/dev/lint.d.ts

@@ -21,7 +21,17 @@ export interface LintContext {
      * `log_attributes` (`logAttributesJsonSchema(allow)`) is the CLI's log allow-list, for `log-attribute-key`.
      */
     schemas?: Readonly<Record<string, unknown>>;
+    /** What `cli-dev lint --cli` saw when it made the built CLI fail once in an empty home; absent with `--commands`. */
+    runLog?: RunLogProbe;
 }
+export interface RunLogProbe {
+    kept: boolean;
+    /** Why no failed run was found, when none was. */
+    detail?: string;
+}
+/** The run log's reader and its switches; what `runsCommand` and cli-core's shared program add. */
+export declare const RUN_LOG_COMMANDS: readonly ["runs list", "runs show"];
+export declare const RUN_LOG_FLAGS: readonly ["--record", "--no-record"];
 /** The schemas cli-base itself defines; every CLI's lint checks them too. */
 export declare const baseSchemas: () => Record<string, unknown>;
 /** Splits an example the way a shell would for the quoting examples use: '…', "…" and a backslash. */

package/dist/dev/lint.js

@@ -25,6 +25,9 @@ export const kindOf = (option) => {
 };
 export const summaryOf = (command) => (command.summary ?? command.description.split("\n")[0] ?? "").trim();
 const label = (command) => command.path.join(" ");
+/** The run log's reader and its switches; what `runsCommand` and cli-core's shared program add. */
+export const RUN_LOG_COMMANDS = ["runs list", "runs show"];
+export const RUN_LOG_FLAGS = ["--record", "--no-record"];
 /** The `--schemas` entry holding the CLI's log allow-list; its keys are camelCase, so `key-casing` skips it. */
 const LOG_ATTRIBUTES = "log_attributes";
 /** The schemas cli-base itself defines; every CLI's lint checks them too. */
@@ -395,6 +398,28 @@ const CHECKS = {
             message: `"${key}" names content or a secret, which no log may carry`,
         }));
     },
+    "missing-run-log": (document, _vocabulary, context) => {
+        const paths = new Set(walk(document.commands).map(label));
+        const flags = new Set(document.global_options.flatMap(optionNames));
+        return [
+            ...RUN_LOG_COMMANDS.filter((path) => !paths.has(path)).map((path) => ({
+                target: path,
+                message: `no \`${path}\`: register cli-core's \`runsCommand(app)\`, so a person can read what a run did`,
+            })),
+            ...RUN_LOG_FLAGS.filter((flag) => !flags.has(flag)).map((flag) => ({
+                target: flag,
+                message: `no global ${flag}: run the program through cli-core's \`run\`, or add the flag at the root`,
+            })),
+            ...(context.runLog && !context.runLog.kept
+                ? [
+                    {
+                        target: "runs",
+                        message: `a failing command left no failed run: ${context.runLog.detail ?? "none listed"}`,
+                    },
+                ]
+                : []),
+        ];
+    },
 };
 export const lintRuleIds = () => Object.keys(CHECKS);
 /** Every violation, one per rule and target, sorted. Generated commands keep the names of the API they mirror. */

package/dist/dev/main.d.ts

@@ -1,3 +1,4 @@
+import { type RunLogProbe } from "./lint.js";
 export interface DevIo {
     cwd: string;
     /** The clock an override's `review_after` is judged by. */
@@ -5,4 +6,10 @@ export interface DevIo {
     out: (text: string) => void;
     err: (text: string) => void;
 }
+/**
+ * Makes the built CLI fail once on an unknown flag and asks its own `runs list --json` whether that failure was
+ * kept. The CLI sees a new empty home and nothing else from this environment: a stray `*_STATE_DIR` or
+ * `XDG_STATE_HOME` would point it at the owner's real runs.
+ */
+export declare const probeRunLog: (cwd: string, bin: string, environment?: NodeJS.ProcessEnv) => RunLogProbe;
 export declare const main: (argv: readonly string[], io: DevIo) => Promise<number>;

package/dist/dev/main.js

@@ -3,7 +3,8 @@
  * reads and writes under `cwd` and reports through `out` and `err`; `main` returns the exit code.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { isAbsolute, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
@@ -20,7 +21,7 @@ import { VOCABULARY } from "../standards/vocabulary.js";
 import { auditClis, scorecardTable, snakeKeys } from "./audit.js";
 import { readCapabilities } from "./capabilities.js";
 import { changelogChange, landChange, landFold, newestTag, processShell, restoreChange } from "./land.js";
-import { baselineOf, judge, lintCommands } from "./lint.js";
+import { baselineOf, judge, lintCommands, RUN_LOG_COMMANDS, walk } from "./lint.js";
 import { nextVersion } from "./next-version.js";
 import { slowTests } from "./slow-tests.js";
 import { matrixPage, matrixRows, parseArgvLog } from "./test-matrix.js";
@@ -238,6 +239,52 @@ const commandsJson = (io, cli, file, commandArgs = ["commands", "--json"]) => {
         throw new Error(`${bin} commands --json failed: ${run.error?.message ?? String(run.stderr).trim().split("\n")[0]}`);
     return JSON.parse(String(run.stdout));
 };
+const PROBE_FLAG = "--cli-dev-run-log-probe";
+/**
+ * Makes the built CLI fail once on an unknown flag and asks its own `runs list --json` whether that failure was
+ * kept. The CLI sees a new empty home and nothing else from this environment: a stray `*_STATE_DIR` or
+ * `XDG_STATE_HOME` would point it at the owner's real runs.
+ */
+export const probeRunLog = (cwd, bin, environment = process.env) => {
+    const home = mkdtempSync(join(tmpdir(), "cli-dev-run-log-"));
+    const env = {
+        PATH: environment.PATH ?? "",
+        HOME: home,
+        USERPROFILE: home,
+        APPDATA: join(home, "AppData", "Roaming"),
+        LOCALAPPDATA: join(home, "AppData", "Local"),
+        CI: "true",
+        ...(environment.SystemRoot ? { SystemRoot: environment.SystemRoot } : {}),
+    };
+    const script = /\.[cm]?js$/.test(bin);
+    const call = (args) => spawn.sync(script ? process.execPath : bin, [...(script ? [bin] : []), ...args], {
+        cwd,
+        env,
+        encoding: "utf8",
+        timeout: 60_000,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    try {
+        const failed = call([PROBE_FLAG]);
+        if (failed.status === 0)
+            return { kept: false, detail: `\`${PROBE_FLAG}\` did not fail, so nothing could be kept` };
+        const listed = call(["runs", "list", "--json"]);
+        if (listed.status !== 0)
+            return { kept: false, detail: `\`runs list --json\` exited ${listed.status ?? listed.error?.message}` };
+        let items;
+        try {
+            items = JSON.parse(String(listed.stdout)).items;
+        }
+        catch {
+            return { kept: false, detail: "`runs list --json` did not print JSON" };
+        }
+        const kept = Array.isArray(items) && items.some((item) => item?.status === "failed");
+        return kept ? { kept } : { kept, detail: `\`runs list --json\` shows no failed run after \`${PROBE_FLAG}\`` };
+    }
+    finally {
+        rmSync(home, { recursive: true, force: true });
+    }
+};
 const readBaseline = (dir, label, problems) => {
     const baseline = {};
     if (existsSync(dir))
@@ -316,9 +363,12 @@ const lintRun = (args, io) => {
         io.err(`${values.schemas}: a JSON object of JSON Schemas by name`);
         return 2;
     }
+    const paths = new Set(walk(parsed.document.commands).map((command) => command.path.join(" ")));
+    const hasRuns = RUN_LOG_COMMANDS.every((path) => paths.has(path));
     const violations = lintCommands(parsed.document, VOCABULARY, LINT_RULES, {
         raw,
         schemas: schemas,
+        ...(values.cli && hasRuns ? { runLog: probeRunLog(io.cwd, values.cli) } : {}),
     });
     const severity = new Map(LINT_RULES.map((rule) => [rule.id, rule.severity]));
     if (values["write-baseline"]) {

package/dist/mcp/index.d.ts

@@ -14,6 +14,25 @@ export interface CommandResult {
 }
 export type RunCommand = (file: string, args: string[]) => CommandResult;
 export declare const setupArguments: (client: McpClient, name: string, entry: StdioEntry) => string[];
+/** `unavailable`: the client is not installed here, or could not be started. */
+export type StdioEntryState = "registered" | "missing" | "unavailable";
+/** Whether the client has a server by this name; reads only, through the client's own `mcp get`. */
+export declare const stdioEntryStatus: (client: McpClient, name: string, { run }?: {
+    run?: RunCommand;
+}) => {
+    client: McpClient;
+    name: string;
+    state: StdioEntryState;
+};
+export declare const removeArguments: (client: McpClient, name: string) => string[];
+/** Takes out what `installStdioEntry` added; a name the client does not have is left alone and reported. */
+export declare const removeStdioEntry: (client: McpClient, name: string, { run }?: {
+    run?: RunCommand;
+}) => {
+    client: McpClient;
+    name: string;
+    removed: boolean;
+};
 export declare const installStdioEntry: (client: McpClient, name: string, entry: StdioEntry, { run }?: {
     run?: RunCommand;
 }) => {

package/dist/mcp/index.js

@@ -10,26 +10,60 @@ const realRun = (file, args) => {
     return { status: result.status, error: result.error, stdout: result.stdout ?? "", stderr: result.stderr ?? "" };
 };
 const executable = (client) => (client === "codex" ? "codex" : "claude");
+const presentIn = (client, name, run) => {
+    const state = lookUp(client, name, run);
+    if (state === "unavailable")
+        throw new Error(`${executable(client)} is not installed or could not be started`);
+    return state === "registered";
+};
 export const setupArguments = (client, name, entry) => {
     const variables = Object.entries(entry.env ?? {}).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
     if (client === "codex")
         return ["mcp", "add", name, ...variables, "--", entry.command, ...entry.args];
     return ["mcp", "add", "--scope", "user", name, ...variables, "--", entry.command, ...entry.args];
 };
-export const installStdioEntry = (client, name, entry, { run = realRun } = {}) => {
+const checkName = (name) => {
     if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name))
         throw new Error("the MCP name must be letters, digits, _ or -");
-    if (!entry.command || entry.args.some((arg) => arg.includes("\0")))
-        throw new Error("invalid MCP command");
+};
+const lookUp = (client, name, run) => {
     const file = executable(client);
     const existing = run(file, ["mcp", "get", name, ...(client === "codex" ? ["--json"] : [])]);
     if (existing.error)
-        throw new Error(`${file} is not installed or could not be started`);
+        return "unavailable";
     if (existing.status === 0)
-        throw new Error(`${name} is already configured in ${file}; remove it there first`);
-    if (existing.status !== 0 && !/No MCP server named/i.test(existing.stdout + existing.stderr)) {
+        return "registered";
+    if (!/No MCP server named/i.test(existing.stdout + existing.stderr)) {
         throw new Error(`${file} could not check its MCP configuration`);
     }
+    return "missing";
+};
+/** Whether the client has a server by this name; reads only, through the client's own `mcp get`. */
+export const stdioEntryStatus = (client, name, { run = realRun } = {}) => {
+    checkName(name);
+    return { client, name, state: lookUp(client, name, run) };
+};
+export const removeArguments = (client, name) => 
+// Claude Code without a scope removes from whichever scope holds the name, which may be a project's own entry.
+client === "codex" ? ["mcp", "remove", name] : ["mcp", "remove", "--scope", "user", name];
+/** Takes out what `installStdioEntry` added; a name the client does not have is left alone and reported. */
+export const removeStdioEntry = (client, name, { run = realRun } = {}) => {
+    checkName(name);
+    if (!presentIn(client, name, run))
+        return { client, name, removed: false };
+    const file = executable(client);
+    const removed = run(file, removeArguments(client, name));
+    if (removed.status !== 0 || removed.error)
+        throw new Error(`${file} could not remove ${name}`);
+    return { client, name, removed: true };
+};
+export const installStdioEntry = (client, name, entry, { run = realRun } = {}) => {
+    checkName(name);
+    if (!entry.command || entry.args.some((arg) => arg.includes("\0")))
+        throw new Error("invalid MCP command");
+    const file = executable(client);
+    if (presentIn(client, name, run))
+        throw new Error(`${name} is already configured in ${file}; remove it there first`);
     const args = setupArguments(client, name, entry);
     const added = run(file, args);
     if (added.status !== 0 || added.error)

package/dist/skill/index.d.ts

@@ -25,6 +25,16 @@ export declare const installSkill: (app: SkillApp, skill: URL, { targets, env }?
     targets?: readonly SkillTarget[];
     env?: Env;
 }) => string[];
+export type SkillState = "current" | "stale" | "missing" | "unversioned";
+export interface SkillTargetStatus {
+    target: SkillTarget;
+    path: string;
+    /** The `metadata.version` of the installed copy; `null` when there is none or it has no version. */
+    installed: string | null;
+    state: SkillState;
+}
+/** Each target's installed copy against this CLI's version; reads only, and an unreadable file is missing. */
+export declare const skillStatus: (app: SkillApp, env?: Env) => SkillTargetStatus[];
 /** What the command writes to and where home is, for this invocation — the host's own output resolution. */
 export type SkillEnvironment = (command: Command) => {
     renderer: Renderer;

package/dist/skill/index.js

@@ -88,6 +88,21 @@ export const installSkill = (app, skill, { targets = SKILL_TARGETS, env = proces
         return path;
     });
 };
+/** Each target's installed copy against this CLI's version; reads only, and an unreadable file is missing. */
+export const skillStatus = (app, env = process.env) => SKILL_TARGETS.map((target) => {
+    const path = skillPath(target, app.appName, env);
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        return { target, path, installed: null, state: "missing" };
+    }
+    const installed = skillVersion(content);
+    if (installed === undefined)
+        return { target, path, installed: null, state: "unversioned" };
+    return { target, path, installed, state: isNewer(app.version, installed) ? "stale" : "current" };
+});
 /**
  * `more`: skills a library ships for every CLI built on it, by name — `skill show <name>` prints one with
  * `{{command}}` turned into this CLI's command. They are printed, not installed: two CLIs would install
@@ -102,13 +117,32 @@ export const skillCommand = (app, skill, environment, more = {}) => {
     const named = Object.keys(more);
     const show = annotate(command.command("show"), { effects: { remote: "none", local: "read" } })
         .summary("print the tool's instructions for AI agents")
-        .description(`print SKILL.md — \`${app.command} skill install\` puts it where Claude Code, Codex and Gemini CLI look for it`);
+        .description(`print SKILL.md — \`${app.command} skill install\` puts it where Claude Code, Codex and Gemini CLI look for it; --for prints the copy already there`);
     if (named.length > 0)
         show.argument("[name]", `one of the skills shipped for a task: ${named.join(", ")}`);
+    show.addOption(new Option("--for <agents>", "print the copy installed for these agents instead of this version's").choices(SKILL_TARGETS));
     show.action(function (given) {
         // Without a declared argument Commander passes the options here, not a name.
         const name = typeof given === "string" ? given : undefined;
-        const { renderer, streams } = environment(this);
+        const { renderer, streams, env } = environment(this);
+        const { for: target } = this.opts();
+        if (target !== undefined) {
+            if (name !== undefined)
+                throw new CliError("validation_error", `only ${app.appName} is installed; leave out "${name}" with --for`);
+            const path = skillPath(target, app.appName, env ?? process.env);
+            let content;
+            try {
+                content = readFileSync(path, "utf8").trimEnd();
+            }
+            catch {
+                throw new CliError("not_found", `no skill is installed for ${target} at ${path} — \`${app.command} skill install --for ${target}\` writes it`);
+            }
+            if (machine(this))
+                renderer.result({ name: app.appName, target, path, installed: skillVersion(content) ?? null, content });
+            else
+                streams.data(content);
+            return;
+        }
         const source = name === undefined ? skill : more[name];
         if (!source) {
             throw new CliError("validation_error", `no skill "${name}" — there are: ${named.join(", ")}`);
@@ -134,20 +168,24 @@ export const skillCommand = (app, skill, environment, more = {}) => {
         renderer.result({ name: app.appName, version: app.version, written });
         renderer.success(`${app.appName} ${app.version} skill installed: ${written.join(", ")}`);
     });
+    annotate(command.command("status"), {
+        effects: { remote: "none", local: "read" },
+        examples: [`${app.command} skill status`, `${app.command} skill status --json`],
+    })
+        .summary("whether the installed instructions for AI agents match this version")
+        .description(`for each place \`${app.command} skill install\` writes to: the path, the version installed there, and whether it is current, stale, missing or unversioned`)
+        .action(function () {
+        const { renderer, env } = environment(this);
+        const targets = skillStatus(app, env ?? process.env);
+        renderer.result({ name: app.appName, version: app.version, targets });
+    });
     return command;
 };
 const isAgent = (env) => Boolean(env.AI_AGENT || env.CLAUDECODE);
 const needsInstall = (app, env) => {
-    const installed = SKILL_TARGETS.flatMap((target) => {
-        try {
-            return [skillVersion(readFileSync(skillPath(target, app.appName, env), "utf8"))];
-        }
-        catch {
-            return [];
-        }
-    });
+    const states = skillStatus(app, env).map(({ state }) => state);
     // A location never installed to is a choice (`--for claude`); only no copy at all, or an old one, is worth a line.
-    return installed.length === 0 || installed.some((version) => version === undefined || isNewer(app.version, version));
+    return (states.every((state) => state === "missing") || states.some((state) => state === "stale" || state === "unversioned"));
 };
 /**
  * One line for an agent whose copy of SKILL.md is missing or older than this CLI, at most once a

package/dist/standards/lint.js

@@ -110,6 +110,12 @@ export const LINT_RULES = defineLintRules([
         scope: "key",
         summary: "no log attribute key on the allow-list names message text, a token or a phone number",
     },
+    {
+        id: "missing-run-log",
+        severity: "high",
+        scope: "group",
+        summary: "the CLI keeps a failed run and reads it back: `runs list`, `runs show`, global `--record` and `--no-record`",
+    },
 ]);
 /** `lint/baseline/<rule-id>.json`: today's violations of one rule, by target. It may only shrink. */
 export const baselineSchema = v.array(text);

package/dist/standards/vocabulary.js

@@ -216,6 +216,7 @@ const collections = [
     ["tags", "labels the owner puts on things"],
     ["searches", "the owner's saved searches"],
     ["copies", "tables kept aside by a repair"],
+    ["tables", "the tables of the local store, with their kind, row count and size"],
     ["attachments", "files of stored messages"],
     ["tasks", "what waits on the owner"],
     ["members", "people in a chat"],

package/docs/standards/README.md

@@ -33,7 +33,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 | [Accounts](accounts.md) | `ACCT` | 11 | The explicit profile, reads across accounts, scope flags, linked identities |
 | [Permissions](permissions.md) | `PERM` | 21 | Levels, keys, defaults, hard limits, the write guard and its journal |
 | [Architecture](architecture.md) | `ARCH` | 17 | Layers, dependency direction, vendor types, what goes in which package |
-| [Lifecycle](lifecycle.md) | `LIFE` | 13 | Opening late, who closes, one-shot exits, long-running commands, the `serve` relay, resumable syncs |
+| [Lifecycle](lifecycle.md) | `LIFE` | 14 | Opening late, who closes, one-shot exits, long-running commands, the `serve` relay, resumable syncs, the run log |
 | [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
 | [Data model](data-model.md) | `DATA` | 7 | Core entities, entities and source records, `external_id`, field names, links and duplicates |
 | [Testing](testing.md) | `TEST` | 17 | Sandbox, no network, no real waits, leak tests, coverage, contracts, test matrix, parity |

package/docs/standards/kit-surface.md

@@ -18,7 +18,7 @@ The list is what the template's `src/` imports today, type imports included.
 |---|---|
 | `@wirecat/cli-base` | `catchCrashes`, `CliError`, `configFilePath`, `mcpErrorResult`, `resolvePaths` |
 | `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `describeProgram` |
-| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `itemOf`, `LOCAL_READ`, `outputFor`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `settingsFor`, `skillCommand`, `upgradeCommand` |
+| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `itemOf`, `LOCAL_READ`, `outputFor`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
 | `@wirecat/cli-core/mcp` | `McpCommand`, `registerCommands`, `runCommandForAgent`, `toolsFromCommands` |
 | `@wirecat/cli-core/sends` | `Level` |
 | `@wirecat/cli-core/update` | `appUpdate` |

package/docs/standards/lifecycle.md

@@ -14,6 +14,16 @@ A "one-shot" command does one job and ends: most commands. A "long-running" comm
 `lifetime: "persistent"` (it runs until it is stopped, such as `serve` or `watch`) or `lifetime: "interactive"` (it
 waits for a person, such as a login).
 
+A "run" is one command's record: what it was, how it ended, and its events, never content. The rules on what a
+run's events may hold are [WC-SECR-1](security.md#wc-secr-1--private-data-and-secrets-never-reach-a-log-a-fixture-or-a-committed-document)
+and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and-hides-content-keys).
+
+### Who follows these rules today
+
+- **WC-LIFE-15:** tg, max, wa and the template. drive, memo and zm do not keep runs yet; each is adding them on a
+  `feat/runs` branch (2026-10-25). zm's `resolveSettings` also returns `keepFailedRuns: false`, which turns off the
+  failure log cli-core's `run` would keep.
+
 ## One-shot commands
 
 ### WC-LIFE-1 · The code that opens a resource closes it, so a one-shot command exits when it has answered
@@ -183,6 +193,29 @@ provider's limit as often as it ends. These three rules make the next run carry
   failed is a different question, answered by `recordRun` and `failingNotice` in cli-core's schedules.
 - **Applies to:** every CLI with a sync. **Since:** cli-base 0.44.0. **Rulings:** none.
 
+## Runs
+
+### WC-LIFE-15 · Keep a run log through cli-core, and read it back with `runs`
+
+A failed command is always kept as a run, unless the person turned recording off with `--no-record` or
+`record: false` in the config. `--record` keeps every run of a command that does its work inside cli-core's run
+(`context.run`, or `startRecording` in a program of its own). A run is a folder `<state>/runs/<day>/<run_id>/` with
+`run.json` and `events.jsonl`, one log record per line. `runs list` and `runs show` read it.
+
+- A CLI that runs its program through cli-core's `run` gets the failure log and `--record`/`--no-record` from it,
+  and adds `runsCommand(app)` to its commands. Its configuration is `settingsFor(app)`, or a `resolveSettings` that
+  returns the owner's `record` and `keep_runs_for_days` as `keepFailedRuns` and `keepRunsForDays`, never fixed values.
+- A CLI with a program of its own opens each command's run with `startRecording` from `@wirecat/cli-core/cli`,
+  ends it with `succeed` or `fail`, adds `--record` and `--no-record` at the root and registers `runsCommand(app)`.
+
+- **Why:** when a command fails, a person or an agent needs to see what it did, in the same place and shape in every
+  CLI. Without the rule, three CLIs shipped with no run log, and one switched cli-core's off.
+- **Enforced by:** `missing-run-log`.
+- **Example:** `tg --bogus` fails, `tg runs list` shows that run as `failed`, and `tg runs show <run_id>` shows its
+  events.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.56.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/new-cli.md

@@ -50,7 +50,8 @@ Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explici
 The reference CLI is the one to compare with when a step is unclear.
 
 The copy already holds every file this handbook asks for: the required root commands (`commands`, `doctor`,
-`skill show`, `skill install`, `mcp`, `upgrade`) and `config` from cli-core, the MCP server with a tool for every
+`skill show`, `skill install`, `mcp`, `upgrade`) and `config` from cli-core, the run log and its `runs` commands
+([WC-LIFE-15](lifecycle.md#wc-life-15--keep-a-run-log-through-cli-core-and-read-it-back-with-runs)), the MCP server with a tool for every
 command, writes included, the community presets in `config/wirecat/`, the TypeScript, Biome and vitest setup,
 `contracts/`, `lint/`, the test matrix, the user pages, `CHANGELOG.md`, `SECURITY.md`, `bin/release`, and the
 `pr.yml`, `ci.yml`, `main.yml`, `standards.yml`, `changelog-guard.yml`, `monthly.yml` and `release.yml` workflows.
@@ -83,7 +84,8 @@ All of these pass on `main`, before the first release:
 
 - `pnpm standards:check`
 - `pnpm typecheck`, `pnpm lint` and `pnpm test` with coverage
-- `cli-dev lint` against the built CLI
+- `cli-dev lint` against the built CLI. It also makes the CLI fail once in an empty home and checks that
+  `runs list` shows the failed run
 - `cli-dev audit --for <cli> --lint <cli>=lint` with no new finding, run with the command trees of the CLIs in
   the same parity groups. `--lint` judges the CLI's lint rules by its own `lint/` folder. What it shares with the
   other CLIs is judged by cli-base's `audit/baseline`; the pull request that adds the CLI to a parity group adds its

package/package.json

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