@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/docs/content/enterprise-workspace.md

@@ -0,0 +1,235 @@
+---
+title: "Enterprise Workspace"
+description: "Host many agent-native apps in one monorepo with shared auth, RBAC, skills, instructions, components, and credentials."
+---
+
+# Enterprise Workspace
+
+When vibe-coding an internal tool takes an afternoon, you don't stop at one. A team ends up with a CRM, a support inbox, a dashboard, a recruiting tracker, an ops console — ten small apps, each scaffolded independently. That's great until you need to change something in all of them.
+
+At that point every app has its own `AGENTS.md`, its own auth plugin, its own copy-pasted layout component, its own hard-coded Slack token, its own idea of what an "organization" is. A compliance rule change means ten PRs. Rotating an API key means ten redeployments. A brand refresh means ten different headers drifting out of sync. The thing that made it easy to build them is now making it hard to manage them.
+
+The **enterprise workspace** pattern is how agent-native solves this. You host all your apps in one monorepo alongside a private **workspace core** package. The core owns everything cross-cutting — auth, RBAC, agent skills, `AGENTS.md`, React components, design tokens, shared credentials, shared actions. Each app shrinks down to the handful of screens that make it unique. Change the core once; every app inherits the change on the next dev reload.
+
+## What gets shared {#what-gets-shared}
+
+Anything every app in your org should agree on lives in the workspace core:
+
+| Shared thing                  | Where it lives in the core                                                   |
+| ----------------------------- | ---------------------------------------------------------------------------- |
+| Auth (login, session, social) | `src/server/auth-plugin.ts`                                                  |
+| Org / RBAC rules              | Better Auth organizations, optionally wrapped in `src/server/auth-plugin.ts` |
+| Agent chat system prompt      | `src/server/agent-chat-plugin.ts`                                            |
+| Enterprise agent instructions | `AGENTS.md`                                                                  |
+| Agent skills                  | `skills/<skill-name>/SKILL.md`                                               |
+| Shared agent actions          | `actions/*.ts`                                                               |
+| Shared React components       | `src/client/*.tsx` (e.g. `AuthenticatedLayout`)                              |
+| Design tokens / brand         | `tailwind.preset.ts`                                                         |
+| Shared API credentials        | `src/credentials.ts` → `resolveCompanyCredential()`                          |
+
+Each individual app becomes _just a set of screens_ — routes, dashboards, views, domain-specific actions. Everything else is inherited. If you're building ten tools for the same org, nine of them are 80% the same package, and the workspace core is where that 80% lives.
+
+## Getting started {#getting-started}
+
+Workspace is the default shape of an agent-native project. Scaffold one with:
+
+```bash
+pnpm dlx @agent-native/core create my-company-platform
+```
+
+The CLI shows a multi-select picker of every first-party template. Pick as many as you want — Mail + Calendar + Forms, for example — and they all get scaffolded into the same workspace sharing auth, brand, and agent config.
+
+You get a pnpm monorepo with the private core package, a root `package.json` that wires up workspace discovery, a shared `.env`, and one sub-directory per app you picked:
+
+```text
+my-company-platform/
+├── package.json                 # declares agent-native.workspaceCore
+├── pnpm-workspace.yaml          # packages: ["packages/*", "apps/*"]
+├── .env.example                 # shared ANTHROPIC_API_KEY, BUILDER_PRIVATE_KEY,
+│                                # A2A_SECRET, DATABASE_URL, ...
+├── packages/
+│   └── core-module/             # @my-company-platform/core-module
+│       ├── src/
+│       │   ├── server/          # auth / agent-chat plugin overrides
+│       │   ├── client/          # shared React components
+│       │   └── credentials.ts   # resolveCompanyCredential()
+│       ├── actions/             # shared agent-callable actions
+│       ├── skills/              # shared agent skills
+│       ├── AGENTS.md            # enterprise-wide instructions
+│       └── tailwind.preset.ts   # brand tokens
+└── apps/
+    ├── mail/
+    ├── calendar/
+    └── forms/
+```
+
+Then boot it:
+
+```bash
+cd my-company-platform
+cp .env.example .env             # fill in ANTHROPIC_API_KEY, BETTER_AUTH_SECRET, ...
+pnpm install
+pnpm dev                         # runs every app
+```
+
+Every app renders through `<AuthenticatedLayout>` from the core. Every agent chat already sees the shared `AGENTS.md` and skills. Every app already knows how to log in and can call shared actions. You didn't wire any of that up — the framework auto-discovered the core via the `agent-native.workspaceCore` field in the root `package.json`:
+
+```json
+{
+  "name": "my-company-platform",
+  "agent-native": {
+    "workspaceCore": "@my-company-platform/core-module"
+  }
+}
+```
+
+## Adding another app {#adding-a-new-app}
+
+From anywhere inside the workspace:
+
+```bash
+agent-native add-app
+```
+
+The CLI shows the template picker again with apps you've already installed filtered out. Pick one or more and they get scaffolded under `apps/`. Non-interactive variant:
+
+```bash
+agent-native add-app crm --template content
+```
+
+Any first-party template works as a workspace app — the CLI runs a small **workspacify** transform on the template that adds the workspace core as a dep and resolves `workspace:*` references. No parallel "workspace-app" scaffold to maintain.
+
+```bash
+pnpm install                     # at the workspace root
+pnpm --filter crm dev
+```
+
+That's it. The new app has the same login as every other app in the workspace, the same agent instructions, the same brand, the same actions, the same shared credentials. All you add is the domain-specific screens.
+
+## What you override where {#layering}
+
+Agent-native apps inside a workspace resolve cross-cutting behavior from three places, in this order:
+
+1. **App local** — files inside `apps/<name>/` (highest priority)
+2. **Workspace core** — files inside `packages/core-module/` (the shared mid-layer)
+3. **Framework default** — `@agent-native/core` (lowest)
+
+The merge happens by file name. If an app provides a local file that also exists upstream, the local one wins. If it doesn't, the workspace core's version applies. If the core doesn't provide one either, the framework default kicks in. This applies to plugins, skills, actions, and `AGENTS.md`.
+
+When one app needs something different, drop a local file:
+
+| Thing to override             | File to create inside the app                       |
+| ----------------------------- | --------------------------------------------------- |
+| Auth plugin                   | `apps/<name>/server/plugins/auth.ts`                |
+| Agent-chat plugin             | `apps/<name>/server/plugins/agent-chat.ts`          |
+| A specific skill              | `apps/<name>/.agents/skills/<skill-name>/SKILL.md`  |
+| A specific action             | `apps/<name>/actions/<action-name>.ts`              |
+| Additional agent instructions | `apps/<name>/AGENTS.md` (merges with workspace one) |
+
+No wiring, no config. Create the file and it takes over.
+
+## Editing shared behavior {#editing-shared-behavior}
+
+Everything cross-cutting lives in `packages/core-module/`. Change `src/server/auth-plugin.ts` and every app in the workspace picks it up on the next dev reload. Add a new file to `skills/` and every app's agent instantly has access to the new skill. Add an action to `actions/` and every app's agent can call it.
+
+Because the core is a `workspace:*` dependency, pnpm symlinks it into each app's `node_modules/`. You never build or publish it — the apps bundle whatever they need from it at build time.
+
+## Authentication and RBAC {#auth-and-rbac}
+
+Every agent-native app already ships with [Better Auth](/docs/authentication) and its organizations plugin — users, organizations, members, and the `owner` / `admin` / `member` roles are all first-class, shared across every template. In a workspace, you get that for free in every app, backed by the same database.
+
+For enterprise-specific rules (allow-list domains, SSO enforcement, extra role checks), wrap the framework auth plugin in `src/server/auth-plugin.ts` and re-export it. Every app in the workspace now enforces those rules.
+
+Active organization flows automatically: `session.orgId` → `AGENT_ORG_ID` → SQL row scoping, so data tagged with `org_id` is invisible to other orgs even to the agent. See [Security & Data Scoping](/docs/security) for the full model.
+
+## Shared environment variables {#shared-env}
+
+The workspace root `.env` is loaded into every app automatically. Put shared keys once at the root — `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET`, `DATABASE_URL`, `BUILDER_PRIVATE_KEY`, etc. — and every app picks them up. Per-app overrides go in `apps/<name>/.env` and win on conflict.
+
+```text
+my-company-platform/
+├── .env                           # shared: ANTHROPIC_API_KEY=... , A2A_SECRET=... , ...
+└── apps/
+    └── mail/
+        └── .env                   # optional overrides just for mail
+```
+
+A few onboarding flows are workspace-aware out of the box:
+
+- **Builder `/cli-auth`**: clicking "Connect Builder" from any app writes `BUILDER_PRIVATE_KEY` and friends to the **workspace root** `.env`, so every app gains browser access at once.
+- **Env-vars settings route** (`POST /_agent-native/env-vars`): when inside a workspace, defaults to writing the workspace root `.env`. Pass `scope: "app"` in the body to override one app.
+
+## Shared credentials {#shared-credentials}
+
+Rotate a third-party API key in one place and every app picks it up:
+
+```ts
+import { resolveCompanyCredential } from "@my-company-platform/core-module/credentials";
+
+const slackToken = await resolveCompanyCredential("SLACK_BOT_TOKEN");
+```
+
+Under the hood this wraps `@agent-native/core`'s `resolveCredential()`, which checks `process.env` first and then falls back to the shared `settings` table. Apps in the same workspace point at the same `DATABASE_URL` by default, so storing a credential in settings once makes it available to every app — no per-app config.
+
+## Shared design tokens {#design-tokens}
+
+The core exports a Tailwind preset. Each app's `tailwind.config.ts` extends it:
+
+```ts
+import preset from "@my-company-platform/core-module/tailwind";
+
+export default {
+  presets: [preset],
+  content: ["./app/**/*.{ts,tsx}"],
+};
+```
+
+Brand colors, typography, spacing scales, and any shared component classes live in one file. Update it in the core and every app rebrands on the next build. Shared React components in `src/client/` pick up the same tokens automatically.
+
+## Deployment {#deployment}
+
+You have two options: **unified deploy** (the default for workspaces) or per-app independent deploy.
+
+### Unified deploy (recommended)
+
+One command builds every app in the workspace and ships them behind a single origin, one path per app:
+
+```bash
+agent-native deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+Each app is built with `APP_BASE_PATH=/<name>` and emitted into `dist/<name>/`. A dispatcher worker at `dist/_worker.js` routes each path to the matching app, and a `_routes.json` manifest tells Cloudflare Pages which paths to treat as dynamic.
+
+Being on the **same origin** is where the real payoff lives:
+
+- **Shared login session.** Better Auth sets its cookie on the apex domain, so logging into any app logs you into every app. No cross-domain SSO dance.
+- **Zero-config cross-app A2A.** `@mail` tagging `@calendar` becomes a same-origin fetch — no CORS, no JWT signing between siblings. External A2A still uses JWT as today.
+- **One DNS record, one cert, one CDN cache.**
+
+Publish the `dist/` output:
+
+```bash
+wrangler pages deploy dist
+```
+
+### Per-app independent deploy
+
+Prefer each app on its own domain (`mail.company.com`, `calendar.company.com`)? Every app in the workspace is still an independent deployable — `cd apps/mail && agent-native build` behaves exactly like a standalone scaffold. Cross-app A2A then goes through the standard JWT-signed path with a shared `A2A_SECRET`.
+
+### Shared database, shared credentials
+
+Whatever you pick, point every app at the same `DATABASE_URL` for cross-app state out of the box: one set of user accounts, one set of organizations, one set of shared settings. If each app has its own database, the workspace pattern still works — you just lose that shared-state story.
+
+The workspace core itself is never built or deployed standalone. It's a `workspace:*` dep that pnpm symlinks into each app's `node_modules/`, so every app transparently bundles whatever it needs from the core at build time.
+
+## Out of scope (for now) {#out-of-scope}
+
+The workspace pattern is intentionally narrow. A few things it deliberately doesn't handle yet:
+
+- **Cross-domain SSO.** The unified `agent-native deploy` flow solves the common case (one origin, many apps at `/mail`, `/calendar`, …). If you need `mail.company.com` and `calendar.company.com` on _different_ domains to share a session, that requires a shared cookie domain or a central auth app with OAuth redirects — both supported by the underlying stack but neither scaffolded out of the box.
+- **Encrypted credential vault.** Shared credentials live in the `settings` table as plain text today. Rotate responsibly.
+- **Publishing the core to private npm.** The core is `workspace:*` only; multi-repo sharing via a private registry is doable but not scaffolded.
+- **Opinionated component library.** The core is where _you_ put shared components. The framework doesn't force shadcn/ui or any other system into that slot.

package/docs/content/faq.md

@@ -0,0 +1,101 @@
+---
+title: "FAQ"
+description: "Frequently asked questions about agent-native apps, development, architecture, and templates."
+---
+
+# FAQ
+
+Frequently asked questions about agent-native apps, development, and the framework.
+
+## General {#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.
+
+### 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}
+
+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.
+
+### Is this open source? {#is-this-open-source}
+
+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.
+
+## Development {#development}
+
+### Which AI coding tools work with agent-native? {#which-ai-tools-work}
+
+Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard and auto-creates symlinks for specific tools:
+
+- **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
+
+### Can I use my own database? {#can-i-use-my-own-database}
+
+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.
+
+### 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).
+
+### 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}
+
+### Why polling instead of WebSockets? {#why-polling-not-websockets}
+
+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}
+
+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.
+
+## 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.
+
+### Can agents talk to each other? {#can-agents-talk-to-each-other}
+
+Yes, via the [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Every agent-native app automatically gets an A2A endpoint. From the mail app, you can tag the analytics agent to query data. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI. No configuration needed — the agent card is auto-generated from your template's actions.
+
+### 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).
+
+## Templates {#templates}
+
+### What templates are available? {#what-templates-are-available}
+
+The framework ships with production-ready templates that you can use as daily drivers:
+
+- **[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)
+
+Each template is a complete app with UI, agent actions, database schema, and AI instructions. See all [Templates](/templates).
+
+### Can I customize templates? {#can-i-customize-templates}
+
+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 from scratch without a template? {#can-i-build-from-scratch}
+
+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).

package/docs/content/file-uploads.md

@@ -0,0 +1,102 @@
+---
+title: "File Uploads"
+description: "Configure file upload storage — SQL fallback for dev, Builder.io or custom providers for production."
+---
+
+# File Uploads
+
+The framework provides a file upload abstraction that routes uploads through a configurable provider. Templates call `uploadFile()` and get back a URL — the storage backend is swappable without changing application code.
+
+## How It Works {#how-it-works}
+
+Upload requests go to `POST /_agent-native/file-upload`, which dispatches to the active provider. You can check which provider is configured at `GET /_agent-native/file-upload/status`.
+
+The provider resolution order is:
+
+1. **User-registered providers** — custom providers registered via `registerFileUploadProvider()`
+2. **Builder.io provider** — built-in, activates automatically when Builder.io is connected
+3. **SQL fallback** — stores files as base64 in the database (fine for dev, not for production)
+
+## Default: SQL Fallback {#sql-fallback}
+
+When no provider is configured, files are stored as base64 data in the SQL database via the resources system. This works out of the box for local development but is not recommended for production — large files bloat the database and there's no CDN.
+
+A one-time warning is logged when the fallback is used.
+
+## Builder.io Hosting {#builder-hosting}
+
+When your app is connected to Builder.io, file uploads are automatically routed to Builder's asset hosting. Files are served from a CDN with no configuration needed. This is the recommended production setup.
+
+## Custom Providers {#custom-providers}
+
+Register a custom provider in a server plugin to use any storage backend (S3, Cloudflare R2, GCS, etc.):
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## Upload API {#upload-api}
+
+The `FileUploadProvider` interface:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+Use `uploadFile()` from `@agent-native/core/file-upload` in actions or server code:
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

package/docs/content/frames.md

@@ -0,0 +1,47 @@
+---
+title: "Frames"
+description: "Embedded agent panel and cloud frame options for running AI agents alongside your app."
+---
+
+# Frames
+
+Agent-native apps run with an AI agent alongside the app UI. Locally, the agent panel is embedded directly in your app. In the cloud, Builder.io provides a managed frame with collaboration and visual editing.
+
+## Embedded Agent Panel {#embedded-agent}
+
+- Ships with `@agent-native/core` — no separate package needed
+- Agent panel embedded directly in your app with chat and optional CLI terminal
+- Supports multiple AI coding CLIs — switch between them from the settings panel
+- Toggle between production mode (app tools only) and development mode (full filesystem, shell, and database access)
+- Great for local development, self-hosted production, and OSS
+
+## Supported CLIs {#supported-clis}
+
+| CLI         | Command    | Key Flags                                           |
+| ----------- | ---------- | --------------------------------------------------- |
+| Claude Code | `claude`   | --dangerously-skip-permissions, --resume, --verbose |
+| Codex       | `codex`    | --full-auto, --quiet                                |
+| Gemini CLI  | `gemini`   | --sandbox                                           |
+| OpenCode    | `opencode` | —                                                   |
+| Builder.io  | `builder`  | —                                                   |
+
+Switch between CLIs at any time from the agent panel settings. The terminal restarts with the selected CLI.
+
+## [Builder.io Cloud](https://www.builder.io) {#cloud-frame}
+
+- Runs in the cloud
+- Real-time collaboration — multiple users can watch/interact simultaneously
+- Visual editing, roles and permissions
+- Parallel agent execution for faster iteration
+- Great for team use
+
+## How It Works {#how-it-works}
+
+The framework provides type-safe APIs so you never deal with raw messaging:
+
+1. **Agent chat** — use `sendToAgentChat()` to send messages to the agent
+2. **Generation state** — use `useAgentChatGenerating()` to track when the agent is running
+3. **File watching** — SSE endpoint keeps UI in sync when the agent modifies files
+4. **Action system** — `pnpm action <name>` dispatches to callable actions
+
+Your app code is identical regardless of how the agent is provided.

package/docs/content/getting-started.md

@@ -0,0 +1,104 @@
+---
+title: "Getting Started"
+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 customize it. Templates are complete, production-ready apps — not starter kits. You get a working app in under a minute and start making it yours.
+
+## Create Your Workspace {#create-your-app}
+
+```bash
+npx @agent-native/core create my-platform
+```
+
+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:
+
+```bash
+cd my-platform
+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.
+
+Want a single app with no monorepo? Pass `--standalone`:
+
+```bash
+npx @agent-native/core create my-app --standalone --template mail
+```
+
+Need to add more apps later? From inside the workspace:
+
+```bash
+agent-native add-app
+```
+
+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.
+
+## Templates {#templates}
+
+Each template is a complete app with UI, agent actions, database schema, and AI instructions ready to go:
+
+| Template                          | Replaces                    |
+| --------------------------------- | --------------------------- |
+| [Mail](/templates/mail)           | Superhuman, Gmail           |
+| [Calendar](/templates/calendar)   | Google Calendar, Calendly   |
+| [Content](/templates/content)     | Notion, Google Docs         |
+| [Slides](/templates/slides)       | Google Slides, Pitch        |
+| [Video](/templates/video)         | video editing               |
+| [Analytics](/templates/analytics) | Amplitude, Mixpanel, Looker |
+
+Browse the [template gallery](/templates) for live demos and detailed feature lists.
+
+## Project Structure {#project-structure}
+
+Every agent-native app — whether from a template or from scratch — follows the same structure:
+
+```text
+my-app/
+  app/             # React frontend (routes, components, hooks)
+  server/          # Nitro API server (routes, plugins)
+  actions/         # Agent-callable actions
+  .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" }
+```
+
+```ts
+// tailwind.config.ts
+import type { Config } from "tailwindcss";
+import preset from "@agent-native/core/tailwind";
+
+export default {
+  presets: [preset],
+  content: ["./app/**/*.{ts,tsx}"],
+} satisfies Config;
+```
+
+## Architecture Principles {#architecture-principles}
+
+These principles apply to all agent-native apps. Understanding them helps you customize templates or build from scratch:
+
+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.
+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.