things-api 0.18.0 → 0.19.0

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

@@ -7,5 +7,6 @@ Curated rendering facts — the bench loop may compress or relocate these but mu
 - **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 checkbox/status, title, tags, deadline, and small marker chips — the Today ★, This Evening ⏾, and (in the Today view only) the provisional `•` "new item" pip, plus has-notes / reminder / checklist glyphs (`things legend` names them all). The **notes TEXT and checklist CONTENTS are invisible until the user opens the item**. Put must-see-at-a-glance information in the title; supporting detail belongs in notes. Projects carry the same Today ★ / This Evening ⏾ pips as to-dos. Why some chips vanish once a row's date goes stale — the reminder bell, the This-Evening section, and the provisional pip — is in [banner.md](banner.md).
 - **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).
+- **An open card renders the notes as markdown, with the syntax characters left in place** — headings, bold/italic, code spans, fenced blocks, and `-`/numbered lists take on their formatting while the user still sees the `#`, `**`, backticks, and dashes that produced it. Write notes the user will read as source AND as formatting: no huge heading stacks, and no `[label](url)` (a bare URL links itself; the label form stays literal). See [data-model.md](data-model.md) for the full construct list.
 - **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/repeating.md

@@ -2,6 +2,12 @@
 
 A repeating item is a **template** plus the **instances** it spawns. The template holds the rule (how often, on what calendar day, with what deadline/reminder/end bound); each occurrence the app materializes is a separate to-do (or project) you complete normally. Completing an instance never touches the template; the template keeps spawning the next occurrence on schedule.
 
