things-api 0.10.0 → 0.12.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, 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, 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) }] };
 }
@@ -44,17 +47,18 @@ function truncatedResult(data, truncation) {
 }
 /**
  * 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 }) }) },
         ],
     };
 }
@@ -72,27 +76,60 @@ function resolveCap(value, all, defaultLimit) {
         return null;
     return value ?? defaultLimit;
 }
-/** Resolve MCP limit/all (flat read tools) into a row cap (null = every row). */
+/**
+ * Resolve MCP limit/all (flat read tools) into a row cap (null = every row).
+ * all:true wins: it lifts the cap and takes precedence over a limit passed
+ * alongside it — an explicit "everything" request resolves the contradiction
+ * rather than erroring — so the pair is never a usage error on the flat tools.
+ */
 function resolveLimit(args) {
-    return resolveCap(args.limit, args.all, DEFAULT_LIST_LIMIT);
+    if (args.all === true)
+        return null;
+    return args.limit ?? DEFAULT_LIST_LIMIT;
 }
+/** Precedence notes appended to `limit`/`all` wherever a flat tool accepts both. */
+const LIMIT_IGNORED_NOTE = "ignored when all is set";
+const ALL_WINS_NOTE = "wins over limit if both are set";
 /** Shared limit/all input schema fragment for the flat read tools. */
 const limitShape = {
-    limit: z.number().int().min(1).optional().describe(LIMIT_DESC),
-    all: z.boolean().optional().describe(ALL_DESC),
+    limit: z.number().int().min(1).optional().describe(`${LIMIT_DESC}; ${LIMIT_IGNORED_NOTE}`),
+    all: z.boolean().optional().describe(`${ALL_DESC}; ${ALL_WINS_NOTE}`),
 };
+/**
+ * The per-call time-zone knob for date-sensitive tools: an IANA zone that
+ * evaluates every date boundary (today/evening/upcoming/logbook/overdue/…) for
+ * the consumer's calendar, overriding the server's THINGS_TZ for THIS call.
+ */
+const TZ_DESC = "IANA time zone (e.g. Asia/Tokyo) to evaluate date boundaries in for this call — " +
+    "overrides the server default. Reminder times stay wall-clock and are never shifted.";
+const tzShape = { tz: z.string().optional().describe(TZ_DESC) };
+/** A usage result when `tz` is present but not a recognized IANA zone; null when it is valid/absent. */
+function badTz(tz) {
+    if (tz !== undefined && !isValidTimeZone(tz)) {
+        return usage(`tz is not a valid IANA time zone: "${tz}" — expected e.g. "America/New_York" or "Asia/Tokyo"`);
+    }
+    return null;
+}
 function errorResult(error) {
     return { content: [{ type: "text", text: JSON.stringify(error) }], isError: true };
 }
 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),
@@ -121,6 +158,89 @@ 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({
+                code: 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 };
@@ -176,6 +296,35 @@ 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` tool, the heading tool's `promote_heading` action, and
+ * the `areas` reorder scope.
+ */
+const driveGuiShape = {
+    dangerously_drive_gui: z
+        .boolean()
+        .optional()
+        .describe("Required: this drives the local Things app through its accessibility interface to " +
+        "make a change the app offers nowhere else. It briefly interacts with the app's UI " +
+        "on the machine running this server, and must be turned on first with `things config " +
+        "set ui-enabled true`. Intended for a dedicated always-on Mac."),
+};
 /** How a tag value may be expressed on any tag-accepting tool. */
 const TAG_REF_FORMAT = "each a tag name or a parent/child path; must exist unless create_tags is set";
 /** create_tags param, shared by every tag-accepting write tool. */
@@ -187,6 +336,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`. */
@@ -211,20 +374,39 @@ function buildInstructions(getClient) {
             "rather than being guessed at. Create missing tags/areas/projects first (add_tag, " +
             "add_area, add_project).",
         `- Scheduling vocabulary: when = ${WHEN_VALUES}; deadlines are ${DATE_FORMAT}; reminders ` +
-            `are ${REMINDER_FORMAT}.`,
+            `are ${REMINDER_FORMAT}. Resolve relative calendar phrases against the Calendar context ` +
+            `below (or a date-sensitive read result's meta.clock.today), then pass the explicit date.`,
         "- Every write tool accepts dry_run: true to preview the change without applying it. " +
-            "Operations with cascading or permanent effects require the explicit confirmation " +
-            "parameter named in their description; refused calls return an error saying what to pass.",
+            "A preview creates no state, so later calls cannot reference an item that only appeared in " +
+            "a dry-run result. Operations with cascading or permanent effects require the explicit " +
+            "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. 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}`,
     ];
     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();
+        const clock = c.clockMeta();
         const shown = projects.slice(0, INSTRUCTIONS_MAX_PROJECTS);
         const overflow = projects.length - shown.length;
-        lines.push("", "Current inventory (read at server start — refresh with list_collections):", `- Areas (${areas.length}): ${areas.map((a) => a.title).join(", ") || "none"}`, `- Tags (${tags.length}): ${tags.map(tagLabel).join(", ") || "none"}`, `- Open projects (${projects.length}): ${shown.map((p) => p.title).join("; ") || "none"}` +
+        lines.push("", "Current inventory (read at server start — refresh with list_collections):", ...(clock !== undefined
+            ? [`- Calendar context at server start: ${JSON.stringify(clock)}`]
+            : []), `- Areas (${areas.length}): ${areas.map((a) => a.title).join(", ") || "none"}`, `- Tags (${tags.length}): ${tags.map(tagLabel).join(", ") || "none"}`, `- Open projects (${projects.length}): ${shown.map((p) => p.title).join("; ") || "none"}` +
             (overflow > 0 ? `; …and ${overflow} more (list_collections for all)` : ""));
     }
     catch {
@@ -256,6 +438,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.
@@ -263,6 +452,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;
@@ -283,8 +473,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) => {
@@ -313,23 +506,52 @@ 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) => {
+    const readGuard = async (fn, tz, extraMeta, extraWarnings) => {
         const result = await guard(fn);
         if (result.isError === true)
             return result;
         let warnings = [];
+        let clock;
         try {
-            warnings = schemaWarnings(getClient().schemaStatus());
+            const c = getClient();
+            warnings = schemaWarnings(c.schemaStatus());
+            // The clock honesty field for this call's effective zone (the per-call
+            // tz over the server default) — present only when a consumer zone /
+            // pinned now is in effect.
+            clock = c.clockMeta(tz);
         }
         catch {
             warnings = [];
         }
-        if (warnings.length === 0)
+        // 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 = {
+            ...(allWarnings.length > 0 && { warnings: allWarnings }),
+            ...(clock !== undefined && { clock }),
+            ...extra,
+        };
+        if (Object.keys(meta).length === 0)
             return result;
         return {
             ...result,
-            content: [...result.content, { type: "text", text: JSON.stringify({ meta: { warnings } }) }],
+            content: [...result.content, { type: "text", text: JSON.stringify({ meta }) }],
         };
     };
     /** Resolve a uuid to to-do/project for the type-generic item tools. */
