things-api 0.13.0 → 0.14.0

package/dist/mcp/server.js

@@ -16,7 +16,7 @@
  */
 import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.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";
+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, RESOLUTION_DATE_FORMAT, schemaWarnings, shapeReadPayload, withTodayBucketTotals, withAreaBucketTotals, withSectionTotals, withUpcomingBlockTotals, splitWhenSugar, tagFilterFields, tagFlagConflict, validateViewArgs, verifyFailedCode, WHEN_VALUES, } from "../index.js";
 function jsonResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
@@ -52,10 +52,11 @@ function truncatedResult(data, truncation, meta) {
     };
 }
 /**
- * Grouped read result (anytime/someday): the per-block-truncated sections plus
- * 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.
+ * Grouped read result (anytime/someday): the per-block-truncated sections (each
+ * capped section carrying its inline `total`, R1) plus a second block carrying
+ * the WHOLE-VIEW {@link Truncation} rollup and, when anything was hidden, a
+ * one-line note the agent can read. The pre-v2 `blocks[]` sidecar is retired —
+ * completeness rides each section's inline `total` (doctrine v2 PR 5).
  */
 function groupedResult(data, truncation) {
     const note = truncation.truncated
@@ -238,6 +239,26 @@ function movePositionArgs(args) {
         return { after: args.after };
     return undefined;
 }
+/** The universal-reorder anchor grammar (start/end/before/after → MovePosition). */
+function reorderPositionArgs(args) {
+    const chosen = [
+        args.start === true,
+        args.end === true,
+        args.before !== undefined,
+        args.after !== undefined,
+    ].filter(Boolean).length;
+    if (chosen > 1)
+        return "conflict";
+    if (args.start === true)
+        return { at: "first" };
+    if (args.end === 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"),
@@ -392,10 +413,9 @@ 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. 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.",
+            "tags inherited from its containing project and area. The today and evening markers are " +
+            "present only for an item in Today (evening implies today); an unscheduled start=active item " +
+            "is in Anytime and carries neither. 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}`,
     ];
@@ -577,14 +597,15 @@ export function createThingsMcpServer(options = {}) {
     };
     // ------------------------------------------------------------------ reads
     server.registerTool("read_view", {
-        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, " +
+        description: "Read a Things list as the app presents it: today (two children buckets — " +
+            "children.today and children.evening, evening expires daily; the whole-view " +
+            "count due/overdue vs. other rides the result's second block), 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 " +
             "from anytime — the project row represents them; someday lists each group's " +
-            "project rows before its to-dos. Flat views (today/inbox/upcoming/logbook/trash) " +
+            "project rows before its to-dos. Row-capped views (today/inbox/upcoming/logbook/trash) " +
             `return at most ${DEFAULT_LIST_LIMIT} items by default (raise with limit); ` +
             "anytime/someday always return every group and cap per block instead — " +
             `area_limit (default ${AREA_PREVIEW_LIMIT}) per area block, and on anytime ` +
@@ -601,10 +622,7 @@ export function createThingsMcpServer(options = {}) {
                 .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)"),
+            evening: z.boolean().optional().describe("today only: show only the This Evening section"),
             show_active_project_items: z
                 .union([z.boolean(), z.number().int().min(1)])
                 .optional()
@@ -707,7 +725,7 @@ export function createThingsMcpServer(options = {}) {
             const area = args.area !== undefined ? { area: args.area } : {};
             switch (args.view) {
                 case "today": {
-                    const { view, truncation, filter: fm, } = c.read.today({
+                    const { view, truncation, totals, filter: fm, } = c.read.today({
                         ...filter,
                         ...zone,
                         ...area,
@@ -715,14 +733,17 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("today", view, full, c.refPromoter()), truncation, { counts: view.counts });
+                    // The data block is the two `children` bucket records (each with its
+                    // inline `total` when capped); the whole-view `counts` aggregate
+                    // rides the metadata block (the CLI meta.counts analog).
+                    return truncatedResult(withTodayBucketTotals(shapeReadPayload("today", view, full, c.refPromoter()), totals), 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({
+                    const { view, truncation, sectionTotals, filter: fm, } = c.read.anytime({
                         ...filter,
                         ...zone,
                         ...area,
@@ -730,10 +751,10 @@ export function createThingsMcpServer(options = {}) {
                         projectLimit,
                     });
                     filterMeta = fm;
-                    return groupedResult(shapeReadPayload("anytime", view, full, c.refPromoter()), truncation);
+                    return groupedResult(withSectionTotals(shapeReadPayload("anytime", view, full, c.refPromoter()), sectionTotals), truncation);
                 }
                 case "upcoming": {
-                    const { items, truncation, filter: fm, } = c.read.upcoming({
+                    const { items, truncation, upcomingTotals, filter: fm, } = c.read.upcoming({
                         ...filter,
                         ...zone,
                         ...area,
@@ -741,14 +762,16 @@ export function createThingsMcpServer(options = {}) {
                         limit,
                     });
                     filterMeta = fm;
-                    return truncatedResult(shapeReadPayload("upcoming", items, full, c.refPromoter()), truncation);
+                    // The data block is the day-block `sections` array, each capped block
+                    // carrying its inline `total` (R1); the flat rollup rides truncation.
+                    return truncatedResult(withUpcomingBlockTotals(shapeReadPayload("upcoming", items, full, c.refPromoter()), upcomingTotals), 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({
+                    const { view, truncation, sectionTotals, filter: fm, } = c.read.someday({
                         ...filter,
                         ...zone,
                         ...area,
@@ -760,7 +783,7 @@ export function createThingsMcpServer(options = {}) {
                         projectLimit: typeof active === "number" ? active : null,
                     });
                     filterMeta = fm;
-                    return groupedResult(shapeReadPayload("someday", view, full, c.refPromoter()), truncation);
+                    return groupedResult(withSectionTotals(shapeReadPayload("someday", view, full, c.refPromoter()), sectionTotals), truncation);
                 }
                 case "logbook": {
                     const { items, truncation, filter: fm, } = c.read.logbook({
@@ -888,13 +911,11 @@ export function createThingsMcpServer(options = {}) {
             : readResult(shapeReadPayload("detail", item, false, getClient().refPromoter()));
     }));
     server.registerTool("get_project", {
-        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). " +
+        description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
+            "Open headings (and archived ones not yet swept to the logbook) stay live, carrying " +
+            "archived once archived; a swept archived heading moves into the logged region as a " +
+            "group with its children. 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,
@@ -922,11 +943,11 @@ export function createThingsMcpServer(options = {}) {
         }), args.full === true, getClient().refPromoter()));
     }, args.tz));
     server.registerTool("get_area", {
-        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 ` +
+        description: "One area's contents: metadata plus its direct to-dos (active first), its " +
+            "projects in canonical order, and later (scheduled/repeating/someday). 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 direct-to-dos sections 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 +
@@ -972,7 +993,7 @@ export function createThingsMcpServer(options = {}) {
             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, {
+            const { view, truncation, totals, notice } = getClient().read.areaView(args.ref, {
                 overdue: args.overdue === true,
                 ...tagFilterFields(tagPresence(args)),
                 ...(args.tz !== undefined && { zone: args.tz }),
@@ -980,7 +1001,9 @@ export function createThingsMcpServer(options = {}) {
                 projectLimit,
             });
             areaNotice = notice;
-            return groupedResult(shapeReadPayload("area-view", view, args.full === true, getClient().refPromoter()), truncation);
+            // Each capped scope's completeness rides its inline `total` (R1, PR 3);
+            // the whole-view rollup rides `truncation` (no `blocks[]` sidecar).
+            return groupedResult(withAreaBucketTotals(shapeReadPayload("area-view", view, args.full === true, getClient().refPromoter()), totals), truncation);
         }, args.tz, undefined, () => (areaNotice !== undefined ? [areaNotice] : undefined));
     });
     server.registerTool("list_collections", {
@@ -1059,6 +1082,15 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("Confirm adding into a completed/canceled project (this reopens it)"),
+            created_at: z
+                .string()
+                .optional()
+                .describe(`Born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`),
+            completed_at: z
+                .string()
+                .optional()
+                .describe(`Born completed, in the Logbook, with this completion timestamp ` +
+                `(${RESOLUTION_DATE_FORMAT}); drop when/reminder`),
             ...createTagsShape,
             ...tzShape,
             ...dryRunShape,
@@ -1085,6 +1117,8 @@ export function createThingsMcpServer(options = {}) {
             ...(args.project !== undefined && { project: containerRef(args.project) }),
             ...(args.area !== undefined && { area: containerRef(args.area) }),
             ...(args.heading !== undefined && { heading: args.heading }),
+            ...(args.created_at !== undefined && { createdAt: args.created_at }),
+            ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
         }, writeOptions(args)));
     }));
     server.registerTool("update", {
@@ -1094,7 +1128,10 @@ export function createThingsMcpServer(options = {}) {
             "deadline/clear_deadline; changing the schedule keeps an existing reminder unless a new " +
             "one is set, schedule and deadline changes are unavailable for repeating items, and " +
             "clear_reminder needs the item scheduled for today or this evening (a reminder on a " +
-            "future date can only be changed, not cleared). kind area: title and/or tags (the full " +
+            "future date can only be changed, not cleared). created_at/completed_at rewrite the " +
+            "resolution timestamps of an already-resolved item; created_at is status-safe, but " +
+            "completed_at on an open item is refused — resolving it is set_status's boundary, not " +
+            "update's. kind area: title and/or tags (the full " +
             "replacement set). kind tag: title, parent (nest under it) or unnest (to the top level; " +
             "exclusive), and shortcut or clear_shortcut (exclusive). Tags must exist unless " +
             "create_tags is set.",
@@ -1113,6 +1150,16 @@ export function createThingsMcpServer(options = {}) {
             clear_reminder: z.boolean().optional().describe("todo/project: remove the reminder"),
             deadline: z.string().optional().describe(`todo/project: ${DATE_FORMAT}`),
             clear_deadline: z.boolean().optional().describe("todo/project: remove the deadline"),
+            created_at: z
+                .string()
+                .optional()
+                .describe(`todo/project: rewrite the creation timestamp (${RESOLUTION_DATE_FORMAT}); status-safe`),
+            completed_at: z
+                .string()
+                .optional()
+                .describe("todo/project: rewrite the completion timestamp of an already-resolved item " +
+                `(${RESOLUTION_DATE_FORMAT}; a canceled one stays canceled); an open item is ` +
+                "refused — use set_status to resolve it"),
             tags: z
                 .array(z.string())
                 .optional()
@@ -1160,6 +1207,8 @@ export function createThingsMcpServer(options = {}) {
                     ...(args.clear_reminder === true && { reminder: null }),
                     ...(args.deadline !== undefined && { deadline: args.deadline }),
                     ...(args.clear_deadline === true && { deadline: null }),
+                    ...(args.created_at !== undefined && { createdAt: args.created_at }),
+                    ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
                 }, opts));
             }
             return mutationResult(await c.write.updateProject(args.uuid, {
@@ -1172,6 +1221,8 @@ export function createThingsMcpServer(options = {}) {
                 ...(args.clear_reminder === true && { reminder: null }),
                 ...(args.deadline !== undefined && { deadline: args.deadline }),
                 ...(args.clear_deadline === true && { deadline: null }),
+                ...(args.created_at !== undefined && { createdAt: args.created_at }),
+                ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
             }, opts));
         }
         if (args.kind === "area") {
@@ -1211,7 +1262,10 @@ export function createThingsMcpServer(options = {}) {
             "scope project, completing or canceling requires a children policy: 'require-resolved' " +
             "errors if open to-dos remain; 'auto-complete'/'auto-cancel' resolves them together with " +
             "the project (canceling never alters already-completed children). scope project, status " +
-            "open, restore_children also reopens the to-dos that were resolved with the project.",
+            "open, restore_children also reopens the to-dos that were resolved with the project. " +
+            "completed_at (status completed or canceled) sets the completion timestamp — also the " +
+            '"Completed on" stamp for a canceled item — backdating it; reaching a backdated canceled ' +
+            "item is a multi-leg, non-atomic sequence, disclosed in the result and in dry_run.",
         inputSchema: {
             scope: z.enum(["todo", "project"]),
             uuid: z
@@ -1226,21 +1280,33 @@ export function createThingsMcpServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe("scope project, open only: also reopen the to-dos resolved with the project"),
+            completed_at: z
+                .string()
+                .optional()
+                .describe(`status completed or canceled: the completion timestamp (${RESOLUTION_DATE_FORMAT})`),
+            ...tzShape,
             ...dryRunShape,
             ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
         const c = getClient();
         const opts = writeOptions(args);
+        if (args.completed_at !== undefined && args.status === "open") {
+            return usage("completed_at applies only to status 'completed' or 'canceled'");
+        }
+        const resolution = args.completed_at !== undefined ? { completedAt: args.completed_at } : {};
         if (args.scope === "todo") {
             if (args.children !== undefined || args.restore_children !== undefined) {
                 return usage("children/restore_children apply only to scope project");
             }
             return mutationResult(args.status === "completed"
-                ? await c.write.completeTodo(args.uuid, opts)
+                ? await c.write.completeTodo(args.uuid, resolution, opts)
                 : args.status === "canceled"
-                    ? await c.write.cancelTodo(args.uuid, opts)
+                    ? await c.write.cancelTodo(args.uuid, resolution, opts)
                     : await c.write.reopenTodo(args.uuid, opts));
         }
         // scope project
@@ -1251,13 +1317,13 @@ export function createThingsMcpServer(options = {}) {
             if (args.children !== "require-resolved" && args.children !== "auto-complete") {
                 return usage("status 'completed' requires children: 'require-resolved' or 'auto-complete'");
             }
-            return mutationResult(await c.write.completeProject(args.uuid, { children: args.children }, opts));
+            return mutationResult(await c.write.completeProject(args.uuid, { children: args.children, ...resolution }, opts));
         }
         if (args.status === "canceled") {
             if (args.children !== "require-resolved" && args.children !== "auto-cancel") {
                 return usage("status 'canceled' requires children: 'require-resolved' or 'auto-cancel'");
             }
-            return mutationResult(await c.write.cancelProject(args.uuid, { children: args.children }, opts));
+            return mutationResult(await c.write.cancelProject(args.uuid, { children: args.children, ...resolution }, opts));
         }
         if (args.children !== undefined) {
             return usage("children applies only to status 'completed' or 'canceled'");
@@ -1521,41 +1587,12 @@ export function createThingsMcpServer(options = {}) {
             ? await c.write.restoreTodo(args.uuid, writeOptions(args))
             : await c.write.restoreProject(args.uuid, writeOptions(args)));
     }));
-    server.registerTool("backdate_todo", {
-        description: "Rewrite a to-do's completion and/or creation timestamp to noon (local) on the " +
-            "given date. completion_date requires the to-do to already be completed or " +
-            "canceled; the Logbook re-sorts to the new date.",
-        inputSchema: {
-            uuid: z.string(),
-            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, {
-        ...(args.completion_date !== undefined && { completionDate: args.completion_date }),
-        ...(args.creation_date !== undefined && { creationDate: args.creation_date }),
-    }, writeOptions(args)))));
-    server.registerTool("add_logged_todo", {
-        description: "Create a to-do directly in the Logbook: completed, with the given past " +
-            "completion date (and optionally a past creation date). For importing history " +
-            "from another system.",
-        inputSchema: {
-            title: z.string(),
-            completion_date: z.string().describe(DATE_FORMAT),
-            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({
-        title: args.title,
-        completionDate: args.completion_date,
-        ...(args.creation_date !== undefined && { creationDate: args.creation_date }),
-        ...(args.notes !== undefined && { notes: args.notes }),
-    }, writeOptions(args)))));
+    // NB: the bespoke backdate_todo / add_logged_todo tools were removed with the
+    // engine ops (plan PR A). MCP parity for the resolution-timestamp surface is
+    // restored (PR B) as created_at/completed_at params folded onto the existing
+    // write tools: add_todo / add_project (Logbook import), update (rewrite an
+    // already-resolved item's timestamps), and set_status (backdate on
+    // complete/cancel) — matching the CLI's --created-at/--completed-at flags.
     server.registerTool("heading", {
         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 " +
@@ -1945,6 +1982,15 @@ export function createThingsMcpServer(options = {}) {
             when: whenSchema,
             deadline: z.string().optional().describe(DATE_FORMAT),
             todos: z.array(z.string()).optional().describe("Initial child to-do titles"),
+            created_at: z
+                .string()
+                .optional()
+                .describe(`Born with this creation timestamp (${RESOLUTION_DATE_FORMAT})`),
+            completed_at: z
+                .string()
+                .optional()
+                .describe(`Born completed, in the Logbook, with this completion timestamp ` +
+                `(${RESOLUTION_DATE_FORMAT}); cannot seed open child to-dos`),
             ...tzShape,
             ...dryRunShape,
             ...opIdShape,
@@ -1961,6 +2007,8 @@ export function createThingsMcpServer(options = {}) {
             ...(args.when !== undefined && { when: args.when }),
             ...(args.deadline !== undefined && { deadline: args.deadline }),
             ...(args.todos !== undefined && { todos: args.todos }),
+            ...(args.created_at !== undefined && { createdAt: args.created_at }),
+            ...(args.completed_at !== undefined && { completedAt: args.completed_at }),
         }, writeOptions(args)));
     }));
     server.registerTool("move_project", {
@@ -2141,87 +2189,53 @@ export function createThingsMcpServer(options = {}) {
         };
     }));
     server.registerTool("reorder", {
-        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.",
+        description: "The ONE reorder tool — rearrange a single-KIND set IN PLACE: to-dos, projects, headings, " +
+            "OR sidebar areas. This REARRANGES, never changes what an item belongs to (to change " +
+            "membership use move_todo / move_project). All refs must be one kind; only to-dos and " +
+            "projects may intermix, and only on the shared Today/Evening/day axes. A mixed-kind set, " +
+            "a cross-container set, and a non-member anchor each get one precise refusal. 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; start/end/" +
+            "before/after position the block. A Today or This Evening member also holds a slot in its " +
+            "container, so a set coherent on BOTH axes is ambiguous — pass `in` to name the axis. " +
+            "HEADINGS: same-project heading re-ranking runs the native heading-block wire (children " +
+            "follow); an archived heading is reorderable but repositioning it brings it back to open " +
+            "(disclosed in the result). AREAS: this drives the local Things app (sidebar drag) and " +
+            "must be turned on with `things config set ui-enabled true` plus dangerously_drive_gui; " +
+            "the areas' projects and to-dos are untouched. Ordering the Today, Inbox, or Someday " +
+            "lists, or a project's to-dos, must first be enabled once via `things config set " +
+            "allow-experimental true`.",
         inputSchema: {
             refs: z
                 .array(z.string())
-                .describe("The items to rearrange, in the order they should land (may be a subset)"),
-            ...positionShape,
+                .describe("The items to rearrange (one kind: to-dos, projects, headings, or areas), in the " +
+                "order they should land (may be a subset)"),
+            start: z.boolean().optional().describe("place the block at the start of its scope"),
+            end: z.boolean().optional().describe("place the block at the end of its scope"),
+            before: z.string().optional().describe("place the block immediately before this item"),
+            after: z.string().optional().describe("place the block immediately after this item"),
             in: z
                 .string()
                 .optional()
-                .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."),
+                .describe("to-dos/projects only — 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; only today | evening | upcoming | a " +
+                "day-block intermix both kinds."),
+            ...driveGuiShape,
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const position = movePositionArgs(args);
+        const position = reorderPositionArgs(args);
         if (position === "conflict")
-            return usage("pass at most one of first/last/before/after");
+            return usage("pass at most one of start/end/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(`place it immediately above this area (${REF_FORMAT})`),
-            after: z
-                .string()
-                .optional()
-                .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 () => {
-        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)));
+        return moveResult(await getClient().write.reorderAny(request, writeOptions(args)));
     }));
     server.registerTool("undo", {
         description: "Undo the last N changes, newest first (changes made directly in the Things app " +