feat: add recurrence and time zone support

docs/ARCHITECTURE.md

@@ -27,6 +27,19 @@ optional descriptive fields, and calendar identity. Queries define overlap as
 `event.start < range.end && event.end > range.start`; this matters for events
 crossing midnight.
 
+Recurring events remain one domain object. Occurrence queries expand only the
+requested time window and return values that point back to their source series,
+preserving series-level storage and mutation semantics. The supported rule
+surface is deliberately bounded to daily/weekly/monthly/yearly frequency,
+interval, count or until, weekly `BYDAY`, monthly `BYMONTHDAY`, yearly
+`BYMONTH`, and `EXDATE`. Invalid metadata retains at most the base event rather
+than crashing a render.
+
+Timed events retain their source basis: UTC, floating process-local time, or an
+IANA `TZID`. C++20 time-zone conversion keeps zoned recurrences at their civil
+wall time across daylight-saving transitions. The month grid displays instants
+in the user's local zone; the reader also names an explicit source zone.
+
 ## Storage
 
 Version 0.1 uses a user-owned iCalendar file, defaulting to
@@ -50,11 +63,13 @@ rolls it back if persistence fails. Its bounded undo/redo history contains only
 mutations that crossed the persistence boundary successfully.
 
 The current writer deliberately refuses to mutate an existing file when the
-loader encounters information it cannot round-trip, including recurrence,
-alarms, attendees, time-zone identifiers, unknown properties, or malformed
-components. Browsing remains available. This conservative boundary is more
-important than partial editing because a successful-looking edit must not
-erase unrelated calendar data.
+loader encounters information it cannot round-trip, including recurrence
+overrides, `RDATE`, custom `VTIMEZONE` definitions, alarms, attendees, unknown
+properties, or malformed components. Supported recurrence rules, exclusions,
+and system IANA time-zone identifiers round-trip semantically. Browsing remains
+available for unsupported files. This conservative boundary is more important
+than partial editing because a successful-looking edit must not erase unrelated
+calendar data.
 
 Provider synchronization will not write directly into this UI file. It will use
 a transaction-capable local cache and preserve remote ETags/sync tokens in a

docs/PRODUCT.md

@@ -78,9 +78,11 @@ full-frame reader, validated add/edit/delete forms, and atomic `.ics` writes.
 Dense days keep every appointment keyboard-reachable even when all lines do
 not fit in the cell. Unknown or unsupported iCalendar content makes a source
 read-only instead of being discarded. Saves reject external changes, retain a
-last-known-good backup, and feed bounded session undo/redo history. The next
-local-data work adds `/` search, calendar visibility toggles, and recurring-event
-and time-zone expansion.
+last-known-good backup, and feed bounded session undo/redo history. Supported
+recurring instances appear throughout the month, preserve civil time across
+daylight-saving changes, and expose their source zone and whole-series mutation
+semantics in the reader. The next local-data work adds `/` search, agenda and
+calendar visibility views, then advanced recurrence overrides and rule editing.
 
 ## Accessibility
 

docs/ROADMAP.md

@@ -8,12 +8,13 @@
 - Validated add/edit/delete forms with confirmation and failure rollback
 - Guarded atomic `.ics` persistence, advisory locking, and round-trip tests
 - Bounded session undo/redo, exact external-change detection, and backup recovery
+- Windowed recurrence expansion, EXDATE, IANA TZID, and multi-day segment cues
 - Meson build, Nix development shell, desktop entry, and Hyprland launcher
 - Seeded sample data when explicitly requested, never silent data mutation
 
 ## 0.1 — complete local calendar
 
-- Recurrence rules, exclusions, time zones, multi-day presentation
+- Advanced recurrence editing, RDATE/overrides, and embedded VTIMEZONE support
 - Search, agenda view, calendar toggles, import/export, configurable week start
 - Screen-reader-friendly linear view and full Unicode display-width handling