@wirecat/cli-core 0.393.0 → 0.394.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## 0.394.0 — 23.10.2026
+
+### Added
+
+- Statistics commands include examples in help and command discovery, with guidance for reusing an exact evidence selection.
+
+- Store commands include concrete examples in help and command discovery.
+
+- **`contacts prepare <person>`: what to know before talking to someone.** What `contacts context` gives, plus the
+  one-to-one chats where their message is the newest the store holds, open tasks assigned to them, accepted facts
+  about them and their projects, your notes about them (withheld when the profile denies `contacts.notes.list`), and
+  their recent meetings — each with its reference, under one byte budget, with `prepare.coverage` saying what each
+  section left out and why. Tasks of another account of the same messenger, and facts on a project bound to one, stay
+  out. It reads messages, so `messages: deny` refuses it, as it does `contacts context`. `personPreparation` in
+  services and `people.preparation` on the store.
+
 ## 0.393.0 — 23.10.2026
 
 ### Added

package/dist/cli/messenger/archive-commands.js

@@ -12,6 +12,7 @@ import { kindsOf } from "../../services/inbox.js";
 import { dateWindow } from "../../services/moment.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { commandAt } from "../steps.js";
 import { jobsCommand } from "./backfill-command.js";
 import { messengerContext } from "./context.js";
 import { admitPassword, linesOf, openFolder, runFileFor, saveManifest, sealRun, writeChanges } from "./export-folder.js";
