@agent-native/core 0.7.13 → 0.7.14

package/docs/content/messaging.md

@@ -0,0 +1,284 @@
+---
+title: "Messaging"
+description: "Talk to your agent from Slack, email, Telegram, or WhatsApp — same agent, same memory, same tools."
+---
+
+# Messaging
+
+Talk to your agent from the platforms you already use. Send a Slack DM, reply to an email, message a Telegram bot, or ping over WhatsApp — same agent, same memory, same tools, same thread history as the web chat.
+
+## Overview {#overview}
+
+Messaging integrations let users reach their agent from external messaging platforms instead of opening the web UI. Whichever platform a message comes in on, the agent processes it with the same system prompt, the same actions, and the same database — and replies in the same thread.
+
+Each integration works through webhooks. The platform delivers incoming messages over HTTP, the agent processes them in the background, and the response is posted back. No polling, no long-lived connections.
+
+> Note: this doc is specifically about platforms you can _message_ your agent over. Other kinds of integrations — Google Docs, OAuth providers, SQL databases, MCP servers, etc. — are covered in their own docs.
+
+## How it works {#how-it-works}
+
+The flow is the same for every platform:
+
+1. A user sends a message on the external platform (Slack, email, Telegram, WhatsApp)
+2. The platform delivers the message to your app via a webhook at `/_agent-native/integrations/<platform>/webhook`
+3. The integrations plugin validates the request, extracts the message text and thread context, and maps it to an internal conversation thread
+4. The agent processes the message in the background using the same pipeline as the web chat
+5. The response is posted back to the external platform in the same thread
+
+`User (Slack/Email/Telegram/WhatsApp)` → `Webhook` → `Agent Processing` → `Response posted back`
+
+## Setup {#setup}
+
+The integrations plugin auto-mounts when no custom version exists in your template. To customize it, create a plugin file:
+
+```ts
+// server/plugins/integrations.ts
+import { createIntegrationsPlugin } from "@agent-native/core/server";
+import { scriptRegistry } from "../../agent.config";
+
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+});
+```
+
+The plugin registers webhook routes for each enabled platform under `/_agent-native/integrations/`. Which platforms are active depends on which environment variables are configured.
+
+## Dispatch as the orchestrator {#dispatch}
+
+Messaging integrations are most powerful when set up in the **Dispatch template** (`templates/dispatch/`). Dispatch is a central control plane that:
+
+- Receives inbound messages from every configured platform (Slack, email, Telegram, WhatsApp) in one place
+- Delegates domain-specific work to specialist agents over the [A2A protocol](/docs/a2a-protocol) via the `call-agent` action
+- Sends the result back to the original platform in the same thread
+
+The pattern is one inbox, many specialist agents. A user emails the Dispatch agent "make me a slide deck about Q3" → Dispatch delegates to the slides agent → the slides agent returns a URL → Dispatch emails the user back with the link. Same flow for analytics queries, calendar invites, content drafts, anything else you have a specialist agent for.
+
+You don't have to use Dispatch — any template that mounts the integrations plugin can receive messages — but Dispatch is the recommended home for messaging because it can route across your whole agent fleet.
+
+See [Dispatch template](/docs/template-dispatch) and [A2A protocol](/docs/a2a-protocol) for details.
+
+## Slack {#slack}
+
+### 1. Create a Slack app
+
+Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app. Under **OAuth & Permissions**, add the following bot token scopes:
+
+- `chat:write` — send messages
+- `app_mentions:read` — receive @-mentions (optional)
+
+### 2. Enable Event Subscriptions
+
+Under **Event Subscriptions**, set the Request URL to:
+
+```text
+https://your-app.example.com/_agent-native/integrations/slack/webhook
+```
+
+Subscribe to the `message.im` bot event (and optionally `app_mention` for channel mentions).
+
+### 3. Set environment variables
+
+```bash
+SLACK_BOT_TOKEN=xoxb-your-bot-token
+SLACK_SIGNING_SECRET=your-signing-secret
+```
+
+The bot token is found under **OAuth & Permissions** after installing the app to your workspace. The signing secret is under **Basic Information**.
+
+## Email {#email}
+
+The email adapter receives inbound mail via Resend or SendGrid webhooks and replies in-thread using standard `Message-ID` / `In-Reply-To` / `References` headers. Sender email addresses are treated as identities — if a user emails the agent from `alice@acme.com`, that maps directly to the workspace user with that email.
+
+Adapter file: `packages/core/src/integrations/adapters/email.ts`
+
+### 1. Set environment variables
+
+```bash
+EMAIL_AGENT_ADDRESS=agent@your-domain.com
+# Configure ONE of these (Resend or SendGrid):
+RESEND_API_KEY=re_...
+SENDGRID_API_KEY=SG...
+# Optional — recommended for production:
+EMAIL_INBOUND_WEBHOOK_SECRET=your-shared-secret
+```
+
+`EMAIL_AGENT_ADDRESS` is the address users send mail to. Set either `RESEND_API_KEY` _or_ `SENDGRID_API_KEY` — whichever provider you use. `EMAIL_INBOUND_WEBHOOK_SECRET` enables Svix signature verification (Resend) or basic-auth / `x-webhook-secret` header verification (SendGrid).
+
+### 2. Configure the webhook URL
+
+```text
+https://your-app.example.com/_agent-native/integrations/email/webhook
+```
+
+### 3. Provider setup — Resend
+
+Two options for the agent address:
+
+- **Free `<slug>.resend.app` address** — no DNS setup required. Pick a slug in the Resend dashboard and your agent gets `agent@<slug>.resend.app`.
+- **Custom domain** — add MX records pointing to Resend per the dashboard's instructions.
+
+Then in the Resend dashboard:
+
+1. Go to **Webhooks** → **Add Endpoint**
+2. Set the URL to `https://your-app.example.com/_agent-native/integrations/email/webhook`
+3. Subscribe to the `email.received` event
+4. Copy the signing secret into `EMAIL_INBOUND_WEBHOOK_SECRET`
+
+### 3. Provider setup — SendGrid
+
+1. In your DNS, add an MX record for the agent's domain pointing to `mx.sendgrid.net` (priority 10)
+2. In the SendGrid dashboard, go to **Settings** → **Inbound Parse** → **Add Host & URL**
+3. Set the host to your domain and the destination URL to `https://your-app.example.com/_agent-native/integrations/email/webhook`
+4. (Recommended) Set basic auth or a custom `x-webhook-secret` header matching `EMAIL_INBOUND_WEBHOOK_SECRET`
+
+### Threading and CC behavior
+
+- **Threading** uses the standard email headers: the agent's reply sets `In-Reply-To` to the inbound `Message-ID` and accumulates the `References` chain. Most clients (Gmail, Outlook, Apple Mail) thread the conversation automatically.
+- **Direct vs CC'd** — the adapter detects whether the agent was in `To` (directly addressed) or `Cc` (overheard). When CC'd, the agent's reply goes to all original recipients (reply-all). The Dispatch system prompt also instructs the agent to only respond when input is clearly being requested, so it stays out of the way on threads it's only copied on.
+- **Identity** — the sender's email address is the identity. It maps directly to a workspace user with that email; the agent acts on behalf of that user.
+
+### Rich responses
+
+Agent replies render as HTML email. The adapter converts markdown to HTML (headings, lists, links, bold, inline code, paragraphs) and wraps it in a minimal styled template, with a plain-text fallback. So tables, bullet lists, and links from the agent come through as proper rich email — not raw markdown.
+
+### Rate limiting and allowed domains
+
+- **Rate limit** — 20 inbound messages per sender per hour, enforced in-memory per process. Excess messages are dropped.
+- **Allowed domains** — the `integration_configs` row for `email` accepts an optional `allowedDomains: string[]`. When set, only senders whose domain is in the list are accepted. Use this to restrict the agent to a specific company or tenant.
+
+### Proactive sends
+
+The agent can email users on its own (not just reply) by calling the `send-platform-message` action with `platform: "email"`. Useful for digest emails, alerts, or follow-ups from automations and recurring jobs.
+
+## Telegram {#telegram}
+
+### 1. Create a bot
+
+Message [@BotFather](https://t.me/BotFather) on Telegram and use the `/newbot` command. You will receive a bot token.
+
+### 2. Set environment variables
+
+```bash
+TELEGRAM_BOT_TOKEN=your-bot-token
+```
+
+### 3. Register the webhook
+
+After deploying your app, call the setup endpoint to register the webhook with Telegram:
+
+```text
+// The integrations plugin exposes a setup endpoint
+POST /_agent-native/integrations/telegram/setup
+
+// This calls Telegram's setWebhook API pointing to:
+// https://your-app.example.com/_agent-native/integrations/telegram/webhook
+```
+
+You can also register the webhook manually using the Telegram Bot API if you prefer.
+
+## WhatsApp {#whatsapp}
+
+### 1. Set up the WhatsApp Cloud API
+
+Go to the [Meta Developer Portal](https://developers.facebook.com/), create an app, and enable the WhatsApp product. Configure a phone number for your business.
+
+### 2. Set environment variables
+
+```bash
+WHATSAPP_ACCESS_TOKEN=your-access-token
+WHATSAPP_VERIFY_TOKEN=your-verify-token
+WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
+```
+
+The verify token is a string you choose — Meta uses it during webhook verification. The access token and phone number ID come from the Meta Developer Portal.
+
+### 3. Configure the webhook
+
+In the Meta Developer Portal, set the webhook URL to:
+
+```text
+https://your-app.example.com/_agent-native/integrations/whatsapp/webhook
+```
+
+Subscribe to the `messages` webhook field.
+
+## Configuration {#configuration}
+
+Integrations can be managed from the settings UI in the sidebar. Each platform shows its connection status and webhook URL. You can enable/disable individual integrations without removing environment variables.
+
+The webhook URLs follow a consistent pattern:
+
+```text
+/_agent-native/integrations/<platform>/webhook
+
+# Examples:
+/_agent-native/integrations/slack/webhook
+/_agent-native/integrations/email/webhook
+/_agent-native/integrations/telegram/webhook
+/_agent-native/integrations/whatsapp/webhook
+```
+
+## Thread continuity {#thread-continuity}
+
+Conversations from external platforms are mapped to internal threads. Each Slack DM, email thread, Telegram chat, or WhatsApp conversation becomes a persistent thread in the agent-native database. This means:
+
+- The agent retains context across messages in the same external conversation
+- External conversations appear in the web UI alongside web-originated threads, tagged with their source platform
+- You can continue a conversation that started in Slack from the web UI, or vice versa
+
+For email specifically, threading uses the `Message-ID`, `In-Reply-To`, and `References` headers — the oldest Message-ID in the References chain is treated as the thread root, matching Gmail's behavior.
+
+## Custom adapters {#custom-adapters}
+
+To add support for a new messaging platform, implement the `PlatformAdapter` interface:
+
+```ts
+import type { PlatformAdapter } from "@agent-native/core/server";
+
+const myAdapter: PlatformAdapter = {
+  platform: "discord",
+
+  // Verify the incoming webhook request is authentic
+  verifyRequest(request: Request): Promise<boolean> {
+    // Validate signature headers
+  },
+
+  // Extract the message text and thread context from the webhook payload
+  parseMessage(body: unknown): Promise<{
+    text: string;
+    threadId: string;
+    senderId: string;
+    metadata?: Record<string, unknown>;
+  }> {
+    // Parse platform-specific payload
+  },
+
+  // Send the agent's response back to the platform
+  sendResponse(threadId: string, text: string): Promise<void> {
+    // Call the platform's API to post the message
+  },
+};
+```
+
+Register your adapter in the integrations plugin config:
+
+```ts
+export default createIntegrationsPlugin({
+  actions: scriptRegistry,
+  systemPrompt: "You are a helpful assistant...",
+  adapters: [myAdapter],
+});
+```
+
+## Security {#security}
+
+Every incoming webhook is verified before processing:
+
+- **Slack** — HMAC-SHA256 signature verification using `SLACK_SIGNING_SECRET`. The `X-Slack-Signature` header is checked against the request body.
+- **Email (Resend)** — Svix signature verification using `EMAIL_INBOUND_WEBHOOK_SECRET`, with a 5-minute replay window.
+- **Email (SendGrid)** — basic auth or `x-webhook-secret` header matching `EMAIL_INBOUND_WEBHOOK_SECRET`. Plus optional `allowedDomains` filtering on the sender.
+- **Telegram** — requests are validated by checking the secret token set during webhook registration via the Telegram Bot API.
+- **WhatsApp** — Meta's webhook verification challenge (using `WHATSAPP_VERIFY_TOKEN`) and payload signature validation.
+
+All platform credentials (tokens, secrets, API keys) are stored as environment variables and never persisted in the database or source code. Use the settings UI or your deployment platform's env var management to configure them.

package/docs/content/pure-agent-apps.md

@@ -1,69 +1,96 @@
 ---
 title: "Pure-Agent Apps"
-description: "Build an agent without a heavy UI — just the agent plus a minimal observability/management surface. All the framework benefits, none of the dashboard work."
+description: "Apps where the agent is the whole product — open it, ask for what you want, and the agent does the rest."
 ---
 
 # Pure-Agent Apps
 
-Not every agent-native app needs a full SaaS-style interface. Sometimes the agent _is_ the product. A support triage agent. A daily report generator. A research bot. An email auto-responder. An ops runbook executor.
+Imagine opening an app and seeing… just a chat. No dashboard. No sidebar full of menus. No forms. You ask for what you want — "summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week" — and the agent goes off and does it. The output shows up in chat, in Slack, in your inbox, wherever it belongs.
 
-For these, the "app" is mostly just the agent doing work in the background. You still want a UI — but a minimal one, focused on **observability, management, and steering** rather than hand-crafted dashboards and forms.
+That's a pure-agent app. The agent _is_ the product.
 
-This is the "agents benefit from a UI even when there's no rich app around them" pattern. The hot take is "agents will replace apps." The reality is "every agent eventually needs a UI for humans to supervise, configure, and debug it." Agent-native gives you that UI for free.
+## What it feels like to use one {#user-experience}
 
-## The minimum viable UI {#minimum-ui}
+Most apps are built around a UI: a database table you browse, a form you fill, a chart you read. The agent is a sidekick.
 
-A pure-agent app ships with five surfaces, all provided by the framework — you don't build them:
+In a pure-agent app, that's flipped. The chat is the front door. You type a request; the agent takes action; you see the result. Everything else — settings, history, what's currently running — is one click away, but most of the time you don't need it.
 
-1. **Chat** — the main input. Users talk to the agent, steer it, queue tasks. (`<AgentSidebar>` or `<AgentPanel>`)
-2. **Workspace** — skills, memory (`learnings.md`), `AGENTS.md`, custom sub-agents, connected MCP servers, scheduled jobs. Customize the agent's behavior without shipping code. (Workspace tab in the sidebar)
-3. **Job history** — which scheduled jobs ran, when, whether they succeeded, what they did. (Workspace tab → `jobs/`)
-4. **Thread history** — every past conversation, each preserved with its tool calls and final output. (Chat tab)
-5. **Settings** — API keys, connected accounts, onboarding status. (Sidebar settings)
+Examples of where this works really well:
 
-Those five together are enough UI for most pure-agent use cases. No analytics dashboard. No Kanban. No forms. Just: talk to it, see what it's done, configure how it behaves.
+- **Background workers** — a triage agent that watches your inbox and labels things, a daily-report agent that posts to Slack each morning, an on-call agent that responds to alerts.
+- **One-shot helpers** — "research this company and write a one-pager," "scan my GitHub issues and tell me which ones look stale."
+- **Channel-driven assistants** — agents you mostly talk to from Slack, Telegram, email, or another agent (via [A2A](/docs/a2a-protocol)). The "app" itself is mostly a control panel.
+- **Internal tools** — an agent that knows your runbooks, your APIs, your conventions, and can act on them.
 
-## When to pick this pattern {#when-to-pick}
+The hot take is "agents will replace apps." The honest version is "agents still need a UI — for humans to supervise, configure, and steer them." Pure-agent apps give you that UI without the dashboard sprawl.
 
-Pure-agent makes sense when:
+## When this beats a traditional app {#when}
 
-- **The work happens in the background.** Scheduled jobs, webhook-triggered handlers, Slack/Telegram responders. Users rarely sit in the app.
-- **The output leaves the app.** The agent posts to Slack, sends email, writes to a third-party system. There's nothing to view in-app; the value is elsewhere.
-- **The domain is one-shot.** A research bot that returns a report. No persistent object to dashboard.
-- **You're prototyping.** Ship the agent now; add a rich UI only when you've proven users need it.
+Pick the pure-agent pattern when:
 
-Pick a full [cloneable SaaS](/docs/cloneable-saas) template instead when the app has real persistent objects (emails, events, documents, charts) users need to browse, pivot, and share.
+- **The work happens in the background.** Most of the value is created while the user isn't looking.
+- **The output leaves the app.** The agent posts to Slack, sends email, updates a third-party system. There's nothing to browse in-app — the value is elsewhere.
+- **The domain is one-shot.** Research bot, summary generator, report writer. There's no persistent object that needs a list view.
+- **You're prototyping.** Ship the agent now; add a richer UI later if it turns out users actually want one.
 
-## The minimal scaffold {#scaffold}
+If your product is built around persistent objects users browse, pivot, and share — emails, events, documents, charts — pick a [cloneable SaaS](/docs/cloneable-saas) template instead. Those have full UIs _plus_ the agent.
 
-Start from the **Starter** template:
+## What ships in the box {#minimum-ui}
+
+Every pure-agent app gets five built-in surfaces, all provided by the framework — you don't build them:
+
+1. **Chat** — the main input. Users talk to the agent, steer it, queue tasks.
+2. **Workspace** — skills, memory, instructions, custom sub-agents, connected MCP servers, scheduled jobs. Customize the agent's behavior without shipping code.
+3. **Job history** — which scheduled jobs ran, when, whether they succeeded, what they did.
+4. **Thread history** — every past conversation, each preserved with its tool calls and final output.
+5. **Settings** — API keys, connected accounts, onboarding status.
+
+Those five are usually enough. No analytics dashboard. No Kanban. No forms. Just: talk to it, see what it's done, configure how it behaves.
+
+## Why you'd pick this over "an app with an AI sidebar" {#vs-traditional}
+
+Two reasons:
+
+1. **You don't have to build the UI.** A pure-agent app skips weeks of dashboard work. The chat handles input; the framework handles supervision and history; the agent handles output.
+2. **It's channel-agnostic from day one.** The same agent that runs in your web UI also runs from Slack, Telegram, email, and other agents — because everything goes through the agent, not the UI. See [Messaging the agent](/docs/messaging) for how that works.
+
+The trade-off: pure-agent apps don't give users a "browse-everything-at-a-glance" view. If your users need that, mix patterns: start pure-agent, add a small status page or list view if you discover users want one.
+
+## Building one {#building}
+
+If you're not a developer, you can usually start with the [Dispatch template](/docs/template-dispatch) — it's a workspace-style pure-agent app with Slack/Telegram, scheduled jobs, and shared secrets out of the box.
+
+For developers who want the absolute minimum, start from the **Starter** template:
 
 ```bash
 pnpm dlx @agent-native/core create my-agent --template starter
 ```
 
-Starter gives you the six-rules architecture, the agent panel, the workspace, auth, polling, and one example action — and nothing else. Add your own actions in `actions/`, connect any MCP servers you need, write the relevant skills into the workspace, and you're done. The "UI" is the agent sidebar — which is already complete.
+Starter gives you the architecture, the agent panel, the workspace, auth, polling, and one example action — and nothing else. Add your own actions in `actions/`, connect any MCP servers you need, write the relevant skills into the workspace, and you're done.
 
-If you really want _zero_ UI except the agent, `app/routes/index.tsx` can just render `<AgentPanel defaultMode="chat" />` fullscreen. The only thing the user sees is the chat. Everything else — job history, workspace, settings — is one click away in the panel's tabs.
+If you really want _zero_ UI except the agent, `app/routes/index.tsx` can render `<AgentPanel defaultMode="chat" />` fullscreen. The only thing the user sees is the chat. Everything else — job history, workspace, settings — is one click away in the panel's tabs.
 
-## What you still get for free {#still-free}
+### What you still get for free {#still-free}
 
 Even with no custom UI, you still inherit every framework benefit:
 
-- **Actions** as agent tools + HTTP endpoints + MCP tools + A2A tools. External agents, Claude Desktop, and your own HTTP clients can drive the agent without going through the chat UI.
-- **Recurring jobs** for scheduled work — "every morning at 7 summarize my unread emails and post to Slack."
+- **Actions** as agent tools, HTTP endpoints, MCP tools, and A2A tools. External agents, Claude Desktop, and your own HTTP clients can drive the agent without going through the chat UI.
+- **Recurring jobs** for scheduled work — "every morning at 7, summarize my unread emails and post to Slack."
 - **The workspace** for per-user customization, skills, memory, MCP connections.
 - **Sub-agent delegation** via [agent teams](/docs/agent-teams).
 - **Portability** — deploys to any serverless host, any SQL database.
 - **Multi-tenant by default** — each user gets their own workspace without a dev-box.
 
-## Adding a tiny bit of UI {#tiny-ui}
+### Adding a tiny bit of UI {#tiny-ui}
 
-Most "pure-agent" apps eventually want a little bit of custom UI — not a dashboard, but maybe a status page, a job history, or a config screen. The [drop-in agent](/docs/drop-in-agent) components coexist with anything else you render. Add a single `/status` route that lists recent runs; keep everything else in the chat. That's usually enough.
+Most pure-agent apps eventually want a little custom UI — not a dashboard, but maybe a status page, a job history, or a config screen. The [drop-in agent](/docs/drop-in-agent) components coexist with anything else you render. Add a single `/status` route that lists recent runs; keep everything else in the chat. That's usually enough.
 
 ## What's next
 
+- [**Getting Started**](/docs/getting-started) — clone the Starter template
+- [**Messaging the agent**](/docs/messaging) — how users talk to the agent across web, Slack, Telegram, email
 - [**Recurring Jobs**](/docs/recurring-jobs) — scheduled prompts the agent runs on its own
+- [**Dispatch**](/docs/template-dispatch) — the workspace template that's a great starting point for pure-agent apps
 - [**Drop-in Agent**](/docs/drop-in-agent) — mounting `<AgentPanel>` fullscreen or in a sidebar
 - [**Actions**](/docs/actions) — the tools your pure-agent will call
 - [**Workspace**](/docs/workspace) — the customization surface for skills, memory, and MCP servers

package/docs/content/template-calendar.md

@@ -1,26 +1,61 @@
 ---
-title: "Calendar Template"
-description: "AI-native calendar with Google Calendar sync and a Calendly-style public booking page."
+title: "Calendar"
+description: "An agent-powered calendar with Google Calendar sync and Calendly-style booking links. Schedule, find slots, and manage availability through plain English."
 ---
 
-# Calendar Template
+# Calendar
 
-The Calendar template is a complete scheduling app: a full calendar UI on top of Google Calendar, plus Calendly-style public booking links, all driven by an agent that can schedule, search, and manage availability on your behalf. It replaces the Google Calendar + Calendly combo with something you own and can extend.
+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.
 
-## Overview {#overview}
+When you open the app, you'll see your calendar in the middle and the agent in the sidebar. The agent always 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.
 
-Calendar is for anyone who currently juggles Google Calendar for their own schedule and Calendly (or similar) for letting other people book time. It gives you:
+## What you can do with it
 
-- Day, week, and month calendar views backed by the Google Calendar API.
-- Multi-account Google OAuth, so several calendars can overlay in one view.
-- External ICS calendar subscriptions (webcal feeds).
-- Configurable weekly availability with timezone support.
-- Public booking links at `/book/{slug}` or `/meet/{username}/{slug}` with custom durations, custom fields, and meeting-link options.
-- An agent that can answer schedule questions, create events, find free slots, and manage booking links through natural language.
+- **See your real Google Calendar** in day, week, or month view, with multiple accounts overlayed.
+- **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.
+- **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.
 
-Events themselves are not copied into the local database. The app reads them from Google Calendar on every request. Bookings, booking links, and settings live in SQL.
+## Getting started
 
-## Quick start {#quick-start}
+Live demo: [calendar.agent-native.com](https://calendar.agent-native.com).
+
+When you first open the app:
+
+1. Click **Settings**.
+2. Click **Connect Google Calendar** and approve.
+3. (Optional) Connect more Google accounts if you want personal + work overlayed.
+4. Open the main view — your real calendar will load.
+
+To create your first booking link:
+
+1. Click **Booking Links** in the sidebar.
+2. Click **New booking link**, set a title and duration.
+3. Share the public URL — visitors pick from your available slots.
+
+Or just ask the agent: "Create a 15-minute intro booking link with a name field."
+
+### Useful prompts
+
+- "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:
 
@@ -33,29 +68,17 @@ pnpm dev
 
 Open `http://localhost:8082` (the default Calendar dev port).
 
-Live demo: [https://calendar.agent-native.com](https://calendar.agent-native.com).
+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.
 
-To connect Google Calendar, 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 (technical)
 
-## Key features {#key-features}
+**Calendar views.** The main view at `/` (route `app/routes/_app._index.tsx`) renders the calendar in day, week, or month mode. Switch views from the toolbar, or ask the agent to switch for you. Events are fetched live from Google Calendar — no local sync step is required to see the latest state.
 
-### Calendar views
+**Multi-account Google Calendar sync.** Connect as many Google accounts as you like. Each connection appears in Settings, and events from every connected calendar overlay in the main view. Sync is pull-based, so no webhooks or background workers are required. The `sync-google-calendar` action refetches a date range on demand. Supporting actions: `list-events`, `search-events`, `get-event`, `create-event`, `sync-google-calendar`.
 
-The main view at `/` (route `app/routes/_app._index.tsx`) renders the calendar in day, week, or month mode. Switch views from the toolbar, or ask the agent to switch for you. Events are fetched live from Google Calendar — no local sync step is required to see the latest state.
+**External calendars (ICS subscriptions).** Subscribe to read-only ICS or `webcal://` feeds — useful for HR time off, conference schedules, or shared team calendars. Feeds are added in Settings and stored per user. Relevant actions: `add-external-calendar`, `list-external-calendars`, `remove-external-calendar`, `update-external-calendars`.
 
-### Multi-account Google Calendar sync
-
-Connect as many Google accounts as you like. Each connection appears in Settings, and events from every connected calendar overlay in the main view. Sync is pull-based, so no webhooks or background workers are required. The `sync-google-calendar` action refetches a date range on demand.
-
-Supporting actions: `list-events`, `search-events`, `get-event`, `create-event`, `sync-google-calendar`.
-
-### External calendars (ICS subscriptions)
-
-Subscribe to read-only ICS or `webcal://` feeds — useful for HR time off, conference schedules, or shared team calendars. Feeds are added in Settings and stored per user. Relevant actions: `add-external-calendar`, `list-external-calendars`, `remove-external-calendar`, `update-external-calendars`.
-
-### Availability rules
-
-Availability is a weekly schedule of time windows per day, plus a timezone. It is stored in the settings table under the key `calendar-availability`:
+**Availability rules.** Availability is a weekly schedule of time windows per day, plus a timezone. It is stored in the settings table under the key `calendar-availability`:
 
 ```json
 {
@@ -77,9 +100,7 @@ Availability is a weekly schedule of time windows per day, plus a timezone. It i
 
 Edit it at `/availability` (`app/routes/_app.availability.tsx`) or via the `update-availability` action. The `check-availability` action reads this schedule, subtracts your existing Google Calendar events, and returns free slots of the requested duration.
 
-### Public booking pages
-
-Booking links are the Calendly replacement. Create one in the UI at `/booking-links` (`app/routes/_app.booking-links._index.tsx`), configure it in the editor at `/booking-links/{id}`, and share the public URL.
+**Public booking pages.** Booking links are the Calendly replacement. Create one in the UI at `/booking-links` (`app/routes/_app.booking-links._index.tsx`), configure it in the editor at `/booking-links/{id}`, and share the public URL.
 
 Every link has:
 
@@ -93,9 +114,7 @@ Visitors land on the public page, pick a date and time from the available slots,
 
 There is also a per-user public URL at `/meet/{username}/{slug}` for clean personal sharing.
 
-### Sharing booking links with teammates
-
-Booking links are private by default — only the creator can edit or delete them. To let a teammate manage a link, either change the link's visibility or grant explicit access. The framework ships these actions, auto-mounted for any `booking-link` resource:
+**Sharing booking links with teammates.** Booking links are private by default — only the creator can edit or delete them. To let a teammate manage a link, either change the link's visibility or grant explicit access. The framework ships these actions, auto-mounted for any `booking-link` resource:
 
 - `share-resource` — grant a user or org `viewer`, `editor`, or `admin` access.
 - `unshare-resource` — revoke a grant.
@@ -104,29 +123,15 @@ Booking links are private by default — only the creator can edit or delete the
 
 Sharing only controls who can manage the link. The public booking URL always accepts bookings from unauthenticated visitors as long as `isActive` is true.
 
-### Inline event previews in chat
+**Inline event previews in chat.** The `/event` route (`app/routes/event.tsx`) renders a compact, chromeless event card that the agent can embed in chat when you ask about a specific event. Title, time, location, attendees, and a description snippet are shown with a button to jump into the main calendar.
 
-The `/event` route (`app/routes/event.tsx`) renders a compact, chromeless event card that the agent can embed in chat when you ask about a specific event. Title, time, location, attendees, and a description snippet are shown with a button to jump into the main calendar.
-
-## Working with the agent {#working-with-the-agent}
+### 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.
 
-Example prompts:
-
-- "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?"
-
 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 {#data-model}
+### Data model
 
 Defined in `templates/calendar/server/db/schema.ts`. Only non-event data is stored locally:
 
@@ -137,7 +142,7 @@ Defined in `templates/calendar/server/db/schema.ts`. Only non-event data is stor
 
 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 {#customizing-it}
+### Customizing it
 
 Every part of the app is editable source. Start here: