@agent-native/core 0.92.0 → 0.92.1

package/corpus/templates/dispatch/app/routes/team.tsx

@@ -1,5 +1,5 @@
 import { Navigate } from "react-router";
 
 export default function TeamRoute() {
-  return <Navigate to="/settings#team" replace />;
+  return <Navigate to="/settings#organization" replace />;
 }

package/corpus/templates/forms/.agents/skills/actions/SKILL.md

@@ -377,6 +377,11 @@ Most operations should be actions. You only need custom routes in `server/routes
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
 
+When the agent needs a durable image or file URL, call the core `upload-image`
+action or use `uploadFile()` in server code. Do not write base64 into SQL,
+markdown, deck/design JSON, or action results. `_agentImages` on action results
+is for ephemeral vision previews only, not persistence.
+
 If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
 
 ## Legacy Pattern (bare export)

package/corpus/templates/forms/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback — it detects DB timestamp changes even when the write happened in a different process or invocation.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/forms/.agents/skills/security/SKILL.md

@@ -51,6 +51,13 @@ export default defineAction({
 
 The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
 
+## Large Payloads
+
+Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
+or `application_state`. Route uploads through the file-upload provider and store
+references. This prevents database bloat, slow hot paths, and accidental secret
+or customer-data embedding inside binary payloads.
+
 ## SQL Injection
 
 Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:

package/corpus/templates/forms/.agents/skills/storing-data/SKILL.md

@@ -13,7 +13,9 @@ metadata:
 
 ## Rule
 
-All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
 
 **Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
 
@@ -136,6 +138,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Use the `settings` store for app configuration and user preferences
 - Use `application-state` for ephemeral UI state that the agent and UI share
 - Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
 - Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
 - Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
 - Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
@@ -146,6 +149,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
 - Don't keep state only in memory (server variables, global stores)
 - Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
 - Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
 - Don't write SQLite-only or Postgres-only SQL in app code
 - Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder

package/corpus/templates/forms/AGENTS.md

@@ -11,6 +11,10 @@ Detailed building, publishing, response, storage, and UI rules live in
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for form lifecycle, fields, publishing, responses, navigation,
   sharing, and database work. Do not bypass ownable access checks.

package/corpus/templates/forms/app/routes/_app.settings.tsx

@@ -49,7 +49,7 @@ export default function SettingsRoute() {
       extraTabs={agentSettingsTabs}
       generalSearchEntries={generalSearchEntries}
       general={
-        <div className="mx-auto w-full max-w-3xl space-y-6">
+        <div className="mx-auto w-full max-w-2xl space-y-6">
           <p className="text-sm leading-6 text-muted-foreground">
             {t("settings.description")}
           </p>
@@ -79,7 +79,7 @@ export default function SettingsRoute() {
         </div>
       }
       whatsNew={
-        <div className="mx-auto w-full max-w-3xl">
+        <div className="mx-auto w-full max-w-2xl">
           <ChangelogSettingsCard markdown={changelog} />
         </div>
       }

package/corpus/templates/forms/app/routes/_app.team.tsx

@@ -5,5 +5,5 @@ export function meta() {
 }
 
 export default function TeamRoute() {
-  return <Navigate to="/settings#team" replace />;
+  return <Navigate to="/settings#organization" replace />;
 }

package/corpus/templates/forms/shared/navigation.ts

@@ -73,7 +73,7 @@ export function formsRoutePath(target: FormsNavigationTarget): string | null {
         ? `/response-insights?formId=${encodeURIComponent(formId)}`
         : "/response-insights";
     case "team":
-      return "/settings#team";
+      return "/settings#organization";
     case "extensions":
       return "/extensions";
     case "form-preview":

package/corpus/templates/macros/.agents/skills/security/SKILL.md

@@ -51,6 +51,13 @@ export default defineAction({
 
 The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
 
+## Large Payloads
+
+Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
+or `application_state`. Route uploads through the file-upload provider and store
+references. This prevents database bloat, slow hot paths, and accidental secret
+or customer-data embedding inside binary payloads.
+
 ## SQL Injection
 
 Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:

package/corpus/templates/macros/AGENTS.md

@@ -6,6 +6,10 @@ actions and SQL state.
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for meals, foods, calorie/macro updates, voice command handling,
   stats, and navigation. Do not mutate app tables directly.

package/corpus/templates/macros/app/routes/settings.tsx

@@ -49,7 +49,7 @@ export default function SettingsRoute() {
       extraTabs={agentSettingsTabs}
       generalSearchEntries={generalSearchEntries}
       general={
-        <div className="mx-auto w-full max-w-3xl space-y-6">
+        <div className="mx-auto w-full max-w-2xl space-y-6">
           <p className="text-sm leading-6 text-muted-foreground">
             {t("settings.description")}
           </p>
@@ -79,7 +79,7 @@ export default function SettingsRoute() {
         </div>
       }
       whatsNew={
-        <div className="mx-auto w-full max-w-3xl">
+        <div className="mx-auto w-full max-w-2xl">
           <ChangelogSettingsCard markdown={changelog} />
         </div>
       }

package/corpus/templates/macros/app/routes/team.tsx

@@ -7,5 +7,5 @@ export function meta() {
 }
 
 export default function TeamRoute() {
-  return <Navigate to="/settings#team" replace />;
+  return <Navigate to="/settings#organization" replace />;
 }

package/corpus/templates/mail/.agents/skills/actions/SKILL.md

@@ -377,6 +377,11 @@ Most operations should be actions. You only need custom routes in `server/routes
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
 
