@wirecat/cli-core 0.395.0 → 0.397.0

package/dist/cli/messenger/private-people-command.js

@@ -16,8 +16,8 @@ export const privatePeopleCommands = (messenger) => {
     const alias = new Command("alias").description("a private local display name in the selected account");
     annotate(alias.command("set"), { effects: LOCAL_WRITE })
         .description("your own name for a person in this account; kept on this machine, never sent")
-        .argument("<person>")
-        .argument("<alias>")
+        .argument("<person>", "the person's id, reference or known name")
+        .argument("<alias>", "the private name to use for this person")
         .action(async function (person, value) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "contacts.alias.set");
@@ -25,7 +25,7 @@ export const privatePeopleCommands = (messenger) => {
     });
     annotate(alias.command("rm"), { effects: LOCAL_WRITE })
         .description("drop your local name for a person; their own name shows again")
-        .argument("<person>")
+        .argument("<person>", "the person's id, reference or known name")
         .action(async function (person) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "contacts.alias.rm");
@@ -34,7 +34,7 @@ export const privatePeopleCommands = (messenger) => {
     const notes = new Command("notes").description("your private notes on a stored contact, the same in every account that sees them");
     withQuery(annotate(notes.command("list"), { effects: LOCAL_READ })
         .description("every private note you keep on a person, oldest first")
-        .argument("<person>"), NOTES_QUERY).action(async function (person, words) {
+        .argument("<person>", "the person's id, reference or known name"), NOTES_QUERY).action(async function (person, words) {
         const context = messengerContext(this, messenger);
         listQuery(typedQuery(words), NOTES_QUERY, "contacts notes list");
         const items = await context.withServices((services) => services.privatePeople.notes(person));
@@ -42,8 +42,8 @@ export const privatePeopleCommands = (messenger) => {
     });
     annotate(notes.command("show"), { effects: LOCAL_READ, output: { entity: "contact_note" } })
         .description("one private note on a person, with its revision for edit")
-        .argument("<person>")
-        .argument("<id>")
+        .argument("<person>", "the person's id, reference or known name")
+        .argument("<id>", "the note id from contacts notes list")
         .action(async function (person, id) {
         const context = messengerContext(this, messenger);
         renderAnswer(this, context, itemOf(await context.withServices((services) => services.privatePeople.note(person, id))));
@@ -56,10 +56,12 @@ export const privatePeopleCommands = (messenger) => {
             .description(name === "add"
             ? "add a private note on a person from stdin or --file; never sent"
             : "replace a note's text; --revision must match the one you read")
-            .argument("<person>")
+            .argument("<person>", "the person's id, reference or known name")
             .addOption(ownerOnlyOption("--file <path>", "read note text from a file; omitted or - reads stdin"));
         if (name === "edit")
-            command.argument("<id>").requiredOption("--revision <n>", "the revision you read before editing");
+            command
+                .argument("<id>", "the note id from contacts notes list")
+                .requiredOption("--revision <n>", "the revision you read before editing");
         command.action(async function (person, id) {
             const context = messengerContext(this, messenger);
             refuseLocalWrite(context, messenger.app.command, `contacts.notes.${name}`);
@@ -76,8 +78,8 @@ export const privatePeopleCommands = (messenger) => {
     }
     annotate(notes.command("remove"), { effects: LOCAL_WRITE })
         .description("delete one private note on a person")
-        .argument("<person>")
-        .argument("<id>")
+        .argument("<person>", "the person's id, reference or known name")
+        .argument("<id>", "the note id from contacts notes list")
         .action(async function (person, id) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "contacts.notes.remove");

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

@@ -25,6 +25,7 @@ const selectionOf = (value) => {
 };
 export const rankingsTopCommand = (messenger, target) => {
     const command = syncOptions(annotate(new Command("top"), { effects: REMOTE_READ, output: { entity: "ranking" } }), messenger)
+        .summary("rank messages or people by a measure or score")
         .description(`rank ${target === "messages" ? "stored messages" : "the human authors of stored messages"} by a measure or explainable score; counters are snapshots with per-field observation freshness`)
         .argument("[query...]", "a strict Lucene query; none selects every stored message")
         .addOption(new Option("--measure <name>", "the ranking metric; not with score or weights").choices(target === "messages" ? [...MESSAGE_MEASURES] : [...AUTHOR_MEASURES]))
@@ -86,6 +87,7 @@ const emojiSplit = (reactions) => [
     ...(reactions.length > SHOWN_REACTIONS ? [`+${reactions.length - SHOWN_REACTIONS}`] : []),
 ].join(" · ");
 export const rankingEvidenceCommand = (messenger, target) => annotate(new Command("evidence"), { effects: LOCAL_READ, output: { entity: "evidence" } })
+    .summary("evidence for an exact statistics selection")
     .description("bounded messages, answer pairs or retention members from an exact drilldown selection")
     .argument(target === "messages" ? "<message>" : "<person>", target === "messages"
     ? "the canonical message locator, or retention cohort reference, from drilldown"

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

@@ -6,7 +6,10 @@ import { messengerContext } from "./context.js";
 /** `reactions add|remove`: the owner's own reaction on a message. */
 export const reactionsCommand = (messenger) => {
     const reactions = new Command("reactions").description("react to messages");
-    annotate(reactions.command("add"), { effects: REMOTE_WRITE })
+    annotate(reactions.command("add"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal reactions add "Book club" 101 👍`],
+    })
         .description("put your reaction on a message; it replaces the one you had")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the message id")
@@ -16,7 +19,10 @@ export const reactionsCommand = (messenger) => {
         const reacted = await context.withServices((services) => services.messages.react({ chat, message: message.trim(), emoji: emoji.trim() }));
         renderAnswer(this, context, itemOf(snakeKeys(reacted)));
     });
-    annotate(reactions.command("remove"), { effects: REMOTE_WRITE })
+    annotate(reactions.command("remove"), {
+        effects: REMOTE_WRITE,
+        examples: [`${messenger.app.command} personal reactions remove "Book club" 101`],
+    })
         .description("take your reaction off a message")
         .argument("<chat>", messenger.chatArgument)
         .argument("<message>", "the message id")

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

@@ -6,6 +6,7 @@ import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
 import { refuseJsonl, retentionAnswer } from "./stats-answers.js";
 export const retentionCommand = (messenger) => annotate(new Command("retention"), { effects: REMOTE_READ, output: { entity: "retention" } })
+    .summary("joining cohorts and observed membership checkpoints")
     .description("joining cohorts and observed checkpoint membership from saved roster observations")
     .argument("<chat>", messenger.chatArgument)
     .option("--since-time <time>", "joining period starts at ISO 8601 or a relative time; last 90 days by default")

package/dist/cli/messenger/review.js

@@ -29,6 +29,7 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
     output: { entity: "message", view: "summary" },
     query: REVIEW_QUERY,
 })
+    .summary("chats with new activity or unanswered messages")
     .description("every message, yours too, in chats that changed since a point — for reviewing who owes what")
     .addHelpText("after", queryHelp(REVIEW_QUERY))
     .argument("[query...]", `where the last review ended and which chat: date>2h, chat:"Book club"; ${REVIEW_DAYS} days ago if no date`)

package/dist/cli/messenger/search-answers.js

@@ -21,6 +21,8 @@ export const messageHitItem = (hit, query = "") => {
         excerpt: hit.excerpt ?? excerpt(hit.text, query),
         matched_in: hit.matchedIn,
         score: hit.score ?? undefined,
+        match: hit.match,
+        corrections: hit.corrections,
         found_in: hit.source,
         discovery: hit.discovery
             ? defined({

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

@@ -34,6 +34,7 @@ const maxMeetingsOf = (value) => {
 };
 const allCommand = (messenger) => {
     const command = annotate(new Command("all"), { effects: REMOTE_READ, partial: true })
+        .summary("search stored messages, notes and selected meeting transcripts")
         .description((messenger.serverSearch
         ? "search messenger messages and notes in the local store, and the messenger's server for messages " +
             "(--backend; notes are local only)"
@@ -95,6 +96,7 @@ const allCommand = (messenger) => {
     });
 };
 const notesCommand = (messenger) => annotate(new Command("notes"), { effects: LOCAL_READ, partial: true, output: { entity: "note", view: "hit" } })
+    .summary("find stored notes by words and filters")
     .description("search the notes — written in memo, or imported from a notes folder — by words and, with the local " +
     "text model, by meaning; each hit says which found it and what it links to")
     .argument("<query...>", 'strict Lucene query: words, "phrases", AND/OR/NOT, tag:, source:internal (written in memo) or source:file ' +
@@ -150,7 +152,9 @@ const notesCommand = (messenger) => annotate(new Command("notes"), { effects: LO
  * hierarchy"). `topics` only where the CLI has forum topics.
  */
 export const searchCommand = (messenger, { topics = false } = {}) => {
-    const search = new Command("search").description("find things by text: one resource when you know it (messages, notes), or search all across messages and notes; for mail, the separate memo CLI: memo search mail");
+    const search = new Command("search")
+        .summary("search the local archive")
+        .description("find things by text: one resource when you know it (messages, notes), or search all across messages and notes; for mail, the separate memo CLI: memo search mail");
     search
         .addCommand(allCommand(messenger))
         .addCommand(messagesSearchCommand(messenger))

package/dist/cli/messenger/searches-command.d.ts

@@ -1,4 +1,6 @@
 import { Command } from "commander";
 import { type Messenger } from "./context.js";
+/** `searches list` takes a query over the saved search fields, none of them a filter: the list is short and whole. */
+export declare const SEARCHES_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
 /** Saved searches and the history of `search messages` and `stats messages show`, in the local store only. */
 export declare const searchesCommand: (messenger: Messenger) => Command;

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

@@ -20,11 +20,20 @@ const line = ({ id, name, command, params, runs, lastRunAt }) => [
     `${runs} runs`,
     lastRunAt?.slice(0, 16).replace("T", " ") ?? "never run",
 ].join("  ");
-const SEARCHES_QUERY = unfilteredQuery("saved_search", savedSearch);
+/** `searches list` takes a query over the saved search fields, none of them a filter: the list is short and whole. */
+export const SEARCHES_QUERY = unfilteredQuery("saved_search", savedSearch);
 /** Saved searches and the history of `search messages` and `stats messages show`, in the local store only. */
 export const searchesCommand = (messenger) => {
-    const searches = new Command("searches").description("saved searches and the history of search messages and stats messages show, kept in the local store; --saved runs one");
-    annotate(searches.command("create"), { effects: LOCAL_WRITE, output: { entity: "saved_search" } })
+    const tool = `${messenger.app.command} personal`;
+    const searches = new Command("searches")
+        .summary("saved searches and their run history")
+        .description("saved searches and the history of search messages and stats messages show, kept in the local store; --saved runs one");
+    annotate(searches.command("create"), {
+        effects: LOCAL_WRITE,
+        output: { entity: "saved_search" },
+        examples: [`${tool} searches create project-drafts draft --chat "Project room"`],
+    })
+        .summary("save a search and its query")
         .description("save a search under a name without running it; search messages --saved <name> runs it")
         .argument("<name>", "up to 64 letters a–z, digits and hyphens, not only digits")
         .argument("[query...]", "the query, as for search messages; none matches every stored message")
@@ -63,7 +72,11 @@ export const searchesCommand = (messenger) => {
         const saved = await context.withServices((services) => services.searches.create(name, params, { replace: replace === true }));
         renderAnswer(this, context, itemOf(savedSearchItem(saved)), () => `${line(saved)}\n`);
     });
-    annotate(searches.command("show"), { effects: REMOTE_READ, output: { entity: "saved_search" } })
+    annotate(searches.command("show"), {
+        effects: REMOTE_READ,
+        output: { entity: "saved_search" },
+        examples: [`${tool} searches show project-drafts`],
+    })
         .description("one saved search or earlier run: its query, options and how often it ran")
         .argument("<name|id>", "a saved search's name, or the id of any row of searches history")
         .action(async function (reference) {
@@ -71,7 +84,7 @@ export const searchesCommand = (messenger) => {
         const found = await context.withServices((services) => services.searches.show(reference));
         renderAnswer(this, context, itemOf(savedSearchItem(found)), () => `${line(found)}\n`);
     });
-    withQuery(annotate(searches.command("list"), { effects: LOCAL_READ }), SEARCHES_QUERY)
+    withQuery(annotate(searches.command("list"), { effects: LOCAL_READ, examples: [`${tool} searches list`] }), SEARCHES_QUERY)
         .description("the saved searches, by name")
         .action(async function (words) {
         const context = messengerContext(this, messenger);
@@ -82,9 +95,10 @@ export const searchesCommand = (messenger) => {
         if (found.length === 0 && context.format === "pretty")
             context.renderer.note("no saved searches — `searches create <name> <query>` saves one");
     });
-    annotate(withPaging(annotate(searches.command("history"), { effects: LOCAL_READ })), {
+    annotate(withPaging(annotate(searches.command("history"), { effects: LOCAL_READ, examples: [`${tool} searches history --limit 10`] })), {
         output: { entity: "saved_search" },
     })
+        .summary("past searches and counts, without their results")
         .description("the searches and counts that ran, newest first — saved ones included; never their results")
         .action(async function () {
         const context = messengerContext(this, messenger);
@@ -97,7 +111,11 @@ export const searchesCommand = (messenger) => {
         if (found.items.length === 0 && context.format === "pretty")
             context.renderer.note("no searches ran yet");
     });
-    annotate(searches.command("delete"), { effects: LOCAL_WRITE, output: { entity: "saved_search" } })
+    annotate(searches.command("delete"), {
+        effects: LOCAL_WRITE,
+        output: { entity: "saved_search" },
+        examples: [`${tool} searches delete project-drafts`],
+    })
         .description("delete a saved search, or one run from the history")
         .argument("<name|id>", "a saved search's name, or the id of any row of searches history")
         .action(async function (reference) {
@@ -106,7 +124,7 @@ export const searchesCommand = (messenger) => {
         const deleted = await context.withServices((services) => services.searches.delete(reference));
         renderAnswer(this, context, itemOf(savedSearchItem(deleted)), () => `deleted ${deleted.name ?? `run ${deleted.id}`}\n`);
     });
-    annotate(searches.command("clear"), { effects: LOCAL_WRITE })
+    annotate(searches.command("clear"), { effects: LOCAL_WRITE, examples: [`${tool} searches clear`] })
         .description("empty the history; saved searches stay")
         .action(async function () {
         const context = messengerContext(this, messenger);

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

@@ -60,7 +60,9 @@ const lockProcess = (app, marker, serveArgv) => (context, system, logPath) => ({
  */
 export const serverCommand = (messenger, options = {}) => {
     const { app } = messenger;
-    const command = annotate(new Command("server"), { mcp: false }).description(`\`${app.command} serve\` in the background: start, stop, restart, status, logs; install adds a systemd or launchd unit`);
+    const command = annotate(new Command("server"), { mcp: false })
+        .summary("manage this profile's background server")
+        .description(`\`${app.command} serve\` in the background: start, stop, restart, status, logs; install adds a systemd or launchd unit`);
     const marker = (profile) => `${app.envPrefix}_SERVER=${profile}`;
     const serveArgv = options.serveArgv ?? ["serve"];
     const prepare = (self) => {
@@ -181,7 +183,9 @@ export const serverCommand = (messenger, options = {}) => {
         return ["--idle", idle];
     };
     const withIdle = (sub) => options.idle ? sub.option("--idle <duration>", "stop after this long with nobody using it — 15m, 1h") : sub;
-    withIdle(destroysNothing(annotate(command.command("start"), { effects: LOCAL_WRITE, examples: [`${app.command} personal server start`] })).description("start serve in the background — through the unit if one is installed — and answer once it connects")).action(async function () {
+    withIdle(destroysNothing(annotate(command.command("start"), { effects: LOCAL_WRITE, examples: [`${app.command} personal server start`] }))
+        .summary("start this profile's background server")
+        .description("start serve in the background — through the unit if one is installed — and answer once it connects")).action(async function () {
         await start(prepare(this), idleArgs(this));
     });
     destroysNothing(annotate(command.command("stop"), { effects: LOCAL_WRITE, examples: [`${app.command} personal server stop`] }))
@@ -199,6 +203,7 @@ export const serverCommand = (messenger, options = {}) => {
         await start(prepared, args);
     });
     annotate(command.command("status"), { effects: LOCAL_READ, examples: [`${app.command} personal server status`] })
+        .summary("this profile's background-server status")
         .description("whether serve runs for this profile, since when, who started it, and the unit if there is one")
         .action(async function () {
         const prepared = prepare(this);

package/dist/cli/messenger/store-maintenance-command.js

@@ -93,6 +93,7 @@ const refuseWhileServing = (command, messenger) => {
     }
 };
 const repairCommand = (messenger) => annotate(new Command("repair"), { effects: LOCAL_WRITE, mcp: false })
+    .summary("repair table shapes while keeping the old tables")
     .description("bring every table to this build's shape, deleting nothing: a table of the wrong shape is kept as a copy beside a new one")
     .option("--dry-run", "say what it would do, and change nothing")
     .action(async function () {
@@ -152,6 +153,7 @@ const copiesCommand = () => new Command("copies").description("the tables `store
     result(this, { path, deleted });
 }));
 const infoCommand = () => annotate(new Command("info"), { effects: LOCAL_READ, mcp: false })
+    .summary("the local archive's format, size and contents")
     .description("the store file: where it is, its size, its schema and how many rows it holds; changes nothing")
     .action(async function () {
     const path = storePath(environmentOf(this).env ?? process.env);
@@ -181,6 +183,7 @@ const infoCommand = () => annotate(new Command("info"), { effects: LOCAL_READ, m
  * newest message held, not `sync_ranges`: those are in message ids, which a chat list does not give.
  */
 const checkCommand = (messenger) => annotate(new Command("check"), { effects: LOCAL_READ, mcp: false })
+    .summary("check the local archive for problems")
     .description("whether the store is healthy — integrity, search indexes, disk, and which chats are behind")
     .action(async function () {
     const { renderer } = outputFor(this);
@@ -360,6 +363,7 @@ const chatsBehind = (database) => database
     refreshed: isoOf(row.refreshed),
 }));
 const migrateCommand = (messenger) => annotate(new Command("migrate"), { effects: LOCAL_WRITE, mcp: false })
+    .summary("migrate an older local archive")
     .description("bring the store up to this build's schema, then normalize, index and stem the messages and notes stored before it")
     .action(async function () {
     const { renderer } = outputFor(this);
@@ -428,6 +432,7 @@ const buildNoteIndex = (database, note, { reset = false } = {}) => {
     return { notesIndexed: drainNoteIndex(database, stemmerCache()) };
 };
 const reindexCommand = (messenger) => destroysNothing(annotate(new Command("reindex"), { effects: LOCAL_WRITE, mcp: false }))
+    .summary("rebuild the local archive's search indexes")
     .description("rebuild the word index, its typo vocabulary, the stems, the files' word index, the notes' indexes and who took part in what, from what is stored; loses nothing")
     .action(async function () {
     const { renderer } = outputFor(this);
@@ -540,6 +545,7 @@ const decryptCommand = () => annotate(new Command("decrypt"), { effects: LOCAL_W
  * `serve` runs: that opens the store on its first write, so until then it holds nothing to see.
  */
 const restoreCommand = (messenger) => annotate(new Command("restore"), { effects: LOCAL_WRITE, mcp: false })
+    .summary("restore a backup while keeping the current store")
     .description("put a backup in place of the store; the store it replaces is kept beside it, never deleted")
     .argument("<file>", "a file `store backup` wrote; one written with --encrypt asks for its password")
     .action(async function (file) {
@@ -656,6 +662,7 @@ const quiesce = async (path, messenger, then, warn, waitMs = STORE_LOCK_WAIT_MS)
  * schema. The backup is made before anything is deleted, and its path is said before the delete.
  */
 const resetCommand = (messenger) => annotate(new Command("reset"), { effects: LOCAL_WRITE, mcp: false })
+    .summary("back up the local archive and replace it with an empty one")
     .description("back the store up beside itself, then delete it and start an empty one at this build's schema; asks first, or --yes")
     .option("--no-backup", "delete the store without backing it up first")
     .action(async function ({ backup: keep }) {

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

@@ -29,7 +29,9 @@ const sourceOf = (value) => {
 /** The owner's labels, in the local store only: `tag:` in a search finds what they label. */
 export const tagsCommand = (messenger) => {
     const tool = `${messenger.app.command} personal`;
-    const tags = new Command("tags").description("your own labels on chats, people, messages and tasks, kept in the local store and never sent; tag: in a search finds them");
+    const tags = new Command("tags")
+        .summary("tags on stored messages and other records")
+        .description("your own labels on chats, people, messages and tasks, kept in the local store and never sent; tag: in a search finds them");
     changesStore(annotate(tags.command("auto"), { effects: FETCH, examples: [`${tool} tags auto --chat "Book club" --dry-run`] }))
         .description("derive local group/channel tags from cached metadata using keyword rules")
         .option("--chat <chat>", "a stored group/channel; repeat to select several", (value, previous) => [...previous, value], [])
@@ -73,7 +75,9 @@ export const tagsCommand = (messenger) => {
     withQuery(annotate(tags.command("list"), {
         effects: LOCAL_READ,
         examples: [`${tool} tags list`, `${tool} tags list tag:reading`],
-    }).description("what is tagged: this account's chats, messages and tasks, and the people of its messenger"), TAGGING_QUERY).action(async function (words) {
+    })
+        .summary("tagged chats, people, messages and tasks")
+        .description("what is tagged: this account's chats, messages and tasks, and the people of its messenger"), TAGGING_QUERY).action(async function (words) {
         const context = messengerContext(this, messenger);
         const query = listQuery(typedQuery(words), TAGGING_QUERY, "tags list");
         const found = await context.withServices((services) => services.tags.list({ ...(query ? { query } : {}), ...pageOf(context.settings) }));

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

@@ -129,7 +129,9 @@ export const tasksCommand = (messenger) => {
     const writerOf = (command) => readOnlyLockOf(messenger.app, environmentOf(command).env ?? process.env) || environmentOf(command).agent
         ? "agent"
         : "owner";
-    const tasks = new Command("tasks").description("what waits on you — unanswered questions, mentions, requests, promises — kept in the local store; review and serve add them");
+    const tasks = new Command("tasks")
+        .summary("tasks found or kept in the local archive")
+        .description("what waits on you — unanswered questions, mentions, requests, promises — kept in the local store; review and serve add them");
     withQuery(annotate(tasks.command("list"), {
         effects: LOCAL_READ,
         examples: [`${tool} personal tasks list --limit 10`],
@@ -283,8 +285,8 @@ export const tasksCommand = (messenger) => {
     }))
         .summary("two tasks are not the same job: the pair is never offered again")
         .description("two tasks are not the same job: the pair leaves the list and is never offered again")
-        .argument("<dup>", "the task listed as the duplicate, by its id or key")
-        .argument("<task>", "the task it was paired with")
+        .argument("<task>", "the task listed as the duplicate, by its id or key")
+        .argument("<other-task>", "the task it was paired with")
         .action(decided("rejected", "tasks.duplicates.reject"));
     destroysNothing(annotate(duplicates.command("defer"), {
         effects: LOCAL_WRITE,
@@ -292,14 +294,14 @@ export const tasksCommand = (messenger) => {
     }))
         .summary("the fields and the text cannot tell: leave the pair to the owner")
         .description("the fields and the text cannot tell: leave the pair to the owner, who lists it with decision:unsure")
-        .argument("<dup>", "the task listed as the duplicate, by its id or key")
-        .argument("<task>", "the task it was paired with")
+        .argument("<task>", "the task listed as the duplicate, by its id or key")
+        .argument("<other-task>", "the task it was paired with")
         .action(decided("unsure", "tasks.duplicates.defer"));
     destroysNothing(annotate(tasks.command("merge"), { effects: LOCAL_WRITE, examples: [`${tool} tasks merge PR-14 --into PR-12`] }))
         .summary("one job seen twice: fold the duplicate into the task that stays")
         .description("one job seen twice: link every message of the duplicate to the task and close the duplicate dismissed, " +
         "duplicate-of the task; nothing is deleted, and tasks unmerge undoes it")
-        .argument("<dup>", "the duplicate, by its id or key; it must be open")
+        .argument("<task>", "the duplicate, by its id or key; it must be open")
         .requiredOption("--into <id>", "the task that stays, by its id or key")
         .action(async function (dup) {
         const context = messengerContext(this, messenger);
@@ -312,7 +314,7 @@ export const tasksCommand = (messenger) => {
     destroysNothing(annotate(tasks.command("unmerge"), { effects: LOCAL_WRITE, examples: [`${tool} tasks unmerge PR-14`] }))
         .summary("undo a merge: reopen the task and remove its duplicate-of relation")
         .description("undo a merge: reopen the task and remove its duplicate-of relation; messages the merge linked stay linked")
-        .argument("<dup>", "the merged task, by its id or key")
+        .argument("<task>", "the merged task, by its id or key")
         .action(async function (dup) {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "tasks.unmerge");
@@ -417,6 +419,7 @@ export const tasksCommand = (messenger) => {
         ],
     }))
         .summary("close a task: done, or dismissed when it needs no answer; an agent's unsure close waits on the owner")
+        .summary("close a task as done or dismissed")
         .description("close a task: done, or dismissed when it needs no answer. An agent (AI_AGENT or CLAUDECODE set) states its " +
         "--certainty; below config task_agent_close_min, or with task_agent_close off, the task stays open and the " +
         "close waits on the owner, who confirms it with tasks close or refuses it with tasks reject. A closed task " +

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

@@ -12,6 +12,7 @@ export const transcribeSubcommand = (messages, messenger) => annotate(messages.c
     examples: [`${messenger.app.command} personal messages transcribe "Book club" 101`],
     effects: REMOTE_READ,
 })
+    .summary("transcribe one voice message")
     .description(`a voice message as text — by ${messenger.name ?? messenger.app.command} where it can, else by a model on this machine`)
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the id of a voice message")

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

@@ -12,6 +12,7 @@ import { messengerContext } from "./context.js";
  * because a stream is not one value. Nothing is marked read.
  */
 export const watchCommand = (messenger) => annotate(new Command("watch"), { effects: REMOTE_READ, lifetime: "persistent" })
+    .summary("stream new messages until interrupted or timed out")
     .description("print new messages as they arrive, until Ctrl-C or --timeout (either ends it normally)")
     .option("--events", "also edits, deletions, reactions, poll votes and chat events; every line then names its event")
     .action(async function () {

package/dist/cli/program.js

@@ -20,6 +20,7 @@ import { changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTarge
 import { itemOf, renderAnswer, snakeKeys } from "./envelope.js";
 import { byteCount, DEFAULT_COMMAND_MS, DEFAULT_OUTPUT_BYTES, execution } from "./execution.js";
 import { installHelp } from "./help/first-screen.js";
+import { showInputFields } from "./input-fields.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
 import { checkJson, liftJson } from "./json-fields.js";
 import { movedPath, movedPointer } from "./moved.js";
@@ -354,7 +355,7 @@ const runOnce = async (argv, definition, options) => {
         // Only before `--`: what follows is a positional, an agent's text among them, never a command word.
         const end = lifted.indexOf("--");
         for (const words of [flags, end < 0 ? lifted : lifted.slice(0, end)])
-            refuseJoinedPath(program, words.filter((word) => !word.startsWith("-")));
+            refuseJoinedPath(program, words.filter((word) => !word.startsWith("-")), profile !== undefined && !/\s/.test(profile) ? [profile] : []);
     }
     catch (failure) {
         const settled = await settleFailure(failure, { definition, program, rest: lifted, profile, options });
@@ -420,7 +421,8 @@ const runOnce = async (argv, definition, options) => {
                 error.code === "commander.unknownCommand" &&
                 rest[0] !== undefined &&
                 !commandWords(program).has(rest[0])) {
-                message += ` "${profile}" is not a command, so it was read as a profile name — which left "${rest[0]}" to be one.`;
+                message = message.trimEnd();
+                message += ` — "${profile}" is not a command, so it was read as a profile name — which left "${rest[0]}" to be one.`;
             }
             const failure = new CliError("validation_error", message);
             const settled = await settleFailure(failure, { definition, program, rest, profile, options });
@@ -577,6 +579,7 @@ const failed = ({ app }, program, rest, error, settled, debug) => {
         targets: judgedTargets(program),
         ...(effects ? { effects } : {}),
     });
+    showInputFields(object, (path && commandAt(program, path)) || program);
     const command = path || app.command;
     return {
         object,

package/dist/entities/contact-read.d.ts

@@ -0,0 +1,119 @@
+import * as v from "valibot";
+export declare const contactLookup: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly username: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export declare const contactSync: v.StrictObjectSchema<{
+    readonly added: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly changed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly known: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+}, undefined>;
+export declare const contactProfile: v.StrictObjectSchema<{
+    readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+    readonly name: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly usernames: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    readonly bio: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly birthday: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly phone: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    readonly flags: Omit<v.StrictObjectSchema<{
+        readonly bot: v.BooleanSchema<undefined>;
+        readonly verified: v.BooleanSchema<undefined>;
+        readonly premium: v.BooleanSchema<undefined>;
+        readonly scam: v.BooleanSchema<undefined>;
+        readonly fake: v.BooleanSchema<undefined>;
+        readonly restricted: v.BooleanSchema<undefined>;
+        readonly deleted: v.BooleanSchema<undefined>;
+        readonly support: v.BooleanSchema<undefined>;
+    }, undefined>, "entries" | "~run" | "~standard" | "~types"> & {
+        readonly entries: {
+            readonly bot: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly verified: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly premium: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly scam: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly fake: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly restricted: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly deleted: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly support: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        };
+        readonly "~standard": v.StandardProps<{
+            bot?: boolean | undefined;
+            verified?: boolean | undefined;
+            premium?: boolean | undefined;
+            scam?: boolean | undefined;
+            fake?: boolean | undefined;
+            restricted?: boolean | undefined;
+            deleted?: boolean | undefined;
+            support?: boolean | undefined;
+        }, {
+            bot?: boolean | undefined;
+            verified?: boolean | undefined;
+            premium?: boolean | undefined;
+            scam?: boolean | undefined;
+            fake?: boolean | undefined;
+            restricted?: boolean | undefined;
+            deleted?: boolean | undefined;
+            support?: boolean | undefined;
+        }>;
+        readonly "~run": (dataset: v.UnknownDataset, config: v.Config<v.BaseIssue<unknown>>) => v.OutputDataset<{
+            bot?: boolean | undefined;
+            verified?: boolean | undefined;
+            premium?: boolean | undefined;
+            scam?: boolean | undefined;
+            fake?: boolean | undefined;
+            restricted?: boolean | undefined;
+            deleted?: boolean | undefined;
+            support?: boolean | undefined;
+        }, v.BooleanIssue | v.StrictObjectIssue>;
+        readonly "~types"?: {
+            readonly input: {
+                bot?: boolean | undefined;
+                verified?: boolean | undefined;
+                premium?: boolean | undefined;
+                scam?: boolean | undefined;
+                fake?: boolean | undefined;
+                restricted?: boolean | undefined;
+                deleted?: boolean | undefined;
+                support?: boolean | undefined;
+            };
+            readonly output: {
+                bot?: boolean | undefined;
+                verified?: boolean | undefined;
+                premium?: boolean | undefined;
+                scam?: boolean | undefined;
+                fake?: boolean | undefined;
+                restricted?: boolean | undefined;
+                deleted?: boolean | undefined;
+                support?: boolean | undefined;
+            };
+            readonly issue: v.BooleanIssue | v.StrictObjectIssue;
+        } | undefined;
+    };
+    readonly seen: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly contact: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly mutual_contact: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly common_chats_count: v.OptionalSchema<v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>, undefined>;
+    readonly registered: v.OptionalSchema<v.NullableSchema<v.StrictObjectSchema<{
+        readonly at: v.StringSchema<undefined>;
+        readonly source: v.PicklistSchema<["telegram", "max", "estimate"], undefined>;
+        readonly precision: v.PicklistSchema<["day", "month"], undefined>;
+    }, undefined>, undefined>, undefined>;
+    readonly has_photo: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+    readonly chats: v.ArraySchema<v.StrictObjectSchema<{
+        readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly kind: v.PicklistSchema<["dialog", "group", "channel", "saved", "unknown"], undefined>;
+        readonly their_messages: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly first_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly last_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly complete: v.BooleanSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly aliases: v.ArraySchema<v.StrictObjectSchema<{
+        readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly username: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly link: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        readonly first_seen_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly last_seen_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly source: v.PicklistSchema<["profile", "messages"], undefined>;
+    }, undefined>, undefined>;
+}, undefined>;