@agent-native/core 0.7.13 → 0.7.15

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

package/docs/content/what-is-agent-native.md

@@ -1,108 +1,73 @@
 ---
 title: "What Is Agent-Native?"
-description: "The ladder from a naked llm() call to a full agent-native app — and why every agent needs a UI (and every app benefits from an agent)."
+description: "Why most AI apps feel half-built, what makes an app truly agent-native, and what your day-to-day experience looks like as a result."
 ---
 
 # What Is Agent-Native?
 
 Agent-native is a way of building software where the AI agent and the UI are **equal partners**. Everything the agent can do, the UI can do. Everything the UI can do, the agent can do. They share the same database, the same state, and they stay in sync.
 
-If you only remember one thing from this page, remember this: most AI apps today stop at the first rung of the ladder, and it's the biggest mistake in the space right now.
+If you only remember one thing from this page, remember this: most AI apps today stop one step short of being useful, and that gap is the biggest mistake in the space right now.
 
-## The ladder {#the-ladder}
+## What it looks like as a user {#what-it-looks-like}
 
-Here's the progression. Most teams stop at rung 1. Agent-native is rung 3.
+Picture your inbox, calendar, or analytics dashboard. Now picture an agent panel docked on the right side of that app. You can:
 
-### Rung 1 — a single LLM call (the anti-pattern) {#rung-one}
-
-```ts
-const output = await llm(prompt);
-```
-
-A text box sends a prompt, you get a string back, maybe you parse it, and you render it. There's no way for the user to course-correct, no way for the LLM to take action, no way to inspect what happened. Non-deterministic output → deterministic pipeline. It breaks the moment reality gets messy.
+- **Click anything you'd normally click.** All the buttons, lists, dashboards, keyboard shortcuts — they all still work. This is a real app, not a chat window pretending to be one.
+- **Or just ask.** Type "reply to the email from Sara saying I'll be there by 3" into the agent. It opens the right thread, drafts the reply, and shows it to you for approval — exactly as if you'd done it by hand.
+- **See what it sees.** Open an email, and the agent knows which one. Select a chart, and the agent knows which chart. Highlight a paragraph and hit Cmd+I, and the agent acts on just that paragraph.
+- **Watch it work.** As the agent does things — opens views, edits drafts, runs reports — the UI updates in real time. You can stop it, redirect it, or take over with the mouse at any moment.
+- **Steer it like a teammate.** Give feedback, queue another task, edit its instructions, audit what it did yesterday. It remembers, and it gets better at your workflows over time.
 
-You see this everywhere: "AI features" bolted onto SaaS that are basically `fetch('/summarize')` with a spinner. That's not AI product; that's a toy.
-
-### Rung 2 — tools and a loop {#rung-two}
-
-```ts
-const loop = query({ prompt, tools });
-for await (const msg of loop) {
-  if (msg.type === "tool_use") {
-    // run the tool, feed the result back into the loop
-  }
-  if (msg.type === "result") {
-    output = msg.text;
-  }
-}
-```
+That's the experience agent-native is designed for. Now here's why most products don't get there.
 
-Now the LLM can _do things_. You give it tools (`draftEmail`, `searchEmails`, `queryData`) and run a loop: LLM requests a tool → your code runs it → result goes back → loop continues until the task is done. This is what Claude Code, Codex, and the Anthropic/OpenAI agent SDKs all do under the hood.
+## Why most "AI apps" fall short {#the-ladder}
 
-This is a real step up. But on its own it still assumes the agent is correct. When it's not, the user has no steering wheel.
+There's a progression most teams climb, and most stop one rung too early.
 
-So the next move is obvious: stream the agent's work into a chat UI where the user can watch, interrupt, give feedback, queue the next message. That's the state of the art today — and it's still not enough for a real product.
+### Rung 1 — a single LLM call (the anti-pattern) {#rung-one}
 
-### Rung 3 — `<Agent />` + actions + workspace {#rung-three}
+A text box sends a prompt, the AI returns a string, and you display it. Maybe with a spinner. There's no way for the user to course-correct, no way for the AI to take action, no way to see what happened or why.
 
