@agent-native/core 0.22.45 → 0.24.0

package/docs/content/skills-guide.md

@@ -42,6 +42,81 @@ Templates include skills specific to their domain. These live in the same `.agen
 
 Domain skills follow the same format as framework skills. They encode patterns specific to the template that the agent needs to follow.
 
+## App-backed skills {#app-backed-skills}
+
+App-backed skills package an agent-native app as a skill marketplace artifact.
+The bundle can include agent instructions, exported skills, MCP connector
+metadata, hosted/local launch instructions, and UI surfaces such as MCP Apps.
+
+Each app-backed skill starts with `agent-native.app-skill.json` at the app root:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "assets",
+  "hosted": {
+    "url": "https://assets.agent-native.com",
+    "mcpUrl": "https://assets.agent-native.com/_agent-native/mcp"
+  },
+  "mcp": { "serverName": "agent-native-assets" },
+  "skills": [
+    {
+      "path": ".agents/skills/asset-generation",
+      "visibility": "both",
+      "exportAs": "assets"
+    }
+  ]
+}
+```
+
+Skill visibility controls what ships:
+
+| Visibility | Meaning                                                         |
+| ---------- | --------------------------------------------------------------- |
+| `internal` | Used by the app's own agent, not exported to marketplaces.      |
+| `exported` | Exported to marketplaces, but not needed by the app internally. |
+| `both`     | Used internally and exported.                                   |
+
+Hosted is the default install path. Local launch is explicit for customization,
+offline work, or privacy-sensitive use.
+
+```bash
+# One-command hosted install for the exported Assets skill plus MCP connector.
+npx @agent-native/core@latest skills add assets
+
+# Register the hosted MCP connector for local agent clients.
+agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Materialize and run editable local source.
+agent-native app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Build marketplace adapters: Codex plugin, Claude marketplace, Vercel skills,
+# plain/Claude skills, and MCP configs.
+agent-native app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install the exported skill with the open skills CLI.
+npx skills add ./dist/assets-skill --skill assets -a codex -y
+
+# Add the generated Claude Code marketplace, then install its Assets plugin.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+Keep secrets out of skill files. The manifest should contain URL-only connector
+metadata; OAuth/device setup happens in the MCP host or through the app's normal
+settings flow.
+
+The Vercel Labs `skills` adapter is a portable `skills/<name>/SKILL.md` bundle
+for `npx skills add ...`. For first-party hosted apps, prefer
+`agent-native skills add assets`; it installs the skill instructions and runs
+the MCP registration step together.
+
+The Claude Code marketplace adapter writes
+`adapters/claude-marketplace/.claude-plugin/marketplace.json` plus a nested
+plugin directory containing `skills/<name>/SKILL.md` and `.mcp.json`. In Claude
+Code, add the marketplace, install `agent-native-assets@agent-native-apps`,
+reload plugins, then authenticate the URL-only MCP connector from `/mcp`.
+
 ## Creating custom skills {#creating-skills}
 
 Create a skill when:

package/docs/content/template-analytics.md

@@ -165,7 +165,7 @@ Credentials are stored via the framework's settings/env layer — no secrets in
 
 | Variable                                 | Purpose                       |
 | ---------------------------------------- | ----------------------------- |
-| `DATABASE_URL`                           | Neon Postgres URL             |
+| `DATABASE_URL`                           | Persistent SQL connection URL |
 | `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` | Auth                          |
 | `GOOGLE_CLIENT_ID` / `_SECRET`           | Google sign-in (OAuth 2.0)    |
 | `BIGQUERY_PROJECT_ID`                    | BigQuery project              |

package/docs/content/template-assets.md

@@ -0,0 +1,130 @@
+---
+title: "Assets"
+description: "An agent-native digital asset manager and cross-agent generation service for brand-consistent media."
+---
+
+# Assets
+
+Assets is an agent-native workspace for creating and managing brand-consistent media. It organizes uploads and generated results into libraries and folders, lets teams collect examples for blog heroes, diagrams, landing pages, product shots, videos, and logos, then routes generation through the agent chat so every asset can be reviewed and refined.
+
+Use it when your team needs reusable visual direction and searchable source assets instead of one-off generic media prompts.
+
+## What You Can Do With It
+
+- **Create asset libraries.** Group reference images, videos, canonical logos, style notes, palettes, folders, and generated output by brand, campaign, product, or category.
+- **Generate through chat.** The home composer and library Generate controls send the prompt to the agent with `sendToAgentChat()`, so users can inspect variants, give feedback, and iterate.
+- **Generate images and videos.** Builder-managed image generation is available when enabled, and Gemini powers video generation plus the manual image fallback.
+- **Upload and describe references.** Add images or videos from the library UI or prompt composer attachment button, then search by title, description, alt text, prompt, model, media type, status, role, folder, or collection.
+- **Keep a generation audit log.** Every run records prompts, model, aspect ratio, references, source asset, lineage, generated assets, status, errors, and timestamps for later design review.
+- **Preserve logo accuracy.** The agent can generate a placeholder area and the server composites the uploaded canonical logo onto the final image instead of relying on the image model to redraw it.
+- **Embed as a picker.** Other apps can iframe `/picker` and listen for the `chooseAsset` event from `@agent-native/embedding`, turning Assets into an asset picker/generator for blog editors, site builders, slide decks, and custom apps. The picker also emits the legacy `chooseImage` alias for existing image-only hosts.
+- **Install as an app-backed skill.** The `agent-native.app-skill.json` manifest exports an Assets skill plus MCP connector metadata so marketplaces can install the app, its instructions, and its picker together.
+- **Serve other agents.** Slides, Design, Content, Mail, and Dispatch can call Assets through A2A to list libraries, generate batches, create videos, refine an asset, fetch exports, and render inline previews where embedding is allowed.
+
+## Why It's Interesting
+
+Most AI media tools treat brand consistency as a prompt-writing problem. Assets treats it as application state: references, folders, collections, style briefs, run history, descriptions, and saved assets live in SQL, while binary media lives in object storage or the local file-upload fallback during development.
+
+Because generation and library management are actions and chat workflows, the UI and the agent share the same operations. A user can start from the big prompt box, a library detail page, another app's chat, or an A2A request from Slides, and the same audit and lineage model is preserved. Once enabled, the provider path prefers Builder-managed image generation so teams do not need to paste model-provider keys into every app.
+
+## For Developers
+
+The rest of this doc is for anyone forking the Assets template or extending it.
+
+### Scaffolding
+
+```bash
+pnpm dlx @agent-native/core create my-assets --template assets --standalone
+```
+
+### Customize It
+
+Assets is a complete, cloneable template. Some practical extension ideas:
+
+- "Add a product catalog connector so product reference shots can be selected by SKU."
+- "Add a strict approval queue before generated assets are marked usable for marketing."
+- "Add a brand review dashboard that filters failed or low-rated generations by model."
+- "Create a workspace-wide default asset library and route Slides image generation through it."
+- "Add a new provider behind the image generation interface after checking the latest provider docs."
+
+The agent edits routes, components, actions, skills, and SQL-backed models as needed. See [Templates](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [A2A Protocol](/docs/a2a-protocol) for cross-app generation.
+
+### Embed The Picker
+
+Use the picker route when a human is choosing or generating an asset inside
+another product. Image is the default media type; pass `mediaType=video` when
+you want video browsing/selection:
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+<EmbeddedApp
+  url="https://assets.agent-native.com/picker?mediaType=image"
+  onMessage={(name, payload) => {
+    if (name === "chooseAsset") {
+      insertAsset((payload as { url: string }).url);
+    }
+  }}
+/>;
+```
+
+External MCP hosts should call `open-asset-picker` instead of constructing this
+iframe by hand. The action returns a browser fallback link and MCP App metadata
+for inline hosts. When a user selects an asset, the picker emits `chooseAsset`,
+the legacy `chooseImage` alias for image assets, and updates MCP App model
+context where the host supports it.
+
+Use A2A when another agent needs to create, search, or export assets without a
+human picker UI.
+
+### Distribute The App Skill
+
+The Assets app skill has app id `assets` and hosted MCP URL
+`https://assets.agent-native.com/_agent-native/mcp`.
+
+```bash
+# Easiest hosted install: exported skill instructions plus MCP connector.
+npx @agent-native/core@latest skills add assets
+
+# Hosted install: URL-only MCP connector, no shared secrets in skill files.
+agent-native app-skill ensure --manifest templates/assets/agent-native.app-skill.json
+
+# Local editable launch.
+agent-native app-skill launch --manifest templates/assets/agent-native.app-skill.json --local --into ./assets-local
+
+# Marketplace package, including Claude Code marketplace and Vercel Labs skills adapters.
+agent-native app-skill pack --manifest templates/assets/agent-native.app-skill.json --out ./dist/assets-skill
+
+# Install the exported Assets skill with the open skills CLI.
+npx skills add ./dist/assets-skill --skill assets -a codex -y
+
+# Install from the generated Claude Code marketplace adapter.
+claude plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace
+claude plugin install agent-native-assets@agent-native-apps
+```
+
+The exported skill teaches agents to use the picker for human-in-the-loop
+selection, direct actions for unattended image/video generation, and browser
+links when inline MCP Apps are unavailable.
+
+The Claude marketplace adapter contains a `.claude-plugin/marketplace.json`
+catalog and an `agent-native-assets` plugin with `skills/assets/SKILL.md` plus
+the hosted `.mcp.json`. In interactive Claude Code, the same flow is available
+as `/plugin marketplace add ./dist/assets-skill/adapters/claude-marketplace`,
+`/plugin install agent-native-assets@agent-native-apps`, `/reload-plugins`, and
+`/mcp` for MCP authentication.
+
+If you install from a raw marketplace bundle with `npx skills`, register the
+hosted MCP connector so those instructions can call the live Assets app:
+
+```bash
+npx @agent-native/core@latest app-skill ensure --manifest ./dist/assets-skill/agent-native.app-skill.json --yes
+```
+
+## What's Next
+
+- [**Templates**](/docs/cloneable-saas) — the clone-and-own model
+- [**Embedding SDK**](/docs/embedding-sdk) — iframe picker and sidecar patterns
+- [**A2A Protocol**](/docs/a2a-protocol) — how other apps call Assets
+- [**File Uploads**](/docs/file-uploads) — storage and authenticated asset serving
+- [**Sharing & Privacy**](/docs/sharing) — library-level access control

