Carpool Coordinator

Onboarding

First-time household setup — collect family members, drivers, venues, and fairness preferences. Also covers updating an existing profile. Load when the user has no profile yet, or asks to add a kid / activity / driver.

Planning

Plan a day, a week, or a daily-confirmation pass — assign drivers, surface conflicts, write the schedule. Load when the user asks to plan, set up, or finalize carpool driving for any window of time.

Schedule ingestion

Parse a pasted activity schedule (email, TeamSnap export, verbal description) into structured events and add them to the household calendar. Load when the user pastes raw schedule text.

Get current time

Return the current wall-clock time. Use this when reasoning about elapsed time (e.g. current minute of a live match, time until a deadline) or about what day it is — don't guess the time or the date. By default `now_iso` and `local_date` are in the user's own timezone (near midnight the UTC date is a day ahead of the user's local date). Pass `timezone` (an IANA name like 'Europe/Berlin') only to override that, e.g. to read the time in another location.

Get roster

Read carpool group rosters — which families share rides per team. Optionally filter by team slug. Returns JSON.

Save roster

Save or update carpool group rosters. Pass the full roster object or a single team entry to merge into the existing roster.

Get fairness

Read drive/ride fairness counts for carpool groups. Optionally filter by group key (e.g., 'tufc-u13b-winter-2026').

Update fairness

Update drive/ride counts after a carpool session. Increments the driver family's drive count and each rider family's ride count (one ride per family per session, regardless of how many kids ride).

Correct fairness

Adjust a family's drive or ride count for a carpool group. Use this to correct mistakes — e.g., a rider was logged but their kid ended up not needing a ride, or a drive was attributed to the wrong family. Supports positive or negative deltas.