@agent-native/core 0.122.4 → 0.123.0

package/corpus/core/docs/content/template-calendar-agent.mdx

@@ -0,0 +1,133 @@
+---
+title: "Calendar: Talking to the Agent"
+description: "What the agent sees when you're in Calendar, prompts organized by task, and when it reaches for the raw Google Calendar API instead of a canned action."
+---
+
+# Talking to the Agent
+
+Everything in Calendar is available to the agent through the same actions the UI uses, so anything you can click, you can also ask for in plain English. This page covers how the agent sees your screen, useful prompts by task, and where it escalates beyond the built-in actions. See [Calendar](/docs/template-calendar) for the overview.
+
+## How the agent sees your screen
+
+The agent always knows the current calendar view, the date range you're looking at, and the event you have selected. That's why "reschedule this" or "who's on this call" resolves correctly without you naming the event — the agent already knows which one "this" refers to.
+
+## Useful prompts by task
+
+**Schedule**
+
+- "Schedule a 30-minute call with Alex tomorrow at 2pm."
+- "Create a Zoom meeting with the design team Thursday at 10."
+- "Set me as out of office Friday."
+
+**Find time**
+
+- "Find a 1-hour slot next week with Sam and Priya and book 'Planning' on it."
+- "Am I free Thursday afternoon?"
+
+**Manage events**
+
+- "Move this event to Friday at 2pm." (with an event selected)
+- "Add Jordan to this meeting as an optional guest."
+- "Accept this invite." / "Decline with a note that I'm out that day."
+- "Delete this meeting, just for me — I'm not the organizer."
+
+**Booking links**
+
+- "Create a 15-minute intro booking link with a name field."
+- "Add Brent as a required co-host on my 'Steve + Brent' link."
+- "Pause my '30 min demo' link."
+- "Show me this week's bookings."
+
+**People and view**
+
+- "Who is jane at acme.com?"
+- "Add Priya's calendar to my view."
+- "Switch to day view and jump to next Monday."
+
+## Group and co-host booking links
+
+When a booking link has required co-hosts, the agent (and the UI) only offers a slot when the owner _and_ every co-host are free — it checks all of their calendars, not just the owner's. Once someone books, the agent invites every co-host to the created Google Calendar event alongside the visitor.
+
+<Diagram id="doc-block-calendar5" title="How a scheduling request flows" summary="Whether you click in the calendar or ask the agent, the same actions read live from Google Calendar and write back to the same view. Zoom and people search plug into the same flow.">
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-col">
+    <div class="diagram-node">
+      You click<br /><small class="diagram-muted"
+        >drag, toolbar, shortcuts</small
+      >
+    </div>
+    <div class="diagram-node">
+      You ask the agent<br /><small class="diagram-muted"
+        >"find a 1-hour slot next week"</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Actions</span
+    ><small class="diagram-muted"
+      >list-events · find-a-time · search-people · create-event</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-col">
+    <div class="diagram-box">
+      Google Calendar<br /><small class="diagram-muted"
+        >live, multi-account</small
+      >
+    </div>
+    <div class="diagram-box">
+      Zoom<br /><small class="diagram-muted">meeting created on booking</small>
+    </div>
+    <div class="diagram-box">
+      SQL<br /><small class="diagram-muted">bookings · availability</small>
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
+  <div class="diagram-box">Calendar view updates live</div>
+</div>
+```
+
+```css
+.diagram-flow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-flow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-flow .diagram-arrow {
+  font-size: 22px;
+  line-height: 1;
+}
+.diagram-flow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+## When the agent goes straight to the Google Calendar API
+
+The built-in actions (`list-events`, `search-events`, `find-a-time`, and so on) cover everyday scheduling. For requests that need an exact Google Calendar endpoint, filter, or pagination mode the actions don't expose — for example scanning every event across six months for a report, or an unusual calendar-list query — the agent can call the real Google Calendar API directly instead of forcing the answer through a narrower action. For large scans, it stages the results into a scratch dataset and works from a compact summary rather than dumping thousands of events into the conversation. You'll typically notice this as "let me pull that directly from Google Calendar" on requests that go beyond a normal schedule question.
+
+## Extensions
+
+Calendar supports Extensions — small sandboxed widgets you or the agent can build and drop into the app. The event detail panel exposes a slot at the bottom where an extension can render, with the event's id, title, times, timezones, location, attendees, and account already available to it. See [Extensions](/docs/extensions) for how to build one.
+
+## What's next
+
+- [**Calendar**](/docs/template-calendar) — the overview and getting-started steps
+- [**Events, Availability & Finding Time**](/docs/template-calendar-scheduling) — views, availability, and finding time
+- [**Booking Links**](/docs/template-calendar-booking-links) — the public scheduling pages these prompts manage
+- [**Developer Guide**](/docs/template-calendar-developers) — every action, the data model, and how to extend the app
+- [**Extensions**](/docs/extensions) — building a widget for the event-detail slot

