🔧 CeCe's Schedule · Sam Setup Guide

📋 Decisions needed

Defaults shown highlighted in green. Change anything Sam wants by editing cece-setup-decisions in KV (or just tell CC).

Decision	Options	Default
Auth path	(A) Google OAuth · cleaner, real-time (B) Public ICS URL · faster prototype	A · Google OAuth recommended
Where it lives	(A) Section of `/our/` (B) Standalone `/cece/` (C) Both — main on `/cece/`, summary on `/our/`	C · both recommended
CeCe involvement	(A) Set prefs once → app suggests automatically (B) Explicit approve-each-suggestion	A with B as override recommended
Notifications	(A) In-app only (B) Browser push (C) Both, configurable	A initially recommended

🔀 Path A vs Path B — pick one

Path A · Google OAuth recommended

Real-time event reads (within seconds)
CeCe taps "Connect Google Calendar" once, app stores refresh token in KV
Token auto-renews via Google's standard flow
Read-only scope (no risk of writes)
Cross-device — same KV-stored token

Setup time: ~30 min Sam (Google Cloud Console) · ~10 sec CeCe (Connect button).

Path B · Public ICS URL

CeCe exports calendar as public read-only ICS link (Google Calendar UI)
App fetches + parses ICS on each page load (~5-30 sec lag vs reality)
No OAuth · no Google Cloud setup
ICS URL must be guarded somehow (it's a public-ish secret token)
Worse UX if CeCe ever resets her sync URL

Setup time: ~5 min CeCe (export URL) · 0 min Sam.

Recommendation: Path A. The 30 min one-time investment is worth it. Path B is a fine fallback if Google's verification screens or app-publishing requirements feel like too much friction for Sam's account.

🅰️ Path A · Google OAuth setup (Sam's todo)

Step 1 · Vagaro 2-way sync

CeCe's task (~5 min): In Vagaro account → Settings → Google Calendar Integration → enable 2-way sync to her personal Google Calendar. All future bookings flow into Google Calendar automatically. Vagaro support article →

Step 2 · Google Cloud project

Go to console.cloud.google.com and create a new project. Name it same-solutions-cece-calendar (or similar).

Step 3 · Enable Calendar API

In the project, navigate to APIs & Services → Library, search "Google Calendar API", click Enable.

Step 4 · OAuth consent screen

User type: External
App name: Same Solutions · CeCe schedule
Support email: Sam's email
Add CeCe's Gmail as a test user (Google requires this in unpublished mode — works fine for a personal app)
Scopes: add https://www.googleapis.com/auth/calendar.events.readonly

Step 5 · OAuth client ID

Credentials → Create credentials → OAuth client ID
Type: Web application
Name: cece-schedule-web
Authorized JavaScript origins: https://samesolutions-equipment-service.pages.dev
Authorized redirect URI: https://samesolutions-equipment-service.pages.dev/auth/google/callback

Save → copy the Client ID and Client Secret.

Step 6 · Cloudflare env vars

From a machine with wrangler authenticated:

wrangler pages secret put GOOGLE_CLIENT_ID
# paste Client ID

wrangler pages secret put GOOGLE_CLIENT_SECRET
# paste Client Secret

(Or set them in the Cloudflare Pages dashboard under Settings → Environment variables.)

Step 7 · Cloudflare Functions ✓ shipped

✓ Phase 2 functions live as of this commit:

/auth/google/connect · generates CSRF state, redirects to Google consent
/auth/google/callback · verifies state, exchanges code for tokens, stores refresh_token in KV
/auth/google/disconnect (POST) · revokes at Google + clears KV
/calendar/cece-status · GET · returns {connected, config_ok, email, connected_at}
/calendar/cece-events?from=&to= · GET · returns normalized event list with category heuristic (work/personal)

KV keys used (auto-managed): cece-google-refresh-token (no TTL), cece-google-access-token (55-min TTL), cece-google-status (display data), cece-google-state-* (10-min TTL).

Step 8 · CeCe connects

Once Sam finishes Steps 2-6 (Google Cloud setup + Cloudflare env vars), CeCe visits /cece/, taps 🔗 Connect Google Calendar, signs in with her Google account, grants read-only access. Tokens land in KV. Today + Week views immediately swap from placeholder events to her real calendar.

Test it: after env vars are set, hit /calendar/cece-status in a browser. Should return {config_ok: true, connected: false} until CeCe connects. After CeCe connects, connected: true + her email.

🅱️ Path B · ICS URL fallback (faster prototype)

Step 1 · Vagaro 2-way sync

(Same as Path A · enable Vagaro → Google sync first.)

Step 2 · Get a public ICS URL

Google Calendar → calendar settings → "Secret address in iCal format" → copy URL. It looks like:

https://calendar.google.com/calendar/ical/.../private-XXXXX/basic.ics

Treat like a password. Anyone with this URL can read CeCe's calendar.

Step 3 · Stash in KV

Tell CC the URL. CC PUTs it to KV key cece-ics-url via /our/data. Next CC session builds /functions/calendar/cece-events.js that fetches that ICS, parses it with a lightweight ICS parser, and returns events as JSON.

Step 4 · Phase 2 integration

Tell CC: "Build Phase 2 of CeCe's calendar — ICS fetch + parse." Page loads pull fresh ICS each time (cached ~5 min in KV).

🅲 (Skip) · Direct Vagaro API

Vagaro does have an API, but it's contract-only (their B2B platform). Not a fit for one personal user. The Vagaro → Google sync route covers everything we need.

📦 Roadmap

✅ Phase 1 — Foundation (shipped)

/cece/ Today view · /cece/week.html grid · /cece/preferences.html form (live KV save) · this setup guide

✅ Phase 2 — Google OAuth flow (shipped)

/functions/auth/google/connect.js + callback.js + disconnect.js
/functions/calendar/cece-status.js + cece-events.js (Google Calendar v3 · category heuristic for work vs personal)
Today + Week views auto-detect connection · placeholder swaps to real events when CeCe connects
Sam todo: Steps 2-6 above (Google Cloud project + env vars). Then CeCe taps Connect on /cece/.

✅ Phase 3 — Suggestion engine (shipped)

/cece/engine.js · pure browser JS module · window.CeceEngine · no deps
Free-block detection: bounded by sleep window (wake→bedtime from prefs) · minimum 15-min blocks · events with all_day ignored
Suggestion logic: workout (per day-of-week template) · meal prep (on meal_prep.days) · daily walk (per timing pref) · reading (before-bed by default) · self-care (weekly) · respects preferred_windows · sorts by start · dedupes overlapping
Templates: 7-day workout rotation (upper / cardio / lower / yoga / full body / long walk / weekend hike) with moves + easy/hard variants + equipment list · 3 meal-prep templates (Sun big-batch / Wed refresh / daily 10-min portion) with stages + shopping list · walk / reading / self-care templates with notes
Mode honoring: auto = full suggestions · minimal = workout + meal-prep only · off = no suggestions, calendar only · ask behaves like auto with the same accept/snooze/skip buttons
After-work evening block: detects last work-category event end · stacks workout → shower → meal → walk-with-dogs → family → tomorrow-prep → reading from work-end → bedtime · per-item checkboxes persist to localStorage per-day key cece-evening-{yyyy-mm-dd}
Action logging: accept/snooze/skip taps append to KV cece-suggestion-log (capped at 200 entries) so Phase 4 can adapt templates to what CeCe actually uses

✅ Phase 4 — Polish (shipped)

Habit tracking · /cece/habits.html full page with weekly progress bars (workouts/meal-prep/walks/reading/self-care vs prefs targets) · streak counter (consecutive days with ≥1 accept) · today's accept/skip/snooze counts · recent activity (last 12 log entries) · adaptive nudges (good / neutral / gentle tones based on accept ratio + skip count)
Habit summary tile on /cece/ Today view — compact 5-row rollup with mini progress bars + top nudge · auto-hidden until first action logged
Sequenced scheduler · engine now tracks per-block consumed minutes so workout + reading + walk can share the same free block (workout 6-6:30 → reading 6:30-7 in the same evening). Replaces the old dedupe-by-overlap that dropped suggestions sharing a block.
Sam coordination card on /our/ · pulls /calendar/cece-events for today only · auto-hides if CeCe not connected · shows "N clients · first-time–last-time" headline + colored time-pills · explicitly hides client names (privacy) · category-only summary · links to /cece/
Adaptive nudges · engine.nudges(habits, prefs) returns prioritized message list with tone (good/neutral/gentle) · used on both habits.html and Today summary

Phase 5 — Future iterations (not yet built)

Template editor — UI to swap workout moves, edit meal recipes, add custom suggestion types
Browser push notifications (service-worker) for protected slots about to start
Friendly weekly recap email/notification (Sunday night) summarizing the week's progress
Multi-week habit trend lines (already storing the log; just needs a chart)