things-api 0.12.0 → 0.14.0

package/schema/envelope.schema.json

@@ -96,7 +96,7 @@
         },
         "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."
+          "description": "The read's completeness metadata (the single truncation shape) — the WHOLE-VIEW rollup. Present on any read that could drop rows — flat views (row `limit`), the `today` view, and grouped views (anytime/someday/`area show`). Per-bucket completeness rides INLINE on the data records' own `total` (R1), never on this envelope. `meta.truncation.truncated` is the universal \"did I see everything\" check."
         },
         "resolvedCommand": {
           "type": "string",
@@ -144,6 +144,20 @@
           "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)."
         },
+        "counts": {
+          "type": "object",
+          "properties": {
+            "dueOrOverdue": {
+              "type": "number"
+            },
+            "other": {
+              "type": "number"
+            }
+          },
+          "required": ["dueOrOverdue", "other"],
+          "additionalProperties": false,
+          "description": "Whole-view aggregate counts (ADDITIVE). Present ONLY on the `today` view: the app's sidebar count split — `dueOrOverdue` (open members whose deadline is due or overdue) vs. `other` (the rest). A convenience aggregate an agent would otherwise recompute over the rows; it lives here so `data` stays pure domain rows. Both counts are OPEN members only, and a `0` is meaningful."
+        },
         "scope": {
           "type": "object",
           "properties": {
@@ -184,87 +198,11 @@
         },
         "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."
+      "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\nThis is the WHOLE-VIEW rollup only. Per-bucket completeness rides INLINE on the data records (read-shape v2 R1): each `children`/`sections`/`projects` bucket carries its own `total`, present iff it was capped. The pre-v2 `blocks[]` descriptor-join sidecar is RETIRED from the wire entirely (doctrine v2 PR 5) — the per-block detail the TTY renderers need is internal render plumbing ( {@link  GroupBlock } ), never serialized."
     },
     "ErrorEnvelope": {
       "type": "object",

package/skills/things-cli/SKILL.md

@@ -1,12 +1,12 @@
 ---
 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
+version: 0.14.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`.
 
@@ -32,15 +32,17 @@ Reads decompose an item's position onto two derived, presence-keyed words (they
 
 ## 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).
+Commands take a `<ref>`: a UUID, a unique UUID prefix (≥ 6 chars), a Things share link, a (unique) title, or a **decorated ref `Title [ref]`** (the bracketed uuid/partial-uuid resolves; the title is an ignored comment, so a stale copy still works). Ambiguous refs fail with the candidates listed, each rendered in the fused `Title [8charPrefix]` form you can paste straight back — 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).
+
+**Container refs and the `type` shorthand in `--json`.** A row's container ref (`area`/`project`/`heading`) is a bare **title string**; a flat sibling `areaUuid` / `projectUuid` / `headingUuid` appears **only when that title alone would not resolve back** to the exact same item (a duplicate title, or a title that shadows a UUID). **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 always emits the `*Uuid` siblings). And **absent `type` = to-do** — a row omits `type` when it is a to-do; it is present for `project`, `heading`, `area`, and `tag`.
 
 ## 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.
+- **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`), 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`).
+- **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.
 - If the user requests a JSON reply schema, return exactly that object after the read or checked write.
 
@@ -54,7 +56,9 @@ Namespaced verb families — run `things <group> --help` for the verbs and `thin
 
 **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).
 

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

@@ -6,8 +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). 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.
+- 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/errors.md

@@ -6,15 +6,23 @@ A failed `--json` call carries `ok: false`, `kind: "error"`, and an `error` obje
 
 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.
