@agent-native/core 0.63.0 → 0.63.1

package/docs/content/creating-templates.md

@@ -282,36 +282,38 @@ Custom routes that touch ownable data must call `getSession(event)` and wrap dat
 
 ## Write Agent Instructions {#write-agents-md}
 
-`AGENTS.md` is the agent's map of your app. Keep it specific and operational:
+`AGENTS.md` is the agent's map of your app — a small, skimmable file with a
+purpose line, core rules, application-state keys, an action table, and a skills
+index:
 
 ```markdown
 # My Template
 
-## Product Model
+One workspace for projects, tasks, and notes.
 
-Projects are the top-level resource. They contain tasks and notes.
+## Core Rules
 
-## Navigation State
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
 
-- `navigation.view`: `home` or `project`
-- `navigation.projectId`: selected project when on a project page
+## Application State
 
-## Actions
-
-| Action           | Purpose                     |
-| ---------------- | --------------------------- |
-| `list-projects`  | List accessible projects    |
-| `create-project` | Create a project            |
-| `update-project` | Rename or archive a project |
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
 
-## Rules
+## Actions
 
-- Use `view-screen` before acting on "this project" if the current screen is unclear.
-- Use actions for project changes; do not write raw SQL except for one-off maintenance/debugging when no action exists.
-- For shared projects, check access through framework sharing helpers.
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
 ```
 
-Update `AGENTS.md` whenever you add a new action, route, state key, or recurring workflow. See [Writing Agent Instructions](/docs/writing-agent-instructions) for how to keep `AGENTS.md` skimmable and word skill and tool descriptions so the agent triggers them reliably.
+Update `AGENTS.md` whenever you add a new action, route, state key, or recurring
+workflow. [Writing Agent Instructions](/docs/writing-agent-instructions) is the
+full guide — how to keep `AGENTS.md` skimmable, what belongs in each of the four
+guidance surfaces, and how to word skill and tool descriptions so the agent
+triggers them reliably.
 
 ## Add Skills {#skills}
 

package/docs/content/database.md

@@ -36,7 +36,7 @@ The framework auto-detects the dialect from the URL and configures Drizzle accor
 
 ## Builder.io Managed Database {#builder-managed}
 
-When connected to Builder.io, your app can use a managed database provisioned automatically — no connection strings required. Coming soon.
+_Planned (not yet available):_ when connected to Builder.io, your app will be able to use a managed database provisioned automatically, with no connection strings required.
 
 ## Where the DB Client Lives {#db-client}
 

package/docs/content/deployment.md