package/docs/content/template-dispatch.md

@@ -26,7 +26,7 @@ If you're running an [multi-app workspace](/docs/multi-app-workspace) with many
 - **Central inbox.** Slack DMs, Telegram messages, email notifications, A2A requests from other agents — all land in one place. The Dispatch agent triages and either handles them itself or delegates. See [Messaging](/docs/messaging) for how to wire Slack, email, and Telegram into your workspace.
 - **Orchestrator, not specialist.** Dispatch does _not_ try to be the email app or the analytics app. When someone asks "summarize last week's signups," Dispatch calls the analytics agent over A2A and returns the answer. When someone asks "draft a reply to Alice," Dispatch calls the mail agent.
 - **Secrets vault.** A central store for API keys, OAuth tokens, and shared credentials. Apps in the workspace resolve secrets from Dispatch instead of duplicating them in every `.env`. Requests + approvals for sensitive access.
-- **Workspace resources.** Global skills, guardrail instructions, custom agent profiles, and reference resources can be created once in Dispatch. All-app resources are inherited at runtime by every app with no copy or manual sync step; selected grants are for app-specific exceptions.
+- **Workspace resources.** Global skills, guardrail instructions, custom agent profiles, reference resources, and HTTP MCP servers can be created once in Dispatch. All-app resources are inherited at runtime by every app with no copy or manual sync step; selected grants are for app-specific exceptions.
 - **Reusable integrations.** One place to connect provider accounts, track
   credential refs, and grant apps access. Dispatch owns provider identity and
   app grants; domain apps still own app-specific source choices such as Brain's
