@agent-native/core 0.92.0 → 0.92.1

package/dist/templates/workspace-core/AGENTS.md

@@ -44,6 +44,10 @@ agent should know.
   UI or "AI" features.
 - Put shared code in `packages/shared` only when multiple apps need it.
 - Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
   `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
@@ -114,7 +118,9 @@ App database code must be provider-agnostic. Define schemas with
 query builder and portable `drizzle-orm` operators. Do not import from
 `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Keep raw SQL
 for additive migrations, health checks, or carefully scoped maintenance, and
-never write SQLite-only or Postgres-only product code.
+never write SQLite-only or Postgres-only product code. Do not use SQL as object
+storage; file bytes belong in upload/private-blob providers with only references
+saved to app tables.
 
 In local development, run
 `pnpm exec agent-native create <app-name> --template=<template>` from the

package/dist/templates/workspace-root/AGENTS.md

@@ -75,6 +75,10 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 - Keep application routes, actions, server plugins, and app state inside the
   relevant `apps/<app>` directory unless multiple apps need the same behavior.
 - Put reusable code in `packages/shared` only after at least two apps need it.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Never copy live credentials, API keys, tokens, webhook URLs, signing secrets,
   personal email addresses, customer data, private Builder/internal data, or
   company-specific placeholder values into source files, docs, prompts,
@@ -153,7 +157,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
   Drizzle's query builder and portable `drizzle-orm` operators. Do not import
   from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates.
   Keep raw SQL for additive migrations, health checks, or carefully scoped
-  maintenance, and never write SQLite-only or Postgres-only product code.
+  maintenance, and never write SQLite-only or Postgres-only product code. Do
+  not use SQL as object storage; file bytes belong in upload/private-blob
+  providers with only references saved to app tables.
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.92.0",
+  "version": "0.92.1",
   "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/default/.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/src/templates/default/.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/src/templates/default/.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/src/templates/default/.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/src/templates/default/.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/src/templates/default/AGENTS.md

@@ -6,7 +6,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 
 ### Core Principles
 
-1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; local PGlite is available as a Postgres-dialect opt-in with `DATABASE_URL=pglite:./data/pglite` after installing `@electric-sql/pglite`. Deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
+1. **Shared SQL database** -- All app state lives in SQL. SQL stores structured records, metadata, references, and searchable text; large files/blob payloads must use file/blob storage and persist only URLs, ids, or handles. Never store large base64, `data:` URLs, images, videos, audio, PDFs, ZIPs, screenshots, thumbnails, or session replay chunks in SQL, `application_state`, `settings`, or `resources`. Local SQLite at `data/app.db` is the zero-setup dev fallback; local PGlite is available as a Postgres-dialect opt-in with `DATABASE_URL=pglite:./data/pglite` after installing `@electric-sql/pglite`. Deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
 2. **AI through the right framework surface** -- Product workflows delegate to the agent via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows; add `newTab: true, background: true, openSidebar: false` when the agent should work silently without focusing the sidebar. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips. For rare server-side text transforms that intentionally need no tools, chat history, or run state, use `completeText()` from `@agent-native/core/server` inside an action instead of importing provider SDKs directly.
 3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
 4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
@@ -67,7 +67,9 @@ Use `getSession(event)` server-side and `useSession()` client-side. When there i
 
 ## Resources
 
-Resources are SQL-backed persistent files for notes, learnings, and context.
+Resources are persistent files for notes, learnings, and context. Text resources
+live in SQL; binary resource uploads require configured file storage and store
+only the hosted URL/reference in SQL.
 
 **At the start of every conversation, read these resources (workspace, shared, and personal scopes as relevant):**
 

package/src/templates/headless/AGENTS.md

@@ -8,6 +8,10 @@ This app is not stateless. The Agent Native runtime uses SQL-backed stores for a
 
 - Prefer actions in `actions/` for every app operation. Do not create REST wrappers around actions.
 - Keep action inputs validated with Zod and return structured data, not JSON strings.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Do not hardcode API keys, tokens, webhook URLs, private data, or credential-looking literals.
 - `actions/run.ts` is the CLI dispatcher for `pnpm action ...`, not an app
   action. Leave it in place and add callable primitives as separate

