# 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.