@agent-native/core 0.175.1 → 0.175.2-nightly-20260826165737

package/dist/server/core-routes-plugin.js

@@ -1,4 +1,4 @@
-import { assertBodySize, defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getHeader, getRequestURL, getRequestIP, readRawBody, } from "h3";
+import { assertBodySize, defineEventHandler, setResponseStatus, setResponseHeader, getMethod, getHeader, getRequestURL, getRequestIP, readRawBody, getCookie, setCookie, deleteCookie, } from "h3";
 import { readMultipartFormData } from "h3";
 import { DEFAULT_MODEL } from "../agent/default-model.js";
 import { registerBuiltinEngines } from "../agent/engine/builtin.js";
@@ -41,8 +41,8 @@ import { createAgentEngineApiKeyHandler } from "./agent-engine-api-key-route.js"
 import { readAnalyticsClientPlatformHeader, readBrowserSessionIdHeader, } from "./agent-run-context.js";
 import { getConfiguredAppBasePath, stripAppBasePath } from "./app-base-path.js";
 import { getSession } from "./auth.js";
-import { BUILDER_CONNECT_PARAM, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, appendBuilderConnectToken, builderConnectTrackingProperties, createBuilderConnectState, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderBrowserOriginForEvent, getBuilderBrowserStatusForEvent, isBuilderConnectCallbackUrlAllowed, isSignedBuilderConnectState, normalizeBuilderAgentContext, resolveBuilderBranchProjectId, resolveBuilderConnectCallbackUrl, resolveBuilderPreviewRelayParentOrigin, runBuilderAgent, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, } from "./builder-browser.js";
-import { BUILDER_OAUTH_SCOPE, deleteBuilderOAuthSession, finishBuilderOAuthAuthorization, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, startBuilderOAuthAuthorization, } from "./builder-oauth.js";
+import { BUILDER_CONNECT_PARAM, BUILDER_CONNECT_STATE_COOKIE, BUILDER_ENV_KEYS, BUILDER_OPENER_PARAM, BUILDER_RELAY_FLOW_HEADER, BUILDER_RELAY_SIGNATURE_HEADER, BUILDER_RELAY_STATE_PARAM, BUILDER_RELAY_TIMESTAMP_HEADER, appendBuilderConnectToken, appendBuilderConnectStateCookie, builderConnectTrackingProperties, createBuilderConnectState, createBuilderBrowserCallbackErrorPage, createBuilderBrowserCallbackPage, createBuilderRelayRequest, getBuilderConnectTrackingParams, getBuilderBrowserOriginForEvent, getBuilderBrowserStatusForEvent, isBuilderConnectCallbackUrlAllowed, isSignedBuilderConnectState, normalizeBuilderAgentContext, resolveBuilderBranchProjectId, resolveBuilderConnectCallbackUrl, resolveBuilderConnectCallbackState, resolveBuilderPreviewRelayParentOrigin, removeBuilderConnectStateCookie, runBuilderAgent, verifyBuilderRelayRequest, verifyBuilderPreviewRelayStateForCallback, verifyBuilderConnectTokenAndGetOwner, } from "./builder-browser.js";
+import { BUILDER_OAUTH_SCOPE, deleteBuilderOAuthSession, exchangeBuilderOAuthAuthorization, hasBuilderOAuthSession, resolveBuilderOAuthRequestAccess, saveBuilderOAuthCredentials, startBuilderOAuthAuthorization, } from "./builder-oauth.js";
 import { captureError, registerErrorCaptureProvider } from "./capture-error.js";
 import { resolveCoreRoutesMcpOptions, } from "./core-routes/mcp-connect-options.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
