@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/database.md

@@ -0,0 +1,183 @@
+---
+title: "Datenbank"
+description: "Verbinden Sie eine portable SQL-Datenbank mit Ihrer agentennativen App und schreiben Sie anbieterunabhängigen Drizzle-Code."
+---
+
+# Datenbank
+
+Agent-native Apps verwenden [Drizzle ORM](https://orm.drizzle.team) und unterstützen portable SQL-Backends. Für alles, was über die lokale Entwicklung hinausgeht, verbinden Sie eine persistente SQL-Datenbank – Postgres, libSQL/Turso oder ein anderes Drizzle-kompatibles Backend – indem Sie `DATABASE_URL` festlegen. Wenn diese Variable nicht gesetzt ist, greift die App auf eine lokale SQLite-Datei ohne Konfiguration zurück, sodass Sie sofort mit der Entwicklung beginnen können.
+
+```an-diagram title="One schema, many backends" summary="App code uses the framework's dialect-agnostic helpers. The dialect is auto-detected from DATABASE_URL at runtime; unset means a local SQLite file."
+{
+  "html": "<div class=\"diagram-db\"><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">@agent-native/core/db/schema</span><small class=\"diagram-muted\">table · text · integer · real · now</small><small class=\"diagram-muted\">+ Drizzle query DSL</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>DATABASE_URL<br><small class=\"diagram-muted\">dialect auto-detected</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Postgres<br><small class=\"diagram-muted\">Neon · Supabase</small></span><span class=\"diagram-pill\">libSQL / Turso</span><span class=\"diagram-pill\">Cloudflare D1</span><span class=\"diagram-pill warn\">SQLite file<br><small class=\"diagram-muted\">unset = local dev only</small></span></div></div>",
+  "css": ".diagram-db{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-db .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-db .diagram-arrow{font-size:22px;line-height:1}.diagram-db .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}"
+}
+```
+
+## Lokaler Standard: SQLite-Datei {#default-sqlite}
+
+Wenn `DATABASE_URL` nicht festgelegt ist, erstellt die App eine SQLite-Datenbank unter `data/app.db`. Dies ist die Zero-Config-Standardeinstellung für die lokale Entwicklung – keine Einrichtung erforderlich. Es ist nur für die Entwicklung gedacht; Legen Sie für die Produktion `DATABASE_URL` auf eine persistente SQL-Datenbank fest.
+
+Verlassen Sie sich bei bereitgestellten Apps nicht auf diese lokale Datei. Container, serverlose Funktionen und Vorschauumgebungen setzen möglicherweise ihr Dateisystem zurück, was bedeutet, dass eine lokale SQLite-Datei zwischen Neustarts verschwinden kann. Legen Sie `DATABASE_URL` vor der Produktionsverwendung auf eine dauerhaft gehostete Datenbank fest.
+
+## Verbinden einer Produktionsdatenbank {#production}
+
+Legen Sie `DATABASE_URL` in Ihrer `.env`-Datei oder Deploy-Provider-Umgebung fest, um eine gehostete Datenbank zu verbinden. Turso ist nicht erforderlich; Verwenden Sie das Drizzle-kompatible SQL-Backend, das zu Ihrer Bereitstellung passt:
+
+```bash
+# Neon Postgres
+DATABASE_URL=postgres://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/mydb?sslmode=require
+
+# Supabase Postgres
+DATABASE_URL=postgres://postgres.xxxx:pass@aws-0-us-east-1.pooler.supabase.com:6543/postgres
+
+# Plain Postgres
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+
+# Turso (libSQL)
+DATABASE_URL=libsql://my-db-org.turso.io
+DATABASE_AUTH_TOKEN=your-token
+```
+
+Das Framework erkennt automatisch den Dialekt von URL und konfiguriert Drizzle entsprechend. Die integrierten Adapter decken Postgres URLs, libSQL/Turso URLs, SQLite-Datei-URLs und Cloudflare D1-Bindungen ab. Zu den gängigen Produktionsoptionen gehören Neon, Supabase, Turso/libSQL, einfaches Postgres, dauerhaftes SQLite und von Builder.io verwaltete Umgebungen, sofern verfügbar.
+
+## Builder.io Verwaltete Datenbank {#builder-managed}
+
+_Geplant (noch nicht verfügbar):_ Wenn Ihre App mit Builder.io verbunden ist, kann sie eine verwaltete Datenbank verwenden, die automatisch bereitgestellt wird, ohne dass Verbindungszeichenfolgen erforderlich sind.
+
+## Wo der DB-Client lebt {#db-client}
+
+Jede Vorlage erstellt einen verzögerten Singleton-Drizzle-Client, indem sie `createGetDb(schema)` von `@agent-native/core/db` aus aufruft. Der kanonische Speicherort ist `server/db/index.ts`:
+
+```ts
+// server/db/index.ts
+import { createGetDb } from "@agent-native/core/db";
+import * as schema from "./schema.js";
+
+export const getDb = createGetDb(schema);
+```
+
+Importieren Sie `getDb` aus diesem vorlagenlokalen Pfad – `../../server/db/index.js` in Routen, `../server/db/index.js` in actions – und nicht direkt aus `@agent-native/core`. Der Kernexport gibt eine generische, untypisierte Instanz zurück; Der `getDb()` der Vorlage trägt Ihre Schematypen. Unter [Server](/docs/server#request-context) erfahren Sie, wie actions und benutzerdefinierte Routen es jeweils importieren.
+
+## Dialektunabhängiges Schema und Abfragen {#schema}
+
+App-Datenbankcode sollte das Schema von Drizzle verwenden und DSL abfragen, damit er anbieterübergreifend ausgeführt werden kann. Schreiben Sie niemals nur die SQLite-Syntax (`INSERT OR REPLACE`, `AUTOINCREMENT`, `datetime('now')`) oder nur die Postgres-Syntax in den Produktcode.
+
+Verwenden Sie die Schema-Helfer des Frameworks von `@agent-native/core/db/schema`:
+
+```ts
+import { table, text, integer, real, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  priority: integer("priority").notNull().default(0),
+  weight: real("weight"),
+  done: integer("done", { mode: "boolean" }).notNull().default(false),
+  ownerEmail: text("owner_email").notNull(),
+  createdAt: text("created_at").notNull().default(now()),
+});
+```
+
+| Helfer    | Zweck                                                                              |
+| --------- | ---------------------------------------------------------------------------------- |
+| `table`   | Definieren Sie eine Tabelle – delegiert an `pgTable` oder `sqliteTable`            |
+| `text`    | Textspalte, unterstützt `{ enum: [...] }`                                          |
+| `integer` | Integer-Spalte, `{ mode: "boolean" }` wird dem booleschen Wert Postgres zugeordnet |
+| `real`    | Float-Spalte – `real` auf SQLite, `double precision` auf Postgres                  |
+| `now`     | Dialektunabhängiger aktueller Zeitstempel für `.default(now())`                    |
+
+Die obige `tasks`-Tabelle definiert die gleichen Spalten auf jedem Backend:
+
+```an-schema title="The tasks table" summary="Defined once with the framework helpers; the dialect is chosen at runtime from DATABASE_URL."
+{
+  "entities": [
+    {
+      "id": "tasks",
+      "name": "tasks",
+      "note": "Domain table. Add owner_email (or ...ownableColumns()) so SQL-level scoping can filter rows to the authenticated user.",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "nullable": false },
+        { "name": "title", "type": "text", "nullable": false },
+        { "name": "priority", "type": "integer", "nullable": false, "note": "default 0" },
+        { "name": "weight", "type": "real", "nullable": true },
+        { "name": "done", "type": "integer (boolean mode)", "nullable": false, "note": "default false; maps to a Postgres boolean" },
+        { "name": "owner_email", "type": "text", "nullable": false, "note": "enables data scoping" },
+        { "name": "created_at", "type": "text", "nullable": false, "note": "default now()" }
+      ]
+    }
+  ]
+}
+```
+
+Niemals direkt aus `drizzle-orm/sqlite-core` oder `drizzle-orm/pg-core` importieren. Verwenden Sie immer `@agent-native/core/db/schema`.
+
+Tabellen, in denen benutzerbezogene Daten gespeichert werden, müssen eine `owner_email`-Spalte enthalten, damit das Scoping auf SQL-Ebene des Frameworks Zeilen für den authentifizierten Benutzer filtern kann – siehe [Security](/docs/security#data-scoping). Tabellen, die auch die Freigabe mit anderen Benutzern oder Organisationen unterstützen, sollten stattdessen `...ownableColumns()` verbreiten, wodurch `owner_email`, `org_id` und `visibility` in einem Aufruf hinzugefügt werden – siehe [Sharing](/docs/sharing#building).
+
+Verwenden Sie für Lese- und Schreibvorgänge den Abfrage-Builder von Drizzle und die portablen Operatoren von `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));
+
+await db.update(tasks).set({ done: true }).where(eq(tasks.id, taskId));
+```
+
+## Rohe SQL Fluchtluken {#raw-sql}
+
+Raw SQL ist nicht der Standard-App-Code API. Verwenden Sie es nur für additive Migrationen, Zustandsprüfungen, sorgfältig geprüfte erweiterte Abfragen, die Drizzle nicht ausdrücken kann, oder einmalige Wartungsarbeiten. Halten Sie es parametrisiert und dialektunabhängig. Für Zeitstempel in Drizzle-Schemas bevorzugen Sie `.default(now())`; Verwenden Sie für die Migration SQL `runMigrations()`, damit vom Framework unterstützte Kompatibilitätsumschreibungen und dialektgesteuerte Anweisungen zentralisiert bleiben.
+
+Für Fälle, in denen Sie wirklich rohes SQL außerhalb von Drizzle-Abfragen benötigen:
+
+- `getDbExec()` – konvertiert `?`-Parameter automatisch in `$1` für Postgres
+- `isPostgres()` – Dialektprüfung zur Laufzeit
+- `intType()` – gibt den richtigen Ganzzahltyp für den aktuellen Dialekt zurück
+
+## Migrationen und Schemaaktualisierungen {#migrations}
+
+In gehosteten Umgebungen nutzen mehrere Bereitstellungsvorschauen, Zweige und der Produktionsserver dieselbe zugrunde liegende Datenbank. Daher müssen Aktualisierungen des Datenbankschemas strengen Einschränkungen unterliegen, um Datenverlust und Dienstunterbrechungen zu vermeiden.
+
+### Die „Zero Destructive Changes“-Regel
+
+Alle Aktualisierungen des Datenbankschemas müssen **streng additiv** erfolgen.
+
+- **Tabellen oder Spalten nicht löschen.**
+- **Benennen Sie keine Tabellen oder Spalten um.** Das Umbenennen einer Spalte oder Tabelle ähnelt einer Drop-+Create-Sequenz in Drizzle, wodurch Ihre vorhandenen Produktionsdaten dauerhaft gelöscht werden.
+- Wenn eine Spalte umbenannt oder ersetzt werden muss, fügen Sie die neue Spalte neben der alten hinzu, aktualisieren Sie Ihren Anwendungscode zum Lesen/Schreiben in beide, migrieren Sie die Daten und entfernen Sie die alte Spalte erst in einer späteren Version, wenn keine aktiven Bereitstellungen darauf verweisen.
+
+> [!WARNING]
+> **Führen Sie `drizzle-kit push` niemals für eine Produktionsdatenbank aus.**
+> Vorlagendatenbankschemata definieren nur anwendungsspezifische Domänentabellen; Sie definieren keine zentralen Rahmentabellen (`user`, `session`, `application_state` usw.). Wenn Sie `drizzle-kit push` für die Produktion ausführen, erkennt Drizzle diese Framework-Tabellen als „nicht im Schema“ und versucht, sie zu löschen, was zu einem sofortigen systemweiten Ausfall und Datenverlust führt.
+
+### Sicherer Migrationspfad
+
+Anstatt direkt zu pushen, sollten Schemaänderungen über SQL-Migrationen angewendet werden, die beim Anwendungsstart ausgeführt werden. Implementieren Sie additive Migrationen innerhalb eines Server-Plugins (z. B. `server/plugins/db.ts`), indem Sie den `runMigrations()`-Helper des Frameworks aufrufen:
+
+```an-annotated-code title="An additive migration plugin"
+{
+  "filename": "server/plugins/db.ts",
+  "language": "ts",
+  "code": "import { runMigrations } from \"@agent-native/core/db\";\n\nexport default runMigrations(\n  [\n    {\n      version: 1,\n      sql: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS sort_order INTEGER NOT NULL DEFAULT 0`,\n    },\n    {\n      // Dialect-gated: runs only on the matching backend. Omit the other key\n      // to make it a no-op on that dialect.\n      version: 2,\n      sql: {\n        postgres: `ALTER TABLE projects ADD COLUMN IF NOT EXISTS tsv tsvector`,\n        sqlite: `SELECT 1`, // no-op; tsvector is Postgres-only\n      },\n    },\n  ],\n  { table: \"my_app_migrations\" },\n);",
+  "annotations": [
+    { "lines": "6-7", "label": "Additive only", "note": "`ADD COLUMN IF NOT EXISTS` is safe to re-run and never drops data. Renames look like drop+create to Drizzle, so add-then-migrate instead." },
+    { "lines": "13-16", "label": "Dialect gating", "note": "Pass an object keyed by dialect to run different SQL per backend. Make the other key a no-op (`SELECT 1`) for Postgres-only or SQLite-only features." },
+    { "lines": "19", "label": "Per-app version table", "note": "Each app tracks its own applied versions so migrations are idempotent across restarts and instances." }
+  ]
+}
+```
+
+## Umgebungsvariablen {#environment-variables}
+
+| Variable              | Zweck                                                                                                                      |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Persistente SQL-Verbindungszeichenfolge (nicht gesetzt = lokales SQLite, das nur für die lokale Entwicklung dauerhaft ist) |
+| `DATABASE_AUTH_TOKEN` | Auth-Token für Anbieter, die ein separates Token erfordern, wie z. B. Turso/libSQL                                         |

package/docs/content/locales/de-DE/deployment.md

@@ -0,0 +1,349 @@
+---
+title: "Bereitstellung"
+description: "Stellen Sie agentennative Apps auf jeder Plattform mit Nitro-Voreinstellungen bereit – Node.js, Vercel, Netlify, Cloudflare, AWS und mehr."
+---
+
+# Bereitstellung
+
+Agent-native Apps verwenden unter der Haube [Nitro](https://nitro.build), was bedeutet, dass Sie sie ohne Konfigurationsänderungen auf jeder Plattform bereitstellen können – legen Sie einfach eine Voreinstellung fest.
+
+## Vor der Bereitstellung: Wählen Sie eine persistente Datenbank {#persistent-database}
+
+Jede bereitgestellte App benötigt eine persistente SQL-Datenbank. Bei der lokalen Entwicklung greift Agent-nativ auf eine SQLite-Datei unter `data/app.db` zurück; Das ist praktisch auf Ihrem Computer, aber in Containern, Vorschauen oder serverlosen Umgebungen, in denen das Dateisystem zurückgesetzt werden kann, ist es nicht dauerhaft.
+
+Legen Sie `DATABASE_URL` in Ihrem Bereitstellungsanbieter fest, bevor Sie eine App in die Produktion hochstufen. Agent-native verwendet Drizzle für Schemata und Abfragen, sodass die Datenschicht über Drizzle-kompatible SQL-Backends portierbar ist und das Framework den Dialekt von URL automatisch erkennt. Die Adapterliste und Dialektdetails finden Sie unter [Database](/docs/database#production).
+
+Verwenden Sie `DATABASE_AUTH_TOKEN` nur, wenn Ihr Datenbankanbieter ein separates Token erfordert, z. B. Turso/libSQL. Für Arbeitsbereiche erben alle Apps standardmäßig das Stammverzeichnis `DATABASE_URL`; Legen Sie `<APP_NAME>_DATABASE_URL` fest, wenn eine App eine andere Datenbank verwenden soll.
+
+## Workspace Deploy: Ein Ursprung, viele Apps {#workspace-deploy}
+
+Wenn es sich bei Ihrem Projekt um ein [workspace](/docs/multi-app-workspace) handelt, können Sie jede darin enthaltene App mit einem einzigen Befehl an einen einzigen Ursprung senden:
+
+```bash
+npx @agent-native/core@latest deploy
+# https://your-agents.com/mail/*       → apps/mail
+# https://your-agents.com/calendar/*   → apps/calendar
+# https://your-agents.com/forms/*      → apps/forms
+```
+
+Jede App wird mit `APP_BASE_PATH=/<name>` und `VITE_APP_BASE_PATH=/<name>` erstellt und dann für die Zielvoreinstellung Nitro gepackt. Cloudflare Pages ist die Standardvoreinstellung und verwendet einen generierten Dispatcher-Worker unter `dist/_worker.js`; Netlify verwendet eine Funktion pro App in `.netlify/functions-internal/<app>-server` plus generierte Weiterleitungen; Vercel schreibt mithilfe der Build-Ausgabe API einen `.vercel/output` auf Arbeitsbereichsebene.
+
+```an-diagram title="One origin, many apps" summary="Each workspace app is built with its own base path and mounted under a path prefix on a single origin — so login and cross-app A2A are same-origin and free."
+{
+  "html": "<div class=\"diagram-ws\"><div class=\"diagram-panel\" data-rough><strong>https://your-agents.com</strong><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/mail/*</span><small class=\"diagram-muted\">apps/mail</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/calendar/*</span><small class=\"diagram-muted\">apps/calendar</small></div><div class=\"diagram-row\"><span class=\"diagram-pill accent\">/forms/*</span><small class=\"diagram-muted\">apps/forms</small></div></div><div class=\"diagram-col wins\"><span class=\"diagram-pill ok\">shared login session</span><span class=\"diagram-pill ok\">zero-config cross-app A2A</span></div></div>",
+  "css": ".diagram-ws{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.diagram-ws .diagram-panel{display:flex;flex-direction:column;gap:6px;padding:14px 16px}.diagram-ws .diagram-row{display:flex;align-items:center;gap:8px}.diagram-ws .wins{display:flex;flex-direction:column;gap:8px;align-items:flex-start}"
+}
+```
+
+Mit der Same-Origin-Bereitstellung erhalten Sie zwei große Gewinne kostenlos:
+
+- **Gemeinsame Anmeldesitzung** – Melden Sie sich bei jeder App an, jede App ist angemeldet.
+- **Zero-config Cross-App A2A** – das Markieren von `@calendar` aus E-Mails ist ein Abruf mit demselben Ursprung; kein CORS, kein JWT, der zwischen Geschwistern signiert.
+
+Veröffentlichen Sie die Ausgabe mit:
+
+```bash
+wrangler pages deploy dist
+```
+
+Verwenden Sie für einheitliche Netlify-Bereitstellungen die Netlify-Voreinstellung:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+Verwenden Sie für einheitliche Vercel-Bereitstellungen die Vercel-Voreinstellung:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Verwenden Sie beim Konfigurieren eines Provider-Build-Befehls denselben Befehl mit `--build-only`. Vercel sollte `npx @agent-native/core@latest deploy --preset vercel --build-only` ausführen; Der Befehl schreibt `.vercel/output` direkt, sodass für das Workspace-Routing kein `vercel.json` erforderlich ist.
+
+Gehostete Workspace-Builds erfordern `A2A_SECRET` in der Bereitstellungsanbieterumgebung.
+Dadurch nehmen Slack, eingehender webhooks und appübergreifender A2A die Arbeit über signiert wieder auf
+Hintergrundprozessoren. Lokale `--build-only`-Artefaktprüfungen werden auch ohne ausgeführt.
+
+Die unabhängige Bereitstellung pro App wird weiterhin unterstützt – nur `cd apps/<name> && npx @agent-native/core@latest build` wie ein eigenständiges Gerüst.
+
+## Wie es funktioniert {#how-it-works}
+
+Wenn Sie `npx @agent-native/core@latest build` ausführen, erstellt Nitro sowohl den Client SPA als auch den Server API in `.output/`:
+
+```an-file-tree title="Build output"
+{
+  "entries": [
+    { "path": ".output/", "note": "self-contained — copy to any environment and run" },
+    { "path": ".output/public/", "note": "built SPA (static assets)" },
+    { "path": ".output/server/index.mjs", "note": "server entry point" },
+    { "path": ".output/server/chunks/", "note": "server code chunks" }
+  ]
+}
+```
+
+Die Ausgabe ist in sich geschlossen – kopieren Sie `.output/` in eine beliebige Umgebung und führen Sie sie aus.
+
+```an-diagram title="Build to deploy" summary="One source tree builds to a Nitro preset; the same self-contained output runs on Node, Vercel, Netlify, Cloudflare, AWS, or Deno. Every instance points at the same persistent DATABASE_URL."
+{
+  "html": "<div class=\"diagram-deploy\"><div class=\"diagram-box\" data-rough>App source</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">build</span><small class=\"diagram-muted\">Nitro preset</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">Node.js</span><span class=\"diagram-pill\">Vercel</span><span class=\"diagram-pill\">Netlify</span><span class=\"diagram-pill\">Cloudflare</span><span class=\"diagram-pill\">AWS Lambda</span><span class=\"diagram-pill\">Deno</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Persistent DATABASE_URL<br><small class=\"diagram-muted\">shared by every instance</small></div></div>",
+  "css": ".diagram-deploy{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-deploy .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px 16px}.diagram-deploy .diagram-arrow{font-size:22px;line-height:1}.diagram-deploy .diagram-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}"
+}
+```
+
+## Voreinstellung festlegen {#setting-the-preset}
+
+Standardmäßig erstellt Nitro für Node.js. Um eine andere Plattform anzusprechen, legen Sie die Voreinstellung in Ihrem `vite.config.ts` fest:
+
+```ts
+import { defineConfig } from "@agent-native/core/vite";
+
+export default defineConfig({
+  nitro: {
+    preset: "vercel",
+  },
+});
+```
+
+Oder verwenden Sie zur Build-Zeit die Umgebungsvariable `NITRO_PRESET`:
+
+```bash
+NITRO_PRESET=netlify npx @agent-native/core@latest build
+```
+
+## Node.js (Standard) {#nodejs}
+
+Die Standardvoreinstellung. Erstellen und ausführen:
+
+```bash
+npx @agent-native/core@latest build
+node .output/server/index.mjs
+```
+
+Legen Sie `PORT` fest, um den Listen-Port zu konfigurieren (Standard: `3000`).
+
+Verwenden Sie die aktuelle Node.js LTS-Reihe für Produktionsbereitstellungen. Ab Mai 2026 ist das
+ist Node.js 24; Node.js 20 hat am 30. April 2026 das Ende seiner Lebensdauer erreicht und nicht mehr
+erhält Upstream-Sicherheitsupdates.
+
+### Docker {#docker}
+
+```dockerfile
+FROM node:24-slim AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:24-slim
+WORKDIR /app
+COPY --from=build /app/.output .output
+# data/ is a runtime-created SQLite directory — do not copy a dev DB into prod.
+# For production, set DATABASE_URL to a hosted Postgres or Turso instance.
+RUN mkdir -p /app/data
+ENV PORT=3000
+EXPOSE 3000
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## Vercel {#vercel}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "vercel" },
+});
+```
+
+Bereitstellung über Vercel CLI oder Git Push:
+
+```bash
+vercel deploy
+```
+
+Erstellen Sie für einen Arbeitsbereich jede App in einem Vercel Build Output API-Bundle:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel
+```
+
+Legen Sie für Vercel Git-Bereitstellungen den Build-Befehl auf Folgendes fest:
+
+```bash
+npx @agent-native/core@latest deploy --preset vercel --build-only
+```
+
+Der Workspace-Build kopiert die Nitro `vercel`-Ausgabe jeder App in das Stammverzeichnis `.vercel/output`, gibt jeder Funktion eine eigene Mount-Pfad-Umgebung und schreibt die Routenkonfiguration, die Apps unter `/<app-id>` bereitstellt.
+
+## Netlify {#netlify}
+
+Die Nitro `netlify`-Voreinstellung funktioniert gut und hat uns in der Praxis viel schnellere Kaltstarts ermöglicht als Cloudflare Pages (~200 ms TTFB vs. ~9 s) für Vorlagen, die mit externem Postgres (Neon) kommunizieren. Legen Sie entweder die Voreinstellung in `vite.config.ts`:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "netlify" },
+});
+```
+
+…oder legen Sie `NITRO_PRESET=netlify` zur Erstellungszeit fest.
+
+Stellen Sie für einen Arbeitsbereich jede App von einer Netlify-Site bereit, indem Sie Folgendes ausführen:
+
+```bash
+npx @agent-native/core@latest deploy --preset netlify
+```
+
+Der Workspace-Build schreibt statische Assets unter `dist/_workspace_static/` und leitet jede App ohne erzwungene Asset-Umleitungen an ihre eigene Netlify-Funktion weiter, sodass Dateien wie `/mail/assets/...` statisch bereitgestellt werden, bevor die Serverfunktion App-Routen verarbeitet.
+
+## Cloudflare-Seiten {#cloudflare-pages}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "cloudflare_pages" },
+});
+```
+
+## AWS Lambda {#aws-lambda}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "aws_lambda" },
+});
+```
+
+## Deno-Bereitstellung {#deno-deploy}
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  nitro: { preset: "deno_deploy" },
+});
+```
+
+## Umgebungsvariablen {#environment-variables}
+
+### Build/Laufzeit {#env-runtime}
+
+| Variable                    | Beschreibung                                                                                                                                                     |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`                      | Server-Port (nur Node.js)                                                                                                                                        |
+| `NITRO_PRESET`              | Build-Voreinstellung zum Build-Zeitpunkt überschreiben                                                                                                           |
+| `APP_BASE_PATH`             | Mounten Sie die App unter einem Präfix (z. B. `/mail`). Automatisch eingestellt durch `npx @agent-native/core@latest deploy`; Für Standalone deaktiviert lassen. |
+| `AGENT_PROD_CODE_EXECUTION` | Optionaler Produktionscode-Ausführungsmodus: `off` (Standard), `sandboxed` oder `trusted`. Siehe [Production Code Execution](#production-code-execution).        |
+
+Datenbankverbindungsvariablen (`DATABASE_URL`, `DATABASE_AUTH_TOKEN`, pro App `<APP_NAME>_DATABASE_URL`) leben in [Database](/docs/database#production).
+
+### In der Produktion erforderlich {#env-required-prod}
+
+Diese müssen festgelegt werden, bevor eine App zu einer echten Produktbereitstellung hochgestuft wird. Fehlende Werte führen entweder zu einem Fail-Closing (das Framework verweigert den Start/verweigert die Bearbeitung von Anfragen) oder sie fallen mit einer lauten Warnung auf ein schwächeres Verhalten zurück.
+
+| Variable                 | Beschreibung                                                                                                                                                                                                                                                                                                                                 |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`     | 32+ Zeichen zufällige Zeichenfolge. Signiert Sitzungscookies. AND ist der Fallback HMAC für `OAUTH_STATE_SECRET` und `SECRETS_ENCRYPTION_KEY`. Unbedingt erforderlich: Das Framework löst beim Start aus, wenn es in der Produktion fehlt.                                                                                                   |
+| `BETTER_AUTH_URL`        | Öffentlicher Ursprung dieser App (z. B. `https://mail.example.com`). Wird für die Cookie-Domäne und die OAuth-Weiterleitungskonstruktion verwendet.                                                                                                                                                                                          |
+| `ANTHROPIC_API_KEY`      | API-Schlüssel für den eingebetteten Produktionsagenten. **Bei mandantenfähigen Bereitstellungen** weigert sich das Framework, darauf zurückzugreifen, wenn der Benutzer keinen benutzerspezifischen Schlüssel hat – Bring-Your-Own-Key ist erforderlich. Selbstgehostete Einzelmandanteninstallationen verwenden ihn als globalen Schlüssel. |
+| `OAUTH_STATE_SECRET`     | Dedizierte HMAC-Taste für OAuth-Staatsumschläge (Google, Atlassian, Zoom). Fällt auf `BETTER_AUTH_SECRET` zurück, wenn es nicht festgelegt ist, es wird jedoch ein dedizierter Wert empfohlen, damit durch Drehen eines Werts der andere nicht ungültig wird. Generieren über `openssl rand -hex 32`.                                        |
+| `A2A_SECRET`             | Gemeinsames HMAC für App-übergreifendes A2A JSON-RPC. Ohne sie geben jeder A2A-Endpunkt und der `/_agent-native/integrations/process-task`-Self-Fire-Endpunkt 503 in der Produktion zurück.                                                                                                                                                  |
+| `SECRETS_ENCRYPTION_KEY` | AES-256-GCM Schlüssel für den Tresor für verschlüsselte ruhende Geheimnisse. Fällt auf `BETTER_AUTH_SECRET` zurück. Hard-Fails in der Produktion, wenn beide nicht festgelegt sind.                                                                                                                                                          |
+
+### Authentifizierung und Identität {#env-auth}
+
+OAuth-Anbieteranmeldeinformationen (Google, GitHub), statische MCP-Bearer-Fallbacks (`ACCESS_TOKEN`/`ACCESS_TOKENS`) und E-Mail-Verifizierungsumschaltungen sind in [Authentication](/docs/authentication) dokumentiert. Legen Sie sie dort entsprechend dem von Ihnen gewählten Authentifizierungsmodus fest.
+
+### Eingehender Webhooks {#env-webhooks}
+
+Jede Messaging-Integration erfordert ein eigenes Signaturgeheimnis in der Produktion (Handler werden bei gefälschten Anfragen nicht geschlossen, wenn das Geheimnis fehlt). Die Variablen pro Integration sind in [Messaging](/docs/messaging) und [Security](/docs/security) aufgeführt. Nur für die lokale Entwicklung entscheidet sich `AGENT_NATIVE_ALLOW_UNVERIFIED_WEBHOOKS=1` wieder für „Warnen und Akzeptieren“ – legen Sie es niemals in Produkt fest.
+
+### Sicherheitskonfiguration (Opt-in) {#security-config}
+
+Die Standardeinstellungen sind streng. Eine Handvoll Opt-in-Flags lockern das Verhalten (Debug-Stack-Traces, nicht verifiziertes webhooks, arbeitsbereichsbezogener Schlüssel-Fallback, der MCP-Hub-Multi-Org-Switch, Laufzeit-Env-Var-Schreibvorgänge). Sie sind mit ihren Sicherheitskompromissen in [Security](/docs/security) dokumentiert. Legen Sie sie nicht fest, es sei denn, Sie möchten ausdrücklich den entspannten Weg.
+
+### Workspace .env-Vererbung {#env-inheritance}
+
+Innerhalb eines Arbeitsbereichs wird der Root-`.env` automatisch in jede App geladen, sodass gemeinsame Schlüssel wie `ANTHROPIC_API_KEY`, `A2A_SECRET`, `BETTER_AUTH_SECRET` und `OAUTH_STATE_SECRET` nur einmal festgelegt werden müssen. `apps/<name>/.env` pro App gewinnt bei Konflikten.
+
+### Generieren starker Geheimnisse {#env-generate-secrets}
+
+Generieren Sie für jedes Geheimnis, das mit „32+ char random“ gekennzeichnet ist (`BETTER_AUTH_SECRET`, `OAUTH_STATE_SECRET`, `A2A_SECRET`, `SECRETS_ENCRYPTION_KEY`), neue Werte mit:
+
+```bash
+openssl rand -hex 32
+```
+
+Rotieren Sie sie, indem Sie die Umgebungsvariable auf jeder Instanz ersetzen und erneut bereitstellen. Sitzungen/OAuth-Statusumschläge, die unter dem alten Schlüssel signiert wurden, werden ungültig, sodass Benutzer sich möglicherweise erneut anmelden müssen.
+
+## Production Agent Tools {#production-agent-tools}
+
+Produktionsagenten erhalten die registrierten actions der App sowie Framework-Tools von
+das Agenten-Chat-Plugin. Datenbankschreibvorgänge sind standardmäßig aktiviert, da Raw-DB
+Tools sind auf den authentifizierten Benutzer/die authentifizierte Organisation beschränkt, aber App-Besitzer können den Bereich einschränken
+Oberfläche, wenn eine Bereitstellung eigenwilliger sein sollte:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  // Default: "write" (also true)
+  databaseTools: "read", // "write" | "read" | "off"
+  extensionTools: false,
+});
+```
+
+- `databaseTools: "write"` – Standard. Register `db-schema`, `db-query`,
+  `db-exec` und `db-patch`. Schreibvorgänge sind auf den aktuellen Benutzer/die aktuelle Organisation und
+  Schemaänderungen werden blockiert.
+- `databaseTools: "read"` – registriert nur `db-schema` und `db-query`; Agenten
+  Daten mit SQL prüfen, für Schreibvorgänge muss jedoch die typisierte App actions verwendet werden.
+- `databaseTools: "off"` oder `false` – entfernt Rohdatenbank-Tools aus
+  Agentenoberfläche, sodass die actions der App der einzige Datenzugriffspfad sind.
+- `extensionTools: false` – entfernt Framework-Erweiterungsverwaltung actions und
+  schnelle Anleitung (`create-extension`, `update-extension` usw.) für Apps, die
+  Sie möchten nicht, dass der Agent Sandbox-Mini-Apps erstellt.
+
+## Produktionscode-Ausführung {#production-code-execution}
+
+Produktionsagenten werden standardmäßig ohne Codeausführungstools ausgeführt. Sie können die App actions, Datenbanktools, MCP-Tools, Browser-/Sitzungstools und andere registrierte Framework-Tools aufrufen, erhalten jedoch keinen Shell- oder Dateisystemzugriff.
+
+Knotenkompatible Bereitstellungen können die Ausführung von Produktionscode über das Agent-Chat-Plugin oder eine Umgebungsüberschreibung aktivieren:
+
+```ts
+// server/plugins/agent-chat.ts
+export default createAgentChatPlugin({
+  codeExecution: { production: "sandboxed" },
+});
+```
+
+Die verfügbaren Modi sind:
+
+- `off` – die Standardeinstellung. In der Produktion sind keine Codeausführungstools registriert.
+- `sandboxed` – registriert `run-code`, einen isolierten Node.js JavaScript-Runner mit einer bereinigten Umgebung, einem neuen temporären Verzeichnis, Ausgabe-/Zeitlimits und einer Localhost-Brücke für registrierte Tools auf der Zulassungsliste wie `provider-api-request`, `provider-api-docs`, `provider-api-catalog`, `web-request` und die von verwendete ressourcengestützte Workspace-Dateibrücke `workspaceRead` / `workspaceWrite`.
+- `trusted` – registriert `run-code` sowie die vollständige Codierungstool-Registrierung (`bash`, `read`, `edit`, `write`). Verwenden Sie dies nur für Einzelmandanten- oder betreibergesteuerte Bereitstellungen, bei denen ein vollständiger Shell-Zugriff auf den Host beabsichtigt ist.
+
+Legen Sie `AGENT_PROD_CODE_EXECUTION=sandboxed` oder `AGENT_PROD_CODE_EXECUTION=trusted` fest, um die Plugin-Option für eine bestimmte Bereitstellung ohne Codeänderung zu überschreiben. `AGENT_PROD_CODE_EXECUTION=off` erzwingt die Codeausführung, auch wenn die Plugin-Option dies aktiviert.
+
+Die `run-code`-Sandbox ist eine Isolierung auf Prozessebene, kein Betriebssystemcontainer. Es entfernt App-Geheimnisse aus der Umgebung des untergeordneten Prozesses und verwendet das Node-Berechtigungsmodell, sofern verfügbar, aber das ausgehende Netzwerk wird nicht vom Node selbst blockiert; Authentifizierte Aufrufe sollten über die Bridge-Helper erfolgen, die das Tool bereitstellt.
+
+## UI in der Produktion aktualisieren {#updating-ui-in-production}
+
+Eine der Kernfunktionen von Agent-Native besteht darin, dass der Agent den Quellcode Ihrer App ändern kann – Komponenten, Routen, Stile usw. Während der lokalen Entwicklung funktioniert dies reibungslos, da der Agent vollen Zugriff auf das Dateisystem hat.
+
+In einer standardmäßigen Produktionsbereitstellung mit weggelassenem [production code execution](#production-code-execution) hat der Agent Zugriff auf App-Tools (actions, Datenbank, MCP), aber nicht auf das Dateisystem. Das bedeutet, dass der Agent Daten lesen und schreiben, actions ausführen und mit externen Diensten interagieren kann – aber er kann Ihre React-Komponenten nicht bearbeiten oder neue Routen auf einer bereitgestellten Instanz hinzufügen.
+
+### Builder.io: Visuelle Bearbeitung in der Produktion {#builderio}
+
+[Builder.io](https://www.builder.io) löst dieses Problem durch die Bereitstellung einer verwalteten Cloud-Umgebung, in der der Agent die Möglichkeit behält, den UI Ihrer App in der Produktion zu ändern. Verbinden Sie Ihr Repo mit Builder.io und fordern Sie direkt UI-Änderungen an – keine erneute Bereitstellung erforderlich.
+
+**So funktioniert es:**
+
+1. Verbinden Sie Ihr agentennatives Repo mit Builder.io
+2. Builder.io bietet einen Cloud-Frame mit dem Agenten, visueller Bearbeitung und Zusammenarbeit in Echtzeit
+3. Fordern Sie den Agenten auf, UI Änderungen vorzunehmen – er bearbeitet Ihre Komponenten, Routen und Stile live
+4. Änderungen werden in Ihr Repo übernommen
+
+Weitere Informationen zum eingebetteten Agent-Panel im Vergleich zu Cloud-Frame-Optionen finden Sie unter [Frames](/docs/frames).
+
+## Mehrinstanzbereitstellungen {#multi-instance}
+
+Agent-native Apps speichern den gesamten Status in SQL über Drizzle und synchronisieren den UI über [polling](/docs/key-concepts#polling-sync) mit der Datenbank – kein Dateisystemstatus, keine Sticky Sessions, keine In-Memory-Caches. Das bedeutet, dass Bereitstellungen mit mehreren Instanzen und serverlosen Bereitstellungen sofort funktionieren: Richten Sie jede Instanz auf denselben `DATABASE_URL` und sie konvergieren automatisch. Siehe [Key Concepts — Data in SQL](/docs/key-concepts#data-in-sql) und [Portability](/docs/key-concepts#hosting-agnostic).