-```tsx
-// actions/reply-to-email.ts
-import { defineAction } from "@agent-native/core";
-import { z } from "zod";
+You see this everywhere: "AI features" that are basically a "Summarize" button bolted onto a SaaS product. They look impressive in demos and break the moment reality gets messy. That's not a product; that's a toy.
 
-export default defineAction({
-  description: "Reply to an email thread",
-  schema: z.object({
-    emailId: z.string(),
-    body: z.string(),
-  }),
-  run: async ({ emailId, body }) => {
-    await db.replies.insert({ emailId, body });
-  },
-});
-```
+### Rung 2 — a chat with tools {#rung-two}
 
-```tsx
-// Anywhere in your React app
-import { AgentSidebar } from "@agent-native/core/client";
+Now the AI can _do things_. It has tools — "draft email," "search contacts," "run query" — and a chat interface where it works in front of you, showing tool calls and results as it goes. This is what Claude, ChatGPT, and Cursor look like under the hood.
 
-<AgentSidebar />;
-```
+This is a real step up. But on its own, it's still a chat window. There's no proper UI. No dashboards, no lists, no forms, no keyboard shortcuts, no team collaboration. If the AI gets confused, you're stuck retyping rather than just clicking the right button. Non-developers struggle to get real work done in this format.
 
-```tsx
-// The same action, typesafe, from a button
-const { mutate } = useActionMutation("replyToEmail");
+### Rung 3 — agent + UI as equal partners {#rung-three}
 
-<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
-  Send Reply
-</Button>;
-```
+This is agent-native. You add a real, full-featured app around the agent — and crucially, every action the agent can take is also a button in the UI, and every button the user clicks runs the same logic the agent uses. One implementation, two ways in.
 
-One action. The agent calls it as a tool. The UI calls it as an HTTP endpoint. External agents call it over [A2A](/docs/a2a-protocol). Claude Desktop calls it as an [MCP server](/docs/mcp-protocol). Four surfaces, one implementation.
+Three things change when you reach rung 3:
 
-And you didn't just add buttons to a chatbot — you added an agent to an app. The user has a real UI with dashboards, lists, forms, and keyboard shortcuts. The agent has real tools, real memory, and real context. Both write to the same database; both see the same state.
+- **You stopped adding buttons to a chatbot. You added an agent to an app.** That's a much higher-quality product on both sides.
+- **The agent has real context.** It sees what you're looking at, what you've selected, what you just did. It writes to the same database the UI reads from, so its work shows up immediately.
+- **External agents can use it too.** Other agent-native apps can call this one's actions over the [A2A protocol](/docs/a2a-protocol). Tools like Claude Desktop can drive it as an [MCP server](/docs/mcp-protocol). One app, many entry points.
 
 That's rung 3. That's agent-native.
 
 ## Why every agent needs a UI {#why-every-agent-needs-a-ui}
 
-The hot take floating around right now is "apps are dead, agents will replace UIs, everyone will just text an agent in Telegram." That's wrong.
+The hot take in 2026 is "apps are dead, agents will replace UIs, everyone will just text an agent in Telegram." That's wrong.
 
-Every agent eventually needs a UI. Even if the agent does all the _work_, humans still need to:
+Even when the agent does all the heavy lifting, humans still need to:
 
-- **See what it's doing** — progress, tool calls, intermediate output
+- **See what it's doing** — progress, intermediate output, what it touched
 - **Steer it** — give feedback, interrupt, queue the next task
 - **Manage it** — edit its instructions, skills, memory, scheduled jobs, connected accounts
-- **Inspect its work** — review drafts, audit trails, rollbacks
-- **Share its output** — dashboards, reports, forms, links
+- **Inspect its work** — review drafts, audit history, roll back mistakes
+- **Share its output** — dashboards, reports, forms, links to send to teammates
 
-At minimum, "a UI for the agent" is an observability + management interface. At maximum, it's a full SaaS app with an agent embedded in it. Both ends of that spectrum are agent-native — see [Pure-Agent Apps](/docs/pure-agent-apps) for the minimal end and [Cloneable SaaS](/docs/cloneable-saas) for the maximal end.
+At minimum, "a UI for the agent" is an observability and management dashboard. At maximum, it's a full SaaS app with the agent embedded as a co-pilot. Both ends count as agent-native — see [Pure-Agent Apps](/docs/pure-agent-apps) for the minimal end and [Cloneable SaaS](/docs/cloneable-saas) for the maximal end.
 
 ## Why every app benefits from an agent {#why-every-app-benefits-from-an-agent}
 
