@wirecat/cli-base 0.64.0 → 0.65.1

package/docs/standards/commands.md

@@ -75,11 +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. `mcp --revoke` forgets every login given to a browser app; it stays an option on `mcp` because it
-  belongs with the HTTP server's login state.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1864.
+  its outcome.
+- **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
 
@@ -117,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
@@ -129,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
@@ -188,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
 
@@ -328,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,7 +12,8 @@ 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 |
@@ -20,9 +21,9 @@ nothing from either package.
 | `@wirecat/cli-base` | `catchCrashes`, `CliError`, `configFilePath`, `mcpErrorResult`, `resolvePaths` |
 | `@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`, `commandHelpMarkdown` (in `scripts/`), `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `httpTokenFile`, `itemOf`, `LOCAL_READ`, `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`, `runCommandForAgent`, `serveOverHttp`, `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

@@ -131,7 +131,7 @@ bundle halved `--help` and every other short command
 - **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"`,
+- **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:
@@ -145,7 +145,8 @@ bundle halved `--help` and every other short command
   - 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).
+    own (`*` matches anything). Quote a pattern with double quotes: pnpm runs scripts through `cmd.exe` on Windows,
+    which keeps single quotes, so `'@mtcute/*'` would match nothing there.
   - 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

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

package/docs/standards/mcp.md

@@ -15,9 +15,12 @@ Rule ids on this page are `WC-MCP-<n>`. How to read a rule, how ids work and whi
 
 ### Who follows these rules today
 
