@agent-native/core 0.7.12 → 0.7.14

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 [Enterprise Workspace](/docs/enterprise-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/key-concepts.md

@@ -270,4 +270,4 @@ For detailed guidance on specific patterns:
 - [Context Awareness](/docs/context-awareness) — navigation state, view-screen, navigate commands
 - [Skills Guide](/docs/skills-guide) — framework skills, domain skills, creating custom skills
 - [A2A Protocol](/docs/a2a-protocol) — agent-to-agent communication
-- [Enterprise Workspace](/docs/enterprise-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials
+- [Multi-App Workspace](/docs/multi-app-workspace) — host many apps in one monorepo with shared auth, skills, components, and credentials

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.