+**Telling the two halves apart in output.** On a TTY both wear the `↻` glyph, in different slots: a TEMPLATE keeps an ordinary checkbox and carries a **blue `↻` in front of its title** (`[ ] ↻ Water plants ‹Jul 8›`, `( ) ↻ Weekly review`); an INSTANCE is an ordinary checkable row with a **muted `↻` after the title**, in the marker cluster beside `≡`/`◷`/`≔` (`[ ] Water plants ↻ ≡`). In `--json` the same split is presence-keyed: a template carries a `repeating` object, an instance carries a flat `instanceOf: <templateUuid>` (the template's uuid — pass it to the repeat verbs), and a plain row carries neither. `things legend` lists both marks.
+
+## Finding a series in the first place
+
+`things repeaters` lists every repeating series in the library — to-dos and projects — with its uuid, its next occurrence, its container, and its decoded rule. Reach for it before any repeat write, because a template is invisible to every other read: the list views show the OCCURRENCES a series spawns rather than the series itself, and `search` matches those occurrences but never the template behind them. Paused and ended series are listed too (each row says which), which is usually the fastest answer to "why has this stopped appearing?". `--json` carries the rule structurally under `repeating.rule`; the uuid it gives you is what `reschedule-repeat`, `pause-repeat`, `resume-repeat`, and `show` all take.
+
 ## The verbs
 
 - `things todo make-repeating <ref> --frequency … --interval …` — turn an existing plain to-do into a repeating series. This **REPLACES the item**: the original to-do disappears and a fresh template takes its place, so the uuid you get back is the TEMPLATE's, not the original's. Cannot be undone through the normal path (the original is moved to the Trash; `things undo` removes the new series and restores it).

package/skills/things-cli/references/tag-cleanup.md

@@ -0,0 +1,64 @@
+# Mass tag cleanup — reshaping a tag vocabulary without flooding the timeline
+
+A tag cleanup ("we have 40 tags, six of them mean the same thing") touches hundreds of items, and the naive version re-dates every one of them: `things changes --since <moment>` — and any watcher or sync-driven review keyed on the modification date — then reports the whole library as freshly changed, burying whatever really happened that day.
+
+It does not have to. **Two of the three moves cost nothing on the timeline, and the third has a flag.** Work in that order.
+
+## The three moves, cheapest first
+
+| Move | Command | Timeline cost |
+| --- | --- | --- |
+| **Rename a tag** (merge a synonym into the survivor's name, fix casing, re-word) | `things tag update <ref> --title "<new>"` | **none** — the assignment stores the tag's identity, not its text, so no member item is touched. Existing assignments follow the rename. |
+| **Delete a tag** (retire it everywhere, including its whole nested subtree) | `things tag delete <ref> --dangerously-permanent [--acknowledge-subtree]` | **none** — the tag is removed from every item without re-dating any of them. Permanent: tags do not go to the Trash. |
+| **Apply or remove a tag on items** (`--set` replaces the tag set, `--add` merges) | `things todo tags <uuid> --add "<tag>"` / `things project tags <ref> --set "<a>,<b>"` | **one re-date per item** — this is the only move that lands on the timeline, and the only one that wants `--preserve-modified`. |
+
+So: **reshape the vocabulary first, re-tag items last.** A rename that turns `errands`, `Errand`, and `errand-run` into one surviving tag costs nothing; every item you can leave alone by renaming instead of re-tagging is an item that never reaches the timeline.
+
+## The recipe
+
+1. **Look before you write.** `things tags` lists the hierarchy; `things anytime --tag <name> --all --json` (or `things search`) enumerates what a tag actually holds. Decide which tag survives.
+2. **Rename the survivor into the name you want** (`tag update`), rather than creating a new tag and re-tagging into it. Free.
+3. **Fold the synonyms.** For each doomed tag, the items that carry it and NOT the survivor need the survivor added — this is the only pass that re-dates anything, so run it with `--preserve-modified`. One item at a time:
+   ```sh
+   things todo tags <uuid> --add "errand" --preserve-modified
+   ```
+   For hundreds of them, `things batch` is the vehicle: it takes `--preserve-modified` at the RUN level, applying it to every line, and the whole submission comes back under one `undoToken`. The batch op is `todo.set-tags`, which REPLACES the tag set (there is no per-line merge — `--add` is CLI sugar over a read), so build each line's full set from the item's current tags:
+   ```sh
+   # anytime is a SECTIONED view (data.sections[].items[]); item tags are
+   # {title} objects, and todo.set-tags wants a flat list of titles.
+   things anytime --tag "Errand" --all --json \
+     | jq -c '.data.sections[].items[]
+         | select(.type == "to-do")
+         | {op: "todo.set-tags",
+            params: {uuid, tags: ([(.tags // [])[].title] - ["errand"] + ["errand"])}}' \
+     | things batch --preserve-modified
+   ```
+   (Project rows carry their own tags — filter them out as above and re-tag them with `project.set-tags` in a second pass, or drop the `select` and branch the `op` on `.type`.)
+   Each line's result carries `preservedModified` (and `preserveFailures` for any restore that did not land), so you can see the pass stayed silent. A single line can opt back onto the timeline with its own `"options": {"preserveModified": false}` — the per-line value always outranks the run flag. Add an `"opId"` per line if you want a stopped batch to be resubmittable verbatim.
+4. **Delete the doomed tags** (`tag delete … --dangerously-permanent`, plus `--acknowledge-subtree` when the tag has children — deleting a parent deletes its whole subtree). Free, and it also removes the tag from anything you missed in step 3, so a stray assignment does not survive as a ghost.
+5. **Check the timeline you were protecting**: `things changes --since <the moment you started>` should show only what you meant to surface.
+
+## `--preserve-modified` in one paragraph
+
+It captures each pre-existing edited item's modification date before the write and restores it (to the whole second) afterwards, so the edit does not surface in `changes`. It is universal — every write verb takes it — and a no-op on a pure create. The restore is best-effort: a failure is reported per item and the change itself still stands, so a cleanup never half-applies because a restore missed. It is **safe against a synced library**: the restored date propagates to your other devices and survives the round-trip, so the item stays off the timeline everywhere; the one edge is a genuinely concurrent edit to the same item on another device, which re-dates it through Things Cloud's per-attribute merge — the edit resurfaces rather than being silently hidden (SYNC2B).
+
+Full contract: the `--preserve-modified` bullet in [../SKILL.md](../SKILL.md); per-operation detail in `things <verb> --help`.
+
+## The adjacent cleanup: retiring an area
+
+The same "make the free move first" logic applies to an `(archived)`-style area you want to dissolve. **Deleting an area treats its members by status:**
+
+- an **open** direct member (to-do or project) is moved to the **Trash** and re-dated;
+- a **logged** member (completed or canceled) is merely **detached** — its area link is cleared, it stays live in the Logbook, and it is **not** re-dated.
+
+So deleting a long-dead area full of finished work is mostly free: the history stays in the Logbook, unlinked, off the timeline. Only the open remnants move, and those are exactly the ones you should look at first. Deleting an area is **permanent** (areas do not go to the Trash) and a non-empty one is refused unless you pass `--allow-non-empty`:
+
+```sh
+things area delete "Old Client (archived)" --dangerously-permanent --allow-non-empty --preserve-modified
+```
+
+Preview it first — `--dry-run` reports the plan — and if you want the open remnants kept, move them out before deleting rather than restoring them from the Trash afterwards.
+
+## What this rests on
+
+The laws above are measured, not assumed: the rename/delete/apply modification-date footprint (TAGMOD), the area-delete status-dependent trash-vs-detach split (TAGMOD-T4, refining AREADEL), and the sync round-trip that makes the restore safe on a real Things Cloud account (SYNC2B). The evidence lives with the project's lab documentation, indexed by those names.