@agent-native/core 0.7.52 → 0.7.53

package/docs/content/messaging.md

@@ -31,11 +31,15 @@ Connect your agent to Slack, email, Telegram, or WhatsApp so you can chat with i
    - `chat:write` — lets the agent send messages
    - `app_mentions:read` — lets the agent see when it's @-mentioned (optional)
    - `im:history` — lets the agent read DMs sent to it
+   - `assistant:write` — optional; lets Slack show native "is thinking..." status in assistant threads
+   - `users:read.email` — optional; helps templates such as Mail verify Slack sender email for draft-queue identity
 3. Click **Install to Workspace** at the top of that page. Slack will give you a **Bot User OAuth Token** that starts with `xoxb-`. Copy it.
 4. Go to **Basic Information** in the sidebar and copy the **Signing Secret**.
 5. Open your app's settings (or your hosting provider's environment variable panel) and paste:
    - `SLACK_BOT_TOKEN` — the `xoxb-…` token
    - `SLACK_SIGNING_SECRET` — the signing secret
+   - `SLACK_ALLOWED_TEAM_IDS` — recommended in production; comma-separated Slack workspace/team IDs allowed to send events
+   - `SLACK_ALLOWED_API_APP_IDS` — recommended for multi-workspace apps; comma-separated Slack app IDs allowed to use this signing secret
 6. Back in Slack, open **Event Subscriptions**, toggle it on, and paste this Request URL:
 
    ```text
@@ -51,6 +55,7 @@ Connect your agent to Slack, email, Telegram, or WhatsApp so you can chat with i
 - **Channel mentions** — the bot only responds in channels when it's @-mentioned, to avoid noise.
 - **DMs** — every DM is treated as a private conversation with the agent.
 - **Same identity, all channels** — if a Slack user has the same email as a registered user in your app, the agent treats them as the same person.
+- **Production allowlists** — set `SLACK_ALLOWED_TEAM_IDS` and, for shared Slack apps, `SLACK_ALLOWED_API_APP_IDS` so a valid signing secret cannot be reused by an unexpected workspace.
 
 ## Set up Telegram {#telegram}
 
@@ -252,12 +257,12 @@ POST /_agent-native/integrations/telegram/setup
 
 ### Environment variables {#env-vars}
 
-| Platform | Required                                                                     | Optional                       |
-| -------- | ---------------------------------------------------------------------------- | ------------------------------ |
-| Slack    | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                    | —                              |
-| Telegram | `TELEGRAM_BOT_TOKEN`                                                         | —                              |
-| Email    | `EMAIL_AGENT_ADDRESS`, plus one of `RESEND_API_KEY` or `SENDGRID_API_KEY`    | `EMAIL_INBOUND_WEBHOOK_SECRET` |
-| WhatsApp | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` | —                              |
+| Platform | Required                                                                     | Optional                                              |
+| -------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Slack    | `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`                                    | `SLACK_ALLOWED_TEAM_IDS`, `SLACK_ALLOWED_API_APP_IDS` |
+| Telegram | `TELEGRAM_BOT_TOKEN`                                                         | —                                                     |
+| Email    | `EMAIL_AGENT_ADDRESS`, plus one of `RESEND_API_KEY` or `SENDGRID_API_KEY`    | `EMAIL_INBOUND_WEBHOOK_SECRET`                        |
+| WhatsApp | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` | —                                                     |
 
 All credentials live in env vars — never the database, never source code. Use the sidebar settings UI or your hosting provider's env panel.
 

package/docs/content/multi-app-workspace.md

@@ -5,7 +5,7 @@ description: "Host many agent-native apps in one monorepo with shared auth, RBAC
 
 # Multi-App Workspaces
 
-> For what a workspace _is_ — the customization layer, AGENTS.md, learnings.md, skills, custom agents — see [Workspace](/docs/workspace). This page is about the **deployment shape**: hosting many agent-native apps in one monorepo with shared auth, components, and a unified deploy.
+> For what a workspace _is_ — the customization layer, `AGENTS.md`, `LEARNINGS.md`, personal memory, skills, and custom agents — see [Workspace](/docs/workspace). This page is about the **deployment shape**: hosting many agent-native apps in one monorepo with shared auth, components, and a unified deploy.
 
 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.
 
@@ -244,6 +244,6 @@ The workspace pattern is intentionally narrow. A few things it deliberately does
 
 ## See also {#see-also}
 
-- [Workspace](/docs/workspace) — the customization layer (AGENTS.md, learnings.md, skills, custom agents) every app in the workspace shares.
+- [Workspace](/docs/workspace) — the customization layer (`AGENTS.md`, `LEARNINGS.md`, personal memory, skills, custom agents) every app in the workspace shares.
 - [Workspace Governance](/docs/workspace-management) — branching, CODEOWNERS, PR review across many apps in one repo.
 - [Dispatch](/docs/dispatch) — the runtime control plane that typically lives inside a multi-app workspace as the secrets vault, integration catalog, and approvals hub.

package/docs/content/server.md

@@ -1,200 +1,184 @@
 ---
 title: "Server"
-description: "Nitro server layer with file-based routing, server plugins, SSE handlers, and production agent configuration."
+description: "Nitro server routes, plugins, framework-mounted routes, request context, and SQL-backed sync."
 ---
 
 # Server
 
-Agent-native apps use [Nitro](https://nitro.build) for the server layer. Nitro is included automatically via the `defineConfig()` Vite plugin — you get file-based API routing, server plugins, and deploy-anywhere presets out of the box.
+Agent-native apps use [Nitro](https://nitro.build) for server routes and plugins. Most product behavior should live in [Actions](/docs/actions); custom routes are for protocol surfaces that actions do not fit: uploads, streaming, public pages, webhooks, OAuth callbacks, and provider-specific APIs.
 
-## File-Based Routing {#file-based-routing}
+## File-Based Routes {#file-based-routes}
 
-API routes live in `server/routes/`. Nitro auto-discovers them based on file name and path:
+Routes live in `server/routes/` and Nitro maps filenames to methods and paths:
 
 ```text
 server/routes/
   api/
