@agent-native/core 0.7.13 → 0.7.15

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-analytics.md

@@ -1,23 +1,63 @@
 ---
-title: "Analytics Template"
-description: "AI-native analytics dashboards — connect data sources, prompt for charts, build reusable SQL dashboards and ad-hoc analyses."
+title: "Analytics"
+description: "Ask analytics questions in plain English, get charts and dashboards back. An open-source replacement for Amplitude, Mixpanel, and Looker."
 ---
 
-# Analytics Template
+# Analytics
 
-An open-source analytics app where the agent writes the SQL, builds the dashboards, and maintains the metric catalog. Replaces Amplitude, Mixpanel, and Looker for teams that want to own the code and the data.
+Ask analytics questions in plain English, get charts and dashboards back. The agent connects to BigQuery, GA4, your app database, HubSpot, Jira, and a dozen other sources, writes the SQL for you, validates it, and renders the answer as a chart, table, or saved dashboard panel.
 
-## Overview {#overview}
+It's an open-source replacement for Amplitude, Mixpanel, and Looker — for teams that want to own the code, the queries, and the data.
 
-The Analytics template is a dashboard app built on `@agent-native/core`. You ask a data question in chat, the agent queries the underlying source (BigQuery, GA4, the app database), and the answer appears as a chart, a table, or a saved dashboard panel. The agent sees the same screen the user sees and edits the same dashboards the user edits.
+## What you can do with it
 