-tg, max and wa serve cli-core's personal server (`<cli> <profile> mcp`) and bot server (`<cli> <profile> bot mcp`).
-zoom serves the three shared tools over its own commands from zoom-cli 0.35.0 (`zm <profile> mcp`, cli-core's
-`toolsFromCommands` and `runCommandForAgent`). memo and drive have their own servers: memo has hand-written tools, and
+tg, max and wa serve cli-core's personal server (`<cli> <profile> mcp serve`) and bot server (`<cli> <profile> bot mcp serve`).
+`mcp serve --profiles` ([WC-MCP-9](#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each)) is not
+built yet: cli-core serves one named profile.
+zoom serves the three shared tools over its own commands from zoom-cli 0.35.0 (`zm <profile> mcp serve`, cli-core's
+`toolsFromCommands` and `runCommandForAgent`), and gcal does the same (`gcal <profile> mcp`; it moves to `mcp serve`
+when it takes cli-core 0.463.0). memo and drive have their own servers: memo has hand-written tools, and
 drive builds one tool per command from its command tree and skips commands through its own list. Those two are known
 gaps against these rules.
 
@@ -66,12 +69,22 @@ Every entry in the catalogue must be a command the CLI has.
 
 Every command says whether it writes. `read` refuses a command that writes, and `write` refuses one that only reads.
 Both declare the answer envelope (a list `{ items, page, … }` or one thing `{ item, … }`) as their `outputSchema`.
-
-- **Why:** an agent host can let `read` run freely and ask a person before `write`.
+A command that reads the service and only saves what it read into the owner's local store, such as `sync` or
+`calendars list`, is a read and runs through `read`
+([WC-CMD-17](commands.md#wc-cmd-17--declare-effects-on-every-command) defines it).
+
+- **Why:** an agent host can let `read` run freely and ask a person before `write`. `read` carries the MCP
+  `readOnlyHint`, which the [MCP schema](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations)
+  describes as "the tool does not modify its environment". A local copy of what the service already holds changes
+  nothing the owner would have to undo, so a sync stays under it; sending it through `write` would make a host ask a
+  person before every refresh.
 - **Enforced by:** `cli-core: src/mcp/mcp.test.ts` · `cli-core: src/mcp/output-schema.test.ts`.
-- **Example:** `max_read { "command": "messages send", … }` is refused.
-- **Exceptions:** none.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Example:** `max_read { "command": "messages send", … }` is refused. Once the gap below is closed,
+  `gcal_read { "command": "sync" }` runs.
+- **Exceptions:** none. Known gap, as of 2026-10-27: cli-core decides with cli-base's `writes()`, which still counts
+  the local write, so `sync` runs through `write` until that follow-up lands (WC-CMD-17).
+- **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-MCP-5 · Unknown arguments are refused before anything runs
 
@@ -116,29 +129,36 @@ profile's permissions, the recipient list and the hourly limit decide.
 
 ### WC-MCP-8 · No `mcp` flag grants access
 
-`mcp --permission <key=level>` may only make a level stricter for that server. An override that would loosen the
+`mcp serve --permission <key=level>` may only make a level stricter for that server. An override that would loosen the
 profile is refused at start-up with `validation_error` naming the key. This includes a parent key that would hide a
-stricter key under it, and lifting a built-in `ask`. `mcp setup --allow-writes` only confirms, at install time, that
+stricter key under it, and lifting a built-in `ask`. `mcp add <client> --allow-writes` only confirms, at install time, that
 the owner saw the profile offers writes.
 
 - **Why:** whoever writes the agent's MCP config must not get more than the profile allows.
 - **Enforced by:** `cli-core: src/cli/messenger/mcp-command-http.test.ts`.
-- **Example:** `max work mcp --permission messages=readonly` works. `max work mcp --permission messages.delete=allow`
+- **Example:** `max work mcp serve --permission messages=readonly` works. `max work mcp serve --permission messages.delete=allow`
   is refused, because the built-in level is `ask`.
-- **Exceptions:** `bot mcp` takes no `--permission` at all. cli-base's flag registry still describes `--allow-writes`
+- **Exceptions:** `bot mcp serve` takes no `--permission` at all. cli-base's flag registry still describes `--allow-writes`
   as "permit writing"; that wording is a gap.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1423.
 
-### WC-MCP-9 · A server speaks for one named profile over one connection
+### WC-MCP-9 · A server serves the profiles it is told, with one connection for each
 
-`mcp` needs a profile, like every command ([WC-ACCT-1](accounts.md)). The server opens one messenger connection and
-every call shares it.
+`mcp serve` serves one named profile (`<cli> <profile> mcp serve`), or the profiles that `--profiles` lists:
+`--profiles work,personal`, or `--profiles all` for every profile on this computer. With neither, it refuses with
+`validation_error` and lists the profiles, like any missing profile ([WC-ACCT-3](accounts.md)). It never serves every
+profile by default. The server opens one messenger connection for each profile it serves, and every call for that
+profile shares it. When it serves more than one profile, each call names its profile; a call without one is refused
+and lists the profiles served. Each call follows its own profile's permissions.
 
-- **Why:** a connection per call would break the messenger's pace limits and look unlike the official client.
+- **Why:** which accounts an agent can reach is the owner's choice, written in the agent's config. A connection per
+  call would break the messenger's pace limits and look unlike the official client.
 - **Enforced by:** review only.
-- **Example:** `max work mcp`. Plain `max mcp` stops and lists the profiles.
+- **Example:** `max work mcp serve`, `max mcp serve --profiles work,personal` or `max mcp serve --profiles all`.
+  Under the last two, a call reads `max_read { "profile": "work", "command": "inbox", "arguments": {} }`.
+  `max mcp serve` alone is refused, and its message lists `personal` and `work`.
 - **Exceptions:** the bot server needs no held connection: each Bot API call is plain HTTPS.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1881.
 
 ### WC-MCP-10 · A tool and its command give the same answer and the same error
 
@@ -170,15 +190,16 @@ it carries.
 
 ### WC-MCP-12 · An MCP server over HTTP follows the same permissions and short-lived logins
 
-`mcp --http` serves on `127.0.0.1` for agents in a browser, behind the owner's tunnel. Writes follow the profile's
+`mcp serve --http` serves on `127.0.0.1` for agents in a browser, behind the owner's tunnel. Writes follow the profile's
 permissions. An access token lives one hour and a refresh token 30 days, replaced on each use. To log in, a browser app
-needs a one-time code that the owner reads in a terminal. `--revoke` ends every login.
+needs a one-time code that the owner reads in a terminal. `mcp revoke` ends every login.
 
 - **Why:** a server reachable from a browser must not be a softer way in than the local one.
 - **Enforced by:** review only.
-- **Example:** `max work mcp --http --public-url https://<name>.ts.net`.
+- **Example:** `max work mcp serve --http --public-url https://<name>.ts.net`.
 - **Exceptions:** none.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-594, NEED-774.
+- **Applies to:** every CLI that offers `mcp serve --http`: the messenger CLIs, cli-template and every CLI made from
+  it. **Since:** cli-base 0.41.0. **Rulings:** NEED-594, NEED-774.
 
 ### WC-MCP-13 · A tool's hints and descriptions never stand in for the permission check
 
@@ -213,8 +234,11 @@ cli-core builds its personal and bot MCP catalogues from the command tree with `
 - **One server per subtree.** The personal server is built from the program without its `bot` group; the bot server
   from the `bot` group. Both keep three tools (WC-MCP-1).
 - **The profile still decides at run time** what is listed (WC-MCP-6).
-- **The whole catalogue is pinned** in each CLI's `contracts/mcp-tools.json`, so a command that becomes visible to
-  agents shows up as a diff in its pull request.
+- **Two snapshots pin what agents see.** `contracts/mcp-tools.json` pins the tools themselves: with three tools
+  (WC-MCP-1) that is three names and their schemas, which do not change when a command is added. So each CLI also
+  pins the command catalogue behind the tools, every command `tools_search` can return and whether it runs through
+  `read` or `write`, in `contracts/mcp-catalogue.json`. A command that becomes visible to agents then shows up as a diff in
+  its pull request. tg and max keep both; wa, zm, gcal and drive pin only the tools, a known gap as of 2026-10-27.
 
 ## Sources
 

package/docs/standards/new-cli.md

@@ -51,8 +51,8 @@ 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 run log and its `runs` commands
-([WC-LIFE-15](lifecycle.md#wc-life-15--keep-a-run-log-through-cli-core-and-read-it-back-with-runs)), the MCP server with a tool for every
-command, writes included, the community presets in `config/wirecat/`, the TypeScript, Biome and vitest setup,
+([WC-LIFE-15](lifecycle.md#wc-life-15--keep-a-run-log-through-cli-core-and-read-it-back-with-runs)), the MCP server with its three tools
+([WC-MCP-1](mcp.md#wc-mcp-1--a-server-offers-three-tools-not-one-per-command)) that reach 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),

package/docs/standards/output.md

@@ -93,7 +93,11 @@ JSON Schema 2020-12.
 - **Why:** a caller that checks only the exit code must not take half an answer for a whole one.
 - **Enforced by:** review only.
 - **Example:** a search across accounts declares `annotate(search, { partial: true })` and exits 0 with
-  `meta.complete: false`. Any other command prints what it read, then exits with the code of its first issue.
+  `meta.complete: false`. Any other command prints the whole envelope of what it read on stdout, with
+  `meta.complete: false` and its `issues`, then exits with the code of its first issue. Such an answer is an answer,
+  not a failure, so [WC-OUT-14](#wc-out-14--print-a-failure-in-machine-mode-as-one-json-object-on-stderr-with-stdout-empty)
+  does not apply to it: a caller reads stdout whenever it is not empty, also after a non-zero exit. cli-core's
+  `renderAnswer` does this.
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
@@ -103,7 +107,8 @@ JSON Schema 2020-12.
 - **Enforced by:** review only.
 - **Example:** `next` holds the step to take, then one alternative. Each has `kind` (`command`, or `user_action` with
   no command) and `safe_to_auto_execute`. A step that reads the service and writes only the local store (a sync) is
-  safe. A step that reads nothing remotely and writes locally (`store reindex`) is not: it waits to be asked. A step
+  safe; it counts as a read, also over MCP
+  ([WC-CMD-17](commands.md#wc-cmd-17--declare-effects-on-every-command)). A step that reads nothing remotely and writes locally (`store reindex`) is not: it waits to be asked. A step
   is built from ids, counts and cursors the CLI holds, never from text a message, mail or document carried. A CLI
   answer's command step also has `line`, the whole command with the profile (`tg personal mcp config`), because
   `command` is the bare path an MCP router takes and a copied path without the profile fails.
@@ -160,6 +165,12 @@ JSON Schema 2020-12.
 
 ### WC-OUT-14 · Print a failure in machine mode as one JSON object on stderr, with stdout empty
 
+A failure is a run that has no answer: the command threw. A command that answers with what it could read and
+`meta.complete: false` has not failed, even when it exits non-zero; that case is
+[WC-OUT-8](#wc-out-8--exit-0-on-a-partial-answer-only-when-the-command-declares-partial). So a non-zero exit does not
+mean stdout is empty: stdout empty and one JSON object on stderr is a failure; an envelope on stdout is an answer,
+whole or partial.
+
 - **Why:** a caller tells success from failure without parsing text, and stdout never holds half an answer and an
   error.
 - **Enforced by:** `src/failure.test.ts` · `cli-core: src/cli/agent-contract.test.ts`.

package/docs/standards/permissions.md

@@ -320,9 +320,15 @@ A messenger's keys come from its resources (`messages`, `chats`). Any other CLI
 - **Keys.** Each command is checked against its own path (`events.create`), the default `keyOf`. Housekeeping has no
   key (WC-PERM-5). `extra` adds the keys a command checks inside itself, such as one per generated API method
   (`api.calendar.events.insert`). A key that names no command is refused when it is set or saved.
-- **Defaults.** `defaults` holds the CLI's built-in levels, beside cli-core's. They only ever tighten (WC-PERM-7). A
-  CLI picks them for what its writes do, not by WC-PERM-6's messenger list: they ask before a write people other
-  than the owner see or cannot easily undo, and deny what an agent must never do unasked.
+- **Defaults.** `defaults` holds the CLI's built-in levels, beside cli-core's. They only ever tighten (WC-PERM-7).
+  Like WC-PERM-6 for the messengers, and as tg and drive do: an ordinary change is `allow`; a delete is `ask`; a
+  write that mails or notifies people other than the owner, or deletes a whole series from their calendars, is a key
+  of its own, `deny` until the owner allows it.
+  Sending a message is not this kind of write; a messenger CLI keeps WC-PERM-6.
+- **Shared keys on every path.** A key a shared command checks inside itself, such as `events.notify` or
+  `events.delete.series`, is checked by every path that can do the same thing, the CLI's own generic API commands
+  included. A gcal `api` call that deletes an event with `sendUpdates: "all"` checks `events.notify` as well as
+  its own `api.calendar.events.delete`; otherwise the generic path is a way round the shared key.
 - **Read-only lock and guard.** `<PREFIX>_READ_ONLY` refuses every write to the service, as in WC-PERM-12. Every
   write runs through cli-core's write guard with `permissionDefaults: configuration.permissions.defaults`
   (cli-core 0.455.0), so `ask` is a y/N question at a terminal (WC-PERM-9) and every attempt goes into the send journal
@@ -331,14 +337,21 @@ A messenger's keys come from its resources (`messages`, `chats`). Any other CLI
 - **Why:** one permission model for every CLI; a CLI-own layer drifts from the shared one and is audited by nobody.
 - **Enforced by:** `cli-core: src/cli/command-permissions.test.ts` · `cli-core: src/calendar/cli/writes.test.ts`.
 - **Example:** a calendar CLI takes cli-core's `CALENDAR_WRITE_DEFAULTS` and `CALENDAR_WRITE_KEYS`
-  (`@wirecat/cli-core/calendar`, cli-core 0.458.0): `events create`, `update`, `respond` and `delete` ask, since each
-  changes a calendar other people may share or be invited from; `events.delete.series` (a whole repeating series) and
-  `events.notify` (mail the attendees) are `deny` until the owner allows them. gcal adds its own: a generated
-  `api <method>` that writes asks, and one that shares, empties or gives away a calendar is `deny`.
-- **Exceptions:** known gaps: drive keeps its own policy and `--read-only` flag, zoom reads its own
-  `remote-meetings` key with `levelFor`, and memo uses cli-core's permissions for the shared commands only. None of
-  them declares `commandPermissions` yet.
-- **Applies to:** every CLI that writes and is not a messenger. **Since:** cli-base 0.64.0. **Rulings:** none.
+  (`@wirecat/cli-core/calendar`, cli-core 0.458.0). By this rule `events create`, `update` and `respond` are `allow`
+  and `events delete` is `ask`. `events.delete.series` (every occurrence of a repeating series, in every attendee's
+  calendar) and `events.notify` (the provider mails the attendees) are `deny` until the owner allows them: over MCP
+  `ask` runs without a question, and each reaches people other than the owner. gcal adds its own keys for its generated
+  `api <method>` commands: sharing a calendar is `ask` (NEED-1857), and emptying the main calendar
+  (`api.calendar.calendars.clear`) is `deny`.
+- **Exceptions:** known gaps, as of 2026-10-27:
+  - cli-core's `CALENDAR_WRITE_DEFAULTS` (`src/calendar/writer.ts`) still has `events create`, `update` and
+    `respond` at `ask`.
+  - gcal's generated `api` commands default every write to `ask`, ordinary changes included, and check neither
+    `events.notify` nor `events.delete.series`.
+  - drive keeps its own policy and `--read-only` flag, zoom reads its own `remote-meetings` key with `levelFor`, and
+    memo uses cli-core's permissions for the shared commands only. None of them declares `commandPermissions` yet.
+- **Applies to:** every CLI that writes and is not a messenger. **Since:** cli-base 0.64.0 (the levels and the shared
+  keys on every path: cli-base 0.65.0). **Rulings:** NEED-1857, NEED-1883.
 
 ## Sources
 

package/docs/standards/releases.md

@@ -192,8 +192,14 @@ fixtures, `scripts/`, `.github/`, `bin/release`, `config/`, `lint/`, `contracts/
 
 - **Why:** a stray file in the package can leak local data and grows every install.
 - **Enforced by:** `node-ci.yml:check` · `<app>: pnpm package:check` · `whatsapp-cli: pnpm release:check`.
-- **Example:** `package.json` `files` lists what ships. The CLI's `pnpm release:check` runs `packContents` from
-  `@wirecat/cli-base/release` and fails on any other path in `npm pack --dry-run`.
+- **Example:** `package.json` `files` lists what ships. `packContents(root, allowed, said)` from
+  `@wirecat/cli-base/release` fails on any path in `npm pack --dry-run` outside `allowed`. It checks the pack against
+  the list it is given, not against this rule: a CLI that passes its own `files` list as `allowed`, as the template's
+  `scripts/smoke.ts` does, checks only that npm packs what `files` says, and cannot fail on a wrong `files` list.
+  `npm pack --dry-run` in gcal-cli (2026-10-27) packs 256 files, `src/`, `scripts/`, `.github/`, `config/`,
+  `contracts/`, `lint/` and `template.json` among them, because its `files` list names them; its check cannot see it. The check this rule needs
+  refuses the forbidden paths above whatever `files` says; it belongs in cli-template, so every CLI gets it by
+  `upgrade` ([cli-template#77](https://github.com/WireCatLabs/cli-template/issues/77)).
 - **Exceptions:** cli-template's own package ships the skeleton's sources and configs, since `new` copies them; the
   `files` list `new` writes into a CLI follows this rule. Each CLI's `package:check` runs `packContents`; tg and max
   as `release-check.ts --package-only`.

package/docs/standards/security.md

@@ -310,16 +310,40 @@ store and runs no search. A CLI declares its provider and may replace any step.
   printed. A CLI that signs in another way (a bot token, a session) does not use the module.
 - **Applies to:** every CLI that signs in with OAuth. **Since:** cli-base 0.57.1. **Rulings:** NEED-1734.
 
-### WC-SECR-23 · Meeting passcodes and the query of a join link never reach the store
+### WC-SECR-23 · Meeting passcodes and the query of a join link never reach the store, the output or an agent
 
-- **Why:** a passcode, PIN or join-link query lets anyone who reads the store join the meeting.
+- **Why:** a passcode, PIN or join-link query lets anyone who reads the store, a terminal log or an agent's
+  transcript join the meeting.
 - **Enforced by:** `cli-core: src/store/calendar.test.ts`.
 - **Example:** a calendar entry's description loses each line that carries a passcode, password or PIN, and every
   link loses its query string, so `join_url` holds `https://zoom.us/j/123` without `?pwd=`. A meeting is matched by
   its room (`join_key`, such as `zoom:<number>`), never by a link that carries the passcode.
-- **Exceptions:** a title that names a PIN or a password is kept: it is the meeting's name.
-- **Applies to:** cli-core and every CLI that stores meetings or calendar entries. **Since:** cli-base 0.57.1.
-  **Rulings:** none (Wave 3 requirements 3.4).
+  The same holds for what a command prints and what an MCP tool answers, also when the answer comes straight from
+  the provider and never touched the store: a generic API command removes the provider's passcode fields (Google's
+  `conferenceData.entryPoints[].passcode`, `pin`, `accessCode`, `password`), the query of every join link and the
+  dial sequence after a phone number, and the passcode lines of a description or a location.
+- **Exceptions:** a title that names a PIN or a password is kept: it is the meeting's name. Known gap, as of
+  2026-10-27: gcal's `api` answers drop the conference entry points' secrets (`src/conference.ts`) but keep the
+  description and location as Google sent them.
+- **Applies to:** cli-core and every CLI that stores or shows meetings or calendar entries. **Since:** cli-base 0.57.1
+  (output and agent answers: cli-base 0.65.0). **Rulings:** none (Wave 3 requirements 3.4).
+
+### WC-SECR-24 · A run with moved folders never writes the owner's system keyring
+
+- **Why:** with its folders moved (`<PREFIX>_CONFIG_DIR`, `<PREFIX>_STATE_DIR`, a throwaway `HOME` or `XDG_*`),
+  `Credentials` keys the keyring by `<app>:<config folder>` (`keyringService`, `isolated`). Each test run, agent check
+  or worktree that signs in then leaves its own copy of a sign-in in the owner's keyring, and nothing removes it.
+- **Enforced by:** `src/credentials.test.ts`.
+- **Example:** a test passes `memoryKeyring()`. An agent checking a built CLI signs in with file storage inside its
+  temp folder (`session start --credential-storage file`), or does not sign in. A run against the owner's real data
+  keeps the default folders, so it reads the owner's existing entry (`<app>` / `oauth:<provider>:<profile>`) instead
+  of making a new one. A throwaway `HOME` does not hide the keyring, which is reached over D-Bus: a run that must not
+  see it also runs with `DBUS_SESSION_BUS_ADDRESS` removed. With `isolated` and the system keyring, `Credentials`
+  saves new secrets to the private file in the moved config folder and only reads the keyring, for a secret saved
+  there before.
+- **Exceptions:** none.
+- **Applies to:** every CLI, its tests and every agent that runs a CLI. **Since:** the next cli-base release. **Rulings:** owner,
+  2026-10-29 (sign-ins copied per work folder should have reused the existing entry).
 
 ## Sources