@wirecat/cli-base 0.63.0 → 0.65.0

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

@@ -12,7 +12,7 @@ built on are on the [Kit surface](kit-surface.md) page.
 ## Start with the template
 
 ```sh
-npx @wirecat/cli-template new cal-cli --command cal --package @wirecat/cal-cli --owner WireCatLabs \
+npx @wirecat/cli-template new gcal-cli --command gcal --package @wirecat/gcal-cli --owner WireCatLabs \
   --category calendar --content-lang en,ru --sign-in oauth --api official-client --filters time,person,text \
   --never-store tokens,secret-links --untrusted names,links
 ```
@@ -24,7 +24,7 @@ the choices. Nothing is guessed.
 |---|---|---|
 | `<name>-cli` | the repository folder | any name |
 | `--command` | the command word people type | one word |
-| `--package` | the npm package name | a scoped name, such as `@wirecat/cal-cli` |
+| `--package` | the npm package name | a scoped name, such as `@wirecat/gcal-cli` |
 | `--owner` | the GitHub owner of the repository | an owner |
 | `--category` | what the CLI reads | `messenger`, `mail`, `notes`, `files`, `calendar`, `meetings` |
 | `--content-lang` | the languages of the content | a list, such as `en,ru` |
@@ -42,17 +42,17 @@ a reference CLI for your category in `AGENTS.md`. It does not install packages,
 publish. Then:
 
 ```sh
-cd cal-cli && pnpm install && pnpm ci:quick
+cd gcal-cli && pnpm install && pnpm ci:quick
 git add -A && git commit -m "chore: start from @wirecat/cli-template"
 ```
 
-Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `cal personal doctor`.
+Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `gcal personal doctor`.
 The reference CLI is the one to compare with when a step is unclear.
 
 The copy already holds every file this handbook asks for: the required root commands (`commands`, `doctor`,
 `skill show`, `skill install`, `mcp`, `upgrade`) and `config` from cli-core, the 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),