-The flip side is equally important. Existing SaaS products hit a wall: 80% of what you need, and 20% you can't change. Bolting a sidebar chat onto a SaaS app rarely works because the chat can't actually _do_ the things the UI can.
+The flip side is just as important. Existing SaaS products keep hitting the same wall: 80% of what you need works great, and 20% you just can't change. Adding a chat sidebar rarely fixes that — the chat usually can't actually _do_ the things the UI can.
 
-Agent-native flips that. Because every action in the app is defined once and exposed as both a UI handler and an agent tool, the agent can do everything the buttons can — and a lot more — without a separate "AI world" to maintain. Natural language becomes a first-class input alongside clicks.
+Agent-native flips that. Because every action in the app is defined once and exposed as both a button and an agent tool, the agent can do everything the buttons can — and more — without a separate "AI world" to maintain. Natural language becomes a first-class input alongside clicks.
 
 The argument isn't "agents replace UI." It's "**agents belong inside applications, with a UI on top, as equal partners**." Neither can stand alone.
 
@@ -114,22 +79,22 @@ This is the defining principle.
 >
 > **From the agent** — natural language, other agents via A2A, Slack, Telegram. The agent writes to the database; the UI updates automatically.
 
-When the agent creates a draft email, it appears in the UI. When the user clicks "Send," the agent knows it was sent. There's no separate "agent world" and "UI world" — it's one system. See [Key Concepts](/docs/key-concepts) for the architecture that makes this work.
+When the agent creates a draft email, it appears in the UI. When you click "Send," the agent knows it was sent. There's no separate "agent world" and "UI world" — it's one system. See [Key Concepts](/docs/key-concepts) for the architecture that makes this work.
 
-## Customization that's usually reserved for Claude Code {#workspace-customization}
+## Customization usually reserved for power tools {#workspace-customization}
 
-The reason tools like Claude Code and Codex are so powerful isn't the model — it's the **customization layer**: per-project instructions, skills, memory files, sub-agents, connected MCP servers. You can shape the agent to your codebase, your preferences, your team.
+The reason tools like Claude Code feel so powerful isn't the model — it's the **customization layer**: per-project instructions, skills, memory, sub-agents, connected services. You can shape the agent to your codebase, your preferences, your team.
 
-Agent-native ships the same customization layer as a first-class part of every app — the **workspace**. Each app includes:
+Agent-native gives every user that same customization layer — without ever leaving the app. Each app comes with a personal **workspace** where you (or anyone on your team) can:
 
-- `AGENTS.md` — team-wide rules (shared)
-- `learnings.md` — per-user memory the agent writes to automatically (personal)
-- `skills/` — reusable how-to guides (`/slash` commands)
-- `agents/` — custom sub-agent profiles (invoked with `@mentions`)
-- `jobs/` — scheduled tasks that run on a cron
-- MCP servers — local _or_ remote, per-user or per-org
+- Edit team-wide rules everyone's agent reads
+- Let the agent remember preferences automatically as you correct it
+- Write reusable how-to guides as `/slash` commands
+- Keep custom sub-agents for specific tasks (invoked with `@mentions`)
+- Schedule jobs to run on a cron (e.g. "every Monday morning, summarize last week")
+- Connect external services (Gmail, Stripe, Slack, internal APIs) via per-user MCP servers
 
-The twist: it's **SQL-backed, not filesystem-backed.** There's no dev-box to spin up, no container per user, no files to sync. Every user gets their own full workspace — personal memory, personal MCP servers, personal skills — for essentially free, because it's all rows in a database. That makes this model viable for real SaaS: multi-tenant, deployable to any serverless or edge host, with Claude-Code-level flexibility per user.
+The twist: it's all stored in the database, not the filesystem. There's no dev environment to spin up, no container per user. Every user gets their own full workspace — personal memory, personal connections, personal skills — for essentially free, because it's all rows in a table. That's what makes Claude-Code-level flexibility viable inside a real multi-tenant SaaS product.
 
 See [Workspace](/docs/workspace) for the full concept.
 