@@ -30,6 +31,33 @@ export const storeCommand = (messenger) => {
         .addCommand(clearCommand(messenger));
     for (const command of storeMaintenanceCommands(messenger))
         store.addCommand(command);
+    const examples = {
+        backup: "./backup.db",
+        check: "",
+        clear: "--left --dry-run",
+        "copies delete": "messages_copy_1",
+        decrypt: "./backup.enc --output ./restored.db",
+        export: '"Book club" --output ./messages.jsonl',
+        "gaps plan": '"Book club"',
+        "gaps repair": '"Book club" --limit 100',
+        info: "",
+        "jobs cancel": "job-101",
+        "jobs clear": "",
+        "jobs list": "",
+        "jobs retry": "--failed",
+        "jobs show": "",
+        migrate: "",
+        reindex: "",
+        repair: "--dry-run",
+        reset: "",
+        restore: "./backup.db",
+        status: '"Book club"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(store, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal store ${path} ${args}`.trimEnd()] });
+    }
     return store;
 };
 /**

package/dist/cli/messenger/contacts-command.js

@@ -137,6 +137,35 @@ export const contactsCommand = (messenger) => {
         if (hasMore)
             context.renderer.note("cut at --limit; a larger one shows more");
     });
+    annotate(contacts.command("prepare"), {
+        effects: REMOTE_READ,
+        examples: [`${messenger.app.command} contacts prepare Ana`],
+    })
+        .summary("what to know before you talk to someone, each item with its reference")
+        .description("before you talk to someone: what contacts context gives, plus the one-to-one chats where they wrote last, " +
+        "open tasks, accepted facts, your notes and their recent meetings, each with its reference; never connects")
+        .argument("<person>", "their id, @username, or part of their name")
+        .option("--limit <n>", `at most this many messages, and items in each section; ${CONTEXT_MESSAGES} if not given`, positiveCount("--limit"))
+        .option("--since-time <time>", "no message or meeting older than this ISO 8601 time, or 2h / 1d ago")
+        .action(async function (person) {
+        const { limit, sinceTime } = this.opts();
+        const context = messengerContext(this, messenger);
+        const window = dateWindow(sinceTime === undefined ? {} : { sinceTime });
+        const found = await context.withServices((services) => services.people.prepare(person, {
+            messages: limit ?? CONTEXT_MESSAGES,
+            notes: levelFor(context.settings.permissions, "contacts.notes.list").level !== "deny",
+            ...(window.since === undefined ? {} : { since: window.since }),
+        }));
+        const { hasMore, ...rest } = found;
+        renderAnswer(this, context, itemOf(snakeKeys(rest), {
+            next: syncsFirst(messenger)
+                ? found.notRead
+                    .filter((chat) => chat.provider === messenger.provider)
+                    .map((chat) => nextStep("messages.sync", { args: { chat: chat.chatId } }))
+                : [],
+            meta: { ...window.meta, ...(hasMore ? { truncated: true } : {}) },
+        }));
+    });
     annotate(contacts.command("timeline"), { effects: REMOTE_READ })
         .description("everything one person took part in, in every messenger linked to them — messages they wrote or were " +
         "mentioned in, chats, mail, meetings, tasks — newest first, from the store; never connects")

package/dist/cli/messenger/stats-command.js

@@ -12,6 +12,7 @@ import { EVENTS_DAYS } from "../../services/chats.js";
 import { dateWindow } from "../../services/moment.js";
 import { destroysNothing, LOCAL_WRITE } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
+import { commandAt } from "../steps.js";
 import { adminStatisticsCommand } from "./admin-statistics-command.js";
 import { statsCommand as chatStatsCommand } from "./chats-stats-command.js";
 import { messengerContext } from "./context.js";
@@ -84,5 +85,30 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
             context.renderer.note("partial data — the chart shows lower bounds");
         renderAnswer(this, context, chartAnswer(chart, chartFile, window.meta));
     });
+    const examples = {
+        charts: '"Book club" --output ./activity.svg',
+        "chats newcomers": '"Book club"',
+        "chats retention": '"Book club"',
+        "chats show": '"Book club"',
+        "contacts evidence": '101 --selection "$selection" --component messages',
+        "contacts responses": '--chat "Project room"',
+        "contacts top": '--chat "Book club" --limit 10',
+        "messages counters refresh": '--chat "Book club" --dry-run',
+        "messages counters show": '--chat "Book club" --limit 10',
+        "messages discussion": '--chat "Book club"',
+        "messages evidence": '"$message" --selection "$selection" --component reactions',
+        "messages show": '--chat "Book club" --by day',
+        "messages top": '--chat "Book club" --limit 10',
+        "messages unanswered": '--chat "Project room"',
+        "tasks show": '--chat "Project room"',
+    };
+    for (const [path, args] of Object.entries(examples)) {
+        const command = commandAt(stats, path);
+        if (command)
+            annotate(command, { examples: [`${messenger.app.command} personal stats ${path} ${args}`] });
+    }
+    for (const target of ["messages", "contacts"]) {
+        commandAt(stats, `${target} evidence`)?.addHelpText("after", `\nSet selection to drilldown.selection from stats ${target} top; copy the matching row's ${target === "messages" ? "message locator into message" : "person id"}.\n`);
+    }
     return stats;
 };

package/dist/meetings/mcp/index.d.ts

@@ -38,6 +38,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -53,11 +54,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -75,11 +76,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -101,7 +102,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -188,6 +188,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -203,11 +204,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -225,11 +226,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -251,7 +252,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -338,6 +338,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -353,11 +354,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -375,11 +376,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -401,7 +402,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -488,6 +488,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -503,11 +504,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -525,11 +526,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -551,7 +552,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
@@ -638,6 +638,7 @@ export declare const meetingTools: ({
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -653,11 +654,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -675,11 +676,11 @@ export declare const meetingTools: ({
             format?: undefined;
             transcript_id?: undefined;
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;
         } | {
+            limit?: undefined;
             event_id?: undefined;
             series_id?: undefined;
             page?: undefined;
@@ -701,7 +702,6 @@ export declare const meetingTools: ({
                 minimum: number;
             };
             query?: undefined;
-            limit?: undefined;
             scan_limit?: undefined;
             max_read_bytes?: undefined;
             cursor?: undefined;

package/dist/sends/permissions.js

@@ -450,7 +450,8 @@ export const keyForCommand = (path) => {
         return path.join(".");
     if (top === "messages" && next === "sync")
         return "messages";
-    if (SHOW_MESSAGES.has(top) || (top === "contacts" && (next === "context" || next === "timeline")))
+    if (SHOW_MESSAGES.has(top) ||
+        (top === "contacts" && (next === "context" || next === "prepare" || next === "timeline")))
         return "messages";
     if (RESOURCES.includes(top))
         return path.join(".");

package/dist/services/index.d.ts

@@ -80,6 +80,8 @@ export type { ContactSync, PeopleService } from "./people.js";
 export { peopleService, phoneOf } from "./people.js";
 export type { ContextMessage, ContextOptions, NotReadReason, PersonContext, SharedChat, } from "./person-context.js";
 export { CONTEXT_BYTES, CONTEXT_MESSAGES, identityIn, personContext } from "./person-context.js";
+export type { PersonPreparation, WaitingDialog } from "./person-preparation.js";
+export { PREPARE_BYTES, personPreparation } from "./person-preparation.js";
 export type { PersonTimeline, Scope, TimelineItem, TimelineOptions } from "./person-timeline.js";
 export { personTimeline, SCOPES, TIMELINE_ITEMS, TIMELINE_MAX } from "./person-timeline.js";
 export type { RankedRow, RankingFound, RankingQuery, RankingsService } from "./rankings.js";

package/dist/services/index.js

@@ -57,6 +57,7 @@ export { searchStore } from "./messages-archive-search.js";
 export { moderationService } from "./moderation.js";
 export { peopleService, phoneOf } from "./people.js";
 export { CONTEXT_BYTES, CONTEXT_MESSAGES, identityIn, personContext } from "./person-context.js";
+export { PREPARE_BYTES, personPreparation } from "./person-preparation.js";
 export { personTimeline, SCOPES, TIMELINE_ITEMS, TIMELINE_MAX } from "./person-timeline.js";
 export { rankingsService } from "./rankings.js";
 export { searchRecordOf } from "./search-record.js";

package/dist/services/people.d.ts

@@ -5,6 +5,7 @@ import type { PersonRecord } from "../store/store.js";
 import type { PageWindow } from "./chats.js";
 import { type ServiceDeps } from "./deps.js";
 import { type ContextOptions, type Detail, type PersonContext, type PersonMessages } from "./person-context.js";
+import { type PersonPreparation } from "./person-preparation.js";
 import { type PersonTimeline, type TimelineOptions } from "./person-timeline.js";
 export interface ContactSync {
     added: number;
@@ -52,6 +53,10 @@ export interface PeopleService {
     }>>;
     /** What the store holds about them, across every messenger linked to them; never connects. */
     context(person: string, options?: ContextOptions): Promise<PersonContext>;
