things-api 0.10.0 → 0.12.0

package/schema/envelope.schema.json

@@ -0,0 +1,383 @@
+{
+  "$id": "https://github.com/mikegreiling/things-api/schema/envelope.schema.json",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/WireEnvelope",
+  "definitions": {
+    "WireEnvelope": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/WireOkEnvelope"
+        },
+        {
+          "$ref": "#/definitions/ErrorEnvelope"
+        }
+      ],
+      "description": "The machine-readable ROOT the envelope JSON Schema is generated from (`schema/envelope.schema.json`, produced by `npm run schema:gen`): the discriminated union — on the boolean `ok` — of a successful envelope and an  {@link  ErrorEnvelope } , exactly as written to stdout by the CLI `--json` surface and inherited by the MCP server. This is the same grammar docs/contract.md describes in prose; the schema is its generated, testable rendering. NB: the streaming commands (`batch`, `undo`) emit JSON Lines, a documented exception NOT covered by this envelope type."
+    },
+    "WireOkEnvelope": {
+      "type": "object",
+      "properties": {
+        "apiVersion": {
+          "type": "number",
+          "const": 1
+        },
+        "ok": {
+          "type": "boolean",
+          "const": true
+        },
+        "kind": {
+          "$ref": "#/definitions/WireOkKind",
+          "description": "The payload class — see  {@link  WireOkKind } ."
+        },
+        "data": {
+          "$ref": "#/definitions/WireData",
+          "description": "Command-specific payload; open at the schema layer (see  {@link  WireData } )."
+        },
+        "meta": {
+          "$ref": "#/definitions/EnvelopeMeta"
+        }
+      },
+      "required": ["apiVersion", "ok", "kind", "data", "meta"],
+      "additionalProperties": false,
+      "description": "A successful `--json` envelope, exactly as emitted on stdout."
+    },
+    "WireOkKind": {
+      "type": "string",
+      "enum": [
+        "inbox",
+        "upcoming",
+        "logbook",
+        "trash",
+        "changes",
+        "search",
+        "projects",
+        "areas",
+        "tags",
+        "today",
+        "anytime",
+        "someday",
+        "area-view",
+        "project-view",
+        "detail",
+        "mutation-result",
+        "move-result",
+        "mutation-plan",
+        "move-plan",
+        "project-reopen",
+        "doctor",
+        "capabilities",
+        "config",
+        "legend",
+        "setup-shortcuts",
+        "install-skill"
+      ],
+      "description": "The envelope `kind` discriminators a SUCCESSFUL response carries today (the error envelope's `kind` is always the literal `\"error\"`). This union is the schema's record of the known payload classes — the flat-list reads (`data.items`), the sectioned reads (`data.sections`), the composite cards (`data.view`), the single-entity detail (`data.item`), the mutations/plans (flat `data` fields), and the diagnostic payloads.\n\nPer the compatibility covenant (docs/contract.md) a consumer MUST tolerate an UNKNOWN `kind`: adding a new kind is additive / non-breaking. So this union is \"the kinds known to THIS build\", not a closed set a generic reader may assume complete — the JSON Schema pins it as an enum so drift is caught, but a forward-compatible consumer routes on the wrapper it finds in `data`."
+    },
+    "WireData": {
+      "type": "object",
+      "additionalProperties": {},
+      "description": "The `data` payload of a successful envelope. Its CONCRETE shape is command-specific — one of the R1/R2 read wrappers (`item` | `view` | `items` | `sections`) or a mutation's flat result fields — and, crucially, entity payloads are omit-empty pruned on the wire (docs/design/contracts.md).\n\nCOVERAGE BOUNDARY: this schema does NOT model the per-kind payload shapes. It pins the ENVELOPE layer exactly (`apiVersion`, `ok`, `kind`, `meta`, and the whole `error` object) and treats `data` as an open JSON object. Fully typing every kind's payload against the omit-empty wire shape is a separate, larger effort; until then `src/contracts.ts` and `docs/contract.md` remain the authoritative description of what each `kind`'s `data` contains."
+    },
+    "EnvelopeMeta": {
+      "type": "object",
+      "properties": {
+        "dbVersion": {
+          "type": ["number", "null"],
+          "description": "Things database schema version (`Meta.databaseVersion`), null when no DB was opened."
+        },
+        "fingerprint": {
+          "type": "string",
+          "enum": ["ok", "drift", "user-accepted", "unknown"],
+          "description": "Schema fingerprint status at the time of the command."
+        },
+        "elapsedMs": {
+          "type": "number",
+          "description": "Wall-clock duration of the command in milliseconds."
+        },
+        "truncation": {
+          "$ref": "#/definitions/Truncation",
+          "description": "The read's completeness metadata (the single truncation shape). Present on any read that could drop rows — flat views (row `limit`), the Today split (`sections`), and grouped views (anytime/someday/`area show`, `blocks`). `meta.truncation.truncated` is the universal \"did I see everything\" check."
+        },
+        "resolvedCommand": {
+          "type": "string",
+          "description": "The canonical `things …` command a sugar invocation normalized to (bare noun, keyword-in-show, uuid/share-link routing). Present only on routed reads reached via a sugar form; absent for canonical invocations."
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Non-blocking advisories about this read (ADDITIVE). Present only when there is something to flag — currently a one-line note when the Things database schema no longer matches the version this build was validated against (reads stay best-effort; run `things doctor`). Absent means none."
+        },
+        "clock": {
+          "type": "object",
+          "properties": {
+            "timezone": {
+              "type": "string"
+            },
+            "today": {
+              "type": "string"
+            }
+          },
+          "required": ["timezone", "today"],
+          "additionalProperties": false,
+          "description": "The effective clock this response's date boundaries were computed for (ADDITIVE honesty field). Present ONLY when a consumer zone (`THINGS_TZ` / the MCP `tz` argument) or a pinned `THINGS_NOW` is in effect; ABSENT on the host clock, so the wire shape is unchanged for ordinary consumers."
+        },
+        "filter": {
+          "type": "object",
+          "properties": {
+            "area": {
+              "type": "object",
+              "properties": {
+                "uuid": {
+                  "type": "string"
+                },
+                "title": {
+                  "type": "string"
+                }
+              },
+              "required": ["uuid", "title"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["area"],
+          "additionalProperties": false,
+          "description": "The active content filter this response was scoped to (ADDITIVE). Present ONLY when a scope was applied — currently `area` (the `--area` view filter), carrying the resolved area's uuid + title; ABSENT otherwise, so the wire shape is unchanged for unscoped reads (the `meta.clock` precedent)."
+        },
+        "scope": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": ["area", "project"]
+            },
+            "uuid": {
+              "type": "string"
+            },
+            "title": {
+              "type": "string"
+            },
+            "source": {
+              "type": "string",
+              "enum": ["flag", "env", "config"]
+            }
+          },
+          "required": ["kind", "uuid", "title", "source"],
+          "additionalProperties": false,
+          "description": "The active container scope this response was jailed to (ADDITIVE). Present ONLY when a scope is in force (the MCP `--scope` flag / `THINGS_API_SCOPE` / a stored `scope`), naming the container + where the scope came from; ABSENT otherwise, so the wire shape is unchanged for unscoped reads. Lets an agent know its own jail — which is not an oracle for what lies outside it (the `meta.clock` / `meta.filter` additive precedent)."
+        }
+      },
+      "required": ["dbVersion", "fingerprint", "elapsedMs"],
+      "additionalProperties": false
+    },
+    "Truncation": {
+      "type": "object",
+      "properties": {
+        "shown": {
+          "type": "number"
+        },
+        "total": {
+          "type": "number"
+        },
+        "limit": {
+          "type": ["number", "null"]
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/SectionCount"
+          },
+          "description": "Per-section shown/total breakdown for a split flat view (Today); absent otherwise."
+        },
+        "blocks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/GroupBlock"
+          },
+          "description": "Per-block nesting for a grouped view (anytime/someday/area card); absent otherwise."
+        }
+      },
+      "required": ["shown", "total", "limit", "truncated"],
+      "additionalProperties": false,
+      "description": "The single truncation-metadata shape for every read (the `meta.truncation` field). `shown` items were returned of `total` that matched after all filters; `limit` is the effective cap (null when the caller asked for all rows, and always null on a grouped view whose caps are per-block); `truncated` is the UNIVERSAL completeness check — true exactly when anything was dropped (`shown < total`, or any block hid rows). The dropped remainder is `total - shown`.\n\nTwo optional per-shape breakdowns hang off it: `sections` for a split flat view (the Today split — per render-section shown/total), and `blocks` for a grouped view (anytime/someday/`area show` — the identity-carrying per-block nesting). Exactly one of them is present on the shapes that have it; both are absent on a plain flat view."
+    },
+    "SectionCount": {
+      "type": "object",
+      "properties": {
+        "key": {
+          "type": "string",
+          "enum": ["today", "evening"]
+        },
+        "shown": {
+          "type": "number"
+        },
+        "total": {
+          "type": "number"
+        }
+      },
+      "required": ["key", "shown", "total"],
+      "additionalProperties": false,
+      "description": "Per-section counts for a SPLIT flat view — currently only `today`'s Today / This-Evening split. One entry per section IN RENDER ORDER, each reporting the rows `shown` of the `total` that matched after all filters. Lets a renderer keep a downstream section (This Evening) honest under a single global cap without a pre-truncation copy of the view."
+    },
+    "GroupBlock": {
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": ["loose", "area", "project", "projects"]
+        },
+        "ref": {
+          "type": ["string", "null"],
+          "description": "Container reference (area or project uuid); null for the loose block."
+        },
+        "title": {
+          "type": ["string", "null"],
+          "description": "Container title; null for the loose block."
+        },
+        "shown": {
+          "type": "number"
+        },
+        "total": {
+          "type": "number"
+        },
+        "limit": {
+          "type": ["number", "null"],
+          "description": "The cap that applied to THIS block (null = uncapped)."
+        },
+        "totalProjects": {
+          "type": "number",
+          "description": "Type split for blocks that mix project rows and to-dos (someday's loose/area blocks; projects always list first, so the hidden split is `totalProjects - min(shown, totalProjects)` projects, remainder to-dos). Absent on single-type blocks."
+        },
+        "totalTodos": {
+          "type": "number"
+        },
+        "children": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/GroupBlock"
+          },
+          "description": "Nested project blocks (anytime item-lists / someday active-project groups). Absent when none."
+        }
+      },
+      "required": ["kind", "ref", "title", "shown", "total", "limit"],
+      "additionalProperties": false,
+      "description": "One identity-carrying block of a grouped catalogue (anytime/someday) or a sectioned detail view (`area show`). Every header/section is always rendered; only the innermost item lists are capped. Emitted for every block that has rows to cap (`total > 0`) — including a block whose rows were ALL dropped (`shown: 0`), so no truncated header is untraceable. A block with no cappable rows of its own (`total: 0`) is omitted UNLESS it wraps truncated `children` — an area whose only capped content is its project item-lists still appears as their container.\n\nBlocks are NESTED: an area/loose block carries its project blocks in `children` — in anytime the project item-lists inside the area, in someday the active-project child groups found in that section. The `area show` `projects`/`area` blocks are siblings of one area and stay top-level."
+    },
+    "ErrorEnvelope": {
+      "type": "object",
+      "properties": {
+        "apiVersion": {
+          "type": "number",
+          "const": 1
+        },
+        "ok": {
+          "type": "boolean",
+          "const": false
+        },
+        "kind": {
+          "type": "string",
+          "const": "error"
+        },
+        "error": {
+          "type": "object",
+          "properties": {
+            "code": {
+              "$ref": "#/definitions/ErrorCode",
+              "description": "Stable machine-readable code from the  {@link  ErrorCode }  registry (mirrors the exit-code family, e.g. \"verify-failed\", \"blocked:H-UNKNOWN-TAG\")."
+            },
+            "message": {
+              "type": "string"
+            },
+            "likelyCause": {
+              "type": "string",
+              "description": "Advisory attribution when failure signals point somewhere: e.g. \"permission-denied\", \"permission-pending\", \"feature-disabled\", \"app-updated\", \"schema-drift\", \"app-behavior-change\"."
+            },
+            "remediation": {
+              "type": "string",
+              "description": "Actionable next step for the caller, when one exists."
+            },
+            "detail": {
+              "type": "object",
+              "properties": {
+                "expected": {},
+                "observed": {
+                  "anyOf": [
+                    {
+                      "type": "object",
+                      "additionalProperties": {}
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "candidates": {
+                  "type": "array",
+                  "items": {}
+                },
+                "suggestions": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "considered": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "vector": {
+                        "type": "string"
+                      },
+                      "why": {
+                        "type": "string"
+                      }
+                    },
+                    "required": ["vector", "why"],
+                    "additionalProperties": false
+                  }
+                },
+                "placed": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "remaining": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "cause": {},
+                "failed": {},
+                "completed": {
+                  "type": "array",
+                  "items": {}
+                }
+              },
+              "additionalProperties": false,
+              "description": "The SINGLE structured, machine-readable failure-context object (there is no separate `details` field — the two were reconciled into this one). Each key is present only for the failures that produce it:  - `expected` / `observed` — a verify-failed mutation's expected delta and    the observed post-write state.  - `candidates` — the disambiguation list for a not-found / ambiguous    resolution (or a show/bare-noun did-you-mean): the ONE fixed, flag-    invariant candidate shape (`CandidateRef`; see docs/contract.md), a    LIVE-scoped pool capped at 8, so an agent can self-correct without    another round-trip.  - `suggestions` — for a bare mutation verb (`things update <ref>`), the    concrete namespaced command(s) to run instead.  - `considered` — the vectors weighed (and why each was rejected) for an    unsupported operation.  - `placed` / `remaining` / `cause` — a bounce reorder that aborted    part-way: the items already placed, those not yet placed, and the cause.  - `failed` / `completed` — a multi-leg move that failed mid-way: the leg    that failed and the legs already completed before it."
+            }
+          },
+          "required": ["code", "message"],
+          "additionalProperties": false
+        },
+        "meta": {
+          "$ref": "#/definitions/EnvelopeMeta"
+        }
+      },
+      "required": ["apiVersion", "ok", "kind", "error", "meta"],
+      "additionalProperties": false
+    },
+    "ErrorCode": {
+      "type": "string",
+      "description": "The registry of stable machine-readable error codes an error envelope can carry — the compiler IS the registry. Every `error.code` value the surfaces emit is a member of this union, and the human-readable meaning of each is frozen at v1.0 (new codes may still be ADDED after v1.0 — that is non-breaking; a documented code's MEANING never changes). The canonical per-code table (meaning + the `detail` keys each may carry) lives in `docs/contract.md` (The error-code registry).\n\nTwo members are template-literal families rather than fixed strings, because their suffix is minted in the write layer and the core deliberately never depends on it (see  {@link  blockedCode }  /  {@link  verifyFailedCode } ):  - `verify-failed:${reason}` — a single mutation executed but read-after-write    verification failed; the suffix is the reason (`timeout` | `mismatch` |    `silent-noop`). The bare `verify-failed` (no suffix) is the multi-leg    move/reorder failure.  - `blocked:${suffix}` — a mutation refused before touching the app; the    suffix is the specific hazard id (`H-…`) when one is named, else the block    reason (`drift` | `disruption-tier` | `lock` | `environment` | `clock` |    `scope`). The bare `blocked` is a policy refusal from the move planner.\n\n`blocked:drift` maps to exit code 5 (DriftBlocked); every other `blocked:*` maps to exit code 4 (Blocked)."
+    }
+  },
+  "title": "things-api envelope",
+  "description": "JSON Schema for the things-api --json response envelope (the discriminated union of a success envelope and an error envelope), generated from the WireEnvelope type in src/contracts.ts. See docs/contract.md (The machine-readable schema). The envelope layer is modeled exactly; the command-specific `data` payload is an open object (coverage boundary)."
+}

