feat: add a calendar card reading khal

The month grid with the week's appointments below it, colour-coded by
calendar. Events come from a cache file rather than a live call: khal
costs about 200ms of Python startup, which is two orders of magnitude
over the 2-second draw budget, so bin/calendar-sample.sh writes the
cache on a 5-minute execi and the widget only parses.

Calendar colours are read out of khal's own config by the sampler and
mapped onto the board's palette roles, so the card follows a scheme
change instead of pinning three literal hues.

khal will not emit an ISO date: {start-date} uses the user's dateformat,
which carries no year here, and a strftime spec inside the field raises.
The sampler asks for {start-date-long} and data.calendar_date recovers
the numbers by position, resolving day/month by magnitude and reading a
genuinely ambiguous pair day-first. A 2-digit year is refused rather
than guessed at.

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

1 files changed, 44 insertions, 2 deletions

diff --git a/README.md b/README.md
index bf71d2d..c3a4261 100644
--- a/README.md
+++ b/README.md
@@ -83,19 +83,23 @@ The disks and cache cards read a cache file that a sampler writes; they never
 call `du` or `statfs` themselves. `statfs` on an unreachable NFS path blocks,
 and the disks sampler exists so that a dead server costs a stale cache rather
 than a frozen draw. Sampling is scheduled by conky itself: `conky.text` carries
-five `${execi}` entries, even though that block renders nothing under Cairo.
+six `${execi}` entries, even though that block renders nothing under Cairo.
 
     ${execi 900  ~/.config/conky/bin/weather-fetch.sh}
     ${execi 60   ~/.config/conky/bin/disks-sample.sh}
     ${execi 900  ~/.config/conky/bin/cache-sample.sh}
     ${execi 1800 ~/.config/conky/bin/pubip-sample.sh}
     ${execi 900  ~/.config/conky/bin/slackware-sample.sh}
+    ${execi 300  ~/.config/conky/bin/calendar-sample.sh}
 
 The disks sampler runs once a minute; the cache, Slackware and public-IP
 samplers run every 15, 15 and 30 minutes respectively, because `du -sh
 ~/.cache` walks the tree and takes about 100ms warm, which is fine on a slow
 cycle and unthinkable on the 2-second draw, and a residential public address
-does not change often enough to warrant asking more frequently. Tying them to
+does not change often enough to warrant asking more frequently. The calendar
+sampler runs every five minutes: khal costs about 200ms of Python startup,
+which rules out calling it from a draw, and the cache has to notice both a
+vdirsyncer run and the day rolling over. Tying them to
 conky means nothing samples while the dashboard is down.
 
 To run a sampler by hand:
@@ -104,6 +108,7 @@ To run a sampler by hand:
     ./bin/cache-sample.sh; echo "exit: $?"
     ./bin/pubip-sample.sh; echo "exit: $?"
     ./bin/slackware-sample.sh; echo "exit: $?"
+    ./bin/calendar-sample.sh; echo "exit: $?"
 
 All print nothing and exit 0 on success, and all write a temp file and rename
 it over the target, so the widget never reads a half-written file.
@@ -142,6 +147,43 @@ beyond, the same three-role language the system, GPU, disks and cache cards
 use. Below it: distribution version, package count, kernel, and install age
 (the root filesystem's birth time, where the filesystem records one).
 
+### Calendar
+
+The month grid with the week's appointments under it. A day carrying an event
+takes its calendar's colour; today takes a filled pill, coloured by its own
+calendar when something is on and `highlight` otherwise, with the number over
+it in the heading colour because a calendar colour loses too much contrast
+against the fill. Past days in the month dim: the grid is mostly about what is
+still coming. Below the grid, one row per appointment, start time left in the
+calendar's colour and title right in the body colour. Colour-coding the whole
+row makes three calendars read as three unrelated cards, so the time carries
+the code and the title stays readable. All-day events read `all day`, never
+`00:00`, because midnight is a legitimate start time.
+
+Events come from a cache file written by `bin/calendar-sample.sh`, which shells
+out to `khal`. The card shows as many rows as the cell affords and ends with
+`+N more` when the week does not fit, since a card that silently drops the rest
+of the week defeats its own purpose.
+
+**Calendar colours come from khal's own config**, parsed out of the
+`[calendars]` section by the sampler, then mapped onto the board's palette
+roles in `COLOUR_ROLE` at the top of `widgets/calendar.lua`: green to `ok`,
+magenta and red to `critical`, blue and cyan to `highlight`, yellow and brown
+to `warning`. The card follows a scheme change that way instead of pinning
+literal hues that drift out of step with the rest of the board. A calendar
+whose colour is not in the table falls back to `value`, so it is visible and
+unstyled rather than invisible.
+
+**khal will not emit an ISO date.** `{start-date}` renders with the user's
+`dateformat`, which here is `%d.%m.` and carries no year at all, and a
+strftime spec inside the field (`{start-date:%Y-%m-%d}`) raises. The sampler
+asks for `{start-date-long}` instead, which uses `longdateformat` and does
+carry the year, and `data.calendar_date` pulls the three numbers out by
+position: the 4-digit group is the year, and of the other two the one over 12
+must be the day. A genuinely ambiguous pair like `03.04.2026` is read
+day-first, matching khal's own defaults. A 2-digit year is refused rather than
+guessed at.
+
 ### Host bindings
 
 These hwmon bindings, and the ceilings beside them, are specific to this machine