+    /** `context` and what to know before talking to them: chats waiting on you, tasks, facts, notes, meetings. */
+    prepare(person: string, options?: ContextOptions & {
+        notes?: boolean;
+    }): Promise<PersonPreparation>;
     /** Everything they took part in, from the store's involvement index; never connects. */
     timeline(person: string, options?: TimelineOptions): Promise<PersonTimeline>;
     /**

package/dist/services/people.js

@@ -8,6 +8,7 @@ import { newOperationId } from "../sends/send-id.js";
 import { fromStore, storeIfOpen } from "./deps.js";
 import { storedChatId } from "./message-resolution.js";
 import { CHAT_MESSAGES, identityIn, personContext, personMessages, } from "./person-context.js";
+import { personPreparation } from "./person-preparation.js";
 import { personProfile } from "./person-profile.js";
 import { personTimeline } from "./person-timeline.js";
 export const peopleService = (deps) => {
@@ -75,6 +76,7 @@ export const peopleService = (deps) => {
         },
         profile: (person) => personProfile(deps, person),
         context: async (person, options) => personContext(await deps.store(), await deps.account(), person, options),
+        prepare: async (person, options) => personPreparation(await deps.store(), await deps.account(), person, options),
         timeline: async (person, options) => personTimeline(await deps.store(), await deps.account(), person, options),
         messagesIn: async (person, { chats, limit, detail, fetch = false }) => {
             const store = await deps.store();

package/dist/services/person-context.d.ts

@@ -1,5 +1,5 @@
-import type { ChatKind, Id, Provider } from "../domain/models.js";
-import type { AccountKey, IdentityRef, MessageStore, PersonRecord } from "../store/store.js";
+import type { ChatKind, Id, Message, Provider } from "../domain/models.js";
+import type { AccountKey, IdentityRef, LinkedIdentity, MessageStore, PersonRecord } from "../store/store.js";
 export declare const CONTEXT_MESSAGES = 10;
 export declare const CONTEXT_BYTES: number;
 export interface ContextMessage {
@@ -60,6 +60,16 @@ export interface ContextOptions {
     /** ms: nothing older. */
     since?: number;
 }