@@ -360,6 +582,11 @@ export function createThingsMcpServer(options = {}) {
         inputSchema: {
             view: z.enum(["today", "inbox", "anytime", "upcoming", "someday", "logbook", "trash"]),
             ...tagFilterShape,
+            ...tzShape,
+            area: z
+                .string()
+                .optional()
+                .describe(`today/anytime/someday/upcoming/logbook only: ${AREA_FILTER_DESC}`),
             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)])
@@ -382,7 +609,7 @@ export function createThingsMcpServer(options = {}) {
                 .int()
                 .min(1)
                 .optional()
-                .describe(`flat views only (not anytime/someday): ${LIMIT_DESC}`),
+                .describe(`flat views only (not anytime/someday): ${LIMIT_DESC}; ${LIMIT_IGNORED_NOTE}`),
             area_limit: z
                 .number()
                 .int()
@@ -398,102 +625,143 @@ export function createThingsMcpServer(options = {}) {
             all: z
                 .boolean()
                 .optional()
-                .describe("show everything (flat views: no row limit; anytime/someday: no per-block caps)"),
+                .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(() => {
-        // 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);
-        if (limit === "conflict")
-            return usage("pass at most one of limit / all");
-        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;
-        switch (args.view) {
-            case "today": {
-                const { view, truncation } = c.read.today({
-                    ...filter,
-                    ...(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, 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, 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,
-                    ...(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,
-                    ...((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, 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({ 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");
             }
-        }
-    }));
+            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), truncation);
+                }
+                case "inbox": {
+                    const { items, truncation } = c.read.inbox({ ...filter, ...zone, limit });
+                    return truncatedResult(shapeReadPayload("inbox", items, full), truncation);
+                }
+                case "anytime": {
+                    const { view, truncation, filter: fm, } = c.read.anytime({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        areaLimit,
+                        projectLimit,
+                    });
+                    filterMeta = fm;
+                    return groupedResult(shapeReadPayload("anytime", view, full), 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), 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), truncation);
+                }
+                case "logbook": {
+                    const { items, truncation, filter: fm, } = c.read.logbook({
+                        ...filter,
+                        ...zone,
+                        ...area,
+                        limit,
+                    });
+                    filterMeta = fm;
+                    return truncatedResult(shapeReadPayload("logbook", items, full), truncation);
+                }
+                case "trash": {
+                    const { items, truncation } = c.read.trash({ ...zone, limit });
+                    return truncatedResult(shapeReadPayload("trash", items, full), 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 " +
@@ -502,6 +770,7 @@ export function createThingsMcpServer(options = {}) {
         inputSchema: {
             query: z.string(),
             ...tagFilterShape,
+            ...tzShape,
             project: z
                 .string()
                 .optional()
@@ -509,18 +778,22 @@ 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"),
             all: z
                 .boolean()
                 .optional()
-                .describe("Everything, unbounded: open + logged + trashed, no row limit"),
-            limit: z.number().int().min(1).optional().describe(LIMIT_DESC),
+                .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(() => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
         // Tag-conflict AND the overdue/status-widening incompatibility both
         // derive from the shared contract (search: statusWidening = true).
         const validated = validateViewArgs("search", {
@@ -537,11 +810,10 @@ export function createThingsMcpServer(options = {}) {
         if (!validated.ok)
             return usage(validated.message);
         const limit = resolveLimit(args);
-        if (limit === "conflict")
-            return usage("pass at most one of limit / all");
         const { items, truncation } = getClient().read.search(args.query, {
             limit,
             ...validated.filter,
+            ...(args.tz !== undefined && { zone: args.tz }),
             ...(args.project !== undefined && { project: args.project }),
             ...(args.area !== undefined && { area: args.area }),
             ...(args.type !== undefined && { type: args.type }),
@@ -549,8 +821,8 @@ export function createThingsMcpServer(options = {}) {
             ...(args.trashed === true && { trashed: true }),
             ...(args.all === true && { all: true }),
         });
-        return truncatedResult(items, truncation);
-    }));
+        return truncatedResult(shapeReadPayload("search", items, args.full === true), 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, " +
@@ -559,19 +831,26 @@ export function createThingsMcpServer(options = {}) {
         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(() => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
         const limit = resolveLimit(args);
-        if (limit === "conflict")
-            return usage("pass at most one of limit / all");
         const since = new Date(args.since);
         if (Number.isNaN(since.getTime())) {
             return usage(`since is not a parseable date: ${args.since}`);
         }
-        const { items, truncation } = getClient().read.changes({ since, limit });
-        return truncatedResult(items, truncation);
-    }));
+        const { items, truncation } = getClient().read.changes({
+            since,
+            limit,
+            ...(args.tz !== undefined && { zone: args.tz }),
+        });
+        return truncatedResult(shapeReadPayload("changes", items, args.full === true), 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 " +
@@ -583,7 +862,7 @@ export function createThingsMcpServer(options = {}) {
         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));
     }));
     server.registerTool("get_project", {
         description: "One project's full contents: metadata plus its to-dos grouped under their headings. " +
@@ -593,23 +872,31 @@ export function createThingsMcpServer(options = {}) {
         inputSchema: {
             uuid: z.string().describe("Project uuid or unique name"),
             ...tagOnlyShape,
+            ...tzShape,
             overdue: z
                 .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(() => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            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));
+    }, 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. " +
+            "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. " +
@@ -617,6 +904,7 @@ export function createThingsMcpServer(options = {}) {
         inputSchema: {
             ref: z.string().describe("Area uuid or unique name"),
             ...tagOnlyShape,
+            ...tzShape,
             area_limit: z
                 .number()
                 .int()
@@ -634,24 +922,36 @@ 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(() => {
-        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)),
-            areaLimit,
-            projectLimit,
-        });
-        return groupedResult(view, grouped);
-    }));
+    }, 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), 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 " +
@@ -660,13 +960,18 @@ export function createThingsMcpServer(options = {}) {
         inputSchema: {
             kind: z.enum(["projects", "areas", "tags"]),
             ...tagOnlyShape,
+            ...tzShape,
             overdue: z
                 .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(() => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
         const c = getClient();
         // areas/tags are not dated entities and have no per-row tag list to
         // filter — overdue and the tag filters are vacuous there, rejected
@@ -688,21 +993,22 @@ 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)),
+                ...(args.tz !== undefined && { zone: args.tz }),
             })
             : args.kind === "areas"
                 ? c.read.areas()
-                : c.read.tags());
-    }));
+                : c.read.tags(), args.full === true));
+    }, args.tz));
     // ---------------------------------------------------------------- to-dos
     const whenSchema = z.string().optional().describe(WHEN_VALUES);
     server.registerTool("add_todo", {
         description: "Create a to-do and return its uuid. Optionally schedule it, set a reminder or " +
             "deadline, tag it, give it a checklist, and place it in a project or area " +
-            "(optionally under an existing heading). A reminder " +
+            "(optionally under a heading within that project). A reminder " +
             "requires when = today, evening, or a date. Adding into a completed or canceled " +
             "project reopens that project — pass acknowledge_project_reopen to confirm.",
         inputSchema: {
@@ -721,10 +1027,15 @@ export function createThingsMcpServer(options = {}) {
                 .optional()
                 .describe("Confirm adding into a completed/canceled project (this reopens it)"),
             ...createTagsShape,
+            ...tzShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
         const sugar = splitWhenSugar(args.when, args.reminder !== undefined, MCP_WHEN_LABELS);
         if (sugar.kind === "error")
             return usage(sugar.message);
@@ -743,90 +1054,228 @@ export function createThingsMcpServer(options = {}) {
             ...(args.heading !== undefined && { heading: args.heading }),
         }, writeOptions(args)));
     }));
