@agent-native/core 0.47.1 → 0.48.1

package/docs/content/template-content.md

@@ -43,6 +43,14 @@ When you open the app, click **+ New page** in the sidebar, give it a title, and
 
 Select text and hit Cmd+I to focus the agent with that selection pre-loaded — "make this punchier" then operates on exactly what you highlighted.
 
+## Why it's interesting
+
+Three things make Content a good showcase of the framework:
+
+1. **Agent and editor share one Yjs document.** The same CRDT that prevents conflicts between two simultaneous human typists is what the agent writes through via `edit-document`. There is no separate AI path — the diff appears live in every open browser tab.
+2. **Notion sync as a two-way bridge.** Rather than replacing Notion, the template treats it as a peer: pull, push, bidirectional comment sync, conflict detection, and content-hash deduplication are all first-class. It demonstrates how agent-native apps can round-trip with external systems without losing their SQL-backed canonical form.
+3. **Inline databases alongside prose.** The `content_databases` / `content_database_items` / `document_property_definitions` stack shows how structured tabular data can live inside an agent-native document without needing a separate app or a custom Airtable integration.
+
 ## For developers
 
 The rest of this doc is for anyone forking the Content template or extending it.
@@ -80,7 +88,7 @@ Interactive surfaces include:
 
 ### 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.
+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 [Real-time collaboration](/docs/real-time-collaboration) for the sync model.
 
 ### Search
 
@@ -132,14 +140,26 @@ For small edits, the agent uses `edit-document --find ... --replace ...` so only
 
 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.
 
+### Databases and properties
+
+Documents can host inline databases — Notion-style tables where each row is itself a document. The agent can create databases, add items, configure column definitions, and set property values through actions: `create-content-database`, `add-database-item`, `set-document-property`. Property definitions (type, visibility, options, position) live in `document_property_definitions`; per-row values live in `document_property_values`.
+
+### Additional actions
+
+Beyond the CRUD surface in the data model, the template ships `export-document` for converting a page to Markdown or HTML, `transcribe-media` for attaching a transcript to a page, and `restore-document-version` for rolling back to an earlier snapshot.
+
 ### Data model
 
-Four core tables, all defined in `server/db/schema.ts`:
+Nine 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_versions`** — full snapshots of title and content for version history. Roll back with `restore-document-version`.
 - **`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_sync_links`** — one row per Notion-linked document tracking remote page ID, last sync times, conflict state, content hash, and errors.
+- **`document_property_definitions`** — column definitions for inline databases: name, type, visibility, options, and position.
+- **`content_databases`** — inline database objects attached to a `document_id` with a title and view config JSON.
+- **`content_database_items`** — rows in an inline database, each linking a `database_id` to a `document_id`.
+- **`document_property_values`** — per-document property values (`property_id` → `value_json`).
 - **`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.

package/docs/content/template-design.md

