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>

2 files changed, 37 insertions, 2 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.
diff --git a/desktop/island/README.md b/desktop/island/README.md
index 8f70506..4d21e6e 100644
--- a/desktop/island/README.md
+++ b/desktop/island/README.md
@@ -42,7 +42,7 @@ reports its initial state as events. The desktop icons come from
 `Wed 07/10  15:07`, then one dot per VM that is running, paused, suspended,
 saved or crashed (a plainly shut-off VM gets none). States come from the
 drawer's `Virsh` service, whose lifecycle event stream runs whether the drawer
-is open or not.
+is open or not. Click opens the calendar panel.
 
 ## Status pill
 
@@ -81,6 +81,23 @@ they change and keeping keys it does not know. A tile added to the code
 later starts hidden. Pure helpers in `Controls.js`, tested with
 `node island/test_controls.js`.
 
+## Calendar panel
+
+The clock pill opens a month grid beside the selected day's agenda. Dots
+are one per calendar with something that day, in the khal colours; a bell on
+an agenda row means the event carries its own alarm. A click on an event, or
+"+ New event", opens the editor; while it is open the grid picks the date
+(shift-click for the end). Repeat is none, daily, weekly, monthly or yearly
+with an optional until-date; the alarm is none, 10m, 1h or 1d. An event with
+something richer shows custom and an edit leaves it alone. Edit and delete
+act on the whole series. Escape closes the editor, then the panel.
+
+Everything goes through `calendar/calctl`, which reads the calendar list
+from khal's config, writes the `.ics` files atomically and starts a
+`vdirsyncer sync` after each write. The panel watches the calendar
+directories, so khal edits and cron syncs show up live. Tests:
+`/usr/bin/python3 calendar/test_calctl.py`, `node calendar/test_cal.js`.
+
 ## Privacy
 
 `privacy.sh` prints `mic cam loc scr`, each 0 or 1, and `Privacy.qml` polls it