@agent-native/core 0.145.5 → 0.145.6

package/docs/content/environment-variables.mdx

@@ -24,44 +24,44 @@ deployment-specific values in the environment or scoped secret store.
 
 ## Common application and deployment variables
 
-| Variable                                    | What it controls                                                                                | Supported values or format                                                                                     |
-| ------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `DATABASE_URL`                              | Primary SQL connection. Local development falls back to SQLite when it is unset.                | A provider-specific SQL URL, or unset for local SQLite.                                                        |
-| `DATABASE_AUTH_TOKEN`                       | Separate database token when the database provider requires one.                                | An opaque provider token, or unset when the URL includes authentication.                                       |
-| `APP_URL`                                   | Canonical public origin used for auth, OAuth, A2A, webhooks, and generated links.               | An absolute public `http(s)` origin.                                                                           |
-| `BETTER_AUTH_URL`                           | Public origin used by Better Auth for cookies and callbacks.                                    | An absolute public `http(s)` origin.                                                                           |
-| `APP_BASE_PATH`                             | Mounts an app under a path such as `/mail`.                                                     | Unset for a standalone app, or a slash-prefixed path.                                                          |
-| `PORT`                                      | Local Node/Nitro server port.                                                                   | A decimal TCP port.                                                                                            |
-| `NITRO_PRESET`                              | Build and deployment adapter.                                                                   | A preset supported by the target host, such as `node`, `netlify`, `vercel`, or `cloudflare_pages`.             |
-| `BETTER_AUTH_SECRET`                        | Better Auth session signing and the legacy encryption fallback. Required in production.         | A fresh random value of at least 32 characters.                                                                |
-| `OAUTH_STATE_SECRET`                        | Dedicated signing key for OAuth state envelopes. Falls back to `BETTER_AUTH_SECRET` when unset. | A fresh random value of at least 32 characters.                                                                |
-| `A2A_SECRET`                                | Shared HMAC for trusted cross-app A2A calls and signed handoffs.                                | One shared random value across trusted apps.                                                                   |
-| `SECRETS_ENCRYPTION_KEY`                    | Legacy app-local/shared encryption fallback.                                                    | A stable encryption key; prefer the workspace key for new shared vaults.                                       |
-| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Stable encryption key for a workspace-shared secrets vault.                                     | The same stable key in every app that reads the vault.                                                         |
-| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation.                                                         | The old key only; remove it after migration.                                                                   |
-| `ANTHROPIC_API_KEY`                         | Optional deploy-level fallback for the embedded production agent.                               | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
-| `AGENT_ENGINE`                              | Explicitly selects the agent engine instead of auto-detecting from provider keys.               | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
-| `AGENT_ENGINE_PREFER_BYO_KEY`               | Prefers a provider key you set over the managed Builder gateway during auto-detection.          | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
-| `AUTH_MODE`                                 | Selects the local authentication behavior used by CLI and agent flows.                          | Unset or `local`; this is not a browser login bypass.                                                          |
-| `AUTH_DISABLED`                             | Disables auth for local or preview-only work.                                                   | `true` or `1`; never use on a public production app.                                                           |
-| `AUTH_MAGIC_LINK`                           | Controls the password-first versus magic-link sign-in path.                                     | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
-| `AUTH_SKIP_EMAIL_VERIFICATION`              | Skips signup email verification for local QA or previews.                                       | `1`; never use it to weaken production auth.                                                                   |
-| `ACCESS_TOKEN` / `ACCESS_TOKENS`            | Static bearer fallback for MCP and Connect clients.                                             | One token or a delimited token list; these are not browser auth.                                               |
-| `AGENT_PROD_CODE_EXECUTION`                 | Production code-execution policy.                                                               | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/deployment#production-code-execution). |
-| `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide public SSR shell cache policy.                                                  | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/deployment#ssr-caching).       |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Lets a scale-to-zero database autosuspend instead of being woken every minute.                  | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
-| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Keep-warm cadence override.                                                                     | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                         |
-| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drops only the background-function warm and keeps the server warm.                              | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
-| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`     | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work.  | `1`; queued work is not retried without another driver.                                                        |
-| `AGENT_NATIVE_SKIP_ENSURE_TABLES`           | Skips on-demand schema DDL for an already-migrated database.                                    | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set.     |
-| `COOKIE_DOMAIN`                             | Shares auth cookies across same-database subdomains when explicitly configured.                 | A cookie domain.                                                                                               |
-| `CORS_ALLOWED_ORIGINS`                      | Cross-origin request allowlist.                                                                 | A comma-separated list of exact origins.                                                                       |
-| `WEBHOOK_BASE_URL`                          | Optional public base URL for self-callback and webhook targets.                                 | An absolute public `http(s)` origin.                                                                           |
-| `APP_NAME`                                  | App identity used by workspace and app-scoped configuration.                                    | A short app name, such as `mail`.                                                                              |
-| `APP_ID` / `APP_TEMPLATE`                   | Optional app identity and generated-template metadata.                                          | App-owned strings.                                                                                             |
-| `NODE_ENV`                                  | Node runtime mode.                                                                              | Normally `development`, `test`, or `production`.                                                               |
-| `CI`                                        | Marks CI-driven test and build behavior.                                                        | A CI-provided truthy value.                                                                                    |
-| `DEBUG`                                     | Enables resolver-specific debug logging.                                                        | A resolver-supported truthy or namespace value.                                                                |
+| Variable                                    | What it controls                                                                                                                                                        | Supported values or format                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`                              | Primary SQL connection. Local development falls back to SQLite when it is unset. Production also accepts `<APP_NAME>_DATABASE_URL` or Netlify's `NETLIFY_DATABASE_URL`. | A provider-specific SQL URL, or unset for local SQLite.                                                        |
+| `DATABASE_AUTH_TOKEN`                       | Separate database token when the database provider requires one.                                                                                                        | An opaque provider token, or unset when the URL includes authentication.                                       |
+| `APP_URL`                                   | Optional canonical public origin used for auth, OAuth, A2A, webhooks, and generated links. Netlify and Vercel metadata are inferred when it is unset.                   | An absolute public `http(s)` origin.                                                                           |
+| `BETTER_AUTH_URL`                           | Optional Better Auth origin override. Known template or request context, `APP_URL`, and platform metadata such as Netlify or Vercel are used when it is unset.          | An absolute public `http(s)` origin.                                                                           |
+| `APP_BASE_PATH`                             | Mounts an app under a path such as `/mail`.                                                                                                                             | Unset for a standalone app, or a slash-prefixed path.                                                          |
+| `PORT`                                      | Local Node/Nitro server port.                                                                                                                                           | A decimal TCP port.                                                                                            |
+| `NITRO_PRESET`                              | Build and deployment adapter.                                                                                                                                           | A preset supported by the target host, such as `node`, `netlify`, `vercel`, or `cloudflare_pages`.             |
+| `BETTER_AUTH_SECRET`                        | Stable Better Auth session signing secret for standalone production apps. Workspace deploys can derive it from `A2A_SECRET`.                                            | A fresh random value of at least 32 characters.                                                                |
+| `OAUTH_STATE_SECRET`                        | Dedicated signing key for OAuth state envelopes. Falls back to `BETTER_AUTH_SECRET` when unset.                                                                         | A fresh random value of at least 32 characters.                                                                |
+| `A2A_SECRET`                                | Shared HMAC for trusted cross-app A2A calls and signed handoffs.                                                                                                        | One shared random value across trusted apps.                                                                   |
+| `SECRETS_ENCRYPTION_KEY`                    | Legacy app-local/shared encryption fallback.                                                                                                                            | A stable encryption key; prefer the workspace key for new shared vaults.                                       |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY`          | Stable encryption key for a workspace-shared secrets vault.                                                                                                             | The same stable key in every app that reads the vault.                                                         |
+| `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS` | Previous workspace key during rotation.                                                                                                                                 | The old key only; remove it after migration.                                                                   |
+| `ANTHROPIC_API_KEY`                         | Optional deploy-level fallback for the embedded production agent.                                                                                                       | An API key; prefer scoped credentials for multi-tenant apps.                                                   |
+| `AGENT_ENGINE`                              | Explicitly selects the agent engine instead of auto-detecting from provider keys.                                                                                       | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                      |
+| `AGENT_ENGINE_PREFER_BYO_KEY`               | Prefers a provider key you set over the managed Builder gateway during auto-detection.                                                                                  | `true` or `1`; Builder still applies as the fallback when no provider key is set.                              |
+| `AUTH_MODE`                                 | Selects the local authentication behavior used by CLI and agent flows.                                                                                                  | Unset or `local`; this is not a browser login bypass.                                                          |
+| `AUTH_DISABLED`                             | Disables auth for local or preview-only work. Unset already means false.                                                                                                | `true` or `1`; never use on a public production app.                                                           |
+| `AUTH_MAGIC_LINK`                           | Controls the password-first versus magic-link sign-in path.                                                                                                             | `0` keeps password-first sign-in; otherwise a configured email transport can enable magic links.               |
+| `AUTH_SKIP_EMAIL_VERIFICATION`              | Skips signup email verification for local QA or previews.                                                                                                               | `1`; never use it to weaken production auth.                                                                   |
+| `ACCESS_TOKEN` / `ACCESS_TOKENS`            | Static bearer fallback for MCP and Connect clients.                                                                                                                     | One token or a delimited token list; these are not browser auth.                                               |
+| `AGENT_PROD_CODE_EXECUTION`                 | Production code-execution policy.                                                                                                                                       | `off`, `sandboxed`, or `trusted`. See [Production Code Execution](/docs/deployment#production-code-execution). |
+| `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide public SSR shell cache policy.                                                                                                                          | Unset/`on`, `off`, or a duration such as `30s` or `5m`. See [SSR Caching](/docs/deployment#ssr-caching).       |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM`            | Lets a scale-to-zero database autosuspend instead of being woken every minute.                                                                                          | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_KEEP_WARM_SCHEDULE`           | Keep-warm cadence override.                                                                                                                                             | A 5-field cron expression such as `*/5 * * * *`; an unparseable value fails the build.                         |
+| `AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND` | Drops only the background-function warm and keeps the server warm.                                                                                                      | `1`; see [Keep-warm](/docs/deployment#netlify-keep-warm).                                                      |
+| `AGENT_NATIVE_DISABLE_INPROCESS_SWEEPS`     | Turns off the in-process backstop sweep timers where a durable scheduler drives the same work.                                                                          | `1`; queued work is not retried without another driver.                                                        |
+| `AGENT_NATIVE_SKIP_ENSURE_TABLES`           | Skips on-demand schema DDL for an already-migrated database.                                                                                                            | `1`; see [On-demand schema DDL](/docs/deployment#skip-ensure-tables). You own migrations when this is set.     |
+| `COOKIE_DOMAIN`                             | Shares auth cookies across same-database subdomains when explicitly configured.                                                                                         | A cookie domain.                                                                                               |
+| `CORS_ALLOWED_ORIGINS`                      | Cross-origin request allowlist.                                                                                                                                         | A comma-separated list of exact origins.                                                                       |
+| `WEBHOOK_BASE_URL`                          | Optional public base URL for self-callback and webhook targets.                                                                                                         | An absolute public `http(s)` origin.                                                                           |
+| `APP_NAME`                                  | App identity used by workspace and app-scoped configuration.                                                                                                            | A short app name, such as `mail`.                                                                              |
+| `APP_ID` / `APP_TEMPLATE`                   | Optional app identity and generated-template metadata.                                                                                                                  | App-owned strings.                                                                                             |
+| `NODE_ENV`                                  | Node runtime mode.                                                                                                                                                      | Normally `development`, `test`, or `production`.                                                               |
+| `CI`                                        | Marks CI-driven test and build behavior.                                                                                                                                | A CI-provided truthy value.                                                                                    |
+| `DEBUG`                                     | Enables resolver-specific debug logging.                                                                                                                                | A resolver-supported truthy or namespace value.                                                                |
 
 Generate strong secrets with:
 
@@ -69,6 +69,31 @@ Generate strong secrets with:
 openssl rand -hex 32
 ```
 
+## What a normal deployment actually needs
+
+Do not copy a five-variable auth checklist into every app. The framework
+defaults `AUTH_DISABLED` to false and infers `BETTER_AUTH_URL` from known
+template/request context and hosting platform metadata. A standalone production app normally
+needs only one auth-specific deploy secret, `BETTER_AUTH_SECRET`, plus a
+persistent SQL URL. Workspace deployments can use the already-required
+`A2A_SECRET` to derive the Better Auth secret and trusted internal signing
+keys.
+
+Local development intentionally uses SQLite when no database URL is present
+and an ephemeral Better Auth secret when no local secret is configured. Those
+fallbacks keep `pnpm dev` zero-setup, but they are not silently accepted as
+production configuration. The build and runtime diagnostics report missing or
+weak auth/A2A secrets, local databases, auth disabled in production, invalid
+public origins, and app-declared required keys without including any secret
+values.
+
+Every framework app exposes the redacted report at
+`/_agent-native/ping?configuration=1`. The shared provider shell turns a
+non-healthy production report into a warning or error chip with a **Copy
+prompt for AI** button. `agent-native.ts` or its compatibility aliases can add
+non-secret requirements under `runtime.environment.required`; set the actual
+values in Netlify, Vercel, or the deployment's secret store.
+
 ## Google sign-in
 
 Set one complete Google OAuth client pair to show the Google sign-in flow.

package/docs/content/getting-started-actions.mdx

@@ -32,27 +32,35 @@ export default defineAction({
     text: z.string().default("The quick brown fox jumps over the lazy dog."),
   }),
   outputSchema: dataChartWidgetResultSchema,
+  http: { method: "GET" },
   chatUI: {
     renderer: ACTION_CHAT_UI_DATA_CHART_RENDERER,
     title: "Text stats",
   },
   readOnly: true,
   run: async ({ text }) => {
+    const summary = {
+      characters: text.length,
+      words: text.split(/\s+/).filter(Boolean).length,
+      sentences: text.split(/[.!?]+/).filter(Boolean).length,
+      paragraphs: text.split(/\n\n+/).filter(Boolean).length,
+    };
     const points = [
-      { label: "Characters", value: text.length },
-      { label: "Words", value: text.split(/\s+/).filter(Boolean).length },
+      { label: "Characters", value: summary.characters },
+      { label: "Words", value: summary.words },
       {
         label: "Sentences",
-        value: text.split(/[.!?]+/).filter(Boolean).length,
+        value: summary.sentences,
       },
       {
         label: "Paragraphs",
-        value: text.split(/\n\n+/).filter(Boolean).length,
+        value: summary.paragraphs,
       },
     ];
 
     return createDataChartWidgetResult({
       title: "Text statistics",
+      summary,
       chartSeries: {
         type: "bar",
         xKey: "label",
@@ -80,5 +88,6 @@ custom native components, see [Native Chat UI](/docs/native-chat-ui).
 
 ## Continue
 
-Continue with [Persist Data in SQL](/docs/getting-started-database) to save
-analysis results for later.
+Continue with [Add a Page](/docs/getting-started-pages) to use the same action
+outside the transcript. When results need to survive conversations, return to
+[Persist Data in SQL](/docs/getting-started-database).

package/docs/content/getting-started-database.mdx

@@ -1,18 +1,20 @@
 ---
 title: "Persist Data in SQL"
-description: "Save action results to a SQL database so the agent can reference them across conversations."
+description: "Persist action results in SQL when they need to survive conversations."
 ---
 
 # Persist Data in SQL
 
-This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions)
-you defined `analyze-text`. Here you'll add a table and two actions so the
-results persist.
+This is the optional fourth part of the Getting Started series. In [Add a Page](/docs/getting-started-pages)
+you used `analyze-text` directly from a route. Here you'll add app-owned SQL
+data when results need to survive conversations.
 
 ## Add a table {#persist-data}
 
-The Chat template uses a local SQLite file by default, so no database server is
-needed for this tutorial. Add these three server files:
+Chat already includes the SQL runtime, framework tables, and a local SQLite file
+by default. You do not need to install a database, set `DATABASE_URL`, or add a
+migration for Chat's built-in tables. For a new app-owned table, add these three
+server files:
 
 1. `server/plugins/db.ts` creates the table with an additive migration.
 2. `server/db/schema.ts` describes the table for typed queries.
@@ -153,7 +155,8 @@ export default defineAction({
 ```
 
 The actions use the typed Drizzle client for app reads and writes. Raw SQL is
-only needed here for the additive migration.
+only needed here for the additive migration. Skip this page until your action
+needs durable domain data.
 
 ## Try it
 
@@ -161,9 +164,10 @@ In chat, ask the agent to do the whole flow:
 
 > Run analyze-text on "Hello world", save the result with save-text-analysis, then list my saved text analyses.
 
-The saved row is now available to the agent and to the page you'll build next.
+The saved row is now available to the agent and to any page that reads
+`list-text-analyses`.
 
 ## Continue
 
-Continue with [Add a Page](/docs/getting-started-pages) to display the saved
-rows in a route.
+You now have durable app data. Continue with [Key Concepts](/docs/key-concepts)
+to learn how actions, SQL, and pages fit together.

package/docs/content/getting-started-pages.mdx

@@ -1,13 +1,14 @@
 ---
 title: "Add a Page"
-description: "Build a React route that displays your saved data and lets the agent open it."
+description: "Build a React route that calls your action and displays its result."
 ---
 
 # Add a Page
 
-This is part four of the Getting Started series. In [Persist Data in SQL](/docs/getting-started-database)
-you saved analysis results. Here you'll build a route that reads those same rows
-through `list-text-analyses`.
+This is part three of the Getting Started series. In [Add an Action](/docs/getting-started-actions)
+you created `analyze-text`. Here you'll call that same action from a route. No
+database is needed yet: Chat already includes the SQL runtime for when you need
+to persist domain data.
 
 ## Create the route {#add-a-page}
 
@@ -19,50 +20,45 @@ Route files in `app/routes/` are picked up automatically. Create
 import { useActionQuery } from "@agent-native/core/client/hooks";
 
 type TextAnalysis = {
-  id: string;
-  input: string;
-  charCount: number;
-  wordCount: number;
-  sentenceCount: number;
-  paragraphCount: number;
-  createdAt: string;
+  summary: {
+    characters: number;
+    words: number;
+    sentences: number;
+    paragraphs: number;
+  };
 };
 
 export default function TextAnalysesRoute() {
-  const { data: analyses = [] } = useActionQuery<TextAnalysis[]>(
-    "list-text-analyses",
-    {},
+  const { data: analysis, isLoading } = useActionQuery<TextAnalysis>(
+    "analyze-text",
+    { text: "Hello world. How are you today?" },
   );
 
   return (
     <main className="mx-auto flex max-w-3xl flex-col gap-6 p-6">
       <header>
         <h1 className="text-2xl font-semibold">Text analyses</h1>
-        <p className="text-muted-foreground">Results saved by the agent.</p>
+        <p className="text-muted-foreground">The same action, on a page.</p>
       </header>
-      <section className="flex flex-col gap-3">
-        {analyses.length === 0 && (
-          <p className="text-muted-foreground">No analyses saved yet.</p>
-        )}
-        {analyses.map((analysis) => (
-          <article key={analysis.id} className="rounded-lg border p-4">
-            <p className="text-sm font-medium">{analysis.input}</p>
-            <p className="text-xs text-muted-foreground">
-              {analysis.wordCount} words, {analysis.charCount} characters,{" "}
-              {analysis.sentenceCount} sentences, {analysis.paragraphCount}{" "}
-              paragraphs
-            </p>
-          </article>
-        ))}
+      <section className="grid gap-3 sm:grid-cols-2">
+        {isLoading && <p className="text-muted-foreground">Analyzing...</p>}
+        {analysis &&
+          Object.entries(analysis.summary).map(([label, value]) => (
+            <article key={label} className="rounded-lg border p-4">
+              <p className="text-sm capitalize text-muted-foreground">
+                {label}
+              </p>
+              <p className="text-2xl font-semibold">{value}</p>
+            </article>
+          ))}
       </section>
     </main>
   );
 }
 ```
 
-`useActionQuery` calls the same action the agent uses. It also refreshes when a
-mutating action completes, so a newly saved analysis appears without a custom
-API route or a second data layer.
+`useActionQuery` calls the same read-only action the agent uses. The page does
+not need a custom API route, a second data layer, or SQL yet.
 
 Open `http://localhost:8080/text-analyses`, or ask the agent:
 
@@ -74,6 +70,7 @@ patterns, see [Context Awareness](/docs/context-awareness).
 
 ## Continue
 
-You've built a chat app with an action, SQL-backed data, and a page that reads
-the same source of truth. Continue with [Key Concepts](/docs/key-concepts) or
-[Agent Surfaces](/docs/agent-surfaces) to explore the architecture behind it.
+You've built a chat app with an action and a page that calls the same source of
+truth. Continue with [Persist Data in SQL](/docs/getting-started-database) when
+results need to persist, or explore [Key Concepts](/docs/key-concepts) and
+[Agent Surfaces](/docs/agent-surfaces).

package/docs/content/getting-started.mdx

@@ -1,13 +1,14 @@
 ---
 title: "Getting Started"
-description: "Create a Chat app and configure an agent, then extend it with an action, SQL data, and a page."
+description: "Create a Chat app and configure an agent, then extend it with an action and a page."
 ---
 
 # Getting Started
 
 Agent-Native apps give the agent and the UI the same [actions](/docs/actions),
 SQL data, and application state. This is the hands-on path: start with chat,
-then add the surfaces your workflow needs.
+then add an action and a page. SQL is already configured in Chat and becomes an
+optional next step when results need to persist.
 
 <Steps>
 
@@ -21,13 +22,13 @@ configure an agent. You'll have a working chat app to extend.
 
 Define a typed text analyzer and render its result as a chart in the chat.
 
-### Persist data in SQL
+### Add a page
 
-Add a table, a save action, and a list action so results survive conversations.
+Build a React route that calls the same action outside the transcript.
 
-### Add a page
+### Persist data in SQL (optional)
 
-Build a React route that lists saved analyses.
+Add a table and persistence actions when results need to survive conversations.
 
 </Steps>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.145.5",
+  "version": "0.145.6",
   "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": {

package/src/templates/chat/.agents/skills/actions/SKILL.md

@@ -20,6 +20,24 @@ Before creating any custom REST/API route for app data, inspect `actions/` and t
 
 **Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
 
+## Keep actions deterministic and composable
+
+An action may call a provider API, validate or normalize data, and persist
+records without being an AI feature. Keep those operations deterministic,
+focused, and independently useful to the agent. Do not put LLM calls or a
+second model runtime in ordinary actions. The only narrow exception is the
+`completeText()` text-in/text-out escape hatch described in
+`delegate-to-agent`; it must not own tools, chat history, run state, side
+effects, or user steering.
+
+When a workflow is framed as research, analysis, generation, recommendation,
+or synthesis, or spans several provider calls and writes, route the user into
+the AgentSidebar and let the agent orchestrate focused actions. Do not hide an
+AI-shaped workflow behind one opaque `generate-*` or `create-*` action just
+because its implementation is deterministic. A visible user-initiated run
+should use `sendToAgentChat({ openSidebar: true })`, and its follow-ups should
+continue in the same thread rather than a separate freeform input.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.

package/src/templates/chat/.agents/skills/agent-native-toolkit/SKILL.md

@@ -56,6 +56,11 @@ The repeated app shell has two distinct navigation surfaces:
   labeled as local, preview, or analyze. For original/generated review, stack
   the source above the result by default and use side-by-side only for short,
   highly scannable content.
+- Deterministic implementation does not make an AI-shaped experience
+  deterministic. If the user expects research, analysis, generation,
+  recommendation, synthesis, visible progress, or steering, route the button
+  to the AgentSidebar and let the agent call focused actions. Keep revisions in
+  the same thread instead of adding a second freeform prompt box.
 - Standalone apps with `AgentSidebar` must resolve one assistant-ui runtime
   context. Match direct assistant-ui pins to the installed core/toolkit peer
   graph, use Vite dedupe/aliases when linked dependencies can split contexts,

package/src/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -14,11 +14,21 @@ metadata:
 
 ## Rule
 
-The UI never calls an LLM directly. Product workflows are delegated to the
-agent through the chat bridge so users can see, steer, and audit the work.
-Server-side one-shot model calls are an explicit escape hatch for narrow text
-transforms only; use `completeText()` from `@agent-native/core/server` when the
-work intentionally does not need tools, chat history, or run state.
+The app's default AI surface is the agent chat. Any user-facing work that asks
+the model to research, analyze, generate, recommend, synthesize, or reason over
+multiple steps must start or continue in the AgentSidebar so users can see,
+steer, and audit the work. UI buttons use `sendToAgentChat()` with
+`openSidebar: true`, and follow-up or revision text belongs in that same thread
+instead of a second app-local textbox.
+
+Actions are tools, not alternate AI runtimes. Keep them deterministic and
+focused: provider reads, validation, deterministic transforms, CRUD, and
+persistence are good action work. Let the agent orchestrate several such tools
+when the workflow is AI-shaped or user-steerable. Server-side one-shot model
+calls are a rare escape hatch for narrow text transforms only; use
+`completeText()` from `@agent-native/core/server` only when the work
+intentionally does not need tools, chat history, run state, side effects, or
+user steering.
 
 ## Why
 
@@ -35,6 +45,7 @@ sendToAgentChat({
   message: "Generate a summary of this document",
   context: documentContent, // optional hidden context (not shown in chat UI)
   submit: true, // auto-submit to the agent
+  openSidebar: true,
 });
 ```
 
@@ -56,6 +67,10 @@ sendToAgentChat({
 This is still a full agent run: tools, actions, thread state, and run tracking
 all remain active. It simply does not focus or open the sidebar.
 
+Use this silent form only for explicitly background or system-initiated work.
+It is not the default for a user clicking an AI-labeled button; visible work
+should open the sidebar so the user can follow and redirect the run.
+
 **From scripts (Node):**
 
 ```ts
@@ -77,8 +92,9 @@ const result = await completeText({
 });
 ```
 
-Wrap user-facing uses in actions so the UI and agent share the same operation.
-Do not call provider SDKs directly.
+If the narrow exception is exposed to the UI, wrap it in an action so the UI
+and agent share the same operation. Keep it clearly non-conversational and do
+not call provider SDKs directly.
 
 **From the UI, detecting when agent is done:**
 
@@ -97,9 +113,9 @@ The `submit` option controls whether the message is sent automatically or placed
 
 | `submit` value | Behavior                                | Use when                                                                            |
 | -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
-| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
-| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
-| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
+| `true`         | Auto-submits to the agent immediately   | Routine operations with clear intent; keep `openSidebar: true` for visible work |
+| `false`        | Prefills the AgentSidebar composer      | Review, edit, or add detail before the run; use the existing sidebar thread   |
+| omitted        | Uses the project's default setting      | General-purpose delegation                                                       |
 
 ```ts
 // Auto-submit: routine operation
@@ -109,61 +125,43 @@ sendToAgentChat({ message: "Update the project summary", submit: true });
 sendToAgentChat({
   message: "Delete all projects older than 30 days",
   submit: false,
+  openSidebar: true,
 });
 ```
 
-## Capture user input first when generating from a prompt
-
-Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
+## Capture user input in the sidebar
 
-**Bad** — auto-submits a placeholder message; the user never said what they wanted:
+The AgentSidebar composer is the default prompt surface. When a button needs
+the user to describe what to create, prefill that same composer and let the
+user edit or complete it:
 
 ```tsx
 <Button
   onClick={() =>
-    sendToAgentChat({ message: "make a design", submit: true })
+    sendToAgentChat({
+      message: "Help me create a research report from this brief:",
+      context: researchBrief,
+      submit: false,
+      openSidebar: true,
+    })
   }
 >
-  New Design
+  Start in agent
 </Button>
 ```
 
-**Good** — Popover anchored to the button captures the prompt, then submits it:
-
-```tsx
-<Popover open={open} onOpenChange={setOpen}>
-  <PopoverTrigger asChild>
-    <Button>New Design</Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-96">
-    <Textarea
-      autoFocus
-      value={prompt}
-      onChange={(e) => setPrompt(e.target.value)}
-      placeholder="What do you want to design?"
-    />
-    <Button
-      onClick={() => {
-        sendToAgentChat({ message: prompt, submit: true });
-        setOpen(false);
-        setPrompt("");
-      }}
-    >
-      Create
-    </Button>
-  </PopoverContent>
-</Popover>
-```
-
-**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
-
-**Auto-submit without input is fine when intent is unambiguous:**
+Never auto-submit a generic creative prompt when the user has not said what
+they want. Auto-submit without additional input is fine when intent is
+unambiguous:
 
 - "Try to fix" on a tool error — submits the error details with a clear fix instruction
 - "Retry the last operation" after a transient failure
 - Single-purpose buttons where there is nothing meaningful for the user to add
 
-If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
+Use a Popover only for compact, structured parameters the UI must validate,
+such as a date range, target, or approval choice. Do not add a second freeform
+prompt or follow-up textbox for an AI workflow; keep the conversation and
+revisions in the AgentSidebar thread.
 
 ## Delegating to a Sub-Agent (Agent Teams)
 

package/src/templates/chat/.agents/skills/frontend-design/SKILL.md

@@ -130,6 +130,7 @@ passed this requirement yet.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
 - Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.