-    hello.get.ts          → GET  /api/hello
-    items/
-      index.get.ts        → GET  /api/items
-      index.post.ts       → POST /api/items
-      [id].get.ts         → GET  /api/items/:id
-      [id].delete.ts      → DELETE /api/items/:id
-      [id]/
-        archive.patch.ts  → PATCH /api/items/:id/archive
+    health.get.ts              -> GET  /api/health
+    uploads.post.ts            -> POST /api/uploads
+    webhooks/
+      stripe.post.ts           -> POST /api/webhooks/stripe
+  [...page].get.ts             -> SSR catch-all for public pages
 ```
 
-Each route file exports a default `defineEventHandler`:
+Each route exports a `defineEventHandler`:
 
 ```ts
-// server/routes/api/items/index.get.ts
+// server/routes/api/health.get.ts
 import { defineEventHandler } from "h3";
-import fs from "fs/promises";
-
-export default defineEventHandler(async () => {
-  const files = await fs.readdir("./data/items");
-  const items = await Promise.all(
-    files
-      .filter((f) => f.endsWith(".json"))
-      .map(async (f) =>
-        JSON.parse(await fs.readFile(`./data/items/${f}`, "utf-8")),
-      ),
-  );
-  return items;
-});
+
+export default defineEventHandler(() => ({
+  ok: true,
+  service: "my-template",
+}));
 ```
 
 ### Route naming conventions {#route-naming-conventions}
 
-| File name pattern  | HTTP method | Example path               |
-| ------------------ | ----------- | -------------------------- |
-| `index.get.ts`     | GET         | `/api/items`               |
-| `index.post.ts`    | POST        | `/api/items`               |
-| `[id].get.ts`      | GET         | `/api/items/:id`           |
-| `[id].patch.ts`    | PATCH       | `/api/items/:id`           |
-| `[id].delete.ts`   | DELETE      | `/api/items/:id`           |
-| `[...slug].get.ts` | GET         | `/api/items/* (catch-all)` |
+| File name pattern  | HTTP method | Example path                |
+| ------------------ | ----------- | --------------------------- |
+| `index.get.ts`     | GET         | `/api/items`                |
+| `index.post.ts`    | POST        | `/api/items`                |
+| `[id].get.ts`      | GET         | `/api/items/:id`            |
+| `[id].patch.ts`    | PATCH       | `/api/items/:id`            |
+| `[id].delete.ts`   | DELETE      | `/api/items/:id`            |
+| `[...slug].get.ts` | GET         | `/api/items/*` or catch-all |
 
-### Accessing route parameters {#accessing-route-parameters}
+## Prefer Actions For App Operations {#actions-first}
 
-```ts
-import { defineEventHandler, getRouterParam, readBody, getQuery } from "h3";
+If the UI and agent both need to do something, define an action instead of a custom API route. Actions automatically become:
 
-// GET /api/items/:id
-export default defineEventHandler(async (event) => {
-  const id = getRouterParam(event, "id");
-  const { filter } = getQuery(event);
-  // ...
-});
-```
+- Agent tools.
+- Typed frontend hooks.
+- HTTP endpoints under `/_agent-native/actions/:name`.
+- MCP and A2A-callable tools.
+- CLI commands for development.
 
-## Server Plugins {#server-plugins}
+Use custom `/api/*` routes only when you need a route-shaped protocol or binary/streaming behavior. See [Actions](/docs/actions).
 
-Cross-cutting concerns — file watchers, file sync, scheduled jobs, auth — go in `server/plugins/`. Nitro runs these at startup before serving requests:
+## Request Context And Access {#request-context}
+
+Actions mounted by the framework automatically run with request context. Custom routes do not. If a custom route reads or writes ownable resources, load the session and wrap the work:
 
 ```ts
-// server/plugins/file-sync.ts
-import { defineNitroPlugin } from "@agent-native/core";
-import { createFileSync } from "@agent-native/core/adapters/sync";
-
-export default defineNitroPlugin(async () => {
-  const result = await createFileSync({ contentRoot: "./data" });
-  if (result.status === "error") {
-    console.warn(`[app] File sync failed: ${result.reason}`);
+import { defineEventHandler } from "h3";
+import { getSession, runWithRequestContext } from "@agent-native/core/server";
+import { getDb } from "@agent-native/core/db";
+import { accessFilter } from "@agent-native/core/access";
+import * as schema from "../../db/schema";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session?.user?.email) {
+    throw new Response("Unauthorized", { status: 401 });
   }
+
+  return runWithRequestContext(
+    { userEmail: session.user.email, orgId: session.orgId },
+    async () => {
+      const db = getDb();
+      return db
+        .select()
+        .from(schema.projects)
+        .where(accessFilter(schema.projects, schema.projectShares));
+    },
+  );
 });
 ```
 
-## Shared State Between Plugins and Routes {#shared-state}
+Do not run unscoped `db.select().from(ownableTable)` in custom routes.
+
+## Server Plugins {#server-plugins}
 
-Use a shared module in `server/lib/` to pass state from plugins to route handlers:
+Plugins live in `server/plugins/` and run at startup. Use them for migrations, provider setup, recurring jobs, integration adapters, and framework plugin configuration.
 
 ```ts
-// server/lib/watcher.ts
-import { createFileWatcher } from "@agent-native/core";
-import type { SSEHandlerOptions } from "@agent-native/core";
-
-export const watcher = createFileWatcher("./data");
-export const sseExtraEmitters: NonNullable<SSEHandlerOptions["extraEmitters"]> =
-  [];
-
-export let syncResult: any = { status: "disabled" };
-export function setSyncResult(result: any) {
-  syncResult = result;
-  if (result.status === "ready" && result.sseEmitter) {
-    sseExtraEmitters.push(result.sseEmitter);
-  }
-}
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db/migrations";
+
+export default runMigrations([
+  {
+    id: "001_create_projects",
+    sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+  },
+]);
 ```
 
-The plugin populates the state at startup; route handlers read it at request time.
+Migrations must be additive. Never put destructive SQL in startup plugins.
 
-## createFileWatcher(dir, options?) {#createfilewatcher}
+## Framework-Mounted Routes {#framework-routes}
 
-Creates a chokidar file watcher for real-time file change detection:
-
-```ts
-import { createFileWatcher } from "@agent-native/core";
+The framework mounts its own routes under `/_agent-native/`. Treat that namespace as reserved.
 
-const watcher = createFileWatcher("./data");
-// watcher emits "all" events: (eventName, filePath)
-```
+| Route prefix                     | Purpose                              |
+| -------------------------------- | ------------------------------------ |
+| `/_agent-native/actions/:name`   | Action HTTP endpoints                |
+| `/_agent-native/agent-chat`      | Agent chat loop                      |
+| `/_agent-native/poll`            | SQL-backed UI sync                   |
+| `/_agent-native/resources/*`     | Workspace resources                  |
+| `/_agent-native/tools/*`         | Runtime tools and tool proxy         |
+| `/_agent-native/integrations/*`  | Messaging/webhook integrations       |
+| `/_agent-native/a2a`             | Agent-to-agent JSON-RPC              |
+| `/_agent-native/mcp`             | MCP endpoint                         |
+| `/_agent-native/onboarding/*`    | Setup checklist                      |
+| `/_agent-native/observability/*` | Traces, feedback, evals, experiments |
+| `/_agent-native/file-upload`     | File upload provider endpoint        |
 
-### Options {#filewatcher-options}
+Custom app routes should use `/api/*`, public app paths, or provider-specific callback paths that do not collide with `/_agent-native/`.
 
-| Option        | Type    | Description                                       |
-| ------------- | ------- | ------------------------------------------------- |
-| `ignored`     | any     | Glob patterns or regex to ignore                  |
-| `emitInitial` | boolean | Emit events for initial file scan. Default: false |
+## SQL-Backed Sync {#sync}
 
-## createSSEHandler(watcher, options?) {#createssehandler}
+Agent-native does not rely on filesystem watchers or sticky in-memory state. When actions or framework helpers mutate data, the database sync version increments. The client `useDbSync()` hook polls `/_agent-native/poll` and invalidates React Query caches.
 
-Creates an H3 event handler that streams file changes as Server-Sent Events:
+This works across serverless and multi-instance deployments because the database is the coordination point. If you write custom mutations outside actions, use framework helpers or emit the appropriate sync invalidation so open UIs refresh.
 
-```ts
-// server/routes/_agent-native/events.get.ts
-import { createSSEHandler } from "@agent-native/core";
-import { watcher, sseExtraEmitters } from "../../lib/watcher.js";
+## Webhooks {#webhooks}
 
-export default createSSEHandler(watcher, {
-  extraEmitters: sseExtraEmitters,
-  contentRoot: "./data",
-});
-```
+Inbound webhooks should verify, persist, and return quickly. Long-running agent work should use the integration queue pattern:
 
-Each SSE message is JSON: `{ "type": "change", "path": "data/file.json" }`
+1. Verify the platform signature or challenge.
+2. Insert durable work into SQL.
+3. Self-fire a signed processor route.
+4. Return 200 immediately.
+5. Let the fresh processor execution run the agent loop and post the result.
 
-### Options {#ssehandler-options}
+Do not rely on unawaited promises after returning a response. See [Messaging](/docs/messaging) for the canonical integration queue.
 
-| Option        | Type                        | Description                                       |
-| ------------- | --------------------------- | ------------------------------------------------- |
-| extraEmitters | `Array<{ emitter, event }>` | Additional EventEmitters to stream                |
-| contentRoot   | string                      | Root directory used to relativize paths in events |
+## Programmatic H3 Servers {#create-server}
 
-## createServer(options?) {#createserver}
-
-Optional helper that creates a pre-configured H3 app with CORS middleware and a health-check route. Returns `{ app, router }`. Useful for programmatic route registration when file-based routing doesn't fit:
+For custom packages or tests that need an H3 app directly, `createServer()` returns a preconfigured app and router:
 
 ```ts
-import { createServer } from "@agent-native/core";
+import { createServer } from "@agent-native/core/server";
 import { defineEventHandler } from "h3";
 
 const { app, router } = createServer();
-router.get("/api/items", defineEventHandler(listItems));
-```
-
-## mountAuthMiddleware(app, accessToken) {#mountauthmiddleware}
-
-Mounts session-cookie authentication onto an H3 app. Serves a login page for unauthenticated browser requests and returns 401 for unauthenticated API requests.
 
-```ts
-import { mountAuthMiddleware } from "@agent-native/core";
-
-mountAuthMiddleware(app, process.env.ACCESS_TOKEN!);
+router.get(
+  "/api/health",
+  defineEventHandler(() => ({ ok: true })),
+);
 ```
 
-Adds two routes automatically: `POST /api/auth/login` and `POST /api/auth/logout`.
+Most templates do not need this helper because Nitro file routes and framework plugins handle the app server.
 
-## createProductionAgentHandler(options) {#createproductionagenthandler}
+## Production Agent Handler {#agent-handler}
 
-Creates an H3 SSE handler at `POST /_agent-native/agent-chat` that runs an agentic tool loop using Claude. Each script's `run()` function is registered as a tool the agent can invoke.
+The framework's agent chat plugin mounts the production agent handler for templates. Only call `createProductionAgentHandler()` directly when building a custom server integration outside the standard template plugin stack.
 
 ```ts
-import { createProductionAgentHandler } from "@agent-native/core";
-import { scripts } from "./scripts/registry.js";
-import { readFileSync } from "fs";
+import { createProductionAgentHandler } from "@agent-native/core/server";
 
-const agent = createProductionAgentHandler({
+const handler = createProductionAgentHandler({
   scripts,
-  systemPrompt: readFileSync("agents/system-prompt.md", "utf-8"),
+  systemPrompt: "You are the app agent...",
 });
 ```
 
-### Options {#agent-handler-options}
-
-| Option         | Type                          | Description                                       |
-| -------------- | ----------------------------- | ------------------------------------------------- |
-| `scripts`      | `Record<string, ScriptEntry>` | Map of script name → { tool, run } entries        |
-| `systemPrompt` | string                        | System prompt for the embedded agent              |
-| `apiKey`       | string                        | Anthropic API key. Default: ANTHROPIC_API_KEY env |
-| `model`        | string                        | Model to use. Default: claude-sonnet-4-6          |
+Standard templates should customize the agent through `AGENTS.md`, skills, actions, and the agent chat plugin rather than hand-mounting this route.

package/docs/content/skills-guide.md

@@ -53,7 +53,7 @@ Create a skill when:
 Don't create a skill when:
 
 - The guidance already exists in another skill — extend it instead
-- The guidance is a one-off — put it in `AGENTS.md` or `learnings.md` instead
+- The guidance is a one-off — put it in `AGENTS.md` or workspace memory instead
 
 ## Skill format {#skill-format}
 
@@ -110,6 +110,6 @@ Save the file at `.agents/skills/my-skill/SKILL.md`. The directory name should m
 
 > **Skills** — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.
 >
-> **Memory (`learnings.md`)** — Per-user notes the agent writes automatically from corrections and preferences. Loaded every turn.
+> **Memory (`LEARNINGS.md` / `memory/MEMORY.md`)** — Shared project learnings and personal structured memory loaded every turn.
 
-If the knowledge applies to _everyone_ working in the app ("always prefer CTEs over subqueries"), it's a skill. If it's about _this particular user_ ("Steve likes concise answers"), it belongs in `learnings.md` — and the agent will put it there itself the next time you correct it. See [Agent Memory (`learnings.md`)](./resources.md#learnings-md) for the full treatment.
+If the knowledge applies to _everyone_ working in the app ("always prefer CTEs over subqueries"), it's a skill or shared `LEARNINGS.md`. If it's about _this particular user_ ("Steve likes concise answers"), it belongs in `memory/MEMORY.md`. See [Workspace Memory](/docs/workspace#memory) for the full treatment.

package/docs/content/template-analytics.md

@@ -5,7 +5,7 @@ description: "Ask analytics questions in plain English, get charts and dashboard
 
 # Analytics
 
-Ask analytics questions in plain English, get charts and dashboards back. The agent connects to BigQuery, GA4, your app database, HubSpot, Jira, and a dozen other sources, writes the SQL for you, validates it, and renders the answer as a chart, table, or saved dashboard panel.
+Ask analytics questions in plain English, get charts and dashboards back. The agent connects to BigQuery, GA4, Amplitude, the built-in first-party event collector, HubSpot, Jira, and a dozen other sources, writes the query for you, validates it, and renders the answer as a chart, table, or saved dashboard panel.
 
 It's an open-source replacement for Amplitude, Mixpanel, and Looker — for teams that want to own the code, the queries, and the data.
 
@@ -26,7 +26,7 @@ When you first open the app:
 
 1. Sign in with Google.
 2. Open the **Data Sources** page from the sidebar.
-3. Each source has a walkthrough — connect the ones you need (start with one, like BigQuery or your app DB).
+3. Each source has a walkthrough — connect the ones you need (start with one, like BigQuery, GA4, Amplitude, or first-party tracking).
 4. Open a new chat with the agent and ask a question: "How many signups did we get last week?"
 
 The first question is enough to confirm the connection works. From there, ask the agent to "save this as a dashboard" or "build a 4-panel overview dashboard for our key metrics."
@@ -62,7 +62,7 @@ The rest of this doc is for anyone forking the Analytics template or extending i
 Create a new Analytics app from the CLI:
 
 ```bash
-npx @agent-native/cli create analytics
+pnpm dlx @agent-native/core create my-analytics --template analytics --standalone
 ```
 
 Local dev:
@@ -73,13 +73,13 @@ pnpm install
 pnpm dev
 ```
 
-The app runs at `http://localhost:3000`. Sign in with Google, then open the **Data Sources** page to connect BigQuery, HubSpot, Jira, and the rest.
+The CLI prints the local dev URL. Sign in with Google, then open the **Data Sources** page to connect BigQuery, GA4, first-party tracking, HubSpot, Jira, and the rest.
 
 ### Key features (technical)
 
 **Natural-language chart generation.** Ask the agent in plain English. It picks the right data source, writes the SQL, validates it against the warehouse, and renders the chart inline in chat or as a saved panel. Chart types: `line`, `area`, `bar`, `metric`, `table`, `pie`.
 
-**Reusable SQL dashboards.** Dashboards are a named config with an array of panels. Each panel has an `id`, `title`, `sql`, `source` (`bigquery` / `app-db` / `ga4`), `chartType`, and `width` (1 or 2 columns). See the full shape in `templates/analytics/app/pages/adhoc/sql-dashboard/types.ts`.
+**Reusable SQL dashboards.** Dashboards are a named config with an array of panels. Each panel has an `id`, `title`, `sql`, `source` (`bigquery` / `ga4` / `amplitude` / `first-party`), `chartType`, and `width` (1 or 2 columns). See the full shape in `templates/analytics/app/pages/adhoc/sql-dashboard/types.ts`.
 
 Dashboards support:
 
@@ -92,7 +92,9 @@ Dashboards support:
 
 **Living data dictionary.** Canonical catalog of metrics — metric name, definition, table, columns, SQL template, known gotchas, owner, and data lag. The agent reads it before writing any SQL, so it uses the real warehouse column names (`hs_is_closed`, not guessed `is_closed`) and knows about caveats like "excludes internal emails". Seeded by asking the agent to import definitions from an existing source (dbt descriptions, a Notion page, a team wiki).
 
-**SQL query explorer.** Direct SQL against BigQuery or the app DB from the **Ad-hoc** view. Useful for iterating on a query before saving it as a dashboard panel.
+**SQL query explorer.** Direct queries against BigQuery and supported analytics backends from the **Ad-hoc** view. Useful for iterating before saving a dashboard panel.
+
+**First-party analytics collector.** Hosted apps can send product and template events to `/track` with a public write key. Query those events through `query-agent-native-analytics` or dashboard panels with `source: "first-party"`.
 
 **Multiple data connectors.** Built-in actions for common sources:
 

package/docs/content/template-design.md

@@ -1,32 +1,30 @@
 ---
 title: "Design"
-description: "An Agent-native design tool — sketch a UI, brand kit, or marketing visual by prompt or by hand, with the agent as your co-designer."
+description: "An agent-native HTML prototyping studio — generate, refine, preview, and export interactive Alpine/Tailwind designs with an agent."
 ---
 
 # Design
 
-A design tool where the agent is a real collaborator. Sketch a UI, a brand kit, or a marketing visual by prompt or by hand, and the agent generates layouts, suggests color systems, swaps fonts, and adjusts spacing alongside you on the same canvas.
+Design is an agent-native HTML prototyping studio. Instead of a layered drawing canvas, the agent generates complete self-contained Alpine/Tailwind HTML prototypes, renders them in an iframe, and lets you refine the result with prompts and tweak controls.
 
-Think along the lines of Figma or Canva, but the agent has full edit rights — it can move shapes, restyle layers, and generate new artwork from a description, all in the same canvas you're working in.
+Use it when you want a polished landing page concept, product UI direction, brand exploration, or interactive prototype that can leave the tool as real HTML.
 
-## What you can do with it
+## What You Can Do With It
 
-- **Prompt-driven design.** Describe what you want — "a hero section for a B2B fintech SaaS, dark mode, brand color #14B8A6" — and the agent drafts it on the canvas.
-- **Edit by hand or by chat.** Drag, resize, recolor with the toolbar; or ask the agent to "tighten the spacing", "swap the headline font for something more editorial", "make every CTA the brand teal".
-- **AI image generation built in.** Generate background art, illustrations, or icons inline. Re-run with refined prompts without leaving the canvas.
-- **Brand-aware.** Save a brand kit (colors, fonts, voice). The agent applies it consistently across new artwork.
-- **Components and frames.** Reusable components, multi-page documents, and export to PNG/SVG/PDF.
-- **Agent context awareness.** When a layer is selected, the agent knows what you've selected and can act on just that piece.
+- **Generate complete prototypes.** Describe the screen or page you need and the agent creates a working HTML document with Tailwind styling and Alpine interactions.
+- **Compare variants.** Start with multiple directions, pick the strongest one, then continue refining.
+- **Tweak visually.** Use the built-in tweak controls for common changes, or ask the agent for copy, layout, color, spacing, and interaction updates.
+- **Apply design systems.** Save and reuse design-system preferences so generated work stays closer to your brand.
+- **Import references.** Bring in existing HTML or reference material as context for a new design pass.
+- **Export real files.** Export HTML, ZIP, or PDF from the generated prototype.
 
-## Why it's interesting
+## Why It's Interesting
 
-Three things make Design a good showcase of what agent-native enables:
+Design is useful because the agent edits an artifact that is already close to shippable web UI. There is no separate "AI mockup" format to translate later: the preview, the editable source, and the exported artifact all come from the same HTML.
 
-1. **The agent edits the canvas directly.** Layers, frames, styles — the agent calls the same actions the toolbar does. There's no "AI mode" separate from the design tool; they're the same tool.
-2. **Selection-aware editing.** Select a button and ask "make this the brand teal across all pages" — the agent knows which element you mean and propagates the change.
-3. **Designs you own.** The files live in your SQL, the artwork lives in your storage, the agent is yours. Fork the template, plug in a different image-generation provider, integrate your team's component library — it's your code.
+The template is also a good example of agent-native ownership. The app stores designs in SQL, exposes template operations as actions, and lets you fork the whole workflow when your team needs a different renderer, exporter, or design-system model.
 
-## For developers
+## For Developers
 
 The rest of this doc is for anyone forking the Design template or extending it.
 
@@ -36,20 +34,20 @@ The rest of this doc is for anyone forking the Design template or extending it.
 pnpm dlx @agent-native/core create my-design --template design --standalone
 ```
 
-### Customize it
+### Customize It
 
-Design is a full cloneable SaaS — fork it and ask the agent to extend it. Some examples:
+Design is a cloneable SaaS template. Some practical extension ideas:
 
-- "Add a 'Generate variations' button that produces five color-swap alternatives for the selected frame."
-- "Wire the brand kit to read from our marketing-site repo so colors stay in sync."
-- "Add a comments layer with @-mentions and email notifications."
-- "Auto-export every published frame as a 1200×630 OG image and upload to our CDN."
-- "Let me drop a Figma link in chat and have the agent re-create it as native components here."
+- "Add a reusable ecommerce design system with our tokens and sample components."
+- "Add an export step that uploads the ZIP to our internal review system."
+- "Let me paste existing landing-page HTML and ask the agent for three stronger versions."
+- "Add a saved prompt library for product-page, dashboard, and onboarding-screen briefs."
+- "Add a custom PDF export preset for stakeholder review."
 
-The agent edits routes, components, canvas actions, and the schema as needed. See [Cloneable SaaS](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [Getting Started](/docs/getting-started) if this is your first agent-native template.
+The agent edits routes, components, actions, and SQL-backed models as needed. See [Cloneable SaaS](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [Getting Started](/docs/getting-started) if this is your first agent-native template.
 
-## What's next
+## What's Next
 
 - [**Cloneable SaaS**](/docs/cloneable-saas) — the clone-and-own model
-- [**Context Awareness**](/docs/context-awareness) — how the agent knows the selected layer
-- [**Tools**](/docs/tools) — generate one-off image-creation utilities alongside the canvas
+- [**Context Awareness**](/docs/context-awareness) — how the agent knows what the user is viewing
+- [**Creating Templates**](/docs/creating-templates) — current build patterns for agent-native templates