+When the agent needs a durable image or file URL, call the core `upload-image`
+action or use `uploadFile()` in server code. Do not write base64 into SQL,
+markdown, deck/design JSON, or action results. `_agentImages` on action results
+is for ephemeral vision previews only, not persistence.
+
 If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
 
 ## Legacy Pattern (bare export)

package/corpus/templates/mail/.agents/skills/email-drafts/SKILL.md

@@ -119,7 +119,7 @@ const drafts = await listAppState("compose-");
 
 ## Attaching Files
 
-The `send-email` action accepts an optional `attachments` array. Each entry must reference a file that was previously uploaded via the media-upload endpoint (`/api/media/upload`). Pass the server-side `filename` (the key returned by the upload endpoint, e.g. `abc123.pdf`), and optionally `originalName` (display name for the recipient) and `mimeType`. The attachment plumbing resolves the file from the upload store (falling back to `data/uploads/`) and includes it as a MIME multipart attachment in the outgoing Gmail message. Files are never sent speculatively — only attach what the user has explicitly provided and confirmed.
+The `send-email` action accepts an optional `attachments` array. Each entry must reference a file that was previously uploaded via the media-upload endpoint (`/api/media/upload`). Pass the server-side `filename` (the key returned by the upload endpoint, e.g. `abc123.pdf`), and optionally `originalName` (display name for the recipient) and `mimeType`. The attachment plumbing resolves the file from `data/uploads/` or from the configured file-storage URL recorded by the upload endpoint, then includes it as a MIME multipart attachment in the outgoing Gmail message. Do not store or paste attachment bytes, base64, or `data:` URLs in draft state/settings; files are never sent speculatively — only attach what the user has explicitly provided and confirmed.
 
 Example:
 ```json

package/corpus/templates/mail/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback — it detects DB timestamp changes even when the write happened in a different process or invocation.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/mail/.agents/skills/security/SKILL.md

@@ -51,6 +51,13 @@ export default defineAction({
 
 The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
 
+## Large Payloads
+
+Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
+or `application_state`. Route uploads through the file-upload provider and store
+references. This prevents database bloat, slow hot paths, and accidental secret
+or customer-data embedding inside binary payloads.
+
 ## SQL Injection
 
 Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:

package/corpus/templates/mail/.agents/skills/storing-data/SKILL.md

@@ -13,7 +13,9 @@ metadata:
 
 ## Rule
 
-All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
 
 **Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
 
@@ -136,6 +138,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Use the `settings` store for app configuration and user preferences
 - Use `application-state` for ephemeral UI state that the agent and UI share
 - Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
 - Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
 - Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
 - Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
@@ -146,6 +149,7 @@ Polling streams database changes to the UI. When the agent writes to the databas
 - Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
 - Don't keep state only in memory (server variables, global stores)
 - Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
 - Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
 - Don't write SQLite-only or Postgres-only SQL in app code
 - Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder

package/corpus/templates/mail/AGENTS.md

@@ -9,6 +9,10 @@ Detailed draft, queue, and contact-resolution patterns live in
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for email reads, labels, settings, drafts, queued drafts, filters,
   scheduling, refresh, and CRM context. Do not edit mail SQL directly unless a

package/corpus/templates/mail/changelog/2026-07-08-mail-attachments-in-hosted-environments-now-require-file-sto.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-08
+---
+
+Mail attachments in hosted environments now require file storage instead of falling back to database-stored file bytes.

package/corpus/templates/mail/server/handlers/media.ts

@@ -1,12 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { uploadFile } from "@agent-native/core/file-upload";
 import { streamFile, getSession } from "@agent-native/core/server";
 import {
   defineEventHandler,
   getQuery,
   readRawBody,
   getRouterParam,
+  sendRedirect,
   setResponseStatus,
   setResponseHeader,
   type H3Event,
@@ -82,11 +84,27 @@ export const uploadMedia = defineEventHandler(async (event: H3Event) => {
     try {
       fs.writeFileSync(filePath, body);
     } catch {
+      const uploaded = await uploadFile({
+        data: body instanceof Uint8Array ? body : new Uint8Array(body),
+        filename: originalName,
+        mimeType,
+        ownerEmail: session.email,
+        recordAsset: false,
+      });
+      if (!uploaded?.url) {
+        setResponseStatus(event, 503);
+        return {
+          error:
+            "File storage is not configured. Connect Builder.io or another upload provider before attaching files in hosted environments.",
+          storageSetupRequired: true,
+        };
+      }
       await putStoredUpload(session.email, {
         ...payload,
-        dataBase64: Buffer.from(body).toString("base64"),
+        url: uploaded.url,
         createdAt: Date.now(),
       });
+      return { ...payload, url: uploaded.url, provider: uploaded.provider };
     }
 
     return payload;
@@ -118,6 +136,13 @@ export const serveMedia = defineEventHandler(async (event: H3Event) => {
       setResponseStatus(event, 404);
       return { error: "File not found" };
     }
+    if (stored.url) {
+      return sendRedirect(event, stored.url, 302);
+    }
+    if (!stored.dataBase64) {
+      setResponseStatus(event, 404);
+      return { error: "File data not found" };
+    }
 
     setResponseHeader(event, "Content-Type", stored.mimeType);
     setResponseHeader(

package/corpus/templates/mail/server/lib/outgoing-email.ts

@@ -17,6 +17,7 @@ import {
 import { getStoredUpload } from "./upload-store.js";
 
 const UPLOADS_DIR = path.resolve("data/uploads");
+const MAX_ATTACHMENT_FETCH_BYTES = 15 * 1024 * 1024;
 
 export type ResolvedComposeAttachment = ComposeAttachment & {
   data: Buffer;
@@ -32,6 +33,22 @@ function stripCrlf(value: string): string {
   return value.replace(/[\r\n]+/g, " ").trim();
 }
 
+async function fetchStoredUpload(url: string): Promise<Buffer> {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Stored upload fetch failed: ${response.status}`);
+  }
+  const contentLength = Number(response.headers.get("content-length") || "0");
+  if (contentLength > MAX_ATTACHMENT_FETCH_BYTES) {
+    throw new Error("Stored upload is too large to attach");
+  }
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.byteLength > MAX_ATTACHMENT_FETCH_BYTES) {
+    throw new Error("Stored upload is too large to attach");
+  }
+  return bytes;
+}
+
 function safeHeaderParam(value: string): string {
   return stripCrlf(value).replace(/["\\]/g, "_") || "attachment";
 }
@@ -227,7 +244,13 @@ export async function resolveComposeAttachments(
       if (!ownerEmail) throw error;
       const stored = await getStoredUpload(ownerEmail, att.filename);
       if (!stored) throw error;
-      data = Buffer.from(stored.dataBase64, "base64");
+      if (stored.url) {
+        data = await fetchStoredUpload(stored.url);
+      } else if (stored.dataBase64) {
+        data = Buffer.from(stored.dataBase64, "base64");
+      } else {
+        throw error;
+      }
       att.originalName = att.originalName || stored.originalName;
       att.mimeType = att.mimeType || stored.mimeType;
       att.size = att.size || stored.size;

package/corpus/templates/mail/server/lib/upload-store.ts

@@ -8,7 +8,8 @@ export interface StoredUpload {
   mimeType: string;
   size: number;
   url?: string;
-  dataBase64: string;
+  /** Legacy SQL fallback used by older uploads. New uploads store provider URLs. */
+  dataBase64?: string;
   createdAt: number;
 }
 

package/corpus/templates/plan/.agents/skills/actions/SKILL.md

@@ -377,6 +377,11 @@ Most operations should be actions. You only need custom routes in `server/routes
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
 
+When the agent needs a durable image or file URL, call the core `upload-image`
+action or use `uploadFile()` in server code. Do not write base64 into SQL,
+markdown, deck/design JSON, or action results. `_agentImages` on action results
+is for ephemeral vision previews only, not persistence.
+
 If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
 
 ## Legacy Pattern (bare export)

package/corpus/templates/plan/.agents/skills/adding-a-feature/SKILL.md

@@ -74,6 +74,11 @@ Builder/internal data, or customer data in the action, UI, seed data, fixtures,
 docs, prompts, or generated extension/app content. Register required secrets,
 use OAuth helpers, or read scoped values from the vault/credential store.
 
+If the feature involves attachments, images, recordings, screenshots, exports,
+or other file-like payloads, design the upload path in the same change:
+provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
+columns or stuff files into `application_state`.
+
 **If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
 
 ### 3. Skills / Instructions

package/corpus/templates/plan/.agents/skills/real-time-sync/SKILL.md

@@ -50,7 +50,7 @@ The agent modifies data in SQL, but the UI runs in the browser. SSE bridges same
 
    For list/sidebar queries, use the same pattern — pass the counter into the queryKey of every list query you want to keep fresh.
 
-4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback — it detects DB timestamp changes even when the write happened in a different process or invocation.
+4. **Fallback** polling calls `/_agent-native/poll?since=N`. It runs every 2 seconds until SSE is connected, then relaxes to 15 seconds (`SSE_FALLBACK_INTERVAL_MS`). If SSE is disabled or unavailable (e.g., edge/serverless deployments), polling continues at the 2 s cadence. Polling is the universal serverless fallback: new framework writes are read from the durable `sync_events` log, while the older DB timestamp scan remains as a slower safety net for direct SQL writes and older processes.
 
 5. When the agent writes to the database, the version increments, SSE/polling detects it, and React Query refetches the affected queries.
 

package/corpus/templates/plan/.agents/skills/security/SKILL.md

@@ -51,6 +51,13 @@ export default defineAction({
 
 The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
 
+## Large Payloads
+
+Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
+or `application_state`. Route uploads through the file-upload provider and store
+references. This prevents database bloat, slow hot paths, and accidental secret
+or customer-data embedding inside binary payloads.
+
 ## SQL Injection
 
 Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:

package/corpus/templates/plan/AGENTS.md

@@ -7,6 +7,10 @@ review before code changes happen.
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Follow the root framework rules: data in SQL, actions first, application
   state for navigation/selection, and shared agent chat for AI work.

package/corpus/templates/plan/app/hooks/use-navigation-state.ts

@@ -195,7 +195,7 @@ function pathForView(view?: string): string {
     case "settings":
       return "/settings";
     case "team":
-      return "/settings#team";
+      return "/settings#organization";
     default:
       return "/";
   }

package/corpus/templates/plan/app/routes/settings.tsx

@@ -56,7 +56,7 @@ export default function SettingsRoute() {
       extraTabs={agentSettingsTabs}
       generalSearchEntries={generalSearchEntries}
       general={
-        <div className="mx-auto w-full max-w-3xl space-y-6">
+        <div className="mx-auto w-full max-w-2xl space-y-6">
           <p className="text-sm leading-6 text-muted-foreground">
             {t("settings.description")}
           </p>
@@ -108,7 +108,7 @@ export default function SettingsRoute() {
         </div>
       }
       whatsNew={
-        <div className="mx-auto w-full max-w-3xl">
+        <div className="mx-auto w-full max-w-2xl">
           <ChangelogSettingsCard markdown={changelog} />
         </div>
       }

package/corpus/templates/plan/app/routes/team.tsx

@@ -7,5 +7,5 @@ export function meta() {
 }
 
 export default function TeamRoute() {
-  return <Navigate to="/settings#team" replace />;
+  return <Navigate to="/settings#organization" replace />;
 }

package/corpus/templates/plan/changelog/2026-07-08-hosted-plan-images-now-require-connected-storage.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-08
+---
+
+Hosted visual plan images now require connected storage instead of saving image files in SQL.

package/corpus/templates/plan/server/lib/plan-assets.ts

@@ -32,6 +32,8 @@ export {
 
 /** The route prefix under which plan assets are served. */
 export const PLAN_ASSET_ROUTE_PREFIX = "/_agent-native/plan-asset";
+const PLAN_ASSET_STORAGE_REQUIRED_REASON =
+  "Image storage is not connected yet. Connect Builder.io or configure S3-compatible storage to add images to visual plans.";
 
 /**
  * Build the serving URL for an asset stored in the `plan_assets` table.
@@ -55,21 +57,44 @@ export interface UpsertPlanAssetResult {
   assetId: string;
   /**
    * A CDN URL when an upload provider was configured and the upload succeeded.
-   * `null` when falling back to the local `plan_assets` table.
+   * `null` only for local-development fallback rows in `plan_assets`.
    */
   cdnUrl: string | null;
   /**
    * The final `src` to embed in the image block.
    * - CDN URL when provider upload succeeded.
-   * - Local route URL (`/_agent-native/plan-asset/...`) otherwise.
+   * - Local route URL (`/_agent-native/plan-asset/...`) for dev fallback rows.
    */
   src: string;
   filename: string;
 }
 
+function requiresConfiguredPlanAssetStorage(): boolean {
+  return process.env.NODE_ENV === "production" || !isLocalPlanAssetDatabase();
+}
+
+function appDatabaseUrl(): string {
+  const appName = process.env.APP_NAME?.toUpperCase().replace(/-/g, "_");
+  if (appName) {
+    const appUrl = process.env[`${appName}_DATABASE_URL`];
+    if (appUrl) return appUrl;
+  }
+  return process.env.DATABASE_URL || process.env.NETLIFY_DATABASE_URL || "";
+}
+
+function isLocalPlanAssetDatabase(): boolean {
+  const url = appDatabaseUrl().toLowerCase();
+  return (
+    url === "" ||
+    url.startsWith("file:") ||
+    url.startsWith("pglite:") ||
+    !url.includes("://")
+  );
+}
+
 /**
  * Store a plan asset, uploading via the active file-upload provider first.
- * Falls back to the `plan_assets` SQL table when no provider is configured.
+ * Falls back to the `plan_assets` SQL table only on local databases.
  *
  * Enforces single-asset and per-plan size caps.
  */
@@ -130,7 +155,11 @@ export async function upsertPlanAsset(
     };
   }
 
-  // SQL fallback: store base64 in plan_assets.
+  if (requiresConfiguredPlanAssetStorage()) {
+    throw new Error(PLAN_ASSET_STORAGE_REQUIRED_REASON);
+  }
+
+  // Local SQL fallback: store base64 in plan_assets for development-only use.
   const assetId = `passet_${randomUUID().replace(/-/g, "")}`;
   const now = new Date().toISOString();
   await db.insert(schema.planAssets).values({

package/corpus/templates/slides/.agents/skills/actions/SKILL.md

@@ -377,6 +377,11 @@ Most operations should be actions. You only need custom routes in `server/routes
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
 
+When the agent needs a durable image or file URL, call the core `upload-image`
+action or use `uploadFile()` in server code. Do not write base64 into SQL,
+markdown, deck/design JSON, or action results. `_agentImages` on action results
+is for ephemeral vision previews only, not persistence.
+
 If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
 
 ## Legacy Pattern (bare export)

package/corpus/templates/slides/.agents/skills/security/SKILL.md

@@ -51,6 +51,13 @@ export default defineAction({
 
 The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
 
+## Large Payloads
+
+Do not accept or persist unbounded base64/file blobs through actions, SQL writes,
+or `application_state`. Route uploads through the file-upload provider and store
+references. This prevents database bloat, slow hot paths, and accidental secret
+or customer-data embedding inside binary payloads.
+
 ## SQL Injection
 
 Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:

package/corpus/templates/slides/AGENTS.md

@@ -9,6 +9,10 @@ Detailed deck, slide-editing, image, design-system, and export workflows live in
 
 ## Core Rules
 
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use actions for deck lifecycle, slide edits, imports, exports, images, design
   systems, and sharing. Do not write deck/slide rows directly.