+export declare const toContext: (key: AccountKey, message: Message, chatTitle: string | null) => ContextMessage;
+/**
+ * The accounts each identity is read in: for the messenger asked, only the account asked about — a
+ * second account of the same messenger is somebody else's view; for a linked messenger, every account
+ * of this store that saw that identity.
+ */
+export declare const readsOf: (record: PersonRecord, asked: AccountKey) => {
+    key: AccountKey;
+    identity: LinkedIdentity;
+}[];
 /**
  * What the store knows about one person, across every identity linked to them. Reads the store
  * only: nothing is fetched, nothing marked read. Identity is by id, never by name.

package/dist/services/person-context.js

@@ -4,7 +4,7 @@ import { pickPerson } from "../resolve.js";
 import { messageOfEmail } from "../store/store.js";
 export const CONTEXT_MESSAGES = 10;
 export const CONTEXT_BYTES = 64 * 1024;
-const toContext = (key, message, chatTitle) => ({
+export const toContext = (key, message, chatTitle) => ({
     locator: formatLocator({ ...key, chat: message.chatId, message: message.id }),
     provider: key.provider,
     account: key.account,
@@ -49,7 +49,7 @@ const newestFirst = (a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp);
  * second account of the same messenger is somebody else's view; for a linked messenger, every account
  * of this store that saw that identity.
  */
-const readsOf = (record, asked) => record.identities.flatMap((identity) => (identity.provider === asked.provider ? [asked.account] : identity.accounts)
+export const readsOf = (record, asked) => record.identities.flatMap((identity) => (identity.provider === asked.provider ? [asked.account] : identity.accounts)
     .filter((account) => identity.accounts.includes(account))
     .map((account) => ({ key: { provider: identity.provider, account }, identity })));
 /**

package/dist/services/person-preparation.d.ts

@@ -0,0 +1,66 @@
+import type { Id, Provider } from "../domain/models.js";
+import type { AccountKey, MessageStore, PreparationFact, PreparationNote, PreparationTask } from "../store/store.js";
+import { type ContextMessage, type ContextOptions, type PersonContext } from "./person-context.js";
+import { type PersonMeetingContextItem } from "./person-meeting-context.js";
+export declare const PREPARE_BYTES: number;
+export interface WaitingDialog {
+    provider: Provider;
+    account: Id;
+    chatId: Id;
+    title: string | null;
+    /** Their message, the newest the store holds in this one-to-one chat. */
+    message: ContextMessage;
+    /** The store does not hold the whole chat, so a later answer may be missing from it. */
+    partial: boolean;
+}
+type Cut = "limit" | "bytes" | null;
+interface SectionCoverage {
+    included: number;
+    hasMore: boolean;
+    cutBy: Cut;
+}
+export interface PersonPreparation extends PersonContext {
+    prepare: {
+        waiting: WaitingDialog[];
+        tasks: PreparationTask[];
+        facts: PreparationFact[];
+        notes: PreparationNote[];
+        meetings: PersonMeetingContextItem[];
+        limits: {
+            items: number;
+            bytes: number;
+        };
+        coverage: {
+            waiting: SectionCoverage & {
+                rule: "their message is the newest the store holds in a one-to-one chat";
+            };
+            tasks: SectionCoverage & {
+                selection: "open, assigned to them in any role";
+                accounts: string[];
+            };
+            facts: SectionCoverage & {
+                selection: "accepted, about them or a project they are a member of";
+            };
+            /** `withheld` when the profile denies `contacts.notes.list`. */
+            notes: SectionCoverage & {
+                selection: "written by you, about them";
+                withheld?: "contacts.notes.list";
+            };
+            /** `accounts`: the ones their meetings came from. */
+            meetings: SectionCoverage & {
+                read: "every account of the store that saw them";
+                accounts: string[];
+                pending: number;
+            };
+        };
+    };
+}
+/**
+ * `contacts context` and what to know before talking to them: the one-to-one chats where they wrote last, open tasks,
+ * accepted facts, your notes and their recent meetings, each item with its reference. The messages keep their own
+ * budget; the sections share what is left of `PREPARE_BYTES`, in that order, so evidence comes first.
+ */
+export declare const personPreparation: (store: MessageStore, asked: AccountKey, reference: string, options?: ContextOptions & {
+    notes?: boolean;
+}) => Promise<PersonPreparation>;
+export {};