package/skills/things-cli/SKILL.md

@@ -0,0 +1,70 @@
+---
+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.12.0
+---
+
+# Things CLI
+
+`things` is a command-line interface to the user's Things 3 task database. Reads are instant SQL queries; writes go through the app itself and are checked after they land. Use `things` when it is on your PATH; otherwise — or when `things --version` reports below **0.12.0** — substitute `npx -y things-api@latest` in every command (identical subcommands and flags), which always pairs the current commands with their current help.
+
+`things --help` is the one-screen index; `things <group> --help` lists a group's verbs and flags (always current for the binary you invoke); `things help <topic>` opens a contract guide — topics: `agent`, `filters`, `ids`, `move`, `output`, `repeating`, `writes`.
+
+## Data model (read this first)
+
+- **To-do** — the basic item: title, notes, an optional **checklist** (sub-steps), tags, schedule, deadline, reminder. Has at most ONE container — loose in an **area**, directly in a **project**, or under a **heading** inside a project — or **none at all** (standalone to-dos are normal, like standalone projects).
+- **Inbox** — not a container but the *untriaged state*: an inbox to-do has no container and no schedule. Filing it into a container or scheduling it moves it out of the Inbox; moving something back TO the Inbox un-files AND un-schedules it.
+- **Project** — a goal-sized container of to-dos, optionally divided by **headings** (section labels; a heading belongs to one project and cannot hold projects). Projects live in an area or stand alone. Projects can also have their own notes, tags, schedule, and deadline.
+- **Area** — a top-level bucket (e.g. a sphere of responsibility) holding projects and loose to-dos. Areas have tags but no dates, and never go to the Trash — deleting one is permanent.
+- **Tags** — form a hierarchy, and are **inherited downward**: a to-do effectively carries its own tags plus those of its project and area. Headings carry no tags, but inheritance flows through them from project to to-do.
+- **Views** are queries over this model, matching the app's sidebar: `inbox` (unsorted), `today` (scheduled for today, incl. This Evening), `upcoming` (future-dated), `anytime` (all active), `someday` (kept without a date), `logbook` (completed/canceled), `trash`.
+- **Scheduling vocabulary**: an item's *when* is `today | evening | anytime | someday | YYYY-MM-DD`. A **deadline** is a separate due date; a **reminder** is a separate time-of-day alert — never write `date@time` into *when*.
+
+## Reading position from JSON: `stage` and `when`
+
+Reads decompose an item's position onto two derived, presence-keyed words (they REPLACED the old `start`/`logged`/`trashed`/`todaySection` fields):
+
+- **`stage`** — the sidebar BUCKET: `inbox | upcoming | anytime | someday | logbook | trash`. Read view membership off it directly (a completed row is `logbook`, a trashed row `trash`, regardless of any other hint). Dropped inside a section that already states it; present in mixed lists, `search`, `changes`, and `detail`.
+- **`when`** — the TIME POSITION: `today | evening | a future ISO date`, or absent. `evening` implies today; someday is a bucket (→ `stage`), never a `when`. A due deadline pulls an undated row into Today (`when: "today"`); the app re-files it into Anytime, so it derives `stage: "anytime"` (it leaves the Inbox/Someday list).
+- **`provisional: true`** marks a Today member the app has not yet materialized (the "N new to-dos" banner / `•` pip); see [references/banner.md](references/banner.md).
+
+**Absence is meaningful.** In the compact list tier a field at its default is omitted (no `status` = open, no `when` = not in Today), and inside a single-container node an item omits ancestry the node already states (absent `project`/`area` there = inherited). Full rules and the compact/full tiers: [references/model.md](references/model.md).
+
+## Referring to items
+
+Commands take a `<ref>`: a UUID, a unique UUID prefix (≥ 6 chars), a Things share link, or a (unique) title. Ambiguous refs fail with the candidates listed — pick one and retry ([references/errors.md](references/errors.md) has the candidate/dead-row/hazard contract). Discover UUIDs via any read command; add `--json` for stable machine output (UUIDs are in `.uuid`; emitted UUIDs are always full).
+
+## Stable contracts
+
+These hold regardless of the binary version; see [references/contracts.md](references/contracts.md) for the full text.
+
+- **JSON envelope**: every `--json` response is `{ apiVersion, ok, kind, data, meta }`. Read results from `.data` (`.data.items`/`.data.sections`/`.data.item`/`.data.view` per `kind`), 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` shows any write's 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`).
+- **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.
+
+## Reading
+
+Views and lookups — pass `--json` whenever you will act on the output: `things today | inbox | upcoming | anytime | someday | logbook | trash`, `things show <ref>` (full detail incl. notes + checklist + effective tags), `things projects [ref]`, `things areas [ref]`, `things tags`, `things search <words>`, `things changes --since <moment>`. Compact rows carry `hasNotes`, `checklist:{open,total}` (to-dos), and `todos:{open,total}` (projects); `--full` (or `show`) adds the full `notes`, `startDate`, and checklist `items`. A `search` hit carries `match:{field,text}` provenance when it matched something other than the title. Filters (`--tag`, `--untagged`, `--overdue`, `--limit N`, `--all`, …) compose with AND — see `things help filters`. The reserved read-only ref `loose` addresses the area-less items as a pseudo-area (`areas loose`, `area show loose`, `--area loose`) and wins over any real area named "Loose"; every write verb refuses it.
+
+## 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`, and `things reorder`.
+
+**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.
+
+**Move vs reorder — keep them apart** (`things help move`). MOVE changes WHAT an item belongs to: `things todo move <refs…> --to-project|--to-heading|--to-area <ref>`, or the detach family `--no-heading` / `--loose` / `--inbox`; `things project move <refs…> --to-area <ref>|--no-area`. REORDER changes only ARRANGEMENT in place, never membership: `things reorder <refs…> [--first|--last|--before <ref>|--after <ref>] [--in <target>]`. Both are variadic (selection order = landing order). An anchor POSITIONS but never MIGRATES — a cross-container/bucket anchor fails closed. A Today/Evening member sits on two axes (its Today slot and its container slot); a set coherent on both is REFUSED until you pass `--in` (`today|evening|anytime|someday|inbox`, or a project/area/heading ref). Every non-template item is sortable; the axes, gates, and automatic fallbacks are in [references/ordering.md](references/ordering.md). (MCP exposes these as the `reorder` and `reorder_areas` tools.)
+
+**Guarded writes** surface their consequence and require an explicit flag: deleting a NON-EMPTY area needs `--allow-non-empty`, a permanent delete needs `--dangerously-permanent`, and a UI-driving op (e.g. `area reorder`) needs `--dangerously-drive-gui` plus `things config set ui-enabled true`. The full acknowledgment contract is in [references/errors.md](references/errors.md).
+
+**Quick skeletons**: `things todo add "T1" "T2" "T3" [shared flags]` creates several to-dos in one call (every shared flag — `--project`/`--area`/`--when`/`--tags`/… — applies to each; `--id-only` prints the new uuids one per line for chaining; one `undoToken` removes the set). To stand up a new project with children, `things project add "<title>" --todo "T1" --todo "T2" …` (repeatable). For richer per-item metadata or cross-item references, use `things batch`.
+
+## Going deeper
+
+- [references/model.md](references/model.md) — the full data model, `stage`/`when` derivation, the compact/full tiers, view membership, and filters.
+- [references/contracts.md](references/contracts.md) — the JSON envelope, exit codes, safety/undo/idempotency, batch chaining, and recurrence.
+- [references/ordering.md](references/ordering.md) — move vs reorder in depth: axes, gates, caps, automatic fallbacks, placement guarantees, and the one dead class (templates).
+- [references/errors.md](references/errors.md) — the error contract: the candidate shape, dead-row hints, hazard acknowledgments, and the error-code registry.
+- [references/banner.md](references/banner.md) — the Today "new to-dos" banner, the provisional `•` pip, reminder/evening liveness, and what a watcher sees.
+- [references/gui.md](references/gui.md) — how the user sees Things in the app (where results appear, what list rows show).

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

