@agent-native/core 0.7.4 → 0.7.7

package/docs/content/actions.md

@@ -1,129 +1,224 @@
 ---
 title: "Actions"
-description: "Action dispatcher, parseArgs, standard actions, and utility functions for agent-callable operations."
+description: "defineAction — the single definition that becomes an agent tool, a typesafe frontend mutation, an HTTP endpoint, an MCP tool, and a CLI command."
 ---
 
 # Actions
 
-`@agent-native/core` provides an action dispatcher and utilities for building agent-callable actions.
+Actions are the single source of truth for anything your app does. Define an action once with `defineAction()`, drop it in `actions/`, and it's immediately available as:
 
-## Action Dispatcher {#action-dispatcher}
+- **An agent tool** — the agent sees it with a zod-derived JSON Schema and can call it in chat.
+- **A typesafe React mutation** — `useActionMutation("name")` on the frontend, types inferred from the schema.
+- **An HTTP endpoint** — `POST /_agent-native/actions/<name>` (auto-mounted by the framework).
+- **An MCP tool** — exposed to Claude Desktop, ChatGPT remote-MCP, and any other MCP client.
+- **An A2A tool** — called by other agent-native apps over A2A.
+- **A CLI command** — `pnpm action <name>` for scripting and dev loops.
 
-The action system lets you create actions that agents can invoke via `pnpm action <name>`. Each action is a TypeScript file that exports a default async function.
+One definition, six consumers. This is rung 3 of the [ladder](/docs/what-is-agent-native#the-ladder).
+
+## Defining an action {#defining}
 
 ```ts
-// actions/run.ts — dispatcher (one-time setup)
-import { runScript } from "@agent-native/core";
-runScript();
+// actions/reply-to-email.ts
+import { defineAction } from "@agent-native/core";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Reply to an email thread in the user's voice.",
+  schema: z.object({
+    emailId: z.string().describe("The id of the email to reply to."),
+    body: z.string().describe("The reply body, in markdown."),
+  }),
+  run: async ({ emailId, body }) => {
+    await db.insert(replies).values({ emailId, body });
+    return { ok: true, emailId };
+  },
+});
 ```
 
-```ts
-// actions/hello.ts — example action
-import { parseArgs } from "@agent-native/core";
+That's it. The framework auto-discovers every file in `actions/` and mounts them on startup.
 
-export default async function hello(args: string[]) {
-  const { name } = parseArgs(args);
-  console.log(`Hello, ${name ?? "world"}!`);
-}
+### Schema options {#schemas}
+
+`schema` accepts any [Standard Schema](https://standardschema.dev)-compatible library:
+
+- **Zod** (v4) — most common, best type inference, auto-converts to JSON Schema.
+- **Valibot** — minimal bundle size if that matters.
+- **ArkType** — if you like the syntax.
+
+The schema is converted to JSON Schema for the Claude API tool definition, _and_ used at runtime to validate inputs before `run()` fires. Invalid inputs never reach your handler.
+
+### HTTP config {#http}
+
+By default every action is exposed as `POST /_agent-native/actions/<name>`. Override with the `http` option:
+
+```ts
+export default defineAction({
+  description: "Get details for a lead.",
+  schema: z.object({ leadId: z.string() }),
+  http: { method: "GET", path: "leads/:leadId" }, // optional override
+  run: async ({ leadId }) => {
+    return await db.select().from(leads).where(eq(leads.id, leadId));
+  },
+});
 ```
 
-```bash
-# Run it
-pnpm action hello --name Steve
+- **`http: { method: "GET" | "POST" | "PUT" | "DELETE" }`** — default `POST`. `GET` actions are auto-marked `readOnly` so successful calls don't trigger a UI poll-refresh.
+- **`http: { path: "..." }`** — override the route path under `/_agent-native/actions/`. Defaults to the filename.
+- **`http: false`** — disable the HTTP endpoint entirely. Agent + CLI only.
+- **`readOnly: true`** — explicitly skip the poll-refresh even for POST actions that don't mutate.
+
+## Calling it from the UI {#ui}
+
+Two hooks, both in `@agent-native/core/client`. Types are inferred from your `defineAction` schemas — no manual type declarations.
+
+### `useActionMutation` {#use-action-mutation}
+
+For actions that change state:
+
+```tsx
+import { useActionMutation } from "@agent-native/core/client";
+
+const { mutate, isPending } = useActionMutation("replyToEmail");
+
+<Button
+  disabled={isPending}
+  onClick={() => mutate({ emailId, body: "Thanks!" })}
+>
+  Send Reply
+</Button>;
 ```
 
-## parseArgs(args) {#parseargs}
+On success, the framework emits a poll event so every `useActionQuery`/`useDbSync` consumer refetches automatically. See [Real-Time Sync](/docs/key-concepts#polling-sync).
 
-Parse CLI arguments in `--key value` or `--key=value` format:
+### `useActionQuery` {#use-action-query}
+
+For read-only GET actions:
 
 ```ts
-import { parseArgs } from "@agent-native/core";
+import { useActionQuery } from "@agent-native/core/client";
 
-const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
-// { name: "Steve", verbose: "true", count: "3" }
+const { data, isLoading } = useActionQuery("getLead", { leadId });
 ```
 
+The query is cached under `["action", "getLead", { leadId }]` and auto-invalidated on any mutating action that completes.
+
+## Calling it from the CLI {#cli}
+
+Every action is runnable via `pnpm action`:
+
+```bash
+pnpm action replyToEmail --emailId thread-123 --body "Thanks!"
+```
+
+Flags are parsed into the shape your schema expects. Useful for agent-dev loops, scripts, and cron.
+
+## Calling it from another agent (A2A) {#a2a}
+
+If your app is an [A2A](/docs/a2a-protocol) peer, other agent-native apps discover your actions automatically and can call them by name. Same-origin deploys skip JWT signing; cross-origin uses a shared `A2A_SECRET`.
+
+## Exposing it over MCP {#mcp}
+
+With MCP enabled, your actions show up in the framework's MCP server at `/_agent-native/mcp`. Any MCP client — Claude Desktop, ChatGPT remote MCP, etc. — can connect and see them as tools. See [MCP Protocol](/docs/mcp-protocol).
+
 ## Standard actions {#standard-actions}
 
-Every template should include these two actions for [context awareness](/docs/context-awareness):
+Every template should include these two for [context awareness](/docs/context-awareness):
 
 ### view-screen {#view-screen}
 
-Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent should always call this before acting.
+Reads the current navigation state, fetches contextual data, and returns a snapshot of what the user sees. The agent calls this when it needs a fresh look at the screen.
 
 ```ts
 // actions/view-screen.ts
+import { defineAction } from "@agent-native/core";
 import { readAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Read the current screen state for context.",
+  schema: z.object({}),
+  http: { method: "GET" },
+  run: async () => {
+    const navigation = await readAppState("navigation");
+    const screen: Record<string, unknown> = { navigation };
+
+    if (navigation?.view === "inbox") {
+      const res = await fetch(
+        `${process.env.APP_URL}/api/emails?label=${navigation.label}`,
+      );
+      screen.emailList = await res.json();
+    }
+
+    return screen;
+  },
+});
+```
 
-export default async function main() {
-  const navigation = await readAppState("navigation");
-  const screen: Record<string, unknown> = { navigation };
-
-  if (navigation?.view === "inbox") {
-    const res = await fetch(
-      "http://localhost:3000/api/emails?label=" + navigation.label,
-    );
-    screen.emailList = await res.json();
-  }
+### navigate {#navigate}
 
-  console.log(JSON.stringify(screen, null, 2));
-}
-```
+Writes a one-shot navigation command to application state. The UI reads it, navigates, and deletes the entry.
 
-```bash
-pnpm action view-screen
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the user to a view.",
+  schema: z.object({
+    view: z.string(),
+    threadId: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
 ```
 
-### navigate {#navigate}
+## Legacy CLI-style actions {#legacy-cli-actions}
 
-Writes a one-shot navigation command to application-state. The UI reads it, navigates, and deletes the entry.
+The framework still supports older `export default async function(args)` actions that aren't wrapped in `defineAction` — useful for one-off dev scripts that don't need agent/HTTP exposure. These are CLI-only; they don't appear as agent tools, don't mount HTTP endpoints, and don't get typesafe frontend hooks.
 
 ```ts
-// actions/navigate.ts
+// actions/debug-dump.ts — CLI-only
 import { parseArgs } from "@agent-native/core";
-import { writeAppState } from "@agent-native/core/application-state";
 
 export default async function main(args: string[]) {
-  const parsed = parseArgs(args);
-  await writeAppState("navigate", parsed);
-  console.log("Navigate command written:", parsed);
+  const { table } = parseArgs(args);
+  // one-off script you wouldn't want the agent to call
 }
 ```
 
-```bash
-pnpm action navigate --view inbox --threadId thread-123
-```
+New code should prefer `defineAction()`. Reach for this pattern only when you deliberately don't want the action exposed to agents or the UI.
 
-## Shared Agent Chat {#shared-agent-chat}
+### `parseArgs(args)` {#parseargs}
 
-`@agent-native/core` provides an isomorphic chat bridge that works in both browser and Node.js:
+Helper for legacy-style actions. Parses CLI arguments in `--key value` or `--key=value` format:
 
 ```ts
-import { agentChat } from "@agent-native/core";
-
-// Auto-submit a message
-agentChat.submit("Generate a report for Q4");
-
-// Prefill without submitting
-agentChat.prefill("Draft an email to...", contextData);
+import { parseArgs } from "@agent-native/core";
 
-// Full control
-agentChat.send({
-  message: "Process this data",
-  context: JSON.stringify(data),
-  submit: true,
-});
+const args = parseArgs(["--name", "Steve", "--verbose", "--count=3"]);
+// { name: "Steve", verbose: "true", count: "3" }
 ```
 
-In the browser, messages are sent via `window.postMessage()`. In Node.js (actions), they use the `BUILDER_PARENT_MESSAGE:` stdout format that the Electron host translates to postMessage.
+## Utility functions {#utility-functions}
+
+| Function                | Returns   | Description                                           |
+| ----------------------- | --------- | ----------------------------------------------------- |
+| `loadEnv(path?)`        | `void`    | Load `.env` from project root (or custom path).       |
+| `camelCaseArgs(args)`   | `Record`  | Convert kebab-case keys to camelCase.                 |
+| `isValidPath(p)`        | `boolean` | Validate a relative path (no traversal, no absolute). |
+| `isValidProjectPath(p)` | `boolean` | Validate a project slug (e.g. `my-project`).          |
+| `ensureDir(dir)`        | `void`    | `mkdir -p` helper.                                    |
+| `fail(message)`         | `never`   | Print to stderr and `exit(1)`.                        |
 
-## Utility Functions {#utility-functions}
+## What's next
 
-| Function                | Returns   | Description                                        |
-| ----------------------- | --------- | -------------------------------------------------- |
-| `loadEnv(path?)`        | `void`    | Load .env from project root (or custom path)       |
-| `camelCaseArgs(args)`   | `Record`  | Convert kebab-case keys to camelCase               |
-| `isValidPath(p)`        | `boolean` | Validate relative path (no traversal, no absolute) |
-| `isValidProjectPath(p)` | `boolean` | Validate project slug (e.g. "my-project")          |
-| `ensureDir(dir)`        | `void`    | mkdir -p helper                                    |
-| `fail(message)`         | `never`   | Print error to stderr and exit(1)                  |
+- [**Drop-in Agent**](/docs/drop-in-agent) — `useActionMutation` / `useActionQuery` in React
+- [**Context Awareness**](/docs/context-awareness) — the `view-screen` + `navigate` pattern in depth
+- [**A2A Protocol**](/docs/a2a-protocol) — how other agents discover and call your actions
+- [**MCP Protocol**](/docs/mcp-protocol) — exposing actions over MCP

package/docs/content/agent-teams.md

@@ -0,0 +1,139 @@
+---
+title: "Agent Teams"
+description: "The main agent delegates work to sub-agents that run in their own threads and appear as live preview chips inline in chat."
+---
+
+# Agent Teams
+
+The agent chat is an **orchestrator**, not a monolith. When the main agent hits a task that's better owned by a specialist — "write this email in my voice," "run a BigQuery analysis," "review this PR" — it spawns a sub-agent in its own thread, tools, and context. The sub-agent shows up as a live preview **chip** inline in the main chat; click it to open the full conversation as a tab.
+
+This keeps the main thread focused, lets sub-agents run in parallel, and gives you a clean audit trail for any delegated work.
+
+## The mental model {#mental-model}
+
+- **Main chat** — the orchestrator. Reads your request, delegates. Rarely does heavy work itself.
+- **Sub-agents** — run with their own thread, their own system prompt, their own tool set. Each maps to a "custom agent" profile in the [workspace](/docs/workspace).
+- **Chips** — the rich preview card that appears inline in the main chat, showing the sub-agent's current step, streaming output, and final summary. Collapsed by default; expands to the full conversation on click.
+- **Bidirectional messaging** — the main agent can send follow-ups to a running sub-agent; a sub-agent can message back when it hits an ambiguous point.
+
+Sub-agent state is persisted in the `application_state` SQL table (under `agent-task:<taskId>`), so tasks survive serverless cold starts and work across multiple processes.
+
+## When to spawn a sub-agent {#when-to-spawn}
+
+Spawn when the task:
+
+- Needs a different **system prompt** (a specialist voice or tone, e.g., "code review").
+- Has a **long-running** tool chain that would pollute the main context.
+- Can run **in parallel** with other work the main agent is doing.
+- Is owned by a **different team** that already has a custom agent profile.
+
+Don't spawn for trivial one-shot work — call the action directly.
+
+## Invoking a sub-agent {#invoking}
+
+Three ways to kick off a sub-agent, from least to most explicit:
+
+### 1. `@mention` a custom agent {#mention}
+
+The user types `@agent-name` in the chat composer. A dropdown of workspace sub-agents appears. Selecting one inserts a chip; on submit the main agent delegates the message to that sub-agent.
+
+Custom agents live in the workspace at `agents/<slug>.md` — a Markdown file with YAML frontmatter. See [Custom Agents](/docs/workspace#custom-agents) for the format.
+
+### 2. The main agent delegates automatically {#auto-delegate}
+
+The framework gives the main agent a `delegate-to-agent` tool. When the model decides a task fits a registered sub-agent profile, it calls the tool. A chip appears; the sub-agent runs. The main agent waits (or moves on in parallel) and incorporates the result when the sub-agent finishes.
+
+### 3. Programmatic spawn {#programmatic-spawn}
+
+For framework-level integrations, use `spawnTask()` from `@agent-native/core/server`:
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from learnings.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  parentSend: emit, // SSE emit function for the parent chat stream
+});
+```
+
+Most app code won't call this directly — the framework does it under the hood for `@mentions` and for the `delegate-to-agent` tool. Reach for `spawnTask()` only when you're wiring a new entry point (e.g., a button that kicks off a background job that runs as a sub-agent).
+
+## Task lifecycle {#lifecycle}
+
+```
+spawnTask()
+  ├─ creates a new thread in chat_threads (with the description as the first user message)
+  ├─ writes agent-task:<taskId> to application_state (status=running)
+  ├─ emits agent_task_started to the parent stream → chip appears in the UI
+  ├─ runs the agent loop in the background
+  │   └─ emits agent_task_step events → chip updates live
+  ├─ on completion: updates status=completed, writes summary + preview
+  └─ emits agent_task_done → chip shows final summary
+```
+
+At any point the parent agent can resume the sub-agent with a follow-up via `sendToTask(taskId, message)`. If the sub-agent errors, `markTaskErrored(taskId, reason)` records the failure and surfaces it to the user.
+
+## Reading task state {#reading-state}
+
+From server code or other actions:
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+`AgentTask` shape:
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+}
+```
+
+## Custom agent profiles {#profiles}
+
+A custom agent is a Markdown file in the workspace:
+
+```markdown
+---
+name: Code Review
+description: >-
+  Reviews TypeScript PRs with a focus on correctness, type safety, and API design.
+model: inherit
+tools: inherit
+delegate-default: true
+---
+
+# Role
+
+You are a meticulous code reviewer. Focus on correctness, subtle type errors,
+and the public API surface. Be terse and concrete — cite file:line wherever
+you can.
+
+## Rules
+
+- Prefer "here's the bug" over "here's why this pattern is wrong."
+- Never LGTM silently; always summarize what you checked.
+```
+
+Store at `agents/code-review.md` in the workspace. It appears in the `@mention` dropdown and is available to the main agent as a delegation target. See [Workspace — Custom Agents](/docs/workspace#custom-agents) for the full format.
+
+## What's next
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) — the profile format
+- [**A2A Protocol**](/docs/a2a-protocol) — when the "sub-agent" lives in a different app entirely
+- [**Actions**](/docs/actions) — the tools a sub-agent calls

package/docs/content/cloneable-saas.md

@@ -0,0 +1,98 @@
+---
+title: "Cloneable SaaS"
+description: "Agent-native templates are not demos — they're complete, SaaS-grade products you clone, customize, and own."
+---
+
+# Cloneable SaaS
+
+The word "template" undersells what ships with agent-native.
+
+In most frameworks, a template is a bare-bones scaffold: a couple of routes, a few components, and a lot of "TODO." Agent-native inverts that. Every template is a **full, SaaS-grade product** — email client, calendar, analytics, deck generator, video editor, form builder, issue tracker — complete enough to use as-is, and also complete enough to fork and make your own.
+
+Think of them less like "templates" and more like **cloneable SaaS**. You get a real product, not a starting point.
+
+## The pitch {#pitch}
+
+Every SaaS product you use today hits the same wall: it gives you 80% of what you need, and you can't change the 20% that really matters. You can't touch the data model. You can't add the metric. You can't wire it to your internal system. You can't give it instructions.
+
+Cloneable SaaS flips that. You start from a production-quality app, and everything about it is yours — the code, the database, the agent, the deploy target, the brand. If you don't like how the inbox groups by thread, change it. If you need a field that the template doesn't have, add it. The agent helps you do all of this in natural language.
+
+This isn't a theoretical claim: it's how Steve (the framework's author) has been using it for months. The mail template _is_ his inbox. The analytics template _is_ his dashboard. The calendar template _is_ his calendar.
+
+## What's in the catalog {#catalog}
+
+All of these ship in the `BuilderIO/agent-native` repo and scaffold via `agent-native create`:
+
+| Template       | What it is                                                                                                      |
+| -------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Mail**       | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, with an agent that can draft and send.    |
+| **Calendar**   | An agent-native Google Calendar. Events, sync, public booking links, agent-driven scheduling.                   |
+| **Content**    | An agent-native Notion / Google Docs. Markdown + Tiptap editor, Notion sync, multi-user real-time collab.       |
+| **Slides**     | An agent-native Google Slides. React-based decks the agent generates and edits directly.                        |
+| **Video**      | An agent-native video editor built on Remotion. Prompt for a cut, the agent assembles it.                       |
+| **Analytics**  | An agent-native Amplitude/Mixpanel. Connect data sources, prompt for charts, pin to dashboards.                 |
+| **Forms**      | An agent-native Typeform. Build, share, and collect; agent handles the schema and analysis of submissions.      |
+| **Issues**     | An agent-native Jira. Projects, issues, priorities, with the agent as your project manager.                     |
+| **Recruiting** | An agent-native Greenhouse. Candidate pipelines, scoring, outreach drafts.                                      |
+| **Dispatch**   | The **workspace control plane**: central secrets vault, cross-app integrations, Slack/Telegram, scheduled jobs. |
+| **Starter**    | The minimal scaffold. Agent chat + the six-rules architecture wired up, nothing else. Build from scratch.       |
+
+Additional templates in active development in the repo: **Clips** (screen recording + transcription), **Calls** (Gong-style conversation intelligence), **Scheduling** (a standalone scheduling app and reusable package).
+
+## The clone → customize → deploy flow {#flow}
+
+Every cloneable SaaS follows the same lifecycle:
+
+### 1. Clone
+
+```bash
+pnpm dlx @agent-native/core create my-platform
+```
+
+The CLI shows a multi-select picker. Pick one app (standalone) or several (workspace — apps share auth, brand, agent config, and database). Each picked template is scaffolded into `apps/<name>/` with every file you need. See [Getting Started](/docs) for the full flow or [Enterprise Workspace](/docs/enterprise-workspace) for the workspace story.
+
+### 2. Use it immediately
+
+Every template is runnable the moment it scaffolds. Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
+
+### 3. Customize with the agent
+
+The agent can modify code — components, routes, actions, styles, the schema. This is a feature, not a bug:
+
+- "Change the inbox to group by sender instead of thread." _The agent edits the component._
+- "Add a `leadScore` column to contacts and compute it from the last email." _The agent adds the Drizzle column, runs a migration, writes the scoring action._
+- "Connect this to our internal HR API." _The agent writes the integration._
+
+Every edit is normal Git-tracked code. Bad changes? Revert them. Good changes? Keep them. See [Self-Modifying Code](/docs/key-concepts#agent-modifies-code) for the full mental model.
+
+### 4. Deploy anywhere
+
+Agent-native apps run on any Nitro-compatible host (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) and any Drizzle-compatible SQL database (SQLite, Postgres, Turso, D1, Supabase, Neon). The framework doesn't lock you in.
+
+For workspaces, `agent-native deploy` builds every app at once and ships them behind a single origin — your own domain, your own cert, one command. See [Deployment](/docs/deployment).
+
+### 5. Stay on `agent-native.com`, or self-host
+
+You can also use these as hosted apps on the Builder-operated `agent-native.com` platform — `mail.agent-native.com`, `calendar.agent-native.com`, etc. — without forking. Fork only when you want to change something the hosted version doesn't let you change.
+
+## Why this works {#why-this-works}
+
+Cloneable SaaS wouldn't be practical in a traditional codebase. Every user forking their own inbox would mean every user maintaining their own inbox — no thanks.
+
+Two framework decisions unlock it:
+
+1. **Agents do the maintenance.** You don't write code to add a column or wire a new integration — you ask the agent. So "your own forked inbox" is a feature, not a burden, because the agent is doing the work.
+2. **The workspace is SQL, not files.** Every user gets their own customization layer (skills, memory, instructions, connected MCP servers, sub-agents) without a dev-box. The shared codebase hosts all of them at once. See [Workspace](/docs/workspace).
+
+Combined, you get Claude-Code-level flexibility per user, with SaaS-grade deployment economics.
+
+## Authoring your own cloneable SaaS {#authoring}
+
+Want to publish a new template — your own cloneable SaaS? See [Creating Templates](/docs/creating-templates). You can publish to `BuilderIO/agent-native` for inclusion in the CLI picker, or host elsewhere and scaffold with `--template github:user/repo`.
+
+## What's next
+
+- [**Enterprise Workspace**](/docs/enterprise-workspace) — bundle many cloneable-SaaS apps into one monorepo that shares auth, brand, and agent instructions
+- [**Key Concepts**](/docs/key-concepts) — the architecture that makes this work
+- [**Deployment**](/docs/deployment) — ship your forked app
+- [**Creating Templates**](/docs/creating-templates) — author and publish a new cloneable SaaS

package/docs/content/creating-templates.md

@@ -209,7 +209,7 @@ Keep your data models simple — flat JSON files, one per entity. The agent can
 
 This is the most important file in your template. `AGENTS.md` tells the AI agent how your app works, what it can and can't do, and how to make changes:
 
-````markdown
+```markdown
 # My Template — Agent-Native App
 
 ## Architecture
@@ -226,12 +226,10 @@ This is an **@agent-native/core** application.
 
 ### Directory Structure
 
-```
-app/             # React frontend (file-based routing in app/routes/)
-server/          # Nitro API server
-actions/         # Agent-callable actions
-data/            # File-based state
-```
+    app/             # React frontend (file-based routing in app/routes/)
+    server/          # Nitro API server
+    actions/         # Agent-callable actions
+    data/            # File-based state
 
 ### Available Actions
 
@@ -242,16 +240,16 @@ data/            # File-based state
 
 Items are stored as `data/items/<id>.json`:
 
-```json
-{ "id": "...", "title": "...", "status": "active" }
-```
+    { "id": "...", "title": "...", "status": "active" }
 
 ### Key Patterns
 
 - API routes in `server/routes/` serve files from `data/`
 - UI delegates AI work via `sendToAgentChat()`
 - Actions write results to `data/` — SSE updates the UI
-````
+```
+
+> Code blocks inside `AGENTS.md` would normally be fenced with triple backticks — they're shown as indented code here to keep this outer example readable.
 
 Be specific about your data models, available actions, and key patterns. The better your `AGENTS.md`, the better the agent will work with your template.
 

package/docs/content/deployment.md

@@ -221,17 +221,10 @@ export default defineConfig({
 | `NITRO_PRESET`      | Override build preset at build time                                                                                  |
 | `ACCESS_TOKEN`      | Enable auth gating for production mode                                                                               |
 | `ANTHROPIC_API_KEY` | API key for embedded production agent                                                                                |
-| `FILE_SYNC_ENABLED` | Enable file sync for multi-instance                                                                                  |
 | `APP_BASE_PATH`     | Mount the app under a prefix (e.g. `/mail`). Set automatically by `agent-native deploy`; leave unset for standalone. |
 
 Inside a workspace, the root `.env` is loaded into every app automatically, so shared keys like `ANTHROPIC_API_KEY` and `A2A_SECRET` only need to be set once. Per-app `apps/<name>/.env` wins on conflict.
 
-## File Sync in Production {#file-sync}
+## Multi-instance deploys {#multi-instance}
 
-By default, agent-native apps store state in local files. For multi-instance deployments (e.g., serverless or load-balanced), enable file sync to keep instances in sync:
-
-```bash
-FILE_SYNC_ENABLED=true
-```
-
-See [File Sync](/docs/file-sync) for adapter configuration (Firestore, Supabase, Convex).
+Agent-native apps store all state in SQL via Drizzle and sync the UI via [polling](/docs/key-concepts#polling-sync) against the database — no file-system state, no sticky sessions, no in-memory caches. That means multi-instance and serverless deployments work out of the box: point every instance at the same `DATABASE_URL` and they converge automatically. See [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) and [Portability](/docs/key-concepts#hosting-agnostic).