docs: the calendar panel and calctl

The island README gains the panel. AGENTS.md records why calctl reads
the vdir itself, the local-time recurrence rule, the system Python it
needs, and two traps the build hit: a QML method named escape fails to
load, and a pill expanding for any panel grew beside the calendar.

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

1 files changed, 19 insertions, 1 deletions

diff --git a/AGENTS.md b/AGENTS.md
index 82b73e0..a7b841f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,7 +13,7 @@ modules.
 
     desktop/          the drawer: sound, mail, VMs, appearance
       island/         top-centre pills on DP-1: clock, volume, tray, layout, privacy,
-                      controls panel (SUPER alone)
+                      controls panel (SUPER alone), calendar
     appearance/       wallpaper picker and colour scheme switcher
     window-switcher/  open windows as live previews in a grid, on ALT+TAB
     keybinds/         live keybind reminder, on SUPER+k
@@ -155,6 +155,24 @@ changing that component. The ones that generalise:
   has no mkdir step. `Quickshell.stateDir` is a per-shell hashed directory
   (`by-shell/<hash>`), not `~/.local/state/quickshell`, which is why the
   preferences path is built from `XDG_STATE_HOME` instead.
+- **khal 0.11 has no JSON output**, which is why the calendar reads the vdir
+  itself through `desktop/island/calendar/calctl` rather than parsing `khal
+  list -f`. A month list over the 281 live event files measured 0.11s. khal
+  and cal-notif read the same files and are unaffected by calctl's writes.
+- **Recurrence is expanded in naive local time.** A TZID event keeps its
+  wall-clock time across DST that way, as RFC 5545 asks; `test_calctl.py`
+  pins a weekly 09:00 on 26 October, the day after the change.
+- **Use `/usr/bin/python3` for calctl and its test.** `python3` on PATH is a
+  pyenv shim without `icalendar`; the system interpreter has it, for
+  cal-notif.
+- **A QML method cannot be named `escape`.** It shadows the global JS
+  function, and the file fails with `Illegal method name` at load, which a
+  hot reload reports as the whole island being unavailable. The island's
+  Escape hooks are `back()`.
+- **A pill that expands for "any panel" grows for its neighbour's.** The
+  status pill once expanded on `panel !== ""`, which was right while it
+  hosted every panel; the calendar lives in the clock pill, and the status
+  pill grew into an empty box beside it. Each pill names its own panels.
 - **Waybar is gone, both bars.** Its DP-3 functions moved to the island. The
   mail count is drawer-only: `Accounts.qml` watches the xapian directory
   itself, and `waybar-mail.sh` was deleted.