-    server.registerTool("update_todo", {
-        description: "Update a to-do's title, notes, schedule, reminder, or deadline. " +
-            "append_notes/prepend_notes add a line to the existing notes (exclusive with " +
-            "notes). Changing the schedule keeps an existing reminder unless the call sets a " +
-            "new one. clear_reminder works while the to-do is scheduled for today or this " +
-            "evening; a reminder on a future date can only be changed, not cleared " +
-            "(re-schedule to today first). Schedule and deadline changes are not available " +
-            "for repeating to-dos.",
+    server.registerTool("update", {
+        description: "Edit an existing to-do, project, area, or tag — kind selects which. " +
+            "kind todo/project: title, notes (or append_notes/prepend_notes to add a line to the " +
+            "existing body, exclusive with notes), schedule (when), reminder/clear_reminder, and " +
+            "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 " +
+            "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.",
         inputSchema: {
-            uuid: z.string(),
-            title: z.string().optional(),
-            notes: z.string().optional().describe("Replaces the whole notes body"),
-            append_notes: z.string().optional(),
-            prepend_notes: z.string().optional(),
+            kind: z.enum(["todo", "project", "area", "tag"]),
+            uuid: z
+                .string()
+                .describe("The item to update — a to-do by uuid; a project, area, or tag also accepts a " +
+                "unique name"),
+            title: z.string().optional().describe("New title (any kind)"),
+            notes: z.string().optional().describe("todo/project: replaces the whole notes body"),
+            append_notes: z.string().optional().describe("todo/project: add a line after the notes"),
+            prepend_notes: z.string().optional().describe("todo/project: add a line before the notes"),
             when: whenSchema,
-            reminder: z.string().optional().describe(REMINDER_FORMAT),
-            clear_reminder: z.boolean().optional(),
-            deadline: z.string().optional().describe(DATE_FORMAT),
-            clear_deadline: z.boolean().optional(),
+            reminder: z.string().optional().describe(`todo/project: ${REMINDER_FORMAT}`),
+            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"),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe(`area: replace the tag set (full) — ${TAG_REF_FORMAT}`),
+            parent: z.string().optional().describe("tag: existing tag to nest under"),
+            unnest: z.boolean().optional().describe("tag: move the tag to the top level"),
+            shortcut: z.string().optional().describe("tag: keyboard shortcut character"),
+            clear_shortcut: z.boolean().optional().describe("tag: remove the keyboard shortcut"),
+            ...createTagsShape,
+            ...tzShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const notesModes = [args.notes, args.append_notes, args.prepend_notes].filter((v) => v !== undefined);
-        if (notesModes.length > 1) {
-            return usage("notes, append_notes, prepend_notes are exclusive");
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
+        const opts = writeOptions(args);
+        const c = getClient();
+        if (args.kind === "todo" || args.kind === "project") {
+            const notesModes = [args.notes, args.append_notes, args.prepend_notes].filter((v) => v !== undefined);
+            if (notesModes.length > 1) {
+                return usage("notes, append_notes, prepend_notes are exclusive");
+            }
+            if (args.reminder !== undefined && args.clear_reminder === true) {
+                return usage("pass at most one of reminder / clear_reminder");
+            }
+            if (args.deadline !== undefined && args.clear_deadline === true) {
+                return usage("pass at most one of deadline / clear_deadline");
+            }
+            if (args.kind === "todo") {
+                const sugar = splitWhenSugar(args.when, args.reminder !== undefined, MCP_WHEN_LABELS);
+                if (sugar.kind === "error")
+                    return usage(sugar.message);
+                const when = sugar.kind === "split" ? sugar.when : args.when;
+                const reminder = sugar.kind === "split" ? sugar.reminder : args.reminder;
+                return mutationResult(await c.write.updateTodo(args.uuid, {
+                    ...(args.title !== undefined && { title: args.title }),
+                    ...(args.notes !== undefined && { notes: args.notes }),
+                    ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
+                    ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
+                    ...(when !== undefined && { when: when }),
+                    ...(reminder !== undefined && { reminder }),
+                    ...(args.clear_reminder === true && { reminder: null }),
+                    ...(args.deadline !== undefined && { deadline: args.deadline }),
+                    ...(args.clear_deadline === true && { deadline: null }),
+                }, opts));
+            }
+            return mutationResult(await c.write.updateProject(args.uuid, {
+                ...(args.title !== undefined && { title: args.title }),
+                ...(args.notes !== undefined && { notes: args.notes }),
+                ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
+                ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
+                ...(args.when !== undefined && { when: args.when }),
+                ...(args.reminder !== undefined && { reminder: args.reminder }),
+                ...(args.clear_reminder === true && { reminder: null }),
+                ...(args.deadline !== undefined && { deadline: args.deadline }),
+                ...(args.clear_deadline === true && { deadline: null }),
+            }, opts));
+        }
+        if (args.kind === "area") {
+            if (args.title === undefined && args.tags === undefined) {
+                return usage("kind area requires title and/or tags");
+            }
+            return mutationResult(await c.write.updateArea(args.uuid, {
+                ...(args.title !== undefined && { title: args.title }),
+                ...(args.tags !== undefined && { tags: args.tags }),
+            }, opts));
+        }
+        // kind tag
+        if (args.title === undefined &&
+            args.parent === undefined &&
+            args.unnest === undefined &&
+            args.shortcut === undefined &&
+            args.clear_shortcut === undefined) {
+            return usage("kind tag requires title, parent, unnest, shortcut, and/or clear_shortcut");
         }
-        if (args.reminder !== undefined && args.clear_reminder === true) {
-            return usage("pass at most one of reminder / clear_reminder");
+        if (args.parent !== undefined && args.unnest === true) {
+            return usage("parent and unnest are exclusive");
         }
-        if (args.deadline !== undefined && args.clear_deadline === true) {
-            return usage("pass at most one of deadline / clear_deadline");
+        if (args.shortcut !== undefined && args.clear_shortcut === true) {
+            return usage("shortcut and clear_shortcut are exclusive");
         }
-        const sugar = splitWhenSugar(args.when, args.reminder !== undefined, MCP_WHEN_LABELS);
-        if (sugar.kind === "error")
-            return usage(sugar.message);
-        const when = sugar.kind === "split" ? sugar.when : args.when;
-        const reminder = sugar.kind === "split" ? sugar.reminder : args.reminder;
-        return mutationResult(await getClient().write.updateTodo(args.uuid, {
+        return mutationResult(await c.write.updateTag(args.uuid, {
             ...(args.title !== undefined && { title: args.title }),
-            ...(args.notes !== undefined && { notes: args.notes }),
-            ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
-            ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
-            ...(when !== undefined && { when: when }),
-            ...(reminder !== undefined && { reminder }),
-            ...(args.clear_reminder === true && { reminder: null }),
-            ...(args.deadline !== undefined && { deadline: args.deadline }),
-            ...(args.clear_deadline === true && { deadline: null }),
-        }, writeOptions(args)));
+            ...(args.parent !== undefined && { parent: args.parent }),
+            ...(args.unnest === true && { unnest: true }),
+            ...(args.shortcut !== undefined && { shortcut: args.shortcut }),
+            ...(args.clear_shortcut === true && { clearShortcut: true }),
+        }, opts));
     }));
-    server.registerTool("set_todo_status", {
-        description: "Set a to-do's status: completed, canceled, or open (reopening a " +
-            "completed/canceled to-do). Not available for repeating to-dos.",
+    server.registerTool("set_status", {
+        description: "Set a to-do's or project's status (scope selects which): completed, canceled, or open " +
+            "(reopening a completed/canceled item). Not available for repeating to-dos. " +
+            "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.",
         inputSchema: {
-            uuid: z.string(),
+            scope: z.enum(["todo", "project"]),
+            uuid: z
+                .string()
+                .describe("The item — a to-do by uuid; a project also accepts a unique name"),
             status: z.enum(["completed", "canceled", "open"]),
+            children: z
+                .enum(["require-resolved", "auto-complete", "auto-cancel"])
+                .optional()
+                .describe("scope project, completed/canceled: what to do with the project's open to-dos"),
+            restore_children: z
+                .boolean()
+                .optional()
+                .describe("scope project, open only: also reopen the to-dos resolved with the project"),
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
         const c = getClient();
         const opts = writeOptions(args);
-        return mutationResult(args.status === "completed"
-            ? await c.write.completeTodo(args.uuid, opts)
-            : args.status === "canceled"
-                ? await c.write.cancelTodo(args.uuid, opts)
-                : await c.write.reopenTodo(args.uuid, opts));
+        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)
+                : args.status === "canceled"
+                    ? await c.write.cancelTodo(args.uuid, opts)
+                    : await c.write.reopenTodo(args.uuid, opts));
+        }
+        // scope project
+        if (args.status !== "open" && args.restore_children !== undefined) {
+            return usage("restore_children applies only to status 'open'");
+        }
+        if (args.status === "completed") {
+            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));
+        }
+        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));
+        }
+        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 }),
+        });
+        return outcome.project.kind === "ok" || outcome.project.kind === "dry-run"
+            ? jsonResult(outcome)
+            : mutationResult(outcome.project);
     }));
     server.registerTool("move_todo", {
-        description: "Move a to-do. Pass exactly one destination: a project and/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("Remove the project/area/heading assignment, keeping the schedule"),
+                .describe("Leave the heading but stay in the current project (unheaded block)"),
+            loose: z
+                .boolean()
+                .optional()
+                .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()
@@ -835,21 +1284,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 " +
@@ -861,6 +1326,7 @@ export function createThingsMcpServer(options = {}) {
             mode: z.enum(["replace", "add"]).optional().describe("Default: replace"),
             ...createTagsShape,
             ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
@@ -965,23 +1431,56 @@ export function createThingsMcpServer(options = {}) {
         return mutationResult(await c.write.editChecklist(args.uuid, edit, writeOptions(args)));
     }));
     // ------------------------------------------------- to-dos AND projects
-    server.registerTool("delete_item", {
-        description: "Move a to-do or project to the Trash (recoverable via restore_item until the " +
-            "Trash is emptied). Deleting a project sends its to-dos to the Trash with it. Not " +
-            "available for repeating to-dos.",
-        inputSchema: { uuid: z.string(), ...dryRunShape },
+    server.registerTool("delete", {
+        description: "Delete a to-do/project (kind item), an area, or a tag — kind selects which. " +
+            "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; 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: {
+            kind: z.enum(["item", "area", "tag"]),
+            uuid: z
+                .string()
+                .describe("The target — an item by uuid; an area or tag also accepts a unique name"),
+            dangerously_permanent: z
+                .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 () => {
         const c = getClient();
-        return mutationResult(itemType(args.uuid) === "to-do"
-            ? await c.write.deleteTodo(args.uuid, writeOptions(args))
-            : await c.write.deleteProject(args.uuid, writeOptions(args)));
+        const opts = writeOptions(args);
+        switch (args.kind) {
+            case "item":
+                return mutationResult(itemType(args.uuid) === "to-do"
+                    ? await c.write.deleteTodo(args.uuid, opts)
+                    : await c.write.deleteProject(args.uuid, opts));
+            case "area":
+                return mutationResult(await c.write.deleteArea(args.uuid, opts));
+            case "tag":
+                return mutationResult(await c.write.deleteTag(args.uuid, opts));
+        }
     }));
     server.registerTool("restore_item", {
         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();
@@ -998,6 +1497,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, {
@@ -1014,6 +1514,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({
@@ -1022,78 +1523,192 @@ export function createThingsMcpServer(options = {}) {
         ...(args.creation_date !== undefined && { creationDate: args.creation_date }),
         ...(args.notes !== undefined && { notes: args.notes }),
     }, writeOptions(args)))));
-    server.registerTool("create_heading", {
-        description: "Create a heading inside an existing project; its uuid is returned. The project " +
-            "must name an existing project. Uses the Things proxy shortcuts — set them up once " +
-            "with `things setup shortcuts`.",
-        inputSchema: {
-            project: z.string().describe(`Existing project (${REF_FORMAT})`),
-            title: z.string(),
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.createHeading(containerRef(args.project), args.title, 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 " +
-            "to-do); otherwise a non-repeating dated to-do falls back to a URL re-schedule that " +
-            "briefly moves it to Today and back. Reversible with the undo tool.",
-        inputSchema: { uuid: z.string(), ...dryRunShape },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.clearReminder(args.uuid, writeOptions(args)))));
-    server.registerTool("rename_heading", {
-        description: "Rename a heading in place (works on archived headings too).",
-        inputSchema: { uuid: z.string(), title: z.string(), ...dryRunShape },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.renameHeading(args.uuid, args.title, writeOptions(args)))));
-    server.registerTool("archive_heading", {
-        description: "Archive a heading — it leaves the active project view (reversible with " +
-            "unarchive_heading). The preferred way to retire a heading: row deletion only " +
-            "exists in the app's UI / Shortcuts behind a per-run consent dialog. With open " +
-            "children the children policy is required: complete or cancel resolve them with " +
-            "the heading in one cascade; reparent moves them to the project root first, " +
-            "keeping them open (a compound sequence that undo reverses as one unit).",
+    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 " +
+            "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: {
-            uuid: z.string(),
+            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(`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("Required when the heading has open children"),
+                .describe("archive_heading: required when the heading has open children"),
+            restore_children: z
+                .boolean()
+                .optional()
+                .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,
         },
-        annotations: NON_DESTRUCTIVE,
+        annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const r = await getClient().write.archiveHeading(args.uuid, args.children !== undefined ? { children: args.children } : {}, writeOptions(args));
-        return r.heading.kind === "ok" || r.heading.kind === "dry-run"
-            ? jsonResult(r)
-            : mutationResult(r.heading);
+        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 "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.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');
+                }
+                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_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 "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 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("unarchive_heading", {
-        description: "Un-archive a heading. restore_children also reopens the children the archive " +
-            "cascade resolved with it (matching resolution timestamps; someday state " +
-            "survives). Children resolved at other times are never touched.",
+    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(),
-            restore_children: z.boolean().optional(),
+            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 " +
+            "to-do); otherwise a non-repeating dated to-do falls back to a URL re-schedule that " +
+            "briefly moves it to Today and back. Reversible with the undo tool.",
+        inputSchema: { uuid: z.string(), ...dryRunShape },
         annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        const r = await getClient().write.unarchiveHeading(args.uuid, args.restore_children === true ? { restoreChildren: true } : {}, writeOptions(args));
-        return r.heading.kind === "ok" || r.heading.kind === "dry-run"
-            ? jsonResult(r)
-            : mutationResult(r.heading);
-    }));
+    }, async (args) => guard(async () => mutationResult(await getClient().write.clearReminder(args.uuid, writeOptions(args)))));
     // -------------------------------------------- GUI-driven (Accessibility)
-    const driveGuiShape = {
-        dangerously_drive_gui: z
-            .boolean()
-            .optional()
-            .describe("Required: this drives the local Things app through its accessibility interface to " +
-            "make a change the app offers nowhere else. It briefly interacts with the app's UI " +
-            "on the machine running this server, and must be turned on first with `things config " +
-            "set ui-enabled true`. Intended for a dedicated always-on Mac."),
-    };
     const WEEKDAY_ENUM = z.enum([
         "sunday",
         "monday",
@@ -1103,7 +1718,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"),
@@ -1171,182 +1786,114 @@ export function createThingsMcpServer(options = {}) {
             fields.startDaysEarlier = a.start_days_earlier;
         return fields;
     };
-    server.registerTool("make_repeating", {
-        description: "Turn a plain to-do into a repeating one. This REPLACES the to-do with a new recurring " +
-            "series — the original disappears and a fresh repeating item takes its place, so it " +
-            "cannot be undone. Set the frequency and interval, and optionally the weekday set, " +
-            "monthly/yearly day, end bound, reminders, or deadline. Returns the new item's uuid.",
-        inputSchema: {
-            uuid: z.string().describe("The to-do to make repeating"),
-            ...repeatRuleShape,
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.run("todo.make-repeating", {
-        uuid: args.uuid,
-        frequency: args.frequency,
-        interval: args.interval,
-        ...repeatExtras(args, args.frequency),
-    }, writeOptions(args)))));
-    server.registerTool("reschedule_repeat", {
-        description: "Change a repeating to-do's rule in place, keeping the same item. Set the frequency and " +
-            "interval, and optionally the weekday set, monthly/yearly day, end bound, reminders, or " +
-            "deadline. This can be undone — it restores the previous rule.",
+    server.registerTool("repeat", {
+        description: "Manage recurrence on a to-do or project (scope) by driving the local Things app's " +
+            "interface — every action needs dangerously_drive_gui. action start: turn a plain item " +
+            "into a repeating one — this REPLACES it with a new series and cannot be undone (give " +
+            "frequency + interval and optionally the weekday set, monthly/yearly day, end bound, " +
+            "reminder, or per-occurrence deadline); returns a repeating block with instanceUuid (the " +
+            "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 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: {
-            uuid: z.string().describe("The repeating to-do to reschedule"),
-            ...repeatRuleShape,
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.run("todo.reschedule-repeat", {
-        uuid: args.uuid,
-        frequency: args.frequency,
-        interval: args.interval,
-        ...repeatExtras(args, args.frequency),
-    }, writeOptions(args)))));
-    server.registerTool("set_repeat_state", {
-        description: "Pause or resume a repeating to-do. 'pause' stops it spawning new occurrences but keeps " +
-            "its rule; 'resume' starts it again. The two are inverses of each other.",
-        inputSchema: {
-            uuid: z.string().describe("The repeating to-do"),
-            state: z.enum(["pause", "resume"]),
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        const op = args.state === "pause" ? "todo.pause-repeat" : "todo.resume-repeat";
-        return mutationResult(await getClient().write.run(op, { uuid: args.uuid }, writeOptions(args)));
-    }));
-    server.registerTool("reschedule_project_repeat", {
-        description: "Change a repeating project's rule in place, keeping the same project. Set the frequency " +
-            "and interval, and optionally the weekday set, monthly/yearly day, end bound, reminders, " +
-            "or deadline. This can be undone — it restores the previous rule.",
-        inputSchema: {
-            uuid: z.string().describe(`The repeating project to reschedule (${REF_FORMAT})`),
-            ...repeatRuleShape,
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.run("project.reschedule-repeat", {
-        uuid: args.uuid,
-        frequency: args.frequency,
-        interval: args.interval,
-        ...repeatExtras(args, args.frequency),
-    }, writeOptions(args)))));
-    server.registerTool("set_project_repeat_state", {
-        description: "Pause or resume a repeating project. 'pause' stops it spawning new occurrences but keeps " +
-            "its rule; 'resume' starts it again. The two are inverses of each other.",
-        inputSchema: {
-            uuid: z.string().describe(`The repeating project (${REF_FORMAT})`),
-            state: z.enum(["pause", "resume"]),
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        const op = args.state === "pause" ? "project.pause-repeat" : "project.resume-repeat";
-        return mutationResult(await getClient().write.run(op, { uuid: args.uuid }, writeOptions(args)));
-    }));
-    server.registerTool("reorder_area", {
-        description: "Move an area to a new position in the area order. Give the area plus exactly one " +
-            "destination: before/after another area, or position first/last. The move is made by " +
-            "driving the Things window with the pointer — the app comes to the front and the " +
-            "sidebar may scroll while the area is dragged; the area's projects and to-dos are " +
-            "untouched. Area references are a uuid or a unique name.",
-        inputSchema: {
-            target: z.string().describe("The area to move (uuid or unique name)"),
-            before: z
+            scope: z.enum(["todo", "project"]),
+            action: z.enum(["start", "reschedule", "pause", "resume", "add"]),
+            uuid: z
                 .string()
                 .optional()
-                .describe("Place it immediately above this area (uuid or unique name)"),
-            after: z
+                .describe("start/reschedule/pause/resume: the item (a project also accepts a unique name)"),
+            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("Place it immediately below this area (uuid or unique name)"),
-            position: z
-                .enum(["first", "last"])
+                .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("Move it to the top or bottom of the area list"),
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => 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)))));
-    server.registerTool("make_project_repeating", {
-        description: "Turn an existing project into a repeating one. This REPLACES the project with a new " +
-            "recurring series — the original disappears and a fresh repeating project takes its place " +
-            "(its area is kept), so it cannot be undone. An area-less project scheduled for Anytime is " +
-            "moved to Someday first (a cleanup-free intermediate step, shown by dry_run). Set the " +
-            "frequency and interval, and optionally the weekday set, monthly/yearly day, end bound, " +
-            "reminders, or deadline. Returns the new project's uuid.",
-        inputSchema: {
-            uuid: z.string().describe(`The project to make repeating (${REF_FORMAT})`),
-            ...repeatRuleShape,
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.makeRepeatingProject(args.uuid, {
-        frequency: args.frequency,
-        interval: args.interval,
-        ...repeatExtras(args, args.frequency),
-    }, writeOptions(args)))));
-    server.registerTool("create_repeating_project", {
-        description: "Create a project and make it repeating in one call. TWO operations: the project is " +
-            "created first and PERSISTS even if the make-repeating step refuses; then it is promoted " +
-            "(which drives the GUI). Give an area to place it, or omit it to create in Someday. Only a " +
-            "frequency and an interval are supported. Returns the new repeating project's uuid.",
-        inputSchema: {
-            title: z.string(),
-            notes: z.string().optional(),
-            area: z.string().optional().describe(`Destination area (${REF_FORMAT})`),
-            deadline: z.string().optional().describe(DATE_FORMAT),
-            todos: z.array(z.string()).optional().describe("Initial child to-do titles"),
-            ...baseRepeatShape,
-            ...driveGuiShape,
-            ...dryRunShape,
-        },
-        annotations: DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.createRepeatingProject({
-        title: args.title,
-        ...(args.notes !== undefined && { notes: args.notes }),
-        ...(args.area !== undefined && { area: containerRef(args.area) }),
-        ...(args.deadline !== undefined && { deadline: args.deadline }),
-        ...(args.todos !== undefined && { todos: args.todos }),
-        frequency: args.frequency,
-        interval: args.interval,
-    }, writeOptions(args)))));
-    server.registerTool("convert_to_project", {
-        description: "Convert a to-do or a heading into a project. This REPLACES the original with a new " +
-            "project (a converted to-do keeps its notes; a converted heading is promoted alongside " +
-            "its project and its to-dos move under the new project). The original is gone and this " +
-            "cannot be undone. Returns the new project's uuid.",
-        inputSchema: {
-            uuid: z.string().describe("The to-do or heading to convert"),
+                .describe("start/reschedule/add: how often it repeats"),
+            interval: z
+                .number()
+                .int()
+                .min(1)
+                .max(99)
+                .optional()
+                .describe("start/reschedule/add: every N units (1–99)"),
+            after_completion: repeatRuleShape.after_completion,
+            weekdays: repeatRuleShape.weekdays,
+            monthly_day: repeatRuleShape.monthly_day,
+            monthly_weekday: repeatRuleShape.monthly_weekday,
+            monthly_ordinal: repeatRuleShape.monthly_ordinal,
+            yearly_month: repeatRuleShape.yearly_month,
+            ends_after: repeatRuleShape.ends_after,
+            ends_on: repeatRuleShape.ends_on,
+            reminder: repeatRuleShape.reminder,
+            deadline: repeatRuleShape.deadline,
+            start_days_earlier: repeatRuleShape.start_days_earlier,
             ...driveGuiShape,
             ...dryRunShape,
         },
         annotations: DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const item = getClient().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 getClient().write.run(op, { uuid: args.uuid }, writeOptions(args)));
+        const c = getClient();
+        const opts = writeOptions(args);
+        const { frequency, interval } = args;
+        if (args.action === "add") {
+            if (args.scope !== "project")
+                return usage('action "add" requires scope "project"');
+            if (args.title === undefined)
+                return usage('action "add" requires title');
+            if (frequency === undefined || interval === undefined) {
+                return usage('action "add" requires frequency and interval');
+            }
+            return mutationResult(await c.write.addRepeatingProject({
+                title: args.title,
+                ...(args.notes !== undefined && { notes: args.notes }),
+                ...(args.area !== undefined && { area: containerRef(args.area) }),
+                ...(args.project_deadline !== undefined && { deadline: args.project_deadline }),
+                ...(args.todos !== undefined && { todos: args.todos }),
+                frequency,
+                interval,
+            }, opts));
+        }
+        if (args.uuid === undefined)
+            return usage(`action "${args.action}" requires uuid`);
+        if (args.action === "pause" || args.action === "resume") {
+            const op = args.scope === "todo"
+                ? args.action === "pause"
+                    ? "todo.pause-repeat"
+                    : "todo.resume-repeat"
+                : args.action === "pause"
+                    ? "project.pause-repeat"
+                    : "project.resume-repeat";
+            return mutationResult(await c.write.run(op, { uuid: args.uuid }, opts));
+        }
+        // start | reschedule
+        if (frequency === undefined || interval === undefined) {
+            return usage(`action "${args.action}" requires frequency and interval`);
+        }
+        const extras = repeatExtras(args, frequency);
+        if (args.scope === "todo") {
+            const op = args.action === "start" ? "todo.make-repeating" : "todo.reschedule-repeat";
+            return mutationResult(await c.write.run(op, { uuid: args.uuid, frequency, interval, ...extras }, opts));
+        }
+        // scope project
+        if (args.action === "reschedule") {
+            return mutationResult(await c.write.run("project.reschedule-repeat", { uuid: args.uuid, frequency, interval, ...extras }, opts));
+        }
+        // scope project, action start → the dedicated make-repeating method
+        return mutationResult(await c.write.makeRepeatingProject(args.uuid, { frequency, interval, ...extras }, opts));
     }));
     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();
@@ -1365,127 +1912,56 @@ 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"),
+            ...tzShape,
             ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.addProject({
-        title: args.title,
-        ...(args.notes !== undefined && { notes: args.notes }),
-        ...(args.area !== undefined && { area: containerRef(args.area) }),
-        ...(args.when !== undefined && { when: args.when }),
-        ...(args.deadline !== undefined && { deadline: args.deadline }),
-        ...(args.todos !== undefined && { todos: args.todos }),
-    }, writeOptions(args)))));
-    server.registerTool("update_project", {
-        description: "Update a project's title, notes, schedule, reminder, or deadline. " +
-            "append_notes/prepend_notes add a line to the existing notes (exclusive with notes). " +
-            "Changing the schedule keeps an existing reminder unless the call sets a new one. " +
-            "clear_reminder works while the project is scheduled for today or this evening; a " +
-            "reminder on a future date can only be changed, not cleared.",
-        inputSchema: {
-            uuid: z.string().describe(`The project to update (${REF_FORMAT})`),
-            title: z.string().optional(),
-            notes: z.string().optional().describe("Replaces the whole notes body"),
-            append_notes: z.string().optional(),
-            prepend_notes: z.string().optional(),
-            when: whenSchema,
-            reminder: z.string().optional().describe(REMINDER_FORMAT),
-            clear_reminder: z.boolean().optional(),
-            deadline: z.string().optional().describe(DATE_FORMAT),
-            clear_deadline: z.boolean().optional(),
-            ...dryRunShape,
+            ...opIdShape,
         },
         annotations: NON_DESTRUCTIVE,
     }, async (args) => guard(async () => {
-        const notesModes = [args.notes, args.append_notes, args.prepend_notes].filter((v) => v !== undefined);
-        if (notesModes.length > 1) {
-            return usage("notes, append_notes, prepend_notes are exclusive");
-        }
-        if (args.reminder !== undefined && args.clear_reminder === true) {
-            return usage("pass at most one of reminder / clear_reminder");
-        }
-        if (args.deadline !== undefined && args.clear_deadline === true) {
-            return usage("pass at most one of deadline / clear_deadline");
-        }
-        return mutationResult(await getClient().write.updateProject(args.uuid, {
-            ...(args.title !== undefined && { title: args.title }),
+        const badZone = badTz(args.tz);
+        if (badZone !== null)
+            return badZone;
+        return mutationResult(await getClient().write.addProject({
+            title: args.title,
             ...(args.notes !== undefined && { notes: args.notes }),
-            ...(args.append_notes !== undefined && { appendNotes: args.append_notes }),
-            ...(args.prepend_notes !== undefined && { prependNotes: args.prepend_notes }),
+            ...(args.area !== undefined && { area: containerRef(args.area) }),
             ...(args.when !== undefined && { when: args.when }),
-            ...(args.reminder !== undefined && { reminder: args.reminder }),
-            ...(args.clear_reminder === true && { reminder: null }),
             ...(args.deadline !== undefined && { deadline: args.deadline }),
-            ...(args.clear_deadline === true && { deadline: null }),
+            ...(args.todos !== undefined && { todos: args.todos }),
         }, writeOptions(args)));
     }));
-    server.registerTool("set_project_status", {
-        description: "Complete, cancel, or reopen a 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). status 'open' reopens a completed or " +
-            "canceled project; its children stay completed/canceled unless restore_children " +
-            "also reopens the ones that were resolved together with the project.",
-        inputSchema: {
-            uuid: z.string().describe(`The project (${REF_FORMAT})`),
-            status: z.enum(["completed", "canceled", "open"]),
-            children: z
-                .enum(["require-resolved", "auto-complete", "auto-cancel"])
-                .optional()
-                .describe("Required for completed/canceled: what to do with the project's open to-dos"),
-            restore_children: z
-                .boolean()
-                .optional()
-                .describe("open only: also reopen the to-dos that were resolved with the project"),
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        const c = getClient();
-        if (args.status !== "open" && args.restore_children !== undefined) {
-            return usage("restore_children applies only to status 'open'");
-        }
-        if (args.status === "completed") {
-            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 }, writeOptions(args)));
-        }
-        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 }, writeOptions(args)));
-        }
-        if (args.children !== undefined) {
-            return usage("children applies only to status 'completed' or 'canceled'");
-        }
-        const outcome = await c.write.reopenProject(args.uuid, {
-            ...writeOptions(args),
-            ...(args.restore_children === true && { restoreChildren: true }),
-        });
-        return outcome.project.kind === "ok" || outcome.project.kind === "dry-run"
-            ? jsonResult(outcome)
-            : mutationResult(outcome.project);
-    }));
     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", {