package/dist/services/person-preparation.js

@@ -0,0 +1,126 @@
+import { CliError } from "@wirecat/cli-base";
+import { parseMeetingReference } from "../meetings/index.js";
+import { CONTEXT_BYTES, CONTEXT_MESSAGES, personContext, readsOf, toContext, } from "./person-context.js";
+import { personMeetingContext } from "./person-meeting-context.js";
+export const PREPARE_BYTES = 96 * 1024;
+const MEETINGS = 5;
+const CUES = 3;
+const size = (value) => Buffer.byteLength(JSON.stringify(value), "utf8");
+const accountName = ({ provider, account }) => `${provider}:${account}`;
+/**
+ * `contacts context` and what to know before talking to them: the one-to-one chats where they wrote last, open tasks,
+ * accepted facts, your notes and their recent meetings, each item with its reference. The messages keep their own
+ * budget; the sections share what is left of `PREPARE_BYTES`, in that order, so evidence comes first.
+ */
+export const personPreparation = async (store, asked, reference, options = {}) => {
+    const context = await personContext(store, asked, reference, { ...options, bytes: CONTEXT_BYTES });
+    const limit = options.messages ?? CONTEXT_MESSAGES;
+    let left = PREPARE_BYTES - size({ recent: context.recent, mentions: context.mentions });
+    const budgeted = (page) => {
+        const items = [];
+        let cut = false;
+        for (const item of page.items.slice(0, limit)) {
+            const bytes = size(item);
+            if (cut || bytes > left) {
+                cut = true;
+                continue;
+            }
+            left -= bytes;
+            items.push(item);
+        }
+        const over = page.hasMore || page.items.length > limit;
+        return {
+            items,
+            coverage: { included: items.length, hasMore: over || cut, cutBy: cut ? "bytes" : over ? "limit" : null },
+        };
+    };
+    const reads = readsOf(context.person, asked);
+    const partial = new Set(context.notRead.map((chat) => `${chat.provider}/${chat.account}/${chat.chatId}`));
+    const waiting = [];
+    for (const chat of context.shared.filter((one) => one.kind === "dialog")) {
+        const key = { provider: chat.provider, account: chat.account };
+        const [newest] = (await store.messages.messages(key, chat.chatId, { limit: 1 })).items;
+        if (newest?.outgoing !== false)
+            continue;
+        waiting.push({
+            ...key,
+            chatId: chat.chatId,
+            title: chat.title,
+            message: toContext(key, newest, chat.title),
+            partial: partial.has(`${chat.provider}/${chat.account}/${chat.chatId}`),
+        });
+    }
+    waiting.sort((a, b) => Date.parse(b.message.timestamp) - Date.parse(a.message.timestamp));
+    const accounts = [...new Map(reads.map(({ key }) => [accountName(key), key])).values()];
+    const held = await store.people.preparation(context.person.uid, { accounts, limit });
+    const stored = await store.accounts.storedAccounts();
+    const meetings = await meetingsOf(store, context.person.uid, stored, options.since, () => left);
+    const sections = {
+        waiting: budgeted({ items: waiting, hasMore: false }),
+        tasks: budgeted(held.tasks),
+        facts: budgeted(held.facts),
+        notes: budgeted(options.notes === false ? { items: [], hasMore: false } : held.notes),
+        meetings: budgeted({ items: meetings.items, hasMore: meetings.hasMore }),
+    };
+    return {
+        ...context,
+        prepare: {
+            waiting: sections.waiting.items,
+            tasks: sections.tasks.items,
+            facts: sections.facts.items,
+            notes: sections.notes.items,
+            meetings: sections.meetings.items,
+            limits: { items: limit, bytes: PREPARE_BYTES },
+            coverage: {
+                waiting: {
+                    ...sections.waiting.coverage,
+                    rule: "their message is the newest the store holds in a one-to-one chat",
+                },
+                tasks: {
+                    ...sections.tasks.coverage,
+                    selection: "open, assigned to them in any role",
+                    accounts: accounts.map(accountName),
+                },
+                facts: { ...sections.facts.coverage, selection: "accepted, about them or a project they are a member of" },
+                notes: {
+                    ...sections.notes.coverage,
+                    selection: "written by you, about them",
+                    ...(options.notes === false ? { withheld: "contacts.notes.list" } : {}),
+                },
+                meetings: {
+                    ...sections.meetings.coverage,
+                    read: "every account of the store that saw them",
+                    accounts: meetings.accounts,
+                    pending: meetings.pending,
+                },
+            },
+        },
+    };
+};
+/** Their recent meetings in every account of the store that saw them; none is not an error. */
+const meetingsOf = async (store, uid, stored, since, left) => {
+    const none = { items: [], hasMore: false, accounts: [], pending: 0 };
+    if (!stored.length || left() < 2)
+        return none;
+    try {
+        const found = await personMeetingContext(store, `person:${uid}`, {
+            accountIds: stored.slice(0, 1000).map(({ id }) => id),
+            meetings: MEETINGS,
+            cues: CUES,
+            bytes: Math.min(left(), 4 * 1024 * 1024),
+            ...(since === undefined ? {} : { since }),
+        });
+        const read = new Set(found.items.map((item) => parseMeetingReference(item.reference).accountId));
+        return {
+            items: found.items,
+            hasMore: found.coverage.truncatedBy !== null || found.coverage.scanLimitReached,
+            accounts: stored.filter(({ id }) => read.has(id)).map(accountName),
+            pending: found.coverage.pending,
+        };
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "not_found")
+            return none;
+        throw error;
+    }
+};

