@agent-native/core 0.172.4 → 0.172.8

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

@@ -1,52 +1,89 @@
 ---
-title: "Calendar: Talking to the Agent"
+title: "Calendar: Talk 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
+# Talk 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.
+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**
+Every prompt below becomes a real action against your actual calendar, the
+same one the UI reads and writes. Here's one worked example:
 
-- "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."
+<Comparison>
 
-**Find time**
+### :blue: You ask
 
-- "Find a 1-hour slot next week with Sam and Priya and book 'Planning' on it."
-- "Am I free Thursday afternoon?"
+"Am I free Thursday afternoon?"
 
-**Manage events**
+### :green: What happens
 
-- "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."
+This is a read-only question. The agent checks your real calendar and
+availability rules, then answers directly in chat, for example "You're open
+from 1 to 4pm." Nothing on your screen changes, since nothing was created or
+moved.
 
-**Booking links**
+</Comparison>
 
-- "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."
+<Cards columns={2}>
 
-**People and view**
+### Schedule
+
+- **"Schedule a 30-minute call with Alex tomorrow at 2pm."** The event
+  appears on your calendar the moment it's created. No dialog needed.
+- **"Create a Zoom meeting with the design team Thursday at 10."** Same as
+  above, and a Zoom link is attached automatically.
+- **"Set me as out of office Friday."** An all-day out-of-office event shows
+  up on your calendar right away.
+
+### Find time
+
+- **"Find a 1-hour slot next week with Sam and Priya and book 'Planning' on
+  it."** The agent checks everyone's real availability, then the new event
+  appears on your calendar live. No dialog needed.
+
+### Manage events
+
+_With an event selected, "this" and "this meeting" resolve on their own._
+
+- **"Move this event to Friday at 2pm."** The event moves on your calendar
+  grid live.
+- **"Add Jordan to this meeting as an optional guest."** Jordan shows up in
+  the attendee list immediately.
+- **"Accept this invite." / "Decline with a note that I'm out that day."**
+  Your RSVP updates on the event right away.
+- **"Delete this meeting, just for me. I'm not the organizer."** The meeting
+  disappears from your calendar. Other attendees still see it on theirs.
+
+### Booking links
+
+- **"Create a 15-minute intro booking link with a name field."** The new
+  meeting type appears in your Booking Links list live.
+- **"Add Brent as a required co-host on my 'Steve + Brent' link."** Brent
+  shows up as a co-host immediately, and future slots only open when you're
+  both free.
+- **"Pause my '30 min demo' link."** The link shows as paused right away and
+  stops accepting new bookings.
+- **"Show me this week's bookings."** A read-only question. The agent
+  answers in chat with the list.
+
+### 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."
 
+</Cards>
+
 ## 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.
+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.">
 
@@ -118,16 +155,16 @@ When a booking link has required co-hosts, the agent (and the UI) only offers a
 
 ## 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.