@@ -1495,46 +1971,10 @@ 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)))));
-    server.registerTool("update_area", {
-        description: "Rename an area and/or replace its tags (the full set). Tags must exist unless " +
-            "create_tags is set.",
-        inputSchema: {
-            target: z.string().describe(`Area to update (${REF_FORMAT})`),
-            title: z.string().optional().describe("New name"),
-            tags: z
-                .array(z.string())
-                .optional()
-                .describe(`Tags (full replacement) — ${TAG_REF_FORMAT}`),
-            ...createTagsShape,
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        if (args.title === undefined && args.tags === undefined) {
-            return usage("pass title and/or tags");
-        }
-        return mutationResult(await getClient().write.updateArea(args.target, {
-            ...(args.title !== undefined && { title: args.title }),
-            ...(args.tags !== undefined && { tags: args.tags }),
-        }, writeOptions(args)));
-    }));
-    server.registerTool("delete_area", {
-        description: "Delete an area PERMANENTLY — areas do not go to the Trash, so this cannot be " +
-            "undone; requires dangerously_permanent. The area's to-dos move to the Trash; its " +
-            "projects remain, no longer assigned to any area.",
-        inputSchema: {
-            target: z.string().describe(`Area to delete (${REF_FORMAT})`),
-            dangerously_permanent: z
-                .boolean()
-                .optional()
-                .describe("Confirm permanent, unrecoverable deletion"),
-            ...dryRunShape,
-        },
-        annotations: DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.deleteArea(args.target, writeOptions(args)))));
     // ------------------------------------------------------------------ tags
     server.registerTool("add_tag", {
         description: "Create a tag, optionally nested under an existing parent tag.",
@@ -1542,64 +1982,10 @@ 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)))));
-    server.registerTool("update_tag", {
-        description: "Rename a tag (existing assignments follow the rename), nest it under another " +
-            "existing tag, un-nest it to the top level, and set or clear its keyboard shortcut. " +
-            "parent and unnest are exclusive; shortcut and clear_shortcut are exclusive.",
-        inputSchema: {
-            target: z.string().describe(`Tag to update (${REF_FORMAT})`),
-            title: z.string().optional().describe("New name"),
-            parent: z.string().optional().describe("Existing tag to nest under"),
-            unnest: z.boolean().optional().describe("Move the tag to the top level"),
-            shortcut: z.string().optional().describe("Keyboard shortcut character"),
-            clear_shortcut: z.boolean().optional().describe("Remove the keyboard shortcut"),
-            ...dryRunShape,
-        },
-        annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => {
-        if (args.title === undefined &&
-            args.parent === undefined &&
-            args.unnest === undefined &&
-            args.shortcut === undefined &&
-            args.clear_shortcut === undefined) {
-            return usage("pass title, parent, unnest, shortcut, and/or clear_shortcut");
-        }
-        if (args.parent !== undefined && args.unnest === true) {
-            return usage("parent and unnest are exclusive");
-        }
-        if (args.shortcut !== undefined && args.clear_shortcut === true) {
-            return usage("shortcut and clear_shortcut are exclusive");
-        }
-        return mutationResult(await getClient().write.updateTag(args.target, {
-            ...(args.title !== undefined && { title: args.title }),
-            ...(args.parent !== undefined && { parent: args.parent }),
-            ...(args.unnest === true && { unnest: true }),
-            ...(args.shortcut !== undefined && { shortcut: args.shortcut }),
-            ...(args.clear_shortcut === true && { clearShortcut: true }),
-        }, writeOptions(args)));
-    }));
-    server.registerTool("delete_tag", {
-        description: "Delete a tag PERMANENTLY — tags do not go to the Trash, so this cannot be undone; " +
-            "requires dangerously_permanent. The tag is removed from every item. If the tag " +
-            "has nested child tags they are ALL permanently deleted with it — pass " +
-            "acknowledge_tag_subtree to confirm.",
-        inputSchema: {
-            target: z.string().describe(`Tag to delete (${REF_FORMAT})`),
-            dangerously_permanent: z
-                .boolean()
-                .optional()
-                .describe("Confirm permanent, unrecoverable deletion"),
-            acknowledge_tag_subtree: z
-                .boolean()
-                .optional()
-                .describe("Confirm permanent deletion of ALL nested child tags too"),
-            ...dryRunShape,
-        },
-        annotations: DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.deleteTag(args.target, writeOptions(args)))));
     // -------------------------------------------------- generic + discovery
     server.registerTool("run_operation", {
         description: "Run any cataloged operation by kind — the generic entry for operations without a " +
@@ -1620,25 +2006,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(),
             }))
@@ -1659,58 +2068,122 @@ 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.",
+        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). 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",
-            ]),
-            container: 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(`Project/area (${REF_FORMAT}) — required for those scopes`),
-            uuids: z.array(z.string()).describe("Desired order, top first (may be a subset)"),
-            strategy: z.enum(["native", "bounce"]).optional(),
+                .describe("Disambiguate the axis of a Today/This Evening set: today | evening | anytime | " +
+                "someday | inbox, or a project/area/heading ref (uuid or unique title)"),
             ...dryRunShape,
         },
         annotations: NON_DESTRUCTIVE,
-    }, async (args) => guard(async () => mutationResult(await getClient().write.reorder({
-        scope: args.scope,
-        uuids: args.uuids,
-        ...(args.container !== undefined && { container: containerRef(args.container) }),
-        ...(args.strategy !== undefined && { strategy: args.strategy }),
-    }, writeOptions(args)))));
+    }, 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(`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)));
+    }));
     server.registerTool("undo", {
         description: "Undo the last N changes, newest first (changes made directly in the Things app " +
             "cannot be undone here). By default this undoes only changes made through THIS " +