@agent-native/core 0.22.45 → 0.23.0

package/docs/content/database.md

@@ -1,19 +1,21 @@
 ---
 title: "Database"
-description: "Connect any SQL database to your agent-native app — SQLite for local dev, Postgres for production."
+description: "Connect a portable SQL database to your agent-native app and write provider-agnostic Drizzle code."
 ---
 
 # Database
 
-Agent-native apps use [Drizzle ORM](https://orm.drizzle.team) and support any SQL database. By default, apps use SQLite with a local file — set `DATABASE_URL` to connect a production database.
+Agent-native apps use [Drizzle ORM](https://orm.drizzle.team) and support portable SQL backends. By default, apps use SQLite with a local file — set `DATABASE_URL` to connect a persistent production database.
 
 ## Default: SQLite {#default-sqlite}
 
 When `DATABASE_URL` is not set, the app creates a SQLite database at `data/app.db`. This is great for local development — no setup required.
 
+Do not rely on that local file for deployed apps. Containers, serverless functions, and preview environments may reset their filesystem, which means a local SQLite file can disappear between restarts. Set `DATABASE_URL` to a persistent hosted database before production use.
+
 ## Connecting a Production Database {#production}
 
-Set `DATABASE_URL` in your `.env` file to connect a hosted database:
+Set `DATABASE_URL` in your `.env` file or deploy-provider environment to connect a hosted database. Turso is not required; use whichever Drizzle-compatible SQL backend fits your deployment:
 
 ```bash
 # Neon Postgres
@@ -27,18 +29,18 @@ DATABASE_URL=postgres://user:pass@localhost:5432/mydb
 
 # Turso (libSQL)
 DATABASE_URL=libsql://my-db-org.turso.io
-TURSO_AUTH_TOKEN=your-token
+DATABASE_AUTH_TOKEN=your-token
 ```
 
-The framework auto-detects the dialect from the URL and configures Drizzle accordingly.
+The framework auto-detects the dialect from the URL and configures Drizzle accordingly. The built-in adapters cover Postgres URLs, libSQL/Turso URLs, SQLite file URLs, and Cloudflare D1 bindings. Common production choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, and Builder.io-managed environments when available.
 
 ## Builder.io Managed Database {#builder-managed}
 
 When connected to Builder.io, your app can use a managed database that is provisioned and scaled automatically. This is the simplest path to production — no connection strings or database admin required. Coming soon.
 
-## Dialect-Agnostic Schema {#schema}
+## Dialect-Agnostic Schema And Queries {#schema}
 
-All SQL must work on both SQLite and Postgres. Never use SQLite-only syntax (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) or Postgres-only syntax.
+App database code should use Drizzle's schema and query DSL so it can run across providers. Never write SQLite-only syntax (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) or Postgres-only syntax in product code.
 
 Use the framework's schema helpers from `@agent-native/core/db/schema`:
 
@@ -66,9 +68,29 @@ export const tasks = table("tasks", {
 
 Never import from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` directly. Always use `@agent-native/core/db/schema`.
 
-## Raw SQL Helpers {#raw-sql}
+For reads and writes, use Drizzle's query builder and portable operators from `drizzle-orm`:
+
+```ts
+import { and, desc, eq } from "drizzle-orm";
+import { getDb } from "../server/db/index.js";
+import { tasks } from "../server/db/schema.js";
+
+const db = getDb();
+
+const openTasks = await db
+  .select()
+  .from(tasks)
+  .where(and(eq(tasks.ownerEmail, userEmail), eq(tasks.done, false)))
+  .orderBy(desc(tasks.createdAt));
 
-For cases where you need raw SQL outside of Drizzle queries:
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## Raw SQL Escape Hatches {#raw-sql}
+
+Raw SQL is not the default app-code API. Use it only for additive migrations, health checks, carefully reviewed advanced queries that Drizzle cannot express, or one-off maintenance. Keep it parameterized and dialect-agnostic. For timestamps in Drizzle schemas, prefer `.default(now())`; for migration SQL, use `runMigrations()` so framework-supported compatibility rewrites and dialect-gated statements stay centralized.
+
+For cases where you truly need raw SQL outside of Drizzle queries:
 
 - `getDbExec()` — auto-converts `?` params to `$1` for Postgres
 - `isPostgres()` — runtime dialect check
@@ -97,15 +119,20 @@ Instead of pushing directly, schema changes should be applied via SQL migrations
 ```ts
 import { runMigrations } from "@agent-native/core/db";
 
-export default defineNitroPlugin(async () => {
-  // Executes pending SQL migrations safely at startup
-  await runMigrations();
-});
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
 ```
 
 ## Environment Variables {#environment-variables}
 
-| Variable           | Purpose                                           |
-| ------------------ | ------------------------------------------------- |
-| `DATABASE_URL`     | Database connection string (unset = local SQLite) |
-| `TURSO_AUTH_TOKEN` | Auth token for Turso (libSQL) databases           |
+| Variable              | Purpose                                                                                              |
+| --------------------- | ---------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Persistent SQL connection string (unset = local SQLite, which is only durable for local development) |
+| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL                         |

package/docs/content/deployment.md

@@ -7,6 +7,14 @@ description: "Deploy agent-native apps to any platform with Nitro presets — No
 
 Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes — just set a preset.
 
+## Before You Deploy: Pick a Persistent Database {#persistent-database}
+
+Every deployed app needs a persistent SQL database. In local development, agent-native falls back to a SQLite file at `data/app.db`; that is convenient on your machine, but it is not durable in containers, previews, or serverless environments where the filesystem can be reset.
+
+Set `DATABASE_URL` in your deploy provider before promoting an app to production. Agent-native uses Drizzle for schema and queries, so the data layer is portable across Drizzle-compatible SQL backends. The built-in adapters auto-detect Postgres URLs, libSQL/Turso URLs, SQLite file URLs, and Cloudflare D1 bindings. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, and Builder.io-managed environments when available. Turso is one option, not a requirement.
+
+Use `DATABASE_AUTH_TOKEN` only when your database provider requires a separate token, such as Turso/libSQL. For workspaces, all apps inherit the root `DATABASE_URL` by default; set `<APP_NAME>_DATABASE_URL` when one app should use a different database.
+
 ## Workspace Deploy: One Origin, Many Apps {#workspace-deploy}
 
 If your project is a [workspace](/docs/multi-app-workspace), you can ship every app in it to a single origin with one command:
@@ -200,13 +208,13 @@ export default defineConfig({
 
 ### Build / Runtime {#env-runtime}
 
-| Variable              | Description                                                                                                          |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `PORT`                | Server port (Node.js only)                                                                                           |
-| `NITRO_PRESET`        | Override build preset at build time                                                                                  |
-| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `agent-native deploy`; leave unset for standalone. |
-| `DATABASE_URL`        | Postgres / Turso / SQLite connection string. Required in production.                                                 |
-| `DATABASE_AUTH_TOKEN` | Auth token for Turso / libsql connections.                                                                           |
+| Variable              | Description                                                                                                                                                                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                | Server port (Node.js only)                                                                                                                                                                         |
+| `NITRO_PRESET`        | Override build preset at build time                                                                                                                                                                |
+| `APP_BASE_PATH`       | Mount the app under a prefix (e.g. `/mail`). Set automatically by `agent-native deploy`; leave unset for standalone.                                                                               |
+| `DATABASE_URL`        | Persistent SQL connection string. Required in production; common options include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, and Builder.io-managed environments when available. |
+| `DATABASE_AUTH_TOKEN` | Auth token for providers that require a separate token, such as Turso/libSQL.                                                                                                                      |
 
 ### Required in Production {#env-required-prod}
 

package/docs/content/dispatch.md

@@ -19,7 +19,7 @@ Reach for Dispatch when any of these are true:
 - You want **one inbox for "the agent"** so users DM a single bot and the right specialist app picks up the work behind the scenes.
 - You have **workspace-wide secrets** (Stripe key, OpenAI key, third-party API tokens) that several apps need and you want one vault instead of copying values into every `.env`.
 - You want a **runtime approval flow** in front of sensitive changes (saved destinations, policy edits) so non-admins can request and admins can sign off without a code deploy.
-- You want **shared skills, instructions, and agent profiles** that every app in the workspace inherits — change once, reach all.
+- You want **shared skills, instructions, agent profiles, and MCP servers** that apps in the workspace inherit — change once, reach all.
 
 If you're running a single template standalone, you don't need Dispatch — each template can wire its own messaging integrations directly. See [Messaging](/docs/messaging) for the standalone setup.
 
@@ -76,6 +76,7 @@ Use the canonical paths to control how agents consume them:
 - `skills/<slug>/SKILL.md` for on-demand skills available through `/` commands and the prompt skill index
 - `context/<slug>.md` for brand, persona, positioning, messaging, company facts, and other reference material the agent reads when relevant
 - `agents/<slug>.md` for reusable custom agent profiles
+- `mcp-servers/<slug>.json` for HTTP MCP servers that should add external tools to granted app agents
 
 Starter global resources usually look like:
 
@@ -89,6 +90,11 @@ skills/company-voice/SKILL.md
 
 Set these to **All apps** when every app should inherit the same company facts, brand rules, messaging, safety constraints, and customer-facing writing style. Use selected-app grants only for resources that are genuinely app-specific.
 
+MCP server resources use JSON and are intentionally HTTP-only. Store tokens in
+Dispatch Vault, grant or sync those keys to the target apps, and reference them
+from headers with `${keys.NAME}` so the raw credential never lives in the
+resource body.
+
 The **Resources** page highlights this starter pack in a Global context section so admins can quickly see which files exist, whether they are scoped to all apps, restore missing starter files without overwriting existing ones, and edit their contents. Expand any resource to preview its effective runtime stack for a selected app/user: workspace default, organization/app override, then personal override. Each app card also has a **Context** view that shows exactly what that app receives: inherited workspace resources, selected grants, and auto-loaded instructions. Use a resource row's **Stack** control to inspect which layer wins for that app.
 
 This is how a team-wide change ("always use British English in customer-facing replies") or a shared brand guideline propagates without editing ten repos.

package/docs/content/embedding-sdk.md

@@ -14,6 +14,85 @@ Use it when you want an assistant that can:
 - Ask the host app to navigate, refresh data, remount a view, or open a resource after durable work completes.
 - Run as an iframe/sidebar now, while leaving room for a no-iframe package or hosted template later.
 
+## Embedded App And Picker Mode
+
+Use `@agent-native/embedding` when the host product wants to launch a complete
+Agent-Native app as a focused iframe surface: an asset picker, asset generator,
+form builder, calendar slot picker, approval panel, or any other task-specific
+workflow. This is intentionally smaller than the sidecar host bridge below: the
+iframe announces readiness, the host can send named messages, and the embedded
+app can emit domain events such as `chooseAsset` or `close`.
+
+```tsx
+import { EmbeddedApp } from "@agent-native/embedding";
+
+export function AssetPickerDialog({ close }) {
+  return (
+    <EmbeddedApp
+      url="https://assets.agent-native.com/picker"
+      className="h-full w-full"
+      onLoad={(ref) => {
+        ref.postMessage("configure", {
+          prompt: "Editorial blog hero",
+          aspectRatio: "16:9",
+        });
+      }}
+      onMessage={(name, payload) => {
+        if (name === "chooseAsset") {
+          const asset = payload as { url: string; altText?: string };
+          insertAsset(asset.url, asset.altText);
+          close();
+        }
+        if (name === "close") close();
+      }}
+    />
+  );
+}
+```
+
+Inside the embedded app, use the browser bridge to announce readiness and send
+events back to the host:
+
+```ts
+import {
+  announceEmbeddedAppReady,
+  sendEmbeddedAppMessage,
+} from "@agent-native/embedding/bridge";
+
+announceEmbeddedAppReady({ app: "assets", mode: "picker" });
+sendEmbeddedAppMessage("chooseAsset", {
+  url: asset.previewUrl,
+  assetId: asset.id,
+  altText: asset.altText,
+});
+```
+
+Assets also emits `chooseImage` as a compatibility alias for older image-picker
+hosts; new integrations should listen for `chooseAsset`.
+
+For hosted first-party apps, enable Cross-App SSO with Dispatch as the identity
+hub so `content.agent-native.com` and `assets.agent-native.com` link users by
+verified email. Iframe launches should still use short-lived, route-scoped
+embed sessions when they need third-party-cookie resilience; normal app cookies
+are not a complete embed auth story on their own.
+
+The same package includes agent endpoint helpers for protocol discovery and
+streaming text over A2A:
+
+```ts
+import { getA2AUrl, getMcpUrl, sendMessage } from "@agent-native/embedding";
+
+getMcpUrl("https://assets.agent-native.com");
+getA2AUrl("https://assets.agent-native.com");
+
+for await (const chunk of sendMessage(
+  "https://assets.agent-native.com",
+  "Generate a blog hero",
+)) {
+  append(chunk);
+}
+```
+
 ## Batteries-Included Embedded Mode
 
 For most SaaS hosts, use the full embedded runtime. The host mounts Agent-Native server routes into its existing app, passes its logged-in user to Agent-Native, and then renders the React sidebar/surface in the product UI. Agent-Native uses the host deployment, host session, and the configured `DATABASE_URL` to manage its own framework tables: chat threads, settings, application state, extensions, extension data, secrets, browser sessions, and action routes.

package/docs/content/key-concepts.md

@@ -96,10 +96,10 @@ export const forms = table("forms", {
 ```
 
 ```bash
-# Core actions for quick database access
+# Core actions for quick database inspection and one-off maintenance
 pnpm action db-schema                                       # show all tables
 pnpm action db-query --sql "SELECT * FROM forms"
-pnpm action db-exec --sql "INSERT INTO forms ..."
+pnpm action db-exec --sql "UPDATE forms SET status = ? WHERE id = ?" --args '["closed","form-1"]'
 # Surgical find/replace on a large text column — sends a diff, not the whole value
 pnpm action db-patch --table documents --column content \
   --where "id='doc-1'" --find "old heading" --replace "new heading"
@@ -227,7 +227,7 @@ There's no shared codebase to break. You own the app, and the agent evolves it f
 
 ## Database agnostic {#database-agnostic}
 
-The framework supports every Drizzle-supported database. Never write SQL that only works on one dialect.
+The framework supports portable Drizzle-backed SQL databases. Write app schemas with `@agent-native/core/db/schema` and app reads/writes with Drizzle's query builder so code can run across providers.
 
 - **SQLite** — local dev fallback when `DATABASE_URL` is unset
 - **Neon Postgres** — common in both dev and production
@@ -236,24 +236,22 @@ The framework supports every Drizzle-supported database. Never write SQL that on
 - **Cloudflare D1**
 - **Plain Postgres**
 
-Use the framework helpers for dialect-agnostic SQL:
+Use Drizzle's portable query DSL for normal app code:
 
 ```ts
-import { getDbExec, isPostgres, intType } from "@agent-native/core/db";
-
-// getDbExec() auto-converts ? params to $1 for Postgres
-const client = getDbExec();
-await client.execute({
-  sql: "SELECT * FROM forms WHERE owner_email = ?",
-  args: [email],
-});
-
-// Branch when syntax differs
-const upsert = isPostgres()
-  ? "INSERT INTO settings (key, value) VALUES ($1, $2) ON CONFLICT (key) DO UPDATE SET value = $2"
-  : "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)";
+import { and, desc, eq } from "drizzle-orm";
+
+const forms = await db
+  .select()
+  .from(schema.forms)
+  .where(
+    and(eq(schema.forms.ownerEmail, email), eq(schema.forms.status, "open")),
+  )
+  .orderBy(desc(schema.forms.createdAt));
 ```
 
+Use raw SQL only for additive migrations, health checks, or one-off maintenance, and keep it parameterized and dialect-agnostic.
+
 ## Hosting agnostic {#hosting-agnostic}
 
 The server runs on Nitro, which compiles to any deployment target:

package/docs/content/mcp-clients.md

@@ -159,6 +159,36 @@ If your workspace runs multiple agent-native apps (e.g. dispatch + mail + clips)
 
 Dispatch is the conventional hub — it already coordinates across apps.
 
+For new workspace setups, prefer **Dispatch workspace MCP resources** when you
+want the same All-app vs selected-app grant model used by workspace skills,
+instructions, and reference resources. Add a workspace resource with:
+
+```json
+{
+  "type": "http",
+  "url": "https://example.com/mcp",
+  "headers": {
+    "Authorization": "Bearer ${keys.MCP_SERVER_TOKEN}"
+  },
+  "description": "Shared MCP tools for workspace apps"
+}
+```
+
+Save it under `mcp-servers/<name>.json` with kind `mcp-server`. All-app
+resources are loaded by every workspace app; selected resources load only in
+apps with an active Dispatch grant. Secret placeholders resolve from the app
+secret store, so put raw bearer tokens in Dispatch Vault and reference them
+with `${keys.NAME}` instead of storing them in the resource body.
+
+Apps refresh their merged MCP config about once a minute, so central resource
+edits, grant changes, and removals take effect without a deploy. Set
+`AGENT_NATIVE_MCP_CONFIG_REFRESH_MS=0` to disable that background refresh, or
+set it to a value of at least `5000` milliseconds to tune the interval.
+
+The older hub mode below remains useful for coarse “share every org-scope MCP
+server from Dispatch” setups and for deployments that already use the MCP
+settings UI as the source of truth.
+
 ### 1. Enable hub-serve on the hub app (dispatch)
 
 Set an env var in dispatch's deployment:

package/docs/content/multi-app-workspace.md

@@ -141,7 +141,7 @@ Use `packages/shared` for code-level defaults that should ship with the repo: pl
 Dispatch resources support two scopes:
 
 - **All apps** — global resources for every app in the workspace. Dispatch stores them once at workspace scope and every app agent inherits them at runtime; no copy or sync step is required.
-- **Selected apps** — resources granted per app for app-specific context. Use these sparingly; most company, brand, persona, positioning, messaging, and guardrail context should be All apps.
+- **Selected apps** — resources granted per app for app-specific context or tools. Use these sparingly; most company, brand, persona, positioning, messaging, and guardrail context should be All apps.
 
 Canonical paths control behavior:
 
@@ -151,8 +151,9 @@ Canonical paths control behavior:
 | Global skills           | `skills/<slug>/SKILL.md`                | Listed as workspace skills and read on demand   |
 | Brand/company resources | `context/<slug>.md`                     | Indexed every turn, read when relevant          |
 | Custom agent profiles   | `agents/<slug>.md`                      | Available as reusable local agent profiles      |
+| Shared HTTP MCP servers | `mcp-servers/<slug>.json`               | Loaded into granted apps' MCP tool registry     |
 
-This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, or other shared knowledge that many apps should benefit from.
+This is the right home for core personas, positioning, messaging, company facts, brand guidelines, support policies, shared skills, or shared HTTP MCP tools that many apps should benefit from.
 
 For a starter workspace, create these Dispatch resources and scope them to **All apps**:
 

package/docs/content/multi-tenancy.md

@@ -54,15 +54,15 @@ For full details on how scoping works at the SQL level, see [Security & Data Sco
 
 ## Adding multi-tenancy to a new table {#new-tables}
 
-When you add a new domain table, include `organization_id` to make it tenant-aware:
+When you add a new domain table, use the framework's dialect-agnostic schema helpers and include ownership columns to make it tenant-aware:
 
 ```typescript
-import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { table, text, ownableColumns } from "@agent-native/core/db/schema";
 
-export const projects = sqliteTable("projects", {
+export const projects = table("projects", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
-  organizationId: text("organization_id").notNull(),
+  ...ownableColumns(),
   // ... other columns
 });
 ```

package/docs/content/server.md

@@ -94,20 +94,23 @@ Plugins live in `server/plugins/` and run at startup. Use them for migrations, p
 
 ```ts
 // server/plugins/db.ts
-import { runMigrations } from "@agent-native/core/db/migrations";
+import { runMigrations } from "@agent-native/core/db";
 
-export default runMigrations([
-  {
-    id: "001_create_projects",
-    sql: `CREATE TABLE IF NOT EXISTS projects (
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
       id TEXT PRIMARY KEY,
       title TEXT NOT NULL,
       owner_email TEXT NOT NULL,
       org_id TEXT,
       created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
     )`,
-  },
-]);
+    },
+  ],
+  { table: "my_app_migrations" },
+);
 ```
 
 Migrations must be additive. Never put destructive SQL in startup plugins.

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              |