@wirecat/cli-base 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -8,6 +8,27 @@ 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.54.0 — 25.10.2026
+
+### Added
+
+- **A Kit surface page in the standards** ([Kit surface](docs/standards/kit-surface.md)) lists the cli-base and cli-core exports that `@wirecat/cli-template` is built on. A change that makes a CLI change its code for one of them ships with a migration note here and with the template already updated, so `npx @wirecat/cli-template upgrade` brings it. Nothing changes in code.
+- **The New CLI page starts with `npx @wirecat/cli-template new`** ([New CLI](docs/standards/new-cli.md)). It gives the command with every flag, the four steps that still need a person, and the same "Done when" checks. A CLI started by hand still passes the same checks.
+
+### Changed — may break callers
+
+- **The release lock is one per package, not one per machine** (`WC-REL-3`, [Releases](docs/standards/releases.md)). Two releases of the same package still never run at once on one machine, from any checkout or worktree; releases of different packages now run side by side. The lock is `leemour-release-<package>.lock`, named from `package.json`, so a `package.json` without a name refuses the release. A CLI picks this up by re-running community's `adopt-standards.py --only release-lock`; until then it keeps the old shared lock.
+
+## 0.53.0 — 25.10.2026
+
+### Added
+
+- **A rule for the provider registry** (`WC-ARCH-21`, [Architecture](docs/standards/architecture.md)): a CLI registers its provider in the store on every run, and a row whose provider no one registered is skipped, never searched as messages. It matches cli-core's stored registry. The Data model, Store and Security pages also list what the approved Wave 3 design adds and is not built yet: files, calendars, contacts by address, one link log and review list, a CLI's own SQLite file, and the sign-in module. The Data model page now names the attendee table `calendar_entry_participants`, lists `meeting_participants` among the known gaps, and names cli-core's schema test as the check of `WC-DATA-2` to `WC-DATA-4`.
+
+### Changed — may break callers
+
+- **Every handwritten list needs a query declaration.** The command lint checks lists that lack answer metadata too. Release this with the matching cli-core list-query changes and consumer updates.
+
 ## 0.52.0 — 25.10.2026
 
 ### Added
@@ -16,6 +37,7 @@ Every entry says what changed as a caller sees it, why, and what to watch for
 - **`cli-dev <command> --help`** prints the usage, as `cli-dev --help` does, instead of failing on an unknown option.
 
 - **A data-model page in the standards** (`WC-DATA-1` to `WC-DATA-7`, [Data model](docs/standards/data-model.md)). It says which records cli-core owns and which stay private to a CLI, keeps a source's records (a calendar entry, a Drive file, a mail contact) apart from the owner's entities (an event, a document, a person), puts every provider id in `external_id`, lists the standard field names, and makes every link record how it was made, with no link when two candidates tie. Nothing changes in code; older tables follow the rules when they next change.
+
 ## 0.51.1 — 24.10.2026
 
 ### Fixed

package/config/wirecat/biome.base.json

@@ -120,6 +120,23 @@
         "!**/fixtures/**"
       ]
     },