@@ -1837,12 +1837,10 @@ export function createCoreRoutesPlugin(options = {}) {
             //      request with the navigation context. We allow `same-origin` or
             //      `none` (typed/bookmark/extension); cross-site / same-site without
             //      a valid connect token are rejected.
-            //   3. Pending row keyed by signed OAuth state — the callback
-            //      requires both a valid session and a one-time row that this
-            //      handler wrote during the same flow. Without the same-origin
-            //      gate or connect token above, an attacker could prime the row from
-            //      cross-site and then trick the victim into completing an
-            //      attacker-initiated authorization flow.
+            //   3. Pending row keyed by signed OAuth state plus a host-only cookie —
+            //      Builder can omit the callback query, but it cannot read or forge
+            //      the cookie. The callback still requires the matching session,
+            //      pending row, and a successful PKCE exchange before persistence.
             getH3App(nitroApp).use(`${P}/builder/connect`, defineEventHandler(async (event) => {
                 const ownerContext = await resolveBuilderOwnerContext(event, "connect");
                 const ownerEmail = ownerContext.email;
@@ -1913,7 +1911,8 @@ export function createCoreRoutesPlugin(options = {}) {
                 catch {
                     // No prior error row — fine
                 }
-                const callbackUrl = resolveBuilderConnectCallbackUrl(event);
+                const state = createBuilderConnectState();
+                const callbackUrl = resolveBuilderConnectCallbackUrl(event, state);
                 if (!callbackUrl ||
                     !isBuilderConnectCallbackUrlAllowed(callbackUrl, event)) {
                     const msg = "This deployment cannot start Builder OAuth from the current origin.";
@@ -1940,7 +1939,6 @@ export function createCoreRoutesPlugin(options = {}) {
                         parentOrigin: getBuilderBrowserOriginForEvent(event),
                     });
                 }
-                const state = createBuilderConnectState();
                 // The standard OAuth client discovers Builder's protected-resource
                 // metadata, dynamically registers, and creates its S256 verifier.
                 // Persist that opaque protocol state encrypted and consume it once.
@@ -1964,6 +1962,13 @@ export function createCoreRoutesPlugin(options = {}) {
                         tracking: connectTracking,
                     });
                     await purgeExpiredBuilderConnectPendingStates().catch(() => 0); // coercion-ok: connect already persisted the new pending row; purge of abandoned rows must not fail OAuth start
+                    setCookie(event, BUILDER_CONNECT_STATE_COOKIE, appendBuilderConnectStateCookie(getCookie(event, BUILDER_CONNECT_STATE_COOKIE), state), {
+                        httpOnly: true,
+                        secure: callbackUrl.startsWith("https://"),
+                        sameSite: "lax",
+                        path: "/",
+                        maxAge: Math.ceil(BUILDER_CONNECT_PENDING_TTL_MS / 1_000),
+                    });
                 }
                 catch (err) {
                     await trackBuilderLifecycle(event, "builder connect failed", ownerEmail, {
@@ -2243,7 +2248,11 @@ export function createCoreRoutesPlugin(options = {}) {
                     setResponseHeader(event, "Content-Type", "text/html; charset=utf-8");
                     return createBuilderBrowserCallbackPage(`${relayParentOrigin}${relayPayload.basePath || "/"}`, { parentOrigin: relayParentOrigin });
                 }
-                const state = requestUrl.searchParams.get("state");
+                // Builder sometimes drops the top-level OAuth state. Recover it
+                // from the host-only cookie set by /builder/connect; the pending row
+                // and authenticated session still bind it to this account.
+                const queryState = requestUrl.searchParams.get("state");
+                const state = resolveBuilderConnectCallbackState(queryState, getCookie(event, BUILDER_CONNECT_STATE_COOKIE));
                 const parentOrigin = getBuilderBrowserOriginForEvent(event);
                 const fail = async (status, message, ownerEmail, reason, tracking = {}) => {
                     if (ownerEmail) {
@@ -2282,7 +2291,7 @@ export function createCoreRoutesPlugin(options = {}) {
                 const redirectUri = typeof pending.redirectUri === "string"
                     ? pending.redirectUri
                     : null;
-                const expectedRedirectUri = resolveBuilderConnectCallbackUrl(event);
+                const expectedRedirectUri = resolveBuilderConnectCallbackUrl(event, state);
                 if (!ownerEmail ||
                     !isBuilderConnectCallbackOwner(ownerEmail, session?.email) ||
                     Date.now() >= expiresAt ||
@@ -2296,10 +2305,6 @@ export function createCoreRoutesPlugin(options = {}) {
                     }
                     return fail(403, "Builder connect callback could not be verified. Restart the connection.", ownerEmail ?? undefined, "callback_verification_failed", tracking);
                 }
-                const consumed = await consumeBuilderConnectPendingState(state);
-                if (!consumed) {
-                    return fail(403, "No active Builder connect flow found. Restart the connection from Settings.", ownerEmail, "callback_verification_failed", tracking);
-                }
                 const denied = requestUrl.searchParams.get("error");
                 const code = requestUrl.searchParams.get("code");
                 const iss = requestUrl.searchParams.get("iss") ?? undefined;
@@ -2308,11 +2313,11 @@ export function createCoreRoutesPlugin(options = {}) {
                         ? "Builder connection was cancelled."
                         : "Builder did not return an authorization code.", ownerEmail, denied ? "authorization_denied" : "missing_code", tracking);
                 }
+                let credentials;
                 try {
                     const oauthFlow = JSON.parse(decryptSecretValue(encryptedOAuthFlow));
-                    await finishBuilderOAuthAuthorization({
+                    credentials = await exchangeBuilderOAuthAuthorization({
                         ownerEmail,
-                        orgId: typeof consumed.orgId === "string" ? consumed.orgId : undefined,
                         code,
                         iss,
                         pending: oauthFlow,
@@ -2321,6 +2326,36 @@ export function createCoreRoutesPlugin(options = {}) {
                 catch {
                     return fail(502, "Builder could not exchange the authorization code. Restart the connection.", ownerEmail, "code_exchange_failed", tracking);
                 }
+                // PKCE proves the callback belongs to this flow before its pending
+                // row is consumed. Persist first so a transient credential-store
+                // failure does not strand an otherwise valid pending flow.
+                try {
+                    await saveBuilderOAuthCredentials({
+                        ownerEmail,
+                        orgId: typeof pending.orgId === "string" ? pending.orgId : undefined,
+                        credentials,
+                    });
+                }
+                catch {
+                    return fail(500, "Builder credentials could not be saved. Restart the connection.", ownerEmail, "credential_write_failed", tracking);
+                }
+                const consumed = await consumeBuilderConnectPendingState(state);
+                if (!consumed) {
+                    return fail(403, "No active Builder connect flow found. Restart the connection from Settings.", ownerEmail, "callback_verification_failed", tracking);
+                }
+                const remainingStates = removeBuilderConnectStateCookie(getCookie(event, BUILDER_CONNECT_STATE_COOKIE), state);
+                if (remainingStates) {
+                    setCookie(event, BUILDER_CONNECT_STATE_COOKIE, remainingStates, {
+                        httpOnly: true,
+                        secure: expectedRedirectUri.startsWith("https://"),
+                        sameSite: "lax",
+                        path: "/",
+                        maxAge: Math.ceil(BUILDER_CONNECT_PENDING_TTL_MS / 1_000),
+                    });
+                }
+                else {
+                    deleteCookie(event, BUILDER_CONNECT_STATE_COOKIE, { path: "/" });
+                }
                 try {
                     await Promise.all([
                         deleteSetting("builder-disconnected").catch(() => false), // coercion-ok: best-effort cleanup after successful OAuth save

package/dist/server/embed-session.js

@@ -761,7 +761,7 @@ export async function resolveEmbedSessionFromRequest(event) {
         if (candidate.source === "query" && candidate.token) {
             try {
                 setEmbedSessionCookie(event, candidate.token);
-                setResponseHeader(event, "Referrer-Policy", "no-referrer");
+                setResponseHeader(event, "Referrer-Policy", "same-origin");
             }
             catch {
                 // Some tests and edge runtimes expose read-only request shims. The

package/dist/server/security-headers.d.ts

@@ -19,6 +19,9 @@
  *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query
  *     from outbound Referer headers when the request crosses origin, so a
  *     public-share viewer's outbound link clicks never leak the share token.
+ *     Validated embed-session responses tighten this to `same-origin`, which
+ *     sends nothing cross-origin at all while keeping the same-origin Referer
+ *     that parent-vs-child app checks depend on.
  *   - `Permissions-Policy: camera=*, microphone=(self), geolocation=(),
  *     screen-wake-lock=()` — allows microphone access for composer dictation
  *     and camera access for media-capture UI (the Clips recorder, and the

package/dist/server/security-headers.js

@@ -19,6 +19,9 @@
  *   - `Referrer-Policy: strict-origin-when-cross-origin` — strips path/query
  *     from outbound Referer headers when the request crosses origin, so a
  *     public-share viewer's outbound link clicks never leak the share token.
+ *     Validated embed-session responses tighten this to `same-origin`, which
+ *     sends nothing cross-origin at all while keeping the same-origin Referer
+ *     that parent-vs-child app checks depend on.
  *   - `Permissions-Policy: camera=*, microphone=(self), geolocation=(),
  *     screen-wake-lock=()` — allows microphone access for composer dictation
  *     and camera access for media-capture UI (the Clips recorder, and the
@@ -112,7 +115,13 @@ export function createSecurityHeadersMiddleware() {
         const iframeNavigationRequest = isIframeNavigationRequest(event);
         const requestOrigin = getHeader(event, "origin");
         setResponseHeader(event, "X-Content-Type-Options", "nosniff");
-        setResponseHeader(event, "Referrer-Policy", embedFrameRequest ? "no-referrer" : "strict-origin-when-cross-origin");
+        setResponseHeader(event, "Referrer-Policy", 
+        /**
+         * Dispatch is served as an embed, and the parent page's path cannot be forged by a
+         * same-origin child app, so stripping it made minting an app session from Dispatch
+         * impossible.
+         */
+        embedFrameRequest ? "same-origin" : "strict-origin-when-cross-origin");
         setResponseHeader(event, "Permissions-Policy", PERMISSIONS_POLICY);
         setResponseHeader(event, "Cross-Origin-Opener-Policy", "same-origin");
         if (embedFrameRequest || iframeNavigationRequest) {

package/dist/server/transcribe-voice.d.ts

@@ -20,6 +20,6 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    text: string;
     error?: undefined;
+    text: string;
 }>>;

package/dist/vite/client.js

@@ -917,6 +917,7 @@ const CORE_CLIENT_SUBPATHS = [
     // (and its transitive ~650-700 KB gzip chat stack) onto the critical path.
     "@agent-native/core/client/api-path",
     "@agent-native/core/client/clipboard",
+    "@agent-native/core/client/zoom-gesture",
     "@agent-native/core/blocks",
     "@agent-native/core/blocks/server",
     "@agent-native/core/client/extensions",
@@ -1216,6 +1217,7 @@ function getCoreSourceAliases(cwd) {
         // Dedicated thin subpath — only the URL helpers, no chat stack in the closure.
         "@agent-native/core/client/api-path": path.join(coreSrc, "client/api-path.ts"),
         "@agent-native/core/client/clipboard": path.join(coreSrc, "client/clipboard.ts"),
+        "@agent-native/core/client/zoom-gesture": path.join(coreSrc, "client/zoom-gesture.ts"),
         "@agent-native/core/blocks": path.join(coreSrc, "client/blocks/index.ts"),
         "@agent-native/core/blocks/server": path.join(coreSrc, "client/blocks/server.ts"),
         "@agent-native/core/client/extensions": path.join(coreSrc, "client/extensions/index.ts"),

package/docs/content/template-chat-developers.mdx

@@ -1,19 +1,81 @@
 ---
-title: "Chat — runtime and admin surfaces"
-description: "The core SQL tables, auth setup, and the Database/Observability/Extensions admin pages that ship by default with the Chat template."
+title: "Chat: Developer Guide"
+description: "Quick start, the action inventory, core tables, auth, and the Database/Observability/Extensions admin pages that ship by default with the Chat template."
 ---
 
-# Chat — runtime and admin surfaces
+# Developer Guide
 
-This page is for developers who need to know what runs under the hood in [Chat](/docs/template-chat): the tables every template shares, how auth is configured, and the admin pages — Database, Observability, and Extensions — that ship in every Chat app whether or not you ever open them.
+This page is for developers running or extending the Chat template: the
+quick start, every built-in action, the core tables it runs on, how auth is
+configured, and the admin pages — Database, Observability, and Extensions —
+that ship by default whether or not you ever open them. See
+[Chat](/docs/template-chat) for what the app does.
 
-## Core SQL tables and live sync {#tables}
+## Quick start {#quick-start}
 
-Chat adds no domain tables of its own (see [What's not in it](/docs/template-chat#not-in-it)). It runs entirely on the framework's core tables: chat threads and messages, `application_state`, `settings`, sessions, resources, and run history.
+This walks through running Chat from nothing installed to a live
+conversation with the agent. The commands are identical whether you're in
+Terminal on macOS or PowerShell/Command Prompt on Windows, they're plain
+Node.js tooling.
 
-`useDbSync()` is already wired into the app shell: when the agent (or anyone else) writes to SQL, the client receives the change over SSE, or the 2-second polling fallback, and invalidates the matching React Query caches — no manual refresh, no websocket you have to manage yourself. See [`useDbSync`](/docs/client-data#usedbsync) for the full hook API.
+<Steps>
+
+### Create the app
+
+```bash
+npx @agent-native/core@latest create my-chat-app --standalone --template chat
+cd my-chat-app
+pnpm install
+```
+
+This needs [Node.js](https://nodejs.org) 22 or later and
+[pnpm](https://pnpm.io) installed first. See [Getting
+started](/docs/getting-started) if you haven't installed either yet.
+
+### Start the dev server
+
+```bash
+pnpm dev
+```
+
+The app opens at `http://localhost:8080`. If it doesn't open automatically,
+visit that URL in your browser.
+
+### Sign in and connect an LLM
+
+On the Welcome screen, select **Continue as local dev** — no email or
+password needed for local development. Then connect an LLM: select
+**Connect Builder.io** for free credits, or **Custom keys** to add an
+Anthropic/OpenAI key or a local Ollama model. Chat ships with no domain data
+to seed, so once an LLM is connected there's nothing else to set up before
+you can start chatting.
+
+</Steps>
+
+## Action inventory {#actions}
 
-`server/plugins/agent-chat.ts` is where the chat runtime itself is configured: it registers every action in `actions/` as a callable tool (`loadActionsFromStaticRegistry`), resolves the current org for scoping (`resolveOrgId`), sets the system prompt, and declares which tools the model sees on the very first turn (`initialToolNames`) — see [Your first feature in Chat](/docs/template-chat-first-edits#first-edits) for what that last part means when you add a new action.
+Every operation is a TypeScript file in `actions/`, auto-mounted at
+`POST /_agent-native/actions/:name`.
+
+| Action        | What it does                                                            |
+| ------------- | ----------------------------------------------------------------------- |
+| `hello`       | Example action; returns a greeting. Replace it or add actions beside it |
+| `view-screen` | Standard context action; reads the current view back for the agent      |
+| `navigate`    | Standard navigation action; moves the UI to a route                     |
+
+`server/plugins/agent-chat.ts` is where the chat runtime itself is
+configured: it registers every action in `actions/` as a callable tool
+(`loadActionsFromStaticRegistry`), resolves the current org for scoping
+(`resolveOrgId`), sets the system prompt, and declares which tools the model
+sees on the very first turn (`initialToolNames`) — see [Your First Feature in
+Chat](/docs/template-chat-first-edits#first-edits) for what that last part
+means when you add a new action.
+
+## Core tables and live sync {#tables}
+
+Chat adds no domain tables of its own (see [What ships](/docs/template-chat#what-ships)). It runs entirely on the framework's core tables: chat threads and messages, `application_state`, `settings`, sessions, resources, and run history.
+
+`useDbSync()` is already wired into the app shell: when the agent (or anyone else) writes to SQL, the client receives the change over SSE, or the 2-second polling fallback, and invalidates the matching React Query caches — no manual refresh, no websocket you have to manage yourself. See [`useDbSync`](/docs/client-data#usedbsync) for the full hook API.
 
 ## Auth {#auth}
 
@@ -78,11 +140,36 @@ Three routes are mounted whether or not your app ever links to them:
 
 **Extensions** are sandboxed Alpine.js mini-apps your users can ask the agent to build inside the running app — a custom widget or checklist, no deploy required. Chat mounts the routes that view and run them (`/extensions/:id`) by default, even before you or your users create one; `/extensions` itself just redirects into the Extensions tab of Settings rather than showing its own list. See [Extensions](/docs/extensions) for what they can and cannot do.
 
+## Customizing it {#customizing}
+
+Every part of the app is editable source. Start here:
+
+- `actions/` — add a new file with `defineAction` to expose new capability
+  to both the agent and the frontend.
+- `app/routes/` — the UI. The app uses file-system routing (`flatRoutes()`
+  in `app/routes.ts`), so adding a route file is enough to mount it.
+- `server/db/schema.ts` — add your own tables with Drizzle once you outgrow
+  the core tables above. Keep the code dialect-agnostic so the app runs on
+  SQLite, Postgres, Turso, D1, and Neon.
+- `AGENTS.md` — agent instructions. Update this when you teach the agent new
+  capabilities or conventions.
+- `.agents/skills/` — detailed patterns the agent follows.
+
+If you add a feature, remember to update all four areas: UI, action, skill
+or AGENTS.md entry, and any application state the agent needs to see. That
+is what keeps the agent and the UI in parity.
+
 ## What's next
 
-- [**Chat Template**](/docs/template-chat) — what ships by default and when to pick it
-- [**Your first feature in Chat**](/docs/template-chat-first-edits) — the starter chat route, annotated, plus a full feature walkthrough
-- [**Database**](/docs/server-database) — connecting a real database and the portable-SQL model
-- [**Agent Observability**](/docs/observability) — what the dashboard tracks and how
+- [**Chat**](/docs/template-chat) — what ships by default and when to pick it
+- [**Your First Feature in Chat**](/docs/template-chat-first-edits) — the
+  starter chat route, annotated, plus a full feature walkthrough
+- [**Actions**](/docs/actions-overview) — the action system this template is
+  built on
+- [**Database**](/docs/server-database) — connecting a real database and the
+  portable-SQL model
+- [**Agent Observability**](/docs/observability) — what the dashboard tracks
+  and how
 - [**Extensions**](/docs/extensions) — building mini-apps inside a template
-- [**Authentication**](/docs/authentication) — sessions, organizations, and protected routes
+- [**Authentication**](/docs/authentication) — sessions, organizations, and
+  protected routes

package/docs/content/template-chat-first-edits.mdx

@@ -1,9 +1,9 @@
 ---
-title: "Your first feature in Chat"
+title: "Chat: Your First Feature"
 description: "The one file that renders Chat's starter screen, what its real props do, and a full walkthrough of adding a feature end to end."
 ---
 
-# Your first feature in Chat
+# Your First Feature
 
 This page is for developers extending the [Chat template](/docs/template-chat). It covers the single file that renders the starter chat screen, then walks through everything the agent typically touches when you ask for a real feature.
 
@@ -96,7 +96,7 @@ Most first features follow the same shape: a table, one or two actions, a route,
 
 > Add a data model for `notes`. A note has an id, title, body, and owner. Render a notes page at `/notes`, add create/list actions, and keep chat able to create notes.
 
-Chat ships with no `server/db/schema.ts` at all (see [What's not in it](/docs/template-chat#not-in-it)), so the first change is a new file, following the same `table`/`text`/`ownableColumns` shape every other template uses:
+Chat ships with no `server/db/schema.ts` at all (see [What ships](/docs/template-chat#what-ships)), so the first change is a new file, following the same `table`/`text`/`ownableColumns` shape every other template uses:
 
 <Diff
   id="doc-block-chat5"
@@ -139,7 +139,7 @@ Use this when your model orchestration already lives elsewhere, but you still wa
 
 ## What's next
 
-- [**Chat Template**](/docs/template-chat) — what ships by default and when to pick it
-- [**Chat — runtime and admin surfaces**](/docs/template-chat-developers) — core tables, auth, and the admin pages
+- [**Chat**](/docs/template-chat) — what ships by default and when to pick it
+- [**Chat: Developer Guide**](/docs/template-chat-developers) — quick start, actions, core tables, auth, and the admin pages
 - [**Actions**](/docs/actions-overview) — the action system chat and UI both call
 - [**Native Chat UI**](/docs/native-chat-ui) — chat surface primitives and runtime options

package/docs/content/template-chat.mdx

@@ -1,13 +1,30 @@
 ---
-title: "Chat Template"
+title: "Chat"
 description: "A minimal chat-first agent-native app: durable chat threads, actions, application state, live sync, auth, and room to add your own UI."
 ---
 
-# Chat Template
+# Chat
 
-Chat is the plainest agent-native starting point: a ChatGPT-style shell with chat at the center, a thread list, auth, and one example action — nothing domain-specific. It's for developers who want a real, deployable app to build their own agent and screens on top of, not a finished product for a specific job.
+Chat is the plainest agent-native starting point: a ChatGPT-style shell with
+chat at the center, a thread list, auth, and one example action, nothing
+domain-specific. It's for developers who want a real, deployable app to build
+their own agent and screens on top of, not a finished product for a specific
+job.
 
-If you want a finished domain product shape, start from [Calendar](/docs/template-calendar), [Mail](/docs/template-mail), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics), or another domain template. If you truly do not need a browser UI yet, see [Automation-First Apps](/docs/pure-agent-apps).
+If you want a finished domain product shape, start from
+[Calendar](/docs/template-calendar), [Mail](/docs/template-mail),
+[Content](/docs/template-content), [Forms](/docs/template-forms),
+[Analytics](/docs/template-analytics), or another domain template. If you
+truly do not need a browser UI yet, see [Automation-First
+Apps](/docs/pure-agent-apps).
+
+<Cards columns={1}>
+
+### [Try it out now →](https://chat.agent-native.com)
+
+See Chat live: start a real conversation with the agent, no setup required.
+
+</Cards>
 
 <WireframeBlock id="doc-block-chat1">
   <Screen
@@ -18,25 +35,40 @@ If you want a finished domain product shape, start from [Calendar](/docs/templat
   />
 </WireframeBlock>
 
-## What's in it {#whats-in-it}
+## What ships {#what-ships}
 
-- **Full-page chat** on `/` using the framework chat surface and durable chat threads.
-- **Thread list in the app sidebar** so users can create, reopen, rename, pin, and archive chats.
-- **Agent chat plugin** pre-configured so the chat talks to the built-in app-agent loop once your agent credentials are set.
-- **Auth** via Better Auth — login, signup, sessions, organizations. See [Chat — runtime and admin surfaces](/docs/template-chat-developers#auth) for how sessions, orgs, and dev-mode email verification are configured.
-- **Actions directory** with one example (`actions/hello.ts`) plus the standard `view-screen` and `navigate` actions.
-- **The framework's core tables** for chat threads, application state, settings, sessions, resources, and run history — plus a Database admin page and an Observability dashboard mounted by default, whether or not you ever open them. See [Chat — runtime and admin surfaces](/docs/template-chat-developers).
-- **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to SQL.
-- **Extensions** routes mounted by default too, for sandboxed mini-apps your users build inside the chat later. See [Extensions](/docs/extensions).
-- **AGENTS.md** with chat-first guidance for adding actions, routes, skills, and application state.
+<Comparison>
 
-## What's _not_ in it {#not-in-it}
+### :green: Included
 
-- No domain tables or seed data.
-- No dashboards, lists, charts, forms, or provider integrations.
-- No domain-specific actions beyond the example stub.
+- Full-page chat on `/` using the framework chat surface and durable chat
+  threads
+- Thread list in the app sidebar to create, reopen, rename, pin, and archive
+  chats
+- The built-in app-agent loop, pre-configured for the chat plugin
+- Auth via Better Auth: login, signup, sessions, organizations
+- An actions directory with one example (`actions/hello.ts`) plus the
+  standard `view-screen` and `navigate` actions
+- The framework's core tables for chat threads, application state, settings,
+  sessions, resources, and run history, plus a Database admin page and an
+  Observability dashboard, mounted whether or not you ever open them
+- Live sync (`useDbSync`) already wired so the UI refreshes when the agent
+  writes to SQL
+- Extensions routes mounted by default, for sandboxed mini-apps your users
+  build inside chat later
+- AGENTS.md with chat-first guidance for adding actions, routes, skills, and
+  application state
 
-That's the point. Chat is a thin, useful default shell for your own agent, not a domain product pretending to be generic.
+### :red: Not included
+
+- Domain tables or seed data
+- Dashboards, lists, charts, forms, or provider integrations
+- Domain-specific actions beyond the example stub
+
+</Comparison>
+
+That's the point. Chat is a thin, useful default shell for your own agent, not
+a domain product pretending to be generic.
 
 <Diagram id="doc-block-chat2" title="What ships in the Chat shell" summary={"A thin chat surface over the framework's standard runtime — actions, durable threads, live sync, and auth — with room to add your own UI."}>
 
@@ -104,34 +136,50 @@ That's the point. Chat is a thin, useful default shell for your own agent, not a
 
 ## When to pick it {#when-to-pick}
 
-- **You want a basic app users can talk to immediately** and then extend with actions and UI.
-- **You want the default Agent-Native on-ramp**: chat first, then actions, native results, and app pages.
-- **You want to plug your own agent backend into a familiar chat UI** while keeping Agent-Native's actions, state, auth, and deployment shape.
-- **You are prototyping a custom internal tool** that does not match a domain template.
+- **You want a basic app users can talk to immediately** and then extend with
+  actions and UI.
+- **You want the default Agent-Native on-ramp**: chat first, then actions,
+  native results, and app pages.
+- **You want to plug your own agent backend into a familiar chat UI** while
+  keeping Agent-Native's actions, state, auth, and deployment shape.
+- **You are prototyping a custom internal tool** that does not match a domain
+  template.
 
-## Scaffolding {#scaffolding}
+## Get started {#get-started}
 
 ```bash
 npx @agent-native/core@latest create my-chat-app --standalone --template chat
 ```
 
-See [Getting started](/docs/getting-started) for `cd`, install, first run, and what the generated app looks like.
-
-For automation-first work with no browser UI at all:
+See [Chat: Developer Guide](/docs/template-chat-developers#quick-start) for
+install, first run, and connecting an LLM. For automation-first work with no
+browser UI at all, scaffold with `--headless` instead:
 
 ```bash
 npx @agent-native/core@latest create my-agent --headless
 ```
 
-Use it for scheduled jobs, queues, CLI loops, or external-agent workflows where chat and app pages are not useful yet. The key invariant stays the same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI. See [Automation-First Apps](/docs/pure-agent-apps) for that path in depth.
+Use it for scheduled jobs, queues, CLI loops, or external-agent workflows
+where chat and app pages are not useful yet. The key invariant stays the
+same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI.
+See [Automation-First Apps](/docs/pure-agent-apps) for that path in depth.
 
 ## What's next
 
-- [**Your first feature in Chat**](/docs/template-chat-first-edits) — the starter chat route, annotated, plus a full walkthrough of adding a real feature
-- [**Chat — runtime and admin surfaces**](/docs/template-chat-developers) — core tables, auth, and the Database/Observability/Extensions pages that ship by default
-- [**Getting Started**](/docs/getting-started) — build the chat-first path from action to inline result to app page
-- [**Templates**](/docs/cloneable-saas) — the Cloneable SaaS model, and every domain template to start from instead
-- [**Agent Surfaces**](/docs/agent-surfaces) — chat, inline UI, app pages, embedded, automation, and external-agent patterns
-- [**Actions**](/docs/actions-overview) — the action system chat and UI both call
-- [**Native Chat UI**](/docs/native-chat-ui) — chat surface primitives and runtime options
-- [**Automation-First Apps**](/docs/pure-agent-apps) — no-browser workflows for jobs, queues, scripts, and external agents
+- [**Your First Feature in Chat**](/docs/template-chat-first-edits) — the
+  starter chat route, annotated, plus a full walkthrough of adding a real
+  feature
+- [**Chat: Developer Guide**](/docs/template-chat-developers) — quick start,
+  actions, core tables, auth, and the admin pages that ship by default
+- [**Getting Started**](/docs/getting-started) — build the chat-first path
+  from action to inline result to app page
+- [**Templates**](/docs/cloneable-saas) — the Cloneable SaaS model, and every
+  domain template to start from instead
+- [**Agent Surfaces**](/docs/agent-surfaces) — chat, inline UI, app pages,
+  embedded, automation, and external-agent patterns
+- [**Actions**](/docs/actions-overview) — the action system chat and UI both
+  call
+- [**Native Chat UI**](/docs/native-chat-ui) — chat surface primitives and
+  runtime options
+- [**Automation-First Apps**](/docs/pure-agent-apps) — no-browser workflows
+  for jobs, queues, scripts, and external agents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.175.1",
+  "version": "0.175.2-nightly-20260826165737",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -134,6 +134,7 @@
     "./client/route-chunk-recovery": "./dist/client/route-chunk-recovery/index.js",
     "./client/settings": "./dist/client/settings/index.js",
     "./client/use-db-sync": "./dist/client/use-db-sync.js",
+    "./client/zoom-gesture": "./dist/client/zoom-gesture.js",
     "./client/ui": "./dist/client/ui/index.js",
     "./client/uploads": "./dist/client/uploads/index.js",
     "./client/widgets": "./dist/client/widgets/index.js",
@@ -432,7 +433,7 @@
     "yjs": "^13.6.32",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.5.15",
-    "@agent-native/toolkit": "^0.17.1"
+    "@agent-native/toolkit": "^0.17.2-nightly-20260826165737"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",