@wirecat/cli-base 0.63.0 → 0.65.0

package/docs/standards/accounts.md

@@ -3,7 +3,7 @@
 ## Scope
 
 How a CLI chooses an account: the profile is always explicit, a read across accounts covers all of them and says so,
-and scope flags work the same everywhere.
+scope flags work the same everywhere, and sign-in has the same four commands in every CLI.
 
 A **profile** is the name of one login of a CLI on one computer, for example `personal` or `work`. One profile can
 hold a personal session, a bot token, or both.
@@ -16,7 +16,8 @@ Rule ids on this page are `WC-ACCT-<n>`. How to read a rule, how ids work and wh
 cli-core resolves the profile for tg, max and wa. WC-ACCT-1 needs cli-core 0.319.0 or newer. memo has no messenger profile: its shared commands run without one, and they pick accounts with `--provider`
 and `--account` (WC-ACCT-7). zoom resolves its own profile word by the same rules (`zm <profile> …`, `ZM_PROFILE`,
 `ZM_PROFILE_LOCK`) from zoom-cli 0.35.0, with cli-core's `liftProfile` and `usableProfileName`. drive still has its own
-profile code: it registers its own profiles. That is a known gap, not an exception.
+profile code: it registers its own profiles. That is a known gap, not an exception. gcal resolves the profile through
+cli-core's `run()`, like tg, max and wa. Which CLIs lack a sign-in command of WC-ACCT-12 is listed in that rule.
 
 ## Rules
 
@@ -31,9 +32,11 @@ on the computer.
 - **Example:** `tg personal chats list`, or `TG_PROFILE=personal tg chats list`. When no profile is named and the
   config file still has `default_profile`, cli-core stops and says which profile to type. `config set default_profile`
   is refused.