package/corpus/core/docs/content/template-calendar-booking-links.mdx

@@ -0,0 +1,73 @@
+---
+title: "Calendar: Booking Links"
+description: "Create Calendly-style public booking pages, connect Zoom or Google Meet, and manage bookings people make with you."
+---
+
+# Booking Links
+
+Booking links are public pages where anyone can pick a time and book it directly onto your calendar — the Calendly-style part of Calendar. This page covers creating, sharing, and managing them. See [Calendar](/docs/template-calendar) for the overview and [Events, Availability & Finding Time](/docs/template-calendar-scheduling) for the availability rules booking links use.
+
+## Creating a booking link
+
+A booking link needs a title and a duration (like "15 min intro" at 15 minutes). From there you can add:
+
+- **Alternate durations** so a visitor can choose 15, 30, or 60 minutes on the same link
+- **Custom fields** to collect a company name, a topic, or anything else before the meeting
+- **A conferencing choice** — Google Meet, Zoom (once connected — see below), or a custom link
+- **A color** so the link's bookings stand out on your calendar
+- **Required co-hosts** — other people who must also be free before a slot is offered. When someone books, everyone (you and your co-hosts) gets invited to the resulting Google Calendar event.
+
+Ask the agent to create one ("Create a 15-minute intro link with a name and company field") or use **New booking link** in the sidebar.
+
+## Connecting Zoom or Google Meet
+
+Booking links can generate a real video meeting automatically when someone books:
+
+- **Google Meet** needs no setup — it's added the same way any Google Calendar invite gets a Meet link.
+- **Zoom** needs your Zoom account connected first. Connect it once from Settings; after that, any booking link set to Zoom creates a real Zoom meeting for each new booking and attaches the join link to the confirmation.
+
+If Zoom isn't connected yet and a link is set to use it, ask the agent to help you connect it, or do it from Settings directly.
+
+## Sharing a booking link with teammates
+
+Sharing controls who can _manage_ the link — edit its duration, pause it, or see its bookings — through the standard viewer/editor/admin roles. It's separate from public access: anyone with the URL can still book as long as the link is active, whether or not they have management access.
+
+## The public booking page
+
+Every booking link has a public URL at `/book/{your-booking-name}/{slug}` — for example `/book/steve/30min`. Your booking name is generated automatically from your email the first time you create a link, and you can change it later from Settings (up to three times every 30 days, since it's part of every public link you've shared).
+
+A visitor picks an available time from your real availability, fills in their name, email, and any custom fields you added, then confirms. They get a confirmation with a link to manage their own booking.
+
+<WireframeBlock id="doc-block-calendar4">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;min-height:480px;box-sizing:border-box;padding:36px 60px;gap:16px'><h2 style='margin:0'>30 min with Steve</h2><p class='wf-muted' style='margin:0'>Quick intro call — tell me a bit about what you're working on.</p><div style='display:flex;gap:20px;flex:1'><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><strong>May 2026</strong><div style='display:grid;grid-template-columns:repeat(7,1fr);gap:6px'><span class='wf-muted'>Su</span><span class='wf-muted'>Mo</span><span class='wf-muted'>Tu</span><span class='wf-muted'>We</span><span class='wf-muted'>Th</span><span class='wf-muted'>Fr</span><span class='wf-muted'>Sa</span><span></span><span></span><span></span><span></span><span></span><span class='wf-pill accent'>1</span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><strong>Friday, May 1</strong><button>9:00 AM</button><button>9:30 AM</button><button class='primary'>10:00 AM</button><button>10:30 AM</button><button>2:00 PM</button></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## Managing, rescheduling, or cancelling a booking
+
+Every confirmation includes a private manage link. Visitors use it to reschedule to a different open slot or cancel outright, without needing an account — no sign-in, since the link itself is the credential. You (the host) see all bookings, past and upcoming, in the **Bookings** list.
+
+## Renaming a link
+
+You can change a booking link's URL slug at any time — for example from `/book/steve/into-call` to `/book/steve/intro`. The old URL keeps working: visitors who still have the old link are automatically forwarded to the new one, so nothing you've already shared (an email signature, a website) breaks.
+
+### Useful prompts
+
+- "Create a 15-minute intro booking link with a name and company field."
+- "Add Brent as a required co-host on my 'Steve + Brent' link."
+- "Switch my '30 min demo' link to Zoom."
+- "Pause my '30 min demo' booking link."
+- "Rename my intro link's URL to '/intro'."
+- "Show me this week's bookings."
+
+## What's next
+
+- [**Calendar**](/docs/template-calendar) — the overview and getting-started steps
+- [**Events, Availability & Finding Time**](/docs/template-calendar-scheduling) — the availability rules booking links draw from
+- [**Talking to the Agent**](/docs/template-calendar-agent) — group/co-host links and more prompts
+- [**Developer Guide**](/docs/template-calendar-developers) — the booking data model and actions
+- [**Sharing**](/docs/sharing) — the share-grant model booking links build on

