todo: what the calendar API deliberately cannot write

recurrence, alarms, attendees and EXDATE. all four read correctly and none can
be authored — which is what the agent skill still drops to raw DAV for. filed
with an order to do them in (EXDATE first: "cancel next Tuesday" is a thing the
owner will say and the honest answer today is a refusal) and the reason the API
stops where it does.

new theme, because burying a calendar gap under plugin-repos is where it goes to
be lost.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

todo/calendar/_index.md

@@ -0,0 +1,8 @@
+---
+theme: calendar
+heading: "Calendar and contacts"
+kind: theme
+---
+
+The caldav plugin: Radicale, the DAV door phones sync against, the `/calendar` and `/contacts` screens,
+and the JSON API both those screens and the agent skill are built on.

todo/calendar/the-json-api-cannot-express-recurrence-alarms.md

@@ -0,0 +1,40 @@
+---
+id: calendar/the-json-api-cannot-express-recurrence-alarms
+title: "The calendar API cannot express repeating events, reminders, invitees or a cancelled occurrence"
+theme: calendar
+status: open
+created: 2026-08-27
+date_source: stated
+order: 1
+---
+
+**The calendar API cannot express repeating events, reminders, invitees or a cancelled occurrence.**
+It reads all four correctly and can neither create nor change them. Raised 2026-08-27, when the agent
+skill was rewritten onto the JSON routes and this became the list of things it still has to drop to
+raw DAV for.
+
+Plainly, what the four are:
+
+- **Recurrence (`RRULE`)** — "every Tuesday", "the last Friday of the month". One stored event with a
+  rule attached, not many copies. Both screens already show a *repeats* badge, and the sidecar passes
+  the rule through unexpanded, so nothing here invents occurrences the server never claimed existed.
+- **Alarms (`VALARM`)** — the reminder. "Tell me fifteen minutes before." A block inside the event.
+- **Attendees (`ATTENDEE`)** — the other people. Adding one is not a note on an event: it is a meeting
+  invitation, with replies coming back, which is a different feature wearing the same field.
+- **`EXDATE`** — one occurrence of a repeating event removed, the rest left alone. This is what
+  "cancel just next Tuesday's" actually is. Deleting the event deletes the whole series, so today the
+  skill is told to say so rather than do it.
+
+**Nothing is broken.** Every one of these survives an edit made from Officer — `patch.ts` replaces only
+the lines it owns, and there are tests for exactly that against an event carrying an alarm, an attendee
+and a rule. The gap is that Officer can only leave them alone, never author them.
+
+The order to do them in is not the order above. **`EXDATE` first**: "cancel next Tuesday" is a thing the
+owner will say, and the honest answer today is a refusal. Then alarms, which are self-contained and
+where "remind me an hour before" is worth having. Recurrence is a real UI problem — a rule builder is a
+small product on its own — and the read side already handles it, so it can wait for the proper calendar
+interface. Attendees should be last and may never be worth it: it drags in iTIP, replies, and mail.
+
+The reason it stops here rather than growing quietly: **a field the screens cannot show is a field an
+editor should not invent.** That rule is why a patch is safe. Widening the API means widening what the
+UI can display at the same time, or the next edit silently drops what the last one wrote.