@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/creating-templates.md

@@ -0,0 +1,411 @@
+---
+title: "Vorlagen erstellen"
+description: "So erstellen und veröffentlichen Sie Ihre eigenen agentennativen App-Vorlagen."
+---
+
+# Vorlagen erstellen
+
+Vorlagen sind vollständige, forkbare agentennative Apps, die einen echten Arbeitsablauf lösen. Die Erstanbieter-Vorlagen werden mit derselben Framework-Oberfläche erstellt, die Sie verwenden: React-Routen für UI, Drizzle SQL für Daten, actions für Vorgänge, Arbeitsbereichsressourcen für Agentenverhalten und Abfragesynchronisierung, damit der Agent und UI aufeinander abgestimmt bleiben.
+
+Eine gute Vorlage:
+
+- Löst einen Workflow durchgängig, mit nützlichen Seed-Daten oder einem Leerzustandsfluss.
+- Speichert den dauerhaften Zustand in SQL-Dateien, nicht in JSON-Dateien.
+- Definiert App-Vorgänge als `defineAction()` actions.
+- Macht Navigation und Auswahl durch den Anwendungsstatus möglich.
+- Liefert ein klares `AGENTS.md` und ein fokussiertes skills für nicht offensichtliche Arbeitsabläufe.
+- Registriert Onboarding-Schritte für erforderliche Anbieter und Geheimnisse.
+- Funktioniert als eigenständige App und als Teil eines Multi-App-Arbeitsbereichs.
+
+## Im Chat starten {#start-from-chat}
+
+Verwenden Sie die Chat-Vorlage, wenn Sie eine minimale App mit bereits vorhandener Framework-Verkabelung wünschen:
+
+```bash
+npx @agent-native/core@latest create my-template --template chat --standalone
+```
+
+Führen Sie für einen Arbeitsbereich mit mehreren Apps die Auswahl aus und schließen Sie Chat mit allen gewünschten Domänenvorlagen ein:
+
+```bash
+npx @agent-native/core@latest create my-platform
+```
+
+Chat bietet Ihnen Authentifizierung, dauerhafte Chat-Threads, von SQL unterstützte Ressourcen, Tools, Anwendungsstatus, actions und Abfragesynchronisierung. Sie fügen das Domänenmodell und das Produkt UI hinzu.
+
+Wenn Sie noch keine wiederverwendbare UI-Vorlage erstellen, verwenden Sie die kopflose Auffahrt in [Getting Started](/docs/getting-started#1-create-your-app): Definieren Sie eine Aktion, führen Sie sie mit `pnpm agent` aus und fügen Sie UI später hinzu, wenn der Workflow eine dauerhafte Oberfläche benötigt.
+
+## Projektstruktur {#project-structure}
+
+Jede Vorlage folgt dem gleichen allgemeinen Layout:
+
+```an-file-tree title="Template project layout"
+{
+  "title": "my-template/",
+  "entries": [
+    { "path": "app/", "note": "React frontend" },
+    { "path": "app/root.tsx", "note": "HTML shell and providers" },
+    { "path": "app/routes/", "note": "React Router file routes" },
+    { "path": "app/components/", "note": "Template UI" },
+    { "path": "app/hooks/", "note": "UI state and data hooks" },
+    { "path": "actions/", "note": "defineAction operations — the single source of truth" },
+    { "path": "server/db/schema.ts", "note": "Drizzle schema" },
+    { "path": "server/plugins/db.ts", "note": "additive migrations" },
+    { "path": "server/plugins/", "note": "startup integrations" },
+    { "path": "server/routes/api/", "note": "custom routes only when actions are not enough" },
+    { "path": "shared/types.ts", "note": "shared client/server types" },
+    { "path": ".agents/skills/", "note": "<skill>/SKILL.md — agent guidance for complex workflows" },
+    { "path": "AGENTS.md", "note": "template-specific agent instructions" },
+    { "path": "package.json" },
+    { "path": "react-router.config.ts" },
+    { "path": "vite.config.ts" }
+  ]
+}
+```
+
+Fügen Sie kein `data/`-Verzeichnis für den Anwendungsstatus hinzu. Dauerhafte App-Daten gehören in SQL, und UI liest sie über actions oder typisierte Server-Handler.
+
+Die vier Bereiche jeder Vorlage sind über eine gemeinsame Aktionsoberfläche und eine SQL-Datenbank miteinander verbunden – der Agent und der UI sind gleichberechtigte Partner bei denselben Vorgängen:
+
+```an-diagram title="How a template's four areas connect" summary="The UI and the agent both reach SQL through the same actions; application state and polling sync keep them aligned."
+{
+  "html": "<div class=\"diagram-tmpl\"><div class=\"diagram-col\"><div class=\"diagram-node\">React UI<br><small class=\"diagram-muted\">app/routes · components</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">AGENTS.md · skills</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">defineAction()</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>SQL via Drizzle<br><small class=\"diagram-muted\">additive schema</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">Polling sync</div></div>",
+  "css": ".diagram-tmpl{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-tmpl .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-tmpl .diagram-arrow{font-size:22px;line-height:1}.diagram-tmpl .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Modelldaten in SQL {#data-models}
+
+Definieren Sie Domänentabellen mit den Framework-Drizzle-Helfern, damit Schemata über SQLite, Postgres, D1, Turso, Supabase, Neon und andere unterstützte Backends hinweg portierbar bleiben:
+
+```ts
+// server/db/schema.ts
+import {
+  table,
+  text,
+  integer,
+  now,
+  ownableColumns,
+  createSharesTable,
+} from "@agent-native/core/db/schema";
+
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  status: text("status", {
+    enum: ["draft", "active", "archived"],
+  })
+    .notNull()
+    .default("draft"),
+  sortOrder: integer("sort_order").notNull().default(0),
+  ...ownableColumns(),
+  createdAt: text("created_at").notNull().default(now()),
+  updatedAt: text("updated_at").notNull().default(now()),
+});
+
+export const projectShares = createSharesTable("project_shares");
+```
+
+Schemaänderungen müssen additiv sein. Fügen Sie Tabellen und Spalten über `runMigrations()` in `server/plugins/db.ts` hinzu; Verwenden Sie niemals destruktive SQL, `drizzle-kit push`, Tabellenumbenennungen oder Spaltenlöschungen.
+
+Für App-Lese- und Schreibvorgänge verwenden Sie den Abfrage-Builder von Drizzle und die portablen Operatoren von `drizzle-orm`. Schreiben Sie keinen Produktcode mit rohem SQL, wenn Drizzle die Abfrage ausdrücken kann, und importieren Sie nicht aus `drizzle-orm/sqlite-core` oder `drizzle-orm/pg-core` in Vorlagen.
+
+```ts
+// server/plugins/db.ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default runMigrations(
+  [
+    {
+      version: 1,
+      sql: `CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      title TEXT NOT NULL,
+      status TEXT NOT NULL DEFAULT 'draft',
+      sort_order INTEGER NOT NULL DEFAULT 0,
+      owner_email TEXT NOT NULL,
+      org_id TEXT,
+      visibility TEXT NOT NULL DEFAULT 'private',
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+      updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    )`,
+    },
+  ],
+  { table: "my_app_migrations" },
+);
+```
+
+Verwenden Sie die Dokumente [Database](/docs/database) und [Security](/docs/security), bevor Sie Schemas hinzufügen, die Benutzer- oder Organisationsdaten enthalten.
+
+## Vorgänge als Actions definieren {#actions}
+
+Actions sind die einzige Quelle der Wahrheit für das App-Verhalten. Der Agent ruft sie als Tools auf, das Frontend ruft sie über Hooks auf und andere Apps können sie über MCP/A2A erreichen.
+
+```an-annotated-code title="actions/create-project.ts"
+{
+  "filename": "actions/create-project.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { getDb } from \"../server/db/index.js\";\nimport { nanoid } from \"nanoid\";\nimport { z } from \"zod\";\nimport * as schema from \"../server/db/schema\";\n\nexport default defineAction({\n  description: \"Create a project.\",\n  schema: z.object({\n    title: z.string().min(1).describe(\"Project title\"),\n  }),\n  run: async ({ title }, ctx) => {\n    const db = getDb();\n    const id = nanoid();\n    await db.insert(schema.projects).values({\n      id,\n      title,\n      ownerEmail: ctx.userEmail,\n      orgId: ctx.orgId,\n    });\n    return { id, title };\n  },\n});",
+  "annotations": [
+    { "lines": "2", "note": "`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`." },
+    { "lines": "8", "label": "Tool surface", "note": "The `description` is what the agent reads to decide when to call this action as a tool." },
+    { "lines": "9-11", "label": "Typisierter Vertrag", "note": "One zod `schema` validates input from the agent, the UI, HTTP, MCP, and A2A." },
+    { "lines": "18-19", "label": "Scoped write", "note": "Stamp `ownerEmail` / `orgId` from `ctx` so the row is correctly scoped for sharing and access checks." }
+  ]
+}
+```
+
+Verwenden Sie `http: { method: "GET" }` oder `readOnly: true` für schreibgeschütztes actions. Verwenden Sie `parallelSafe: true` nur für mutierende actions, die sicher gleichzeitig mit Werkzeugaufrufen für die gleiche Drehung ausgeführt werden können. Verwenden Sie `toolCallable: false` für actions mit hohem Explosionsradius, das nicht mit Sandbox-Tools ausgeführt werden sollte.
+
+## Erstellen Sie das UI {#ui}
+
+Routen leben in `app/routes/` und verwenden das Dateirouting von React Router v7. Fragen Sie Daten über actions- oder API-Handler ab und machen Sie Mutationen standardmäßig optimistisch.
+
+```tsx
+import { useActionMutation, useActionQuery } from "@agent-native/core/client";
+
+export default function ProjectsPage() {
+  const { data: projects = [] } = useActionQuery("list-projects", {});
+  const create = useActionMutation("create-project");
+
+  return (
+    <button onClick={() => create.mutate({ title: "Launch plan" })}>
+      New project ({projects.length})
+    </button>
+  );
+}
+```
+
+Verdrahten Sie die Live-Synchronisierung einmal in der Nähe der App-Shell, damit React Abfrage-Caches aktualisiert werden, wenn der Agent, eine andere Registerkarte oder eine Aktion Daten ändert:
+
+```tsx
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+export function AppSync() {
+  const queryClient = useQueryClient();
+  useDbSync({ queryClient });
+  return null;
+}
+```
+
+**Das agentennative Versprechen: Agentenschreibvorgänge werden im UI ohne manuelle Aktualisierung angezeigt.** `useActionQuery` ist der einfache Weg – jeder Hook wird erneut abgerufen, wenn eine mutierende Aktion `source: "action"` ausgibt. Wenn Sie mit einem benutzerdefinierten Schlüssel nach dem rohen `useQuery` greifen (z. B. einem Low-Level-Client-Helper, der den Integrationsstatus liest), falten Sie den Zähler pro Quelle in den queryKey für gezielte Aktualisierungen:
+
+```tsx
+import { useChangeVersions } from "@agent-native/core/client";
+
+const v = useChangeVersions(["dashboards", "action"]);
+useQuery({
+  queryKey: ["dashboard", id, v],
+  queryFn: () => fetchDashboard(id),
+  placeholderData: (prev) => prev, // no flicker on refetch
+});
+```
+
+Gemeinsame Quellen: `"action"` (jede erfolgreiche Agentenaktion – der zuverlässige Fallback), `"app-state"`, `"settings"` sowie jede benutzerdefinierte Ressourcenquelle, die Ihr Shop über `recordChange` ausgibt. Das vollständige Muster finden Sie im `real-time-sync`-Skill.
+
+## Anwendungsstatus hinzufügen {#application-state}
+
+Durch den Anwendungsstatus weiß der Agent, was der Benutzer sieht. Fügen Sie mindestens Folgendes hinzu:
+
+- Ein UI-Hook, der den semantischen `navigation`-Status schreibt, wenn sich Routen, ausgewählte Datensätze, aktive Registerkarten oder Editorauswahlen ändern.
+- Eine `view-screen`-Aktion, die diesen Status liest und den aktuellen Bildschirm-Snapshot zurückgibt.
+- Eine `navigate`-Aktion, die einen einmaligen `navigate`-Befehl schreibt, den UI nutzen soll.
+
+Verwenden Sie `useAgentRouteState` für den UI-Hook, damit Anwendungsstatus-Schreibvorgänge, tabulatorbezogene Befehlslesevorgänge, Löschung nach dem Lesen und Schutz vor doppelten Befehlen konsistent bleiben:
+
+```tsx
+import { useAgentRouteState } from "@agent-native/core/client";
+import { TAB_ID } from "@/lib/tab-id";
+
+export function useNavigationState() {
+  useAgentRouteState({
+    browserTabId: TAB_ID,
+    requestSource: TAB_ID,
+    getNavigationState: ({ pathname, searchParams }) => ({
+      view: pathname === "/" ? "home" : pathname.slice(1),
+      selectedId: searchParams.get("id"),
+    }),
+    getCommandPath: (command: any) => command.path ?? "/",
+    navigateOptions: { replace: true, flushSync: true },
+  });
+}
+```
+
+Behalten Sie gemeinsam nutzbare Filter in URL-Abfrageparametern bei. Das Framework stellt sie dem Agenten als `<current-url>` zur Verfügung und der integrierte Agent kann sie mit `set-search-params` ändern; `navigation` sollte semantische IDs und Aliase enthalten, keine zweite Kopie der vollständigen Abfragezeichenfolge.
+
+Bevorzugen Sie für die App-Navigation einen `navigate`-Befehl, der einen gleichen Ursprung enthält
+`path`, wenn URL bekannt ist. Schreiben Sie nicht auch `__set_url__` für denselben Zug;
+Dieser Schlüssel ist für die Framework-URL-Tools und nur URL-Filteränderungen reserviert.
+
+```ts
+// actions/navigate.ts
+import { defineAction } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Navigate the UI.",
+  schema: z.object({
+    view: z.enum(["home", "project"]),
+    projectId: z.string().optional(),
+    path: z.string().optional(),
+  }),
+  run: async (args) => {
+    await writeAppState("navigate", args);
+    return { ok: true };
+  },
+});
+```
+
+Das vollständige Muster finden Sie unter [Context Awareness](/docs/context-awareness).
+
+## Verwenden Sie API-Routen sparsam {#api-routes}
+
+Bevorzugen Sie actions für App-Vorgänge. Erstellen Sie benutzerdefinierte Nitro-Routen nur für Oberflächen, die nicht sauber actions sein können:
+
+- Datei-Upload oder binäres Streaming.
+- Öffentliche anonyme Seiten und webhooks.
+- OAuth-Rückrufe und anbieterspezifische Protokollhandler.
+- Vom Server gerenderter öffentlicher Inhalt.
+
+Benutzerdefinierte Routen, die besitzbare Daten berühren, müssen `getSession(event)` aufrufen und die Datenbankarbeit in `runWithRequestContext({ userEmail, orgId }, fn)` umschließen, bevor Zugriffshilfen verwendet werden.
+
+## Agentenanweisungen schreiben {#write-agents-md}
+
+`AGENTS.md` ist die Agentenkarte Ihrer App – eine kleine, überstreichbare Datei mit einem
+Zweckzeile, Kernregeln, Anwendungsstatusschlüssel, eine Aktionstabelle und ein skills
+Index:
+
+```markdown
+# My Template
+
+One workspace for projects, tasks, and notes.
+
+## Core Rules
+
+- Data lives in SQL via Drizzle. Use actions for all writes; schema is additive.
+- Use `view-screen` before acting on "this project" if the screen is unclear.
+
+## Application State
+
+- `navigation.view`: `home` | `project`
+- `navigation.projectId`: selected project on a project page
+
+## Actions
+
+| Action           | Purpose                  |
+| ---------------- | ------------------------ |
+| `list-projects`  | List accessible projects |
+| `create-project` | Create a project         |
+```
+
+Aktualisieren Sie `AGENTS.md`, wann immer Sie eine neue Aktion, Route, einen neuen Statusschlüssel oder eine wiederkehrende Aktion hinzufügen
+Workflow. [Writing Agent Instructions](/docs/writing-agent-instructions) ist der
+vollständige Anleitung – wie man `AGENTS.md` überstreichbar hält, was zu jedem der vier gehört
+Anleitungsoberflächen und wie man Fertigkeits- und Werkzeugbeschreibungen für den Agenten formuliert
+löst sie zuverlässig aus.
+
+## Skills hinzufügen {#skills}
+
+Verwenden Sie skills für detaillierte Muster, die `AGENTS.md` aufblähen würden: anbieterspezifische APIs, Import-/Exportformate, komplexe Bearbeitungsabläufe oder Domänenterminologie.
+
+```markdown
+---
+name: project-imports
+description: How to import projects from the legacy CSV export.
+---
+
+# Project Imports
+
+Use this skill when the user uploads a legacy project CSV.
+
+## Rules
+
+- Validate required columns before creating rows.
+- Use `create-project` for each project so ownership and sync are correct.
+- Save rejected rows as a note attached to the import summary.
+```
+
+Vorlage skills in `.agents/skills/<name>/SKILL.md` speichern. Wenn Benutzer die Anleitung zur Laufzeit bearbeiten können sollen, zeigen Sie sie auch über Arbeitsbereichsressourcen an.
+
+## Einrichtungsschritte registrieren {#onboarding}
+
+Wenn eine Vorlage einen API-Schlüssel, eine OAuth-Verbindung oder ein Anbieterkonto benötigt, registrieren Sie einen Onboarding-Schritt, anstatt die Anforderung in einem README zu vergraben.
+
+```ts
+// server/plugins/onboarding.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+export default defineNitroPlugin(() => {
+  registerOnboardingStep({
+    id: "github",
+    title: "Connect GitHub",
+    description: "Needed to import repositories and pull requests.",
+    order: 100,
+    methods: [
+      {
+        id: "token",
+        kind: "form",
+        primary: true,
+        label: "Save token",
+        payload: {
+          fields: [
+            { key: "GITHUB_TOKEN", label: "GitHub token", secret: true },
+          ],
+        },
+      },
+    ],
+    isComplete: () => !!process.env.GITHUB_TOKEN,
+  });
+});
+```
+
+Siehe [Onboarding & API Keys](/docs/onboarding).
+
+## Machen Sie es arbeitsplatzbereit {#workspace-ready}
+
+Vorlagen sollten natürlich in [Multi-App Workspaces](/docs/multi-app-workspace) passen, normalerweise koordiniert von [Dispatch](/docs/dispatch).
+
+Checkliste:
+
+- Befestigen Sie A2A über das Framework-Agent-Chat-Plugin oder `mountA2A()`, damit Geschwister-Apps Ihren Agenten anrufen können.
+- Halten Sie die Beschreibungen der Agentenkarten spezifisch genug, damit Dispatch die Arbeit genau weiterleiten kann.
+- Registrieren Sie die erforderlichen Geheimnisse/Onboarding, damit das Setup in der Seitenleiste angezeigt wird und Dispatch gemeinsame Anmeldeinformationen verwalten kann.
+- Behalten Sie übergreifende Anweisungen im Arbeitsbereich `AGENTS.md` oder in den Arbeitsbereichsressourcen bei und kopieren Sie sie nicht in jede App.
+- Verwenden Sie Freigabe-/Zugriffshelfer für alle besitzbaren Ressourcen, damit organisationsbezogene Arbeitsbereiche isoliert bleiben.
+
+## Eine Vorlage veröffentlichen {#publishing}
+
+Vor dem Teilen:
+
+1. Führen Sie `pnpm install`, `pnpm typecheck` und die Tests der Vorlage aus.
+2. Stellen Sie sicher, dass es funktioniert, ohne dass optionale Anbieterschlüssel konfiguriert sind.
+3. Überprüfen Sie Authentifizierung, Freigabe und Datenisolation für zwei Benutzer.
+4. Dokumentieren Sie die erforderlichen Umgebungsvariablen und Onboarding-Schritte.
+5. Fügen Sie Beispiele oder Seed-Zeilen durch additive Migrationen ein, nicht durch verfolgte Laufzeitdatendateien.
+
+Community-Vorlagen können aus einem GitHub-Repo erstellt werden:
+
+```bash
+npx @agent-native/core@latest create my-app --template github:user/repo
+```
+
+## Beitrag zum Framework Monorepo {#contributing}
+
+### Unveröffentlichte Framework-Änderungen testen {#test-unpublished-framework-changes}
+
+Wenn Sie innerhalb des Frameworks Monorepo arbeiten und ein generiertes benötigen
+Arbeitsbereich, um unveröffentlichte Paket- oder Vorlagenänderungen zu verwenden, führen Sie „Create“ mit dem
+Lokalpaket-Flag:
+
+```bash
+AGENT_NATIVE_CREATE_USE_LOCAL_CORE=1 pnpm --filter @agent-native/core create my-platform
+```
+
+Der generierte Arbeitsbereich verknüpft die lokalen `@agent-native/core` und
+`@agent-native/dispatch`-Pakete, also Änderungen an Core APIs, Dispatch-Arbeitsbereich
+-Verhalten oder Erstanbieter-Vorlagen können vor der Veröffentlichung getestet werden. Das Paket
+`prepack`-Skripte erstellen `dist` vor dem Verknüpfen, wodurch die generierten Daten erhalten bleiben
+Arbeitsbereich zeigte auf aktuelle Build-Ausgabe.

package/docs/content/locales/de-DE/cross-app-sso.md

@@ -0,0 +1,185 @@
+---
+title: "App-übergreifend SSO"
+description: "Melden Sie sich bei jeder gehosteten agentennativen App einmal über einen Identitätsverbund mit Dispatch als Identitätsinstanz an – Opt-in pro App, umkehrbar mit einer einzigen Umgebungsvariable."
+---
+
+# App-übergreifend SSO
+
+Jede gehostete App bei `*.agent-native.com` führt ihre eigene Bereitstellung mit ihrem **eigenen separaten Benutzerspeicher** aus. `mail.agent-native.com` und `calendar.agent-native.com` nutzen keine gemeinsame Datenbank, Sitzungstabelle oder Cookie-Domäne. „Einmal anmelden, jede App verwenden“ kann also kein gemeinsam genutztes Cookie sein – es muss eine **Identitätsföderation** sein, wobei [Dispatch](/docs/dispatch) als Identitätsautorität für den Arbeitsbereich fungiert.
+
+Dies ist das gleiche Vertrauensprimitiv, das [A2A](/docs/a2a-protocol) und [External Agents](/docs/external-agents) bereits verwenden – ein `A2A_SECRET`-signiertes JWT, das an der Anforderungsgrenze überprüft wird – angewendet auf den menschlichen Anmeldepfad anstelle von Agent-zu-Agent-Aufrufen.
+
+> **Einheitliche Bereitstellung vs. Bereitstellung pro Domäne.** Wenn Sie alle Apps an einem Ursprung hosten (`your-agents.com/mail`, `your-agents.com/calendar`), erhalten Sie bereits eine gemeinsame Anmeldung über eine einzige Cookie-Domäne – kein Verbund erforderlich. Cross-App SSO ist nur erforderlich, wenn Apps auf separaten Domänen ausgeführt werden. Siehe [Multi-App Workspaces — Unified deploy](/docs/multi-app-workspace#deployment).
+
+## Was und warum {#what-why}
+
+Benutzerspezifische Stores pro App bedeuten, dass es keinen einzigen Ort gibt, an dem ein Browser-Cookie gespeichert werden kann, dem jede App vertraut. Das Föderationsmodell benennt stattdessen eine App – **Dispatch** – als Identitätsautorität. Jede andere App kann „Wer ist diese Person?“ delegieren. an Dispatch senden, erhalten Sie eine kurzlebige signierte Bestätigung der verifizierten E-Mail-Adresse des Benutzers zurück und **verknüpfen Sie diese dann per E-Mail mit seinem eigenen lokalen Konto**.
+
+Die Verlinkungsregel ist bewusst eng und additiv:
+
+- **Vorhandener Benutzer mit derselben E-Mail-Adresse → verknüpft.** Das lokale Konto wird mit der bestätigten E-Mail-Adresse abgeglichen und unverändert wiederverwendet. Es wird **niemals geändert, umbenannt oder gelöscht** – die Föderationsschicht liest es immer nur und erstellt eine Sitzung dafür.
+- **Neue E-Mail → erstellt.** Für diese bestätigte E-Mail wird ein neues lokales Konto erstellt, dann wird eine normale lokale Sitzung erstellt.
+
+Dies macht den Rollout sicher, auch wenn dabei Personen abgemeldet werden. **Abmeldung wird erwartet.** Wenn eine App dies aktiviert, werden bestehende Sitzungen beendet und Benutzer authentifizieren sich erneut über Dispatch. Aber sie melden sich immer wieder bei dem **gleichen E-Mail-Konto an, bei dem alle Daten intakt sind**, da Identitätszeilen immer nur _hinzugefügt_ werden – niemals zerstört, umbenannt oder neu zugewiesen.
+
+## Wie es funktioniert {#how-it-works}
+
+Der Ablauf ist eine standardmäßige Autorisierung → Signiertes Token → Rückrufumleitung, wobei E-Mail das einzige ist, was die Vertrauensgrenze überschreitet.
+
+```an-diagram title="Identity federation flow" summary="Dispatch authenticates the human and returns a short-lived signed assertion of one thing — the verified email. The app links by email and mints its own local session."
+{
+  "html": "<div class=\"diagram-sso\"><div class=\"diagram-card\" data-rough><strong>Client app</strong><small class=\"diagram-muted\">own user store</small></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill\">authorize</span></div><div class=\"diagram-card\" data-rough><strong>Dispatch</strong><small class=\"diagram-muted\">identity authority</small><span class=\"diagram-pill accent\">authenticates human</span></div><div class=\"diagram-step\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><span class=\"diagram-pill accent\">302 + signed JWT</span></div><div class=\"diagram-card\" data-rough><strong>App callback</strong><small class=\"diagram-muted\">verify signature · scope:identity · exp &le; 2 min</small><span class=\"diagram-pill ok\">JIT-link by email</span><span class=\"diagram-pill ok\">mint local session</span></div></div>",
+  "css": ".diagram-sso{display:flex;align-items:stretch;gap:12px;flex-wrap:wrap}.diagram-sso .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px;min-width:150px}.diagram-sso .diagram-step{display:flex;flex-direction:column;align-items:center;justify-content:center;gap:6px}.diagram-sso .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+1. **App → Versenden (autorisieren).** Die App sendet den Benutzer an die Identitätsbehörde:
+
+   ```
+   GET https://dispatch.agent-native.com/_agent-native/identity/authorize
+       ?app=<requesting-app>
+       &redirect_uri=<app-callback-url>
+       &state=<csrf-state>
+   ```
+
+   ```an-api title="Identity Authorize Endpoint"
+   {
+     "Methode": "GET",
+     "Pfad": "/_agent-native/identity/authorize",
+     "summary": „Dispatch (Identitätsbehörde) authentifiziert den Menschen und leitet ihn mit einem signierten Identitätstoken zurück“,
+     "auth": „Sitzung weiterleiten (interaktive Anmeldung, falls keine)“,
+     "params": [
+       { „name“: „app“, „in“: „query“, „type“: „string“, „required“: true, „description“: „Die anfordernde App-ID.“ },
+       { „name“: „redirect_uri“, „in“: „query“, „type“: „string“, „required“: true, „description“: „App-Rückruf URL. Validiert anhand einer strengen Zulassungsliste (standardmäßig `*.agent-native.com` oder localhost).“ },
+       { „name“: „state“, „in“: „query“, „type“: „string“, „required“: true, „description“: „CSRF-Status wird bei der Umleitung zurückgegeben.“
+     ],
+     "Antworten": [
+       { „status“: „302“, „description“: „Weiterleitung zu `redirect_uri` mit einer kurzlebigen `A2A_SECRET`-signierten Identität JWT (`scope: \"identity\"`, `exp` ≤ 2 Minuten) plus der ursprünglichen `state`.“ },
+       { „status“: „400“, „description“: „`redirect_uri` ist bei der Zulassungslistenvalidierung fehlgeschlagen (herkunftsübergreifend, schemarelatives `//host` oder nicht gelistetes Suffix).“
+     ]
+   }
+   ```
+
+2. **Dispatch authentifiziert den Menschen.** Wenn der Benutzer bereits eine Dispatch-Sitzung hat, ist dies transparent. Wenn nicht, zeigt Dispatch sein eigenes normales Login an (E-Mail/Passwort, Google usw. – siehe [Authentication](/docs/authentication)). Dispatch ist hier nur eine normale agentennative App; Es wird kein spezieller Authentifizierungsmodus ausgeführt.
+
+3. **Dispatch → App (signiertes Identitätstoken).** Dispatch validiert `redirect_uri` anhand einer strengen Zulassungsliste und leitet 302 zurück zum `redirect_uri` der App mit einer kurzlebigen **`A2A_SECRET`-signierten Identität JWT**. Die Ansprüche des Tokens sind bewusst minimal:
+
+   | Anspruch     | Bedeutung                                                                        |
+   | ------------ | -------------------------------------------------------------------------------- |
+   | `sub`        | Stabile Benutzer-ID bei der Identitätsbehörde                                    |
+   | `email`      | Die **bestätigte** E-Mail-Adresse des Benutzers – der einzige Beitrittsschlüssel |
+   | `name`       | Anzeigename (nicht autorisierend, nur für UI)                                    |
+   | `org_domain` | Workspace/org-Domäne, falls vorhanden                                            |
+   | `scope`      | Immer `"identity"` – dieses Token autorisiert nur die Anmeldung                  |
+   | `exp`        | **≤ 2 Minuten** ab Problem                                                       |
+
+4. **App verifiziert und JIT-Links per E-Mail.** Die App überprüft die Token-Signatur mit ihrem eigenen `A2A_SECRET`, überprüft `scope: "identity"` und `exp` und führt dann **Just-in-Time-Verknüpfung ausschließlich per verifizierter E-Mail** durch:
+   - Wenn ein lokaler Benutzer mit dieser E-Mail existiert → unverändert wiederverwenden.
+   - Wenn nicht → erstellen Sie einen lokalen Benutzer für diese E-Mail.
+
+5. **App erstellt eine normale lokale Sitzung.** Von hier aus verfügt der Benutzer über eine normale lokale Sitzung im eigenen Store dieser App – alle vorhandenen Zugriffsprüfungen, Organisationsbereiche und Aktionsschutzfunktionen funktionieren genau wie zuvor. Die Föderation geschah erst vor der Haustür.
+
+### Aktivieren {#opt-in}
+
+Eine App nimmt **nur** teil, wenn diese Umgebungsvariable bei ihrer Bereitstellung festgelegt ist:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+- **Set** → Die App zeigt die Option **„Mit Agent-Native anmelden“** an, die den obigen Ablauf ausführt. Daneben funktioniert weiterhin die direkte lokale Anmeldung (E-Mail/Passwort, Google).
+- **Deaktiviert (Standard)** → **Keine Verhaltensänderung.** Die App authentifiziert sich genau wie zuvor; Der Verbundcodepfad ist inaktiv. Es gibt keine Schemaänderung und es muss nichts migriert werden, sodass das Ein- oder Ausschalten der Variablen jederzeit vollständig rückgängig gemacht werden kann.
+
+## Sicherheit {#security}
+
+Das gesamte Modell basiert auf ein paar bewusst kleinen Garantien:
+
+- **Kurzlebiges signiertes Token.** Die Identitätszusicherung ist ein `A2A_SECRET`-signiertes JWT mit einem **≤ 2-Minuten** Ablaufdatum und `scope: "identity"`. Es autorisiert eine einmalige Anmeldung und kann nicht für längere Zeit wiedergegeben oder für den API/A2A-Zugriff umgewidmet werden.
+- **Strikte `redirect_uri`-Zulassungsliste.** Dispatch leitet standardmäßig immer nur zu `*.agent-native.com` oder localhost weiter. Beliebige, schemarelative (`//host`) und Cross-Origin-Redirect-Ziele werden abgelehnt, sodass die Autorität nicht in ein Open-Redirect- oder Token-Exfiltration-Orakel umgewandelt werden kann.
+- **Nur E-Mail-Beitritt von einem verifizierten Token aus.** Das Einzige, was die Vertrauensgrenze überschreitet, ist die verifizierte E-Mail in einem signierten Token. Die App akzeptiert keine Benutzer-ID, Rolle, Organisationsmitgliedschaft oder einen privilegierten Status aus der Verbindung – sie leitet alles lokal vom übereinstimmenden Konto ab.
+- **Nur additive Identitätsschreibvorgänge.** Beim Verknüpfen wird entweder ein vorhandenes Konto mit derselben E-Mail-Adresse unverändert wiederverwendet oder ein neues eingefügt. Auf diesem Pfad findet niemals eine Aktualisierung, Umbenennung, Neuzuweisung oder Löschung von Identitätszeilen statt.
+- **Standardmäßig deaktiviert.** Wenn `AGENT_NATIVE_IDENTITY_HUB_URL` deaktiviert ist, ist die gesamte Funktion inaktiv.
+
+```an-callout
+{
+  "tone": "success",
+  "body": "**Safe to enable, safe to revert.** Identity writes are **additive only** — an existing same-email account is reused untouched, and a new email just inserts a fresh row. There is no schema change and nothing to migrate, so flipping `AGENT_NATIVE_IDENTITY_HUB_URL` on or off is fully reversible at any time, per app."
+}
+```
+
+Der Just-in-Time-Link ist eine einzelne Entscheidung, die vollständig auf der verifizierten E-Mail basiert:
+
+```an-diagram title="JIT-link decision" summary="Linking is keyed on the verified email and is additive only — existing accounts are reused unchanged, new emails create a fresh local user."
+{
+  "html": "<div class=\"diagram-jit\"><div class=\"diagram-node\" data-rough>Verified email<br><small class=\"diagram-muted\">from signed identity JWT</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-branch\"><div class=\"diagram-box\" data-rough>Local user exists?<span class=\"diagram-pill ok\">yes &rarr; reuse unchanged</span><span class=\"diagram-pill accent\">no &rarr; create local user</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Mint normal local session</div></div></div>",
+  "css": ".diagram-jit{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-node{display:flex;flex-direction:column;gap:4px;padding:12px 14px}.diagram-jit .diagram-branch{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-jit .diagram-box{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-jit .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Selbsthosting {#self-hosting}
+
+Jede Dispatch-Bereitstellung kann als Identitäts-Hub dienen – Sie sind nicht auf `dispatch.agent-native.com` beschränkt. Legen Sie `AGENT_NATIVE_IDENTITY_HUB_URL` in jeder Client-App so fest, dass es auf Ihre Dispatch-Instanz verweist:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.yourcompany.com
+```
+
+**Zulassungsliste für Weiterleitungen.** Der Hub (Dispatch) validiert `redirect_uri` auf dem Autorisierungsendpunkt, bevor er ein Token ausstellt. Die Zulassungsliste wird in `templates/dispatch/server/lib/identity-sso.ts`:
+
+- **Standard:** Nur `*.agent-native.com` und localhost (die `DEFAULT_ALLOWED_HOST_SUFFIXES`-Konstante).
+- **Erweitern:** Legen Sie die Umgebungsvariable `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` in der Dispatch-Bereitstellung mit einer durch Kommas getrennten Liste zusätzlicher Hostsuffixe fest:
+
+  ```bash
+  # Subdomains von yourcompany.com zusätzlich zu den Standardeinstellungen zulassen
+  IDENTITY_SSO_ALLOWED_HOST_SUFFIXES=".yourcompany.com,.staging.yourcompany.com"
+  ```
+
+  Jeder Eintrag ist auf ein Suffix mit vorangestelltem Punkt (`.yourcompany.com`) normalisiert, sodass eine Suffixprüfung sowohl ausreichend als auch am wenigsten anfällig für Fußwaffen ist – es gibt keine App-Liste, die synchron gehalten werden muss. Einträge, die zu allem passen würden (leer oder nur `.`), werden herausgefiltert.
+
+- **Localhost** ist unabhängig von `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` immer für die lokale Entwicklung clientseitiger Apps zulässig.
+
+Ohne `IDENTITY_SSO_ALLOWED_HOST_SUFFIXES` kann ein selbstgehosteter Dispatch nur Token für Apps auf `*.agent-native.com` ausgeben. Legen Sie die Umgebungsvariable in Ihrer Dispatch-Bereitstellung fest, um andere Domänen freizuschalten.
+
+## Canary-Rollout-Runbook {#canary-rollout}
+
+Cutover und Rollback sind **eine einzelne Umgebungsvariable pro App-Bereitstellung**. Führen Sie jeweils eine App aus, überprüfen Sie sie und erweitern Sie sie dann. Legen Sie die Variable nicht für jede App gleichzeitig fest.
+
+**1. Stellen Sie den Code bereit – keine Verhaltensänderung.**
+Versenden Sie die Veröffentlichung an jede App mit `AGENT_NATIVE_IDENTITY_HUB_URL` **überall deaktiviert**. Bestätigen Sie, dass normale Anmeldungen bei einigen Apps weiterhin funktionieren.
+
+**2. Aktivieren Sie jeweils den Canary in der ONE-App.**
+Eingestellt, nur für eine Bereitstellung:
+
+```bash
+AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com
+```
+
+Lassen Sie die Umgebung aller anderen Apps deaktiviert. Erneut bereitstellen/neu starten, damit die Variable übernommen wird.
+
+**3. Überprüfen Sie den Kanarienvogel (Checkliste).**
+
+- Melden Sie sich von der App **ab** ab.
+- Der Anmeldebildschirm zeigt jetzt **„Mit Agent-Native anmelden“** an. Klicken Sie darauf.
+- Sie werden zu **Versand** weitergeleitet und vervollständigen die Anmeldung (oder gehen direkt durch, wenn Sie dort bereits angemeldet sind).
+- Sie werden **zurück zur App weitergeleitet, angemeldet** – und es ist dasselbe **bereits bestehende Konto** (dieselbe E-Mail-Adresse), das Sie zuvor hatten, kein neues.
+- **App-Daten sind intakt** – Ihre vorhandenen Datensätze, Einstellungen und Organisationsbereiche sind genau so, wie sie waren.
+- **Bestehende Direktanmeldungen funktionieren weiterhin** – E-Mail/Passwort und Google-Anmeldung funktionieren weiterhin neben SSO.
+
+Wenn eine Prüfung fehlschlägt, fahren Sie direkt mit Schritt 4 (Rollback) fort – es erfolgt sofort und ist datensicher.
+
+**4. Erweitern Sie App für App.**
+Sobald eine App verifiziert ist, wiederholen Sie die Schritte 2–3 für die nächste App und legen Sie `AGENT_NATIVE_IDENTITY_HUB_URL` jeweils für eine Bereitstellung fest. Niemals stapelweise aktivieren.
+
+**5. Rollback = Deaktivieren Sie die Umgebungsvariable bei der Bereitstellung dieser App.**
+Um eine App zurückzusetzen, **entfernen Sie `AGENT_NATIVE_IDENTITY_HUB_URL` aus der Umgebung dieser App und stellen Sie sie erneut bereit/starten Sie sie neu.** Die App kehrt sofort zu ihrem vorherigen Authentifizierungsverhalten zurück. Es gibt **keine Datenänderung, die rückgängig gemacht werden kann** – Identitätszeilen wurden immer nur hinzugefügt, und das Deaktivieren der Variablen macht den Verbundpfad einfach wieder in den Ruhezustand. Die Umstellung und das Rollback jeder App sind unabhängig und umkehrbar.
+
+> Beim Rollout werden Benutzer abgemeldet, wenn jede App aktiviert wird (sie authentifizieren sich erneut über Dispatch), aber sie melden sich immer wieder beim **gleichen E-Mail-abgeglichenen Konto mit intakten Daten** an, da Identitätszeilen nie zerstört oder umbenannt, sondern nur hinzugefügt werden.
+
+## Verwandt {#related}
+
+- [Authentication](/docs/authentication) – lokale Authentifizierungsmodi, Sitzungen, Organisationen, die `A2A_SECRET`-Umgebungsvariable.
+- [A2A Protocol](/docs/a2a-protocol) – das signierte JWT-Vertrauensmodell mit Überprüfung an der Grenze, das hier wiederverwendet wird.
+- [External Agents](/docs/external-agents) – das gleiche `A2A_SECRET`-signierte Identitätsmuster, das auf Agentenverbindungen und Deep Links angewendet wird.
+- [Dispatch](/docs/dispatch) – die Workspace-Identitätsbehörde und der Routing-Hub.
+- [Security & Data Scoping](/docs/security) – Nur additive Datenschreibvorgänge und Scoping pro Konto.
+- [Multi-App Workspaces](/docs/multi-app-workspace) – die einheitliche Single-Origin-Bereitstellung, die domänenübergreifendes SSO vollständig vermeidet.