Plan the Panama calendar agenda

2026-08-17 11:15:19 -04:00
parent e92c2ee5f9
commit 530a5590a6
1 changed files with 811 additions and 0 deletions
@@ -0,0 +1,811 @@
+# Calendar Agenda Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the approved A · Daybook date menu using the workstation's existing Evolution Data Server calendars, with a quiet upcoming-event capsule and GNOME Calendar handoff.
+
+**Architecture:** A Python/GObject bridge queries enabled EDS calendar sources through `EDataServer` and `ECal`, expands recurring instances, and streams normalized JSON snapshots. A Quickshell singleton owns that stream and exposes date/event selectors to a two-column Daybook, while GNOME Calendar remains responsible for accounts and event editing.
+
+**Tech Stack:** Python 3.14, PyGObject, Evolution Data Server 3.60 (`EDataServer`, `ECal`, `ICalGLib`), Quickshell 0.3/QML, Gio D-Bus, Bash contract tests, jq, Hyprland 0.56
+
+**Spec:** `docs/superpowers/specs/2026-08-17-calendar-agenda-design.md`
+
+## Global Constraints
+
+- Use only enabled EDS event sources; never read authentication extensions or credential stores.
+- GNOME Calendar owns account configuration and event editing.
+- Live event content must never be written to logs, settings, test fixtures, screenshots committed to the repository, or documentation.
+- The bridge may emit event content only to its Quickshell consumer over stdout.
+- Descriptions and attendees never enter the bridge output; descriptions may only be inspected to locate an allowed HTTPS meeting URL.
+- Allowed meeting providers are Google Meet, Zoom, Microsoft Teams, Webex, and Jitsi.
+- Calendar failures must not break notifications, media, weather, or the static month grid.
+- The bar capsule appears from 15 minutes before through 5 minutes after a timed event starts; all-day events never produce it.
+- No calendar toasts, sounds, pulse, shimmer, or continuously repainting animation.
+- No test may create, modify, or delete a real calendar event.
+- Wi-Fi QR sharing is removed from Panama's roadmap and package guidance.
+
+---
+
+## File map
+
+### Calendar data boundary
+
+- `config/dot/quickshell/scripts/calendar-agenda` — executable Python bridge; the only code that imports EDS libraries.
+- `config/dot/quickshell/services/CalendarAgenda.qml` — singleton state consumed by shell UI; supervises the bridge and owns date-derived selectors.
+- `tests/quickshell/calendar_agenda_bridge_test.py` — pure normalization and URL-policy tests using synthetic components only.
+- `tests/quickshell/calendar-agenda-helper-contract.sh` — executable/probe/live-query contract that redacts live content.
+- `tests/quickshell/calendar-agenda-contract.sh` — live Quickshell IPC/state contract using synthetic in-memory fixtures.
+
+### Daybook presentation
+
+- `config/dot/quickshell/modules/datemenu/AgendaEvent.qml` — one event row.
+- `config/dot/quickshell/modules/datemenu/AgendaPane.qml` — Up Next, all-day section, timed agenda, empty/error states, and notification summary.
+- `config/dot/quickshell/modules/datemenu/NotificationSummary.qml` — quiet bridge from Agenda to the existing grouped notification list.
+- `config/dot/quickshell/modules/datemenu/DateMenuPanel.qml` — approved two-column layout and agenda/notification routing.
+- `config/dot/quickshell/modules/datemenu/CalendarGrid.qml` — date selection, adjacent-month navigation, and event dots.
+- `config/dot/quickshell/modules/datemenu/DateMenu.qml` — panel sizing, preparation, and notification read-state behavior.
+- `config/dot/quickshell/modules/datemenu/qmldir` — explicit registrations for new components.
+
+### Shell and bar integration
+
+- `config/dot/quickshell/services/ShellState.qml` — `dateMenuPage` and explicit Agenda/Notifications open semantics.
+- `config/dot/quickshell/modules/bar/Clock.qml` — clock opens Agenda rather than an undifferentiated notification overlay.
+- `config/dot/quickshell/modules/bar/CalendarIndicator.qml` — quiet 15-minute capsule.
+- `config/dot/quickshell/modules/bar/Bar.qml` — mounts the capsule in the right status area.
+- `config/dot/quickshell/shell.qml` — calendar IPC fixture/diagnostics surface and notification-page routing.
+
+### Documentation
+
+- `config/dot/hypr/DESKTOP-PARITY.md` — calendar becomes Live and Wi-Fi QR is removed.
+- `config/dot/hypr/README.md` — EDS/GNOME Calendar handoff and capsule behavior.
+- `setup/packages/hyprland-packages` — remove `qrencode` if it is present only for the abandoned Wi-Fi QR feature.
+
+---
+
+### Task 1: EDS calendar bridge
+
+**Files:**
+- Create: `config/dot/quickshell/scripts/calendar-agenda`
+- Create: `tests/quickshell/calendar_agenda_bridge_test.py`
+- Create: `tests/quickshell/calendar-agenda-helper-contract.sh`
+
+**Interfaces:**
+- Consumes: enabled sources returned by `EDataServer.SourceRegistry.list_enabled(EDataServer.SOURCE_EXTENSION_CALENDAR)`.
+- Produces: `calendar-agenda probe`, `calendar-agenda query START END`, and `calendar-agenda watch START END`.
+- Produces: one-line JSON snapshots with `ok`, `generatedAt`, `sources`, `events`, and `errors`.
+- Produces event objects with exactly `id`, `sourceId`, `uid`, `summary`, `start`, `end`, `allDay`, `location`, and `joinUrl`.
+
+- [ ] **Step 1: Write failing pure bridge tests**
+
+Create `tests/quickshell/calendar_agenda_bridge_test.py` with import-by-path and synthetic policy cases:
+
+```python
+import importlib.machinery
+import importlib.util
+import pathlib
+import unittest
+from unittest.mock import Mock
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+HELPER = ROOT / "config/dot/quickshell/scripts/calendar-agenda"
+
+loader = importlib.machinery.SourceFileLoader("calendar_agenda", str(HELPER))
+spec = importlib.util.spec_from_loader(loader.name, loader)
+calendar_agenda = importlib.util.module_from_spec(spec)
+loader.exec_module(calendar_agenda)
+
+
+class CalendarAgendaBridgeTest(unittest.TestCase):
+    def test_meeting_url_allowlist(self):
+        values = ["Planning: https://meet.google.com/abc-defg-hij"]
+        self.assertEqual(calendar_agenda.find_join_url(values), values[0].split()[-1])
+        self.assertEqual(calendar_agenda.find_join_url(["https://example.com/private"]), "")
+        self.assertEqual(calendar_agenda.find_join_url(["http://zoom.us/j/123"]), "")
+
+    def test_stable_instance_id_includes_recurrence(self):
+        self.assertEqual(
+            calendar_agenda.stable_event_id("source", "uid", "20260817T133000Z"),
+            "source:uid:20260817T133000Z",
+        )
+
+    def test_snapshot_sort_order(self):
+        events = [
+            {"id": "b", "start": 20, "end": 30, "allDay": False},
+            {"id": "a", "start": 10, "end": 20, "allDay": True},
+        ]
+        self.assertEqual([event["id"] for event in calendar_agenda.sort_events(events)], ["a", "b"])
+
+    def test_normalizes_an_all_day_recurrence_instance(self):
+        component_id = Mock()
+        component_id.get_uid.return_value = "uid"
+        component_id.get_rid.return_value = "20260817"
+        summary = Mock()
+        summary.get_value.return_value = "Synthetic event"
+        component = Mock()
+        component.get_id.return_value = component_id
+        component.get_summary.return_value = summary
+        component.get_location.return_value = ""
+        component.get_url.return_value = None
+        component.get_descriptions.return_value = []
+        start = Mock()
+        start.as_timet.return_value = 1786924800
+        start.is_date.return_value = True
+        end = Mock()
+        end.as_timet.return_value = 1787011200
+        end.is_date.return_value = True
+
+        event = calendar_agenda.normalize_instance(
+            {"id": "source", "name": "Synthetic", "color": "#82aaff"},
+            component,
+            start,
+            end,
+        )
+        self.assertTrue(event["allDay"])
+        self.assertEqual(event["id"], "source:uid:20260817")
+
+
+if __name__ == "__main__":
+    unittest.main()
+```
+
+- [ ] **Step 2: Run the unit test and verify RED**
+
+Run:
+
+```bash
+python3 tests/quickshell/calendar_agenda_bridge_test.py
+```
+
+Expected: FAIL because `config/dot/quickshell/scripts/calendar-agenda` does not exist.
+
+- [ ] **Step 3: Implement the bridge's pure contract and CLI boundary**
+
+Create `config/dot/quickshell/scripts/calendar-agenda` with a Python shebang and no top-level execution on import. Begin with these pure helpers:
+
+```python
+MEETING_HOST_SUFFIXES = (
+    "meet.google.com",
+    "zoom.us",
+    "teams.microsoft.com",
+    "teams.live.com",
+    "webex.com",
+    "meet.jit.si",
+)
+
+def stable_event_id(source_id: str, uid: str, recurrence_id: str) -> str:
+    return f"{source_id}:{uid}:{recurrence_id}"
+
+def sort_events(events: list[dict[str, object]]) -> list[dict[str, object]]:
+    return sorted(events, key=lambda event: (not bool(event["allDay"]), int(event["start"]), str(event["id"])))
+
+def is_allowed_meeting_host(host: str) -> bool:
+    normalized = host.lower().rstrip(".")
+    return any(normalized == suffix or normalized.endswith("." + suffix) for suffix in MEETING_HOST_SUFFIXES)
+```
+
+`find_join_url` must parse URLs with `urllib.parse.urlsplit`, require `https`, lowercase the hostname, and match either an exact allowed host or a subdomain boundary (`host == suffix or host.endswith("." + suffix)`). Strip trailing sentence punctuation before parsing.
+
+Then implement these exact public boundaries: `find_join_url(values: list[str]) -> str`, `normalize_instance(source_meta, component, instance_start, instance_end) -> dict[str, object]`, `probe() -> dict[str, object]`, `collect_snapshot(start: int, end: int) -> dict[str, object]`, `watch(start: int, end: int) -> int`, and `main(argv: list[str]) -> int`.
+
+Import GI with exact version requirements:
+
+```python
+import gi
+gi.require_version("ECal", "2.0")
+gi.require_version("EDataServer", "1.2")
+from gi.repository import ECal, EDataServer, Gio, GLib
+```
+
+For each enabled source:
+
+```python
+client = ECal.Client.connect_sync(source, ECal.ClientSourceType.EVENTS, 5, None)
+client.generate_instances_sync(start, end, None, on_instance, None)
+```
+
+The callback signature is `(component, instance_start, instance_end, cancellable, callback_data)`. Convert callback times with `as_timet()`. Use `component.get_id().get_uid()` and `.get_rid()`, `component.get_summary().get_value()`, `component.get_location()`, `component.get_url()`, and `component.get_descriptions()`.
+
+Use source metadata from `source.get_uid()`, `source.get_display_name()`, and the calendar extension's `get_color()`. Fall back to `#82aaff` only when color is absent or invalid. Catch failures per source and append a generic `{sourceId, code: "unavailable"}` error without raw exception text.
+
+`watch` must emit the initial snapshot, subscribe to EDS source-registry changes and GNOME CalendarServer invalidation signals when available, debounce refreshes by 350 ms, and emit a fallback snapshot every 600 seconds. Failure to subscribe to GNOME CalendarServer must not stop periodic EDS reads.
+
+Write each snapshot with `json.dumps(snapshot, separators=(",", ":")) + "\n"` and immediately flush stdout. Never print event data to stderr.
+
+Make the helper executable:
+
+```bash
+chmod +x config/dot/quickshell/scripts/calendar-agenda
+```
+
+- [ ] **Step 4: Run pure tests and verify GREEN**
+
+Run:
+
+```bash
+python3 tests/quickshell/calendar_agenda_bridge_test.py
+```
+
+Expected: four tests PASS.
+
+- [ ] **Step 5: Add the redacted live helper contract**
+
+Create `tests/quickshell/calendar-agenda-helper-contract.sh` with:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+fail() { printf 'calendar agenda helper contract: %s\n' "$1" >&2; exit 1; }
+project_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+helper="$project_root/config/dot/quickshell/scripts/calendar-agenda"
+
+[[ -x "$helper" ]] || fail 'helper is missing or not executable'
+probe="$($helper probe)"
+jq -e '.eds == true and .sourceRegistry == true and .enabledSources > 0' <<<"$probe" >/dev/null \
+    || fail 'EDS readiness probe failed'
+
+range_start="$(date +%s)"
+range_end="$((range_start + 1209600))"
+snapshot="$($helper query "$range_start" "$range_end")"
+jq -e '
+  .ok == true and
+  (.sources | type == "array" and length > 0) and
+  (.events | type == "array") and
+  ([.events[] | keys_unsorted - ["id","sourceId","uid","summary","start","end","allDay","location","joinUrl"]] | all(length == 0))
+' <<<"$snapshot" >/dev/null || fail 'live snapshot shape is invalid'
+
+printf 'calendar agenda helper contract: PASS (%s sources, %s events; contents redacted)\n' \
+  "$(jq '.sources | length' <<<"$snapshot")" "$(jq '.events | length' <<<"$snapshot")"
+```
+
+Make it executable and run it. Expected: PASS with counts only; no source names, summaries, locations, or URLs in terminal output.
+
+- [ ] **Step 6: Commit the bridge**
+
+```bash
+git add config/dot/quickshell/scripts/calendar-agenda \
+  tests/quickshell/calendar_agenda_bridge_test.py \
+  tests/quickshell/calendar-agenda-helper-contract.sh
+git commit -m "Add the EDS calendar bridge"
+```
+
+---
+
+### Task 2: Quickshell calendar service and deterministic contract
+
+**Files:**
+- Create: `config/dot/quickshell/services/CalendarAgenda.qml`
+- Create: `tests/quickshell/calendar-agenda-contract.sh`
+- Modify: `config/dot/quickshell/shell.qml`
+
+**Interfaces:**
+- Consumes: `calendar-agenda watch START END` newline-delimited snapshots.
+- Produces: singleton properties `phase`, `available`, `sources`, `events`, `selectedDate`, `selectedDateKey`, `selectedEvents`, `nextEvent`, `nextEventForSelectedDate`, `rangeStart`, `rangeEnd`, `capsuleVisible`, and `capsuleText`.
+- Produces: functions `selectDate(date)`, `selectIsoDate(dateString)`, `setVisibleMonth(year, month)`, `eventsForDate(date)`, `markersForDate(date)`, `openEvent(event)`, `openCalendar(date)`, `join(event)`, `refresh()`, `applyFixture(name)`, and `clearFixture()`.
+- Produces IPC target `calendar-agenda` with `fixture`, `reset`, `open`, `select`, `refresh`, and `status`.
+
+- [ ] **Step 1: Write the failing live service contract**
+
+Create `tests/quickshell/calendar-agenda-contract.sh` that first asserts the IPC target, loads fixture `daybook`, and validates only synthetic state:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+fail() { printf 'calendar agenda contract: %s\n' "$1" >&2; exit 1; }
+cleanup() {
+  qs ipc call calendar-agenda reset >/dev/null 2>&1 || true
+  qs ipc call calendar-agenda close >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+qs ipc show | rg -q '^target calendar-agenda$' || fail 'calendar IPC target is missing'
+qs ipc call calendar-agenda fixture daybook >/dev/null
+status="$(qs ipc call calendar-agenda status)"
+jq -e '.fixture == true and .sourceCount == 3 and .eventCount == 5 and .selectedDate == "2026-08-17"' \
+  <<<"$status" >/dev/null || fail 'daybook fixture state is malformed'
+
+qs ipc call calendar-agenda select 2026-08-18 >/dev/null
+jq -e '.selectedDate == "2026-08-18" and .selectedEventCount == 1' \
+  <<<"$(qs ipc call calendar-agenda status)" >/dev/null || fail 'date selection did not update events'
+
+qs ipc call calendar-agenda reset >/dev/null
+jq -e '.fixture == false' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
+  || fail 'fixture reset did not restore live mode'
+printf 'calendar agenda contract: PASS\n'
+```
+
+- [ ] **Step 2: Run the contract and verify RED**
+
+Run `tests/quickshell/calendar-agenda-contract.sh`.
+
+Expected: FAIL with `calendar IPC target is missing`.
+
+- [ ] **Step 3: Implement `CalendarAgenda.qml` stream supervision**
+
+Create the singleton with `pragma Singleton`, `Quickshell`, `Quickshell.Io`, and `QtQuick` imports. Use a streaming parser, not `StdioCollector`:
+
+```qml
+Process {
+    id: watchProc
+    command: [root.helperPath, "watch", String(root.rangeStart), String(root.rangeEnd)]
+    running: !root.fixtureMode && root.rangeStart > 0
+    stdout: SplitParser {
+        onRead: data => root.consumeSnapshot(data)
+    }
+    onExited: (code, status) => {
+        if (!root.fixtureMode)
+            restartTimer.restart();
+    }
+}
+```
+
+The restart timer uses 2 seconds and does not loop while fixture mode is active. `consumeSnapshot(data)` parses one line, rejects snapshots without `ok === true`, assigns arrays atomically, and sets `phase` to `ready` or `degraded` when `errors.length > 0`.
+
+Implement date keys in local time with `Qt.formatDate(new Date(epoch * 1000), "yyyy-MM-dd")`. For multi-day/all-day markers, treat `end` as exclusive and include each local date touched before `end - 1`.
+
+`setVisibleMonth(year, month)` computes a range from seven days before the first day through seven days after the final 42-cell grid day. Only restart the bridge when the requested range falls outside the loaded range.
+
+`nextEvent` excludes all-day and ended events. `capsuleVisible` is true when `start - now` is at most 900 seconds and at least -300 seconds. `capsuleText` is `Now` after start, otherwise the ceiling minute count plus `m`.
+
+`applyFixture("daybook")` must install three synthetic sources and five synthetic events spanning August 17–18, 2026. Use clearly synthetic labels (`Fixture standup`, `Fixture planning`, `Fixture focus`, `Fixture dinner`, `Fixture tomorrow`) and no real account or event data.
+
+- [ ] **Step 4: Add calendar IPC without exposing live content**
+
+Add to `shell.qml`:
+
+```qml
+IpcHandler {
+    target: "calendar-agenda"
+    function fixture(name: string): void { CalendarAgenda.applyFixture(name); }
+    function reset(): void { CalendarAgenda.clearFixture(); }
+    function refresh(): void { CalendarAgenda.refresh(); }
+    function open(): void { ShellState.openDateMenu("agenda"); }
+    function close(): void { ShellState.close(); }
+    function select(date: string): void { CalendarAgenda.selectIsoDate(date); }
+    function status(): string {
+        return JSON.stringify({
+            phase: CalendarAgenda.phase,
+            fixture: CalendarAgenda.fixtureMode,
+            sourceCount: CalendarAgenda.sources.length,
+            eventCount: CalendarAgenda.events.length,
+            selectedDate: CalendarAgenda.selectedDateKey,
+            selectedEventCount: CalendarAgenda.selectedEvents.length,
+            capsuleVisible: CalendarAgenda.capsuleVisible,
+            capsuleText: CalendarAgenda.capsuleText
+        });
+    }
+}
+```
+
+Do not include titles, source names, locations, identifiers, or URLs in status output.
+
+- [ ] **Step 5: Run service contracts and verify GREEN**
+
+Allow Quickshell to hot reload, then run:
+
+```bash
+tests/quickshell/calendar-agenda-contract.sh
+tests/quickshell/calendar-agenda-helper-contract.sh
+qs log -n 80 | rg -i 'calendar|error|warn'
+```
+
+Expected: both contracts PASS; no calendar QML error or bridge restart loop.
+
+- [ ] **Step 6: Commit the service**
+
+```bash
+git add config/dot/quickshell/services/CalendarAgenda.qml \
+  config/dot/quickshell/shell.qml \
+  tests/quickshell/calendar-agenda-contract.sh
+git commit -m "Add live calendar state to Quickshell"
+```
+
+---
+
+### Task 3: Explicit date-menu routing and interactive month grid
+
+**Files:**
+- Modify: `config/dot/quickshell/services/ShellState.qml`
+- Modify: `config/dot/quickshell/modules/bar/Clock.qml`
+- Modify: `config/dot/quickshell/shell.qml`
+- Modify: `config/dot/quickshell/modules/datemenu/CalendarGrid.qml`
+- Modify: `tests/quickshell/calendar-agenda-contract.sh`
+
+**Interfaces:**
+- Consumes: `CalendarAgenda.selectDate(date)` and `CalendarAgenda.markersForDate(date)`.
+- Produces: `ShellState.dateMenuPage`, `ShellState.toggleDateMenu(page)`, and `ShellState.openDateMenu(page)`.
+- Produces from CalendarGrid: signals `dateActivated(date)` and `visibleMonthChanged(year, month)`.
+
+- [ ] **Step 1: Extend the failing contract with page-routing assertions**
+
+Append fixture assertions:
+
+```bash
+qs ipc call calendar-agenda open >/dev/null
+jq -e '.open == true and .page == "agenda"' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
+  || fail 'calendar open did not route to Agenda'
+
+qs ipc call notifications open >/dev/null
+jq -e '.open == true and .page == "notifications"' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
+  || fail 'notification open did not route to Notifications'
+```
+
+Update the calendar status response to include only `open: ShellState.notificationsOpen` and `page: ShellState.dateMenuPage` in addition to the non-sensitive fields from Task 2.
+
+- [ ] **Step 2: Run the contract and verify RED**
+
+Expected: FAIL because `dateMenuPage` and notification `open()` do not exist.
+
+- [ ] **Step 3: Implement explicit ShellState routing**
+
+Add:
+
+```qml
+property string dateMenuPage: "agenda"
+
+function openDateMenu(page: string): void {
+    root.dateMenuPage = page === "notifications" ? "notifications" : "agenda";
+    root.activeOverlay = "notifications";
+}
+
+function toggleDateMenu(page: string): void {
+    const target = page === "notifications" ? "notifications" : "agenda";
+    if (root.activeOverlay === "notifications" && root.dateMenuPage === target) {
+        root.activeOverlay = "";
+        return;
+    }
+    root.dateMenuPage = target;
+    root.activeOverlay = "notifications";
+}
+```
+
+Change Clock activation to `ShellState.toggleDateMenu("agenda")`. Change notification IPC `toggle()` to `ShellState.toggleDateMenu("notifications")`, add `open()` using `openDateMenu("notifications")`, and leave `Super+B` routed through that IPC target.
+
+- [ ] **Step 4: Make CalendarGrid date-aware and event-aware**
+
+Replace numeric-only cell objects with full local `Date` values and add:
+
+```qml
+signal dateActivated(date date)
+signal visibleMonthChanged(int year, int month)
+property date selectedDate: CalendarAgenda.selectedDate
+
+function activateCell(cell): void {
+    if (!cell.current) {
+        root.viewYear = cell.date.getFullYear();
+        root.viewMonth = cell.date.getMonth();
+    }
+    root.dateActivated(cell.date);
+}
+```
+
+Every cell receives `markers: CalendarAgenda.markersForDate(cell.date).slice(0, 3)`. Render dots in a centered row beneath the day number with each marker's source color. Today remains solid accent; selected non-today uses `Theme.alpha(Theme.accent, 0.18)` plus accent text. Add a hover surface only now that cells are actionable.
+
+Month changes call `visibleMonthChanged(viewYear, viewMonth)`. Adjacent-month date activation changes month and selection in one click.
+
+- [ ] **Step 5: Verify routing and grid contracts**
+
+Run:
+
+```bash
+tests/quickshell/calendar-agenda-contract.sh
+rg -q 'markersForDate' config/dot/quickshell/modules/datemenu/CalendarGrid.qml
+rg -q 'dateActivated' config/dot/quickshell/modules/datemenu/CalendarGrid.qml
+```
+
+Expected: contract PASS and both interaction hooks present.
+
+- [ ] **Step 6: Commit routing and grid behavior**
+
+```bash
+git add config/dot/quickshell/services/ShellState.qml \
+  config/dot/quickshell/modules/bar/Clock.qml \
+  config/dot/quickshell/shell.qml \
+  config/dot/quickshell/modules/datemenu/CalendarGrid.qml \
+  tests/quickshell/calendar-agenda-contract.sh
+git commit -m "Route the interactive Panama date menu"
+```
+
+---
+
+### Task 4: Build the approved A · Daybook panel
+
+**Files:**
+- Create: `config/dot/quickshell/modules/datemenu/AgendaEvent.qml`
+- Create: `config/dot/quickshell/modules/datemenu/AgendaPane.qml`
+- Create: `config/dot/quickshell/modules/datemenu/NotificationSummary.qml`
+- Modify: `config/dot/quickshell/modules/datemenu/DateMenuPanel.qml`
+- Modify: `config/dot/quickshell/modules/datemenu/DateMenu.qml`
+- Modify: `config/dot/quickshell/modules/datemenu/MediaCard.qml`
+- Modify: `config/dot/quickshell/modules/datemenu/qmldir`
+- Modify: `tests/quickshell/calendar-agenda-contract.sh`
+
+**Interfaces:**
+- Consumes: `CalendarAgenda.selectedEvents`, `nextEventForSelectedDate`, `phase`, and action functions.
+- Consumes: `ShellState.dateMenuPage`, `Notifs.hasNotifications`, and existing `NotificationList`.
+- Produces: a 760-pixel two-column date menu with left width 310 and independently bounded right content.
+
+- [ ] **Step 1: Add failing structural and live-surface assertions**
+
+Extend the contract to assert the loaded layer and approved components:
+
+```bash
+hyprctl layers | rg -q 'namespace: qs-popover-datemenu' || fail 'Daybook layer did not map'
+rg -q 'implicitWidth: 760' config/dot/quickshell/modules/datemenu/DateMenu.qml \
+  || fail 'Daybook is not the approved width'
+for component in AgendaPane AgendaEvent NotificationSummary; do
+  rg -q "${component} 1.0 ${component}.qml" config/dot/quickshell/modules/datemenu/qmldir \
+    || fail "$component is not registered"
+done
+```
+
+Run the contract and expect failure on width or missing components.
+
+- [ ] **Step 2: Implement focused event and summary components**
+
+`AgendaEvent.qml` accepts `property var event`, `property bool past`, and signals `activated` and `joinRequested`. It renders a 48-pixel tabular time column, 3-pixel source-color rail, elided summary, source/location metadata, and optional Join pill. All-day rows replace time with `All day`.
+
+`NotificationSummary.qml` is visible only when `Notifs.hasNotifications`; it displays history count and emits `activated`. It never marks notifications read by itself.
+
+`AgendaPane.qml` renders exactly one of:
+
+- loading copy (`Loading calendars…`);
+- unavailable copy plus `Open Calendar`;
+- empty-day copy plus `Open Calendar`;
+- Up Next plus the selected day's ordered list.
+
+The Up Next card is omitted for selected dates other than today and when no future timed event exists. Use `ScrollColumn` with a maximum content height derived from the panel's available height. Event clicks call `CalendarAgenda.openEvent(event)`; Join calls `CalendarAgenda.join(event)`.
+
+- [ ] **Step 3: Recompose DateMenuPanel as Daybook**
+
+Keep the existing header styling and Prism container, but replace the single `Column` with this concrete structure:
+
+```qml
+Column {
+    id: frame
+    spacing: 0
+    Item {
+        id: header
+        width: parent.width
+        height: 42
+    }
+    Rectangle { width: parent.width; height: 1; color: Theme.alpha(Theme.fg, 0.1) }
+    Row {
+        width: parent.width
+        Item {
+            id: leftColumn
+            width: 310
+            height: rightColumn.height
+        }
+        Rectangle {
+            width: 1
+            height: rightColumn.height
+            color: Theme.alpha(Theme.fg, 0.1)
+        }
+        Item {
+            id: rightColumn
+            width: frame.width - 311
+            height: Math.max(438, activeContent.implicitHeight)
+            property Item activeContent: ShellState.dateMenuPage === "agenda" ? agendaPane : notificationList
+            AgendaPane { visible: ShellState.dateMenuPage === "agenda" }
+            NotificationList { visible: ShellState.dateMenuPage === "notifications" }
+        }
+    }
+}
+```
+
+Populate `leftColumn` inline in `DateMenuPanel.qml` with a `Column` containing CalendarGrid, conditional MediaCard, and WeatherCard. Populate `header` with the existing date text and pill controls. Bind date activation to `CalendarAgenda.selectDate(date)` and month changes to `CalendarAgenda.setVisibleMonth(year, month)`.
+
+When Agenda's notification summary activates, set `ShellState.dateMenuPage = "notifications"` and call `Notifs.markAllRead()`. Notification view header exposes `Back to agenda`, DND, and Clear All. Returning to agenda retains selected date and month.
+
+Resize MediaCard typography/controls responsively for the 310-pixel column; do not duplicate its playback logic.
+
+- [ ] **Step 4: Update DateMenu lifecycle and bounds**
+
+Set `DateMenu.implicitWidth: 760`. Bound height to the active screen's available geometry, with the panel content choosing a maximum right-column scroll height instead of overflowing the monitor.
+
+On opening:
+
+```qml
+CalendarAgenda.refresh();
+if (ShellState.dateMenuPage === "notifications")
+    Notifs.markAllRead();
+panel.prepare(ShellState.dateMenuPage);
+```
+
+Add a connection that marks notifications read when an already-open panel switches into Notifications. Opening from the clock must not mark them read.
+
+- [ ] **Step 5: Verify fixture visuals on the real layer surface**
+
+Run:
+
+```bash
+qs ipc call calendar-agenda fixture daybook
+qs ipc call calendar-agenda open
+tests/quickshell/calendar-agenda-contract.sh
+```
+
+Capture a temporary full-screen screenshot with `grim`, inspect the Daybook at original detail, and verify:
+
+- no clipped text at 1.5 scale;
+- month and agenda are simultaneously visible;
+- right content has no unexplained empty glass;
+- three source colors remain restrained;
+- notification summary is quieter than Up Next;
+- no continuously repainting animation.
+
+Close the panel and reset fixture mode after inspection. Do not add screenshots to git.
+
+- [ ] **Step 6: Commit the Daybook**
+
+```bash
+git add config/dot/quickshell/modules/datemenu \
+  tests/quickshell/calendar-agenda-contract.sh
+git commit -m "Build the Prism calendar Daybook"
+```
+
+---
+
+### Task 5: Quiet upcoming-event capsule
+
+**Files:**
+- Create: `config/dot/quickshell/modules/bar/CalendarIndicator.qml`
+- Modify: `config/dot/quickshell/modules/bar/Bar.qml`
+- Modify: `config/dot/quickshell/services/CalendarAgenda.qml`
+- Modify: `tests/quickshell/calendar-agenda-contract.sh`
+
+**Interfaces:**
+- Consumes: `CalendarAgenda.capsuleVisible`, `capsuleText`, and `nextEvent`.
+- Produces: a right-side Pill showing calendar glyph plus `12m` or `Now`.
+- Produces: `applyFixture("upcoming")` and `applyFixture("outside-window")` for boundary tests.
+
+- [ ] **Step 1: Add failing capsule boundary assertions**
+
+Append:
+
+```bash
+qs ipc call calendar-agenda fixture upcoming >/dev/null
+jq -e '.capsuleVisible == true and .capsuleText == "12m"' \
+  <<<"$(qs ipc call calendar-agenda status)" >/dev/null || fail 'upcoming capsule window is wrong'
+
+qs ipc call calendar-agenda fixture outside-window >/dev/null
+jq -e '.capsuleVisible == false' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
+  || fail 'capsule appears outside the quiet window'
+```
+
+Run and expect RED because those fixtures do not exist.
+
+- [ ] **Step 2: Implement deterministic timing fixtures and capsule state**
+
+Add `fixtureNow` to CalendarAgenda. Production uses `Date.now() / 1000`; fixture modes use their explicit clock. `upcoming` creates one timed event exactly 12 minutes ahead. `outside-window` creates one 20 minutes ahead plus an all-day event. Verify all-day never wins `nextEvent`.
+
+Use a one-minute `Timer` only while events are loaded to update relative time. Midnight refresh remains separate. There is no sub-minute repaint.
+
+- [ ] **Step 3: Build CalendarIndicator and mount it in Bar**
+
+Use `Pill` with `visible: CalendarAgenda.capsuleVisible`, horizontal padding 8, a calendar Nerd Font glyph, and tabular relative text. `onActivated` opens Agenda. Import `QtQuick.Controls` and use `ToolTip.visible: root.hovered && root.visible` with the next event's title; the title must not otherwise appear in the bar.
+
+Mount the indicator at the beginning of Bar's right row, before ActivityIndicator, so it does not shift the centered clock.
+
+Use a single 120 ms opacity/width entrance tied to visibility. No looping animation.
+
+- [ ] **Step 4: Run capsule and full shell contracts**
+
+```bash
+tests/quickshell/calendar-agenda-contract.sh
+for test in tests/quickshell/*.sh; do "$test"; done
+```
+
+Expected: calendar fixture boundaries PASS and every existing Quickshell contract remains green.
+
+- [ ] **Step 5: Commit the capsule**
+
+```bash
+git add config/dot/quickshell/modules/bar/CalendarIndicator.qml \
+  config/dot/quickshell/modules/bar/Bar.qml \
+  config/dot/quickshell/services/CalendarAgenda.qml \
+  tests/quickshell/calendar-agenda-contract.sh
+git commit -m "Add the quiet calendar capsule"
+```
+
+---
+
+### Task 6: Documentation, live EDS verification, and delivery
+
+**Files:**
+- Modify: `config/dot/hypr/DESKTOP-PARITY.md`
+- Modify: `config/dot/hypr/README.md`
+- Modify: `setup/packages/hyprland-packages`
+- Modify: `docs/superpowers/plans/2026-08-17-calendar-agenda.md`
+
+**Interfaces:**
+- Consumes: completed helper, service, Daybook, capsule, and test suite.
+- Produces: documented live behavior and a pushed sequence of reviewed commits.
+
+- [ ] **Step 1: Update parity and operator documentation**
+
+In DESKTOP-PARITY:
+
+- change Calendar Agenda to Live with EDS/Google/iCloud/Nextcloud wording;
+- remove Wi-Fi QR from remaining work;
+- remove `qrencode` from the privileged package command;
+- keep KDE Connect, Home Assistant, printer UI, and RustDesk lock-screen validation as future work.
+
+In Hyprland README document:
+
+- clock opens Agenda;
+- `Super+B` opens Notifications inside the same Daybook;
+- event clicks hand off to GNOME Calendar;
+- account management remains in GNOME Calendar/Online Accounts;
+- the bar capsule's 15-minute to +5-minute window.
+
+Remove `qrencode` from `setup/packages/hyprland-packages` only if `rg -n qrencode .` confirms no remaining runtime consumer.
+
+- [ ] **Step 2: Run static verification**
+
+```bash
+bash -n tests/quickshell/*.sh config/dot/quickshell/scripts/screen-intelligence
+python3 -c 'compile(open("config/dot/quickshell/scripts/calendar-agenda", encoding="utf-8").read(), "calendar-agenda", "exec")'
+python3 tests/quickshell/calendar_agenda_bridge_test.py
+desktop-file-validate config/local/share/applications/*.desktop
+Hyprland --verify-config
+git diff --check
+```
+
+Expected: every command exits 0 and Hyprland reports `config ok`.
+
+- [ ] **Step 3: Run every Quickshell contract**
+
+```bash
+for test in tests/quickshell/*.sh; do
+  "$test"
+done
+```
+
+Expected: all prior contracts plus both calendar contracts report PASS.
+
+- [ ] **Step 4: Verify the live calendar without leaking content**
+
+Reset fixture mode and refresh:
+
+```bash
+qs ipc call calendar-agenda reset
+qs ipc call calendar-agenda refresh
+```
+
+Poll status until `phase` is `ready` or `degraded`. Assert `sourceCount > 0`; report only source/event counts. Open Agenda from the clock path, inspect the real panel locally, test one date containing events, and confirm event clicks launch GNOME Calendar. Do not capture or print a screenshot containing real event details.
+
+Test a Join action only when a recognized URL is already present; opening that URL is an external navigation and requires an explicit click in the local UI. Do not fabricate or modify an event for testing.
+
+- [ ] **Step 5: Review logs and the complete diff**
+
+```bash
+qs log -n 250 | rg -i 'calendar|qml|error|warn'
+git status --short
+git diff --stat 5248883..HEAD
+git diff --check 5248883..HEAD
+```
+
+Expected: no calendar QML errors, no bridge restart loop, no secrets, and only calendar/planned-roadmap changes beyond the already-approved desktop snapshot.
+
+- [ ] **Step 6: Mark this plan complete and commit documentation**
+
+Mark completed checkboxes only after their commands actually passed, then:
+
+```bash
+git add config/dot/hypr/DESKTOP-PARITY.md \
+  config/dot/hypr/README.md \
+  setup/packages/hyprland-packages \
+  docs/superpowers/plans/2026-08-17-calendar-agenda.md
+git commit -m "Document the Panama calendar agenda"
+```
+
+- [ ] **Step 7: Push without rewriting history**
+
+```bash
+git status --short
+git push origin main
+```
+
+Expected: clean worktree and `main` advances on `origin`. If Gitea still returns HTTP 502, preserve all commits locally, report the remote outage, and do not force-push or change remote history.