things-api 0.17.0 → 0.19.0

package/dist/cli/commands/writes.js

@@ -1,30 +1,55 @@
+/**
+ * Write commands. Help text is the agent API: every command's --help states
+ * its behavior, side effects, and required confirmation flags in consumer
+ * voice (docs/design/surface-copy.md) — internals stay in docs/ and the
+ * capabilities/dry-run OUTPUT. No interactive prompts: risky semantics
+ * require explicit flags.
+ */
+import { Option } from "commander";
 import { readFileSync } from "node:fs";
 import { armInterrupt, disarmInterrupt } from "../interrupt.js";
 import { isDevVersion } from "../skill.js";
 import { CLI_VERSION } from "../version.js";
 import { addRepeatCalendarFlags, addRepeatingRuleFieldsFromOpts, addRepeatRuleFlags, repeatRuleFlagsFromOpts, } from "./repeat-flags.js";
-import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, installCliTrace, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { aggregateExitCode, blockedCode, buildUpdatePatch, capabilitiesTable, CLI_UPDATE_LABELS, ClockError, closeCliTrace, describeConfig, errorEnvelope, ExitCode, HELPERS_MODES, installCliTrace, getConfigKey, parseHelpersMode, mutationWireData, NOTES_FORMAT, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ParamSchemaError, ReferenceResolutionError, saveConfigKey, splitWhenSugar, trace, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
 import { dim } from "../style.js";
-function addWriteFlags(cmd) {
+/**
+ * The `--preserve-modified` help text, shared by the universal write flag and
+ * the run-level `batch` flag (which applies it as the default for every line) —
+ * one source so the two surfaces can never drift.
+ */
+const PRESERVE_MODIFIED_HELP = "keep this change off the modification-date timeline: capture each pre-existing edited " +
+    "item's modification date and restore it (to the whole second) after the change, so a " +
+    "changes/watch query keyed on it does not surface the edit. A no-op on a pure create. " +
+    "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
+    "the item stays off the timeline everywhere — unless another device edits the same item " +
+    "at nearly the same time, which re-dates it.";
+function addWriteFlags(cmd, capability = {}) {
+    const opId = new Option("--op-id <key>", "idempotency key: a resubmission with the same key is recognized as already applied " +
+        "and not re-run (matches [A-Za-z0-9_-], 1-64 chars)");
+    if (capability.opId === "unsupported")
+        opId.hideHelp();
     return cmd
         .option("--json", "emit versioned JSON envelope on stdout")
         .option("--db <path>", "explicit database path")
         .option("--dry-run", "preview the planned change and its expected effect; nothing executes")
-        .option("--preserve-modified", "keep this change off the modification-date timeline: capture each pre-existing edited " +
-        "item's modification date and restore it (to the whole second) after the change, so a " +
-        "changes/watch query keyed on it does not surface the edit. A no-op on a pure create. " +
-        "Safe with Things Cloud: the restored date syncs to your other devices and stays put, so " +
-        "the item stays off the timeline everywhere — unless another device edits the same item " +
-        "at nearly the same time, which re-dates it.")
+        .option("--preserve-modified", PRESERVE_MODIFIED_HELP)
         .option("--vector <id>", "force how the change is delivered: url-scheme | applescript | shortcuts | ui")
         .option("--allow-disruptive", "permit changes that briefly steal window focus")
         .option("--allow-very-disruptive", "permit changes that visibly drive the Things UI")
         .option("--verify-timeout <ms>", "how long to wait for the change to take effect")
         .option("--actor <name>", "author name recorded for this change (default: from config)")
-        .option("--op-id <key>", "idempotency key: a resubmission with the same key is recognized as already applied " +
-        "and not re-run (matches [A-Za-z0-9_-], 1-64 chars)");
+        .addOption(opId);
 }
+/**
+ * The write flags for a multi-leg COMPOUND command: the same set, with `--op-id`
+ * kept out of `--help` because that command's execution refuses it (see
+ * `opIdCompoundRefused` / `runMoveCmd`). Every command wrapped in this MUST
+ * refuse `--op-id` at runtime, and every command that refuses it MUST be wrapped
+ * in this — `test/cli/help-contract.test.ts` holds the two halves together.
+ */
+const addCompoundWriteFlags = (cmd) => addWriteFlags(cmd, { opId: "unsupported" });
 /** Validate an `--op-id`; on a malformed value emit the usage error and return false. */
 function opIdOk(opts) {
     if (opts.opId === undefined)
@@ -190,20 +215,44 @@ function splitCsv(value) {
         .map((s) => s.trim())
         .filter((s) => s !== "");
 }
-async function runWrite(opts, fn, emitFn = emitResult) {
-    if (!opIdOk(opts))
-        return;
-    const started = Date.now();
-    // Dev-mode step-timeline trace + signal-safe interrupt guard (TRACE1, #487).
-    // Scoped to the write driver — the invocations where a per-step timeline earns
-    // its keep, and where a mid-drive kill would otherwise leave empty stdout. The
-    // sink is a no-op unless tracing is on (a `-dev` build, or config/env forced).
+/**
+ * Open a CLI write invocation: install the dev-mode step-timeline trace and arm
+ * the signal-safe interrupt guard (TRACE1, #487). Returns the teardown for the
+ * driver's `finally` — it closes the trace with the final exit code, then
+ * disarms the guard so a signal during teardown/reads emits nothing.
+ *
+ * EVERY write driver calls this, not just the single-mutation one: the library
+ * half (the in-flight marker, the watchdog, the plain-stderr interrupt line)
+ * works everywhere, but the trace FILE and the `--json` `interrupted` envelope
+ * exist only where the driver installs and arms them. `json` says whether this
+ * invocation's stdout is machine-readable — drivers that emit JSONL regardless
+ * of `--json` (batch, undo) pass true.
+ *
+ * The sink is a no-op unless tracing is on (a `-dev` build, or config/env
+ * forced), so this costs a config read on every write and nothing else.
+ */
+function beginWriteInvocation(json, startedAt) {
     installCliTrace({
         argv: process.argv.slice(1),
         version: CLI_VERSION,
         isDev: isDevVersion(CLI_VERSION),
     });
-    armInterrupt(opts.json === true);
+    armInterrupt(json);
+    return () => {
+        trace(() => ({
+            phase: "invocation-end",
+            exitCode: process.exitCode ?? 0,
+            elapsedMs: Date.now() - startedAt,
+        }));
+        disarmInterrupt();
+        closeCliTrace();
+    };
+}
+async function runWrite(opts, fn, emitFn = emitResult) {
+    if (!opIdOk(opts))
+        return;
+    const started = Date.now();
+    const endInvocation = beginWriteInvocation(opts.json === true, started);
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
@@ -245,6 +294,14 @@ async function runWrite(opts, fn, emitFn = emitResult) {
             usageError(opts, err.message);
             return;
         }
+        // A structural parameter refusal (#580) is an INPUT-CONTRACT error — the
+        // caller's bag was malformed and nothing was dispatched — not an internal
+        // fault. It exits `usage`, naming the JSON path, the expected shape, and
+        // what was received.
+        if (err instanceof ParamSchemaError) {
+            usageError(opts, err.message);
+            return;
+        }
         const isEnv = err instanceof ThingsDbNotFoundError || err instanceof ThingsDbOpenError;
         const message = err instanceof Error ? err.message : String(err);
         if (opts.json) {
@@ -257,16 +314,7 @@ async function runWrite(opts, fn, emitFn = emitResult) {
     }
     finally {
         client?.close();
-        // Close the trace with a final result line (the exit code the caller sees),
-        // then disarm the interrupt guard so a later signal during teardown/reads
-        // emits nothing.
-        trace(() => ({
-            phase: "invocation-end",
-            exitCode: process.exitCode ?? 0,
-            elapsedMs: Date.now() - started,
-        }));
-        disarmInterrupt();
-        closeCliTrace();
+        endInvocation();
     }
 }
 /**
@@ -286,6 +334,22 @@ function emitPreserveNote(result) {
         process.stderr.write(`warning: preserve-modified: ${f.uuid}: ${f.detail}\n`);
     }
 }
+/**
+ * TTY disclosure for a TEMPLATE-TARGET composite (`complete`/`cancel`/`update
+ * --exception` aimed at a repeating to-do): a dim line naming BOTH uuids — the
+ * occurrence that was written (the result's own uuid) and the series it belongs
+ * to — plus whether that occurrence was created for this call. The human render
+ * would otherwise show one uuid with nothing saying which of the two it is.
+ * Silent for every other op (the field is absent).
+ */
+function emitOccurrenceNote(result) {
+    const o = result.occurrence;
+    if (o === undefined)
+        return;
+    const dated = o.date === null ? "" : ` dated ${o.date}`;
+    const origin = o.minted ? "created for this change" : "already open";
+    process.stdout.write(dim(`  occurrence ${o.occurrenceUuid}${dated} (${origin}) of repeating to-do ${o.templateUuid}\n`));
+}
 /**
  * TTY disclosure for the HINTS1 completion-context on a verified complete/cancel:
  * a dim line naming the OPEN work remaining in the to-do's project and/or Today,
@@ -337,6 +401,7 @@ function emitResult(result, opts, meta) {
                     ? "already applied — matched op-id in the change history, not re-run"
                     : `vector=${result.vector}, tier=${result.tier}, verified`;
                 process.stdout.write(`ok ${result.op}${uuid} (${status})\n`);
+                emitOccurrenceNote(result);
                 emitPreserveNote(result);
                 emitContextNote(result);
             }
@@ -354,6 +419,7 @@ function emitResult(result, opts, meta) {
                     `  invocation: ${result.plan.invocation}`,
                     `  hazards checked: ${result.plan.hazardsChecked.join(", ") || "none"}`,
                     `  expected delta: ${JSON.stringify(result.plan.expectedDelta)}`,
+                    ...(result.plan.notes ?? []).map((n) => `  note: ${n}`),
                     "",
                 ].join("\n"));
             }
@@ -431,6 +497,7 @@ async function runMoveCmd(opts, fn) {
         return;
     }
     const started = Date.now();
+    const endInvocation = beginWriteInvocation(opts.json === true, started);
     let client = null;
     const meta = () => {
         let dbVersion = null;
@@ -468,6 +535,7 @@ async function runMoveCmd(opts, fn) {
     }
     finally {
         client?.close();
+        endInvocation();
     }
 }
 function emitMoveResult(result, opts, meta) {
@@ -689,6 +757,7 @@ function addResultLine(r) {
  * in creation order, and nothing else. Exit code is the worst leg's failure.
  */
 async function runBulkAdd(opts, ops, idOnly) {
+    const endInvocation = beginWriteInvocation(opts.json === true, Date.now());
     let client = null;
     try {
         client = openThings(opts.db ? { dbPath: opts.db } : {});
@@ -734,6 +803,7 @@ async function runBulkAdd(opts, ops, idOnly) {
     }
     finally {
         client?.close();
+        endInvocation();
     }
 }
 /** Read newline-delimited titles from stdin; blank lines (whitespace-only) skipped. */
@@ -747,6 +817,45 @@ async function readStdinTitles() {
         .map((l) => l.replace(/\r$/, ""))
         .filter((l) => l.trim() !== "");
 }
+/**
+ * The CLI-only half of the notes vocabulary (the shared half is NOTES_FORMAT):
+ * how a multi-line body gets in from a shell. `-` reads STDIN, so a heredoc or
+ * a pipe composes; the `$'…'` form covers the inline case.
+ */
+const NOTES_INPUT = "pass - to read the body from stdin, or $'line 1\\nline 2' to give it inline";
+/**
+ * Read the whole of STDIN as one UTF-8 note body. One trailing newline is
+ * dropped (a heredoc and most pipes add one); every other newline is kept.
+ */
+async function readStdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks)
+        .toString("utf8")
+        .replace(/\r?\n$/, "");
+}
+/**
+ * Resolve `--notes -` into the body waiting on STDIN, in place on `opts`. A
+ * terminal STDIN has nothing to read, so it is refused with the two working
+ * spellings rather than hanging on an input nobody is going to type. Returns
+ * false when the invocation was refused (the usage error is already emitted).
+ */
+async function resolveNotesStdin(opts, conflictsWithStdinFlag = false) {
+    if (opts["notes"] !== "-")
+        return true;
+    if (conflictsWithStdinFlag && opts["stdin"] === true) {
+        usageError(opts, "--notes - and --stdin both read stdin; pass at most one of them");
+        return false;
+    }
+    if (process.stdin.isTTY === true) {
+        usageError(opts, "--notes - reads the note body from stdin, and stdin is a terminal: pipe the body in " +
+            "(or redirect a file with < notes.md), or give the text inline with --notes $'line 1\\nline 2'");
+        return false;
+    }
+    opts["notes"] = await readStdinText();
+    return true;
+}
 function group(program, name, description) {
     const existing = program.commands.find((c) => c.name() === name);
     if (existing !== undefined)
@@ -771,7 +880,7 @@ export function registerWriteCommands(program) {
         "--create-tags. Adding into a completed/canceled project reopens that project — " +
         "requires --acknowledge-project-reopen. When several to-dos are created, one undo " +
         "token removes the whole skeleton at once.")
-        .option("--notes <text>", "notes body")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <HH:mm>", "time-of-day reminder (24h); requires --when today|evening|YYYY-MM-DD")
         .option("--deadline <date>", "YYYY-MM-DD")
@@ -791,6 +900,8 @@ export function registerWriteCommands(program) {
             usageError(opts, "--id-only and --json are mutually exclusive");
             return;
         }
+        if (!(await resolveNotesStdin(opts, true)))
+            return;
         if (useStdin && titles.length > 0) {
             usageError(opts, "--stdin is mutually exclusive with title arguments");
             return;
@@ -883,15 +994,17 @@ export function registerWriteCommands(program) {
     });
     addWriteFlags(todo
         .command("update <uuid>")
-        .description("Update title/notes/when/reminder/deadline. Schedule and deadline changes are not " +
-        "available for repeating to-dos (title/notes are). --reminder needs --when " +
+        .description("Update title/notes/when/reminder/deadline. On a REPEATING to-do a schedule or " +
+        "deadline change needs --exception (change only the next occurrence) or " +
+        "`things todo reschedule-repeat` (change the series); title/notes apply to the " +
+        "series as they always have. --reminder needs --when " +
         "today|evening|YYYY-MM-DD; when re-scheduling WITHOUT --reminder an existing " +
         "reminder is auto-preserved. --clear-reminder works while the to-do is scheduled " +
         "for today|evening — a DATED reminder can only be changed, not cleared " +
         "(re-schedule to today first). --append-notes/--prepend-notes join with a " +
         "newline (exclusive with --notes).")
         .option("--title <text>", "new title")
-        .option("--notes <text>", "replace notes")
+        .option("--notes <text>", `replace the notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--append-notes <text>", "append to existing notes (newline-joined)")
         .option("--prepend-notes <text>", "prepend to existing notes (newline-joined)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
@@ -900,33 +1013,35 @@ export function registerWriteCommands(program) {
         .option("--deadline <date>", "YYYY-MM-DD")
         .option("--clear-deadline", "remove the deadline")
         .option("--created-at <iso>", "rewrite the creation timestamp (ISO date or datetime; a date is noon in the effective zone); status-safe")
-        .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved to-do (a canceled one stays canceled); open to-dos are refused — use complete/cancel")).action(async (uuid, opts) => {
-        const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
-        if (notesModes.length > 1) {
-            usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
+        .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved to-do (a canceled one stays canceled); open to-dos are refused — use complete/cancel")
+        .option("--exception", "repeating to-dos only: change just the NEXT occurrence and leave the series alone " +
+        "(creates that occurrence if it has not appeared yet); refused when the series already " +
+        "lands on the requested day. The result names both the occurrence and the series. Each " +
+        "re-run takes another occurrence out of the series, so pass --op-id on a retry: a " +
+        "resubmission with the same key replays the first result instead of creating a second " +
+        "occurrence")).action(async (uuid, opts) => {
+        if (!(await resolveNotesStdin(opts)))
             return;
-        }
-        if (opts["reminder"] !== undefined && opts["clearReminder"] === true) {
-            usageError(opts, "pass at most one of --reminder / --clear-reminder");
+        // The patch (and every exclusive-flag pair in it, the @time sugar included)
+        // comes from the ONE update-vocabulary builder both surfaces share.
+        const built = buildUpdatePatch(opts, CLI_UPDATE_LABELS);
+        if (built.kind === "error") {
+            usageError(opts, built.message);
             return;
         }
-        if (!whenSugarOk(opts))
+        if (opts["exception"] === true) {
+            // The occurrence is a to-do of its own once it exists, so the whole update
+            // vocabulary applies to it — except the timestamp rewrites, which are about
+            // a row's history and have no meaning for an occurrence created this second.
+            const stamped = ["createdAt", "completedAt"].filter((k) => opts[k] !== undefined);
+            if (stamped.length > 0) {
+                usageError(opts, "--exception cannot be combined with --created-at/--completed-at");
+                return;
+            }
+            await runWrite(opts, (c) => c.write.updateTodoOccurrence(uuid, built.patch, writeOptionsFrom(opts)));
             return;
-        await runWrite(opts, (c) => c.write.updateTodo(uuid, {
-            ...(opts["title"] !== undefined && { title: opts["title"] }),
-            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
-            ...(opts["appendNotes"] !== undefined && { appendNotes: opts["appendNotes"] }),
-            ...(opts["prependNotes"] !== undefined && {
-                prependNotes: opts["prependNotes"],
-            }),
-            ...(opts["when"] !== undefined && { when: opts["when"] }),
-            ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
-            ...(opts["clearReminder"] === true && { reminder: null }),
-            ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
-            ...(opts["clearDeadline"] === true && { deadline: null }),
-            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
-            ...(opts["completedAt"] !== undefined && { completedAt: opts["completedAt"] }),
-        }, writeOptionsFrom(opts)));
+        }
+        await runWrite(opts, (c) => c.write.updateTodo(uuid, built.patch, writeOptionsFrom(opts)));
     });
     for (const verb of ["complete", "cancel"]) {
         const method = verb === "complete" ? "completeTodo" : "cancelTodo";
@@ -935,7 +1050,13 @@ export function registerWriteCommands(program) {
             : "keeping it canceled via the certified flip legs";
         addWriteFlags(todo
             .command(`${verb} <uuid>`)
-            .description(`${verb[0]?.toUpperCase()}${verb.slice(1)} a to-do. Not available for repeating to-dos. ` +
+            .description(`${verb[0]?.toUpperCase()}${verb.slice(1)} a to-do. On a REPEATING to-do this ${verb}s ` +
+            "the series' current occurrence — the unfinished one if there is one, otherwise the " +
+            "next one, created for the purpose — and leaves the series running; the result names " +
+            "both the occurrence and the series, and says which of the two it created. Each " +
+            `re-run is a new ${verb} that takes the FOLLOWING occurrence, so pass --op-id on a ` +
+            "retry: a resubmission with the same key replays the first result instead of " +
+            "creating a second occurrence. " +
             '--completed-at sets the completion timestamp (also the "Completed on" stamp for a canceled ' +
             `item), ${stampNote} — a multi-leg sequence, disclosed in the result and --dry-run.`)
             .option("--completed-at <iso>", "completion timestamp (ISO date or datetime; a date is noon in the effective zone)")).action(async (uuid, opts) => {
@@ -948,7 +1069,7 @@ export function registerWriteCommands(program) {
         .description("Reopen a to-do. Not available for repeating to-dos.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.reopenTodo(uuid, writeOptionsFrom(opts)));
     });
-    addPositionFlags(addWriteFlags(todo
+    addPositionFlags(addCompoundWriteFlags(todo
         .command("move <refs...>")
         .description("Move one or more to-dos as an ordered block (the argument order is the order they " +
         "land — name them backwards to reverse). MOVE changes WHAT a to-do belongs to; to " +
@@ -1108,8 +1229,12 @@ export function registerWriteCommands(program) {
     });
     addWriteFlags(todo
         .command("delete <uuid>")
-        .description("Move a to-do to the Trash (recover with `things todo restore`). Not available " +
-        "for repeating to-dos.")).action(async (uuid, opts) => {
+        .description("Move a to-do to the Trash (recover with `things todo restore`). Deleting a repeating " +
+        "series' TEMPLATE is allowed and ends the series: it stops generating new occurrences " +
+        "and its existing occurrences are left in place (the result names how many, and the " +
+        "current one). That cannot be undone here — the series comes back only via Put Back " +
+        "in the Things app's Trash — so no undo token is returned. Deleting a single " +
+        "occurrence leaves the series running.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.deleteTodo(uuid, writeOptionsFrom(opts)));
     });
     addWriteFlags(todo
@@ -1122,7 +1247,7 @@ export function registerWriteCommands(program) {
     addWriteFlags(todo
         .command("clear-reminder <uuid>")
         .description("Clear a to-do's time-of-day reminder, keeping its scheduled date. With the proxy " +
-        "shortcuts installed (`things setup shortcuts`) this is in place, and is the only " +
+        "shortcuts installed (`things setup`) this is in place, and is the only " +
         "way for a repeating to-do; otherwise a date-scheduled to-do is cleared by a brief " +
         "re-schedule through Today. Reversible with `things undo`.")).action(async (uuid, opts) => {
         if (opIdCompoundRefused(opts, "clear-reminder"))
@@ -1200,11 +1325,11 @@ export function registerWriteCommands(program) {
     // silently re-targets a different heading after any reorder). An empty-string
     // title selects a titleless heading; duplicates fail closed with uuid
     // candidates.
-    addPlacementFlags(addWriteFlags(project
+    addPlacementFlags(addCompoundWriteFlags(project
         .command("add-heading <project> <title>")
         .description("Create a heading inside an existing project; its uuid is printed on success. The " +
         "project must name an existing project (uuid or unique name). Uses the Things proxy " +
-        "shortcuts — run `things setup shortcuts` once first. By default the heading is " +
+        "shortcuts — run `things setup` once first. By default the heading is " +
         "appended; a placement flag positions it among the project's headings (that leg " +
         "needs `things config set allow-experimental true`)."))).action(async (projectRef, title, opts) => {
         if (countPlacementFlags(opts) > 1) {
@@ -1229,7 +1354,7 @@ export function registerWriteCommands(program) {
             return c.write.renameHeading(h.uuid, opts["to"], writeOptionsFrom(opts));
         });
     });
-    addWriteFlags(project
+    addCompoundWriteFlags(project
         .command("archive-heading <project> <heading>")
         .description("Archive a heading — it leaves the active project view (reversible with " +
         "`things project unarchive-heading`). This is the preferred way to retire a heading: " +
@@ -1252,7 +1377,7 @@ export function registerWriteCommands(program) {
             return outcome.heading;
         });
     });
-    addWriteFlags(project
+    addCompoundWriteFlags(project
         .command("unarchive-heading <project> <heading>")
         .description("Un-archive a heading. --restore-children also reopens the children the archive " +
         "cascade resolved with it (identified by matching resolution timestamps; a " +
@@ -1367,7 +1492,7 @@ export function registerWriteCommands(program) {
             await runWrite(opts, (c) => c.write.run(op, { uuid }, writeOptionsFrom(opts)));
         });
     }
-    addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(project
+    addDriveGuiFlag(addRepeatRuleFlags(addCompoundWriteFlags(project
         .command("make-repeating <ref>")
         .description("Turn a project into a repeating one. A disposable copy is promoted and the ORIGINAL is " +
         "moved to the Trash — so `things undo` reverses it (it removes the new series and " +
@@ -1385,17 +1510,19 @@ export function registerWriteCommands(program) {
             ...repeatRuleFlagsFromOpts(opts, frequency),
         }, writeOptionsFrom(opts)));
     });
-    addDriveGuiFlag(addRepeatCalendarFlags(addWriteFlags(project
+    addDriveGuiFlag(addRepeatCalendarFlags(addCompoundWriteFlags(project
         .command("add-repeating <title>")
         .description("Create a project and turn it into a repeating series in ONE call. Two legs: the project " +
         "is created (notes/area/when/deadline/child to-dos) and PERSISTS even if the promote " +
         "refuses; then it is promoted (which drives the GUI). Give --area to place it, or omit " +
         "it to create in Someday. The new repeating project's uuid is printed; `things undo` " +
         "removes the created series (trash-both).")
-        .option("--notes <text>", "notes body")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
-        .option("--deadline <date>", "YYYY-MM-DD")
+        .option("--deadline <date>", "YYYY-MM-DD — deadlines EVERY occurrence: each starts (deadline − --when) days " +
+        "before its own deadline (needs a concrete --when, on or before the deadline; " +
+        "not available with --after-completion)")
         .option("--todo <title>", "initial child to-do (repeatable)", collect, [])
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (title, opts) => {
@@ -1404,6 +1531,8 @@ export function registerWriteCommands(program) {
         const frequency = opts["frequency"];
         if (opIdCompoundRefused(opts, "project add-repeating"))
             return;
+        if (!(await resolveNotesStdin(opts)))
+            return;
         await runWrite(opts, (c) => c.write.addRepeatingProject({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
@@ -1414,16 +1543,21 @@ export function registerWriteCommands(program) {
             ...addRepeatingRuleFieldsFromOpts(opts, frequency, Number(opts["interval"])),
         }, writeOptionsFrom(opts)));
     });
-    addDriveGuiFlag(addRepeatCalendarFlags(addWriteFlags(todo
+    addDriveGuiFlag(addRepeatCalendarFlags(addCompoundWriteFlags(todo
         .command("add-repeating <title>")
         .description("Create a to-do and turn it into a repeating series in ONE call. Two legs: the to-do is " +
         "created (notes/tags/when/deadline/reminder/checklist/--created-at) and PERSISTS even " +
         "if the promote refuses; then it is promoted (which drives the GUI). The new repeating " +
         "template's uuid is printed; `things undo` removes the created series (trash-both).")
-        .option("--notes <text>", "notes body")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--reminder <time>", "HH:mm reminder (needs a schedulable --when)")
-        .option("--deadline <date>", "YYYY-MM-DD")
+        .option("--deadline <date>", "YYYY-MM-DD — deadlines EVERY occurrence: each starts (deadline − --when) days " +
+        "before its own deadline (needs a concrete --when, on or before the deadline; " +
+        "alternative spelling of --start-days-earlier — give one or the other, both must agree)")
+        .option("--start-days-earlier <n>", "deadlines EVERY occurrence, naming the lead directly: each starts N days before " +
+        "its own deadline (needs a concrete --when; alternative spelling of --deadline <date> — " +
+        "give one or the other, both must agree)")
         .option("--tag <name>", "tag to attach (repeatable)", collect, [])
         .option("--checklist-item <title>", "checklist item (repeatable)", collect, [])
         .option("--project <ref>", "destination project (uuid or unique name)")
@@ -1439,12 +1573,17 @@ export function registerWriteCommands(program) {
         const frequency = opts["frequency"];
         if (opIdCompoundRefused(opts, "todo add-repeating"))
             return;
+        if (!(await resolveNotesStdin(opts)))
+            return;
         await runWrite(opts, (c) => c.write.addRepeatingTodo({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
             ...(opts["when"] !== undefined && { when: opts["when"] }),
             ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
             ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
+            ...(opts["startDaysEarlier"] !== undefined && {
+                startDaysEarlier: Number(opts["startDaysEarlier"]),
+            }),
             ...(tags.length > 0 && { tags }),
             ...(checklistItems.length > 0 && { checklistItems }),
             ...(projectRef !== undefined && { project: projectRef }),
@@ -1459,7 +1598,7 @@ export function registerWriteCommands(program) {
         .description("Create a project; its uuid is printed on success. Give --todo (repeatable) to " +
         "seed it with child to-dos in the same call — the quick way to stand up a new " +
         "project skeleton.")
-        .option("--notes <text>", "notes body")
+        .option("--notes <text>", `notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
         .option("--deadline <date>", "YYYY-MM-DD")
@@ -1468,6 +1607,8 @@ export function registerWriteCommands(program) {
         .option("--completed-at <iso>", "born completed (in the Logbook) with this completion timestamp; cannot seed open child to-dos (§5b)")).action(async (title, opts) => {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
+        if (!(await resolveNotesStdin(opts)))
+            return;
         await runWrite(opts, (c) => c.write.addProject({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
@@ -1487,7 +1628,7 @@ export function registerWriteCommands(program) {
         "--notes). --reminder needs --when today|evening|YYYY-MM-DD; when re-scheduling " +
         "WITHOUT --reminder an existing reminder is auto-preserved."))
         .option("--title <text>", "new title")
-        .option("--notes <text>", "replace notes")
+        .option("--notes <text>", `replace the notes body — ${NOTES_FORMAT} (${NOTES_INPUT})`)
         .option("--append-notes <text>", "append to existing notes (newline-joined)")
         .option("--prepend-notes <text>", "prepend to existing notes (newline-joined)")
         .option("--when <value>", "today | evening | anytime | someday | YYYY-MM-DD")
@@ -1498,36 +1639,14 @@ export function registerWriteCommands(program) {
         .option("--created-at <iso>", "rewrite the creation timestamp (ISO date or datetime; a date is noon in the effective zone); status-safe")
         .option("--completed-at <iso>", "rewrite the completion timestamp of an already-resolved project (a canceled one stays canceled); open projects are refused — use complete/cancel")
         .action(async (uuid, opts) => {
-        const notesModes = ["notes", "appendNotes", "prependNotes"].filter((k) => opts[k] !== undefined);
-        if (notesModes.length > 1) {
-            usageError(opts, "--notes, --append-notes, --prepend-notes are exclusive");
+        if (!(await resolveNotesStdin(opts)))
             return;
-        }
-        if (opts["reminder"] !== undefined && opts["clearReminder"] === true) {
-            usageError(opts, "pass at most one of --reminder / --clear-reminder");
+        const built = buildUpdatePatch(opts, CLI_UPDATE_LABELS);
+        if (built.kind === "error") {
+            usageError(opts, built.message);
             return;
         }
-        if (!whenSugarOk(opts))
-            return;
-        await runWrite(opts, (c) => c.write.updateProject(uuid, {
-            ...(opts["title"] !== undefined && { title: opts["title"] }),
-            ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
-            ...(opts["appendNotes"] !== undefined && {
-                appendNotes: opts["appendNotes"],
-            }),
-            ...(opts["prependNotes"] !== undefined && {
-                prependNotes: opts["prependNotes"],
-            }),
-            ...(opts["when"] !== undefined && { when: opts["when"] }),
-            ...(opts["reminder"] !== undefined && { reminder: opts["reminder"] }),
-            ...(opts["clearReminder"] === true && { reminder: null }),
-            ...(opts["deadline"] !== undefined && { deadline: opts["deadline"] }),
-            ...(opts["clearDeadline"] === true && { deadline: null }),
-            ...(opts["createdAt"] !== undefined && { createdAt: opts["createdAt"] }),
-            ...(opts["completedAt"] !== undefined && {
-                completedAt: opts["completedAt"],
-            }),
-        }, writeOptionsFrom(opts)));
+        await runWrite(opts, (c) => c.write.updateProject(uuid, built.patch, writeOptionsFrom(opts)));
     });
     addCreateTagsFlag(addWriteFlags(project
         .command("tags <ref>")
@@ -1547,7 +1666,7 @@ export function registerWriteCommands(program) {
             ? c.write.setProjectTags(uuid, set, writeOptionsFrom(opts, createTagsExtra(opts)))
             : c.write.addProjectTags(uuid, add ?? [], writeOptionsFrom(opts, createTagsExtra(opts))));
     });
-    addPositionFlags(addWriteFlags(project
+    addPositionFlags(addCompoundWriteFlags(project
         .command("move <refs...>")
         .description("Move one or more projects as an ordered block (argument order = resulting order). " +
         "Pass one destination: --to-area (uuid or unique name) or --no-area (leave the " +
@@ -1593,7 +1712,7 @@ export function registerWriteCommands(program) {
             }),
         }, writeOptionsFrom(opts)));
     });
-    addWriteFlags(project
+    addCompoundWriteFlags(project
         .command("reopen <ref>")
         .description("Reopen a completed/canceled project (target by uuid or unique name). Its children " +
         "stay completed/canceled unless " +
@@ -1604,6 +1723,7 @@ export function registerWriteCommands(program) {
         if (opIdCompoundRefused(opts, "project reopen"))
             return;
         const started = Date.now();
+        const endInvocation = beginWriteInvocation(opts.json === true, started);
         let client = null;
         try {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
@@ -1640,6 +1760,7 @@ export function registerWriteCommands(program) {
         }
         finally {
             client?.close();
+            endInvocation();
         }
     });
     addWriteFlags(project
@@ -1688,7 +1809,10 @@ export function registerWriteCommands(program) {
     addWriteFlags(project
         .command("delete <ref>")
         .description("Move a project (target by uuid or unique name) to the Trash; its children go with " +
-        "it (recover with `things project restore`).")).action(async (uuid, opts) => {
+        "it (recover with `things project restore`). Deleting a repeating series' TEMPLATE is " +
+        "allowed and ends the series: it stops generating new occurrences and its existing " +
+        "occurrences are left in place. That cannot be undone here — the series comes back " +
+        "only via Put Back in the Things app's Trash — so no undo token is returned.")).action(async (uuid, opts) => {
         await runWrite(opts, (c) => c.write.deleteProject(uuid, writeOptionsFrom(opts)));
     });
     const area = group(program, "area", "Area-scoped operations");
@@ -1858,9 +1982,11 @@ export function registerWriteCommands(program) {
         .description("Run MANY mutations from JSONL (file, or stdin when omitted/'-'): one op per line, " +
         '{"op": "<kind>", "params": {...}, "options": {...}} — see `things capabilities` for ' +
         "op kinds and params. Ops run sequentially and independently — NO transactions; a " +
-        "failure does not roll back earlier ops. A statically-invalid line (bad shape, unknown " +
-        "op, a $ref to an undeclared/forward tempId, a duplicate tempId) refuses the WHOLE " +
-        "batch before anything runs, naming every bad line. Otherwise ops run and per-op " +
+        "failure does not roll back earlier ops. A statically-invalid line (unknown op, an " +
+        "unknown or wrongly-typed param, a $ref to an undeclared/forward tempId, a duplicate " +
+        "tempId) refuses the WHOLE batch before anything runs, naming every bad line and the " +
+        'field it names. A container param takes an object — {"project": {"uuid": "…"}} — ' +
+        "never a bare string. Otherwise ops run and per-op " +
         "results stream as JSONL. Per-op " +
         "options carry the confirmation flags (acknowledgeChecklistReset, " +
         "acknowledgeProjectReopen, dangerouslyPermanent, acknowledgeTagSubtree). " +
@@ -1873,12 +1999,18 @@ export function registerWriteCommands(program) {
         "re-created (put an opId on EVERY line so a stopped batch can be resubmitted verbatim " +
         "to resume). The trailing summary line adds `tempIdMapping` (handle → uuid) and " +
         "`undoToken` — undo the WHOLE batch with `things undo --txn <undoToken>`. " +
+        "TIMELINE: --preserve-modified applies to every line (each line may override it with its " +
+        'own `"options": {"preserveModified": true|false}`), so a bulk re-tag stays off the ' +
+        "modification-date timeline under one undo token; each line's result then carries " +
+        "`preservedModified` (and `preserveFailures` for any restore that did not land). " +
         "By DEFAULT a runtime failure STOPS the batch (later lines reported not-run, with resume " +
         "guidance in the summary); --continue-on-error runs past failures. --dry-run plans " +
         "everything without executing. Exit (worst failure wins): 0 all ok · 3 any " +
         "verify-failed/invalid · 4 any blocked · 5 any drift-blocked · 6 any unsupported.")
         .option("--dry-run", "plan every op; execute nothing")
         .option("--continue-on-error", "run past a failed op instead of stopping (default: stop)")
+        .option("--preserve-modified", `${PRESERVE_MODIFIED_HELP} Applies to EVERY line; a line that sets its own ` +
+        '`"options": {"preserveModified": false}` opts back onto the timeline.')
         .option("--json", "JSONL results + summary on stdout (also the default)")
         .option("--db <path>", "explicit database path")
         .option("--actor <name>", "author name recorded for the whole batch")
@@ -1914,12 +2046,18 @@ export function registerWriteCommands(program) {
                 });
             }
         }
+        // batch streams JSONL regardless of --json, so the interrupt guard is
+        // armed machine-readable.
+        const endInvocation = beginWriteInvocation(true, Date.now());
         let client = null;
         try {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
             const batchResult = await client.write.batch(ops, {
                 ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
                 ...(opts["continueOnError"] === true && { continueOnError: true }),
+                // Run-level default for every line; a line's own explicit
+                // `options.preserveModified` outranks it (src/write/batch.ts).
+                ...(opts.preserveModified === true && { preserveModified: true }),
                 ...(opts.actor !== undefined && { actor: opts.actor }),
             }, (r) => {
                 const pre = preInvalid.find((p) => p.index === r.index);
@@ -1951,6 +2089,7 @@ export function registerWriteCommands(program) {
         }
         finally {
             client?.close();
+            endInvocation();
         }
     });
     program
@@ -1998,6 +2137,9 @@ export function registerWriteCommands(program) {
             usageError(opts, "--txn cannot be combined with --last or --by");
             return;
         }
+        // undo streams JSONL regardless of --json, so the interrupt guard is armed
+        // machine-readable (each inverse is a real write, GUI drives included).
+        const endInvocation = beginWriteInvocation(true, Date.now());
         let client = null;
         try {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
@@ -2054,9 +2196,10 @@ export function registerWriteCommands(program) {
         }
         finally {
             client?.close();
+            endInvocation();
         }
     });
-    addReorderPositionFlags(addDriveGuiFlag(addWriteFlags(program
+    addReorderPositionFlags(addDriveGuiFlag(addCompoundWriteFlags(program
         .command("reorder <refs...>")
         .description("The ONE reorder verb — rearrange to-dos, projects, headings, OR sidebar areas IN " +
         "PLACE (REARRANGES, never changes membership; to change what an item belongs to use " +
@@ -2155,7 +2298,8 @@ export function registerWriteCommands(program) {
         .command("set <key> <value>")
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
         "accepted-fingerprint | certified-app-version | allow-experimental | bounce-enabled | " +
-        "bounce-max-items | auto-launch | ui-enabled | ui-drive-budget-ms | trace | scope")
+        "bounce-max-items | auto-launch | helpers-enabled (auto | true | false) | ui-enabled | " +
+        "ui-drive-budget-ms | trace | scope")
         .action((key, value, opts) => {
         const map = {
             profile: "profile",
@@ -2168,6 +2312,7 @@ export function registerWriteCommands(program) {
             "bounce-enabled": "bounceEnabled",
             "bounce-max-items": "bounceMaxItems",
             "auto-launch": "autoLaunch",
+            "helpers-enabled": "helpersMode",
             "ui-enabled": "uiEnabled",
             "ui-drive-budget-ms": "uiDriveBudgetMs",
             trace: "traceEnabled",
@@ -2179,6 +2324,14 @@ export function registerWriteCommands(program) {
             process.exitCode = ExitCode.Usage;
             return;
         }
+        // `helpers-enabled` is TRI-state (auto | true | false): anything else is
+        // refused rather than silently coerced to a boolean, so a typo can never
+        // read as "off" on a machine that meant "auto".
+        if (target === "helpersMode" && parseHelpersMode(value) === undefined) {
+            process.stderr.write(`error: helpers-enabled accepts ${HELPERS_MODES.join(" | ")} (got "${value}")\n`);
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
         const parsed = target === "maxDisruption" || target === "bounceMaxItems" || target === "uiDriveBudgetMs"
             ? Number(value)
             : target === "auditEnabled" ||