@agent-native/core 0.7.51 → 0.7.53

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

package/docs/content/template-dispatch.md

@@ -5,6 +5,8 @@ description: "Dispatch is the workspace control plane — central inbox, cross-a
 
 # Dispatch
 
+> **See also:** for the conceptual overview of what Dispatch does and when you want it, see [Dispatch](/docs/dispatch). This page is the template-specific reference.
+
 Dispatch is the **workspace control plane**. Where other templates are domain apps (Mail, Calendar, Analytics), Dispatch is the app you run _alongside_ them to coordinate everything: a central inbox, a secrets vault, scheduled jobs, Slack/Telegram integration, and an orchestrator agent that delegates domain work to the right specialist app over [A2A](/docs/a2a-protocol).
 
 If you're running an [multi-app workspace](/docs/multi-app-workspace) with many apps, Dispatch is the glue.
@@ -45,7 +47,7 @@ Day-to-day, Dispatch is the place admins and ops folks open to keep the workspac
 _How it works under the hood (for developers)._
 
 - **Orchestrator agent.** The chat is set up as a router: it reads `AGENTS.md`, `LEARNINGS.md`, and routes to specialist sub-agents or remote A2A agents.
-- **Remote agent registry.** A2A manifests live in `remote-agents/*.json` — one per app. Dispatch calls them using the `call-agent` action.
+- **Remote agent registry.** A2A manifests live in `remote-agents/*.json` — one per app. Dispatch calls them using the `call-agent` action. In a multi-app workspace, sibling apps under `apps/` are auto-discovered as A2A peers — no manual registration needed.
 - **Vault schema.** Drizzle tables for secrets, grants, requests, approvals, and audit logs. See `server/db/schema.ts` in the template.
 - **Slack / Telegram plugins.** Server plugins that register webhooks and forward incoming messages to the orchestrator agent.
 - **MCP hub mode.** Dispatch can act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list.

package/docs/content/template-forms.md

@@ -1,28 +1,30 @@
 ---
 title: "Forms Template"
-description: "Agent-native form builder — create, edit, and analyze forms through natural language, with a live preview and click-to-edit GUI."
+description: "Agent-native form builder — create, edit, publish, and route form submissions through natural language plus a visual editor."
 ---
 
 # Forms
 
-A form builder where the form builder _is_ the agent. Drag fields around in the editor, or just say "add a 'how did you hear about us' dropdown with five options and make it required" — same result, same underlying data. Think Typeform, but you can build, edit, and analyze forms by talking to the agent.
+Forms is an agent-native form builder. Describe the form you want, refine it in the editor, and publish a public form that stores submissions in your own SQL database.
 
-When you open the app, you'll see a list of your forms on the left and the editor in the middle. Open a form and you can click any field to fine-tune it, or ask the agent to make changes for you.
+When you open the app, you see your forms, the current editor, and a live preview. The agent can create a form from a prompt, update field labels and options, change validation, and connect submission destinations using the same actions the UI uses.
 
 ## What you can do with it
 
-- **Build forms conversationally.** "Create a contact form," "add an NPS score question," "make the email field required." The agent updates the schema and the preview updates live.
-- **Click-to-edit fine-tuning.** Every field in the preview is editable in place — label, placeholder, validation, conditional logic — with the usual GUI controls.
-- **Field types out of the box:** short text, long text, email, phone, URL, number, date, single-select, multi-select, rating, file upload, section header, conditional branch.
-- **Responses dashboard.** Per-response view plus an aggregate dashboard the agent can pivot on request: "show me signups from the last 30 days grouped by source."
-- **Agent-driven analysis.** Ask the agent to cluster free-text responses, extract sentiments, or draft a reply to everyone who scored the NPS below 7.
-- **Publish anywhere.** Public share link, embed snippet, branded thank-you page, webhook on submit.
+- **Build forms conversationally.** "Create a contact form," "add an NPS score question," "make the email field required." The agent updates the form schema and the preview updates from SQL-backed state.
+- **Fine-tune visually.** Edit labels, placeholders, required state, options, and field order from the builder UI when you want direct control.
+- **Use the shipped field types.** Text, email, number, long text, select, multi-select, checkbox, radio, date, rating, and scale fields are supported out of the box.
+- **Collect responses.** Each submission is stored in SQL with a per-response detail view and a dashboard for reviewing entries.
+- **Route submissions.** Send submission payloads to webhooks, Slack, Discord, or Google Sheets using the built-in integrations.
+- **Publish public forms.** Share a public form URL and show a thank-you message after submission.
 
 ## Why it's interesting
 
-The hard part of a form builder isn't the editor UI — it's everything around it: changing the questions after responses are already in, analyzing what people said, adding conditional logic, publishing, notifications, hooking it into Slack or your CRM. Most of that is just asking the agent. See [What is agent-native?](/docs/what-is-agent-native) for the bigger picture.
+The useful part of an agent-native form builder is that setup and iteration happen in the same place. You can ask the agent to add fields, adjust copy, connect Slack notifications, or inspect the submission data, while the UI remains the direct editor for the same SQL records.
 
-## For developers
+See [What is agent-native?](/docs/what-is-agent-native) for the broader framework model.
+
+## For Developers
 
 ### Scaffolding
 
@@ -30,25 +32,28 @@ The hard part of a form builder isn't the editor UI — it's everything around i
 pnpm dlx @agent-native/core create my-forms --template forms --standalone
 ```
 
-For a workspace with forms alongside other apps:
+For a workspace with Forms alongside other apps:
 
 ```bash
-pnpm dlx @agent-native/core create my-platform  # pick Forms + other templates
+pnpm dlx @agent-native/core create my-platform
 ```
 
-### Customize it
+Pick Forms and any other templates you want during the workspace setup.
+
+### Customize It
 
-Ask the agent for the outcome you want:
+Ask the agent for shipped behavior first:
 
-- "Add a signature field where people can draw their name."
-- "When someone submits this form, post it in our #signups Slack channel." (Connect Slack first via [Messaging](/docs/messaging).)
+- "Add a required radio field for preferred contact method."
+- "Post every new submission to Slack." Connect Slack first via [Messaging](/docs/messaging).
+- "Add a webhook destination for our CRM."
+- "Create a customer feedback form with a 1-10 scale and a long-text follow-up."
 - "Make some forms public and others login-only."
-- "Send everyone who scored below 5 a follow-up email asking what we could do better."
 
-The agent figures out the schema changes, components, and storage on its own — you just describe the result you want. See [Cloneable SaaS](/docs/cloneable-saas) for the full clone, customize, deploy flow.
+If you need new capabilities such as file uploads, signatures, or custom field widgets, treat them as template extensions: add the SQL shape, actions, UI editor controls, public renderer support, and agent instructions together. See [Creating Templates](/docs/creating-templates) for the current build pattern.
 
-## What's next
+## What's Next
 
 - [**Cloneable SaaS**](/docs/cloneable-saas) — the clone-and-own model
 - [**Actions**](/docs/actions) — the action system powering the builder
-- [**Real-Time Sync**](/docs/real-time-collaboration) — how the preview stays in sync with agent edits
+- [**Messaging**](/docs/messaging) — Slack and other submission destinations