things-api 0.11.0 → 0.13.0

package/dist/mcp/server.js

@@ -1,9 +1,12 @@
 /**
  * MCP surface over ThingsClient — the third thin layer (CLI, library, MCP),
- * all consuming the same client. Tools return the SAME JSON objects the
- * library returns (and the CLI wraps in --json envelopes); mutation failures
- * surface as MCP tool errors carrying the machine-readable code + the
- * remediation text the guards produce. Nothing here contains Things logic.
+ * all consuming the same client. Read tools return the library's JSON objects
+ * verbatim; mutation/move tools frame their result the same way the CLI's wire
+ * envelope does (docs/contract.md) — a success drops the internal discriminator
+ * (via mutationWireData), a dry-run emits the bare plan, and batch lines flatten
+ * to the string-`outcome` JSONL shape. Mutation failures surface as MCP tool
+ * errors carrying the machine-readable code + the remediation text the guards
+ * produce. Nothing here contains Things logic.
  *
  * Tool descriptions and the server instructions follow the consumer-voice
  * contract in docs/design/surface-copy.md: behavior and side effects only,
@@ -13,7 +16,7 @@
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ALL_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, BOUNCE_MAX_ITEMS, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, hasTagPresence, isValidTimeZone, LIMIT_DESC, MCP_WHEN_LABELS, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, ReferenceResolutionError, REMINDER_FORMAT, schemaWarnings, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
+import { ALL_DESC, AREA_FILTER_DESC, AREA_LIMIT_DESC, AREA_PREVIEW_LIMIT, blockedCode, capabilitiesTable, DATE_FORMAT, DEFAULT_LIST_LIMIT, diagnose, FILTER_CONTRACT, FULL_DESC, hasTagPresence, isLooseRef, isValidTimeZone, LIMIT_DESC, looseShadowNotice, MCP_WHEN_LABELS, mutationWireData, noUuidMatch, omitEmpty, OMIT_EMPTY_NOTE, OP_ID_RE, OPERATION_KINDS, openThings, PKG_VERSION, PROJECT_LIMIT_DESC, PROJECT_PREVIEW_LIMIT, REF_FORMAT, REF_RULE_NOTE, ReferenceResolutionError, REMINDER_FORMAT, schemaWarnings, shapeReadPayload, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
 function jsonResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -29,32 +32,39 @@ function readResult(data) {
 /**
  * A read result carrying truncation metadata: the data (already limited) in
  * the first content block, and a second block with the {@link Truncation}
- * numbers plus a one-line note the agent can read when rows were dropped.
+ * numbers plus a one-line note the agent can read when rows were dropped. `meta`
+ * merges extra whole-view metadata into that second block — the today view's
+ * `counts` aggregate (the analog of the CLI envelope's `meta.counts`), so `data`
+ * stays pure domain rows.
  */
