@agent-native/core 0.76.5 → 0.76.6

package/corpus/core/docs/content/locales/de-DE/authentication.md

@@ -0,0 +1,332 @@
+---
+title: "Authentifizierung"
+description: "Bessere Auth-Integration mit E-Mail/Passwort, sozialen Anbietern, Organisationen und MCP-Inhaber-Anmeldeinformationen."
+---
+
+# Authentifizierung
+
+Agent-native Apps verwenden [Better Auth](https://better-auth.com) für die Authentifizierung mit einem Account-First-Design. Benutzer erstellen beim ersten Besuch ein Konto und erhalten vom ersten Tag an eine echte Identität.
+
+## Übersicht {#overview}
+
+Auth wird automatisch über `autoMountAuth(app)` im Authentifizierungsserver-Plugin konfiguriert. Es gibt drei Modi:
+
+- **Standard:** Bessere Authentifizierung mit E-Mail/Passwort + sozialen Anbietern. Onboarding-Seite wird beim ersten Besuch angezeigt.
+- **Remote MCP OAuth:** Standard OAuth 2.1 für MCP-Hosts wie Claude-Code und ChatGPT-Anschlüsse.
+- **Benutzerdefiniert:** Bringen Sie Ihre eigene Authentifizierung über den `getSession`-Rückruf mit.
+
+```an-diagram title="Three ways in, one session" summary="Browser visitors, programmatic MCP clients, and custom providers all resolve to the same AuthSession that downstream scoping reads."
+{
+  "html": "<div class=\"auth-modes\"><div class=\"diagram-col\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Default</span><strong>Better Auth</strong><small class=\"diagram-muted\">email/password &middot; Google &middot; GitHub</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Remote MCP OAuth</span><strong>OAuth 2.1 + PKCE</strong><small class=\"diagram-muted\">Claude Code, ChatGPT connectors</small></div><div class=\"diagram-card\"><span class=\"diagram-pill\">Custom</span><strong>getSession callback</strong><small class=\"diagram-muted\">Clerk &middot; Auth0 &middot; Firebase</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill ok\">AuthSession</span><small class=\"diagram-muted\">email &middot; orgId &middot; orgRole</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Request context &amp; data scoping</div></div>",
+  "css": ".auth-modes{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.auth-modes .diagram-col{display:flex;flex-direction:column;gap:10px}.auth-modes .diagram-card{display:flex;flex-direction:column;gap:4px;padding:10px 12px}.auth-modes .diagram-arrow{font-size:22px;line-height:1}.auth-modes .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+Der Browser-Flow ist überall derselbe. Besserer Auth-Flow – es gibt **keine Umgehung der Entwicklerauthentifizierung** und `getSession()` greift nie auf einen `local@localhost`-Sentinel zurück. Was sich zwischen den Umgebungen ändert, ist die Reibung bei der Anmeldung, nicht die Login-Wall:
+
+| Umgebung               | Verhalten beim ersten Laden                                                                             | E-Mail-Bestätigung                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Lokaler Entwickler** | Erstellt automatisch ein Wegwerf-Entwicklerkonto und meldet Sie an (keine Login-Wall)                   | Standardmäßig übersprungen (und wenn kein E-Mail-Anbieter vorhanden ist) |
+| **QA/Vorschau**        | Normale Anmeldung, aber die Überprüfung kann übersprungen werden, damit Tester nicht auf E-Mails warten | Mit `AUTH_SKIP_EMAIL_VERIFICATION=1` überspringen                        |
+| **Produktion**         | Normale Better Auth-Anmeldung/Anmeldung                                                                 | Erforderlich (wenn ein E-Mail-Anbieter konfiguriert ist)                 |
+
+Ein paar Flags optimieren dies; Ausführliche Informationen finden Sie in der Tabelle [Environment Variables](#environment-variables):
+
+- `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT=1` – Verwenden Sie die normale Anmeldeseite im lokalen Entwickler anstelle des automatischen Entwicklerkontos.
+- `AUTH_DISABLED=true` – Überspringen Sie die Anmeldung/Registrierung vollständig und führen Sie jede Anfrage als ein gemeinsamer Benutzer aus (nur lokale Entwicklung/Vorschauen/Demos, niemals Produktion mit echten Benutzern).
+- `AUTH_MODE=local` – betrifft nur die CLI/Agent-Identität (als die der Entwicklerbenutzer `pnpm action` ausgeführt wird); Es ist **keine** Umgehung der Browser-Anmeldung.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "`AUTH_DISABLED=true` runs **every request as one shared user**. Use it only for local dev, previews, or demos — never in production with real users, where it would expose all data to anyone."
+}
+```
+
+## Bessere Authentifizierung (Standard) {#better-auth}
+
+Standardmäßig unterstützt Better Auth die Authentifizierung. Es bietet:
+
+- E-Mail-/Passwort-Registrierung und Anmeldung
+- Soziale Anbieter (Google, GitHub und über 35 andere)
+- Organisationen mit Rollen und Einladungen
+- JWT-Tokens für API- und A2A-Zugriff
+- Bearer-Token-Unterstützung für programmatische Clients
+
+Bessere Auth-Routen werden unter `/_agent-native/auth/ba/*` bereitgestellt. Das Framework bietet auch abwärtskompatible Endpunkte:
+
+- `GET /_agent-native/auth/session` – aktuelle Sitzung abrufen
+- `POST /_agent-native/auth/login` – E-Mail-/Passwort-Anmeldung
+- `POST /_agent-native/auth/register` – Konto erstellen
+- `POST /_agent-native/auth/logout` – Abmelden
+
+## Cookie-Bereiche {#cookie-realms}
+
+Der Bereich des Sitzungscookies folgt der Bereitstellungsform, also Apps, die eine teilen
+Datenbank-/Origin-Freigabeanmeldung und Apps, die nicht isoliert bleiben:
+
+| Bereitstellungsform                               | Cookie-Bereich                                                                                                                                  |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Eigenständige App                                 | Isoliert pro App durch Slug (`APP_NAME` oder Paketname im lokalen Entwickler); stabiles `an`-Präfix in der Produktion                           |
+| Arbeitsbereichsmodus (`AGENT_NATIVE_WORKSPACE=1`) | Ein gemeinsamer Bereich – Arbeitsbereichs-Apps teilen sich einen Ursprung und eine Datenbank                                                    |
+| Benutzerdefinierte Subdomains derselben Datenbank | Aktivieren Sie freigegebene Cookies mit `COOKIE_DOMAIN`                                                                                         |
+| Vom Erstanbieter gehostet (`*.agent-native.com`)  | Isolierter Namespace pro App (jede hat ihre eigene Authentifizierungsdatenbank); `COOKIE_DOMAIN=.agent-native.com` wird standardmäßig ignoriert |
+
+Von Erstanbietern gehostete Apps verfügen jeweils über eine eigene Authentifizierungsdatenbank, also App-übergreifende Anmeldung
+läuft über [Cross-App SSO](/docs/cross-app-sso) und nicht über ein gemeinsames Cookie.
+Diese Bereitstellungen müssen `APP_NAME` oder eine ableitbare App URL (`APP_URL`, `URL`,
+`DEPLOY_PRIME_URL` oder `DEPLOY_URL`); andernfalls schlägt der Start fehl, anstatt abzustürzen
+zurück zum gemeinsamen `an_session`-Namen. Absichtlich eine Authentifizierungsdatenbank gemeinsam nutzen
+über Subdomains hinweg `AGENT_NATIVE_SHARE_COOKIE_DOMAIN=1` daneben setzen
+`COOKIE_DOMAIN`.
+
+## QA-Konten {#qa-accounts}
+
+Lokale Entwicklung und Tests überspringen standardmäßig die Überprüfung der Anmelde-E-Mail, damit Sie
+kann echte E-Mail-/Passwortkonten erstellen, ohne auf einen Posteingang warten zu müssen. Erzwingen
+Überprüfung lokal beim Testen dieses Ablaufs, legen Sie `AUTH_SKIP_EMAIL_VERIFICATION=0` fest.
+
+Für gehostete QA-Umgebungen, in denen Tester echte Konten benötigen, aber nicht warten sollten
+Stellen Sie bei der E-Mail-Zustellung Folgendes ein:
+
+```bash
+AUTH_SKIP_EMAIL_VERIFICATION=1
+```
+
+Wenn dieses Flag gesetzt ist, ist für die E-Mail-/Passwort-Anmeldung keine E-Mail erforderlich
+Bestätigung und die Anmeldebestätigungs-E-Mail wird nicht gesendet. Verwenden Sie es nur zur Qualitätssicherung
+oder Vorschauumgebungen und benennen Sie Testkonten mit einer `+qa`-Adresse
+(`name+qa@example.com`), damit sie leicht zu identifizieren sind.
+
+## Soziale Anbieter {#social-providers}
+
+Legen Sie Umgebungsvariablen fest, um die soziale Anmeldung zu ermöglichen. Better Auth erkennt sie automatisch:
+
+```bash
+# Google OAuth
+GOOGLE_SIGN_IN_CLIENT_ID=your-low-scope-sign-in-client-id
+GOOGLE_SIGN_IN_CLIENT_SECRET=your-low-scope-sign-in-client-secret
+
+# Backwards-compatible fallback, and provider OAuth credentials for templates
+# that connect to Google APIs such as Gmail or Calendar.
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-client-id
+GITHUB_CLIENT_SECRET=your-client-secret
+```
+
+Vorlagen, die `createGoogleAuthPlugin()` verwenden, zeigen eine Seite „Mit Google anmelden“ an. Der Google OAuth-Rückruf verarbeitet mobile Deep-Links für native Apps automatisch.
+
+Bevorzugen Sie `GOOGLE_SIGN_IN_CLIENT_ID` / `GOOGLE_SIGN_IN_CLIENT_SECRET` für Normal
+App-Anmeldung. Dieser Client sollte nur Identitätsbereiche anfordern. Behalten
+`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` für Produktintegrationen, die benötigt werden
+Google API-Bereiche oder als Legacy-Fallback, wenn eine Bereitstellung nicht aufgeteilt wurde
+noch. Apps im E-Mail- und Kalenderstil sollten daher die OAuth-Clients ihres eigenen Anbieters verwenden
+Einwilligungsbildschirme mit großem Umfang haben keinen Einfluss auf die allgemeine App-Anmeldung.
+
+### OAuth Zustandssignierung {#oauth-state-secret}
+
+Legen Sie `OAUTH_STATE_SECRET` in der Produktion auf einen zufälligen Wert von mehr als 32 Zeichen fest, sodass OAuth-Statusumschläge (Google, Atlassian, Zoom) mit einem dedizierten Schlüssel unabhängig von Geheimnissen Dritter HMAC-signiert werden. Die vollständigen Anforderungen und das Bedrohungsmodell finden Sie unter [Security — OAuth State Signing](/docs/security#oauth-state).
+
+## Organisationen {#organizations}
+
+Das Framework bietet ein integriertes Organisationssystem. Dies ist das `org/`-Modul des Frameworks – unterstützt durch die Tabellen `organizations` und `org_members` – und nicht das Organisations-Plugin von Better Auth, das absichtlich nicht registriert ist. Jede App unterstützt:
+
+- Organisationen erstellen
+- Einladen von Mitgliedern mit Rollen (`owner`, `admin`, `member`)
+- Aktive Organisation wechseln
+- Datenbereich pro Organisation über `org_id`-Spalten
+
+Die aktive Organisation wird in der Sitzung als `session.orgId` verfolgt und durch den Wechsel der Organisation ändern sich die Daten, die dem Benutzer und Agent angezeigt werden. Das eigentliche Daten-Scoping erfolgt weiter unten im Stapel – siehe [Security & Data Scoping](/docs/security#data-scoping) für die vollständige `session.orgId → AGENT_ORG_ID → SQL`-Pipeline und die Zugriffswächter. Die [Multi-Tenancy](/docs/multi-tenancy)-Dokumente decken die Organisationsverwaltungsoberfläche ab.
+
+## Statische MCP-Inhaber-Token {#access-tokens}
+
+`ACCESS_TOKEN` und `ACCESS_TOKENS` sind keine Browser-Authentifizierung und machen eine App nicht privat. Sie bleiben nur als statische Trägeranmeldeinformationen für MCP/connect-Clients erhalten, die den OAuth-Flow nicht verwenden können.
+
+```bash
+# Single token
+ACCESS_TOKEN=my-secret-token
+
+# Multiple tokens
+ACCESS_TOKENS=token1,token2,token3
+```
+
+Durch die Konfiguration dieser Variablen wird niemals eine Token-Anmeldeseite für Besucher gerendert. Die Webanmeldung bleibt bei Better Auth oder Ihrem benutzerdefinierten `getSession`-Anbieter.
+
+## Remote MCP OAuth {#remote-mcp-oauth}
+
+Der MCP-Endpunkt jeder App kann als standardmäßig geschützte MCP-Ressource fungieren. OAuth-fähige Clients können nur mit dem Remote-MCP URL:
+
+```text
+https://mail.agent-native.com/_agent-native/mcp
+```
+
+Nicht authentifizierte MCP-Anfragen geben eine `WWW-Authenticate`-Herausforderung zurück, die auf `/.well-known/oauth-protected-resource` verweist. Der Client erkennt dann die OAuth-Metadaten der App, registriert dynamisch einen öffentlichen Client, öffnet die Autorisierungsseite der App und tauscht einen Autorisierungscode mit PKCE für Zugriffs- und Aktualisierungstoken aus.
+
+```an-diagram title="Remote MCP OAuth handshake" summary="An OAuth-capable client bootstraps from just the MCP URL — challenge, discovery, dynamic registration, then a PKCE code exchange."
+{
+  "html": "<div class=\"mcp-flow\"><div class=\"diagram-node\">1 &middot; MCP request<br><small class=\"diagram-muted\">no token</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node warn\">2 &middot; 401 challenge<br><small class=\"diagram-muted\">WWW-Authenticate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">3 &middot; Discover metadata<br><small class=\"diagram-muted\">.well-known</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">4 &middot; Register client<br><small class=\"diagram-muted\">dynamic, public</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">5 &middot; Authorize + PKCE<br><small class=\"diagram-muted\">code exchange</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node ok\">6 &middot; Access + refresh<br><small class=\"diagram-muted\">audience-bound</small></div></div>",
+  "css": ".mcp-flow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.mcp-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.mcp-flow .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+Zugriffstoken werden bei Festlegung mit `A2A_SECRET` signiert, andernfalls mit `BETTER_AUTH_SECRET`. Sie tragen die signierte Benutzer-/Organisationsidentität und die Bereiche `mcp:read`, `mcp:write` und/oder `mcp:apps` und sind an die genaue MCP-Ressource URL zielgruppengebunden. Aktualisierungstoken werden nur als Hashes gespeichert und rotieren bei jeder Aktualisierung. Toolaufrufe und MCP Apps-Ressourcenlesevorgänge werden im selben Anforderungskontext wie der angemeldete Benutzer ausgeführt. Der eingebettete MCP-App-Iframe empfängt niemals rohe OAuth-Token.
+
+`npx @agent-native/core@latest connect <url> --client claude-code` schreibt den nur für URL gültigen MCP-Eintrag für diesen Standardablauf. Für Clients, die kein Remote-MCP OAuth ausführen können, verwenden Sie die Seite „Verbinden“ oder den `npx @agent-native/core@latest connect --token <token>`-Fallback, um einen expliziten Bearer-Token-Eintrag zu schreiben.
+
+## Bringen Sie Ihre eigene Authentifizierung mit {#byoa}
+
+Übergeben Sie einen benutzerdefinierten `getSession`-Rückruf, um einen beliebigen Authentifizierungsanbieter (Clerk, Auth0, Firebase usw.) zu verwenden:
+
+```ts
+// server/plugins/auth.ts
+import { createAuthPlugin } from "@agent-native/core/server";
+
+export default createAuthPlugin({
+  getSession: async (event) => {
+    // Your custom auth logic here
+    const session = await myAuthProvider.verify(event);
+    if (!session) return null;
+    return { email: session.email };
+  },
+  publicPaths: ["/api/webhooks"],
+});
+```
+
+## Öffentliche Workspace-Apps {#public-workspace-apps}
+
+Workspace-Apps sind standardmäßig intern. Damit anonyme Besucher eine öffentliche laden können
+Site, während die Verwaltungsseiten hinter der Authentifizierung bleiben, deklarieren Sie den Routenzugriff in
+`apps/<id>/package.json`:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin"]
+    }
+  }
+}
+```
+
+Behalten Sie für die umgekehrte Form die standardmäßige interne Zielgruppe bei und stellen Sie sie nur zur Verfügung
+spezifische öffentliche Seiten:
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "publicPaths": ["/", "/share"]
+    }
+  }
+}
+```
+
+`publicPaths` und `protectedPaths` verwenden Präfix-Matching, also auch `"/admin"`
+deckt `"/admin/users"` ab. Diese Einstellungen öffnen nur die Seitennavigation. Rahmen
+Routen (`/_agent-native/*`) und benutzerdefinierte API-Routen (`/api/*`) erfordern weiterhin eine Authentifizierung
+es sei denn, die App fügt diese Präfixe explizit hinzu
+`createAuthPlugin({ publicPaths: [...] })`.
+
+## Sitzung API {#session-api}
+
+Das von `getSession(event)` zurückgegebene Sitzungsobjekt hat diese Form:
+
+```ts
+interface AuthSession {
+  email: string; // User's email (primary identifier)
+  userId?: string; // Better Auth user ID
+  token?: string; // Session token
+  name?: string; // Display name from the auth provider, when available
+  image?: string; // Profile image from the auth provider, when available
+  orgId?: string; // Active organization ID
+  orgRole?: string; // Role in active org (owner/admin/member)
+}
+```
+
+Verwenden Sie auf dem Client den Hook `useSession()`:
+
+```ts
+import { useSession } from "@agent-native/core/client";
+
+function MyComponent() {
+  const { session, isLoading } = useSession();
+  if (isLoading) return <p>Loading...</p>;
+  if (!session) return <p>Not signed in</p>;
+  return <p>Hello, {session.email}</p>;
+}
+```
+
+## Anmelden mit Return URL {#sign-in-return-url}
+
+Vorlagen mit **öffentlichen Seiten** (Freigabelinks, Einbettungen, Marketingseiten) benötigen häufig einen In-Page-CTA, der anonyme Betrachter auffordert, sich anzumelden, und sie zu der Seite zurückführt, auf der sie sich befanden. Das Framework bietet hierfür einen einzigen Einstiegspunkt:
+
+```
+/_agent-native/sign-in?return=<same-origin-path>
+```
+
+Wenn ein anonymer Betrachter auf dieses URL trifft, wird die Anmeldeseite des Frameworks bereitgestellt. Nach einer erfolgreichen Anmeldung (beliebiger Ablauf – Token, E-Mail/Passwort oder Google OAuth) wird der Betrachter zu `return` weitergeleitet.
+
+Der Parameter `return` wird als **Pfad gleichen Ursprungs** validiert. Netzwerkpfadreferenzen (`//evil.com/...`), absolute URLs, `data:`/`javascript:`-Schemata und eingebettete Steuerzeichen greifen alle auf `/` zurück. Der validierte Pfad wird vom URL-Parser rekonstruiert und nicht von der Eingabe zurückgegeben.
+
+**Von einer React-Komponente:**
+
+```tsx
+import { Button } from "@/components/ui/button";
+
+function SignInCta() {
+  const onClick = () => {
+    const ret = window.location.pathname + window.location.search;
+    window.location.href =
+      "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+  };
+  return <Button onClick={onClick}>Sign in</Button>;
+}
+```
+
+### Private Pfade mit Lesezeichen versehen
+
+Wenn ein anonymer Benutzer direkt zu einem privaten Pfad wie `/dashboard` navigiert, stellt das Framework bereits die Anmeldeseite unter diesem URL bereit – nach erfolgreicher Anmeldung wird die Seite neu geladen und der Benutzer landet auf `/dashboard`. Keine besondere Handhabung erforderlich; Dies funktioniert für Token, E-Mail/Passwort, **und** Google OAuth.
+
+### Hinter den Kulissen: Google OAuth
+
+Beide Flüsse (der explizite `/_agent-native/sign-in`-Einstiegspunkt und der Fall des mit Lesezeichen versehenen Pfads) führen den zurückgegebenen URL durch den OAuth-Status. Der Status ist HMAC-signiert und kann daher während der Übertragung nicht gefälscht werden. Beim Rückruf wird der zurückgegebene URL vor der Umleitung erneut als Same-Origin validiert – ein durchgesickerter Signaturschlüssel kann also immer noch nicht in ein Open-Redirect-Orakel umgewandelt werden.
+
+Wenn Ihre Vorlage `/_agent-native/google/auth-url` direkt umschließt (z. B. E-Mail- und Kalendervorlagen, um den Umfang zu erweitern), akzeptieren Sie eine `?return=<path>`-Abfrage und leiten Sie sie über die Optionsobjektform von `encodeOAuthState` weiter:
+
+```ts
+const returnUrl = getQuery(event).return;
+const state = encodeOAuthState({
+  redirectUri,
+  desktop,
+  returnUrl: typeof returnUrl === "string" ? returnUrl : undefined,
+});
+```
+
+Die Standardroute `/_agent-native/google/auth-url` führt dies automatisch aus – überschreibt es nur, wenn Ihre Vorlage eine benutzerdefinierte OAuth-Behandlung erfordert.
+
+## Umgebungsvariablen {#environment-variables}
+
+| Variable                                | Zweck                                                                                                                                                                                                                        |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET`                    | Signaturschlüssel für Better Auth (automatisch generiert, wenn nicht festgelegt)                                                                                                                                             |
+| `AUTH_SKIP_EMAIL_VERIFICATION`          | In QA-/Vorschauumgebungen auf `1` setzen, damit E-Mail-/Passwort-Anmeldungen ohne Überprüfung durchgeführt werden können. Lokale Entwicklung/Test überspringt standardmäßig                                                  |
+| `AUTH_DISABLED`                         | Auf `true` oder `1` einstellen, um Anmeldung/Registrierung zu überspringen; Alle Anfragen werden von einem gemeinsamen Benutzer ausgeführt (nur lokale Entwicklung/Vorschau – nicht für die Produktion mit echten Benutzern) |
+| `AGENT_NATIVE_DISABLE_AUTO_DEV_ACCOUNT` | Auf `1` einstellen, um die automatische Anmeldung von Localhost in einer neuen Entwicklungsdatenbank zu deaktivieren                                                                                                         |
+| `AUTH_MODE`                             | `local` löst nur die CLI/Agent-Identität auf (unter der der Entwicklerbenutzer `pnpm action` ausgeführt wird); niemals eine Browser-Anmeldeumgehung                                                                          |
+| `COOKIE_DOMAIN`                         | Aktivieren Sie gemeinsam genutzte Sitzungscookies für Subdomains derselben Datenbank (siehe [Cookie Realms](#cookie-realms))                                                                                                 |
+| `AGENT_NATIVE_WORKSPACE`                | `1` wird im Workspace-Modus ausgeführt – ein gemeinsamer Sitzungsbereich für alle Workspace-Apps                                                                                                                             |
+| `AGENT_NATIVE_SHARE_COOKIE_DOMAIN`      | Mit `COOKIE_DOMAIN` festlegen, um eine Authentifizierungsdatenbank für alle Erstanbieter-Subdomänen gemeinsam zu nutzen                                                                                                      |
+| `OAUTH_STATE_SECRET`                    | Dedizierter HMAC-Schlüssel für OAuth-Statusumschläge (siehe [Security — OAuth State Signing](/docs/security#oauth-state))                                                                                                    |
+| `GOOGLE_SIGN_IN_CLIENT_ID`              | Bevorzugte Low-Scope-Client-ID von Google OAuth für die App-Anmeldung                                                                                                                                                        |
+| `GOOGLE_SIGN_IN_CLIENT_SECRET`          | Bevorzugtes Google OAuth-Geheimnis mit niedrigem Gültigkeitsbereich für die App-Anmeldung                                                                                                                                    |
+| `GOOGLE_CLIENT_ID`                      | Legacy-Google-Login-Fallback und Anbieter-OAuth-Client-ID für Google API-Integrationen                                                                                                                                       |
+| `GOOGLE_CLIENT_SECRET`                  | Alter Google-Login-Fallback und Anbieter-OAuth-Geheimnis für Google API-Integrationen                                                                                                                                        |
+| `GITHUB_CLIENT_ID`                      | GitHub OAuth aktivieren                                                                                                                                                                                                      |
+| `GITHUB_CLIENT_SECRET`                  | GitHub OAuth Geheimnis                                                                                                                                                                                                       |
+| `ACCESS_TOKEN`                          | Statischer Bearer-Fallback für MCP/connect-Clients; keine Browser-Authentifizierung                                                                                                                                          |
+| `ACCESS_TOKENS`                         | Durch Kommas getrennte statische Bearer-Fallbacks für MCP/connect-Clients; keine Browser-Authentifizierung                                                                                                                   |
+| `A2A_SECRET`                            | Gemeinsames Geheimnis für die JWT-signierte A2A-Cross-App-Identitätsüberprüfung und, falls vorhanden, MCP OAuth-Zugriffstoken-Signierung                                                                                     |

package/corpus/core/docs/content/locales/de-DE/automations.md

@@ -0,0 +1,268 @@
+---
+title: "Automatisierungen"
+description: "Ereignisausgelöste und geplante Automatisierungen mit Bedingungen in natürlicher Sprache"
+---
+
+# Automatisierungen
+
+Eine **Automatisierung** ist eine Regel: _Wenn X passiert, mache Y_ – beschrieben in natürlicher Sprache. Der Agent führt die Anweisungen aus, sodass Automatisierungen Zugriff auf alle Aktionen, Tools und MCP-Server haben, die der Agent in einem interaktiven Chat verwenden kann.
+
+Automatisierungen erweitern [recurring jobs](/docs/recurring-jobs) mit **Ereignisauslösern**, **Bedingungen in natürlicher Sprache** und **ausgehendem HTTP** über das `web-request`-Tool. Sie verwenden dasselbe `jobs/<name>.md`-Dateiformat, denselben Speicher und denselben „Drei-Wege-erstellen“-Workflow wie wiederkehrende Aufträge – siehe [Recurring Jobs](/docs/recurring-jobs#job-file) für das gemeinsame Format. Auf dieser Seite werden nur die Neuerungen bei ereignisgesteuerten Automatisierungen behandelt.
+
+```an-diagram title="When X happens, do Y" summary="An event fires on the bus, an optional natural-language condition gates it, and the agent runs the automation body with full tool access."
+{
+  "html": "<div class=\"auto-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Event</span><small class=\"diagram-muted\"><code>calendar.booking.created</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Condition</span><small class=\"diagram-muted\">Haiku checks: &ldquo;email ends with @builder.io&rdquo;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">Agent runs the body</span><small class=\"diagram-muted\">actions &middot; web-request &middot; MCP &middot; sub-agents</small></div></div>",
+  "css": ".auto-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.auto-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.auto-flow .diagram-arrow{font-size:22px}"
+}
+```
+
+## Zwei Triggertypen {#trigger-types}
+
+| Typ        | Wird ausgelöst, wenn                                                 | Schlüsselfeld     |
+| ---------- | -------------------------------------------------------------------- | ----------------- |
+| `schedule` | Ein Cron-Ausdruck stimmt überein (wie bei wiederkehrenden Jobs)      | `schedule` (cron) |
+| `event`    | Ein passendes Ereignis wird auf dem Framework-Ereignisbus ausgegeben | `event` (Name)    |
+
+Ereignisauslöser können einen `condition` enthalten – eine Zeichenfolge in natürlicher Sprache, die von Haiku vor dem Versand anhand der Ereignisnutzlast ausgewertet wird. Wenn die Bedingung nicht zutrifft, wird die Automatisierung stillschweigend übersprungen.
+
+## Automatisierungen erstellen {#creating}
+
+### Indem Sie den Agenten fragen
+
+> „Wenn jemand ein Meeting mit einer @builder.io-E-Mail bucht, senden Sie mir eine Nachricht in Slack.“
+
+Der Agent erkennt verfügbare Ereignisse, bestätigt den Plan und schreibt die Automatisierung für Sie.
+
+### Aus den Einstellungen UI
+
+Automatisierungen werden im Einstellungsfeld angezeigt. Benutzer können sie dort anzeigen, aktivieren/deaktivieren und löschen.
+
+Der dritte Pfad – das manuelle Schreiben der `jobs/<name>.md`-Datei über `resourcePut` – funktioniert genauso wie für [recurring jobs](/docs/recurring-jobs#creating). Für eine ereignisgesteuerte Automatisierung fügen Sie der folgenden Datei den Event-Trigger-Frontmatter hinzu. Ein durch ein Ereignis ausgelöster Job legt `schedule: ""` fest und liefert `triggerType: event`, einen `event`-Namen und optional einen `condition`:
+
+```an-annotated-code title="An event-triggered automation"
+{
+  "filename": "jobs/slack-on-builder-booking.md",
+  "language": "markdown",
+  "code": "---\nschedule: \"\"\nenabled: true\ntriggerType: event\nevent: calendar.booking.created\ncondition: \"attendee email ends with @builder.io\"\nmode: agentic\ndomain: calendar\nrunAs: creator\n---\nSend a Slack message to #sales with the booking details.\nUse the web-request tool to POST to ${keys.SLACK_WEBHOOK}.",
+  "annotations": [
+    { "lines": "2", "label": "No cron", "note": "Event triggers set `schedule` to `\"\"` — the cron field stays empty." },
+    { "lines": "4-5", "label": "The trigger", "note": "`triggerType: event` plus the `event` name subscribes this automation to the bus." },
+    { "lines": "6", "label": "Gate", "note": "An optional natural-language `condition`, evaluated by Haiku against the payload before dispatch." },
+    { "lines": "12", "label": "Server-side secret", "note": "`${keys.SLACK_WEBHOOK}` is resolved server-side — the raw value never enters the agent's context." }
+  ]
+}
+```
+
+## Automatisierungsthema {#frontmatter}
+
+Automatisierungen teilen sich jedes Feld im [recurring-jobs frontmatter table](/docs/recurring-jobs#frontmatter). Diese zusätzlichen Felder steuern Ereignisauslöser, Bedingungen und den Ausführungsmodus:
+
+| Feld          | Typ                              | Standard     | Beschreibung                                                                                                                                                                                                                |
+| ------------- | -------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `triggerType` | `"schedule"` \| `"event"`        | `"schedule"` | Wie die Automatisierung ausgelöst wird                                                                                                                                                                                      |
+| `event`       | Zeichenfolge                     | _(optional)_ | Ereignisname zum Abonnieren (nur Ereignisauslöser)                                                                                                                                                                          |
+| `condition`   | Zeichenfolge                     | _(optional)_ | Zustand in natürlicher Sprache wird vor dem Versand ausgewertet                                                                                                                                                             |
+| `mode`        | `"agentic"` \| `"deterministic"` | `"agentic"`  | Vollständige Agentenschleife. (`"deterministic"` ist reserviert, aber noch nicht implementiert – Automatisierungen, die es festlegen, werden übersprungen. Verwenden Sie `"agentic"` für alle aktuellen Automatisierungen.) |
+| `domain`      | Zeichenfolge                     | _(optional)_ | Gruppierungs-Tag (E-Mail, Kalender, Clips usw.)                                                                                                                                                                             |
+
+Für einen Ereignisauslöser ist `schedule` `""` (leer); Für einen Zeitplanauslöser trägt es den Cron-Ausdruck. Der Dispatcher schreibt außerdem dieselben verwalteten `lastRun`-/`lastStatus`-/`lastError`-Felder wie der Scheduler, plus einen `"skipped"`-Status, wenn eine Bedingung als „falsch“ ausgewertet wird.
+
+## Der Eventbus {#event-bus}
+
+Integrationen registrieren Ereignisse zur Modulladezeit. Der Bus validiert Nutzdaten anhand der [Standard Schema](https://standardschema.dev)-Definitionen und sendet sie an Abonnenten.
+
+### Eingebaute Ereignisse {#built-in-events}
+
+| Ereignis               | Quelle                                           |
+| ---------------------- | ------------------------------------------------ |
+| `test.event.fired`     | Handbuch / `manage-automations` action=fire-test |
+| `agent.turn.completed` | Agenten-Chat                                     |
+| `calendar.*`           | Kalenderintegration                              |
+| `clip.*`               | Clips-Integration                                |
+| `mail.*`               | Mail-Integration                                 |
+
+Rufen Sie `manage-automations` mit `action=list-events` vom Agenten auf, um alle registrierten Ereignisse mit Beschreibungen und Nutzlastschemata für die aktuelle Vorlage anzuzeigen.
+
+### Benutzerdefinierte Ereignisse ausgeben {#emitting-events}
+
+Registrieren Sie einen Ereignistyp in einem Server-Plugin und geben Sie ihn dann von actions oder Webhook-Handlern aus:
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register the event type (once, at module load)
+registerEvent({
+  name: "order.completed",
+  description: "A customer completed an order",
+  payloadSchema: z.object({
+    orderId: z.string(),
+    customerEmail: z.string(),
+    total: z.number(),
+  }),
+  example: {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit(
+  "order.completed",
+  {
+    orderId: "ord_123",
+    customerEmail: "jane@example.com",
+    total: 49.99,
+  },
+  { owner: "steve@builder.io" },
+);
+```
+
+Die `owner` in den Emissionsmetadatenbereichen, die Automatisierungen auslösen – nur Automatisierungen, die demselben Benutzer gehören (oder freigegebene Automatisierungen), werden ausgewertet.
+
+## Bedingungen {#conditions}
+
+Bedingungen sind Zeichenfolgen in natürlicher Sprache, die von Claude Haiku anhand der Ereignisnutzlast ausgewertet werden. Dies ist eine Ja/Nein-Klassifizierung, keine Generierungsaufgabe.
+
+- **Leere oder fehlende Bedingung** = unbedingt (wird immer ausgelöst).
+- Ergebnisse werden gespeichert (SHA-256 der Bedingung + Nutzlast) mit einem 5-Minuten-TTL- und 500-Eintrags-LRU-Cache.
+- Die Nutzlast wird vor dem Senden an Haiku auf 4000 Zeichen gekürzt.
+- Bei einem API-Fehler wird die Bedingung zu `false` ausgewertet (sichere Standardeinstellung – die Automatisierung wird übersprungen).
+
+Beispiele für Bedingungen:
+
+- `"attendee email ends with @builder.io"`
+- `"the order total is greater than $100"`
+- `"the message contains the word 'urgent'"`
+
+## Das Web-Anfrage-Tool {#web-request}
+
+Automatisierungen verwenden das `web-request`-Tool für ausgehende HTTP. Es unterstützt `${keys.NAME}`-Platzhalter im URL, in Headern und im Text:
+
+```
+POST to ${keys.SLACK_WEBHOOK}
+
+Headers: {"Authorization": "Bearer ${keys.API_TOKEN}"}
+
+Body: {"text": "New booking from ${attendeeEmail}"}
+```
+
+Platzhalter werden **serverseitig** aufgelöst, nachdem der Agent den Tool-Aufruf ausgibt – der rohe geheime Wert gelangt nie in den Kontext des Agenten.
+
+### Parameter {#web-request-params}
+
+| Parameter    | Typ          | Standard | Beschreibung                                               |
+| ------------ | ------------ | -------- | ---------------------------------------------------------- |
+| `url`        | Zeichenfolge | —        | Vollständig URL. Kann `${keys.NAME}`-Referenzen enthalten. |
+| `method`     | Zeichenfolge | `GET`    | HTTP-Methode (GET, POST, PUT, PATCH, DELETE, HEAD).        |
+| `headers`    | Zeichenfolge | `{}`     | JSON-Objekt der Header. Kann `${keys.NAME}` enthalten.     |
+| `body`       | Zeichenfolge | —        | Anforderungstext. Kann `${keys.NAME}` enthalten.           |
+| `timeout_ms` | Nummer       | 15000    | Timeout in Millisekunden (max. 30.000).                    |
+
+## Schlüssel {#keys}
+
+Schlüssel sind Ad-hoc-Geheimnisse, die von Benutzern oder dem Agenten zur Automatisierung erstellt werden (z. B. `SLACK_WEBHOOK`, `HUBSPOT_API_KEY`). Sie unterscheiden sich von registrierten Geheimnissen (`registerRequiredSecret`) dadurch, dass sie keine vorlagendefinierten Metadaten oder Onboarding-Schritte haben.
+
+- Erstellt über die Einstellungen UI oder `/_agent-native/secrets/adhoc` API.
+- Jeder Schlüssel kann eine **URL-Zulassungsliste** haben, die einschränkt, an welche Ursprünge der Schlüssel gesendet werden kann (Abgleich auf Ursprungsebene).
+- Der Rohwert wird niemals der KI angezeigt – im Kontext des Agenten werden nur `${keys.NAME}`-Platzhalter angezeigt.
+- Die Auflösung fällt vom Benutzerbereich auf den Arbeitsbereichsbereich zurück, sodass Benutzer gemeinsame Schlüssel überschreiben können.
+
+## Agent-Tools {#agent-tools}
+
+Der Zugriff auf alle Automatisierungsvorgänge erfolgt über ein einziges `manage-automations`-Tool mit einem `action`-Parameter:
+
+| Aktion        | Zweck                                                                                 |
+| ------------- | ------------------------------------------------------------------------------------- |
+| `list-events` | Erkennen Sie alle registrierten Ereignisse mit Beschreibungen und Nutzlastschemata    |
+| `list`        | Alle Automatisierungen mit Status auflisten; Nach Domäne filtern oder aktiviert       |
+| `define`      | Erstellen Sie eine neue Automatisierung (Name, Triggertyp, Ereignis, Bedingung, Text) |
+| `update`      | Aktualisieren Sie eine vorhandene Automatisierung (aktiviert, Bedingung, Text)        |
+| `delete`      | Eine Automatisierung löschen (immer zuerst mit dem Benutzer bestätigen)               |
+| `fire-test`   | Ein `test.event.fired`-Ereignis ausgeben, um Automatisierungen zu validieren          |
+
+Zusätzliches Tool: `web-request` – ausgehender HTTP mit `${keys.NAME}`-Ersetzung.
+
+## API-Endpunkte {#api}
+
+| Endpunkt                               | Methode | Beschreibung                                            |
+| -------------------------------------- | ------- | ------------------------------------------------------- |
+| `/_agent-native/automations`           | GET     | Alle Automatisierungen auflisten (geparst)              |
+| `/_agent-native/automations/fire-test` | POST    | Ein `test.event.fired`-Ereignis ausgeben                |
+| `/_agent-native/secrets/adhoc`         | GET     | Ad-hoc-Schlüssel auflisten (keine Werte)                |
+| `/_agent-native/secrets/adhoc`         | POST    | Erstellen oder aktualisieren Sie einen Ad-hoc-Schlüssel |
+| `/_agent-native/secrets/adhoc/:name`   | DELETE  | Einen Ad-hoc-Schlüssel löschen                          |
+
+```an-api title="Fire a test event"
+{
+  "method": "POST",
+  "path": "/_agent-native/automations/fire-test",
+  "summary": "Emit a test.event.fired event to validate event-triggered automations",
+  "description": "Confirm an automation's wiring and condition without waiting for a real provider event. Equivalent to the `manage-automations` action `fire-test`.",
+  "responses": [
+    { "status": "200", "description": "Event emitted; matching automations are dispatched through the normal condition + ownership path." }
+  ]
+}
+```
+
+## So funktioniert der Versand {#dispatch}
+
+```an-diagram title="The dispatch path" summary="From a fired event to a completed agent run, gated by ownership scope and the natural-language condition."
+{
+  "html": "<div class=\"disp\"><div class=\"diagram-box accent\">event fired on the bus</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">match</span><small class=\"diagram-muted\">load enabled automations subscribed to this event name</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">scope</span><small class=\"diagram-muted\">keep only those owned by the event's owner (or shared)</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">condition</span><small class=\"diagram-muted\">Haiku yes/no on the payload &mdash; false &rarr; <code>skipped</code></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card accent\"><span class=\"diagram-pill accent\">run</span><small class=\"diagram-muted\"><code>runAgentLoop</code> with body as prompt, payload as context, 5-min timeout</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">record</span><small class=\"diagram-muted\">write <code>lastRun</code> / <code>lastStatus</code> / <code>lastError</code></small></div></div>",
+  "css": ".disp{display:flex;flex-direction:column;gap:6px;max-width:540px}.disp .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.disp .diagram-box{align-self:flex-start}.disp .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+## Beispiel {#example}
+
+**Benutzer:** „Wenn jemand mit einer @builder.io-E-Mail bucht, senden Sie mir eine Nachricht in Slack.“
+
+**Agent-Flow:**
+
+1. Ruft `manage-automations` mit `action=list-events` auf – findet `calendar.booking.created`.
+2. Bestätigt den Plan mit dem Benutzer.
+3. Ruft `manage-automations` mit `action=define` auf:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @builder.io`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+4. Die Automatisierung wird als `jobs/slack-on-builder-booking.md` gespeichert und beginnt sofort mit dem Abhören.
+
+## Weitere Beispiele {#more-examples}
+
+### Über Webhook benachrichtigen, wenn ein Plan kommentiert wird
+
+Fragen Sie den Planagenten: _„Wenn jemand einen menschlichen Kommentar zu einem Plan hinzufügt, POST a
+Benachrichtigung an meinen Webhook."_
+
+```yaml
+---
+triggerType: event
+event: plan.commented
+condition: "resolutionTarget is human or resolutionTarget is null"
+mode: agentic
+domain: plan
+enabled: true
+---
+
+POST to ${keys.NOTIFY_WEBHOOK} with a JSON body:
+{"title": "<plan title>", "excerpt": "<comment excerpt>", "author": "<author email or null>", "url": "<app base url + path>"}
+```
+
+Legen Sie `NOTIFY_WEBHOOK` auf einen beliebigen HTTP-Endpunkt fest – einen eingehenden Slack-Webhook, einen generischen
+Benachrichtigungsdienst oder ein benutzerdefinierter Empfänger. Das `web-request`-Tool löst
+`${keys.NOTIFY_WEBHOOK}` serverseitig; Das rohe URL erscheint nie im Agenten
+Kontext. Siehe [Visual Plans — Events and notifications](/docs/template-plan#events)
+für die vollständige `plan.commented`-Nutzlastreferenz und alle vier Planereignisse.
+
+## Was kommt als nächstes?
+
+- [**Recurring Jobs**](/docs/recurring-jobs) – durch einen Zeitplan ausgelöste Automatisierungen verwenden denselben Planer wieder
+- [**Actions**](/docs/actions) – Automatisierungen können jede registrierte Aktion über die Agentenschleife aufrufen
+- [**Security**](/docs/security) – Eingabevalidierung und Geheimbehandlung
+- [**Visual Plans — Events**](/docs/template-plan#events) – Referenz für Planungsereignisse und Automatisierungsrezepte