@wirecat/cli-core 0.581.0 → 0.583.0

package/CHANGELOG.md

@@ -7,6 +7,60 @@ shape of this file.
 
 ## Unreleased
 
+## 0.583.0 — 05.11.2026
+
+### Changed — may break callers
+
+- **`--compact` says a day once above its rows in a list in time order.** When a list's rows are sorted by time and
+  a day holds three rows on average, a `# YYYY-MM-DD` line opens each day and its rows print only `HH:MM`. A
+  1,000-message `messages list` drops from 43 % to 41 % of JSON's tokens (53 % to 52 % of its bytes). A reader that
+  parsed `MM-DD HH:MM` from such a row reads the day from the line above it. Searches and other unsorted lists are
+  unchanged.
+- **An item answer's compact sections share one span line.** The days and zone are printed once, as
+  `# <first>…<last> · <zone>` above the first section, not on every section's header (`projects status`,
+  `projects evidence`).
+- **`projects status` leaves out what the answer already says.** `item.window` is gone (it is `meta.window`). A
+  listed item drops `chat` when its `ref` is a message of that chat, drops `basis` when it is `store`, and a promise
+  drops `data.source`, which equals its `basis`. `who.name` and a chat row's `role` are left out instead of `null`.
+  The promise row of `--compact` prints `basis`. On the E7 fixture JSON goes from 3,998 to 3,676 bytes and compact
+  from 1,511 to 1,387.
+- **Every mail finding kind needs `reason`.** A fact, a memory and a new contact had none or an optional one; the
+  owner reads it beside each finding when he decides. A missing field is refused with its name, the finding and what
+  that kind needs (`finding.missing-field`, `details.fields`, `details.needs`). Batches staged before keep theirs.
+
+### Added
+
+- **`invoices` takes `number`.** `finance.invoices({ number })` lists the invoices whose printed number is exactly
+  that, as `orders.list({ number })` does for orders.
+- **`MAIL_FINDING_FIELDS` and `mailFindingFieldsHelp()`.** The fields each mail finding kind needs and takes, the
+  table the validator itself reads, so a host's `--help` lists them without drifting from the checks.
+
+### Fixed
+
+- **A `messages reset` that leaves the mark where it is still counts.** It adds to `resets`, so the holder's next
+  findings key is new, and says "mark unchanged … counted as a reset"; the answer gives `resets`. Before, it wrote
+  nothing, and a run after it was refused with `mail-findings.key-used`.
+- **`review --holder` gives no `mail-findings.add` step when it gives no emails.**
+- **A task finding's `due_at` refusals say what is needed.** A date without a time and timezone, `due_at` without
+  `due_evidence`, and `due_evidence` given as evidence objects each name the field and show the right form, such as
+  `"due_at":"2026-11-09T09:00:00Z","due_evidence":["<reference>"]`.
+
+## 0.582.0 — 05.11.2026
+
+### Added
+
+- **`knowledge.updateOrganization(organization, { name })` renames an organization**, given as `organization:<id>` or
+  by its id; its kind and scope stay. An agent's rename is a proposal for the owner: the `organization_rename`
+  proposal kind and `proposeOrganizationRename(store, { organization, name }, by, reason?)`. It shows in `review` as
+  an `organization` row (`rename organization:3 to ...`); confirming it renames, rejecting it changes nothing. No
+  schema change.
+
+### Fixed
+
+- **`knowledge.organizations` answers a `name:` term.** `ORGANIZATIONS_QUERY` listed `name`, but the store had no
+  column for it, so `organizations list name:acme` failed. The match ignores case in any script, and `name:*acme*`
+  finds a name that holds a word.
+
 ## 0.581.0 — 05.11.2026
 
 ### Added

package/dist/cli/compact.js

@@ -200,7 +200,9 @@ const cellOf = (item, column, clock) => {
             if (!parts)
                 return { text: clean(iso) };
             const day = parts.date.slice(5);
-            return { text: column.as === "day" ? day : `${day} ${parts.time}`, date: parts.date };
+            return column.as === "day"
+                ? { text: day, date: parts.date }
+                : { text: `${day} ${parts.time}`, date: parts.date, time: parts.time };
         }
         case "count":
             return typeof value === "number" && value !== 0