-Three primary surfaces:
+- **Ask data questions in plain English.** "What percent of signups last month converted to paid?" or "Show me weekly active users for the past 6 months." The agent picks the right source, writes the SQL, and renders the chart.
+- **Build reusable SQL dashboards** with filters, saved views, and parametric queries.
+- **Run ad-hoc analyses** that cross-reference multiple data sources — saved as re-runnable investigations with the original question, instructions, and findings.
+- **Maintain a living data dictionary** of metrics, tables, and SQL recipes so the agent uses the right column names every time (no more guessed `is_closed` when it's actually `hs_is_closed`).
+- **Share dashboards** with your team — private by default, shareable per-user or per-org with viewer / editor / admin roles.
+- **Connect to many sources** out of the box: BigQuery, GA4, Mixpanel, Amplitude, PostHog, HubSpot, Jira, Apollo, Pylon, Gong, Common Room, Twitter, plus app-specific SEO sources.
 
-- **SQL Dashboards** — reusable panels with filters, saved views, and parametric SQL.
-- **Ad-hoc Analyses** — long-form investigations that pull from multiple sources and save re-run instructions.
-- **Data Dictionary** — a canonical catalog of metrics, tables, columns, and SQL recipes that the agent consults before writing any SQL.
+## Getting started
 
-## Quick start {#quick-start}
+Live demo: [analytics.agent-native.com](https://analytics.agent-native.com).
+
+When you first open the app:
+
+1. Sign in with Google.
+2. Open the **Data Sources** page from the sidebar.
+3. Each source has a walkthrough — connect the ones you need (start with one, like BigQuery or your app DB).
+4. Open a new chat with the agent and ask a question: "How many signups did we get last week?"
+
+The first question is enough to confirm the connection works. From there, ask the agent to "save this as a dashboard" or "build a 4-panel overview dashboard for our key metrics."
+
+### Useful prompts
+
+- "Build a dashboard showing weekly active users for the past 6 months."
+- "What percent of signups last month converted to paid?"
+- "Add a chart comparing revenue by plan to this dashboard."
+- "Reorder the panels on this dashboard so the MRR metric comes first."
+- "Analyze our closed-lost deals from Q1 and save the analysis."
+- "Re-run the churn analysis with this month's data."
+- "Document this metric in the data dictionary."
+
+The agent always knows what you're looking at — current dashboard, filters, view — so you can say "this dashboard" or "that panel" without being explicit.
+
+## Three things to know
+
+The app has three primary surfaces you'll spend time in:
+
+- **SQL Dashboards** — reusable panels with filters and saved views. Best for metrics you check regularly.
+- **Ad-hoc Analyses** — long-form investigations that pull from multiple sources, with re-run instructions saved alongside. Best for one-off questions you might want to revisit.
+- **Data Dictionary** — the canonical catalog of metrics, tables, columns, and SQL recipes. The agent consults it before writing any SQL, so it uses real warehouse column names and knows about caveats like "excludes internal emails".
+
+The dictionary is seeded by asking the agent: "import our dbt definitions" or "pull the metrics from our Notion handbook" and it does the work.
+
+## For developers
+
+The rest of this doc is for anyone forking the Analytics template or extending it.
+
+### Quick start
 
 Create a new Analytics app from the CLI:
 
@@ -25,8 +65,6 @@ Create a new Analytics app from the CLI:
 npx @agent-native/cli create analytics
 ```
 
-Or try the hosted demo: [analytics.agent-native.com](https://analytics.agent-native.com).
-
 Local dev:
 
 ```bash
@@ -37,15 +75,11 @@ pnpm dev
 
 The app runs at `http://localhost:3000`. Sign in with Google, then open the **Data Sources** page to connect BigQuery, HubSpot, Jira, and the rest.
 
-## Key features {#key-features}
+### Key features (technical)
 
-### Natural-language chart generation
+**Natural-language chart generation.** Ask the agent in plain English. It picks the right data source, writes the SQL, validates it against the warehouse, and renders the chart inline in chat or as a saved panel. Chart types: `line`, `area`, `bar`, `metric`, `table`, `pie`.
 
-Ask the agent in plain English. It picks the right data source, writes the SQL, validates it against the warehouse, and renders the chart inline in chat or as a saved panel. Chart types: `line`, `area`, `bar`, `metric`, `table`, `pie`.
-
-### Reusable SQL dashboards
-
-Dashboards are a named config with an array of panels. Each panel has an `id`, `title`, `sql`, `source` (`bigquery` / `app-db` / `ga4`), `chartType`, and `width` (1 or 2 columns). See the full shape in `templates/analytics/app/pages/adhoc/sql-dashboard/types.ts`.
+**Reusable SQL dashboards.** Dashboards are a named config with an array of panels. Each panel has an `id`, `title`, `sql`, `source` (`bigquery` / `app-db` / `ga4`), `chartType`, and `width` (1 or 2 columns). See the full shape in `templates/analytics/app/pages/adhoc/sql-dashboard/types.ts`.
 
 Dashboards support:
 
@@ -54,25 +88,13 @@ Dashboards support:
 - **Resizable panels** — 1- or 2-column width per panel; the grid fills the rest.
 - **Sharing** — private by default, share with users or orgs (`viewer` / `editor` / `admin`).
 
-### Ad-hoc analyses
-
-Long-form investigations that cross-reference sources. An analysis saves the original question, step-by-step re-run instructions, the data sources it touched, and the full findings in Markdown. Anyone with access can re-run it against fresh data.
-
-Stored in the `analyses` table (see `templates/analytics/server/db/schema.ts`).
-
-### Living data dictionary
+**Ad-hoc analyses.** Long-form investigations that cross-reference sources. An analysis saves the original question, step-by-step re-run instructions, the data sources it touched, and the full findings in Markdown. Anyone with access can re-run it against fresh data. Stored in the `analyses` table (see `templates/analytics/server/db/schema.ts`).
 
-The dictionary is the canonical catalog of metrics used by the org — metric name, definition, table, columns, SQL template, known gotchas, owner, and data lag. The agent reads it before writing any SQL, so it uses the real warehouse column names (`hs_is_closed`, not guessed `is_closed`) and knows about caveats like "excludes internal emails".
+**Living data dictionary.** Canonical catalog of metrics — metric name, definition, table, columns, SQL template, known gotchas, owner, and data lag. The agent reads it before writing any SQL, so it uses the real warehouse column names (`hs_is_closed`, not guessed `is_closed`) and knows about caveats like "excludes internal emails". Seeded by asking the agent to import definitions from an existing source (dbt descriptions, a Notion page, a team wiki).
 
-The dictionary is seeded by asking the agent to import definitions from an existing source (dbt descriptions, a Notion page, a team wiki).
+**SQL query explorer.** Direct SQL against BigQuery or the app DB from the **Ad-hoc** view. Useful for iterating on a query before saving it as a dashboard panel.
 
-### SQL query explorer
-
-Direct SQL against BigQuery or the app DB from the **Ad-hoc** view. Useful for iterating on a query before saving it as a dashboard panel.
-
-### Multiple data connectors
-
-Built-in actions for common sources:
+**Multiple data connectors.** Built-in actions for common sources:
 
 | Category      | Actions                                                                  |
 | ------------- | ------------------------------------------------------------------------ |
@@ -86,44 +108,28 @@ Built-in actions for common sources:
 
 Full list lives in `templates/analytics/actions/`. New sources are added by dropping a new action file — the agent picks them up automatically.
 
-### Organizations and sharing
-
-Multi-org deployments are wired up by default via `@agent-native/core/org`. Dashboards and analyses are scoped to the active org. The `/team` route manages members and invitations. See `templates/analytics/app/routes/team.tsx`.
-
-Sharing uses the framework's `share-resource` primitive. Coarse visibility is `private` / `org` / `public`; fine-grained grants are per-principal with `viewer` / `editor` / `admin` roles.
+**Organizations and sharing.** Multi-org deployments are wired up by default via `@agent-native/core/org`. Dashboards and analyses are scoped to the active org. The `/team` route manages members and invitations. See `templates/analytics/app/routes/team.tsx`. Sharing uses the framework's `share-resource` primitive. Coarse visibility is `private` / `org` / `public`; fine-grained grants are per-principal with `viewer` / `editor` / `admin` roles.
 
-## Working with the agent {#working-with-the-agent}
+### Working with the agent
 
 The agent always knows what you're looking at. The current screen state is injected into every message as a `<current-screen>` block — it contains the active view, the open dashboard or analysis, and any selected filters.
 
-Useful prompts:
-
-- "Build a dashboard showing weekly active users for the past 6 months."
-- "What percent of signups last month converted to paid?"
-- "Add a chart comparing revenue by plan to this dashboard."
-- "Reorder the panels on this dashboard so the MRR metric comes first."
-- "Analyze our closed-lost deals from Q1 and save the analysis."
-- "Re-run the churn analysis with this month's data."
-- "Document this metric in the data dictionary."
-
 The agent's system prompt gets an injected `<data-dictionary>` block with the approved metric entries for the active org. When you ask for a dashboard, the agent consults the dictionary first and uses the documented `table` / `columns` / `queryTemplate` verbatim — it does not guess column names.
 
-### Context it has automatically
+**Context it has automatically:**
 
 - **Current view** — `overview`, `adhoc` (with `dashboardId`), `analyses` (with `analysisId`), `data-dictionary`, `data-sources`, or `settings`.
 - **Active org** — scopes all queries and writes.
 - **Approved dictionary entries** — for the active workspace.
 
-### Dashboard edits
-
-The agent uses the `update-dashboard` action to edit dashboards. It supports two modes:
+**Dashboard edits.** The agent uses the `update-dashboard` action to edit dashboards. It supports two modes:
 
 - `ops` — JSON-Pointer patches for surgical edits (move a panel, replace one SQL string, remove a filter).
 - `config` — full replacement of the dashboard config.
 
 Every BigQuery panel's SQL is dry-run against the warehouse before the dashboard saves. If a column is wrong, the save is rejected with the BigQuery error — the agent fixes the SQL and retries instead of persisting broken panels.
 
-## Connecting data sources {#connecting-data-sources}
+### Connecting data sources
 
 Open the **Data Sources** page (`/data-sources`) to connect providers. Each source exposes an env-key list, a walkthrough, and a **Test Connection** button. The page calls `/api/credential-status`, `/api/credentials`, and `/api/test-connection`.
 
@@ -142,7 +148,7 @@ Provider-specific keys (HubSpot, Jira, Gong, Pylon, etc.) are documented in each
 
 Note: the BigQuery OAuth credential for Google sign-in is a **separate** credential from the BigQuery service account JSON. Create the sign-in client at GCP Console → APIs & Services → Credentials → OAuth client ID.
 
-## Data model {#data-model}
+### Data model
 
 Core tables (see `templates/analytics/server/db/schema.ts`):
 
@@ -157,7 +163,7 @@ Plus the org tables (`organizations`, `org_members`, `org_invitations`) provided
 
 The data dictionary lives in the framework's `settings` table under scoped keys; see the `list-data-dictionary` and `save-data-dictionary-entry` actions for the full shape.
 
-## Customizing it {#customizing-it}
+### Customizing it
 
 The Analytics template is meant to be forked and extended. Everything lives in `templates/analytics/`:
 

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:
 

package/docs/content/template-clips.md

@@ -1,36 +1,36 @@
 ---
-title: "Clips Template"
-description: "Agent-native screen recording with AI transcription, auto-titles, summaries, chapter markers, and full-text search across every clip."
+title: "Clips"
+description: "Record your screen, get an AI-generated title, summary, and chapter markers automatically, and search across every recording you've ever made."
 ---
 
 # Clips
 
-Clips is an agent-native screen-recording app. The user records a video, the app transcribes it, and the agent takes over: suggests titles, writes summaries, builds chapters, finds the exact moment someone said X, opens the right recording, shares it with the right teammate, drafts replies to comments.
+A screen-recording app where the agent does the post-production work for you. Record your screen, and Clips transcribes it, suggests a title and summary, builds chapter markers, and tags the content automatically. Ask "find the clip where we discussed the rollout plan" and the agent searches across every transcript you've ever made.
 
-Think Loom, but the agent is a first-class editor — and the recordings are yours, not a SaaS vendor's.
+Think along the lines of products that record short async videos for your team — but the agent is a first-class editor, and the recordings are yours, not a SaaS vendor's.
 
-## What it does {#what-it-does}
+## What you can do with it
 
-- **Record your screen.** Built-in recorder with webcam overlay, audio capture, and pause/trim.
-- **Auto-transcribe.** Every recording is transcribed on upload. Speaker turns, timestamps, searchable.
-- **Agent-generated metadata.** Titles, summaries, chapter markers, tags — the agent fills them in and keeps them current.
-- **Full-text search.** Query across every transcript in your library. "Find the clip where we discussed the rollout plan."
-- **Share links.** Per-clip permissions (public, team, private), link tracking, comments threaded with the agent in the loop.
-- **Smart library.** Group by project, filter by speaker, auto-tag based on content.
+- **Record your screen** with a built-in recorder, webcam overlay, audio capture, and pause/trim.
+- **Get an auto-generated title, summary, and chapter markers** for every recording — the agent fills them in and keeps them current.
+- **Search across every transcript** with full-text search. "Find the clip where we discussed the rollout plan."
+- **Share clips** with per-clip permissions (public, team, private). Link tracking and threaded comments work too.
+- **Smart library views.** Group by project, filter by speaker, auto-tag based on content.
+- **Edit the transcript through chat.** "Fix the mis-transcribed word at 1:42." "Pull three quotes for a blog post." The agent edits the transcript and the UI updates live.
 
-## Why it's interesting {#why}
+## Why it's interesting
 
-Three things make the Clips template a good showcase of what agent-native enables:
+Three things make Clips a good showcase of what agent-native enables:
 
 1. **The agent edits the transcript.** Fix a mis-transcribed word, generate chapter timestamps, pull quotes for a blog post — all in natural language, in the chat, with the UI updating live via polling.
 2. **Context awareness on recordings.** When you're viewing a clip, the agent knows the clip id, the current playhead, and the selected transcript range. Ask "summarize from here to the end" and it understands what "here" means.
-3. **Clips you own, not a vendor.** Unlike Loom, the recordings live in your storage, the transcripts live in your SQL, and the agent is yours. Fork the template, change how chapters get built, wire it to your own CDN — it's your code.
+3. **Clips you own, not a vendor.** The recordings live in your storage, the transcripts live in your SQL, and the agent is yours. Fork the template, change how chapters get built, wire it to your own CDN — it's your code.
 
-## Naming note {#naming-note}
+## For developers
 
-In the template, always say **"Clip"** in user-facing strings and agent messages — never "Loom." Internal table / variable names (`recordings`, `recording_transcripts`, etc.) stay as-is.
+The rest of this doc is for anyone forking the Clips template or extending it.
 
-## Scaffolding {#scaffolding}
+### Scaffolding
 
 ```bash
 pnpm dlx @agent-native/core create my-clips --template clips --standalone
@@ -38,15 +38,17 @@ pnpm dlx @agent-native/core create my-clips --template clips --standalone
 
 Clips is a larger template with a native recorder (it ships a desktop companion for local capture). See the template `README.md` for setup specifics around screen-capture permissions and storage configuration.
 
-## Customize it {#customize}
+### Customize it
 
-Ask the agent:
+Clips is a full cloneable SaaS — fork it and ask the agent to extend it. Some examples:
 
-- "Add a 'filler word removal' button that strips ums and uhs from the transcript and re-stitches the video." It edits the transcript processor and wires the UI.
-- "Auto-post a new clip to Slack #eng-demos when I record one." It adds the hook.
-- "Group the library by project — detect the project from the first words of each transcript." It updates the list view.
+- "Add a filler-word removal button that strips ums and uhs from the transcript and re-stitches the video."
+- "Auto-post a new clip to Slack #eng-demos whenever I finish a recording." (Connect Slack first via [Messaging](/docs/messaging).)
+- "Group the library by project — detect the project from the first words of each transcript."
+- "Add a 'Generate blog post from this clip' button that drafts a post from the transcript and saves it as a draft."
+- "Let viewers leave timestamped reactions on a shared clip."
 
-See [Cloneable SaaS](/docs/cloneable-saas) for the full clone → customize → deploy flow.
+The agent edits routes, components, the transcript pipeline, and the schema as needed. See [Cloneable SaaS](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [Getting Started](/docs/getting-started) if this is your first agent-native template.
 
 ## What's next