@@ -215,10 +215,10 @@ export default defineConfig({
 | `PORT`                      | Server port (Node.js only)                                                                                                                        |
 | `NITRO_PRESET`              | Override build preset at build time                                                                                                               |
 | `APP_BASE_PATH`             | Mount the app under a prefix (e.g. `/mail`). Set automatically by `npx @agent-native/core@latest deploy`; leave unset for standalone.             |
-| `DATABASE_URL`              | Persistent SQL connection string. Required in production. See [Database](/docs/database#production) for adapter and dialect details.              |
-| `DATABASE_AUTH_TOKEN`       | Auth token for providers that require a separate token, such as Turso/libSQL.                                                                     |
 | `AGENT_PROD_CODE_EXECUTION` | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](#production-code-execution). |
 
+Database connection variables (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, per-app `<APP_NAME>_DATABASE_URL`) live in [Database](/docs/database#production).
+
 ### Required in Production {#env-required-prod}
 
 These must be set before promoting an app to a real prod deploy. Missing values either fail-closed (the framework refuses to start / refuses to handle requests) or fall back to weaker behavior with a loud warning.
@@ -234,47 +234,15 @@ These must be set before promoting an app to a real prod deploy. Missing values
 
 ### Auth & Identity {#env-auth}
 
-| Variable                       | Description                                                                                                                                                                                   |
-| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ACCESS_TOKEN`                 | Static bearer fallback for MCP/connect clients that cannot use OAuth. Does not enable browser auth or make the app private.                                                                   |
-| `ACCESS_TOKENS`                | Comma-separated static bearer fallbacks for MCP/connect clients. Does not enable browser auth or make the app private.                                                                        |
-| `AUTH_SKIP_EMAIL_VERIFICATION` | Skip email verification for QA accounts. Local dev/test skips by default; hosted deploys must set this explicitly. **Disables a real security control** — only use on hosted QA environments. |
-| `GOOGLE_CLIENT_ID`             | Google OAuth client ID. Auto-enables "Sign in with Google" in Better Auth.                                                                                                                    |
-| `GOOGLE_CLIENT_SECRET`         | Google OAuth client secret.                                                                                                                                                                   |
-| `GITHUB_CLIENT_ID`             | GitHub OAuth client ID.                                                                                                                                                                       |
-| `GITHUB_CLIENT_SECRET`         | GitHub OAuth client secret.                                                                                                                                                                   |
+OAuth provider credentials (Google, GitHub), static MCP bearer fallbacks (`ACCESS_TOKEN` / `ACCESS_TOKENS`), and email-verification toggles are documented in [Authentication](/docs/authentication). Set them there per the auth mode you choose.
 
 ### Inbound Webhooks {#env-webhooks}
 
-Inbound webhook handlers refuse forged requests when their signing secret is missing in production (was previously fail-open with a warning — see CHANGELOG / [security audit fixes](#security-config)).
-
-| Variable                        | Required when                                                                                                  |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `EMAIL_INBOUND_WEBHOOK_SECRET`  | Inbound email integration is enabled. Verifies Resend / SendGrid / Svix signatures.                            |
-| `TELEGRAM_WEBHOOK_SECRET`       | Telegram bot integration is enabled.                                                                           |
-| `WHATSAPP_APP_SECRET`           | WhatsApp Business integration is enabled.                                                                      |
-| `WHATSAPP_VERIFY_TOKEN`         | WhatsApp webhook verification handshake (set in your Meta app dashboard too).                                  |
-| `SLACK_SIGNING_SECRET`          | Slack integration is enabled. Verifies Slack request signatures.                                               |
-| `GOOGLE_DOCS_PUSH_AUDIENCE`     | Google Docs Pub/Sub push integration is enabled. Set to the public URL of your push endpoint.                  |
-| `GOOGLE_DOCS_PUSH_SIGNER_EMAIL` | Google Docs Pub/Sub push integration is enabled. Set to the Pub/Sub service account email.                     |
-| `GMAIL_WATCH_TOPIC`             | Gmail Pub/Sub push (mail template). Optional — disables push if unset and falls back to history-delta polling. |
-| `GMAIL_PUSH_AUDIENCE`           | Gmail Pub/Sub push audience.                                                                                   |
-| `GMAIL_PUSH_SIGNER_EMAIL`       | Gmail Pub/Sub push signer email.                                                                               |
-
-For local development of any of these integrations, set `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` to opt back into the old "warn and accept" behavior — never set this in prod.
+Each messaging integration requires its own signing secret in production (handlers fail-closed on forged requests when the secret is missing). The per-integration variables are listed in [Messaging](/docs/messaging) and [Security](/docs/security). For local development only, `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` opts back into "warn and accept" — never set it in prod.
 
 ### Security Configuration (Opt-in) {#security-config}
 
-Defaults are strict; these flags relax behavior. Don't set them unless you specifically want the relaxed path.
-
-| Variable                                 | Effect                                                                                                                                                                                                                                                                                                              |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AGENT_NATIVE_DEBUG_ERRORS`              | `=1` to include stack traces in 500 JSON responses. Useful on previews; do **not** set in real prod (was previously gated by `NODE_ENV !== "production"`, which leaked stacks on misconfigured deploys).                                                                                                            |
-| `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS` | `=1` to accept webhooks without their signing secret (local dev only). Defaults to fail-closed in production.                                                                                                                                                                                                       |
-| `AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK`   | `=1` to let `${keys.NAME}` resolution in tools/automations fall through user-scope → workspace-scope. Default off (user-scope only) — a malicious org member could otherwise plant a workspace `OPENAI_API_KEY` and harvest other members' requests. Turn on only if your org genuinely shares workspace-wide keys. |
-| `AGENT_NATIVE_MCP_HUB_MULTI_ORG`         | `=1` to allow `AGENT_NATIVE_MCP_HUB_TOKEN` to serve multiple orgs from a single hub deployment. Default refuses to serve when more than one org exists in a hub deploy. Only relevant if you operate the workspace MCP hub.                                                                                         |
-| `AGENT_NATIVE_ALLOW_ENV_VAR_WRITES`      | `=1` to let runtime code mutate `process.env` from the env-var write API. Off by default — required to be explicitly enabled outside dev SQLite.                                                                                                                                                                    |
-| `AUTH_SKIP_EMAIL_VERIFICATION`           | `=1` to skip email verification for password signups. Local dev/test skips by default; hosted deploys should use this only for QA — see Auth section above.                                                                                                                                                         |
+Defaults are strict. A handful of opt-in flags relax behavior (debug stack traces, unverified webhooks, workspace-scoped key fallback, the MCP hub multi-org switch, runtime env-var writes). They are documented with their security trade-offs in [Security](/docs/security). Don't set them unless you specifically want the relaxed path.
 
 ### Workspace .env Inheritance {#env-inheritance}
 

package/docs/content/dispatch.md

@@ -25,46 +25,35 @@ If you're running a single template standalone, you don't need Dispatch — each
 
 ## What Dispatch does {#what-it-does}
 
-Six capabilities, all sitting on top of the same workspace database the other apps use.
+Seven capabilities, all sitting on top of the same workspace database the other apps use:
 
-### Central inbox
+| Capability               | What it gives you                                                               | Set it up                                                     |
+| ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Central inbox**        | Slack, email, Telegram, WhatsApp all reach one agent with shared memory + tools | **Settings → Messaging** ([Messaging](/docs/messaging))       |
+| **Secret vault**         | Store each credential once; rotate in one place across every app                | **Vault** + access mode (all-apps or manual)                  |
+| **Cross-app delegation** | Routes a request to the right specialist app over A2A and replies in-thread     | Automatic ([A2A](/docs/a2a-protocol))                         |
+| **Unified MCP gateway**  | One MCP connector for external agents reaches every granted workspace app       | [External Agents](/docs/external-agents)                      |
+| **Workspace resources**  | Author skills/instructions/profiles once; apps inherit them at runtime          | **Resources** ([Workspace](/docs/workspace#global-resources)) |
+| **Dreams**               | Reviews past runs/feedback and proposes durable improvements for you to approve | **Dreams** tab                                                |
+| **Approval flow**        | Gate sensitive runtime changes behind inline admin review                       | **dispatch approval policy**                                  |
 
-Slack, email, Telegram, and WhatsApp all flow into Dispatch's agent loop. Connect each platform once in **Settings → Messaging** and every channel reaches the same agent with the same memory and tools. A Slack DM and an email to `agent@yourcompany.com` end up as two surfaces on one conversation history, not two disconnected bots.
+Each is detailed below.
 
-See [Messaging](/docs/messaging) for the credentials and webhook URLs for each platform.
+### Central inbox
 
-### Secret vault
+Slack, email, Telegram, and WhatsApp all flow into Dispatch's agent loop. Connect each platform once in **Settings → Messaging** and every channel reaches the same agent with the same memory and tools. A Slack DM and an email to `agent@yourcompany.com` end up as two surfaces on one conversation history, not two disconnected bots. See [Messaging](/docs/messaging) for the credentials and webhook URLs.
 
-Store credentials once in Dispatch's vault. By default, vault access is **all apps**: every saved key is available to every workspace app, and `sync-vault-to-app` pushes the full vault to the target app. Workspaces that need stricter separation can switch the vault to **manual** mode, where explicit per-app grants are required before sync. Non-admins can **request** a secret for an app; admins **approve**, which creates the secret and, in manual workflows, the grant. Every read, grant, sync, and rotation is captured in an audit log.
+### Secret vault
 
-This is what makes "rotate the OpenAI key" a one-click operation across ten apps instead of ten PRs.
+Store credentials once in Dispatch's vault. By default, vault access is **all apps**: every saved key is available to every workspace app, and `sync-vault-to-app` pushes the full vault to the target app. Workspaces that need stricter separation can switch the vault to **manual** mode, where explicit per-app grants are required before sync. Non-admins can **request** a secret for an app; admins **approve**, which creates the secret and, in manual workflows, the grant. Every read, grant, sync, and rotation is captured in an audit log. This is what makes "rotate the OpenAI key" a one-click operation across ten apps instead of ten PRs.
 
 ### Cross-app delegation
 
-Dispatch auto-discovers the other apps in your workspace as A2A peers — no manual registration, no per-app config. When a user asks "summarize last week's signups" in Slack, Dispatch recognizes that as an analytics request and calls the analytics app over [A2A](/docs/a2a-protocol). When they ask "draft a reply to Alice", it routes to the mail app. Dispatch posts the final answer back in the originating thread.
-
-The behavioral rule lives in the dispatch agent's instructions: domain work belongs to the domain app. Dispatch is the orchestrator, not the specialist.
+Dispatch auto-discovers the other apps in your workspace as A2A peers — no manual registration, no per-app config. When a user asks "summarize last week's signups" in Slack, Dispatch recognizes that as an analytics request and calls the analytics app over [A2A](/docs/a2a-protocol). When they ask "draft a reply to Alice", it routes to the mail app. Dispatch posts the final answer back in the originating thread. The behavioral rule lives in the dispatch agent's instructions: domain work belongs to the domain app. Dispatch is the orchestrator, not the specialist.
 
 ### Unified MCP gateway
 
-Dispatch can also be the single MCP connector for external agents. Add
-`https://dispatch.agent-native.com/_agent-native/mcp` once in Claude, ChatGPT,
-Codex, Cursor, or another MCP host, sign in through the host's OAuth flow, then
-manage which apps that gateway can reach from Dispatch's **Agents** page. The
-gateway exposes `list_apps`, `ask_app`, and `open_app`, filtered by the
-selected app grants, so external agents can route work to Mail, Calendar,
-Analytics, Brain, and workspace apps without a separate authorization for every
-app.
-
-When a host supports MCP Apps, that same Dispatch connector can render granted
-app routes inline too: email drafts, calendar invites, decks, forms, docs,
-designs, dashboards, clips, and other app routes can preview in chat without
-adding per-app connectors.
-
-Direct per-app MCP URLs such as
-`https://mail.agent-native.com/_agent-native/mcp` still exist when you
-intentionally want one isolated app surface. For most workspace use, the
-Dispatch gateway is the lower-friction path.
+Dispatch can be the single MCP connector for external agents: add `https://dispatch.agent-native.com/_agent-native/mcp` once in Claude, ChatGPT, Codex, or Cursor, and one authorization reaches every granted workspace app instead of one connector per app. See [External Agents](/docs/external-agents) for the full connect flow, app grants, OAuth, and inline MCP App previews.
 
 ### Workspace resources
 

package/docs/content/drop-in-agent.md

@@ -164,117 +164,30 @@ import { useSendToAgentChat } from "@agent-native/core/client";
 const { send, isGenerating } = useSendToAgentChat();
 ```
 
-## Custom chat UI layers {#custom-chat-ui}
-
-If you do not want `<AgentSidebar>`, choose the lowest layer that still lets the
-framework own the agent runtime:
-
-- **`<AgentChatSurface>`** — use this for a dedicated chat route or embedded
-  panel. It keeps the standard chat/runtime wiring without the sidebar wrapper.
-- **`<AssistantChat>`** — use this when you want to own surrounding chrome,
-  tabs, headers, empty states, or composer slots while keeping the standard
-  conversation renderer and adapter.
-- **`@agent-native/core/client/chat`** — use this focused subpath when building
-  a custom surface from pieces: `AssistantChat`, `MultiTabAssistantChat`,
-  `useChatThreads`, `AgentConversation`, composer exports, and the standard
-  chat adapters.
-- **`@agent-native/core/client/composer`** — use this for the chat field itself:
-  `PromptComposer` for the complete field, or `TiptapComposer` only when you
-  are already wiring assistant-ui primitives yourself.
-- **`@agent-native/core/client/conversation`** — use this for transcript
-  rendering without the full chat runtime.
-- **`createAgentChatAdapter()`** — use this only when building a custom
-  assistant-ui transport for the built-in Agent-Native chat endpoint. It
-  connects to the same `/_agent-native/agent-chat` stream and preserves
-  run-manager recovery, attachments, model selection, native widgets, and
-  thread metadata.
-- **`createHttpAgentChatRuntime()`** — use this when a BYO agent exposes a
-  POST endpoint that streams `AgentChatRuntime` events. Pass the runtime to
-  `<AssistantChat runtime={runtime} />`.
-
-Avoid posting directly to `/_agent-native/agent-chat` from product UI. If a
-lower-level helper is missing for a real custom surface, add that named helper
-first so client code does not learn a second, ad hoc transport.
-
-For BYO agent runtimes, keep actions and SQL-backed app state as the contract.
-Adapt the runtime into `<AssistantChat runtime={...} />` when you want
-Agent-Native chat behavior. Use `<AssistantChat createAdapter={...} />` only
-for lower-level assistant-ui transports, or `PromptComposer` by itself only
-when the external runtime owns the transcript and loop. See
-[Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes) and
-[Agent Surfaces](/docs/agent-surfaces#byo-agent).
-
-### Build your own sidebar from pieces {#build-your-own-sidebar}
-
-The stock sidebar is optional. This example builds the agent-side UI itself.
-Render it inside your own shell, drawer, split pane, or route when you want to
-own the layout around the agent runtime:
-
-```tsx
-import { AssistantChat, useChatThreads } from "@agent-native/core/client/chat";
-
-function MyAgentSidebar({ projectSlug }: { projectSlug: string }) {
-  const threads = useChatThreads(undefined, projectSlug);
-  const threadId = threads.activeThreadId ?? undefined;
-
-  return (
-    <aside className="grid h-full grid-cols-[220px_1fr]">
-      <ThreadList
-        threads={threads.threads}
-        activeThreadId={threadId}
-        onSelect={threads.switchThread}
-      />
-      <AssistantChat threadId={threadId} />
-    </aside>
-  );
-}
-```
-
-If you only need the field for a custom runtime, use the composer subpath:
-
-```tsx
-import { PromptComposer } from "@agent-native/core/client/composer";
-
-<PromptComposer
-  placeholder="Ask the agent..."
-  onSubmit={async (text, files, references, options) => {
-    await sendToYourRuntime({ text, files, references, options });
-  }}
-/>;
-```
-
-`TiptapComposer` is also public, but it is intentionally lower-level: render it
-inside an assistant-ui thread/composer context. Most app code should use
-`PromptComposer` or `AssistantChat`.
-
-### Raw text completion escape hatch {#raw-text-completion}
-
-For narrow server-side transforms that intentionally do not need tools, chat
-history, run state, or user steering, use `completeText()` from
-`@agent-native/core/server`. Keep it server-only and wrap user-facing usage in
-an action so the UI and agent share the same operation.
-
-```ts
-import { defineAction } from "@agent-native/core/action";
-import { completeText } from "@agent-native/core/server";
-
-export default defineAction({
-  description: "Classify a message",
-  run: async ({ body }: { body: string }) => {
-    const result = await completeText({
-      systemPrompt: "Return exactly one label.",
-      input: body,
-      maxOutputTokens: 12,
-      temperature: 0,
-    });
-    return { label: result.text.trim() };
-  },
-});
-```
-
-If the work needs actions, files, database writes, auditability, or multi-step
-reasoning, use `sendToAgentChat()` instead, optionally with `background: true`
-and `openSidebar: false`.
+## When the stock sidebar isn't the fit {#custom-chat-ui}
+
+`<AgentSidebar>` and `<AgentPanel>` cover most apps. When you need to own the
+layout around the agent, or you want to power the conversation with an agent
+you built elsewhere, drop down a layer — but keep letting the framework own the
+runtime, actions, and SQL-backed state:
+
+- **Own the chrome around the standard runtime.** Use `<AgentChatSurface>` for
+  a dedicated chat route, or `<AssistantChat>` when you want custom headers,
+  tabs, and empty states around the standard conversation. The full layer map —
+  every component, hook, composer, and adapter, with import paths — lives in
+  [Component API](/docs/components#agent-chat-ui).
+- **Bring your own agent runtime.** If an agent you built elsewhere should
+  power the conversation while Agent-Native keeps the composer, transcript, tool
+  cards, approvals, and native widgets, pass an `AgentChatRuntime` to
+  `<AssistantChat runtime={...} />`. The connectors
+  (`createHttpAgentChatRuntime()` and the OpenAI / Claude / Vercel AI / AG-UI
+  helpers) and the event contract are documented in
+  [Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes).
+
+Whichever layer you pick, keep actions and SQL-backed app state as the contract,
+and avoid posting directly to `/_agent-native/agent-chat` from product UI. If a
+named helper is missing for a real custom surface, add that helper first so
+client code does not learn a second, ad hoc transport.
 
 ## Typesafe actions from the UI: `useActionMutation()` {#use-action-mutation}
 

package/docs/content/durable-resume.md

@@ -5,6 +5,10 @@ description: "When a hosted agent run is interrupted and resumes, completed side
 
 # Durable Resume
 
+> **Who is this for:** anyone who wants to understand how the framework's run
+> recovery avoids duplicate side effects. This is built-in behavior — there is
+> nothing to wire up.
+
 Hosted agent runs get interrupted: a serverless function hits its hard timeout mid-stream, a gateway drops the connection at 45s, a socket hangs up, the platform cold-starts. The framework already recovers from these by saving the conversation prefix and re-running the LLM call ("continue from where you left off"). But recovery alone has a sharp edge: if the interrupted attempt **already sent an email or created a ticket**, a naive resume could do it again.
 
 Durable resume closes that gap. On resume, the framework knows which side-effecting tool calls already completed and refuses to re-run them — at two layers.