# Kade v0.4 — Calendar Integration Scoping

**From:** Kade
**To:** Forge (lead) + Riv (consumer)
**Date:** 2026-05-24
**Priority:** Net-new scope, queues behind persistent-runtime → v0.2 tasks → v0.3 DND
**Status:** Scoping — Forge drafts approach memo first, then full contract

---

## Owner decision locked

- **Account:** `jimmie@j2bookkeeping.com` — main calendar, everything else feeds from it
- **Access level:** **Full read + write** — I create, move, delete, and reschedule events on Jimmie's behalf, not just read

## The ask

Scope and build the Google Calendar integration so I can:

1. **Read** the day — pre-review at morning briefing, surface conflicts, see prep needs
2. **Write** the day — create events from DMs ("block 2-4pm tomorrow for Acadian quote"), move conflicts, delete cancellations
3. **Sync** with tasks — due-dated tasks can optionally drop a calendar block; calendar events can read as Today-list items
4. **Honor DND windows** — calendar reflects DND so I don't accidentally book over Jimmie's quiet hours (v0.3 dependency — note but don't block)

## Forge scoping deliverable (Phase 1, before code)

Drop an approach memo in Team Inbox covering:

1. **OAuth flow** — service account vs. user OAuth? Token storage location (likely `.env.local` per [[reference-atlas-secrets-location]]). What's the one-time grant step Jimmie has to click through, and how do we handle refresh-token expiry?
2. **Data model** — calendar events stored in Atlas DB (cached/mirrored) vs. live API hits every read? Caching has staleness risk; live has latency + quota risk. Recommend a path.
3. **Sync direction** — Google Calendar is source-of-truth ([[feedback-lean-on-source-files]] pattern — don't make Jimmie double-enter). Atlas writes propagate to GCal, GCal changes propagate back via push notifications or polling.
4. **Quota planning** — Google Calendar API quotas, our expected call volume, headroom.
5. **Endpoint sketch** — `/api/kade/calendar/*` endpoint list (no full contract yet, just names + one-liners).

## Phase 2 (after memo approval)

- Full API contract draft (same quality as v0.1 meds contract)
- Migration for any new tables
- OAuth setup runbook for Jimmie (single click-through, then done)

## Riv coordination

You're the bot-side consumer. Ack the contract when Forge drafts it. Bot commands to plan for:

- "what's on my calendar [today/tomorrow/Friday]"
- "block [time] for [thing]"
- "move [event] to [new time]"
- "what conflicts do I have"
- "cancel [event]"

## Sequencing

This brief sits in queue. Don't start until persistent runtime and v0.2 tasks are shipping. Memo can be drafted in parallel — it's design work, not code.

## Sign-off

Forge: reply with
- ✅ Approach memo drafted at `Team Inbox/Forge/kade-v04-calendar-approach.md`
- 🔧 Scope concern: [what]
- ❓ Question: [what]

Riv: ack receipt only — your turn comes after Forge's contract lands.