@wirecat/cli-base 0.40.4 → 0.41.0

package/docs/standards/commands.md

@@ -0,0 +1,302 @@
+# Commands
+
+## Scope
+
+How a command is shaped: its path and the verb and resource words it uses, flags and arguments, the effects and
+lifetime it declares, the entity it prints, the query language for lists, the `mcp` setting and help text.
+
+Rule ids on this page are `WC-CMD-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). What a command prints is on the [output](output.md) page. How long it runs and how it ends is on
+the [lifecycle](lifecycle.md) page.
+
+The words themselves are not copied here. They live in the cli-base registries, and `cli-dev lint` reads them from
+there:
+
+- verbs, views, resources and root words: [`src/standards/vocabulary.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/vocabulary.ts);
+- flags with one meaning in every CLI, and the option roles: [`src/standards/flags-how.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/flags-how.ts)
+  and [`src/standards/flags-what.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/flags-what.ts);
+- the lint rules: [`src/standards/lint.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/lint.ts); the audit rules and the required roots:
+  [`src/standards/audit.ts`](https://github.com/WireCatLabs/cli-base/blob/main/src/standards/audit.ts).
+
+A "messenger CLI" below is one of the CLIs that share cli-core's messenger commands: tg, max and wa. Their option
+catalogue and parity manifest stay in cli-core
+[`docs/dev/STANDARD.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md).
+
+## Paths and words
+
+### WC-CMD-1 · Build every path as resource first, then a verb or a view
+
+- **Why:** an agent that knows two commands can guess the third.
+- **Enforced by:** `unknown-verb` · `unknown-resource`.
+- **Example:** `<tool> [profile] [namespace] <resource> [subresource ...] <verb-or-view> [arguments]`, such as
+  `tg work chats members list <chat>`. A collection is plural (`chats`). A thing a profile has exactly one of is
+  singular (`account`). A group is never a verb.
+- **Exceptions:** a root word stands alone (`doctor`, `upgrade`). Generated commands (`bot api`) mirror the official
+  API's names.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-48, NEED-417.
+
+### WC-CMD-2 · Take every verb, view, resource and root word from the cli-base vocabulary
+
+- **Why:** one word has one meaning in every CLI, so `show` never means "list" somewhere else.
+- **Enforced by:** `unknown-verb` · `unknown-resource`.
+- **Example:** `show`, not `get` or `view`. Groups and channels are both `chats`. A new word goes into the registry in
+  its own pull request first, and the owner approves the wording. Then the command uses it.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-199, NEED-417.
+
+### WC-CMD-3 · Give a group without a leaf only its help, never a hidden default action
+
+- **Why:** a group that runs something when its leaf is missing does work nobody asked for.
+- **Enforced by:** `cli-core: src/cli/program.test.ts`.
+- **Example:** `tg chats` prints the commands under `chats`. At a terminal the help goes to stderr and the exit code
+  is 2. In machine mode the answer is a `validation_error` that names `--help`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-4 · Add a root word only when no resource or namespace can hold the command
+
+- **Why:** every root word is one more place an agent must look.
+- **Enforced by:** `unknown-verb`.
+- **Example:** statistics are `stats messages top`, not a new root `top`. The pull request that adds a root says which
+  group could not hold it and which commands it groups. One new report never earns a root of its own.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-5 · Give every CLI the required root commands
+
+- **Why:** agents and the cross-CLI audit start from the same entry points in every CLI.
+- **Enforced by:** `required-root` (weekly audit; it does not block a pull request yet).
+- **Example:** `commands`, `doctor`, `skill show`, `skill install`, `mcp`, `upgrade`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-6 · Give one action or one report one leaf command
+
+- **Why:** an option that turns a command into a different report hides that report from anyone reading the tree.
+- **Enforced by:** review only.
+- **Example:** ranking is `stats messages top`, not a ranking mode on `search messages`. Options choose the scope,
+  measure, order or format of the same action. No command both shows and changes something.
+- **Exceptions:** a documented preparatory fetch such as `--sync-first`. It keeps its own permissions and reports
+  its outcome.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-7 · Never let two commands overlap
+
+- **Why:** an agent that learns the narrow command never finds the wide one.
+- **Enforced by:** review only.
+- **Example:** a command whose main result is a search sits under `search <resource>` (`search all`,
+  `search messages`), and every statistic under `stats <resource>`. A narrower scope is an option or a resource of
+  the same command, not a sibling elsewhere. There is no `messages search` beside `search messages`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-846, NEED-847, NEED-1087.
+
+### WC-CMD-8 · Keep no aliases: a renamed path stops working in the release that renames it
+
+- **Why:** two names for one command split the docs, the tests and what agents learn.
+- **Enforced by:** review only.
+- **Example:** the release notes give the old and the new path under "Changed — may break callers". Help, completion,
+  generated pages, the skill, MCP names and permission keys move in the same change.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-417.
+
+### WC-CMD-9 · Answer the naming questions in the pull request before you build a new command
+
+- **Why:** a name is cheap to change before code, docs and agents depend on it.
+- **Enforced by:** review only.
+- **Example:** the pull request says what the user wants and which resource owns it, whether it is a new action or
+  an option of an existing one, how its path maps to its MCP name, what it answers and what it may change, and what
+  it moves or replaces.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-417.
+
+## Flags and arguments
+
+### WC-CMD-10 · Use a vocabulary flag for its meaning, and give one flag one kind of value everywhere
+
+- **Why:** `--limit` must mean "how many items" in every command of every CLI.
+- **Enforced by:** `flag-synonym` · `flag-two-meanings` · `same-flag-meaning` (weekly audit; it does not block a pull
+  request yet).
+- **Example:** `--limit <n>`, never `--max`, `--take` or `--count`. `--cursor <cursor>`, never `--offset`. How much
+  to read is `--limit`, `--page` and `--page-size`. A count of pages is never an option.
+- **Exceptions:** generated commands (`bot api`) are exempt from the naming rules.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-11 · Name an option in plain words, with the kind of value in the name
+
+- **Why:** a wire field name means nothing to a person, and an option that guesses its value's kind guesses wrong.
+- **Enforced by:** review only.
+- **Example:** `--operation-id`, not `--cid`. `--before-id` takes a message id, `--after-time` a time, `--before-n` a
+  count: two kinds are two options. A length of time is a `<duration>` with a unit (`500ms`, `30s`, `2m`, `4h`, `1d`),
+  never a bare number.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-12 · Give every option a role from the vocabulary, and filter a list with its query
+
+- **Why:** a filter flag per field grows without end and differs between CLIs. One query language does not.
+- **Enforced by:** `option-role` · `filter-flag`.
+- **Example:** the roles are paging, output, sort, mode, action, budget, scope, target, value and query. A list of open
+  tasks is `tasks list state:open`, not `tasks list --state open`.
+- **Exceptions:** `scope` flags pick accounts, providers or sources. They stay flags, because a scope is never picked
+  for you.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-13 · Name arguments with a singular noun of the thing they take
+
+- **Why:** the same thing has the same placeholder in every command, so an agent knows what to pass.
+- **Enforced by:** review only.
+- **Example:** messenger CLIs use `<chat>`, `<message>`, `<person>`, `<text>`, `<link>`, `<file>`, `<job>` and `<task>`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs; the fixed list applies to messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-14 · Keep the shared global flags at their meaning
+
+- **Why:** a script that works with one CLI works with the next.
+- **Enforced by:** review only.
+- **Example:** `--json` and `--jsonl` choose machine output. `--quiet` turns diagnostics off, but a failure is still
+  said. `-v` and `-vv` add detail, `-V` prints the version, `--trace` writes request diagnostics, `--debug` adds the
+  whole failure record. `--timeout <duration>` bounds the command. `--no-input` never prompts. `--dry-run` previews.
+  `--yes` answers the question an `ask` permission level puts before a write.
+- **Exceptions:** none.
+- **Applies to:** CLIs that run on cli-core's `run()`. **Since:** cli-base 0.41.0. **Rulings:** NEED-125.
+
+### WC-CMD-15 · Never prompt when no person can answer
+
+- **Why:** a prompt in a pipe or under an agent waits for ever.
+- **Enforced by:** review only.
+- **Example:** `--no-input`, `--json`, `--jsonl`, a `CI` variable or a stdout that is not a terminal each switch prompts
+  and browser logins off. Data piped on stdin for an explicit command still works. Buffered stdin stops at
+  `--max-input-bytes` (16 MiB by default).
+- **Exceptions:** none. `--yes` confirms a write; it never lifts a `deny`
+  ([WC-PERM-10](permissions.md#wc-perm-10--a-flag-confirms-it-never-grants)).
+- **Applies to:** CLIs that run on cli-core's `run()`. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-16 · Offer only ids in shell completion, with titles as their descriptions, from local data
+
+- **Why:** the shell calls completion on every Tab, so it must be fast and must not touch the network.
+- **Enforced by:** review only.
+- **Example:** `tg messages show <Tab>` offers chat ids, each with the chat's title beside it. The values come from a
+  local cache through `suggest` in `@wirecat/cli-base/completion`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-270.
+
+## What a command declares
+
+Each of these is set with `annotate(command, { … })` from `@wirecat/cli-base/commands` and appears in
+`commands --json`.
+
+### WC-CMD-17 · Declare `effects` on every command
+
+- **Why:** retries and unasked next steps are judged on effects, and a command without them counts as a write.
+- **Enforced by:** `cli-core: src/cli/effects.test.ts` · `cli-memo: src/effects.test.ts`.
+- **Example:** `annotate(send, { effects: { remote: "write", local: "write" } })`. Each side is `none`, `read` or
+  `write`. A sync that reads the service and writes the local store is `{ remote: "read", local: "write" }`.
+- **Exceptions:** none. Without `effects`, the error handler never marks a failure safe to retry, and a next step
+  that runs the command is never safe to run unasked.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-18 · Declare `lifetime` and `cooperative` instead of matching command names
+
+- **Why:** the runner decides the deadline, the signal handling and the exit code from the metadata, never from the
+  name, so a renamed command keeps its behaviour.
+- **Enforced by:** review only.
+- **Example:** `annotate(serve, { lifetime: "persistent" })` for a command that runs until stopped,
+  `annotate(login, { lifetime: "interactive" })` for a login that waits for a person, `cooperative: true` for a long
+  fetch that stops at its own pace. A runner reads them with `metaOf(command)`. What each does at run time is on the
+  [lifecycle](lifecycle.md) page.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-19 · Declare the entity a command answers with
+
+- **Why:** field projection, the query fields and the cross-CLI schema check all start from the entity.
+- **Enforced by:** review only.
+- **Example:** `annotate(list, { output: { entity: "meeting" } })`, or `{ entity: "contact", view: "profile" }` for a
+  view of one.
+- **Exceptions:** a command whose answer is not about the owner's data, such as `commands --json` or a `--dry-run`
+  preview.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-20 · Give a list one query over its entity's fields, as its last argument
+
+- **Why:** one query language for every list means an agent learns filtering once.
+- **Enforced by:** `list-without-query` · `query-example`.
+- **Example:** `tasks list state:open priority>1`. The list takes `[query...]` last. The fields come from the entity's
+  Valibot schema through `queryFieldsOf`, and every field example and default term parses and validates. The list
+  filters where its data lives, in the store or at the provider, never in memory.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-21 · Set `mcp: false` on a command or group that MCP servers must not offer
+
+- **Why:** the MCP tools are generated from the command tree, so the tree says what stays off it.
+- **Enforced by:** `src/commands/commands.test.ts`.
+- **Example:** `annotate(flood, { mcp: false })` keeps `flood` and every command under it off MCP servers. The CLI
+  still runs it. `commands --json` shows `mcp: false` on that command and each one below, and leaves the key out
+  everywhere else. Which commands get it is on the [MCP](mcp.md) page.
+- **Exceptions:** cli-base has had the field on commands and groups since 0.40.4; it has none on options yet.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1411.
+
+## Help and discovery
+
+### WC-CMD-22 · Describe every command, argument and option, with a summary of at most 80 characters
+
+- **Why:** help and `commands --json` are where people and agents learn the command.
+- **Enforced by:** `missing-command-help` · `missing-argument-help` · `missing-option-help` · `command-help-too-long`.
+- **Example:** `.description("stored meetings, newest first")`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-23 · Write help as the user sees the command: one line, lower case, no full stop, no internal term
+
+- **Why:** a wire field, a port or an adapter name means nothing to the person reading help.
+- **Enforced by:** review only.
+- **Example:** an option says what it changes and its unit: `--pause <duration>` "wait this long between pages".
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-24 · Give every leaf command one to three examples that run as written
+
+- **Why:** an example an agent copies must work.
+- **Enforced by:** `command-example-count` · `faulty-help-example-parameters`.
+- **Example:** `annotate(list, { examples: ["max chats list --limit 20"] })`. Each example starts with the tool, runs
+  its own command, and gives only arguments and options that command takes.
+- **Exceptions:** generated commands (`bot api`) need no examples.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-25 · Give a shared command and a shared option the same sentence in every CLI of its group
+
+- **Why:** they are one command, so they read as one.
+- **Enforced by:** `same-path-contract` (weekly audit; it does not block a pull request yet).
+- **Example:** the shared factory in cli-core writes the description. A CLI changes it only to name its messenger.
+- **Exceptions:** a sentence may differ where it names something the messenger's own way. The option catalogue in
+  cli-core says why.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-26 · Print the command tree with cli-base's `commandsDocument`, and keep every key snake_case
+
+- **Why:** agents, `cli-dev lint` and the audit read one shape from every CLI.
+- **Enforced by:** `key-casing`.
+- **Example:** `max commands --json` prints `{ cli, version, contract, description, global_options, … }`.
+  `max commands search messages --json` describes one command and adds `scope` and `inherited_options`. An unknown
+  or hidden path is a `validation_error` (exit 2) that lists the valid commands at that level.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CMD-27 · Refuse a command path that arrived as one word
+
+- **Why:** a shell loop that quotes `"projects add"` would otherwise get the root help and no reason.
+- **Enforced by:** `src/commands/commands.test.ts` · `cli-memo: src/program.test.ts`.
+- **Example:** call `refuseJoinedPath(program, args)` before `parseAsync`. It throws a `validation_error` that names
+  the words to type.
+- **Exceptions:** none. Only memo calls `refuseJoinedPath` today; cli-core and the other CLIs do not yet.
+- **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.
+
+- [cli-core `STANDARD.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/STANDARD.md): command names, agent
+  execution contract, help text
+- [cli-base API reference](https://github.com/WireCatLabs/cli-base/blob/main/docs/REFERENCE.md)

package/docs/standards/docs.md

@@ -0,0 +1,214 @@
+# Documents
+
+<!-- cspell:ignore whatsapp -->
+
+## Scope
+
+How documents are written: user pages and developer pages, generated pages, current facts only, languages, and the
+changelog.
+
+Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+## Rules
+
+### WC-DOC-1 · Keep user pages and developer pages apart
+
+- **Why:** a user page is read to do a task; a developer page is read to change the code. Mixed pages serve neither.
+- **Enforced by:** review only.
+- **Example:** `README.md` and `docs/*.md` are user pages. `docs/dev/*.md`, `CLAUDE.md`, `AGENTS.md` and
+  `SECURITY.md` are developer pages.
+- **Exceptions:** `CHANGELOG.md` is read by users and has its own rules (WC-DOC-14 to WC-DOC-20).
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-2 · A user page has no correction marks, no struck-out text and no internal ids
+
+- **Why:** the reader wants the current behaviour, not the history of a page or a journal number they cannot open.
+- **Enforced by:** `tg-cli: pnpm docs:check` · `max-cli: pnpm docs:check` · `whatsapp-cli: pnpm docs:check` ·
+  `zoom-cli: pnpm docs:check`.
+- **Example:** write "`--limit` defaults to 50", not "~~20~~ 50 (correction 2026-10-01, NEED-12)".
+- **Exceptions:** none. `cli-dev docs-check` checks this when the CLI's rules module sets `userPage`. tg, max, wa
+  and zoom set it; memo, drive and cli-base's default check do not.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-3 · Every document states current facts; rewrite a wrong sentence in place
+
+- **Why:** a confidently stale document causes a wrong decision; git already keeps the old text.
+- **Enforced by:** review only.
+- **Example:** a claim that turns out wrong is rewritten to the current fact, with no "correction" note and no dated
+  "measured on" trail. A finished plan or handoff is deleted. A done backlog or cleanup line is deleted.
+- **Exceptions:** `CHANGELOG.md` is the one place with version history.
+- **Applies to:** all CLIs, user and developer pages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-4 · A generated page is never edited by hand
+
+- **Why:** the next generation overwrites a hand edit, and the page then disagrees with the program until it does.
+- **Enforced by:** `cli-memo: pnpm generate:check` · `drive-cli: pnpm generate:check` ·
+  `zoom-cli: pnpm generate:check` · `tg-cli: ci.yml:ci` · `max-cli: ci.yml:ci` · `whatsapp-cli: ci.yml:ci`.
+- **Example:** `docs/commands.md` comes from the program. Change the command's help text, then run `pnpm generate`.
+- **Exceptions:** none. memo, drive and zoom check this with `pnpm generate:check`. tg, max and wa run the generator
+  and then `git diff --exit-code` in full validation.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-5 · Every relative link and anchor resolves
+
+- **Why:** a broken link sends the reader nowhere at the moment they need the next step.
+- **Enforced by:** `pnpm docs:check`.
+- **Example:** `cli-dev docs-check` fails on `[setup](usage.md#setup)` when `usage.md` has no "Setup" heading.
+- **Exceptions:** a link into a private checkout that CI does not have (for example `docs_ai/`) is skipped by the CLI's
+  rules module.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-6 · The `docs/` folder matches `docs/meta.json` and has the shared page set
+
+- **Why:** every tool has the same pages at the same addresses, so a reader who knows one tool knows them all.
+- **Enforced by:** `max-cli: pnpm docs:check` · `whatsapp-cli: pnpm docs:check` · `tg-cli: pnpm docs:check`.
+- **Example:** `docs/meta.json` lists every page once, in sidebar order. The folder has `index`, `installation`,
+  `usage`, `commands`, `configuration`, `troubleshooting` and `security`. Each page has exactly one `#` heading.
+- **Exceptions:** `changelog` in `meta.json` comes from the root `CHANGELOG.md`. `cli-dev docs-check --pages` checks
+  this. max and wa run it, and tg runs the same check in its own `scripts/docs-check.ts`. memo, drive and zoom do not
+  yet.
+- **Applies to:** every CLI in the docs portal. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-7 · `README.md` is the full introduction to the tool
+
+- **Why:** most readers open only the README; it must take them from "what is this" to a first result.
+- **Enforced by:** review only.
+- **Example:** follow max-cli's README order: quick start, what you can do, for AI agents, why this tool, the main
+  features, sign-in and profiles, settings and permissions, limits, security, when it does not work, documentation,
+  development.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-500.
+
+### WC-DOC-8 · A user guide follows the portal's authoring and terminology rules
+
+- **Why:** one vocabulary and one page shape across tools; the portal copies these pages as they are.
+- **Enforced by:** review only.
+- **Example:** a guide opens with when to use it and what result the reader gets, then the steps. It says "agent",
+  not "assistant" or "model". See cli-docs `AUTHORING.md` and `TERMINOLOGY.md`.
+- **Exceptions:** reference pages, such as the generated `commands.md`, follow their generator.
+- **Applies to:** every CLI in the docs portal. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-9 · A tool's security page links the shared page and keeps only what is its own
+
+- **Why:** shared behaviour written in each tool drifts; the reader needs only what differs for this tool.
+- **Enforced by:** review only.
+- **Example:** `docs/security.md` links the portal's shared security page, then states what this messenger stores and
+  sends.
+- **Exceptions:** none.
+- **Applies to:** every CLI in the docs portal. **Since:** cli-base 0.41.0. **Rulings:** NEED-556.
+
+### WC-DOC-10 · One fact has one home; every other document links to it
+
+- **Why:** two copies of a fact drift, and the reader cannot tell which one is current.
+- **Enforced by:** review only.
+- **Example:** a rule lives on its handbook page; a repository's `CLAUDE.md` links the page instead of restating the
+  rule. A task lives in the backlog; a plan links it.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-11 · A developer page anchors each claim and says how it was verified
+
+- **Why:** a claim with no source cannot be checked when the code or the service changes.
+- **Enforced by:** review only.
+- **Example:** cite `src/store/open.ts:42` for our code, a URL for anything outside, a commit for history. Write "ran
+  X, saw Y" for what you ran, and "the docs describe X" for what you only read. Say at the top what is not verified.
+- **Exceptions:** user pages state behaviour and do not carry code anchors.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-12 · A runnable command in a document has no placeholder in it
+
+- **Why:** a placeholder such as `<your-chat-id>` gets pasted as it is and runs against the wrong thing.
+- **Enforced by:** review only.
+- **Example:** paste a real value from a real run, or an obviously synthetic one that is labelled as such. Ask for a
+  value in a plain sentence before the command.
+- **Exceptions:** syntax lines in a reference page, which are not meant to be run.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-13 · Each file is in one language, and each repository has a fixed document language
+
+- **Why:** a reader and the spell checker both handle one language per file.
+- **Enforced by:** review only.
+- **Example:** English everywhere, except max-cli: its user pages, its changelog and its new documents are Russian.
+  A section added to an existing file follows that file's language.
+- **Exceptions:** command names, option names and quoted output stay as the program prints them.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-14 · `CHANGELOG.md` has one section per version, newest first, under a pending section
+
+- **Why:** the GitHub release and the release scripts read the changelog by its headings.
+- **Enforced by:** `pnpm docs:check` · `changelog-guard.yml`.
+- **Example:** `## Unreleased` at the top while work is merged; a release dates it as `## 0.41.0 — 17.10.2026`. Each
+  version heading and the pending heading appear once.
+- **Exceptions:** max-cli names the pending section `## Не выпущено`.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-15 · Changelog entries go under five fixed headings, each at most once per section
+
+- **Why:** one heading set lets a reader, an agent and one guard read every repository the same way.
+- **Enforced by:** `pnpm docs:check` · `changelog-guard.yml`.
+- **Example:** `### Added`, `### Changed — may break callers`, `### Fixed`, `### Security`, `### Removed`. max-cli
+  uses this fixed Russian rendering: `Что нового`, `Изменено — может сломать скрипты`, `Исправлено`, `Безопасность`,
+  `Удалено`.
+- **Exceptions:** none. tg-cli and whatsapp-cli still check `What's new` and `Changed — may break scripts`, and memo
+  and drive have used `Changed` and `Documentation`. They move to this set.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-16 · A change a caller may notice goes under "Changed — may break callers"
+
+- **Why:** this heading is what a reader scans before an upgrade.
+- **Enforced by:** review only.
+- **Example:** a changed output field, exit code, option, permission or config key, or a changed exported signature
+  in a shared library. The entry says what each caller has to do.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-17 · Each entry says what changed for the caller, why, and what to watch for
+
+- **Why:** a line that only names the change leaves the reader unable to decide whether it touches them.
+- **Enforced by:** review only.
+- **Example:** "**`chats list` sorts by the last message.** It sorted by name before. A script that needs the old
+  order passes `--sort name`." The bold lead is a whole sentence. No file paths or internal names a caller cannot
+  see; link the page that describes it.
+- **Exceptions:** "why" is left out when it is obvious, such as a new command.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-18 · The changelog has no internal ids
+
+- **Why:** a journal, backlog or ruling id means nothing to a reader outside the project.
+- **Enforced by:** `pnpm docs:check`.
+- **Example:** `cli-dev docs-check` fails on `NEED-12` or `TASK-3` anywhere in `CHANGELOG.md`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-19 · A pull request with a breaking title adds an entry to the pending section
+
+- **Why:** a breaking change with no changelog line reaches callers with no warning.
+- **Enforced by:** `changelog-guard.yml`.
+- **Example:** a title `feat(store)!: …` fails the guard unless the pull request adds a line under `## Unreleased`.
+- **Exceptions:** none.
+- **Applies to:** every repository that calls the changelog guard. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-DOC-20 · A released section is frozen, and a new entry goes under an existing heading
+
+- **Why:** a release's notes must match what shipped, and one section with two `### Fixed` headings reads as two
+  lists.
+- **Enforced by:** `changelog-guard.yml`.
+- **Example:** the guard fails a change to a section whose `v<version>` tag exists, unless the change restores the
+  exact text in that tag. It also fails a new repeated `###` heading in any section that has no tag yet.
+- **Exceptions:** a dated section with no tag is still open to fixes; a release is tagged only after npm has it.
+- **Applies to:** every repository that calls the changelog guard. **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-base `CONVENTIONS.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/CONVENTIONS.md)
+- [max-cli `CONVENTIONS.md`](https://github.com/WireCatLabs/max-cli/blob/main/docs/dev/CONVENTIONS.md), sections
+  "Documents" and "The changelog"
+- [cli-docs `STRUCTURE.md`](https://github.com/WireCatLabs/cli-docs/blob/main/docs/STRUCTURE.md),
+  [`AUTHORING.md`](https://github.com/WireCatLabs/cli-docs/blob/main/docs/AUTHORING.md),
+  [`TERMINOLOGY.md`](https://github.com/WireCatLabs/cli-docs/blob/main/docs/TERMINOLOGY.md) and
+  [`REVIEWING.md`](https://github.com/WireCatLabs/cli-docs/blob/main/docs/REVIEWING.md). These stay the contract
+  of the docs portal. This page links them and does not repeat them.

package/docs/standards/layout.md

@@ -0,0 +1,128 @@
+# Layout
+
+## Scope
+
+Where things live in a CLI repository: the folders, the entry points, what the package exports, how large a file may
+grow, one job per file, and how a large unit is split.
+
+Rule ids on this page are `WC-LAY-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). Which layer may import which, and what goes in cli-base, cli-core or the CLI, is on the
+[Architecture page](architecture.md). The hard file size cap is a lint rule on the [Toolchain page](toolchain.md).
+
+## Rules
+
+### WC-LAY-1 · Use the shared top-level layout
+
+- **Why:** an agent that knows one WireCat CLI finds its way in the next one without a map.
+- **Enforced by:** review only.
+- **Example:** a CLI repository has these at its root:
+  - `src/`: all code, tests beside it;
+  - `bin/`: the repository's own scripts, such as `bin/release` and a wrapper that runs the local build;
+  - `scripts/`: development scripts in TypeScript or JavaScript;
+  - `docs/`: user pages; `docs/dev/`: developer pages;
+  - `lint/`: `baseline/` and `overrides.json` for the command lint;
+  - `contracts/`: the offline contract plan and its snapshots;
+  - `config/wirecat/`: the shared presets;
+  - `skills/`: the agent skill the package ships;
+  - `CHANGELOG.md`, `CLAUDE.md`, `CLEANUP.md`, `SECURITY.md`, `README.md`, `LICENSE`.
+- **Exceptions:** a folder the CLI has no use for may be missing; memo has no `contracts/` yet. A product folder may
+  be added, such as `spec/` for a protocol or API description.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-2 · Start the command from `src/bin/<command>.ts`, and keep that file thin
+
+- **Why:** the start file runs before any error handling exists, so every line in it is a line that can crash without
+  a useful message.
+- **Enforced by:** review only.
+- **Example:** `src/bin/max.ts` is built to `dist/bin/max.js`, which `package.json` names in `"bin"`. It sets up
+  crash handling and a quiet exit on a closed pipe, then imports `../program.js` and sets `process.exitCode` to the
+  result of `run(argv)`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-3 · Export `createProgram` from `src/program.ts`
+
+- **Why:** the test matrix, the reference page and the tests build the command tree from this one function, without
+  a process.
+- **Enforced by:** review only.
+- **Example:** `cli-dev test-matrix --program dist/program.js` loads `createProgram` from the built file. Tests call
+  `run()` from the same module.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-4 · Put test-only helpers outside the published folder
+
+- **Why:** everything under `src/` of a library is compiled into `dist/` and published, so a test helper there ships
+  to every user.
+- **Enforced by:** review only.
+- **Example:** cli-base keeps its test sandbox in `test/sandbox.ts`, not in `src/`. A helper that callers also use in
+  their own tests is a public entry point instead, such as `@wirecat/cli-base/testing`.
+- **Exceptions:** a CLI's colocated `*.test.ts` files stay in `src/`, because its `tsconfig.json` excludes them from
+  the build.
+- **Applies to:** cli-base, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-5 · Add an entry point as an `exports` entry built from `src/<name>/index.ts`
+
+- **Why:** a caller can import only what `exports` names, so each entry point is a public promise that needs its own
+  door.
+- **Enforced by:** review only.
+- **Example:** `"./query": { "types": "./dist/query/index.d.ts", "default": "./dist/query/index.js" }`, built from
+  `src/query/index.ts`. The same pull request adds a line to `scripts/smoke.ts` that loads it under Bun.
+- **Exceptions:** a CLI that is used only as a command has no `exports`, or only `"."`.
+- **Applies to:** cli-base, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-6 · Keep generated code in a `generated/` folder, and commit it
+
+- **Why:** a reader and the lint must tell generated code from written code, and a stale generated file must show as
+  a diff.
+- **Enforced by:** review only.
+- **Example:** max keeps its generated protocol wrappers in `src/generated/`. Full validation runs `pnpm generate`
+  and then `git diff --exit-code`. The size cap and the secret lint skip `**/generated/**` by path.
+- **Exceptions:** a single generated file may use a `.generated.ts` suffix, such as cli-core's
+  `migrations.generated.ts`, and is then excluded from Biome by name.
+- **Applies to:** all CLIs and libraries that generate code. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-7 · Treat 300 and 500 lines as review signals
+
+- **Why:** size is a sign of mixed jobs, not a proof, so it starts a review question instead of failing a build.
+- **Enforced by:** review only.
+- **Example:** at about 300 lines of handwritten production code, look for jobs that can be separated. Above 500,
+  split them, or say in the pull request why keeping them together is clearer. The hard cap of 1,000 lines is
+  [WC-TOOL-13](toolchain.md#wc-tool-13--cap-every-file-at-1000-lines-with-biome).
+- **Exceptions:** generated code, declarative registries and cohesive test scenarios get their own judgment. Do not
+  meet the number with a new barrel file, an operation scattered into trivial files or a class around each function.
+- **Applies to:** all CLIs and libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-8 · Give each module one reason to change
+
+- **Why:** a module that mixes a domain rule, a use case and a transport mapping changes for three reasons, and
+  every change risks the other two.
+- **Enforced by:** review only.
+- **Example:** split when unrelated policies, different effects or separate consumers collect in one file. Keep
+  validation, orchestration and output mapping apart when each has real logic. Do not write a catch-all `utils`
+  module, a boolean flag that selects unrelated workflows, or a command handler that also holds SQL. Split a large
+  unit along a named seam, and dispatch by lookup, not by a branch per case:
+  - the tg adapter is a thin class over feature modules (folders, topics, groups, contacts, login, watch) that share a
+    small feature context;
+  - the cli-core store is a set of areas, each in its own file ([Store](store.md));
+  - the Lucene compiler has one compiler per field, picked from the field registry by name.
+- **Exceptions:** do not scatter one operation into trivial files, add a barrel or wrap each function in a class only
+  to meet a size limit.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-LAY-9 · Do not add a new job to a large file because it is already there
+
+- **Why:** an existing large file is not evidence that a mixed responsibility belongs in it.
+- **Enforced by:** review only.
+- **Example:** extract the part a change needs when that makes its boundary clearer, keep its behaviour with focused
+  tests, and record other structural debt in the backlog instead of fixing it in the same pull request.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and libraries. **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-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)