things-api 0.10.0 → 0.12.0

package/dist/cli/commands/writes.js

@@ -1,7 +1,8 @@
 import { readFileSync } from "node:fs";
 import { addRepeatRuleFlags, repeatRuleFlagsFromOpts } from "./repeat-flags.js";
-import { aggregateExitCode, blockedCode, BOUNCE_MAX_ITEMS, capabilitiesTable, errorEnvelope, ExitCode, okEnvelope, openThings, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
+import { aggregateExitCode, blockedCode, capabilitiesTable, ClockError, describeConfig, errorEnvelope, ExitCode, getConfigKey, mutationWireData, okEnvelope, openThings, OP_ID_RE, outcomeFailed, ReferenceResolutionError, saveConfigKey, splitWhenSugar, ThingsDbNotFoundError, ThingsDbOpenError, verifyFailedCode, } from "../../index.js";
 import { usageError } from "../read-driver.js";
+import { dim } from "../style.js";
 function addWriteFlags(cmd) {
     return cmd
         .option("--json", "emit versioned JSON envelope on stdout")
@@ -11,14 +12,68 @@ function addWriteFlags(cmd) {
         .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("--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)");
+}
+/** Validate an `--op-id`; on a malformed value emit the usage error and return false. */
+function opIdOk(opts) {
+    if (opts.opId === undefined)
+        return true;
+    if (OP_ID_RE.test(opts.opId))
+        return true;
+    usageError(opts, "--op-id must match [A-Za-z0-9_-] and be 1-64 characters");
+    return false;
+}
+/**
+ * Refuse `--op-id` on a multi-leg COMPOUND command. Single-op idempotency (phase
+ * 1) replays exactly ONE recorded ok result; a compound records several (or a
+ * summary) and its idempotency is the batch-shaped per-line `op_id`. Refusing is
+ * honest — dropping the flag silently would leave a resubmission un-deduped.
+ * Returns true when refused (the caller returns).
+ */
+function opIdCompoundRefused(opts, what) {
+    if (opts.opId === undefined)
+        return false;
+    usageError(opts, `--op-id is not available on ${what} (a multi-leg compound in phase 1) — express it as ` +
+        "`things batch` with a per-line op_id for idempotent resubmission");
+    return true;
 }
 /** A commander flag value when present-with-value (bare presence yields `true`). */
 const flagVal = (v) => (typeof v === "string" ? v : undefined);
-/** Writes one batch result as an NDJSON line to stdout. */
+/**
+ * Writes one batch result as a FLATTENED NDJSON line to stdout: the internal
+ * `outcome` union object is collapsed to one level. `outcome` becomes its tag
+ * as a plain string (`"ok"`, `"blocked"`, `"verify-failed"`, `"unsupported"`,
+ * `"dry-run"`, `"invalid"`, `"skipped"`, `"already-applied"`, `"bounce-aborted"`),
+ * and every variant field (uuid, detail, plan, expected, observed, considered,
+ * placed, remaining, cause, …) sits as a sibling of the line-level keys. The
+ * outcome's own `op` duplicates the line-level `op`, so it is dropped. No
+ * variant field name collides with a line-level key (index, op, outcome,
+ * tempId, boundUuid, opId).
+ */
 const emit = (r) => {
-    process.stdout.write(`${JSON.stringify(r)}\n`);
+    const { index, op, outcome, tempId, boundUuid, opId } = r;
+    const { kind, op: _outcomeOp, ...variant } = outcome;
+    const line = {
+        index,
+        op,
+        outcome: kind,
+        ...variant,
+        ...(tempId !== undefined && { tempId }),
+        ...(boundUuid !== undefined && { boundUuid }),
+        ...(opId !== undefined && { opId }),
+    };
+    process.stdout.write(`${JSON.stringify(line)}\n`);
 };
+/**
+ * One `config get` line: `key: value`, plus a dim provenance marker for a
+ * default, env-sourced, or derived value (stored keys render bare).
+ */
+function configKeyLine(entry) {
+    const marker = entry.source === "stored" ? "" : ` ${dim(`(${entry.source})`)}`;
+    return `${entry.key}: ${String(entry.value)}${marker}`;
+}
 function writeOptionsFrom(opts, extra = {}) {
     const maxDisruption = opts.allowVeryDisruptive
         ? 3
@@ -32,6 +87,7 @@ function writeOptionsFrom(opts, extra = {}) {
         ...(opts.verifyTimeout !== undefined && { verifyTimeoutMs: Number(opts.verifyTimeout) }),
         ...(opts.actor !== undefined && { actor: opts.actor }),
         ...(opts.dangerouslyDriveGui === true && { dangerouslyDriveGui: true }),
+        ...(opts.opId !== undefined && { opId: opts.opId }),
         ...extra,
     };
 }
@@ -41,18 +97,48 @@ function writeOptionsFrom(opts, extra = {}) {
  * refusing. Nesting is via the clean `make new tag` path.
  */
 function addCreateTagsFlag(cmd) {
-    return cmd.option("--create-tags", "create any named tag that does not exist yet (nesting parent/child) before applying, " +
-        "instead of stopping on an unknown tag");
+    return cmd.option("--create-tags", "create any missing tag (nesting parent/child) instead of failing on an unknown tag");
 }
 /** WriteOptions extra carrying createTags when the flag is set. */
 function createTagsExtra(opts) {
     return opts["createTags"] === true ? { createTags: true } : {};
 }
+/** Heading selector help string (exact title or uuid — never an ordinal). */
+const HEADING_SEL_HELP = "heading selector: exact title or uuid";
+/** The four heading-placement flags (spec §2), shared by add/move-heading. */
+function addPlacementFlags(cmd) {
+    return cmd
+        .option("--first", "place it first among the project's headings")
+        .option("--last", "place it last among the project's headings")
+        .option("--before-heading <sel>", "place it immediately before this heading (title or uuid)")
+        .option("--after-heading <sel>", "place it immediately after this heading (title or uuid)");
+}
+function countPlacementFlags(opts) {
+    return [
+        opts["first"] === true,
+        opts["last"] === true,
+        opts["beforeHeading"] !== undefined,
+        opts["afterHeading"] !== undefined,
+    ].filter(Boolean).length;
+}
+/** Build the resolved placement from the flags, resolving anchor selectors. */
+function headingPlacement(c, projectUuid, opts) {
+    if (opts["first"] === true)
+        return { position: "first" };
+    if (opts["last"] === true)
+        return { position: "last" };
+    if (opts["beforeHeading"] !== undefined) {
+        return { before: c.resolve.heading(projectUuid, opts["beforeHeading"]).uuid };
+    }
+    if (opts["afterHeading"] !== undefined) {
+        return { after: c.resolve.heading(projectUuid, opts["afterHeading"]).uuid };
+    }
+    return undefined;
+}
 /** Add the mandatory GUI-drive acknowledgement to a ui-vector command. */
 function addDriveGuiFlag(cmd) {
-    return cmd.option("--dangerously-drive-gui", "required: this drives the local Things app through its accessibility interface to make a " +
-        "change the app offers nowhere else; also needs `things config set ui-enabled true`. " +
-        "Intended for a dedicated always-on Mac.");
+    return cmd.option("--dangerously-drive-gui", "required: visibly drives the Things app to make a change it offers nowhere else; " +
+        "also needs `things config set ui-enabled true`");
 }
 function collect(value, previous) {
     return [...previous, value];
@@ -89,23 +175,27 @@ function splitCsv(value) {
         .map((s) => s.trim())
         .filter((s) => s !== "");
 }
-async function runWrite(opts, fn) {
+async function runWrite(opts, fn, emitFn = emitResult) {
+    if (!opIdOk(opts))
+        return;
     const started = Date.now();
     let client = null;
     const meta = (client_) => {
         let dbVersion = null;
         let fingerprint = "unknown";
+        let clock;
         if (client_ !== null) {
             const fp = client_.fingerprint();
             dbVersion = fp.observation.databaseVersion;
             fingerprint = fp.kind === "ok" ? "ok" : fp.kind === "drift" ? "drift" : "unknown";
+            clock = client_.clockMeta();
         }
-        return { dbVersion, fingerprint, elapsedMs: Date.now() - started };
+        return { dbVersion, fingerprint, elapsedMs: Date.now() - started, ...(clock && { clock }) };
     };
     try {
         client = openThings(opts.db ? { dbPath: opts.db } : {});
         const result = await fn(client);
-        emitResult(result, opts, meta(client));
+        emitFn(result, opts, meta(client));
     }
     catch (err) {
         // An unresolved write target (uuid/partial-uuid/name that is ambiguous or
@@ -116,7 +206,7 @@ async function runWrite(opts, fn) {
                 process.stdout.write(`${JSON.stringify(errorEnvelope({
                     code: err.code,
                     message: err.message,
-                    details: { candidates: err.candidates },
+                    detail: { candidates: err.candidates },
                 }, meta(client)))}\n`);
             }
             else {
@@ -125,6 +215,11 @@ async function runWrite(opts, fn) {
             process.exitCode = ExitCode.Usage;
             return;
         }
+        // A malformed THINGS_TZ / THINGS_NOW fails closed as a usage error.
+        if (err instanceof ClockError) {
+            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) {
@@ -162,11 +257,14 @@ function emitResult(result, opts, meta) {
                 process.stderr.write(`warning: ${warning}\n`);
             }
             if (opts.json) {
-                process.stdout.write(`${JSON.stringify(okEnvelope("mutation-result", result, meta))}\n`);
+                process.stdout.write(`${JSON.stringify(okEnvelope("mutation-result", mutationWireData(result), meta))}\n`);
             }
             else {
                 const uuid = result.uuid === null ? "" : ` uuid=${result.uuid}`;
-                process.stdout.write(`ok ${result.op}${uuid} (vector=${result.vector}, tier=${result.tier}, verified)\n`);
+                const status = "alreadyApplied" in result && result.alreadyApplied === true
+                    ? "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`);
             }
             process.exitCode = ExitCode.Ok;
             return;
@@ -228,7 +326,7 @@ function emitResult(result, opts, meta) {
                 process.stdout.write(`${JSON.stringify(errorEnvelope({
                     code: "unsupported",
                     message: `no validated vector supports ${result.op}`,
-                    detail: result.considered,
+                    detail: { considered: result.considered },
                 }, meta))}\n`);
             }
             else {
@@ -246,6 +344,292 @@ function emitResult(result, opts, meta) {
         }
     }
 }
+// -------------------------------------------------- move / reorder (spec §4)
+/** Open the client, run a MoveResult-returning fn, and render it. */
+async function runMoveCmd(opts, fn) {
+    // A variadic move/reorder is a multi-leg COMPOUND (the batch-shaped case), not
+    // a single recorded mutation — single-op idempotency (--op-id) does not apply
+    // in phase 1. Refuse it loudly rather than silently drop it; the compound
+    // analogue is `things batch` with a per-line op_id.
+    if (opts.opId !== undefined) {
+        usageError(opts, "--op-id is not available on a variadic move/reorder (a multi-leg compound) — express it " +
+            "as `things batch` with a per-line op_id for idempotent resubmission");
+        return;
+    }
+    const started = Date.now();
+    let client = null;
+    const meta = () => {
+        let dbVersion = null;
+        let fingerprint = "unknown";
+        if (client !== null) {
+            const fp = client.fingerprint();
+            dbVersion = fp.observation.databaseVersion;
+            fingerprint = fp.kind === "ok" ? "ok" : fp.kind === "drift" ? "drift" : "unknown";
+        }
+        return { dbVersion, fingerprint, elapsedMs: Date.now() - started };
+    };
+    try {
+        client = openThings(opts.db ? { dbPath: opts.db } : {});
+        emitMoveResult(await fn(client), opts, meta());
+    }
+    catch (err) {
+        if (err instanceof ReferenceResolutionError) {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(errorEnvelope({ code: err.code, message: err.message, detail: { candidates: err.candidates } }, meta()))}\n`);
+            }
+            else {
+                process.stderr.write(`error: ${err.message}\n`);
+            }
+            process.exitCode = ExitCode.Usage;
+            return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(errorEnvelope({ code: "unexpected", message }, meta()))}\n`);
+        }
+        else {
+            process.stderr.write(`error: ${message}\n`);
+        }
+        process.exitCode = ExitCode.Unexpected;
+    }
+    finally {
+        client?.close();
+    }
+}
+function emitMoveResult(result, opts, meta) {
+    switch (result.kind) {
+        case "move-ok": {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(okEnvelope("move-result", mutationWireData(result), meta))}\n`);
+            }
+            else {
+                const who = result.movees.map((m) => m.title ?? m.uuid).join(", ");
+                process.stdout.write(`ok ${result.op}: moved ${result.movees.length} item(s) — ${who}\n` +
+                    `  placement: ${result.placementClass} — ${result.note}\n`);
+            }
+            process.exitCode = ExitCode.Ok;
+            return;
+        }
+        case "move-dry-run": {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(okEnvelope("move-plan", result.plan, meta))}\n`);
+            }
+            else {
+                process.stdout.write([
+                    `DRY RUN ${result.op}`,
+                    `  movees: ${result.plan.movees.join(", ")}`,
+                    `  membership: ${result.plan.membership}`,
+                    `  placement: ${result.plan.placement} (${result.plan.placementClass})`,
+                    `  ${result.plan.note}`,
+                    "",
+                ].join("\n"));
+            }
+            process.exitCode = ExitCode.Ok;
+            return;
+        }
+        case "move-refused": {
+            const code = result.refusal === "usage"
+                ? ExitCode.Usage
+                : result.refusal === "unsupported"
+                    ? ExitCode.Unsupported
+                    : ExitCode.Blocked;
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(errorEnvelope({
+                    code: result.refusal,
+                    message: result.detail,
+                    ...(result.remediation !== undefined && { remediation: result.remediation }),
+                    ...(result.candidates !== undefined && {
+                        detail: { candidates: result.candidates },
+                    }),
+                }, meta))}\n`);
+            }
+            else {
+                process.stderr.write(`${result.refusal === "usage" ? "error" : result.refusal.toUpperCase()}: ${result.detail}\n` +
+                    (result.remediation !== undefined ? `  remediation: ${result.remediation}\n` : ""));
+            }
+            process.exitCode = code;
+            return;
+        }
+        case "move-leg-failed": {
+            if (opts.json) {
+                process.stdout.write(`${JSON.stringify(errorEnvelope({ code: "verify-failed", message: result.detail, detail: { failed: result.failed, completed: result.completed } }, meta))}\n`);
+            }
+            else {
+                process.stderr.write(`MOVE FAILED: ${result.detail}\n`);
+            }
+            process.exitCode = ExitCode.VerifyFailed;
+            return;
+        }
+    }
+}
+/** Build a MovePosition from the shared --first/--last/--before/--after flags. */
+function movePosition(opts) {
+    const chosen = [
+        opts["first"] === true,
+        opts["last"] === true,
+        opts["before"] !== undefined,
+        opts["after"] !== undefined,
+    ].filter(Boolean).length;
+    if (chosen > 1)
+        return "conflict";
+    if (opts["first"] === true)
+        return { at: "first" };
+    if (opts["last"] === true)
+        return { at: "last" };
+    if (opts["before"] !== undefined)
+        return { before: opts["before"] };
+    if (opts["after"] !== undefined)
+        return { after: opts["after"] };
+    return undefined;
+}
+/** Build a to-do move destination; "conflict" when more than one is named. */
+function todoDestination(opts) {
+    const dests = [];
+    const toProject = opts["toProject"];
+    const toHeading = opts["toHeading"];
+    if (toHeading !== undefined) {
+        dests.push({
+            kind: "heading",
+            sel: toHeading,
+            ...(toProject !== undefined && { project: { uuid: toProject, title: toProject } }),
+        });
+    }
+    else if (toProject !== undefined) {
+        dests.push({ kind: "project", ref: { uuid: toProject, title: toProject } });
+    }
+    const toArea = opts["toArea"];
+    if (toArea !== undefined)
+        dests.push({ kind: "area", ref: { uuid: toArea, title: toArea } });
+    // Commander maps `--no-heading`/`--no-area` onto the base key as `false`.
+    if (opts["heading"] === false)
+        dests.push({ kind: "no-heading" });
+    if (opts["loose"] === true)
+        dests.push({ kind: "loose" });
+    if (opts["inbox"] === true)
+        dests.push({ kind: "inbox" });
+    if (opts["area"] === false)
+        dests.push({ kind: "no-area" });
+    if (opts["detach"] === true)
+        dests.push({ kind: "detach" });
+    if (dests.length > 1)
+        return "conflict";
+    return dests[0];
+}
+/** Build a project move destination; "conflict" when more than one is named. */
+function projectDestination(opts) {
+    const dests = [];
+    const toArea = opts["toArea"];
+    if (toArea !== undefined)
+        dests.push({ kind: "area", ref: { uuid: toArea, title: toArea } });
+    // Commander maps `--no-area` onto the base key `area` as `false`.
+    if (opts["area"] === false)
+        dests.push({ kind: "no-area" });
+    if (opts["loose"] === true)
+        dests.push({ kind: "loose" });
+    if (opts["detach"] === true)
+        dests.push({ kind: "detach" });
+    if (dests.length > 1)
+        return "conflict";
+    return dests[0];
+}
+/** The shared position flags (--first/--last/--before/--after) for move/reorder. */
+function addPositionFlags(cmd) {
+    return cmd
+        .option("--first", "place the block at the top of its bucket")
+        .option("--last", "place the block at the bottom of its bucket")
+        .option("--before <ref>", "place the block immediately before this item (same bucket)")
+        .option("--after <ref>", "place the block immediately after this item (same bucket)");
+}
+/** One TTY line for a bulk-add batch item (the human, non-JSON multi rendering). */
+function addResultLine(r) {
+    const o = r.outcome;
+    switch (o.kind) {
+        case "ok":
+            return `ok todo.add uuid=${o.uuid ?? ""} (vector=${o.vector}, tier=${o.tier}, verified)\n`;
+        case "dry-run":
+            return `DRY RUN todo.add (vector=${o.plan.vector}, tier ${o.plan.tier}) ${o.plan.invocation}\n`;
+        case "already-applied":
+            return `already-applied todo.add uuid=${o.uuid}\n`;
+        case "skipped":
+            return `skipped todo.add: ${o.detail}\n`;
+        case "invalid":
+            return `FAILED todo.add: ${o.detail}\n`;
+        case "blocked":
+            return `BLOCKED todo.add (${o.hazard ?? o.reason}): ${o.detail}\n`;
+        case "verify-failed":
+            return `VERIFY FAILED todo.add (${o.reason}): ${o.detail}\n`;
+        case "unsupported":
+            return `UNSUPPORTED todo.add\n`;
+        default:
+            return `FAILED todo.add: ${JSON.stringify(o)}\n`;
+    }
+}
+/**
+ * Run a bulk `todo add` as ONE batch of `todo.add` legs (shared flags already
+ * compiled into every op's params). Streams per-line results and a trailing
+ * summary carrying the single `undoToken` that removes the whole skeleton —
+ * except under `--id-only`, where output is exactly one uuid per created item,
+ * in creation order, and nothing else. Exit code is the worst leg's failure.
+ */
+async function runBulkAdd(opts, ops, idOnly) {
+    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.actor !== undefined && { actor: opts.actor }),
+        }, (r) => {
+            if (idOnly) {
+                if (r.outcome.kind === "ok" && r.outcome.uuid !== null)
+                    process.stdout.write(`${r.outcome.uuid}\n`);
+            }
+            else if (opts.json) {
+                emit(r);
+            }
+            else {
+                process.stdout.write(addResultLine(r));
+            }
+        });
+        const failed = batchResult.results.filter((r) => outcomeFailed(r.outcome));
+        if (!idOnly) {
+            const total = batchResult.results.length;
+            const okCount = total - failed.length;
+            if (opts.json) {
+                const summary = {
+                    summary: {
+                        total,
+                        ok: okCount,
+                        failed: failed.filter((r) => r.outcome.kind !== "skipped").length,
+                        skipped: batchResult.results.filter((r) => r.outcome.kind === "skipped").length,
+                        ...(batchResult.undoToken !== undefined && { undoToken: batchResult.undoToken }),
+                    },
+                };
+                process.stdout.write(`${JSON.stringify(summary)}\n`);
+            }
+            else {
+                const undo = batchResult.undoToken !== undefined
+                    ? ` (undo all: things undo --txn ${batchResult.undoToken})`
+                    : "";
+                process.stdout.write(`added ${okCount}/${total} to-dos${undo}\n`);
+            }
+        }
+        process.exitCode = aggregateExitCode(failed.map((r) => r.outcome));
+    }
+    finally {
+        client?.close();
+    }
+}
+/** Read newline-delimited titles from stdin; blank lines (whitespace-only) skipped. */
+async function readStdinTitles() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks)
+        .toString("utf8")
+        .split("\n")
+        .map((l) => l.replace(/\r$/, ""))
+        .filter((l) => l.trim() !== "");
+}
 function group(program, name, description) {
     const existing = program.commands.find((c) => c.name() === name);
     if (existing !== undefined)
@@ -256,12 +640,15 @@ const containerRef = (value) => value === undefined ? undefined : { uuid: value,
 export function registerWriteCommands(program) {
     const todo = group(program, "todo", "To-do–scoped operations");
     addCreateTagsFlag(addWriteFlags(todo
-        .command("add <title>")
-        .description("Create a to-do; its uuid is printed on success. Projects, areas, and headings " +
-        "must name existing items — unknown or ambiguous references are rejected. A tag " +
-        "may be a name or a parent/child path, and must exist unless " +
+        .command("add [titles...]")
+        .description("Create one or more to-dos; each new uuid is printed on success. Pass several " +
+        "titles to create a quick skeleton in one call, or stream them with --stdin " +
+        "(one title per line); every shared flag below applies to each title. Projects, " +
+        "areas, and headings must name existing items — unknown or ambiguous references " +
+        "are rejected. A tag may be a name or a parent/child path, and must exist unless " +
         "--create-tags. Adding into a completed/canceled project reopens that project — " +
-        "requires --acknowledge-project-reopen.")
+        "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("--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")
@@ -271,14 +658,33 @@ export function registerWriteCommands(program) {
         .option("--project <ref>", "destination project (uuid or unique name)")
         .option("--area <ref>", "destination area (uuid or unique name)")
         .option("--heading <name>", "existing heading in the destination project")
-        .option("--acknowledge-project-reopen", "allow adding into a completed/canceled project"))).action(async (title, opts) => {
+        .option("--acknowledge-project-reopen", "allow adding into a completed/canceled project")
+        .option("--stdin", "read newline-delimited titles from stdin (blank lines skipped); exclusive with title arguments")
+        .option("--id-only", "print only the new uuid(s), one per line in creation order, and nothing else (exclusive with --json)"))).action(async (titles, opts) => {
+        const idOnly = opts["idOnly"] === true;
+        const useStdin = opts["stdin"] === true;
+        if (idOnly && opts.json === true) {
+            usageError(opts, "--id-only and --json are mutually exclusive");
+            return;
+        }
+        if (useStdin && titles.length > 0) {
+            usageError(opts, "--stdin is mutually exclusive with title arguments");
+            return;
+        }
+        const finalTitles = useStdin ? await readStdinTitles() : titles;
+        if (finalTitles.length === 0) {
+            usageError(opts, useStdin
+                ? "no titles: --stdin received no non-empty lines"
+                : "provide at least one title, or pass --stdin to read titles from stdin");
+            return;
+        }
         const checklist = opts["checklistItem"];
         const tags = splitCsv(opts["tags"]);
         const project = containerRef(opts["project"]);
         const area = containerRef(opts["area"]);
         if (!whenSugarOk(opts))
             return;
-        await runWrite(opts, (c) => c.write.addTodo({
+        const buildParams = (title) => ({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
             ...(opts["when"] !== undefined && { when: opts["when"] }),
@@ -289,12 +695,65 @@ export function registerWriteCommands(program) {
             ...(project !== undefined && { project }),
             ...(area !== undefined && { area }),
             ...(opts["heading"] !== undefined && { heading: opts["heading"] }),
-        }, writeOptionsFrom(opts, {
-            ...(opts["acknowledgeProjectReopen"] !== undefined && {
-                acknowledgeProjectReopen: opts["acknowledgeProjectReopen"],
-            }),
-            ...createTagsExtra(opts),
-        })));
+        });
+        const ackReopen = opts["acknowledgeProjectReopen"] !== undefined
+            ? { acknowledgeProjectReopen: opts["acknowledgeProjectReopen"] }
+            : {};
+        // A multi-title add compiles onto the batch machinery (below), where
+        // idempotency is a per-LINE op_id, not one key for the whole skeleton —
+        // refuse --op-id there rather than drop it. A single-title add is a single
+        // mutation and takes --op-id normally (validated inside runWrite).
+        if (finalTitles.length > 1 && opts.opId !== undefined) {
+            usageError(opts, "--op-id applies to a single-title add — for a multi-title add use `things batch` with a " +
+                "per-line op_id");
+            return;
+        }
+        // Single title (positional or a one-line stdin) keeps today's single
+        // mutation-result envelope exactly — unless --id-only, which prints just
+        // the new uuid. Multiple titles compile onto the batch machinery.
+        if (finalTitles.length === 1) {
+            const params = buildParams(finalTitles[0]);
+            const wopts = writeOptionsFrom(opts, { ...ackReopen, ...createTagsExtra(opts) });
+            if (!idOnly) {
+                await runWrite(opts, (c) => c.write.addTodo(params, wopts));
+                return;
+            }
+            await runWrite(opts, (c) => c.write.addTodo(params, wopts), (result, o, meta) => {
+                if (result.kind === "ok") {
+                    if (result.uuid !== null)
+                        process.stdout.write(`${result.uuid}\n`);
+                    process.exitCode = ExitCode.Ok;
+                }
+                else if (result.kind === "dry-run") {
+                    // --id-only mints no uuid to print on a dry-run; stay silent.
+                    process.exitCode = ExitCode.Ok;
+                }
+                else {
+                    emitResult(result, { ...o, json: false }, meta);
+                }
+            });
+            return;
+        }
+        // Multi-title: one batch of todo.add legs, shared flags applied to each.
+        const perOpOptions = {
+            ...ackReopen,
+            ...(opts["createTags"] === true && { createTags: true }),
+            ...(opts.vector !== undefined && { vector: opts.vector }),
+            ...(opts.allowVeryDisruptive === true
+                ? { maxDisruption: 3 }
+                : opts.allowDisruptive === true
+                    ? { maxDisruption: 2 }
+                    : {}),
+            ...(opts.verifyTimeout !== undefined && { verifyTimeoutMs: Number(opts.verifyTimeout) }),
+        };
+        const hasPerOpOptions = Object.keys(perOpOptions).length > 0;
+        const ops = finalTitles.map((title) => {
+            const op = { op: "todo.add", params: buildParams(title) };
+            if (hasPerOpOptions)
+                op.options = perOpOptions;
+            return op;
+        });
+        await runBulkAdd(opts, ops, idOnly);
     });
     addWriteFlags(todo
         .command("update <uuid>")
@@ -350,35 +809,47 @@ export function registerWriteCommands(program) {
             await runWrite(opts, (c) => c.write[method](uuid, writeOptionsFrom(opts)));
         });
     }
-    addWriteFlags(todo
-        .command("move <uuid>")
-        .description("Move a to-do into a project or area (optionally under an existing heading), back " +
-        "to the Inbox, or out of every container. Unknown or ambiguous destinations are " +
-        "rejected. Moving into a completed/canceled project reopens that project — " +
-        "requires --acknowledge-project-reopen.")
-        .option("--project <ref>", "destination project (uuid or unique name)")
-        .option("--area <ref>", "destination area (uuid or unique name)")
-        .option("--heading <name>", "existing heading in the destination project")
+    addPositionFlags(addWriteFlags(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 " +
+        "rearrange to-dos that already share a container use `things todo reorder`. Pass one " +
+        "destination: --to-project / --to-heading / --to-area, or the detach family " +
+        "--no-heading (leave the heading, stay in the project) / --loose (leave heading, " +
+        "project, AND area). --inbox files back to the Inbox. Position with " +
+        "--first/--last/--before/--after (an anchor positions but never migrates — an " +
+        "anchor-only move that would cross containers is refused). Membership always " +
+        "succeeds; placement is guaranteed for loose lists, a project's/area's members, a " +
+        "heading's children, and a container's same-day scheduled children — the result " +
+        "states the placement class, and a bounce that co-bounces unnamed siblings to honor " +
+        "an anchor lists them. Set bounce-max-items to cap how many items a bounce touches; " +
+        "bounce-enabled=false refuses bounce-dependent placements. Moving into a " +
+        "completed/canceled project reopens it — requires --acknowledge-project-reopen.")
+        .option("--to-project <ref>", "destination project (uuid or unique name)")
+        .option("--to-heading <sel>", "destination heading (exact title or uuid; within --to-project)")
+        .option("--to-area <ref>", "destination area (uuid or unique name)")
+        .option("--no-heading", "leave the heading but stay in the current project (unheaded block)")
+        .option("--loose", "detach from heading, project, AND area (keeping the schedule)")
         .option("--inbox", "move back to the Inbox — removes any schedule")
-        .option("--detach", "remove ALL container links (project/area/heading) keeping the schedule")
-        .option("--acknowledge-project-reopen", "allow moving into a completed/canceled project")).action(async (uuid, opts) => {
-        const project = containerRef(opts["project"]);
-        const area = containerRef(opts["area"]);
-        const inbox = opts["inbox"] === true;
-        const detach = opts["detach"] === true;
-        const dest = project !== undefined || area !== undefined || opts["heading"] !== undefined;
-        if ((inbox && (dest || detach)) || (detach && dest)) {
-            usageError(opts, "--inbox/--detach are exclusive with each other and with --project/--area/--heading");
+        .option("--no-area", "(not a to-do flag — teaches the correct spelling)")
+        .option("--detach", "(removed — teaches the replacement family)")
+        .option("--acknowledge-project-reopen", "allow moving into a completed/canceled project"))).action(async (refs, opts) => {
+        const dest = todoDestination(opts);
+        if (dest === "conflict") {
+            usageError(opts, "pass at most one destination (--to-project/--to-heading/--to-area/--no-heading/--loose/--inbox)");
             return;
         }
-        await runWrite(opts, (c) => c.write.moveTodo(uuid, {
-            ...(project !== undefined && { project }),
-            ...(area !== undefined && { area }),
-            ...(opts["heading"] !== undefined && { heading: opts["heading"] }),
-            ...(inbox && { inbox: true }),
-            ...(detach && { detach: true }),
-        }, writeOptionsFrom(opts, {
-            ...(inbox && { vector: "applescript" }),
+        const position = movePosition(opts);
+        if (position === "conflict") {
+            usageError(opts, "pass at most one of --first/--last/--before/--after");
+            return;
+        }
+        const request = {
+            uuids: refs,
+            ...(dest !== undefined && { destination: dest }),
+            ...(position !== undefined && { position }),
+        };
+        await runMoveCmd(opts, (c) => c.write.moveTodos(request, writeOptionsFrom(opts, {
             ...(opts["acknowledgeProjectReopen"] !== undefined && {
                 acknowledgeProjectReopen: opts["acknowledgeProjectReopen"],
             }),
@@ -411,12 +882,10 @@ export function registerWriteCommands(program) {
         .command("checklist <uuid>")
         .description("Edit a to-do's checklist. WHOLESALE: --item (repeatable) replaces the whole list, " +
         "discarding the existing items and their checked states — requires " +
-        "--acknowledge-checklist-reset when items exist. GRANULAR (one per call): " +
-        "--add/--remove/--check/--uncheck/--rename+--to/--move-item+--to-position change " +
-        "a single item with every other item's checked state PRESERVED (no reset flag " +
-        "needed). Target an item by title or by --index (1-based); duplicate titles are " +
-        "resolved best-effort (check → first unchecked, etc.). Checklist item uuids are " +
-        "internal and never exposed.")
+        "--acknowledge-checklist-reset when items exist. GRANULAR (one action per call): " +
+        "the flags below add, remove, check, uncheck, rename, or move a single item, with " +
+        "every other item's checked state PRESERVED. Target an item by title or by --index " +
+        "(1-based); duplicate titles resolve best-effort. Checklist items have no exposed uuid.")
         .option("--item <text>", "wholesale: checklist item in order (repeatable)", collect, [])
         .option("--acknowledge-checklist-reset", "accept wholesale replacement of existing items")
         .option("--add <title>", "granular: append an item")
@@ -472,6 +941,8 @@ export function registerWriteCommands(program) {
                             : action === "rename"
                                 ? { action: "rename", ...target, title: opts["to"] }
                                 : { action: "move", ...target, to: Number(opts["toPosition"]) };
+            if (opIdCompoundRefused(opts, "a granular checklist edit"))
+                return;
             await runWrite(opts, (c) => c.write.editChecklist(uuid, edit, writeOptionsFrom(opts)));
             return;
         }
@@ -496,12 +967,12 @@ export function registerWriteCommands(program) {
     });
     addWriteFlags(todo
         .command("clear-reminder <uuid>")
-        .description("Clear a to-do's time-of-day reminder while keeping its scheduled date. When the " +
-        "Things proxy shortcuts are installed (`things setup shortcuts`) this happens in " +
-        "place, and it is the only way for a repeating to-do; otherwise a non-repeating " +
-        "date-scheduled to-do falls back to a URL re-schedule that briefly moves it to Today " +
-        "and back. Reversible with `things undo`. Force a delivery path with --vector " +
-        "shortcuts|url-scheme.")).action(async (uuid, opts) => {
+        .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 " +
+        "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"))
+            return;
         await runWrite(opts, (c) => c.write.clearReminder(uuid, writeOptionsFrom(opts)));
     });
     addWriteFlags(todo
@@ -542,15 +1013,14 @@ export function registerWriteCommands(program) {
             "todo.make-repeating",
             "Turn a plain to-do into a repeating one. This REPLACES the to-do with a new repeating " +
                 "series — the original disappears and a fresh recurring item takes its place " +
-                "(cannot be undone). Set the frequency and interval, and optionally the weekday set, " +
-                "monthly/yearly day, end bound, reminders, or deadline.",
+                "(cannot be undone). Set the rule with the flags below; see `things help repeating`.",
         ],
         [
             "reschedule-repeat",
             "todo.reschedule-repeat",
             "Change an existing repeating to-do's rule in place (the item keeps its identity). Set the " +
-                "frequency and interval, and optionally the weekday set, monthly/yearly day, end bound, " +
-                "reminders, or deadline. `things undo` restores the previous rule.",
+                "new rule with the flags below; see `things help repeating`. `things undo` restores the " +
+                "previous rule.",
         ],
     ]) {
         addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(todo
@@ -591,69 +1061,153 @@ export function registerWriteCommands(program) {
             await runWrite(opts, (c) => c.write.run(op, { uuid }, writeOptionsFrom(opts)));
         });
     }
-    const heading = group(program, "heading", "Heading-scoped operations");
-    addWriteFlags(heading
-        .command("add <project> <title>")
+    const project = group(program, "project", "Project-scoped operations");
+    // --- project headings (spec §2) ------------------------------------------
+    // A heading exists only inside a project. Each verb takes <project-ref> then
+    // a heading selector: an exact title OR a uuid (never an ordinal — an index
+    // 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
+        .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). This uses the Things " +
-        "proxy shortcuts — run `things setup shortcuts` once first.")).action(async (project, title, opts) => {
-        await runWrite(opts, (c) => c.write.createHeading({ uuid: project, title: project }, title, writeOptionsFrom(opts)));
+        "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 " +
+        "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) {
+            usageError(opts, "pass at most one of --first / --last / --before-heading / --after-heading");
+            return;
+        }
+        if (opIdCompoundRefused(opts, "add-heading"))
+            return;
+        await runWrite(opts, (c) => {
+            const proj = c.resolve.project(projectRef);
+            const placement = headingPlacement(c, proj.uuid, opts);
+            return c.write.addHeading({ uuid: proj.uuid }, title, placement, writeOptionsFrom(opts));
+        });
     });
-    addWriteFlags(heading
-        .command("rename <uuid> <title>")
-        .description("Rename a heading in place (works on archived headings too).")).action(async (uuid, title, opts) => {
-        await runWrite(opts, (c) => c.write.renameHeading(uuid, title, writeOptionsFrom(opts)));
+    addWriteFlags(project
+        .command("rename-heading <project> <heading>")
+        .description(`Rename a heading in place (works on archived headings too). <heading> is a ${HEADING_SEL_HELP}.`)
+        .requiredOption("--to <title>", "the new heading title")).action(async (projectRef, sel, opts) => {
+        await runWrite(opts, (c) => {
+            const proj = c.resolve.project(projectRef);
+            const h = c.resolve.heading(proj.uuid, sel);
+            return c.write.renameHeading(h.uuid, opts["to"], writeOptionsFrom(opts));
+        });
     });
-    addWriteFlags(heading
-        .command("archive <uuid>")
+    addWriteFlags(project
+        .command("archive-heading <project> <heading>")
         .description("Archive a heading — it leaves the active project view (reversible with " +
-        "`things heading unarchive`). This is the preferred way to retire a heading: " +
+        "`things project unarchive-heading`). This is the preferred way to retire a heading: " +
         "row DELETION exists only in the app's UI and Shortcuts with a per-run consent " +
         "dialog, never headlessly. With open children, --children is required: " +
         "complete/cancel resolve them with the heading (one atomic cascade); reparent " +
         "moves them to the project root first, keeping them open — a compound sequence " +
-        "that `things undo` reverses as one unit.")
-        .option("--children <policy>", "complete | cancel | reparent (required when children are open)")).action(async (uuid, opts) => {
+        `that \`things undo\` reverses as one unit. <heading> is a ${HEADING_SEL_HELP}.`)
+        .option("--children <policy>", "complete | cancel | reparent (required when children are open)")).action(async (projectRef, sel, opts) => {
         const children = opts["children"];
+        if (opIdCompoundRefused(opts, "archive-heading"))
+            return;
         await runWrite(opts, async (c) => {
-            const outcome = await c.write.archiveHeading(uuid, children ? { children } : {}, writeOptionsFrom(opts));
+            const proj = c.resolve.project(projectRef);
+            const h = c.resolve.heading(proj.uuid, sel);
+            const outcome = await c.write.archiveHeading(h.uuid, children ? { children } : {}, writeOptionsFrom(opts));
             for (const leg of outcome.reparented) {
                 process.stderr.write(`reparented: ${leg.title} (${leg.result.kind})\n`);
             }
             return outcome.heading;
         });
     });
-    addWriteFlags(heading
-        .command("unarchive <uuid>")
+    addWriteFlags(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 " +
         "someday child comes back as someday). Children resolved at other times are " +
-        "never touched.")
-        .option("--restore-children", "reopen cascade-resolved children too")).action(async (uuid, opts) => {
+        `never touched. <heading> is a ${HEADING_SEL_HELP}.`)
+        .option("--restore-children", "reopen cascade-resolved children too")).action(async (projectRef, sel, opts) => {
+        if (opIdCompoundRefused(opts, "unarchive-heading"))
+            return;
         await runWrite(opts, async (c) => {
-            const outcome = await c.write.unarchiveHeading(uuid, opts["restoreChildren"] === true ? { restoreChildren: true } : {}, writeOptionsFrom(opts));
+            const proj = c.resolve.project(projectRef);
+            const h = c.resolve.heading(proj.uuid, sel);
+            const outcome = await c.write.unarchiveHeading(h.uuid, opts["restoreChildren"] === true ? { restoreChildren: true } : {}, writeOptionsFrom(opts));
             for (const child of outcome.children) {
                 process.stderr.write(`restored: ${child.title} (${child.result.kind})\n`);
             }
             return outcome.heading;
         });
     });
-    addDriveGuiFlag(addWriteFlags(heading
-        .command("convert-to-project <uuid>")
-        .description("Convert a heading into a project. This REPLACES the heading with a new project — it " +
+    addDriveGuiFlag(addWriteFlags(project
+        .command("promote-heading <project> <heading>")
+        .description("Promote a heading into a project. This REPLACES the heading with a new project — it " +
         "is promoted alongside its parent project (into the same area) and the heading's " +
         "to-dos move under the new project. The heading's identity is gone and it cannot be " +
-        "undone. The new project's uuid is printed on success."))).action(async (uuid, opts) => {
-        await runWrite(opts, (c) => c.write.run("heading.convert-to-project", { uuid }, writeOptionsFrom(opts)));
+        `undone. The new project's uuid is printed on success. <heading> is a ${HEADING_SEL_HELP}.`))).action(async (projectRef, sel, opts) => {
+        await runWrite(opts, (c) => {
+            const proj = c.resolve.project(projectRef);
+            const h = c.resolve.heading(proj.uuid, sel);
+            return c.write.run("project.promote-heading", { uuid: h.uuid }, writeOptionsFrom(opts));
+        });
+    });
+    addPlacementFlags(addWriteFlags(project
+        .command("move-heading <project> <headings...>")
+        .description("Reposition one or more of a project's headings as an ordered block — the selection " +
+        "order is the resulting order, and each heading's to-dos follow it. Pass exactly one " +
+        "placement: --first, --last, --before-heading <sel>, or --after-heading <sel>. Each " +
+        `<heading> is a ${HEADING_SEL_HELP}. Reordering headings rides the same experimental ` +
+        "surface as `things reorder` — enable it once with `things config set " +
+        "allow-experimental true`."))).action(async (projectRef, sels, opts) => {
+        if (countPlacementFlags(opts) !== 1) {
+            usageError(opts, "pass exactly one of --first / --last / --before-heading / --after-heading");
+            return;
+        }
+        await runWrite(opts, (c) => {
+            const proj = c.resolve.project(projectRef);
+            const headings = sels.map((s) => c.resolve.heading(proj.uuid, s).uuid);
+            const placement = headingPlacement(c, proj.uuid, opts);
+            return c.write.moveHeading({ uuid: proj.uuid }, headings, placement, writeOptionsFrom(opts));
+        });
+    });
+    addWriteFlags(project
+        .command("move-heading-to-project <project> <heading>")
+        .requiredOption("--to <project>", "destination project (uuid or unique title)")
+        .description("Move a heading — WITH its to-dos — to a DIFFERENT project. This is the cross-project " +
+        "relocation, distinct from `move-heading` (which only reorders a heading within its own " +
+        `project). <heading> is a ${HEADING_SEL_HELP} in the SOURCE <project>; --to names the ` +
+        "destination. GUI-ONLY: it drives the heading row's ellipsis Move… menu, so enable it " +
+        "once with `things config set ui.enabled true` and pass --dangerously-drive-gui. Fails " +
+        "closed when the heading title is shared by another heading in the project, or the " +
+        "destination title by another project (the drive addresses both by title). No undo — " +
+        "move it back to reverse.")).action(async (projectRef, sel, opts) => {
+        await runWrite(opts, (c) => {
+            const proj = c.resolve.project(projectRef);
+            const dest = c.resolve.project(String(opts["to"]));
+            return c.write.moveHeadingToProject({ uuid: proj.uuid }, sel, { uuid: dest.uuid }, writeOptionsFrom(opts));
+        });
+    });
+    addWriteFlags(project
+        .command("dissolve-heading <project> <heading>")
+        .description("Dissolve a heading — remove it but KEEP its to-dos, which become direct children of the " +
+        "project (in the same order), NOT trashed. This is the opposite of deleting: nothing is " +
+        `lost. <heading> is a ${HEADING_SEL_HELP}. Contrast \`things todo delete\` and the ` +
+        "Shortcuts heading-delete cascade, which TRASH the children. GUI-ONLY (drives the " +
+        "heading row's ellipsis Delete): enable it once with `things config set ui.enabled true` " +
+        "and pass --dangerously-drive-gui. Fails closed when the heading title is shared by " +
+        "another heading in the project. No undo — re-create the heading and move the to-dos back.")).action(async (projectRef, sel, opts) => {
+        await runWrite(opts, (c) => {
+            const proj = c.resolve.project(projectRef);
+            const h = c.resolve.heading(proj.uuid, sel);
+            return c.write.dissolveHeading(h.uuid, writeOptionsFrom(opts));
+        });
     });
-    const project = group(program, "project", "Project-scoped operations");
     // --- ui vector: repeating-project transforms (two-key gated) -------------
     addDriveGuiFlag(addRepeatRuleFlags(addWriteFlags(project
         .command("reschedule-repeat <ref>")
         .description("Change an existing repeating project's rule in place (target by uuid or unique name; " +
-        "the project keeps its identity). " +
-        "Set the frequency and interval, and optionally the weekday set, monthly/yearly day, " +
-        "end bound, reminders, or deadline. `things undo` restores the previous rule.")
+        "the project keeps its identity). Set the new rule with the flags below; see " +
+        "`things help repeating`. `things undo` restores the previous rule.")
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
         const frequency = opts["frequency"];
@@ -686,12 +1240,13 @@ export function registerWriteCommands(program) {
         .description("Turn a project into a repeating one. This REPLACES the project with a new repeating " +
         "series — the original disappears and a fresh recurring project takes its place (its " +
         "area is kept; cannot be undone). An Anytime project with no area is moved to Someday " +
-        "first (a cleanup-free intermediate step, shown in --dry-run). Set the frequency and " +
-        "interval, and optionally the weekday set, monthly/yearly day, end bound, reminders, " +
-        "or deadline.")
+        "first (a cleanup-free intermediate step, shown in --dry-run). Set the rule with the " +
+        "flags below; see `things help repeating`.")
         .requiredOption("--frequency <freq>", REPEAT_FREQ_HELP)
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP)))).action(async (uuid, opts) => {
         const frequency = opts["frequency"];
+        if (opIdCompoundRefused(opts, "project make-repeating"))
+            return;
         await runWrite(opts, (c) => c.write.makeRepeatingProject(uuid, {
             frequency,
             interval: Number(opts["interval"]),
@@ -699,7 +1254,7 @@ export function registerWriteCommands(program) {
         }, writeOptionsFrom(opts)));
     });
     addDriveGuiFlag(addWriteFlags(project
-        .command("create-repeating <title>")
+        .command("add-repeating <title>")
         .description("Create a project and turn it into a repeating series in ONE call. Two operations: the " +
         "project is created first and PERSISTS even if the make-repeating step refuses; then it " +
         "is promoted (which drives the GUI). Give --area to place it, or omit it to create in " +
@@ -712,7 +1267,9 @@ export function registerWriteCommands(program) {
         .requiredOption("--interval <n>", REPEAT_INTERVAL_HELP))).action(async (title, opts) => {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
-        await runWrite(opts, (c) => c.write.createRepeatingProject({
+        if (opIdCompoundRefused(opts, "project add-repeating"))
+            return;
+        await runWrite(opts, (c) => c.write.addRepeatingProject({
             title,
             ...(opts["notes"] !== undefined && { notes: opts["notes"] }),
             ...(area !== undefined && { area }),
@@ -724,12 +1281,14 @@ export function registerWriteCommands(program) {
     });
     addWriteFlags(project
         .command("add <title>")
-        .description("Create a project; its uuid is printed on success.")
+        .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("--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("--todo <title>", "initial child to-do (repeatable)", collect, [])).action(async (title, opts) => {
+        .option("--todo <title>", "initial child to-do, repeatable (seeds the new project)", collect, [])).action(async (title, opts) => {
         const todos = opts["todo"];
         const area = containerRef(opts["area"]);
         await runWrite(opts, (c) => c.write.addProject({
@@ -803,20 +1362,35 @@ export function registerWriteCommands(program) {
             ? c.write.setProjectTags(uuid, set, writeOptionsFrom(opts, createTagsExtra(opts)))
             : c.write.addProjectTags(uuid, add ?? [], writeOptionsFrom(opts, createTagsExtra(opts))));
     });
-    addWriteFlags(project
-        .command("move <ref>")
-        .description("Move a project (target by uuid or unique name) to another area, or DETACH it from " +
-        "its current area (--detach). Status and schedule are untouched. Unknown areas are " +
-        "rejected.")
-        .option("--area <ref>", "destination area (uuid or unique name)")
-        .option("--detach", "remove the current area assignment (exclusive with --area)")).action(async (uuid, opts) => {
-        if ((opts.detach === true) === (opts.area !== undefined)) {
-            usageError(opts, "pass exactly one of --area / --detach");
+    addPositionFlags(addWriteFlags(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 " +
+        "area — a project's complete detach). Position among siblings with " +
+        "--first/--last/--before/--after (an anchor positions but never migrates). " +
+        "Membership always succeeds; top-of-bucket placement is guaranteed only where a " +
+        "reorder protocol exists (the result states the class). Status and schedule are " +
+        "untouched.")
+        .option("--to-area <ref>", "destination area (uuid or unique name)")
+        .option("--no-area", "leave the current area (a project's single-level detach)")
+        .option("--loose", "(not a project flag — teaches the correct spelling)")
+        .option("--detach", "(removed — teaches the replacement)"))).action(async (refs, opts) => {
+        const dest = projectDestination(opts);
+        if (dest === "conflict") {
+            usageError(opts, "pass at most one of --to-area / --no-area");
             return;
         }
-        await runWrite(opts, (c) => opts.detach === true
-            ? c.write.detachProject(uuid, writeOptionsFrom(opts))
-            : c.write.moveProject(uuid, { uuid: opts.area, title: opts.area }, writeOptionsFrom(opts)));
+        const position = movePosition(opts);
+        if (position === "conflict") {
+            usageError(opts, "pass at most one of --first/--last/--before/--after");
+            return;
+        }
+        const request = {
+            uuids: refs,
+            ...(dest !== undefined && { destination: dest }),
+            ...(position !== undefined && { position }),
+        };
+        await runMoveCmd(opts, (c) => c.write.moveProjects(request, writeOptionsFrom(opts)));
     });
     addWriteFlags(project
         .command("cancel <ref>")
@@ -834,6 +1408,8 @@ export function registerWriteCommands(program) {
         "project — children resolved earlier are never touched. Exit 3 if any child " +
         "restore fails.")
         .option("--restore-children", "also reopen the children resolved with the project")).action(async (uuid, opts) => {
+        if (opIdCompoundRefused(opts, "project reopen"))
+            return;
         const started = Date.now();
         let client = null;
         try {
@@ -928,9 +1504,8 @@ export function registerWriteCommands(program) {
         .command("reorder <ref>")
         .description("Move an area to a new position in the area order (target by uuid or unique name). " +
         "Pass exactly one destination: --before/--after another area, or --first/--last. " +
-        "This drives the Things window with the pointer — the app comes to the front and " +
-        "the sidebar may scroll while the area is moved; the area's projects and to-dos " +
-        "are untouched.")
+        "This visibly drives the Things app (the window comes forward and the sidebar may " +
+        "scroll); the area's projects and to-dos are untouched.")
         .option("--before <area>", "place it immediately above this area (uuid or unique name)")
         .option("--after <area>", "place it immediately below this area (uuid or unique name)")
         .option("--first", "move it to the top of the area list")
@@ -956,13 +1531,18 @@ export function registerWriteCommands(program) {
     addWriteFlags(area
         .command("delete <ref>")
         .description("Delete an area PERMANENTLY — areas do not go to the Trash, so this cannot be " +
-        "undone; requires --dangerously-permanent. The area's to-dos move to the Trash; " +
-        "its projects remain, no longer assigned to any area.")
-        .option("--dangerously-permanent", "accept permanent, unrecoverable deletion")).action(async (target, opts) => {
+        "undone; requires --dangerously-permanent. Deleting an area moves its to-dos and " +
+        "projects to the Trash, so a non-empty area is refused unless you pass " +
+        "--allow-non-empty; empty the area first to keep its contents.")
+        .option("--dangerously-permanent", "accept permanent, unrecoverable deletion")
+        .option("--allow-non-empty", "delete the area together with its contents (its to-dos and projects move to the Trash)")).action(async (target, opts) => {
         await runWrite(opts, (c) => c.write.deleteArea(target, writeOptionsFrom(opts, {
             ...(opts["dangerouslyPermanent"] !== undefined && {
                 dangerouslyPermanent: opts["dangerouslyPermanent"],
             }),
+            ...(opts["allowNonEmpty"] !== undefined && {
+                allowNonEmptyArea: opts["allowNonEmpty"],
+            }),
         })));
     });
     const tag = group(program, "tag", "Tag-scoped operations");
@@ -1044,6 +1624,15 @@ export function registerWriteCommands(program) {
         "failure does not roll back earlier ops. Per-op results stream as JSONL. Per-op " +
         "options carry the confirmation flags (acknowledgeChecklistReset, " +
         "acknowledgeProjectReopen, dangerouslyPermanent, acknowledgeTagSubtree). " +
+        "CHAINING: an op that creates something may carry a `tempId` (a handle like " +
+        '"proj1"); a LATER op references that new uuid as "$proj1" in any id/container ' +
+        'param (dotted "$proj1.instance"/"$proj1.replaced" reach a repeating op\'s spawned ' +
+        "instance / replaced source). A tempId is valid only on a creating op (not tag.add — " +
+        "reference a tag by title) and unique per batch; an unresolved/forward $ref fails just " +
+        "that line. IDEMPOTENCY: a line's `opId` makes resubmission safe — a matching earlier " +
+        "success is reported already-applied, not re-created. The trailing summary line adds " +
+        "`tempIdMapping` (handle → uuid) and `undoToken` — undo the WHOLE batch with " +
+        "`things undo --txn <undoToken>`. " +
         "--dry-run plans everything without executing; --fail-fast skips the rest after " +
         "the first failure. Exit (worst failure wins): 0 all ok · 3 any verify-failed/invalid " +
         "· 4 any blocked · 5 any drift-blocked · 6 any unsupported.")
@@ -1087,7 +1676,7 @@ export function registerWriteCommands(program) {
         let client = null;
         try {
             client = openThings(opts.db ? { dbPath: opts.db } : {});
-            const results = await client.write.batch(ops, {
+            const batchResult = await client.write.batch(ops, {
                 ...(opts.dryRun !== undefined && { dryRun: opts.dryRun }),
                 ...(opts["failFast"] === true && { failFast: true }),
                 ...(opts.actor !== undefined && { actor: opts.actor }),
@@ -1095,14 +1684,19 @@ export function registerWriteCommands(program) {
                 const pre = preInvalid.find((p) => p.index === r.index);
                 emit(pre ?? r);
             });
-            const merged = results.map((r) => preInvalid.find((p) => p.index === r.index) ?? r);
+            const merged = batchResult.results.map((r) => preInvalid.find((p) => p.index === r.index) ?? r);
             const failed = merged.filter((r) => outcomeFailed(r.outcome));
+            const hasMapping = Object.keys(batchResult.tempIdMapping).length > 0;
             const summary = {
                 summary: {
                     total: merged.length,
                     ok: merged.length - failed.length,
                     failed: failed.filter((r) => r.outcome.kind !== "skipped").length,
                     skipped: merged.filter((r) => r.outcome.kind === "skipped").length,
+                    // ADDITIVE: the temp-id → uuid mapping and the batch undo token
+                    // (undo the whole submission with `things undo --txn <token>`).
+                    ...(hasMapping && { tempIdMapping: batchResult.tempIdMapping }),
+                    ...(batchResult.undoToken !== undefined && { undoToken: batchResult.undoToken }),
                 },
             };
             process.stdout.write(`${JSON.stringify(summary)}\n`);
@@ -1212,35 +1806,35 @@ export function registerWriteCommands(program) {
             client?.close();
         }
     });
-    addWriteFlags(program
-        .command("reorder <uuids...>")
-        .description("Reorder items within Today, This Evening, the Inbox, Someday (loose to-dos or " +
-        "area-less someday projects — one kind per call), a " +
-        "project's to-dos, a project's HEADINGS, an area, or the top-level sidebar " +
-        "projects — uuids are placed at the TOP in the given order; unlisted members " +
-        "keep their relative order below. Strategies: native (EXPERIMENTAL — requires " +
-        "`things config set allow-experimental true` and may stop working after a " +
-        "Things update; today/inbox/someday/project/headings/area) and bounce " +
-        `(today/evening/projects, max ${BOUNCE_MAX_ITEMS} items; an interrupted run ` +
-        "reports which items were placed). Evening and projects (top-level sidebar " +
-        "order — each project takes a brief someday/anytime round-trip) are " +
-        "bounce-only. Project children under headings cannot be reordered; reordering " +
-        "a heading carries its children with it. Area scope reorders to-dos OR " +
-        "projects — never mixed in one request.")
-        .requiredOption("--scope <scope>", "today | evening | inbox | someday | project | headings | area | projects")
-        .option("--project <ref>", "project (uuid or unique name) — scope=project|headings")
-        .option("--area <ref>", "area (uuid or unique name) — scope=area")
-        .option("--strategy <name>", "force native | bounce (default: per-scope)")).action(async (uuids, opts) => {
-        const scope = opts["scope"];
-        const container = containerRef(opts["project"] ?? opts["area"]);
-        await runWrite(opts, (c) => c.write.reorder({
-            scope,
-            uuids,
-            ...(container !== undefined && { container }),
-            ...(opts["strategy"] !== undefined && {
-                strategy: opts["strategy"],
-            }),
-        }, writeOptionsFrom(opts)));
+    addPositionFlags(addWriteFlags(program
+        .command("reorder <refs...>")
+        .description("Rearrange to-dos (and the project rows the Today/Evening/day lists intermix with " +
+        "them) IN PLACE within the container and bucket they already share — REARRANGES, " +
+        "never changes membership (to change what an item belongs to, use `things todo " +
+        "move` / `things project move`). Argument order is the resulting order; unmentioned " +
+        "siblings keep theirs. Bare (no position) assembles the named items as a block at " +
+        "the EARLIEST one's current slot (partial-selection friendly); --first/--last/" +
+        "--before/--after position the block. Operands that span containers or buckets fail " +
+        "closed. A Today/Evening member also has an index slot in its container, so a set " +
+        "sharing BOTH axes is ambiguous — pass --in to say which (the refusal names both " +
+        "spellings). Ordering uses the native re-rank where available (private surface, on " +
+        "by default) and a verified when= bounce otherwise; bounce-max-items caps a bounce, " +
+        "bounce-enabled=false refuses bounce-dependent placements rather than degrading. " +
+        "For a project's HEADINGS use `things project move-heading`; for sidebar AREAS use " +
+        "`things area reorder`.")
+        .option("--in <target>", "disambiguate the axis of a Today/Evening set: today | evening | anytime | someday | " +
+        "inbox, or a project/area/heading ref (uuid or unique title)"))).action(async (refs, opts) => {
+        const position = movePosition(opts);
+        if (position === "conflict") {
+            usageError(opts, "pass at most one of --first/--last/--before/--after");
+            return;
+        }
+        const request = {
+            uuids: refs,
+            ...(position !== undefined && { position }),
+            ...(opts["in"] !== undefined && { in: opts["in"] }),
+        };
+        await runMoveCmd(opts, (c) => c.write.reorderTodos(request, writeOptionsFrom(opts)));
     });
     program
         .command("capabilities")
@@ -1253,7 +1847,7 @@ export function registerWriteCommands(program) {
         const data = capabilitiesTable(opts.op);
         if (opts.json) {
             const meta = { dbVersion: null, fingerprint: "unknown", elapsedMs: 0 };
-            process.stdout.write(`${JSON.stringify(okEnvelope("capabilities", data, meta))}\n`);
+            process.stdout.write(`${JSON.stringify(okEnvelope("capabilities", { items: data }, meta))}\n`);
             return;
         }
         for (const entry of data) {
@@ -1271,31 +1865,44 @@ export function registerWriteCommands(program) {
     });
     const config = group(program, "config", "things-api configuration");
     config
-        .command("show")
-        .description("Show the effective configuration (profile, disruption policy, actor)")
+        .command("get [key]")
+        .description("Show one config key's effective value, or every effective value when no key is given " +
+        "(including read-only derived values like host). Precedence is env > stored > default; " +
+        "each value is marked with the layer that supplied it. Unknown key is a usage error. " +
+        "--json emits a versioned envelope.")
         .option("--json", "emit versioned JSON envelope on stdout")
-        .option("--db <path>", "explicit database path")
-        .action((opts) => {
-        const client = openThings(opts.db ? { dbPath: opts.db } : {});
-        try {
+        .action((key, opts) => {
+        const meta = { dbVersion: null, fingerprint: "unknown", elapsedMs: 0 };
+        if (key !== undefined) {
+            const entry = getConfigKey(key);
+            if (entry === undefined) {
+                process.stderr.write(`error: unknown config key "${key}"\n`);
+                process.exitCode = ExitCode.Usage;
+                return;
+            }
             if (opts.json) {
-                const meta = { dbVersion: null, fingerprint: "unknown", elapsedMs: 0 };
-                process.stdout.write(`${JSON.stringify(okEnvelope("config", client.config, meta))}\n`);
+                process.stdout.write(`${JSON.stringify(okEnvelope("config", entry, meta))}\n`);
             }
             else {
-                for (const [k, v] of Object.entries(client.config)) {
-                    process.stdout.write(`${k}: ${String(v)}\n`);
-                }
+                process.stdout.write(`${configKeyLine(entry)}\n`);
             }
+            return;
         }
-        finally {
-            client.close();
+        const all = describeConfig();
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(okEnvelope("config", { items: all }, meta))}\n`);
+        }
+        else {
+            for (const entry of all) {
+                process.stdout.write(`${configKeyLine(entry)}\n`);
+            }
         }
     });
     config
         .command("set <key> <value>")
         .description("Persist a config key: profile | maxDisruption | actor | auditEnabled | " +
-        "accepted-fingerprint | allow-experimental | ui-enabled")
+        "accepted-fingerprint | certified-app-version | allow-experimental | bounce-enabled | " +
+        "bounce-max-items | ui-enabled | scope")
         .action((key, value) => {
         const map = {
             profile: "profile",
@@ -1303,8 +1910,12 @@ export function registerWriteCommands(program) {
             actor: "actor",
             auditEnabled: "auditEnabled",
             "accepted-fingerprint": "acceptedFingerprint",
+            "certified-app-version": "certifiedAppVersion",
             "allow-experimental": "allowExperimental",
+            "bounce-enabled": "bounceEnabled",
+            "bounce-max-items": "bounceMaxItems",
             "ui-enabled": "uiEnabled",
+            scope: "scope",
         };
         const target = map[key];
         if (target === undefined) {
@@ -1312,13 +1923,25 @@ export function registerWriteCommands(program) {
             process.exitCode = ExitCode.Usage;
             return;
         }
-        const parsed = target === "maxDisruption"
+        const parsed = target === "maxDisruption" || target === "bounceMaxItems"
             ? Number(value)
-            : target === "auditEnabled" || target === "allowExperimental" || target === "uiEnabled"
+            : target === "auditEnabled" ||
+                target === "allowExperimental" ||
+                target === "bounceEnabled" ||
+                target === "uiEnabled"
                 ? value === "true"
                 : value;
         saveConfigKey(target, parsed);
         process.stdout.write(`set ${key} = ${String(parsed)}\n`);
+        // A stored scope jails EVERY process on this host — including this
+        // terminal — until removed. Per-process scoping belongs on the
+        // THINGS_API_SCOPE env var or the `things mcp --scope` flag instead.
+        if (target === "scope") {
+            process.stderr.write("warning: a stored scope limits EVERY things-api process on this machine to " +
+                `"${value}" — including your own terminal — until you clear it with ` +
+                '`things config set scope ""`. For per-process limits (e.g. one MCP server), ' +
+                "prefer `things mcp --scope <ref>` or the THINGS_API_SCOPE environment variable.\n");
+        }
     });
 }
 //# sourceMappingURL=writes.js.map