Calendar

Calendar is Herald’s schedule workspace. It uses the same terminal-native chrome as Timeline: top tabs, a left rail, a dense main view, a right inspector or command panel, bottom status, and context-sensitive hints.

Overview

Press 3 to open Calendar when a calendar source is configured or when Herald is running in demo mode. Calendar can show a week time-grid, a focused day agenda, a 3-day command view, agenda/search lists, and event detail. The left rail groups enabled calendars by source, uses colored swatches for each calendar, and lets you filter visible events without exposing provider IDs.

Screen Anatomy

Area	What it shows
Calendar rail	Mini month, source groups, colored calendar swatches, enabled/disabled state, visible counts, and filter scope.
Week Time-Grid	Seven days of timed events with half-hour guide rows, selected event focus, RSVP markers, and source colors.
Day Agenda	One selected day with full-width timed event rows and a persistent detail drawer.
3-Day Command	Today, tomorrow, and the next day with a command panel for selected event, next-up, open slots, and conflicts.
Agenda/Search list	Compact cached event rows with source labels, RSVP markers, and a detail panel.
Event detail	Time, local/event timezone, location, attendees, RSVP state, recurrence, attachments, notes, and available actions.

Views

Week Time-Grid

Week view is the spatial planning view. Use it to spot dense days, open blocks, conflicts, and events requiring a response.

Day Agenda

Day view narrows the schedule to one day while keeping the selected event drawer visible.

3-Day Command

The 3-day command view bridges today, tomorrow, and the following day. Its side panel summarizes next-up context, open slots, and conflicts for the current enabled calendar scope.

Calendar Search

Calendar search is cache-backed and searches event titles, notes, locations, organizers, attendees, recurrence, attachments, and source labels while keeping provider internals hidden.

Controls

Key	Context	Preconditions	Result
3	Main UI	Calendar is available.	Opens Calendar.
tab / shift+tab	Calendar	Multiple panels are visible.	Cycles focus between rail, main view, and detail/command panel.
j / down	Calendar main panel	Events are visible.	Moves to the next visible event, crossing day boundaries where useful.
k / up	Calendar main panel	Events are visible.	Moves to the previous visible event.
h / left	Calendar main panel	A date-ranged view is active.	Moves to the previous day, week, or 3-day range.
l / right	Calendar main panel	A date-ranged view is active.	Moves to the next day, week, or 3-day range.
w	Calendar	Any calendar view.	Switches to Week Time-Grid.
d	Calendar	Any calendar view.	Switches to Day Agenda.
t	Calendar	Any calendar view.	Switches to 3-Day Command.
a	Calendar	Any calendar view.	Switches to Agenda List.
/	Calendar	Calendar search is closed.	Opens Calendar Search.
x	Calendar	Cross-source search is available.	Opens blended mail-and-calendar search.
enter	Calendar event	An event is selected.	Opens full event detail.
e	Calendar event	The selected source supports editing.	Opens Event Edit.
y / m / n	RSVP action picker	Selected event supports RSVP.	Accepts, tentatively accepts, or declines.
space	Calendar rail	Rail has focus.	Shows or hides the highlighted calendar.
p	Agenda	Hidden past events exist.	Shows or hides past agenda rows.
esc	Calendar detail, search, or edit	A transient state is active.	Returns to the prior Calendar view without losing range and selection.

Workflows

Scan The Week

1. Press 3.
2. Press w for Week Time-Grid.
3. Use h/l to move week ranges.
4. Use j/k to move through events.
5. Read the inspector for timezone, RSVP, location, and notes context.

Focus On Today

1. Press d.
2. Use h/l to move between days.
3. Move through the day’s rows with j/k.
4. Press enter when the drawer is not enough and you need full event detail.

Plan The Next Three Days

1. Press t.
2. Review the command panel’s selected-event, next-up, open-slot, and conflict sections.
3. Use h/l to slide the 3-day window.
4. Press w, d, or a to jump into another Calendar view with the same event context.

Search Events

1. Press /.
2. Type a query such as design.
3. Press enter.
4. Move through results with j/k.
5. Read the detail panel, or press enter for the full event reader.

States

State	What happens
Calendar unavailable	Mail-only sessions do not advertise the Calendar tab. Add a calendar source from Settings or use demo mode to explore it.
Loading	Calendar shows cached data when available while the provider refresh continues.
Rail filtering	Disabled calendars immediately disappear from the visible event set while date range and selection are preserved when possible.
Read-only source	Events remain readable, but mutation and RSVP actions are hidden or disabled with a clear reason.
Provider-backed edit	Event edits write through Google Calendar or CalDAV first, then update the cache only after provider success.
Conflict or unsupported recurrence	Herald keeps the edit/error visible and does not rewrite cached event rows on failed provider writes.
Narrow terminal	Calendar collapses to a compact layout or the global minimum-size guard instead of clipping columns.

Data And Privacy

Calendar reads cached event metadata, notes, attendees, reminders, recurrence, attachments, and source labels from configured calendar sources. Provider IDs, CalDAV URLs, Google event IDs, sync tokens, and internal scoped refs stay out of the TUI. Event edits, RSVP changes, and invitation imports can write to the selected provider-backed calendar source.

Troubleshooting

If Calendar is missing, open Settings and add a calendar source under Accounts, or run ./bin/herald --demo to see the deterministic demo calendar.

If a view looks empty, check the mini month, range header, enabled calendars in the rail, and whether Agenda has hidden past rows. Search still looks across cached events even when the current date range has no visible rows.

Related Pages

• Global UI
• Settings
• Search
• Provider Setup