-function truncatedResult(data, truncation) {
+function truncatedResult(data, truncation, meta) {
     const note = truncation.truncated
         ? `showing ${truncation.shown} of ${truncation.total} items — pass limit (or all: true) to see more`
         : undefined;
     return {
         content: [
             { type: "text", text: JSON.stringify(omitEmpty(data)) },
-            { type: "text", text: JSON.stringify({ truncation, ...(note !== undefined && { note }) }) },
+            {
+                type: "text",
+                text: JSON.stringify({ truncation, ...meta, ...(note !== undefined && { note }) }),
+            },
         ],
     };
 }
 /**
  * Grouped read result (anytime/someday): the per-block-truncated sections plus
- * a second block carrying the {@link GroupedTruncation} counts and, when
- * anything was hidden, a one-line note the agent can read.
+ * a second block carrying the unified {@link Truncation} counts (its `blocks`
+ * hold the per-block nesting) and, when anything was hidden, a one-line note the
+ * agent can read.
  */
-function groupedResult(data, grouped) {
-    const note = grouped.truncated
+function groupedResult(data, truncation) {
+    const note = truncation.truncated
         ? "some blocks are previews — raise area_limit/project_limit for more per block, or all: true for every item"
         : undefined;
     return {
         content: [
             { type: "text", text: JSON.stringify(omitEmpty(data)) },
-            { type: "text", text: JSON.stringify({ grouped, ...(note !== undefined && { note }) }) },
+            { type: "text", text: JSON.stringify({ truncation, ...(note !== undefined && { note }) }) },
         ],
     };
 }
@@ -112,12 +122,20 @@ function errorResult(error) {
 function usage(message) {
     return errorResult({ code: "usage", message });
 }
-/** Map a mutation outcome to an MCP result (errors carry remediation). */
+/**
+ * Map a mutation outcome to an MCP result (errors carry remediation). Framing
+ * mirrors the CLI wire (docs/contract.md, phase-2 alignment): a SUCCESS drops
+ * the internal success discriminator via {@link mutationWireData} (call success
+ * is the tool result's own not-an-error signal — the payload carries no `kind`),
+ * and a dry-run returns the bare plan (the CLI's `mutation-plan` data). Failures
+ * stay tool errors carrying the machine-readable code.
+ */
 function mutationResult(result) {
     switch (result.kind) {
         case "ok":
+            return jsonResult(mutationWireData(result));
         case "dry-run":
-            return jsonResult(result);
+            return jsonResult(result.plan);
         case "blocked":
             return errorResult({
                 code: blockedCode(result),
@@ -146,6 +164,93 @@ function mutationResult(result) {
             });
     }
 }
+/**
+ * Map a move/reorder orchestrator outcome to an MCP result (spec §4/§7). Framing
+ * mirrors {@link mutationResult}: a `move-ok` drops the internal discriminator
+ * (the placement-honesty `note` and every `membership`/`placement` field — with
+ * their own `touched`/`warnings` disclosures — pass through), and a dry-run
+ * returns the bare plan.
+ */
+function moveResult(result) {
+    switch (result.kind) {
+        case "move-ok":
+            return jsonResult(mutationWireData(result));
+        case "move-dry-run":
+            return jsonResult(result.plan);
+        case "move-refused":
+            return errorResult({
+                // A hoisted placement block names its hazard — surface the canonical
+                // `blocked:<hazard>` code, matching a direct reorder hazard block.
+                code: result.hazard !== undefined
+                    ? blockedCode({ hazard: result.hazard, reason: "hazard" })
+                    : result.refusal,
+                message: result.detail,
+                ...(result.remediation !== undefined && { remediation: result.remediation }),
+                ...(result.candidates !== undefined && { details: { candidates: result.candidates } }),
+            });
+        case "move-leg-failed":
+            return errorResult({
+                code: "verify-failed",
+                message: result.detail,
+                remediation: `completed ${result.completed.length} leg(s) before the failure`,
+            });
+    }
+}
+/**
+ * Flatten one batch line to the wire shape (docs/contract.md — the JSONL grammar
+ * shared with the CLI): the internal `outcome` union object collapses to one
+ * level. `outcome` becomes its tag as a plain string (`"ok"`, `"blocked"`,
+ * `"dry-run"`, `"already-applied"`, …), and every variant field (uuid, detail,
+ * plan, expected, observed, …) 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.
+ */
+function flattenBatchLine(r) {
+    const { index, op, outcome, tempId, boundUuid, opId } = r;
+    const { kind, op: _outcomeOp, ...variant } = outcome;
+    return {
+        index,
+        op,
+        outcome: kind,
+        ...variant,
+        ...(tempId !== undefined && { tempId }),
+        ...(boundUuid !== undefined && { boundUuid }),
+        ...(opId !== undefined && { opId }),
+    };
+}
+/** Build a MovePosition from the shared MCP position args (null when none). */
+function movePositionArgs(args) {
+    const chosen = [
+        args.first === true,
+        args.last === true,
+        args.before !== undefined,
+        args.after !== undefined,
+    ].filter(Boolean).length;
+    if (chosen > 1)
+        return "conflict";
+    if (args.first === true)
+        return { at: "first" };
+    if (args.last === true)
+        return { at: "last" };
+    if (args.before !== undefined)
+        return { before: args.before };
+    if (args.after !== undefined)
+        return { after: args.after };
+    return undefined;
+}
+/** The shared position input schema for the move tools. */
+const positionShape = {
+    first: z.boolean().optional().describe("place the block at the top of its bucket"),
+    last: z.boolean().optional().describe("place the block at the bottom of its bucket"),
+    before: z
+        .string()
+        .optional()
+        .describe("place the block immediately before this item (same bucket)"),
+    after: z
+        .string()
+        .optional()
+        .describe("place the block immediately after this item (same bucket)"),
+};
 const READ_ONLY = { readOnlyHint: true };
 const NON_DESTRUCTIVE = { destructiveHint: false };
 const DESTRUCTIVE = { destructiveHint: true };
@@ -201,10 +306,25 @@ const MCP_UNTAGGED_CONFLICT = "untagged does not combine with tag/exact_tag";
 const dryRunShape = {
     dry_run: z.boolean().optional().describe("Preview the planned change without applying anything"),
 };
+/**
+ * The per-call idempotency key for a single write tool — the analogue of a batch
+ * line's op_id. A resubmission carrying the same key is recognized as already
+ * applied (a prior verified change with that key) and is not re-run. Spread into
+ * the single-mutation write tools (not the variadic move/reorder tools, whose
+ * idempotency is the batch-shaped per-line op_id).
+ */
+const opIdShape = {
+    op_id: z
+        .string()
+        .optional()
+        .describe("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)"),
+};
 /**
  * The per-call opt-in for the tools that reach a change only by driving the
  * local Things app's accessibility interface. Shared by `repeat`, the
- * `convert_to_project` heading action, and the `areas` reorder scope.
+ * `convert_to_project` tool, the heading tool's `promote_heading` action, and
+ * the `areas` reorder scope.
  */
 const driveGuiShape = {
     dangerously_drive_gui: z
@@ -226,6 +346,20 @@ const createTagsShape = {
         "instead of stopping on an unknown tag"),
 };
 const containerRef = (ref) => ({ uuid: ref, title: ref });
+/**
+ * The `loose` reserved-word disclosure for the area-filtered read tools
+ * (read_view, search — the same advisory the CLI surfaces, #333/#346). `loose`
+ * ALWAYS addresses the null area; when a real area named "Loose" shadows the
+ * reserved word this names it (by uuid) so it stays targetable. Returns
+ * undefined when the ref is not the reserved word, or nothing shadows it.
+ * (get_area reads its disclosure from the area-view result's own `notice`.)
+ */
+function looseAreaWarnings(c, areaRef) {
+    if (areaRef === undefined || !isLooseRef(areaRef))
+        return undefined;
+    const shadow = c.read.areas().find((a) => isLooseRef(a.title));
+    return shadow !== undefined ? [looseShadowNotice(shadow.uuid)] : undefined;
+}
 /** Cap on project titles inlined into the server instructions. */
 const INSTRUCTIONS_MAX_PROJECTS = 100;
 /** A tag's display label: nested tags show `parent > child`. */
@@ -258,14 +392,23 @@ function buildInstructions(getClient) {
             "confirmation parameter named in their description; refused calls return an error saying " +
             "what to pass.",
         "- Read-result semantics: an item's tags are its direct tags; its effective tags also include " +
-            "tags inherited from its containing project and area. todaySection appears only for an item " +
-            "in Today, naming its section there (today or evening); an unscheduled start=active item is " +
-            "in Anytime and omits the field. Completing an item makes it findable in Logbook.",
+            "tags inherited from its containing project and area. An item's when is today or evening for " +
+            "a Today member (evening implies today), a future date for a scheduled item, else absent; an " +
+            "unscheduled start=active item is in Anytime and carries no when. Completing an item makes it " +
+            "findable in Logbook.",
         "- For capped reads, pass limit to cap rows or all: true for everything; if both are set, all wins.",
         `- Read results are compact: ${OMIT_EMPTY_NOTE}`,
     ];
     try {
         const c = getClient();
+        // Under a container scope the inventory below is already limited to in-scope
+        // containers (the client filters areas/projects), so out-of-scope names are
+        // never embedded here. State the scope plainly so the agent knows its bounds.
+        if (c.scope !== undefined) {
+            lines.push("", `Scope: this server is limited to the ${c.scope.kind} "${c.scope.title}". Only items ` +
+                "within it are readable, and every change is confined to it; a reference naming anything " +
+                "outside it returns not-found, exactly as a nonexistent reference does.");
+        }
         const areas = c.read.areas();
         const tags = c.read.tags();
         const projects = c.read.projects();
@@ -306,6 +449,13 @@ function deriveMcpActor(clientName) {
         .replaceAll(/-+$/g, "");
     return slug === "" ? MCP_ACTOR_PREFIX : `${MCP_ACTOR_PREFIX}:${slug}`;
 }
+/** Validate an op_id (throwing RangeError → mapped to a `usage` tool error by `guard`). */
+function assertOpId(opId) {
+    if (!OP_ID_RE.test(opId)) {
+        throw new RangeError("op_id must match [A-Za-z0-9_-] and be 1-64 characters");
+    }
+    return opId;
+}
 export function createThingsMcpServer(options = {}) {
     // One lazily-opened client for the server's lifetime; SQLite read
     // snapshots are per-statement, so fresh reads see external commits.
@@ -313,6 +463,7 @@ export function createThingsMcpServer(options = {}) {
     const getClient = () => {
         client ??= openThings({
             ...(options.dbPath !== undefined && { dbPath: options.dbPath }),
+            ...(options.scope !== undefined && { scope: options.scope }),
             ...options.openOptions,
         });
         return client;
@@ -333,9 +484,11 @@ export function createThingsMcpServer(options = {}) {
         ...(args.acknowledge_project_reopen === true && { acknowledgeProjectReopen: true }),
         ...(args.dangerously_permanent === true && { dangerouslyPermanent: true }),
         ...(args.acknowledge_tag_subtree === true && { acknowledgeTagSubtree: true }),
+        ...(args.allow_non_empty_area === true && { allowNonEmptyArea: true }),
         ...(args.dangerously_drive_gui === true && { dangerouslyDriveGui: true }),
         ...(args.create_tags === true && { createTags: true }),
         ...(args.tz !== undefined && { zone: args.tz }),
+        ...(args.op_id !== undefined && { opId: assertOpId(args.op_id) }),
     });
     /** Run a handler, mapping environment/usage throws to tool errors. */
     const guard = async (fn) => {
@@ -364,8 +517,13 @@ export function createThingsMcpServer(options = {}) {
      * same note the CLI prints), so a consumer sees when the Things database no
      * longer matches the validated schema and its data may be incomplete. No
      * block is added when the schema checks out or the read itself errored.
+     *
+     * `extraWarnings` folds in the read's own advisories (the `loose` reserved-word
+     * shadow disclosure, an area-view's placement `notice`) so they reach the
+     * consumer in the SAME `meta.warnings` array the CLI surfaces — schema warnings
+     * first, then the read-specific notices.
      */
-    const readGuard = async (fn, tz) => {
+    const readGuard = async (fn, tz, extraMeta, extraWarnings) => {
         const result = await guard(fn);
         if (result.isError === true)
             return result;
@@ -382,9 +540,23 @@ export function createThingsMcpServer(options = {}) {
         catch {
             warnings = [];
         }
+        // Read-specific advisories the handler resolved (loose-shadow / area notice)
+        // — merged AFTER the schema warnings, defensive against a DB read throwing.
+        let readNotices = [];
+        try {
+            readNotices = extraWarnings?.() ?? [];
+        }
+        catch {
+            readNotices = [];
+        }
+        const allWarnings = [...warnings, ...readNotices];
+        // Extra additive meta the handler resolved during the read (e.g. the active
+        // `area` filter) — evaluated AFTER fn ran, so a value it populated is seen.
+        const extra = extraMeta?.() ?? {};
         const meta = {
-            ...(warnings.length > 0 && { warnings }),
+            ...(allWarnings.length > 0 && { warnings: allWarnings }),
             ...(clock !== undefined && { clock }),
+            ...extra,
         };
         if (Object.keys(meta).length === 0)
             return result;
@@ -405,8 +577,9 @@ export function createThingsMcpServer(options = {}) {
     };
     // ------------------------------------------------------------------ reads
     server.registerTool("read_view", {
-        description: "Read a Things list as the app presents it: today (split into Today and This " +
-            "Evening), inbox, anytime, upcoming, someday, logbook, or trash. For upcoming, " +
+        description: "Read a Things list as the app presents it: today (one flat list of Today " +
+            "members, each item's when marking Today vs This Evening), inbox, anytime, " +
+            "upcoming, someday, logbook, or trash. For upcoming, " +
             "horizon > 1 also includes future occurrences of repeating items (up to 10 each). " +
             "anytime/someday return sections in canonical order (area + items; null area = the " +
             "top-level block); children of someday/future-scheduled projects are excluded " +
@@ -417,12 +590,21 @@ export function createThingsMcpServer(options = {}) {
             `area_limit (default ${AREA_PREVIEW_LIMIT}) per area block, and on anytime ` +
             `project_limit (default ${PROJECT_PREVIEW_LIMIT}) per project block. ` +
             "all: true lifts every cap; the result's second block reports the counts. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             view: z.enum(["today", "inbox", "anytime", "upcoming", "someday", "logbook", "trash"]),
             ...tagFilterShape,
             ...tzShape,
-            evening: z.boolean().optional().describe("today only: show only the This Evening section"),
+            area: z
+                .string()
+                .optional()
+                .describe(`today/anytime/someday/upcoming/logbook only: ${AREA_FILTER_DESC}`),
+            evening: z
+                .boolean()
+                .optional()
+                .describe("today only: show only This-Evening members (when = evening)"),
             show_active_project_items: z
                 .union([z.boolean(), z.number().int().min(1)])
                 .optional()
@@ -462,116 +644,148 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("show everything (flat views: no row limit; anytime/someday: no per-block caps); " +
                 ALL_WINS_NOTE),
+            full: z.boolean().optional().describe(FULL_DESC),
         },
         annotations: READ_ONLY,
-    }, async (args) => readGuard(() => {
-        const badZone = badTz(args.tz);
-        if (badZone !== null)
-            return badZone;
-        // Tag-conflict AND overdue-applicability both derive from the shared
-        // contract: read_view honors overdue only on today/inbox/anytime/someday
-        // (the current-work views), matching FILTER_CONTRACT.
-        const validated = validateViewArgs(args.view, { ...tagPresence(args), overdue: args.overdue }, {
-            untaggedConflict: MCP_UNTAGGED_CONFLICT,
-            overdueRejected: `overdue applies to today/inbox/anytime/someday, not ${args.view}`,
-            overdueStatusWiden: "",
-        });
-        if (!validated.ok)
-            return usage(validated.message);
-        // show_active_project_items is the preferred name; active_project_items
-        // stays accepted as a compatibility alias.
-        const showActiveProjectItems = args.show_active_project_items ?? args.active_project_items;
-        const isGrouped = args.view === "anytime" || args.view === "someday";
-        if (isGrouped && args.limit !== undefined) {
-            return usage(`limit does not apply to ${args.view} — cap blocks with area_limit` +
-                `${args.view === "anytime" ? "/project_limit" : ""}, or pass all: true`);
-        }
-        if (!isGrouped && (args.area_limit !== undefined || args.project_limit !== undefined)) {
-            return usage(`area_limit/project_limit apply only to anytime/someday, not ${args.view}`);
-        }
-        if (args.view !== "someday" && showActiveProjectItems !== undefined) {
-            return usage("show_active_project_items applies only to someday");
-        }
-        if (args.view !== "today" && args.evening === true) {
-            return usage(`evening applies only to today, not ${args.view}`);
-        }
-        if (args.view === "someday" && args.project_limit !== undefined) {
-            return usage("project_limit does not apply to someday — pass a number as show_active_project_items " +
-                "to cap that section's project lists");
-        }
-        const limit = resolveLimit(args);
-        const areaLimit = resolveCap(args.area_limit, args.all, AREA_PREVIEW_LIMIT);
-        const projectLimit = resolveCap(args.project_limit, args.all, PROJECT_PREVIEW_LIMIT);
-        if (areaLimit === "conflict" || projectLimit === "conflict") {
-            return usage("pass at most one of area_limit/project_limit / all");
-        }
-        const c = getClient();
-        const filter = validated.filter;
-        const zone = args.tz !== undefined ? { zone: args.tz } : {};
-        switch (args.view) {
-            case "today": {
-                const { view, truncation } = c.read.today({
-                    ...filter,
-                    ...zone,
-                    ...(args.evening === true && { eveningOnly: true }),
-                    limit,
-                });
-                return truncatedResult(view, truncation);
+    }, async (args) => {
+        // The active `area` scope, resolved during the read and surfaced as the
+        // additive `meta.filter` (the readGuard extra-meta thunk reads it after fn).
+        let filterMeta;
+        const full = args.full === true;
+        return readGuard(() => {
+            const badZone = badTz(args.tz);
+            if (badZone !== null)
+                return badZone;
+            // Tag-conflict AND overdue-applicability both derive from the shared
+            // contract: read_view honors overdue only on today/inbox/anytime/someday
+            // (the current-work views), matching FILTER_CONTRACT.
+            const validated = validateViewArgs(args.view, { ...tagPresence(args), overdue: args.overdue }, {
+                untaggedConflict: MCP_UNTAGGED_CONFLICT,
+                overdueRejected: `overdue applies to today/inbox/anytime/someday, not ${args.view}`,
+                overdueStatusWiden: "",
+            });
+            if (!validated.ok)
+                return usage(validated.message);
+            // show_active_project_items is the preferred name; active_project_items
+            // stays accepted as a compatibility alias.
+            const showActiveProjectItems = args.show_active_project_items ?? args.active_project_items;
+            const isGrouped = args.view === "anytime" || args.view === "someday";
+            if (isGrouped && args.limit !== undefined) {
+                return usage(`limit does not apply to ${args.view} — cap blocks with area_limit` +
+                    `${args.view === "anytime" ? "/project_limit" : ""}, or pass all: true`);
             }
-            case "inbox": {
-                const { items, truncation } = c.read.inbox({ ...filter, ...zone, limit });
-                return truncatedResult(items, truncation);
+            if (!isGrouped && (args.area_limit !== undefined || args.project_limit !== undefined)) {
+                return usage(`area_limit/project_limit apply only to anytime/someday, not ${args.view}`);
             }
-            case "anytime": {
-                const { view, grouped } = c.read.anytime({
-                    ...filter,
-                    ...zone,
-                    areaLimit,
-                    projectLimit,
-                });
-                return groupedResult(view, grouped);
+            if (args.view !== "someday" && showActiveProjectItems !== undefined) {
+                return usage("show_active_project_items applies only to someday");
             }
-            case "upcoming": {
-                const { items, truncation } = c.read.upcoming({
-                    ...filter,
-                    ...zone,
-                    ...(args.horizon !== undefined && { horizon: args.horizon }),
-                    limit,
-                });
-                return truncatedResult(items, truncation);
+            if (args.view !== "today" && args.evening === true) {
+                return usage(`evening applies only to today, not ${args.view}`);
             }
-            case "someday": {
-                const active = showActiveProjectItems;
-                if (typeof active === "number" && args.all === true) {
-                    return usage("pass at most one of a numeric show_active_project_items / all");
-                }
-                const { view, grouped } = c.read.someday({
-                    ...filter,
-                    ...zone,
-                    ...((active === true || typeof active === "number") && {
-                        activeProjectItems: true,
-                    }),
-                    areaLimit,
-                    // true = every item per project; a number caps each list.
-                    projectLimit: typeof active === "number" ? active : null,
-                });
-                return groupedResult(view, grouped);
+            // The `area` filter applies to the area-carrying views only; inbox
+            // (area-less captures) and trash have no area to scope by.
+            if ((args.view === "inbox" || args.view === "trash") && args.area !== undefined) {
+                return usage(`area applies to today/anytime/someday/upcoming/logbook, not ${args.view}`);
             }
-            case "logbook": {
-                const { items, truncation } = c.read.logbook({ ...filter, ...zone, limit });
-                return truncatedResult(items, truncation);
+            if (args.view === "someday" && args.project_limit !== undefined) {
+                return usage("project_limit does not apply to someday — pass a number as show_active_project_items " +
+                    "to cap that section's project lists");
             }
-            case "trash": {
-                const { items, truncation } = c.read.trash({ ...zone, limit });
-                return truncatedResult(items, truncation);
+            const limit = resolveLimit(args);
+            const areaLimit = resolveCap(args.area_limit, args.all, AREA_PREVIEW_LIMIT);
+            const projectLimit = resolveCap(args.project_limit, args.all, PROJECT_PREVIEW_LIMIT);
+            if (areaLimit === "conflict" || projectLimit === "conflict") {
+                return usage("pass at most one of area_limit/project_limit / all");
             }
-        }
-    }, args.tz));
+            const c = getClient();
+            const filter = validated.filter;
+            const zone = args.tz !== undefined ? { zone: args.tz } : {};
+            // The `area` scope, threaded into the area-carrying views; the client
+            // resolves it, applies the post-filter, and hands back the target for
+            // the `meta.filter` annotation (captured into `filterMeta`).
+            const area = args.area !== undefined ? { area: args.area } : {};
+            switch (args.view) {
+                case "today": {
+                    const { view, truncation, filter: fm, } = c.read.today({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        ...(args.evening === true && { eveningOnly: true }),
+                        limit,
+                    });
+                    filterMeta = fm;
+                    return truncatedResult(shapeReadPayload("today", view, full, c.refPromoter()), truncation, { counts: view.counts });
+                }
+                case "inbox": {
+                    const { items, truncation } = c.read.inbox({ ...filter, ...zone, limit });
+                    return truncatedResult(shapeReadPayload("inbox", items, full, c.refPromoter()), truncation);
+                }
+                case "anytime": {
+                    const { view, truncation, filter: fm, } = c.read.anytime({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        areaLimit,
+                        projectLimit,
+                    });
+                    filterMeta = fm;
+                    return groupedResult(shapeReadPayload("anytime", view, full, c.refPromoter()), truncation);
+                }
+                case "upcoming": {
+                    const { items, truncation, filter: fm, } = c.read.upcoming({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        ...(args.horizon !== undefined && { horizon: args.horizon }),
+                        limit,
+                    });
+                    filterMeta = fm;
+                    return truncatedResult(shapeReadPayload("upcoming", items, full, c.refPromoter()), truncation);
+                }
+                case "someday": {
+                    const active = showActiveProjectItems;
+                    if (typeof active === "number" && args.all === true) {
+                        return usage("pass at most one of a numeric show_active_project_items / all");
+                    }
+                    const { view, truncation, filter: fm, } = c.read.someday({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        ...((active === true || typeof active === "number") && {
+                            activeProjectItems: true,
+                        }),
+                        areaLimit,
+                        // true = every item per project; a number caps each list.
+                        projectLimit: typeof active === "number" ? active : null,
+                    });
+                    filterMeta = fm;
+                    return groupedResult(shapeReadPayload("someday", view, full, c.refPromoter()), truncation);
+                }
+                case "logbook": {
+                    const { items, truncation, filter: fm, } = c.read.logbook({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        limit,
+                    });
+                    filterMeta = fm;
+                    return truncatedResult(shapeReadPayload("logbook", items, full, c.refPromoter()), truncation);
+                }
+                case "trash": {
+                    const { items, truncation } = c.read.trash({ ...zone, limit });
+                    return truncatedResult(shapeReadPayload("trash", items, full, c.refPromoter()), truncation);
+                }
+            }
+        }, args.tz, () => (filterMeta !== undefined ? { filter: filterMeta } : undefined), () => looseAreaWarnings(getClient(), args.area));
+    });
     server.registerTool("search", {
         description: "Find items by title/notes substring. Returns open, untrashed items by default; " +
             "include more with logged/trashed/all. Scope with project/area/tag — scope " +
             "references must name existing items. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             query: z.string(),
             ...tagFilterShape,
@@ -583,7 +797,7 @@ export function createThingsMcpServer(options = {}) {
             area: z
                 .string()
                 .optional()
-                .describe(`Restrict to one area's direct members (${REF_FORMAT})`),
+                .describe(`Restrict to one area's subtree — its direct items plus its projects' children (${REF_FORMAT}, or \`loose\` for area-less)`),
             type: z.enum(["to-do", "project"]).optional(),
             logged: z.boolean().optional().describe("Also include completed/canceled items"),
             trashed: z.boolean().optional().describe("Also include trashed items"),
@@ -592,6 +806,7 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe(`Everything, unbounded: open + logged + trashed, no row limit; ${ALL_WINS_NOTE}`),
             limit: z.number().int().min(1).optional().describe(`${LIMIT_DESC}; ${LIMIT_IGNORED_NOTE}`),
+            full: z.boolean().optional().describe(FULL_DESC),
         },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
@@ -625,17 +840,20 @@ export function createThingsMcpServer(options = {}) {
             ...(args.trashed === true && { trashed: true }),
             ...(args.all === true && { all: true }),
         });
-        return truncatedResult(items, truncation);
-    }, args.tz));
+        return truncatedResult(shapeReadPayload("search", items, args.full === true, getClient().refPromoter()), truncation);
+    }, args.tz, undefined, () => looseAreaWarnings(getClient(), args.area)));
     server.registerTool("changes_since", {
         description: "List items created or modified since a moment — including trashed, logged, and " +
             "repeating items (inspect each item's fields to tell them apart). Edits to tags, " +
             "areas, and checklist items do not mark the containing item as modified. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             since: z.string().describe("ISO date-time, e.g. 2026-07-06T08:00:00"),
             ...limitShape,
             ...tzShape,
+            full: z.boolean().optional().describe(FULL_DESC),
         },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
@@ -652,26 +870,34 @@ export function createThingsMcpServer(options = {}) {
             limit,
             ...(args.tz !== undefined && { zone: args.tz }),
         });
-        return truncatedResult(items, truncation);
+        return truncatedResult(shapeReadPayload("changes", items, args.full === true, getClient().refPromoter()), truncation);
     }, args.tz));
     server.registerTool("get_item", {
         description: "Full detail for one item by uuid: notes, schedule, reminder, deadline, tags " +
             "(direct and inherited), checklist with per-item state, repeat schedule, and its " +
             "project/area/heading. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: { uuid: z.string() },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
         const item = getClient().read.byUuid(args.uuid);
         return item === null
             ? errorResult({ code: "not-found", message: noUuidMatch("item", args.uuid) })
-            : readResult(item);
+            : readResult(shapeReadPayload("detail", item, false, getClient().refPromoter()));
     }));
     server.registerTool("get_project", {
-        description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
-            "The tag filters keep only the child to-dos matching by their own tags (a heading left " +
-            "with none is dropped). " +
-            OMIT_EMPTY_NOTE,
+        description: "One project's full contents: metadata, its live child to-dos as one flat list (items, " +
+            "in index order — each carrying its stage, when, and, when it lives under a heading, " +
+            "its heading ref), the heading catalog (headings — every heading in index order, " +
+            "carrying archived once archived), and its logged children (logbook, most recent " +
+            "first, each carrying its heading ref). Reconstruct a heading's members by filtering " +
+            "items (or logbook) on the heading ref. The tag filters keep only the child to-dos " +
+            "matching by their own tags (a heading left with none is dropped). " +
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             uuid: z.string().describe("Project uuid or unique name"),
             ...tagOnlyShape,
@@ -680,6 +906,7 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("Keep only child to-dos past their deadline (due today is not overdue); headings left empty are dropped"),
+            full: z.boolean().optional().describe(FULL_DESC),
         },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
@@ -688,19 +915,23 @@ export function createThingsMcpServer(options = {}) {
             return badZone;
         if (tagFlagConflict(tagPresence(args)))
             return usage(MCP_UNTAGGED_CONFLICT);
-        return readResult(getClient().read.projectView(args.uuid, {
+        return readResult(shapeReadPayload("project-view", getClient().read.projectView(args.uuid, {
             overdue: args.overdue === true,
             ...tagFilterFields(tagPresence(args)),
             ...(args.tz !== undefined && { zone: args.tz }),
-        }));
+        }), args.full === true, getClient().refPromoter()));
     }, args.tz));
     server.registerTool("get_area", {
-        description: "One area's contents: metadata plus its direct to-dos (active first), its " +
-            "projects in canonical order, later (scheduled/repeating/someday), and logged items. " +
-            `The project-rows and direct-to-dos sections are capped at ${AREA_PREVIEW_LIMIT} each ` +
+        description: "One area's contents: metadata plus its direct to-dos as one flat list (items, in " +
+            "index order — each row carrying its stage and when) and its projects in canonical " +
+            "order (projects). The area logbook is not returned here — read it with read_view " +
+            "logbook + area; trashed rows live in read_view trash. " +
+            `The project rows and the open/current direct to-dos are capped at ${AREA_PREVIEW_LIMIT} each ` +
             "by default (project_limit / area_limit adjust them; all: true lifts both); the " +
             "second result block reports the counts. " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             ref: z.string().describe("Area uuid or unique name"),
             ...tagOnlyShape,
@@ -722,33 +953,43 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("Keep only rows (loose to-dos AND child projects) whose own deadline is past (due today is not overdue); no descent into project contents"),
             all: z.boolean().optional().describe("return both sections in full (no caps)"),
+            full: z.boolean().optional().describe(FULL_DESC),
         },
         annotations: READ_ONLY,
-    }, async (args) => readGuard(() => {
-        const badZone = badTz(args.tz);
-        if (badZone !== null)
-            return badZone;
-        if (tagFlagConflict(tagPresence(args)))
-            return usage(MCP_UNTAGGED_CONFLICT);
-        const areaLimit = resolveCap(args.area_limit, args.all, AREA_PREVIEW_LIMIT);
-        const projectLimit = resolveCap(args.project_limit, args.all, AREA_PREVIEW_LIMIT);
-        if (areaLimit === "conflict" || projectLimit === "conflict") {
-            return usage("pass at most one of area_limit/project_limit / all");
-        }
-        const { view, grouped } = getClient().read.areaView(args.ref, {
-            overdue: args.overdue === true,
-            ...tagFilterFields(tagPresence(args)),
-            ...(args.tz !== undefined && { zone: args.tz }),
-            areaLimit,
-            projectLimit,
-        });
-        return groupedResult(view, grouped);
-    }, args.tz));
+    }, async (args) => {
+        // The `loose` pseudo-area shadow disclosure the area-view read resolves —
+        // captured after fn runs and folded into meta.warnings (parity with the
+        // CLI's `area show loose` notice).
+        let areaNotice;
+        return readGuard(() => {
+            const badZone = badTz(args.tz);
+            if (badZone !== null)
+                return badZone;
+            if (tagFlagConflict(tagPresence(args)))
+                return usage(MCP_UNTAGGED_CONFLICT);
+            const areaLimit = resolveCap(args.area_limit, args.all, AREA_PREVIEW_LIMIT);
+            const projectLimit = resolveCap(args.project_limit, args.all, AREA_PREVIEW_LIMIT);
+            if (areaLimit === "conflict" || projectLimit === "conflict") {
+                return usage("pass at most one of area_limit/project_limit / all");
+            }
+            const { view, truncation, notice } = getClient().read.areaView(args.ref, {
+                overdue: args.overdue === true,
+                ...tagFilterFields(tagPresence(args)),
+                ...(args.tz !== undefined && { zone: args.tz }),
+                areaLimit,
+                projectLimit,
+            });
+            areaNotice = notice;
+            return groupedResult(shapeReadPayload("area-view", view, args.full === true, getClient().refPromoter()), truncation);
+        }, args.tz, undefined, () => (areaNotice !== undefined ? [areaNotice] : undefined));
+    });
     server.registerTool("list_collections", {
         description: "List every project, area, or tag (tags include their parent-tag nesting). Use to " +
             "refresh the inventory summarized in the server instructions. The tag filters scope " +
             "the projects list by each project's own tags (areas/tags reject them). " +
-            OMIT_EMPTY_NOTE,
+            OMIT_EMPTY_NOTE +
+            " " +
+            REF_RULE_NOTE,
         inputSchema: {
             kind: z.enum(["projects", "areas", "tags"]),
             ...tagOnlyShape,
@@ -757,6 +998,7 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("projects only: keep only projects past their deadline (due today is not overdue); areas/tags carry no deadline and reject it"),
+            full: z.boolean().optional().describe(`projects only: ${FULL_DESC}`),
         },
         annotations: READ_ONLY,
     }, async (args) => readGuard(() => {
@@ -784,7 +1026,7 @@ export function createThingsMcpServer(options = {}) {
         }
         if (tagFlagConflict(tagPresence(args)))
             return usage(MCP_UNTAGGED_CONFLICT);
-        return readResult(args.kind === "projects"
+        return readResult(shapeReadPayload(args.kind, args.kind === "projects"
             ? c.read.projects({
                 overdue: args.overdue === true,
                 ...tagFilterFields(tagPresence(args)),
@@ -792,7 +1034,7 @@ export function createThingsMcpServer(options = {}) {
             })
             : args.kind === "areas"
                 ? c.read.areas()
-                : c.read.tags());
+                : c.read.tags(), args.full === true, c.refPromoter()));
     }, args.tz));
     // ---------------------------------------------------------------- to-dos
     const whenSchema = z.string().optional().describe(WHEN_VALUES);
@@ -820,6 +1062,7 @@ export function createThingsMcpServer(options = {}) {
             ...createTagsShape,
             ...tzShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -881,6 +1124,7 @@ export function createThingsMcpServer(options = {}) {
             ...createTagsShape,
             ...tzShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -983,6 +1227,7 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("scope project, open only: also reopen the to-dos resolved with the project"),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1017,6 +1262,13 @@ export function createThingsMcpServer(options = {}) {
         if (args.children !== undefined) {
             return usage("children applies only to status 'completed' or 'canceled'");
         }
+        // Reopening a project is a multi-leg compound — single-op idempotency
+        // (op_id) does not apply to it in phase 1 (every other set_status path
+        // is a single mutation). Refuse rather than silently drop the key.
+        if (args.op_id !== undefined) {
+            return usage("op_id is not available when reopening a project (a multi-leg compound in phase 1) — " +
+                "use the batch tool with a per-line op_id");
+        }
         const outcome = await c.write.reopenProject(args.uuid, {
             ...opts,
             ...(args.restore_children === true && { restoreChildren: true }),
@@ -1026,21 +1278,37 @@ export function createThingsMcpServer(options = {}) {
             : mutationResult(outcome.project);
     }));
     server.registerTool("move_todo", {
-        description: "Move a to-do. Pass exactly one destination: a project or area (optionally an " +
-            "existing heading within the project), to_inbox, or detach. Moving to the Inbox " +
-            "removes any schedule; detach removes the project/area/heading assignment while " +
-            "keeping the schedule. Moving into a completed or canceled project reopens that " +
-            "project — pass acknowledge_project_reopen to confirm.",
+        description: "Move one or more to-dos as an ordered block (spec §4). MOVE changes WHAT a to-do " +
+            "belongs to (membership somewhere); to REARRANGE to-dos that already share a container " +
+            "without changing membership, call this with a position (first/last/before/after) and " +
+            "NO destination — that is an in-place reorder, anchored at the earliest movee's slot, " +
+            "and unmentioned siblings keep their order. The uuids order is the order they land " +
+            "(name them backwards to reverse). Pass at most one destination: to_project, to_heading " +
+            "(within to_project, or the movees' shared project), to_area, no_heading (leave the " +
+            "heading, stay in the project), loose (leave heading, project, AND area), or to_inbox. " +
+            "An anchor (before/after) positions but never migrates — an anchor-only move that would " +
+            "cross containers is refused, as is a --before/--after whose movees span buckets. " +
+            "Membership always succeeds; top-of-bucket placement is guaranteed only where a reorder " +
+            "protocol exists (the result's placementClass states which). Moving into a " +
+            "completed/canceled project reopens it — pass acknowledge_project_reopen.",
         inputSchema: {
-            uuid: z.string(),
-            project: z.string().optional().describe(`Destination project (${REF_FORMAT})`),
-            area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
-            heading: z.string().optional().describe("Existing heading in the destination project"),
-            to_inbox: z.boolean().optional().describe("Move back to the Inbox (removes any schedule)"),
-            detach: z
+            uuids: z.array(z.string()).describe("The to-dos to move, in the order they should land"),
+            to_project: z.string().optional().describe(`Destination project (${REF_FORMAT})`),
+            to_heading: z
+                .string()
+                .optional()
+                .describe("Destination heading (exact title or uuid; within to_project or the shared project)"),
+            to_area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
+            no_heading: z
+                .boolean()
+                .optional()
+                .describe("Leave the heading but stay in the current project (unheaded block)"),
+            loose: z
                 .boolean()
                 .optional()
-                .describe("Remove the project/area/heading assignment, keeping the schedule"),
+                .describe("Detach from heading, project, AND area, keeping the schedule"),
+            to_inbox: z.boolean().optional().describe("Move back to the Inbox (removes any schedule)"),
+            ...positionShape,
             acknowledge_project_reopen: z
                 .boolean()
                 .optional()
@@ -1049,21 +1317,37 @@ export function createThingsMcpServer(options = {}) {
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const dest = args.project !== undefined || args.area !== undefined || args.heading !== undefined;
-        const modes = [dest, args.to_inbox === true, args.detach === true].filter(Boolean).length;
-        if (modes !== 1) {
-            return usage("pass exactly one destination: project/area/heading, to_inbox, or detach");
+        const dests = [];
+        if (args.to_heading !== undefined) {
+            dests.push({
+                kind: "heading",
+                sel: args.to_heading,
+                ...(args.to_project !== undefined && { project: containerRef(args.to_project) }),
+            });
         }
-        return mutationResult(await getClient().write.moveTodo(args.uuid, {
-            ...(args.project !== undefined && { project: containerRef(args.project) }),
-            ...(args.area !== undefined && { area: containerRef(args.area) }),
-            ...(args.heading !== undefined && { heading: args.heading }),
-            ...(args.to_inbox === true && { inbox: true }),
-            ...(args.detach === true && { detach: true }),
-        }, {
-            ...writeOptions(args),
-            ...(args.to_inbox === true && { vector: "applescript" }),
-        }));
+        else if (args.to_project !== undefined) {
+            dests.push({ kind: "project", ref: containerRef(args.to_project) });
+        }
+        if (args.to_area !== undefined)
+            dests.push({ kind: "area", ref: containerRef(args.to_area) });
+        if (args.no_heading === true)
+            dests.push({ kind: "no-heading" });
+        if (args.loose === true)
+            dests.push({ kind: "loose" });
+        if (args.to_inbox === true)
+            dests.push({ kind: "inbox" });
+        if (dests.length > 1) {
+            return usage("pass at most one destination (to_project/to_heading/to_area/no_heading/loose/to_inbox)");
+        }
+        const position = movePositionArgs(args);
+        if (position === "conflict")
+            return usage("pass at most one of first/last/before/after");
+        const request = {
+            uuids: args.uuids,
+            ...(dests[0] !== undefined && { destination: dests[0] }),
+            ...(position !== undefined && { position }),
+        };
+        return moveResult(await getClient().write.moveTodos(request, writeOptions(args)));
     }));
     server.registerTool("set_tags", {
         description: "Replace or extend a to-do's or project's tags. mode 'replace' (default) sets exactly " +
@@ -1075,6 +1359,7 @@ export function createThingsMcpServer(options = {}) {
             mode: z.enum(["replace", "add"]).optional().describe("Default: replace"),
             ...createTagsShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1184,8 +1469,9 @@ export function createThingsMcpServer(options = {}) {
             "kind item: moves a to-do or project to the Trash (recoverable via restore_item until " +
             "the Trash is emptied; a deleted project takes its to-dos with it; not available for " +
             "repeating to-dos). kind area: PERMANENT — areas do not go to the Trash, so this cannot " +
-            "be undone and requires dangerously_permanent; the area's to-dos move to the Trash and " +
-            "its projects remain, no longer assigned to any area. kind tag: PERMANENT — requires " +
+            "be undone and 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_area (empty it first to keep its contents). kind tag: PERMANENT — requires " +
             "dangerously_permanent; the tag is removed from every item, and if it has nested child " +
             "tags they are ALL permanently deleted with it — pass acknowledge_tag_subtree to confirm.",
         inputSchema: {
@@ -1197,11 +1483,16 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("kind area/tag: confirm permanent, unrecoverable deletion"),
+            allow_non_empty_area: z
+                .boolean()
+                .optional()
+                .describe("kind area: delete a non-empty area together with its contents (its to-dos and projects move to the Trash)"),
             acknowledge_tag_subtree: z
                 .boolean()
                 .optional()
                 .describe("kind tag: confirm permanent deletion of ALL nested child tags too"),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1222,7 +1513,7 @@ export function createThingsMcpServer(options = {}) {
         description: "Restore a trashed to-do or project. A to-do returns to the Inbox without its " +
             "previous schedule or project/area. A project is restored in place: its schedule, " +
             "area, and children come back exactly as they were.",
-        inputSchema: { uuid: z.string(), ...dryRunShape },
+        inputSchema: { uuid: z.string(), ...dryRunShape, ...opIdShape },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
         const c = getClient();
@@ -1239,6 +1530,7 @@ export function createThingsMcpServer(options = {}) {
             completion_date: z.string().optional().describe(DATE_FORMAT),
             creation_date: z.string().optional().describe(DATE_FORMAT),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.backdateTodo(args.uuid, {
@@ -1255,6 +1547,7 @@ export function createThingsMcpServer(options = {}) {
             creation_date: z.string().optional().describe(`${DATE_FORMAT}; <= completion_date`),
             notes: z.string().optional(),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addLoggedTodo({
@@ -1264,33 +1557,76 @@ export function createThingsMcpServer(options = {}) {
         ...(args.notes !== undefined && { notes: args.notes }),
     }, writeOptions(args)))));
     server.registerTool("heading", {
-        description: "Manage a project heading — action selects which. create: a new heading in an existing " +
-            "project (project + title; returns its uuid; uses the Things proxy shortcuts, set up " +
-            "once with `things setup shortcuts`). rename: rename in place (uuid + title; works on " +
-            "archived headings). archive: retire a heading so it leaves the active project view " +
-            "(reversible with action unarchive); with open children pass children — complete or " +
-            "cancel resolve them with the heading in one cascade, reparent moves them to the project " +
-            "root keeping them open. unarchive: bring an archived heading back; restore_children also " +
-            "reopens the children the archive resolved with it. convert_to_project: promote a to-do " +
-            "or heading into a new project — this REPLACES the original and cannot be undone (a " +
-            "converted heading's to-dos move under the new project), and requires " +
-            "dangerously_drive_gui.",
+        description: "Manage a project's headings — action selects which; project is always required, and a " +
+            "heading is selected by its exact title or its uuid (never an ordinal). add_heading: a " +
+            "new heading in the project (project + title; returns its uuid; uses the Things proxy " +
+            "shortcuts, set up once with `things setup shortcuts`); a placement flag positions it, " +
+            "else it appends. rename_heading: rename in place (project + heading + title; works on " +
+            "archived headings). archive_heading: retire a heading so it leaves the active project " +
+            "view (reversible with unarchive_heading); with open children pass children — complete " +
+            "or cancel resolve them with the heading in one cascade, reparent moves them to the " +
+            "project root keeping them open. unarchive_heading: bring an archived heading back; " +
+            "restore_children also reopens the children the archive resolved with it. " +
+            "promote_heading: promote a heading into a new project — this REPLACES the heading and " +
+            "cannot be undone (its to-dos move under the new project), and requires " +
+            "dangerously_drive_gui. move_heading: reposition headings as an ordered block (children " +
+            "follow); pass exactly one placement flag. Reordering headings needs allow-experimental. " +
+            "move_heading_to_project: relocate ONE heading (with its to-dos) to a DIFFERENT project " +
+            "(project + heading + to_project) — the cross-project move, distinct from move_heading's " +
+            "within-project reorder; GUI-only (requires dangerously_drive_gui), fails closed on a " +
+            "source-heading or destination-project title collision, and has no undo (move it back). " +
+            "dissolve_heading: remove a heading but KEEP its to-dos as direct project children (NOT " +
+            "trashed — the opposite of a delete cascade); GUI-only (requires dangerously_drive_gui), " +
+            "fails closed on a title collision, no undo.",
         inputSchema: {
-            action: z.enum(["create", "rename", "archive", "unarchive", "convert_to_project"]),
-            project: z.string().optional().describe(`create: existing project (${REF_FORMAT})`),
-            uuid: z
+            action: z.enum([
+                "add_heading",
+                "rename_heading",
+                "archive_heading",
+                "unarchive_heading",
+                "promote_heading",
+                "move_heading",
+                "move_heading_to_project",
+                "dissolve_heading",
+            ]),
+            project: z.string().describe(`the heading's project (${REF_FORMAT})`),
+            heading: z
+                .string()
+                .optional()
+                .describe("rename/archive/unarchive/promote: the heading selector (exact title or uuid)"),
+            headings: z
+                .array(z.string())
+                .optional()
+                .describe("move_heading: heading selectors in the order they should land"),
+            to_project: z
                 .string()
                 .optional()
-                .describe("rename/archive/unarchive/convert_to_project: the target's uuid"),
-            title: z.string().optional().describe("create: the new heading; rename: the new title"),
+                .describe(`move_heading_to_project: the destination project (${REF_FORMAT})`),
+            title: z
+                .string()
+                .optional()
+                .describe("add_heading: the new heading; rename_heading: the new title"),
             children: z
                 .enum(["complete", "cancel", "reparent"])
                 .optional()
-                .describe("archive: required when the heading has open children"),
+                .describe("archive_heading: required when the heading has open children"),
             restore_children: z
                 .boolean()
                 .optional()
-                .describe("unarchive: also reopen the children archived with the heading"),
+                .describe("unarchive_heading: also reopen the children archived with the heading"),
+            first: z
+                .boolean()
+                .optional()
+                .describe("add/move: place first among the project's headings"),
+            last: z.boolean().optional().describe("add/move: place last among the project's headings"),
+            before_heading: z
+                .string()
+                .optional()
+                .describe("add/move: place immediately before this heading (title or uuid)"),
+            after_heading: z
+                .string()
+                .optional()
+                .describe("add/move: place immediately after this heading (title or uuid)"),
             ...driveGuiShape,
             ...dryRunShape,
         },
@@ -1298,45 +1634,105 @@ export function createThingsMcpServer(options = {}) {
     }, async (args) => guard(async () => {
         const c = getClient();
         const opts = writeOptions(args);
+        const proj = c.resolve.project(args.project);
+        const placementCount = [
+            args.first === true,
+            args.last === true,
+            args.before_heading !== undefined,
+            args.after_heading !== undefined,
+        ].filter(Boolean).length;
+        const placement = () => {
+            if (args.first === true)
+                return { position: "first" };
+            if (args.last === true)
+                return { position: "last" };
+            if (args.before_heading !== undefined) {
+                return { before: c.resolve.heading(proj.uuid, args.before_heading).uuid };
+            }
+            if (args.after_heading !== undefined) {
+                return { after: c.resolve.heading(proj.uuid, args.after_heading).uuid };
+            }
+            return undefined;
+        };
         switch (args.action) {
-            case "create":
-                if (args.project === undefined || args.title === undefined) {
-                    return usage('action "create" requires project and title');
+            case "add_heading": {
+                if (args.title === undefined)
+                    return usage('action "add_heading" requires title');
+                if (placementCount > 1) {
+                    return usage("pass at most one of first/last/before_heading/after_heading");
                 }
-                return mutationResult(await c.write.createHeading(containerRef(args.project), args.title, opts));
-            case "rename":
-                if (args.uuid === undefined || args.title === undefined) {
-                    return usage('action "rename" requires uuid and title');
+                return mutationResult(await c.write.addHeading({ uuid: proj.uuid }, args.title, placement(), opts));
+            }
+            case "rename_heading": {
+                if (args.heading === undefined || args.title === undefined) {
+                    return usage('action "rename_heading" requires heading and title');
                 }
-                return mutationResult(await c.write.renameHeading(args.uuid, args.title, opts));
-            case "archive": {
-                if (args.uuid === undefined)
-                    return usage('action "archive" requires uuid');
-                const r = await c.write.archiveHeading(args.uuid, args.children !== undefined ? { children: args.children } : {}, opts);
+                const h = c.resolve.heading(proj.uuid, args.heading);
+                return mutationResult(await c.write.renameHeading(h.uuid, args.title, opts));
+            }
+            case "archive_heading": {
+                if (args.heading === undefined)
+                    return usage('action "archive_heading" requires heading');
+                const h = c.resolve.heading(proj.uuid, args.heading);
+                const r = await c.write.archiveHeading(h.uuid, args.children !== undefined ? { children: args.children } : {}, opts);
                 return r.heading.kind === "ok" || r.heading.kind === "dry-run"
                     ? jsonResult(r)
                     : mutationResult(r.heading);
             }
-            case "unarchive": {
-                if (args.uuid === undefined)
-                    return usage('action "unarchive" requires uuid');
-                const r = await c.write.unarchiveHeading(args.uuid, args.restore_children === true ? { restoreChildren: true } : {}, opts);
+            case "unarchive_heading": {
+                if (args.heading === undefined) {
+                    return usage('action "unarchive_heading" requires heading');
+                }
+                const h = c.resolve.heading(proj.uuid, args.heading);
+                const r = await c.write.unarchiveHeading(h.uuid, args.restore_children === true ? { restoreChildren: true } : {}, opts);
                 return r.heading.kind === "ok" || r.heading.kind === "dry-run"
                     ? jsonResult(r)
                     : mutationResult(r.heading);
             }
-            case "convert_to_project": {
-                if (args.uuid === undefined) {
-                    return usage('action "convert_to_project" requires uuid');
+            case "promote_heading": {
+                if (args.heading === undefined)
+                    return usage('action "promote_heading" requires heading');
+                const h = c.resolve.heading(proj.uuid, args.heading);
+                return mutationResult(await c.write.run("project.promote-heading", { uuid: h.uuid }, opts));
+            }
+            case "move_heading": {
+                if (args.headings === undefined || args.headings.length === 0) {
+                    return usage('action "move_heading" requires headings');
+                }
+                if (placementCount !== 1) {
+                    return usage("move_heading requires exactly one of first/last/before_heading/after_heading");
+                }
+                const headings = args.headings.map((s) => c.resolve.heading(proj.uuid, s).uuid);
+                return mutationResult(await c.write.moveHeading({ uuid: proj.uuid }, headings, placement(), opts));
+            }
+            case "move_heading_to_project": {
+                if (args.heading === undefined || args.to_project === undefined) {
+                    return usage('action "move_heading_to_project" requires heading and to_project');
                 }
-                const item = c.read.byUuid(args.uuid);
-                if (item === null)
-                    throw new RangeError(`no item with uuid ${args.uuid}`);
-                const op = item.type === "heading" ? "heading.convert-to-project" : "todo.convert-to-project";
-                return mutationResult(await c.write.run(op, { uuid: args.uuid }, opts));
+                const dest = c.resolve.project(args.to_project);
+                return mutationResult(await c.write.moveHeadingToProject({ uuid: proj.uuid }, args.heading, { uuid: dest.uuid }, opts));
+            }
+            case "dissolve_heading": {
+                if (args.heading === undefined)
+                    return usage('action "dissolve_heading" requires heading');
+                const h = c.resolve.heading(proj.uuid, args.heading);
+                return mutationResult(await c.write.dissolveHeading(h.uuid, opts));
             }
         }
     }));
+    server.registerTool("convert_to_project", {
+        description: "Promote a to-do into a project. This REPLACES the to-do with a new project (its notes " +
+            "are kept); the to-do's identity is gone and it cannot be undone. Requires " +
+            "dangerously_drive_gui. The new project's uuid is on the result. (To promote a HEADING, " +
+            "use the heading tool's promote_heading action.)",
+        inputSchema: {
+            uuid: z.string().describe("the to-do's uuid"),
+            ...driveGuiShape,
+            ...dryRunShape,
+            ...opIdShape,
+        },
+        annotations: DESTRUCTIVE,
+    }, async (args) => guard(async () => mutationResult(await getClient().write.run("todo.convert-to-project", { uuid: args.uuid }, writeOptions(args)))));
     server.registerTool("clear_reminder", {
         description: "Clear a to-do's time-of-day reminder while keeping its scheduled date. Uses the " +
             "Things proxy shortcuts when installed (in place, and the only path for a repeating " +
@@ -1355,7 +1751,7 @@ export function createThingsMcpServer(options = {}) {
         "friday",
         "saturday",
     ]);
-    // The base rule (also used by create_repeating_project, which stays minimal —
+    // The base rule (also used by the repeat tool's create action, which stays minimal —
     // its own `deadline` is the project's due DATE, not the repeat's Add-deadlines).
     const baseRepeatShape = {
         frequency: z.enum(["daily", "weekly", "monthly", "yearly"]).describe("How often it repeats"),
@@ -1432,39 +1828,36 @@ export function createThingsMcpServer(options = {}) {
             "visible occurrence), templateUuid (the rule), and replacedUuid. action reschedule: " +
             "change a repeating item's rule in place, keeping the same item (undoable — it restores " +
             "the previous rule). action pause/resume: stop or restart its new occurrences, keeping " +
-            "the rule. action create (scope project only): create a project and make it repeating in " +
+            "the rule. action add (scope project only): create a project and make it repeating in " +
             "one call — the project is created first and PERSISTS even if the make-repeating step " +
             "refuses; give an area to place it or omit it to create in Someday (only frequency and " +
             "interval are supported); returns the new project's uuid.",
         inputSchema: {
             scope: z.enum(["todo", "project"]),
-            action: z.enum(["start", "reschedule", "pause", "resume", "create"]),
+            action: z.enum(["start", "reschedule", "pause", "resume", "add"]),
             uuid: z
                 .string()
                 .optional()
                 .describe("start/reschedule/pause/resume: the item (a project also accepts a unique name)"),
-            title: z.string().optional().describe("create (project): the new project's title"),
-            notes: z.string().optional().describe("create (project): notes"),
-            area: z.string().optional().describe(`create (project): destination area (${REF_FORMAT})`),
+            title: z.string().optional().describe("add (project): the new project's title"),
+            notes: z.string().optional().describe("add (project): notes"),
+            area: z.string().optional().describe(`add (project): destination area (${REF_FORMAT})`),
             project_deadline: z
                 .string()
                 .optional()
-                .describe(`create (project): the project's due date — ${DATE_FORMAT}`),
-            todos: z
-                .array(z.string())
-                .optional()
-                .describe("create (project): initial child to-do titles"),
+                .describe(`add (project): the project's due date — ${DATE_FORMAT}`),
+            todos: z.array(z.string()).optional().describe("add (project): initial child to-do titles"),
             frequency: z
                 .enum(["daily", "weekly", "monthly", "yearly"])
                 .optional()
-                .describe("start/reschedule/create: how often it repeats"),
+                .describe("start/reschedule/add: how often it repeats"),
             interval: z
                 .number()
                 .int()
                 .min(1)
                 .max(99)
                 .optional()
-                .describe("start/reschedule/create: every N units (1–99)"),
+                .describe("start/reschedule/add: every N units (1–99)"),
             after_completion: repeatRuleShape.after_completion,
             weekdays: repeatRuleShape.weekdays,
             monthly_day: repeatRuleShape.monthly_day,
@@ -1484,15 +1877,15 @@ export function createThingsMcpServer(options = {}) {
         const c = getClient();
         const opts = writeOptions(args);
         const { frequency, interval } = args;
-        if (args.action === "create") {
+        if (args.action === "add") {
             if (args.scope !== "project")
-                return usage('action "create" requires scope "project"');
+                return usage('action "add" requires scope "project"');
             if (args.title === undefined)
-                return usage('action "create" requires title');
+                return usage('action "add" requires title');
             if (frequency === undefined || interval === undefined) {
-                return usage('action "create" requires frequency and interval');
+                return usage('action "add" requires frequency and interval');
             }
-            return mutationResult(await c.write.createRepeatingProject({
+            return mutationResult(await c.write.addRepeatingProject({
                 title: args.title,
                 ...(args.notes !== undefined && { notes: args.notes }),
                 ...(args.area !== undefined && { area: containerRef(args.area) }),
@@ -1533,7 +1926,7 @@ export function createThingsMcpServer(options = {}) {
     server.registerTool("duplicate_item", {
         description: "Duplicate a to-do or project and return the copy's uuid; a duplicated project " +
             "includes its children. Not available for repeating items.",
-        inputSchema: { uuid: z.string(), ...dryRunShape },
+        inputSchema: { uuid: z.string(), ...dryRunShape, ...opIdShape },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
         const c = getClient();
@@ -1554,6 +1947,7 @@ export function createThingsMcpServer(options = {}) {
             todos: z.array(z.string()).optional().describe("Initial child to-do titles"),
             ...tzShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -1570,23 +1964,37 @@ export function createThingsMcpServer(options = {}) {
         }, writeOptions(args)));
     }));
     server.registerTool("move_project", {
-        description: "Move a project into an area, or detach it from its current area. Pass exactly " +
-            "one of area / detach. The project's status and schedule are unaffected.",
+        description: "Move one or more projects as an ordered block (spec §4/§5). Pass at most one " +
+            "destination: to_area, or no_area (leave the area — a project's complete detach). To " +
+            "REORDER projects among their siblings without changing area, pass a position " +
+            "(first/last/before/after) and NO destination. An anchor positions but never migrates. " +
+            "The project's status and schedule are unaffected; the result's placementClass states " +
+            "whether top-of-bucket placement was guaranteed.",
         inputSchema: {
-            uuid: z.string().describe(`The project to move (${REF_FORMAT})`),
-            area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
-            detach: z.boolean().optional().describe("Remove the current area assignment"),
+            uuids: z.array(z.string()).describe(`The projects to move (${REF_FORMAT}), in order`),
+            to_area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
+            no_area: z.boolean().optional().describe("Leave the current area (a project's detach)"),
+            ...positionShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        if ((args.detach === true) === (args.area !== undefined)) {
-            return usage("pass exactly one of area / detach");
-        }
-        const c = getClient();
-        return mutationResult(args.detach === true
-            ? await c.write.detachProject(args.uuid, writeOptions(args))
-            : await c.write.moveProject(args.uuid, containerRef(args.area), writeOptions(args)));
+        const dests = [];
+        if (args.to_area !== undefined)
+            dests.push({ kind: "area", ref: containerRef(args.to_area) });
+        if (args.no_area === true)
+            dests.push({ kind: "no-area" });
+        if (dests.length > 1)
+            return usage("pass at most one of to_area / no_area");
+        const position = movePositionArgs(args);
+        if (position === "conflict")
+            return usage("pass at most one of first/last/before/after");
+        const request = {
+            uuids: args.uuids,
+            ...(dests[0] !== undefined && { destination: dests[0] }),
+            ...(position !== undefined && { position }),
+        };
+        return moveResult(await getClient().write.moveProjects(request, writeOptions(args)));
     }));
     // ----------------------------------------------------------------- areas
     server.registerTool("add_area", {
@@ -1596,6 +2004,7 @@ export function createThingsMcpServer(options = {}) {
             tags: z.array(z.string()).optional().describe(`Tags — ${TAG_REF_FORMAT}`),
             ...createTagsShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addArea({ title: args.title, ...(args.tags !== undefined && { tags: args.tags }) }, writeOptions(args)))));
@@ -1606,6 +2015,7 @@ export function createThingsMcpServer(options = {}) {
             title: z.string(),
             parent: z.string().optional().describe("Existing parent tag name"),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.addTag({ title: args.title, ...(args.parent !== undefined && { parent: args.parent }) }, writeOptions(args)))));
@@ -1629,25 +2039,48 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("Required for area/tag delete and trash.empty (PERMANENT, no Trash)"),
+            allow_non_empty_area: z
+                .boolean()
+                .optional()
+                .describe("area.delete: delete a non-empty area together with its contents"),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => mutationResult(await getClient().write.run(args.op, args.params, writeOptions(args)))));
     server.registerTool("batch", {
         description: "Run several operations in order, each independently — there are no transactions, " +
             "and a failure does not roll back earlier operations. Per-operation results return " +
-            "in order; fail_fast skips the remainder after the first failure.",
+            "in order; fail_fast skips the remainder after the first failure. " +
+            "CHAINING: an operation that creates something may carry temp_id (a handle); a LATER " +
+            'operation references that new uuid as "$handle" in any id/container field (dotted ' +
+            '"$handle.instance"/"$handle.replaced" reach a repeating op\'s spawned instance / ' +
+            "replaced source). A temp_id is valid only on a creating operation (not tag.add — " +
+            "reference a tag by title) and unique per batch. IDEMPOTENCY: op_id makes resubmission " +
+            "safe — an operation matching an earlier success is reported already-applied, not " +
+            "re-created. The result adds temp_id_mapping (handle → uuid) and undo_token, which " +
+            "reverses the whole batch as one unit via the undo tool.",
         inputSchema: {
             ops: z
                 .array(z.object({
                 op: z.enum(OPERATION_KINDS),
                 params: z.record(z.string(), z.unknown()),
+                temp_id: z
+                    .string()
+                    .optional()
+                    .describe('Handle for this op\'s new uuid, referenced later as "$handle"'),
+                op_id: z
+                    .string()
+                    .optional()
+                    .describe("Idempotency id — a resubmitted op matching an earlier success is skipped"),
                 options: z
                     .object({
                     acknowledge_checklist_reset: z.boolean().optional(),
                     acknowledge_project_reopen: z.boolean().optional(),
                     dangerously_permanent: z.boolean().optional(),
                     acknowledge_tag_subtree: z.boolean().optional(),
+                    allow_non_empty_area: z.boolean().optional(),
+                    dangerously_drive_gui: z.boolean().optional(),
                 })
                     .optional(),
             }))
@@ -1668,91 +2101,126 @@ export function createThingsMcpServer(options = {}) {
                 ...(o?.acknowledge_project_reopen === true && { acknowledgeProjectReopen: true }),
                 ...(o?.dangerously_permanent === true && { dangerouslyPermanent: true }),
                 ...(o?.acknowledge_tag_subtree === true && { acknowledgeTagSubtree: true }),
+                ...(o?.allow_non_empty_area === true && { allowNonEmptyArea: true }),
+                ...(o?.dangerously_drive_gui === true && { dangerouslyDriveGui: true }),
                 ...(ceiling !== undefined && { maxDisruption: ceiling }),
             };
             return {
                 op: op.op,
                 params: op.params,
+                ...(op.temp_id !== undefined && { tempId: op.temp_id }),
+                ...(op.op_id !== undefined && { opId: op.op_id }),
                 ...(Object.keys(opts).length > 0 && { options: opts }),
             };
         });
-        const results = await getClient().write.batch(ops, {
+        const batchResult = await getClient().write.batch(ops, {
             ...(args.dry_run === true && { dryRun: true }),
             ...(args.fail_fast === true && { failFast: true }),
             actor: mcpActor(),
         });
-        return jsonResult(results);
+        // First block: the per-op results, each FLATTENED to the wire shape (a
+        // string `outcome` with the variant fields hoisted — parity with the CLI
+        // JSONL stream, docs/contract.md). Second block (additive): the batch
+        // chaining/undo summary, present only when the batch minted a token or
+        // bound temp ids.
+        const lines = batchResult.results.map(flattenBatchLine);
+        const hasSummary = batchResult.undoToken !== undefined || Object.keys(batchResult.tempIdMapping).length > 0;
+        if (!hasSummary)
+            return jsonResult(lines);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(lines) },
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        tempIdMapping: batchResult.tempIdMapping,
+                        ...(batchResult.undoToken !== undefined && { undoToken: batchResult.undoToken }),
+                    }),
+                },
+            ],
+        };
     }));
     server.registerTool("reorder", {
-        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 (scope=headings — children move with " +
-            "their heading), an area, or the top-level projects (scope=projects — " +
-            "each project takes a brief someday/anytime round-trip) — the given uuids move " +
-            "to the TOP in the given order; unlisted items keep their relative order below. " +
-            "Today/inbox/someday/project/headings/area ordering must first be enabled once " +
-            "via `things config set allow-experimental true`. This Evening and " +
-            `scope=projects handle at most ${BOUNCE_MAX_ITEMS} items per call. An area's ` +
-            "to-dos and projects are ordered separately — one kind per call. " +
-            "scope=areas instead moves the sidebar areas themselves: give target plus exactly " +
-            "one of before/after/position, and pass dangerously_drive_gui (it drives the local " +
-            "Things app). Every other scope takes uuids.",
+        description: "Rearrange to-dos IN PLACE within the list or container and the bucket they already " +
+            "share — this REARRANGES, never changes what an item belongs to (to change membership " +
+            "use move_todo / move_project). The refs 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 instead. Refs that span different containers or buckets are refused. " +
+            "A Today or This Evening member also holds a slot in its own container, so a set that is " +
+            "coherent on BOTH axes is ambiguous — pass `in` to name the axis (the refusal names both " +
+            "choices). A deadline-forecast set sharing one Upcoming day is dual-axis the same way (the " +
+            "day-block vs its container order); `in: upcoming` or `in: <YYYY-MM-DD>` names the day-block. " +
+            "The project rows the Today/Evening/day lists intermix with to-dos may be " +
+            "reordered alongside them. Ordering the Today, Inbox, or Someday lists, a project's " +
+            "to-dos, or an area must first be enabled once via `things config set allow-experimental " +
+            "true`. To reorder a project's HEADINGS (children follow) use the heading tool's " +
+            "move_heading action; to reorder sidebar AREAS use reorder_areas.",
         inputSchema: {
-            scope: z.enum([
-                "today",
-                "evening",
-                "inbox",
-                "someday",
-                "project",
-                "headings",
-                "area",
-                "projects",
-                "areas",
-            ]),
-            container: z
-                .string()
-                .optional()
-                .describe(`Project/area (${REF_FORMAT}) — required for those scopes`),
-            uuids: z
+            refs: z
                 .array(z.string())
+                .describe("The items to rearrange, in the order they should land (may be a subset)"),
+            ...positionShape,
+            in: z
+                .string()
                 .optional()
-                .describe("Desired order, top first (may be a subset) — required for every scope but areas"),
-            strategy: z.enum(["native", "bounce"]).optional(),
-            target: z.string().optional().describe(`scope areas: the area to move (${REF_FORMAT})`),
+                .describe("Name the axis to reorder on: today | evening | anytime | someday | inbox, a project/" +
+                "area/heading ref (uuid or unique title), upcoming (the one future day the set " +
+                "shares), or a YYYY-MM-DD day-block. A stage-list or container axis sorts one KIND " +
+                "at a time — a mixed to-do+project set is refused (even sharing a container); only " +
+                "today | evening | upcoming | a day-block intermix both kinds. Reorder a project's " +
+                "headings with the heading tool's move_heading action."),
+            ...dryRunShape,
+        },
+        annotations: NON_DESTRUCTIVE,
+    }, async (args) => guard(async () => {
+        const position = movePositionArgs(args);
+        if (position === "conflict")
+            return usage("pass at most one of first/last/before/after");
+        const request = {
+            uuids: args.refs,
+            ...(position !== undefined && { position }),
+            ...(args.in !== undefined && { in: args.in }),
+        };
+        return moveResult(await getClient().write.reorderTodos(request, writeOptions(args)));
+    }));
+    server.registerTool("reorder_areas", {
+        description: "Move a sidebar 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 " +
+            "visibly drives the local Things app (the window comes forward and the sidebar may " +
+            "scroll) and must be turned on first with `things config set ui-enabled true`; the " +
+            "area's projects and to-dos are untouched.",
+        inputSchema: {
+            target: z.string().describe(`the area to move (${REF_FORMAT})`),
             before: z
                 .string()
                 .optional()
-                .describe(`scope areas: place it immediately above this area (${REF_FORMAT})`),
+                .describe(`place it immediately above this area (${REF_FORMAT})`),
             after: z
                 .string()
                 .optional()
-                .describe(`scope areas: place it immediately below this area (${REF_FORMAT})`),
-            position: z
-                .enum(["first", "last"])
-                .optional()
-                .describe("scope areas: move it to the top or bottom of the area list"),
+                .describe(`place it immediately below this area (${REF_FORMAT})`),
+            first: z.boolean().optional().describe("move it to the top of the area list"),
+            last: z.boolean().optional().describe("move it to the bottom of the area list"),
             ...driveGuiShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        if (args.scope === "areas") {
-            if (args.target === undefined)
-                return usage('scope "areas" requires target');
-            return mutationResult(await getClient().write.run("area.reorder", {
-                target: args.target,
-                ...(args.before !== undefined && { before: args.before }),
-                ...(args.after !== undefined && { after: args.after }),
-                ...(args.position !== undefined && { position: args.position }),
-            }, writeOptions(args)));
-        }
-        if (args.uuids === undefined)
-            return usage(`scope "${args.scope}" requires uuids`);
-        return mutationResult(await getClient().write.reorder({
-            scope: args.scope,
-            uuids: args.uuids,
-            ...(args.container !== undefined && { container: containerRef(args.container) }),
-            ...(args.strategy !== undefined && { strategy: args.strategy }),
+        const chosen = [
+            args.before !== undefined,
+            args.after !== undefined,
+            args.first === true,
+            args.last === true,
+        ].filter(Boolean).length;
+        if (chosen !== 1)
+            return usage("pass exactly one of before / after / first / last");
+        return mutationResult(await getClient().write.run("area.reorder", {
+            target: args.target,
+            ...(args.before !== undefined && { before: args.before }),
+            ...(args.after !== undefined && { after: args.after }),
+            ...(args.first === true && { position: "first" }),
+            ...(args.last === true && { position: "last" }),
         }, writeOptions(args)));
     }));
     server.registerTool("undo", {