+    {
+      "path": "./config/wirecat/no-sqlite-driver.grit",
+      "includes": [
+        "**",
+        "!**/*.test.*",
+        "!**/*.spec.*",
+        "!**/test/**",
+        "!**/tests/**",
+        "!**/__tests__/**",
+        "!**/fixtures/**",
+        "!**/testing/**",
+        "!**/scripts/**",
+        "!**/bench/**",
+        "!**/performance/**",
+        "!**/contracts/**"
+      ]
+    },
     {
       "path": "./config/wirecat/no-unbounded-spread.grit",
       "includes": [

package/config/wirecat/manifest.json

@@ -2,7 +2,7 @@
   "source": "https://github.com/WireCatLabs/community",
   "revision": "b22b7ede5931a4058fc763e0a7d6bfe0fbdb87c8",
   "files": {
-    "biome.base.json": "5d265b71896cdb0454260fa8d897bd517f61de512f16831e5d5273f29775f9f3",
+    "biome.base.json": "63760337a2e68522ad75e0ba163635785a01ec34dbd3cf338a09a4145932cf2a",
     "cspell.json": "8241122ed4d461976a838099b265ef8f2689a066608257b6fdc250d9b49b58aa",
     "lefthook.yml": "2f65a2e3103006d43f6d6f0a07ab333c132286157763222a59a5a22676acd391",
     "markdownlint.json": "5ed7d6980054c539f3f3c0e47a090f1a725b15be2c486a769a836bc6cd48ad2d",
@@ -12,9 +12,10 @@
     "no-shell-true.grit": "d3943cfa1d7ebbf7be0fa22c2aaf2b7d7aa9ff462f2eb14a7798632764e3875c",
     "no-unbounded-spread.grit": "f4178e5b74212fef58fec8916b6783d9f4f192ac618aa4ced041c4167bfbf81b",
     "release-lock-info.mjs": "4abab1f01ceee7d4c709222e923c9a6fc634bcf7b8b64d745a9ac495993310e0",
-    "release-lock.sh": "f3309e569daea423c35f2a7b51cd55aec24c28160428b67ee2ece05e67fab877",
+    "release-lock.sh": "bef364092c4ab595f3b9b4130e23570c8306223228cdfa3e9384230f3b7f4a49",
     "rumdl.toml": "048b929176f13234324f5825d1e811397f1491b9cb6684a1953e268e2c2ed863",
-    "check.mjs": "34b266411eaab7707030915f645308e86784b1574b21fa44ca974861a90c9ce1"
+    "check.mjs": "34b266411eaab7707030915f645308e86784b1574b21fa44ca974861a90c9ce1",
+    "no-sqlite-driver.grit": "19e1f510a88ddd9df44d6db43c1c9b603c3e5bbec03a3f65305b72eac7f09389"
   },
   "packageManager": "pnpm@11.20.0",
   "node": ">=22",
@@ -26,5 +27,11 @@
     "cspell": "10.3.6",
     "lefthook": "2.1.16",
     "markdownlint-cli2": "0.23.3"
+  },
+  "fileRevisions": {
+    "release-lock.sh": "49e630a99d758e3e113749bef2049b258c7262e3",
+    "release-lock-info.mjs": "49e630a99d758e3e113749bef2049b258c7262e3",
+    "biome.base.json": "06c612c609d870f0ba00010612e0413f65340408",
+    "no-sqlite-driver.grit": "06c612c609d870f0ba00010612e0413f65340408"
   }
 }

package/config/wirecat/no-sqlite-driver.grit

@@ -0,0 +1,15 @@
+language js
+
+or {
+  `import $_ from $source`,
+  `import $source`,
+  `export { $_ } from $source`,
+  `export * from $source`,
+  `export * as $_ from $source`,
+  `export type { $_ } from $source`,
+  `import($source)`,
+  `require($source)`
+} where {
+  $source <: r"^[\"'`](?:node:sqlite|bun:sqlite|better-sqlite3|drizzle-orm)(?:/.*)?[\"'`]$",
+  register_diagnostic(span=$source, message="The shared store belongs to cli-core (WC-STORE-5): a CLI opens no SQLite driver and writes no SQL against it. Ask cli-core for a store method.", severity="error")
+}

package/config/wirecat/release-lock.sh

@@ -8,7 +8,16 @@ wirecat_release_lock() {
     echo "release locking requires flock" >&2
     return 1
   }
-  _wirecat_release_lock="${XDG_RUNTIME_DIR:-/tmp}/leemour-release.lock"
+  # Keyed by package name, not folder: one package releases from several checkouts and worktrees.
+  _wirecat_release_key=$(node -e '
+    const { name } = JSON.parse(require("node:fs").readFileSync("package.json", "utf8"))
+    if (typeof name !== "string" || !name) throw Error("package.json has no name")
+    process.stdout.write(name.replace(/^@/, "").replace(/[^A-Za-z0-9._-]+/g, "-"))
+  ' 2>/dev/null) && [ -n "$_wirecat_release_key" ] || {
+    echo "release locking needs a package name in ./package.json" >&2
+    return 1
+  }
+  _wirecat_release_lock="${XDG_RUNTIME_DIR:-/tmp}/leemour-release-$_wirecat_release_key.lock"
   exec 9>>"$_wirecat_release_lock"
   if flock -E 75 -w "$_wirecat_release_wait" 9; then
     printf '%s pid %s since %s\n' "$(basename "$PWD")" "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$_wirecat_release_lock.who"

package/dist/dev/lint.js

@@ -342,10 +342,10 @@ const CHECKS = {
             .map(({ target, option }) => ({ target, message: `${longName(option.flags)} has no role in the vocabulary` }));
     },
     "list-without-query": (document) => handwrittenLeaves(document)
