@agent-native/core 0.7.13 → 0.7.14

package/docs/content/authentication.md

@@ -139,6 +139,57 @@ function MyComponent() {
 }
 ```
 
+## Sign-In with Return URL {#sign-in-return-url}
+
+Templates with **public pages** (share links, embeds, marketing pages) often need an in-page CTA that asks anonymous viewers to sign in and brings them back to the page they were on. The framework provides a single entry point for this:
+
+```
+/_agent-native/sign-in?return=<same-origin-path>
+```
+
+When an anonymous viewer hits this URL, the framework's login page is served. After a successful sign-in (any flow — token, email/password, or Google OAuth), the viewer is 302'd to `return`.
+
+The `return` parameter is validated as a **same-origin path**. Network-path references (`//evil.com/...`), absolute URLs, `data:` / `javascript:` schemes, and embedded control characters all fall back to `/`. The validated path is reconstructed from the URL parser, not echoed back from the input.
+
+**From a React component:**
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+function SignInCta() {
+  const onClick = () => {
+    const ret = window.location.pathname + window.location.search;
+    window.location.href =
+      "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+  };
+  return <Button onClick={onClick}>Sign in</Button>;
+}
+```
+
+### Bookmarked private paths
+
+When an anonymous user navigates directly to a private path like `/dashboard`, the framework already serves the login page at that URL — after successful sign-in, the page reloads and the user lands on `/dashboard`. No special handling needed; this works for token, email/password, **and** Google OAuth.
+
+### Behind the scenes: Google OAuth
+
+Both flows (the explicit `/_agent-native/sign-in` entrypoint and the bookmarked-path case) thread the return URL through the OAuth state. The state is HMAC-signed, so it can't be forged in transit. On the callback, the return URL is re-validated as same-origin before the redirect — so a leaked signing key still can't be turned into an open-redirect oracle.
+
+If your template wraps `/_agent-native/google/auth-url` directly (e.g. mail and calendar templates do, to widen scopes), accept a `?return=<path>` query and forward it as the sixth argument to `encodeOAuthState`:
+
+```typescript
+const returnUrl = getQuery(event).return;
+const state = encodeOAuthState(
+  redirectUri,
+  undefined,
+  desktop,
+  false,
+  undefined,
+  typeof returnUrl === "string" ? returnUrl : undefined,
+);
+```
+
+The default `/_agent-native/google/auth-url` route does this automatically — only override if your template needs custom OAuth handling.
+
 ## Environment Variables {#environment-variables}
 
 | Variable               | Purpose                                                          |

package/docs/content/cloneable-saas.md

@@ -1,98 +1,95 @@
 ---
 title: "Cloneable SaaS"
-description: "Agent-native templates are not demos — they're complete, SaaS-grade products you clone, customize, and own."
+description: "Fork a working SaaS product and make it yours — agent included."
 ---
 
 # Cloneable SaaS
 
-The word "template" undersells what ships with agent-native.
+Want to ship your own AI-powered analytics tool? Mail client? Forms builder? Pick a template, and you've got a working SaaS in minutes — agent, database, auth, and deploy pipeline already wired up.
 
-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.
+Most templates give you a blank scaffold and a long TODO list. Agent-native flips that. Each template is a **complete, SaaS-grade product** — already runnable on day one, already shippable, and entirely yours to customize, brand, and deploy.
 
-Think of them less like "templates" and more like **cloneable SaaS**. You get a real product, not a starting point.
+We call them **cloneable SaaS**, not templates. You're not starting from scratch. You're forking a finished product.
 
-## The pitch {#pitch}
+## Templates available {#catalog}
 
-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.
+Each one is a real app you could use today, and the launching pad for your own version of it.
 
-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.
+| Template       | What it is                                                                                                |
+| -------------- | --------------------------------------------------------------------------------------------------------- |
+| **Mail**       | An agent-native Superhuman. Inbox, labels, AI triage, keyboard-first, drafts and sends through the agent. |
+| **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, real-time multi-user collab. |
+| **Slides**     | An agent-native Google Slides. React-based decks the agent generates and edits directly.                  |
+| **Video**      | An agent-native video editor 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; the agent handles schema and submission analysis.    |
+| **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: shared secrets, cross-app integrations, Slack/Telegram, scheduled jobs.      |
+| **Starter**    | The minimal scaffold. Agent chat plus the architecture, nothing else. Build something new.                |
 
-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.
+More are in active development: **Clips** (screen recording + transcription), **Calls** (Gong-style conversation intelligence), and **Scheduling** (a standalone scheduling app).
 
-## What's in the catalog {#catalog}
+See the full catalog under [Templates](/templates), or jump straight to one — for example, [Dispatch](/docs/template-dispatch) is a great place to start if you want a workspace-style app.
 
-All of these ship in the `BuilderIO/agent-native` repo and scaffold via `agent-native create`:
+## What you get out of the box {#what-you-get}
 
-| 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.       |
+Every cloneable SaaS ships with the parts that normally take months to build:
 
-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).
+- **A working agent** — already wired into the app, already able to take actions on your data, already context-aware about what you're looking at. See [Messaging the agent](/docs/messaging) for how it works.
+- **Auth** — sign in, sessions, organizations, multi-tenant isolation. Already done.
+- **A database** — every template has its schema, queries, and migrations ready to go. Bring your own SQL database (Postgres, SQLite, Turso, D1) — the framework adapts.
+- **A real-time UI** — the screen stays in sync with what the agent does. Click "draft an email" in chat, watch the draft appear in your inbox immediately.
+- **Deploy-ready** — push to Netlify, Vercel, Cloudflare, AWS, or anywhere else that runs Node. No vendor lock-in.
+- **Branding hooks** — name, colors, logo, copy are all easy to change.
 
-## The clone → customize → deploy flow {#flow}
+This isn't a theoretical claim. The framework's author runs his actual inbox on the Mail template, his actual calendar on the Calendar template, and his actual analytics on the Analytics template. Templates are daily-driver software.
 
-Every cloneable SaaS follows the same lifecycle:
+## What you do {#what-you-do}
 
-### 1. Clone
+The path from "I want my own SaaS" to "I have my own SaaS" is short:
 
-```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 [Multi-App Workspace](/docs/multi-app-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.
+1. **Pick a template.** Use the CLI picker, or browse the docs and pick one to start from.
+2. **Brand it.** Change the name, colors, logo, and copy. Most templates expose this in a single config file.
+3. **Customize it.** Ask the agent to add the column you need, change how the inbox groups, connect to your internal API, add a new view. The agent edits the code; you review the diff.
+4. **Ship it.** Run the deploy command. You now have your own production SaaS at your own domain.
 
-### 3. Customize with the agent
+Steps 2–4 typically take days, not months. Step 3 is open-ended — your forked SaaS evolves over time, in plain English, by talking to the agent.
 
-The agent can modify code — components, routes, actions, styles, the schema. This is a feature, not a bug:
+## Why this is practical {#why}
 
-- "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._
+A traditional fork-the-codebase model breaks down at scale: every user maintaining their own inbox sounds like a maintenance nightmare. Two framework decisions make it work:
 
-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.
+1. **The agent does 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.
+2. **Per-user customization without per-user code.** Skills, memory, instructions, connected MCP servers, and sub-agents all live in SQL. Every user gets their own customization layer; the shared codebase hosts all of them at once.
 
-### 4. Deploy anywhere
+The result: Claude-Code-level flexibility for each user, with normal SaaS deployment economics.
 
-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.
+## Don't want to fork? {#hosted}
 
-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).
+You don't have to. Every template is also available as a hosted app on `agent-native.com` — `mail.agent-native.com`, `calendar.agent-native.com`, and so on. Use the hosted version for free or paid; fork only when you want to change something the hosted version doesn't expose.
 
-### 5. Stay on `agent-native.com`, or self-host
+## Building on this
 
-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.
+- [**Getting Started**](/docs/getting-started) — clone your first template and run it locally
+- [**Messaging the agent**](/docs/messaging) — how users (and you) talk to the agent that ships with each template
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — bundle several cloneable-SaaS apps into one workspace that shares auth, brand, and agent
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane template
+- [**Creating Templates**](/docs/creating-templates) — author and publish your own cloneable SaaS
 
-## Why this works {#why-this-works}
+### For developers {#dev-details}
 
-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.
+If you're scaffolding now, the CLI command is:
 
-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.
+```bash
+pnpm dlx @agent-native/core create my-platform
+```
 
-## Authoring your own cloneable SaaS {#authoring}
+You'll get 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.
 
-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`.
+Fill in `.env` (mostly `ANTHROPIC_API_KEY` and `DATABASE_URL`), `pnpm install`, `pnpm dev`, and it works. No "TODO: implement login," no placeholder routes.
 
-## What's next
+Deploy targets: any Nitro-compatible host (Node, Cloudflare, Netlify, Vercel, Deno, Lambda, Bun) and any Drizzle-compatible SQL database (SQLite, Postgres, Turso, D1, Supabase, Neon). For workspaces, `agent-native deploy` builds every app at once and ships them behind a single origin. See [Deployment](/docs/deployment).
 
-- [**Multi-App Workspace**](/docs/multi-app-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
+To author and publish your own cloneable SaaS, see [Creating Templates](/docs/creating-templates).

package/docs/content/faq.md

@@ -1,73 +1,92 @@
 ---
 title: "FAQ"
-description: "Frequently asked questions about agent-native apps, development, architecture, and templates."
+description: "Common questions about agent-native — what it is, who it's for, what you can build, and how it works."
 ---
 
 # FAQ
 
-Frequently asked questions about agent-native apps, development, and the framework.
+Common questions about agent-native, organized from "I'm just looking" to "I'm wiring up auth right now."
 
-## General {#general}
+## The basics {#general}
 
 ### What is agent-native? {#what-is-agent-native}
 
 Agent-native is a framework for building apps where the AI agent and the UI are equal partners. They share the same database, the same state, and they always stay in sync. Everything the UI can do, the agent can do — and vice versa. See [What Is Agent-Native?](/docs/what-is-agent-native) for the full explanation.
 
+### Who is this for? {#who-is-this-for}
+
+Anyone who wants to ship an AI-powered product without spending a year building the boring parts. That includes:
+
+- **Founders and PMs** who want to fork a working SaaS and make it their own — see [Cloneable SaaS](/docs/cloneable-saas).
+- **Operators** who want a [pure-agent app](/docs/pure-agent-apps) — an agent that does work in the background with a minimal management UI.
+- **Developers** building agent-driven products from scratch and want auth, multi-tenancy, real-time sync, and an architecture that won't break when AI is the primary user.
+
 ### How is this different from adding AI to an existing app? {#how-is-this-different}
 
 Most apps bolt AI on as an afterthought — an autocomplete here, a chat sidebar there. The AI can't actually _do_ things in the app. In an agent-native app, the agent is a first-class citizen. It can create emails, schedule events, build forms, generate slides, and modify the app's own code. The architecture is designed for this from the ground up.
 
-### Do I need to know AI/ML? {#do-i-need-to-know-ai}
+### Is it open source? {#is-this-open-source}
 
-No. You don't train models, fine-tune, or deal with embeddings. You build a regular web app with React, TypeScript, and SQL. The framework handles the agent integration — routing messages, running actions, syncing state. You write standard web code and the agent just works.
+Yes. The framework and all templates are open source. You can run everything locally, self-host, or use Builder.io's cloud for managed hosting, collaboration, and team features.
 
-### Is this open source? {#is-this-open-source}
+### How much does it cost? {#how-much}
 
-Yes. The framework and all templates are open source. You can run everything locally, self-host, or use Builder.io's cloud for managed hosting, collaboration, and team features.
+The framework itself is free. The two costs you'll see in practice:
 
-## Development {#development}
+- **AI usage.** You bring your own API key (Anthropic, OpenAI, etc.) and pay the model provider directly. There's no markup from us.
+- **Hosting.** Whatever your host charges. Most templates run fine on free tiers (Netlify, Vercel, Cloudflare) for small workloads.
 
-### Which AI coding tools work with agent-native? {#which-ai-tools-work}
+If you'd rather not manage any of this, the hosted version on `agent-native.com` (operated by Builder.io) bundles inference and hosting into a per-seat plan.
 
-Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard and auto-creates symlinks for specific tools:
+### Can I host this myself? {#can-i-self-host}
 
-- **Claude Code** — reads CLAUDE.md (symlinked from AGENTS.md)
-- **Cursor** — reads .cursorrules (symlinked from AGENTS.md)
-- **Windsurf** — reads .windsurfrules (symlinked from AGENTS.md)
-- **Codex, Gemini, and others** — work via the embedded agent panel
-- **Builder.io** — cloud-hosted agent with visual editing and collaboration
+Yes. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, your own server — and any SQL database (Postgres, SQLite, Turso, D1). The framework is built to be portable. See [Deployment](/docs/deployment).
 
-### Can I use my own database? {#can-i-use-my-own-database}
+### What AI models does it support? {#what-models}
 
-Yes. Set `DATABASE_URL` and the framework auto-detects your database. Supported databases include SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL), and Cloudflare D1. All SQL is dialect-agnostic via Drizzle ORM — the same code works everywhere.
+Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, and any provider that speaks the OpenAI API shape (including local models via Ollama). You configure the model in settings; switching is a config change, not a code rewrite. The framework's heaviest tested path is Claude, so that's the default recommendation.
 
-### Where can I deploy? {#where-can-i-deploy}
+### Do I need to know AI/ML? {#do-i-need-to-know-ai}
 
-Anywhere. The server runs on Nitro, which compiles to any deployment target: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda, and Bun. You can also use Builder.io's hosting for managed deployments. See the [Deployment guide](/docs/deployment).
+No. You don't train models, fine-tune, or deal with embeddings. You build a regular web app — and on the hosted version, you barely build anything at all. The framework handles the agent integration: routing messages, running actions, syncing state.
 
 ### Can I migrate an existing app to agent-native? {#can-i-use-existing-code}
 
 You can, but agent-native works best when built from the ground up. The architecture — shared database, polling sync, actions, application state — needs to be integrated throughout. Starting from a template and customizing it is the recommended path. Think of it like the shift from desktop-first to mobile-first: you _can_ retrofit, but building native is better.
 
-## Architecture {#architecture}
+## Templates and what you can build {#templates}
 
-### Why polling instead of WebSockets? {#why-polling-not-websockets}
+### What templates are available? {#what-templates-are-available}
 
-Polling works in every deployment environment — including serverless, edge, and container platforms where persistent connections aren't available. The framework polls every 2 seconds using a lightweight version counter. When changes are detected, React Query caches are invalidated and components re-render. It's simple, reliable, and universal. SSE is also supported as an alternative.
+The framework ships with production-ready templates you can use as daily drivers:
 
-### Why can't the UI call an LLM directly? {#why-no-inline-llm-calls}
+- **[Mail](/templates/mail)** — full-featured email client (like Superhuman)
+- **[Calendar](/templates/calendar)** — Google Calendar + Calendly-style booking links
+- **[Content](/templates/content)** — Notion-style documents
+- **[Slides](/templates/slides)** — presentation builder
+- **[Video](/templates/video)** — video composition with Remotion
+- **[Analytics](/templates/analytics)** — data platform (like Amplitude/Mixpanel)
+- **[Forms](/templates/forms)**, **[Issues](/templates/issues)**, **[Recruiting](/templates/recruiting)**, and the **[Dispatch](/docs/template-dispatch)** workspace control plane.
 
-AI is non-deterministic — you need conversation flow to give feedback and iterate, not one-shot buttons. The agent has your full codebase, instructions, skills, and conversation history. An inline LLM call has none of that. Plus, routing everything through the agent means the app can be driven from Slack, Telegram, or another agent via [A2A](/docs/a2a-protocol) — not just the UI.
+Each template is a complete app with UI, agent actions, database schema, and AI instructions. See [Cloneable SaaS](/docs/cloneable-saas) for the full picture, or all [Templates](/templates).
 
-### Why is this a framework and not a library? {#why-framework-not-library}
+### Can I customize templates? {#can-i-customize-templates}
 
-The shared database, polling sync, actions system, and application state all need to work together as a cohesive architecture. A library could give you pieces, but agent-native requires that the agent and UI are wired together from the ground up. Multiple agents need to be able to communicate, the UI needs to react to agent changes instantly, and the agent needs to understand what the user is looking at. That's an architecture, not a utility.
+That's the whole point. Fork a template and customize it by asking the agent. "Add a priority field to forms." "Connect to our Salesforce instance." "Change the color scheme to match our brand." The agent modifies the code, and your app evolves over time.
+
+### Can I build something the templates don't cover? {#build-from-scratch}
+
+Yes. Run `npx @agent-native/core create my-app` without picking a template — you get the framework scaffolding (frontend, backend, agent panel, database) but no domain-specific code. See [Getting Started](/docs/getting-started). For agent-first products with no traditional UI, see [Pure-Agent Apps](/docs/pure-agent-apps).
 
-## Agent Capabilities {#agent-capabilities}
+## Agent capabilities {#agent-capabilities}
 
 ### Can the agent really modify the app's own code? {#can-the-agent-modify-code}
 
-Yes, and it's a feature. The agent can safely edit components, routes, styles, and actions. You ask "add a cohort analysis chart" and the agent builds it. You ask "connect to our Stripe account" and the agent writes the integration.
+Yes, and it's a feature. The agent can safely edit components, routes, styles, and actions. You ask "add a cohort analysis chart" and the agent builds it. You ask "connect to our Stripe account" and the agent writes the integration. Everything is normal Git-tracked code, so bad changes are easy to revert.
+
+### Can users talk to the agent from outside the app? {#external-channels}
+
+Yes. The same agent runs in your web UI, in Slack, in Telegram, over email, and from other agents (via [A2A](/docs/a2a-protocol)). It's the same agent with the same memory and the same actions, just reached through different channels. See [Messaging the agent](/docs/messaging).
 
 ### Can agents talk to each other? {#can-agents-talk-to-each-other}
 
@@ -75,27 +94,38 @@ Yes, via the [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Every agent-na
 
 ### What can the agent see in the app? {#what-can-the-agent-see}
 
-The agent always knows what the user is currently viewing. The UI writes navigation state to the database on every route change — which view is open, which item is selected. The agent reads this via the `view-screen` action before taking action. If an email is open, the agent knows which email. If a slide is selected, the agent knows which slide. See [Context Awareness](/docs/context-awareness).
+The agent always knows what the user is currently viewing. The UI writes navigation state to the database on every route change — which view is open, which item is selected. The agent reads this before taking action. If an email is open, the agent knows which email. If a slide is selected, the agent knows which slide. See [Context Awareness](/docs/context-awareness).
 
-## Templates {#templates}
+## Development questions {#development}
 
-### What templates are available? {#what-templates-are-available}
+### Which AI coding tools work with agent-native? {#which-ai-tools-work}
 
-The framework ships with production-ready templates that you can use as daily drivers:
+Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard and auto-creates symlinks for specific tools:
 
-- **[Mail](/templates/mail)** — full-featured email client (like Superhuman)
-- **[Calendar](/templates/calendar)** — Google Calendar + Calendly-style meeting links
-- **[Content](/templates/content)** — Notion-style documents
-- **[Slides](/templates/slides)** — presentation builder
-- **[Video](/templates/video)** — video composition with Remotion
-- **[Analytics](/templates/analytics)** — data platform (like Amplitude/Mixpanel)
+- **Claude Code** — reads CLAUDE.md (symlinked from AGENTS.md)
+- **Cursor** — reads .cursorrules (symlinked from AGENTS.md)
+- **Windsurf** — reads .windsurfrules (symlinked from AGENTS.md)
+- **Codex, Gemini, and others** — work via the embedded agent panel
+- **Builder.io** — cloud-hosted agent with visual editing and collaboration
 
-Each template is a complete app with UI, agent actions, database schema, and AI instructions. See all [Templates](/templates).
+### Can I use my own database? {#can-i-use-my-own-database}
 
-### Can I customize templates? {#can-i-customize-templates}
+Yes. Set `DATABASE_URL` and the framework auto-detects it. Supported databases include SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL), and Cloudflare D1. All SQL is dialect-agnostic via Drizzle ORM — the same code works everywhere.
 
-That's the whole point. Fork a template and customize it by asking the agent. "Add a priority field to forms." "Connect to our Salesforce instance." "Change the color scheme to match our brand." The agent modifies the code, and your app evolves over time.
+### Where can I deploy? {#where-can-i-deploy}
+
+Anywhere. The server runs on Nitro, which compiles to any deployment target: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda, and Bun. You can also use Builder.io's hosting for managed deployments. See the [Deployment guide](/docs/deployment).
+
+## Architecture {#architecture}
+
+### Why polling instead of WebSockets? {#why-polling-not-websockets}
 
-### Can I build from scratch without a template? {#can-i-build-from-scratch}
+Polling works in every deployment environment — including serverless, edge, and container platforms where persistent connections aren't available. The framework polls every 2 seconds using a lightweight version counter. When changes are detected, React Query caches are invalidated and components re-render. It's simple, reliable, and universal. SSE is also supported as an alternative.
+
+### Why can't the UI call an LLM directly? {#why-no-inline-llm-calls}
+
+AI is non-deterministic — you need conversation flow to give feedback and iterate, not one-shot buttons. The agent has your full codebase, instructions, skills, and conversation history. An inline LLM call has none of that. Plus, routing everything through the agent means the app can be driven from Slack, Telegram, or another agent via [A2A](/docs/a2a-protocol) — not just the UI.
+
+### Why is this a framework and not a library? {#why-framework-not-library}
 
-Yes. Run `npx @agent-native/core create my-app` without the `--template` flag. You get the framework scaffolding — React frontend, Nitro backend, agent panel, database — but no domain-specific code. See [Getting Started](/docs).
+The shared database, polling sync, actions system, and application state all need to work together as a cohesive architecture. A library could give you pieces, but agent-native requires that the agent and UI are wired together from the ground up. Multiple agents need to be able to communicate, the UI needs to react to agent changes instantly, and the agent needs to understand what the user is looking at. That's an architecture, not a utility.

package/docs/content/getting-started.md

@@ -5,37 +5,51 @@ description: "Pick a template, create your app, and start customizing it with AI
 
 # Getting Started
 
-The fastest way to get started is to pick a template and make it yours. Agent-native templates are **[cloneable SaaS](/docs/cloneable-saas)** — complete, production-grade apps, not starter kits. You get a working product in under a minute and start customizing it with the agent.
+By the end of this page, you'll have a working app — Mail, Calendar, Forms, or any other template — running with an AI agent built into the sidebar that can drive every part of it.
 
-## Create Your Workspace {#create-your-app}
+## Who is this for? {#who-is-this-for}
 
-```bash
-npx @agent-native/core create my-platform
-```
+There are two ways to use agent-native, depending on how hands-on you want to be:
+
+- **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
+- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
 
-The CLI shows a multi-select picker — pick as many templates as you want (Mail + Calendar + Forms, for example) and they all get scaffolded into the same workspace sharing auth, brand, and agent config. Then boot them all:
+Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.
+
+## First run {#create-your-app}
+
+Three commands and you're up:
 
 ```bash
+npx @agent-native/core create my-platform
 cd my-platform
-pnpm install
-pnpm dev
+pnpm install && pnpm dev
 ```
 
-That's it — you have every app running locally with an AI agent built in. Open the agent panel, ask it to do something, and watch it work.
+The `create` command shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config.
 
-Want a single app with no monorepo? Pass `--standalone`:
+Open the URL the dev server prints (usually `http://localhost:3000`).
 
-```bash
-npx @agent-native/core create my-app --standalone --template mail
-```
+## What just happened? {#what-just-happened}
 
-Need to add more apps later? From inside the workspace:
+You now have a real, full-featured app running on your machine. Open it in the browser and try it:
 
-```bash
-agent-native add-app
-```
+- Click around the UI like you would any SaaS product.
+- Open the agent panel on the right side. Type something like "show me my settings" or "create a new entry called Welcome." Watch the agent click through the app on your behalf.
+- Anything you do by clicking, the agent can do by reading and writing the same database. Anything the agent does shows up in the UI immediately.
+
+That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
+
+## What's next {#whats-next}
+
+From here, use any AI coding tool (Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.
 
-From here, use your AI coding tool (Claude Code, Cursor, Windsurf, etc.) to customize it. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase. See [Multi-App Workspace](/docs/multi-app-workspace) for the full story on sharing auth, skills, components, and credentials across apps.
+Common next steps:
+
+- **Add another app to the same workspace** — run `agent-native add-app` from inside the workspace folder. See [Multi-App Workspace](/docs/multi-app-workspace) for sharing auth, components, and credentials across apps.
+- **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core create my-app --standalone --template mail`.
+- **Build a brand-new template from scratch** — see [Creating Templates](/docs/creating-templates) for the full Vite, Tailwind, and TypeScript setup.
+- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
 
 ## Templates {#templates}
 
@@ -55,7 +69,7 @@ Each template is a complete app with UI, agent actions, database schema, and AI
 
 Browse the [template gallery](/templates) for live demos, or see [Cloneable SaaS](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
 
-## Project Structure {#project-structure}
+## Project structure {#project-structure}
 
 Every agent-native app — whether from a template or from scratch — follows the same structure:
 
@@ -67,53 +81,15 @@ my-app/
   .agents/         # Agent instructions and skills
 ```
 
-Templates add domain-specific code on top of this: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`.
-
-## Configuration {#configuration}
-
-Templates come pre-configured. If you're starting from scratch, here are the config files:
-
-```ts
-// vite.config.ts
-import { defineConfig } from "@agent-native/core/vite";
-export default defineConfig();
-```
-
-```json
-// tsconfig.json
-{ "extends": "@agent-native/core/tsconfig.base.json" }
-```
-
-```css
-/* app/global.css — Tailwind v4 (CSS-first, no tailwind.config.ts needed) */
-@import "tailwindcss";
-@import "@agent-native/core/styles/agent-native.css";
-
-@source "./**/*.{ts,tsx}";
-
-:root {
-  --background: 0 0% 100%;
-  --foreground: 220 10% 10%;
-  /* ...rest of your shadcn-style tokens */
-}
-
-.dark {
-  --background: 220 6% 6%;
-  --foreground: 0 0% 90%;
-  /* ... */
-}
-```
-
-The framework auto-injects `@tailwindcss/vite` from `defineConfig()`.
-No `tailwind.config.ts`, `postcss.config.js`, or vite changes needed.
+Templates add domain-specific code on top: database schemas in `server/db/`, API routes in `server/routes/api/`, and actions in `actions/`. Building from scratch? See [Creating Templates](/docs/creating-templates) for `vite.config.ts`, `tsconfig.json`, and Tailwind setup.
 
-## Architecture Principles {#architecture-principles}
+## Architecture principles {#architecture-principles}
 
-These principles apply to all agent-native apps. Understanding them helps you customize templates or build from scratch:
+These principles apply to all agent-native apps. Skim them now, revisit them when you're customizing.
 
 1. **Agent + UI are equal partners** — Everything the UI can do, the agent can do, and vice versa. They share the same database and always stay in sync. You don't think about "the agent" and "the app" separately — you think about them together.
 2. **Context-aware** — The agent always knows what you're looking at. If an email is open, it knows which one. If you select text and hit Cmd+I, it can act on just that selection.
-3. **Skills-driven** — Core functionalities have instructions so the agent doesn't explore from scratch every time. When you add a feature, you update all four areas: UI, actions, skills/instructions, and application state.
+3. **Skills-driven** — Core functionality has written instructions so the agent doesn't explore from scratch every time. New features update all four areas: UI, actions, skills/instructions, and application state.
 4. **Inter-agent communication** — Agents can discover and call each other via the A2A protocol. Tag your analytics agent from the mail app to pull data into a draft.
 5. **Fully portable** — Any SQL database Drizzle supports, any hosting backend Nitro supports, any AI coding tool. These are non-negotiable.
 6. **Fork and customize** — Apps you clone and evolve. The agent can modify the app's own code — components, routes, styles, actions — so it gets better over time.

package/docs/content/mcp-clients.md

@@ -77,7 +77,20 @@ This means users who've installed the claude-in-chrome extension get browser con
 
 ## Remote MCP servers via the settings UI {#remote-via-ui}
 
-Users don't have to edit `mcp.config.json` to add a remote, HTTP-based MCP server (Zapier, Cloudflare, Composio, an internal tool, etc). Open the settings panel → **MCP Servers** and paste the server's URL. Two scopes are supported:
+MCP (Model Context Protocol) servers give your agent new abilities — like connecting to Zapier, Cloudflare, Composio, or your company's internal tools. Once connected, the agent can use those tools just like its built-in ones.
+
+### How to connect a remote MCP server
+
+1. **Server name** — a short label for your own reference (e.g. "zapier", "slack-tools").
+2. **URL** — the HTTPS endpoint the MCP server provider gave you (e.g. `https://mcp.zapier.com/s/abc123/mcp`). This is usually found in the provider's dashboard or integration docs.
+3. **Description** (optional) — a note about what this server does.
+4. **Headers** — authentication credentials the server requires, one per line. Most servers need an `Authorization` header. Example: `Authorization: Bearer sk-your-key-here`. The provider's docs will tell you what to put here.
+
+Click **Test** to verify the connection before saving. If it succeeds, you'll see the number of tools available. Click **Connect** to add it.
+
+### Personal vs Organization scope
+
+Two scopes are supported:
 
 - **Personal** — only the signed-in user gets the tools. Stored as a user-scope setting.
 - **Team** — everyone in the active organization gets the tools. Owners and admins can add; members see the list read-only. Stored as an org-scope setting.