@@ -11,7 +11,18 @@ Use it when you want a polished landing page concept, product UI direction, bran
 
 ![Design studio showing generated HTML prototypes and tweak controls](https://cdn.builder.io/api/v1/image/assets%2F348da13fcd8b414c87de9066196f7266%2F961bedb713a94463b834c1f2f4643bcf?format=webp&width=1200)
 
-## Start Here
+## What you can do with it
+
+- **Generate complete prototypes.** Describe the screen or page you need and the agent creates a working HTML document with Tailwind styling and Alpine interactions.
+- **Compare variants.** Start with multiple directions, pick the strongest one, then continue refining.
+- **Tweak visually.** Use the built-in tweak controls for common changes, or ask the agent for copy, layout, color, spacing, and interaction updates.
+- **Apply design systems.** Save and reuse design-system preferences so generated work stays closer to your brand.
+- **Import references.** Bring in existing HTML or reference material as context for a new design pass.
+- **Export real files.** Export HTML, ZIP, or PDF from the generated prototype.
+
+## Getting started
+
+Live demo: [design.agent-native.com](https://design.agent-native.com).
 
 1. **Describe the artifact.** Ask for the screen, flow, landing page, or visual
    direction you want. Include audience, tone, and any product constraints.
@@ -22,7 +33,7 @@ Use it when you want a polished landing page concept, product UI direction, bran
 4. **Export when it is useful.** Download HTML, ZIP, or PDF once the prototype
    is ready to hand to another tool or teammate.
 
-## Useful Prompts
+### Useful prompts
 
 - "Create three landing-page directions for a technical analytics product."
 - "Make this dashboard denser and easier to scan for an operations team."
@@ -30,22 +41,13 @@ Use it when you want a polished landing page concept, product UI direction, bran
 - "Export this prototype as a ZIP once the final variant is selected."
 - "Turn this HTML into a stronger pricing page without changing the brand colors."
 
-## What You Can Do With It
-
-- **Generate complete prototypes.** Describe the screen or page you need and the agent creates a working HTML document with Tailwind styling and Alpine interactions.
-- **Compare variants.** Start with multiple directions, pick the strongest one, then continue refining.
-- **Tweak visually.** Use the built-in tweak controls for common changes, or ask the agent for copy, layout, color, spacing, and interaction updates.
-- **Apply design systems.** Save and reuse design-system preferences so generated work stays closer to your brand.
-- **Import references.** Bring in existing HTML or reference material as context for a new design pass.
-- **Export real files.** Export HTML, ZIP, or PDF from the generated prototype.
-
-## Why It's Interesting
+## Why it's interesting
 
 Design is useful because the agent edits an artifact that is already close to shippable web UI. There is no separate "AI mockup" format to translate later: the preview, the editable source, and the exported artifact all come from the same HTML.
 
 The template is also a good example of agent-native ownership. The app stores designs in SQL, exposes template operations as actions, and lets you fork the whole workflow when your team needs a different renderer, exporter, or design-system model.
 
-## For Developers
+## For developers
 
 The rest of this doc is for anyone forking the Design template or extending it.
 
@@ -55,7 +57,7 @@ The rest of this doc is for anyone forking the Design template or extending it.
 npx @agent-native/core create my-design --standalone --template design
 ```
 
-### Data Model
+### Data model
 
 All data lives in SQL via Drizzle ORM. Schema: `templates/design/server/db/schema.ts`. Designs and design systems carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
 
@@ -71,7 +73,7 @@ A design project is a shell until it has content: `create-design` makes an empty
 
 Routes in the UI live under `templates/design/app/routes/`: `_index.tsx` (list), `design.$id.tsx` (editor), `present.$id.tsx` (presentation), `design-systems.tsx` and `design-systems_.setup.tsx`, `templates.tsx`, `examples.tsx`, plus `settings.tsx` and `team.tsx`.
 
-### Key Actions
+### Key actions
 
 Every agent-callable operation is a TypeScript file in `templates/design/actions/`, auto-mounted at `POST /_agent-native/actions/:name` and runnable from the CLI as `pnpm action <name>`. The groupings:
 
@@ -82,7 +84,7 @@ Every agent-callable operation is a TypeScript file in `templates/design/actions
 - **Export & handoff** — `export-html`, `export-pdf`, `export-svg`, `export-zip`, and `export-coding-handoff` to turn a design into a coding-tool handoff.
 - **Context & navigation** — `view-screen` (current design, open file, view, pending question or variant grid), `get-design-snapshot` (current state for an external agent to continue from), and `navigate`.
 
-### Customizing It
+### Customizing it
 
 Design is a complete, cloneable template. Some practical extension ideas:
 
@@ -94,7 +96,7 @@ Design is a complete, cloneable template. Some practical extension ideas:
 
 The agent edits routes, components, actions, and SQL-backed models as needed. See [Templates](/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
+## What's next
 
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model
 - [**Context Awareness**](/docs/context-awareness) — how the agent knows what the user is viewing

package/docs/content/template-dispatch.md

@@ -46,6 +46,8 @@ Use Dispatch when:
 
 Skip it for a single-app scaffold — use the [Starter template](/docs/template-starter) or any of the domain templates directly.
 
+Live demo: [dispatch.agent-native.com](https://dispatch.agent-native.com).
+
 ## What you'll do with it {#what-youll-do}
 
 Day-to-day, Dispatch is the place admins and ops folks open to keep the workspace running:

package/docs/content/template-forms.md

@@ -30,6 +30,8 @@ When you open the app, you see your forms, the current editor, and a live previe
 
 ## Getting started
 
+Live demo: [forms.agent-native.com](https://forms.agent-native.com).
+
 1. **Create a form from a prompt.** Ask for the form you want, including the
    audience and what should happen after submission.
 2. **Refine in the editor.** Adjust labels, validation, choices, and order in
@@ -49,7 +51,11 @@ When you open the app, you see your forms, the current editor, and a live previe
 
 ## Why it's interesting
 
-The useful part of an agent-native form builder is that setup and iteration happen in the same place. You can ask the agent to add fields, adjust copy, connect Slack notifications, or inspect the submission data, while the UI remains the direct editor for the same SQL records.
+Three things make Forms a good showcase of the framework:
+
+1. **Single SQL record, two editors.** The form's `fields` JSON column is the source of truth for both the visual builder and the agent. Ask the agent to add a field and the builder re-renders — no sync step, no separate "AI draft" state.
+2. **Public and private surfaces from one schema.** The same form row serves authenticated editors (full field + settings access) and anonymous respondents (public fill page with secrets stripped). `toPublicFormSettings` handles the split at the action layer.
+3. **Integrations as settings, not infrastructure.** Slack, Discord, Google Sheets, and webhook destinations are stored as JSON in the form's settings column and executed server-side at submission time — adding a new integration type is an action-layer change, not a schema migration.
 
 See [What is agent-native?](/docs/what-is-agent-native) for the broader framework model.
 
@@ -81,6 +87,27 @@ All data lives in SQL via Drizzle ORM. Schema: `templates/forms/server/db/schema
 
 The `fields` and `settings` JSON shapes are defined in `templates/forms/shared/types.ts` (`FormField`, `FormSettings`). Owner-private settings such as integration webhook URLs and allowed origins are stripped before any data reaches the public fill page via `toPublicFormSettings`.
 
+### Key features (technical) {#key-features}
+
+Forms are defined as JSON field arrays (`FormField[]`) and stored in a single `fields` column — no separate table per field type. This makes the schema additive and the agent's edits surgical: changing a field label is a JSON-patch on one column, not a row update across a join table. All field types (text, email, number, long text, select, multi-select, checkbox, radio, date, rating, scale) are handled by the renderer and editor without schema changes.
+
+The public fill page is fully unauthenticated. `toPublicFormSettings` strips integration URLs and other owner-private settings before the form data reaches the browser, so secrets never leak to respondents.
+
+Integrations (Slack, Discord, Google Sheets, webhooks) are stored as settings inside the form's `settings` JSON column and executed server-side at submission time.
+
+### Key actions
+
+Every operation is a TypeScript file in `templates/forms/actions/`, auto-mounted at `POST /_agent-native/actions/:name`:
+
+- `create-form` — create a new form (title, description, fields, settings)
+- `update-form` — update fields, settings, or status
+- `get-form` — retrieve a form by id or slug
+- `list-forms` — list accessible forms
+- `delete-form` — soft-delete (sets `deleted_at`)
+- `restore-form` — restore a soft-deleted form
+- `list-responses` — list submissions for a form with optional filters
+- `export-responses` — export responses as CSV or JSON
+
 ### Customizing it
 
 Ask the agent for shipped behavior first:

package/docs/content/template-mail.md

@@ -82,6 +82,14 @@ If you select text and hit Cmd+I, that selection travels with your next message
 | `G A`     | Go to Archive               |
 | `Esc`     | Close thread / clear search |
 
+## Why it's interesting
+
+Three things make Mail a good showcase of the framework:
+
+1. **Gmail as a view, not a copy.** Email lives in Gmail; the app is a fast keyboard-first view on top. Actions like `list-emails` and `search-emails` query the Gmail API live rather than maintaining a local sync — demonstrating how agent-native apps can wrap external services without duplicating state.
+2. **Shared compose state between the agent and the UI.** Each draft tab is an `application_state` entry at `compose-{id}`. The agent can create, edit, or close drafts via `manage-draft`; the UI reads the same entry and renders it live. No separate draft format, no polling — same row.
+3. **Queued-draft review.** Teammates or Slack users can ask the agent to prepare an email on behalf of an org member. The draft sits in the `queued_email_drafts` SQL table until the owner reviews and explicitly sends — demonstrating how agent-native apps can keep humans in the loop for consequential, irreversible actions.
+
 ## For developers
 
 The rest of this doc is for anyone forking the Mail template or extending it.
@@ -103,6 +111,15 @@ Or add Mail to an existing agent-native workspace:
 npx @agent-native/core add-app
 ```
 
+To connect Gmail in dev, you need a Google OAuth client:
+
+1. Open [Google Cloud Console](https://console.cloud.google.com/) and create a project.
+2. Enable the **Gmail API** under APIs & Services → Library.
+3. Create OAuth 2.0 credentials (type: Web application). Add `http://localhost:8085/_agent-native/google/callback` as an authorized redirect URI.
+4. Copy the Client ID and Client Secret into the Settings page of the running app, then click **Connect Google account**.
+
+Tokens are stored in the `oauth_tokens` SQL table and refresh automatically. You can connect multiple Gmail accounts once the first is set up.
+
 ### Key features (technical)
 
 **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.

package/docs/content/template-plan.md

@@ -236,7 +236,7 @@ available.
 The rest of this doc is for anyone forking or self-hosting the Plans template.
 Most users should install the skill with the CLI instead of scaffolding the app.
 
-### Scaffold the template
+### Quick start
 
 ```bash
 npx @agent-native/core create my-plans --standalone --template plan
@@ -250,21 +250,188 @@ The hosted app-backed skill uses:
 - App: `https://plan.agent-native.com`
 - MCP: `https://plan.agent-native.com/_agent-native/mcp`
 
-The local template is useful when you are developing Plans itself, testing local
-persistence, or running a fully self-hosted review surface.
+The local template is useful when you are developing Plans itself, testing local persistence, or running a fully self-hosted review surface.
 
-### Local mode (advanced, offline)
+### Data model
 
-For fully offline, no-account use, you can run the Plans app locally and sync
-your plans to your repo as MDX. This local mode is a separate, advanced path —
-not the default hosted flow — and is best when you need everything to stay on
-your machine and in version control. For the stricter no-DB path, use
-[local-files privacy mode](#local-files), which reads from MDX folders instead
-of creating local SQL rows.
+Schema lives in `templates/plan/server/db/schema.ts`. Core tables:
+
+| Table              | What it holds                                                                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `plans`            | Each plan or recap — `title`, `brief`, `kind` (plan/recap), `status`, `source`, `html`/`markdown`/`content`, `hosted_plan_id/url`, usage stats, `source_url` |
+| `plan_sections`    | Ordered sections within a plan — `type`, `title`, `body`, `html`, `sort_order`, `created_by`                                                                 |
+| `plan_comments`    | Threaded comments — `kind`, `status`, `anchor`, `message`, `resolution_target`, `mentions_json`, `resolved_by`                                               |
+| `plan_events`      | Audit log of agent/human events on a plan                                                                                                                    |
+| `plan_versions`    | Point-in-time snapshots for version history                                                                                                                  |
+| `plan_shares`      | Per-principal share grants (viewer / editor / admin)                                                                                                         |
+| `plan_guest_mints` | Rate-limit records for guest session issuance                                                                                                                |
+| `plan_assets`      | Inline image assets stored as base64 (fallback when no upload provider)                                                                                      |
+
+### Key actions
+
+Actions in `templates/plan/actions/`:
+
+- **Creation** — `create-visual-plan`, `create-visual-recap`, `create-ui-plan`, `create-prototype-plan`, `create-plan-design`, `create-visual-questions`
+- **Reading & editing** — `get-visual-plan`, `update-visual-plan`, `list-visual-plans`, `import-visual-plan-source`, `patch-visual-plan-source`, `read-visual-plan-source`, `export-visual-plan`
+- **Publishing & sharing** — `publish-visual-plan`
+- **Versions** — `list-plan-versions`, `get-plan-version`, `restore-plan-version`
+- **Comments & feedback** — `get-plan-feedback`, `reply-to-plan-comment`, `resolve-plan-comment`, `consume-plan-feedback`
+- **Prototype** — `convert-visual-plan-to-prototype`, `create-prototype-plan`
+- **Context & navigation** — `view-screen`, `navigate`
+
+### Route map
+
+- `app/routes/plans.$id.tsx` — plan editor / review surface
+- `app/routes/plans._index.tsx` — plan list
+- `app/routes/share.$token.tsx` — public / shared plan view
+- `app/routes/local-plans.$slug.tsx` — local-files mode preview
+
+### Local mode (advanced, offline) {#local-mode}
+
+For fully offline, no-account use, you can run the Plans app locally and point it at local MDX folders. For the stricter no-DB path, use [local-files privacy mode](#local-files), which reads from MDX folders instead of creating local SQL rows. Local mode is a separate, advanced path — not the default hosted flow.
+
+## Events and notifications {#events}
+
+The Plan template emits four events on the framework event bus. Any automation
+can subscribe to them — no custom integration code needed.
+
+### Event reference {#event-reference}
+
+#### `plan.created`
+
+Fires when a new visual plan or recap is created.
+
+| Field       | Type                  | Description                              |
+| ----------- | --------------------- | ---------------------------------------- |
+| `planId`    | string                | Unique plan identifier                   |
+| `title`     | string                | Plan title                               |
+| `kind`      | `"plan"` \| `"recap"` | Whether this is a plan or a recap        |
+| `status`    | string                | Initial status (e.g. `"review"`)         |
+| `path`      | string                | App-relative path (e.g. `/plans/plan-…`) |
+| `createdBy` | string                | Always `"agent"` for plan creation       |
+
+#### `plan.commented`
+
+Fires when one or more comments are added to a plan.
+
+| Field              | Type                             | Description                                                 |
+| ------------------ | -------------------------------- | ----------------------------------------------------------- |
+| `planId`           | string                           | Plan identifier                                             |
+| `title`            | string                           | Plan title                                                  |
+| `kind`             | `"plan"` \| `"recap"`            | Plan or recap                                               |
+| `commentIds`       | string[]                         | IDs of the new comments                                     |
+| `commentCount`     | number                           | Number of new comments in this batch                        |
+| `resolutionTarget` | `"agent"` \| `"human"` \| `null` | Dominant target — `"agent"` if any comment targets an agent |
+| `excerpt`          | string                           | First 200 characters of the first comment                   |
+| `author`           | string \| null                   | Email of the commenter, if known                            |
+| `path`             | string                           | App-relative path                                           |
+
+#### `plan.published`
+
+Fires when a local plan is published (or re-published) to a hosted shareable URL.
+
+| Field                 | Type                  | Description                        |
+| --------------------- | --------------------- | ---------------------------------- |
+| `planId`              | string                | Local plan identifier              |
+| `title`               | string                | Plan title                         |
+| `kind`                | `"plan"` \| `"recap"` | Plan or recap                      |
+| `hostedPlanId`        | string                | Hosted plan identifier             |
+| `url`                 | string                | Full public URL of the hosted plan |
+| `requestedVisibility` | string                | `"public"`, `"private"`, etc.      |
+
+#### `plan.status.changed`
+
+Fires when a plan's status changes (e.g. `review` → `approved`).
+
+| Field       | Type                  | Description                        |
+| ----------- | --------------------- | ---------------------------------- |
+| `planId`    | string                | Plan identifier                    |
+| `title`     | string                | Plan title                         |
+| `kind`      | `"plan"` \| `"recap"` | Plan or recap                      |
+| `oldStatus` | string \| null        | Previous status                    |
+| `newStatus` | string                | New status                         |
+| `changedBy` | string \| null        | Email of the person who changed it |
+| `path`      | string                | App-relative path                  |
+
+### Automation recipes {#automation-recipes}
+
+These automations are created by asking the plan agent — no code changes needed.
+The agent calls `manage-automations` with `action=define`, writes a
+`jobs/<name>.md` resource, and the event subscription starts immediately.
+
+#### Notify via webhook when someone comments on a plan
+
+Ask the plan agent:
+
+> "When someone adds a human comment on a plan, POST a message to my webhook."
+
+The agent creates an automation like this:
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+Send a POST request to ${keys.NOTIFY_WEBHOOK} with a JSON body containing:
+  - "title": the plan title from the event payload
+  - "excerpt": the comment excerpt from the event payload
+  - "url": the base app URL concatenated with the path field from the event payload
+  - "author": the author field from the event payload (may be null)
+```
+
+Before the automation can fire you need to add the webhook URL as an ad-hoc key:
+
+1. Go to **Settings → Keys** and add a key named `NOTIFY_WEBHOOK` with your
+   webhook URL (e.g. a Slack incoming webhook, a generic HTTP endpoint, or any
+   notification service URL).
+2. Optionally set a URL allowlist on the key to restrict which origins it can
+   POST to.
+
+The `web-request` tool resolves `${keys.NOTIFY_WEBHOOK}` server-side before
+sending — the raw URL never appears in the agent's context.
+
+**To target Slack specifically:** set `NOTIFY_WEBHOOK` to your Slack incoming
+webhook URL
+(`https://hooks.slack.com/services/…`). The automation body above already
+produces a payload Slack's incoming webhook accepts via the `text` or `blocks`
+fields — ask the agent to format the body as a Slack message if you want richer
+formatting.
+
+#### Wake the coding agent when feedback targets it
+
+For feedback directed at the coding agent (`resolutionTarget === "agent"`), ask:
+
+> "When a plan comment targets the agent, run my coding agent with the plan
+> excerpt as context."
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is agent"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+Use the manage-notifications action or web-request tool to alert the coding agent
+that new agent-targeted feedback has arrived on plan ${planId}: "${excerpt}".
+Include the plan path so the agent can navigate directly to it.
+```
+
+Because the automation runs a full agent loop (`mode: agentic`), it can call
+`web-request`, send notifications, or invoke any action the agent has access to.
+The exact delivery mechanism depends on what notification channels you have
+configured — the agent picks the best available one.
 
 ## What's next
 
 - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
+- [**Automations**](/docs/automations) — event-triggered and scheduled automations
 - [**Plan plugin & marketplace**](/docs/plan-plugin) — install the Plan skills as a Claude Code or Codex plugin
 - [**Skills**](/docs/skills-guide) — how Agent-Native installs skills
 - [**MCP Clients**](/docs/mcp-clients) — configuring hosted MCP connectors

package/docs/content/template-slides.md

@@ -28,6 +28,9 @@ When you open a deck, you get a slide editor in the middle, a sidebar of slides
 - **Present full-screen** with keyboard navigation, auto-hiding controls, and speaker notes.
 - **Comment, collaborate, and share.** Multiple people can edit the same deck in real time. Generate a public read-only URL or share with specific teammates.
 - **Import from PDF.** Turn a PDF into a starter deck — the agent parses it and lays out the content.
+- **Import from other formats.** Import PPTX, DOCX, Google Docs, GitHub repos, or any URL as a starting point. Export to PPTX, Google Slides, or HTML.
+- **Apply design systems.** Brand tokens, custom instructions, and default palettes are saved as design systems and applied to new decks.
+- **Restore earlier versions.** Each deck change is snapshotted; list or restore any prior version.
 
 ## Getting started
 
@@ -51,6 +54,14 @@ When you open the app:
 
 Select text on a slide and hit Cmd+I to focus the agent with that selection — it'll act only on what you selected.
 
+## Why it's interesting
+
+Three things make Slides a good showcase of the framework:
+
+1. **Streamed, parallel generation.** The agent fires parallel `add-slide` calls so you see the deck assemble in real time — one slide at a time — rather than waiting for a full batch. That pattern works for any content type that benefits from progressive rendering.
+2. **Agent and editor share one document.** The same Yjs CRDT that lets two humans type concurrently is what the agent writes through via `update-slide --find/--replace`. There is no separate "AI-only" edit path.
+3. **Multi-modal source ingestion.** PPTX, DOCX, Google Docs, PDFs, URLs, and GitHub repos all feed through the same `import-*` action surface. Adding a new source format is a single action file; the agent picks it up immediately.
+
 ## For developers
 
 The rest of this doc is for anyone forking the Slides template or extending it.
@@ -68,7 +79,19 @@ pnpm dev
 
 ### Key features (technical) {#key-features}
 
-### Prompt-to-deck generation
+#### Import and export
+
+The template can pull content in from PPTX (`import-pptx`), DOCX (`import-docx`), Google Docs (`import-google-doc`), arbitrary URLs (`import-from-url`), and GitHub repos (`import-github`). Export paths cover PPTX (`export-pptx`), Google Slides (`export-google-slides`), and HTML (`export-html`). Importing uses the same action surface as the rest of the template — no separate pipeline.
+
+#### Design systems
+
+Reusable brand tokens are stored in the `design_systems` table (colors, typography, spacing, assets, custom instructions, and an `is_default` flag). Sharing is managed via `design_system_shares`. Actions: `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `set-default-design-system`, `apply-design-system`, and `analyze-brand-assets` (collects brand data before analysis). See the `design-systems` and `image-generation-via-a2a` skills for the full pattern.
+
+#### Deck versions
+
+Every significant deck change is snapshotted in the `deck_versions` table (stores a full copy of title and deck data with an optional `changeLabel`). Actions: `list-deck-versions`, `restore-deck-version`, `get-deck-version`.
+
+#### 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.
 
@@ -150,7 +173,7 @@ The agent can embed a live slide preview directly in a chat reply using the fram
 
 All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
 
-### decks
+#### decks
 
 | Column       | Type | Notes                                                     |
 | ------------ | ---- | --------------------------------------------------------- |
@@ -162,7 +185,7 @@ All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/
 
 Each deck also carries the standard `ownableColumns` (owner, visibility, share token) so it slots into the framework's sharing model.
 
-### slide_comments
+#### slide_comments
 
 | Column                        | Notes                                  |
 | ----------------------------- | -------------------------------------- |
@@ -174,11 +197,27 @@ Each deck also carries the standard `ownableColumns` (owner, visibility, share t
 | `author_email`, `author_name` | Author                                 |
 | `resolved`                    | Boolean flag                           |
 
-### deck_shares
+#### deck_shares
 
 Framework-provided shares table (created via `createSharesTable`) that maps principals (users or orgs) to roles (viewer, editor, admin) per deck.
 
-### Slide structure
+#### deck_versions
+
+Point-in-time snapshots of a deck — `deck_id`, `title`, `data` (full deck JSON), and an optional `change_label`. Used by `list-deck-versions` / `restore-deck-version`.
+
+#### design_systems
+
+Reusable brand tokens — `data` (colors/typography/spacing), `assets`, `custom_instructions`, and an `is_default` flag. Uses `ownableColumns` so design systems can be shared per-user or per-org.
+
+#### design_system_shares
+
+Framework shares table for design systems, mapping principals to roles (viewer, editor, admin).
+
+#### deck_share_links
+
+Persisted public share-link snapshots keyed by `token`. Each row stores a `title`, a JSON `slides` array snapshot, an optional `aspect_ratio`, and `created_at`. Persisting share links here means they survive server restarts and work across serverless instances.
+
+#### Slide structure
 
 Each slide inside `decks.data` is:
 
@@ -192,11 +231,11 @@ Each slide inside `decks.data` is:
 
 `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 {#customizing}
 
 The Slides template is fully forkable. Key places to look when extending it:
 
-### Actions — `templates/slides/actions/`
+#### Actions — `templates/slides/actions/`
 
 Every agent-callable operation lives here as a TypeScript file. A few you'll touch often:
 
@@ -209,7 +248,7 @@ Every agent-callable operation lives here as a TypeScript file. A few you'll tou
 
 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/`
+#### Routes — `templates/slides/app/routes/`
 
 - `_index.tsx` — deck list.
 - `deck.$id.tsx` — the editor.
@@ -219,11 +258,11 @@ Every action is auto-mounted at `POST /_agent-native/actions/:name` and callable
 - `settings.tsx` — template settings.
 - `team.tsx` — org and team management.
 
-### Editor components — `templates/slides/app/components/editor/`
+#### 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/`
+#### Skills — `templates/slides/.agents/skills/`
 
 Agent skills that explain patterns when the agent needs to modify code:
 
@@ -232,10 +271,10 @@ Agent skills that explain patterns when the agent needs to modify code:
 - `deck-management/` — how decks are stored and accessed.
 - `slide-images/` — image generation and search workflow.
 
-### AGENTS.md
+#### AGENTS.md
 
 `templates/slides/AGENTS.md` is the short router the agent reads on every conversation. It points at the skills under `.agents/skills/` and lays out the core rules, application-state contract, and skill index. The exact slide HTML templates for every layout live in `.agents/skills/create-deck/SKILL.md` — update that skill whenever you add or change a slide layout pattern.
 
-### API routes
+#### 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/`.

package/docs/content/template-videos.md

@@ -52,6 +52,14 @@ When you open the studio:
 
 If you select a track in the timeline and hit Cmd+I, the agent picks up that selection — "make this one snappier" just works.
 
+## Why it's interesting
+
+Three things make the Video template a good showcase of the framework:
+
+1. **Code as the authoring format.** Each composition is a React component, so the agent can write entirely new animation types — not just adjust parameters. The template demonstrates that an agent-native app can treat source code as a first-class editable artifact rather than a fixed runtime.
+2. **Track-based animation as structured data.** Animations are `AnimationTrack` rows (start, end, easing, animated props) rather than hardcoded frame checks. This makes AI edits ("shift this track 10 frames later") reliable and composable without touching render logic.
+3. **SQL + localStorage fusion.** User-created compositions persist in SQL; per-session tweaks (easing experiments, parameter knobs) persist in localStorage and deep-merge on load. This two-layer approach shows how to keep the agent's durable state separate from ephemeral in-session exploration.
+
 ## For developers
 
 The rest of this doc is for anyone forking the Video template or extending it. This template is more code-forward than the others — every composition is a React component and every animation is data on a track.
@@ -137,6 +145,15 @@ Server-side schema is in `templates/videos/server/db/schema.ts`:
 
 - `compositions` — id, title, type, `data` (full composition JSON blob), ownership columns, timestamps.
 - `composition_shares` — standard share grants produced by `createSharesTable()`.
+- `design_systems` — reusable brand tokens (colors, typography, spacing, assets, custom instructions, `is_default` flag) with `ownableColumns`.
+- `design_system_shares` — share grants for design systems.
+- `folders` — nestable folders for library organization, with `ownableColumns`.
+- `folder_shares` — share grants for folders.
+- `folder_memberships` — many-to-many join between a `folder_id` and a `composition_id`.
+
+### Folders and design systems
+
+Compositions can be organized into folders and styled with design systems. Actions: `create-folder`, `rename-folder`, `delete-folder`, `move-composition-to-folder`. Design system actions: `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `set-default-design-system`, `apply-design-system`, `analyze-brand-assets`. Import actions: `import-github`, `import-from-url`, `import-document` (DOCX/PPTX/PDF).
 
 The registry in `app/remotion/registry.ts` is the in-code source of truth for what ships with the template. The SQL table stores user-created compositions and overrides. Studio state (per-composition track edits, prop overrides, composition settings) is mirrored to `localStorage` under `videos-tracks:<id>`, `videos-props:<id>`, and `videos-comp-settings:<id>`, and deep-merged back onto the registry defaults on load.