@agent-native/core 0.7.4 → 0.7.7

package/docs/content/template-starter.md

@@ -0,0 +1,68 @@
+---
+title: "Starter Template"
+description: "The minimal agent-native scaffold — agent chat, actions, application state, polling, auth — wired up, with no domain code. Build from scratch."
+---
+
+# Starter
+
+Starter is the minimum viable agent-native app. You get the six-rules architecture, the agent sidebar, the workspace tab, polling sync, auth, and exactly one example action. Nothing else. Build from there.
+
+Pick Starter when you're not sure which domain template fits, or when you want to learn the framework by doing — there's almost nothing to delete.
+
+## What's in it {#whats-in-it}
+
+- **Agent sidebar** (`<AgentSidebar>`) wired into `app/root.tsx`. Chat, CLI, workspace tabs all present.
+- **Agent chat plugin** pre-configured so the chat actually talks to Claude (once `ANTHROPIC_API_KEY` is set).
+- **Auth** via Better Auth — login, signup, sessions, organizations. Local-mode fallback (`local@localhost`) for first-run dev.
+- **Actions directory** with one example (`actions/hello-world.ts`) and the `view-screen` / `navigate` standard actions wired up.
+- **Drizzle schema** with the framework's core tables (application_state, settings, oauth_tokens, sessions, resources).
+- **Polling sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to the database.
+- **AGENTS.md** with the framework-wide rules the agent reads on every turn.
+- **One route** at `/` that says hi and renders the sidebar toggle. That's it.
+
+## What's _not_ in it {#not-in-it}
+
+- No domain tables (no emails, no events, no forms)
+- No fancy UI — no dashboards, no lists, no charts
+- No template-specific actions beyond the stubs
+- No integrations (Slack, SendGrid, etc.)
+
+That's the point. Ship whatever belongs to _your_ app, not someone else's.
+
+## When to pick it {#when-to-pick}
+
+- **Building a pure-agent app** — the kind where the UI is mostly "let me see what the agent did." See [Pure-Agent Apps](/docs/pure-agent-apps).
+- **Learning the framework** — this is the smallest surface to wrap your head around.
+- **An internal tool** with a unique domain that doesn't match any of the other templates.
+- **A prototype** — ship the agent now, add real UI later.
+
+Pick a domain template ([Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics), etc.) when there's an existing product shape that fits.
+
+## Scaffolding {#scaffolding}
+
+```bash
+pnpm dlx @agent-native/core create my-app --template starter --standalone
+```
+
+Or, in a workspace:
+
+```bash
+pnpm dlx @agent-native/core create my-platform  # pick "Starter" (pre-selected by default) plus any others
+```
+
+## First edits {#first-edits}
+
+After scaffolding:
+
+1. Ask the agent: "Add a data model for `notes` — a note has an id, title, body, owner. Render a list of notes at `/notes` and let the user create one."
+2. The agent adds the Drizzle schema, the `create-note` and `list-notes` actions, and the new route. You watch it happen.
+3. `pnpm dev`, navigate to `/notes`, add a note through the UI. Ask the agent "draft a note summarizing yesterday's standup." Watch it use your new action.
+
+That's the loop.
+
+## What's next
+
+- [**Getting Started**](/docs) — the broader CLI + workspace flow
+- [**Key Concepts**](/docs/key-concepts) — the six rules and what you get for free
+- [**Actions**](/docs/actions) — the action system you'll add to
+- [**Adding a Feature**](/docs/key-concepts#four-area-checklist) — the four-area checklist every new feature should update

package/docs/content/template-video.md

@@ -0,0 +1,162 @@
+---
+title: "Video Template"
+description: "A Remotion-based animation studio where compositions are React components, animations are timeline tracks, and the agent edits alongside you."
+---
+
+# Video Template
+
+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.
+
+## Overview {#overview}
+
+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}
+
+Create a workspace with the Video app scaffolded:
+
+```bash
+npx @agent-native/core create my-video-app
+```
+
+During the picker, select **Video**. Then:
+
+```bash
+cd my-video-app
+pnpm install
+pnpm dev
+```
+
+Open the studio in your browser and pick a composition from the home screen. Ask the agent something like "add a logo reveal that fades in at 2 seconds" and it will edit the registry and the composition for you.
+
+Live demo: [videos.agent-native.com](https://videos.agent-native.com).
+
+## Key features {#key-features}
+
+### React-based compositions
+
+Every video is a React component built on Remotion primitives (`AbsoluteFill`, `useCurrentFrame`, `useVideoConfig`). Twelve example compositions ship by default — kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows. Add new ones by dropping a `.tsx` file in `app/remotion/compositions/` and registering it in `app/remotion/registry.ts`.
+
+### Timeline tracks
+
+Animations are tracks, not hardcoded frame checks. A track has `startFrame`, `endFrame`, `easing`, and a list of `animatedProps` (`opacity`, `translateY`, `scale`, rotation, colors, etc.). Three track shapes:
+
+- **Duration tracks** — bars you can drag and resize in the timeline.
+- **Keyframe tracks** — diamond markers at specific frames for instant state changes (`startFrame === endFrame`).
+- **Expression tracks** — programmatic animations (typing reveals, particle bursts) flagged with `programmatic: true` and shown with a purple `fx` badge.
+
+Helper utilities in `app/remotion/trackAnimation.ts` (`findTrack`, `trackProgress`, `getPropValue`) wire a track's values into a component's render.
+
+### Easing curves
+
+30+ easing curves ship in `app/types.ts` — linear, power1-4 in/out/inOut, back, bounce, circ, elastic, expo, sine, and Remotion's `spring`. The Properties panel shows a visual preview of the curve shape for each one.
+
+### Camera controls
+
+Each composition has a dedicated `camera` track with six animatable properties: `translateX`, `translateY`, `scale`, `rotateX`, `rotateY`, `perspective`. The camera toolbar above the player has pan, zoom, and tilt tools — click a tool, drag on the preview, and a keyframe is auto-created at the current frame. `CameraHost` (in `app/remotion/CameraHost.tsx`) applies the chained CSS 3D transform to everything inside.
+
+### Multi-keyframe editing
+
+Every animated property supports an optional `keyframes` array. Interpolation is linear between keyframes, with hold-at-first and hold-at-last at the edges. In the timeline you can box-select keyframes, shift-click to add or remove, and drag groups while keeping relative timing.
+
+### Adjustable parameters
+
+Programmatic animations expose internal magic numbers as user-editable `parameters` — character width, drift distance, particle count, stagger delay. Inputs appear in the Properties panel with min/max/step bounds and save to localStorage automatically.
+
+### Interactive cursor system
+
+The `cursor` track drives a visible cursor that moves across the composition. Hover zones on interactive elements (buttons, tabs, inputs, cards) change the cursor appearance — arrow, pointer, or I-beam. See `app/remotion/hooks/useInteractiveComponent.ts` and `app/remotion/ui-components/InteractiveCard.tsx`.
+
+### View range and repeat playback
+
+The timeline has a range navigator at the bottom (AE-style triangular handles). Drag to zoom and pan the visible time window. Playback in the player is constrained to that range, with a repeat toggle that loops inside it.
+
+### Render output
+
+Composition size, fps, and render quality are per-composition in the Properties panel. Render quality is supersampling — 1x, 2x, or 3x internal resolution to keep text and vectors crisp during camera zoom. Final render happens via the Remotion CLI to MP4 or WebM.
+
+### Composition persistence
+
+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}
+
+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}
+
+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()`.
+
+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.
+
+Core TypeScript shapes (`app/types.ts`):
+
+- `AnimationTrack` — `id`, `label`, `startFrame`, `endFrame`, `easing`, `animatedProps[]`.
+- `AnimatedProp` — `property`, `from`, `to`, `unit`, plus optional `keyframes`, `programmatic`, `description`, `codeSnippet`, `parameters`, `parameterValues`.
+- `CompositionEntry` — `id`, `title`, `description`, `component`, `durationInFrames`, `fps`, `width`, `height`, `defaultProps`, `tracks`.
+
+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}
+
+The template folder is `templates/videos/` (the user-facing slug is `video`, but the folder is plural).
+
+**Actions** — `templates/videos/actions/`
+
+- `view-screen.ts` — returns current navigation state for the agent.
+- `navigate.ts` — navigate to a composition (`--compositionId <id>`) or the home view (`--view home`).
+- `create-composition.ts` — scaffold a new composition with the standard camera and cursor tracks.
+- `generate-animated-component.ts` — generate a new animated component file with boilerplate.
+- `validate-compositions.ts` — check all registered compositions for structural problems.
+- `list-compositions.ts`, `get-composition.ts`, `update-composition.ts`, `delete-composition.ts`, `save-composition.ts` — CRUD over the SQL table.
+
+**Routes** — `templates/videos/app/routes/`
+
+- `_index.tsx` — studio home; renders the shell and composition list.
+- `c.$compositionId.tsx` — composition editor (timeline, player, properties panel).
+- `components.tsx` — component library browser.
+- `team.tsx` — team management.
+
+**Remotion internals** — `templates/videos/app/remotion/`
+
+- `registry.ts` — the authoritative composition list.
+- `compositions/` — one `.tsx` per composition, plus an `index.ts` barrel.
+- `trackAnimation.ts` — `trackProgress`, `getPropValue`, `findTrack`, `getPropValueKeyframed`.
+- `CameraHost.tsx` — wraps composition content with the camera transform.
+- `hooks/`, `ui-components/`, `components/` — interactive element helpers, cursor rendering, animated element wrappers.
+
+**Studio UI** — `templates/videos/app/components/`
+
+- `Timeline.tsx` — the fully-controlled timeline (`viewStart` / `viewEnd` own no state internally).
+- `VideoPlayer.tsx` — Remotion `<Player>` wrapper with range-constrained playback.
+- `TrackPropertiesPanel.tsx`, `CompSettingsEditor.tsx`, `PropsEditor.tsx` — the right-side panels.
+- `CameraToolbar.tsx`, `CameraControls.tsx` — camera tools and numeric controls.
+
+**Agent instructions** — `templates/videos/AGENTS.md` is the long-form guide the agent reads. It covers the animation-as-track rule, camera system, cursor system, CSS filter units, interactive component registration, UI spacing, and checklists for creating or editing compositions.
+
+**Skills** — `templates/videos/.agents/skills/`
+
+- `composition-management/SKILL.md` — how to create and register compositions.
+- `animation-tracks/SKILL.md` — how to edit tracks and animated props.
+- Plus the standard framework skills: `actions`, `self-modifying-code`, `delegate-to-agent`, `storing-data`, `security`, `frontend-design`, `create-skill`, `capture-learnings`.
+
+To add a new composition, follow the checklist in `AGENTS.md`: create the component, declare `FALLBACK_TRACKS`, use `findTrack` / `trackProgress` / `getPropValue` (never hardcode frames), export from `compositions/index.ts`, add a `CompositionEntry` to the registry, and run `pnpm typecheck`.

package/docs/content/voice-input.md

@@ -0,0 +1,59 @@
+---
+title: "Voice Input"
+description: "Voice dictation in the agent chat composer — OpenAI Whisper with a browser Web Speech fallback."
+---
+
+# Voice Input
+
+Every agent-native app has a microphone in the chat composer. Click it, talk, and your words get transcribed into the prompt. Useful on mobile, useful for long prompts, useful when your hands are on something else.
+
+The framework handles all of this automatically — no setup on your end other than an OpenAI API key for best-quality transcription.
+
+## How it works {#how-it-works}
+
+The composer's voice button records audio in the browser, then picks a provider:
+
+1. **OpenAI Whisper (preferred).** If an `OPENAI_API_KEY` is configured, the browser POSTs the audio to `/_agent-native/transcribe-voice`, which proxies to Whisper and returns the transcript. Hard 25 MB limit per clip (Whisper's).
+2. **Browser Web Speech API (fallback).** If no key is available, the composer falls back to the browser's built-in speech recognition. Works in Chromium-based browsers (Chrome, Edge, Arc) and Safari. Less accurate; streams live.
+
+Provider choice is stored in application state under `settings.voiceTranscriptionProvider` (`"openai"` or `"browser"`) so the user can force one or the other in the sidebar settings.
+
+The route is **same-origin only** — cross-site POSTs are rejected so an attacker can't burn your OpenAI credits from an external page.
+
+## Enabling Whisper {#enabling-whisper}
+
+Two ways to provide an OpenAI key:
+
+### Per-user (recommended for SaaS)
+
+The user sets their own key via the agent sidebar settings UI. It's stored as a user-scoped encrypted secret (via `readAppSecret`). Each user pays for their own transcription; zero cost to the host.
+
+### Shared (for internal tools)
+
+Set `OPENAI_API_KEY` as an environment variable or in the `settings` table. Every user's transcription hits the shared key.
+
+The route checks user-scope first, then falls back to the shared credential — so a power user with their own key can override the shared one.
+
+If no key is configured at all, the route returns a 400 the composer recognizes, and silently falls back to Web Speech.
+
+## The route {#route}
+
+`POST /_agent-native/transcribe-voice`
+
+- **Body:** multipart form with a single `audio` part (webm/opus by default).
+- **Response:** `{ text }` on success, `{ error }` on failure.
+- **Auth:** requires an active session (Better Auth cookie).
+- **Origin check:** same-origin only.
+- **Max size:** 25 MB (Whisper's hard limit).
+
+You don't need to call this directly — the composer does. But if you're building a custom input surface and want the same transcription, POST a `FormData` with an `audio` blob to the same route.
+
+## Customizing the provider {#customizing}
+
+The provider field is a plain application-state key, so the agent can change it on request (`"use the browser speech recognizer instead"`). If you're building a template with different requirements — say, an on-prem Whisper deployment — swap the route handler by registering your own `transcribe-voice` route before the framework mounts the default.
+
+## What's next
+
+- [**Drop-in Agent**](/docs/drop-in-agent) — the composer that exposes the voice button
+- [**Onboarding**](/docs/onboarding) — registering the OpenAI key as a setup step
+- [**Security & Data Scoping**](/docs/security) — how encrypted secrets are stored per user

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

@@ -1,61 +1,152 @@
 ---
 title: "What Is Agent-Native?"
-description: "What agent-native apps are, what agent-native development means, and why every AI agent needs a management interface."
+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)."
 ---
 
 # 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.
+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.
 
-## What is an agent-native app? {#what-is-an-agent-native-app}
+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.
 
-Think of agent-native apps as a layer on top of AI agents. An agent has skills, instructions, and tools. It can be autonomous and general purpose. The application sits on top of that and gives it structure.
+## The ladder {#the-ladder}
 
-Importantly, agent-native does **not** mean "app that calls an LLM." That's the anti-pattern. A text box that sends a prompt and returns a response gives you no ability to give feedback, no way to understand what the agent is doing, and no way to customize its behavior with instructions and skills.
+Here's the progression. Most teams stop at rung 1. Agent-native is rung 3.
 
-An agent-native app gives you everything good about traditional applications — databases, dashboards, workflows, persistence, shareability — plus everything good about AI agents. The agent can do anything the UI can do, and the things it does persist to the UI so you can inspect them, visualize them, and share them.
+### Rung 1 — a single LLM call (the anti-pattern) {#rung-one}
 
-## Not just a chatbot {#not-just-a-chatbot}
+```ts
+const output = await llm(prompt);
+```
 
-A chat interface alone isn't enough. When you're building tools for people to actually use, you need more than a box for them to type a prompt into:
+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.
 
-- **Discoverability** — users need to know what the app can do without guessing prompts
-- **Workflows** — structured flows for common tasks like composing emails, creating events, or building forms
-- **Visualization** — charts, calendars, email threads, and slide decks are better as visual interfaces than text
-- **Persistence** — a dashboard to come back to, data that doesn't disappear between sessions
-- **Shareability** — share a form link, a slide deck URL, or a report with your team
-- **Speed** — clicking a button is faster than typing a prompt for routine tasks
+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.
 
-Agent-native apps give you all of this while keeping the full power of the AI agent. The agent is always there — you can ask it to do anything. But the UI makes common workflows fast, visual, and accessible to everyone on the team.
+### 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;
+  }
+}
+```
+
+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.
+
+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.
+
+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 3 — `<Agent />` + actions + workspace {#rung-three}
+
+```tsx
+// 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
+// Anywhere in your React app
+import { AgentSidebar } from "@agent-native/core/client";
+
+<AgentSidebar />;
+```
+
+```tsx
+// The same action, typesafe, from a button
+const { mutate } = useActionMutation("replyToEmail");
+
+<Button onClick={() => mutate({ emailId, body: "Thanks!" })}>
+  Send Reply
+</Button>;
+```
+
+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.
+
+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.
+
+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.
+
+Every agent eventually needs a UI. Even if the agent does all the _work_, humans still need to:
+
+- **See what it's doing** — progress, tool calls, intermediate output
+- **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
+
+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.
+
+## 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.
+
+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.
+
+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.
 
 ## Agent + UI parity {#agent-ui-parity}
 
-This is the defining principle. Any application functionality should be able to be done by the agent _or_ the UI:
+This is the defining principle.
 
-> **From the UI** — Click buttons, fill forms, navigate views. The UI writes to the database and the agent can see the results.
+> **From the UI** — click buttons, fill forms, navigate views. The UI writes to the database; the agent sees the results.
 >
-> **From the agent** — Natural language, other agents via A2A, Slack, Telegram. The agent writes to the database and the UI updates automatically.
+> **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.
+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.
 
-## What makes it different {#what-makes-it-different}
+## Customization that's usually reserved for Claude Code {#workspace-customization}
 
-Every agent ultimately needs a management interface. At the minimum, you need to understand what it's doing, inspect the data it's creating, and debug when things go wrong. That's just called an application.
+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.
+
+Agent-native ships the same customization layer as a first-class part of every app — the **workspace**. Each app includes:
+
+- `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
+
+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.
+
+See [Workspace](/docs/workspace) for the full concept.
+
+## What makes it different {#what-makes-it-different}
 
 | Approach                               | Description                                                                                                                            |
 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | **Traditional apps with AI bolted on** | The AI is an afterthought. Limited to autocomplete, summaries, or a chat sidebar that can't actually do anything in the app.           |
+| **Pure chat / agent interfaces**       | Powerful but inaccessible. No dashboards, no workflows, no persistence. Non-developers can't use them effectively.                     |
+| **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. |
-| **Pure chat/agent interfaces**         | Powerful but inaccessible. No dashboards, no workflows, no persistence. Non-developers can't use them effectively.                     |
-| **Agent-native apps**                  | Full application UI with discoverability, workflows, and visualization — plus the agent for anything that needs AI.                    |
-
-The argument is simple: make your agents composable, think of them as applications. An analytics application, a slide generation application, a document application. Each one is a complete tool that humans and agents can both use.
 
 ## What is agent-native development? {#what-is-agent-native-development}
 
-Agent-native development means building with agents first. You build projects that work great when prompted from AI coding tools like Claude Code, Codex, Cursor, Windsurf, and Builder.io.
+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 idea is that you build instructions and skills into the project as prerequisites. The agent will tend to do _better_ than a human developer because you can encode rules like "when you add a feature, also add a skill for it" — things that humans will tend to forget or skip reading the docs for.
+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}
 
@@ -63,38 +154,44 @@ 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** can validate that the four-area checklist was followed, that skills were updated, and that the code matches the project's conventions
-- **Auto-maintained docs and tests** — agents can be instructed to keep documentation up to date and tests passing, making it easier for humans to contribute
+- **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 similar to the shift from desktop-first to mobile-first development. Mobile-first didn't mean "no desktop" — it meant designing for mobile constraints first and then scaling up. Agent-native development means designing for agent workflows first and then making sure humans can work effectively too.
+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. The goal is actual agent-native development as a team:
+Agent-native development isn't just for developers:
 
-- **Designers** can update designs directly in the code through the agent
-- **Product managers** can update functionalities and requirements
-- **QA** can test and prompt for fixes
-- **Anyone on the team** can contribute through natural language
+- **Designers** update designs directly in the code through the agent
+- **Product managers** update functionalities and requirements
+- **QA** tests and prompts for fixes
+- **Anyone on the team** contributes through natural language
 
-The vision is to reduce handoffs and enable one-person-to-full-team productivity using real collaboration between humans and agents.
+The vision: reduce handoffs, enable one-person-to-full-team productivity.
 
 ## Fork and customize {#fork-and-customize}
 
-Agent-native apps follow a fork-and-customize model. You start from a template — mail, calendar, analytics, slides — and make it yours:
+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 [agentnative.com](/templates)
-2. Start using it immediately as a hosted app (e.g. mail.agentnative.com)
-3. Fork it when you want to customize — "connect to our Stripe account", "add a cohort chart"
+1. Pick a template on [agent-native.com](/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
-5. Deploy your fork to your own domain
+5. Deploy your fork to your own domain — or stay on agent-native.com
 
-Because it's your app — not shared infrastructure — the agent can safely evolve the code over time. Your app keeps improving as you use it.
+Because it's _your_ app, not shared infrastructure, the agent can safely evolve the code. Your app keeps improving as you use it. See [Cloneable SaaS](/docs/cloneable-saas) for the full story.
 
 ## Composable agents {#composable-agents}
 
-Agent-native apps can communicate with each other using the [A2A protocol](/docs/a2a-protocol). From the mail app, you can tag the analytics agent to query data and include results in a draft. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI.
+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.
+
+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.
 
-This is why agent-native is a **framework and not a library**. The architecture — shared database, polling sync, actions, application state — needs to be built in from the ground up. You can migrate existing apps, but the best practice is to build agent-native from the start.
+## What's next
 
-See the [Key Concepts](/docs/key-concepts) doc for the full technical details.
+- [**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/docs/content/workspace-management.md

@@ -222,3 +222,4 @@ For a new workspace, after running `agent-native create`:
 - [ ] Configure the approval policy and approver emails
 - [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications
 - [ ] Connect Slack or Telegram for workspace messaging
+- [ ] Configure shared MCP servers — drop `mcp.config.json` at the workspace root, or enable Dispatch as the workspace [MCP hub](/docs/mcp-clients#hub) so every app inherits the same server list