-- **Exceptions:** a command that touches no account runs without a profile, for example `account list`,
-  `config show` and `commands`.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-84.
+- **Exceptions:** a command that touches no account runs without a profile, for example `session list`
+  ([WC-ACCT-12](#wc-acct-12--sign-in-is-session-start-status-and-end-and-session-list-names-the-profiles)),
+  `config show` and `commands`; tg, max and wa still name their list `account list`. `mcp serve` may name its profiles with `--profiles <names|all>` instead
+  ([WC-MCP-9](mcp.md#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each)); `all` is the owner's explicit choice, never a fallback.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-84, NEED-1881.
 
 ### WC-ACCT-2 · The profile is a word, never a flag
 
@@ -44,8 +47,9 @@ profile.
 - **Enforced by:** `cli-core: src/cli/profile.test.ts`.
 - **Example:** `max work bot messages send …` uses the same first word as `max work chats list`. `tg --json chats list`
   still works, because `--json` is an option.
-- **Exceptions:** none.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-84, NEED-294.
+- **Exceptions:** `mcp serve --profiles <names|all>` names the profiles one server serves ([WC-MCP-9](mcp.md#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each)). It is used in
+  place of the first word, never with it.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-84, NEED-294, NEED-1881.
 
 ### WC-ACCT-3 · A missing profile is an error that lists the choices
 
@@ -57,8 +61,8 @@ CLI with a `setup` command suggests it, and any other CLI suggests the command t
 - **Enforced by:** `cli-core: src/cli/settings.test.ts` · `cli-core: src/cli/program.test.ts`.
 - **Example:** ``name a profile: `tg <profile> …` — profiles here: personal, work (or set TG_PROFILE)``. With none,
   tg, which has `setup`, says to ``create one with `tg personal setup` (any name in place of personal)``. A CLI
-  without `setup`, such as one made from cli-template, answers `cal events list` with ``name a profile: there is none
-  on this computer yet — any name works, such as `cal personal events list` (or set CAL_PROFILE)`` (cli-core 0.424.0
+  without `setup`, such as one made from cli-template, answers `gcal events list` with ``name a profile: there is none
+  on this computer yet — any name works, such as `gcal personal events list` (or set GCAL_PROFILE)`` (cli-core 0.424.0
   and later).
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
@@ -78,8 +82,8 @@ top-level command, such as `chats` or `bot`, is refused when the profile is crea
 
 ### WC-ACCT-5 · A profile lock pins a process to one profile
 
-When `<PREFIX>_PROFILE_LOCK` is set, a first word or `<PREFIX>_PROFILE` that names any other profile is refused with
-`permission_error`.
+When `<PREFIX>_PROFILE_LOCK` is set, a first word, `<PREFIX>_PROFILE` or `mcp serve --profiles` that names any other
+profile is refused with `permission_error`. `--profiles all` names every profile, so it is refused too.
 
 - **Why:** an agent must not escape its guards by naming a profile with fewer of them.
 - **Enforced by:** `cli-core: src/cli/settings.test.ts`.
@@ -155,6 +159,35 @@ inferred from a matching name, and `unlink` undoes it.
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.43.1. **Rulings:** none.
 
+### WC-ACCT-12 · Sign-in is `session start`, `status` and `end`, and `session list` names the profiles
+
+Every CLI that signs in has four commands under `session`:
+
+- `<cli> <profile> session start` signs the profile in.
+- `<cli> <profile> session status` says whether this profile is signed in, and as whom.
+- `<cli> <profile> session end` signs the profile out and forgets its login.
+- `<cli> session list` takes no profile and lists the profiles on this computer.
+
+`status` answers about one profile; `list` answers which profiles exist. Neither one connects to more than it must:
+`list` reads only what the computer holds.
+
+- **Why:** the owner and an agent look for sign-in in the same place in every CLI. Today each CLI has a different
+  part of the set, so an agent that learned one CLI guesses wrong in the next.
+- **Enforced by:** review only.
+- **Example:** `gcal personal session status` answers whether the `personal` profile holds a Google login;
+  `gcal session list` lists `personal` and `work` with no profile named.
+- **Exceptions:** known gaps, as of 2026-10-27:
+  - tg, max and wa have `session start` and `session end`, no `session status`, and list their profiles with
+    `account list` instead of `session list`.
+  - drive has `session start`, `session list` and `session end`, and no `session status`.
+  - gcal has `session start`, `session status` and `session end`, and no `session list`.
+  - zm has `session start` and `session status`, and no `session end` or `session list`.
+  - memo signs in per mail account with `mail add` and has no `session` group.
+
+  A CLI that adds a missing command adds it under `session`; a renamed path keeps no alias
+  ([WC-CMD-8](commands.md#wc-cmd-8--keep-no-aliases-a-renamed-path-stops-working-in-the-release-that-renames-it)).
+- **Applies to:** every CLI that signs in. **Since:** cli-base 0.65.0. **Rulings:** NEED-1884.
+
 ## 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/architecture.md

@@ -20,7 +20,9 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Service:** a use case, written once, that both a command and an MCP tool call.
 - **Composition root:** the place in a CLI where real implementations are chosen and connected, usually
   `program.ts` and the command context.
-- **Vendor type:** a type from a provider library, such as `@mtcute/*` or `ws`.
+- **Vendor type:** a type from a provider library, such as `@mtcute/*` or `ws`, and a type generated from a
+  provider's API description, such as gcal's and drive's types under `src/generated/` from a Google Discovery
+  document: both change when the provider changes, not when we do.
 
 ## Rules
 
@@ -57,7 +59,9 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
   `src/adapter/` maps the client onto the shared messenger port. A field that only one provider has travels in
   `providerMetadata`.
 - **Exceptions:** a bot slice that talks to an official HTTP API keeps its own transport, beside the personal
-  account's adapter, never above it.
+  account's adapter, never above it. Generated API types may also be used by the generated `api <method>` commands,
+  which are the provider's own API by design; the shared ports and services never see them. In gcal,
+  `calendar-source.ts` and `calendar-writer.ts` translate the generated event type into cli-core's calendar entry.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-12.
 
 ### WC-ARCH-4 · Put code in the lowest shared package that can hold it
@@ -77,14 +81,16 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 
 ### WC-ARCH-5 · Build a feature that another provider could have as a shared command behind a capability
 
-- **Why:** a command written once in cli-core gives every messenger the same path, flags and output.
+- **Why:** a command written once in cli-core gives every provider of a kind the same path, flags and output.
 - **Enforced by:** review only.
 - **Example:** topics and polls are port groups and shared commands in cli-core. A messenger that lacks a capability
   refuses the command; it does not silently do less. A bot is another messenger with fewer capabilities, and tg and
-  max share the bot code.
-- **Exceptions:** a feature stays in one CLI only when the other providers cannot have it, such as MAX's socket server
-  or Telegram's app registration.
-- **Applies to:** messenger CLIs (tg, max, wa). **Since:** cli-base 0.41.0. **Rulings:** NEED-820, NEED-440,
+  max share the bot code. Calendars have the same shape: cli-core's `addCalendarCommands` builds `calendars`,
+  `sync`, `status`, `events` and `search` over the `CalendarSource` and `CalendarWriter` ports, and mounts
+  `calendars busy` or the event writes only when the provider has them.
+- **Exceptions:** a feature stays in one CLI only when the other providers cannot have it, such as MAX's socket server,
+  Telegram's app registration, or gcal's generated `api` commands.
+- **Applies to:** messenger CLIs (tg, max, wa) and calendar CLIs (gcal). **Since:** cli-base 0.41.0. **Rulings:** NEED-820, NEED-440,
   NEED-301, NEED-444.
 
 ### WC-ARCH-6 · Replace a use case, not a command
@@ -93,9 +99,10 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Enforced by:** review only.
 - **Example:** `Messenger.services` receives the shared services and returns only the ones it changes:
   `services: (base) => ({ messages: { ...base.messages, list: maxList } })`. To add a subcommand, a CLI calls
-  `addCommand` on the command a factory returns.
+  `addCommand` on the command a factory returns. A calendar CLI changes what the shared calendar commands do through
+  the source and writer it passes to `addCalendarCommands`, never by writing its own `sync` or `events list`.
 - **Exceptions:** none.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** messenger CLIs and calendar CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-ARCH-7 · Keep policy in the service; a command or MCP handler only parses input and presents the result
 
@@ -215,9 +222,9 @@ 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.
+- **Example:** gcal registers `{ name: "google-calendar", kind: "events", aliases: ["gcal", "calendar"], command:
+  "gcal" }` each time it opens the store. On a machine where gcal has never run, a search across accounts lists
+  gcal'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.0. **Rulings:** none

package/docs/standards/ci.md

@@ -10,8 +10,9 @@ Rule ids on this page are `WC-CI-<n>`. How to read a rule, how ids work and whic
 [Releases page](releases.md); which scanners must exist and how workflows are hardened is on the
 [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-template follows every rule here as a CLI does
+"The WireCat repositories" on this page means every WireCat CLI (today tg, max, memo, drive, zoom, wa and gcal; a
+CLI made with `npx @wirecat/cli-template new` counts from its first commit), cli-base, cli-core, 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
@@ -24,7 +25,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   `gitleaks git --staged --redact`. A clone without gitleaks gets a warning and can still commit; CI scans anyway.
   The `prepare` script installs the hooks; `LEFTHOOK=0 git commit` skips them for one commit.
 - **Exceptions:** none.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-2 · Add no push hook, and no hook that installs, builds, checks types, generates or tests
 
@@ -34,7 +35,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   does not run `standards:check`, the full lint, spelling, a build or the test suite on each commit or push; it runs a
   targeted check when it needs one.
 - **Exceptions:** none. cli-base `config/lefthook.yml` still has a pre-push typecheck, but no repository extends it.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-3 · Run the fast standards job on every pull request and every push to `main`
 
@@ -45,7 +46,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   commit cancels the run it replaces. The job times out after five minutes, a ceiling for a stalled setup, not an
   expected time.
 - **Exceptions:** none. Runner queues and cold downloads are outside the budget.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-4 · Keep `ci:quick` to early bug checks that finish within two minutes
 
@@ -61,7 +62,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
 - **Exceptions:** never put live-account suites, agent suites or platform jobs here. Full tests and coverage run in
   the pull request validation job ([WC-CI-5](#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out)),
   not in `ci:quick`.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-5 · Run the full Linux validation on every pull request, and keep platform suites out
 
@@ -139,10 +140,13 @@ cannot pass yet; the `skip` input names it.
 
 The shared workflows are not in the npm package, because CI runs the pinned commit, not the installed copy. To see
 what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/…@<commit>` lines in `ci.yml`,
-`release.yml` and `monthly.yml`, and opens each workflow file at that commit in cli-base.
+`release.yml` and `monthly.yml`, and opens each workflow file at that commit in cli-base. The fresh-agent audit on the
+[New CLI](new-cli.md#done-when) page is given these files for this reason, beside the handbook and the repository;
+its prompt in cli-template says so from cli-template 0.8.0. A CLI on an older template takes the prompt with
+`upgrade`.
 
 - **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.
+  breaking every repository at once.
 - **Enforced by:** `ci.yml:ci`.
 - **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
@@ -158,12 +162,29 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
 - **Example:** `monthly.yml`, from the community template, calls the repository's `ci.yml` and the pinned cli-base
   `release-checks.yml`. Each repository has its own minute, between 02:17 and 03:20 UTC, so runs do not overlap. No
   check compares the minutes across repositories; review keeps them apart. A CLI made from cli-template starts with
-  the template's own minute and changes it (see [New CLI](new-cli.md)).
+  the template's own minute and changes it (see [New CLI](new-cli.md)). Taken minutes, from each `monthly.yml` on
+  the default branch:
+
+  | UTC | Repository |
+  |---|---|
+  | 02:17 | cli-base |
+  | 02:24 | whatsapp-cli |
+  | 02:27 | gcal-cli |
+  | 02:31 | cli-memo |
+  | 02:38 | cli-core |
+  | 02:45 | drive-cli |
+  | 02:52 | cli-testing |
+  | 02:59 | max-cli |
+  | 03:02 | cli-template |
+  | 03:06 | tg-cli |
+  | 03:13 | zoom-cli |
+  | 03:20 | cli-docs |
+
 - **Exceptions:** cli-core also builds and probes its native packages in their own workflows, after the window:
   `onnx.yml` at 03:27 and `sqlite.yml` at 03:37 UTC. A scheduled run of either never publishes; only a manual run
   with `publish` does. community has no build, so it runs only the release security checks, at 03:47 UTC. A monthly
   run never publishes a package or deploys the site.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-10 · Run heavy security checks only at release, monthly or on request
 
@@ -177,7 +198,7 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
   job ([WC-CI-5](#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out)); it
   takes seconds. The dependency audit, `zizmor` and CodeQL stay out. Do not add a heavy scanner to an editor hook, a
   stop hook or an ordinary pull request job.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** sc:9.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** sc:9.
 
 ### WC-CI-11 · Moved to [WC-SECR-20](security.md#wc-secr-20--pin-each-third-party-action-to-a-commit-and-give-each-workflow-read-only-defaults)
 
@@ -195,7 +216,7 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
   release changes `main` the same way
   ([WC-REL-2](releases.md#wc-rel-2--main-changes-only-through-a-pull-request-also-during-a-release)).
 - **Exceptions:** none.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** NEED-381.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** NEED-381.
 
 ### WC-CI-13 · Start no live messenger or account test from a workflow
 

package/docs/standards/commands.md

@@ -75,10 +75,12 @@ catalogue and parity manifest stay in cli-core
 - **Why:** an option that turns a command into a different report hides that report from anyone reading the tree.
 - **Enforced by:** review only.
 - **Example:** ranking is `stats messages top`, not a ranking mode on `search messages`. Options choose the scope,
-  measure, order or format of the same action. No command both shows and changes something.
+  measure, order or format of the same action. No command both shows and changes something; saving what it read
+  into the local store is not a change ([WC-CMD-17](#wc-cmd-17--declare-effects-on-every-command)).
 - **Exceptions:** a documented preparatory fetch such as `--sync-first`. It keeps its own permissions and reports
   its outcome.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1880 (`mcp revoke` is its own command; it
+  replaces NEED-1864, which kept `--revoke` as an option on `mcp`).
 
 ### WC-CMD-7 · Never let two commands overlap
 
@@ -116,9 +118,16 @@ catalogue and parity manifest stay in cli-core
 - **Why:** `--limit` must mean "how many items" in every command of every CLI.
 - **Enforced by:** `flag-synonym` · `flag-two-meanings` · `same-flag-meaning` (weekly audit; it does not block a pull
   request yet).
-- **Example:** `--limit <n>`, never `--max`, `--take` or `--count`. `--cursor <cursor>`, never `--offset`. How much
-  to read is `--limit`, `--page` and `--page-size`. A count of pages is never an option.
-- **Exceptions:** generated commands (`bot api`) are exempt from the naming rules.
+- **Example:** `--limit <n>`, never `--max`, `--take` or `--count`. `--cursor <cursor>`, never `--offset`. How big
+  the answer is: `--limit`, `--page` and `--page-size`; a count of pages is never a paging option. How much work a
+  command may do is a `budget` option: `--max-pages <pages>` caps the pages a sync reads from the source, and
+  `--max-output-bytes` the size of the answer. A budget changes how far the command gets, never which items one page
+  of the answer holds. A retry after `outcome_unknown` is `--operation-id`: the attempt in the send journal. The
+  calendar vocabulary's `--id <id>` is a different value: the provider's own id for a thing being created, chosen
+  before the create, so a retry finds it at the provider. A CLI whose provider takes such an id may offer both.
+- **Exceptions:** generated commands (`bot api`) are exempt from the naming rules. Known gap, as of 2026-10-27: gcal's
+  `events create` offers `--id` and no `--operation-id`, so its `outcome_unknown` names the event id instead of an
+  `operation_id` (WC-LIFE-9, WC-OUT-10).
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CMD-11 · Name an option in plain words, with the kind of value in the name
@@ -128,7 +137,10 @@ catalogue and parity manifest stay in cli-core
 - **Example:** `--operation-id`, not `--cid`. `--before-id` takes a message id, `--after-time` a time, `--before-n` a
   count: two kinds are two options. A length of time is a `<duration>` with a unit (`500ms`, `30s`, `2m`, `4h`, `1d`),
   never a bare number.
-- **Exceptions:** none.
+- **Exceptions:** `--duration-minutes <minutes>` (zm's meeting length, gcal's `calendars busy`) takes a bare count of
+  minutes. It is a known gap in the vocabulary, as of 2026-10-27: it stays until the vocabulary has
+  `--duration <duration>`, and then moves in the release that adds it, under "Changed — may break callers". No new
+  option follows it.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CMD-12 · Give every option a role from the vocabulary, and filter a list with its query
@@ -187,13 +199,25 @@ Each of these is set with `annotate(command, { … })` from `@wirecat/cli-base/c
 
 ### WC-CMD-17 · Declare `effects` on every command
 
+A command **writes** when it changes something on the service (`remote: "write"`), or when it changes the local
+store or files without reading the service first (`remote: "none"`, `local: "write"`, such as `store reindex` or
+`config set`). A command that reads the service and only saves what it read into the owner's local store
+(`{ remote: "read", local: "write" }`, such as `sync` or `calendars list`) is a **read**: on the command line, in
+[WC-CMD-6](#wc-cmd-6--give-one-action-or-one-report-one-leaf-command), over MCP
+([WC-MCP-4](mcp.md#wc-mcp-4--read-runs-only-reading-commands-and-write-only-writing-ones)) and as a next step
+([WC-OUT-9](output.md#wc-out-9--offer-at-most-two-next-steps-and-mark-a-step-safe-only-when-it-changes-nothing-on-the-service)).
+
 - **Why:** retries and unasked next steps are judged on effects, and a command without them counts as a write.
 - **Enforced by:** `missing-command-effects` · `cli-core: src/cli/effects.test.ts` · `cli-memo: src/effects.test.ts`.
 - **Example:** `annotate(send, { effects: { remote: "write", local: "write" } })`. Each side is `none`, `read` or
   `write`. A sync that reads the service and writes the local store is `{ remote: "read", local: "write" }`.
 - **Exceptions:** none. Without `effects`, the error handler never marks a failure safe to retry, and a next step
-  that runs the command is never safe to run unasked.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+  that runs the command is never safe to run unasked. Known gap, as of 2026-10-27: cli-base's `writes()`
+  (`src/standards/effects.ts`) still counts every local write as a write, so cli-core's MCP router serves `sync` and
+  `calendars list` through the `write` tool. The follow-up makes `writes()` true for `remote: "write"`, or for
+  `local: "write"` when `remote` is `none`.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0 (what counts as a read: cli-base 0.65.0). **Rulings:** the
+  owner's ruling on what counts as a read over MCP (2026-10-27).
 
 ### WC-CMD-18 · Declare `lifetime` and `cooperative` instead of matching command names
 
@@ -327,8 +351,9 @@ The references, each for its own part:
   [WC-OUT-18](output.md#wc-out-18--exit-with-cli-bases-code-for-each-kind-of-failure), prompts follow
   [WC-CMD-15](#wc-cmd-15--never-prompt-when-no-person-can-answer), and a renamed path keeps no alias
   ([WC-CMD-8](#wc-cmd-8--keep-no-aliases-a-renamed-path-stops-working-in-the-release-that-renames-it)), unlike the
-  deprecation advice of the Command Line Interface Guidelines. A read may have documented local effects, such as storing what it read or recording a failed
-  run, so a failed command does not promise that it wrote nothing. A write is never retried on its own, and a tool's
+  deprecation advice of the Command Line Interface Guidelines. A read may have documented local effects, such as
+  storing what it read or recording a failed run, so a failed command does not promise that it wrote nothing; what
+  counts as a read is in [WC-CMD-17](#wc-cmd-17--declare-effects-on-every-command). A write is never retried on its own, and a tool's
   whole payload is never logged. The `stats` root and its resources are the project's own choice.
 - **Exceptions:** the CLI Agent Spec's rule that help goes to stderr when stdout is not a terminal is not adopted. The
   Agent Client Protocol links an editor to a coding agent; a WireCat CLI is a tool an agent calls, so it adds no

package/docs/standards/data-model.md

@@ -37,6 +37,8 @@ is rewritten only to follow it:
   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).
 
+The calendar tables that gcal fills through cli-core (`calendars`, `calendar_entries`) follow them from the start.
+
 ## Rules
 
 ### WC-DATA-1 · A record more than one tool needs is a core entity in cli-core; a CLI's own tables stay private
@@ -73,7 +75,9 @@ to its entity. One entity may combine source records from several sources and ac
 ### WC-DATA-3 · A provider's id goes in `external_id`
 
 The id a provider gives a record is stored in `external_id`, unique with `account_id` (or with `provider` where the
-record has no account). Never in a column named after the provider (`google_id`, `file_id`) and never only in
+record has no account). Where the provider's id is unique only inside a container the record belongs to, it is unique
+with that container instead: a calendar entry's `external_id` is unique with its `calendar_id`, because the same event
+id appears in each calendar that holds a copy of the event, and the calendar is unique with `account_id`. Never in a column named after the provider (`google_id`, `file_id`) and never only in
 `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.

package/docs/standards/docs.md

@@ -37,7 +37,10 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
 - **Enforced by:** review only.
 - **Example:** a claim that turns out wrong is rewritten to the current fact, with no "correction" note and no dated
   "measured on" trail. A finished plan or handoff is deleted. A done backlog or cleanup line is deleted.
-- **Exceptions:** `CHANGELOG.md` is the one place with version history.
+- **Exceptions:** `CHANGELOG.md` is the one place with version history. A template-owned file (`AGENTS.md`,
+  `docs/dev/TESTING.md`, the skills under `docs/dev/skills/` and the others
+  [New CLI](new-cli.md) lists) that has turned false is fixed in cli-template, never only in the CLI: `upgrade` brings
+  the fix to every CLI, and a local edit would make `upgrade` ask about it each time.
 - **Applies to:** all CLIs, user and developer pages. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-DOC-4 · A generated page is never edited by hand

package/docs/standards/kit-surface.md

@@ -12,17 +12,18 @@ This page is a reference, not a rule page: it assigns no rule ids. How to start
 
 ## What the template imports
 
-The list is what the template's `src/` and `scripts/` import today, type imports and re-exports included. `kit/` imports
+The list is what the template's `src/` and `scripts/` import today, type imports, re-exports and imports loaded on
+demand included. `kit/` imports
 nothing from either package.
 
 | Package and path | Exports |
 |---|---|
 | `@wirecat/cli-base` | `catchCrashes`, `CliError`, `configFilePath`, `mcpErrorResult`, `resolvePaths` |
-| `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `describeProgram` |
+| `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `COMMANDS_PAGE_LABELS` (in `scripts/`), `commandsPage` (in `scripts/`), `describeOptions` (in `scripts/`), `describeProgram` |
 | `@wirecat/cli-base/codegen` | `writeArtifacts` (in `scripts/`) |
-| `@wirecat/cli-base/release` | `DocsRules`, `JOURNAL_IDS`, `markdownFiles`, `packContents` (in `scripts/`) |
-| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `itemOf`, `LOCAL_READ`, `outputFor`, `privateFiles`, `profileFree`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
-| `@wirecat/cli-core/mcp` | `McpCommand`, `registerCommands`, `runCommandForAgent`, `toolsFromCommands` |
+| `@wirecat/cli-base/release` | `DocsRules`, `JOURNAL_IDS`, `markdownFiles`, `packContents` (all in `scripts/`) |
+| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandHelpMarkdown` (in `scripts/`), `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `httpTokenFile`, `itemOf`, `LOCAL_READ`, `LOCAL_WRITE`, `MCP_HTTP_DEFAULT_PORT`, `mcpServerCommand`, `outputFor`, `privateFiles`, `profileFree`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `refuseUnderReadOnly`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
+| `@wirecat/cli-core/mcp` | `httpLockFile`, `MCP_PATH`, `McpCommand`, `portOf`, `publicUrlOf`, `registerCommands`, `revokeAll`, `runCommandForAgent`, `serveOverHttp`, `toolsFromCommands` |
 | `@wirecat/cli-core/sends` | `Level` |
 | `@wirecat/cli-core/update` | `appUpdate` |
 | `@wirecat/cli-core/testing` | `ARGV_LOG`, `argvLogSetup` |

package/docs/standards/layout.md

@@ -122,6 +122,38 @@ Rule ids on this page are `WC-LAY-<n>`. How to read a rule, how ids work and whi
 - **Exceptions:** none.
 - **Applies to:** all CLIs and libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
+### WC-LAY-10 · Ship the bin as a bundle that `cli-dev bundle` builds
+
+A command that imports about a thousand module files spends most of its start resolving and reading them. tg's
+bundle halved `--help` and every other short command
+([measurements](https://github.com/WireCatLabs/cli-testing/blob/main/performance/startup/tg-bundle/README.md)).
+
+- **Why:** one shared build keeps what tg learned in one place: lazy imports stay lazy, files and packages are found
+  where they were installed, and a running server survives an in-place upgrade.
+- **Enforced by:** `<app>: pnpm build` · `<app>: pnpm smoke:node` · `<app>: pnpm smoke:bun`.
+- **Example:** `"build": "tsc --build --force && cli-dev bundle --bin dist/bin/tg.js --external '@mtcute/*' --external undici"`,
+  with `esbuild` as a devDependency in cli-base's peer range. `dist/bundle/` holds the bundle, split so every lazy
+  `import()` stays a chunk of its own; `dist/bin/tg.js` stays the path `"bin"` names and becomes a loader. What it
+  does and checks:
+  - The loader answers `--version` from the version built into it, turns the compile cache on, and imports the
+    bundle. Under `serve`, `watch` and `mcp` it loads every chunk 2 s after start and resolves imports between chunks
+    without looking on disk: an upgrade deletes the old chunks, whose names carry a hash.
+  - In the CLI's own modules and in cli-core's and cli-base's (`--anchor` adds a package), `import.meta.url` is the
+    module's place before bundling, so skills, fonts, scenarios, migrations and child scripts are found. A package
+    they load at run time resolves from that place too (a resolve hook under Node, `Bun.resolveSync` under Bun):
+    pnpm installs cli-core's dependencies beside cli-core.
+  - A dynamic import of CommonJS (`yaml`) keeps its named exports. Names are kept (`keepNames`), so `commands --json`
+    and errors read as before.
+  - Native modules, Bun's SQLite and the packages cli-core loads by name stay outside; `--external` adds the CLI's
+    own (`*` matches anything).
+  - The build fails when a bundled module would look for a file or package from the chunk's place, or when the loader
+    names a chunk that was not built. A third-party file read and found harmless is named with `--harmless`.
+  - The CLI's smoke test runs the built bin under Node and Bun and checks that the store opens and the document
+    readers resolve.
+- **Exceptions:** a CLI moves when its outputs are byte-identical before and after and its start gains 15% or more;
+  until then it ships `tsc`'s output. cli-base, cli-core and cli-testing ship libraries, not a bin.
+- **Applies to:** all CLIs. **Since:** cli-base 0.64.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/lifecycle.md

@@ -20,9 +20,13 @@ and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and
 
 ### 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
+- **WC-LIFE-15:** tg, max, wa, gcal 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.
+- **WC-LIFE-16:** cli-core's shared calendar `sync`, from cli-core 0.464.0 (cli-core #2118); gcal gets it when it
+  moves up from cli-core 0.459.0. The deadlines of WC-LIFE-5 come with the same release. The other syncs
+  (`messages sync` in tg, max and wa, drive's `sync`, memo's mail import, zm's `recordings sync`) are cooperative but
+  spend no request budget yet, and gcal sets no `requestMs` of its own, so it uses the 2 s default.
 
 ## One-shot commands
 
@@ -74,15 +78,31 @@ and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and
 
 ### WC-LIFE-5 · Bound every one-shot command by a deadline
 
-- **Why:** a command that waits for ever on a dead connection never fails, so nobody learns why it hangs.
+| Command | At a terminal or in a script | Called over MCP |
+|---|---|---|
+| one-shot | 30 s | 30 s |
+| `cooperative` ([WC-LIFE-10](#wc-life-10--mark-a-long-command-cooperative-when-it-should-stop-at-its-own-pace-and-keep-its-work)) | 5 min | 45 s |
+
+`--timeout 2m` or the `<PREFIX>_TIMEOUT` variable sets the deadline, higher or lower. Past the deadline a one-shot
+command fails with `timeout` (exit 9).
+
+- **Why:** a command that waits for ever on a dead connection never fails, so nobody learns why it hangs. Over MCP
+  the client cuts a tool call at about 60 s: the MCP TypeScript SDK's `DEFAULT_REQUEST_TIMEOUT_MSEC` is 60000
+  (`@modelcontextprotocol/sdk` 1.32.1, `dist/esm/shared/protocol.js:8`), and users report the same for Claude Desktop
+  and ChatGPT. A cooperative command answers at 45 s, so the agent gets the answer and the way to continue instead of
+  a cut call. Claude Code waits longer ([its MCP page](https://code.claude.com/docs/en/mcp)), but a CLI does not know
+  its client, so it takes the shortest.
 - **Enforced by:** `cli-core: src/cli/deadline.test.ts` · `cli-core: src/cli/program.test.ts`.
-- **Example:** the default is 30 seconds. `--timeout 2m` or the `<PREFIX>_TIMEOUT` variable changes it. Past the
-  deadline the command fails with `timeout` (exit 9).
+- **Example:** from cli-core 0.464.0, a calendar `sync` in a terminal may run 5 minutes; the same command called over
+  MCP stops at 45 seconds with what it saved. cli-core's `DEFAULT_COMMAND_MS`, `DEFAULT_COOPERATIVE_MS` and
+  `DEFAULT_AGENT_COOPERATIVE_MS` (`src/cli/execution.ts`) hold the three values, and `run()` picks one when it starts
+  the command.
 - **Exceptions:** a `persistent` command has no deadline and ignores `--timeout`. An `interactive` command has none
   while a person is at the terminal; run headless, it keeps the deadline. `--help` and `--version` need none. A
   background fetch started with `<PREFIX>_BACKFILL_JOB` is bounded only by an explicit `--timeout`.
 - **Applies to:** CLIs that run on cli-core's `run()`; other CLIs use cli-base's `createDeadline`. **Since:** cli-base
-  0.41.0. **Rulings:** none.
+  0.41.0 (the cooperative deadlines: cli-base 0.65.0, cli-core 0.464.0). **Rulings:** the owner's deadlines and
+  request budgets (2026-10-27).
 
 ### WC-LIFE-6 · Open nothing until an action needs it
 
@@ -131,7 +151,9 @@ and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and
 - **Enforced by:** review only.
 - **Example:** `annotate(fetch, { cooperative: true })`. The runner then does not cut the command when the run is
   aborted from outside. The command passes the signal to every operation that can be cancelled, checks it before
-  each write, and stops after the current step. `persistent` commands count as cooperative.
+  each write, and stops after the current step. `persistent` commands count as cooperative. A cooperative command
+  gets the longer deadline of WC-LIFE-5, and a sync among them spends a request budget (WC-LIFE-16), so it stops
+  before the deadline instead of at it.
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
@@ -147,14 +169,15 @@ and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and
   a CLI's own commands included, connects through `connectFor`: a relayed run gets serve's own adapter, and a run for
   another profile is refused. With no live `serve`, the command connects on its own. A `serve` that offers the socket
   but does not answer gives `provider_unavailable`, never a second connection.
-- **Exceptions:** `serve`, `server`, `bot`, logins, `--offline`, `--dry-run` and `mcp --http` are not relayed.
+- **Exceptions:** `serve`, `server`, `bot`, logins, `--offline`, `--dry-run` and `mcp serve --http` are not relayed.
 - **Applies to:** messenger CLIs with an exclusive connection (wa today). **Since:** cli-base 0.41.0.
   **Rulings:** NEED-1389.
 
 ## Resumable syncs
 
 A long sync — a mailbox, a chat history, a Drive folder, a recording archive — is stopped by a kill, a reboot or a
-provider's limit as often as it ends. These three rules make the next run carry on.
+provider's limit as often as it ends. These three rules make the next run carry on, and WC-LIFE-16 stops a run
+before its deadline.
 
 ### WC-LIFE-12 · Save a long sync's work per item or per page, so a kill loses nothing saved
 
@@ -221,6 +244,44 @@ every value that may be content
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.56.0. **Rulings:** none.
 
+## Request budgets
+
+A sync that resumes (WC-LIFE-12 to WC-LIFE-14) also stops on its own before its deadline.
+
+### WC-LIFE-16 · A sync spends a request budget sized to its deadline, and its answer says how to continue
+
+Before each request to the provider, a sync asks its budget whether one more may go. The budget is
+
+`requests = floor((deadline − margin) / requestMs)`, at least one,
+
+where `margin` is the larger of 5 s and 15 % of the deadline, and `requestMs` is how long one request of this CLI is
+expected to take: one constant per CLI, `AppIdentity.requestMs` (2 s when it is not set). `--timeout` changes the
+deadline, and the budget is computed again from it; `--max-pages <pages>` can only lower it. The budget also stops
+when the deadline is closer than the margin plus the slowest request so far, and when the run is cancelled.
+
+When the budget stops the sync before its end, the sync saves where it is (WC-LIFE-12), exits 0 as a declared
+`partial` answer ([WC-OUT-8](output.md#wc-out-8--exit-0-on-a-partial-answer-only-when-the-command-declares-partial))
+and says in the answer why it stopped and how far it got. Its `next` holds the exact command that continues it, the
+same `sync` with the same budget and timeout, marked safe to run unasked; over MCP the step carries that command and
+its arguments for the `read` tool. A run that moved nothing on offers no step, so an agent cannot loop. The sync's
+status command answers how far it is
+([WC-LIFE-14](#wc-life-14--a-syncs-status-command-says-how-far-it-is-in-one-shape)).
+
+- **Why:** a first sync of a large account does not fit one deadline. Without a budget the deadline cuts it mid-page
+  and the run loses its round; with one, every run ends with an answer, saves its work and says how to go on. One
+  `requestMs` per CLI, in one place, keeps the arithmetic the same in every sync of that CLI.
+- **Enforced by:** `cli-core: src/background/budget.test.ts` · `cli-core: src/calendar/testing/sync-contract.ts`.
+- **Example:** `gcal personal sync` over MCP has 45 s: margin 6.75 s, so with the 2 s default about 19 requests. It
+  answers `state: "partial"`, `stopped: "requests"`, `progress: { calendars, calendarsDone, requests, saved }`, and
+  `next` with `gcal personal sync`; `gcal personal status` shows each calendar's progress. cli-core builds the budget
+  with `runBudgetOf(command, maxPages)` from `@wirecat/cli-core/cli` over `runBudget` in
+  `@wirecat/cli-core/background`.
+- **Exceptions:** known gaps, as of 2026-10-27: only the calendar sync spends a budget (see "Who follows"). The
+  continuing step names the command, not the MCP tool, and until the WC-CMD-17 follow-up the router sends that
+  command to `write`, not `read`.
+- **Applies to:** every CLI with a sync. **Since:** cli-base 0.65.0. **Rulings:** the owner's deadlines and request
+  budgets (2026-10-27).
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page