@wirecat/cli-base 0.61.2 → 0.62.0

package/CHANGELOG.md

@@ -8,6 +8,43 @@ 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.62.0 — 26.10.2026
+
+### Added
+
+- **`describeAlone(command, known)` describes a command as if it had no parent, reusing what `known` already holds.**
+  The shared-command check uses it to describe each command once per pass. Keep `known` for one pass only: a map kept
+  longer returns descriptions of commands that have since changed.
+
+### Fixed
+
+- **The shared-command check describes each command once per pass, not once for itself and again for every group
+  above it.** It runs when a shared command is built and before each command runs, so every command of every CLI paid
+  for it: about 60% of tg's setup, even for `tg --version`. On tg's real program one check now takes about 5 ms
+  instead of 11, building the program about 35 ms instead of 46, and a warm `run(["--version"])` about 30 ms instead
+  of 47 ([measurement](https://github.com/WireCatLabs/cli-testing/blob/main/performance/cli/shared-contract-check/README.md)).
+  The check still covers every protected subcommand, with the same errors and overrides, and `sharedContracts` returns
+  the same contracts as before.
+
+## 0.61.3 — 26.10.2026
+
+### Fixed
+
+- **Handbook corrections from the cli-template 0.6.0 audit.** [CI](docs/standards/ci.md): the shared `node-ci.yml`
+  runs a CLI's contract, leak, version, generate, test matrix, docs, package and command lint steps itself with
+  `cli: true`; the repository's `ci.yml` names a step it cannot run yet in `skip` and puts only extra checks in
+  `checks`. The page used to say the repository listed those steps in `checks`.
+  [Architecture](docs/standards/architecture.md): a command may fall back to `process.env` when the environment leaves
+  `env` unset, as in `environmentOf(this).env ?? process.env`; the two rules on the command environment no longer
+  disagree. [Testing](docs/standards/testing.md): tests that only read may share a profile; a test that writes config
+  or the store uses its own profile or undoes the write in a `finally` block. The upgrade check defines local state:
+  data the CLI's own code writes and reads back, not cli-core's config file and run records.
+  [Documents](docs/standards/docs.md): an empty `## Unreleased` is not kept, and a developer page anchors claims about
+  behaviour, measurements and findings, not instructions. [New CLI](docs/standards/new-cli.md): the copy tool under
+  `kit/` follows the rules for code and the repository but not those for a CLI's commands and runtime, and the
+  `CLIDEV_` prefix is a placeholder like `clidev`. The repository lists on the CI, Toolchain, Security and Documents
+  pages now include cli-template.
+
 ## 0.61.2 — 26.10.2026
 
 ### Fixed

package/dist/commands/contracts.js

@@ -1,25 +1,22 @@
 import { isDeepStrictEqual } from "node:util";
 import { Command } from "commander";
 import { CliError } from "../errors.js";
-import { describeProgram } from "./registry.js";
+import { describeAlone } from "./registry.js";
 const protectedCommands = new WeakMap();
 export const hasSharedContract = (command) => protectedCommands.has(command);
-const snapshot = (command, children) => {
-    const root = new Command("contract");
-    const parent = command.parent;
-    root.addCommand(command);
-    const described = describeProgram(root)[0];
-    command.parent = parent;
-    if (!described)
+const hidden = (command) => Boolean(command._hidden);
+/** Shares arrays with the live command and with `known`: clone it before keeping it past the pass. */
+const snapshot = (command, known = new Map(), children) => {
+    if (hidden(command))
         throw new Error("a hidden command cannot own a shared contract");
-    const { commands: _, usage: __, path: ___, ...contract } = described;
-    return structuredClone({
+    const { commands: _, usage: __, path: ___, ...contract } = describeAlone(command, known);
+    return {
         ...contract,
         aliases: [...command.aliases()],
         children: (children ?? protectedCommands.get(command)?.originalChildren ?? command.commands)
-            .filter((child) => command.commands.includes(child) && !child._hidden)
+            .filter((child) => command.commands.includes(child) && !hidden(child))
             .map((child) => child.name()),
-    });
+    };
 };
 const same = isDeepStrictEqual;
 const visit = (root, fn) => {
@@ -36,11 +33,12 @@ const pathOf = (command) => {
 const differences = (before, after) => [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((field) => !same(before[field], after[field]));
 export const assertSharedContracts = (root) => {
     const changed = [];
+    const known = new Map();
     visit(root, (command) => {
         const protectedContract = protectedCommands.get(command);
         if (!protectedContract)
             return;
-        const fields = differences(protectedContract.contract, snapshot(command));
+        const fields = differences(protectedContract.contract, snapshot(command, known));
         if (fields.length)
             changed.push({ command: pathOf(command).join(" "), fields });
     });
@@ -55,9 +53,9 @@ export const overrideSharedContract = (command, reason, change) => {
     if (!protectedContract)
         throw new Error("only a core-owned command contract can be overridden");
     assertSharedContracts(command);
-    const before = snapshot(command);
+    const before = structuredClone(snapshot(command));
     change(command);
-    const after = snapshot(command);
+    const after = structuredClone(snapshot(command));
     const fields = differences(before, after);
     if (fields.length === 0)
         throw new Error("a shared contract override must change its named command");
@@ -119,14 +117,18 @@ export const sharedCommand = (factory) => (...args) => {
             if (!command.summary() && first.length > 80)
                 command.summary(`${first.slice(0, 77).replace(/\s+\S*$/, "")}…`);
         });
+        const known = new Map();
         visit(shared, (command) => {
-            if (!command._hidden && !protectedCommands.has(command))
-                protectedCommands.set(command, {
-                    contract: snapshot(command),
-                    reference: snapshot(command),
-                    overrides: [],
-                    originalChildren: [...command.commands],
-                });
+            if (hidden(command) || protectedCommands.has(command))
+                return;
+            // One object for both: `contract` is only ever replaced, and `reference` is cloned on the way out.
+            const contract = structuredClone(snapshot(command, known));
+            protectedCommands.set(command, {
+                contract,
+                reference: contract,
+                overrides: [],
+                originalChildren: [...command.commands],
+            });
         });
         shared.hook("preAction", () => {
             let root = shared;
@@ -147,6 +149,7 @@ export const customizeSharedCommand = (reference, reason, build, expectedOverrid
     const command = build();
     assertSharedContracts(command);
     const pending = [];
+    const known = new Map();
     const edits = [];
     const bindingPath = (own) => {
         const path = [own.name()];
@@ -163,7 +166,7 @@ export const customizeSharedCommand = (reference, reason, build, expectedOverrid
             return;
         if (!protectedCommands.has(own)) {
             const originalChildren = own.commands.filter((child) => inherited.reference.children.includes(child.name()));
-            const actual = snapshot(own, originalChildren);
+            const actual = structuredClone(snapshot(own, known, originalChildren));
             const overrides = differences(inherited.contract, actual).map((field) => ({
                 command: bindingPath(own),
                 field,

package/dist/commands/registry.d.ts

@@ -119,3 +119,8 @@ export declare const flatten: (commands: readonly CommandInfo[]) => CommandInfo[
  * in snake_case. Hand it to `stepOf` and `errorObjectOf` as `targets`.
  */
 export declare const stepTargets: (root: Command) => ((command: string) => StepTarget | undefined);
+/**
+ * The command as if it had no parent, so it inherits nothing, and its subcommands the same way. `known` holds what one
+ * pass has described already, so a whole tree costs one description per command; keep it no longer than that pass.
+ */
+export declare const describeAlone: (command: Command, known: Map<Command, CommandInfo>) => CommandInfo;

package/dist/commands/registry.js

@@ -40,7 +40,19 @@ export const stepTargets = (root) => {
         visit(child, [], root.options);
     return (command) => found.get(command);
 };
-const describe = (command, cli, parents, above) => {
+/**
+ * The command as if it had no parent, so it inherits nothing, and its subcommands the same way. `known` holds what one
+ * pass has described already, so a whole tree costs one description per command; keep it no longer than that pass.
+ */
+export const describeAlone = (command, known) => {
+    let found = known.get(command);
+    if (!found) {
+        found = describe(command, "", [], { offMcp: false, noOffline: false }, known);
+        known.set(command, found);
+    }
+    return found;
+};
+const describe = (command, cli, parents, above, known) => {
     const path = [...parents, command.name()];
     const args = command.registeredArguments.map(describeArgument);
     const options = describeOptions(command);
@@ -68,7 +80,7 @@ const describe = (command, cli, parents, above) => {
         ...(visible(command).length > 0 && hasAction(command) ? { runnable: true } : {}),
         arguments: args,
         options,
-        commands: visible(command).map((child) => describe(child, cli, path, here)),
+        commands: visible(command).map((child) => (known ? describeAlone(child, known) : describe(child, cli, path, here))),
     };
 };
 // Commander has no public getter for the action either; without one, a group prints its help.

package/docs/standards/architecture.md

@@ -144,7 +144,8 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Why:** two registries of the same environment must both be filled on every run, and one is always forgotten.
 - **Enforced by:** review only.
 - **Example:** a CLI extends `BaseEnvironment`, hands it to cli-core's `provide(program, environment)`, and its
-  commands read it with `environmentOf<Environment>(command)`, never with `process.*`.
+  commands read it with `environmentOf<Environment>(command)`. `process.*` appears only as the default for a field
+  the environment leaves unset, as WC-ARCH-10 says: `environmentOf(this).env ?? process.env`.
 - **Exceptions:** a CLI that does not use cli-core's command skeleton keeps one environment of its own.
 - **Applies to:** CLIs built on cli-core's command skeleton. **Since:** cli-base 0.41.0. **Rulings:** none.
 

package/docs/standards/ci.md

@@ -11,7 +11,8 @@ Rule ids on this page are `WC-CI-<n>`. How to read a rule, how ids work and whic
 [Security page](security.md).
 
 "The ten repositories" on this page means the six CLIs (tg, max, memo, drive, zoom, wa), cli-base, cli-core,
-cli-testing, cli-docs, plus community itself.
+cli-testing, cli-docs, plus community itself. cli-template follows every rule here as a CLI does
+([New CLI](new-cli.md#the-template-repository-itself)).
 
 ## Rules
 
@@ -51,7 +52,7 @@ cli-testing, cli-docs, plus community itself.
 - **Why:** it is the first build-level answer on a pull request, so it must stay fast enough that nobody wants it gone.
 - **Enforced by:** `standards.yml:standards` · `pnpm ci:quick`.
 - **Example:** what each repository runs today:
-  - tg, max, memo and wa: `pnpm typecheck && pnpm build && pnpm lint:commands`;
+  - tg, max, memo, wa and cli-template: `pnpm typecheck && pnpm build && pnpm lint:commands`;
   - drive: `pnpm typecheck && pnpm lint:commands`, which builds first;
   - zoom, cli-base and cli-testing: `pnpm typecheck`;
   - cli-core: `pnpm typecheck` and its command lint test;
@@ -95,8 +96,8 @@ cli-testing, cli-docs, plus community itself.
   cli-base `macos.yml` for the path code. cli-docs and community run `security-pr.yml`, a new-commit secret scan;
   cli-docs validates its site before each deployment instead, and community has no build. Third-party security apps
   may post their own checks.
-- **Applies to:** the CLIs, cli-base, cli-core and cli-testing. cli-base, whatsapp-cli, tg-cli, max-cli, cli-core
-  cli-memo, zoom-cli and drive-cli have `pr.yml`; cli-testing does not have it yet. **Since:**
+- **Applies to:** the CLIs, cli-base, cli-core and cli-testing. cli-base, whatsapp-cli, tg-cli, max-cli, cli-core,
+  cli-memo, zoom-cli, drive-cli and cli-template have `pr.yml`; cli-testing does not have it yet. **Since:**
   cli-base 0.41.0 (pull request validation since cli-base 0.45.0). **Rulings:** none.
 
 ### WC-CI-6 · Run the changelog guard on every pull request
@@ -115,9 +116,12 @@ cli-testing, cli-docs, plus community itself.
   catches that merge skew the same hour, not at the next release.
 - **Enforced by:** `main.yml:validation` · `node-ci.yml:check` · `node-ci.yml:bun` · `node-ci.yml:secrets`.
 - **Example:** `main.yml` calls the repository's own `ci.yml`, which calls cli-base `node-ci.yml`. That runs
-  `pnpm lint`, `pnpm typecheck`, `pnpm test:coverage`, `pnpm build`, then the project's `checks` lines (for max:
-  contracts, the no-leak scan, the version check, `pnpm generate` and `git diff --exit-code`, the test matrix,
-  `docs:check` and parity), a Bun job, and a gitleaks scan of the whole history.
+  `pnpm lint`, `pnpm typecheck`, `pnpm test:coverage` and `pnpm build`. With `cli: true` it then runs one named step
+  per CLI script: `contracts:check`, `contracts:upgrade`, `security:no-leak`, `version:check`, `generate:check`,
+  `test:matrix:check`, `docs:check`, `package:check`, `lint:commands`, and `parity:check` with `parity: true`. Then
+  the project's `checks` lines, a Bun job, and a gitleaks scan of the whole history. The shared workflow owns the CLI
+  steps: the repository's `ci.yml` names a step it cannot run yet in `skip`, with the reason beside it, and puts only
+  its extra checks in `checks` (tg and max: `pnpm check:agent-docs`).
 - **Exceptions:** platform suites (Windows, macOS, install checks) are skipped here and run at release, monthly or on
   request. Nothing in this run publishes or tags. cli-docs runs its full validation before each deployment and monthly
   instead; community has no build to validate.
@@ -140,8 +144,8 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
 - **Why:** one shared workflow keeps the full suite the same everywhere, and a pin keeps a cli-base change from
   breaking ten repositories at once.
 - **Enforced by:** `ci.yml:ci`.
-- **Example:** `uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@<commit> # v0.31.0`, with the project's own
-  checks in the `checks` input and `bun-run` for the Bun job. A job that only one repository needs stays beside it in
+- **Example:** `uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@<commit> # v0.31.0`, with `cli: true` for
+  the CLI steps (WC-CI-7), the project's extra checks in the `checks` input and `bun-run` for the Bun job. A job that only one repository needs stays beside it in
   that repository's `ci.yml`.
 - **Exceptions:** never pin to `main`. cli-base itself calls `./.github/workflows/node-ci.yml`. cli-docs has its own
   full workflow for the site, and community has none.
@@ -182,8 +186,8 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
 - **Why:** a red merge breaks `main` for every parallel branch, and an admin merge skips the only gate there is.
 - **Enforced by:** `whatsapp-cli: main ruleset required checks` · `cli-core: main ruleset required checks` ·
   `tg-cli: main ruleset required checks` · `max-cli: main ruleset required checks` ·
-  `cli-memo: main ruleset required checks` · `drive-cli: main ruleset required checks`, plus the main ruleset of
-  cli-base itself. In each repository with pr.yml, the ruleset requires the pull request validation jobs besides the
+  `cli-memo: main ruleset required checks` · `drive-cli: main ruleset required checks`, plus the main rulesets of
+  cli-base and cli-template. In each repository with pr.yml, the ruleset requires the pull request validation jobs besides the
   standards job. cli-testing and cli-docs have no pr.yml, so their rulesets require only the standards job, and
   review covers the rest. zoom-cli has pr.yml,
   but its ruleset still requires only the standards job.

package/docs/standards/docs.md

@@ -27,8 +27,8 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
 - **Enforced by:** `tg-cli: pnpm docs:check` · `max-cli: pnpm docs:check` · `whatsapp-cli: pnpm docs:check` ·
   `zoom-cli: pnpm docs:check`.
 - **Example:** write "`--limit` defaults to 50", not "~~20~~ 50 (correction 2026-10-01, NEED-12)".
-- **Exceptions:** none. `cli-dev docs-check` checks this when the CLI's rules module sets `userPage`. tg, max, wa
-  and zoom set it; memo, drive and cli-base's default check do not.
+- **Exceptions:** none. `cli-dev docs-check` checks this when the CLI's rules module sets `userPage`. tg, max, wa,
+  zoom and cli-template set it; memo, drive and cli-base's default check do not.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-DOC-3 · Every document states current facts; rewrite a wrong sentence in place
@@ -110,7 +110,9 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
 - **Enforced by:** review only.
 - **Example:** cite `src/store/open.ts:42` for our code, a URL for anything outside, a commit for history. Write "ran
   X, saw Y" for what you ran, and "the docs describe X" for what you only read. Say at the top what is not verified.
-- **Exceptions:** user pages state behaviour and do not carry code anchors.
+- **Exceptions:** an instruction or a rule ("run `pnpm test`", "one store per profile") needs no anchor; a claim about
+  how the code or a service behaves, a measurement and a finding do. A file path with no line number is enough when
+  the claim is about the whole file. User pages state behaviour and do not carry code anchors.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-DOC-12 · A runnable command in a document has no placeholder in it
@@ -136,7 +138,9 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
 - **Why:** the GitHub release and the release scripts read the changelog by its headings.
 - **Enforced by:** `pnpm docs:check` · `changelog-guard.yml`.
 - **Example:** `## Unreleased` at the top while work is merged; a release dates it as `## 0.41.0 — 17.10.2026`. Each
-  version heading and the pending heading appear once.
+  version heading and the pending heading appear once. The pending section exists only while it has entries: after a
+  release the changelog opens on the dated section, and the next entry adds `## Unreleased` back. Never keep an empty
+  one.
 - **Exceptions:** max-cli names the pending section `## Не выпущено`.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 

package/docs/standards/new-cli.md

@@ -114,8 +114,12 @@ upgrade, and no script or agent reads its answers.
 | [WC-LAY-2](layout.md) | The skeleton keeps it in `src/bin/clidev.ts`. The package's `"bin"` names the copy tool, `kit/dist/main.js`. | `new` writes the CLI's own `"bin"` entry into the copy. |
 | [WC-OUT-18](output.md#wc-out-18--exit-with-cli-bases-code-for-each-kind-of-failure), [WC-OUT-19](output.md#wc-out-19--report-a-wrong-command-line-as-validation_error-exit-2) | The copy tool is exempt: it exits 1 with a plain sentence. The skeleton follows them. | People run the copy tool by hand; nothing branches on its exit code or parses its errors (owner, ASK-349). |
 | [WC-TOOL-4](toolchain.md#wc-tool-4--extend-the-shared-typescript-config-and-do-not-loosen-it), [WC-TEST-11](testing.md#wc-test-11--keep-a-coverage-floor-and-raise-it-never-lower-it) | Both programs follow them: `kit/tsconfig.json` extends the shared base, and `kit/src` has its own coverage floor. | The copy tool writes into a person's new repository, so it gets the same build-time and test checks (owner, ASK-349). |
-| [WC-TEST-14](testing.md#wc-test-14--check-the-upgrade-from-the-previous-published-version) | Exempt: `ci.yml` skips `contracts:upgrade`. | The skeleton is never published under its own name, so there is no earlier package to upgrade from. A CLI made from the template turns the step on after its first release. |
-| [WC-DOC-12](docs.md#wc-doc-12--a-runnable-command-in-a-document-has-no-placeholder-in-it) | Exempt only for the placeholder names `clidev`, `clidev-cli`, `@wirecat/clidev-cli` and `WireCatLabs/clidev-cli`. | `new` replaces each of them with the CLI's own name. Any other placeholder is still a gap. |
+| [WC-TEST-14](testing.md#wc-test-14--check-the-upgrade-from-the-previous-published-version) | Exempt: `ci.yml` skips `contracts:upgrade`. | The skeleton has no local state of its own: its config file and run records are written by cli-core. A CLI made from the template turns the step on once it has local state and a published version to upgrade from. |
+| [WC-DOC-12](docs.md#wc-doc-12--a-runnable-command-in-a-document-has-no-placeholder-in-it) | Exempt only for the placeholder names `clidev`, `clidev-cli`, `@wirecat/clidev-cli` and `WireCatLabs/clidev-cli`, and the upper-case prefix `CLIDEV_` (as in `CLIDEV_PROFILE`). | `new` replaces each of them with the CLI's own name. Any other placeholder is still a gap. |
 | [WC-DOC-17](docs.md#wc-doc-17--each-entry-says-what-changed-for-the-caller-why-and-what-to-watch-for) | A changelog entry may name a file path. | The template's readers are CLI authors, who edit those files or take them with `upgrade`; for them a path is what they see. |
 
-Every other rule that applies to all CLIs, or to the ten repositories, applies to cli-template as it is written.
+Every other rule that applies to all CLIs, or to the ten repositories, applies to cli-template as it is written,
+with one limit for the copy tool. It follows the rules for code and the repository: Toolchain, Layout, Style,
+Testing, Security and Documents. It has no profile, no machine mode, no MCP server, no store and no agent reading its
+answers, so the rules for a CLI's commands and runtime do not reach it: Commands, Output, MCP, Accounts, Permissions,
+Architecture, Lifecycle, Store, Data model and Time. Those apply to the skeleton.

package/docs/standards/security.md

@@ -274,7 +274,8 @@ general words.
   asks for it on that job only. The `zizmor` scan in `release-checks.yml` reports high findings at release, but does
   not fail on them.
 - **Exceptions:** none.
-- **Applies to:** the ten repositories: the six CLIs, cli-base, cli-core, cli-testing, cli-docs and community.
+- **Applies to:** the ten repositories: the six CLIs, cli-base, cli-core, cli-testing, cli-docs and community; and
+  cli-template.
   **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-SECR-21 · Names, message text and retrieved documents are data, never instructions

package/docs/standards/store.md

@@ -181,7 +181,7 @@ messages), or other people's data.
   `WIRECAT_STATE_DIR` and every `<APP>_CONFIG_DIR`, `_STATE_DIR` and `_CACHE_DIR` that is set at a temporary
   directory before any test runs, and the home folder with them, so one that is not set lands there too. cli-core and
   every CLI load it first, then their own setup file for what is theirs alone. A test that needs its own store is
-  [WC-TEST-9](testing.md#wc-test-9--give-each-test-its-own-profile-or-its-own-store). The rest of the sandbox is
+  [WC-TEST-9](testing.md#wc-test-9--leave-no-tests-config-or-store-change-for-the-next-test-to-see). The rest of the sandbox is
   [WC-TEST-1](testing.md#wc-test-1--point-every-path-a-test-could-write-at-a-temporary-directory).
 - **Exceptions:** none.
 - **Applies to:** all CLIs that use the store, and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.

package/docs/standards/testing.md

@@ -130,12 +130,14 @@ and which run after merge is in [CI](ci.md).
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
-### WC-TEST-9 · Give each test its own profile or its own store
+### WC-TEST-9 · Leave no test's config or store change for the next test to see
 
 - **Why:** the sandbox is per file, so tests in one file share config, the send journal and the store.
 - **Enforced by:** review only.
-- **Example:** each test passes its own profile name first, or a file-level constant. A test that needs an empty
-  store makes a fresh directory and passes `MESSAGING_STORE`.
+- **Example:** tests that only read may share one profile name, such as a file-level constant. A test that writes
+  config or the store either uses a profile name no other test in the file uses, or undoes its write in a `finally`
+  block, so a failed assertion does not skip the undo. A test that needs an empty store makes a fresh directory and
+  passes `MESSAGING_STORE`.
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
@@ -190,7 +192,9 @@ and which run after merge is in [CI](ci.md).
 - **Enforced by:** `node-ci.yml:check` · `<app>: pnpm contracts:upgrade`.
 - **Example:** `pnpm contracts:upgrade` runs the previous published package and this build on the same synthetic
   state and checks that the data survives. Each store migration also has its own upgrade test (WC-STORE-9).
-- **Exceptions:** a CLI with no local state.
+- **Exceptions:** a CLI with no local state, or with no published version yet. Local state is data the CLI's own
+  code writes and reads back in a later run, such as a store, a session or a cache. A config file and run records
+  that only cli-core writes do not count.
 - **Applies to:** all CLIs with local state. wa has no upgrade contract yet. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TEST-15 · A refactor keeps `commands --json` and the MCP tool list as they were

package/docs/standards/toolchain.md

@@ -16,7 +16,8 @@ one source of the presets. Each repository holds a copy of them in `config/wirec
 `adopt-standards.py`.
 
 "The ten repositories" on this page means the six CLIs (tg, max, memo, drive, zoom, wa), cli-base, cli-core,
-cli-testing, cli-docs, plus community itself.
+cli-testing, cli-docs, plus community itself. cli-template follows every rule here as a CLI does
+([New CLI](new-cli.md#the-template-repository-itself)).
 
 ## Rules
 

package/package.json

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