@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,321 @@
+---
+title: "Workspace-Verbindungen"
+description: "Gemeinsam genutzte Anbietermetadaten, Berechtigungen und Anmeldeinformationsreferenzen für Connect-Once-Use-Everywhere-Integrationen."
+---
+
+# Workspace-Verbindungen
+
+Workspace-Verbindungen sind das Grundgerüst für wiederverwendbare Integrationsmetadaten. Sie ermöglichen „einmalige Verbindung, Gewährung von Apps, Wiederverwendung von Anmeldeinformationen“, ohne vorzutäuschen, dass jeder Anbieter vollständig generisch sei.
+
+## Schnellstart {#quickstart}
+
+### Die vier Konzepte
+
+- **Verbindung** – ein benanntes Anbieterkonto (`team-slack`, `acme-hubspot`). Zeichnet Anbieter-ID, Kontobezeichnung, Status, Bereiche und sichere Konfiguration auf. Speichert niemals geheime Werte.
+- **Grant** – Berechtigung für eine bestimmte App, eine Verbindung zu verwenden. Eine App ohne Gewährung kann die Anmeldeinformationen der Verbindung nicht sehen.
+- **credentialRef** – ein Zeiger auf ein Tresorgeheimnis (`{ key: "SLACK_BOT_TOKEN", scope: "org" }`). Die Verbindung gibt an, wo sich der Token befindet; Der Tresor speichert den Wert.
+- **Bereitschaft** – der kombinierte Status, den eine App sieht: `connected` (erteilt + Anmeldeinformationen vorhanden), `needs_grant`, `needs_credentials`, `needs_attention` oder `not_configured`.
+
+```an-diagram title="Connect once, grant apps, reuse credentials" summary="A Connection holds provider metadata (never secrets) and credentialRefs that point at the vault. Per-app Grants unlock it. Apps read a single Readiness status."
+{
+  "html": "<div class=\"diagram-conn\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection</span><div class=\"diagram-box\" data-rough>named provider account<br><small class=\"diagram-muted\">provider, label, status, scopes, config &middot; never stores secret values</small></div><div class=\"diagram-muted\">credentialRef &rarr; pointer to a vault secret</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill\">Grant</span><div class=\"diagram-box\" data-rough>per-app permission<br><small class=\"diagram-muted\">no grant = no credential access</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Readiness</span><small class=\"diagram-muted\">what the app sees</small><div class=\"sev-row\"><span class=\"diagram-pill ok\">connected</span><span class=\"diagram-pill warn\">needs_grant</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">needs_credentials</span><span class=\"diagram-pill warn\">needs_attention</span></div><div class=\"sev-row\"><span class=\"diagram-pill\">not_configured</span></div></div></div>",
+  "css": ".diagram-conn{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-conn .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-conn .diagram-arrow{font-size:22px;line-height:1}.diagram-conn .sev-row{display:flex;gap:8px;flex-wrap:wrap}"
+}
+```
+
+### Arbeitsbeispiel: Slack
+
+Verbinden Sie Slack einmal und gewähren Sie es Brain and Analytics:
+
+```ts
+import {
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+await upsertWorkspaceConnection({
+  id: "acme-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "Acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history", "chat:write"],
+  config: {
+    teamDomain: "acme",
+    channelHints: ["product", "dev-fusion", "customer-success"],
+  },
+  credentialRefs: [{ key: "SLACK_BOT_TOKEN", scope: "org" }],
+});
+
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "acme-slack",
+  appId: "analytics",
+});
+```
+
+```an-schema title="The connection model" summary="A connection records safe provider metadata and credentialRefs (pointers, not secrets). Each grant unlocks one app — one connection, many grants."
+{
+  "entities": [
+    {
+      "id": "conn",
+      "name": "workspace_connections",
+      "note": "Named provider account. Never stores secret values.",
+      "fields": [
+        { "name": "id", "type": "string", "pk": true, "note": "e.g. acme-slack" },
+        { "name": "provider", "type": "string", "note": "stable provider id, e.g. slack" },
+        { "name": "label", "type": "string" },
+        { "name": "accountId", "type": "string", "nullable": true },
+        { "name": "accountLabel", "type": "string", "nullable": true },
+        { "name": "status", "type": "string", "note": "e.g. connected" },
+        { "name": "scopes", "type": "string[]", "nullable": true },
+        { "name": "config", "type": "json", "nullable": true, "note": "safe, non-secret config" },
+        { "name": "credentialRefs", "type": "json", "nullable": true, "note": "pointers to vault keys, e.g. { key, scope }" }
+      ]
+    },
+    {
+      "id": "grant",
+      "name": "workspace_connection_grants",
+      "note": "Per-app permission to use a connection.",
+      "fields": [
+        { "name": "connectionId", "type": "string", "fk": "conn.id" },
+        { "name": "appId", "type": "string", "note": "e.g. brain, analytics" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "conn", "to": "grant", "kind": "1-n", "label": "grants apps" }
+  ]
+}
+```
+
+### Was Apps aufrufen
+
+Bevor Sie einen Benutzer auffordern, einen neuen Schlüssel einzufügen, prüfen Sie zunächst die Bereitschaft:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+const catalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+  provider: "slack",
+  includeConnections: "all",
+});
+
+const slack = catalog.providers[0];
+if (slack.workspaceConnection.grantState === "needs_grant") {
+  // Show "Grant Brain access" instead of asking for a second Slack token.
+}
+if (slack.readiness.status === "needs_credentials") {
+  // Show the missing credential ref names, never a secret value.
+}
+```
+
+## Referenz {#reference}
+
+### Anbieterkatalog
+
+Katalog aus `@agent-native/core/connections` importieren:
+
+```ts
+import {
+  getWorkspaceConnectionProvider,
+  listWorkspaceConnectionProvidersForTemplate,
+  workspaceConnectionProviderSupports,
+} from "@agent-native/core/connections";
+
+const brainProviders = listWorkspaceConnectionProvidersForTemplate("brain");
+const slack = getWorkspaceConnectionProvider("slack");
+
+if (workspaceConnectionProviderSupports("slack", "messages")) {
+  // Offer a Slack source, sync check, or onboarding step.
+}
+```
+
+Die anfänglichen Anbieter-IDs sind:
+
+| Anbieter       | Fähigkeiten                             | Häufige Verwendungszwecke                        |
+| -------------- | --------------------------------------- | ------------------------------------------------ |
+| `slack`        | Suche, Import, Nachrichten              | Gehirn, Versand, Analyse                         |
+| `github`       | Suche, Import, Code, Dokumente          | Gehirn, Analyse, Versand                         |
+| `notion`       | Suche, Import, Dokumente                | Gehirn, Inhalt, Versand                          |
+| `gmail`        | Suche, Import, Nachrichten              | Post, Gehirn, Versand                            |
+| `google_drive` | Suche, Import, Dokumente                | Gehirn, Inhalte, Folien                          |
+| `hubspot`      | Suche, Import, CRM                      | Analyse, Gehirn, E-Mail                          |
+| `granola`      | Suche, Import, Besprechungen, Dokumente | Gehirn, Kalender, Versand                        |
+| `clips`        | Suche, Import, Besprechungen            | Gehirn, Clips, Videos                            |
+| `generic`      | Suche, Import, Dokumente                | benutzerdefiniertes webhooks und Dateilöschungen |
+
+Anmeldeinformationsschlüssel sind nur Namen, wie z. B. `SLACK_BOT_TOKEN` oder `GITHUB_TOKEN`. Anbietermetadaten dürfen niemals tatsächliche Anmeldeinformationswerte enthalten.
+
+### Verbindungsspeicher API
+
+```ts
+import {
+  listWorkspaceConnectionProviderCatalogForApp,
+  listWorkspaceConnectionGrants,
+  listWorkspaceConnections,
+  summarizeWorkspaceConnectionProviderForApp,
+  summarizeWorkspaceConnectionProviderReadiness,
+  upsertWorkspaceConnection,
+  upsertWorkspaceConnectionGrant,
+  revokeWorkspaceConnectionGrant,
+} from "@agent-native/core/workspace-connections";
+
+const connections = await listWorkspaceConnections({ includeDisabled: true });
+const grants = await listWorkspaceConnectionGrants({ appId: "brain" });
+
+const appGrant = summarizeWorkspaceConnectionProviderForApp({
+  providerId: "slack",
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const readiness = summarizeWorkspaceConnectionProviderReadiness({
+  provider: slack!,
+  appId: "brain",
+  connections,
+  grants,
+});
+
+const brainCatalog = await listWorkspaceConnectionProviderCatalogForApp({
+  appId: "brain",
+  templateUse: "brain",
+});
+```
+
+Das `credentialRefs`-Array zeigt auf Tresorschlüssel; Es handelt sich nicht um einen Anmeldeinformationsspeicher. Beispielsweise weist `{ key: "SLACK_BOT_TOKEN", scope: "org" }` eine berechtigte App an, das organisationsweite Tresorgeheimnis mit dem Namen `SLACK_BOT_TOKEN` nachzuschlagen, wenn sie Slack aufrufen muss. Referenzen auf Verbindungsebene beschreiben das Anbieterkonto. Refs auf Grant-Ebene können einschränken oder überschreiben, was eine bestimmte App verwenden soll.
+
+Verbindungszeilen beziehen sich auf die aktive Organisation, sofern eine solche vorhanden ist. Ohne eine Organisation sind sie auf den authentifizierten Benutzer beschränkt. Grant-Zeilen verwenden denselben Bereich.
+
+**Legacy `allowedApps`-Feld:** `allowedApps: []` bedeutet, dass jede App im gleichen Bereich die Verbindung verwenden darf; `allowedApps: ["dispatch"]` gewährt Zugriff über das Legacy-Feld. Verwenden Sie explizite `workspace_connection_grants`-Zeilen für die Neueinrichtung – sie erleichtern den Widerruf, die Prüfung und die Bereitschaft pro App. `revokeWorkspaceConnectionGrant(connectionId, appId)` entfernt eine explizite Erteilung, ändert jedoch nichts an der Vorgängerversion `allowedApps`.
+
+Verwenden Sie `summarizeWorkspaceConnectionProviderForApp()` und `summarizeWorkspaceConnectionProviderReadiness()` für den App-bezogenen Status, anstatt Zuschussschecks manuell durchzuführen. Die freigegebenen Zusammenfassungen geben `grantState`, `grantAvailability`, Referenznamen für sichere Anmeldeinformationen, Verbindungszeilen pro App und Bereitschaftsfelder wie `readyConnectionCount` und `missingRequiredCredentialKeys` zurück.
+
+Für neue App-Setup-Bildschirme bevorzugen Sie `listWorkspaceConnectionProviderCatalogForApp()` als übergeordnete Grenze – es kombiniert den Anbieterkatalog, bereichsbezogene Verbindungen, explizite Gewährungen, Zugriffszusammenfassungen pro App und Anbieterbereitschaft in einer sicheren Form.
+
+### Wie dies den Tresor ergänzt
+
+Der Anmeldeinformations-Tresor antwortet: „Wo wird das Geheimnis gespeichert, wer kann darauf zugreifen und welche Apps erhalten es?“
+
+Metadaten des Workspace-Verbindungsanbieters antworten: „Welcher Anbieter ist das, was kann er, welche Anmeldeinformationsschlüssel benötigt er möglicherweise und welche Vorlagen sollten ihn anbieten?“
+
+```an-diagram title="Connection store vs. vault" summary="The vault owns the secret value. The connection owns provider metadata plus credentialRefs (pointers). At execution time the app resolves the ref through a granted connection and reads the value from the vault."
+{
+  "html": "<div class=\"diagram-vault\"><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill accent\">Connection store</span><div class=\"diagram-box\" data-rough>provider account + metadata<br><small class=\"diagram-muted\">status, scopes, config</small></div><div class=\"diagram-box\" data-rough>credentialRef<br><small class=\"diagram-muted\">{ key: SLACK_BOT_TOKEN, scope: org }</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">App action</span><small class=\"diagram-muted\">resolves at execution time through a granted ref</small><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel col\" data-rough><span class=\"diagram-pill ok\">Vault</span><div class=\"diagram-box\" data-rough>secret value<br><small class=\"diagram-muted\">never returned to the agent or UI</small></div></div></div>",
+  "css": ".diagram-vault{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-vault .col{display:flex;flex-direction:column;gap:8px;padding:14px;min-width:220px}.diagram-vault .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-vault .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Beides zusammen verwenden:
+
+1. Dispatch (oder ein anderer Workspace-Setup-Flow) erstellt das zugrunde liegende Tresorgeheimnis oder die OAuth-Anmeldeinformationsreferenz.
+2. Der Workspace-Verbindungsspeicher zeichnet das Anbieterkonto, sichere Metadaten, Anmeldeinformationsreferenzen und App-Zuweisungen auf.
+3. Jede App liest Anbietermetadaten aus dem Katalog und Verbindungs-/Gewährungszusammenfassungen aus dem freigegebenen Speicher.
+4. Die App UI zeigt Bereitschaft an: verbunden, gewährt, aber fehlerhaft, benötigt Genehmigung, fehlende Anmeldeinformationen oder nur Metadaten.
+5. App-spezifisch SQL speichert nur app-spezifische Quell-IDs, Cursor, Filter, Synchronisierungsfenster, Metrikdefinitionen, Überprüfungsregeln und Benutzerauswahlen.
+6. App actions löst Anmeldeinformationen zur Ausführungszeit über gewährte Verbindungsreferenzen und den Tresor auf und gibt niemals geheime Werte zurück.
+
+### Laufzeit des Anbieterlesers
+
+Die Anbieter-Reader-Ebene ist zunächst ein Vertrag und kein Versprechen, dass jeder Anbieter über einen gemeinsamen Live-Reader verfügt. Leserdefinitionen beschreiben unterstützte Vorgänge, Anmeldeinformationsanforderungen und Implementierungsstatus: `metadata-only`, `template-owned` oder `shared`. Die Laufzeit löst die gewährten Workspace-Verbindungs- und Anmeldeinformationsreferenzen für eine App auf, ruft einen registrierten Handler auf und gibt normalisierte Elemente zurück, ohne geheime Werte preiszugeben.
+
+Die meisten Live-Handler bleiben auch heute noch im Besitz von Vorlagen, was bedeutet, dass Brain immer noch das Slack/GitHub-Aufnahmeverhalten besitzt und Analytics immer noch die Analyseinterpretation besitzt. Befördern Sie einen Leser nur dann zu `shared`, wenn die anbieterspezifischen API-Aufrufe, Paginierung, Berechtigungen und Ergebnissemantik wirklich vorlagenübergreifend wiederverwendbar sind.
+
+### App-Bereitschaftsmuster
+
+Apps, die gemeinsam genutzte Anbieteranmeldeinformationen nutzen, sollten eine schreibgeschützte Bereitschaftsaktion und eine kleine Setup-Oberfläche bereitstellen, die Folgendes abdeckt:
+
+- **Anbieterkatalog:** Anbieter-ID, Bezeichnung, Funktionen, empfohlene Vorlagenverwendungen und erforderliche Anmeldeinformationsschlüsselnamen von `@agent-native/core/connections`.
+- **Zusammenfassung des Arbeitsbereichs:** Verbindungsanzahl, aktive/gewährte Anzahl, Gewährungsstatus, Namen von Anmeldeinformationsreferenzen und nicht geheime Kontobezeichnungen von `@agent-native/core/workspace-connections`.
+- **Anbieterbereitschaft:** `ready`, `needs_credentials`, `needs_attention`, `checking`, `disabled` oder `not_configured` über `summarizeWorkspaceConnectionProviderReadiness()`.
+- **Quellenstatus:** App-lokal konfigurierte Quellen, Cursor, Synchronisierungsstatus und nächste Aktion.
+
+Die Quellenseite von Brain ist die Referenzimplementierung. Es zeigt wiederverwendbare Workspace-Verbindungsanbieter neben Brain-Quelldatensätzen an, beschriftet Gewährungsstatus als `connected`, `granted`, `needs_grant` oder `not_connected` und zeigt den Anbieterzustand als „Bereit“, „Fehlende Schlüssel“, „Genehmigung erforderlich“, „Reparatur erforderlich“ oder nur „Metadaten“ an.
+
+### Erstellen eines wiederverwendbaren Connectors
+
+Wenn ein neuer Anbieter über mehrere Vorlagen hinweg funktionieren soll:
+
+1. **Anbietermetadaten:** Fügen Sie einen Anbieter in `@agent-native/core/connections` hinzu oder verwenden Sie ihn wieder. Dabei handelt es sich um die stabile ID, die Anzeigebezeichnung, die Funktionsliste, die empfohlenen Vorlagenverwendungen und die Namen der Anmeldeinformationsschlüssel.
+2. **Workspace-Verbindung:** Dispatch oder eine andere Workspace-Setup-Oberfläche speichert die sicheren Metadaten, den Status, die Bereiche, `credentialRefs` und App-Zuweisungen des verbundenen Kontos über `@agent-native/core/workspace-connections`.
+3. **App-lokale Quelle:** Brain, Analytics, Mail oder eine andere App speichert nur die app-spezifischen Auswahlmöglichkeiten, die sie besitzt, wie z. B. Slack-Kanäle, GitHub-Repositorys, HubSpot-Objektfilter, Synchronisierungscursor oder Abfragerhythmus.
+
+ZxQ6QXZ/Token-Speicher nicht in jeder App duplizieren. Im Verbindungsdatensatz steht: „Dies ist Acme Slack und sein Token befindet sich bei `SLACK_BOT_TOKEN`“; In der App-lokalen Quelle heißt es: „Brain kann `#product` und `#dev-fusion` von dieser Slack-Verbindung aufnehmen.“
+
+### Einrichtung der Dispatch-Steuerungsebene
+
+Dispatch macht die Steuerungsebene actions verfügbar, die dieselben gemeinsam genutzten Store-Funktionen schreibt, die eine App direkt aufrufen könnte:
+
+```ts
+// templates/dispatch/actions/upsert-workspace-connection.ts delegates to this.
+await upsertWorkspaceConnection({
+  id: "team-slack",
+  provider: "slack",
+  label: "Acme Slack",
+  accountId: "T012345",
+  accountLabel: "acme",
+  status: "connected",
+  scopes: ["channels:history", "groups:history"],
+  config: { teamDomain: "acme", preferredChannels: ["product", "dev-fusion"] },
+  credentialRefs: [
+    {
+      key: "SLACK_BOT_TOKEN",
+      scope: "org",
+      provider: "slack",
+      label: "Slack bot token",
+    },
+  ],
+});
+
+// Then grant the apps that should reuse the provider.
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "brain",
+});
+await upsertWorkspaceConnectionGrant({
+  connectionId: "team-slack",
+  appId: "analytics",
+});
+```
+
+Verwenden Sie `allowedApps: []` nur, wenn eine Verbindung für jede App im gleichen Bereich verfügbar sein soll. Bevorzugen Sie explizite Gewährungszeilen für die Produktionseinrichtung.
+
+### Anmeldeinformationsauflösung
+
+App-Ausführungscode löst Anmeldeinformationswerte aus gewährten `credentialRefs` über den Tresor im aktiven Anforderungsbereich auf. Brains `source-credentials.ts` ist die aktuelle Referenzimplementierung: Es listet Workspace-Verbindungen für den Anbieter auf, überprüft `getWorkspaceConnectionAppAccess` auf `appId: "brain"`, führt Referenzen für Anmeldeinformationen auf Verbindungs- und Gewährungsebene zusammen und liest das erste passende, bereichsbezogene Tresorgeheimnis. Andere Apps sollten dieser Form folgen, anstatt nach `process.env` zu greifen.
+
+## Designhinweise {#design-notes}
+
+<details>
+<summary>Reader-Promotion-Richtlinie und Pfad zu „Einmal verbinden, überall verwenden“</summary>
+
+### App-lokale Grenze
+
+Die Grenze zwischen gemeinsam genutzten Verbindungen und lokalen App-Quellen ist beabsichtigt. Was heute wiederverwendbar ist, ist die Anbieteridentität, die Auflösung von Anmeldeinformationsreferenzen, Gewährungen pro App, die Anbieterbereitschaft, sichere Kontometadaten und der normalisierte Anbieter-Leser-Vertrag. Was noch nicht generisch ist, sind die meisten Live-Provider-API-Lesungen, OAuth-Flow-Besitz, Aufnahmecursor, Quellfilter, Synchronisierungsrhythmus und Domäneninterpretation. Diese bleiben in der App, die den Workflow besitzt, es sei denn, eine Leserimplementierung wird ausdrücklich auf „Freigegeben“ hochgestuft.
+
+App-Quellkonnektoren sollten keine Umgebungsvariablen auf Bereitstellungsebene als Ersatz für Benutzer-/Organisations-Quellanmeldeinformationen lesen. Umgebungsvariablen gelten global für die Bereitstellung und stellen keine Arbeitsbereichszuweisungen dar.
+
+Agenten sollten einer einfachen Regel folgen: Wenn ein Benutzer eine Verbindung zu Slack, GitHub, HubSpot, Gmail, Google Drive, Granola oder einem anderen gemeinsam genutzten Anbieter wünscht, überprüfen Sie zuerst den Workspace-Verbindungskatalog. Wenn der Anbieter `connected` ist, verwenden Sie ihn. Wenn es sich um `needs_grant` handelt, beantragen Sie die App-Bewilligung oder führen Sie sie durch. Wenn es `needs_credentials` ist, fragen Sie nach dem fehlenden Tresorschlüssel. Fordern Sie nur dann einen neuen Rohschlüssel an, wenn keine wiederverwendbare Verbindung besteht.
+
+### Pfad zu „Einmal verbinden, überall verwenden“
+
+Der Anbieterkatalog und der Grant Store bilden die Grundlage für eine breitere Arbeitsbereichsebene:
+
+- Gemeinsame Anbieter-IDs und Funktionsnamen sorgen für eine einheitliche Ausrichtung der Vorlagen.
+- Das Inventar auf Workspace-Ebene kann zeigen, welche Anbieter in Brain, Mail, Analytics, Dispatch und zukünftigen Apps konfiguriert sind.
+- Verbindungszeilen zeichnen Kontobezeichnungen, Status, zugelassene Apps, Anmeldeinformationsreferenzen und Integritätsprüfungen auf, ohne die vorlagenbezogenen Anbieter-IDs zu ändern.
+- Grant-Zeilen ermöglichen es einem Arbeitsbereichsbesitzer, einmal eine Verbindung herzustellen und dann einzelne Apps zu aktivieren, wenn der Arbeitsbereich sie übernimmt.
+- Agenten können Arbeit über Apps hinweg weiterleiten und wissen, welche Anbieter bereits verbunden sind und welche Apps Berechtigungen haben.
+- Die Verbundsuche kann nach Anbietern mit `search`-, `docs`-, `messages`-, `meetings`-, `crm`- oder `code`-Funktionen fragen, anstatt die Connector-Liste jeder App fest zu codieren.
+- Anbieterspezifische Leser, OAuth-Aktualisierungsflüsse, Aufnahmeprüfpunkte und App-eigene Datenmodelle können später gemeinsam genutzt werden, sind jedoch heute nicht durch eine Workspace-Verbindung impliziert.
+
+Halten Sie die Grenze streng: Anbietermetadaten können sicher angezeigt werden; Anmeldeinformationswerte bleiben im Tresor.
+
+</details>

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

@@ -0,0 +1,175 @@
+---
+title: "Workspace Governance"
+description: "Verzweigung, CODEOWNERS, PR-Überprüfung und wie Dispatch die Laufzeit-Governance neben der Governance auf Git-Ebene handhabt."
+---
+
+# Workspace Governance
+
+> **Welches Workspace-Dokument?** Auf dieser Seite geht es um **Governance** – wer überprüft, genehmigt und besitzt was für viele Apps in einem Repo. Was ein Arbeitsbereich ist (die Anpassungsebene), erfahren Sie unter [Workspace](/docs/workspace); Informationen zur Bereitstellungsform (ein Monorepo, viele Apps) finden Sie unter [Multi-App Workspaces](/docs/multi-app-workspace).
+
+Dieser Leitfaden behandelt die betriebliche Seite der Ausführung eines agentennativen Arbeitsbereichs – wie man verzweigt, wer was überprüft, wie man Codebesitz einrichtet und wie die Dispatch-Steuerungsebene in Ihr Governance-Modell passt.
+
+```an-diagram title="Two governance planes" summary="Git governs code; Dispatch governs runtime. They are complementary — don't replicate one inside the other."
+{
+  "html": "<div class=\"gov\"><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Git / GitHub</span><strong>Code governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">CODEOWNERS</span><span class=\"diagram-pill\">branch protection</span><span class=\"diagram-pill\">PR review</span><span class=\"diagram-pill\">git log / blame</span></div></div><div class=\"diagram-pill diagram-muted\">+</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Dispatch</span><strong>Runtime governance</strong><div class=\"gov-list\"><span class=\"diagram-pill\">vault secrets &amp; grants</span><span class=\"diagram-pill\">workspace resources</span><span class=\"diagram-pill\">agent profiles</span><span class=\"diagram-pill\">approvals &amp; audit</span></div></div></div>",
+  "css": ".gov{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.gov .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.gov .gov-list{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}"
+}
+```
+
+## Verzweigung
+
+### Feature-Zweige
+
+Verwenden Sie kurzlebige Funktionszweige für alle Arbeiten:
+
+```
+main                         ← production
+├── feat/mail-filters        ← single-app change
+├── feat/core-oauth-refresh  ← framework change
+├── fix/analytics-chart      ← targeted bug fix
+└── feat/vault-encryption    ← dispatch/infra change
+```
+
+**Namenskonventionen:**
+
+- **Änderungen einzelner Apps:** `feat/<app>-<description>` oder `fix/<app>-<description>` – z. B. `feat/mail-thread-search`, `fix/calendar-recurrence-parse`
+- **Framework-Änderungen:** `feat/core-<description>` oder `fix/core-<description>` – z.B. `feat/core-polling-v2`
+- **Versandänderungen:** `feat/dispatch-<description>` – z.B. `feat/dispatch-vault-policies`
+- **App-übergreifende Änderungen:** Wenn eine Framework-Änderung Vorlagenaktualisierungen erfordert, führen Sie beide in einem Zweig durch, damit sie atomar versendet werden
+
+Halten Sie Zweige kurzlebig. Langlebige Zweige weichen von den Hauptzweigen ab und führen zu schmerzhaften Zusammenführungen – insbesondere in einem Monorepo, in dem mehrere Teams täglich pushen.
+
+### Nicht-Entwickler-Branche
+
+Nicht jeder, der Änderungen vornehmen muss, ist mit Git vertraut. [Builder.io](https://www.builder.io) unterstützt ein visuelles Verzweigungsmodell, das Git-Zweigen unter der Haube zuordnet – nützlich für Inhalts- und Textänderungen, Layoutanpassungen, Designiterationen und A/B-Tests ohne Entwicklungsumgebung.
+
+## Code-Eigentum
+
+Code Governance wird durch eine Handvoll Dateien im Repo-Stammverzeichnis konfiguriert:
+
+```an-file-tree title="Governance config in the repo"
+{
+  "entries": [
+    { "path": ".github/CODEOWNERS", "note": "Auto-assigns reviewers per changed path" },
+    { "path": ".github/labeler.yml", "note": "Auto-labels PRs by app" },
+    { "path": "pnpm-workspace.yaml", "note": "Workspace-level — broad review" },
+    { "path": "package.json", "note": "Workspace-level — platform team owns" }
+  ]
+}
+```
+
+Die CODEOWNERS-Datei von GitHub weist Prüfer automatisch PRs zu, basierend auf den geänderten Dateien. Erstellen Sie `.github/CODEOWNERS` im Repo-Root:
+
+```
+# Framework core — affects every app; platform team reviews all changes
+packages/core/                     @your-org/platform-team
+
+# Dispatch control plane — secrets, integrations, workspace resources
+templates/dispatch/                @your-org/platform-team
+
+# Per-app ownership — each team reviews their own app
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+# ... add an entry per app
+
+# Workspace-level config — broad review since it affects everyone
+.github/                           @your-org/platform-team
+package.json                       @your-org/platform-team
+pnpm-workspace.yaml                @your-org/platform-team
+```
+
+Wichtige Tipps: Verwenden Sie GitHub-Teams (`@org/team`), keine Einzelpersonen. Framework- und Dispatch-Änderungen sollten immer eine Plattformüberprüfung erfordern. Informationen zur Glob-Syntax und zu Mustern mit mehreren Eigentümern finden Sie unter [GitHub CODEOWNERS docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
+
+So aktivieren Sie erforderliche Überprüfungen: Einstellungen → Zweige → Zweigschutz für `main` → **Vor dem Zusammenführen ist eine Pull-Anfrage erforderlich** → **Überprüfung durch Codebesitzer erforderlich**.
+
+## PR-Kennzeichnung
+
+PRs per App automatisch kennzeichnen mit `.github/labeler.yml` (Auszug):
+
+```yaml
+app:mail:
+  - changed-files:
+      - any-glob-to-any-file: templates/mail/**
+app:analytics:
+  - changed-files:
+      - any-glob-to-any-file: templates/analytics/**
+core:
+  - changed-files:
+      - any-glob-to-any-file: packages/core/**
+```
+
+Dann fügen Sie die Aktion [actions/labeler](https://github.com/actions/labeler) hinzu – siehe README des Repos für den vollständigen Workflow YAML. Beschriftungen werden automatisch angewendet, wenn PRs geöffnet oder aktualisiert werden.
+
+## PR-Überprüfungsrichtlinien
+
+| Typ ändern                       | Wer bewertet                             | Worauf Sie achten sollten                                                                |
+| -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Nur App** (`templates/<app>/`) | Eigentümer des App-Teams                 | Domänenkorrektheit, Aktionsschemata                                                      |
+| **Framework** (`packages/core/`) | Plattformteam + ein betroffenes App-Team | Breaking Changes, Leistung, Abwärtskompatibilität                                        |
+| **Schemamigrationen**            | Plattformteam + leitender Ingenieur      | Datensicherheit, Dialektagnostizismus (SQLite + Postgres)                                |
+| **Actions**                      | Eigentümerteam                           | Actions sind beide Agent-Tools, AND HTTP Endpunkte – Überprüfung aus beiden Blickwinkeln |
+| **App-übergreifendes A2A**       | Beide App-Teams                          | Wenn Sie eine A2A-Schnittstelle ändern, müssen die Anrufer davon erfahren                |
+| **Tresor/Ressourcen versenden**  | Plattform-Team                           | Geheimer Zugriff, Gewährungsbereich, wer was bekommt                                     |
+
+### Gleichzeitige Agentenarbeit
+
+Agent-native Arbeitsbereiche verfügen oft über mehrere KI-Agenten, die gleichzeitig im selben Zweig arbeiten. Dies ist beabsichtigt – die Agenten teilen sich einen Zweig und pushen unabhängig voneinander.
+
+```an-callout
+{ "tone": "warning", "body": "**The later commit wins.** Two agents touching the same file won't conflict at commit time — the conflict surfaces at review. Run `pnpm run prep` (typecheck + test + format) before pushing, and don't revert changes you didn't make unless they're clearly broken." }
+```
+
+Beim Überprüfen von PRs in dieser Umgebung:
+
+- **Machen Sie Änderungen, die Sie nicht vorgenommen haben, nicht rückgängig**, es sei denn, sie sind eindeutig fehlerhaft.
+- **Dateien können von mehreren Agenten** im selben PR geändert werden – das ist normal
+- **Führen Sie `pnpm run prep`** (Typprüfung + Test + Formatierung) aus, bevor Sie pushen, um Integrationsprobleme zwischen Agentenänderungen zu erkennen
+- **Wenn zwei Agenten dieselbe Datei berühren,** gewinnt der spätere Commit. Konflikte tauchen zum Zeitpunkt der Überprüfung auf, nicht zum Zeitpunkt der Festschreibung
+- **Beheben Sie Fehler in jedem Code im PR,** unabhängig davon, welcher Agent ihn geschrieben hat. Die PR wird als Ganzes überprüft.
+
+## Versand als Governance
+
+Die [Dispatch](/docs/dispatch)-App ist die Laufzeitsteuerungsebene des Arbeitsbereichs. Es ergänzt die Governance auf Git-Ebene durch die Laufzeit-Governance:
+
+| Bedenken                                 | Git / GitHub            | Versand                                                            |
+| ---------------------------------------- | ----------------------- | ------------------------------------------------------------------ |
+| Wer kann Code ändern?                    | CODEOWNERS, Zweigschutz | —                                                                  |
+| Wer kann auf Geheimnisse zugreifen?      | —                       | Vault-Richtlinie, Zuschüsse, Antragsworkflow                       |
+| Welche Anweisungen Agenten befolgen      | —                       | Globale Arbeitsbereichsressourcen (AGENTS.md, Anweisungen, skills) |
+| Welche Agenten werden gemeinsam genutzt? | —                       | Workspace-Agentenprofile                                           |
+| Integrationsinventar                     | —                       | Katalog für Workspace-Verbindungen und -Integrationen              |
+| Genehmigung von Laufzeitänderungen       | —                       | Versandgenehmigungsablauf                                          |
+| Audit-Trail                              | `git log` / `git blame` | Vault-Audit- und Versand-Audit-Protokolle                          |
+| Nachrichten und Routing                  | —                       | Slack / Telegram-Integration                                       |
+
+**Git übernimmt die Code-Governance. Dispatch übernimmt die Laufzeit-Governance.** Versuchen Sie nicht, Git-Workflows innerhalb von Dispatch zu replizieren oder umgekehrt.
+
+Dispatch verwaltet: Tresorgeheimnisse, wiederverwendbare Arbeitsbereichsverbindungen, Arbeitsbereichsressourcen (skills, Anweisungen, Agentenprofile, MCP-Server), Genehmigungen und Prüfprotokolle. Informationen zur Konfiguration öffentlicher App-Routen (`workspaceApp.audience` / `publicPaths` / `protectedPaths`) finden Sie unter [Multi-App Workspaces — Public app routes](/docs/multi-app-workspace#deployment).
+
+Informationen zum Ressourcenmodell und zu den kanonischen Pfaden finden Sie unter [Workspace — Global resources](/docs/workspace#global-resources).
+
+## Setup-Checkliste
+
+Für einen neuen Arbeitsbereich nach dem Ausführen von `npx @agent-native/core@latest create`:
+
+**Git & GitHub:**
+
+- [ ] Erstellen Sie `.github/CODEOWNERS` mit Teameigentum pro App
+- [ ] Aktivieren Sie den Branch-Schutz auf `main` mit erforderlichen Code-Eigentümer-Überprüfungen
+- [ ] Fügen Sie `.github/labeler.yml` für die automatische Kennzeichnung von PRs per App hinzu
+- [ ] Erstellen Sie GitHub-Teams für jede App und das Plattformteam
+
+**Versand:**
+
+- [ ] Gemeinsame Geheimnisse zum Tresor hinzufügen (API-Schlüssel, OAuth-Anmeldeinformationen usw.)
+- [ ] Behalten Sie die standardmäßige Tresorrichtlinie für alle Apps bei oder wechseln Sie zu manuellen Gewährungen pro App
+- [ ] Synchronisieren Sie Tresorgeheimnisse, um sie an Apps zu übertragen
+- [ ] Dann registrieren Sie wiederverwendbare Workspace-Verbindungen für freigegebene Anbieterkonten
+      Gewähren Sie Apps wie Brain, Analytics, Mail oder Dispatch nur bei Bedarf
+      dieses Konto
+- [ ] Fügen Sie über die Seite „Ressourcen“ arbeitsbereichsweite skills-, Leitplanken-Anweisungen und Marken-/Firmenreferenzressourcen hinzu. Die vollständige Ressourcenmodelltabelle und das empfohlene Starterpaket finden Sie unter [Workspace](/docs/workspace#global-resources).
+- [ ] Konfigurieren Sie die Genehmigungsrichtlinie und die E-Mails der Genehmiger
+- [ ] Richten Sie SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) für Administratorbenachrichtigungen ein
+- [ ] Verbinden Sie Slack oder Telegram für Workspace-Messaging
+- [ ] Gemeinsam genutzte MCP-Server konfigurieren – `mcp-servers/<name>.json`-Arbeitsbereichsressourcen in Dispatch für All-App- oder ausgewählte App-Zuteilungen hinzufügen; Verwenden Sie `mcp.config.json` oder [MCP hub mode](/docs/mcp-clients#hub) für Bereitstellungen auf niedrigerer Ebene