@agent-native/core 0.122.4 → 0.123.0

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

@@ -0,0 +1,128 @@
+---
+title: "Calendar: Events, Availability & Finding Time"
+description: "How to view your schedule across accounts, set your working hours, and let the agent find and book a shared free slot."
+---
+
+# Events, Availability & Finding Time
+
+This page is for anyone using Calendar day to day: viewing your schedule, telling the app when you're free, and finding time with other people. See [Calendar](/docs/template-calendar) for the overview and [Booking Links](/docs/template-calendar-booking-links) for public scheduling pages.
+
+## Viewing your schedule
+
+Switch between day, week, and month views from the toolbar. Every view reads your real, connected Google Calendar — nothing is cached or synthetic. If you connect more than one Google account (say, work and personal), both show in the same grid, color-coded so you can tell them apart.
+
+You can also subscribe to read-only calendar feeds by pasting an ICS or `webcal://` URL — useful for a company holidays calendar, a conference schedule, or a teammate's public calendar. Subscribed feeds get their own color and appear mixed into your regular view; you can't edit events that come from a feed.
+
+<Callout tone="warning">
+
+If part of your schedule fails to load — one account's token expired, or a feed URL times out — the app tells you which source failed instead of quietly showing an empty day. A blank calendar and a broken connection look different on purpose, so you never mistake "nothing loaded" for "nothing scheduled."
+
+</Callout>
+
+## Setting your availability
+
+Availability is a weekly schedule: which days you work and what hours you're open on each one, plus your timezone. On top of that you can set:
+
+- **Buffer time** between meetings, so back-to-back bookings don't happen
+- **Minimum notice**, so people can't book you five minutes from now
+- **How far ahead** people can book (advance window)
+- **Default slot length** for new booking links
+
+The agent reads the same schedule the UI edits, so "set my hours to 9-5 weekdays" and dragging the sliders in the Availability page produce the same result.
+
+## Finding a shared free slot
+
+Ask the agent to find time and it checks your availability, your real Google Calendar events, and — when you name other people — their free/busy status too, then proposes concrete slots. Once you pick one, the agent books it directly on Google Calendar.
+
+<Diagram id="doc-block-calendar3" title="From availability to a booked event" summary="The agent combines your availability rules, your existing events, and (when named) other attendees' free/busy before proposing slots.">
+
+```html
+<div class="diagram-flow">
+  <div class="diagram-col">
+    <div class="diagram-box">
+      Your availability<br /><small class="diagram-muted"
+        >weekly hours, buffer, notice</small
+      >
+    </div>
+    <div class="diagram-box">
+      Existing events<br /><small class="diagram-muted"
+        >Google Calendar, live</small
+      >
+    </div>
+    <div class="diagram-box">
+      Attendees' free/busy<br /><small class="diagram-muted"
+        >when you name people</small
+      >
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">Find a time</span
+    ><small class="diagram-muted">candidate slots</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">You pick one</div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box">Event created on Google Calendar</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>
+
+## Overlaying other people's calendars
+
+Beyond checking free/busy for one request, you can pin a person's calendar into your regular view — useful for a manager checking a direct report's schedule, or two people who plan a lot of time together. Each overlaid person gets their own color, and their events show up alongside yours in every view. Ask the agent: "Add Priya's calendar to my view" or manage the list from Settings.
+
+## Finding people
+
+When you're scheduling with someone new, search by name or email instead of typing an exact address. Calendar searches your Google Contacts plus your Workspace directory, so you can ask "who is Dana at Acme" or "find people named Priya" and get real matches to pick from.
+
+## Attendee timezones
+
+For guests in other timezones, the event detail can show each person's local start time. Calendar knows a guest's timezone when Google reports it; when it doesn't, you can save a per-guest override so their local time keeps showing correctly going forward.
+
+## Working locations and recurring events
+
+Google Calendar's native "working location" status (home, office, or another location) is supported as a real status, not a generic all-day event — it shows up as a working-location marker and never blocks your availability. Recurring events are supported end to end: create a recurring series, and edit either a single occurrence or the whole series going forward.
+
+### Useful prompts
+
+- "What's on my calendar today?"
+- "Am I free Thursday afternoon for 30 minutes?"
+- "Find a 1-hour slot next week with Sam and book 'Planning' on it."
+- "Block Friday afternoons on my availability."
+- "Add Priya's calendar to my view in blue."
+- "Who is jane at acme.com?"
+- "Show Alex's local time on this event." (when an event is selected)
+- "Set my working location to home for tomorrow."
+
+## What's next
+
+- [**Calendar**](/docs/template-calendar) — the overview and getting-started steps
+- [**Booking Links**](/docs/template-calendar-booking-links) — turn your availability into a public scheduling page
+- [**Talking to the Agent**](/docs/template-calendar-agent) — how the agent sees your current view and when it escalates to the raw Google Calendar API
+- [**Developer Guide**](/docs/template-calendar-developers) — the actions and data behind all of this

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

@@ -7,7 +7,7 @@ description: "An agent-powered calendar with Google Calendar sync and Calendly-s
 
 An agent-powered calendar app. Connect your Google Calendar and the agent can read your schedule, find free slots, create events, and manage Calendly-style booking links — all in plain English. It replaces the Google Calendar + Calendly combo with one app you own.
 
-<WireframeBlock id="doc-block-6wsrao">
+<WireframeBlock id="doc-block-calendar1">
   <Screen
     surface="desktop"
     html={
@@ -18,7 +18,7 @@ An agent-powered calendar app. Connect your Google Calendar and the agent can re
 
 When you open the app, the active calendar view is the primary surface. The agent still knows which day, week, or event you're looking at, so you can say "schedule a 30-minute call with Alex on this day" without spelling everything out.
 
-<Diagram id="doc-block-1vg8pim" 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.">
+<Diagram id="doc-block-calendar2" 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.">
 
 ```html
 <div class="diagram-flow">
