@agent-native/core 0.92.0 → 0.92.2

package/corpus/templates/clips/server/routes/api/uploads/[recordingId]/chunk.post.ts

@@ -37,7 +37,11 @@ import {
 import finalizeRecording from "../../../../../actions/finalize-recording.js";
 import { getDb, schema } from "../../../../db/index.js";
 import { debugLog } from "../../../../lib/debug.js";
-import { sumRecordingChunkBytes } from "../../../../lib/recording-upload-state.js";
+import {
+  deleteRecordingChunks,
+  pruneStaleRecordingChunks,
+  sumRecordingChunkBytes,
+} from "../../../../lib/recording-upload-state.js";
 import {
   getEventOwnerContext,
   ownerEmailMatches,
@@ -49,6 +53,7 @@ import {
 } from "../../../../lib/resumable-session.js";
 import { isStreamingUploadDisabled } from "../../../../lib/streaming-upload-mode.js";
 import {
+  allowsSqlRecordingChunkScratch,
   shouldRejectVideoUploadWithoutStorage,
   STORAGE_SETUP_REQUIRED_REASON,
 } from "../../../../lib/video-storage.js";
@@ -175,6 +180,13 @@ export default defineEventHandler(async (event: H3Event) => {
   debugLog("[chunk] resolved owner:", ownerEmail);
 
   return runWithRequestContext({ userEmail: ownerEmail, orgId }, async () => {
+    await pruneStaleRecordingChunks(ownerEmail).catch((err) => {
+      console.warn("[chunk] stale recording chunk prune failed:", {
+        ownerEmail,
+        err: err instanceof Error ? err.message : String(err),
+      });
+    });
+
     const db = getDb();
 
     // Verify the recording belongs to the current user.
@@ -271,6 +283,15 @@ export default defineEventHandler(async (event: H3Event) => {
         storageSetupRequired: true,
       };
     }
+    if (!allowsSqlRecordingChunkScratch()) {
+      setResponseStatus(event, 409);
+      return {
+        ok: false,
+        error:
+          "Recording upload storage is configured, but this upload did not start a resumable storage session. Refresh and start the recording again.",
+        storageSetupRequired: false,
+      };
+    }
 
     const raw = await readRawBody(event, false);
     const bodySize = raw ? raw.byteLength : 0;
@@ -320,6 +341,12 @@ export default defineEventHandler(async (event: H3Event) => {
           ? latestState.failureReason
           : "Recording upload has already failed.";
       if (latestState?.status === "failed") {
+        await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+          console.warn("[chunk] failed upload chunk cleanup failed:", {
+            recordingId,
+            err: err instanceof Error ? err.message : String(err),
+          });
+        });
         return failedUploadResponse(latestReason);
       }
 
@@ -333,6 +360,12 @@ export default defineEventHandler(async (event: H3Event) => {
       if (current?.status === "failed") {
         const reason =
           current.failureReason ?? "Recording upload has already failed.";
+        await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+          console.warn("[chunk] failed recording chunk cleanup failed:", {
+            recordingId,
+            err: err instanceof Error ? err.message : String(err),
+          });
+        });
         await writeAppState(`recording-upload-${recordingId}`, {
           recordingId,
           status: "failed",
@@ -364,6 +397,12 @@ export default defineEventHandler(async (event: H3Event) => {
         maxBytes: MAX_RECORDING_UPLOAD_BYTES,
         updatedAt: now,
       });
+      await deleteRecordingChunks(ownerEmail, recordingId).catch((err) => {
+        console.warn("[chunk] oversized upload chunk cleanup failed:", {
+          recordingId,
+          err: err instanceof Error ? err.message : String(err),
+        });
+      });
       setResponseStatus(event, 413);
       return {
         ok: false,

package/corpus/templates/content/.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/content/.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/content/.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/content/.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/content/AGENTS.md

@@ -9,6 +9,10 @@ Detailed document editing, Notion, 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 documents, blocks, comments, media, sharing, navigation, and
   Notion integration. Do not mutate document rows directly unless a skill says to

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

@@ -43,7 +43,7 @@ export default function SettingsRoute() {
         extraTabs={agentSettingsTabs}
         generalSearchEntries={generalSearchEntries}
         general={
-          <main className="mx-auto w-full max-w-3xl space-y-6">
+          <main className="mx-auto w-full max-w-2xl space-y-6">
             <p className="text-sm leading-6 text-muted-foreground">
               {t("settings.description")}
             </p>
@@ -77,7 +77,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/content/app/routes/_app.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/design/.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/design/.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/design/AGENTS.md

@@ -9,6 +9,10 @@ patterns live in `.agents/skills/`.
 
 ## 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 the app actions for designs, files, versions, design systems, variants,
   export, and sharing. Do not write design rows directly with SQL.

package/corpus/templates/design/actions/take-design-screenshot.ts

@@ -12,10 +12,9 @@
  * returns:
  *
  *   - `screenshots[]` — a PNG per viewport, persisted through the shared
- *     `uploadFile` provider (falls back to an inline base64 data URL when no
- *     upload provider is configured, matching `set-thumbnail`'s fallback
- *     pattern). The result carries a plain `url` per screenshot so a human can
- *     view it by opening the link, or the agent can embed it as
+ *     `uploadFile` provider. The result carries a plain `url` per screenshot
+ *     when storage is configured so a human can view it by opening the link,
+ *     or the agent can embed it as
  *     `![...](url)` in its own chat reply today. NOTE: tool results are
  *     currently text-only end-to-end — this action does not attach the PNG as
  *     a model-visible image content block. The moment the engine supports
@@ -97,8 +96,9 @@ export interface ScreenshotDiagnostics {
 export interface ScreenshotResult {
   viewport: ScreenshotViewport;
   url: string;
-  /** True when persisted via a durable upload provider; false for the inline data-URL fallback. */
+  /** True when persisted via a durable upload provider. */
   persisted: boolean;
+  uploadError?: string;
   bytes: number;
   diagnostics: ScreenshotDiagnostics;
 }
@@ -620,13 +620,16 @@ export default defineAction({
             ownerEmail,
           }).catch(() => null);
 
-          const url =
-            uploaded?.url ?? `data:image/png;base64,${png.toString("base64")}`;
-
           screenshots.push({
             viewport,
-            url,
+            url: uploaded?.url ?? "",
             persisted: !!uploaded,
+            ...(uploaded?.url
+              ? {}
+              : {
+                  uploadError:
+                    "Screenshot was rendered but not returned because file storage is not configured.",
+                }),
             bytes: png.byteLength,
             diagnostics: {
               viewport,

package/corpus/templates/design/app/components/design/inspector/ImageFillControls.tsx

@@ -1,3 +1,4 @@
+import { callAction, useT } from "@agent-native/core/client";
 import { IconPhotoPlus, IconX } from "@tabler/icons-react";
 import { useEffect, useRef, useState } from "react";
 
@@ -32,6 +33,11 @@ export interface ImageFillBackgroundStyles {
   backgroundPosition?: string;
 }
 
+type UploadImageResult = {
+  url?: string;
+  error?: string;
+};
+
 const FIT_MODES: Array<{ mode: ImageFitMode; label: string }> = [
   { mode: "fill", label: "Fill" }, // i18n-ignore image fit mode
   { mode: "fit", label: "Fit" }, // i18n-ignore image fit mode
@@ -51,6 +57,19 @@ function escapeForQuotedUrl(url: string): string {
   return url.replace(/\\/g, "\\\\").replace(/"/g, "%22").replace(/\r?\n/g, "");
 }
 
+function readFileAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () =>
+      typeof reader.result === "string"
+        ? resolve(reader.result)
+        : reject(new Error("Image upload did not produce a data URL"));
+    reader.onerror = () =>
+      reject(reader.error ?? new Error("Image read failed"));
+    reader.readAsDataURL(file);
+  });
+}
+
 const CHECKER_A = "#d4d4d4";
 const CHECKERBOARD_IMAGE = `linear-gradient(45deg, ${CHECKER_A} 25%, transparent 25%), linear-gradient(-45deg, ${CHECKER_A} 25%, transparent 25%), linear-gradient(45deg, transparent 75%, ${CHECKER_A} 75%), linear-gradient(-45deg, transparent 75%, ${CHECKER_A} 75%)`;
 const FIT_MARKER_RE =
@@ -261,9 +280,12 @@ export function ImageFillControls({
   disabled = false,
   className,
 }: ImageFillControlsProps) {
+  const t = useT();
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [urlDraft, setUrlDraft] = useState(value.url);
   const urlDraftRef = useRef(value.url);
+  const [uploadingImage, setUploadingImage] = useState(false);
+  const [uploadError, setUploadError] = useState<string | null>(null);
   // Guard re-syncing the draft from an external value change while the field
   // is focused (mirrors ScrubInput's `focused` pattern): without this, an
   // incoming prop update while the user is mid-typing a URL — e.g. a
@@ -281,20 +303,36 @@ export function ImageFillControls({
     onChange({ ...value, url: urlDraftRef.current.trim() });
   };
 
-  const handleFilePick = (event: React.ChangeEvent<HTMLInputElement>) => {
+  const handleFilePick = async (event: React.ChangeEvent<HTMLInputElement>) => {
     const file = event.target.files?.[0];
     if (!file) return;
-    const reader = new FileReader();
-    reader.onload = () => {
-      const dataUrl = typeof reader.result === "string" ? reader.result : "";
-      if (dataUrl) {
-        setUrlDraft(dataUrl);
-        onChange({ ...value, url: dataUrl });
+    setUploadingImage(true);
+    setUploadError(null);
+    try {
+      const dataUrl = await readFileAsDataUrl(file);
+      const result = (await callAction("upload-image", {
+        data: dataUrl,
+        filename: file.name,
+      })) as UploadImageResult;
+      if (result.url) {
+        urlDraftRef.current = result.url;
+        setUrlDraft(result.url);
+        onChange({ ...value, url: result.url });
+      } else {
+        setUploadError(
+          result.error ||
+            "File storage is not configured. Connect an upload provider before using local images.",
+        );
       }
-    };
-    reader.readAsDataURL(file);
-    // Allow re-selecting the same file later.
-    event.target.value = "";
+    } catch (error) {
+      setUploadError(
+        error instanceof Error ? error.message : t("common.genericError"),
+      );
+    } finally {
+      setUploadingImage(false);
+      // Allow re-selecting the same file later.
+      event.target.value = "";
+    }
   };
 
   return (
@@ -376,13 +414,14 @@ export function ImageFillControls({
           <TooltipTrigger asChild>
             <button
               type="button"
-              disabled={disabled}
+              disabled={disabled || uploadingImage}
               aria-label={"Upload image" /* i18n-ignore */}
               onClick={() => fileInputRef.current?.click()}
               className={cn(
                 "flex size-6 shrink-0 items-center justify-center rounded-md border border-[var(--design-editor-control-border)] bg-[var(--design-editor-control-bg)] text-muted-foreground hover:text-foreground",
                 "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
-                disabled && "pointer-events-none opacity-40",
+                (disabled || uploadingImage) &&
+                  "pointer-events-none opacity-40",
               )}
             >
               <IconPhotoPlus className="size-3.5" />
@@ -398,6 +437,11 @@ export function ImageFillControls({
           onChange={handleFilePick}
         />
       </div>
+      {uploadError && (
+        <p className="text-[10px] leading-snug text-destructive">
+          {uploadError}
+        </p>
+      )}
 
       {/* ── Fit mode dropdown ─────────────────────────────────────────────── */}
       <Select

package/corpus/templates/design/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/design/changelog/2026-07-08-local-images-added-to-designs-now-upload-to-file-storage-ins.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-08
+---
+
+Local images added to designs now upload to file storage instead of being saved as inline data URLs.

package/corpus/templates/dispatch/.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/dispatch/.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/dispatch/AGENTS.md

@@ -8,6 +8,10 @@ specific essentials.
 
 ## 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.
 - Treat Dispatch as workspace infrastructure. Prefer actions over raw SQL for
   vault, integrations, resource grants, messaging, routing, and approvals.

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

@@ -216,7 +216,7 @@ function resolvePath(
     case "threads":
       return "/thread-debug";
     case "team":
-      return "/settings#team";
+      return "/settings#organization";
     case "extensions":
       return command?.extensionId
         ? `/extensions/${encodeURIComponent(command.extensionId)}`

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

@@ -54,7 +54,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>
@@ -102,7 +102,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/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: