@agent-native/scheduling 0.1.1

package/docs/llms.txt

@@ -0,0 +1,89 @@
+# @agent-native/scheduling
+
+Scheduling primitives for agent-native apps — event types, availability,
+bookings, team scheduling, workflows, routing forms. A self-hosted,
+locally-owned scheduling stack, not an API wrapper.
+
+## What this package provides
+
+- **Drizzle schemas** (`/schema`) — event_types, schedules, availability,
+  date_overrides, bookings, booking_attendees, booking_references, teams,
+  team_members, credentials, calendar_cache, selected_calendars,
+  destination_calendars, hashed_links, workflows, workflow_steps,
+  scheduled_reminders, webhooks, routing_forms, routing_form_responses,
+  api_keys, out_of_office_entries, travel_schedules.
+- **Pure helpers** (`/core`) — DST-safe slot computation, timezone math,
+  availability rule evaluation, round-robin host selection, buffer
+  application, booking-limit bucketing, recurring-event expansion.
+- **Server layer** (`/server`) — DB repos, availability engine, booking
+  service, pluggable calendar + video providers (Google Calendar, Outlook,
+  Zoom, Google Meet, built-in video), iCal generator, lifecycle hooks →
+  workflows.
+- **Actions** (`/actions/*`) — ~55 `defineAction` modules covering every
+  operation in the product (event type CRUD, availability edit, booking
+  lifecycle, calendar connect, team ops, round-robin, workflows, routing
+  forms). Re-export from a consumer template's `actions/` folder for
+  zero-boilerplate adoption.
+- **React primitives** (`/react`, `/react/components`) — headless hooks for
+  timezone, slots, booking flow; minimal unstyled primitives (SlotPicker,
+  TimezoneSelect).
+- **Skill docs** (`/skills/*`) — drop-in agent skills for scheduling
+  concepts: `scheduling-basics`, `event-types`, `availability`, `bookings`,
+  `booker`, `slot-engine`, `team-scheduling`, `integrations`, `embeds`,
+  `workflows`, `routing-forms`.
+
+## Quick start
+
+```ts
+// server/db/schema.ts
+export * from "@agent-native/scheduling/schema";
+
+// server/bootstrap.ts
+import { setSchedulingContext } from "@agent-native/scheduling/server";
+import {
+  registerCalendarProvider,
+  registerVideoProvider,
+  createGoogleCalendarProvider,
+  createDailyVideoProvider,
+} from "@agent-native/scheduling/server/providers";
+import { getDb, schema } from "./db/index.js";
+
+setSchedulingContext({
+  getDb,
+  schema,
+  getCurrentUserEmail: () => getRequestUserEmail(),
+  getCurrentOrgId: () => getRequestOrgId(),
+  publicBaseUrl: process.env.PUBLIC_URL,
+});
+
+registerCalendarProvider(createGoogleCalendarProvider({
+  clientId: process.env.GOOGLE_CLIENT_ID!,
+  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  getAccessToken: fetchGoogleToken, // your implementation
+}));
+
+registerVideoProvider(createDailyVideoProvider({
+  apiKey: process.env.DAILY_API_KEY!,
+}));
+```
+
+## Full documentation
+
+For the full bundled docs (every .md file concatenated), see
+`llms-full.txt` in this folder.
+
+## Individual skills
+
+- skills/scheduling-basics/SKILL.md — Core concepts, terminology.
+- skills/event-types/SKILL.md — Event type model, tabs, scheduling types.
+- skills/availability/SKILL.md — Schedules, date overrides, timezone rules.
+- skills/bookings/SKILL.md — Lifecycle, reschedule, cancel, no-show.
+- skills/booker/SKILL.md — Public booking flow, state machine.
+- skills/slot-engine/SKILL.md — The pure slot-computation function and
+  invariants.
+- skills/team-scheduling/SKILL.md — Team event types, round-robin,
+  collective.
+- skills/integrations/SKILL.md — Calendar + video provider integrations.
+- skills/embeds/SKILL.md — Inline/popup/floating-button embeds.
+- skills/workflows/SKILL.md — Trigger-based automations.
+- skills/routing-forms/SKILL.md — Pre-booking routing forms.

package/docs/providers.md

@@ -0,0 +1,68 @@
+# Writing a custom provider
+
+Scheduling needs two kinds of providers:
+
+- **CalendarProvider** — reads busy intervals + writes events.
+- **VideoProvider** — creates meeting rooms when a booking is confirmed.
+
+Built-ins: Google Calendar, Office 365, Zoom, built-in video (Daily.co), Google
+Meet (piggy-backs on Google Calendar).
+
+## CalendarProvider
+
+```ts
+import { registerCalendarProvider } from "@agent-native/scheduling/server/providers";
+
+registerCalendarProvider({
+  kind: "my_calendar",
+  label: "My Calendar",
+  async startOAuth({ redirectUri, state }) {
+    /* return { authUrl } */
+  },
+  async completeOAuth({ code, credentialId, userEmail, redirectUri }) {
+    /* exchange code, persist tokens, return externalEmail + calendars */
+  },
+  async listCalendars({ credentialId }) {
+    /* ... */
+  },
+  async getBusy({ credentialId, calendarExternalIds, start, end }) {
+    /* ... */
+  },
+  async createEvent({
+    credentialId,
+    calendarExternalId,
+    booking,
+    includeConference,
+  }) {
+    /* ... */
+  },
+  async updateEvent({ credentialId, externalId, booking }) {
+    /* ... */
+  },
+  async deleteEvent({ credentialId, externalId }) {
+    /* ... */
+  },
+});
+```
+
+All methods receive a `credentialId` — use it to look up the OAuth token via
+your token store. The package's `setSchedulingContext()` doesn't touch
+tokens; consumers typically use core's `oauth_tokens` and pass a
+`getAccessToken(credentialId)` callback.
+
+## VideoProvider
+
+```ts
+registerVideoProvider({
+  kind: "my_video",
+  label: "My Video",
+  async createMeeting({ credentialId, booking }) {
+    return { meetingUrl, meetingId, meetingPassword? };
+  },
+  async deleteMeeting?({ credentialId, meetingId }) { /* ... */ },
+});
+```
+
+Video providers are invoked by the booking service when a booking's location
+is `builtin-video`, `zoom`, `google-meet`, or `teams`. Meeting URLs land in
+`booking_references`.

package/docs/schema.md

@@ -0,0 +1,86 @@
+# Schema reference
+
+All tables use dialect-agnostic helpers from `@agent-native/core/db/schema`
+and compose with `ownableColumns()` + `createSharesTable()` for framework-
+wide sharing.
+
+## event_types
+
+The primary bookable resource. Duration, location options, custom fields,
+buffers, limits, period (rolling/range/unlimited), scheduling type
+(personal/collective/round-robin/managed), optional team assignment,
+hashed-link support.
+
+## event_type_hosts
+
+Join between event types and users for collective / round-robin. Each host
+has `isFixed`, `weight`, `priority`, optional per-host `scheduleId` override.
+
+## hashed_links
+
+Private booking links: `/d/:hash/:slug`. Optional `expiresAt` and
+`isSingleUse`.
+
+## event_type_slug_redirects
+
+Rename history so old URLs keep working.
+
+## schedules / schedule_availability / date_overrides
+
+Named availability presets. `schedules` is the header (name, timezone,
+isDefault). `schedule_availability` rows are one weekly interval per day.
+`date_overrides` replaces the weekly rule for a specific date (empty =
+fully blocked).
+
+## travel_schedules / out_of_office_entries
+
+Per-user timezone overrides for trips; OOO windows that block bookings and
+optionally redirect.
+
+## bookings / booking_attendees / booking_references / booking_seats /
+
+## booking_notes
+
+Bookings are the materialized appointments. Attendees are N per booking.
+References are external IDs (Google event id, Zoom meeting id). Seats are
+reservation tokens for seated events. Notes are host-only.
+
+## teams / team_members
+
+Teams group users. `team_members.role` ∈ owner|admin|member.
+
+## scheduling_credentials / selected_calendars / destination_calendars
+
+`scheduling_credentials` is a view over OAuth tokens (with display metadata
+and `invalid` flag). Selected calendars are read for busy-time. Destination
+calendar is where new events get written.
+
+## calendar_cache
+
+Short-TTL cache of busy intervals. Busted on booking write.
+
+## workflows / workflow_steps / scheduled_reminders
+
+Trigger-based automations. `workflows` is the rule; `workflow_steps` are
+ordered actions; `scheduled_reminders` are materialized sends waiting to
+fire (drained by a recurring job).
+
+## webhooks / webhook_deliveries / api_keys
+
+Developer-facing surface: outgoing webhooks with HMAC-signed payloads, and
+API keys for programmatic access.
+
+## routing_forms / routing_form_responses
+
+ChiliPiper-style routing forms. Fields + rules → either an event type,
+external URL, or custom message.
+
+## verified_emails / verified_numbers
+
+Verified sender addresses / numbers used by workflows.
+
+## Shares tables
+
+For every ownable resource: `event_type_shares`, `schedule_shares`,
+`team_shares`, `workflow_shares`, `routing_form_shares`, `booking_shares`.
+Use `share-resource` / `set-resource-visibility` framework actions.

package/docs/skills/availability/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: availability
+description: How schedules, weekly rules, date overrides, travel schedules, and out-of-office entries combine to determine when someone is bookable.
+---
+
+# Availability
+
+## Schedule
+
+A named set of rules (e.g. "Working Hours"). Each user has ≥1 schedule and
+marks one as `isDefault`. Event types either use the user's default or
+reference a specific schedule.
+
+Timezone is set on the schedule, not the user — lets you have a "Europe
+hours" schedule and a "US hours" schedule for the same person.
+
+## Weekly availability
+
+Rows in `schedule_availability`: (day 0-6, startTime "HH:MM", endTime
+"HH:MM"). You can have multiple intervals per day — e.g. Mon 9-12 and 1-5.
+
+## Date overrides
+
+Rows in `date_overrides`: (date "YYYY-MM-DD", intervals JSON).
+- `intervals: []` → day fully blocked.
+- `intervals: [{start, end}]` → only those times available on that date.
+
+## Travel schedules
+
+`travel_schedules` overrides the user's default timezone for a date range.
+
+## Out of office
+
+`out_of_office_entries` blocks bookings across a range, optionally with a
+redirect to another team member.
+
+## Common tasks
+
+| User request | Action |
+|---|---|
+| "I'm unavailable next Friday" | `add-date-override --scheduleId <id> --date 2026-04-10 --intervals []` |
+| "I take lunch 12-1 weekdays" | `update-schedule --weeklyAvailability [...9-12, 13-17...]` |
+| "Create evenings schedule" | `create-schedule --name Evenings --weeklyAvailability [...]` |
+| "Going to Tokyo next week" | Insert a `travel_schedules` row (no dedicated action yet) |

package/docs/skills/booker/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: booker
+description: Public booking flow — the state machine, animations, and URL/app-state sync.
+---
+
+# Booker
+
+## Stages
+
+1. **pick-date** — month grid shows days with availability
+2. **pick-slot** — available slots on the selected day
+3. **fill-form** — attendee form (name, email, custom fields)
+4. **success** — confirmation with add-to-calendar buttons
+
+Plus **reschedule** mode — prefilled from existing booking uid.
+
+## Animations
+
+Use motion (`motion/react`) `AnimatePresence` with `fadeInLeft` variants. The outer
+container animates its width across stages: narrow (calendar only) → wider
+(calendar + slots) → widest (form).
+
+## Timezone + 12/24h
+
+- Detect browser timezone at mount; let user override via dropdown.
+- Persist choice to localStorage key `scheduling.timezone`.
+- 12/24h toggle near slot column; persist to user settings.
+
+## URL + application-state sync
+
+Selected date, slot, timezone, and duration are mirrored to URL query
+params AND `application_state.booker-state` so:
+- Page refresh preserves selection.
+- Agent can read the user's current pick.
+
+## Copy-link affordance
+
+Every event-type row has a "copy link" button. On click, write to clipboard
+and toast "Copied!" with Sonner. Works on mobile Safari too.
+
+## Accessibility
+
+- Month grid is ARIA `grid` + `gridcell` with arrow-key nav.
+- Slot buttons are keyboard-focusable, with `aria-pressed`.
+- Focus returns to trigger on modal close.
+- Toast content announced via `aria-live=polite`.
+
+## Mobile
+
+`< 768px`: stack vertically. Calendar full-width, slot list below, form
+slides in as full-screen sheet.

package/docs/skills/bookings/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: bookings
+description: Booking lifecycle — pending, confirmed, rescheduled, cancelled — plus attendees, references, no-shows, and reminders.
+---
+
+# Bookings
+
+## Lifecycle
+
+- **pending** — requires-confirmation event types start here
+- **confirmed** — normal state
+- **rescheduled** — the old booking after a reschedule (the new one is
+  confirmed; `from_reschedule` links them)
+- **cancelled** — either party cancelled
+- **rejected** — pending was declined
+
+## Reschedule vs cancel+rebook
+
+The `reschedule-booking` action creates a new booking with a link back to
+the old via `fromReschedule`. iCalUID is preserved across the reschedule
+chain (RFC 5545), and `iCalSequence` is bumped.
+
+## No-show
+
+`mark-no-show` sets `noShow: true` on an attendee. Round-robin calibration
+uses this to penalize hosts whose attendees no-show frequently.
+
+## Cancel / reschedule tokens
+
+Every booking has a `cancelToken` and `rescheduleToken` used in public
+magic links sent to attendees. These let them manage the booking without
+logging in.
+
+## References
+
+External system IDs: Google Calendar event id, Zoom meeting id, Daily.co
+room name. Stored in `booking_references`, used during cancel/reschedule to
+propagate changes back to the source system.
+
+## ICS
+
+`/booking/:uid.ics` returns the RFC 5545 calendar file. Used for
+confirmation-email attachments and "Add to calendar" buttons.

package/docs/skills/embeds/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: embeds
+description: Inline, popup, and floating-button embeds — snippet generation and theming.
+---
+
+# Embeds
+
+## Modes
+
+- **inline** — iframe embedded in the page
+- **popup** — trigger opens modal overlay with iframe
+- **element-click / floating-button** — fixed-position trigger anywhere on
+  the page
+
+## URL
+
+Embed page: `/:user/:slug/embed` — same Booker, no chrome, theme honored
+via query params.
+
+## Snippet
+
+```html
+<script src="https://<host>/embed.js" async></script>
+<div id="cal-inline-embed"></div>
+<script>
+  Cal("init", { origin: "https://<host>" });
+  Cal("inline", {
+    elementOrSelector: "#cal-inline-embed",
+    calLink: "my-user/intro",
+    config: { theme: "light" }
+  });
+</script>
+```
+
+## Theming
+
+Query params on the embed URL:
+- `theme=light|dark`
+- `primaryColor=<hex>`
+- `locale=en|es|...`
+- `timeZone=America/Los_Angeles`
+
+These override the event type's defaults for the embedded session only.
+
+## Message passing
+
+The iframe posts messages to the parent on lifecycle events:
+`__cal.init`, `__cal.booking-successful`, `__cal.booking-cancelled`,
+`__cal.booking-rescheduled`.

package/docs/skills/event-types/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: event-types
+description: How event types work — fields, scheduling types, tabs in the editor, and the full set of configurable options.
+---
+
+# Event types
+
+## Editor tabs
+- **Setup** — title, slug, duration(s), description, default location
+- **Availability** — pick a schedule or override per-event-type
+- **Limits** — buffers, min notice, booking window (rolling/range), caps
+  (perDay/perWeek/perMonth/perYear), slot interval
+- **Advanced** — event name template, lock timezone, require confirmation,
+  disable guests, redirect URL, private hashed links, seats
+- **Apps** — connect per-event location types (Zoom, Meet, etc.)
+- **Workflows** — attach workflows to run on booking lifecycle events
+
+## Scheduling types
+
+| Type | Meaning |
+|---|---|
+| `personal` | Owned by a user, only they host |
+| `collective` | Team event; all selected hosts must be free |
+| `round-robin` | Team event; assign to one host by rotation |
+| `managed` | Parent event pushed to child event types across members |
+
+## Location kinds
+
+`builtin-video`, `zoom`, `google-meet`, `teams`, `phone`, `in-person`,
+`custom-link`, `attendee-phone`, `organizer-phone`, `attendee-choice`.
+
+## Custom fields
+
+Text, textarea, number, email, phone, select, multiselect, boolean, radio.
+Stored on the event type; responses stored on the booking.
+
+## Hashed links
+
+Private booking URLs at `/d/:hash/:slug`. Create via `add-private-link`,
+optionally with `expiresAt` and `isSingleUse`.

package/docs/skills/integrations/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: integrations
+description: Calendar + video provider integrations — Google Calendar, Office 365, Zoom, built-in video, Google Meet — and how to write new ones.
+---
+
+# Integrations
+
+## Calendar providers
+
+- **google_calendar** — OAuth; read freeBusy + write events; optionally
+  create Google Meet conference via `includeConference=true`.
+- **office365_calendar** — Microsoft Graph; read freeBusy + write events.
+- **caldav** (planned) — generic CalDAV for Apple iCloud, Fastmail, etc.
+
+## Video providers
+
+- **builtin_video** — Daily.co-backed; zero OAuth; server-to-server API key.
+- **zoom_video** — OAuth; create meetings via Zoom REST API.
+- **google_meet** — piggy-backs on Google Calendar credential.
+- **teams_video** (planned) — Microsoft Teams.
+
+## Credential lifecycle
+
+1. User clicks "Connect" → `connect-calendar` returns `authUrl` + `state`
+2. Redirect to provider → consent → provider redirects to our callback
+3. Server exchanges code → writes `scheduling_credentials` row +
+   core `oauth_tokens` entry
+4. We fetch calendar list, let user pick "checked" + "destination"
+5. Token expires → refresh flow runs silently; on failure, set
+   `invalid: true` and show re-connect banner
+
+## Busy-time aggregation
+
+`aggregateBusy({userEmail, rangeStart, rangeEnd})` merges:
+- Confirmed bookings hosted by the user
+- External busy from each `selected_calendars` entry via the provider
+
+Cached in `calendar_cache` (short TTL, default 5 min). Busted on any
+booking write for that host.
+
+## Writing a new provider
+
+See `docs/providers.md` for the full interface.
+
+## Common tasks
+
+| User | Action |
+|---|---|
+| "Connect Google Calendar" | `connect-calendar --kind google_calendar --redirectUri ...` → redirect to returned `authUrl` |
+| "Stop checking my vacation calendar" | `toggle-selected-calendar --include false` for that externalId |
+| "Default to Zoom for new bookings" | `set-default-conferencing-app --credentialId <zoom-cred>` |
+| "Refresh calendar cache" | `refresh-busy-times` |

package/docs/skills/routing-forms/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: routing-forms
+description: ChiliPiper-style pre-booking forms that route prospects to the right event type based on their answers.
+---
+
+# Routing forms
+
+## Shape
+
+- **Fields** — text, email, phone, number, select, multi
+- **Rules** — ordered list of `{conditions, action}`
+- **Fallback** — action taken when no rule matches
+
+## Rule conditions
+
+`conditions: [{fieldId, op, value}, …]` — all ANDed together. Ops:
+- `equals`, `not-equals`, `contains`, `starts-with`, `in` (value is array)
+
+## Rule actions
+
+- `{kind: "event-type", eventTypeId, teamId?}` → redirect to Booker
+- `{kind: "external-url", url}` → redirect off-site
+- `{kind: "custom-message", message}` → render message, no booking
+
+## Public URL
+
+`/forms/:formId` renders the form. On submit:
+1. Walk rules in order; first match wins.
+2. If none match, use `fallback`.
+3. Record the response in `routing_form_responses` with `matchedRuleId`.
+4. If the action is `event-type`, redirect to Booker with prefilled
+   `name` / `email` / custom-field values from the form answers.
+
+## Common tasks
+
+| User | Action |
+|---|---|
+| "Route enterprise prospects to Bob" | `create-routing-form` with a rule matching company size → Bob's event type |
+| "See submissions" | `list-routing-form-responses --formId <id>` |

