things-api 0.13.0 → 0.15.0

package/skills/things-cli/SKILL.md

@@ -1,15 +1,17 @@
 ---
 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.13.0
+version: 0.15.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` 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 the version stamped in this skill's `version:` frontmatter above (set at publish time; the commands and read-view JSON shapes documented here — including the bucketed `today` / project / area shapes — track the release this skill ships with) — 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`.
 
+**This skill's reference files** are exactly `data-model`, `contracts`, `ordering`, `errors`, `banner`, `gui` (all `references/*.md`) — do not guess other names. Read *shapes* (every view's JSON, `stage`/`when`, the compact/full tiers) live in `data-model`; the envelope, exit codes, undo, batch, and recurrence in `contracts`; move/reorder axes in `ordering`; the error contract in `errors`. There is no `reads`/`writes`/`recurrence`/`safety` file. Most tasks need only this page — open a reference only when a link below sends you there.
+
 ## 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).
@@ -24,11 +26,11 @@ version: 0.13.0
 
 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 only where a view provably states it — the stage-pure flat views (`inbox`/`anytime`/`someday`/`logbook`/`trash`) and the `today` view; KEPT everywhere it is stage-mixed — `upcoming`, `search`, `changes`, the projects/areas listings, the project/area card `items` (and the project `logbook`), and `detail`.
+- **`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`, `deadlines`, 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).
+**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/data-model.md](references/data-model.md).
 
 ## Referring to items
 
@@ -40,7 +42,7 @@ Commands take a `<ref>`: a UUID, a unique UUID prefix (≥ 6 chars), a Things sh
 
 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.
+- **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`).
 - **Preconditions**: referenced containers and tags must already exist — create nested structures outside-in and reuse each returned UUID.
@@ -48,15 +50,17 @@ These hold regardless of the binary version; see [references/contracts.md](refer
 
 ## 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.
+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>`. `things deadlines` is the deadline horizon — every item (to-dos AND projects) that HAS a deadline, in deadline order, most-overdue first; it is a derived query view, NOT reorderable, and repeating items appear at their next occurrence's projected deadline. Scope it with `--today` (only what's due in Today), `--overdue` (only items already past their deadline), and `--project`/`--area`/`--tag`. 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`.
+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).
 
 **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.)
+**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…> [--start|--end|--before <ref>|--after <ref>] [--in <target>]` is the ONE reorder verb across ALL kinds — to-dos, projects, a project's headings, AND sidebar areas — dispatching the protocol by kind. All refs must be one KIND (only to-dos and projects intermix, and only on the shared Today/Evening/day axes); a mixed-kind set, a cross-container set, a cross-axis anchor, and a non-member each fail closed with one precise message. Reorder is variadic (selection order = landing order); an anchor POSITIONS but never MIGRATES. 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 — to-dos/projects only). Reordering a HEADING runs the native heading-block wire (children follow); an archived heading is reorderable but repositioning it brings it back to open (disclosed). `things project move-heading` (cross-project moves / demotion) and `things area reorder` remain as kind-specific spellings. The axes, gates, #V11 heading policy, and automatic fallbacks are in [references/ordering.md](references/ordering.md). (MCP exposes this as the single `reorder` tool.)
+
+**Resolution timestamps** (`--created-at` / `--completed-at`, both to-dos and projects; ISO date or datetime — a bare date is NOON in the effective zone): `add --completed-at <iso> [--created-at <iso>]` creates the item already RESOLVED in the Logbook (the history-import / GTD-migration path); `add --created-at <iso>` alone is born-open with a backdated creation. On an EXISTING item, `update --created-at` rewrites creation (any status); `update --completed-at` rewrites the completion timestamp of an ALREADY-resolved item (a canceled one stays canceled) — an OPEN item is refused, pointing you at `complete --completed-at` (resolve-and-backdate completed) or `cancel --completed-at` (resolve-and-backdate canceled; the "Completed on" stamp applies to canceled items too). Backdating a resolved item can be a multi-leg, non-atomic sequence — the leg list is disclosed in the result and in `--dry-run`. A project `add --completed-at` cannot seed open `--todo` children (a completed-project import needs every child resolved).
 
 **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).
 
