@agent-native/core 0.7.2 → 0.7.6

package/docs/content/recurring-jobs.md

@@ -0,0 +1,123 @@
+---
+title: "Recurring Jobs"
+description: "Cron-scheduled prompts the agent runs on its own — daily digests, weekly reports, hourly polling."
+---
+
+# Recurring Jobs
+
+A **recurring job** is a prompt that runs on a cron schedule. It's how the agent does things on its own: "every morning at 7 summarize my overnight emails," "every Monday post last week's signup numbers to Slack," "every hour sweep for stale drafts and delete them."
+
+Jobs live in the [workspace](/docs/workspace) at `jobs/<name>.md` — just a Markdown file with YAML frontmatter. No registration, no wiring. Drop the file in and the framework picks it up.
+
+## A job file {#job-file}
+
+```markdown
+---
+schedule: "0 7 * * *"
+enabled: true
+runAs: creator
+---
+
+# Morning digest
+
+Summarize the emails received overnight. Group by sender domain.
+Pin the top 3 threads that look like they need a reply today to the
+"Needs reply" label. Draft replies for any that are obvious.
+```
+
+That's it. The body is a prompt the agent runs at each scheduled firing. The agent has access to all the same tools and workspace context it has in an interactive chat — actions, skills, memory, connected MCP servers, sub-agents.
+
+## Frontmatter {#frontmatter}
+
+| Field        | Type                          | Default      | Description                                                                                            |
+| ------------ | ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
+| `schedule`   | cron expression               | _(required)_ | Standard 5-field cron. `"0 7 * * *"` = every day at 07:00; `"0 */4 * * *"` = every 4 hours.            |
+| `enabled`    | boolean                       | `true`       | Flip to `false` to pause without deleting the job.                                                     |
+| `runAs`      | `"creator"` \| `"shared"`     | `"creator"`  | `"creator"` runs with the job owner's identity and `ANTHROPIC_API_KEY`. `"shared"` uses the org's key. |
+| `createdBy`  | email                         | _(auto)_     | Populated when the job is created through the workspace UI or by the agent.                            |
+| `orgId`      | string                        | _(auto)_     | Org scope; inherited from the creator's active org.                                                    |
+| `lastRun`    | ISO timestamp                 | _(managed)_  | Written by the scheduler after each run.                                                               |
+| `lastStatus` | `"success"` \| `"error"` \| … | _(managed)_  | Latest outcome.                                                                                        |
+| `lastError`  | string                        | _(managed)_  | Error message if the last run failed.                                                                  |
+| `nextRun`    | ISO timestamp                 | _(managed)_  | Computed from `schedule`; used by the scheduler to decide when to fire next.                           |
+
+The `last*` and `nextRun` fields are written by the scheduler. You can read them to see the history, but don't edit them by hand — the next run will overwrite.
+
+## Cron syntax {#cron}
+
+Standard 5-field cron (minute, hour, day-of-month, month, day-of-week):
+
+| Cron           | Meaning                  |
+| -------------- | ------------------------ |
+| `*/5 * * * *`  | Every 5 minutes          |
+| `0 * * * *`    | Every hour on the hour   |
+| `0 */4 * * *`  | Every 4 hours            |
+| `0 7 * * *`    | Every day at 07:00       |
+| `0 9 * * 1`    | Every Monday at 09:00    |
+| `0 17 * * 1-5` | Weekdays at 17:00        |
+| `0 0 1 * *`    | First day of every month |
+
+The framework exports `isValidCron()` and `describeCron()` from `@agent-native/core/jobs` if you want to validate or render cron strings in the UI.
+
+## Creating a job {#creating}
+
+### From the Workspace tab
+
+`+` → **Scheduled Task** in the workspace panel. Fill in the prompt and schedule. Saves as `jobs/<slug>.md` and starts running on the next matching tick.
+
+### By asking the agent
+
+> "Create a scheduled task that summarizes my unread emails every morning at 7."
+
+The agent writes the file for you.
+
+### By hand
+
+Drop a Markdown file in `jobs/` via the framework's resource APIs:
+
+```ts
+import { resourcePut } from "@agent-native/core/resources";
+
+await resourcePut(
+  ownerEmail,
+  "jobs/morning-digest.md",
+  `---
+schedule: "0 7 * * *"
+enabled: true
+---
+Summarize overnight emails.`,
+);
+```
+
+## How the scheduler runs {#how-scheduler-runs}
+
+The scheduler is a framework plugin (`processRecurringJobs()` in `@agent-native/core/jobs`). On each tick it:
+
+1. Lists every enabled `jobs/*.md` resource across all owners.
+2. Compares `nextRun` to the current time.
+3. For each due job, spins up a fresh agent thread with the job body as the user message.
+4. The agent runs its loop — calling actions, writing to SQL, sending A2A messages, emailing, whatever the prompt asks for.
+5. On completion, writes `lastRun`, `lastStatus`, `lastError`, and recomputes `nextRun` from the cron.
+
+If the runtime is serverless/edge, trigger the tick from an external cron (Cloudflare Cron Triggers, Vercel Cron, GitHub Actions on a schedule, etc.) by hitting the framework's scheduler endpoint. If you're on Node, the scheduler can run in-process on a `setInterval`.
+
+## Debugging a job {#debugging}
+
+- Open `jobs/<name>.md` in the workspace — the frontmatter shows `lastRun`, `lastStatus`, `lastError`, `nextRun`.
+- **Run it now:** ask the agent to "run the `morning-digest` job right now." The agent will invoke the scheduler tool to force-fire it.
+- **Pause it:** flip `enabled: false`. The file stays put, just stops running.
+
+## Different from the scheduling package {#vs-scheduling-package}
+
+Don't confuse recurring jobs with `@agent-native/scheduling`:
+
+- **Recurring jobs (this page)** — cron-scheduled _prompts_ the agent runs in the background. Framework-level. Lives in the workspace. Runs on any agent-native app.
+- **`@agent-native/scheduling`** — a reusable domain package for building calendar/booking features (event types, availability windows, bookings). Powers the `calendar` and `scheduling` templates. See the scheduling template for usage.
+
+Recurring jobs are "how do I make the agent act on its own?" The scheduling package is "how do I build a calendar app?" Different concerns.
+
+## What's next
+
+- [**Workspace**](/docs/workspace) — where jobs live alongside skills, memory, and custom agents
+- [**Actions**](/docs/actions) — the tools a job calls
+- [**Agent Teams**](/docs/agent-teams) — jobs often spawn sub-agents to do parallel work

package/docs/content/skills-guide.md

@@ -105,3 +105,11 @@ Save the file at `.agents/skills/my-skill/SKILL.md`. The directory name should m
 > **Skills** — Deep dives. Each skill focuses on one pattern with detailed rules, code examples, and do/don't lists. The agent reads these when it needs to follow a specific pattern.
 
 `AGENTS.md` tells the agent _what_ the app does. Skills tell the agent _how_ to do specific things correctly. Both are needed — `AGENTS.md` for orientation, skills for execution.
+
+## Skills vs memory {#skills-vs-memory}
+
+> **Skills** — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.
+>
+> **Memory (`learnings.md`)** — Per-user notes the agent writes automatically from corrections and preferences. Loaded every turn.
+
+If the knowledge applies to _everyone_ working in the app ("always prefer CTEs over subqueries"), it's a skill. If it's about _this particular user_ ("Steve likes concise answers"), it belongs in `learnings.md` — and the agent will put it there itself the next time you correct it. See [Agent Memory (`learnings.md`)](./resources.md#learnings-md) for the full treatment.

package/docs/content/template-analytics.md

@@ -0,0 +1,190 @@
+---
+title: "Analytics Template"
+description: "AI-native analytics dashboards — connect data sources, prompt for charts, build reusable SQL dashboards and ad-hoc analyses."
+---
+
+# Analytics Template
+
+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.
+
+## Overview {#overview}
+
+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.
+
+Three primary surfaces:
+
+- **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.
+
+## Quick start {#quick-start}
+
+Create a new Analytics app from the CLI:
+
+```bash
+npx @agent-native/cli create analytics
+```
+
+Or try the hosted demo: [analytics.agent-native.com](https://analytics.agent-native.com).
+
+Local dev:
+
+```bash
+cd my-analytics-app
+pnpm install
+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}
+
+### 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`.
+
+### 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:
+
+- **Parametric SQL** — declare `variables` and `filters` at the dashboard level; panels reference them with `{{var}}` interpolation.
+- **Saved views** — per-dashboard filter presets stored in the `dashboard_views` table.
+- **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
+
+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".
+
+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.
+
+### Multiple data connectors
+
+Built-in actions for common sources:
+
+| Category      | Actions                                                                  |
+| ------------- | ------------------------------------------------------------------------ |
+| Warehouse     | `bigquery`, `bigquery-table-info`, `ga4-report`                          |
+| Product       | `mixpanel-events`, `amplitude-events`, `posthog-events`                  |
+| CRM & Revenue | `hubspot-deals`, `hubspot-metrics`, `hubspot-pipelines`, `apollo-search` |
+| Engineering   | `github-prs`, `jira-search`, `jira-analytics`                            |
+| Support       | `pylon-issues`, `gong-calls`                                             |
+| Community     | `commonroom-members`, `twitter-tweets`                                   |
+| Content & SEO | `seo-top-keywords`, `seo-page-keywords`, `seo-blog-pages`                |
+
+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.
+
+## 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
+
+- **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:
+
+- `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}
+
+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`.
+
+Credentials are stored via the framework's settings/env layer — no secrets in git. Production requires:
+
+| Variable                                 | Purpose                       |
+| ---------------------------------------- | ----------------------------- |
+| `DATABASE_URL`                           | Neon Postgres URL             |
+| `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | Auth                          |
+| `GOOGLE_CLIENT_ID` / `_SECRET`           | Google sign-in (OAuth 2.0)    |
+| `BIGQUERY_PROJECT_ID`                    | BigQuery project              |
+| `GOOGLE_APPLICATION_CREDENTIALS_JSON`    | BigQuery service-account JSON |
+| `ANTHROPIC_API_KEY`                      | Agent chat                    |
+
+Provider-specific keys (HubSpot, Jira, Gong, Pylon, etc.) are documented in each source's walkthrough on the Data Sources page. If you add a new action that needs an API key, it appears as a new source on that page via the template's onboarding registration.
+
+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}
+
+Core tables (see `templates/analytics/server/db/schema.ts`):
+
+- **`dashboards`** — both Explorer and SQL dashboards. `kind` is `"explorer"` or `"sql"`; `config` is a JSON blob matching `SqlDashboardConfig`.
+- **`dashboard_shares`** — per-resource share grants (principal, role).
+- **`dashboard_views`** — saved filter presets per dashboard.
+- **`analyses`** — ad-hoc investigations with `question`, `instructions`, `dataSources`, `resultMarkdown`, and optional `resultData`.
+- **`analysis_shares`** — per-resource share grants for analyses.
+- **`bigquery_cache`** — query result cache keyed by SQL hash with bytes-processed accounting.
+
+Plus the org tables (`organizations`, `org_members`, `org_invitations`) provided by `@agent-native/core/org`.
+
+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}
+
+The Analytics template is meant to be forked and extended. Everything lives in `templates/analytics/`:
+
+- **`AGENTS.md`** — the agent's top-level guide. Documents views, actions, and workflows.
+- **`actions/`** — every agent-callable operation. Add a new file to add a new action. Notable ones:
+  - `update-dashboard.ts` — dashboard edits (ops + full-replace)
+  - `save-analysis.ts` / `list-analyses.ts` — ad-hoc analyses
+  - `save-data-dictionary-entry.ts` / `list-data-dictionary.ts` — dictionary
+  - `bigquery.ts` — raw BigQuery execution
+  - `view-screen.ts` / `navigate.ts` — context awareness
+- **`app/routes/`** — file-based routes. Each route is a thin wrapper around a page in `app/pages/`.
+- **`app/pages/adhoc/sql-dashboard/`** — the SQL dashboard renderer, panel editor, filter bar, saved views.
+- **`app/pages/analyses/`** — analyses list and detail view.
+- **`app/pages/DataSources.tsx`** — the data-source onboarding UI.
+- **`app/pages/DataDictionary.tsx`** — the dictionary browser and editor.
+- **`.agents/skills/`** — pattern guides the agent reads on demand:
+  - `dashboard-management` — storage, scope resolution, dashboard config shape
+  - `data-querying` — which script to reach for, filtering patterns
+  - `adhoc-analysis` — workflow for cross-source investigations
+  - `data-querying`, `real-time-sync`, `frontend-design`, `storing-data`, `self-modifying-code`
+- **`.builder/skills/<provider>/SKILL.md`** — provider-specific gotchas (BigQuery, HubSpot, Jira, GA4, etc.). Read before querying; update when you learn something new.
+- **`server/db/schema.ts`** — Drizzle schema for dashboards, shares, views, analyses, BigQuery cache.
+- **`server/lib/dashboards-store.ts`** — dashboard read/write with scope resolution and legacy KV migration.
+- **`server/lib/bigquery.ts`** — BigQuery client, dry-run validator, cache logic.
+
+To add a new data source, drop a script in `actions/` that calls the provider and returns results via the `output()` helper. It becomes available to the agent immediately and can be used inside dashboard panels (if you expose the result via a server handler).
+
+To add a new chart type, extend the `ChartType` union in `app/pages/adhoc/sql-dashboard/types.ts`, handle it in `SqlChartCard.tsx`, and the agent can use it in any panel.
+
+For the broader pattern on extending templates, see the [adding-a-feature skill](/docs/skills-guide) and [actions](/docs/actions).

package/docs/content/template-calendar.md

@@ -0,0 +1,151 @@
+---
+title: "Calendar Template"
+description: "AI-native calendar with Google Calendar sync and a Calendly-style public booking page."
+---
+
+# Calendar Template
+
+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.
+
+## Overview {#overview}
+
+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:
+
+- 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.
+
+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.
+
+## Quick start {#quick-start}
+
+Create a new workspace with the Calendar template:
+
+```bash
+npx @agent-native/core create my-app --template calendar
+cd my-app
+pnpm install
+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, 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 {#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.
+
+### 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`:
+
+```json
+{
+  "timezone": "America/Los_Angeles",
+  "schedule": {
+    "monday": [{ "start": "09:00", "end": "17:00" }],
+    "tuesday": [{ "start": "09:00", "end": "17:00" }],
+    "wednesday": [
+      { "start": "09:00", "end": "12:00" },
+      { "start": "13:00", "end": "17:00" }
+    ],
+    "thursday": [{ "start": "09:00", "end": "17:00" }],
+    "friday": [{ "start": "09:00", "end": "16:00" }],
+    "saturday": [],
+    "sunday": []
+  }
+}
+```
+
+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.
+
+Every link has:
+
+- A URL slug, so the public page lives at `/book/{slug}`.
+- A primary duration plus an optional list of alternative durations (for example 15, 30, or 60 minutes).
+- Optional custom fields collected at booking time.
+- A conferencing option (Google Meet, Zoom, or a custom meeting link).
+- An `isActive` toggle to pause bookings without deleting the link.
+
+Visitors land on the public page, pick a date and time from the available slots, fill in name, email, and any custom fields, and receive a confirmation. Bookings are stored in the `bookings` table with a `cancelToken`, which powers the public cancel/reschedule page at `/booking/manage/{token}`.
+
+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:
+
+- `share-resource` — grant a user or org `viewer`, `editor`, or `admin` access.
+- `unshare-resource` — revoke a grant.
+- `list-resource-shares` — show current visibility plus all grants.
+- `set-resource-visibility` — change the coarse visibility (`private`, `org`, or `public`).
+
+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
+
+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}
+
+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}
+
+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.
+
+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}
+
+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.

package/docs/content/template-clips.md

@@ -0,0 +1,55 @@
+---
+title: "Clips Template"
+description: "Agent-native screen recording with AI transcription, auto-titles, summaries, chapter markers, and full-text search across every clip."
+---
+
+# 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.
+
+Think Loom, but the agent is a first-class editor — and the recordings are yours, not a SaaS vendor's.
+
+## What it does {#what-it-does}
+
+- **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.
+
+## Why it's interesting {#why}
+
+Three things make the Clips template 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.
+
+## Naming note {#naming-note}
+
+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.
+
+## Scaffolding {#scaffolding}
+
+```bash
+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}
+
+Ask the agent:
+
+- "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.
+
+See [Cloneable SaaS](/docs/cloneable-saas) for the full clone → customize → deploy flow.
+
+## What's next
+
+- [**Cloneable SaaS**](/docs/cloneable-saas) — the clone-and-own model
+- [**Context Awareness**](/docs/context-awareness) — how the agent knows the current clip and playhead
+- [**Agent Teams**](/docs/agent-teams) — delegate transcript cleanup to a specialist sub-agent