@wirecat/cli-base 0.40.3 → 0.41.0

package/docs/standards/output.md

@@ -0,0 +1,256 @@
+# Output
+
+## Scope
+
+What a command prints and how it fails: data on stdout and nothing else in machine mode, the envelopes, errors and
+exit codes, partial answers, field projection and retries.
+
+Rule ids on this page are `WC-OUT-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). What a command declares about itself is on the [commands](commands.md) page. How a process ends
+on a signal is on the [lifecycle](lifecycle.md) page.
+
+"Machine mode" means `--json` or `--jsonl`. The shapes below are Valibot schemas in cli-base
+[`src/standards/output.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/output.ts) and
+[`src/standards/errors.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/errors.ts). They also emit
+JSON Schema 2020-12.
+
+## Streams
+
+### WC-OUT-1 · Put data on stdout and nothing else in machine mode
+
+- **Why:** agents and scripts parse stdout, and one stray line breaks every caller.
+- **Enforced by:** review only.
+- **Example:** `tg chats list --json | jq .items` gets one JSON value. Notes, warnings, progress and next-step hints go
+  to stderr. cli-base's renderer sends every diagnostic to stderr in every mode, and in machine mode it drops the
+  `✓` and `·` marks.
+- **Exceptions:** an explicit `--help` or `--version` prints text on stdout and exits 0.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-88.
+
+### WC-OUT-2 · Build the human view from the same facts as the machine answer
+
+- **Why:** machine output stays one stable value, and the human view can change freely.
+- **Enforced by:** review only.
+- **Example:** the command builds one answer object. `--json` prints it whole, and the pretty view draws its items.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-3 · Fail loudly for what the person asked for, and quietly, with a reason on stderr, for the rest
+
+- **Why:** a side task that breaks must not hide the answer, and a main task that breaks must not look like success.
+- **Enforced by:** review only.
+- **Example:** a send that fails exits non-zero. A side check nobody asked for that fails writes one line to stderr,
+  and the command keeps its own exit code. Once a write is under way, a run log that cannot be written is a warning
+  and never changes the exit code.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-97, NEED-133.
+
+## Envelopes
+
+### WC-OUT-4 · Answer every JSON request with one envelope: a list or one thing
+
+- **Why:** a caller reads `items` or `item`, `page` and `meta` in the same place in every command of every CLI.
+- **Enforced by:** `cli-core: src/cli/envelope.test.ts` · `cli-core: src/mcp/output-schema.test.ts`.
+- **Example:** a list is `{ items, page, next?, missing?, meta }`. One thing is `{ item, next?, missing?, meta }`.
+  cli-core builds them with `listOf` and `itemOf`, and its `renderAnswer` refuses any other shape. A list never
+  answers a bare array.
+- **Exceptions:** a document that is not about the owner's data is printed whole, with no envelope: `commands --json`
+  and a `--dry-run` preview.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-358 (its older list shape is replaced by
+  this one), NEED-431.
+
+### WC-OUT-5 · Say in `page` how the source pages
+
+- **Why:** a cursor source has no page numbers, and pretending it has them sends the caller to the wrong place.
+- **Enforced by:** review only.
+- **Example:** `{ mode: "page", limit, has_more, next_page? }`, or `{ mode: "cursor", limit, has_more,
+  next_cursor? }` for a source with its own position, such as a message history.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-6 · End a `--jsonl` stream with one end record
+
+- **Why:** a reader can tell a finished stream from a cut one.
+- **Enforced by:** review only.
+- **Example:** one `{"type":"item","data":…}` line per item, then `{"type":"end","complete":true,"page":{…}}`, with
+  `issues` when a source failed. A one-thing answer is one item line and the end line.
+- **Exceptions:** a report that is one object may refuse `--jsonl` with the reason `output.one-object`.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-7 · Put the facts about the run in `meta`
+
+- **Why:** `run_id` finds the run later, and `complete` says whether the answer can be trusted as whole.
+- **Enforced by:** review only.
+- **Example:** `{ run_id, duration_ms, accounts?, complete, issues?, truncated? }`. `complete: false` with
+  `issues: [{ code, reason?, source }]` says a source failed or was skipped. `truncated` says a size cap cut the
+  answer. Neither one means another page exists: that is `page.has_more`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-8 · Exit 0 on a partial answer only when the command declares `partial`
+
+- **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.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-9 · Offer at most two next steps, and mark a step safe only when it changes nothing on the service
+
+- **Why:** an agent may run a safe step unasked, so "safe" must be true.
+- **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
+  is built from ids, counts and cursors the CLI holds, never from text a message, mail or document carried.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-10 · Answer a write with what it did and its `operation_id`
+
+- **Why:** the id ties the answer to the send journal, and it is how a caller repeats the write safely.
+- **Enforced by:** review only.
+- **Example:** `{ "item": { "operation_id": "…", … }, "meta": { … } }`, with the ids the write touched beside
+  `operation_id`. The same id is in the send journal.
+- **Exceptions:** a bot account's send has no `--operation-id`, because no Bot API makes a repeat safe.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-431.
+
+### WC-OUT-11 · Give a shared command the same answer shape in every CLI of its group
+
+- **Why:** an agent that reads one CLI's answer can read the other's.
+- **Enforced by:** `same-path-contract` (weekly audit; it does not block a pull request yet) · `same-entity-schema`
+  (not wired yet: no CLI passes its schemas to the audit).
+- **Example:** what only one messenger knows goes under `provider_metadata`, never as a top-level field one CLI has and
+  the other lacks.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+## Keys and values
+
+### WC-OUT-12 · Use snake_case keys, one meaning per key, and the registered identifier names
+
+- **Why:** a key that changes name or meaning between commands breaks every parser that relied on it.
+- **Enforced by:** `key-casing` · `identifier-name`.
+- **Example:** `run_id`, never `execution_id` or `log_id`. `operation_id`, never `send_id`. `request_id` and `trace_id`
+  are the other registered ids.
+- **Exceptions:** keys that are the owner's or a provider's own words stay as written, such as a note's front matter
+  or an email's headers. `key-casing` checks the `commands --json` document today; it checks entity schemas only when
+  a CLI passes `--schemas`.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-13 · Write times, durations, references and empty values one way
+
+- **Why:** a caller must not guess whether `0` means "none" or "unknown".
+- **Enforced by:** `nullable-list`.
+- **Example:** a time is an ISO 8601 string with a zone, never epoch milliseconds. A length of time is a number of
+  milliseconds in a key ending in `_ms`. A stored thing is named by `ref`. A key that is absent was not asked for or
+  is not known. `null` is known to have no value. `[]` is known to be empty, never `null`. `0` is measured, never a
+  stand-in for unknown.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+## Errors and exit codes
+
+### WC-OUT-14 · Print a failure in machine mode as one JSON object on stderr, with stdout empty
+
+- **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`.
+- **Example:** `{"error":{"code":"not_found","reason":"item.not-found","message":"…","retry":{"safe":false}}}`. The
+  keys are `code`, `reason`, `message`, `param?`, `details?`, `next?`, `retry` and `run_id?`. MCP answers the same
+  object with `isError`. cli-base's `errorObjectOf` builds it.
+- **Exceptions:** with `--debug`, a second JSON line follows it on stderr: the failure's whole record. Under
+  `--jsonl`, lines already printed before a failure stay on stdout.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-15 · Branch on `code` and `reason`, never on `message`
+
+- **Why:** the message is for a person and may change. The code and reason are the contract.
+- **Enforced by:** `same-error-reason` (not wired yet: no CLI passes its reasons to the audit).
+- **Example:** `reason` is a registered dotted id, such as `query.too-large`, defined with `defineReasons` where it is
+  raised. `details` keeps only registered keys, and never a `cause`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-16 · Report a failure that is not a `CliError` as `internal_error`, exit 1, with a fixed message
+
+- **Why:** a foreign error's own text can carry anything, including data that must not reach the screen.
+- **Enforced by:** `src/failure.test.ts` · `cli-core: src/mcp/result-contract.test.ts`.
+- **Example:** `{"error":{"code":"internal_error","reason":"command.crashed",…}}`. No command can raise this code
+  itself.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-17 · Show a person one failure line and at most one next step
+
+- **Why:** a person reads the first line, and a stack trace tells them nothing they can act on.
+- **Enforced by:** review only.
+- **Example:** `✗ nothing found by that name` and then `→ list the chats: tg work chats list`. `--debug` adds the
+  whole record, cause and stack included.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-18 · Exit with cli-base's code for each kind of failure
+
+- **Why:** a script branches on `$?` without parsing text, and the numbers are the same in every CLI.
+- **Enforced by:** `src/exit-codes.test.ts`.
+- **Example:** 0 ok · 1 internal error · 2 validation error · 3 configuration error · 4 authentication error ·
+  5 permission error · 6 not found · 7 confirmation required · 8 rate limited · 9 timeout · 10 network error ·
+  11 provider error · 12 provider unavailable · 13 invalid response · 14 outcome unknown · 130 cancelled.
+- **Exceptions:** on cli-core's `run()`, a one-shot command stopped by SIGTERM exits 143. A `persistent` command
+  stopped by Ctrl-C or SIGTERM exits 0. A closed pipe exits 0. See the [lifecycle](lifecycle.md) page.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-19 · Report a wrong command line as `validation_error`, exit 2
+
+- **Why:** an unknown option and a missing argument are failures like any other, in the same shape.
+- **Enforced by:** review only.
+- **Example:** an unknown command or option, a missing argument or a missing required option prints the error object
+  and exits 2. So does a group named without a leaf.
+- **Exceptions:** an explicit `--help` or `--version` exits 0.
+- **Applies to:** CLIs that run on cli-core's `run()`. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-OUT-20 · Mark a failure safe to retry only when repeating it cannot do harm
+
+- **Why:** an agent repeats a failure marked safe, so a write that may have landed must never be marked safe.
+- **Enforced by:** `src/failure.test.ts`.
+- **Example:** every error has `retry: { safe, after_ms? }`. A transient failure (`timeout`, `rate_limited`,
+  `network_error`, `provider_unavailable`) is safe for a command that writes nothing on the service, or for a write
+  that never left (`sent: false`). A sync that only writes the local store is safe to repeat. `outcome_unknown` is
+  never safe: repeat that write only with its `--operation-id`.
+- **Exceptions:** cli-base's `retryOf`, used on its own, also counts a local write as a write, so it is stricter
+  than cli-core's runner.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+## Size and projection
+
+### WC-OUT-21 · Keep only the asked fields with `--json=a,b`, and keep the envelope
+
+- **Why:** an agent pays for every byte it reads, but it still needs to know the answer's limits.
+- **Enforced by:** review only.
+- **Example:** `tg chats list --json=items.id,items.title`. `source.title` picks a nested field. The keys `page`,
+  `next`, `missing`, `meta`, `coverage` and `operation_id` stay. A field that does not exist is left out. A bare
+  `--json` at a terminal lists the fields of a command that declares its answer, instead of printing them all.
+- **Exceptions:** numeric indexes and wildcards are not supported.
+- **Applies to:** CLIs that run on cli-core's `run()`; the projector itself (`projectFields`) is cli-base's.
+  **Since:** cli-base 0.41.0. **Rulings:** NEED-761.
+
+### WC-OUT-22 · Fail visibly when machine output passes its size cap
+
+- **Why:** a silently cut JSON answer looks whole.
+- **Enforced by:** `cli-core: src/cli/execution.test.ts` · `src/failure.test.ts`.
+- **Example:** machine output stops at 4 MiB by default. `--max-output-bytes <bytes>` changes it, and 0 turns the cap
+  off. Past the cap the command fails with `invalid_response`, reason `output.too-large`, `retry.safe: false`, and
+  `partial_output` says whether some output was already printed.
+- **Exceptions:** file exports keep their own streaming limits.
+- **Applies to:** CLIs that run on cli-core's `run()`; zoom uses cli-base's `createOutputBuffer` for the same cap.
+  **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.
+
+- [cli-core `STANDARD.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md): agent execution
+  contract, output
+- [cli-base API reference](https://github.com/WireCatLabs/cli-base/blob/main/docs/REFERENCE.md)

package/docs/standards/permissions.md

@@ -0,0 +1,295 @@
+# Permissions
+
+## Scope
+
+What a CLI may do without asking: permission levels and keys, their defaults, the limits no level lifts, the write
+guard and its journal.
+
+Two words used on this page:
+
+- A **write** is anything that changes something outside the local store: a message, a reaction, a group change, an
+  account change.
+- The **write guard** is the one check every write passes before it leaves the computer. cli-core builds it
+  (`sendGuard`), from the profile's settings.
+
+Rule ids on this page are `WC-PERM-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+### Who follows these rules today
+
+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 only reads. 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.
+
+## Rules
+
+### WC-PERM-1 · `permissions` is the only access setting
+
+A profile's `permissions` is a JSON object. Each key is a command path, and each value is a level. It holds the same
+way for a command the owner types and for an agent over MCP. A config file that still has the old `read_only` or
+`allow` settings is refused as an unknown setting.
+
+- **Why:** one setting means one place to look when the owner asks "what may this profile do".
+- **Enforced by:** review only.
+- **Example:** `{ "permissions": { "messages": "allow", "messages.delete": "ask", "contacts": "readonly" } }`.
+- **Exceptions:** the recipient list (WC-PERM-14), the hourly limit (WC-PERM-15) and the file guard
+  ([WC-SECR-9](security.md)) are separate settings with separate jobs.
+- **Applies to:** every CLI that writes. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-2 · There are four levels: `deny`, `readonly`, `ask`, `allow`
+
+- `deny` — nothing, not even a read. The command answers `permission_error` (exit 5) before it connects, and an agent
+  is not offered the command.
+- `readonly` — reads work, writes answer `permission_error`. On a key that only writes, such as `messages.delete`, it
+  is the same as `deny`.
+- `ask` — a write asks first. See WC-PERM-9 for a terminal and [WC-MCP-7](mcp.md) for an agent.
+- `allow` — goes ahead and never asks.
+- **Why:** four words cover every choice the owner makes, and each one reads the same for every command.
+- **Enforced by:** review only.
+- **Example:** `tg work config set permissions.messages readonly`.
+- **Exceptions:** none.
+- **Applies to:** every CLI that writes. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-3 · A key is a command path, and the most specific key wins
+
+Keys are dotted command paths, such as `messages`, `messages.delete` or `chats.members.remove`. There is no wildcard.
+A key starts with a resource, so a misspelled key is refused, not ignored. Every command maps to exactly one key.
+
+- **Why:** the owner names exactly what they mean, and a typo cannot silently allow more.
+- **Enforced by:** review only.
+- **Example:** `messages: readonly` with `messages.send: allow` lets the profile send but not edit or delete.
+- **Exceptions:** see WC-PERM-4 and WC-PERM-5 for commands that map to another key or to none.
+- **Applies to:** every CLI that writes. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-4 · A command that shows messages is checked as `messages`
+
+A command outside `messages` that prints what people wrote, or who sent what, is checked against `messages` too.
+
+- **Why:** `deny messages` must stop every way of reading messages, not only the `messages` commands.
+- **Enforced by:** review only.
+- **Example:** `inbox`, `review`, `watch`, `serve`, `conversations`, `attachments list`, `chats documents`, `mentions`,
+  `contacts context`, `contacts timeline` and the `search` commands that read messages.
+- **Exceptions:** `search notes` reads only the owner's notes.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-5 · Housekeeping is never gated
+
+Commands that look after the tool and its files, and never show a message, have no key. No level stops them.
+
+- **Why:** a profile that denies everything must still be able to fix its own config and log in.
+- **Enforced by:** review only.
+- **Example:** `config`, `session`, `doctor`, `commands`, `complete`, `upgrade`, `skill`, `models`, `server`,
+  `schedule`, `runs`, `sends`, `recipients`, `flood`, `mcp`, `replies`, and `store info|check|migrate|backup|restore|
+  repair|copies`. Under `bot`: `auth`, `list`, `sends`, `recipients`, `mcp`.
+- **Exceptions:** what a schedule or a reply rule does is checked by its own key when it runs (`replies.send`).
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-6 · The built-in defaults ask only before what cannot be undone
+
+With no `permissions` set, a profile may do almost everything. The built-in defaults are:
+
+```json
+{
+  "messages.delete": "ask", "bot.messages.delete": "ask", "account.sessions.end": "ask",
+  "topics.enable": "ask", "topics.delete": "ask", "chats.delete": "ask", "chats.clear": "ask",
+  "replies.send": "deny"
+}
+```
+
+A default is never made stricter without the owner's word.
+
+- **Why:** the tool should work without questions; only a deletion, a logout or an automatic reply needs one.
+- **Enforced by:** `cli-core: src/sends/permissions.test.ts`.
+- **Example:** a new profile sends at once, and asks before `messages delete`.
+- **Exceptions:** `replies.send` is `deny`: a reply rule writes to people with nobody typing a command, so it waits for
+  the owner's own `allow`.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-568.
+
+### WC-PERM-7 · A built-in default only ever tightens
+
+Against a broader key the owner set, the stricter of the two holds. A key the owner set at the same depth or deeper
+wins. In the config file, a key in a nearer section also hides that key and every key under it in farther sections.
+
+- **Why:** `messages: allow` must not remove the question before a deletion by accident.
+- **Enforced by:** `cli-core: src/sends/permissions.test.ts`.
+- **Example:** `messages: allow` still asks before `messages delete`; `messages.delete: allow` does not. A profile's
+  `messages: readonly` is not undone by `messages.delete: allow` in `defaults`.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-8 · A permission path that moved is refused, not ignored
+
+When a command path moves, a config that still names the old path stops the command with `configuration_error` and
+says what to rename.
+
+- **Why:** a `deny` under an old path would stop working without anyone noticing.
+- **Enforced by:** review only.
+- **Example:** `messages.search` is refused with "rename … to search.messages"; `messages.stats` with
+  "rename … to stats.messages.show".
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-9 · `ask` at a terminal is a y/N question, default no
+
+The question shows what will change. A flag answers it: `--allow-dangerous` for a deletion nobody gets back, `--yes`
+for every other write. With no terminal and no flag, the command answers `confirmation_required` (exit 7).
+
+- **Why:** a deletion needs a flag a person has to mean, not a habit.
+- **Enforced by:** review only.
+- **Example:** `tg work messages delete @me 42 --allow-dangerous`.
+- **Exceptions:** `--allow-dangerous` is the flag for `messages.delete`, `bot.messages.delete`, `topics.delete`,
+  `chats.delete` and `chats.clear`; every other key takes `--yes`.
+- **Applies to:** every CLI that writes. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-10 · A flag confirms; it never grants
+
+`--yes` and `--allow-dangerous` only answer `ask`. They never lift `deny` or `readonly`. An `mcp` flag never grants
+either ([WC-MCP-8](mcp.md#wc-mcp-8--no-mcp-flag-grants-access)).
+
+- **Why:** a flag an agent can add must not be a way around the owner's settings.
+- **Enforced by:** `cli-core: src/cli/messenger/messenger.test.ts`.
+- **Example:** with `messages: readonly`, `messages send … --yes` is still refused.
+- **Exceptions:** none.
+- **Applies to:** every CLI that writes. **Since:** cli-base 0.41.0. **Rulings:** NEED-1423.
+
+### WC-PERM-11 · Some limits no level lifts
+
+An agent never deletes a message for everyone, and never ends the owner's other sessions.
+
+- **Why:** both hurt people other than the owner, or lock the owner out, and cannot be undone.
+- **Enforced by:** `cli-core: src/mcp/mcp.test.ts`.
+- **Example:** MCP `messages delete` has no `for_everyone` argument. A messenger whose every delete is for everyone
+  sets `Messenger.deleteForMe: false`, and there the MCP delete refuses with `permission_error` without connecting.
+  No MCP command ends sessions; `account sessions end` exists only on the command line.
+- **Exceptions:** the owner still has `messages delete --for-everyone` and `account sessions end` on the command line.
+  The sessions limit holds today only because no agent command was written for it.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-202, NEED-1423.
+
+### WC-PERM-12 · `<PREFIX>_READ_ONLY` refuses every write
+
+When this variable is set, every write answers `permission_error`, whatever `permissions` or a flag say.
+
+- **Why:** an unattended agent needs one switch that the config file and `--permission` cannot undo.
+- **Enforced by:** review only.
+- **Example:** `schedule` starts an agent with `MAX_READ_ONLY=1`, so it reads and drafts and cannot send.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-13 · Every write passes the write guard before it leaves
+
+The guard checks, in order: the read-only lock, the permission level, the recipient list, a flood hold from the
+messenger, and the hourly limit. Then it reserves a line in the send journal. A background server runs the same guard
+before every write it forwards, and so does an MCP server.
+
+- **Why:** a model that was talked into sending by a message it read must be stopped by code, not by its own judgement.
+- **Enforced by:** `cli-core: src/sends/guard.test.ts`.
+- **Example:** `messages send`, `reactions add`, `chats members add` and `polls vote` all call the guard.
+- **Exceptions:** the guard does not stop an agent that can edit the config file itself. Run an unattended agent under
+  `<PREFIX>_READ_ONLY` or `<PREFIX>_PROFILE_LOCK`, somewhere it cannot write the config.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-161, NEED-269, NEED-772.
+
+### WC-PERM-14 · The recipient list limits which chats a profile writes to
+
+Each profile may have a list of chats, kept in a state file and changed with `recipients add` and `recipients clear`.
+
+- No file means the check is off.
+- A file with no chats means nowhere.
+- A file that cannot be read refuses every write with `configuration_error`; it never opens up.
+- A person added to a group must have a one-to-one chat on the list.
+- A write to a chat not on the list answers `confirmation_required`, with the command that adds it.
+- **Why:** the owner can fence an agent into a few chats without changing any level.
+- **Enforced by:** `cli-core: src/sends/guard.test.ts`.
+- **Example:** `max work recipients add 123456`.
+- **Exceptions:** a bot has its own list.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-159, NEED-305.
+
+### WC-PERM-15 · The hourly limit counts what puts something in front of a person
+
+`sends_per_hour` is 30 for a personal account by default. A bot has no limit unless its `bot` section sets one.
+
+- Counted: a message, a forward, an edit, each deleted message, a pin that notifies, a new group, each person added or
+  let in, a join, and each imported phone number.
+- Not counted: a reaction, a quiet pin, a title change.
+- A scheduled message counts in the hour it is sent. One batch larger than the limit is refused.
+- Over the limit, the write answers `rate_limited` with the time the next one is possible.
+- **Why:** many writes at once is what the messenger reads as automation, and what bans an account.
+- **Enforced by:** `cli-core: src/sends/guard.test.ts`.
+- **Example:** `{ "defaults": { "sends_per_hour": 10 } }`.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-168, NEED-282, NEED-305.
+
+### WC-PERM-16 · A retry of an unknown outcome counts once
+
+When a write's outcome was unknown, a retry with the same send id in the same chat is not counted again. A retry under
+another `--send-as` identity is refused, because it may post twice.
+
+- **Why:** the provider delivers one message for both tries, so the limit must count one.
+- **Enforced by:** review only.
+- **Example:** `messages send … --operation-id 7f3c…` after `outcome_unknown`.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-277.
+
+### WC-PERM-17 · The send journal records every write attempt, and never its content
+
+Each attempt gets a line: time, profile, chat id, kind, action, count and outcome (`reserved`, `sent`,
+`outcome_unknown`, `refused`, `failed`). A line never holds the text, a title, a new value, or a person's id. A failure
+to write the journal after a send only warns.
+
+- **Why:** the journal is what the hourly limit counts and what the owner audits; content in it would be a second copy
+  of private messages. After a send, an error would invite a second send.
+- **Enforced by:** `cli-core: src/sends/guard.test.ts` · `cli-core: src/sends/journal.test.ts`.
+- **Example:** `{ "at": "…", "profile": "work", "chatId": "…", "kind": "message", "outcome": "sent" }`.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-161.
+
+### WC-PERM-18 · A flood hold stops writes until it ends
+
+When the messenger says the account may not write for a while, the profile holds every counted write until that time.
+Reads still work. The owner lifts the hold with `flood clear`.
+
+- **Why:** writing through a hold makes the messenger's penalty longer, or permanent.
+- **Enforced by:** review only.
+- **Example:** `max work doctor --online` shows the hold; `max work flood clear` lifts it once it is over.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-PERM-19 · Reading never marks anything read unless the command asks
+
+- **Why:** the other side sees a chat marked read; that is a write the owner did not ask for.
+- **Enforced by:** review only.
+- **Example:** `inbox --mark-read`, or `catch_up_marks_read: true` in the config, both checked as `chats.mark-read`.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-566.
+
+### WC-PERM-20 · A bot's keys are the personal keys under `bot`
+
+`bot.messages.send` and `bot.chats.members.remove` are bot keys; `bot` alone covers every bot command. A profile can
+allow its bot what it does not allow its personal account, and the other way round.
+
+- **Why:** a bot and a personal account do different jobs and need different limits.
+- **Enforced by:** review only.
+- **Example:** `{ "messages": "readonly", "bot.messages.send": "allow" }`.
+- **Exceptions:** bot housekeeping is never gated (WC-PERM-5).
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-294.
+
+### WC-PERM-21 · Group actions happen only inside a command the owner typed
+
+Moderation rules use the same four levels for each kind of action (delete, remove, accept, decline). `readonly` means
+"report it, do nothing". A background `serve` never polls or moderates groups.
+
+- **Why:** typing the command is the owner's consent for what the rules do.
+- **Enforced by:** review only.
+- **Example:** `tg work chats moderate @group` acts under `chats.moderate`; `tg work bot chats moderate` under
+  `bot.chats.moderate`.
+- **Exceptions:** an agent may run the same check over MCP, under the same levels. A rule's level is meant to be no
+  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.
+
+## 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`, "Permissions"](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md#permissions)