@@ -76,7 +76,8 @@ _How it works under the hood (for developers)._
 - **Remote agent registry.** A2A manifests live in `remote-agents/*.json` — one per app. Dispatch calls them using the `call-agent` action. In a multi-app workspace, sibling apps under `apps/` are auto-discovered as A2A peers — no manual registration needed.
 - **Vault schema.** Drizzle tables for secrets, grants, requests, approvals, and audit logs. See `server/db/schema.ts` in the template.
 - **Slack / Telegram plugins.** Server plugins that register webhooks and forward incoming messages to the orchestrator agent.
-- **MCP hub mode.** Dispatch can act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list. Separately, Dispatch's own `/_agent-native/mcp` endpoint is the recommended external MCP connector for Claude, ChatGPT, and other hosts that should reach multiple workspace apps.
+- **Workspace MCP resources.** Add HTTP MCP server definitions under `mcp-servers/*.json` in Resources, then scope them to All apps or selected app grants just like skills and context.
+- **MCP hub mode.** Dispatch can still act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list. Separately, Dispatch's own `/_agent-native/mcp` endpoint is the recommended external MCP connector for Claude, ChatGPT, and other hosts that should reach multiple workspace apps.
 
 ## Dreams {#dreams}
 

package/docs/content/template-slides.md

