@wirecat/cli-base 0.40.4 → 0.41.0

package/README.md

@@ -24,6 +24,7 @@ the command tree as data — the parts every CLI needs and nobody should write t
 | [Shared tooling](docs/TOOLING.md) | The TypeScript, Biome, lefthook, docs and CI setup a CLI takes from here, and `cli-dev` |
 | [Testing](docs/dev/TESTING.md) | The checks, and what each one is for |
 | [Conventions](docs/dev/CONVENTIONS.md) | How code here is written |
+| [Standards handbook](docs/standards/README.md) | The rules every WireCat CLI follows, one page per area (a skeleton for now) |
 | [CLI standard](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md) | The rules every WireCat CLI follows; this package holds them as data |
 | [Changelog](CHANGELOG.md) | What each version changed, and what may break callers |
 

package/docs/standards/README.md

@@ -0,0 +1,111 @@
+# WireCat CLI standards
+
+This handbook holds the rules every WireCat CLI follows: tools, layout, commands, output, MCP, accounts,
+permissions, architecture, tests, security, documents, releases and CI. Read this page first. Then read the page
+for the area you are about to change.
+
+It ships in the `@wirecat/cli-base` package. A CLI that depends on cli-base has it at
+`node_modules/@wirecat/cli-base/docs/standards/README.md`, at the same version as the `cli-dev lint` it runs.
+
+## How to use this for a new CLI
+
+Start with the [New CLI](new-cli.md) checklist. Each step names the check that proves it and the area page whose
+rules it keeps. A new CLI is ready for its first release when every check under "Done when" passes.
+
+## Which rule wins
+
+1. **The handbook wins over a repository's own documents.** When a `CONVENTIONS.md`, `CLAUDE.md` or `AGENTS.md`
+   disagrees with a rule here, the rule here applies, and the repository document is the one to fix.
+2. **A repository may be stricter, never looser.** For example, a smaller file size cap is fine. Turning off a
+   rule is not.
+3. **Product rules stay local.** A rule that only makes sense for one CLI lives in that CLI's `CLAUDE.md`, under
+   "Local rules", below a link to this page.
+
+## Areas
+
+| Page | Area id | Rules | What it covers |
+|---|---|---:|---|
+| [Toolchain](toolchain.md) | `TOOL` | 19 | TypeScript, Biome, grit plugins, size caps, import cycles, spelling, Markdown |
+| [Layout](layout.md) | `LAY` | 9 | Repository layout, entry points, exports, file size, one job per file, splitting a unit |
+| [Commands](commands.md) | `CMD` | 27 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help |
+| [Output](output.md) | `OUT` | 22 | Data on stdout only, envelopes, errors, exit codes, partial answers, projection |
+| [MCP](mcp.md) | `MCP` | 12 | The MCP tools, how they come from commands, what each permission shows |
+| [Accounts](accounts.md) | `ACCT` | 10 | The explicit profile, reads across accounts, scope flags |
+| [Permissions](permissions.md) | `PERM` | 21 | Levels, keys, defaults, hard limits, the write guard and its journal |
+| [Architecture](architecture.md) | `ARCH` | 16 | Layers, dependency direction, vendor types, what goes in which package |
+| [Lifecycle](lifecycle.md) | `LIFE` | 10 | Opening late, who closes, one-shot exits, long-running commands, the `serve` relay |
+| [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
+| [Testing](testing.md) | `TEST` | 17 | Sandbox, no network, no real waits, leak tests, coverage, contracts, test matrix, parity |
+| [Security](security.md) | `SECR` | 19 | Secrets, logs, keyring, argv, error text, scanners, workflow hardening, reporting |
+| [Documents](docs.md) | `DOC` | 20 | User pages and developer pages, generated pages, current facts, changelog |
+| [Releases](releases.md) | `REL` | 16 | `bin/release`, the release lock, versions, release reports, trusted publishing |
+| [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |
+| [Style](style.md) | `STYLE` | 10 | Comments, TypeScript habits, commit messages |
+| [New CLI](new-cli.md) | — | — | The checklist for starting a new CLI |
+
+Each count leaves out the ids that moved or merged (see "How ids work").
+
+## How a page is laid out
+
+Every area page has the same parts, in this order:
+
+1. **Scope:** what the page covers, its rule id prefix, and links to the pages that own nearby rules. It may add
+   "Words used here" for terms the page defines, and "Who follows these rules today" for known gaps in a CLI.
+2. **The rules:** under one `## Rules` heading, or under a few `##` headings that group them by theme.
+3. **Planned — not built yet** (only on a page that needs it): an approved design that is not true yet. It has no
+   rule ids.
+4. **Sources:** a short list of the documents the rules came from. Where one of them disagrees with the page, the
+   page holds.
+
+## How a rule is written
+
+Every rule has the same shape. A rule may add a sentence or a short list under its heading, before the bullets.
+
+```markdown
+### WC-<AREA>-<n> · <the rule, in one short sentence>
+
+- **Why:** <one line>.
+- **Enforced by:** <check names in backticks, joined by " · ">, or the words "review only".
+- **Example:** <a command or a piece of code that keeps the rule>.
+- **Exceptions:** <when the rule does not apply>, or "none".
+- **Applies to:** <all CLIs, or which ones>. **Since:** cli-base <version>. **Rulings:** <ids>, or "none".
+```
+
+- **Enforced by** names checks in one of these forms:
+  - a check in this repository: a `cli-dev lint` or `cli-dev audit` rule (`flag-synonym`), a workflow (`ci.yml`, or
+    `ci.yml:ci` for one job), a `pnpm` script (`pnpm standards:check`) or a file by its path (`src/keyring.test.ts`);
+  - a check in another repository, as `<repo>: <check>`, such as `cli-core: pnpm parity:check` or
+    `cli-core: biome noRestrictedImports`. `<repo>` is the repository's name on GitHub: `cli-core`, `cli-testing`,
+    `cli-docs`, `community`, `tg-cli`, `max-cli`, `cli-memo`, `drive-cli`, `zoom-cli` or `whatsapp-cli`. `<app>`
+    stands for each CLI the rule applies to, when every one of them runs that check in its own repository.
+- **Since** is the cli-base release whose handbook first carried the rule. A feature can be older than its rule.
+
+## How ids work
+
+- A rule id is `WC-<AREA>-<n>`, for example `WC-OUT-3`. The area id is in the table above.
+- The `WC-` prefix keeps rule ids apart from other ids in the WireCat repositories.
+- Numbers go up within a page and are never reused or renumbered. A new rule takes the next number and goes last on
+  its page.
+- A rule that moves to another page, or merges into another rule, keeps its id as a one-line entry, so a citation of
+  the old id still leads somewhere:
+
+  ```markdown
+  ### 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)
+  ### WC-ARCH-12 · Merged into [WC-LIFE-6](lifecycle.md#wc-life-6--open-nothing-until-an-action-needs-it)
+  ```
+- A `cli-dev lint` or `cli-dev audit` rule keeps its own kebab-case name, such as `flag-synonym`. The handbook rule
+  names it under "Enforced by".
+
+## What `pnpm docs:check` checks here
+
+[`scripts/standards-ids.ts`](https://github.com/WireCatLabs/cli-base/blob/main/scripts/standards-ids.ts) reads every
+page and fails when:
+
+- a rule id appears twice, belongs to another page's area, or is out of order on its page;
+- a rule has no "Enforced by" line;
+- a name in an "Enforced by" line, on any of its lines, is not a known check. A check in this repository must exist.
+  A check in another repository cannot be read from here, so only its form is checked: a known repository name, a
+  colon and a space, and a check name. Anything else says "review only";
+- a "Moved to" or "Merged into" entry points at an id that is not a rule;
+- the rule count in the table above differs from the page;
+- a page in this folder is not linked from this index.

package/docs/standards/accounts.md

@@ -0,0 +1,148 @@
+# Accounts
+
+## 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.
+
+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.
+
+Rule ids on this page are `WC-ACCT-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+### Who follows these rules today
+
+cli-core resolves the profile for tg, max and wa. WC-ACCT-1 needs cli-core 0.319.0 or newer, and all three pin
+0.321.0. memo has no messenger profile: its shared commands run without one, and they pick accounts with `--provider`
+and `--account` (WC-ACCT-7). drive and zoom still have their own profile code: drive registers its own profiles, and
+zoom keeps one saved profile in its config file. These are known gaps, not exceptions.
+
+## Rules
+
+### WC-ACCT-1 · Name the profile on every command that acts for an account
+
+The profile is the first word on the command line, or the `<PREFIX>_PROFILE` variable. Nothing picks one for the
+owner: not a config file, not the first profile in a list, not a profile called `default`, and not the only profile
+on the computer.
+
+- **Why:** which account a command speaks for is the owner's choice; a guess sends from the wrong account.
+- **Enforced by:** `cli-core: src/cli/settings.test.ts`.
+- **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.
+
+### WC-ACCT-2 · The profile is a word, never a flag
+
+There is no `--profile` option. The first word is the profile unless it names a command, and an option is never a
+profile.
+
+- **Why:** one place for the profile keeps every command line readable the same way, in every CLI.
+- **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.
+
+### WC-ACCT-3 · A missing profile is an error that lists the choices
+
+When a command needs a profile and none is named, it fails with `validation_error`. The message and
+`details.profiles` list the profiles on this computer. With no profile at all, the message says how to create one by
+name.
+
+- **Why:** the owner, or an agent, can fix the command from the error alone.
+- **Enforced by:** `cli-core: src/cli/settings.test.ts`.
+- **Example:** ``name a profile: `tg <profile> …` — profiles here: personal, work (or set TG_PROFILE)``. With none,
+  the message says to ``create one with `tg personal setup` (any name in place of personal)``.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ACCT-4 · A profile name is a plain word and never a command word
+
+A name has letters, digits, dot, dash and underscore only, and starts with a letter or a digit. A name that is also a
+top-level command, such as `chats` or `bot`, is refused when the profile is created. `default` is an ordinary name.
+
+- **Why:** the name becomes a file name and a keyring account, and a profile named after a command could never be
+  selected.
+- **Enforced by:** `cli-core: src/cli/profile.test.ts` · `cli-core: src/cli/settings.test.ts`.
+- **Example:** `tg work setup` works. `tg chats setup` is refused with the list of command words to avoid.
+  `tg a/../b setup` is refused as a name.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-294.
+
+### 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`.
+
+- **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`.
+- **Example:** with `MAX_PROFILE_LOCK=agent`, `max personal messages send …` is refused, and `max messages list` runs
+  as `agent`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ACCT-6 · The most specific setting wins
+
+A setting is read from the nearest of these sections: this profile's `personal` or `bot` entry, then the profile,
+then every personal account or every bot (`personal.defaults`, `bot.defaults`), then `defaults`.
+
+- **Why:** naming one account says more than naming all of them, so it must not be undone by a broader section.
+- **Enforced by:** review only.
+- **Example:** `defaults.sends_per_hour: 30` and `profiles.work.sends_per_hour: 10` give `work` a limit of 10.
+- **Exceptions:** permissions layer the same way, with one more rule: see [WC-PERM-7](permissions.md).
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-355.
+
+### WC-ACCT-7 · Never pick an account inside a provider for the owner
+
+When a provider has several accounts, the command takes `--account <account>` or reads all of them. It never takes the
+first account in a list.
+
+- **Why:** the same reason as WC-ACCT-1, one level down.
+- **Enforced by:** review only.
+- **Example:** `memo search mail "invoice"` reads every mailbox; `--source email:work` reads one.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ACCT-8 · Scope flags have one meaning in every CLI
+
+`--account` names one account. `--provider` reads every account of one provider. `--source` takes a comma-separated
+list of `provider:account`, a provider, a kind, or `group:<name>`. `--all-bots` also reads the other bots' copies that
+the config allows.
+
+- **Why:** an agent that learned a flag in one CLI must not be surprised by it in another.
+- **Enforced by:** `flag-two-meanings` · `flag-synonym` · `option-role` · `same-flag-meaning`.
+- **Example:** `memo search messages "invoice" --source telegram,max`.
+- **Exceptions:** `same-flag-meaning` runs weekly and does not block a pull request.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ACCT-9 · A read across accounts covers all of them and says which it read
+
+A read that is not limited to one account reads every account in its scope, and its answer names them, for example in
+`coverage.accounts`.
+
+- **Why:** an answer from part of the data must not look like an answer from all of it.
+- **Enforced by:** review only.
+- **Example:** `search messages` answers `coverage.accounts`; `search mail` names the mailboxes it read.
+- **Exceptions:** a meaning search never reads wider than the running account unless `--source` says so. `search all`
+  reads meetings only when they are named. Not every cross-account read reports its accounts yet.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** ss:8.
+
+### WC-ACCT-10 · A bot reads another bot's copy only when the config and the command both say so
+
+- **Why:** each bot's local copy belongs to that bot; reading it is a choice, not a default.
+- **Enforced by:** review only.
+- **Example:** `read_other_bots: ["support"]` in the bot's section, and `--all-bots` or `--bots support` on the command.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** bots:12.
+
+## Sources
+
+These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page
+holds.
+
+- [cli-core `STANDARD.md`, "Command names"](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md#command-names), rule 1
+- [cli-core `ARCHITECTURE.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ARCHITECTURE.md), on the account-bound store

package/docs/standards/architecture.md

@@ -0,0 +1,214 @@
+# Architecture
+
+## Scope
+
+How the code is split: the layers and the direction of dependencies, no vendor type above the adapter, and what
+belongs in cli-base, in cli-core or in the CLI itself.
+
+Rule ids on this page are `WC-ARCH-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+Related pages: file size, one job per file and how a large unit is split are in [Layout](layout.md); import cycles
+and the lint that holds the layers are in [Toolchain](toolchain.md); who opens and closes a resource, what may open
+at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's own rules are in [Store](store.md).
+
+### Words used here
+
+- **Adapter:** the code that talks to one provider (Telegram, MAX, WhatsApp, Google Drive, Zoom) and translates its
+  objects into our own types.
+- **Port:** an interface that says what a service needs, for example `MessengerAdapter` or a store area.
+- **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`.
+
+## Rules
+
+### WC-ARCH-1 · Call only the layers below you: interface, then service, then port, then adapter
+
+- **Why:** when a command calls an adapter directly, the MCP tool for the same job does something different.
+- **Enforced by:** review only.
+- **Example:** cli-core has five layers: domain (`src/domain/`), adapters, ports (`port.ts`, the store), services
+  (`src/services/`) and the interface (commands and MCP tools). Its `biome.json` is meant to refuse an import of
+  `commander` or of `src/cli/` from the services and the layers below them, and an import of a command file from
+  `src/mcp/`. What a
+  command and a service share lives below the command.
+- **Exceptions:** none. A new adapter method goes into a named group in `port.ts`, never into the domain. Today the
+  last `noRestrictedImports` override in cli-core's `biome.json` replaces the earlier ones, so cli-core's layer,
+  provider, module and store import rules (WC-ARCH-2, WC-ARCH-8, WC-STORE-4) catch nothing until it is fixed.
+- **Applies to:** all CLIs. Each repository's `biome.json` holds its own import rules. **Since:** cli-base 0.41.0.
+  **Rulings:** none.
+
+### WC-ARCH-2 · Dependencies point one way: a CLI depends on cli-core, cli-core on cli-base, never back
+
+- **Why:** a shared package that imports an app cannot be shared.
+- **Enforced by:** review only.
+- **Example:** cli-base has no dependency on cli-core or on any CLI. cli-core's `biome.json` is meant to refuse an import
+  of a messenger library or an adapter directory ("cli-core speaks no provider"); today it does not (WC-ARCH-1).
+- **Exceptions:** none.
+- **Applies to:** cli-base, cli-core and all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-3 · Only the adapter imports a vendor library; nothing above it sees a vendor type
+
+- **Why:** the provider library underneath must be replaceable, and the layers above must not change when it is.
+- **Enforced by:** `max-cli: biome noRestrictedImports` · `tg-cli: biome noRestrictedImports` ·
+  `whatsapp-cli: biome noRestrictedImports`.
+- **Example:** in max-cli, `biome.json` lets only `src/client.ts` and `src/client/` reach the protocol, and only
+  `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.
+- **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
+
+- **Why:** the CLIs keep to one standard by sharing code, not by copying text.
+- **Enforced by:** review only.
+- **Example:**
+  - cli-base: general CLI infrastructure that needs no domain knowledge. This includes the streams, the renderer,
+    errors and exit codes, the keyring, config and paths, clocks, retry, the command registry and format-neutral code
+    generation.
+  - cli-core: provider-neutral models, ports and use cases, even when only one CLI uses them today. Meeting discovery
+    is in cli-core although Zoom was its first user.
+  - The CLI: vendor translation, profile binding, resource lifetimes and rules that only make sense for that product.
+- **Exceptions:** share an invariant or a real capability. Lines that only look alike are not a reason for a new
+  shared abstraction.
+- **Applies to:** cli-base, cli-core and all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-292, NEED-440.
+
+### 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.
+- **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,
+  NEED-301, NEED-444.
+
+### WC-ARCH-6 · Replace a use case, not a command
+
+- **Why:** when a CLI replaces the service method, its command and its MCP tool both get the change.
+- **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.
+- **Exceptions:** none.
+- **Applies to:** messenger 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
+
+- **Why:** two transports that each interpret a query or a write policy drift apart.
+- **Enforced by:** review only.
+- **Example:** query interpretation, cursor binding, evidence checks and write policy live in the service. Each
+  caller parses its own input, so an error names `--since` in a command and `since` in a tool, but both run the same
+  method and give the same error for the same input.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-8 · Cross a module boundary only through the module's entry point
+
+- **Why:** a deep import ties the caller to another module's internals.
+- **Enforced by:** `cli-memo: biome noRestrictedImports` · `drive-cli: biome noRestrictedImports` ·
+  `zoom-cli: biome noRestrictedImports`.
+- **Example:** in cli-core, `src/tasks/` and `src/meetings/` are entered only through their `index.ts`, `cli/`, `mcp/`
+  and `testing/` entries; its `biome.json` is meant to refuse the rest, and today does not (WC-ARCH-1). memo, drive and zoom have a "public exports only" rule. A
+  package's own entry points are its `exports`
+  ([WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcindexts)).
+- **Exceptions:** tests may import what they test.
+- **Applies to:** all CLIs. tg, max and wa do not have the import rule yet. **Since:** cli-base 0.41.0.
+  **Rulings:** none.
+
+### WC-ARCH-9 · Pass the narrow port or callback a use case needs, not a whole store or container
+
+- **Why:** a narrow dependency shows what the use case touches and is easy to replace in a test.
+- **Enforced by:** review only.
+- **Example:** a service sees the messenger as `MessengerTraits`, only the fields it reads. The CLI's `Messenger`
+  adds how commands connect.
+- **Exceptions:** none. Add a factory, inheritance or a dependency-injection framework only for a concrete benefit.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-10 · Pass every effect on the machine as an argument, with the real one only as the default
+
+- **Why:** a test then replaces the clock, the keyring or the network, and never touches the real machine.
+- **Enforced by:** review only.
+- **Example:** clock, sleep, keyring, `env`, `fetch`, streams, stdin and the TTY check are parameters or fields of the
+  command environment. Production code uses `environment.sleep ?? realSleep`. A new effect gets a new field, not a
+  module mock.
+- **Exceptions:** none. Watch the defaults: `new Credentials({...})` without `keyring` is the owner's real keychain,
+  and `resolvePaths` without `env` reads `process.env`.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-11 · Keep one command environment per program, cli-core's
+
+- **Why:** two registries of the same environment must both be filled on every run, and one is always forgotten.
+- **Enforced by:** review only.
+- **Example:** a CLI extends `BaseEnvironment`, hands it to cli-core's `provide(program, environment)`, and its
+  commands read it with `environmentOf<Environment>(command)`, never with `process.*`.
+- **Exceptions:** a CLI that does not use cli-core's command skeleton keeps one environment of its own.
+- **Applies to:** CLIs built on cli-core's command skeleton. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-12 · Merged into [WC-LIFE-6](lifecycle.md#wc-life-6--open-nothing-until-an-action-needs-it)
+
+### WC-ARCH-13 · Merged into [WC-LIFE-1](lifecycle.md#wc-life-1--the-code-that-opens-a-resource-closes-it-so-a-one-shot-command-exits-when-it-has-answered)
+
+### WC-ARCH-14 · Merged into [WC-LIFE-11](lifecycle.md#wc-life-11--run-commands-through-serve-when-the-messenger-allows-one-connection-per-account)
+
+### WC-ARCH-15 · Each CLI runs its own background server, built on cli-core's process library
+
+- **Why:** a server shared between CLIs couples their releases and their failures.
+- **Enforced by:** review only.
+- **Example:** cli-core's `./background` export holds the lock per app and profile, the PID check and the systemd and
+  launchd units. `tg serve` and `max serve` are each built on it.
+- **Exceptions:** none.
+- **Applies to:** CLIs with a background process. **Since:** cli-base 0.41.0. **Rulings:** NEED-492.
+
+### WC-ARCH-16 · Layers below the commands never name a command
+
+- **Why:** an adapter that prints "check `tg polls show`" breaks when the command is renamed and cannot be shared.
+- **Enforced by:** review only.
+- **Example:** a tg adapter error carries a typed reason, such as `{ check: "polls.show" }`. The command layer turns
+  the reason into the words `tg polls show`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-17 · Merged into [WC-LAY-8](layout.md#wc-lay-8--give-each-module-one-reason-to-change)
+
+### WC-ARCH-18 · An optional capability that is missing fails out loud
+
+- **Why:** a request that quietly becomes a smaller one gives the caller a wrong answer that looks right.
+- **Enforced by:** review only.
+- **Example:** a new adapter method is optional and reached with `capability()`. When it is absent, the command
+  refuses with a reason; it does not drop the filter or the scope it could not apply.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-820.
+
+### WC-ARCH-19 · Shared packages print nothing and log nothing on their own
+
+- **Why:** what is written, and where, is the host's decision; a stray line breaks machine output.
+- **Enforced by:** review only.
+- **Example:** cli-base hands the host a `Logger` interface, a Pino adapter and a renderer. It never calls
+  `console.log`, nor `console.error`, which the lint allows elsewhere
+  ([WC-TOOL-9](toolchain.md#wc-tool-9--write-to-the-console-only-with-consoleerror-except-in-scripts)).
+- **Exceptions:** none.
+- **Applies to:** cli-base and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-20 · Keep HTTP out of cli-base's root export
+
+- **Why:** a CLI that only speaks a socket must not depend on an HTTP stack.
+- **Enforced by:** review only.
+- **Example:** a helper that reads a status code or a header goes to `@wirecat/cli-base/http`. How an entry point
+  is added is [WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcindexts).
+- **Exceptions:** none.
+- **Applies to:** cli-base. **Since:** cli-base 0.41.0. **Rulings:** NEED-15.
+
+## Sources
+
+These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page
+holds.
+
+- [cli-base `MODULARITY.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/MODULARITY.md)
+- [cli-base `ARCHITECTURE.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/ARCHITECTURE.md)
+- [cli-core `ARCHITECTURE.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ARCHITECTURE.md)
+- [cli-core `ADAPTERS.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ADAPTERS.md)

package/docs/standards/ci.md

@@ -0,0 +1,159 @@
+# CI
+
+## Scope
+
+What runs where: the local hooks, the checks on every pull request and their time budget, full validation on each
+merge to `main`, and the monthly runs.
+
+Rule ids on this page are `WC-CI-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). What each tool checks is on the [Toolchain page](toolchain.md); the release workflow is on the
+[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.
+
+## Rules
+
+### WC-CI-1 · Run only staged lint and a staged secret scan before a commit
+
+- **Why:** a hook that takes more than a second makes people skip it, which is worse than a small hook.
+- **Enforced by:** `pnpm standards:check` · `standards.yml:standards`.
+- **Example:** the shared `lefthook` config runs, in parallel, Biome on the staged files and
+  `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.
+
+### WC-CI-2 · Add no push hook, and no hook that installs, builds, checks types, generates or tests
+
+- **Why:** every check in a hook runs again in CI, so a slow hook only costs time and teaches people to bypass hooks.
+- **Enforced by:** review only.
+- **Example:** a repository's `lefthook.yml` holds only the `extends` line for `config/wirecat/lefthook.yml`. An agent
+  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.
+
+### WC-CI-3 · Run the fast standards job on every pull request and every push to `main`
+
+- **Why:** it catches broken presets, lint, Markdown, types and new secrets in well under a minute, before review.
+- **Enforced by:** `standards.yml:standards`.
+- **Example:** the job does one cached install with lifecycle scripts off, then runs `pnpm standards:check`,
+  `pnpm lint`, `pnpm docs:lint`, `pnpm run --if-present ci:quick` and a gitleaks scan of the new commits only. A new
+  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.
+
+### WC-CI-4 · Keep `ci:quick` to early bug checks that finish within two minutes
+
+- **Why:** it is the only build-level check on a pull request, so it must stay fast enough that nobody wants it gone.
+- **Enforced by:** `standards.yml:standards` · `pnpm ci:quick`.
+- **Example:** what each repository runs today:
+  - tg, max, memo and wa: `pnpm typecheck && pnpm build && pnpm lint:commands`;
+  - drive: `pnpm typecheck && pnpm lint:commands`, which builds first;
+  - zoom, cli-base and cli-testing: `pnpm typecheck`;
+  - cli-core: `pnpm typecheck` and its command lint test;
+  - cli-docs: its unit tests, without the one that needs generated pages;
+  - community: its script tests.
+- **Exceptions:** never put live-account suites, agent suites, full tests, coverage or platform jobs here.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-5 · Keep full tests, builds of documents, parity and platform suites out of pull request CI
+
+- **Why:** pull request CI is the step people wait on; the heavy suites run once on `main`, where a failure still
+  shows within minutes of the merge.
+- **Enforced by:** review only.
+- **Example:** on a pull request, only the standards job, the changelog guard and small path-scoped jobs run. Coverage,
+  contracts, the test matrix, `docs:check`, parity, Windows and macOS run in full validation (WC-CI-7).
+- **Exceptions:** a path-scoped job that tests one platform-specific file may run on pull requests, such as cli-base
+  `macos.yml` for the path code. cli-docs and community run `security-pr.yml`, a new-commit secret scan. Third-party
+  security apps may post their own checks.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-6 · Run the changelog guard on every pull request
+
+- **Why:** the guard is the only check that reads the changelog on a pull request.
+- **Enforced by:** `changelog-guard.yml:guard`.
+- **Example:** each repository's `changelog-guard.yml` calls
+  `WireCatLabs/cli-base/.github/workflows/changelog-guard.yml` at a pinned commit, on `opened`, `edited`,
+  `synchronize` and `reopened`. The changelog rules it applies are on the [Documents page](docs.md).
+- **Exceptions:** cli-testing, cli-docs and community have no changelog guard yet.
+- **Applies to:** the CLIs, cli-base and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-7 · Run full validation once on each merge to `main`, on Linux, without publishing
+
+- **Why:** a merge that breaks the full suite shows up the same hour, not at the next release.
+- **Enforced by:** `main.yml:validation` · `node-ci.yml:check` · `node-ci.yml:bun` · `node-ci.yml:secrets`.
+- **Example:** `main.yml` calls the repository's own `ci.yml`, which calls cli-base `node-ci.yml`. That runs
+  `pnpm lint`, `pnpm typecheck`, `pnpm test:coverage`, `pnpm build`, then the project's `checks` lines (for max:
+  contracts, the no-leak scan, the version check, `pnpm generate` and `git diff --exit-code`, the test matrix,
+  `docs:check` and parity), a Bun job, and a gitleaks scan of the whole history.
+- **Exceptions:** platform suites (Windows, macOS, install checks) are skipped here and run at release, monthly or on
+  request. Nothing in this run publishes or tags. cli-docs runs its full validation before each deployment and monthly
+  instead; community has no build to validate.
+- **Applies to:** the CLIs, cli-base, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-8 · Call cli-base `node-ci.yml` from `ci.yml`, pinned to a tag or commit
+
+- **Why:** one shared workflow keeps the full suite the same everywhere, and a pin keeps a cli-base change from
+  breaking ten repositories at once.
+- **Enforced by:** `ci.yml:ci`.
+- **Example:** `uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@<commit> # v0.31.0`, with the project's own
+  checks in the `checks` input and `bun-run` for the Bun job. A job that only one repository needs stays beside it in
+  that repository's `ci.yml`.
+- **Exceptions:** never pin to `main`. cli-base itself calls `./.github/workflows/node-ci.yml`. cli-docs has its own
+  full workflow for the site, and community has none.
+- **Applies to:** the CLIs, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-9 · Run full validation and release security on the first day of each month, without publishing
+
+- **Why:** a repository with no merges for weeks still meets new advisories, new runner images and expired pins.
+- **Enforced by:** `monthly.yml:validation` · `monthly.yml:security`.
+- **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:21 UTC, so runs do not overlap.
+- **Exceptions:** 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.
+
+### WC-CI-10 · Run heavy security checks only at release, monthly or on request
+
+- **Why:** a pull request needs a fast secret check; source scanners take minutes and find nothing new on most
+  changes.
+- **Enforced by:** `release.yml:checks` · `monthly.yml:security`.
+- **Example:** cli-base `release-checks.yml` runs the production dependency audit, the workflow scan (`zizmor`),
+  CodeQL and a full-history gitleaks scan. A release depends on it. A pull request runs only the new-commit gitleaks
+  scan in the standards job.
+- **Exceptions:** none. 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.
+
+### 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)
+
+### WC-CI-12 · Merge to `main` only through a pull request whose checks all passed
+
+- **Why:** a red merge breaks `main` for every parallel branch, and an admin merge skips the only gate there is.
+- **Enforced by:** review only.
+- **Example:** `gh pr checks <number>` shows every line as pass before `gh pr merge`. Never merge with `--admin`. A
+  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.
+
+### WC-CI-13 · Start no live messenger or account test from a workflow
+
+- **Why:** a live test acts on a real account; only a person who chose to run it may start it.
+- **Enforced by:** review only.
+- **Example:** the offline contracts run in full validation. The live scenarios run only by hand, through the CLI's
+  live-test procedure, on test accounts.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.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
+holds. The procedures stay in their own homes.
+
+- [community check schedule](https://github.com/WireCatLabs/community/blob/main/standards/CHECKS.md): the rough timings
+- [cli-testing CI folder](https://github.com/WireCatLabs/cli-testing/tree/main/docs/ci): the cross-project timing
+  table, the monthly runbook and the contract runner