@@ -0,0 +1,35 @@
+# The Today banner, provisional pips, and liveness (deep reference)
+
+Things renders three presentation-layer facts that are NOT stored as their own bytes — the "new to-dos" banner, the evening section, and the reminder bell. The reader mirrors the app faithfully rather than reporting the raw columns. This page is the model behind the `provisional` field, the `•` pip, and reminder/evening liveness.
+
+## The provisional `•` pip and the "N new to-dos" banner
+
+When items arrive in Today on their own, Things shows a yellow "You have N new to-dos" banner and a yellow `•` pip on each such row. Those rows are **provisional** — Today members the app has not yet materialized.
+
+- The wire emits presence-keyed **`provisional: true`** on exactly those rows, on every tier, and never drops it (the banner is not a section). The banner's `N` equals the count of `provisional` Today members, exactly — **the banner as data.**
+- **What "new" means:** the flagged rows are the AUTONOMOUS entrants — a scheduled arrival (lands on its startDate), a repeat-instance spawn, or a due-deadline pull (no startDate yet). A USER-placed entrant (`add`/`update --when today`, which lands materialized) is never flagged. The wire hands you `provisional` directly, so you never compute it; the underlying law (what a raw-DB watcher would evaluate) is `start` is not `1` (active) OR `startDate IS NULL`.
+- `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.
+
+## There is no `today ok` — dismissing the banner is a data mutation
+
+`things today ok` (acknowledge the banner / clear the pips) is a DECIDED not-to-implement (⛔). Reasons worth knowing:
+
+- Clicking **OK** in the app does exactly one thing: it MATERIALIZES the provisional rows — `start := 1` and `startDate := ` the cohort/deadline date where it was NULL — and writes nothing else, in no other table. There is no separate "reviewed" marker anywhere; acknowledgment IS the row mutation.
+- That mutation is **not byte-reproducible** through a supported write (`--when today` no-ops on a provisional row; the OK'd `startDate` is a past date every URL write clamps; `--when anytime` is the only leg that flips the bucket but it ejects the row from Today), and it silently **de-inboxes / de-somedays** an untriaged pulled item (`start 0→1` / `2→1`). Approximating it would diverge silently from the app's own bytes, so it is not offered.
+
+**The per-item dismiss you CAN drive (deadline-pulled rows):** rescheduling an overdue-deadline row out of Today to a no-startDate bucket — `things todo update <ref> --when someday` (or `anytime`) — auto-stamps the app's own suppression so the past deadline stops re-pulling it; or `things todo update <ref> --clear-deadline` removes the deadline outright. There is no dedicated "dismiss deadline" affordance in the app either — this reschedule side effect is it.
+
+## What a watcher sees
+
+A process polling the database must tolerate the app rewriting provisional rows' schedule bytes out from under it: when a human clicks OK (on this or any synced device), every listed row's `start`/`startDate` change (`start:=1`, `startDate:=` the cohort date). Nothing else moves. So a watcher should key "new/unreviewed" off the same derivation the reader uses (`start != 1 OR startDate IS NULL`), NOT off a stored marker (there is none), and expect those bytes to settle once the user acknowledges.
+
+## Reminder and evening liveness (§9n)
+
+The app shows a reminder bell and a "This Evening" placement only while the row's `startDate` is TODAY (or future, for a reminder). Once `startDate` goes strictly past, the app discards both at the presentation layer while leaving the raw columns in the database forever — nothing clears them, not a day-rollover, not the banner OK. The reader mirrors this:
+
+- **Reminders.** A today- or future-dated reminder is reported (`reminder` present); a strictly-past one is OMITTED on every surface (list rows, detail, JSON, search, and the TTY `◷` chip). The stored byte is never touched. On the WRITE side a bare `--when` re-schedule auto-preserves a LIVE reminder but never RESURRECTS a stale one (so `--when evening` on a weeks-past row no longer re-arms an 18:00 bell the user believed gone).
+- **Evening.** An arrived evening row whose `startDate` has gone past collapses to a plain Today member — `when` reads `"today"`, not `"evening"`. The evening section expires daily.
+- **Reminder format:** the JSON wire carries `HH:MM` (24-hour); the human TTY chip renders 12-hour. Same fact, two renderings.

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

@@ -0,0 +1,62 @@
+# Stable contracts: envelope, exit codes, safety, recurrence
+
+The apiVersion-stable contracts that hold regardless of which binary version you invoke. Mechanics — verbs, flags, per-operation preconditions — live in `things <group> --help` and `things help <topic>` and version with the binary; the contracts here do not.
+
+## JSON envelope
+
+Every `--json` response is an envelope `{ apiVersion, ok, kind, data, meta }`:
+
+- Results are in `.data`, in exactly one of four wrappers named by `kind`: `.data.item` (one entity), `.data.view` (an area/project card), `.data.items` (a flat list), or `.data.sections` (a list split into named sections). Never `.items` at the top level. Item UUIDs are in `.uuid`, not `.id`; emitted UUIDs are always full.
+- Check `meta.truncation.truncated` before concluding "no match" or "that's everything": it is `true` exactly when any row was hidden (`shown < total`, or any grouped block capped). Raise `--limit`/`--all` or narrow the filter rather than assuming you saw everything.
+- List/search rows are compact **summaries**: their `tags` field is not necessarily the complete effective set, and placement can be partial. Use `things show <ref> --json` when notes, checklist, placement, or inherited/effective tags matter.
+
+## Exit codes (writes are verified after they land)
+
+A value once assigned keeps its meaning forever — the codes are never renumbered.
+
+- `0` — the change landed and was verified.
+- `1` — unexpected (an internal error / bug): stop and report.
+- `2` — usage error: fix your invocation and retry.
+- `3` — verify-failed: the change did NOT stick; the message carries the reason and usually the remediation.
+- `4` — blocked: refused before it touched the app (a guard/hazard, scope, lock, …); the message names the flag or fix.
+- `5` — drift-blocked: the database schema fingerprint no longer matches; writes are held until re-certified.
+- `6` — unsupported: no available write surface performs this operation.
+- `7` — environment: database not found, Things not installed, or a permission problem.
+
+A nonzero exit is informative, not a dead end — it means the write did not silently half-apply, so you are never left guessing whether it took. Read the message; it usually names the fix. The error `code`, the candidate/dead-row contract, and the hazard acknowledgments are in [errors.md](errors.md).
+
+## 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.
+- 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)).
+- 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.
+
+## 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`).
+- **One undo for the whole set**: a multi-title add runs as one unit. `--json` streams a per-line result plus a trailing `summary` line carrying a single `undoToken`; `things undo --txn <undoToken>` removes the whole skeleton at once. A single-title `add` is unchanged — it still returns the ordinary single mutation-result envelope.
+- **New project with children**: `things project add "<title>" --todo "T1" --todo "T2" …` (`--todo` repeatable) seeds a project skeleton in one call.
+- **Richer batches**: for per-item metadata that differs, or cross-item references (`tempId`/`$ref`), use `things batch` (JSONL) — same one-`undoToken` undo semantics.
+
+## 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:
+
+- **`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`.
+- **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`.
+- 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`.

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