@@ -23,7 +23,7 @@ When you open a deck, you get a slide editor in the middle, a sidebar of slides
 
 - **Generate decks from a prompt.** "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
 - **Edit slides visually** — double-click text to edit, click a block for the bubble menu, use `/` for the slash menu to insert blocks.
-- **Generate images with AI.** Hero images, product mockups, illustrations — preferably delegated to Images, with Builder-managed image generation ready to enable once deployed and direct provider keys as today's fallback.
+- **Generate images with AI.** Hero images, product mockups, illustrations — preferably delegated to Assets, with Builder-managed image generation ready to enable once deployed and direct provider keys as today's fallback.
 - **Search stock photos and company logos.** "Find the logo for stripe.com and add it to slide 2."
 - **Present full-screen** with keyboard navigation, auto-hiding controls, and speaker notes.
 - **Comment, collaborate, and share.** Multiple people can edit the same deck in real time. Generate a public read-only URL or share with specific teammates.
@@ -86,7 +86,7 @@ Built-in layouts: title, section divider, content with bullets, two-column, imag
 
 ### AI image generation
 
-Generate images through the Images app when brand libraries matter; once the managed backend is deployed, that path can use Builder-managed image generation and keep the audit trail with the source library. Direct provider-key generation remains the fallback for standalone decks.
+Generate images through the Assets app when brand libraries matter; once the managed backend is deployed, that path can use Builder-managed image generation and keep the audit trail with the source library. Direct provider-key generation remains the fallback for standalone decks.
 
 Actions: `generate-image`, `edit-image`, `image-search`, `logo-lookup`. UI panels: `ImageGenPanel.tsx`, `ImageSearchPanel.tsx`, `LogoSearchPanel.tsx`.
 

package/docs/content/workspace-management.md

@@ -202,7 +202,7 @@ The [Dispatch](/docs/dispatch) app is the workspace's runtime control plane. It
   secrets. Dispatch is the control plane for provider inventory, repair,
   grants, and audit; the vault/secrets layer owns values; each app keeps its
   own source configuration and interpretation.
-- **Workspace resources** — manage global skills, always-on guardrail instructions, reusable agent profiles, and reference resources inherited by apps. Use `AGENTS.md` or `instructions/<slug>.md` for instructions loaded every turn, `skills/<slug>/SKILL.md` for on-demand skills, and `context/<slug>.md` for brand/company/product knowledge. Scope to All apps for workspace defaults; apps read those defaults at runtime with no copy or manual sync step, and app shared or personal resources can override locally. The Resources page highlights the starter global context files, can restore missing starter files, and each app card shows the exact inherited/granted resources that app receives.
+- **Workspace resources** — manage global skills, always-on guardrail instructions, reusable agent profiles, reference resources, and HTTP MCP servers inherited by apps. Use `AGENTS.md` or `instructions/<slug>.md` for instructions loaded every turn, `skills/<slug>/SKILL.md` for on-demand skills, `context/<slug>.md` for brand/company/product knowledge, and `mcp-servers/<slug>.json` for shared HTTP MCP tool servers. Scope to All apps for workspace defaults; apps read those defaults at runtime with no copy or manual sync step, and app shared or personal resources can override locally. The Resources page highlights the starter global context files, can restore missing starter files, and each app card shows the exact inherited/granted resources that app receives.
 - **Approvals** — require review before runtime changes (destinations, settings) take effect.
 - **Audit** — full history of secret access, grants, syncs, and changes.
 