@@ -255,6 +257,22 @@ const sameEverywhere = (rows, index) => {
     const first = rows[0]?.cells[index]?.text;
     return first !== undefined && rows.every(({ cells }) => cells[index]?.text === first);
 };
+const ordered = (dates) => dates.every((one, at) => at === 0 || one >= dates[at - 1]) ||
+    dates.every((one, at) => at === 0 || one <= dates[at - 1]);
+/**
+ * The column whose date is said once on a `# YYYY-MM-DD` line above its rows: a list in time order, such as a chat's
+ * messages. Only when days hold three rows on average: with fewer, the day lines cost more than they save.
+ */
+const dayColumn = (rows, shape, hoisted) => {
+    const index = shape.columns.findIndex((column, at) => column.as === "time" && !hoisted[at]);
+    if (index < 0)
+        return -1;
+    const dates = rows.map(({ cells }) => cells[index]?.date);
+    if (dates.some((one) => one === undefined))
+        return -1;
+    const days = dates;
+    return ordered(days) && new Set(days).size * 3 <= days.length ? index : -1;
+};
 const rowsOfItems = (items, shape, clock, chars) => {
     const dates = [];
     const rows = items.map((item) => {
@@ -277,17 +295,30 @@ const rowsOfItems = (items, shape, clock, chars) => {
             return [];
         return [`${sourceOf(item, column) ?? fieldsOfColumn(column.field)[0]}: ${rows[0]?.cells[index]?.text}`];
     });
-    const lines = rows.map(({ cells, text, item }) => {
+    const byDay = dayColumn(rows, shape, hoisted);
+    let shownDay;
+    const lines = rows.flatMap(({ cells, text, item }) => {
         const parts = cells.map((cell, index) => (hoisted[index] ? undefined : cell?.text));
+        const dayLine = [];
+        const cell = cells[byDay];
+        if (byDay >= 0 && cell?.date && cell.time) {
+            if (cell.date !== shownDay)
+                dayLine.push(`# ${cell.date}`);
+            shownDay = cell.date;
+            parts[byDay] = cell.time;
+        }
         const shortened = prefix ? clean(prefix) : undefined;
         if (shortened && parts[0]?.startsWith(shortened))
             parts[0] = `#${parts[0].slice(shortened.length)}`;
         const shown = [...parts, text].filter((part) => part !== undefined && part !== "");
-        return guarded(shown.length ? shown.join(" · ") : item ? blockLine(item, chars) : "");
+        return [...dayLine, guarded(shown.length ? shown.join(" · ") : item ? blockLine(item, chars) : "")];
     });
+    const header = [...(prefix ? [`ref: ${clean(prefix)}<id>`] : []), ...named];
+    return { header, lines, dates };
+};
+const spanOf = (dates, clock) => {
     const when = span(dates);
-    const header = [...(prefix ? [`ref: ${clean(prefix)}<id>`] : []), ...named, ...(when ? [when, clock.zone] : [])];
-    return { header, lines };
+    return when ? [when, clock.zone] : [];
 };
 const blockLine = (fields, chars) => blockOf(fields, chars).join("  ");
 /** A record as `field: value` lines; a nested record is indented under its field, a list of records counted. */
@@ -352,20 +383,26 @@ export const compactText = (body, shape, options, rowsOf = rowsOfEntity()) => {
     const chars = options.textChars ?? TEXT_CHARS;
     let lines = [];
     if ("items" in body) {
-        const { header, lines: rows } = rowsOfItems(body.items, shape, clock, chars);
-        lines = (header.length ? [`# ${header.join(" · ")}`] : []).concat(rows.length ? rows : ["# nothing found"]);
+        const { header, lines: rows, dates } = rowsOfItems(body.items, shape, clock, chars);
+        const head = [...header, ...spanOf(dates, clock)];
+        lines = (head.length ? [`# ${head.join(" · ")}`] : []).concat(rows.length ? rows : ["# nothing found"]);
     }
     else if (isFields(body.item)) {
         const sections = shape.sections ?? {};
         const rest = Object.fromEntries(Object.entries(body.item).filter(([name]) => !Object.hasOwn(sections, name) && !shape.hidden?.includes(name)));
         lines = blockOf(rest, chars, "", shape.whole).map(guarded);
+        let dates = [];
+        let drawn = [];
         for (const [name, entity] of Object.entries(sections)) {
             const list = body.item[name];
             if (!Array.isArray(list))
                 continue;
-            const { header, lines: rows } = rowsOfItems(list, rowsOf(entity), clock, chars);
-            lines = lines.concat([`# ${[`${clean(name)}: ${list.length}`, ...header].join(" · ")}`], rows);
+            const { header, lines: rows, dates: more } = rowsOfItems(list, rowsOf(entity), clock, chars);
+            dates = dates.concat(more);
+            drawn = drawn.concat([`# ${[`${clean(name)}: ${list.length}`, ...header].join(" · ")}`], rows);
         }
+        const when = spanOf(dates, clock);
+        lines = lines.concat(when.length ? [`# ${when.join(" · ")}`] : [], drawn);
     }
     else if (present(body.item))
         lines = [guarded(cut(clean(String(body.item)), chars))];

package/dist/cli/index.d.ts

@@ -6,6 +6,7 @@ export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
 export { type AppErrors, failureContext } from "../errors/reasons.js";
+export { mailFindingFieldsHelp } from "../mail/findings.js";
 export { botInstructions } from "../mcp/bot/instructions.js";
 export type { BotServerOptions, RunBotCommand } from "../mcp/bot/server.js";
 export type { HttpOptions } from "../mcp/http/serve.js";

package/dist/cli/index.js

@@ -5,6 +5,7 @@ export { botTemplate } from "../entities/list-results.js";
 export { syncProgress } from "../entities/store-records.js";
 export { isCliFailure, isCommanderFailure } from "../errors/failures.js";
 export { failureContext } from "../errors/reasons.js";
+export { mailFindingFieldsHelp } from "../mail/findings.js";
 export { botInstructions } from "../mcp/bot/instructions.js";
 export { callMeetingPreparationTool, meetingPreparationTool } from "../mcp/meeting-preparation.js";
 export { callMeetingProjectCandidatesTool, meetingProjectCandidatesTool } from "../mcp/meeting-project-candidates.js";

package/dist/cli/project-status-rows.js

@@ -15,7 +15,7 @@ export const STATUS_SIGNAL_ROWS = {
         columns: [
             ...where,
             { field: "at", as: "day" },
-            { field: "data.source" },
+            { field: "basis" },
             { field: "data.side" },
             { field: "data.due", as: "day" },
             { field: "data.status" },

package/dist/cli/project-status.d.ts

@@ -27,10 +27,6 @@ export declare const projectStatusSchema: v.LooseObjectSchema<{
     readonly project: v.StringSchema<undefined>;
     readonly key: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly name: v.StringSchema<undefined>;
-    readonly window: v.StrictObjectSchema<{
-        readonly since: v.StringSchema<undefined>;
-        readonly until: v.StringSchema<undefined>;
-    }, undefined>;
     /** Each signal's version, so a saved answer says which rules made it. */
     readonly signals: v.RecordSchema<v.StringSchema<undefined>, v.NumberSchema<undefined>, undefined>;
     readonly money: v.ArraySchema<v.StrictObjectSchema<{
@@ -43,7 +39,7 @@ export declare const projectStatusSchema: v.LooseObjectSchema<{
         readonly chat: v.StringSchema<undefined>;
         readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly kind: v.StringSchema<undefined>;
-        readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly role: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly purpose: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly project: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         readonly coverage: v.StringSchema<undefined>;
@@ -54,7 +50,7 @@ export declare const projectStatusSchema: v.LooseObjectSchema<{
             readonly at: v.StringSchema<undefined>;
             readonly who: v.StrictObjectSchema<{
                 readonly ref: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
-                readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
                 readonly owner: v.BooleanSchema<undefined>;
             }, undefined>;
         }, undefined>, undefined>;
@@ -100,10 +96,6 @@ export declare const projectStatusAnswer: (found: ProjectStatus, hints: ProjectS
         project: string;
         key: string | null;
         name: string;
-        window: {
-            since: string;
-            until: string;
-        };
         signals: {
             [x: string]: number;
         };
@@ -117,7 +109,7 @@ export declare const projectStatusAnswer: (found: ProjectStatus, hints: ProjectS
             chat: string;
             title: string | null;
             kind: string;
-            role: string | null;
+            role?: string | undefined;
             purpose?: string | undefined;
             project?: string | undefined;
             coverage: string;
@@ -128,7 +120,7 @@ export declare const projectStatusAnswer: (found: ProjectStatus, hints: ProjectS
                 at: string;
                 who: {
                     ref?: string | undefined;
-                    name: string | null;
+                    name?: string | undefined;
                     owner: boolean;
                 };
             } | undefined;

package/dist/cli/project-status.js

@@ -13,21 +13,23 @@ const SECTIONS = {
 /** The `project_status` answer drawn by `--compact`: a row per chat, then each listed signal with its own row. */
 export const projectStatusRow = (signals) => ({
     columns: [],
-    hidden: ["project", "window", "purposes", "signals"],
+    hidden: ["project", "purposes", "signals"],
     sections: {
         ...SECTIONS,
         ...Object.fromEntries(signals.flatMap(({ id }) => (ON_CHAT_ROW.has(id) ? [] : [[listKey(id), `status.${id}`]]))),
     },
 });
-const who = v.strictObject({ ref: v.optional(v.string()), name: v.nullable(v.string()), owner: v.boolean() });
+const who = v.strictObject({ ref: v.optional(v.string()), name: v.optional(v.string()), owner: v.boolean() });
 const statusItem = v.looseObject({
     ref: v.nullable(v.string()),
-    chat: v.nullable(v.string()),
+    /** Left out when `ref` is a message of that chat. */
+    chat: v.optional(v.nullable(v.string())),
     at: v.nullable(v.string()),
     who: v.optional(who),
     /** Every ref the item cites, when it cites more than `ref`. */
     evidence: v.optional(v.array(v.string())),
-    basis: v.picklist(["store", "fact", "task", "pattern"]),
+    /** Left out for `store`, what most items are read from. */
+    basis: v.optional(v.picklist(["fact", "task", "pattern"])),
     data: v.record(v.string(), v.unknown()),
 });
 /** Where a project stands: per chat signals, open money, and what was left out. Empty lists are left out. */
@@ -35,7 +37,6 @@ export const projectStatusSchema = v.looseObject({
     project: v.string(),
     key: v.nullable(v.string()),
     name: v.string(),
-    window: v.strictObject({ since: v.string(), until: v.string() }),
     /** Each signal's version, so a saved answer says which rules made it. */
     signals: v.record(v.string(), v.number()),
     money: v.array(v.strictObject({ direction: v.string(), currency: v.nullable(v.string()), amount: v.string(), rows: v.number() })),
@@ -43,7 +44,7 @@ export const projectStatusSchema = v.looseObject({
         chat: v.string(),
         title: v.nullable(v.string()),
         kind: v.string(),
-        role: v.nullable(v.string()),
+        role: v.optional(v.string()),
         purpose: v.optional(v.string()),
         project: v.optional(v.string()),
         coverage: v.string(),
@@ -139,14 +140,33 @@ const missingOf = (found, hints) => {
         ...found.failed.map((one) => ({ field: `signal:${one.signal}`, why: one.why })),
     ];
 };
-const whoOf = (one) => one === null ? {} : { who: { ...(one.ref === null ? {} : { ref: one.ref }), name: one.name, owner: one.owner } };
-/** An item as listed: its first ref, every ref only when there are more. */
-const listed = ({ signal: _signal, who, evidence, ...one }) => ({
-    ...one,
-    ref: evidence[0]?.ref ?? one.chat,
-    ...whoOf(who),
-    ...(evidence.length > 1 ? { evidence: evidence.map((each) => each.ref) } : {}),
-});
+const whoOf = (one) => one === null
+    ? {}
+    : {
+        who: {
+            ...(one.ref === null ? {} : { ref: one.ref }),
+            ...(one.name === null ? {} : { name: one.name }),
+            owner: one.owner,
+        },
+    };
+const inChat = (ref, chat) => ref !== null && chat !== null && (ref === chat || ref.startsWith(`msg:${chat.slice("chat:".length)}/`));
+/**
+ * An item as listed: its first ref, every ref only when there are more. What the rest of the item already says is
+ * left out: the chat its message ref names, the `store` basis, and a promise's `source`, which is its basis.
+ */
+const listed = ({ signal: _signal, who, evidence, chat, basis, data, ...one }) => {
+    const ref = evidence[0]?.ref ?? chat;
+    const { source, ...rest } = data;
+    return {
+        ...(inChat(ref, chat) ? {} : { chat }),
+        ...one,
+        ...(basis === "store" ? {} : { basis }),
+        data: source === basis ? rest : data,
+        ref,
+        ...whoOf(who),
+        ...(evidence.length > 1 ? { evidence: evidence.map((each) => each.ref) } : {}),
+    };
+};
 /**
  * Low signal items, counted on their chat's row instead of listed: questions others ask in a group with no role (a
  * leads group's requests), promises found by words that others wrote in a group, and past the newest one per chat.
@@ -194,7 +214,7 @@ const chatRow = (found, hints, chat, unlisted) => {
         chat: chat.ref,
         title: chat.title,
         kind: chat.kind,
-        role: chat.role,
+        ...(chat.role === null ? {} : { role: chat.role }),
         ...(Array.isArray(found.purposes) && found.purposes.length === 1 ? {} : { purpose: chat.purpose }),
         ...(chat.project === found.project.ref ? {} : { project: chat.project }),
         coverage: chat.coverage.completeness.state,
@@ -225,7 +245,6 @@ export const projectStatusAnswer = (found, hints) => {
         project: found.project.ref,
         key: found.project.key,
         name: found.project.name,
-        window: found.window,
         signals: Object.fromEntries(found.signals.map(({ id, version }) => [id, version])),
         money: found.money.open,
         chats: found.chats.map((chat) => chatRow(found, hints, chat, [...unlisted].filter((one) => one.chat === chat.ref))),

package/dist/entities/index.d.ts

@@ -5936,6 +5936,7 @@ export declare const ENTITIES: {
                 readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
                 readonly statement: v.StringSchema<undefined>;
+                readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             }, undefined>, v.StrictObjectSchema<{
                 readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
                 readonly evidence: v.ArraySchema<v.StrictObjectSchema<{
@@ -5960,6 +5961,7 @@ export declare const ENTITIES: {
                 readonly body: v.StringSchema<undefined>;
                 readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
                 readonly project: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+                readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
             }, undefined>, v.StrictObjectSchema<{
                 readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
                 readonly evidence: v.ArraySchema<v.StrictObjectSchema<{

package/dist/entities/mail-findings.d.ts

@@ -41,6 +41,8 @@ export declare const mailFindings: v.StrictObjectSchema<{
             readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
             readonly statement: v.StringSchema<undefined>;
+            /** Every new finding gives one; a batch staged before reason was needed on every kind has none. */
+            readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, v.StrictObjectSchema<{
             readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
             readonly evidence: v.ArraySchema<v.StrictObjectSchema<{
@@ -65,6 +67,7 @@ export declare const mailFindings: v.StrictObjectSchema<{
             readonly body: v.StringSchema<undefined>;
             readonly subject: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
             readonly project: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+            readonly reason: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
         }, undefined>, v.StrictObjectSchema<{
             readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
             readonly evidence: v.ArraySchema<v.StrictObjectSchema<{

package/dist/entities/mail-findings.js

@@ -30,6 +30,8 @@ const finding = v.variant("kind", [
         subject: v.optional(reference),
         type: v.picklist(FACT_TYPES),
         statement: text,
+        /** Every new finding gives one; a batch staged before reason was needed on every kind has none. */
+        reason: v.optional(text),
     }),
     v.strictObject({
         ...base,
@@ -48,6 +50,7 @@ const finding = v.variant("kind", [
         body: text,
         subject: v.optional(reference),
         project: v.optional(reference),
+        reason: v.optional(text),
     }),
     v.strictObject({ ...base, kind: v.literal("link"), from: reference, to: reference, reason: text }),
     v.strictObject({ ...base, kind: v.literal("new_contact"), address: text, name: text, reason: v.optional(text) }),

package/dist/errors/reasons.js

@@ -65,6 +65,7 @@ const OTHERS = [
     validation("mail-findings.invalid", "a checked mail findings batch would be refused; details.problems names why, finding by finding"),
     validation("mail-findings.key-used", "the findings batch key was already used for different input"),
     validation("finding.unknown-field", "a finding has a field its kind does not take"),
+    validation("finding.missing-field", "a finding leaves out a field its kind needs"),
     validation("document.changed", "the document changed while it was read; nothing was saved"),
     ["document.not-imported", "not_found", "the document is not imported in this source account"],
     ["extraction.invalid-proposals", "invalid_response", "the model's memory proposals could not be used"],

package/dist/mail/cli/marks.js

@@ -78,6 +78,8 @@ const mailMarkReset = v.strictObject({
     bulk: v.number(),
     /** Emails between the two marks it skips again: drafts, envelopes, suspicious senders, partial mail. */
     skipped: v.number(),
+    /** How often the owner moved this mark back, this reset counted even when the mark stays: the findings key names it. */
+    resets: v.number(),
     /** Nothing moved: `--dry-run` only counts. */
     dry_run: v.boolean(),
 });
@@ -102,7 +104,8 @@ export const resetMarkCommand = (mail) => answerEntity(annotate(new Command("res
     .summary("move a holder's processing mark back, so it reads that mail again (owner only)")
     .description("the owner moves a holder's mark back past the mail received since --since-time, or past the last --last " +
     "emails it was given; its next reviews give that mail again. The answer says how many emails it reads " +
-    "again. An agent cannot: a holder only moves its own mark forward, with `messages acknowledge`")
+    "again. Every reset counts, even one that leaves the mark where it is, so the holder's next findings key " +
+    "is new. An agent cannot: a holder only moves its own mark forward, with `messages acknowledge`")
     .requiredOption("--holder <name>", "whose mark: lower-case letters, digits and dashes, such as mail-triage")
     .option("--since-time <time>", "read again what was received since this ISO 8601 time, or 2d ago")
     .option("--last <n>", "read again the last n emails the holder was given", wholeNumber)
@@ -125,12 +128,15 @@ export const resetMarkCommand = (mail) => answerEntity(annotate(new Command("res
         again: reset.again,
         bulk: reset.bulk,
         skipped: reset.skipped,
+        resets: reset.mark.resets,
         dry_run: reset.dry,
     };
     renderAnswer(this, outputFor(this), itemOf(item), () => {
         const mark = reset.mark.throughId === reset.fromId
-            ? `the mark stays at ${reset.fromId}`
-            : `the mark ${reset.dry ? "would move" : "moved"} from ${reset.fromId} to ${reset.mark.throughId}`;
+            ? `mark unchanged at ${reset.fromId}, ${reset.dry ? "would be counted" : "counted"} as a reset ` +
+                `(resets ${reset.mark.resets}): the next run gets a new findings key`
+            : `the mark ${reset.dry ? "would move" : "moved"} from ${reset.fromId} to ${reset.mark.throughId} ` +
+                `(resets ${reset.mark.resets})`;
         return (`${holder} ${reset.dry ? "would read" : "reads"} ${reset.again} emails again, and ${reset.bulk} bulk ` +
             `ones as excerpts unless they are newsletters; ${reset.skipped} are skipped again; ${mark}\n`);
     });

package/dist/mail/cli/review.js

@@ -208,7 +208,7 @@ const holderReview = async (command, mail, holder, query) => {
     const step = stepsFor(mail.mount, mailbox);
     const answer = reviewAnswer(found, mailbox, true, step);
     const skipped = Object.entries(read.skipped).filter(([, count]) => count > 0);
-    const stage = read.findingsKey === undefined ? [] : step("mail-findings.add", { key: read.findingsKey });
+    const stage = read.findingsKey === undefined || emails.length === 0 ? [] : step("mail-findings.add", { key: read.findingsKey });
     answer.next = [
         ...stage,
         ...step("mail-messages.acknowledge", { holder, cursor: read.cursor }),
@@ -233,7 +233,7 @@ const holderReview = async (command, mail, holder, query) => {
     const output = outputFor(command);
     renderAnswer(command, output, answer, () => {
         output.renderer.note(read.mark
-            ? `${holder}: past ${read.mark.throughId}; findings key ${read.findingsKey}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
+            ? `${holder}: past ${read.mark.throughId}${emails.length ? `; findings key ${read.findingsKey}` : ""}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
             : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
         return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id), hit.excerptOnly)}\n`).join("");
     });

package/dist/mail/findings.d.ts

@@ -11,7 +11,10 @@ interface Cited {
     evidence: FindingEvidence[];
 }
 export type MailTaskFinding = TaskFinding;
-export type MailFactFinding = FactFinding;
+/** The owner reads `reason` beside every finding when he decides it, so every kind gives one. */
+export type MailFactFinding = FactFinding & {
+    reason: string;
+};
 export interface MailTaskUpdateFinding extends Cited {
     kind: "task_update";
     task: string;
@@ -27,6 +30,7 @@ export interface MailMemoryFinding extends Cited {
     body: string;
     subject?: string;
     project?: string;
+    reason: string;
 }
 /** Address → person, person → organization, or thread → project. */
 export interface MailLinkFinding extends Cited {
@@ -39,7 +43,7 @@ export interface MailNewContactFinding extends Cited {
     kind: "new_contact";
     address: string;
     name: string;
-    reason?: string;
+    reason: string;
 }
 /** An invoice the mail carries; accepting it records the invoice through `store.finance`, confirmed. */
 export interface MailInvoiceFinding extends Cited {
@@ -139,6 +143,56 @@ export interface MailFindingsInput {
     extractor: string;
     findings: MailFinding[];
 }
+/**
+ * What each kind takes besides `id`, `kind` and `evidence`, in the order the validator reads them: `needs` it refuses
+ * without, `may` it takes. `--help`, `details.allowed` and `details.needs` all read this table, so they cannot drift
+ * from the checks. Some fields go together (due_at with due_evidence) or replace each other (counterparty or
+ * counterparty_name); the check of each kind says which.
+ */
+export declare const MAIL_FINDING_FIELDS: {
+    readonly task: {
+        readonly needs: readonly ["type", "title", "reason", "commitment"];
+        readonly may: readonly ["project", "dueAt", "dueEvidence", "assignee", "assigneeEvidence", "externalId", "sourceUrl"];
+    };
+    readonly task_update: {
+        readonly needs: readonly ["task", "change", "reason"];
+        readonly may: readonly ["dueAt", "detail"];
+    };
+    readonly fact: {
+        readonly needs: readonly ["type", "statement", "reason"];
+        readonly may: readonly ["subject", "project"];
+    };
+    readonly memory: {
+        readonly needs: readonly ["memoryKind", "scope", "body", "reason"];
+        readonly may: readonly ["subject", "project"];
+    };
+    readonly link: {
+        readonly needs: readonly ["from", "to", "reason"];
+        readonly may: readonly [];
+    };
+    readonly new_contact: {
+        readonly needs: readonly ["address", "name", "reason"];
+        readonly may: readonly [];
+    };
+    readonly invoice: {
+        readonly needs: readonly ["direction", "currency", "lines", "reason"];
+        readonly may: readonly ["counterparty", "counterpartyName", "counterpartyEmail", "total", "number", "issueDate", "dueDate", "project"];
+    };
+    readonly payment: {
+        readonly needs: readonly ["direction", "amount", "currency", "date", "reason"];
+        readonly may: readonly ["payer", "payerName", "payerEmail", "payee", "payeeName", "payeeEmail", "reference", "allocations", "project"];
+    };
+    readonly order: {
+        readonly needs: readonly ["purpose", "supplierName", "reason"];
+        readonly may: readonly ["customer", "customerName", "customerEmail", "supplier", "number", "total", "currency", "status", "orderDate", "fulfilledDate", "invoice", "payment", "project", "sourceUrl"];
+    };
+    readonly order_update: {
+        readonly needs: readonly ["supplierName", "number", "status", "reason"];
+        readonly may: readonly ["date"];
+    };
+};
+/** One line per kind, `kind: needed fields; optional ones`, for `mail findings add --help`. */
+export declare const mailFindingFieldsHelp: () => string;
 export declare const validateMailFindings: (input: MailFindingsInput) => MailFindingsInput;
 /** Why one finding, or the batch when `finding` is null, would be refused. */
 export interface MailFindingProblem {