@@ -61,6 +61,15 @@ The rules they keep are on the area pages: [Commands](commands.md), [MCP](mcp.md
 Later template changes come in with `npx @wirecat/cli-template upgrade`, file by file: apply, replace, skip or diff.
 See [Kit surface](kit-surface.md#how-your-cli-stays-current).
 
+The template's `template.json` splits the copy in two. A **seed** (`DESIGN.md`, `CLAUDE.md`, `README.md`, the user
+pages, `src/`) is the CLI's own from the first commit: rewrite it freely. A **template-owned** file (`AGENTS.md`,
+`docs/dev/TESTING.md`, `docs/dev/reference-clis.md`, the skills under `docs/dev/skills/`, `.github/`) holds only what
+is true for every CLI made from the template. Do not rewrite one to fit this CLI: put the CLI's own facts in a seed.
+A template-owned page that is wrong for this CLI is a gap in cli-template, under
+[WC-DOC-3](docs.md#wc-doc-3--every-document-states-current-facts-rewrite-a-wrong-sentence-in-place) like any other
+wrong sentence: fix it there, and `upgrade` brings the fix. Change it in the CLI only where the CLI must differ for
+good; `upgrade` then asks before it touches the change.
+
 ## Four steps that need a person
 
 `new` prints these at the end.
@@ -69,12 +78,14 @@ See [Kit surface](kit-surface.md#how-your-cli-stays-current).
    changes only through a pull request, required status checks, and no bypass. Add the ruleset after the first
    commit is on `main`, since a pull request rule leaves an empty repository no way to get one, and the required
    check names exist only once CI has run. See [Releases](releases.md).
-2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. See
+2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. npm
+   offers this only once the package exists, so the owner publishes the first version with `bin/release --local`
+   and sets it right after. See
    [WC-REL-11](releases.md#wc-rel-11--publish-from-github-actions-with-npm-trusted-publishing).
-3. **Pick a monthly cron minute** between 02:17 and 03:20 UTC that no other repository uses. The copy of
-   `.github/workflows/monthly.yml` keeps the template's own minute, 03:02, and no check compares minutes across
-   repositories, so change it by hand. See
+3. **Pick a monthly cron minute** between 02:17 and 03:20 UTC that is not in the list of taken minutes under
    [WC-CI-9](ci.md#wc-ci-9--run-full-validation-and-release-security-on-the-first-day-of-each-month-without-publishing).
+   The copy of `.github/workflows/monthly.yml` keeps the template's own minute, 03:02, and no check compares minutes
+   across repositories, so change it by hand, and add the new minute to the list in the step 4 pull request.
 4. **WireCat CLIs only: join the shared lists.** A pull request to cli-base's `PARITY_GROUPS` (at least the `all`
    group, which compares the shared root commands), a line in cli-core's `WIRECAT_TOOLS` and a line in cli-docs'
    `tools.json`. A messenger also joins cli-core's `parity.json`. A CLI outside WireCatLabs keeps its parity groups
@@ -89,17 +100,20 @@ All of these pass on `main`, before the first release:
 - `cli-dev lint` against the built CLI. It also makes the CLI fail once in an empty home and checks that
   `runs list` shows the failed run
 - `cli-dev audit --for <cli> --lint <cli>=lint` with no new finding, run with the command trees of the CLIs in
-  the same parity groups. `--lint` judges the CLI's lint rules by its own `lint/` folder. What it shares with the
-  other CLIs is judged by cli-base's `audit/baseline`; the pull request that adds the CLI to a parity group adds its
-  shared findings there
+  the same parity groups (`pnpm audit:commands`). `--lint` judges the CLI's lint rules by its own `lint/` folder.
+  What it shares with the other CLIs has no baseline: `audit/baseline` does not accept a shared-contract finding
+  (cli-base 0.51.0). Fix each one, or, where the CLI must differ for good, the pull request that adds it to a parity
+  group declares the exact difference with its reason in that group's `differences`
 - `pnpm contracts:check`
 - `cli-dev test-matrix --check`
 - `pnpm docs:check`, with `--pages`, and the CLI's `generate:check`
 - the changelog guard on a pull request
 - `pnpm release:check`
 
-The last test is a fresh agent. Give it only this handbook's [index](README.md) and the new repository, and ask it to
-audit the CLI. Every gap it lists is either a gap in the CLI, to fix before the first release, or a hole in the
+The last test is a fresh agent. Give it only this handbook's [index](README.md), the new repository and the cli-base
+workflow files its own workflows pin
+([WC-CI-8](ci.md#wc-ci-8--call-cli-base-node-ciyml-from-ciyml-pinned-to-a-tag-or-commit)), and ask it to audit the
+CLI. Every gap it lists is either a gap in the CLI, to fix before the first release, or a hole in the
 handbook, to fix here.
 
 ## The template repository itself
@@ -118,7 +132,7 @@ upgrade, and no script or agent reads its answers.
 | [WC-DOC-12](docs.md#wc-doc-12--a-runnable-command-in-a-document-has-no-placeholder-in-it) | Exempt only for the placeholder names `clidev`, `clidev-cli`, `@wirecat/clidev-cli` and `WireCatLabs/clidev-cli`, and the upper-case prefix `CLIDEV_` (as in `CLIDEV_PROFILE`). | `new` replaces each of them with the CLI's own name. Any other placeholder is still a gap. |
 | [WC-DOC-17](docs.md#wc-doc-17--each-entry-says-what-changed-for-the-caller-why-and-what-to-watch-for) | A changelog entry may name a file path. | The template's readers are CLI authors, who edit those files or take them with `upgrade`; for them a path is what they see. |
 
-Every other rule that applies to all CLIs, or to the ten repositories, applies to cli-template as it is written,
+Every other rule that applies to all CLIs, or to the WireCat repositories, applies to cli-template as it is written,
 with one limit for the copy tool. It follows the rules for code and the repository: Toolchain, Layout, Style,
 Testing, Security and Documents. It has no profile, no machine mode, no MCP server, no store and no agent reading its
 answers, so the rules for a CLI's commands and runtime do not reach it: Commands, Output, MCP, Accounts, Permissions,

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

@@ -20,8 +20,9 @@ Rule ids on this page are `WC-PERM-<n>`. How to read a rule, how ids work and wh
 tg, max and wa use cli-core's permissions and write guard in full. memo uses them for the shared commands only. drive
 has its own policy and guard, with its own `--read-only` flag. zoom has per-profile `permissions` from zoom-cli 0.35.0,
 read with cli-core's `levelFor`; its writes change Zoom meetings, its built-in default is `remote-meetings: ask`, and
-it has no send journal or recipient list, since it sends no messages. Where this page says "every CLI that writes",
-drive is a known gap.
+it has no send journal or recipient list, since it sends no messages. gcal declares its own keys through cli-core's
+`commandPermissions` and runs its event writes through cli-core's write guard (WC-PERM-22). Where this page says
+"every CLI that writes", drive is a known gap.
 
 WC-PERM-10 and WC-PERM-11 need cli-core 0.321.0, which tg, max and wa pin. WC-PERM-12 as written needs cli-core
 0.337.0; before it, the lock let through some local writes that overwrite what the owner saved. A command other
@@ -114,7 +115,8 @@ A default is never made stricter without the owner's word.
 - **Exceptions:** where the messenger has replies, `replies.send` is `deny`: a reply rule writes to people with nobody
   typing a command, so it waits for the owner's own `allow`. A messenger with no `replies` group, such as wa, has no
   use for the key.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-568.
+- **Applies to:** messenger CLIs. A CLI that is not a messenger sets its own defaults (WC-PERM-22). **Since:** cli-base
+  0.41.0. **Rulings:** NEED-568.
 
 ### WC-PERM-7 · A built-in default only ever tightens
 
@@ -310,6 +312,47 @@ Moderation rules use the same four levels for each kind of action (delete, remov
   looser than the profile's `chats.moderate`; the code does not check that yet.
 - **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-306, NEED-310.
 
+### WC-PERM-22 · A CLI that is not a messenger declares its own keys and defaults with `commandPermissions`
+
+A messenger's keys come from its resources (`messages`, `chats`). Any other CLI names its own with cli-core's
+`commandPermissions({ keyOf, extra, defaults })`, passed as `settingsFor(app, { permissions })` (cli-core 0.450.0):
+
+- **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).
+  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
+  (WC-PERM-17). A CLI that sends no messages has no recipient list or hourly limit to set.
+
+- **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). 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
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page

package/docs/standards/releases.md

@@ -125,7 +125,11 @@ on the [CI](ci.md) page.
 - **Example:** `bin/release` starts `release.yml` and follows it. Only the `publish` job has the OIDC permission (the
   short-lived identity npm trusts), and it runs no project code: it only runs `npm publish` on the validated file.
 - **Exceptions:** npm trusts the workflow by file name: renaming `release.yml` stops publishing until npm's trusted
-  publisher settings are updated.
+  publisher settings are updated. npm sets a trusted publisher on the package's settings page
+  ([npm docs](https://docs.npmjs.com/trusted-publishers)), which a package has only once it is published, so its
+  first version is published with `bin/release --local` by the owner, from a clean `main`. Right after it, the owner
+  adds the trusted publisher on npmjs.com (step 2 of [New CLI](new-cli.md#four-steps-that-need-a-person)), and every
+  later version goes through `release.yml`.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-REL-12 · Publish only after full validation and the release security checks pass
@@ -181,12 +185,24 @@ on the [CI](ci.md) page.
 
 ### WC-REL-16 · The package ships only the files it names
 
+A CLI's `files` holds only what the installed CLI runs from or shows its user: `dist`, the agent skill (`skills`),
+`README.md`, `LICENSE`, and files its code reads or runs after install, such as `scenarios` for `guide`, an `install`
+script, third-party notices and licenses. `CHANGELOG.md` may ship too. It never holds `src/`, tests, fakes or
+fixtures, `scripts/`, `.github/`, `bin/release`, `config/`, `lint/`, `contracts/`, `docs/dev/` or `template.json`.
+
 - **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`.
-- **Exceptions:** none. Each CLI's `package:check` runs `packContents`; tg and max as
-  `release-check.ts --package-only`.
+- **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`.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ## Sources

package/docs/standards/security.md

@@ -67,8 +67,9 @@ name. Any other top-level key is written as `[not allowed]`. A key that names co
 ### WC-SECR-4 · Secrets come from the environment, then the OS keyring, then a private file
 
 cli-base's `Credentials` reads the environment variable first (for CI), then the OS keyring, then a file with mode
-`0600`. The keyring service is the command's name. When the config directory comes from the environment, the service
-name is scoped to that directory (`isolated: true`).
+`0600`. The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
+the command word people type (`max`, `gcal`). When the config directory comes from the environment, the service name
+is scoped to that directory (`isolated: true`).
 
 - **Why:** the keyring is the safest store on the computer, and a throwaway config directory must not overwrite the
   owner's real keyring entry.
@@ -274,7 +275,7 @@ general words.
   asks for it on that job only. The `zizmor` scan in `release-checks.yml` reports high findings at release, but does
   not fail on them.
 - **Exceptions:** none.
-- **Applies to:** the ten repositories: the six CLIs, cli-base, cli-core, cli-testing, cli-docs and community; and
+- **Applies to:** the WireCat repositories: every CLI, cli-base, cli-core, cli-testing, cli-docs and community; and
   cli-template.
   **Since:** cli-base 0.41.0. **Rulings:** none.
 
@@ -309,16 +310,23 @@ 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).
 
 ## Sources
 

package/docs/standards/store.md

@@ -30,7 +30,7 @@ Related pages: which account a read covers, and how a read across accounts is as
   `%LOCALAPPDATA%\WireCat\Data\` on Windows). Rows are keyed by provider and account. `storePath` is the only code
   that reads `MESSAGING_STORE` and `WIRECAT_STATE_DIR`.
 - **Exceptions:** none. Older documents that name `messages.db` describe a store that is no longer used.
-- **Applies to:** CLIs that keep local data through cli-core (tg, max, wa, memo, drive, zoom). **Since:** cli-base 0.41.0.
+- **Applies to:** CLIs that keep local data through cli-core (tg, max, wa, memo, drive, zoom, gcal). **Since:** cli-base 0.41.0.
   **Rulings:** NEED-383.
 
 ### WC-STORE-2 · Reach the data through its area, and add a new kind of record as a new area
@@ -52,8 +52,9 @@ Related pages: which account a read covers, and how a read across accounts is as
   accounts on purpose asks for the whole store with `crossAccount(deps, reason)`; see [Accounts](accounts.md).
 - **Exceptions:** `forAccount` binds only the account areas (accounts, chats, sync, messages, attachments, roster,
   people, conversations, vectors, counters, tags, mentions). The `chats`, `conversations` and `attachments` services
-  use the bound store; the other services still pair `deps.store()` with `deps.account()`. New code uses the bound
-  store.
+  use the bound store; the other services still pair `deps.store()` with `deps.account()`. The calendar areas
+  (calendars, calendar entries, their sync cursors) are not bound either: cli-core's calendar commands pass
+  `accountId` to every call, a known gap as of 2026-10-27. New code uses the bound store.
 - **Applies to:** cli-core and every CLI that adds a service. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-STORE-4 · Reach the store through its public module, never a table module

package/docs/standards/testing.md

@@ -44,7 +44,7 @@ and which run after merge is in [CI](ci.md).
   file, listed after the shared one, adds only what is its own, such as a default profile.
 - **Exceptions:** keep coverage reports and debug traces outside the sandbox, with bounded retention. Never clean
   another session's scratch directory as test teardown.
-- **Applies to:** all CLIs and the shared packages. cli-base, cli-core, the six CLIs and cli-template load the shared
+- **Applies to:** all CLIs and the shared packages. cli-base, cli-core, every CLI and cli-template load the shared
   setup first in `setupFiles`; cli-testing does not use it yet. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TEST-2 · No test opens a real credential store
@@ -94,7 +94,9 @@ and which run after merge is in [CI](ci.md).
 - **Enforced by:** review only.
 - **Example:** waits go through an injected `SleepLike`, and `fakeClock()` from `@wirecat/cli-base/testing` records
   them without waiting. A test harness passes `sleep: async () => {}`. `pnpm test:slow` lists the 20 slowest tests
-  and the 10 slowest files.
+  and the 10 slowest files. A test may wait for a local process or server it started, for example polling its
+  status with `vi.waitFor` and a timeout shorter than the test's own; that waits for an event, not for time. A
+  fixed sleep or `setTimeout` is still a wait for real time.
 - **Exceptions:** none. A new wait in the code gets a seam, never a longer test timeout.
 - **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** dev-process:4.
 
@@ -169,9 +171,14 @@ and which run after merge is in [CI](ci.md).
 - **Enforced by:** `node-ci.yml:check` · `<app>: pnpm test:matrix:check`.
 - **Example:** under vitest, `run()` appends each parsed command path and option name (never a value) to
   `coverage/argv.jsonl`. `pnpm test:matrix` turns that into `docs/dev/test-matrix.md` and fails on a command or
-  option with neither a test nor a reason. A reason names the live scenario that covers it. A test that calls a
-  function directly does not count.
-- **Exceptions:** none.
+  option with neither a test nor a reason. A test counts only when it runs the command through `run()`: a test that
+  calls a function directly records no command line, so the matrix does not see it. A reason says what covers the
+  command instead: the live scenario that runs it, or, for a generated group, the two tests below.
+- **Exceptions:** commands generated from a service's API description, such as drive's and gcal's
+  `api <method>` from a Google Discovery snapshot, share one reason for the whole group (`api *` and its options).
+  It names two tests: one that checks every generated command's options against the snapshot, and one that drives a
+  generated command through `run()` into the executor every generated command shares. A hand-written command in the
+  same CLI still needs its own test or live scenario.
 - **Applies to:** all CLIs. memo's check fails only on a stale page, not yet on an option with no test.
   **Since:** cli-base 0.41.0. **Rulings:** NEED-359.
 
@@ -192,9 +199,13 @@ and which run after merge is in [CI](ci.md).
 - **Enforced by:** `node-ci.yml:check` · `<app>: pnpm contracts:upgrade`.
 - **Example:** `pnpm contracts:upgrade` runs the previous published package and this build on the same synthetic
   state and checks that the data survives. Each store migration also has its own upgrade test (WC-STORE-9).
-- **Exceptions:** a CLI with no local state, or with no published version yet. Local state is data the CLI's own
-  code writes and reads back in a later run, such as a store, a session or a cache. A config file and run records
-  that only cli-core writes do not count.
+- **Exceptions:** a CLI with no local state, or with no published version yet. Local state is data the CLI writes
+  and reads back in a later run, such as a store, a session or a cache. The shared store counts, also when cli-core's
+  code writes it, because the CLI's release decides which cli-core and so which migrations run: gcal's calendars and
+  events in the store are its local state. A config file, run records, the
+  update check, MCP logins and lock files that only cli-core writes do not count. Tests still keep them in the
+  sandboxed home, like every other path
+  ([WC-TEST-1](#wc-test-1--point-every-path-a-test-could-write-at-a-temporary-directory)).
 - **Applies to:** all CLIs with local state. wa has no upgrade contract yet. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TEST-15 · A refactor keeps `commands --json` and the MCP tool list as they were

package/docs/standards/time.md

@@ -76,7 +76,14 @@ local midnight. The answer gives the window it used, in UTC.
 - **Why:** "messages of 1 September" means the owner's day, not the UTC day, which starts hours earlier or later.
 - **Enforced by:** review only.
 - **Example:** in `Asia/Vladivostok`, `--since-time 2026-09-01` gives `meta.window.since` = `2026-08-31T14:00:00.000Z`.
-- **Exceptions:** none.
+  A thing that has only dates, such as an all-day event (`start_date` 2026-09-01, `end_date` 2026-09-02, the end
+  not included), matches by comparing local dates, never UTC moments: it is in the window when its dates overlap the
+  local dates the window covers. So in `Europe/Madrid` a filter for 1 September returns the all-day event of
+  1 September and not the one of 31 August, whatever zone the event's calendar is in.
+- **Exceptions:** none. Known gap, as of 2026-10-27, read from the code and not run: cli-core's event filter
+  (`src/store/sqlite/calendar.ts`, the `events` query) compares `starts_at` and `ends_at` with the UTC window for
+  all-day events too, and gcal stores an all-day event's start as midnight in its calendar's zone. The two agree
+  when the calendar's zone is the zone in use, and miss by a day at the edges when it is not.
 - **Applies to:** all CLIs. **Since:** cli-base 0.48.0. **Rulings:** none.
 
 ### WC-TIME-6 · Run the tests in a zone that is not UTC, and prove stored values do not depend on it