@@ -85,13 +85,15 @@ When you open the app, the active calendar view is the primary surface. The agen
 
 ## What you can do with it
 
-- **See your real Google Calendar** in day, week, or month view, with multiple accounts overlayed.
+- **See your real Google Calendar** in day, week, or month view, with multiple accounts overlayed in one grid.
 - **Subscribe to ICS feeds** (HR time off, conference schedules, team calendars) — read-only, mixed into the same view.
-- **Set weekly availability** with timezone support — the agent uses this when finding free slots.
-- **Create public booking links** at `/book/{slug}` for things like "15-minute intro" or "30-minute demo." Configure durations, custom fields, and which conferencing tool to use.
+- **Set weekly availability** with timezone support, buffer time, and minimum notice — the agent uses this when finding free slots.
+- **Create public booking links** at `/book/{your-name}/{slug}` for things like "15-minute intro" or "30-minute demo." Configure durations, custom fields, required co-hosts, and whether visitors get Google Meet or Zoom.
 - **Ask the agent anything schedule-related**: "Am I free Thursday afternoon?" "Find a 1-hour slot next week and put 'Planning with Alex' on it." "Pause my demo booking link."
 - **Share booking links** with teammates so they can manage them too.
 
+See [Scheduling, Availability & Finding Time](/docs/template-calendar-scheduling) and [Booking Links](/docs/template-calendar-booking-links) for the full detail on each.
+
 ## Getting started
 
 Live demo: [calendar.agent-native.com](https://calendar.agent-native.com).
@@ -116,268 +118,19 @@ Or just ask the agent: "Create a 15-minute intro booking link with a name field.
 - "What is on my calendar today?"
 - "Am I free Thursday afternoon for 30 minutes?"
 - "Find a 1-hour slot next week and put 'Planning with Alex' on it."
-- "Reschedule this event to Friday at 2pm." (when an event is selected)
-- "Switch to day view and jump to next Monday."
 - "Create a booking link called '15 min intro' at 15 minutes with a note field."
-- "Pause my '30 min demo' booking link."
 - "Block Friday afternoons on my availability."
-- "What meetings do I have about 'launch' this month?"
-
-The agent will query Google Calendar live for any schedule question — it never guesses.
-
-## For developers
-
-The rest of this doc is for anyone forking the Calendar template or extending it.
-
-### Quick start
-
-Create a new workspace with the Calendar template:
-
-```bash
-npx @agent-native/core@latest create my-app --standalone --template calendar
-cd my-app
-pnpm install
-pnpm dev
-```
-
-Open `http://localhost:8082` (the default Calendar dev port).
-
-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. Tokens are stored in the `oauth_tokens` SQL table and refresh automatically.
-
-### Key features
-
-**Live calendar views.** Day, week, and month views read directly from connected Google accounts, with optional read-only ICS feeds layered into the same schedule.
-
-**Availability and free-slot search.** Weekly availability rules, timezone support, and existing events all feed the same availability action the UI and agent use.
 
-**Booking links.** Public `/book/{slug}` pages collect name, email, custom fields, conferencing preferences, and cancellation/reschedule tokens.
+See [Talking to the Agent](/docs/template-calendar-agent) for the full list of prompts by task.
 
-**Shareable management.** Booking links are private by default, but can be shared with teammates through the framework sharing actions.
-
-**Inline event previews.** The agent can embed compact event cards in chat with title, time, location, attendees, and a jump-back button.
-
-### Working with the agent
-
-The agent sees what you are looking at. The current calendar view, the selected date, and the selected event are included in every message as a `current-screen` block, so you can say "this event" or "this day" and it resolves correctly.
-
-Under the hood the agent calls actions like `list-events`, `check-availability`, `create-event`, `navigate`, and `update-availability`. Because events live in Google Calendar, the agent always queries the API instead of guessing — it will not return empty results without running a script first.
-
-### Data model
-
-Defined in `templates/calendar/server/db/schema.ts`. Only non-event data is stored locally:
-
-- `bookings` — confirmed appointments from public booking pages. Stores name, email, start, end, slug, optional notes, custom field responses, meeting link, a `cancelToken` for the public manage URL, and a `confirmed` or `cancelled` status.
-- `booking_links` — the Calendly-style link definitions. Slug, title, description, primary `duration`, optional `durations` list, `customFields`, `conferencing`, `color`, and an `isActive` flag. Uses the framework's `ownableColumns` so the sharing system applies.
-- `booking_slug_redirects` — remembers old slugs when a link is renamed so existing public URLs keep working.
-- `booking_link_shares` — share grants for booking links.
-
-<DataModel
-  id="doc-block-1bkv9ic"
-  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."
-  }
-  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: "public page at /book/{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: "customFields",
-          type: "json",
-          nullable: true,
-        },
-        {
-          name: "conferencing",
-          type: "string",
-          note: "Google Meet / Zoom / custom",
-        },
-        {
-          name: "color",
-          type: "string",
-          nullable: true,
-        },
-        {
-          name: "isActive",
-          type: "bool",
-          note: "pause without deleting",
-        },
-      ],
-    },
-    {
-      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: "notes",
-          type: "string",
-          nullable: true,
-        },
-        {
-          name: "customFields",
-          type: "json",
-          nullable: true,
-          note: "custom field responses",
-        },
-        {
-          name: "meetingLink",
-          type: "string",
-          nullable: true,
-        },
-        {
-          name: "cancelToken",
-          type: "string",
-          note: "powers /booking/manage/{token}",
-        },
-        {
-          name: "status",
-          type: "enum",
-          note: "confirmed | cancelled",
-        },
-      ],
-    },
-    {
-      id: "booking_slug_redirects",
-      name: "booking_slug_redirects",
-      note: "Keeps old public URLs working after a link is renamed",
-      fields: [
-        {
-          name: "oldSlug",
-          type: "string",
-          pk: true,
-        },
-        {
-          name: "linkId",
-          type: "id",
-          fk: "booking_links.id",
-        },
-      ],
-    },
-    {
-      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_slug_redirects",
-      kind: "1-n",
-      label: "has old slugs",
-    },
-    {
-      from: "booking_links",
-      to: "booking_link_shares",
-      kind: "1-n",
-      label: "has share grants",
-    },
-  ]}
-/>
-
-Availability rules and per-user configuration live in the settings table, keyed by `calendar-availability`. Google 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.
-
-### Customizing it
-
-Every part of the app is editable source. Start here:
-
-- `templates/calendar/actions/` — every agent-callable operation. Add a new file with `defineAction` to expose new capability to both the agent and the frontend. Key files: `check-availability.ts`, `create-event.ts`, `list-events.ts`, `create-booking-link.ts`, `update-availability.ts`, `add-external-calendar.ts`, `navigate.ts`, `view-screen.ts`.
-- `templates/calendar/app/routes/` — the UI. `_app._index.tsx` is the calendar, `_app.availability.tsx` is the schedule editor, `_app.booking-links._index.tsx` and `_app.booking-links.$id.tsx` manage booking links, `_app.bookings.tsx` lists bookings, `_app.settings.tsx` is Settings, and `book.$slug.tsx` plus `meet.$username.$slug.tsx` are the public booking pages.
-- `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/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 (`AvailabilityConfig`, `BookingLink`, `ExternalCalendar`, 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.
+The agent will query Google Calendar live for any schedule question — it never guesses.
 
 ## What's next
 
+- [**Scheduling, Availability & Finding Time**](/docs/template-calendar-scheduling) — views, availability, free-slot search, overlays, and people search
+- [**Booking Links**](/docs/template-calendar-booking-links) — creating, sharing, and managing Calendly-style booking pages
+- [**Talking to the Agent**](/docs/template-calendar-agent) — prompts by task, application state, and Extensions
+- [**Developer Guide**](/docs/template-calendar-developers) — quick start, actions, data model, and routes
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model, and every other domain template to start from
 - [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync
 - [**Mail**](/docs/template-mail) — a sibling domain template covering inbox and automations

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

@@ -0,0 +1,88 @@
+---
+title: "Chat — runtime and admin surfaces"
+description: "The core SQL tables, auth setup, and the Database/Observability/Extensions admin pages that ship by default with the Chat template."
+---
+
+# Chat — runtime and admin surfaces
+
+This page is for developers who need to know what runs under the hood in [Chat](/docs/template-chat): the tables every template shares, how auth is configured, and the admin pages — Database, Observability, and Extensions — that ship in every Chat app whether or not you ever open them.
+
+## Core SQL tables and live sync {#tables}
+
+Chat adds no domain tables of its own (see [What's not in it](/docs/template-chat#not-in-it)). It runs entirely on the framework's core tables: chat threads and messages, `application_state`, `settings`, sessions, resources, and run history.
+
+`useDbSync()` is already wired into the app shell: when the agent (or anyone else) writes to SQL, the client receives the change over SSE, or the 2-second polling fallback, and invalidates the matching React Query caches — no manual refresh, no websocket you have to manage yourself. See [`useDbSync`](/docs/client#usedbsync) for the full hook API.
+
+`server/plugins/agent-chat.ts` is where the chat runtime itself is configured: it registers every action in `actions/` as a callable tool (`loadActionsFromStaticRegistry`), resolves the current org for scoping (`resolveOrgId`), sets the system prompt, and declares which tools the model sees on the very first turn (`initialToolNames`) — see [Your first feature in Chat](/docs/template-chat-first-edits#first-edits) for what that last part means when you add a new action.
+
+## Auth {#auth}
+
+Auth runs on Better Auth: login, signup, sessions, and organizations, configured in `server/plugins/auth.ts` via `createAuthPlugin`. The same flow runs locally and in production, except that development skips email verification so you can sign up and start building immediately. `createAuthPlugin` also takes the login page's marketing copy — app name, tagline, and feature bullets — as plain config in that same file. See [Authentication](/docs/authentication) for the full auth model (sessions, organizations, protected routes).
+
+## Admin surfaces that ship by default {#admin-surfaces}
+
+Three routes are mounted whether or not your app ever links to them:
+
+<Table
+  id="doc-block-chat6"
+  title="Chat's mounted routes"
+  columns={["Route", "Renders", "What it's for"]}
+  rows={[
+    [
+      "/",
+      "ChatRoute (app/routes/_index.tsx)",
+      "Full-page chat, the default view",
+    ],
+    [
+      "/chat/:threadId",
+      "same component, re-exported",
+      "Chat with the open thread synced into the URL",
+    ],
+    [
+      "/agent",
+      "AgentTabsPage (falls back to a plain chat surface on older core versions)",
+      "The full Agent page — Context, Files, Connections, Jobs, Access tabs",
+    ],
+    ["/database", "DbAdminPage", "Browse and edit every SQL table directly"],
+    [
+      "/observability",
+      "ObservabilityDashboard",
+      "Agent traces, cost, evals, and feedback",
+    ],
+    [
+      "/extensions",
+      "redirects to /settings#extensions",
+      "Extensions are managed from Settings, not a standalone list page",
+    ],
+    [
+      "/extensions/:id (or /extensions/:id/:slug)",
+      "ExtensionViewerPage",
+      "Runs one saved extension mini-app; the optional slug segment is just a friendlier URL for the same page",
+    ],
+    [
+      "/settings",
+      "SettingsTabsPage",
+      "Account, language, agent, team, and what's-new tabs",
+    ],
+    [
+      "/team",
+      "redirects to /settings#organization",
+      "Organization membership lives under Settings",
+    ],
+  ]}
+/>
+
+**Database** (`/database`) is the same `DbAdminPage` every template gets — a direct table browser/editor over the app's SQL database. See [Database](/docs/database) for the connection model behind it.
+
+**Observability** (`/observability`) is the same zero-config `ObservabilityDashboard` every template gets: traces, cost, evals, and feedback for every agent run, computed from data already in your own database. See [Agent Observability](/docs/observability).
+
+**Extensions** are sandboxed Alpine.js mini-apps your users can ask the agent to build inside the running app — a custom widget or checklist, no deploy required. Chat mounts the routes that view and run them (`/extensions/:id`) by default, even before you or your users create one; `/extensions` itself just redirects into the Extensions tab of Settings rather than showing its own list. See [Extensions](/docs/extensions) for what they can and cannot do.
+
+## What's next
+
+- [**Chat Template**](/docs/template-chat) — what ships by default and when to pick it
+- [**Your first feature in Chat**](/docs/template-chat-first-edits) — the starter chat route, annotated, plus a full feature walkthrough
+- [**Database**](/docs/database) — connecting a real database and the portable-SQL model
+- [**Agent Observability**](/docs/observability) — what the dashboard tracks and how
+- [**Extensions**](/docs/extensions) — building mini-apps inside a template
+- [**Authentication**](/docs/authentication) — sessions, organizations, and protected routes