@@ -0,0 +1,49 @@
+# The error contract (deep reference)
+
+A failed `--json` call carries `ok: false`, `kind: "error"`, and an `error` object with a machine-readable `code`, a human `message`, an optional `likelyCause` and `remediation`, and at most one structured `detail`. The exit code mirrors the family (see [contracts.md](contracts.md)). A nonzero exit is informative, not a dead end — the change did not silently half-apply, and the message usually names the fix.
+
+## Candidates — self-correcting from an ambiguous or missing ref
+
+When a name or partial-uuid resolves to more than one row, or to none, `error.detail.candidates` offers a disambiguation list so you self-correct without another round-trip. Each entry is ONE fixed, slim shape:
+
+- `uuid`, `title`, and `type` (`"to-do" | "project" | "heading" | "area" | "tag"`) — always.
+- A container hint `area` and/or `project` as a TITLE string — only when set.
+- `stage` / `when` (the same derivations as the item wire) — only for a to-do/project candidate whose row carries them. A trashed/logged candidate needs no boolean: `stage` already reads `"trash"` / `"logbook"`.
+- NOTHING else — no notes, counts, dates, or raw fields.
+
+The shape is **flag-invariant**: `--full` / `--all` never widen it (an error payload is the most determinism-critical surface). The list is **capped at 8**; when more matched, the `message` states the total (e.g. "matches 12 projects … 4 more"). `ambiguous` carries the candidate list; `not-found` carries `candidates: []`.
+
+**Live-scoped pool + dead-row hints.** By default candidates are LIVE rows only — a trashed or logged row never appears as a "did you mean". A trash/logbook-domain op (e.g. `project restore`) widens its own pool to that domain. When a name matches ZERO live rows but a DEAD row exists, the `message` gains an honest tail ("1 trashed item matches this name — see `things trash`", or the logbook equivalent) and `candidates` stays `[]` — no dangling-ref invitation. A write whose only name-match is a completed/logged project resolves to nothing by name (target it by uuid if intended); this prevents stranding an open child inside an invisible done project.
+
+Never guess between candidates for a destructive action — inspect details or ask.
+
+## Guarded writes and their acknowledgments
+
+Some writes have a cascading or permanent effect. Each is refused BEFORE touching the app until you pass the flag that names the consequence; a `--dry-run` shows the same refusal. The CLI describes each by its consequence, but the JSON error's `blocked:<hazard>` code is the machine-readable handle:
+
+- **Delete a NON-EMPTY area** → `--allow-non-empty`. Deleting an area sends its to-dos AND its projects (with their children) to the Trash and destroys the area row permanently. A delete pre-counts live members and refuses with the counts ("the area is not empty — it contains 3 projects and 12 to-dos"), naming both remediations: empty the area first, or pass `--allow-non-empty`. An empty area is unaffected (still just `--dangerously-permanent`). Code: `blocked:H-AREA-NOT-EMPTY`.
+- **Permanent delete** (an area; emptying the Trash) → `--dangerously-permanent`. There is no inverse; `undo` names the manual one rather than pretending. Code: `blocked:H-PERMANENT-DELETE`.
+- **Drive the live UI** (the ops the app offers nowhere else — e.g. `area reorder`, and some heading/repeat ops) → the two-key gate: the `--dangerously-drive-gui` flag AND `things config set ui-enabled true` (plus Accessibility granted to the process). These visibly drive the Things window. Code: `blocked:H-UI-DRIVE`. (Separately, the `--allow-disruptive` / `--allow-very-disruptive` flags raise the process's disruption ceiling for any op that steals focus or drives the UI.)
+- **Reopen or reuse a resolved project** — moving or adding an OPEN child into a completed/canceled project reopens it via the app; that is acknowledged (`blocked:H-REOPEN-RESOLVED-PROJECT`) so it is never a silent side effect.
+- Other guards name their own consequence the same way (heading cascades, backdating an open item, checklist replacement, repeat scheduling, tag-subtree delete, …).
+
+`things capabilities` lists every operation's support and preconditions; `--dry-run` previews any plan. If a request needs a capability the tool reports as unsupported, say so plainly rather than improvising through unrelated commands.
+
+## The error-code families
+
+Every `error.code` is drawn from a frozen registry. Route on the code, and for the two template families route on the prefix:
+
+| Family | Meaning | Exit |
+|---|---|---|
+| `usage` | Bad flags/arguments, mutually-exclusive flags, an unparseable date, or a move that meant to schedule. | 2 |
+| `not-found` | A ref or subject resolved to nothing (`candidates: []`). | 2 |
+| `ambiguous` | A name/partial-uuid matched several rows (carries `candidates`). | 2 |
+| `unsupported` | No available write vector supports the operation (`detail.considered`). | 6 |
+| `environment` | Database not found, Things not installed, or a permission problem. | 7 |
+| `unexpected` | An internal error (a bug) — stop and report. | 1 |
+| `verify-failed:<reason>` | A single mutation executed but the read-back check failed. `<reason>` ∈ `timeout | mismatch | silent-noop`. | 3 |
+| `blocked:<suffix>` | Refused before dispatch — a hazard id (above) or a reason (`disruption-tier`, `lock`, `scope`, `clock`, `environment`, `drift`). `blocked:drift` is exit 5; all other `blocked:` are exit 4. | 4 / 5 |
+| `bounce-aborted` | A reorder bounce aborted part-way (`detail.placed`/`remaining`/`cause`). | 3 |
+| `verify-failed` | A multi-leg move/reorder failed mid-way (`detail.failed`/`completed`). | 3 |
+
+A consumer that does not recognize a specific suffix routes on the prefix (`blocked:` / `verify-failed:`) and the exit code.