From c2293d23efc3c3fdf19dfe564387e08e98e4464b Mon Sep 17 00:00:00 2001 From: Ted Kulp Date: Mon, 12 Oct 2026 14:42:14 -0400 Subject: [PATCH] Add Meeting terms to the glossary and the ICS-feed ADR Co-Authored-By: Claude Opus 5.5 --- GLOSSARY.md | 10 ++++++++++ docs/adr/0002-calendar-source-is-ics-feeds.md | 11 +++++++++++ 2 files changed, 21 insertions(+) create mode 100644 docs/adr/0002-calendar-source-is-ics-feeds.md diff --git a/GLOSSARY.md b/GLOSSARY.md index 1c82b5d..db9c09b 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -30,6 +30,16 @@ _Avoid_: card, atomic note, permanent note A Note whose contents become the starting text of a new Note, after its placeholders are filled in. _Avoid_: skeleton, boilerplate +### Meetings + +**Meeting**: +One event on the user's calendar, read from a calendar feed. pholio only reads Meetings, never changes them. Each occurrence of a recurring Meeting is its own Meeting. +_Avoid_: event, appointment + +**Meeting Note**: +The Note for one Meeting, created from the meeting Template the first time that Meeting is picked. Picking the same Meeting again opens its existing Meeting Note. +_Avoid_: meeting minutes, event note + ### Connections **Link**: diff --git a/docs/adr/0002-calendar-source-is-ics-feeds.md b/docs/adr/0002-calendar-source-is-ics-feeds.md new file mode 100644 index 0000000..5b3df88 --- /dev/null +++ b/docs/adr/0002-calendar-source-is-ics-feeds.md @@ -0,0 +1,11 @@ +# Meetings come from private ICS feed URLs + +pholio reads Meetings from one or more private ICS feed URLs (the "secret address in iCal format" that Google, Outlook/M365 and Fastmail all publish), fetched with a plain read-only HTTP GET. We chose this over the Google Calendar API, Microsoft Graph, macOS EventKit and CalDAV because pholio only reads Meetings, never changes them, and a feed URL gives that with no OAuth app registration, token refresh, platform-specific code or per-provider client. One parser (golang-ical plus rrule-go for recurrence) covers every provider, and the user's real calendars all reach pholio through Fastmail as Outlook-flavoured ICS anyway. + +## Consequences + +- Feed URLs are secrets, so they live only in the user config (`[[calendars]]`), never in the Vault config, which may be synced or shared. The cached feed bodies are written with mode `0600`. +- Feeds are whole calendars, not a window: pholio fetches each one in full (about 250 KB total for the user's four) and filters to the day it shows. +- pholio cannot create, edit or RSVP to Meetings, and it cannot see anything a provider leaves out of its published feed (feeds rarely carry the user's own declines, for example). +- Freshness depends on the provider's publishing delay as well as pholio's own refetch rule; a just-added Meeting may not show for a while. +- A feed with an unusual dialect (Outlook's `Customized Time Zone`, conference links in `X-` properties) is handled in pholio's own glue rather than by a provider SDK.