things-api 0.15.0 → 0.16.0

package/skills/things-cli/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: things-cli
 description: Read and manage a user's tasks in the Things 3 app (macOS) through the `things` CLI — list views like Today/Inbox/Upcoming, search, and create, edit, schedule, complete, move, or organize to-dos, projects, areas, headings, and tags. Use whenever the user asks about their tasks, to-dos, projects, or anything in Things.
-version: 0.15.0
+version: 0.16.0
 ---
 
 # Things CLI
@@ -45,6 +45,7 @@ These hold regardless of the binary version; see [references/contracts.md](refer
 - **JSON envelope**: every `--json` response is `{ apiVersion, ok, kind, data, meta }`. Read results from `.data` (`.data.items`/`.data.sections`/`.data.item`/`.data.view`/`.data.children` per `kind`; `today` is `.data.children.{today,evening}.items` with its count on `meta.counts`; the `logbook` view carries the log-move cadence on `meta.logging = {cadence, lastLoggedAt?}` — CC's Settings words `Immediately|Daily|Manually`, `lastLoggedAt` under Daily and Manually), never `.items`; UUIDs are `.uuid`, not `.id`. Check `meta.truncation.truncated` before concluding "no match" or "that's everything". List/search rows are compact summaries whose `tags` may be incomplete — use `things show <ref> --json` for effective tags, checklist, notes, and placement.
 - **Exit codes**: `0` landed and checked · `2` usage · `3` verify-failed · `4` blocked · `5` drift-blocked · `6` unsupported · `7` environment (`1` is an internal bug). Nonzero means the change did NOT stick; the message names the fix.
 - **Previews, undo & idempotency**: `--dry-run` is universal — accepted by every command, it guarantees nothing changes: on a read it returns the normal output unchanged, on a write it shows the exact plan without executing; `things undo` reverses recent changes made through this tool (each reversible write returns an `undoToken`); a single mutation may carry `--op-id <key>` so an ambiguous resubmission is recognized as already applied (the variadic `move`/`reorder` refuse it — use `things batch` with a per-line `opId`).
+- **Timeline-silent mutations** (`--preserve-modified`, MCP `preserve_modified`): a universal write flag that keeps a change off the modification-date timeline. Some writes (applying/removing a tag, editing a field, resolving an item) re-stamp each edited item's modification date — the key `things changes --since <moment>` and any watch/sync process sort on. `--preserve-modified` captures each PRE-EXISTING edited item's modification date before the write and restores it (to the whole second) afterward, so the edit does not surface as a new change. It is the enabler for a mass retro-tag or bulk cleanup that must not flood `changes`. A pure create (`add`) is a no-op; the restore is best-effort (a failure is reported per item, the change itself stands) and the result carries `preservedModified: <n>`. **Safe against a synced (Things Cloud) store** — the restored modification date syncs to the other devices and survives the round-trip, so the item stays off the timeline on every device (SYNC2B); the only edge is a genuinely concurrent edit to the same item on another device, which re-dates it via Things Cloud's per-attribute merge (fails safe — the edit resurfaces, never silently hidden).
 - **Preconditions**: referenced containers and tags must already exist — create nested structures outside-in and reuse each returned UUID.
 - If the user requests a JSON reply schema, return exactly that object after the read or checked write.
 
@@ -54,7 +55,7 @@ Views and lookups — pass `--json` whenever you will act on the output: `things
 
 ## Writing
 
-Namespaced verb families — run `things <group> --help` for the verbs and `things <group> <verb> --help` for exact flags: `things todo …` (add/update/complete/cancel/reopen/move/delete/restore/tags/checklist/make-repeating), `things project …` (add/update/move/complete/… plus the heading verbs), `things area …`, `things tag …`, plus `things batch` (JSONL — chain created uuids across lines with `tempId`/`$ref`, retry safely with `opId`, undo the whole run with its `undoToken`), `things undo`, `things reorder`, and `things log-now` (move completed items into the Logbook now; reports how many moved, a clean no-op when none are pending, and cannot be undone).
+Namespaced verb families — run `things <group> --help` for the verbs and `things <group> <verb> --help` for exact flags: `things todo …` (add/update/complete/cancel/reopen/move/delete/restore/tags/checklist/make-repeating/add-repeating/clone), `things project …` (add/update/move/complete/… plus add-repeating/make-repeating, clone and the heading verbs), `things area …`, `things tag …`, plus `things batch` (JSONL — chain created uuids across lines with `tempId`/`$ref`, retry safely with `opId`, undo the whole run with its `undoToken`), `things undo`, `things reorder`, and `things log-now` (move completed items into the Logbook now; reports how many moved, a clean no-op when none are pending, and cannot be undone).
 
 **Scheduling is an update, not a move**: `things todo update <ref> --when today|evening|anytime|someday|YYYY-MM-DD` schedules or parks an item; `move` changes its CONTAINER only.
 

package/skills/things-cli/references/banner.md

@@ -11,7 +11,7 @@ When items arrive in Today on their own, Things shows a yellow "You have N new t
 - `provisional` reuses the same Today markers `when` does, so it can never disagree with the ★ the row would render.
 - **The pip is Today-view-only.** In the app's Anytime list the same provisional row shows the ordinary Today ★ and no pip. So the TTY renders `•` only in `things today` (Today and This Evening sections); the wire `provisional` field is present on every surface, but the `•` glyph is not.
 
-**A provisional row is already a full Today member** — visible, sortable, and mutable through every ordinary write. Model it as `stage: "anytime"` + `when: "today"` + `provisional: true`: at pull time the app re-files a deadline-pulled Inbox/Someday row into Anytime (R13/BANNER1b), so it is EXCLUDED from the Inbox/Someday lists and INCLUDED in Anytime even though the user never chose to leave those buckets — the derived stage reflects where the app actually shows it.
+**A provisional row is already a full Today member** — visible, sortable, and mutable through every ordinary write. Model it as `stage: "anytime"` + `when: "today"` + `provisional: true`: at pull time the app re-files a deadline-pulled Inbox/Someday row into Anytime (RS8/BANNER1b), so it is EXCLUDED from the Inbox/Someday lists and INCLUDED in Anytime even though the user never chose to leave those buckets — the derived stage reflects where the app actually shows it.
 
 ## There is no `today ok` — dismissing the banner is a data mutation
 

package/skills/things-cli/references/contracts.md

@@ -29,13 +29,19 @@ A nonzero exit is informative, not a dead end — it means the write did not sil
 ## Safety & recovery
 
 - `--dry-run` previews the exact plan (operation, target, expected change) for ANY write without executing — use it for anything destructive, bulk, or unfamiliar.
-- `things undo` reverses recent changes made through this tool (its own audit trail, not arbitrary app history). Prefer a targeted fix when you know it; undo is the safety net.
+- `things undo` reverses recent changes made through this tool (its own audit trail, not arbitrary app history). Prefer a targeted fix when you know it; undo is the safety net. `--last N` / `--by <actor>` select the N newest NOT-YET-undone changes: an already-undone change is SKIPPED, so running `undo --last N` again walks progressively DEEPER into history (it does not re-select what you just undid). An IRREVERSIBLE change (a permanent delete, or one whose prior state is unknown) is the exception — it is NOT skipped: it still counts toward N and is reported every pass, so you always SEE it rather than silently reaching past it to undo something older. Use `--txn <undoToken>` to target one exact change surgically (immune to interleaving; re-running it on an already-undone change reports that loudly).
 - To-do/project deletes are TRASHES: `todo delete` moves to Trash and is restorable (`todo restore`). Emptying the trash is permanent and requires explicit user intent — don't do it unless asked. AREAS are the exception — an area does not go to the Trash, so deleting one is permanent (`--dangerously-permanent`), and a non-empty area also needs `--allow-non-empty` (see [errors.md](errors.md)).
+- **Deleting a repeating TEMPLATE** (the hidden rule, `projectIsTemplate`/`repeating` row) is allowed but is a one-way action here: it STOPS the series generating new occurrences and returns success with NO undo token plus warnings — the series' existing occurrences are left in place (the warning names how many and the current occurrence's uuid), and the only way to bring the series back is the Things app's Trash ▸ Put Back. So `undo`/`things undo` cannot reverse it; restoring a trashed template headlessly is refused with that same Put-Back pointer. (To END a series but KEEP its current occurrence, delete the TEMPLATE; to remove just one occurrence, delete that instance — series-preserving.)
+- **Copy an item:** `things todo clone <ref>` / `things project clone <ref>` make a faithful CONTENT copy through official surfaces — title, notes, tags, schedule (`when`), reminder, deadline, checklist items (incl. checked state), container, and completed/canceled state with the original timestamp; a project also copies its area, headings, and children. The clone is a NEW capture (a new uuid, created now, at its container's usual position); the clone's uuid is printed. `--title <t>` renames the copy; `--preserve-created` keeps the original's creation date (to the minute). It REFUSES a trashed source (restore it first), and a `project clone` refuses a project that CONTAINS a nested repeating template (it names the child). Cloning a repeating **TEMPLATE** itself is supported and makes a NEW repeating series — it copies the template's content and re-creates the recurrence with the source's rule (a fresh series identity; no past/future instances are copied; one instance spawns on create). Because that drives the app's Repeat dialog, a template clone needs `--dangerously-drive-gui` (an ordinary clone stays headless), and it refuses fail-closed if the source's rule can't be expressed by the Repeat dialog (e.g. two end bounds, or a month/year rule with multiple anchors — it names the feature). A paused source is cloned UNPAUSED (re-pause with `pause-repeat`). `undo` trashes the clone (a template clone removes the new series). This differs from the app's native `duplicate` (shallow, URL-only) — prefer `clone` when you need the checked/logged/structural state carried over.
 - Ambiguous refs FAIL with the candidates listed — retry with a UUID or a unique prefix. Never guess between candidates for a destructive action; inspect details or ask. The full candidate shape and dead-row hints are in [errors.md](errors.md).
 - Referenced containers and tags must already exist. Create nested structures **outside-in** (area → project → heading → to-do), and prefer each newly returned UUID as the next reference so duplicate titles cannot redirect placement.
 - Some operations are disruptive and require an explicit flag, **including their dry runs**: `--allow-disruptive` permits an op that briefly steals window focus; an op that visibly DRIVES the Things UI needs both `--allow-disruptive` and `--allow-very-disruptive` (the two-key gate). `things capabilities` lists each operation's support and any preconditions.
 - If a request needs a capability the tool reports as unsupported, say so plainly rather than improvising through unrelated commands.
 
+## Cross-device sync timing
+
+A verified write is committed to the LOCAL Things database immediately — `ok`/exit 0 means it is present here, right now, and every read on this host sees it at once. Propagation to Things Cloud is prompt too: a change starts syncing out within about 2–3 seconds (Things syncs on change, with no periodic heartbeat to wait for). When another device seems slow to show a change, that lag is the RECEIVING device's own pull/wake cadence — not a delay on the writing side — so do not treat "the write hasn't appeared on my phone yet" as a failed or pending write. Conversely, a change made on ANOTHER device lands in this host's database only once this host has pulled it; if you need to observe an edit made elsewhere, allow for that receive-side cadence rather than assuming it is already here.
+
 ## Bulk creation (contract summary)
 
 - **Several to-dos at once**: `things todo add "T1" "T2" "T3" [shared flags]`. Every shared flag (`--project`/`--area`/`--heading`/`--when`/`--tags`/`--deadline`/…) applies to each title; titles land in argument order. `--stdin` reads newline-delimited titles from stdin (blank lines skipped) instead of positional args (the two are mutually exclusive). `--id-only` prints exactly one uuid per line in creation order — pipe it to chain follow-up commands (mutually exclusive with `--json`).
@@ -45,19 +51,21 @@ A nonzero exit is informative, not a dead end — it means the write did not sil
 
 ## Batch (many changes at once)
 
-`things batch` runs a JSONL script (one `{"op","params",…}` per line) sequentially and independently — no transactions; a failure does not roll back earlier lines. Three fields make multi-step work reliable:
+`things batch` runs a JSONL script (one `{"op","params",…}` per line) sequentially and independently — no transactions; a failure does not roll back earlier lines. Key behaviors:
 
-- **`tempId` (chaining):** a line that CREATES something (a to-do, project, area, heading, repeater — never `tag.add`) can carry `"tempId":"proj1"`; a LATER line references that new uuid as `"$proj1"` in any id/container field. Dotted forms reach a repeater's parts: `"$proj1.instance"` (the visible occurrence), `"$proj1.replaced"` (the original). This is how you "create a project, then file to-dos into it" in one submission without knowing the uuid up front. Handles are `[A-Za-z0-9_-]{1,32}` and unique per batch; an unknown or forward `$ref` fails just that line.
-- **`opId` (safe retry):** carry a stable `"opId"` per line so resubmitting a batch after an ambiguous failure does not double-create — a line matching an earlier success is reported `already-applied`, not re-run. The single-op analogue is `--op-id <key>` (MCP `op_id`) on ONE mutation: a resubmission with a matched key returns the original success (`alreadyApplied: true`, the original `uuid`/`undoToken`) instead of running again. The variadic `move`/`reorder` are multi-leg compounds and REFUSE `--op-id` — express their idempotency as `things batch` with a per-line `opId`.
+- **Static preflight — one bad line refuses the WHOLE batch:** before anything runs, every line is checked for structural errors that need no app state (a torn/non-object line, a missing/unknown op, a `make-repeating`/`add-repeating` compound (refused in a batch), non-object `params`, a malformed `opId`, a `$ref` naming a `tempId` that no EARLIER line declares — unknown or forward — or a duplicate `tempId`). ANY such line refuses the ENTIRE batch up front, enumerating every offending line, and dispatches nothing (dry-run runs the same check). Fix the script and resubmit. Only RUNTIME failures (a guard block, verify-failed, an unsupported vector, a `$ref` to an earlier line that ended up creating nothing) are per-line.
+- **Stop-on-failure is the DEFAULT:** a runtime per-line failure HALTS the batch — the failed line is reported and every later line is reported not-run. Pass `--continue-on-error` (MCP `continue_on_error`) to run past failures instead (the old proceed-past behavior). The summary states how many lines did not run and whether a verbatim resubmission is safe to resume.
+- **`tempId` (chaining):** a line that CREATES something (a to-do, project, area, heading — never `tag.add`, and NOT `make-repeating`/`add-repeating`) can carry `"tempId":"proj1"`; a LATER line references that new uuid as `"$proj1"` in any id/container field. This is how you "create a project, then file to-dos into it" in one submission without knowing the uuid up front. Handles are `[A-Za-z0-9_-]{1,32}` and unique per batch.
+- **`opId` (safe retry + RESUME):** carry a stable `"opId"` per line so resubmitting a batch after a failure does not double-create — a line matching an earlier success is reported `already-applied`, not re-run. **Put an `opId` on EVERY line** so a batch that stopped mid-way can be resubmitted VERBATIM to resume: already-applied lines are skipped and the run continues from the failure. Without opIds, a verbatim resubmission RE-RUNS the lines that already committed (the summary's resume guidance names those indices). The single-op analogue is `--op-id <key>` (MCP `op_id`) on ONE mutation: a resubmission with a matched key returns the original success (`alreadyApplied: true`, the original `uuid`/`undoToken`) instead of running again. The variadic `move`/`reorder` are multi-leg compounds and REFUSE `--op-id` — express their idempotency as `things batch` with a per-line `opId`.
 - **Undo the whole batch:** the trailing summary line returns `tempIdMapping` (handle → uuid) and `undoToken`; `things undo --txn <undoToken>` reverses the entire submission as one unit.
 
 ## Recurrence (contract summary)
 
 Full rule vocabulary and worked examples: **`things help repeating`**. The stable contract:
 
-- Turning an item into a **fixed** repeater REPLACES it: the original becomes a hidden template plus a fresh first occurrence, so its UUID changes. The response returns a `repeating` block — `instanceUuid` (the visible current occurrence; use it to reach the item), `templateUuid` (the recurring rule; use it for `reschedule-repeat`), and `replacedUuid` (the original). Use these rather than re-finding the item by title.
-- `--after-completion` schedules the next occurrence N units after you complete the current one, and KEEPS the item's UUID.
-- Repeating operations require `--allow-disruptive` (including dry runs) and a required `--interval <n>` alongside `--frequency` (`--interval 1` for every unit).
-- New repeater: add the item first (`things todo add "<title>" --json`), then `things todo make-repeating <returned-uuid> --frequency <f> --interval 1 [--weekdays …] --allow-disruptive`.
+- `make-repeating` is **promote-via-clone and RECOVERABLE**: it copies the item, promotes the copy to a repeating series, and moves the ORIGINAL to the Trash. The response returns a `repeating` block — `instanceUuid` (the visible current occurrence; use it to reach the item), `templateUuid` (the recurring rule; use it for `reschedule-repeat`), and `replacedUuid` (the disposable clone) — plus a warning naming the trashed original. Use these rather than re-finding the item by title. **`things undo` reverses a promote**: it removes the new series (trashes the template AND its current instance) and restores the original from the Trash. `make-repeating` on a project that CONTAINS a nested repeating template is refused (it names the child). `make-repeating` and `add-repeating` are STANDALONE-only — they are refused as `things batch` lines (multi-leg promote compounds, not atomic ops); run them as their own command.
+- `--after-completion` schedules the next occurrence N units after you complete the current one (a fixed vs after-completion cadence — same recoverable promote).
+- Repeating operations require `--dangerously-drive-gui` (including dry runs — they drive the app's Repeat dialog) and a required `--interval <n>` alongside `--frequency` (`--interval 1` for every unit).
+- New repeater in ONE call: `things todo add-repeating "<title>" --frequency <f> --interval 1 [--when …] [--weekdays …] --dangerously-drive-gui` (and `things project add-repeating "<title>" [--area …] [--todo …] --frequency … --interval …`). The item is created first (and persists even if the promote refuses); `undo` removes the created series. Or make an existing item repeat with `make-repeating`.
 - Multiple weekdays go in ONE rule (`--weekdays monday,thursday,friday`) — never create two repeaters for "every Thursday and Friday".
-- `things show <ref> --json` on an occurrence exposes `repeating.templateUuid` — use it as the `<ref>` for `reschedule-repeat`.
+- `things show <ref> --json` on an occurrence exposes `instanceOf` (the `<templateUuid>`) — use it as the `<ref>` for `reschedule-repeat`. That detail read also carries `repeats: {rule?, next?, paused?}`, the instance's joined template context (the GUI's lower-corner "Repeats on …" caption); `repeats.next` is the projected next occurrence for a fixed rule (absent for after-completion).

package/skills/things-cli/references/data-model.md

@@ -45,7 +45,7 @@ Reads decompose an item's position onto two derived, presence-keyed words (they
 
 - **`stage`** — the sidebar BUCKET: `inbox | upcoming | anytime | someday | logbook | trash`. Read view membership off it directly. It is dropped inside a section/catalogue that already states it (the stage-pure `inbox`/`anytime`/`someday`/`logbook`/`trash` lists and the `today` view's two `children` buckets) and kept everywhere it is not implied (the mixed `upcoming` day blocks — future-dated `upcoming` rows beside deadline-forecast `anytime`/`someday` ones — plus `search`, `changes`, `deadlines`, the projects/areas listings, and `detail`).
 - **`when`** — the TIME POSITION: `today | evening | a future ISO date`, or absent (unscheduled and not in Today). `evening` implies today. Someday is a bucket, never a `when`. The `today` view returns `data.children = { today: {items, total?}, evening: {items, total?} }` — two keyed buckets (the bucket key states today/evening, so `when` is dropped inside them); the whole-view count rides `meta.counts` (`{dueOrOverdue, other}`).
-- The two are DIFFERENT facts. A due deadline pulls an UNDATED row into Today: it reads `when: "today"` and derives `stage: "anytime"` — the app re-files a deadline-pulled Inbox/Someday row into Anytime at pull time (R13/BANNER1b), so it drops out of the Inbox/Someday lists and joins Anytime while its `when` reads `today`. Completed/canceled → `stage: "logbook"`, trashed → `stage: "trash"`, regardless of any other hint.
+- The two are DIFFERENT facts. A due deadline pulls an UNDATED row into Today: it reads `when: "today"` and derives `stage: "anytime"` — the app re-files a deadline-pulled Inbox/Someday row into Anytime at pull time (RS8/BANNER1b), so it drops out of the Inbox/Someday lists and joins Anytime while its `when` reads `today`. Completed/canceled → `stage: "logbook"`, trashed → `stage: "trash"`, regardless of any other hint.
 - `provisional: true` marks a Today member the app has not yet materialized — see [banner.md](banner.md).
 
 ## Tiers — compact vs full (absence is meaningful)
@@ -58,6 +58,7 @@ Every row comes back at one of two densities, selected by view kind + flag, neve
 - **Container absence rule:** inside a single-container node (a project/area card, an `anytime`/`someday` section, a `project show` `headings[]` entry) an item omits any ancestry the node already states, so absent `project`/`area`/`heading` there means *inherited from the enclosing node*. A mixed list (`inbox`/`today`/`search`/`changes`) still names each row's own `project`/`area` (the `heading` ref is compact-dropped outside a project view; `--full` keeps it). In a read-shape v2 **`project show`** view membership is fully STRUCTURAL: every bucket row — un-headed body children AND rows nested under a `headings[]` entry, INCLUDING each `children.logbook` row — drops its `heading` ref, because its position states it. A swept child of an OPEN heading rides that heading's `children.logbook`; a swept child of an ARCHIVED heading rides the archived heading's `children.logbook`; the GUI's PROJECT-vs-HEADING logbook sublabel is TTY-derived from that structural placement, not from a per-row ref.
 - **Container ref shape:** a container ref is a bare **title string** (`"area": "Family"`, `"project": "Groceries"`, `"heading": "Backlog"`). A flat sibling `areaUuid` / `projectUuid` / `headingUuid` (the full uuid) rides alongside **only when the bare title would not resolve back** to that exact item — a duplicate title in the same resolution scope, or a title that is itself a valid uuid prefix. **To act on a ref, pass `.areaUuid // .area`** (same for project/heading): the uuid when present, else the title. For unattended pipelines or stored refs, use `--full` and key on the uuids — the full tier emits every `*Uuid` sibling unconditionally. A row whose container project is a repeating template carries a flat `projectIsTemplate: true` (the JSON twin of the TTY `↻` glyph) — acting on such a row edits the blueprint, affecting future occurrences, so target the intended copy via `projectUuid` (a same-titled occurrence exists alongside the hidden template).
 - **`type` is presence-keyed:** **absent `type` = to-do.** A row omits `type` when it is a to-do; `type` is present for a `project`, `heading`, `area`, or `tag` ROW (including in the error `candidates` shape). This is scoped to ROWS/candidates — a positional keyed node whose kind is fixed by its slot (a `project show` `headings[]` entry) drops `type` too, since its position already states it is a heading.
+- **Repeating templates vs instances (presence-keyed):** a repeating **template** (the hidden rule; list views hide it, `show` finds it) carries a nested `repeating: {paused?, deadlined?, rule?, latestInstance?}` — presence of `repeating` MEANS template; `rule`/`latestInstance` appear on a `show`/`detail` read only, and its projected next date rides the top-level `when`. A spawned **instance** (the visible occurrence) carries a flat `instanceOf: <templateUuid>` and NO `repeating` — presence of `instanceOf` MEANS instance. **On a `show`/`detail` read an instance ALSO carries `repeats: {rule?, next?, paused?}`** — its template's repeat context, the GUI's lower-corner "Repeats on Aug 19" / "Repeats 1 day after completion" caption: `rule` is the same decoded shape the template card emits, `next` the projected next occurrence for a **fixed** rule (ABSENT for after-completion — no successor date until the current instance completes), `paused: true` when the template is paused. It is read-only CONTEXT — `instanceOf` is the write handle (target the occurrence by it; the rule lives on the template). `repeats` is absent on list rows and when the template is unresolvable. A plain (non-repeating) row carries none of these.
 
 ## Filters over views