package/src/templates/workspace-core/.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/src/templates/workspace-core/.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/src/templates/workspace-core/.agents/skills/context-awareness/SKILL.md

@@ -65,6 +65,10 @@ const navigation = await readAppState("navigation");
 
 Raw URL query params are already synced by the framework to `__url__` and shown to the built-in agent as `<current-url>`. Keep shareable filters in URL state, then use `view-screen` to summarize important query params as `activeFilters` when helpful.
 
+Keep `application_state` values small. Do not store pasted files, base64 images,
+recording chunks, screenshots, or other large blobs in navigation or app-state
+keys; upload them and store only a URL or storage handle.
+
 ### 2. Current URL (`__url__` key)
 
 `AgentPanel` automatically writes `__url__` with `{ pathname, search, hash, searchParams }`. The built-in agent sees it as a `<current-url>` block in every turn.

package/src/templates/workspace-core/.agents/skills/extensions/SKILL.md

@@ -391,6 +391,12 @@ extension HTML, inline scripts, docs, examples, or extension seed content.
 Extensions are stored in SQL and rendered in the browser; anything written into
 the extension body should be treated as visible.
 
+Extension HTML belongs in SQL, but large media does not. Do not embed pasted
+files, base64 assets, screenshots, or binary blobs in `content` or
+`extensionData`; upload media to file/blob storage and reference hosted URLs or
+opaque handles. For large pasted text bodies, use the documented
+`contentFromAttachment` flow instead of a megabyte inline string.
+
 For external API calls, use `extensionFetch()` with `${keys.NAME}` placeholders
 inside single-quoted strings, for example
 `Authorization: 'Bearer ${keys.GITHUB_TOKEN}'`. The proxy resolves the value

package/src/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -128,6 +128,10 @@ index the growing tables first.
   demand.
 - Don't store **unbounded blobs inline** in a row that a list/load pulls.
   Reference large content separately so opening the parent stays cheap.
+- Never inline binary payloads in columns a list, poll, or `view-screen` summary
+  reads. Images, PDFs, audio/video, archives, screenshots, and base64
+  attachments belong in file/blob storage; SQL rows should hold URLs, asset ids,
+  storage keys, or opaque blob refs.
 - **Virtualize** very long rendered lists on the client so off-screen rows aren't
   parsed/rendered every update.
 

package/src/templates/workspace-core/.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/src/templates/workspace-core/.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/src/templates/workspace-core/.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/src/templates/workspace-core/AGENTS.md

@@ -44,6 +44,10 @@ agent should know.
   UI or "AI" features.
 - Put shared code in `packages/shared` only when multiple apps need it.
 - Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Store shared runtime configuration in the workspace root `.env`; use
   `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
   tokens, webhook URLs, signing secrets, private Builder/internal data, customer
@@ -114,7 +118,9 @@ App database code must be provider-agnostic. Define schemas with
 query builder and portable `drizzle-orm` operators. Do not import from
 `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Keep raw SQL
 for additive migrations, health checks, or carefully scoped maintenance, and
-never write SQLite-only or Postgres-only product code.
+never write SQLite-only or Postgres-only product code. Do not use SQL as object
+storage; file bytes belong in upload/private-blob providers with only references
+saved to app tables.
 
 In local development, run
 `pnpm exec agent-native create <app-name> --template=<template>` from the

package/src/templates/workspace-root/AGENTS.md

@@ -75,6 +75,10 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
 - Keep application routes, actions, server plugins, and app state inside the
   relevant `apps/<app>` directory unless multiple apps need the same behavior.
 - Put reusable code in `packages/shared` only after at least two apps need it.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
 - Never copy live credentials, API keys, tokens, webhook URLs, signing secrets,
   personal email addresses, customer data, private Builder/internal data, or
   company-specific placeholder values into source files, docs, prompts,
@@ -153,7 +157,9 @@ refreshes framework-provided shared skills and repairs `CLAUDE.md` /
   Drizzle's query builder and portable `drizzle-orm` operators. Do not import
   from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates.
   Keep raw SQL for additive migrations, health checks, or carefully scoped
-  maintenance, and never write SQLite-only or Postgres-only product code.
+  maintenance, and never write SQLite-only or Postgres-only product code. Do
+  not use SQL as object storage; file bytes belong in upload/private-blob
+  providers with only references saved to app tables.
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch