@agent-native/core 0.7.13 → 0.7.14

package/docs/content/template-clips.md

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

package/docs/content/template-content.md

@@ -1,19 +1,43 @@
 ---
-title: "Content Template"
-description: "A Notion-style document editor with an AI agent that can read, write, organize, and publish your pages."
+title: "Content"
+description: "A Notion-style document editor with an AI agent that can read, write, reorganize, and publish your pages — all in plain English."
 ---
 
-# Content Template
+# Content
 
-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.
+A Notion-style document workspace where the agent can read, write, reorganize, and publish pages for you. Open a doc, ask "rewrite this paragraph to be more concise" or "create a page called Q4 Planning with sub-pages for Goals, Metrics, and Risks" — same result whether you do it yourself or ask.
 
-## Overview {#overview}
+When you open the app, you'll see a sidebar tree of pages on the left, the editor in the middle, and the agent in the sidebar on the right. The agent always knows which page you're viewing and what text you have selected.
 
-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.
+## What you can do with it
 
-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.
+- **Write rich text** with headings, lists, tables, code blocks, images, and links. Slash commands (`/`) insert blocks; selecting text pops up a formatting toolbar.
+- **Organize pages in a tree** — nest infinitely, drag to reorder, favorite pages you use often.
+- **Search across everything** with full-text search across titles and content.
+- **Sync with Notion.** Link a local doc to a Notion page and pull or push content in either direction. Comments sync both ways too.
+- **Collaborate in real time.** Multiple people (and the agent) can edit the same doc at the same time.
+- **Share docs** with teammates or make them public — private by default, with viewer / editor / admin roles.
+- **Ask the agent for anything**: "Rewrite this paragraph." "Add a TL;DR at the top." "Find all my meeting notes from last week." "Make this tone more formal."
 
-## Quick start {#quick-start}
+## Getting started
+
+Live demo: [content.agent-native.com](https://content.agent-native.com).
+
+When you open the app, click **+ New page** in the sidebar, give it a title, and start writing. To use the agent, type in the sidebar:
+
+- "Create a page called Onboarding and add three sub-pages under it."
+- "Rewrite this paragraph to be more concise." (with a page open)
+- "Add a section about pricing with three bullet points."
+- "Summarize this doc into a TL;DR at the top."
+- "Pull the latest from Notion." (after linking a Notion page)
+
+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.
+
+## For developers
+
+The rest of this doc is for anyone forking the Content template or extending it.
+
+### Quick start
 
 Scaffold a new workspace with the Content template:
 
@@ -26,9 +50,7 @@ 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}
+### Key features (technical) {#key-features}
 
 ### Hierarchical pages
 
@@ -92,27 +114,15 @@ See the `sharing` skill.
 
 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}
+### 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}
+### Data model
 
 Four core tables, all defined in `server/db/schema.ts`:
 
@@ -126,7 +136,7 @@ Content is stored as markdown. The editor converts to and from the Tiptap JSON m
 
 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}
+### Customizing it
 
 The four places to look when changing behavior:
 

package/docs/content/template-dispatch.md

@@ -11,7 +11,7 @@ If you're running an [multi-app workspace](/docs/multi-app-workspace) with many
 
 ## 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.
+- **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. See [Messaging](/docs/messaging) for how to wire Slack, email, and Telegram into your workspace.
 - **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.
@@ -52,6 +52,7 @@ Dispatch is a full cloneable SaaS like any other template — see [Cloneable Saa
 
 ## What's next
 
+- [**Messaging**](/docs/messaging) — connecting Slack, email, and Telegram so you can talk to your agent from anywhere
 - [**Multi-App Workspace**](/docs/multi-app-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

package/docs/content/template-forms.md

@@ -5,24 +5,26 @@ description: "Agent-native form builder — create, edit, and analyze forms thro
 
 # 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.
+A form builder where the form builder _is_ the agent. Drag fields around in the editor, or just say "add a 'how did you hear about us' dropdown with five options and make it required" — same result, same underlying data. Think Typeform, but you can build, edit, and analyze forms by talking to the agent.
 
-Think Typeform, but the form builder _is_ the agent.
+When you open the app, you'll see a list of your forms on the left and the editor in the middle. Open a form and you can click any field to fine-tune it, or ask the agent to make changes for you.
 
-## What it does {#what-it-does}
+## What you can do with it
 
-- **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.
+- **Build forms conversationally.** "Create a contact form," "add an NPS score question," "make the email field required." The agent updates the schema and 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."
+- **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 plus 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.
+- **Publish anywhere.** Public share link, embed snippet, branded thank-you page, webhook on submit.
 
-## Why it's interesting {#why}
+## Why it's interesting
 
-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.
+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}
+## For developers
+
+### Scaffolding
 
 ```bash
 pnpm dlx @agent-native/core create my-forms --template forms --standalone
@@ -34,7 +36,7 @@ For a workspace with forms alongside other apps:
 pnpm dlx @agent-native/core create my-platform  # pick Forms + other templates
 ```
 
-## Customize it {#customize}
+### Customize it
 
 Ask the agent:
 

package/docs/content/template-slides.md

@@ -1,25 +1,51 @@
 ---
-title: "Slides Template"
-description: "Agent-native presentation editor — generate decks from a prompt, edit visually, and present in full-screen."
+title: "Slides"
+description: "Generate decks from a prompt, edit visually, and present full-screen. An open-source replacement for Google Slides, Pitch, and PowerPoint."
 ---
 
-# Slides Template
+# Slides
 
-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.
+Generate full presentation decks from a prompt, edit slides visually, and present full-screen. Ask the agent for "a 10-slide pitch deck for a coffee subscription service" and watch it stream slide-by-slide into the editor in seconds. An open-source replacement for Google Slides, Pitch, and PowerPoint.
 
-## Overview {#overview}
+When you open the app, you'll see your deck list. Click into a deck and you get a slide editor in the middle, a sidebar of slides on the left, and the agent on the right.
 
-The Slides template is a full presentation studio:
+## What you can do with it
 
-- 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.
+- **Generate decks from a prompt.** "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
+- **Edit slides visually** — double-click text to edit, click a block for the bubble menu, use `/` for the slash menu to insert blocks.
+- **Generate images with AI.** Hero images, product mockups, illustrations — generated with Gemini, multiple variations per request.
+- **Search stock photos and company logos.** "Find the logo for stripe.com and add it to slide 2."
+- **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.
 
-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.
+## Getting started
 
-## Quick start {#quick-start}
+Live demo: [slides.agent-native.com](https://slides.agent-native.com).
+
+When you open the app:
+
+1. Click **New deck**.
+2. In the agent sidebar, ask: "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
+3. Watch slides stream in. Click any slide to edit, or keep asking the agent to refine.
+
+### Useful 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)
+
+Select text on a slide and hit Cmd+I to focus the agent with that selection — it'll act only on what you selected.
+
+## For developers
+
+The rest of this doc is for anyone forking the Slides template or extending it.
+
+### Quick start
 
 Create a new Slides app from the CLI:
 
@@ -29,11 +55,7 @@ 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}
+### Key features (technical) {#key-features}
 
 ### Prompt-to-deck generation
 
@@ -91,20 +113,10 @@ Cmd+Z and Cmd+Shift+Z work across the whole deck, with a labeled history panel (
 
 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}
+### 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:
@@ -123,7 +135,7 @@ Select text on a slide and hit Cmd+I to focus the agent with that selection pre-
 
 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}
+### Data model
 
 All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
 
@@ -169,7 +181,7 @@ 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 it
 
 The Slides template is fully forkable. Key places to look when extending it:
 

package/docs/content/template-video.md

@@ -1,19 +1,58 @@
 ---
-title: "Video Template"
-description: "A Remotion-based animation studio where compositions are React components, animations are timeline tracks, and the agent edits alongside you."
+title: "Video"
+description: "A programmatic video studio for motion graphics, product demos, and kinetic text. Generate animations from a prompt and tune them on a timeline."
 ---
 
-# Video Template
+# Video
 
-The Video template is a programmatic video studio built on [Remotion](https://remotion.dev). Compositions are React components, animations are tracks on a timeline, and renders output to MP4 or WebM. It replaces point-and-click editors like After Effects, Premiere, and Veed for the kind of motion graphics, product demos, and kinetic text videos that are a pain to keyframe by hand.
+A programmatic video studio for the kind of motion graphics, product demos, and kinetic-text videos that are a pain to keyframe by hand. Ask the agent for "a 6-second logo reveal that fades in at 2 seconds" and it builds the animation. Tune timing, easing, and camera moves on a timeline, then render to MP4 or WebM.
 
-## Overview {#overview}
+When you open the studio, you'll see a list of compositions on the home screen. Click into one and you get a player on top, a timeline at the bottom, and a properties panel on the right. The agent always knows which composition you have open.
+
+## What you can do with it
+
+- **Generate animations from a prompt.** "Add a title card that fades in at 2 seconds and holds until 5." The agent edits the composition.
+- **Tune timing on a timeline.** Drag and resize animation tracks, scrub through frames, set easing curves visually.
+- **Animate the camera.** Pan, zoom, and tilt with on-screen tools. Click the tool, drag in the preview, and a keyframe is auto-created.
+- **Built-in compositions to start from.** Twelve examples ship: kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows.
+- **Edit easing curves visually.** 30+ curves shipped — power, back, bounce, circ, elastic, expo, sine, plus spring physics.
+- **Render to MP4 or WebM** at 1x, 2x, or 3x supersampling for crisp text and vectors during camera zoom.
+
+This is more of a developer-flavored tool than other templates — compositions are React components, so power users (or the agent) can write whole new animation types from scratch. But everyday tweaks ("make the typing slower," "drop the particle count to 12") are just chat.
+
+## Getting started
+
+Live demo: [videos.agent-native.com](https://videos.agent-native.com).
+
+When you open the studio:
+
+1. Pick a composition from the home screen.
+2. Try the agent: "add a logo reveal that fades in at 2 seconds." Watch the timeline update.
+3. Drag tracks to retime, click the camera tool, scrub the player.
+
+### Useful prompts
+
+- "Add a title card that fades in at 2 seconds and holds until 5."
+- "Change the camera to zoom 2x on the logo between frames 60 and 90."
+- "Make the typing reveal slower — 40% longer."
+- "The particle burst is too dense. Drop the count to 12."
+- "Create a new composition called intro-loop, 1080x1080, 6 seconds."
+- "Add a click animation on the button zone and animate the cursor to it."
+- "Give this track a spring easing instead of ease-out."
+
+If you select a track in the timeline and hit Cmd+I, the agent picks up that selection — "make this one snappier" just works.
+
+## 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.
+
+### Architecture
 
 Everything you see in the studio is code. A composition is a `CompositionEntry` in `app/remotion/registry.ts` that points at a React component in `app/remotion/compositions/`. Every animation in that component reads from an `AnimationTrack` so users can drag, resize, and retime it in the timeline UI. The agent can create new compositions, add tracks, tune easing, and write whole React components that plug into the registry.
 
 The studio runs on Remotion's `<Player>` for preview and the Remotion CLI for final render. Output defaults to 1920x1080 at 30fps.
 
-## Quick start {#quick-start}
+### Quick start
 
 Create a workspace with the Video app scaffolded:
 
@@ -33,7 +72,7 @@ Open the studio in your browser and pick a composition from the home screen. Ask
 
 Live demo: [videos.agent-native.com](https://videos.agent-native.com).
 
-## Key features {#key-features}
+### Key features (technical)
 
 ### React-based compositions
 
@@ -81,25 +120,13 @@ Composition size, fps, and render quality are per-composition in the Properties
 
 User edits (track values, parameter values, prop overrides, composition settings) persist to localStorage per composition. The **Save** button in the top-right of the composition view writes the current state back to `app/remotion/registry.ts` as TypeScript — so new users and sessions pick up the changes.
 
-## Working with the agent {#working-with-the-agent}
+### Working with the agent
 
 The agent always knows which composition you have open. Navigation state (`{ view, compositionId }`) is written to the framework's `application_state` table, and the `view-screen` action returns it plus a hint pointing at `app/remotion/registry.ts`. You don't have to tell the agent which composition you're on — ask it to act on "this one" and it will.
 
-Example prompts:
-
-- "Add a title card that fades in at 2 seconds and holds until 5."
-- "Change the camera to zoom 2x on the logo between frames 60 and 90."
-- "Make the typing reveal slower — 40% longer."
-- "The particle burst is too dense. Drop the count to 12."
-- "Create a new composition called intro-loop, 1080x1080, 6 seconds."
-- "Add a click animation on the button zone and animate the cursor to it."
-- "Give this track a spring easing instead of ease-out."
-
 Under the hood the agent calls actions like `navigate`, `create-composition`, `generate-animated-component`, and edits `app/remotion/registry.ts` and `app/remotion/compositions/*.tsx` directly. Every change shows up in the timeline.
 
-If you select a track in the UI and hit Cmd+I to focus the agent, it sees which track you've selected — "make this one snappier" just works.
-
-## Data model {#data-model}
+### Data model
 
 Server-side schema is in `templates/videos/server/db/schema.ts`:
 
@@ -116,7 +143,7 @@ Core TypeScript shapes (`app/types.ts`):
 
 Compositions are private by default. Visibility can be `private`, `org`, or `public`, and share grants give `viewer`, `editor`, or `admin` roles — wired through the framework's sharing primitive.
 
-## Customizing it {#customizing-it}
+### Customizing it
 
 The template folder is `templates/videos/` (the user-facing slug is `video`, but the folder is plural).
 

package/docs/content/tools.md

@@ -0,0 +1,107 @@
+---
+title: "Tools"
+description: "Lightweight interactive apps — dashboards, widgets, calculators, monitors — that the agent creates for you instantly, without changing your app's code."
+---
+
+# Tools
+
+Tools are lightweight interactive apps that live inside your agent-native app. Think dashboards, widgets, calculators, API monitors, data lookups — anything you'd otherwise build by hand.
+
+The key difference from the rest of your app: **tools don't require code changes.** The agent creates and updates them at runtime, they're stored in the database, and they're ready to use immediately. No deploys, no builds, no pull requests.
+
+## Tools vs. editing the app {#tools-vs-code}
+
+Your agent-native app has a full codebase — React components, routes, actions, styles. When the agent edits that code, it's changing the app itself. That's powerful, but it requires a build step and a deploy.
+
+Tools are different:
+
+|                       | App code                                | Tools                                              |
+| --------------------- | --------------------------------------- | -------------------------------------------------- |
+| **Created by**        | Developer or agent editing source files | Agent or user, instantly from chat                 |
+| **Stored in**         | Git repository                          | Database                                           |
+| **Requires a build**  | Yes                                     | No                                                 |
+| **Requires a deploy** | Yes                                     | No                                                 |
+| **Scope**             | Part of the app for all users           | Private by default, shareable                      |
+| **Best for**          | Core app features                       | Personal dashboards, utilities, quick integrations |
+
+Use app code for features that are core to the product. Use tools for everything else — one-off utilities, personal dashboards, quick integrations, monitors, and things you want to spin up in seconds.
+
+## Creating a tool {#creating}
+
+### From the sidebar
+
+Click the **+** button in the Tools section of the sidebar. Describe what you want in plain language — "a dashboard that shows my open GitHub PRs" — and the agent builds it for you.
+
+### From chat
+
+Just ask: "Create a tool that monitors our API health" or "Make me a calculator for shipping costs." The agent handles the rest.
+
+### Updating a tool
+
+Ask the agent: "Update my PR dashboard to also show draft PRs" or "Add a dark mode toggle to the weather widget." The agent makes surgical edits without regenerating the whole thing.
+
+## What tools can do {#capabilities}
+
+Tools are fully capable despite being lightweight. They can:
+
+- **Call external APIs** — GitHub, Stripe, weather services, any REST API. Requests go through a secure server-side proxy that keeps your API keys safe.
+- **Call your app's actions** — anything your agent can do, a tool can trigger.
+- **Query your app's database** — read and write data directly.
+- **Store their own data** — each tool has built-in persistent storage, no setup required. Save notes, preferences, cached results — whatever the tool needs.
+- **Call any endpoint in your app** — hit custom API routes, webhooks, or internal services.
+
+All of this works out of the box. No configuration, no new files, no schema changes.
+
+## Persistent storage {#persistent-storage}
+
+Every tool has access to a built-in key-value store. Data is automatically scoped per tool and per user — your data stays yours.
+
+When you ask the agent to "add persistence" or "remember state" in a tool, it uses this built-in storage. No database tables to create, no migrations to run.
+
+## API keys and secrets {#secrets}
+
+When a tool needs an API key (for GitHub, OpenAI, a weather service, etc.), the agent will tell you what's needed and where to get it. You add the key through the Settings UI in the agent sidebar.
+
+Keys are encrypted and stored securely. Each key is restricted to specific domains — a GitHub token can only be sent to `api.github.com`, never anywhere else.
+
+## Sharing {#sharing}
+
+Tools are **private by default** — only you can see and use a tool you create.
+
+You can share tools with your team:
+
+- **Org-visible** — everyone in your organization can use it.
+- **Per-user sharing** — grant access to specific people as viewers, editors, or admins.
+
+Shared tools have their own URLs, so you can link to them directly.
+
+## Security {#security}
+
+Tools run in a secure sandbox:
+
+- **Isolated** — tools can't access your app's cookies, session, or page content.
+- **API keys stay server-side** — secrets are injected by the server, never exposed to the browser.
+- **Domain-restricted secrets** — each API key can only be sent to its approved domains.
+- **Private network protection** — tools can't reach internal/private network addresses.
+- **Authentication required** — only logged-in users can use tools.
+
+## Examples {#examples}
+
+Here are some things people build as tools:
+
+- **GitHub PR dashboard** — see open PRs, review status, and CI checks at a glance
+- **API health monitor** — check if your services are up with a single click
+- **Weather widget** — quick weather lookup for any city
+- **Stripe payment lookup** — search recent payments and refunds
+- **Database explorer** — browse and query your app's data
+- **Shipping cost calculator** — compute rates based on weight and destination
+- **Meeting notes summarizer** — paste notes, get action items
+- **Social media scheduler** — draft and schedule posts across platforms
+
+To create any of these, just describe what you want in the agent chat.
+
+## What's next
+
+- [**Actions**](/docs/actions) — the operations that tools (and the agent) can call
+- [**Workspace**](/docs/workspace) — the broader workspace system tools live alongside
+- [**Security**](/docs/security) — the framework's data scoping and access control