Calendar Sync Workflow
Sync Google Calendar events into daily files under
raw/calendar/for temporal context in the wiki.
The calendar-sync automation runs weekly (local and cloud). Source: automations/calendar-sync.md, 2026-05-31
Command
npx tsx scripts/sync-calendar.ts
Google OAuth required (--auth on first run). Shared state: ~/.kevin-wiki/integrations.pglite. Source: recipes/calendar-to-brain.md
Runbook
- Read
automations/calendar-sync.md. - Run
npx tsx scripts/sync-calendar.ts. - Inspect the newest
raw/calendar/daily files. - Extract repeated attendees, recurring meetings, travel/event constraints, and project timeline anchors.
- Search existing person/project pages before creating anything.
- Write
outputs/<YYYY-MM-DD>/calendar-sync/codex.mdwhen run as an automation. - Update
state.jsonautomations.calendar-syncafter scheduled completion; the sync script updatessyncs.calendarafter successful collection. - Append
wiki/log.md. - If wiki pages changed, run
npx tsx scripts/build-index.tsandqmd update && qmd embed.
Trigger And Inputs
Run weekly through the scheduler, after a calendar-auth repair, or manually before time-sensitive event planning. Required inputs are Google Calendar OAuth, scripts/sync-calendar.ts, automations/calendar-sync.md, and access to existing person/project/place pages for enrichment.
Use cases
- Anchor timeline entries on person and project pages
- Feed active project and event-planning pages with upcoming events
- Cross-reference Meeting Sync Workflow when Circleback captures overlap
Raw calendar files stay immutable; compiled summaries live in wiki pages above the --- separator.
Promotion Rules
| Calendar signal | Durable action |
|---|---|
| Attendee appears 3+ times and already has context | Update person page with meeting cadence or timeline entry. |
| Event changes project timeline, travel, or offsite planning | Update project/place/planning page. |
| Routine class, travel hold, or duplicate invite | Keep raw only unless it explains a later decision. |
| Missing OAuth or empty sync | Write blocker/no-op output; do not update syncs.calendar unless collection succeeded. |
Validation
npx tsx scripts/check-freshness.ts
Freshness should show Google Calendar current only after the script successfully collected events.
The output is incomplete if it advances syncs.calendar without a collection result or if it updates person/project pages without source dates from the calendar files.
Run Contract
This workflow follows Workflow Run Contract: name the sources, write output or no-op proof, promote only durable facts, update state only when the run really completed, refresh generated surfaces when durable pages or skills change, and log user-visible work.
Timeline
- 2026-07-01 | Added trigger/input boundaries and validation rules so calendar freshness and durable timeline updates remain evidence-backed. Source: User request, 2026-07-01
- 2026-07-14 | Removed routing to the retired offsites and Hawaii planning automations while preserving calendar support for active event planning. Source: User request, 2026-07-14
- 2026-06-30 | Expanded from command stub into runbook with state writes, promotion rules, and validation behavior. Source: User request, 2026-06-30
- 2026-05-31 | Workflow page created from calendar-sync automation. Source: automations/calendar-sync.md, 2026-05-31