+The built-in actions (`list-events`, `search-events`, `find-a-time`, and so on) cover everyday scheduling. Some requests need an exact Google Calendar endpoint, filter, or pagination mode that the actions don't expose, like scanning every event across six months for a report, or an unusual calendar-list query. For those, 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.
+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
+- [**Features**](/docs/template-calendar-features) — views, availability, finding time, and booking links, with setup steps for each
+- [**Calendar in a Multi-App Workspace**](/docs/template-calendar-integrations) — integration strategies and connecting to Dispatch
 - [**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/docs/content/template-calendar-developers.mdx

@@ -9,15 +9,91 @@ This page is for anyone customizing the Calendar template or extending it: the q
 
 ## Quick start
 
+This walks through running Calendar from nothing installed to a connected
+Google Calendar. The commands are identical whether you're in Terminal on
+macOS or PowerShell/Command Prompt on Windows, they're plain Node.js tooling.
+
+<Steps>
+
+### Create the app
+
 ```bash
 npx @agent-native/core@latest create my-calendar --standalone --template calendar
+cd my-calendar
+pnpm install
+```
+
+This needs [Node.js](https://nodejs.org) 22 or later and
+[pnpm](https://pnpm.io) installed first. See
+[Getting started](/docs/getting-started) if you haven't installed either
+yet, or don't have an LLM connection (Builder.io, an Anthropic/OpenAI key,
+or local Ollama) set up.
+
+### Start the dev server
+
+```bash
+pnpm dev
+```
+
+The app opens at `http://localhost:8082`. If it doesn't open automatically,
+visit that URL in your browser. Calendar works fully with Google
+disconnected. You'll only hit an error if you try an action that needs it
+before connecting.
+
+### Connect Google Calendar
+
+In the app, open **Settings**, and on the **General** tab find the **Google
+Calendar** card, then click **Connect Google Calendar**. This opens a setup
+wizard:
+
+1. **Create a Google Cloud project**, if you don't already have one to use:
+   in [Google Cloud Console](https://console.cloud.google.com/), click the
+   project dropdown near the top of the page, then **New Project**. Give it
+   any name, click **Create**, and wait for the notification that it's
+   ready. Make sure it's selected in that same dropdown before continuing.
+2. **Enable the API**: with your project selected, go to **APIs & Services
+   → Library**, search for "Google Calendar API," open it, and click
+   **Enable**.
+3. **Configure the consent screen**: under **APIs & Services → OAuth
+   consent screen**, set one up ("External" is fine for development).
+4. **Create credentials**: under **APIs & Services → Credentials**, create
+   an OAuth client ID of type "Web application," and add
+   `http://localhost:8082/_agent-native/google/callback` as an authorized
+   redirect URI (8082 is Calendar's default dev port).
+5. **Add the credentials**: download the credentials JSON and upload it in
+   the wizard, or toggle "Paste manually" and enter the Client ID and Client
+   Secret directly.
+
+Calendar saves these to its own secret store, not a `.env` file, so this
+step is identical on Windows and macOS. Tokens refresh automatically once
+connected.
+
+### Connect Zoom (optional)
+
+Unlike Google, Zoom has no Settings form. Create a `.env` file in the
+project root (or add to the existing one) with:
+
+```text
+ZOOM_CLIENT_ID=your-client-id
+ZOOM_CLIENT_SECRET=your-client-secret
 ```
 
-See [Getting started](/docs/getting-started) for installing dependencies and running the dev server.
+Get a Client ID and Secret from a [Zoom OAuth app](https://marketplace.zoom.us/)
+(Zoom Marketplace → Develop → Build App → OAuth), with
+`/_agent-native/zoom/callback` as the redirect URI, then restart `pnpm dev`
+so it picks up the new values. Without Zoom connected, booking links can
+still offer Google Meet, just not Zoom.
+
+</Steps>
 
-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.
+<Callout tone="warning">
 
-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.
+On Windows, some editors add a hidden `.txt` extension when you save a file
+named `.env`, leaving a `.env.txt` that Calendar never reads. In File
+Explorer, turn on "File name extensions" (View tab) and confirm the saved
+file is named exactly `.env`, with nothing after it.
+
+</Callout>
 
 <Callout tone="info">
 
@@ -29,57 +105,101 @@ To enable Zoom conferencing on booking links, set `ZOOM_CLIENT_ID` and `ZOOM_CLI
 
 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:
+### 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
+| Action | What it does |
+| --- | --- |
+| `list-events` | List events in a date range |
+| `search-events` | Search events by query |
+| `get-event` | Read one event by id |
+| `create-event` | Create an event, including recurrence (RRULE), working locations, and status types (`outOfOffice`, `focusTime`) |
+| `update-event` | Update an event, including recurrence, working locations, and status types |
+| `delete-event` | Delete an event |
+| `manage-event-draft` | Stage an unsent invite for user review before anything is written or guests are notified |
+| `rsvp-event` | Accept, decline, or mark tentative on an invitation |
+| `get-attendee-timezones` | Read per-guest timezone overrides |
+| `set-attendee-timezone` | Set a per-guest timezone override so their local time keeps showing correctly |
 
-**Availability & finding time:**
+### 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
+| Action | What it does |
+| --- | --- |
+| `get-availability` | Read the weekly schedule, timezone, buffer, notice, and advance-window settings |
+| `update-availability` | Update the weekly schedule, timezone, buffer, notice, and advance-window settings |
+| `check-availability` | Find 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:**
+### 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
+| Action | What it does |
+| --- | --- |
+| `create-booking-link` | Create a booking link |
+| `update-booking-link` | Update a booking link |
+| `duplicate-booking-link` | Duplicate a booking link, including co-hosts (`hosts`) |
+| `list-booking-links` | List accessible booking links |
+| `list-bookings` | List confirmed appointments |
 
-**External calendars (read-only ICS feeds):**
+### External calendars
 
-- `add-external-calendar`, `list-external-calendars`, `remove-external-calendar`, `update-external-calendars`
+Read-only ICS feeds.
 
-**People & overlays:**
+| Action | What it does |
+| --- | --- |
+| `add-external-calendar` | Subscribe to a read-only ICS/webcal feed |
+| `list-external-calendars` | List subscribed feeds |
+| `remove-external-calendar` | Remove a subscribed feed |
+| `update-external-calendars` | Update subscribed feeds |
 
-- `search-people` — Google Contacts + Workspace directory search
-- `get-overlay-people`, `update-overlay-people` — other people's calendars pinned into your view
+### People & overlays
 
-**Zoom:**
+| Action | What it does |
+| --- | --- |
+| `search-people` | Search Google Contacts and the Workspace directory |
+| `get-overlay-people` | Read the other people whose calendars are pinned into your view |
+| `update-overlay-people` | Update the other people whose calendars are pinned into your view |
 
-- `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
+### Zoom
 
-**Google Calendar connection & sync:**
+| Action | What it does |
+| --- | --- |
+| `get-zoom-status` | Read the current user's Zoom connection status. Connect and disconnect happen through `/_agent-native/zoom/*` routes, not an action, since OAuth needs the signed-in browser session |
 
-- `connect-google-calendar` — returns the OAuth connect URL for the signed-in browser session
-- `sync-google-calendar` — forces a resync
+### Google Calendar connection & sync
 
-**Settings & preferences:**
+| Action | What it does |
+| --- | --- |
+| `connect-google-calendar` | Return the OAuth connect URL for the signed-in browser session |
+| `sync-google-calendar` | Force a resync |
 
-- `get-settings`, `update-settings` — user-level settings
-- `update-calendar-visual-preferences` — local-only display prefs (event colors, hidden weekends); never touches Google Calendar
+### Settings & preferences
 
-**Navigation & UI state:**
+| Action | What it does |
+| --- | --- |
+| `get-settings` | Read user-level settings |
+| `update-settings` | Update user-level settings |
+| `update-calendar-visual-preferences` | Update local-only display preferences (event colors, hidden weekends). Never touches Google Calendar |
 
-- `navigate` — moves the UI to a view, date, or event
-- `view-screen` — reads the current view back for the agent
+### Navigation & UI state
 
-**Provider API escalation** — the raw Google Calendar (and connected CRM) API, for when the actions above are too narrow:
+| Action | What it does |
+| --- | --- |
+| `navigate` | Move the UI to a view, date, or event |
+| `view-screen` | Read the current view back for the agent |
 
-- `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
+### Provider API escalation
+
+The raw Google Calendar (and connected CRM) API, for when the actions above are too narrow.
+
+| Action | What it does |
+| --- | --- |
+| `provider-api-catalog` | List the raw provider APIs available to call directly |
+| `provider-api-docs` | Read documentation for a raw provider API endpoint |
+| `provider-api-request` | Call the raw Google Calendar (or connected CRM) API directly |
+| `list-staged-datasets` | List large scans staged for querying instead of returning raw results |
+| `query-staged-dataset` | Query a staged dataset |
+| `delete-staged-dataset` | Delete a staged dataset |
 
 ## Data model
 
@@ -246,7 +366,7 @@ Availability rules live in per-user settings under the `calendar-availability` k
 
 ## 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.
+`create-booking-link` shows patterns worth reusing in any action: validating input before it touches the database, enforcing a rule across two tables, safely resolving the signed-in user, and normalizing a flexible input shape once instead of in every reader.
 
 <AnnotatedCode
   id="doc-block-calendar8"
@@ -258,7 +378,7 @@ Availability rules live in per-user settings under the `calendar-availability` k
   }
   annotations={[
     {
-      lines: "38-42",
+      lines: "37-41",
       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.",
     },
@@ -272,6 +392,11 @@ Availability rules live in per-user settings under the `calendar-availability` k
       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: "94-98",
+      label: "The signed-in user is resolved once, and narrowed",
+      note: "`getRequestUserEmail()` returns `string | undefined`, since there's technically no signed-in user for an unauthenticated call. Wrapping it in an immediately-invoked function lets the action throw right there if that ever happens, so `ownerEmail` is a plain `string` for the rest of the function instead of something every later line would have to re-check.",
+    },
     {
       lines: "110",
       label: "Co-host input is normalized once",
@@ -359,8 +484,8 @@ If you add a feature, remember to update all four areas: UI, action, skill or AG
 ## 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
+- [**Features**](/docs/template-calendar-features) — the user-facing behavior these actions and this data model power
+- [**Talk to the Agent**](/docs/template-calendar-agent) — how the agent chooses between these actions and the raw Google Calendar API
+- [**Calendar in a Multi-App Workspace**](/docs/template-calendar-integrations) — how these actions get exposed to other apps and Dispatch
 - [**Actions**](/docs/actions-overview) — the action system this template is built on
 - [**Sharing**](/docs/sharing) — the share-grant model `booking_link_shares` uses