@agent-native/core 0.7.4 → 0.7.7

package/docs/content/template-content.md

@@ -0,0 +1,141 @@
+---
+title: "Content Template"
+description: "A Notion-style document editor with an AI agent that can read, write, organize, and publish your pages."
+---
+
+# Content Template
+
+A hierarchical document editor in the style of Notion or Google Docs. The AI agent has full parity with the UI — it can create pages, edit selections, reorganize the tree, and sync with Notion, all while seeing exactly what you see.
+
+## Overview {#overview}
+
+The Content template is a rich-text document workspace with a sidebar tree, a Tiptap-based editor, and an agent panel. Pages live in a nested tree, content is stored as markdown in SQL, and the agent uses the same actions the UI calls for every operation.
+
+Everything lives in one database (SQLite, Postgres, Turso — anything Drizzle supports) and the agent sees your current view, so you can say "rewrite this paragraph" or "add a sub-page for Q4 planning" and it knows what you mean without you pasting anything.
+
+## Quick start {#quick-start}
+
+Scaffold a new workspace with the Content template:
+
+```bash
+npx @agent-native/core create my-workspace --template content
+cd my-workspace
+pnpm install
+pnpm dev
+```
+
+Open `http://localhost:8080` and create your first page. The agent panel is on the right — try asking it to "create a page called Onboarding and add three sub-pages under it".
+
+Live demo: https://content.agent-native.com
+
+## Key features {#key-features}
+
+### Hierarchical pages
+
+Documents nest infinitely via a `parent_id` column. The sidebar renders a draggable tree; children move with their parents and ordering uses an integer `position` field. See `app/components/sidebar/DocumentSidebar.tsx` and `app/components/sidebar/DocumentTreeItem.tsx`.
+
+### Rich-text editor
+
+The editor is built on Tiptap with a custom extension set. It supports headings, lists, tables, code blocks with syntax highlighting, images, and links. Implementation lives in `app/components/editor/DocumentEditor.tsx` and `app/components/editor/VisualEditor.tsx`, with custom nodes under `app/components/editor/extensions/` (`CodeBlockNode.tsx`, `ImageNode.ts`, `DragHandle.tsx`, `NotionExtensions.tsx`).
+
+Interactive surfaces include:
+
+- `BubbleToolbar.tsx` — formatting toolbar that appears over a selection
+- `SlashCommandMenu.tsx` — slash-command inserter for blocks
+- `LinkHoverPreview.tsx` — hover previews for inline links
+- `TableHoverControls.tsx` — add/remove table rows and columns
+- `EmojiPicker.tsx` — emoji picker for page icons
+
+### Collaborative editing
+
+Content is edited through Yjs CRDT so multiple users and the agent can type into the same document at once without clobbering each other. The agent's `edit-document` action writes through the same pipeline as a human keystroke, so changes appear live in every open editor. See the `real-time-collab` skill for the sync model.
+
+### Search
+
+Full-text search across titles and markdown content, powered by `actions/search-documents.ts`. The sidebar exposes a search box; the agent uses the same action via `pnpm action search-documents --query "..."`.
+
+### Favorites and icons
+
+Each document can be favorited (`is_favorite`) and given an emoji `icon`. The index route auto-opens your first favorite on load — see `app/routes/_app._index.tsx`.
+
+### Notion sync
+
+Documents can be linked to a Notion page and synced in either direction:
+
+- `connect-notion-status` — check whether a Notion integration is connected
+- `link-notion-page` — link a local doc to a Notion page
+- `pull-notion-page` — overwrite local content from Notion
+- `push-notion-page` — overwrite Notion content from local
+- `list-notion-links` — list all linked documents
+- `sync-notion-comments` — bidirectionally sync comment threads
+
+Sync state is tracked in the `document_sync_links` table (last synced time, conflict flag, last error). Markdown-to-Notion block conversion lives in `shared/notion-markdown.ts`. Conflict and status UI is in `app/components/editor/NotionConflictBanner.tsx` and `NotionSyncBar.tsx`. See the `notion-integration` skill for the full flow.
+
+### Comments
+
+Threaded comments on documents with quoted-text anchors, replies, and resolve state. Backed by the `document_comments` table and `app/components/editor/CommentsSidebar.tsx`. Actions: `list-comments`, `add-comment`. Notion comments can sync both ways via `sync-notion-comments`.
+
+### Version history
+
+Every significant update snapshots a row in the `document_versions` table. The UI surfaces these in `app/components/editor/VersionHistoryPanel.tsx`.
+
+### Sharing and visibility
+
+Documents are private by default. You can change visibility to `org` or `public`, or grant per-user and per-org roles (`viewer`, `editor`, `admin`). The framework's auto-mounted sharing actions work out of the box:
+
+- `share-resource --resourceType document --resourceId <id> --principalType user --principalId <email> --role editor`
+- `unshare-resource` / `list-resource-shares` / `set-resource-visibility`
+
+See the `sharing` skill.
+
+### Teams
+
+A dedicated team page at `/team` (see `app/routes/_app.team.tsx`) uses the framework's `TeamPage` component for creating orgs and managing members.
+
+## Working with the agent {#working-with-the-agent}
+
+Because the agent sees your current screen, most prompts don't need you to reference a document explicitly. When you have a page open, "this" means that page.
+
+Example prompts:
+
+- "Rewrite this paragraph to be more concise."
+- "Add a section about pricing with three bullet points."
+- "Create a page called Q4 Planning with sub-pages for Goals, Metrics, and Risks."
+- "Summarize this doc into a TL;DR at the top."
+- "Find all my meeting notes from last week."
+- "Change the tone of this page to be more formal."
+- "Pull the latest from Notion."
+- "Share this doc with hbikna@gmail.com as an editor."
+- "Move this page under Onboarding."
+
+For small edits, the agent uses `edit-document --find ... --replace ...` so only the changed text flows through Yjs — you'll see the diff applied in place rather than the whole page re-render. For bigger rewrites it uses `update-document --content ...`.
+
+If you select text and press Cmd+I (or focus the agent panel), the selection travels with your next message as context, so "make this punchier" operates on exactly what you highlighted.
+
+## Data model {#data-model}
+
+Four core tables, all defined in `server/db/schema.ts`:
+
+- **`documents`** — the page tree. Columns: `id`, `parent_id`, `title`, `content` (markdown), `icon`, `position`, `is_favorite`, `visibility`, `owner_email`, `org_id`, `created_at`, `updated_at`.
+- **`document_versions`** — full snapshots of title and content for version history.
+- **`document_comments`** — threaded comments with `thread_id`, `parent_id`, `quoted_text`, `resolved`, and an optional `notion_comment_id` for bidirectional Notion sync.
+- **`document_sync_links`** — one row per Notion-linked document tracking remote page ID, last sync times, conflict state, and errors.
+- **`document_shares`** — per-user and per-org grants created via `createSharesTable`.
+
+Content is stored as markdown. The editor converts to and from the Tiptap JSON model in memory; the SQL row is always markdown so actions, search, and Notion sync can operate on a single canonical format.
+
+All ownable tables include `owner_email` and `org_id` via `ownableColumns()`, so a local-mode workspace (`local@localhost`) can be upgraded to a real account without losing history.
+
+## Customizing it {#customizing-it}
+
+The four places to look when changing behavior:
+
+- **`actions/`** — every operation the agent or UI can perform. Add a new file like `actions/publish-to-wordpress.ts` using `defineAction` and both sides get it for free. Key existing actions: `create-document.ts`, `edit-document.ts`, `update-document.ts`, `delete-document.ts`, `list-documents.ts`, `search-documents.ts`, `get-document.ts`, `pull-notion-page.ts`, `push-notion-page.ts`, `add-comment.ts`, `view-screen.ts`, `navigate.ts`.
+- **`app/routes/`** — the page surface. `_app.tsx` is the pathless layout that keeps the sidebar and agent panel mounted; `_app._index.tsx` is the landing view; `_app.page.$id.tsx` is the editor route; `_app.team.tsx` is the team settings page.
+- **`app/components/editor/`** — the Tiptap editor. Add a new node type under `extensions/` and register it in `DocumentEditor.tsx`. The bubble toolbar, slash menu, and hover previews are all component files you can edit.
+- **`.agents/skills/`** — guidance the agent reads before acting. If you add a new capability (say, a CMS publishing pipeline), drop a `SKILL.md` in a new skill folder so the agent uses it correctly. Existing skills: `document-editing`, `notion-integration`, `real-time-sync`, `delegate-to-agent`, `storing-data`, `self-modifying-code`, `security`, `frontend-design`, `create-skill`, `capture-learnings`.
+- **`AGENTS.md`** — the top-level agent guide with the action cheatsheet and common-tasks table. Update it whenever you add a major feature so the agent discovers it without exploring.
+- **`server/db/schema.ts`** — data model. Add a column or table here, run `pnpm db:push`, and it's available to every action.
+- **`shared/notion-markdown.ts`** — markdown-to-Notion-blocks conversion. Extend this if you add new block types that need to round-trip through Notion.
+
+The agent can make all of these changes itself — ask it to "add a tags column to documents and expose it in the sidebar" and it will update the schema, migrate, wire the UI, and write the action.

package/docs/content/template-dispatch.md

@@ -0,0 +1,58 @@
+---
+title: "Dispatch Template"
+description: "Dispatch is the workspace control plane — central inbox, cross-app orchestration, secrets vault, Slack/Telegram integration, and scheduled jobs."
+---
+
+# Dispatch
+
+Dispatch is the **workspace control plane**. Where other templates are domain apps (Mail, Calendar, Analytics), Dispatch is the app you run _alongside_ them to coordinate everything: a central inbox, a secrets vault, scheduled jobs, Slack/Telegram integration, and an orchestrator agent that delegates domain work to the right specialist app over [A2A](/docs/a2a-protocol).
+
+If you're running an [enterprise workspace](/docs/enterprise-workspace) with many apps, Dispatch is the glue.
+
+## What it does {#what-it-does}
+
+- **Central inbox.** Slack DMs, Telegram messages, email notifications, A2A requests from other agents — all land in one place. The Dispatch agent triages and either handles them itself or delegates.
+- **Orchestrator, not specialist.** Dispatch does _not_ try to be the email app or the analytics app. When someone asks "summarize last week's signups," Dispatch calls the analytics agent over A2A and returns the answer. When someone asks "draft a reply to Alice," Dispatch calls the mail agent.
+- **Secrets vault.** A central store for API keys, OAuth tokens, and shared credentials. Apps in the workspace resolve secrets from Dispatch instead of duplicating them in every `.env`. Requests + approvals for sensitive access.
+- **Integrations catalog.** One page showing every third-party integration — Slack, Telegram, SendGrid, Apollo, etc. — with a "configured / not configured / pending approval" status per app.
+- **Scheduled jobs hub.** Cross-app [recurring jobs](/docs/recurring-jobs) live here: "every weekday at 7, pull yesterday's key metrics from analytics and draft a morning summary email."
+- **Approval flow.** Destructive or external actions (sending money, shipping an outbound email, posting to Slack at scale) can require an admin OK before they fire. Dispatch owns the queue.
+
+## When to use it {#when-to-use}
+
+Use Dispatch when:
+
+- You have **two or more** agent-native apps in a workspace and want one place to coordinate between them.
+- You need **centralized secrets** with per-app grants and an audit trail.
+- You want a **messaging hub** that routes Slack or Telegram into the right domain agent.
+- You want **scheduled jobs** that pull data from several apps.
+
+Skip it for a single-app scaffold — use the [Starter template](/docs/template-starter) or any of the domain templates directly.
+
+## Architecture at a glance {#architecture}
+
+- **Orchestrator agent.** The chat is set up as a router: it reads `AGENTS.md`, `LEARNINGS.md`, and routes to specialist sub-agents or remote A2A agents.
+- **Remote agent registry.** A2A manifests live in `remote-agents/*.json` — one per app. Dispatch calls them using the `call-agent` action.
+- **Vault schema.** Drizzle tables for secrets, grants, requests, approvals, and audit logs. See `server/db/schema.ts` in the template.
+- **Slack / Telegram plugins.** Server plugins that register webhooks and forward incoming messages to the orchestrator agent.
+- **MCP hub mode.** Dispatch can act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list.
+
+## Scaffolding {#scaffolding}
+
+```bash
+pnpm dlx @agent-native/core create my-platform
+# pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
+```
+
+Dispatch is usually scaffolded into a workspace alongside the apps it coordinates. For a workspace, Dispatch's shared auth, database, and brand are inherited from the workspace core — see [Enterprise Workspace](/docs/enterprise-workspace).
+
+## Customize it {#customize}
+
+Dispatch is a full cloneable SaaS like any other template — see [Cloneable SaaS](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the issues agent" and it'll edit the routing config, add the webhook handler, and wire it up.
+
+## What's next
+
+- [**Enterprise Workspace**](/docs/enterprise-workspace) — running Dispatch alongside multiple apps
+- [**A2A Protocol**](/docs/a2a-protocol) — how Dispatch delegates to specialist agents
+- [**MCP Clients — Hub Mode**](/docs/mcp-clients#hub) — sharing MCP servers across the workspace
+- [**Recurring Jobs**](/docs/recurring-jobs) — scheduled tasks Dispatch runs

package/docs/content/template-forms.md

@@ -0,0 +1,51 @@
+---
+title: "Forms Template"
+description: "Agent-native form builder — create, edit, and analyze forms through natural language, with a live preview and click-to-edit GUI."
+---
+
+# Forms
+
+Forms is an agent-native form builder with a simple premise: everything the GUI can do, the agent can do, and vice versa. You can drag fields around in the editor, or you can type "add a 'how did you hear about us' dropdown with five options and make it required" — same result, same underlying data.
+
+Think Typeform, but the form builder _is_ the agent.
+
+## What it does {#what-it-does}
+
+- **Build forms conversationally.** "Create a contact form," "add a NPS score question," "make the email field required." The agent updates the schema; the preview updates live.
+- **Click-to-edit fine-tuning.** Every field in the preview is editable in place — label, placeholder, validation, conditional logic — with the usual GUI controls.
+- **Field types** out of the box: short text, long text, email, phone, URL, number, date, single-select, multi-select, rating, file upload, section header, conditional branch.
+- **Responses dashboard.** Per-response view + an aggregate dashboard the agent can pivot on request: "show me signups from the last 30 days grouped by source."
+- **Agent-driven analysis.** Ask the agent to cluster free-text responses, extract sentiments, or draft a reply to everyone who scored the NPS below 7.
+- **Publishing.** Public share link with embed snippet, branded thank-you page, webhook on submit.
+
+## Why it's interesting {#why}
+
+Forms is a clear example of the [ladder](/docs/what-is-agent-native#the-ladder) rung 3 payoff. The hard part of a form builder isn't the editor UI — it's everything around it: schema evolution, response analytics, conditional logic, publishing, notifications, integrations. Most of that is just prompting the agent, because every capability is an action the agent can call.
+
+## Scaffolding {#scaffolding}
+
+```bash
+pnpm dlx @agent-native/core create my-forms --template forms --standalone
+```
+
+For a workspace with forms alongside other apps:
+
+```bash
+pnpm dlx @agent-native/core create my-platform  # pick Forms + other templates
+```
+
+## Customize it {#customize}
+
+Ask the agent:
+
+- "Add a new 'signature' field type that captures a drawn signature." It adds the schema entry, renders the component, handles storage.
+- "When someone submits a form, post the response to our #signups Slack channel." It wires the webhook.
+- "Add per-form access control — some are public, some require a login." It updates the publishing flow.
+
+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
+- [**Actions**](/docs/actions) — the action system powering the builder
+- [**Real-Time Sync**](/docs/real-time-collaboration) — how the preview stays in sync with agent edits

package/docs/content/template-mail.md

@@ -0,0 +1,169 @@
+---
+title: "Mail Template"
+description: "An agent-native email client. A Gmail and Superhuman alternative you own."
+---
+
+# Mail Template
+
+Mail is an agent-native email client built on `@agent-native/core`. It reads from your real Gmail when you connect a Google account, and works as a local mailbox when you don't — with an AI agent that can triage, search, draft, and send on your behalf.
+
+## Overview {#overview}
+
+Mail is a drop-in replacement for Gmail and Superhuman. The UI is keyboard-first: a thread list on the left, the open thread in the middle, and a compose panel that opens as tabs on the right. The agent sits alongside in the sidebar and has the same powers the UI has — read, search, archive, label, star, draft, and send — via actions in `templates/mail/actions/`.
+
+Use it if you want:
+
+- An email client where an AI agent can actually work on your mail, not just suggest.
+- Superhuman-style keyboard shortcuts without the subscription.
+- Multi-account Gmail support (personal + work in one inbox).
+- Your own codebase. Fork it, change anything, own the data.
+
+The agent always knows which view, thread, and message you're looking at because the UI writes that state into SQL (`application_state`) where the agent can read it.
+
+## Quick start {#quick-start}
+
+Create a new workspace with the Mail template:
+
+```bash
+npx @agent-native/core create my-mail --standalone --template mail
+cd my-mail
+pnpm install
+pnpm dev
+```
+
+Or add Mail to an existing agent-native workspace:
+
+```bash
+agent-native add-app
+```
+
+Live demo: [mail.agent-native.com](https://mail.agent-native.com)
+
+On first run, connect a Google account from Settings to sync real Gmail. Without a Google account, the app runs against an empty local email store (useful for screenshots or demos).
+
+## Key features {#key-features}
+
+### Gmail sync (multi-account)
+
+Connect one or many Google accounts via OAuth. List and search actions query all connected inboxes by default; results carry an `accountEmail` field so you can tell which inbox each thread came from. Scope to a single account with `--account=user@example.com`. OAuth tokens are stored via `@agent-native/core/oauth-tokens` under the `"google"` provider.
+
+### Keyboard-first navigation
+
+The app is designed to run without a mouse. `J`/`K` move between threads, `E` archives, `R` replies, `C` composes, `/` focuses search, and `G` begins a "go to" chord (`G I` for Inbox, `G S` for Starred, etc.). See the [full list below](#keyboard-shortcuts).
+
+### Multiple compose drafts
+
+The compose panel supports multiple draft tabs at once. Each draft is stored as an `application_state` entry at `compose-{id}` and syncs live between the agent and the UI. The agent can create a new draft with `manage-draft --action=create`, edit your in-progress draft with `--action=update`, or close tabs with `--action=delete`. Drafts use markdown in the body field; the TipTap editor renders it as rich text and converts to HTML on send.
+
+### AI triage via automations
+
+Mail supports automation rules that run against new inbox email using AI. A rule has a natural-language condition (for example, `"from a newsletter"` or `"subject contains invoice"`) and a list of actions (`label`, `archive`, `mark_read`, `star`, `trash`). Manage them via `pnpm action manage-automations --action=create|list|update|delete|enable|disable`, or through the Settings page. Rules fire automatically and can be triggered manually with `pnpm action trigger-automations`.
+
+### Send tracking
+
+Sent messages get open-pixel and link-click tracking injected automatically. Settings live under `mail-settings.tracking` with `tracking.opens` and `tracking.clicks` (both default `true`). Only links in the new portion of a reply or forward are rewritten — quoted content is left alone. Pull stats for any sent message with `pnpm action get-tracking --id=<message-id>`, or from `GET /api/emails/:id/tracking`. Open and click events are stored in the `email_tracking` and `email_link_tracking` tables.
+
+### Search
+
+`pnpm action search-emails --q=<term>` searches across all views and all connected accounts. The UI search bar maps to the same action. Both `search-emails` and `list-emails` take `--compact` for shorter output and `--fields=from,subject,date` to limit returned fields.
+
+### Bulk operations and export
+
+- `pnpm action bulk-archive --older-than=30` archives everything older than N days.
+- `pnpm action export-emails --view=inbox --output=file.json` dumps a view to JSON.
+- Archive, trash, mark-read, and star all accept comma-separated IDs (`--id=id1,id2,id3`) for bulk changes.
+
+### Inline thread previews in agent chat
+
+When the agent answers a question about a specific thread, it can embed a live preview of the thread directly in the chat message via an `embed` code fence. The preview is a sandboxed iframe that shows the full conversation without leaving the chat, with an "Open in app" button that navigates the main window to that thread.
+
+## Working with the agent {#working-with-the-agent}
+
+The agent reads `application_state.navigation` on every turn, so it already knows which view you're in, which thread is open, and which message is focused — you don't have to tell it. You can just say things like:
+
+- "Summarize my unread emails."
+- "Find the latest thread from Alice about the budget."
+- "Draft a reply that politely declines."
+- "Archive all Netlify bot emails older than a week."
+- "Open my starred emails."
+- "Make this draft more formal."
+- "Did they open my email?"
+
+How the agent sees your context:
+
+- **Current view and thread** — the UI writes `navigation` (view, threadId, focusedEmailId, search, label) whenever you navigate. The agent reads it via `readAppState("navigation")` or `pnpm action view-screen`.
+- **Open draft** — if you're composing a reply and ask "help me word this", the agent reads the matching `compose-{id}` entry to see your current subject and body, then writes an updated draft back. The UI picks up the edit live.
+- **Thread history** — for context mid-reply, the agent fetches the full thread with `pnpm action get-thread --id=<threadId>`.
+
+How the agent takes action:
+
+- **Mail operations** — archive, trash, star, mark read, send, draft — all run as `pnpm action <name>` scripts under `templates/mail/actions/`.
+- **Navigation** — to open a thread or switch views for you, the agent writes `application_state.navigate`, which the UI consumes and deletes. The `pnpm action navigate` script wraps this.
+- **Refresh** — after any change, the agent runs `pnpm action refresh-list` so the UI refetches.
+
+## Keyboard shortcuts {#keyboard-shortcuts}
+
+| Key       | Action                      |
+| --------- | --------------------------- |
+| `J`       | Next email                  |
+| `K`       | Previous email              |
+| `Up/Down` | Same as J/K                 |
+| `Enter`   | Open focused email          |
+| `E`       | Archive email or thread     |
+| `D`       | Trash email or thread       |
+| `S`       | Star or unstar              |
+| `R`       | Reply                       |
+| `U`       | Toggle read/unread          |
+| `C`       | Compose new email           |
+| `/`       | Focus search bar            |
+| `Cmd+K`   | Open command palette        |
+| `G I`     | Go to Inbox                 |
+| `G S`     | Go to Starred               |
+| `G T`     | Go to Sent                  |
+| `G D`     | Go to Drafts                |
+| `G A`     | Go to Archive               |
+| `Esc`     | Close thread / clear search |
+
+## Data model {#data-model}
+
+When a Google account is connected, email lives in Gmail — the app is a view on top. When no account is connected, emails live in the SQL settings store under `getSetting("local-emails")` (empty by default).
+
+| Store / Table                 | What it holds                                                  |
+| ----------------------------- | -------------------------------------------------------------- |
+| `getSetting("local-emails")`  | Local email fallback when no Google account is connected       |
+| `getSetting("labels")`        | System and user labels, with unread counts                     |
+| `getSetting("mail-settings")` | User profile, tracking preferences, signature, aliases         |
+| `getSetting("aliases")`       | Email aliases                                                  |
+| `email_tracking` table        | Open-pixel events for sent messages                            |
+| `email_link_tracking` table   | Link-click events for sent messages                            |
+| `application_state` table     | `navigation`, `navigate`, `compose-{id}` entries (ephemeral)   |
+| `oauth_tokens` table          | Google OAuth tokens (provider `"google"`, one row per account) |
+
+Emails flowing through the API have the shape `{ id, threadId, from, to, cc, subject, snippet, body, date, isRead, isStarred, isArchived, isTrashed, labelIds, accountEmail, attachments }`.
+
+Routes in the UI:
+
+- `/_index.tsx` — redirects to the default inbox view.
+- `/$view.tsx` — a list view (`inbox`, `starred`, `sent`, `drafts`, `archive`, `trash`, etc.).
+- `/$view.$threadId.tsx` — a list view with a specific thread open.
+- `/email` — the embedded thread preview used in agent chat.
+- `/settings` — account connections, tracking, automations.
+- `/team` — team members and shared resources.
+
+## Customizing it {#customizing-it}
+
+Mail is yours to change. Everything important lives in a handful of places — start there.
+
+**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes both a CLI command (`pnpm action <name>`) and an HTTP endpoint (`/_agent-native/actions/<name>`). Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-automations.ts` for one with multiple sub-actions. See the [actions](/docs/actions) docs for the full pattern.
+
+**Changing the UI.** Routes are in `templates/mail/app/routes/` and components in `templates/mail/app/components/email/` and `templates/mail/app/components/layout/`. The app uses shadcn/ui primitives from `app/components/ui/` and Tabler Icons — stick to those.
+
+**Changing how the agent behaves.** Agent guidance lives in `templates/mail/AGENTS.md` and the skills in `templates/mail/.agents/skills/` (`email-drafts`, `real-time-sync`, `security`, `self-modifying-code`, and others). Agent behavior is changed by editing markdown — not code.
+
+**Changing data or settings.** Schemas for the tracking tables and related structures are in `templates/mail/server/db/`. Settings reads and writes go through `readSetting` / `writeSetting` from `@agent-native/core/settings`. Application state (navigation, drafts, one-shot commands) uses `readAppState` / `writeAppState` from `@agent-native/core/application-state`.
+
+**Adding a new automation action type.** Extend the action schema in `templates/mail/actions/manage-automations.ts` and the executor in `templates/mail/actions/trigger-automations.ts`.
+
+**Changing keyboard shortcuts.** Keybind handlers live in `templates/mail/app/components/email/` — search for `useHotkeys` or `addEventListener("keydown"` to find where each key is wired.
+
+Ask the agent to make any of these changes for you. The agent can edit its own source — see [Self-Modifying Code](/docs/key-concepts#agent-modifies-code).

package/docs/content/template-slides.md

@@ -0,0 +1,218 @@
+---
+title: "Slides Template"
+description: "Agent-native presentation editor — generate decks from a prompt, edit visually, and present in full-screen."
+---
+
+# Slides Template
+
+An open-source, agent-native presentation editor built on `@agent-native/core`. It replaces Google Slides, Pitch, and PowerPoint with a deck you can author in three ways at once — by talking to the agent, by clicking the canvas, or by editing HTML.
+
+## Overview {#overview}
+
+The Slides template is a full presentation studio:
+
+- Generate complete decks from a prompt, one slide at a time.
+- Edit slides visually or drop into raw HTML for full control.
+- Generate images with Gemini, search stock photos, and look up company logos.
+- Present full-screen with keyboard navigation and speaker notes.
+- Comment, share, and collaborate in real time over Yjs.
+
+Every operation the UI does — creating a deck, adding a slide, swapping an image — is exposed as an action the agent can call too. The agent and UI always stay in sync because they read and write the same SQL database.
+
+## Quick start {#quick-start}
+
+Create a new Slides app from the CLI:
+
+```bash
+npx @agent-native/core create my-slides --template slides
+cd my-slides
+pnpm dev
+```
+
+Or try the hosted demo at [slides.agent-native.com](https://slides.agent-native.com).
+
+Once running, open the app, click "New deck", and ask the agent in the sidebar: "Generate a 10-slide pitch deck for a coffee subscription service."
+
+## Key features {#key-features}
+
+### Prompt-to-deck generation
+
+Ask the agent for a deck and it builds one slide at a time. Slides stream into the editor live as each one is generated — the agent fires parallel `add-slide` calls so you see the deck assemble in seconds.
+
+Under the hood, this is powered by the `add-slide` and `create-deck` actions in `templates/slides/actions/`.
+
+### Eight slide layouts
+
+Built-in layouts: title, section divider, content with bullets, two-column, image, statement or quote, full-bleed, and blank. Each layout is a pure HTML template with inline styles — the agent picks the right one based on slide purpose. Templates live inside `templates/slides/AGENTS.md` so the agent can reference them without exploring the codebase.
+
+### Visual and code editing
+
+- Double-click any text to edit inline.
+- Click a block to open the bubble menu for styles, alignment, and layout.
+- Switch to the code editor (`app/components/editor/CodeEditor.tsx`) to edit raw slide HTML.
+- Use the slash menu (`SlideSlashMenu.tsx`) to insert blocks by typing `/`.
+
+### AI image generation
+
+Generate images with Gemini directly from the editor or via the agent. Each request returns multiple variations so you can pick the one that fits. Style reference images keep results visually consistent.
+
+Actions: `generate-image`, `edit-image`, `image-search`, `logo-lookup`. UI panels: `ImageGenPanel.tsx`, `ImageSearchPanel.tsx`, `LogoSearchPanel.tsx`.
+
+### Logo and stock image search
+
+- `logo-lookup --domain acme.com` fetches a company logo via Logo.dev or Brandfetch.
+- `image-search --query "mountain landscape"` searches Google Images for stock photos.
+
+### Comments and threads
+
+Leave comments on specific slides, quote selected text, and reply in threads. Stored in the `slide_comments` table. Actions: `add-slide-comment`, `list-slide-comments`.
+
+### Drag and drop reordering
+
+Reorder slides in the sidebar, duplicate, or delete with hover controls. The sidebar lives in `app/components/editor/EditorSidebar.tsx`.
+
+### Presentation mode
+
+Full-screen presentation at `/deck/:id/present` with keyboard navigation (arrow keys, space, escape), auto-hiding controls, and speaker notes. See `app/routes/deck.$id_.present.tsx` and `app/components/presentation/PresentationView.tsx`.
+
+### Share links
+
+Generate a public read-only URL for a deck so reviewers can view without an account. The share page is `app/routes/share.$token.tsx`. Fine-grained sharing (viewer, editor, admin roles, per-user or org-wide) is also available via the framework's `share-resource` action.
+
+### Real-time collaboration
+
+Multiple people can edit the same deck simultaneously. Text edits sync through Yjs CRDT so there are no conflicts, and the agent sees and edits the same live document via the `update-slide --find/--replace` action.
+
+### Undo and redo
+
+Cmd+Z and Cmd+Shift+Z work across the whole deck, with a labeled history panel (`HistoryPanel.tsx`) you can scrub through.
+
+### Extract from PDF
+
+Turn a PDF into a starter deck. The `extract-pdf` action parses the file and hands the content to the agent for layout.
+
+## Working with the agent {#working-with-the-agent}
+
+The agent chat lives in the sidebar. It can create decks, edit individual slides, generate images, search logos, and navigate the UI — all using the same actions you'd run from the CLI.
+
+### Example prompts
+
+- "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
+- "Add a pricing slide after slide 3."
+- "Make the title on this slide bigger and change the accent color to green."
+- "Generate a hero image for the current slide — dark, minimal, cinematic."
+- "Find the logo for stripe.com and add it to slide 2."
+- "Replace the word 'customers' with 'members' everywhere in this deck."
+- "Summarize this PDF as a 6-slide deck." (attach the PDF)
+
+### What the agent sees
+
+When a deck is open, the agent automatically sees:
+
+- The current `deckId` and `slideIndex`.
+- The full list of slides in the open deck.
+- The HTML content of the currently selected slide.
+
+This is injected into every message as a `current-screen` block, so the agent never has to guess what "this slide" means. The data comes from the `navigation` application-state key, which the UI writes on every navigation. See `templates/slides/actions/view-screen.ts`.
+
+### Selecting text for focused edits
+
+Select text on a slide and hit Cmd+I to focus the agent with that selection pre-loaded. The agent will act only on what you selected.
+
+### Inline slide previews in chat
+
+The agent can embed a live slide preview directly in a chat reply using the framework's embed fence. It renders a chromeless iframe via `app/routes/slide.tsx` so you can see the result without leaving the conversation.
+
+## Data model {#data-model}
+
+All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
+
+### decks
+
+| Column       | Type | Notes                                                     |
+| ------------ | ---- | --------------------------------------------------------- |
+| `id`         | text | Primary key, e.g. `deck-1712345-abc`                      |
+| `title`      | text | Deck title                                                |
+| `data`       | text | JSON blob: `{ title, slides: [{ id, content, layout }] }` |
+| `created_at` | text | Timestamp                                                 |
+| `updated_at` | text | Timestamp                                                 |
+
+Each deck also carries the standard `ownableColumns` (owner, visibility, share token) so it slots into the framework's sharing model.
+
+### slide_comments
+
+| Column                        | Notes                                  |
+| ----------------------------- | -------------------------------------- |
+| `id`                          | Primary key                            |
+| `deck_id`                     | Parent deck                            |
+| `slide_id`                    | Slide the comment lives on             |
+| `thread_id`, `parent_id`      | Threading                              |
+| `content`, `quoted_text`      | Comment body and optional text excerpt |
+| `author_email`, `author_name` | Author                                 |
+| `resolved`                    | Boolean flag                           |
+
+### deck_shares
+
+Framework-provided shares table (created via `createSharesTable`) that maps principals (users or orgs) to roles (viewer, editor, admin) per deck.
+
+### Slide structure
+
+Each slide inside `decks.data` is:
+
+```json
+{
+  "id": "slide-1",
+  "layout": "title",
+  "content": "<div class=\"fmd-slide\" style=\"...\">...</div>"
+}
+```
+
+`content` is raw HTML — the renderer (`app/components/deck/SlideRenderer.tsx`) provides the black background and fixed aspect ratio, and the HTML provides everything inside. Rich embedding is supported too: Excalidraw diagrams via `ExcalidrawSlide.tsx` and Mermaid charts via `MermaidRenderer.tsx`.
+
+## Customizing it {#customizing-it}
+
+The Slides template is fully forkable. Key places to look when extending it:
+
+### Actions — `templates/slides/actions/`
+
+Every agent-callable operation lives here as a TypeScript file. A few you'll touch often:
+
+- `create-deck.ts` — new deck from scratch or bulk replace.
+- `add-slide.ts` — append one slide; prefer this for streaming generation.
+- `update-slide.ts` — surgical find/replace or full content swap.
+- `view-screen.ts` — snapshot of what the user sees.
+- `generate-image.ts`, `edit-image.ts`, `image-search.ts`, `logo-lookup.ts` — image tooling.
+- `extract-pdf.ts` — PDF ingestion.
+
+Every action is auto-mounted at `POST /_agent-native/actions/:name` and callable from the CLI as `pnpm action <name>`. Add a new file here to give the agent a new capability.
+
+### Routes — `templates/slides/app/routes/`
+
+- `_index.tsx` — deck list.
+- `deck.$id.tsx` — the editor.
+- `deck.$id_.present.tsx` — presentation mode.
+- `share.$token.tsx` — public read-only share page.
+- `slide.tsx` — single-slide embed used in chat previews.
+- `settings.tsx` — template settings.
+- `team.tsx` — org and team management.
+
+### Editor components — `templates/slides/app/components/editor/`
+
+Most UI customization happens here: `SlideEditor.tsx`, `EditorToolbar.tsx`, `EditorSidebar.tsx`, bubble menus, slash menu, and the panels for image generation, search, and history.
+
+### Skills — `templates/slides/.agents/skills/`
+
+Agent skills that explain patterns when the agent needs to modify code:
+
+- `create-deck/` — how to create a new deck with slides.
+- `slide-editing/` — how to edit individual slides.
+- `deck-management/` — how decks are stored and accessed.
+- `slide-images/` — image generation and search workflow.
+
+### AGENTS.md
+
+`templates/slides/AGENTS.md` is the single source of truth the agent reads on every conversation. It contains the full action list, every slide HTML template, the navigation state contract, and rules for delegating to sub-agents. Update this file whenever you add an action or a new slide layout pattern.
+
+### API routes
+
+For cases where actions aren't the right fit (file uploads, streaming), the template exposes a small set of REST endpoints: `GET/POST /api/decks`, `GET/PUT/DELETE /api/decks/:id`. See `templates/slides/server/routes/api/`.