@wirecat/cli-core 0.19.4 → 0.262.0

package/README.md

@@ -1,375 +1,514 @@
-# @wirecat/cli-core
-
-The parts every command line tool needs and nobody enjoys writing twice: the two output streams,
-a renderer for people and for machines, a closed error model with stable exit codes, the OS
-keyring behind a testable seam, and injectable clocks.
-
-Extracted from [`brazecli`](https://github.com/leemour/brazecli), where each piece earned its
-shape, and shared with [`max-cli`](https://github.com/WireCatLabs/max-cli).
-
-Published on npm and used by `max-cli`, `cli-messaging`, `tg-cli` and `brazecli`. What changed in
-each version is in [`CHANGELOG.md`](CHANGELOG.md); how the package is put together and released is in
-[`docs/dev/`](docs/dev/ARCHITECTURE.md).
-
-## The rule this package exists to keep
-
-**In a machine mode, stdout carries data and nothing else.** No spinner, no `✓`, no warning, no
-ANSI. Diagnostics go to stderr, in every mode including the pretty one. That is the contract a
-script or an agent depends on, and `captureStreams` exists so a test can prove nothing leaked
-across.
-
-```ts
-import { captureStreams, createRenderer } from "@wirecat/cli-core"
-
-const streams = captureStreams()
-createRenderer({ format: "json", color: false, streams }).result({ chats: 2 })
+<p align="center">
+  <img src="https://raw.githubusercontent.com/WireCatLabs/cli-core/main/docs/images/cli-core-banner.png" alt="Built on cli-base: the foundation for agent-ready CLIs" width="100%">
+</p>
 
-streams.stdout // ['{"chats":2}']
-streams.stderr // []
-```
+# @wirecat/cli-core
 
-## What is in it
+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`.
 
 | | |
 |---|---|
-| `streams` | the stdout/stderr split, and the capture used to test it |
-| `renderer` · `pretty` | `pretty` / `json` / `jsonl`; tables for lists, labelled lines for objects; `quiet` keeps only failures on stderr |
-| `errors` · `exit-codes` | 14 closed error codes, one exit number each, so a script can branch on `$?` |
-| `keyring` | `KeyringStore` with the system, memory and deliberately-broken implementations |
-| `fieldsOf` · `projectFields` | validated field selection preserving list metadata and operation identifiers |
-| `createOutputBuffer` | bounded UTF-8 output held until successful completion and resource cleanup |
-| `createDeadline` | cooperative command cancellation with injected sleep and a parent abort signal |
-| `time` | monotonic and wall clocks, and the one sleep that both timeouts and backoff use |
-| `logger` | the four-method interface a host adapts Pino to — this package logs nothing itself |
-| `paths` | `env-paths` for config, state and cache, each overridable by environment variable |
-| `config` | JSON config loading that names the bad field, and an atomic write that locks the directory down |
-| `credentials` | environment → keyring → file, warning once and falling through when the keyring refuses |
-| `logging` | a Pino adapter writing JSON lines with secrets redacted by field name; a file that cannot be written is reported to `onError`, never thrown |
-| `retry` | full-jitter backoff, and the distinction between "no answer came" and "safe to repeat" |
-| `/testing` | `captureStreams`, `memoryKeyring`, `brokenKeyring`, `fakeClock` |
-| `/commands` | the command registry: `describeProgram`, `annotate`, `flatten` — see below |
-| `/completion` | shell completion over the registry: `suggest`, `formatSuggestions` — see below |
-| `/update` | keeping an install current: `installerOf`, `updateCommand`, `latestVersion`, `mayNotify`, `updateNotice`, `runUpdate` — see below |
-| `/codegen` | build time: an official API description → types, Valibot schemas, an operation manifest and a coverage page — see below |
-| `/release` | release time: `releaseCheck` and the checks it runs — changelog shape, links, package contents, version in step — see below |
-| `/skill` | the CLI's SKILL.md for coding agents: `skillCommand` (`show`, `install`), `skillHint`, `skillResource` — see below |
-| `/mcp` | local stdio MCP setup for Codex and Claude Code, plus a read-only handshake and tool-list probe |
-
-**Nothing in the root export is HTTP.** Status classification, `Retry-After` parsing and the fetch
-seam live in `@wirecat/cli-core/http`, so a CLI that speaks a socket never depends on a stack it
-does not call:
+| `.` | `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:
 
 ```ts
-import { providerWaitMs, statusToCode } from "@wirecat/cli-core/http"
-```
-
-**Portable command control stays independent of provider and store lifetimes.**
-`fieldsOf("id,speaker.id")` parses up to 128 field paths; `projectFields(value, paths)` selects data
-from objects or list items while preserving the list envelope and `operationId` / `sendId`.
-`items.id` also works for bare objects and JSONL items. Unknown fields are omitted; parent selections
-win over their children. Unsafe prototype paths are refused, including when paths are passed directly.
-
-`createOutputBuffer({ maxOutputBytes })` retains raw output chunks until `flush(write)` or `discard()`.
-Its default limit is 4 MiB; zero disables the limit. It counts actual UTF-8 bytes, including delimiters
-the caller passes, and adds no newlines. Use a new buffer for each command and flush only after resource
-cleanup succeeds; discard on failure. A flush consumes the buffer even when its writer throws.
-The `bytes` property reports the cumulative accepted byte count. A writer failure can leave partial
-output; buffering only guarantees no output before flushing.
-
-Optional `{ fields, format: "json" | "jsonl" }` projects before counting bytes. With projection,
-each `data(text)` must contain a complete JSON value or complete JSONL lines; fragments fail before
-buffering. Without projection, arbitrary text chunks work. Hosts can instead project values before
-rendering and buffer the renderer's raw text. For core renderers, pass the line delimiter explicitly
-when adapting `Streams.data`: `data: (text) => buffer.data(text + "\n")`.
-
-`createDeadline({ timeoutMs, signal, sleep })` supplies a command signal and `race(body)`. An omitted
-timeout creates no timer; zero aborts synchronously without calling sleep, and the maximum is 2147483647 milliseconds.
-Pass its signal to every cancellable operation and check it before writes. On timeout or parent
-cancellation, `race` waits for the body to settle before rejecting, so a caller can safely close
-resources afterwards. An operation ignoring its signal can delay completion; this helper never
-abandons it in the background. A body's more precise `outcome_unknown` error survives interruption.
-Call `dispose()` in `finally` to remove the timer and parent listener. There are no process signal
-handlers, retries, automatic resource cleanup or HTTP behavior in these helpers.
-
-**The command registry is `@wirecat/cli-core/commands`** — the whole command tree as data, like
-`rails routes`, for an agent to read instead of `--help` and for generated documentation. It walks
-the live [Commander](https://github.com/tj/commander.js) tree, so a command built in a loop from a
-catalog appears exactly like a handwritten one; `annotate` adds what the tree cannot say. Commander
-is a type here, not a runtime dependency — an optional peer, 15 or newer.
-
-```ts
-import { annotate, describeProgram } from "@wirecat/cli-core/commands"
-
-annotate(program.command("send"), { mutates: true, examples: ["max messages send 42 hi"] })
-annotate(generated, { origin: "generated", operationId: "campaigns.list" })
-
-describeProgram(program) // [{ path: ["send"], usage, origin, mutates, options: [...], commands: [...] }]
-```
-
-Each option says whether it `takesValue` and, separately, whether it is `mandatory` — not
-Commander's `required`, which means "takes a value when given" — plus its choices, default,
-environment variable, the options it `conflicts` with and the values it `implies`.
-
-**Shell completion is `@wirecat/cli-core/completion`**, built on the registry. `suggest` takes the
-words typed so far and answers what may come next: a command, an action, an option, one of its
-values, or an argument's values from a source the CLI hands in — a local cache, never the network,
-because a shell calls it on every Tab. `formatSuggestions` writes the answer in the protocol of the
-shell scripts [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab) generates, so the CLI prints
-those scripts with tab and answers `<cli> complete -- <words>` with this; cli-core itself does not
-depend on tab.
-
-```ts
-import { formatSuggestions, suggest } from "@wirecat/cli-core/completion"
-
-const words = argv.slice(argv.indexOf("--") + 1)
-streams.data(formatSuggestions(suggest({ commands, globalOptions, words, sources: { arguments: { chat: chatNames } } })))
+const found = await searchAllIncludingMeetings(store, account, {
+  text: "project AND plan",
+  limit: 20,
+  meetingAccount: { provider: "zoom", account: "zm-profile:example" },
+  maxMeetings: 100,
+})
 ```
 
-**Two traps worth knowing before you use the credential store.** The OS keyring is global: an entry
-is addressed by service and account and knows nothing about which config directory asked for it, so
-a throwaway config directory silently overwrites the real secret unless you pass `isolated: true`.
-And a secret should never be handed to a logger in the first place — redaction by field name is the
-second line of defence, not the first.
-
-**Everything the environment knows can be passed in**: the clock, the sleep, the keyring, `env`,
-`fetch` and the streams. The real ones are only defaults — `Credentials` without a `keyring` uses the
-system keychain, `resolvePaths` without `env` reads `process.env`. Passing them is what makes a
-timeout test finish instantly and a keyring test incapable of reaching a real keychain.
-
-**Generating an API catalog is `@wirecat/cli-core/codegen`**, a build-time tool. It reads a
-format-neutral `ApiModel` — operations with a transport binding (`http` method and path, or `rpc`
-name), an `effect` (`read`, `write`, `destructive`) and how far the source can be trusted
-(`contract`, `example`, `inferred`, `override`) — and writes committed files. It parses no file
-format: the adapter from OpenAPI, Postman or anything else lives in the CLI that has that source,
-so this adds no dependency. Generation stops, naming the problem, when two operations collide, an
-operation is not classified as a read or a write, an override matches nothing, a reference points
-nowhere or a construct cannot be expressed; it never drops an operation or falls back to `any`.
+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:
 
 ```ts
-import { generate, manifestGenerator, typesGenerator, valibotGenerator, writeArtifacts } from "@wirecat/cli-core/codegen"
+import { prepareEvidencePacket } from "@wirecat/cli-core/services"
 
-const artifacts = generate(model, [typesGenerator({ path }), valibotGenerator({ path, typesImport }), manifestGenerator({ path })], {
-  overrides: { answerOnCallback: { effect: "write", reason: "a POST that edits a message" } },
-  banner: ["Source: spec/bot/schema.yaml", "Run: pnpm bot:generate"],
+const packet = prepareEvidencePacket({
+  kind: "chats", // or "news" or "person"
+  source: { provider, account, chat: chatId },
+  page,
+  limits: { messages: 100, bytes: 64 * 1024 },
 })
-const stale = writeArtifacts(artifacts, { root, check: process.argv.includes("--check") })
 ```
 
-The generated schemas import `@wirecat/cli-core/codegen/runtime` at run time — a few number
-helpers, not the generator. Numbers are expected from a lossless JSON parser (`lossless-json`): a
-64-bit integer comes out as its exact decimal string, and any other integer that does not fit a JS
-number fails instead of rounding. Objects are loose, so a field the API added later passes through.
-Unions retain every alternative, including recursive references and Boolean literals.
-`definitionsGenerator` emits the same schema nodes for runtime input traversal; RPC parameters can be in the JSON body.
-Enums and discriminated unions are **strict**: a value or subtype the snapshot does not know fails,
-so decode a live stream (updates, webhooks) only where that is what you want.
-
-**The schemas decode; they do not encode.** Their output carries an `int64` as a string, so sending
-it back would put a string where the API expects a number. Validate a request with the schema, then
-send the original lossless value.
-
-**Keeping an install current is `@wirecat/cli-core/update`.** `installerOf(realpath(script))` says
-which package manager put the CLI there — pnpm, npm or bun, measured on real installs — and
-`updateCommand` gives the argv that updates it; a checkout or `npx` gets none. `latestVersion` asks
-npm with a timeout and answers `undefined` on any failure. `mayNotify` says whether a person is at a
-terminal to be told: never in JSON, a pipe, `--quiet`, `CI` or with `NO_UPDATE_NOTIFIER`.
-`updateNotice` is the whole daily line: it stays silent when `update` or `complete` is anywhere on
-the command line, asks npm at most once a day through a state file the CLI names, and returns the
-sentence or `undefined` — it never throws. `runUpdate` starts the package manager with its output on
-stderr (`spawnPlan` is the Windows `.cmd` rule). Nothing here updates or prints by itself — a CLI
-holding somebody's credentials must not change itself unasked.
-
-**A CLI's guide for coding agents is `@wirecat/cli-core/skill`.** `skillCommand(app, skillUrl,
-environment)` is `<cli> skill show` — SKILL.md on stdout, even into a pipe, or `{ name, content }`
-with `--json` — and `<cli> skill install [--for claude|agents|all]`, which writes it to
-`~/.claude/skills/<appName>/` and `~/.agents/skills/<appName>/` with the CLI's version as
-`metadata.version` in the frontmatter, refusing a file whose `name` is not `<appName>`. `environment` is the host's own renderer, streams and `env` for that invocation.
-`skillHint` is one line, or `undefined`, for an agent (`AI_AGENT` or `CLAUDECODE` set) with no copy
-installed or an older one, at most once a day, through the same state file as `updateNotice`; the
-host prints it on stderr. `skillResource` is what an MCP server registers to serve the file as
-`<command>://skill`, plus a line for its `instructions` — the SDK stays the host's.
-
-**The release checks are `@wirecat/cli-core/release`** — everything about a release that a program
-can decide. A check is `{ name, run }`, and `run` returns the problems it found, one line each; an
-empty list is a pass. `releaseCheck(checks, { version, log })` runs them all, even after a failure,
-prints `ok` or `FAIL` per check and returns how many failed — the caller exits. The checks every CLI
-shares: `command(root, "pnpm", "lint")` for anything that passes by exiting 0, `notOnNpm`,
-`packContents` against a list of what may ship, `changelogProblems` for the fixed headings and the
-dated top section, `docsProblems` for dead links and anchors and the rules of the pages a user reads,
-and `versionScript` — the whole of a `version:check` / `version:sync` script. Each CLI passes its
-own headings, id prefixes and pages; the checks that belong to one messenger stay in that CLI.
+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`.
 
 ```ts
-import { command, notOnNpm, packageVersion, releaseCheck } from "@wirecat/cli-core/release"
-
-const version = packageVersion(root)
-const failed = releaseCheck(
-  [
-    { name: "version not on npm", run: notOnNpm(root, "@wirecat/tg-cli", version) },
-    { name: "lint", run: command(root, "pnpm", "lint") },
-  ],
-  { version, log: console.log },
-)
-process.exit(failed === 0 ? 0 : 1)
-```
-
-## Where secrets actually go, per platform
-
-The keyring is real on every desktop and absent on most servers, so the fallback is not an edge
-case — it is the normal path in CI and containers. Checked against `@napi-rs/keyring` 2.1.0 on
-2026-09-19.
+import { readMeetingEvidence, resolveMeetingReference, proposeMeetingTask } from "@wirecat/cli-core/services"
 
-| Platform | Backing store | Needs installing |
-|---|---|---|
-| macOS | Keychain, via the Security framework | nothing — part of the OS |
-| Windows | Credential Manager | nothing — part of the OS |
-| Linux desktop (GNOME, KDE) | Secret Service over D-Bus — `gnome-keyring`, `kwallet` | nothing on a normal desktop; the keyring must be **unlocked** |
-| Linux headless, container, WSL, CI | usually **nothing** — no session bus, no secrets daemon | falls back to a `0600` file, with one warning on stderr |
-| FreeBSD | Secret Service, same as Linux | same |
-
-**No compiler is involved.** The package ships prebuilt binaries for twelve platform triples —
-macOS arm64/x64, Windows x64/ia32/arm64, Linux x64 and arm64 in both glibc and musl, armv7,
-riscv64, FreeBSD x64 — so there is no Rust toolchain and no node-gyp on any mainstream target.
-The Linux binary links only against libc: it speaks D-Bus itself rather than through libsecret,
-so *libsecret is not a requirement* — a running Secret Service provider is.
-
-Two consequences worth designing for rather than discovering:
-
-- **`auto` is the right default and `file` must stay available.** `credentialStorage: "file"` skips
-  the keyring entirely, which is what a container wants and what a locked keyring makes necessary.
-- **A locked Linux keyring can block on a prompt** rather than failing. That is the one case the
-  fallback does not rescue, and a CLI that hangs looks broken rather than locked.
-
-## Both runtimes
-
-Node 22+ and Bun, and the Bun half is executed rather than assumed:
-
-```sh
-pnpm test        # vitest, Node
-pnpm smoke:bun   # the same exports, actually run under Bun
-pnpm lint
-pnpm typecheck
-pnpm build
+// 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")
 ```
 
-The rest of the checks, and what each is for, are in [`docs/dev/TESTING.md`](docs/dev/TESTING.md).
+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
 
-## Shared tooling
-
-The configuration, development scripts and CI that every CLI on cli-core used to copy. A repository
-takes each piece on its own.
-
-**TypeScript.** Compiler options only; paths and file lists stay in the repository, because `tsc`
-resolves them against the file that declares them.
-
-```jsonc
-// tsconfig.json
-{
-  "extends": "@wirecat/cli-core/tsconfig.base.json",
-  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
-  "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.test.ts"]
-}
-// tsconfig.test.json — checks every file under src/, tests included, without emitting
-{ "extends": ["./tsconfig.json", "@wirecat/cli-core/tsconfig.test.json"] }
-// tsconfig.scripts.json — checks scripts/
-{ "extends": ["./tsconfig.json", "@wirecat/cli-core/tsconfig.scripts.json"] }
-```
-
-**Biome.** Formatter, linter and the rule that lets `scripts/` print. Your `files.includes` and
-your own `overrides` (import boundaries) stay in your file; Biome adds them to the shared ones.
-Write the specifier without `.json`: Biome reads anything ending in `.json` as a relative path.
-
-```json
-{ "extends": ["@wirecat/cli-core/biome"], "files": { "includes": ["**", "!**/dist", "!**/node_modules", "!pnpm-lock.yaml"] } }
-```
-
-**lefthook.** Biome and gitleaks on staged files before a commit, `pnpm typecheck` before a push.
-An extended file **overrides** your `lefthook.yml`; to change a shared hook, use `lefthook-local.yml`.
-
-```yaml
-extends:
-  - node_modules/@wirecat/cli-core/config/lefthook.yml
+```sh
+pnpm install
+pnpm lint && pnpm typecheck && pnpm test
+pnpm smoke:bun    # the same exports, run under Bun
 ```
 
-**`cli-dev`.** Installed with the package; `pnpm exec cli-dev help` lists the commands.
+## Releasing
 
-| Instead of | Run |
-|---|---|
-| `scripts/slow-tests.ts` | `cli-dev slow-tests [report] [count]` |
-| `scripts/next-version.mjs` | `cli-dev next-version <wanted> <latest> <versions-json>` |
-| `scripts/version.ts` | `cli-dev version [--sync] [--file src/version.ts]` |
-| `scripts/docs-check.ts` | `cli-dev docs-check --rules scripts/release/checks.ts`, or `--ids CLI,MAX` with the English defaults |
-| `scripts/test-matrix.ts` | `cli-dev test-matrix --program dist/program.js --untested scripts/test-matrix-untested.ts --name max [--check]` |
-
-`--rules` names a module exporting `CHANGELOG` and `docsRules(root)`; `--program` one exporting
-`createProgram`; `--untested` one exporting `UNTESTED`. A TypeScript module loads on Node 24 as it is.
-
-**Docs.** Spelling, Markdown form and prose rules for the pages a user reads. The tools are your
-own dev dependencies (`cspell`, `@cspell/dict-ru_ru`, `@cspell/dict-en-gb`, `rumdl`); the settings
-and the shared word list are here. Code blocks and inline code are not spell-checked: commands and
-options are checked against the program by the parity check.
-
-```jsonc
-// cspell.json — the dictionaries resolve from your node_modules, so you import them yourself
-{
-  "version": "0.2",
-  "import": ["@wirecat/cli-core/cspell", "@cspell/dict-en-gb/cspell-ext.json", "@cspell/dict-ru_ru/cspell-ext.json"],
-  "ignorePaths": ["docs/commands.md", "docs/dev/**", "CHANGELOG.md"],
-  "words": []
-}
-```
+Raise `version` in `package.json` through a pull request, merge it, then on `main`:
 
 ```sh
-cspell --no-progress README.md "docs/*.md"
-rumdl check --config node_modules/@wirecat/cli-core/config/rumdl.toml README.md docs/*.md
-vale README.md docs/*.md   # .vale.ini: StylesPath = node_modules/@wirecat/cli-core/config/vale
+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
 ```
 
-`cli-dev docs-check --pages` adds the structure check: `docs/` against `docs/meta.json`, the
-sidebar of [the docs portal](https://github.com/WireCatLabs/cli-docs/blob/main/docs/STRUCTURE.md).
-Vale's styles are `CliDocs` (filler words, long sentences) and `Tg` (tg's tone: a Telegram client,
-never "unofficial"); its rules warn rather than fail until they are tuned.
-
-**CI.** Install, lint, typecheck, test with coverage, build, your extra checks, Bun, and a gitleaks
-scan of the whole history. Jobs only your repository needs stay beside it in your `ci.yml`.
-
-```yaml
-jobs:
-  ci:
-    uses: WireCatLabs/cli-core/.github/workflows/node-ci.yml@v<version>
-    with:
-      checks: |
-        pnpm docs:check
-      bun-run: pnpm build && pnpm smoke:bun   # the default is pnpm smoke:bun
-```
+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.
 
-Inputs: `node-version` (`"24"`), `checks` (shell lines run after the build), `bun` (`true`),
-`bun-run`. The workflow is in the repository, not the package: pin a tag or a commit, not `main`.
+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`.
 
-## Releasing
-
-Raise `version` in `package.json` and date the `## Unreleased` section of
-[`CHANGELOG.md`](CHANGELOG.md) as that version, through a pull request; merge it, then on `main`:
+### How often, and what may break
 
-```sh
-bin/release
-```
+**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.
 
-It refuses a dirty tree, a branch other than `main` and a `main` that is not pushed. When npm already
-has the version, or a higher one, it commits the next free version to `main` — the next minor for
-`x.y.0`, the next patch otherwise — renames the changelog heading to match, and publishes that. Then it starts
-[`release.yml`](.github/workflows/release.yml) and follows it. The workflow runs every check,
-publishes through npm's [trusted publishing](https://docs.npmjs.com/trusted-publishers/) — no npm
-token in GitHub, and npm attaches provenance — and tags `v<version>` only once npm shows the new version.
+**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.
 
-npm trusts the workflow **by file name**: the package's Trusted Publisher settings on npmjs.com name
-`WireCatLabs` / `cli-core` / `release.yml`. Rename the file and publishing stops until they are updated.
+| 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 |
 
-`bin/release --local` is the fallback: it runs the same checks here and publishes with the npm token
-from the keyring (`secret-tool`, service `npm`, account `leemour`) without printing it. The token
-must be allowed to write `@wirecat/cli-core`, not only `@wirecat/max-cli`.
+`./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.
 
 ## 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.
+
+
+For agent consumption, global `--agent-json` renders control and direction characters visibly in JSON
+strings and keys. `--json` retains raw values; `--agent-json --jsonl` applies the safe form to every
+streamed record. MCP already uses this form. MCP contact searches keep third-party registries off
+unless the caller explicitly sets `registries: true`.