+- `uuid` and `title` — always. `type` (`"project" | "heading" | "area" | "tag"`) — present for those kinds only; **absent `type` = to-do** (the same convention the item wire uses).
 - 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: []`.
 
+**Fused refs and decorated input.** On a TTY the human candidate lines render each entry in the fused form **`Title [8charPrefix]`** (a duplicate-titled project/to-do candidate also gets a `· started YYYY-MM-DD` tail so recurring twins are distinguishable). That fused string is itself a valid **decorated ref**: `<ref>` slots everywhere (CLI flags, `--to-project` / `--to-heading` / `--area`, MCP args, library refs) accept **`Title [ref]`** — the bracketed segment (a uuid or ≥6-char partial-uuid) is resolved and the title half is an ignored comment, so a stale copy keeps working after a rename. Copy a fused candidate straight back as the ref. A *literal* title that really looks like `Name [abcd1234]` still wins (exact-title resolution outranks the bracket parse); the empty-title form `[prefix]` (a titleless heading) is legal.
+
 **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.
 
+**Read-side liveness (project name resolution).** The SAME live-only law governs names on the read side, so `things "X"` (the bare-ref shorthand) and `things project show X` always agree, and an ambiguity's count always matches its candidate list. A NAME resolves against live (untrashed) rows only; an explicit uuid / partial-uuid still reaches a trashed project (viewing one by id is unchanged). Three read-only consequences:
+
+- **Unique-dead fallback.** A name matching zero live rows but exactly ONE trashed project resolves to it and the view discloses it (the card's `(trashed)` marker / the JSON node's `stage: "trash"`). Several trashed-only twins → not-found with the dead-row hint above.
+- **Trash disclosure on ambiguity.** `"X" matches N projects` counts only live rows (equal to the candidate list); extra trashed twins are disclosed — `… also matched: N in the trash — \`things trash\` lists them, a uuid reaches one directly` — never folded into the count. The error `code` is `ambiguous`, with the live candidates under `detail.candidates`.
+- **Cross-kind merge.** The shorthand's namespace spans to-dos, areas, and projects. A unique winner follows the chain uuid → area → project; but an AMBIGUOUS subject with live matches at more than one kind refuses with the candidates MERGED across kinds (each carries its `type`) — `"X" matches 2 areas and 3 projects — use \`things area show\` / \`things project show\`, or a ref below` — so the shorthand never hides an option the narrower command would show.
+
 Never guess between candidates for a destructive action — inspect details or ask.
 
 ## Guarded writes and their acknowledgments

package/skills/things-cli/references/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, tagged, or completed; deleting/archiving it 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,9 +29,9 @@ 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).
 
@@ -41,8 +41,8 @@ Entities, relationships, and how the sidebar views are computed over them, as ex
 
 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 already states it (the stage-pure `inbox`/`anytime`/`someday`/`logbook`/`trash` lists and the `today` view's sections) and kept everywhere it is not implied (the mixed `upcoming` catalogue, `search`, `changes`, 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`.
+- **`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`, 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,7 +53,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, a heading group) 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).
+- **Container absence rule:** inside a single-container node (a project/area card, an `anytime`/`someday` section, a `project show` `headings[]` entry) an item omits any ancestry the node already states, so absent `project`/`area`/`heading` there means *inherited from the enclosing node*. A mixed list (`inbox`/`today`/`search`/`changes`) still names each row's own `project`/`area` (the `heading` ref is compact-dropped outside a project view; `--full` keeps it). In a read-shape v2 **`project show`** view membership is fully STRUCTURAL: every bucket row — un-headed body children AND rows nested under a `headings[]` entry, INCLUDING each `children.logbook` row — drops its `heading` ref, because its position states it. A swept child of an OPEN heading rides that heading's `children.logbook`; a swept child of an ARCHIVED heading rides the archived heading's `children.logbook`; the GUI's PROJECT-vs-HEADING logbook sublabel is TTY-derived from that structural placement, not from a per-row ref.
+- **Container ref shape:** a container ref is a bare **title string** (`"area": "Family"`, `"project": "Groceries"`, `"heading": "Backlog"`). A flat sibling `areaUuid` / `projectUuid` / `headingUuid` (the full uuid) rides alongside **only when the bare title would not resolve back** to that exact item — a duplicate title in the same resolution scope, or a title that is itself a valid uuid prefix. **To act on a ref, pass `.areaUuid // .area`** (same for project/heading): the uuid when present, else the title. For unattended pipelines or stored refs, use `--full` and key on the uuids — the full tier emits every `*Uuid` sibling unconditionally. A row whose container project is a repeating template carries a flat `projectIsTemplate: true` (the JSON twin of the TTY `↻` glyph) — acting on such a row edits the blueprint, affecting future occurrences, so target the intended copy via `projectUuid` (a same-titled occurrence exists alongside the hidden template).
+- **`type` is presence-keyed:** **absent `type` = to-do.** A row omits `type` when it is a to-do; `type` is present for a `project`, `heading`, `area`, or `tag` ROW (including in the error `candidates` shape). This is scoped to ROWS/candidates — a positional keyed node whose kind is fixed by its slot (a `project show` `headings[]` entry) drops `type` too, since its position already states it is a heading.
 
 ## Filters over views
 

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

@@ -21,14 +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
 