package/dist/store/exports.d.ts

@@ -31,6 +31,7 @@ export { OTHER_SOURCES, type OtherSource, type SourceMention } from "./sqlite/me
 export { MENTION_QUERY, MENTION_STATUSES, type MentionDecision, type MentionStatus, type MentionsRebuild, type MentionsState, type StoredMention, type StoredPlace, } from "./sqlite/mentions.js";
 export { drainNoteIndex, noteIndexState, resetNoteIndex } from "./sqlite/note-index.js";
 export type { Link as ThingLink } from "./sqlite/notes.js";
+export type { PersonPreparationRead, PreparationFact, PreparationNote, PreparationTask, } from "./sqlite/person-preparation.js";
 export { savedPhoneCountries, saveStorePhoneCountries } from "./sqlite/phone-countries.js";
 export type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
 export type { ProposedAction } from "./sqlite/proposed-actions.js";

package/dist/store/people.d.ts

@@ -2,6 +2,7 @@ import type { Contact, Id, Page, PersonAlias, Provider } from "../domain/models.
 import type { PeopleLookup } from "../resolve.js";
 import type { ContactFilter } from "./sqlite/identities.js";
 import type { StoreContext } from "./sqlite/open.js";
+import { type PersonPreparationRead } from "./sqlite/person-preparation.js";
 import type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
 import type { AccountKey, IdentityRef, LinkOptions, PersonFacts, PersonRecord } from "./types.js";
 export interface AccountPeople {
@@ -44,6 +45,11 @@ export interface PeopleStore extends AccountPeople {
     /** The person a `person:<uid>` reference names. */
     personSeenInAccounts(uid: string, accountIds: readonly number[]): Promise<boolean>;
     personByUid(uid: string): Promise<PersonRecord | undefined>;
+    /** Accepted facts, the owner's notes and open tasks about them; tasks of an account only if `accounts` holds it. */
+    preparation(uid: string, options: {
+        accounts: readonly AccountKey[];
+        limit: number;
+    }): Promise<PersonPreparationRead>;
     /** Records the decision in `identity_link_events`; `unlinkIdentity` undoes it. */
     linkIdentities(person: IdentityRef, other: IdentityRef, options: LinkOptions): Promise<PersonRecord>;
     unlinkIdentity(identity: IdentityRef, options: LinkOptions): Promise<PersonRecord>;

package/dist/store/people.js

@@ -2,6 +2,7 @@ import { keysOver } from "./keys.js";
 import * as identities from "./sqlite/identities.js";
 import { linkToOwner } from "./sqlite/own-identities.js";
 import * as personLinks from "./sqlite/person-links.js";
+import { personPreparation } from "./sqlite/person-preparation.js";
 import { personSeenInAccounts } from "./sqlite/person-scope.js";
 import * as privatePeople from "./sqlite/private-people.js";
 import { write } from "./sqlite/transaction.js";
@@ -55,6 +56,7 @@ export const peopleStoreOver = (context, keyed) => {
         personOf: async (identity) => personLinks.personOf(context, identity),
         personSeenInAccounts: async (uid, accountIds) => personSeenInAccounts(context, uid, accountIds),
         personByUid: async (uid) => personLinks.personByUid(context, uid),
+        preparation: async (uid, options) => personPreparation(context, uid, options),
         linkIdentities: async (person, other, options) => {
             return write(database, () => personLinks.linkIdentities(context, person, other, options));
         },

package/dist/store/sqlite/person-preparation.d.ts

@@ -0,0 +1,48 @@
+import type { AccountKey } from "../types.js";
+import type { StoreContext } from "./open.js";
+export interface PreparationFact {
+    ref: string;
+    type: string;
+    statement: string;
+    subject: string | null;
+    project: string | null;
+    updatedAt: string;
+}
+export interface PreparationNote {
+    ref: string;
+    title: string | null;
+    text: string;
+    revision: number;
+    updatedAt: string;
+}
+export interface PreparationTask {
+    ref: string;
+    title: string;
+    role: string;
+    dueAt: string | null;
+    project: string;
+    source: string | null;
+    createdAt: string;
+}
+export interface PersonPreparationRead {
+    facts: {
+        items: PreparationFact[];
+        hasMore: boolean;
+    };
+    notes: {
+        items: PreparationNote[];
+        hasMore: boolean;
+    };
+    tasks: {
+        items: PreparationTask[];
+        hasMore: boolean;
+    };
+}
+/**
+ * The accepted facts, the owner's notes and the open tasks about one person. A project bound to an account is that
+ * account's: its facts never come along, and its tasks only when `accounts` holds it.
+ */
+export declare const personPreparation: ({ database }: Pick<StoreContext, "database">, uid: string, { accounts, limit }: {
+    accounts: readonly AccountKey[];
+    limit: number;
+}) => PersonPreparationRead;

package/dist/store/sqlite/person-preparation.js

@@ -0,0 +1,72 @@
+import { CliError } from "@wirecat/cli-base";
+import { linkKind } from "./link-kinds.js";
+import { taskIdOf } from "./things.js";
+import { read } from "./transaction.js";
+const GLOBAL_PROJECT = "SELECT id FROM main.projects WHERE account_id IS NULL AND deleted_at IS NULL";
+const iso = (value) => (value == null ? null : new Date(Number(value)).toISOString());
+/**
+ * The accepted facts, the owner's notes and the open tasks about one person. A project bound to an account is that
+ * account's: its facts never come along, and its tasks only when `accounts` holds it.
+ */
+export const personPreparation = ({ database }, uid, { accounts, limit }) => {
+    const person = Number(uid);
+    if (!/^[1-9]\d*$/.test(uid) || !Number.isSafeInteger(person) || !Number.isSafeInteger(limit) || limit < 1)
+        throw new CliError("validation_error", "person preparation takes a person id and a positive limit");
+    const page = (rows) => ({ items: rows.slice(0, limit), hasMore: rows.length > limit });
+    return read(database, () => {
+        const projects = `SELECT l.to_id FROM links l WHERE l.from_type='person' AND l.from_id=? AND l.to_type='project'
+      AND l.kind=${linkKind("member-of")} AND l.confirmed=1 AND l.to_id IN (${GLOBAL_PROJECT})`;
+        const facts = database
+            .prepare(`SELECT f.id,f.type,f.statement,f.subject_type,f.subject_id,f.project_id,f.updated_at FROM facts f
+        WHERE f.status='accepted' AND f.deleted_at IS NULL
+        AND ((f.subject_type='person' AND f.subject_id=?) OR (f.subject_type='project' AND f.subject_id IN (${projects}))
+          OR f.project_id IN (${projects}))
+        AND (f.subject_type IS NOT 'project' OR f.subject_id IN (${GLOBAL_PROJECT}))
+        AND (f.project_id IS NULL OR f.project_id IN (${GLOBAL_PROJECT}))
+        ORDER BY f.updated_at DESC, f.id DESC LIMIT ?`)
+            .all(person, person, person, limit + 1)
+            .map((row) => ({
+            ref: `fact:${row.id}`,
+            type: String(row.type),
+            statement: String(row.statement),
+            subject: row.subject_type == null ? null : `${row.subject_type}:${row.subject_id}`,
+            project: row.project_id == null ? null : `project:${row.project_id}`,
+            updatedAt: iso(row.updated_at),
+        }));
+        const notes = database
+            .prepare(`SELECT n.id,n.title,n.body,n.revision,n.updated_at FROM notes n
+        JOIN persons owner ON n.author_type='person' AND n.author_id=owner.id AND owner.owner=1
+        WHERE n.deleted_at IS NULL
+        AND ((n.notable_type='person' AND n.notable_id=?) OR EXISTS(SELECT 1 FROM links l WHERE l.from_type='note'
+          AND l.from_id=n.id AND l.to_type='person' AND l.to_id=? AND l.kind=${linkKind("about")} AND l.confirmed=1))
+        AND (n.notable_type='person' OR (n.notable_type='project' AND n.notable_id IN (${GLOBAL_PROJECT})))
+        ORDER BY n.updated_at DESC, n.id DESC LIMIT ?`)
+            .all(person, person, limit + 1)
+            .map((row) => ({
+            ref: `note:${row.id}`,
+            title: row.title == null ? null : String(row.title),
+            text: String(row.body),
+            revision: Number(row.revision),
+            updatedAt: iso(row.updated_at),
+        }));
+        const tasks = database
+            .prepare(`SELECT t.id,t.title,t.due_at,t.project_id,t.source_locator,t.created_at,group_concat(DISTINCT ta.role) AS role
+        FROM task_assignments ta JOIN tasks t ON t.id=ta.task_id JOIN main.projects p ON p.id=t.project_id
+        WHERE ta.assignee_type='person' AND ta.assignee_id=? AND t.deleted_at IS NULL AND t.status='open'
+        AND p.deleted_at IS NULL AND (p.account_id IS NULL OR p.account_id IN (SELECT a.id FROM accounts a
+          JOIN json_each(?) k ON a.provider=json_extract(k.value,'$.provider')
+          AND a.external_id=json_extract(k.value,'$.account')))
+        GROUP BY t.id ORDER BY t.due_at IS NULL, t.due_at, t.created_at, t.id LIMIT ?`)
+            .all(person, JSON.stringify(accounts.map(({ provider, account }) => ({ provider, account }))), limit + 1)
+            .map((row) => ({
+            ref: `task:${taskIdOf(database, Number(row.id))}`,
+            title: String(row.title),
+            role: String(row.role),
+            dueAt: iso(row.due_at),
+            project: `project:${row.project_id}`,
+            source: row.source_locator == null ? null : String(row.source_locator),
+            createdAt: iso(row.created_at),
+        }));
+        return { facts: page(facts), notes: page(notes), tasks: page(tasks) };
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.393.0",
+  "version": "0.394.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",

package/parity.json

@@ -2816,6 +2816,13 @@
     "contacts notes show": {
       "in": "all"
     },
+    "contacts prepare": {
+      "in": "all",
+      "options": {
+        "--limit": "all",
+        "--since-time": "all"
+      }
+    },
     "contacts profile": {
       "in": "all",
       "options": {