@@ -64,7 +68,7 @@ Namespaced verb families — run `things <group> --help` for the verbs and `thin
 
 ## Going deeper
 
-- [references/model.md](references/model.md) — the full data model, `stage`/`when` derivation, the compact/full tiers, view membership, and filters.
+- [references/data-model.md](references/data-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.

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

@@ -6,10 +6,9 @@ The apiVersion-stable contracts that hold regardless of which binary version you
 
 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 — only the area-grouped `anytime`/`someday`). Never `.items` at the top level. Item UUIDs are in `.uuid`, not `.id`; emitted UUIDs are always full.
-- **The composite cards are flat.** A `project show` `view` is `{ project, headings, items, logbook, openChildrenWhileResolved?, openChildrenUnderArchivedHeading? }`: `items` is ONE flat list of every live child (index order, each carrying `stage`/`when` and, when under a heading, its `heading` ref); `headings` is the flat catalog of EVERY heading `{uuid, title, archived?}` in index order; `logbook` is one flat `stopDate DESC` list of all logged children (each with its `heading` ref). An `area show` `view` is `{ area, projects, items }`: `items` is the flat direct-to-dos (index order), `projects` the child-project rows (sidebar order). Reconstruct a heading's members by filtering `items` (or `logbook`) on the `heading` ref. There are no `anytime`/`upcoming`/`someday` card buckets and no `logbookHeadings` — the terminal re-derives the GUI's grouped layout from these flat rows.
-- **Container refs and `type`.** A row's `area`/`project`/`heading` is a bare **title string**; a flat sibling `areaUuid`/`projectUuid`/`headingUuid` appears **only when that title would not resolve back** to the exact same item. **To act on a ref, pass `.areaUuid // .area`** (same for project/heading). For unattended pipelines or stored refs, use `--full` and key on uuids (the full tier always emits the `*Uuid` siblings). **Absent `type` = to-do** — `type` is present only for a `project`, `heading`, `area`, or `tag` ROW/candidate. A `headings[]` catalog entry drops `type` (its slot states it is a heading) and emits a presence-keyed **`archived`** (the archive timestamp, present iff archived) instead of any status/stage — a heading is archive/unarchive only, never completed/canceled. Every heading, live or archived, is a catalog entry; a swept archived heading's logged children ride the flat `logbook` (with their `heading` ref).
-- 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.
+- Results are in `.data`, in exactly one of five wrappers named by `kind`: `.data.item` (one entity), `.data.view` (an area/project card), `.data.items` (a flat list), `.data.sections` (a list split into named sections), or `.data.children` (the `today` view's two keyed buckets `{ today: {items, total?}, evening: {items, total?} }`). Never `.items` at the top level. Item UUIDs are in `.uuid`, not `.id`; emitted UUIDs are always full. The `today` view's whole-view count rides `meta.counts` (`{dueOrOverdue, other}`), not `data`.
+- **Container refs and `type`.** A row's `area`/`project`/`heading` is a bare **title string**; a flat sibling `areaUuid`/`projectUuid`/`headingUuid` appears **only when that title would not resolve back** to the exact same item. **To act on a ref, pass `.areaUuid // .area`** (same for project/heading). For unattended pipelines or stored refs, use `--full` and key on uuids (the full tier always emits the `*Uuid` siblings). **Absent `type` = to-do** — `type` is present only for a `project`, `heading`, `area`, or `tag` ROW/candidate (a `project show` `headings[]` entry drops it — its slot already states it is a heading, and it emits a presence-keyed **`archived`** — the archive timestamp, present iff archived — instead of any status/stage; a heading is archive/unarchive only, never completed/canceled). **A `project show` view is `data.view = { project, children, headings[] }`** (read-shape v2): `children` is the un-headed body's stage buckets `{ anytime: {items, total?}, upcoming: [{when, items, total?} …], someday: {items, total?}, logbook: {items, total?} }` (the `upcoming` day-block array ends with a `{when: null, items}` resting block when a container holds date-less recurring templates); `headings[]` is EVERY heading in order — open, archived-unswept, AND archived-swept — each `{ uuid, title, archived?, children }` with the same recursive `children`. A swept heading's logged children ride ITS `children.logbook`; there is no `logbookHeadings` and no root `logbook` (the GUI's merged logbook region is TTY-only). **An `area show` view is `data.view = { area, children, projects }`** (read-shape v2): `area` is the area node (or `null` for the `loose` pseudo-area); `children` is the area's DIRECT to-dos as three stage buckets `{ anytime: {items, total?}, upcoming: [{when, items, total?} …], someday: {items, total?} }` (same `{when: null, items}` resting-block rule; NO `logbook` key — read an area's archive with `things logbook --area <ref>`); `projects` is the child-project rows as ONE record `{items, total?}` (a mixed-stage listing keeping each row's `stage`/`when`). A capped scope carries its inline `total` — `children.anytime` for `--area-limit`, `projects` for `--project-limit`; this view emits no `meta.truncation.blocks`. **The global `things upcoming` view is `data.sections = [{when, items, total?} …]`** (read-shape v2 PR 4): chronological DAY BLOCKS keyed by `when` (an ISO date — also the `--in <when>` reorder token), each the complete global day scope, then a trailing `{when: null, items}` block of date-less recurring templates when any exist. Rows KEEP `stage` (the view is mixed — future-dated `upcoming` rows beside deadline-forecast `anytime`/`someday` rows at their deadline day) and drop `when` inside their block (a scheduled row's `when` is the block key). To flatten: `.data.sections[].items[]`. A capped day block (the `--limit` cut straddled it) carries its inline `total`; the whole-view `shown/total/limit/truncated` rollup rides `meta.truncation` (no `blocks`). **The global `things anytime` / `things someday` views are `data.sections = [{ area, items, total? } …]`** (read-shape v2 PR 5): area-grouped sections in sidebar-rank order, `area` the area node (or `null` for the loose section). Each section's `items` are its flattened rows (area-direct/loose to-dos, then each project row with its capped children); the section carries its inline `total` iff those `items` were capped (by `--area-limit` / `--project-limit`). To flatten: `.data.sections[].items[]`. **NO view emits `meta.truncation.blocks[]` any longer — it is retired from the wire entirely (PR 5); per-bucket completeness is always the inline `total`.**
+- Check `meta.truncation.truncated` before concluding "no match" or "that's everything": it is `true` exactly when any row was hidden (`shown < total` on the whole-view rollup, or any bucket's inline `total` exceeds its shown `items`). Raise `--limit` (or `--area-limit`/`--project-limit` on the grouped views) / `--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)

package/skills/things-cli/references/{model.md → data-model.md}

@@ -17,7 +17,7 @@ Entities, relationships, and how the sidebar views are computed over them, as ex
 
 - A to-do has at most ONE container, and may have none — standalone to-dos (no project, no area) are normal and appear at the top level of Anytime/Someday/Upcoming. Moving changes the container; completing or trashing does not.
 - The **Inbox is a state, not a container**: "in the Inbox" means untriaged — no container AND no schedule. Filing or scheduling an inbox to-do moves it out (filing promotes it to Anytime); moving a to-do TO the Inbox clears both its container and its schedule.
-- A heading is a section label inside one project — not a task. It cannot be scheduled or tagged, and its lifecycle is **archive/unarchive ONLY** — a heading is never completed or canceled (it has no canceled state). In a `project show` view every heading (live and archived) is an entry in the flat `headings` catalog `{uuid, title, archived?}` — it carries no `status`/`stage`, and emits a presence-keyed **`archived`** (the ISO archive timestamp) when archived, absent when open. A heading's members are not nested under it: they ride the flat `items` (live children) and `logbook` (logged children) rows as a `heading` ref, so you reconstruct a heading's contents by filtering those lists on the ref. Deleting/archiving a heading affects only the label, per the operation's contract.
+- A heading is a section label inside one project — not a task. It cannot be scheduled or tagged, and its lifecycle is **archive/unarchive ONLY** — a heading is never completed or canceled (it has no canceled state). In a `project show` view (read-shape v2) a heading is an entry of `headings[]` — `{ uuid, title, archived?, children }` — carrying no `status`/`stage`; it emits a presence-keyed **`archived`** (the ISO archive timestamp) when archived, absent when open. ALL headings live in that one `headings[]` array in order regardless of lifecycle class — open, archived-unswept, AND archived-swept; sweep state is NOT on the wire. A swept heading simply carries `archived` and its logged children ride ITS `children.logbook`; the GUI's grouping of swept headings into the logbook region is TTY-derived from that, not a separate wire array. Deleting/archiving a heading affects only the label, per the operation's contract.
 - Tag inheritance flows downward: area → project → (through heading) → to-do. A to-do's *effective* tags = own tags ∪ project tags ∪ area tags. List output distinguishes own vs inherited tags.
 - **Status**: open → completed or canceled (both land in the Logbook) or trashed (Trash; restorable until emptied). Reopen brings a logged item back.
 - **when** (`today | evening | anytime | someday | YYYY-MM-DD`) controls which view an item appears in; **deadline** is an independent due date shown alongside the item; **reminder** is a time-of-day alert attached to a dated when.
@@ -29,20 +29,22 @@ Entities, relationships, and how the sidebar views are computed over them, as ex
 
 - **inbox** — untriaged to-dos (no container, no schedule).
 - **today** — items scheduled for today, with the **This Evening** section beneath.
-- **upcoming** — future-dated items, forward-ordered by date.
-- **anytime** — all active items kept without a specific date (standalone or filed).
-- **someday** — items deliberately kept without a date.
+- **upcoming** — future-dated items, forward-ordered by date. JSON returns `data.sections = [{when, items, total?} …]` — chronological day blocks keyed by `when` (an ISO date), then a trailing `{when: null, items}` block of date-less recurring templates when any exist (flatten with `.data.sections[].items[]`).
+- **anytime** — all active items kept without a specific date (standalone or filed). JSON returns `data.sections = [{area, items, total?} …]` — area-grouped sections (sidebar-rank order; `area` is `null` for the loose section), each carrying its inline `total` iff its rows were capped by `--area-limit`/`--project-limit` (flatten with `.data.sections[].items[]`).
+- **someday** — items deliberately kept without a date. Same `data.sections = [{area, items, total?} …]` shape as anytime.
 - **logbook** — completed/canceled items.
 - **trash** — trashed items (restorable until the trash is emptied).
 
+Beyond the sidebar mirror, **`things deadlines`** is a derived query view (not an app sidebar list): one flat `data.items[]` of every LIVE item — to-dos AND projects — that carries a deadline, ordered `deadline` ASC (most-overdue first), tie-broken by Today order then uuid. Its `stage` is KEPT (stage-mixed, like `search`/`changes`). It is presentation-ordered and **NON-SCOPE** — deadline order IS the view, so it is not reorderable (`reorder --in deadlines` is refused). A dismissed deadline nag does NOT hide a row here (dismissal only affects the Today pull, not the deadline). Deadline-bearing repeating items are PROJECTED at their next occurrence's deadline (the same projection the `upcoming` view uses); a deadline-less or unprojectable template is left out. Filters: `--today` (only current Today members, This-Evening included), `--overdue` (only open items already past today — never projections), `--project`/`--area`/`--tag`, `--limit`/`--all`. MCP: `read_view deadlines` with `today`/`overdue`/`project`/`area`/`tag` params.
+
 `things projects`/`areas`/`tags` list containers; `things projects <ref>` / `things areas <ref>` / `things show <ref>` show one item's full detail — notes, checklist, effective tags — which the compact list rows do NOT display.
 
 ### Reading view membership from JSON — `stage` and `when`
 
 Reads decompose an item's position onto two derived, presence-keyed words (they REPLACED the old `start`/`startDate`/`logged`/`trashed`/`todaySection` wire fields, which no longer appear):
 
-- **`stage`** — the sidebar BUCKET: `inbox | upcoming | anytime | someday | logbook | trash`. Read view membership off it directly. It is dropped inside a section/catalogue that provably states it (the stage-pure `inbox`/`anytime`/`someday`/`logbook`/`trash` lists and the `today` view) and kept everywhere it is stage-mixed (the mixed `upcoming` catalogue, `search`, `changes`, the projects/areas listings, the project/area card `items` and the project `logbook`, 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 is one flat `data.items` list (no `sections`); each row's `when` marks Today-proper vs This-Evening, and the whole-view count rides `meta.counts` (`{dueOrOverdue, other}`).
+- **`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.
 - `provisional: true` marks a Today member the app has not yet materialized — see [banner.md](banner.md).
 
@@ -53,9 +55,9 @@ Every row comes back at one of two densities, selected by view kind + flag, neve
 - **Compact** (the list default) keeps identity + structural + non-default facts. A field at its default is OMITTED, so absence = the default: no `status` = open, no `checklist` = none, no `todos` = no child to-dos, no `when` = not in Today and unscheduled, no `provisional` = materialized. The full `notes` string is dropped and replaced by presence-keyed `hasNotes: true`; `startDate`, `created`, and `modified` are dropped.
 - **Full** (`show`/`detail`, or a list forced with `--full`) is the whole record — the complete `notes`, the raw `startDate` substrate behind `when`, the checklist `items` array, and timestamps.
 - Compact rows still carry the useful summaries: `checklist:{open,total}` on a to-do, `todos:{open,total}` on a project (app-maintained leaf-action counts — never headings, checklist items, or trashed rows), and `match:{field,text}` on a `search` hit whose match was NOT the title (`field` ∈ `heading | notes | checklist`).
-- **Container absence rule:** inside a single-container node (a project/area card, an `anytime`/`someday` section) an item omits any ancestry the node already states, so absent `project`/`area` 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). **The project view is the exception where a `heading` ref is self-describing state:** a project-view row (the flat `items`, and a `logbook` row) that lives under a heading KEEPS its `heading` ref even in compact, because membership is a per-row attribute, not a bucket — so a swept child of an ARCHIVED heading is a flat `logbook` row carrying its `heading` ref (no more nested group). **Two-view sublabel asymmetry:** that in-project `logbook` row's `heading` labels the HEADING, while the same row in the GLOBAL `logbook` view is labeled by its PROJECT instead.
+- **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 sub-object whose kind is fixed by its slot (a `project show` heading GROUP node) drops `type` too, since its position already states it is a heading.
+- **`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.
 
 ## Filters over views
 

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

@@ -21,15 +21,24 @@ The SKILL.md summary is enough for most calls; this page is the full contract. E
 
 ## Reorder — changing arrangement
 
-`things reorder <refs…> [--first | --last | --before <ref> | --after <ref>] [--in <target>]` is the ONE kind-neutral in-place verb (it replaced the old `todo reorder` subcommand and the raw `reorder --scope`). It rearranges to-dos AND the project rows the Today/Evening/day lists intermix with them.
+`things reorder <refs…> [--start | --end | --before <ref> | --after <ref>] [--in <target>]` is the ONE reorder verb across EVERY kind — to-dos, projects, a project's headings, AND sidebar areas — dispatching the protocol by kind (it replaced the old `todo reorder` subcommand and the raw `reorder --scope`). All refs must be one KIND; only to-dos and projects intermix, and only on the shared Today/Evening/day axes.
 
-- **Bare (no position)**: the named items assemble as ONE block at the EARLIEST one's current slot, in argument order (`--first` is NOT implied). Partial selection is fine — unmentioned siblings keep their order.
-- **Positioned**: `--first`/`--last` send the block to the top/bottom of its bucket; `--before <ref>`/`--after <ref>` place it relative to an anchor.
+- **Bare (no position)**: the named items assemble as ONE block at the EARLIEST one's current slot, in argument order (`--start` is NOT implied). Partial selection is fine — unmentioned siblings keep their order.
+- **Positioned**: `--start`/`--end` send the block to the start/end of its scope; `--before <ref>`/`--after <ref>` place it relative to an anchor.
 - **Selection order = landing order** (reverse by naming the refs backwards).
-- **Mixed to-do + project refs are allowed** in the Today/Evening/day buckets those kinds share; elsewhere reorder operates within one container+bucket.
+- **Mixed to-do + project refs are allowed** in the Today/Evening/day buckets those kinds share; elsewhere reorder operates within one container+bucket. A heading or area NEVER mixes with another kind — a mixed-kind set is refused with one message.
 - **Deadline-forecast rows sort on their Upcoming day too (projects too).** A someday/anytime to-do OR project with a future **deadline** and no start date renders in the Upcoming block on its deadline day. `things reorder` treats it as a first-class member of that day-group: it sorts on the same axis as the day's scheduled rows and interleaves with them, so you can reorder a mixed set of scheduled rows, deadline-forecast to-dos, and deadline-forecast projects in one call. This works with `allow-experimental` OFF — it rides a public-URL deadline-cycle, not the private surface (still gated by `bounce-enabled`, like every multi-leg reorder). An INBOX to-do that merely carries the same deadline is NOT on that day's axis and is refused with a message saying so (schedule it, or take it out of the Inbox, first).
+- **Resolved to-do movees (LOGSORT ORD-13):** an UNSWEPT completed/canceled to-do — one still struck-through in its live container body, before the Logbook sweep boundary — CAN be reordered in place: it re-ranks by index only, staying resolved (no reopen). This is permitted ONLY on the pure-native index reorder (a project/area/inbox/someday re-rank, which needs `allow-experimental` ON); a mixed OPEN + unswept-resolved set is fine. A SWEPT completed/canceled to-do (a Logbook resident) is refused, pointing at `things todo reopen` (reactivation) or `--completed-at` (to re-date it in the Logbook — sort order can't express Logbook re-dating). An unswept-resolved movee that would have to ride an uncertified path (a bounce/move fallback — e.g. `allow-experimental` OFF — or an `--in <date>` day-axis target) is likewise refused, telling you to reopen it first.
 
-Sibling verbs for the two things `reorder` does NOT touch: `things project move-heading` reorders a project's HEADINGS; `things area reorder` reorders the sidebar AREAS.
+Headings and areas are now first-class `reorder` operands (see the two sections below); the kind-specific spellings `things project move-heading` (which ALSO does cross-project moves / demotion — the placement verb) and `things area reorder` (a single sidebar area) remain.
+
+## Reordering a project's headings (#V11)
+
+`things reorder <heading-refs…> --start|--end|--before <h>|--after <h>` re-ranks a project's headings in place, dispatching onto the certified native heading-block wire (children follow their heading). All headings must be in ONE project (cross-project is refused). `--in` does not apply (a heading has no stage/day/view axis). Archived headings (completed — unswept OR swept) are reorderable UNGUARDED, exactly like the GUI: the engine composes the minimal wire so an archived heading that need not move stays untouched, but when the target order forces an archived heading to move it PROCEEDS and DISCLOSES that repositioning it brought it back to open (result warning + `--dry-run` leg plan) — never silent. `things project move-heading` remains for cross-project moves and demotion.
+
+## Reordering sidebar areas
+
+`things reorder <area-refs…> --start|--end|--before <area>|--after <area>` re-ranks sidebar areas. This drives the local Things app (a sidebar drag), so it needs `--dangerously-drive-gui` plus `things config set ui-enabled true`; a set of areas is a sequence of drags (non-atomic, disclosed). An area reorder needs a position (there is no bucket to assemble a block in). `things area reorder <ref>` is the single-area spelling.
 
 ## Anchors POSITION, never MIGRATE
 
@@ -44,11 +53,13 @@ A Today/Evening member has TWO order slots: its slot in the Today VIEW (`todayIn
 - `--in` accepts `today | evening | anytime | someday | inbox`, a project/area/heading ref (uuid or unique title), `upcoming` (the one future day the whole set shares), or a `YYYY-MM-DD` day-block. `loose` is refused (it is a read view, not a bucket).
   - `--in <YYYY-MM-DD>` names one exact Upcoming day-block: every movee must be on that day (scheduled for it, or carrying it as a deadline) and the date must be strictly future (a today/past date is refused, pointing you at `--in today`). `--in upcoming` is the proxy — it derives the single future day the set shares and refuses (listing the per-item days) if they span days. Neither needs a shared container — a day-block is ONE cross-container sortability bucket.
   - `--in someday` / `--in anytime` reorder within a shared container's stage list: every movee must BE that stage AND they must share one direct container (same project, heading, area, or all loose), else it is refused naming the mismatch. `--in inbox` needs only that every movee is inbox-stage.
-  - **One KIND per index token.** A stage-list token (`anytime`/`someday`/`inbox`) or a container ref sorts each object kind in its own order-space, so all movees must be the SAME kind — a mixed to-do + project set is refused naming each movee's kind, *even when they share a container* (an area's someday to-dos and someday projects are different index buckets). The `today`/`evening`/`upcoming`/`<YYYY-MM-DD>` day-and-view tokens are the exception: those axes intermix to-dos and projects. A **heading** has no stage/day/view order of its own — it is never a member of any of these buckets, so a heading movee is refused on every token, pointing you at `things project move-heading`.
+  - **One KIND per index token.** A stage-list token (`anytime`/`someday`/`inbox`) or a container ref sorts each object kind in its own order-space, so all movees must be the SAME kind — a mixed to-do + project set is refused naming each movee's kind, *even when they share a container* (an area's someday to-dos and someday projects are different index buckets). The `today`/`evening`/`upcoming`/`<YYYY-MM-DD>` day-and-view tokens are the exception: those axes intermix to-dos and projects. A **heading** has no stage/day/view order of its own, so `--in` never applies to a heading set — reorder headings without `--in` (they dispatch onto the project's heading axis; see "Reordering a project's headings" above).
   - The container form of `--in` is POLYMORPHIC — it tries project → area → heading — so a heading whose title is shadowed by a project or area of the same name would resolve to the wrong kind. Pin it with the heading's **decorated ref** `Heading [ref]` (or a bare uuid). Decorated refs (`Title [ref]`) work in every `<ref>` slot: the bracketed uuid/partial-uuid resolves and the title is an ignored comment. A literal title that really contains brackets still wins over the bracket parse (exact-title resolves first).
 - `--in someday` / `--in anytime` / a container ref on a same-day forecast set reorders its CONTAINER index (its someday/anytime list order), never the day-block — the explicit axis is honored, not overridden by the day route.
 - Forcing the container index axis on a Today/Evening member PRESERVES the Today/Evening flag — a flag-safe move protocol routes it off the de-Today path. Only the someday/inbox loose axes still refuse a flagged member (their re-entry cannot preserve the flag).
 
+**A Today reorder preserves the rest of Today's grouping.** The Today view groups rows by the day each ENTERED Today (its entry cohort), newest first, then manual order within a cohort. The app's native Today reorder can only pull a named row up to *today*'s cohort, so `things reorder` composes the MINIMAL wire that realizes your placement — it names only what must move, and every other Today row keeps its entry cohort and its visible position untouched. A `--first`/`--start` moves the named row(s) to the visible top, re-dating only THEIR entry cohort to today (inherent, expected). A `--before`/`--after`/`--end` that reaches across the grouping has to name the co-listed rows ABOVE the drop point too, which re-stamps THEIR entry cohort to today (changing only their Today grouping, never their schedule) — the result `warnings` + `--dry-run` disclose how many co-listed rows that is, so a broad cohort re-date is never silent. (A container reorder — project/area/heading/inbox/someday — has no entry-cohort dimension, so this note is Today/Evening-only.)
+
 ## Mixed-stage move placement
 
 A `move` selection spanning stage sub-buckets (anytime + scheduled + someday + templates):
@@ -85,4 +96,4 @@ Everything non-template is sortable on every guaranteed surface above.
 
 ## MCP parity
 
-The MCP server exposes reorder as two tools: **`reorder`** (the planner form — `refs`, an optional position, an optional `in` axis) mirrors `things reorder`, and **`reorder_areas`** mirrors `things area reorder` (sidebar areas, with the same two-key GUI gate). Both call the same library entries the CLI does, so the dual-axis refusal, the flag-safe routing, and the automatic fallbacks behave identically.
+The MCP server exposes reorder as the single **`reorder`** tool — `refs`, an optional position (`start`/`end`/`before`/`after`), an optional `in` axis, and `dangerously_drive_gui` for area drags — mirroring `things reorder` across every kind. It calls the same library entry the CLI does, so the kind dispatch, the mixed-kind / cross-container / cross-axis refusals, the #V11 heading disclosure, the dual-axis refusal, the flag-safe routing, and the automatic fallbacks behave identically. (`reorder_areas` was folded into this tool and removed — plan PR D.)