things-api 0.10.0 → 0.11.0

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

@@ -0,0 +1,41 @@
+# Stable contracts: envelope, exit codes, safety, recurrence
+
+The apiVersion-stable contracts that hold regardless of which binary version you invoke. Mechanics — verbs, flags, per-operation preconditions — live in `things <group> --help` and `things help <topic>` and version with the binary; the contracts here do not.
+
+## JSON envelope
+
+Every `--json` response is an envelope `{ ok, data, meta }`:
+
+- Results are in `.data` (usually `.data[]`), **never** `.items`. Item UUIDs are in `.uuid`, not `.id`.
+- Check `meta.truncation` (and `meta.grouped`) before concluding "no match" or "that's everything": if `shown < total`, raise `--limit` or narrow the filter rather than assuming you saw everything.
+- List/search rows are **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)
+
+- `0` — the change landed and was verified.
+- `2` — usage error: fix your invocation and retry.
+- `3` — verify-failed: the change did NOT stick; the message carries the reason and usually the remediation.
+- other — unexpected; stop and report.
+
+A nonzero exit is informative, not a dead end — it means the write did not silently half-apply, so you are never left guessing whether it took. Read the message; it usually names the fix.
+
+## Safety & recovery
+
+- `--dry-run` previews the exact plan (operation, target, expected change) for ANY write without executing — use it for anything destructive, bulk, or unfamiliar.
+- `things undo` reverses recent changes made through this tool (its own audit trail, not arbitrary app history). Prefer a targeted fix when you know it; undo is the safety net.
+- Deletes are TRASHES: `todo delete` moves to Trash and is restorable (`todo restore`). Emptying the trash is permanent and requires explicit user intent — don't do it unless asked.
+- Ambiguous refs FAIL with the candidates listed — retry with a UUID or a unique prefix. Never guess between candidates for a destructive action; inspect details or ask.
+- Referenced containers and tags must already exist. Create nested structures **outside-in** (area → project → heading → to-do), and prefer each newly returned UUID as the next reference so duplicate titles cannot redirect placement.
+- Some operations are disruptive (may move focus in the app) and require `--allow-disruptive`, **including their dry runs**. `things capabilities` lists each operation's support and any preconditions.
+- If a request needs a capability the tool reports as unsupported, say so plainly rather than improvising through unrelated commands.
+
+## Recurrence (contract summary)
+
+Full rule vocabulary and worked examples: **`things help repeating`**. The stable contract:
+
+- Turning an item into a **fixed** repeater REPLACES it: the original becomes a hidden template plus a fresh first occurrence, so its UUID changes. The response returns a `repeating` block — `instanceUuid` (the visible current occurrence; use it to reach the item), `templateUuid` (the recurring rule; use it for `reschedule-repeat`), and `replacedUuid` (the original). Use these rather than re-finding the item by title.
+- `--after-completion` schedules the next occurrence N units after you complete the current one, and KEEPS the item's UUID.
+- Repeating operations require `--allow-disruptive` (including dry runs) and a required `--interval <n>` alongside `--frequency` (`--interval 1` for every unit).
+- New repeater: add the item first (`things todo add "<title>" --json`), then `things todo make-repeating <returned-uuid> --frequency <f> --interval 1 [--weekdays …] --allow-disruptive`.
+- Multiple weekdays go in ONE rule (`--weekdays monday,thursday,friday`) — never create two repeaters for "every Thursday and Friday".
+- `things show <ref> --json` on an occurrence exposes `repeating.templateUuid` — use it as the `<ref>` for `reschedule-repeat`.

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

@@ -0,0 +1,11 @@
+# How the user sees Things (the app GUI)
+
+Curated rendering facts — the bench loop may compress or relocate these but must never add or change their meaning without Mike's approval (bench/CONSTITUTION.md).
+
+<!-- STATUS: v0 seeded from Mike's description 2026-07-17; awaiting his review pass. -->
+
+- **Sidebar**: top-level views (Inbox, Today, Upcoming, Anytime, Someday, Logbook, Trash), then each **area** with its active **projects** nested beneath it — in the same order this CLI/API reports them. Reordering areas or projects changes what the user sees there.
+- **List rows are compact**: a to-do in any list shows its title, tags, and deadline only. Its **notes and checklist are invisible until the user opens the item**. Put must-see-at-a-glance information in the title; supporting detail belongs in notes.
+- **Project notes** are likewise visible only when the project itself is opened in project view — in lists, a project is just its title (and progress ring).
+- **Today** shows the day's scheduled items, with **This Evening** as a separate section beneath. **Upcoming** is a forward-looking date-ordered calendar of scheduled items. **Logbook** is where completed/canceled items go — after completing something for the user, that's where they'll find it.
+- When telling the user where something landed, name the container and view ("in project P under area A"; "it'll show in Today this evening").

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

@@ -0,0 +1,51 @@
+# The Things data model (deep reference)
+
+Entities, relationships, and how the sidebar views are computed over them, as exposed by the `things` CLI. The SKILL.md "Data model" section is the summary; this is the full version.
+
+## Entities
+
+| Entity | Container | Can contain | Dates | Tags |
+| --- | --- | --- | --- | --- |
+| To-do | area, project, heading, or NONE (standalone) | checklist items | when, deadline, reminder | own + inherited |
+| Checklist item | its to-do | — | — | — |
+| Heading | its project | to-dos | — | none (inheritance passes through) |
+| Project | area or standalone | headings, to-dos | when, deadline | own + inherited from area |
+| Area | top level | projects, loose to-dos | — | own |
+| Tag | tag hierarchy (may nest) | child tags | — | — |
+
+## Rules
+
+- 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.
+- 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.
+- "Overdue" = open with a deadline strictly before today (a deadline of today is "due", not overdue).
+
+## Views (queries over the model)
+
+`things inbox|today|upcoming|anytime|someday|logbook|trash` mirror the app's sidebar. Each is a query over the rules above, not a stored list:
+
+- **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.
+- **logbook** — completed/canceled items.
+- **trash** — trashed items (restorable until the trash is emptied).
+
+`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
+
+When reasoning about which view an item belongs to from `--json`, key on the fields together, not on a single hint:
+
+- `start: "inbox"` → Inbox; `start: "someday"` → Someday; `start: "active"` with no `startDate` → Anytime.
+- A dated open item belongs to **Today** when dated for `meta.clock.today`, otherwise **Upcoming** when future-dated.
+- `todaySection` only describes placement WITHIN Today (e.g. `evening`); it is NOT evidence that an undated item is in Today.
+- Completed/canceled items are in the Logbook and trashed items in Trash, regardless of a stale-looking `logged` field.
+
+## Filters over views
+
+Read filters compose with AND: `--tag <name>` (repeatable) / `--untagged` / `--exact-tag` for tags (in single-container `project show` / `area show` these match the row's own tags; in flat views they include inherited tags), `--overdue` (open items whose deadline is before today), `--limit N`, and `--since`/`--until` where offered. `things search <words>` matches title/notes over open items — widen with `--all`, `--logged`, `--trashed`; narrow with `--type project`. `things changes --since <moment>` is the pull-based substitute for a watch mode. Exact flags per command: `things <group> --help` and `things help filters`.