@@ -38,7 +48,14 @@ A `--before`/`--after` anchor only says WHERE in a bucket — it never moves the
 
 A Today/Evening member has TWO order slots: its slot in the Today VIEW (`todayIndex`) and its slot in its own CONTAINER (`index` — a project/area/heading child, or the loose Anytime bucket). When a set (and its anchor) is coherent on BOTH axes and no `--in` is given, the reorder is REFUSED with a message naming both readings and their exact `--in` spellings — this replaces any silent always-Today guess.
 
-- `--in` accepts `today | evening | anytime | someday | inbox`, or a project/area/heading ref (uuid or unique title). `loose` is refused (it is a read view, not a bucket).
+**The forecast day is a second dual axis (§9o dual-citizen).** A deadline-forecast row (someday/anytime, no start date, a future deadline) is BOTH a member of its Upcoming day-block (ordered on `todayIndex`) and a member of its container's someday/anytime list (ordered on `index`). So a set where every movee is a forecast member of ONE shared day AND they all share one direct container (same project/heading/area, or all loose) is dual-axis too: a bare reorder is REFUSED, naming the real date and the container/list spelling. A forecast set that spans containers, or a mix of scheduled + forecast rows on one day, is coherent on only the day axis (the day-block) and auto-routes there — no `--in` needed.
+
+- `--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, 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).
 
 ## Mixed-stage move placement
@@ -60,12 +77,21 @@ Three config knobs (`things config get/set …`) tune ordering; every default gi
 
 **Flag-aware routing (SIT6).** A reorder touching a Today/Evening-FLAGGED row never de-Todays it: the whole touched set swaps to a flag-safe MOVE protocol on the same axis (the `when=` bounce would strip the flag). This is transparent — you still call `things reorder`; the chosen strategy is disclosed in the result.
 
-## Placement guarantees and the one dead class
+## Placement guarantees
+
+"Top of bucket in selection order" is GUARANTEED wherever a lab-clean protocol exists: loose inbox/today/evening/someday/anytime; a project's or area's members (anytime AND someday); a heading's anytime/someday children; any container child's evening slot; area-less someday/anytime projects; and a whole future day-group across containers (including scheduled project rows, area'd ones too, and deadline-forecast rows — to-dos and projects — on their deadline day). The result's placement class names which guarantee you got, and a bounce that co-touches unnamed siblings to honor a `--before`/`--after` anchor lists them.
+
+## Repeating templates in day-blocks
+
+A repeating template's projected occurrence renders in an Upcoming day-block, and `things reorder` can now position it there — with two constraints, because a dated `when=`/`deadline=` leg CRASHES a template so the app's own private surface is the only safe writer.
 
-"Top of bucket in selection order" is GUARANTEED wherever a lab-clean protocol exists: loose inbox/today/evening/someday/anytime; a project's or area's members (anytime AND someday); a heading's anytime/someday children; any container child's evening slot; area-less someday/anytime projects; and a whole future day-group across containers (including scheduled project rows, area'd ones too). The result's placement class names which guarantee you got, and a bounce that co-touches unnamed siblings to honor a `--before`/`--after` anchor lists them.
+- **On TOMORROW, full power.** When a template's next occurrence lands on tomorrow, BOTH to-do and project templates sort inline with the day's scheduled rows in one native `list "Tomorrow"` call — any position, exact order.
+- **On a later future day, to-do templates sort; project templates hold their spot.** A TO-DO template front-inserts via a single-id `list "Upcoming"` native leg interleaved with the day's other rows, so it lands anywhere in the block. A PROJECT template has NO headless reach on a non-tomorrow day (only the Tomorrow call or a manual drag place it), so it stays byte-untouched at the bottom of the block and every other item sorts ABOVE it. A reorder that would need a project template above a movable row (or would re-order two project templates) is REFUSED, naming the arrangement it CAN reach — do that in the app by dragging, or reorder on the day it becomes tomorrow.
+- **Templates need `allow-experimental` on.** Any day-group reorder that includes a template requires the private native surface (the to-do-template leg uses it). With `allow-experimental` off, such a reorder is REFUSED, naming the template(s) — it never silently skips them and never routes them onto a crash-path leg.
+- A template's placement write is `userModificationDate`-SILENT (a sync/watcher keyed on that timestamp will not see the move); the result discloses it.
 
-**The one class that cannot be reordered is a repeating TEMPLATE** — a dated `when=` leg crashes it, so a template movee or anchor is refused and template placement stays app-default (disclosed). Everything non-template is sortable.
+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.)