package/corpus/core/docs/content/template-calendar-developers.mdx

@@ -0,0 +1,366 @@
+---
+title: "Calendar: Developer Guide"
+description: "Quick start, the full action inventory, data model, routes, and how to extend the Calendar template."
+---
+
+# Developer Guide
+
+This page is for anyone forking the Calendar template or extending it: the quick start, every action, the data model, the route surface, and how to add to it. See [Calendar](/docs/template-calendar) for what the app does.
+
+## Quick start
+
+```bash
+npx @agent-native/core@latest create my-calendar --standalone --template calendar
+```
+
+See [Getting started](/docs/getting-started) for installing dependencies and running the dev server.
+
+To connect Google Calendar in dev, open the Settings view, paste a `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` from [Google Cloud Console](https://console.cloud.google.com/), and click "Connect Google Calendar." The OAuth redirect URI is `http://localhost:8082/_agent-native/google/callback` in dev (8082 is the default Calendar dev port). Tokens are stored in the framework `oauth_tokens` table and refresh automatically.
+
+To enable Zoom conferencing on booking links, set `ZOOM_CLIENT_ID` and `ZOOM_CLIENT_SECRET` from a [Zoom OAuth app](https://marketplace.zoom.us/). Its redirect URI is `/_agent-native/zoom/callback`. Without these set, booking links can still offer Google Meet — Zoom just won't appear as a conferencing option.
+
+<Callout tone="info">
+
+**Events live in Google Calendar, not SQL.** Every event action calls the Google Calendar API directly — there is no local events table. Only booking links, bookings, availability, and connection state are stored locally. Never read or write event data with raw SQL.
+
+</Callout>
+
+## Action inventory
+
+Every operation is a TypeScript file in `templates/calendar/actions/`, auto-mounted at `POST /_agent-native/actions/:name`.
+
+**Events & guests** — event data lives in Google Calendar, never SQL:
+
+- `list-events`, `search-events`, `get-event` — read events in a range or by id
+- `create-event`, `update-event`, `delete-event` — write events, including recurrence (RRULE), working locations, and status types (`outOfOffice`, `focusTime`)
+- `manage-event-draft` — stage an unsent invite for user review before anything is written or guests are notified
+- `rsvp-event` — accept/decline/tentative on an invitation
+- `get-attendee-timezones`, `set-attendee-timezone` — per-guest timezone overrides for showing local times
+
+**Availability & finding time:**
+
+- `get-availability`, `update-availability` — the weekly schedule, timezone, buffer, notice, and advance-window settings
+- `check-availability` — open slots for one date
+- `find-a-time` — shared free-slot search across an organizer and named attendees, combining Google free/busy with local conflicts
+
+**Booking links & bookings:**
+
+- `create-booking-link`, `update-booking-link`, `duplicate-booking-link` — link lifecycle, including co-hosts (`hosts`)
+- `list-booking-links`, `list-bookings` — accessible links and their confirmed appointments
+
+**External calendars (read-only ICS feeds):**
+
+- `add-external-calendar`, `list-external-calendars`, `remove-external-calendar`, `update-external-calendars`
+
+**People & overlays:**
+
+- `search-people` — Google Contacts + Workspace directory search
+- `get-overlay-people`, `update-overlay-people` — other people's calendars pinned into your view
+
+**Zoom:**
+
+- `get-zoom-status` — connection status for the current user; connect/disconnect happen through `/_agent-native/zoom/*` routes, not an action, since OAuth needs the signed-in browser session
+
+**Google Calendar connection & sync:**
+
+- `connect-google-calendar` — returns the OAuth connect URL for the signed-in browser session
+- `sync-google-calendar` — forces a resync
+
+**Settings & preferences:**
+
+- `get-settings`, `update-settings` — user-level settings
+- `update-calendar-visual-preferences` — local-only display prefs (event colors, hidden weekends); never touches Google Calendar
+
+**Navigation & UI state:**
+
+- `navigate` — moves the UI to a view, date, or event
+- `view-screen` — reads the current view back for the agent
+
+**Provider API escalation** — the raw Google Calendar (and connected CRM) API, for when the actions above are too narrow:
+
+- `provider-api-catalog`, `provider-api-docs`, `provider-api-request`
+- `list-staged-datasets`, `query-staged-dataset`, `delete-staged-dataset` — for staging and querying large scans instead of returning raw results
+
+## Data model
+
+Defined in `templates/calendar/server/db/schema.ts`. Only non-event data is stored locally — events themselves live in Google Calendar.
+
+<DataModel
+  id="doc-block-calendar6"
+  title="Calendar data model"
+  summary={
+    "Only non-event data is stored locally — events live in Google Calendar. Booking links use ownableColumns so the sharing system applies; booking usernames are a separate reservation table because a username is shared across every link a user owns."
+  }
+  entities={[
+    {
+      id: "booking_links",
+      name: "booking_links",
+      note: "Calendly-style link definitions (ownable)",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        {
+          name: "slug",
+          type: "string",
+          note: "unique; public page at /book/{username}/{slug}",
+        },
+        { name: "title", type: "string" },
+        { name: "description", type: "string", nullable: true },
+        { name: "duration", type: "int", note: "primary duration in minutes" },
+        {
+          name: "durations",
+          type: "json",
+          nullable: true,
+          note: "alternative durations",
+        },
+        {
+          name: "hosts",
+          type: "json",
+          nullable: true,
+          note: "required co-hosts besides the owner",
+        },
+        { name: "customFields", type: "json", nullable: true },
+        {
+          name: "conferencing",
+          type: "json",
+          nullable: true,
+          note: "none | google_meet | zoom | custom",
+        },
+        { name: "color", type: "string", nullable: true },
+        { name: "isActive", type: "bool", note: "pause without deleting" },
+        { name: "ownerEmail", type: "string" },
+        { name: "orgId", type: "id", nullable: true },
+      ],
+    },
+    {
+      id: "bookings",
+      name: "bookings",
+      note: "Confirmed appointments from public booking pages",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "slug", type: "string", fk: "booking_links.slug" },
+        { name: "name", type: "string" },
+        { name: "email", type: "string" },
+        { name: "start", type: "datetime" },
+        { name: "end", type: "datetime" },
+        { name: "eventTitle", type: "string", nullable: true },
+        { name: "notes", type: "string", nullable: true },
+        {
+          name: "fieldResponses",
+          type: "json",
+          nullable: true,
+          note: "custom field responses",
+        },
+        {
+          name: "meetingLink",
+          type: "string",
+          nullable: true,
+          note: "Zoom, Google Meet, or custom",
+        },
+        { name: "googleEventId", type: "string", nullable: true },
+        {
+          name: "calendarAccountId",
+          type: "string",
+          nullable: true,
+          note: "connected account that owns the event",
+        },
+        {
+          name: "cancelToken",
+          type: "string",
+          note: "powers /booking/manage/{token}",
+        },
+        { name: "status", type: "enum", note: "confirmed | cancelled" },
+        { name: "ownerEmail", type: "string" },
+        { name: "orgId", type: "id", nullable: true },
+      ],
+    },
+    {
+      id: "booking_slug_redirects",
+      name: "booking_slug_redirects",
+      note: "Keeps old public URLs working after a link's slug is renamed",
+      fields: [
+        { name: "oldSlug", type: "string", pk: true },
+        {
+          name: "newSlug",
+          type: "string",
+          note: "the link's current slug",
+        },
+        { name: "createdAt", type: "datetime" },
+      ],
+    },
+    {
+      id: "booking_usernames",
+      name: "booking_usernames",
+      note: "Reserves the {username} segment of /book/{username}/{slug}, one per owner",
+      fields: [
+        { name: "username", type: "string", pk: true },
+        {
+          name: "ownerEmail",
+          type: "string",
+          note: "unique — one booking username per user",
+        },
+        { name: "createdAt", type: "datetime" },
+        { name: "updatedAt", type: "datetime" },
+      ],
+    },
+    {
+      id: "booking_username_changes",
+      name: "booking_username_changes",
+      note: "Audit trail enforcing the 3-changes-per-30-days rate limit",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "ownerEmail", type: "string" },
+        { name: "oldUsername", type: "string", nullable: true },
+        { name: "newUsername", type: "string" },
+        { name: "createdAt", type: "datetime" },
+      ],
+    },
+    {
+      id: "booking_link_shares",
+      name: "booking_link_shares",
+      note: "Share grants for booking links",
+      fields: [
+        { name: "id", type: "id", pk: true },
+        { name: "linkId", type: "id", fk: "booking_links.id" },
+        { name: "principal", type: "string", note: "user or org" },
+        { name: "role", type: "enum", note: "viewer | editor | admin" },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "booking_links",
+      to: "bookings",
+      kind: "1-n",
+      label: "has bookings",
+    },
+    {
+      from: "booking_links",
+      to: "booking_link_shares",
+      kind: "1-n",
+      label: "has share grants",
+    },
+  ]}
+/>
+
+Availability rules live in per-user settings under the `calendar-availability` key; overlay people under `calendar-overlay-people`; attendee timezone overrides under `attendee-timezones`; subscribed ICS feeds under `external-calendars`. Google and Zoom OAuth tokens live in the framework `oauth_tokens` table. Ephemeral UI state (current view, date, selected event) lives in `application_state` under the `navigation` key.
+
+## An action walked through
+
+`create-booking-link` shows the two guardrails every booking-link write needs: a validated slug and a check against the other table that can claim one.
+
+<AnnotatedCode
+  id="doc-block-calendar8"
+  title="Creating a booking link"
+  filename="templates/calendar/actions/create-booking-link.ts"
+  language="ts"
+  code={
+    'import { defineAction } from "@agent-native/core";\nimport {\n  getRequestUserEmail,\n  getRequestOrgId,\n} from "@agent-native/core/server/request-context";\nimport { eq } from "drizzle-orm";\nimport { nanoid } from "nanoid";\nimport { z } from "zod";\n\nimport { getDb, schema } from "../server/db/index.js";\nimport { normalizeBookingDurationInput } from "../server/lib/booking-durations.js";\nimport {\n  rowToBookingLink,\n  serializeBookingHosts,\n} from "../server/lib/booking-link-utils.js";\n\nconst hostsSchema = z\n  .union([\n    z.array(\n      z.union([\n        z.string(),\n        z.object({\n          email: z.string(),\n          displayName: z.string().optional(),\n        }),\n      ]),\n    ),\n    z.string(),\n  ])\n  .optional();\n\nexport default defineAction({\n  description:\n    "Create a new booking link/event type. Use this instead of raw SQL for booking links.",\n  schema: z.object({\n    title: z.string().min(1).describe("Booking link title"),\n    slug: z\n      .string()\n      .min(1)\n      .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)\n      .describe("URL slug, lowercase words separated by hyphens"),\n    duration: z.coerce\n      .number()\n      .int()\n      .min(5)\n      .max(24 * 60)\n      .describe("Default duration in minutes"),\n    description: z.string().optional().describe("Description"),\n    durations: z\n      .array(\n        z.coerce\n          .number()\n          .int()\n          .min(5)\n          .max(24 * 60),\n      )\n      .optional()\n      .describe("Optional duration choices, e.g. [30,45,60]"),\n    hosts: hostsSchema.describe(\n      "Required co-hosts besides the owner. Accepts emails, comma-separated emails, or {email, displayName} objects.",\n    ),\n    customFields: z.array(z.any()).optional().describe("Custom form fields"),\n    conferencing: z.any().optional().describe("Conferencing configuration"),\n    color: z.string().optional().describe("Display color"),\n    isActive: z.boolean().optional().describe("Whether the link is active"),\n  }),\n  run: async (args) => {\n    const body = args as Record<string, any>;\n    const durationInput = normalizeBookingDurationInput({\n      duration: body.duration,\n      durations: body.durations,\n    });\n    if ("error" in durationInput) {\n      throw new Error(durationInput.error);\n    }\n    const slug = String(body.slug).trim().toLowerCase();\n    const [existingLink, existingRedirect] = await Promise.all([\n      getDb()\n        .select({ id: schema.bookingLinks.id })\n        .from(schema.bookingLinks)\n        .where(eq(schema.bookingLinks.slug, slug)),\n      getDb()\n        .select({ oldSlug: schema.bookingSlugRedirects.oldSlug })\n        .from(schema.bookingSlugRedirects)\n        .where(eq(schema.bookingSlugRedirects.oldSlug, slug)),\n    ]);\n\n    if (existingLink.length > 0 || existingRedirect.length > 0) {\n      throw new Error("A booking link with this slug already exists");\n    }\n\n    const now = new Date().toISOString();\n    const id = nanoid();\n    const ownerEmail = (() => {\n      const e = getRequestUserEmail();\n      if (!e) throw new Error("no authenticated user");\n      return e;\n    })();\n    await getDb()\n      .insert(schema.bookingLinks)\n      .values({\n        id,\n        slug,\n        title: String(body.title).trim(),\n        description: body.description ? String(body.description).trim() : null,\n        duration: durationInput.duration,\n        durations: durationInput.durations\n          ? JSON.stringify(durationInput.durations)\n          : null,\n        hosts: serializeBookingHosts(body.hosts, ownerEmail),\n        customFields: body.customFields\n          ? JSON.stringify(body.customFields)\n          : null,\n        conferencing: body.conferencing\n          ? JSON.stringify(body.conferencing)\n          : null,\n        color: body.color ? String(body.color).trim() : null,\n        isActive: body.isActive ?? true,\n        ownerEmail,\n        orgId: getRequestOrgId(),\n        createdAt: now,\n        updatedAt: now,\n      });\n\n    const created = await getDb()\n      .select()\n      .from(schema.bookingLinks)\n      .where(eq(schema.bookingLinks.id, id));\n    return rowToBookingLink(created[0]);\n  },\n});'
+  }
+  annotations={[
+    {
+      lines: "38-42",
+      label: "Slug format is validated up front",
+      note: "The regex enforces lowercase, hyphen-separated URL slugs before anything touches the database, so a malformed slug never reaches the uniqueness check below.",
+    },
+    {
+      lines: "59-61",
+      label: "Hosts are optional",
+      note: "Omitting `hosts` creates a solo link. A non-empty list becomes required co-hosts who must also be free before `find-a-time` offers a slot.",
+    },
+    {
+      lines: "76-90",
+      label: "A slug must be free in two tables",
+      note: "A new slug has to be unused in both `booking_links` and `booking_slug_redirects` — otherwise a fresh link could silently claim a URL an older, renamed link still forwards visitors from.",
+    },
+    {
+      lines: "110",
+      label: "Co-host input is normalized once",
+      note: "`serializeBookingHosts` accepts emails, comma-separated strings, or `{email, displayName}` objects and always stores the same JSON shape, so every reader only handles one format.",
+    },
+  ]}
+/>
+
+## Routes reference
+
+<FileTree
+  id="doc-block-calendar7"
+  title="Calendar template layout"
+  entries={[
+    {
+      path: "actions/",
+      note: "every agent-callable action — events, availability, booking, people, Zoom, sharing",
+    },
+    {
+      path: "app/routes/_app._index.tsx",
+      note: "the main calendar view (day/week/month)",
+    },
+    { path: "app/routes/_app.agent.tsx", note: "full-page agent chat tab" },
+    {
+      path: "app/routes/_app.availability.tsx",
+      note: "the availability editor",
+    },
+    {
+      path: "app/routes/_app.booking-links._index.tsx",
+      note: "booking link list; _app.booking-links.$id.tsx edits one",
+    },
+    { path: "app/routes/_app.bookings.tsx", note: "confirmed bookings list" },
+    {
+      path: "app/routes/_app.extensions.tsx",
+      note: "Extension widget routes",
+    },
+    {
+      path: "app/routes/_app.settings.tsx",
+      note: "Google/Zoom connect, availability defaults, sharing",
+    },
+    {
+      path: "app/routes/book.$username.$slug.tsx",
+      note: "the public booking page (canonical: /book/{username}/{slug})",
+    },
+    {
+      path: "app/routes/booking.manage.$token.tsx",
+      note: "the visitor's reschedule/cancel page",
+    },
+    {
+      path: "app/routes/event.tsx",
+      note: "standalone inline event-preview page the agent embeds in chat",
+    },
+    {
+      path: "server/db/schema.ts",
+      note: "Drizzle tables — booking_links, bookings, booking_usernames, shares",
+    },
+    { path: "server/lib/zoom.ts", note: "Zoom OAuth + meeting creation" },
+    {
+      path: "server/lib/google-calendar.ts",
+      note: "the Google Calendar API client",
+    },
+    {
+      path: "shared/api.ts",
+      note: "shared TypeScript types used by server and client",
+    },
+  ]}
+/>
+
+Two legacy routes stay mounted for links shared before a URL scheme changed: `book.$slug.tsx` (no username segment) and `meet.$username.$slug.tsx`, both of which canonicalize to `/book/:username/:slug`. `_app.team.tsx` redirects to `/settings#organization` — team management lives in Settings, not a separate page.
+
+## Customizing it
+
+Every part of the app is editable source. Start here:
+
+- `templates/calendar/actions/` — add a new file with `defineAction` to expose new capability to both the agent and the frontend.
+- `templates/calendar/app/routes/` — the UI, listed above.
+- `templates/calendar/server/db/schema.ts` — add columns or tables with Drizzle. Keep the code dialect-agnostic so the template runs on SQLite, Postgres, Turso, D1, and Neon.
+- `templates/calendar/server/lib/` — provider integrations: `google-calendar.ts`, `zoom.ts`, `people-search.ts`, `ical-fetcher.ts`, `find-time.ts`, `provider-api.ts`.
+- `templates/calendar/AGENTS.md` — agent instructions. Update this when you teach the agent new capabilities or conventions.
+- `templates/calendar/.agents/skills/` — detailed patterns the agent follows. Relevant skills: `event-management`, `availability-booking`, `real-time-sync`, `storing-data`, `delegate-to-agent`, `frontend-design`.
+- `templates/calendar/shared/api.ts` — the shared TypeScript types (`CalendarEvent`, `BookingLink`, `ExternalCalendar`, `ConferencingConfig`, etc.) used by both the server and the client.
+
+If you add a feature, remember to update all four areas: UI, action, skill or AGENTS.md entry, and any application state the agent needs to see. That is what keeps the agent and the UI in parity.
+
+## What's next
+
+- [**Calendar**](/docs/template-calendar) — the overview and getting-started steps
+- [**Events, Availability & Finding Time**](/docs/template-calendar-scheduling) — the user-facing behavior these actions power
+- [**Booking Links**](/docs/template-calendar-booking-links) — the user-facing behavior this data model powers
+- [**Talking to the Agent**](/docs/template-calendar-agent) — how the agent chooses between these actions and the raw Google Calendar API
+- [**Actions**](/docs/actions) — the action system this template is built on
+- [**Sharing**](/docs/sharing) — the share-grant model `booking_link_shares` uses