@@ -142,39 +107,22 @@ See [Workspace](/docs/workspace) for the full concept.
 | **Claude Code / Codex for SaaS**       | Great for devs on their own machines. Doesn't translate to multi-tenant SaaS — one codebase per user on a dev-box doesn't scale.       |
 | **Agent-native apps**                  | The agent is a first-class citizen. It shares the same database, the same state, and can do everything the UI can do — and vice versa. |
 
-## What is agent-native development? {#what-is-agent-native-development}
-
-Agent-native development means building with agents first. Projects are structured so any AI coding tool — Claude Code, Codex, Cursor, Windsurf, Builder.io — reads the same instructions and follows the same patterns.
-
-The payoff: the agent tends to do _better_ than a human developer because you can encode rules like "when you add a feature, also add a skill for it" — the kind of thing humans skip when they're tired or rushed.
-
-## Agents as first-class developers {#agents-as-first-class-developers}
-
-In an agent-native project:
-
-- **AGENTS.md** gives every AI coding tool the same instructions — Claude Code, Cursor, Windsurf, and others all read the same file
-- **Skills** teach the agent patterns for specific tasks — adding features, storing data, wiring real-time sync
-- **Agent PR reviewers** validate the four-area checklist, that skills were updated, and that code matches conventions
-- **Auto-maintained docs and tests** — agents are instructed to keep docs current and tests passing
-
-This is the shift from desktop-first to mobile-first applied to development. Mobile-first didn't mean "no desktop" — it meant designing for mobile constraints first. Agent-native development means designing for agent workflows first, then ensuring humans work effectively too.
-
 ## Whole-team development {#whole-team-development}
 
-Agent-native development isn't just for developers:
+Agent-native isn't just for developers. Because the agent can edit the app's own code, evolving an app stops being a developer-only activity:
 
-- **Designers** update designs directly in the code through the agent
-- **Product managers** update functionalities and requirements
-- **QA** tests and prompts for fixes
+- **Designers** update designs directly in the running app through the agent
+- **Product managers** add functionality and update flows by describing them
+- **QA** tests the app and asks the agent to fix what's broken
 - **Anyone on the team** contributes through natural language
 
-The vision: reduce handoffs, enable one-person-to-full-team productivity.
+The vision: fewer handoffs, one person doing the work of a small team.
 
 ## Fork and customize {#fork-and-customize}
 
 Agent-native apps follow a fork-and-customize model. You start from a **cloneable SaaS** template — Mail, Calendar, Analytics, Slides, Clips, Forms, Dispatch — and make it yours:
 
-1. Pick a template on [agent-native.com](/templates)
+1. Pick a template on [agent-native.com/templates](/templates)
 2. Use it immediately as a hosted app (e.g. mail.agent-native.com)
 3. Fork it when you want to customize — "connect our Stripe account," "add a cohort chart"
 4. The agent modifies the code to match your needs
@@ -184,14 +132,50 @@ Because it's _your_ app, not shared infrastructure, the agent can safely evolve
 
 ## Composable agents {#composable-agents}
 
-Agent-native apps talk to each other over the [A2A protocol](/docs/a2a-protocol). From the mail app, you can tag the analytics agent to query data and include the results in a draft email. Agents discover what other agents are available, call them over the protocol, and show results in the UI.
+Agent-native apps can talk to each other. From inside the mail app, you can tag the analytics agent to query data and include the result in a draft email. The agents discover what other agents are available, hand off work between each other, and surface the results in the UI you're already in.
+
+This is powered by [A2A](/docs/a2a-protocol) and [MCP](/docs/mcp-protocol) under the hood — same definition, multiple surfaces — but as a user, all you have to know is "I can ask any of my apps for help with anything any of them can do."
+
+## What does this look like in code? {#what-does-it-look-like-in-code}
+
+If you're building or extending an agent-native app, here's the central pattern: every operation in the app is an **action** — defined once, available to both the agent and the UI.
+
+```ts
+// actions/reply-to-email.ts
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Reply to an email thread",
+  schema: z.object({ emailId: z.string(), body: z.string() }),
+  run: async ({ emailId, body }) => {
+    await db.replies.insert({ emailId, body });
+  },
+});
+```
+
+```tsx
+// In any React component — same action, called from a button
+const { mutate } = useActionMutation("replyToEmail");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+```tsx
+// And the agent panel mounted anywhere in your app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
 