-        .filter((command) => command.name === "list" && command.output !== undefined && command.query === undefined)
+        .filter((command) => command.name === "list" && command.query === undefined)
         .map((command) => ({
         target: label(command),
-        message: `answers with ${command.output?.entity} but takes no query`,
+        message: "list declares no query",
     })),
     "query-example": (document) => walk(document.commands).flatMap((command) => command.query
         ? exampleProblems(command.query).map(({ field, problem }) => ({

package/docs/standards/README.md

@@ -9,8 +9,8 @@ It ships in the `@wirecat/cli-base` package. A CLI that depends on cli-base has
 
 ## How to use this for a new CLI
 
-Start with the [New CLI](new-cli.md) checklist. Each step names the check that proves it and the area page whose
-rules it keeps. A new CLI is ready for its first release when every check under "Done when" passes.
+Start with the [New CLI](new-cli.md) page: `npx @wirecat/cli-template new` makes the repository, and the page lists
+the four steps that need a person. A new CLI is ready for its first release when every check under "Done when" passes.
 
 ## Which rule wins
 
@@ -32,7 +32,7 @@ rules it keeps. A new CLI is ready for its first release when every check under
 | [MCP](mcp.md) | `MCP` | 13 | The MCP tools, how they come from commands, what each permission shows |
 | [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` | 16 | Layers, dependency direction, vendor types, what goes in which package |
+| [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 |
 | [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 |
@@ -44,7 +44,8 @@ rules it keeps. A new CLI is ready for its first release when every check under
 | [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 |
-| [New CLI](new-cli.md) | — | — | The checklist for starting a new CLI |
+| [New CLI](new-cli.md) | — | — | Starting a new CLI from the template: the command, the four manual steps, the checks |
+| [Kit surface](kit-surface.md) | — | — | The cli-base and cli-core exports the template is built on, and how a change to one reaches you |
 
 Each count leaves out the ids that moved or merged (see "How ids work").
 

package/docs/standards/architecture.md

@@ -204,6 +204,24 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Exceptions:** none.
 - **Applies to:** cli-base. **Since:** cli-base 0.41.0. **Rulings:** NEED-15.
 
+### WC-ARCH-21 · A CLI registers its provider in the store; an unknown provider's rows are skipped, never guessed
+
+Every run, a CLI writes its provider's entry — `{ name, kind, aliases, command }` — with `registerProvider` from
+`@wirecat/cli-core/store`. cli-core reads its built-in providers plus the stored entries when the store opens, so
+every other CLI knows the new provider's kind without a cli-core release. A row whose provider no entry names is left
+out of search and listed under `skipped`, with the hint to run that CLI once.
+
+- **Why:** a new source joins search and memo without editing cli-core, and a provider nobody described is never read
+  as something it is not (until this rule, an unlisted provider was searched as a messenger).
+- **Enforced by:** `cli-core: src/store/sqlite/providers.test.ts`.
+- **Example:** cal registers `{ name: "google-calendar", kind: "events", aliases: ["cal"], command: "cal" }` each
+  time it starts. On a machine where cal has never run, a search across accounts lists cal's accounts under
+  `skipped` instead of reading their rows as messages.
+- **Exceptions:** the built-in providers of cli-core need no entry. Two entries that disagree on a kind are an error
+  naming both.
+- **Applies to:** cli-core and every CLI with a provider of its own. **Since:** cli-base 0.53.1. **Rulings:** none
+  (Wave 3 requirements 3.2).
+
 ## 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/data-model.md

@@ -33,6 +33,13 @@ is rewritten only to follow it:
   and nothing joins the two (WC-DATA-6).
 - `events` rows made from Zoom meetings have no source record of their own besides the meeting (WC-DATA-2 holds:
   `meetings` is that record).
+- Local folders are accounts with provider `folder` (an Obsidian vault and a plain folder look the same), and Drive's
+  stand-in account uses it too (WC-DATA-3).
+- Contacts live in `identities`, with no address column: an address is only the `external_id` of provider `email`
+  (WC-DATA-6).
+- `documents` keeps its source columns (`account_id`, `external_id`, `url`, `mime`, `front_matter`…) next to the
+  entity's own fields (WC-DATA-2).
+- `meeting_participants` is unique on the meeting and the contact; its `external_id` is in no unique key (WC-DATA-3).
 
 ## Rules
 
@@ -59,7 +66,7 @@ to its entity. One entity may combine source records from several sources and ac
 
 - **Why:** the same meeting in two calendars and in Zoom is one event to the owner; the same document in Drive and on
   disk is one document.
-- **Enforced by:** review only.
+- **Enforced by:** `cli-core: src/store/sqlite/schema.test.ts`, for the entity tables only; which table is which kind is review.
 - **Example:** a Google Calendar entry is a `calendar_entries` row with `event_id`; the Zoom recording of that meeting
   is a `meetings` row with the same `event_id`.
 - **Exceptions:** an entity the owner makes has no source record; a source record may wait unlinked until matching
@@ -73,7 +80,7 @@ record has no account). Never in a column named after the provider (`google_id`,
 `metadata`. A second id the provider also uses gets a named column of its own (`ical_uid`).
 
 - **Why:** one place to look for every provider's id, and one unique key to update a record by.
-- **Enforced by:** review only.
+- **Enforced by:** `cli-core: src/store/sqlite/schema.test.ts`.
 - **Example:** a Drive file: `files.external_id = '<Drive file id>'`; a Google calendar entry:
   `calendar_entries.external_id = '<event id>'`, `ical_uid = '<iCalUID>'`.
 - **Exceptions:** a local file has no provider id; its `external_id` is its path relative to its folder root.
@@ -103,7 +110,7 @@ Times are UTC milliseconds ([Time](time.md)).
 
 - **Why:** a reader of any table knows what a field holds, and a new table does not invent a third name for "edited
   at".
-- **Enforced by:** review only.
+- **Enforced by:** `cli-core: src/store/sqlite/schema.test.ts`.
 - **Example:** `files.external_updated_at`, not `modified_at` or `modifiedAt` in JSON.
 - **Exceptions:** existing columns keep their names until their table changes for another reason.
 - **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** NEED-1732.
@@ -141,17 +148,32 @@ link is made and the pair goes to the owner's review list. Title or time overlap
 
 ## Planned — not built yet
 
-From the Wave 3 requirements (cli-private `plans/2026-10-24-open-cli-core-design.md`, under the owner's review):
-
-- a `files` table as the source record of `documents`: a materialised `path` plus `parent_id` to the folder's own
-  row, so a folder is found by path prefix and a document by part of its path (NEED-1739);
-- memo's vault files as documents; an Obsidian vault is provider `obsidian` with its own metadata (tags, aliases,
-  wiki links), a plain folder is `local`; `notes` are only the owner's notes on entities (NEED-1738);
-- a cli-core helper that opens a CLI's own SQLite file (NEED-1737);
-- `calendars`, `calendar_entries` and `calendar_attendees` on the `events` hub;
-- an `email` column on contacts, so one address joins one person across sources;
-- one link log for events and documents, and one review list for ambiguous pairs;
-- renaming `identities` to `contacts`.
+From the Wave 3 requirements, approved by the owner on 2026-10-24 (cli-private
+`plans/2026-10-24-open-cli-core-design.md`, sections 3.3–3.6). Each item moves into the rules in the pull request that
+builds it.
+
+- **Files.** A `files` table holds the source records of `documents`: one row per item in one place (a local file, a
+  Drive file or folder, later a Notion page). It has `account_id`, `external_id` (a local file's path relative to its
+  root), `kind` (`file`, `folder`, `page`), `name`, `path` and `path_folded` from the account root, `parent_id` to the
+  folder's own row, `document_id`, the file facts and the provider's times (NEED-1739).
+- **Matching a file to a document:** the same account and `external_id` is the same file; a `content_hash` equal to
+  the preferred file of exactly one live document joins that document; more than one candidate goes to the review
+  list; otherwise a new document. The document shows its most recently changed file, unless the owner pins one.
+- **Folder accounts by kind.** Provider `obsidian` for a vault (front matter, tags, aliases and wiki links kept as
+  Obsidian's own metadata), `local` for a plain folder; Drive files under a real `google-drive` account. memo's vault
+  files are documents; `notes` are only the owner's notes on entities (NEED-1738).
+- **Calendars.** `calendars` and `calendar_entries` (source records) feed `events` and `event_series` (entities).
+  Attendees are `calendar_entry_participants`; changes to tracked fields go to `calendar_entry_revisions` first. An
+  entry joins an event by, in order: the same Google id; the same series slot (`original_starts_at`); the same
+  `ical_uid` in another calendar; a Zoom event with the same `join_key` and an overlapping time; else a new event.
+- **History on delete.** An event deleted in Google keeps its past occurrences with `source_deleted_at`; future ones
+  become `cancelled`. Nothing is removed without an explicit owner command (NEED-1764).
+- **Contacts by address.** A lower-cased `identities.email` column; contacts with the same address link to one
+  person (method `email`) unless the owner said otherwise; two persons with one address go to the review list.
+- **One link log and one review list.** `entity_link_events` logs link changes for events and documents in the shape
+  of `identity_link_events`; one review list of ambiguous pairs for every entity, resolved by the owner.
+- **A CLI's own SQLite file**, opened through a cli-core helper ([Store](store.md), NEED-1737).
+- **Later:** renaming `identities` to `contacts`; dropping `documents`' source columns once nothing reads them.
 
 ## Sources
 

package/docs/standards/kit-surface.md

@@ -0,0 +1,50 @@
+# Kit surface
+
+## Scope
+
+These are the parts of cli-core and cli-base that the template is built on. A CLI started with
+`npx @wirecat/cli-template new` imports them from its first commit. When one of them changes in a way your code must
+follow, the changelog gives the steps, and the template is already updated, so `npx @wirecat/cli-template upgrade`
+brings the change into your CLI.
+
+This page is a reference, not a rule page: it assigns no rule ids. How to start a CLI from the template is on the
+[New CLI](new-cli.md) page. How a release is made is on the [Releases](releases.md) page.
+
+## What the template imports
+
+The list is what the template's `src/` imports today, type imports included.
+
+| Package and path | Exports |
+|---|---|
+| `@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/mcp` | `McpCommand`, `registerCommands`, `runCommandForAgent`, `toolsFromCommands` |
+| `@wirecat/cli-core/sends` | `Level` |
+| `@wirecat/cli-core/update` | `appUpdate` |
+| `@wirecat/cli-core/testing` | `ARGV_LOG`, `argvLogSetup` |
+
+## When one of them changes
+
+A change that makes a CLI change its code for one of these exports ships with two things:
+
+1. **A migration note in the changelog**, under "Changed — may break callers": what to change in your code, step by
+   step. See [Documents](docs.md) for the changelog's shape.
+2. **A green cli-template job before the pull request merges.** cli-base and cli-core build the template against
+   each pull request, so the template is updated in the same change, and `upgrade` has the new version to bring.
+
+## How your CLI stays current
+
+- **Exact versions.** The template depends on `@wirecat/cli-base` and `@wirecat/cli-core` at exact versions, the
+  normal setup for every WireCat CLI. A CLI made from it starts with the same pins.
+- **Dependabot.** The template's `dependabot.yml` checks `@wirecat/*` every day and opens one pull request for the
+  shared packages within a day of a release. Its CI shows whether anything else needs to change.
+- **`upgrade`.** In your CLI, with a clean git working tree:
+
+  ```sh
+  npx @wirecat/cli-template upgrade
+  ```
+
+  For each template file that changed since your version, it asks: apply (merge the change into your file, keeping
+  your edits), replace, skip or diff. Without a terminal, `--apply`, `--replace` or `--skip` answers for every file,
+  and `--dry-run` lists what each file would get. Then re-run community's `adopt-standards.py` for `config/wirecat/`.

package/docs/standards/new-cli.md

@@ -1,100 +1,81 @@
 # New CLI
 
-<!-- cspell:ignore rumdl whatsapp -->
-
 ## Scope
 
-The steps to start a new WireCat CLI and the checks that prove each step. Every item names the check that proves
-it, or the handbook page whose rules it keeps. A new CLI is done when every check in "Done when" passes.
+How to start a new WireCat CLI: one command that copies the template, the four steps that need a person, and the
+checks that prove the result. A new CLI is done when every check in "Done when" passes.
 
 This page is a checklist, not a rule page: it assigns no rule ids. The rules are on the area pages it links. How to
-read a rule and which rule wins are in the [index](README.md).
-
-whatsapp-cli is the worked example: it has every file below. Compare with it when a step is unclear.
-
-## Start from the shared standards
-
-1. **Create the repository** under `WireCatLabs`, with a `main` branch that takes changes only through pull requests.
-   Proved by: the repository ruleset. See [Releases](releases.md).
-2. **Install the community presets.** From a reviewed checkout of
-   [WireCatLabs/community](https://github.com/WireCatLabs/community):
-
-   ```sh
-   python3 scripts/adopt-standards.py ../whatsapp-cli
-   ```
-
-   This is the command that was run for whatsapp-cli; use your new repository's folder instead.
-
-   The installer copies the Biome base, the grit plugins, cspell, markdownlint, rumdl, lefthook and the release lock
-   helper into `config/wirecat/`, pins the tool versions, records the file hashes and writes the `standards.yml`
-   workflow. Commit the result with the lockfile. Proved by: `pnpm standards:check`, run by `standards.yml`.
-3. **Copy community's `monthly.yml` template** into `.github/workflows/`, and set its cron to a day no other
-   repository uses. Proved by: the workflow appears in the Actions tab. See [CI](ci.md).
-4. **Add `pr.yml`**, the pull request validation that calls `ci.yml` with platform suites skipped, as shown in
-   [WC-CI-5](ci.md#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out).
-   Proved by: the `validation` check on the first pull request.
-
-## Toolchain
-
-1. **Depend on the shared packages at exact versions.** `@wirecat/cli-base` always, at 0.41.0 or later: it is the
-   first version that ships this handbook and the `cli-dev` lint and audit that the checks below run.
-   `@wirecat/cli-core` as well when the CLI is a messenger or uses the shared store, search, MCP server or send guard.
-   What cli-core already does, the new CLI does not do again. See [Architecture](architecture.md).
-2. **Extend the shared TypeScript configuration**: `@wirecat/cli-base/tsconfig.base.json` for `src/`,
-   `tsconfig.test.json` for tests and `tsconfig.scripts.json` for `scripts/`. Every directory with `.ts` files is in a
-   project the build checks. Proved by: `pnpm typecheck`.
-3. **Extend the community Biome base** (`./config/wirecat/biome.base.json`) in the root `biome.json`, and add the
-   project rules there: the 1,000-line file cap, import cycles and the layer imports. Proved by: `pnpm lint`. See
-   [Toolchain](toolchain.md) and [Layout](layout.md).
-4. **Add `ci:quick`**: typecheck, build and `cli-dev lint`. Proved by: the pull request CI. See [CI](ci.md).
-
-## Commands every CLI has
-
-1. **The required root commands.** `cli-dev audit` checks these six paths:
-   - `commands`: the command tree as JSON, which agents and the audit read.
-   - `doctor`: checks this machine and the profile, and says what to fix. `doctor --online` logs in once, never
-     retries, sends nothing and marks nothing read (ruling NEED-288).
-   - `skill show` and `skill install`: print and install the agent skill from `skills/<cli>/SKILL.md`, which the
-     package ships. A missing or older skill is suggested on stderr at most once a day (ruling NEED-797).
-   - `mcp`: the MCP server. Its tools are generated from the commands. See [MCP](mcp.md).
-   - `upgrade`: updates the CLI.
-
-   Proved by: `cli-dev audit --for <cli>`, rule `required-root`. A CLI on cli-core gets these from cli-core.
-2. **`config`, where the CLI has settings.** cli-core provides it. It is not a required root. See
-   [Accounts](accounts.md) for the profile, which is always explicit.
-3. **Every command declares its effects and its lifetime**, and has a summary, described arguments and options, and
-   examples. Proved by: `cli-dev lint`. See [Commands](commands.md), [Output](output.md) and
-   [Lifecycle](lifecycle.md).
-4. **Every write is gated by a permission.** See [Permissions](permissions.md).
-5. **Add the CLI to the `all` parity group** in cli-base's `PARITY_GROUPS`. That group compares the shared root
-   commands. Proved by: `cli-dev audit`, rule `same-path-contract`. A messenger also joins cli-core's `parity.json`,
-   which `pnpm parity:check` reads. See [Testing](testing.md).
-
-## Files to add
-
-1. **`CLAUDE.md`** (and `AGENTS.md`, if the repository has one): a short file. It links this handbook at
-   `node_modules/@wirecat/cli-base/docs/standards/README.md`, lists the CLI's "Local rules" below that link, and says
-   where the private working folder lives. It does not restate handbook rules. See [Documents](docs.md).
-2. **`lint/baseline/`** and `lint/overrides.json`: written once with `cli-dev lint --write-baseline`. The baseline only
-   shrinks, and at most 10 overrides are allowed. Proved by: `cli-dev lint`.
-3. **The test setup**: `vitest.config.ts` with a `setupFiles` line that points configuration, state, cache and the
-   store at a temporary directory, and coverage thresholds. Proved by: `pnpm test`. See [Testing](testing.md) and
-   [Store](store.md).
-4. **`contracts/plan.json`** and its reviewed snapshots for `cli-contract` (cli-testing): help, discovery JSON, MCP
-   tools and the no-leak check. Proved by: `pnpm contracts:check`. See [Testing](testing.md).
-5. **The test matrix**: `docs/dev/test-matrix.md`, built by `cli-dev test-matrix`. Proved by:
-   `cli-dev test-matrix --check`.
-6. **The user pages**: `README.md`, `docs/meta.json` and the shared page set, with `docs/commands.md` generated from
-   the program. Proved by: `cli-dev docs-check --pages` and the CLI's `generate:check`. See [Documents](docs.md).
-7. **`CHANGELOG.md`** with `## Unreleased` at the top and the shared headings, and
-   **`.github/workflows/changelog-guard.yml`** calling cli-base's `changelog-guard.yml` at a pinned commit. Proved by:
-   `cli-dev docs-check` and the guard on the first pull request. See [Documents](docs.md).
-8. **`SECURITY.md`**: how to report a vulnerability, linking cli-testing's security method. See
-   [Security](security.md).
-9. **`bin/release`**, **`release.yml`** and a release skill, copied from the nearest CLI. `bin/release` takes the
-   release lock (WC-REL-3) and npm's trusted publisher settings name `release.yml`. A messenger CLI also checks a signed
-   release report (WC-REL-10). See [Releases](releases.md).
-10. **`src/version.ts`** kept in step with `package.json`. Proved by: `pnpm version:check`.
+read a rule and which rule wins are in the [index](README.md). The parts of cli-base and cli-core the template is
+built on are on the [Kit surface](kit-surface.md) page.
+
+## Start with the template
+
+```sh
+npx @wirecat/cli-template new cal-cli --command cal --package @wirecat/cal-cli --owner WireCatLabs \
+  --category calendar --content-lang en,ru --sign-in oauth --api official-client --filters time,person,text \
+  --never-store tokens,secret-links --untrusted names,links
+```
+
+In a terminal, `new` asks for every answer you leave out. Without a terminal, a missing answer is an error that lists
+the choices. Nothing is guessed.
+
+| Flag | What it sets | Choices |
+|---|---|---|
+| `<name>-cli` | the repository folder | any name |
+| `--command` | the command word people type | one word |
+| `--package` | the npm package name | a scoped name, such as `@wirecat/cal-cli` |
+| `--owner` | the GitHub owner of the repository | an owner |
+| `--category` | what the CLI reads | `messenger`, `mail`, `notes`, `files`, `calendar`, `meetings` |
+| `--content-lang` | the languages of the content | a list, such as `en,ru` |
+| `--sign-in` | how the CLI signs in | `oauth`, `token`, `session`, `none` |
+| `--api` | what the service offers | `official-client`, `official-docs`, `unofficial` |
+| `--filters` | how people narrow a list | a list of `time`, `person`, `container`, `text`, `status` |
+| `--never-store` | what the store must never keep | a list of `tokens`, `codes`, `secret-links`, `content` |
+| `--untrusted` | what text comes from other people | a list of `messages`, `files`, `links`, `names`, or `none` |
+
+Every choice question also takes `other:<your answer>`.
+
+`new` copies the template of its own package version into `<name>-cli/`, renames the command word everywhere, runs
+`git init`, records the template version in `template.json`, writes `docs/dev/DESIGN.md` from your answers and names
+a reference CLI for your category in `AGENTS.md`. It does not install packages, push, create the repository or
+publish. Then:
+
+```sh
+cd cal-cli && pnpm install && pnpm ci:quick
+git add -A && git commit -m "chore: start from @wirecat/cli-template"
+```
+
+Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `cal personal doctor`.
+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
+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.
+The rules they keep are on the area pages: [Commands](commands.md), [MCP](mcp.md), [Accounts](accounts.md),
+[Permissions](permissions.md), [Testing](testing.md), [Documents](docs.md), [Releases](releases.md) and [CI](ci.md).
+
+Later template changes come in with `npx @wirecat/cli-template upgrade`, file by file: apply, replace, skip or diff.
+See [Kit surface](kit-surface.md#how-your-cli-stays-current).
+
+## Four steps that need a person
+
+`new` prints these at the end.
+
+1. **Create the repository** under the owner, with a ruleset on the default branch: no deletion, no force push,
+   changes only through a pull request, required status checks, and no bypass. Add the ruleset after the first
+   commit is on `main`, since a pull request rule leaves an empty repository no way to get one, and the required
+   check names exist only once CI has run. See [Releases](releases.md).
+2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. See
+   [WC-REL-11](releases.md#wc-rel-11--publish-from-github-actions-with-npm-trusted-publishing).
+3. **Pick a monthly cron day** no other repository uses. `.github/workflows/monthly.yml` holds a placeholder that CI
+   rejects. See [CI](ci.md).
+4. **WireCat CLIs only: join the shared lists.** A pull request to cli-base's `PARITY_GROUPS` (at least the `all`
+   group, which compares the shared root commands), a line in cli-core's `WIRECAT_TOOLS` and a line in cli-docs'
+   `tools.json`. A messenger also joins cli-core's `parity.json`. A CLI outside WireCatLabs keeps its parity groups
+   in its own repository and runs `cli-dev audit --groups <file>`. See [Testing](testing.md).
 
 ## Done when
 

package/docs/standards/releases.md

@@ -32,9 +32,10 @@ on the [CI](ci.md) page.
 - **Exceptions:** none.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
-### WC-REL-3 · `bin/release` takes the machine release lock before it builds or publishes
+### WC-REL-3 · `bin/release` takes its package's release lock before it builds or publishes
 
-- **Why:** two sessions published at the same time on one machine; one release at a time, across every package.
+- **Why:** two sessions published the same package at the same time on one machine. Different packages do not
+  conflict, so each package has its own lock and they release side by side.
 - **Enforced by:** `<app>: bin/release`.
 - **Example:**
 
@@ -44,9 +45,12 @@ on the [CI](ci.md) page.
   ```
 
   The helper comes from the community presets (`adopt-standards.py --only release-lock`). It holds
-  `${XDG_RUNTIME_DIR:-/tmp}/leemour-release.lock` with `flock` on file descriptor 9 until the release ends.
-- **Exceptions:** none. cli-testing still opens the lock with its own `flock` line and moves to the helper.
-- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-854.
+  `${XDG_RUNTIME_DIR:-/tmp}/leemour-release-<key>.lock` with `flock` on file descriptor 9 until the release ends.
+  `<key>` is the `name` in `package.json`, made safe for a file name: `@wirecat/cli-core` locks
+  `leemour-release-wirecat-cli-core.lock`. The key is the package, not the folder, so every checkout and worktree
+  of one package shares the lock. A `package.json` without a name refuses the release.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-854, ASK-336.
 
 ### WC-REL-4 · Never break the release lock; wait for the holder and try again
 
@@ -95,7 +99,8 @@ on the [CI](ci.md) page.
 - **Enforced by:** review only.
 - **Example:** tg-cli can release an hour after its last version, and cli-core can ship a breaking change on the same
   day as the previous one. Bump the library in every CLI that uses it on the day it ships.
-- **Exceptions:** none. The release lock (WC-REL-3) still keeps two releases on one machine from running at once.
+- **Exceptions:** none. The release lock (WC-REL-3) still keeps two releases of one package on one machine from
+  running at once.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.52.0. **Rulings:** NEED-1741.
 
 ### WC-REL-9 · Merged into [WC-REL-8](#wc-rel-8--any-package-may-release-at-any-time)

package/docs/standards/security.md

@@ -1,6 +1,6 @@
 # Security
 
-<!-- cspell:words zizmor -->
+<!-- cspell:words zizmor PKCE -->
 
 ## Scope
 
@@ -271,6 +271,21 @@ not carried out. A name that matches is not proof of who someone is.
   tells an agent about it is [WC-MCP-11](mcp.md#wc-mcp-11--the-server-tells-the-agent-that-message-text-is-data).
 - **Applies to:** all CLIs. **Since:** cli-base 0.44.0. **Rulings:** none.
 
+## Planned — not built yet
+
+From the Wave 3 requirements, approved by the owner on 2026-10-24 (sections 3.4 and 3.7). Each item moves into the
+rules in the pull request that builds it.
+
+- **One sign-in module** in cli-core, `@wirecat/cli-core/oauth`, with no store and no search: authorize (a loopback
+  address on `127.0.0.1` or a relay page, `state`, PKCE S256, a timeout, cancel, a paste fallback), exchange, refresh
+  and revoke, and a token keeper with a lock per profile across processes. A CLI declares its provider and may
+  replace any step, but keeps the explicit profile, the lock, and tokens that are never printed (NEED-1734).
+- **Keys in one place:** one keyring naming scheme for new entries; today's entries of drive and zm are read as they
+  are, so no one signs in again.
+- **Meeting secrets never reach the store:** passcodes, PINs, passwords and access codes from a calendar's conference
+  data, and the query string of any join URL. Lines of a description that carry a passcode, password or PIN are
+  removed.
+
 ## 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/store.md

@@ -185,6 +185,17 @@ messages), or other people's data.
 - **Exceptions:** none.
 - **Applies to:** all CLIs that use the store, and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
 
+## Planned — not built yet
+
+From the Wave 3 requirements, approved by the owner on 2026-10-24 (NEED-1737). It moves into the rules in the pull
+request that builds the helper.
+
+- **A CLI's own tables live in its own SQLite file**, next to the shared store, with its own migrations. They refer to
+  core rows by id only, and no other CLI opens that file. A cli-core helper opens it (the path, the migrations, the
+  same driver); it is built when the first CLI needs private tables.
+- **WC-STORE-5 gets a check:** a grit plugin, `no-sqlite-driver`, that refuses a CLI's import of a SQLite driver or
+  of `drizzle-orm`. cli-core, which owns the store, turns it off.
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page

package/package.json

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