diff --git a/README.md b/README.md
index 48dd3e901..34117d2f6 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,58 @@
-
+
# @wirecat/cli-core
-The engine behind the WireCat command-line tools for Telegram, MAX, WhatsApp, mail, notes, meetings and Google
-Drive. Everything that
-does not depend on one messenger lives here: the data model, a local SQLite store with full-text and semantic
-search, a Lucene query language, the shared commands, an MCP server for AI agents, and the guard around every
-write. A messenger plugs in as one adapter and gets all of it.
+Build a CLI that lets people and AI agents search a messenger, a mailbox or any service with a history, in
+TypeScript on Node or Bun. You write the adapter that talks to the service, and cli-core gives it a local store with
+search, the shared commands and an MCP server.
+
+```ts
+import { type Messenger, mcpCommand, messagesCommand, run, searchCommand, settingsFor } from "@wirecat/cli-core/cli"
+import { acmeAdapter } from "./adapter.js" // your code: the only part that speaks to Acme Chat
+
+const app = { command: "acme", appName: "acme-cli", envPrefix: "ACME", description: "Acme Chat", version: "0.1.0" }
+const settings = settingsFor(app)
+
+const acme: Messenger = {
+ app,
+ provider: "acme",
+ resolveSettings: settings.resolveSettings,
+ connect: async () => acmeAdapter(),
+ chatArgument: "a chat: its name or its Acme id",
+}
+
+process.exitCode = await run(process.argv.slice(2), {
+ app,
+ configuration: settings,
+ commands: () => [messagesCommand(acme), searchCommand(acme), mcpCommand(acme)],
+})
+```
+
+```sh
+acme personal messages sync --all # every chat's history into the local store
+acme personal search messages come --json=excerpt # {"items":[{"excerpt":"are you coming?",…}],…}
+acme personal mcp check # {"item":{"healthy":true,…,"tools":3,…},…}
+```
+
+That output is real, from this program with the in-memory `fakeAdapter` of `@wirecat/cli-core/testing` in place of
+Acme. The search found "are you coming?" from the word "come", with no network.
+
+**Built on it:** [tg-cli](https://github.com/WireCatLabs/tg-cli), [max-cli](https://github.com/WireCatLabs/max-cli),
+[gcal-cli](https://github.com/WireCatLabs/gcal-cli) and 12 more WireCat CLIs, such as the mail and notes tool
+[cli-memo](https://github.com/WireCatLabs/cli-memo), the [WhatsApp tool](https://github.com/WireCatLabs/whatsapp-cli),
+[zoom-cli](https://github.com/WireCatLabs/zoom-cli) and [drive-cli](https://github.com/WireCatLabs/drive-cli).
+
+## Install
+
+```sh
+npm install --save-exact @wirecat/cli-core
+```
+
+npm 7+ and pnpm also install its peers: `@wirecat/cli-base` in the range `package.json` names, and `commander` 15 or
+later. `@napi-rs/canvas` is optional, and charts need it only for PNG output. It runs on Node 22.16+ and 24+, and on
+Bun. Pin an exact version, because any release before 1.0 may break a caller ([Build on it](#build-on-it)).
[Architecture](docs/dev/ARCHITECTURE.md) · [Write an adapter](docs/dev/ADAPTERS.md) ·
[Query language](docs/search/query-language.md) · [Messenger rules](docs/dev/STANDARD.md) ·
@@ -20,57 +64,49 @@ write. A messenger plugs in as one adapter and gets all of it.
[](https://bun.sh/)
[](LICENSE)
-## Key documents
+## Which package to install
-| Document | What it answers |
-|---|---|
-| [Architecture](docs/dev/ARCHITECTURE.md) | The layers, the module map, the store internals and migrations, who consumes what |
-| [Document workflows](docs/dev/DOCUMENTS.md) | Shared file ingestion, sync, scoped knowledge and extraction; the ports a file provider supplies |
-| [Media archives](docs/dev/MEDIA-ARCHIVE.md) | Independent verified file copies, interruption recovery and opt-in daily timers |
-| [Write an adapter](docs/dev/ADAPTERS.md) | How to add a messenger: the port, the `Messenger` description, the contract cases |
-| [Messenger rules](docs/dev/STANDARD.md) | What binds tg, max and wa beyond the [CLI standards handbook](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/README.md): parity, the option catalogue, `bot` |
-| [Glossary](docs/dev/GLOSSARY.md) | One word, one meaning across the tools |
-| [Query language](docs/search/query-language.md) · [spec](docs/search/query-language-spec.md) · [Image search](docs/search/images.md) | The search syntax and its exact grammar; finding pictures by context and by what they show |
-| [Mentions](docs/mentions.md) · [how they work](docs/dev/MENTIONS.md) | Phones, e-mail, links, documents and names found in messages: search, review, rebuild; the tables and the rules |
-| [Storage](docs/storage/README.md) | The schema, the search indexes and the decisions behind them |
-| [Knowledge](docs/dev/KNOWLEDGE.md) · [Meetings](docs/dev/MEETINGS.md) | Labels, links and proposals across sources; the meetings module and its providers |
-| [Testing](docs/dev/TESTING.md) · [Parity audit](docs/dev/PARITY-AUDIT.md) | The sandbox, the coverage floor, the checks across tg and max |
-| [Tool boundaries](docs/dev/TOOL-BOUNDARIES.md) | Which tool owns which command |
-| [API reference](docs/REFERENCE.md) | Every entry point and the detailed contract of each feature |
-| [Roadmap](docs/roadmap.md) | What is being built next for developers on this package |
-| [Changelog](CHANGELOG.md) | What each version changed, and what may break callers |
-
-## What it is
-
-A messaging CLI has two halves. One speaks a protocol: MTProto for Telegram, a WebSocket for MAX, IMAP for mail.
-The other half is the same for every messenger: store what was read, search it, render it for a person and as JSON
-for a program, guard every send, expose it all to an agent. This package is the second half.
-
-[tg-cli](https://github.com/WireCatLabs/tg-cli), [max-cli](https://github.com/WireCatLabs/max-cli) and
-the [WhatsApp tool](https://github.com/WireCatLabs/whatsapp-cli) are built on it, and so are the mail and notes tool
-[cli-memo](https://github.com/WireCatLabs/cli-memo), [zoom-cli](https://github.com/WireCatLabs/zoom-cli) and
-[drive-cli](https://github.com/WireCatLabs/drive-cli). They import it as `@wirecat/cli-core`. Up to 0.261.0 the package
-was named `@wirecat/cli-messaging`, which is deprecated. The npm versions 0.0.0-stage, 0.0.0 and 0.18–0.20 of
-`@wirecat/cli-core` are deprecated too: they are placeholders and the old cli-base.
-
-**Who it is for.** First of all, it is the engine of the WireCat tools, and it changes as fast as they need. You can
-build your own messenger CLI on it, but expect to follow a moving API (see [Build on it](#build-on-it)).
-
-```sh
-npm install --save-exact @wirecat/cli-core
+```mermaid
+flowchart LR
+ cli["Your CLI"] -->|"keeps messages, mail or files to search"| core["@wirecat/cli-core"]
+ cli -->|"any other CLI"| base["@wirecat/cli-base"]
+ core --> base
+ base --> runtime["Node or Bun"]
```
-npm 7+ and pnpm also install its peers: `@wirecat/cli-base` in the range `package.json` names, and `commander` 15 or
-later. `@napi-rs/canvas` is optional; charts need it only for PNG output.
-
-It is built on [`@wirecat/cli-base`](https://github.com/WireCatLabs/cli-base), the layer every CLI needs: two output
-streams, closed error codes, the keyring, injectable clocks, the query parser. cli-base is a peer dependency, so an
-install holds one copy.
+cli-core is for a tool that keeps what it reads in a local store and searches it. It is built on
+[`@wirecat/cli-base`](https://github.com/WireCatLabs/cli-base), the layer every CLI needs: two output streams, closed
+error codes, the keyring, injectable clocks and the query parser. cli-base is a peer dependency, so an install holds
+one copy. A CLI with nothing to store needs only cli-base.
-It has 26 entry points (the `exports` of `package.json`), 27 search fields and 13 search presets.
-It runs on Node 22.16+ and 24+, and on Bun.
+## Features
-## Architecture
+- **Search that finds the message, not only the word.** One query language for every list and every source, a
+ TypeScript port of the Apache Lucene 9.12.3 parsers: phrases, `from:(alice OR bob)`, `date:[2026-01-01 TO
+ 2026-02-01}`, `size>10MB`. Word forms in Russian, English and Spanish (`встреча` finds `встречи`), any three letters
+ inside a word, and search by meaning when you opt in. A question over 100,341 synthetic messages took 54 ms at the
+ median ([measured](https://github.com/WireCatLabs/cli-testing/blob/main/performance/search/model-free/FRESH-VALIDATION.md#archive-size-latency-and-query-ram),
+ [every search measurement](https://github.com/WireCatLabs/cli-testing/tree/main/performance/search)).
+ [Syntax](docs/search/query-language.md) · [grammar](docs/search/query-language-spec.md) ·
+ [image search](docs/search/images.md)
+- **One store for every source.** Messages from Telegram and MAX, mail, notes and meeting transcripts sit side by side
+ in one SQLite file, `wirecat.db`, so one query searches all of them. Edits are kept as revisions and deletions as
+ tombstones. Migrations only move forward, and an older CLI keeps reading a file a newer one migrated.
+ [Storage](docs/storage/README.md) · [why SQLite FTS5 and no daemon](docs/storage/decisions.md)
+- **An MCP server that leaves room in the agent's context.** The shared commands reach an agent as 3 MCP tools: find a
+ command, run a read, run a write. It runs over stdio, or over HTTP on 127.0.0.1 behind the owner's tunnel with a
+ one-owner OAuth login.
+- **Every write behind a guard.** A permission level per command path (deny, readonly, ask or allow), a list of
+ allowed recipients, and at most 30 sends an hour by default. A write whose outcome is unknown is never retried, and
+ a retry under the same send id cannot send twice.
+- **Knowledge, tasks and meetings across sources.** What an agent proposes stays proposed until the owner accepts it.
+ Tasks have project keys like `RES-12`, and a meeting transcript is kept by revision.
+ [Knowledge](docs/dev/KNOWLEDGE.md) · [Meetings](docs/dev/MEETINGS.md) · [Mentions](docs/mentions.md)
+- **Files and voice as text.** Readers for PDF, Word, HTML and more, each loaded on first use, and speech recognition
+ on your computer from a pinned model catalogue. [Document workflows](docs/dev/DOCUMENTS.md) ·
+ [Media archives](docs/dev/MEDIA-ARCHIVE.md)
+
+## How it works
```mermaid
flowchart TB
@@ -90,152 +126,14 @@ Five layers, and each calls only the layers below it: domain, adapters behind a
- **The CLI and the MCP server are two adapters over the same services.** A command and its MCP tool answer with
the same data, because one service produces it.
-- **A port with one required core and optional groups.** `MessengerCore` is what every messenger must do. The other
- groups — server reads, polls, forums, reactions and the rest — are optional and reached through `capability()`.
- A messenger without a group refuses the command before connecting; it never crashes and never silently drops an
- option.
-- **Decorators, so no service can forget.** Every adapter is wrapped twice: `stored` saves what a read answered,
- and `observed` times each call for the run record.
-- **Override a use case, not a command.** A tool replaces one service through `Messenger.services`; every command
+- **A port with one required core and optional groups.** `MessengerCore` is what every messenger must do. Groups such
+ as polls or forums are optional and reached through `capability()`. A messenger without a group refuses the command
+ before it connects. It never crashes and never drops an option in silence.
+- **Override a use case, not a command.** A tool replaces one service through `Messenger.services`, and every command
and tool that uses it follows.
-- **Tasks and meetings know nothing of SQLite.** They define their own ports (`TaskStore`, `MeetingStore`), and the
- store implements them.
-
-**The build enforces these boundaries.** Biome import rules refuse, under `src/`:
-
-- any messenger library or adapter — this package speaks no provider;
-- `commander` or a command file in services, sends or MCP;
-- the SQLite table modules anywhere outside the store's own interface;
-- any import from the rest of the package inside tasks and meetings, and any file system or SQLite there.
-
-Tests guard the rest. Migrations must be numbered without gaps and may not rebuild a table. The schema spec, the
-code and its document must agree. A search plan that reads an index once per message fails the build.
-
-## Features
-
-### Search that finds it
-
-- **One query language for every list and every source.** A TypeScript port of the Apache Lucene 9.12.3 parsers,
- with no runtime parser dependency. Phrases, `AND` / `OR` / `NOT`, `+required`, grouping, field groups like
- `from:(alice OR bob)`, ranges `date:[2026-01-01 TO 2026-02-01}`, comparisons `size>10MB`, wildcards and regular
- expressions. 27 fields: sender, chat, date, file name, MIME type, transcript, subject, label and more.
- Proximity `"invoice paid"~3` finds the words close together in one message; the fuzzy operator `word~1` is
- refused with an error that names the alternative.
- [Syntax](docs/search/query-language.md) · [grammar](docs/search/query-language-spec.md)
-- **Any three letters inside a word.** An FTS5 trigram index finds `port` inside `report`. A
- second, word index ranks by BM25.
-- **Word forms in three languages.** Snowball 3.1.1 stemmers for Russian, English and Spanish: `встреча` finds
- `встречи`. Exact forms rank first; `exact:` turns stemming off.
-- **Safe regular expressions.** A Thompson NFA without backtracking, with budgets for states and work, so no
- pattern can hang the search.
-- **Presets for what people actually look for.** `preset:password`, `api-key`, `card`, `phone`, `email`, `url` and
- seven more find candidates, labelled as candidates.
-- **Search by meaning, opt in.** Conversations are split into chunks and embedded locally by ONNX Runtime — native
- on Linux (glibc), Apple-silicon Macs and Windows once `models download` has fetched it, WebAssembly elsewhere, on
- Node and Bun alike — EmbeddingGemma by default (e5-small to choose), or any OpenAI-compatible API with your own key, after
- you see the cost. Results by meaning and by words are merged by reciprocal rank fusion.
-- **The archive and the server together.** `--backend both` also asks the messenger's own search; its hits are saved
- and filtered by the same query, so nothing is counted twice. `--thread` brings the reply thread around a hit.
-- **Bounded by design.** Query size, depth, nodes, pattern length, expansions and run time all have limits.
-
-Measured on synthetic data ([methodology and results](https://github.com/WireCatLabs/cli-testing/tree/main/performance/search)):
-
-| Stored messages | Search p50 / p95 |
-|---|---|
-| 10,341 | 9.0 / 22.6 ms |
-| 100,341 | 53.9 / 107.6 ms |
-
-### One local store for every source
-
-- **One file, every messenger and account:** `wirecat.db` in `~/.local/share/WireCat/` (`%LOCALAPPDATA%\WireCat\Data\`
- on Windows). Messages from Telegram and MAX, mail, notes and meeting transcripts sit side by side, so one query
- searches all of them.
-- **`node:sqlite` under Node and `bun:sqlite` under Bun,** behind a small seam. WAL and a busy timeout on both.
-- **History you can trust.** Edits are kept as revisions and deletions as tombstones. Every sender is an identity
- with a person of their own, so one person across two messengers can be linked.
-- **Migrations an older build survives.** Forward-only, additive and frozen once released. `min_compatible` lets an
- older CLI keep using a file a newer one migrated, and refuses a file it cannot read.
-- **Built for the long run.** History download is resumable and respects the messenger's rate limits; it can run in
- the background as a job. `store check`, `backup` and `restore` look after the file itself.
-
-[Storage](docs/storage/README.md) · [why SQLite FTS5 and no daemon](docs/storage/decisions.md)
-
-### A full CLI and an MCP server from one adapter
-
-Describe a messenger once — its name, how to connect, how `me` maps to a chat — and the tool gets about sixty
-shared commands: chats, contacts, messages, search, reactions, polls, the inbox of unread messages, `watch` for live
-updates, history download, the store, run records, configuration, shell completion, `doctor`, and `commands --json`,
-the whole command tree as data for an agent.
-
-The same commands become MCP tools for agents without a terminal. The server offers three tools — find a command,
-run a read, run a write — so an agent's context does not fill with a hundred tool schemas. It runs over stdio, or
-over HTTP on 127.0.0.1 behind the owner's tunnel, with a one-owner OAuth login.
-
-`serve` keeps the store current, one process per profile by a lock file; `server install` adds a systemd user unit
-or a launchd agent that starts at every login.
-
-### Every write behind a guard
-
-- **A permission level per command path:** deny, readonly, ask or allow. The most specific key wins, and a built-in
- default can only tighten what the owner set. No level lets an agent delete for everyone.
-- **A recipient list and an hourly limit** for sends, and a journal of every attempt that records the length of the
- text, never the text. Each photo or file of an album counts as one send.
-- **A send id across retries.** A write whose outcome is unknown is never retried automatically; a retry under the
- same send id cannot send twice.
-- **Deletion asks first,** at most ten messages at a time.
-- **MCP writes follow the same profile permissions.** An agent sees only the tools the profile allows.
-
-### Knowledge, tasks and meetings
-
-- **Labels, links and facts across sources,** always scoped to an explicit account. What an agent adds stays
- *proposed* until the owner accepts it, with a fingerprint so a stale review cannot overwrite a newer change.
-- **A shared vocabulary.** Before a new tag is created, similar existing tags and aliases are offered for review.
-- **Tasks** with project keys (`RES-12`), dependencies and a readiness check.
-- **Meetings:** a WebVTT parser, a `MeetingSource` port a provider implements, transcripts kept by revision, and
- references to one cue of one transcript.
-
-### Files, voice and charts
-
-- **Readers for PDF, Word, ODF, HTML and more,** each library loaded on first use.
-- **Local speech recognition** from a pinned model catalogue; importing it loads no engine and downloads nothing.
-- **Charts from statistics** as JSON, SVG or PNG, with a replaceable renderer loaded only when an image is asked for.
-
-## Engineering standards
-
-The [WireCat CLI standards handbook](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/README.md) in cli-base binds every WireCat CLI; the
-[messenger rules](docs/dev/STANDARD.md) add what binds tg, max and wa. They measure themselves against POSIX, GNU,
-[Command Line Interface Guidelines](https://clig.dev), the MCP specification and JSON Schema 2020-12, and say where
-they deliberately differ. A rule changes in its own pull request, before the code that needs it.
-
-- **stdout carries data, stderr carries diagnostics,** in every mode. `--json` prints one object; `--jsonl` one per
- line; `--json=id,text` only those fields.
-- **Stable exit codes** a script can branch on: 2 validation, 3 config, 4 auth, 5 permission, 6 not found,
- 8 rate limited, 9 timeout, 14 outcome unknown, and the rest. An error is one JSON object with a stable `code` and
- `reason` — callers never parse the message.
-- **Built for agents.** `--no-input` never prompts. Input and output are bounded (16 MiB in, 4 MiB out) and fail
- visibly instead of truncating. One-shot commands time out after 30 seconds and close what they hold. `--dry-run`
- previews any write.
-- **The tool never picks an account.** Every account command names its profile — the first word in tg, max and
- wa, an option such as `--account` or `--profile` in the others; without one, the command stops and lists the
- choices — even when there is only one.
-- **Run records keep the command as typed, never a secret.** Every run is kept, with one line per request it made,
- so `runs show` can explain it: successes for 7 days, failures for 30, within a size limit. A token, a password or
- a phone number is hidden; `record_input: false` leaves the typed words out, `"failed"` keeps them only for a
- failure, and `record: false` keeps failures only.
-- **Tests that cannot touch real data.** A sandbox keeps every test away from the owner's store, and no test may
- sleep. A coverage floor: 92% of lines, and at least half of every file.
-- **Contract cases for every adapter.** `contractCases` turns the port's promises into cases any test runner can run,
- over an in-memory fake or a real client.
-- **Checked across tools and runtimes.** CI runs on Linux: the test suite on Node 24, smoke checks on Bun and on
- Node 22.16, a parity workflow that builds the Telegram, MAX and WhatsApp CLIs against this repository, and
- gitleaks over the full history. macOS and Windows run only four workflows: the SQLite library build (macOS) and
- the ONNX runtime probe (macOS and Windows) run monthly and when started by hand; the native-runtime check (Linux,
- macOS and Windows, x64 and arm64, and Alpine) runs monthly and on every pull request that changes how models
- load; the scheduler test (macOS and Windows) runs only when started by hand. The rest of the suite does not run on
- macOS or Windows.
-- **One shared toolchain.** Biome, markdownlint, CSpell and Lefthook configs come from the
- [WireCat standards](https://github.com/WireCatLabs/community/blob/main/standards/README.md), and CI fails when a
- copy drifts.
+- **The build keeps the lines.** Biome import rules refuse any messenger library under `src/`, `commander` in a
+ service, and the SQLite tables outside the store. Tests refuse a gap in the migration numbers and a search plan that
+ reads an index once per message.
## Build on it
@@ -243,8 +141,8 @@ A new messenger is three pieces: an adapter that implements `MessengerCore` (and
`Messenger` that describes it, and the contract cases run against it. The
[adapter guide](docs/dev/ADAPTERS.md) walks through each one.
-This runs as it is under vitest. `fakeAdapter` is the in-memory adapter the kit ships; put your own adapter there,
-built over a fake client filled from `seed`. The `./testing` kit is not stable yet.
+This runs as it is under vitest and gives 29 cases. `fakeAdapter` is the in-memory adapter the kit ships. Put your own
+adapter there, built over a fake client filled from `seed`. The `./testing` kit is not stable yet.
```ts
import { contractCases, digitIds, fakeAdapter } from "@wirecat/cli-core/testing"
@@ -259,15 +157,30 @@ describe("the adapter keeps the port's promises", () => {
})
```
-**Before 1.0, any release may break a caller.** Releases are frequent, sometimes several a day, and any of them
-may change any entry point. Every such change is listed in the [changelog](CHANGELOG.md) under "Changed — may break
-callers", with what to change. tg-cli and max-cli pin an exact version and move to a new one in their own pull request.
-Pin an exact version too.
+**Before 1.0, any release may break a caller.** Releases are frequent, sometimes several a day, and any of them may
+change any entry point. The [changelog](CHANGELOG.md) lists every such change in its own section, with what to change.
+tg-cli and max-cli pin an exact version and move to a new one in their own pull request. Pin an exact version too.
The full list of entry points and what each holds is in the [API reference](docs/REFERENCE.md).
⚠ **Errors are recognised by shape, not by class** (`isCliFailure`). A package linked during development brings its
own copy of cli-base, and an error built by one copy is not an `instanceof` the other's class.
+## Engineering standards
+
+The [WireCat CLI standards handbook](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/README.md) in
+cli-base binds every WireCat CLI, and the [messenger rules](docs/dev/STANDARD.md) add what binds tg, max and wa. They
+measure themselves against POSIX, GNU, [Command Line Interface Guidelines](https://clig.dev), the MCP specification
+and JSON Schema 2020-12, and say where they differ on purpose.
+
+- **Tests that cannot touch real data.** A sandbox keeps every test away from the owner's store, and no test may
+ sleep. The coverage floor is 92% of lines, and at least half of every file.
+- **Checked against the tools that use it.** Every pull request builds tg-cli, max-cli, whatsapp-cli and
+ cli-template against the branch. Which checks run on macOS and Windows is in
+ [Testing](docs/dev/TESTING.md#platforms).
+- **One shared toolchain.** Biome, markdownlint, CSpell and Lefthook configs come from the
+ [WireCat standards](https://github.com/WireCatLabs/community/blob/main/standards/README.md), and CI fails when a
+ copy drifts.
+
## Development
```sh
@@ -276,9 +189,34 @@ pnpm lint && pnpm typecheck && pnpm test
pnpm smoke:bun # the same exports, run under Bun
```
-Releases go through `bin/release` from `main`: it refuses a dirty tree, runs every check, publishes to npm and tags
+Releases go through `bin/release` from `main`. It refuses a dirty tree, runs every check, publishes to npm and tags
`v`. The steps and the release rules are in [RELEASING.md](docs/dev/RELEASING.md).
+## Key documents
+
+| Document | What it answers |
+|---|---|
+| [Architecture](docs/dev/ARCHITECTURE.md) | The layers, the module map, the store internals and migrations, who consumes what |
+| [Document workflows](docs/dev/DOCUMENTS.md) | Shared file ingestion, sync, scoped knowledge and extraction, and the ports a file provider supplies |
+| [Media archives](docs/dev/MEDIA-ARCHIVE.md) | Independent verified file copies, interruption recovery and opt-in daily timers |
+| [Write an adapter](docs/dev/ADAPTERS.md) | How to add a messenger: the port, the `Messenger` description, the contract cases |
+| [Messenger rules](docs/dev/STANDARD.md) | What binds tg, max and wa beyond the [CLI standards handbook](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/README.md): parity, the option catalogue, `bot` |
+| [Glossary](docs/dev/GLOSSARY.md) | One word, one meaning across the tools |
+| [Query language](docs/search/query-language.md) · [spec](docs/search/query-language-spec.md) · [Image search](docs/search/images.md) | The search syntax and its exact grammar, and finding pictures by context and by what they show |
+| [Mentions](docs/mentions.md) · [how they work](docs/dev/MENTIONS.md) | Phones, e-mail, links, documents and names found in messages: search, review, rebuild, the tables and the rules |
+| [Storage](docs/storage/README.md) | The schema, the search indexes and the decisions behind them |
+| [Knowledge](docs/dev/KNOWLEDGE.md) · [Meetings](docs/dev/MEETINGS.md) | Labels, links and proposals across sources, the meetings module and its providers |
+| [Testing](docs/dev/TESTING.md) · [Parity audit](docs/dev/PARITY-AUDIT.md) | The sandbox, the coverage floor, the checks across tg and max |
+| [Tool boundaries](docs/dev/TOOL-BOUNDARIES.md) | Which tool owns which command |
+| [API reference](docs/REFERENCE.md) | Every entry point and the detailed contract of each feature |
+| [Roadmap](docs/roadmap.md) | What is being built next for developers on this package |
+| [Changelog](CHANGELOG.md) | What each version changed, and what may break callers |
+
+## History
+
+Up to 0.261.0 the package was named `@wirecat/cli-messaging`, which is deprecated. The npm versions 0.0.0-stage, 0.0.0
+and 0.18 to 0.20 of `@wirecat/cli-core` are deprecated too: they are placeholders and the old cli-base.
+
## Licence
[Apache License 2.0](LICENSE).
diff --git a/cspell.json b/cspell.json
index 3e5011d3c..3040d81d7 100644
--- a/cspell.json
+++ b/cspell.json
@@ -2,5 +2,5 @@
"version": "0.2",
"files": ["README.md"],
"import": ["./config/wirecat/cspell.json"],
- "words": ["CLIG", "resvg", "zrender"]
+ "words": ["CLIG", "gcal", "resvg", "whatsapp", "zrender"]
}
diff --git a/docs/dev/TESTING.md b/docs/dev/TESTING.md
index cc4fa8031..fdb3a4a8c 100644
--- a/docs/dev/TESTING.md
+++ b/docs/dev/TESTING.md
@@ -161,3 +161,12 @@ fixture checks saving/deleting/restoring thread counts, read/star changes and no
account isolation. It refuses an existing database path. This protects the Node22 SQLite binding
boundary that a Node 24-only mail suite cannot establish. Use a new temporary path when running it
locally; no owner store or credentials are needed.
+
+## Platforms
+
+CI runs on Linux: the test suite on Node 24, smoke checks on Bun and on Node 22.16, a parity workflow that builds the
+Telegram, MAX and WhatsApp CLIs against this repository, and gitleaks over the full history. macOS and Windows run
+only four workflows. The SQLite library build (macOS) and the ONNX runtime probe (macOS and Windows) run monthly and
+when started by hand. The native-runtime check (Linux, macOS and Windows, x64 and arm64, and Alpine) runs monthly and
+on every pull request that changes how models load. The scheduler test (macOS and Windows) runs only when started by
+hand. The rest of the suite does not run on macOS or Windows.
diff --git a/docs/images/cli-core-banner.png b/docs/images/cli-core-banner.png
index 8efcb3780..1df69b623 100644
Binary files a/docs/images/cli-core-banner.png and b/docs/images/cli-core-banner.png differ
diff --git a/docs/images/src/banner.html b/docs/images/src/banner.html
new file mode 100644
index 000000000..c1e19556d
--- /dev/null
+++ b/docs/images/src/banner.html
@@ -0,0 +1,30 @@
+
+
+
+
+cli-core banner
+
+
+
+
+ cli-core
+ Messages and mail your agent can search
+ Write one adapter, get a local store and an MCP server
+
+
+
diff --git a/docs/images/src/render.ts b/docs/images/src/render.ts
new file mode 100644
index 000000000..9c6762b83
--- /dev/null
+++ b/docs/images/src/render.ts
@@ -0,0 +1,28 @@
+// Renders banner.html to the README banner. Run from anywhere: node docs/images/src/render.ts
+import { spawnSync } from "node:child_process"
+import { mkdtempSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const CHROME = process.env.CHROME ?? "/usr/bin/google-chrome"
+const SOURCE = fileURLToPath(new URL("banner.html", import.meta.url))
+const OUTPUT = fileURLToPath(new URL("../cli-core-banner.png", import.meta.url))
+
+// A throwaway profile, so the render never opens the owner's Chrome profile.
+const profile = mkdtempSync(join(tmpdir(), "banner-chrome-"))
+const result = spawnSync(
+ CHROME,
+ [
+ "--headless",
+ "--disable-gpu",
+ "--hide-scrollbars",
+ "--force-device-scale-factor=1",
+ "--window-size=1280,640",
+ `--user-data-dir=${profile}`,
+ `--screenshot=${OUTPUT}`,
+ pathToFileURL(SOURCE).href,
+ ],
+ { stdio: "inherit" },
+)
+process.exitCode = result.status ?? 1
diff --git a/package.json b/package.json
index 3f61f8f1c..ecdb37860 100644
--- a/package.json
+++ b/package.json
@@ -239,6 +239,7 @@
"search:docs": "pnpm build && node scripts/search-docs.ts",
"check:agent-process": "pnpm build && node --experimental-strip-types scripts/check-agent-process.ts",
"standards:check": "node config/wirecat/check.mjs",
+ "docs:images": "node docs/images/src/render.ts",
"docs:lint": "markdownlint-cli2",
"docs:spell": "cspell lint --config cspell.json --no-progress README.md",
"ci:quick": "pnpm typecheck && vitest run src/cli/command-lint.test.ts",