@@ -264,4 +264,4 @@ For a new workspace, after running `agent-native create`:
 - [ ] Configure the approval policy and approver emails
 - [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications
 - [ ] Connect Slack or Telegram for workspace messaging
-- [ ] Configure shared MCP servers — drop `mcp.config.json` at the workspace root, or enable Dispatch as the workspace [MCP hub](/docs/mcp-clients#hub) so every app inherits the same server list
+- [ ] Configure shared MCP servers — add `mcp-servers/<name>.json` workspace resources in Dispatch for All-app or selected-app grants; use `mcp.config.json` or [MCP hub mode](/docs/mcp-clients#hub) for lower-level deployments

package/docs/content/workspace.md

@@ -46,6 +46,7 @@ The **Workspace** tab in the agent sidebar is where you and the agent share pers
 | `skills/<name>/SKILL.md`    | Focused domain guidance the agent pulls in on demand (invoked with `/` slash commands).                 |
 | `agents/<name>.md`          | **Custom agents** — reusable sub-agent profiles the agent can delegate to (invoked with `@` mentions).  |
 | `remote-agents/<name>.json` | A2A manifests for connected remote agents — edited via a form, not raw JSON.                            |
+| `mcp-servers/<name>.json`   | HTTP MCP server definitions that add external tools to the agent.                                       |
 | `jobs/<name>.md`            | Scheduled tasks that run on a cron (see the recurring-jobs docs).                                       |
 | `context/<name>.md`         | Shared reference material: brand guidelines, personas, positioning, product facts, messaging, etc.      |
 | Anything else               | Notes, prompts, config, dataset snippets — any text file.                                               |
@@ -58,7 +59,7 @@ Resources have three runtime scopes:
 
 - **Personal** — scoped to a single user (their email). Good for preferences, notes, and per-user context.
 - **Shared / organization** — visible to all users in the app or organization. Good for app/team instructions, skills, and shared config.
-- **Workspace** — inherited global defaults managed from Dispatch Resources. Good for company facts, positioning, brand guidelines, global guardrails, and workspace-wide skills. Apps read these at runtime; they are not copied into each app.
+- **Workspace** — inherited global defaults managed from Dispatch Resources. Good for company facts, positioning, brand guidelines, global guardrails, workspace-wide skills, and shared MCP servers. Apps read these at runtime; they are not copied into each app.
 
 The in-app Workspace panel shows all three scopes. Personal and shared/organization resources are editable there. Workspace-scope resources are read-only in app panels and edited centrally from Dispatch, so every app sees the same canonical files without a sync step.
 
@@ -270,14 +271,15 @@ The resource system also seeds a personal `LEARNINGS.md` for compatibility with
 
 **Where it fits.**
 
-| Surface            | Scope    | Written by                | Read when                              |
-| ------------------ | -------- | ------------------------- | -------------------------------------- |
-| `AGENTS.md`        | Shared   | Humans / agent on request | Every turn                             |
-| `LEARNINGS.md`     | Shared   | Humans / agent on request | Every turn                             |
-| `memory/MEMORY.md` | Personal | Agent / humans            | Every turn                             |
-| `instructions/…`   | Shared   | Humans / agent on request | Every turn                             |
-| `skills/…`         | Shared   | Humans / agent on request | On demand (`/slash` command)           |
-| `context/…`        | Shared   | Humans / agent on request | Indexed every turn, read when relevant |
+| Surface            | Scope              | Written by                           | Read when                              |
+| ------------------ | ------------------ | ------------------------------------ | -------------------------------------- |
+| `AGENTS.md`        | Shared             | Humans / agent on request            | Every turn                             |
+| `LEARNINGS.md`     | Shared             | Humans / agent on request            | Every turn                             |
+| `memory/MEMORY.md` | Personal           | Agent / humans                       | Every turn                             |
+| `instructions/…`   | Shared             | Humans / agent on request            | Every turn                             |
+| `skills/…`         | Shared             | Humans / agent on request            | On demand (`/slash` command)           |
+| `context/…`        | Shared             | Humans / agent on request            | Indexed every turn, read when relevant |
+| `mcp-servers/…`    | Workspace / shared | Humans via Dispatch or app workspace | MCP config refresh                     |
 
 Users can edit these memory files directly in the Workspace tab — they're regular resources. Delete lines the agent got wrong, keep personal preferences in `memory/MEMORY.md`, or promote team-wide rules into `AGENTS.md`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.22.45",
+  "version": "0.24.0",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",

package/src/templates/default/AGENTS.md

@@ -6,12 +6,19 @@ 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 (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
+1. **Shared SQL database** -- All app state lives in SQL. Local SQLite at `data/app.db` is the zero-setup dev fallback; 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. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
 3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `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.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
 
+### Database Code
+
+- Define tables with `@agent-native/core/db/schema` helpers (`table`, `text`, `integer`, `real`, `now`, sharing helpers), never `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`.
+- Use Drizzle's query builder (`db.select`, `db.insert`, `db.update`, `db.delete`) plus portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads and writes.
+- Keep raw SQL out of normal actions, handlers, and stores. Use it only for additive migrations, health checks, or last-resort maintenance, and keep it parameterized and dialect-agnostic.
+- Do not write SQLite-only or Postgres-only syntax in product code. The same app should run on SQLite, Postgres, libSQL/Turso, D1, and other supported Drizzle backends.
+
 ### Authentication
 
 Auth is automatic and environment-driven:
@@ -77,12 +84,13 @@ You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at t
 | `hello`       | `[--name <name>]`                                                              | Example script                                                                          |
 | `db-schema`   |                                                                                | Show all tables, columns, types                                                         |
 | `db-query`    | `--sql "SELECT ..."`                                                           | Run a SELECT query                                                                      |
-| `db-exec`     | `--sql "INSERT ..."`                                                           | Run INSERT/UPDATE/DELETE (use for short/multi-column writes)                            |
+| `db-exec`     | `--sql "UPDATE ..."`                                                           | Last-resort ad-hoc maintenance; prefer domain actions and Drizzle code for product work |
 | `db-patch`    | `--table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` | Surgical search/replace on a large text column — sends a diff instead of the full value |
 
-**Pick the right SQL tool:**
+**For one-off maintenance, pick the right SQL tool:**
 
-- Use `db-exec UPDATE` for short columns, multi-column writes, or computed updates.
+- Use domain actions first. They validate input, enforce access, and refresh the UI.
+- Use `db-exec UPDATE` only when no domain action exists and you need a small ad-hoc change.
 - Use `db-patch` when you only need to tweak a small slice of a **large** text/JSON column (documents, slide HTML, dashboard/form JSON). It saves tokens by sending `{find, replace}` instead of re-transmitting the whole column. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` for replace-every-occurrence.
 - If a template-specific action exists (e.g. `edit-document`, `update-slide`), prefer it — those also push live updates to any open collaborative editor.
 

package/src/templates/default/DEVELOPING.md

@@ -110,12 +110,14 @@ agentChat.submit("Generate something");
 
 ## Database
 
-By default, data is stored in SQLite at `data/app.db`. For production/cloud deployment, set `DATABASE_URL` to point to a remote database (Turso, Neon, Supabase, D1).
+Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.
 
-| Variable              | Required         | Description                                                |
-| --------------------- | ---------------- | ---------------------------------------------------------- |
-| `DATABASE_URL`        | No (has default) | Database connection string (default: `file:./data/app.db`) |
-| `DATABASE_AUTH_TOKEN` | For remote DBs   | Auth token for Turso or other remote databases             |
+When adding app data, define tables with `@agent-native/core/db/schema` helpers and use Drizzle's query builder for reads/writes. Do not import dialect-specific schema helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`, and do not write raw SQL in normal actions or handlers when Drizzle can express the query. Raw SQL belongs in additive migrations, health checks, or carefully scoped maintenance.
+
+| Variable              | Required                        | Description                                                                |
+| --------------------- | ------------------------------- | -------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Production yes, local dev no    | Persistent SQL connection string (local dev default: `file:./data/app.db`) |
+| `DATABASE_AUTH_TOKEN` | Only when the provider needs it | Auth token for providers such as Turso/libSQL                              |
 
 ## Tech Stack
 

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

@@ -77,6 +77,13 @@ the same data unless the route is for uploads, streaming, webhooks, OAuth, or
 another route-only concern. Action-backed UI is what makes agent-created or
 agent-edited records appear without a manual refresh.
 
+App database code must be provider-agnostic. Define schemas with
+`@agent-native/core/db/schema` helpers and write app reads/writes with 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.
+
 In local development, run
 `pnpm exec agent-native create <app-name> --template=<template>` from the
 workspace root. In production, Dispatch posts new-app requests to Builder

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

@@ -102,6 +102,12 @@ coding agents can discover the same workspace-wide guidance from the root.
   for the same data unless the route is for uploads, streaming, webhooks,
   OAuth, or another route-only concern. Action-backed UI is what makes
   agent-created or agent-edited records appear without a manual refresh.
+- App database code must be provider-agnostic. Define schemas with
+  `@agent-native/core/db/schema` helpers and write app reads/writes with
+  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.
 - 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/docs/content/template-images.md

@@ -1,55 +0,0 @@
----
-title: "Images"
-description: "An agent-native image library and cross-agent image service for brand-consistent AI imagery."
----
-
-# Images
-
-Images is an agent-native workspace for creating brand-consistent AI imagery. It organizes references into flat Libraries, lets teams upload examples for blog heroes, diagrams, landing pages, product shots, and logos, then routes generation through the agent chat so every image can be reviewed and refined.
-
-Use it when your team needs reusable visual direction instead of one-off generic image prompts.
-
-## What You Can Do With It
-
-- **Create image libraries.** Group reference images, canonical logos, style notes, palettes, and generated output by brand, campaign, product, or image category.
-- **Generate through chat.** The home composer and library Generate controls send the prompt to the agent with `sendToAgentChat()`, so users can inspect variants, give feedback, and iterate.
-- **Use Builder-managed generation when enabled.** The Builder-managed path is wired behind `BUILDER_IMAGE_GENERATION_ENABLED=true`; until that backend is deployed, a Gemini API key is the manual fallback.
-- **Upload references.** Add image examples from the library UI or the prompt composer attachment button, then tag them as hero, landing, product, logo, diagram, style-only, or other.
-- **Keep a generation audit log.** Every run records prompts, model, aspect ratio, references, source asset, lineage, generated assets, status, errors, and timestamps for later design review.
-- **Preserve logo accuracy.** The agent can generate a placeholder area and the server composites the uploaded canonical logo onto the final image instead of relying on the image model to redraw it.
-- **Serve other agents.** Slides, Design, Content, Mail, and Dispatch can call Images through A2A to list libraries, generate batches, refine an asset, fetch exports, and render inline previews where embedding is allowed.
-
-## Why It's Interesting
-
-Most AI image tools treat brand consistency as a prompt-writing problem. Images treats it as application state: references, collections, style briefs, run history, and saved assets live in SQL, while image bytes live in object storage or the local file-upload fallback during development.
-
-Because generation is an action and a chat workflow, the UI and the agent share the same operations. A user can start from the big prompt box, a library detail page, another app's chat, or an A2A request from Slides, and the same audit and lineage model is preserved. Once enabled, the provider path prefers Builder-managed image generation so teams do not need to paste model-provider keys into every app.
-
-## For Developers
-
-The rest of this doc is for anyone forking the Images template or extending it.
-
-### Scaffolding
-
-```bash
-pnpm dlx @agent-native/core create my-images --template images --standalone
-```
-
-### Customize It
-
-Images is a complete, cloneable template. Some practical extension ideas:
-
-- "Add a product catalog connector so product reference shots can be selected by SKU."
-- "Add a strict approval queue before generated images are marked usable for marketing."
-- "Add a brand review dashboard that filters failed or low-rated generations by model."
-- "Create a workspace-wide default image library and route Slides image generation through it."
-- "Add a new provider behind the image generation interface after checking the latest provider docs."
-
-The agent edits routes, components, actions, skills, and SQL-backed models as needed. See [Templates](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [A2A Protocol](/docs/a2a-protocol) for cross-app generation.
-
-## What's Next
-
-- [**Templates**](/docs/cloneable-saas) — the clone-and-own model
-- [**A2A Protocol**](/docs/a2a-protocol) — how other apps call Images
-- [**File Uploads**](/docs/file-uploads) — storage and authenticated asset serving
-- [**Sharing & Privacy**](/docs/sharing) — library-level access control