Availability BookingCAUTION

A framework for building agentic apps

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: availability-booking
description: >-
  How the booking system works: checking availability, managing booking links,
  configuring availability settings, and the public booking URL pattern.
---

# Availability & Booking

The calendar app includes a booking system where users can share public URLs for others to book time. Availability is configured per-user, and bookings are stored in SQL via Drizzle ORM.

## Availability Settings

Availability is stored in the SQL settings table under the key `calendar-availability`. It defines which days and time windows the user is available.

```json
{
  "timezone": "America/Los_Angeles",
  "schedule": {
    "monday": [{ "start": "09:00", "end": "17:00" }],
    "tuesday": [{ "start": "09:00", "end": "17:00" }],
    "wednesday": [
      { "start": "09:00", "end": "12:00" },
      { "start": "13:00", "end": "17:00" }
    ],
    "thursday": [{ "start": "09:00", "end": "17:00" }],
    "friday": [{ "start": "09:00", "end": "16:00" }],
    "saturday": [],
    "sunday": []
  }
}
```

Read via: `readSetting("calendar-availability")`
Write via: `writeSetting("calendar-availability", { ... })`

## Checking Availability

The `check-availability` script finds open time slots for a given date by:

1. Reading the availability schedule from settings
2. Fetching events from Google Calendar for that date
3. Computing free slots by subtracting busy intervals from available windows

```bash
# Find 30-minute slots on a date
pnpm action check-availability --date 2026-04-05

# Find 60-minute slots
pnpm action check-availability --date 2026-04-05 --duration 60
```

Required: `--date` (YYYY-MM-DD format).
Optional: `--duration` (minimum slot length in minutes, default 30).

## Booking Links

Booking links are stored in SQL via Drizzle ORM. Each link has a slug, duration, and associated availability.

Booking links can also have required co-hosts. The owner is always included;
`hosts` stores additional required co-hosts:

```bash
pnpm action create-booking-link \
  --title "Steve + Brent" \
  --slug "steve-brent-30" \
  --duration 30 \
  --hosts "[email protected]"
```

Use `update-booking-link` to add or remove co-hosts on an existing link. Group
booking links only show slots when the owner and every co-host can be checked as
free. When a booking is confirmed, the app creates the Google Calendar event on
the owner's connected account and adds co-hosts as invited attendees.

### Peer working-hours hard filtering

A co-host gets working-hours-aware scheduling only when the owner has also
added that person to their calendar overlay ("subscribed to their calendar")
via `add-overlay-person`, AND that person has reciprocally added the owner
back to their own overlay list. `getEligibleHostAvailability`
(`server/lib/booking-host-availability.ts`) enforces this two-way check before
reading a peer's private `calendar-availability`/`calendar-settings` — overlay
membership is just the owner's own setting, so without the reciprocal check an
owner could add any registered email with no relationship required and have
that stranger's private schedule and time zone read and enriched onto an
anonymous public booking link. For reciprocally-overlaid hosts, the
booking-link slot generator additionally intersects the owner's
`weeklySchedule` with the host's own saved `calendar-availability` schedule
(converted through the host's own time zone) before checking Google free/busy
— so a group link never offers a time outside either person's working hours.
Co-hosts who aren't in a two-way overlay relationship with the owner keep the
original free/busy-only behavior; the UI picks hosts from the overlay list via
a combobox in `BookingHostsEditor` (`app/pages/BookingLinksPage.tsx`), but
still allows a raw email for hosts who should only be checked for conflicts.

The public booking page also exposes each eligible host's resolved IANA time
zone (never their raw schedule) so the booker can reveal a "Show time zones"
grid comparing every host's local time for the same slots, in addition to
their own browser time zone shown by default.

### Working-hours status and the "send request" flow

`BookingHostsEditor` (`app/pages/BookingLinksPage.tsx`) shows a per-host icon
saying whether that host's real working hours are actually being used for the
link. Four states, backed by `getHostOverlayStatuses`
(`server/lib/booking-host-availability.ts`) through the
`get-host-overlay-status` action:

- reciprocal **and** has a saved schedule + resolvable time zone — applied.
- reciprocal but no saved schedule — not applied, and **no action offered**.
  The peer has already done their part; only they can add their own schedule.
- in the owner's overlay list but not reciprocal — not applied, and the only
  state with a `send-overlay-request` button.
- a manual raw-email host — not applied, and offers "Add to my calendar"
  (`add-overlay-person`) rather than a request, because `send-overlay-request`
  rejects any address outside the owner's overlay list.

`reciprocal` and `hasWorkingHours` are reported as two independent booleans and
must not be collapsed into one "applied" flag: the two failure modes are
indistinguishable in the final availability result but need different copy, and
only one of them is actionable by the owner.

The manual state is derived on the client, not returned by the server.
`getHostOverlayStatuses` only ever returns rows for emails already in the
owner's `calendar-overlay-people`; widening it to report on arbitrary addresses
would make it an oracle for probing whether an address has a Calendar account
and a saved schedule.

**Identity.** Both actions resolve the owner from the booking-link row's
persisted `ownerEmail`, never from the signed-in caller, because links are
shareable with non-owner editors and the working-hours relationship is always
about the _owner's_ calendar. Only a brand-new unsaved draft (no
`bookingLinkId` yet) treats the caller as the presumptive owner. When the
caller is n

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.agents/skills/an

.agents/skills/content-product-development

.agents/skills/design-exploration

.agents/skills/turn-into-app

.agents/skills/visual-edit

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Availability Booking](https://modelsatlas.com/skills/builderio/availability-booking/badge.svg)](https://modelsatlas.com/skills/builderio/availability-booking/)

Not your listing, or something out of date? Claim or update your listing.