@wirecat/cli-core 0.263.0 → 0.265.0

package/README.md

@@ -4,391 +4,240 @@
 
 # @wirecat/cli-core
 
-The messenger-neutral half of a messaging command line tool, shared by
-[`tg-cli`](https://github.com/WireCatLabs/tg-cli) and [`max-cli`](https://github.com/WireCatLabs/max-cli).
-Built on [`@wirecat/cli-base`](https://github.com/WireCatLabs/cli-base), a peer dependency: the CLI installs
-it itself, so the install holds one copy.
-
-**Status: on npm** — what each version changed is in [CHANGELOG.md](CHANGELOG.md). The domain model, message locators, message rendering, name
-resolution, the SQLite seam that runs under Node and Bun, and the first part of the command
-skeleton with the shared read commands, the send guard, run records and the message store — see
-[the platform proposal](docs/dev/BACKLOG.md).
-
-## Retained meeting references
-
-`parseMeetingReference`, `formatMeetingReference` and `canonicalMeetingReference` name local meeting
-records as `meeting:<accountId>/<meetingId>`, a retained transcript revision with `/<transcriptId>`,
-and one cue with `/<cuePosition>`. IDs are positive safe integers; cue positions start at zero.
-These references stay within one store and retain the exact revision after a correction.
-They use a dedicated parser; the general `parseReference` and existing knowledge targets do not
-accept them yet. A reader must verify the caller's authorized account before returning content.
-
-## Canonical project and label vocabulary
-
-`store.knowledge.vocabulary({ kind?, scope?, maxEntries?, maxReadBytes?, signal? })` lists live owner
-projects and tags/topics with stable IDs, aliases, usage counts and a preview fingerprint.
-`resolveVocabulary(name, options)` matches only explicit aliases, canonical names or project keys;
-several matches remain ambiguous. Unicode normalization preserves accents and distinct letters.
-Person/contact aliases are independent and retain their existing behavior.
-
-`addVocabularyAlias({ kind, id }, name, { expectedFingerprint?, by?, signal? })` and
-`removeVocabularyAlias(target, aliasId, options)` are owner writes with transactional collision and
-stale-preview checks. Creating a project cannot shadow an existing project alias. Knowledge labels,
-main-topic selection and label filters resolve an exact tag/topic alias to its canonical name.
-
-`tagPreflight(name, { kind?, maxEntries?, maxReadBytes?, signal? })` returns `reuse`, `create` or
-`review`, with lexical candidates and a vocabulary fingerprint. Its separate `creationFingerprint`
-binds owner approval to the requested name, kind and current label/alias metadata. Similarity suggests
-review; it never selects a synonym, changes a tag or loads a model.
-
-Every native new-label path checks tags, topics and their aliases before insertion, including implicit
-knowledge labels, note-file imports and automatic chat tagging. A lexical score of at least 0.65
-refuses creation with `tag_review_required` and up to ten candidates. The whole enclosing write rolls
-back. Existing exact names and explicit aliases still reuse their canonical label.
-
-Reuse an existing label or add an owner-reviewed alias when the names mean the same thing. For a
-purposefully distinct label, call `createTag(name, { kind?, expectedCreationFingerprint })` with the
-current preflight receipt. This owner-only acceptance is checked under the write lock and refuses
-stale or differently targeted receipts. There is no force bypass. The creation check bounds input to
-5,000 labels, 100,000 aliases and 4 MiB of names, and fails before hydration if those limits are exceeded.
-`auditVocabulary({ kind?, scope?, minSimilarity?, maxComparisons?, limit?, maxEntries?, maxReadBytes?, signal? })`
-reports pairs of distinct canonical records with lexical similarity. It compares projects with projects,
-and tags/topics with labels, including explicit aliases. Defaults are similarity 0.65, 10,000 name
-comparisons and 20 pairs; maximums are 100,000 comparisons and 200 pairs. `complete: false` means a
-budget stopped the scan, not that remaining names are unique. The fingerprint identifies the reviewed
-catalog. Names in output are capped at 300 characters with an explicit truncation flag. This read does
-not accept a synonym, mutate tags or load a model. Semantic detection and reviewed merges remain separate work.
-
-## Meeting-project membership
-
-`store.knowledge.linkMeetingProject(account, meetingId, projectId, options)` records one `member-of`
-link in the shared relationship table. Meetings are checked against the explicit provider/account;
-projects must be live owner projects. `by: "agent"` creates a proposed link; it cannot confirm one.
-An owner accepts a proposal by passing its `expectedFingerprint`, preserving its recorded provenance.
-Replaying an existing link returns `changed: false`; stale review fails before writing.
-
-`meetingProjects(account, { meetingId?, projectId?, confirmed?, limit?, offset?, signal? })` lists
-membership in that account, with canonical references and fingerprints. Reads take at most 500 rows
-and 2000 provenance characters per row; deleted/foreign meetings and deleted/account projects are
-excluded. Title/alias similarity never creates membership. These are shared store APIs; a command
-surface and project-selected transcript retrieval are separate consumer work.
-
-## Project task keys and dependencies
-
-New owner projects receive a 3–4-character uppercase key, or take an explicit key of that shape.
-Existing keys stay stable. Task creation allocates `<project key>-<number>` inside a write transaction;
-a failed creation rolls back the counter. No project or task is renumbered.
-
-`store.tasks.linkTask(from, to, kind, "owner")` and `unlinkTask` manage `blocked-by`, `follow-up-of`
-and `related-to`. `RES-2 blocked-by RES-1` means RES-1 must finish first. Informational follow-up and
-related links do not affect readiness; related pairs are symmetric. Cycles and self-links fail before
-writing, replays return `changed: false`, and actual changes append linked/unlinked task events.
-Agents propose changes for owner review. Targets must be live tasks in owner projects; inbox tasks
-need their separate account-scoped service. Parent hierarchy remains a separate field.
-
-`taskRelations(id)`, `taskReadiness(id)` and `readyTasks(project, { limit? })` read bounded coherent
-snapshots. Only a done blocker is resolved: dismissed/deleted blockers continue to require review.
-Ready reads are discovery, not a work claim or exclusive lock. SQLite write transactions serialize
-counter/dependency mutations; expiring agent leases and command mounting are subsequent work.
-
-## The rule this package keeps
-
-**Nothing here knows a messenger.** An adapter translates its provider's objects into these types,
-and a lint rule refuses any import of a messenger library or an adapter under `src/`. What only one
-provider has travels in `providerMetadata`.
-
-| | |
-|---|---|
-| `.` | `Chat`, `Message`, `Contact`, `Page`… · `formatLocator` / `parseLocator` · `renderMessages` · `pickChat` / `pickPerson` |
-| `./charts` | neutral chart data, a replaceable renderer interface and on-demand dark SVG and PNG images |
-| `./models` | `modelGateway`, provider-neutral requests, adapter-owned option checks, injected keys and purpose consent, and `modelTarget` for effective configuration; [provider settings](docs/search/ai-providers.md) |
-| `./store` | `openCache` — `node:sqlite` under Node, `bun:sqlite` under Bun, WAL and a busy timeout on both · `openStore` — the shared message store, every method async: one file for every messenger (`wirecat.db` in `~/.local/share/WireCat/`, `%LOCALAPPDATA%\WireCat\Data\` on Windows; `MESSAGING_STORE` overrides where), forward-only migrations with `min_compatible`, every sender an identity with a person of their own, edits kept as revisions, a message by its id, deletions kept as tombstones, trigram search · `find` — by text, by sender, or both; `together` for the chats where every sender wrote, `perChat` to cap each chat · `savePeople` and `people` — usernames and bot flags, and a `PeopleLookup` for `pickPerson` |
-| `./sends` | the send guard: a level per command path (`permissions`: deny, readonly, ask, allow — `readOnly` and `allow` read as levels), a recipient list, an hourly limit, and a journal of every attempt that never holds the text; `newSendId` for a send's identity across retries |
-| `./cli` | the command skeleton: `run` (never throws, returns an exit code), the global flags, `settingsFor` (flag → environment → file → default, one strict file schema with each CLI's own fields), the profile as the first word, `--timeout` that closes what a command holds, paging, and run records: `--record` keeps a run's ids and timings (never content), a failure is kept unless `--no-record`, and `runsCommand` gives `runs list\|show\|path` · `configCommand(app, config)` shows and changes the settings with where each came from, and `config migrate --dry-run` previews translation of legacy access settings before `config migrate` saves it; `migratePermissionConfig` provides the same layer-preserving transformation to consumers · `completeCommand(messenger, config, options?)` gives shell completion, account-scoped chat and person ids from the store and never a connection; `options.sources` can supply local suggestions for a separate command group and `options.account` can read an existing local account binding · `storeSummary(env)` gives its local store diagnostics to consumers retaining their own doctor command · `doctorCommand(messenger)` reports the installation's state from disk (the store, the account, sends, runs, the messenger's own checks), and connects only with `--online`; `doctor report create` writes that, the failed run and the recent sends to a file with every id a label · `skillCommand(app, url)` prints the CLI's own SKILL.md for an agent (`skill show`) · `commandsCommand(app)` describes every command as JSON, with `contract` (`CONTRACT`, the major version of the output types) and which commands write · the shared read commands: a CLI describes its messenger once (`Messenger`: its app, a `connect` that returns a `MessengerAdapter`, how `me` maps to a chat) and gets `accountCommand`, `chatsCommand` (`list`, `show`), `contactsCommand` (`list`, `show`) `recipientsCommand`, `sendsCommand`, `watchCommand` (new messages as they arrive, `--jsonl`, until Ctrl-C or `--timeout`; `--events` adds edits, deletions and reactions, each kept in the store), `storeCommand` (the local store: `messages sync` (mounted under `messages`) puts a chat's history into it, resumable, FloodWait-aware, `--since` to stop at a time, `--background` for a detached job that `store jobs list|show|cancel` follow, `--estimate` to only price what is left from the store alone; `store status` what it holds; `store export` a chat's messages out of it, as JSON or `--format markdown`; `store clear --left` deletes the chats the account has left; `store info`, `store check`, `store migrate`, `store backup` and `store restore` look after the file itself — its size and schema, whether it is healthy and which chats are behind, bringing it up to this build, and a copy to go back to), `inboxCommand` (other people's unread messages in every chat, or with `--new` what arrived since the last check — each message once, the point moved only by a run that printed; copied from max-cli), `serveCommand` (keeps the store current until stopped — one per profile by a lock file, catch-up on, started by a person, `server start` or a unit), `serverCommand` (`server start|stop|restart|status|logs`: `serve` in the background, as max-cli's `server`; `install|uninstall` add a systemd user unit or a launchd agent per profile, and `install` starts nothing), and `messagesCommand` (`list`, `show`, `context`, `search` over the store by any three letters inside a word, or `--regex`, `send` through the send guard (`--reply-to`, `--silent`, `--no-preview`, `--md`, `--file` and `--photo` with the text as the caption, and `--at` to send later, with `scheduled` listing the queue), `edit` of the owner's own message, `forward` to another chat and `pin`/`unpin` through it too (the adapter's optional `edit`, `forward`, `pin` and `unpin`), and `delete` — at most 10, for the owner unless `--for-everyone`; it asks first by default, and `--allow-dangerous` is the yes · `reactionsCommand` (`add`, `remove`: the owner's reaction on a message, through the guard; the adapter's optional `react`) · `pollsCommand` (`show` a poll with its answer ids, `vote` by id or `--retract`, `close` the owner's own, `create` one — a vote guarded as a reaction, closing as an edit, a new poll as a message with a send id); a `msg:` locator names a message) — every read saved to the store, `--offline` answered from it, each call a run event · `mcpCommand(messenger)` serves the profile to an agent over MCP on stdin and stdout (copied from max-cli: one connection held for minutes, one call at a time, read tools named `<cli>_<command words>` answering what `--json` prints, `<cli>_status` without connecting; the write tools — `<cli>_messages_send`, `_edit`, `_forward`, `_pin`, `_unpin`, `_delete`, `<cli>_reactions_add`, `_remove`, `<cli>_chats_mark_read`, `<cli>_polls_vote`, `_close` and `_create` — are offered by the profile's `permissions` and run through the same guard as their commands; a write at level `ask` follows the host approval boundary and profile permissions without a form; retired confirmation flags only warn, and `messages_delete` never deletes for everyone), and `mcp config` prints the entry for a desktop client · `mcp --http` serves the same tools over HTTP on 127.0.0.1 behind the owner's tunnel with a one-owner login; a CLI with its own MCP server mounts `serveOverHttp(build, options)` with `httpServerOptions(mode)`, `httpTokenFile` and `revokeAll` (`OVER_HTTP` follows the same profile permission policy) |
-| `./testing` | the adapter kit — **not stable yet**, so it may change in any release: `fakeAdapter(seed)`, a messenger in memory with every method group, for command tests; `contractCases({ connect })`, the port's promises as cases any test runner runs over an adapter; `contractSeed`, the chats and messages they read. How to write an adapter and run them: [the adapter guide](docs/dev/ADAPTERS.md) |
-| `./tasks`, `./tasks/testing` | what waits on the owner: the task model, `TaskStore` and the service over it; the testing entry adds a memory store. Was `@wirecat/cli-tasks` |
-| `./meetings` (`/cli`, `/mcp`, `/testing`) | events and meetings: the model, the WebVTT parser, the `MeetingSource` port a provider implements, `MeetingStore`, pull and import, the meeting commands and MCP reads; the testing entry adds a memory store, a fake source and the contract cases. Was `@wirecat/cli-meetings` — see [Meetings](docs/dev/MEETINGS.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.
-
-Field selection uses cli-base's `fieldsOf` and `projectFields`; list envelopes and operation IDs
-stay intact. Direct empty field lists keep only operation metadata, preserving the existing helper
-contract. Direct invalid or unsafe paths are rejected before projection. cli-base 0.19.2 or newer
-within the 0.19 series is required.
-
-`searchAllIncludingMeetings` from `./services` adds one selected meeting account to the existing
-message, mail and notes search. It leaves `searchAll` and its item references unchanged. The CLI
-reaches it with `search all <query> --source zoom:<account>` (or `zoom`, `meetings`, `all`) and MCP with
-`search_all`'s `source`; a bare word takes the one account that holds meetings and refuses when several do.
-Choose another meeting account explicitly:
+The engine behind the WireCat command-line tools for Telegram, MAX, mail, notes and meetings. 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.
 
-```ts
-const found = await searchAllIncludingMeetings(store, account, {
-  text: "project AND plan",
-  limit: 20,
-  meetingAccount: { provider: "zoom", account: "zm-profile:example" },
-  maxMeetings: 100,
-})
-```
+[Architecture](docs/dev/ARCHITECTURE.md) · [Write an adapter](docs/dev/ADAPTERS.md) ·
+[Query language](docs/search/query-language.md) · [CLI standard](docs/dev/STANDARD.md) ·
+[API reference](docs/REFERENCE.md) · [Changelog](CHANGELOG.md) · [wirecat.dev](https://wirecat.dev)
 
-Meeting hits have `kind: "meeting"`, `accountId`, `meetingId`, `scope`, `id` and `startMs`, with no
-canonical `ref`. They contain text previews of at most 2000 characters; their meeting timestamp can
-be null. The existing unified ranking and the meeting list are blended by reciprocal rank. Meeting
-order follows newest meeting first, then stored hit order; it does not claim a relevance score.
-
-Meetings support letter/digit words joined by AND, including adjacent words, as word prefixes.
-Exact forms, phrases, OR/NOT, patterns and field/date filters skip only meetings with a reason.
-The meeting account defaults to `account` and is looked up without registration. Search reads
-current transcripts, chat and summaries and excludes deleted meetings.
-
-`maxMeetings` limits visited candidate meetings (1–1000, default 100), while `limit` bounds returned
-items (1–1000). The store can allocate many hit rows within one candidate meeting; this service
-cannot promise a hard query memory bound. `hasMore: null` means the scan stopped before proving
-whether another match exists. `meetings.complete` describes the selected source's scan, and
-`meetings.nextCursor` resumes with `only: ["meetings"]`, the same query and the same account. It
-retains unreturned hits even when another resource filled the result limit. This is a meeting source
-continuation, not a global cursor or a snapshot; changing archive contents can require restarting.
-
-
-A **message locator** names one message across every provider and account:
-`msg:telegram/<account>/<chat>/<message>`. A message id alone does not — Telegram numbers messages
-per chat in channels and per account in private chats.
-
-Forum addressing is an optional adapter capability: `messages send --topic` and `polls create --topic`
-pass `threadId` through the shared service/guard. `validateThread` checks the topic and any reply
-before sending, after the permission gate. Telegram group forums support it; MAX refuses it.
-Journal records carry only the thread id. A retry keeps the same send id, chat and topic; scheduled
-sends must be checked in the queue instead of repeated.
-
-Consumers retaining their own personal MCP session can import `personalMcpTools`,
-`registerPersonalMcpTools`, `personalMcpConfirmer` and the `PersonalMcpRegistration` types from
-`./cli`. Filter unsupported provider capabilities before mounting. The host supplies its held
-session, account-scoped store, defaults and permission scope (`around`); `withServices` and
-`resolveChat` bind its service overrides and confirmation titles. Session callbacks receive a
-`release` function for local inference. The host closes `warmEmbedders()` on shutdown. The same
-strict catalogue is mounted by the built-in server; unknown arguments fail before execution.
-
-## Media options
-
-`messages send --spoiler` hides a photo or video until tapped, and `--caption-above` shows the text above the
-attachment (send tool: `spoiler`, `caption_above`). A messenger offers them through `Messenger.mediaOptions`;
-where it is unset the service refuses them before connecting, so an adapter that does not know an option never
-receives one to drop. Both need an attachment. Per-message forward protection is left out: Telegram grants it
-to bots only, and a personal account protects a whole chat instead.
-
-## Sender identities
-
-`chats send-as <chat>` lists who the account may post as in a chat: `{ id, title, kind, premiumRequired,
-default }`, `kind` being `self`, `channel` or `group`. The personal identity is always in the list, and
-`default` marks the chat's saved choice. Reading it changes nothing — the saved choice stays as it is.
-`messages send`, `messages forward` and `polls create` take `--send-as <id>` (their tools `send_as`): the
-service lists the identities of the chat the message lands in, in the same connection, and refuses an id
-that is not there. An adapter without the optional `sendAsIdentities` refuses the option — it is never
-dropped, and never falls back to the personal identity. Without `--send-as`, a chat whose saved sender is not
-the account (the adapter's `savedSender`, say a group that posts as a linked channel) is refused before
-sending: the messenger would post as that sender, and nothing typed said so. The refusal names both ids. The journal records the identity, and a retry of an
-unknown send under the same send id must name the same identity.
-
-## Message permalinks
-
-The personal `messages link <chat> <message>` command also accepts a `msg:` locator.
-Its read-only MCP tool and CLI call the same service and return `{ locator, url, access, reason }`.
-Adapters can implement optional `permalink` to return HTTPS links; its result contains no message
-content. Link audience is `public`, `restricted` or `unknown`; a URL grants no membership.
-Without support, a validated target returns `url: null`, `access: unavailable`, and a reason.
-Offline validates this account's stored message and returns reason `offline`, without connecting.
-A locator for another messenger or account is refused. Singular `link` differs from graph `links`.
-
-## Command discovery
-
-The [CLI standard](docs/dev/STANDARD.md#external-references-and-our-adoption-profile) explains
-which POSIX, GNU, CLIG and agent-facing conventions we adopt. The [architecture](docs/dev/ARCHITECTURE.md#cli-design-references)
-shows where their contracts live; the [compliance audit](docs/dev/CLI-COMPLIANCE.md) records
-remaining gaps and deliberate differences.
-
-To discover arguments without reading the whole command tree, run
-`<cli> commands messages evidence --json`. Replace the path with any command or group;
-`<cli> commands messages --json` includes its descendants. The response retains global options
-and exit codes, includes options inherited from ancestor groups, and resolves command aliases.
-Give one command path per call; inspect other groups in separate calls.
-`<cli> commands --json` still returns the full tree.
-
-## Evidence packets for agents
-
-`prepareEvidencePacket` from `@wirecat/cli-core/services` packages a message page that the
-caller has already read and authorised. It works with any messenger's domain messages:
+[![npm](https://img.shields.io/npm/v/@wirecat/cli-core)](https://www.npmjs.com/package/@wirecat/cli-core)
+[![CI](https://github.com/WireCatLabs/cli-core/actions/workflows/ci.yml/badge.svg)](https://github.com/WireCatLabs/cli-core/actions/workflows/ci.yml)
+[![Node](https://img.shields.io/node/v/@wirecat/cli-core)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/bun-tested-f9f1e1)](https://bun.sh/)
+[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
 
-```ts
-import { prepareEvidencePacket } from "@wirecat/cli-core/services"
+## Key documents
 
-const packet = prepareEvidencePacket({
-  kind: "chats", // or "news" or "person"
-  source: { provider, account, chat: chatId },
-  page,
-  limits: { messages: 100, bytes: 64 * 1024 },
-})
+| Document | What it answers |
+|---|---|
+| [Architecture](docs/dev/ARCHITECTURE.md) | The layers, the module map, the store internals and migrations, who consumes what |
+| [Write an adapter](docs/dev/ADAPTERS.md) | How to add a messenger: the port, the `Messenger` description, the contract cases |
+| [CLI standard](docs/dev/STANDARD.md) | The rules every WireCat CLI follows: command shape, output, exit codes, permissions, MCP |
+| [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) | The search syntax and its exact grammar |
+| [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 |
+| [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) and [max-cli](https://github.com/WireCatLabs/max-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). Until
+they move to the new name, they import it as `@wirecat/cli-messaging`: that was this package's name up to 0.261.0.
+
+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.
+
+In numbers, on `main`: 608 source files and 344 test files, 23 entry points, 27 search fields, 13 search presets.
+It runs on Node 22.16+ and 24+, and on Bun.
+
+## Architecture
+
+```mermaid
+flowchart TB
+  tools["tg · max · memo · zm · drive"] --> interface
+  subgraph core ["@wirecat/cli-core"]
+    interface["Interface: CLI commands and MCP tools"] --> services["Services: one use case each"]
+    services --> ports["Ports: MessengerAdapter · MeetingSource · TaskStore"]
+    services --> store[("Store: one SQLite file, wirecat.db")]
+    ports --> domain["Domain types"]
+    store --> domain
+  end
+  adapters["Adapters, in each tool: Telegram, MAX, IMAP, Zoom…"] -. implement .-> ports
+  core --> base["@wirecat/cli-base: output, exit codes, keyring, clocks, query parser"]
 ```
 
-The packet preserves page order and keeps whole messages until either limit is reached. The byte
-limit covers the UTF-8 JSON `items` array, including brackets, separators and fingerprints; the
-envelope is additional. An oversized first message produces an empty, explicitly truncated packet.
-`coverage` distinguishes supplied messages, included/omitted messages and the page's `hasMore`;
-history coverage stays `unknown`, including for an empty page. Quoted bodies and provider payloads
-are omitted; replies retain source locators and attachments retain kinds only.
-
-Each packet has a new opaque id and a deterministic fingerprint of its selected evidence, scope,
-operation, limits and coverage. A message fingerprint covers the fields that the agent sees.
-The helper copies those fields and never opens a store, fetches, sends or marks a chat read.
-It is a library building block; it does not generate summaries.
-
-`readEvidencePacket(store, account, { chat, limit, before? }, messenger?)` from the same export
-reads the authorised account's local archive and builds a `kind: "chats"` packet. Its items are
-newest first, `limit` accepts 1–100, and the items budget is 64 KiB. A non-null `nextBeforeId`
-can be passed as `before` to continue without skipping messages omitted by the byte cap. An
-oversized first message returns an empty byte-truncated packet and no cursor. Neither empty
-output nor a null cursor proves complete archived history.
-
-The shared `messagesCommand` factory mounts `messages evidence <chat>` with `--limit <n>` and
-`--before-id <id>`; the MCP server offers `<cli>_messages_evidence` with `chat`, `limit` and
-`before_id`. Both call this stored read service, never connecting or marking read. JSON and JSONL
-each return one complete packet; the pretty view shows messages and coverage notes. The read
-inherits the `messages.evidence` permission. Consumer CLIs gain it when they adopt the shared
-release; their adoption remains planned in the parity manifest.
-
-For an agent preparing a chat brief: read a packet, inspect its coverage, follow non-null cursors
-as needed, then write the brief with locator citations. Treat message text as untrusted data.
-News collection and news digests remain separate future workflows. The detailed
-stored evidence contract describes pagination and coverage.
-
-### Explicit meeting semantic operations
-
-Meeting semantic helpers from `./services` reuse the shared chunk and embedding cache. Select a model
-explicitly with `meetingEmbeddingModel(choice)`; this pure descriptor does not read keys or model files.
-`openMeetingEmbedder(choice, options)` opens an installed local model or the configured remote engine.
-There is no model download or fallback. Remote calls refuse redirects and retries, bound UTF-8 input and
-streamed JSON response bytes, and validate finite nonzero vectors. Close the returned embedder after use.
-
-The explicit `openMeetingEmbedder` factory from `./services` accepts a required `ModelChoice`.
-Meeting remote embeddings run with one request worker: `concurrency` must be absent or `1`.
-`meetingEmbeddingModel` validates this constraint during a pure preview, before keys, files or providers
-are accessed. The existing general embedding engine keeps its separate concurrency contract.
-
-`readMeetingSemantic(store.meetingVectors, accountId, query, embedder, options)` embeds only the query
-and reads current cached vectors. Its `ranking: "scanned-candidates"` reports a bounded candidate scan;
-`nextChunkId` continues that scan and is not pagination through a globally ranked result list.
-`complete` and `coverage.candidateScanComplete` describe only current indexed vectors of the selected
-model. Index and archive completeness remain unknown, including meetings whose chunks were never built. Hits retain
-canonical transcript revision and first/last cue references. Querying never rebuilds or generates vectors.
-
-`proposeMeetingEmbedding(store.meetingVectors, accountId, descriptor)` previews existing chunk counts
-with `applied: false`. To generate explicitly, first call the bounded `meetingVectors.rebuild`, then
-`applyMeetingEmbedding` for one capped missing-hash batch. Text, chunk and vector payload budgets are
-separate. The native atomic save rechecks live account ownership after model inference and skips newly
-superseded or deleted sources. An acknowledged commit remains acknowledged if cancellation follows it.
-These helpers neither download models nor add tasks, memories or messages.
-
-
-### Stored meeting evidence
-
-The read-only meeting helpers from `./services` let an agent cite an exact retained transcript
-revision. The caller supplies the authorized numeric account ID; a foreign account reference is
-rejected before reading the meeting. Meeting-only references select current revisions that are still available.
-An explicit revision or cue keeps its historical text and reports `current` or `superseded`.
+Five layers, and each calls only the layers below it: domain, adapters behind a port, ports, services, interface.
+
+- **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. Seventeen
+  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
+  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. Fuzzy
+  and proximity operators are 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 a WebAssembly ONNX
+  runtime, the same on Node and Bun — e5-small by default, 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.
+
+### 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.
+- **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 [CLI standard](docs/dev/STANDARD.md) binds every WireCat CLI. It measures itself against POSIX, GNU, [Command Line Interface Guidelines](https://clig.dev),
+the MCP specification and JSON Schema 2020-12, and says where it deliberately differs. 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.** The profile is the first word of every account command; without one, the
+  command stops and lists the choices — even when there is only one.
+- **Run records keep ids and timings, never content.** A failure is kept by default, so `runs show` can explain it
+  without anyone sending a log full of messages.
+- **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 Node 24 and on Bun; a parity workflow
+  builds tg-cli and max-cli against this repository; macOS and Windows run on a schedule; gitleaks scans the full
+  history.
+- **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.
+
+## Build on it
+
+A new messenger is three pieces: an adapter that implements `MessengerCore` (and any optional groups), a
+`Messenger` that describes it, and the contract cases run against it. The
+[adapter guide](docs/dev/ADAPTERS.md) walks through each one.
 
 ```ts
-import { readMeetingEvidence, resolveMeetingReference, proposeMeetingTask } from "@wirecat/cli-core/services"
-
-// Invented local records; the caller must authorize account 1 first.
-const evidence = await readMeetingEvidence(store.meetings, 1, "meeting:1/2", { cues: 100, bytes: 65536 })
-const cue = await resolveMeetingReference(store.meetings, 1, "meeting:1/2/3/0")
-const proposal = await proposeMeetingTask(store.meetings, 1, "meeting:1/2/3/0", "promise")
+import { contractCases, digitIds } from "@wirecat/cli-core/testing"
+import { describe, it } from "vitest"
+
+describe("the adapter keeps the port's promises", () => {
+  for (const one of contractCases({ connect: (seed) => adapterOver(fakeClient(seed)), ids: digitIds }))
+    it(one.name, async (context) => {
+      const result = await one.run()
+      if (result) context.skip(result.skipped)
+    })
+})
 ```
 
-Evidence keeps whole cues within its UTF-8 JSON `items` budget; envelope fields are additional.
-Defaults are 100 cues and 64 KiB, with maxima of 1000 cues and 4 MiB. An oversized first cue returns
-an empty byte-truncated packet. Cue fingerprints stay stable when their revision is superseded.
-`coverage.input` is `bounded-meeting-pages`: these helpers require the native bounded meeting read
-capabilities and never materialize complete meeting history. `maxReadBytes` caps stored TEXT per SQL
-page (4 MiB by default), separately from the output JSON budget. A read visits at most
-`maxTranscriptPages` revisions (100 by default, at most 1000). Capped coverage reports observed cues;
-`providedExact` is false and `omitted` is null when further rows or revisions remain. Continue with
-`after: coverage.nextReference`, or `afterTranscriptId: coverage.nextTranscriptId` when empty revisions
-reach the revision-work cap. The cursor belongs to the same authorized source. Individual SQL reads
-have snapshots; the service does not claim one snapshot across pages. Archive completeness remains unknown.
-
-`personMeetingContext(store, "person:1", { accountIds: [1] })` reads linked meeting
-participation for explicitly authorized accounts. A native account-presence check runs before the global
-person lookup; a person seen only by other accounts returns `not_found` without exposing their name.
-The allowed accounts are snapshotted before asynchronous reads. It returns current meeting context, without
-claiming that the person spoke every returned cue. Defaults are 10 meetings, 5 cues per meeting,
-64 KiB for the JSON `items` array, and a scan of at most 1000 mixed involvement rows. Coverage
-reports the scan cap, queued changes and skipped unavailable meetings; it never claims complete history or matches people by
-name or email. The helper does not rebuild the derived index.
-
-A task proposal has a stable source-and-kind ID and `applied: false`; it creates no task or message.
-The separate `createTaskFromMeeting(store, accountKey, { source, kind, origin, dueAt? })` helper
-explicitly writes one local task after looking up the existing account and authorizing its source.
-It accepts the task package's kinds and origins, keeps canonical references, and reuses an existing
-task of the same kind; `rule` origin reuses any task from that source, including a closed task.
-Deduplication follows the task package's sequential find-and-add contract; concurrent writers need
-additional coordination. Proposal generation never calls this helper.
-
-`readMeetingTask(store, accountKey, id)` resolves source text on demand, with a preview of at most
-200 text characters. A deleted source returns `state: "unavailable"` and `source: null`; other source
-errors propagate. The task itself retains its reference rather than transcript text.
-
-Canonical meeting, revision and cue references can also be stored in memory and fact evidence
-and in note links. Cue references use the actual cue position, and keep pointing to their retained
-revision after a correction. Deleted parents refuse new links; existing evidence retains its source
-reference so callers can report that it is unavailable.
-
-`store.meetingVectors` shares the existing text chunks and model/content-hash embedding cache.
-Explicit `rebuild({ accountId })` creates bindings for current live transcripts; `chunksToEmbed(model,
-{ accountId, limit })` reads missing texts, and `saveCurrent(model, dims, rows, { accountId })`
-rechecks their current account ownership atomically before caching model results. It acknowledges
-saved and skipped hashes and never replaces an existing vector. No operation chooses a model,
-downloads one or calls a provider.
-Rebuild retires inactive transcript bindings and their orphaned model vectors atomically, while
-preserving every hash still used by another corpus or live meeting binding.
-
-Vector operations default to a 4 MiB aggregate text budget and 10,000 rows per transcript, with
-explicit maxima of 64 MiB and 100,000 rows. Oversized rebuilds roll back the complete batch.
-`nearest(model, query, { accountId, limit, maxChunks? })` defaults to scanning at most 1000 chunks
-and ranks only those candidates. Its `ranking: "scanned-candidates"`, `scanned`, `complete`,
-`hasMore` and `nextChunkId` fields distinguish a complete scan from continuation; continuation
-pages do not promise a global ranking. Vector writes and scans additionally cap payloads at 16 MiB.
-
-These helpers add no CLI or MCP command. Persisting meeting references through existing memory
-or fact evidence links needs separate store integration.
-
-## Charts from statistics
-
-`statsCommand(messenger)` from `./cli` mounts `stats charts <chat>`. It returns `{ chart }`:
-messages per day/week, active authors, or joins and leaves (`--chart-kind`). `--output activity.svg`
-or `--output activity.png` also saves a dark image in a new private file and returns `chartFile`. The command reads the same
-statistics service; the chart itself never fetches extra history, sends or marks read. Missing dates
-are gaps, and partial data is labelled. `--jsonl` and image output to stdout are unavailable.
-
-The read-only MCP `stats_charts` returns the same chart JSON from the store, without writing a file
-or connecting. Optional `format: "png"` returns PNG image content and JSON text containing
-`chart` and `image: { format, width, height }`; the default remains JSON. Membership is unavailable in that stored mode because it needs online events.
-Both interfaces inherit the `messages` read permission.
-
-`./charts` exports the library-neutral `ChartData`, `ChartRenderer`, `chatChart`, `CHART_SIZE`
-and the lazy `chartRenderer()` loader, plus the separate `chartPng(svg)` encoder. ECharts types stay in the renderer module; JSON-only commands
-do not load it. PNG lazily loads resvg-js 2.6.2 and uses bundled Noto Sans Regular (SIL OFL 1.1),
-with system fonts disabled. SVG does not load resvg. Pass a renderer loader as the second argument to `statsCommand` to replace the image implementation
-while keeping the neutral data and command contract. Images default to a dark theme. ECharts is pinned at 6.1.0; its published unpacked files
-plus zrender and tslib total about 61.6 MiB before package-manager deduplication.
-
-## Where it came from
-
-The files were copied from max-cli at `3ca8874`, from the part its lint rule `CLI-30` already kept
-free of MAX. What changed on the way is listed as `DEBT-1`…`DEBT-10` in the proposal.
-
-## Checks
+**Seven entry points are stable:** `.`, `./cli`, `./store`, `./sends`, `./speech`, `./services` and `./background`.
+A change that breaks them waits for a breaking release — at most one a week — whose changelog says what to change.
+Everything else may change in any release and is still listed under "Changed — may break callers". 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.
+
+## Development
 
 ```sh
 pnpm install
@@ -396,118 +245,9 @@ pnpm lint && pnpm typecheck && pnpm test
 pnpm smoke:bun    # the same exports, run under Bun
 ```
 
-## Releasing
-
-Raise `version` in `package.json` through a pull request, merge it, then on `main`:
-
-```sh
-bin/release --local   # from this machine: NPM_TOKEN if exported, else the keyring (service npm, account leemour)
-bin/release           # from GitHub Actions, once npm trusts .github/workflows/release.yml
-```
-
-Both refuse a dirty tree, a branch other than `main` and an unpushed `main`. When npm already has the
-version, or a higher one, they raise it to the next free version through a pull request — the next
-minor for `x.y.0`, the next patch otherwise — merge it once its checks pass, and publish that. They run every check, and tag `v<version>` once npm
-shows it. The token is never printed and never
-written to a file.
-
-The GitHub form publishes from the job in the `npm` environment, which is what
-npm's trusted publisher names: `WireCatLabs` / `cli-core` / `release.yml` / environment `npm`.
-
-### How often, and what may break
-
-**Release when a consumer needs it.** Changes wait under `## Unreleased` until then; there is no
-gap to keep between releases — tg-cli and max-cli pace their own.
-
-**These exports are stable.** A change that breaks them waits for a **breaking release**, at most one
-a week, whose changelog section says what to change in a consumer; tg-cli and max-cli move to it
-the same day.
-
-| Export | Stable |
-|---|---|
-| `.` | the domain types (`Chat`, `Message`, `Contact`, `Page`, …), the message locator |
-| `./cli` | `Messenger`, `MessengerAdapter` and its method groups (`MessengerCore` required; `ServerReads` and the rest optional), `createProgram`, `run`, `messengerContext`, the command factories' names and arguments |
-| `./store` | `openStore`, `MessageStore`, `storePath`, and the file format: `minCompatible` rises only in a breaking release |
-| `./sends` | `sendGuard`, `SendJournal`, the journal's line format |
-| `./speech` | The pinned speech-model catalogue, shared directories, verified installer and installed-only bounded PCM recognizer. Importing it does not load a recognizer or download a model |
-| `./services` | `servicesFor`, `Override` and the service names |
-| `./background` | `lockPath`, `readLock`, `holdLock`, `releaseLock`, `servingProfiles`, `alive`, `carries`, `holdersOf`, `ServerSystem`, `thisMachine`, `platformFor` and the systemd and launchd units |
-
-`./testing` and `./parity` are not on this list. Everything else may change in any release, and still goes under "Changed — may break callers" when
-it does. tg-cli and max-cli take new versions through Dependabot pull requests.
+Releases go through `bin/release` from `main`: it refuses a dirty tree, runs every check, publishes to npm and tags
+`v<version>`. The steps and the release rules are in [RELEASING.md](docs/dev/RELEASING.md).
 
 ## Licence
 
 [Apache License 2.0](LICENSE).
-
-Forum configuration uses the shared topics service: explicit enable/upgrade and named creation,
-with staged guards, original/result chat ids and unknown-outcome handling. Adapters opt into the
-forum capabilities; sending and creating a topic never implicitly convert a group. Enabling defaults
-to confirmation; topic creation preserves a caller's send id. Local history remains under its
-original peer id after migration.
-
-Markdown conversion belongs to each messenger adapter through optional `formatMarkdown`.
-Shared personal and bot send/edit use its neutral `FormattedText`/`TextSpan` result; they do not
-choose a dialect. New adapters must implement the capability to support `--md`. The legacy
-`parseMarkdown` export and `markup` port argument remain available for existing callers.
-
-## MCP from browser clients
-
-Writes over MCP show no form, over stdio or HTTP: the profile's permissions decide, and a level of
-`ask` goes ahead, since nobody is at a terminal to answer it. An app's own permission prompt is
-separate and cannot be verified by the server; its “always allow” setting may permit later calls
-without another prompt.
-
-Repeat `--permission key=level` to override profile permissions only for the server process.
-For example, `--permission messages.send=allow` enables sending even in a read-only profile.
-A broader key overrides saved descendant keys; built-in defaults still tighten broader grants.
-Recipient restrictions and hourly limits remain in effect; no saved configuration is changed.
-
-The browser connector uses the tunnel's HTTPS URL ending in `/mcp`, with the owner OAuth login.
-Both legacy session-based and modern HTTP MCP clients are supported. Web clients can use tools
-without prompts or resources; neither is required for reading and sending.
-
-Message and author rankings are mounted by `statsCommand`: see the [ranking guide](docs/rankings.md)
-for metrics, scores, saved selections, evidence paging and data-quality limits.
-
-### Private contact metadata and automatic tags
-
-Both messenger consumers can keep private contact aliases, scoped to one account, and multiple notes,
-which belong to the owner: a contact's notes show in every account that sees the contact.
-`contacts alias set <person> <alias>` and `contacts alias rm <person>` affect local display and
-resolution only. `contacts rename` continues to change the messenger address book. Show/list
-retain the messenger name; a local alias adds `alias` and `displayName`. Duplicate aliases require
-an explicit id. Stored direct-chat resolution supports aliases; it never invents a chat id from
-an identity id. `contacts show --with-notes` includes private notes explicitly; the notes read permission still applies. Local metadata survives profile refresh and stays on its original identity/account
-when identities are linked or unlinked.
-
-`contacts notes add <person> --file <path>` (or stdin) creates a stable note id. Use `list`,
-`show`, `edit --revision <number>` and `remove` for that person's notes. Notes are independent of
-public bios, imported documents and source messages. They are rows of the store's `notes` table (version
-25), linked to the contact, so `search notes` and `search all` find them too. `contacts list --search-notes
-<text>` is an explicit substring search over the notes of the selected account's contacts.
-
-`metadata get --chat <chat>` reads the cached group/channel description and fetched time.
-`metadata refresh --chat <chat>` reads it from the messenger, without changing the remote chat.
-The refresh command accepts repeated chats and a bounded `--limit` (1–500).
-`tags auto [--chat <chat>] [--limit 50]` classifies cached title, username and description with
-versioned keyword rules. It works offline and uses only stored group/channel titles when there is
-no full metadata snapshot. `--refresh-metadata` explicitly fetches descriptions; `--dry-run`
-previews cached results without writes. These flags cannot be combined. Results identify matched
-fields and a rule score, not a topic probability. No model or message text is used.
-
-Automatic tag claims are distinct from manual labels. Rerunning removes obsolete automatic tags
-and preserves manual tags. Adding a label already generated promotes it to manual ownership;
-listing generated tags includes `sources`. Use `tags list|remove --source manual|auto` to select one ownership source. Removing a tag without a source removes its claims; a later explicit
-automatic run can regenerate it. Upgrade consumers together before relying on manual promotion:
-older builds cannot record manual ownership of an already generated label.
-
-Administrator reports are mounted by the same `statsCommand`: `stats messages unanswered`,
-`stats contacts responses`, `stats chats newcomers` and `stats messages discussion`. They read
-held data only; [the guide](docs/rankings.md#find-questions-and-posts-that-need-attention) explains
-explicit reply attribution, selected answerers, unknown joining dates and bounded evidence.
-
-
-`--json` prints text as it was written; MCP answers show control and direction characters visibly in
-strings and keys. `--json=id,text` keeps only those fields. MCP contact searches keep third-party registries off
-unless the caller explicitly sets `registries: true`.