-Every action you define is also a tool exposed over A2A _and_ as an MCP server, so external tools like Claude Desktop can drive your app directly. Same definition, four surfaces.
+One action, four surfaces: the agent calls it as a tool, the UI calls it as a typesafe mutation, external agents reach it over [A2A](/docs/a2a-protocol), and tools like Claude Desktop talk to it as an [MCP server](/docs/mcp-protocol). See [Actions](/docs/actions) for the full reference.
 
-## What's next
+## What's next {#whats-next}
 
+- [**Getting Started**](/docs) — pick a template and run it
 - [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, context awareness, portability
 - [**Cloneable SaaS**](/docs/cloneable-saas) — templates as complete products you own
 - [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP)
 - [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>` into any React app
-- [**Getting Started**](/docs) — scaffold your first app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.7.13",
+  "version": "0.7.15",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "./server/ssr-handler": "./dist/server/ssr-handler.js",
     "./server/agent-discovery": "./dist/server/agent-discovery.js",
     "./server/request-context": "./dist/server/request-context.js",
+    "./server/design-token-utils": "./dist/server/design-token-utils.js",
     "./db": "./dist/db/index.js",
     "./db/schema": "./dist/db/schema.js",
     "./db/drizzle-config": "./dist/db/drizzle-config.js",
@@ -40,6 +41,7 @@
     "./credentials": "./dist/credentials/index.js",
     "./event-bus": "./dist/event-bus/index.js",
     "./fetch-tool": "./dist/tools/fetch-tool.js",
+    "./tools/url-safety": "./dist/tools/url-safety.js",
     "./file-upload": "./dist/file-upload/index.js",
     "./resources": "./dist/resources/index.js",
     "./resources/store": "./dist/resources/store.js",
@@ -54,6 +56,7 @@
     "./sharing/actions/list-resource-shares": "./dist/sharing/actions/list-resource-shares.js",
     "./sharing/actions/set-resource-visibility": "./dist/sharing/actions/set-resource-visibility.js",
     "./client/sharing": "./dist/client/sharing/index.js",
+    "./client/tools": "./dist/client/tools/index.js",
     "./client/transcription/use-live-transcription": "./dist/client/transcription/use-live-transcription.js",
     "./client/transcription/BuilderTranscriptionCta": "./dist/client/transcription/BuilderTranscriptionCta.js",
     "./transcription/builder": "./dist/transcription/builder-transcription.js",
@@ -123,6 +126,7 @@
     "drizzle-orm": "^0.45.2",
     "h3": "^2.0.1-rc.20",
     "isbot": "^5",
+    "jiti": "^2.6.1",
     "jose": "^6.2.2",
     "minimatch": "^10.0.0",
     "nanoid": "^5.1.9",

package/src/templates/default/.agents/skills/delegate-to-agent/SKILL.md

@@ -70,6 +70,59 @@ sendToAgentChat({
 });
 ```
 
+## Capture user input first when generating from a prompt
+
+Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+
+**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+
+```tsx
+<Button
+  onClick={() =>
+    sendToAgentChat({ message: "make a design", submit: true })
+  }
+>
+  New Design
+</Button>
+```
+
+**Good** — Popover anchored to the button captures the prompt, then submits it:
+
+```tsx
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>New Design</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-96">
+    <Textarea
+      autoFocus
+      value={prompt}
+      onChange={(e) => setPrompt(e.target.value)}
+      placeholder="What do you want to design?"
+    />
+    <Button
+      onClick={() => {
+        sendToAgentChat({ message: prompt, submit: true });
+        setOpen(false);
+        setPrompt("");
+      }}
+    >
+      Create
+    </Button>
+  </PopoverContent>
+</Popover>
+```
+
+**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
+
+**Auto-submit without input is fine when intent is unambiguous:**
+
+- "Try to fix" on a tool error — submits the error details with a clear fix instruction
+- "Retry the last operation" after a transient failure
+- Single-purpose buttons where there is nothing meaningful for the user to add
+
+If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+
 ## Don't
 
 - Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
@@ -77,6 +130,7 @@ sendToAgentChat({
 - Don't make direct API calls to any LLM provider
 - Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
 - Don't build "AI features" that bypass the agent chat
+- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
 
 ## Exception