package/docs/skills/scheduling-basics/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: scheduling-basics
+description: Core concepts of the scheduling package — event types, schedules, bookings, hosts, teams, and how they compose.
+---
+
+# Scheduling basics
+
+The mental model:
+
+- **Event Type** — a definition of "a bookable thing" (30-minute intro call,
+  45-minute demo). Lives at `/:user/:slug` or `/team/:teamSlug/:slug`.
+- **Schedule** — a named set of availability rules ("Working Hours",
+  "Evenings"). Weekly intervals plus date-specific overrides. Each user
+  has a default schedule; event types can pick any.
+- **Booking** — the materialized appointment. Has attendees, references to
+  external systems (Google Calendar event, Zoom meeting), and a stable
+  iCalUID across reschedules.
+- **Host** — a user assigned to an event type. Hosts have weights and
+  priorities for round-robin.
+- **Team** — a group of users who can co-host event types.
+- **Location** — where the meeting happens. Video (built-in, Zoom, Meet,
+  Teams), phone, in-person, or custom link.
+
+## Workflows and routing forms
+
+- **Workflow** — trigger + ordered steps. "Email attendee 1h before event."
+- **Routing Form** — pre-booking form with rules that route to the right
+  event type based on answers. Like ChiliPiper.
+
+## Public URLs
+
+- `/:user` — user profile with event type list
+- `/:user/:slug` — Booker for a personal event type
+- `/:user/:slug/embed` — chromeless for iframe embedding
+- `/team/:teamSlug` — team profile
+- `/team/:teamSlug/:slug` — Booker for team event type (round-robin or collective)
+- `/d/:hash/:slug` — private hashed-link Booker
+- `/booking/:uid` — booking detail / manage
+- `/reschedule/:uid` — reschedule Booker
+- `/forms/:formId` — public routing form
+
+## Common tasks
+
+| User request | Action(s) |
+|---|---|
+| "Create a 30-minute intro meeting" | `create-event-type --title "Intro" --slug intro --length 30` |
+| "What's my availability tomorrow?" | `check-availability --slug <slug> --from ... --to ...` |
+| "Cancel my 3pm with Alex" | `list-bookings --status upcoming`, then `cancel-booking --uid ...` |
+| "Block next Friday" | `add-date-override --scheduleId <id> --date 2026-04-10 --intervals []` |
+| "Connect Google Calendar" | `connect-calendar --kind google_calendar --redirectUri ...` |
+| "Make a team event rotating between Alice and Bob" | `create-event-type --schedulingType round-robin --teamId ...`, then `set-event-type-hosts` |

package/docs/skills/slot-engine/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: slot-engine
+description: The pure `computeAvailableSlots` function — inputs, outputs, invariants, and debugging guide.
+---
+
+# Slot engine
+
+`import { computeAvailableSlots } from "@agent-native/scheduling/core"`
+
+## Inputs
+- Event type config (duration, buffers, minimum notice, period, limits,
+  slot interval)
+- Schedule (timezone + weekly availability + date overrides)
+- Busy intervals (UTC, aggregated from external calendars + existing
+  bookings)
+- Booking counts by bucket (day/week/month/year) for limit enforcement
+- Time range to compute over
+- Optional seats-per-slot + seats-taken map
+- Viewer timezone (for limit bucketing, if it differs from the schedule)
+
+## Output
+- Array of `Slot { start: ISO, end: ISO, available: boolean, seatsRemaining?, hostEmail? }`
+
+## Invariants
+
+The function guarantees, in order:
+
+1. No slot falls in the past (`now + minimumBookingNotice` is the floor).
+2. No slot overlaps a busy interval (with buffers applied).
+3. No slot falls outside the schedule's available intervals for that day.
+4. No slot exceeds a booking limit.
+5. No slot falls outside the event's period (rolling/range).
+6. DST-safe: we convert to UTC using the schedule's timezone before doing
+   any interval arithmetic.
+
+## Debugging
+
+If a slot is unexpectedly missing:
+1. Check the schedule's weekly availability for that day-of-week in the
+   schedule's timezone (not UTC — weekends can shift across the date line).
+2. Check date overrides for that local date (empty intervals = fully
+   blocked).
+3. Check merged busy intervals for overlap, *including* the before/after
+   buffer expansion.
+4. Check booking limits: a single existing booking can close a day.
+5. Check period caps: rolling periods restrict how far in the future slots
+   appear.
+
+If a slot is unexpectedly present:
+1. Check that `now` is being passed correctly (defaults to `new Date()`).
+2. Check that busy intervals from providers are in UTC.
+3. Confirm slot interval matches what you expect (default = duration).