@agent-native/core 0.76.5 → 0.76.6

package/docs/content/locales/de-DE/native-chat-ui.md

@@ -0,0 +1,321 @@
+---
+title: "Nativer Chat UI"
+description: "Aktionsdeklarierte native Chat-Renderer, wiederverwendbare DataTable-/DataChart-Ausgaben und wie BYO-Agentenlaufzeiten eine Verbindung zum Agent-Native-Chat herstellen sollten."
+---
+
+# Nativer Chat UI
+
+Nativer Chat UI ist der In-App-Rendering-Pfad für die Ausgabe von Erstanbieter-Agenten. Ein
+Aktion gibt strukturiertes JSON zurück, die Chat-Laufzeit erkennt ein explizites Widget
+diskriminant, und `<AssistantChat>` rendert eine echte React-Komponente im
+Gespräch. Sie erstellen keinen Iframe oder ein einmaliges HTML-Artefakt für
+normaler App-Chat.
+
+Verwenden Sie den nativen Chat UI, wenn der Benutzer die Ausgabe dort überprüfen soll, wo sich der Agent befindet
+redet bereits: Abfrageergebnisse, Antworteinblicke, Setup-Zusammenfassungen,
+Genehmigungs-/Ablehnungskontrollen oder Links zu App-Ansichten. Verwenden Sie [MCP Apps](/docs/mcp-apps)
+wenn ein externer Host wie Claude, ChatGPT, Copilot oder Cursor rendern soll
+eine Inline-Route aus Ihrer App.
+
+```an-diagram title="The native render path" summary="An action returns JSON; the runtime matches an explicit widget discriminant or chatUI.renderer; AssistantChat mounts a real React component. No iframe, no HTML execution."
+{
+  "html": "<div class=\"diagram-render\"><div class=\"diagram-node\">Action runs<br><small class=\"diagram-muted\">returns structured JSON</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough><span class=\"diagram-pill accent\">Match</span><small class=\"diagram-muted\">explicit widget &middot; chatUI.renderer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">&lt;AssistantChat&gt;<br><small class=\"diagram-muted\">mounts a React widget</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill ok\">DataTable</div><div class=\"diagram-pill ok\">DataChart</div><div class=\"diagram-pill ok\">DataInsights</div></div></div>",
+  "css": ".diagram-render{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-render .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-render .col{display:flex;flex-direction:column;gap:6px;padding:12px}.diagram-render .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Aktionsdeklarierte Widgets {#action-declared-widgets}
+
+Der native Pfad besteht aus zwei expliziten Teilen:
+
+- `outputSchema` validiert die Antwortform der Aktion.
+- `chatUI.renderer` wählt den nativen React-Renderer für das validierte Ergebnis aus.
+
+Die integrierten Datenrenderer verwenden ein einfaches JSON-Ergebnis mit `widget` plus
+passende Nutzlast:
+
+| Widget            | Erforderliche Nutzlast         | Wird gerendert als                                           |
+| ----------------- | ------------------------------ | ------------------------------------------------------------ |
+| `"data-table"`    | `table`                        | Eine native, wiederverwendbare Datentabelle                  |
+| `"data-chart"`    | `chartSeries`                  | Ein natives Balken-, Linien- oder Flächendiagramm            |
+| `"data-insights"` | `table` und/oder `chartSeries` | Eine kombinierte Insight-Karte mit Diagramm-/Tabellenausgabe |
+
+Server actions sollte die serversicheren Helfer und Schemata importieren von
+`@agent-native/core/data-widgets`; Client-Code kann dieselben Typen importieren aus
+`@agent-native/core/client/chat` oder `@agent-native/core/client`.
+
+```ts
+import { defineAction } from "@agent-native/core/action";
+import { ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER } from "@agent-native/core/action-ui";
+import {
+  createDataInsightsWidgetResult,
+  dataInsightsWidgetResultSchema,
+} from "@agent-native/core/data-widgets";
+
+export default defineAction({
+  description: "Analyze form responses.",
+  readOnly: true,
+  outputSchema: dataInsightsWidgetResultSchema,
+  chatUI: {
+    renderer: ACTION_CHAT_UI_DATA_INSIGHTS_RENDERER,
+    title: "Response insights",
+  },
+  run: async () =>
+    createDataInsightsWidgetResult({
+      title: "Response insights",
+      display: {
+        title: "42 responses",
+        description: "Completion rate rose this week.",
+        primaryAction: {
+          label: "Open response insights",
+          href: "/response-insights",
+        },
+      },
+      chartSeries: {
+        type: "bar",
+        title: "Responses by day",
+        xKey: "day",
+        series: [{ key: "responses", label: "Responses" }],
+        data: [
+          { day: "Mon", responses: 8 },
+          { day: "Tue", responses: 13 },
+        ],
+      },
+      table: {
+        title: "Top answers",
+        columns: [
+          { key: "answer", label: "Answer" },
+          { key: "count", label: "Count", align: "right" },
+        ],
+        rows: [
+          { answer: "Yes", count: 31 },
+          { answer: "No", count: 11 },
+        ],
+        totalRows: 2,
+      },
+    }),
+});
+```
+
+```an-callout
+{
+  "tone": "success",
+  "body": "The renderer only takes over when the action declares `chatUI` **or** the result carries an explicit known `widget` discriminant. It never shape-infers arbitrary objects and never executes HTML or JavaScript from tool results — so a native widget can't become an injection vector."
+}
+```
+
+Wenn ein Benutzer nach einem Diagramm, einer Grafik, einer Tabelle, einem Trend oder einem kompakten Bericht fragt, app-Agents
+sollte eine Aktion bevorzugen, die einen dieser nativen Renderer deklariert. Das Finale
+Assistententext sollte kurz bleiben und das Widget die Daten übertragen lassen; nicht kopieren
+dieselben Zeilen in eine Markdown-Tabelle einfügen, es sei denn, der Benutzer fragt ausdrücklich nach einem Text
+exportieren.
+
+Wenn keine Domänenaktion vorhanden ist, der Agent jedoch bereits die Kompaktheit abgerufen hat,
+wahrheitsgemäße Daten, es kann die Framework-Aktion `render-data-widget` mit dem aufrufen
+gleiche `data-table`-, `data-chart`- oder `data-insights` JSON-Form. Nur diese Aktion
+überprüft und rendert das Widget; Es ist keine Datenquelle und darf nicht verwendet werden
+um Platzhaltermetriken zu erfinden.
+
+## DataTable-Ausgabe {#data-table}
+
+`table` ist bewusst einfach gehalten, sodass Liste, SQL, Analyse und Einrichtung von actions möglich sind
+wiederverwenden:
+
+```ts
+{
+  title?: string;
+  columns: Array<{ key: string; label: string; align?: "left" | "right" }>;
+  rows: Array<Record<string, unknown>>;
+  totalRows?: number;
+  sampledRows?: number;
+  truncated?: boolean;
+}
+```
+
+Stabile Spaltenschlüssel und JSON-sichere Zeilenwerte bevorzugen. Verwenden Sie `totalRows`,
+`sampledRows` und `truncated`, wenn die Aktion einen Ausschnitt eines größeren zeigt
+Ergebnissatz.
+
+## DataChart-Ausgabe {#data-chart}
+
+`chartSeries` unterstützt die gängigen Diagrammformen, die in Agentenantworten verwendet werden, ohne
+Jede Vorlage muss ihren eigenen Chat-Renderer liefern:
+
+```ts
+{
+  type: "bar" | "line" | "area";
+  title?: string;
+  xKey: string;
+  series: Array<{ key: string; label: string; color?: string }>;
+  data: Array<Record<string, unknown>>;
+  sampled?: boolean;
+}
+```
+
+Kartendaten kompakt halten. Bei großen Datensätzen die Aktion aggregieren und verknüpfen
+zur vollständigen App-Ansicht mit `display.primaryAction`- oder Aktions-`link`-Metadaten.
+
+## Native Widgets vs. MCP Apps {#native-vs-mcp-apps}
+
+Native Chat-Widgets und MCP Apps ergänzen sich:
+
+- **Native Widgets** sind für die eigene Chat-Laufzeitumgebung der App vorgesehen. Das Aktionsergebnis ist
+  JSON, und das Framework rendert das integrierte React-Widget.
+- **MCP Apps** sind für externe Hosts. Die Aktion deklariert `mcpApp` und normalerweise
+  `link`, und der Host rendert eine echte App-Route inline, sofern unterstützt.
+- **Deep Links** bleiben der universelle Fallback. Verwenden Sie die Aktion `link` oder
+  `display.primaryAction` also CLI-Clients, ältere MCP-Hosts und einfaches Transkript
+  Leser können die vollständige App-Ansicht öffnen.
+
+Wenn sowohl eine native Widget-Nutzlast als auch MCP Apps-Metadaten vorhanden sind, die In-App
+chat bevorzugt das native Widget. Externe Hosts verwenden die MCP Apps-Ressource oder die
+Deep-Link-Fallback.
+
+## Benutzerdefinierte native Renderer {#custom-native-renderers}
+
+Produktspezifische Komponenten anhand der genauen Renderer-ID registrieren und dann diese ID deklarieren
+zur Aktion:
+
+```tsx
+import { registerActionChatRenderer } from "@agent-native/core/client/chat";
+
+registerActionChatRenderer({
+  id: "crm.deal-card",
+  renderer: "crm.deal-card",
+  Component: ({ context }) => <DealCard result={context.resultJson} />,
+});
+```
+
+```ts
+export default defineAction({
+  description: "Show a deal card.",
+  outputSchema: dealCardSchema,
+  chatUI: { renderer: "crm.deal-card" },
+  run: async () => ({ dealId: "deal_123", amount: 42000 }),
+});
+```
+
+Verwenden Sie dies für die Erstanbieter-App UI. Behalten Sie den hostübergreifenden Iframe UI in `mcpApp` und behalten Sie
+willkürliche Abfrageausführung hinter eingegebenem Lese-actions anstelle von rohem SQL im Chat.
+
+## BYO Agentenlaufzeiten {#byo-agent-runtimes}
+
+`AgentChatRuntime` ist der Bring-Your-Own-Agent-Vertrag für die Chat-Shell und
+Dieser Abschnitt ist seine kanonische Referenz. Es ermöglicht einen Agenten, den Sie woanders erstellt haben
+normalisierte Ereignisse in die Konversation UI von Agent-Native streamen und dabei die beibehalten
+Gemeinsamer Composer, Transkript-Rendering, Toolkarten, Genehmigungen, native Widgets,
+und das umgebende App-Layout. Der [Drop-in Agent](/docs/drop-in-agent#custom-chat-ui)
+Tutorial-Punkte hier für die Laufzeitgeschichte und [Component API](/docs/components#agent-chat-ui)
+listet jeden Connector und Adapter mit seinem Importpfad auf; Der Vertrag selbst ist
+unten beschrieben.
+
+```an-diagram title="BYO runtime keeps the Agent-Native chat shell" summary="Your external agent streams normalized events through a connector; Agent-Native keeps the composer, transcript, tool cards, approvals, and native widgets."
+{
+  "html": "<div class=\"diagram-byo\"><div class=\"diagram-box\" data-rough>Your agent<br><small class=\"diagram-muted\">OpenAI &middot; Claude &middot; Vercel AI &middot; AG-UI &middot; HTTP</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">connector</span><small class=\"diagram-muted\">normalized message-* / tool-* events</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card col\"><div class=\"diagram-pill\">&lt;AssistantChat runtime=&hellip; /&gt;</div><small class=\"diagram-muted\">composer &middot; transcript &middot; tool cards</small><small class=\"diagram-muted\">approvals &middot; native widgets</small></div></div>",
+  "css": ".diagram-byo{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-byo .center{display:flex;flex-direction:column;align-items:center;gap:4px;padding:14px}.diagram-byo .col{display:flex;flex-direction:column;gap:6px;padding:14px}.diagram-byo .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+Alle Connectors werden aus `@agent-native/core/client/chat` (und dem Root) exportiert
+`@agent-native/core/client`-Eintrag). Verwenden Sie die generische HTTP-Laufzeit, wenn Ihr Agent
+kann einen POST-Endpunkt verfügbar machen, der SSE- oder NDJSON-Laufzeitereignisse zurückgibt:
+
+```tsx
+import {
+  AssistantChat,
+  createHttpAgentChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const runtime = createHttpAgentChatRuntime({
+  id: "external:mastra",
+  label: "Mastra",
+  endpoint: "/api/mastra/chat",
+  headers: async () => ({
+    Authorization: `Bearer ${await getAgentToken()}`,
+  }),
+});
+
+export function SupportChat() {
+  return <AssistantChat runtime={runtime} threadId="support" />;
+}
+```
+
+Wenn Ihr Endpunkt bereits ein gemeinsames Agentenprotokoll streamt, verwenden Sie das entsprechende
+Connector und überspringen Sie das Schreiben eines benutzerdefinierten Mappers:
+
+```ts
+import {
+  createAgUiChatRuntime,
+  createClaudeAgentChatRuntime,
+  createOpenAIAgentsChatRuntime,
+  createOpenAIResponsesChatRuntime,
+  createVercelAiChatRuntime,
+} from "@agent-native/core/client/chat";
+
+const openAiAgentsRuntime = createOpenAIAgentsChatRuntime({
+  endpoint: "/api/openai-agents/chat",
+});
+
+const openAiResponsesRuntime = createOpenAIResponsesChatRuntime({
+  endpoint: "/api/openai-responses/chat",
+});
+
+const claudeAgentRuntime = createClaudeAgentChatRuntime({
+  endpoint: "/api/claude-agent/chat",
+});
+
+const vercelAiRuntime = createVercelAiChatRuntime({
+  endpoint: "/api/vercel-ai/chat",
+});
+
+const agUiRuntime = createAgUiChatRuntime({
+  endpoint: "/api/ag-ui/chat",
+});
+```
+
+Der Endpunkt kann die normalisierte Ereignisform direkt streamen:
+
+```text
+data: {"type":"message-start","message":{"id":"m1","role":"assistant","content":[]}}
+data: {"type":"message-delta","messageId":"m1","delta":{"type":"text","text":"Hello"}}
+data: {"type":"tool-start","toolCall":{"id":"t1","name":"query","input":{"q":"forms"}}}
+data: {"type":"tool-done","toolCallId":"t1","toolName":"query","status":"completed","resultText":"34 rows"}
+data: {"type":"done","reason":"complete"}
+```
+
+Für sehr einfache Agenten wird eine JSON-Antwort `{ "text": "..." }` akzeptiert und
+in eine einzelne Assistentennachricht umgewandelt. Für umfangreichere Agenten streamen Sie
+`message-*`, `tool-*`, `approval-request`, `status`, `artifact`, `file`,
+`usage`-, `error`- und `done`-Ereignisse. Werkzeugergebnisse können `mcpApp` oder
+`chatUI`-Metadaten, sodass aktionsdeklarierte native Widgets immer noch ohne gerendert werden
+iframes.
+
+Wenn Sie den integrierten Agent-Native-Transport als Laufzeitobjekt verwenden möchten, verwenden Sie:
+
+```ts
+import { createAgentNativeChatRuntime } from "@agent-native/core/client/chat";
+
+const runtime = createAgentNativeChatRuntime({
+  threadId: "forms-chat",
+  mode: "act",
+});
+```
+
+Verwenden Sie `<AssistantChat createAdapter={...} />` nur, wenn Sie die volle Kapazität benötigen
+Assistent-UI-Adaptersteuerung. Verwenden Sie `PromptComposer` allein für Ihr Produkt
+besitzt das gesamte externe Transkript und möchte nur den Komponisten von Agent-Native
+Feld.
+
+OpenAI-, AG-UI-, Claude Agent SDK- und Vercel AI SDK-Streams können den Standard verwenden
+Connector-Helfer. ACP bleibt die Interoperabilität zwischen Codierungsagent und Editor, nicht die
+allgemeine App-Chat-Laufzeit für Endbenutzer. A2UI wird hier nicht als unterstützt beansprucht;
+Wenn es ausgereift ist, sollte es sich an denselben expliziten Laufzeit-/Widget-Vertrag anpassen.
+
+## Verwandte Dokumente {#related-docs}
+
+- [Actions](/docs/actions) – Definieren Sie die Vorgänge, die native Widget-Daten zurückgeben.
+- [Agent Surfaces](/docs/agent-surfaces) – entscheiden Sie, ob Sie eine Headless-, Chat-, Sidecar- oder vollständige App benötigen.
+- [Drop-in Agent](/docs/drop-in-agent) – das Tutorial zum Mounten der Standard-Chat-Laufzeitumgebung.
+- [Component API](/docs/components) – die API-Karte pro Export für Chat-Ebenen, Laufzeiten und Tool-Renderer.
+- [MCP Apps](/docs/mcp-apps) – Inline-UI für externe MCP-Hosts.
+- [Key Concepts](/docs/key-concepts#protocols) – Protokollstatus und Positionierung.

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

@@ -0,0 +1,231 @@
+---
+title: "Benachrichtigungen"
+description: "In-App-Benachrichtigungen mit steckbaren Kanälen – Posteingang, Webhook oder benutzerdefiniert"
+---
+
+# Benachrichtigungen
+
+Eine Funktion, viele Ziele. Rufen Sie `notify()` von einem beliebigen serverseitigen Code aus auf – einer Aktion, einer Automatisierung, einem Plugin – und das Ereignis landet im In-App-Posteingang des Benutzers und wird an jeden registrierten Kanal weitergeleitet. Wird mit einer Bell-and-Dropdown-UI-Komponente geliefert, die die Host-Vorlage in ihren Header einfügt.
+
+Benachrichtigungen sind unidirektionale Benachrichtigungen an den Glockeneingang der App (plus Webhook-Fanout). Informationen zum _Unterhalten_ mit Ihrem Agenten über Slack/email/Telegram/WhatsApp finden Sie unter [Messaging](/docs/messaging).
+
+```ts
+import { notify } from "@agent-native/core/notifications";
+
+await notify(
+  { severity: "info", title: "Booking confirmed", body: "Jane at 3pm" },
+  { owner: "steve@builder.io" },
+);
+```
+
+```an-diagram title="One call, many destinations" summary="notify() always writes the owner-scoped inbox row, fans out to every registered channel in parallel (best-effort), then emits notification.sent on the event bus."
+{
+  "html": "<div class=\"diagram-notify\"><div class=\"diagram-node\">notify(input, { owner })<br><small class=\"diagram-muted\">any server code &middot; action, automation, plugin</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel fan\" data-rough><div class=\"fan-row\"><span class=\"diagram-pill accent\">inbox</span><div class=\"diagram-box\" data-rough>notifications table &rarr; bell UI<br><small class=\"diagram-muted\">always on &middot; owner-scoped</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">webhook</span><div class=\"diagram-box\" data-rough>POST JSON to NOTIFICATIONS_WEBHOOK_URL<br><small class=\"diagram-muted\">best-effort</small></div></div><div class=\"fan-row\"><span class=\"diagram-pill\">custom</span><div class=\"diagram-box\" data-rough>registerNotificationChannel(...)<br><small class=\"diagram-muted\">best-effort &middot; runs in parallel</small></div></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill ok\">notification.sent</span><small class=\"diagram-muted\">event bus &middot; automations can chain</small></div></div>",
+  "css": ".diagram-notify{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-notify .fan{display:flex;flex-direction:column;gap:10px;padding:14px}.diagram-notify .fan-row{display:flex;align-items:center;gap:10px}.diagram-notify .diagram-card{display:flex;flex-direction:column;gap:6px;padding:12px 14px}.diagram-notify .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Schweregrade {#severities}
+
+| Schweregrad | Verwenden für                                    |
+| ----------- | ------------------------------------------------ |
+| `info`      | Bestätigungen, Fortschrittsmeilensteine, FYI     |
+| `warning`   | Etwas, das sich der Benutzer bald ansehen sollte |
+| `critical`  | Benötigt sofortige Aufmerksamkeit                |
+
+Der Schweregrad steuert den Badge-Stil im Dropdown-Menü und wird an die Kanäle weitergeleitet, damit diese nach Dringlichkeit verzweigen können.
+
+## Eingebaute Kanäle {#channels}
+
+| Kanal     | Lieferung                                                      | Erfordert                                                            |
+| --------- | -------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `inbox`   | Bleibt in der `notifications`-Tabelle; treibt die Glocke an UI | Immer an – Teil des Grundelements.                                   |
+| `webhook` | POST JSON zu einem konfigurierten URL                          | `NOTIFICATIONS_WEBHOOK_URL` Umgebungsvariable beim Start festgelegt. |
+
+Der Webhook-Kanal löst `${keys.NAME}`-Referenzen sowohl im URL als auch im `NOTIFICATIONS_WEBHOOK_AUTH` anhand des Ad-hoc-[secrets](/docs/security) des Eigentümers auf, sodass der Rohwert niemals in den Kontext des Agenten gelangt. Es werden URL-Zulassungslisten pro Schlüssel erzwungen – dieselbe Regel, die das Automatisierungstool `web-request` verwendet.
+
+```an-diagram title="Channels and severity" summary="inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."
+{
+  "html": "<div class=\"diagram-channels\"><div class=\"diagram-panel col\" data-rough><strong>Channels</strong><div class=\"diagram-box\" data-rough>inbox<br><small class=\"diagram-muted\">always on &mdash; part of the primitive</small></div><div class=\"diagram-box\" data-rough>webhook<br><small class=\"diagram-muted\">needs NOTIFICATIONS_WEBHOOK_URL</small></div><div class=\"diagram-box\" data-rough>custom<br><small class=\"diagram-muted\">registerNotificationChannel()</small></div></div><div class=\"diagram-panel col\" data-rough><strong>Severity drives the badge</strong><div class=\"sev-row\"><span class=\"diagram-pill\">info</span><span class=\"diagram-muted\">confirmations, FYI</span></div><div class=\"sev-row\"><span class=\"diagram-pill warn\">warning</span><span class=\"diagram-muted\">look at soon</span></div><div class=\"sev-row\"><span class=\"diagram-pill accent\">critical</span><span class=\"diagram-muted\">needs immediate attention</span></div></div></div>",
+  "css": ".diagram-channels{display:flex;gap:16px;flex-wrap:wrap;align-items:flex-start}.diagram-channels .col{display:flex;flex-direction:column;gap:10px;padding:14px;min-width:240px}.diagram-channels .sev-row{display:flex;align-items:center;gap:10px}"
+}
+```
+
+## API {#api}
+
+### `notify(input, meta)` {#notify}
+
+Übermitteln Sie eine Benachrichtigung. Bleibt immer im Posteingang bestehen, sofern nicht ausdrücklich ausgeschlossen; Zusätzliche registrierte Kanäle laufen parallel, Best-Effort.
+
+```ts
+await notify(
+  {
+    severity: "critical",
+    title: "Database offline",
+    body: "Primary dropped connections",
+    metadata: { runbookUrl: "https://runbooks/db-offline" },
+    channels: ["inbox", "webhook"], // optional allowlist; omit to run all
+  },
+  { owner: "ops@company.com" },
+);
+```
+
+`meta.owner` ist erforderlich – legt den Umfang der Benachrichtigung so fest, dass nur dieser Benutzer sie in der Glocke sieht.
+
+### `registerNotificationChannel(channel)` {#register}
+
+Registrieren Sie einen benutzerdefinierten Kanal von einem beliebigen Server-Plugin.
+
+```ts
+import { registerNotificationChannel } from "@agent-native/core/notifications";
+
+registerNotificationChannel({
+  name: "slack-ops",
+  async deliver(input, meta) {
+    await fetch(process.env.OPS_SLACK_WEBHOOK!, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: `*${input.severity.toUpperCase()}* — ${input.title}\n${input.body ?? ""}`,
+        owner: meta.owner,
+      }),
+    });
+  },
+});
+```
+
+Kanalnamen sind eindeutig – bei einer erneuten Registrierung wird der vorherige Kanal ersetzt. `deliver()` ist Best-Effort; Durch das Auswerfen wird der Fehler protokolliert, andere Kanäle oder die Posteingangszeile werden jedoch nicht blockiert.
+
+### Auflisten und Lesen {#read}
+
+```ts
+import {
+  listNotifications,
+  countUnread,
+  markNotificationRead,
+  markAllNotificationsRead,
+  deleteNotification,
+} from "@agent-native/core/notifications";
+
+const rows = await listNotifications("steve@builder.io", {
+  unreadOnly: true,
+  limit: 50,
+});
+const unread = await countUnread("steve@builder.io");
+await markNotificationRead(rows[0].id, "steve@builder.io");
+await markAllNotificationsRead("steve@builder.io");
+await deleteNotification(rows[0].id, "steve@builder.io");
+```
+
+Jede Funktion unterliegt dem Eigentümerbereich – keine benutzerübergreifenden Lesevorgänge und keine benutzerübergreifenden Schreibvorgänge.
+
+## Die NotificationChannel-Schnittstelle {#channel-interface}
+
+```ts
+interface NotificationChannel {
+  name: string;
+  deliver(
+    input: NotificationInput,
+    meta: NotificationMeta,
+  ): void | Promise<void>;
+}
+
+interface NotificationInput {
+  severity: "info" | "warning" | "critical";
+  title: string;
+  body?: string;
+  metadata?: Record<string, unknown>;
+  channels?: string[];
+}
+
+interface NotificationMeta {
+  owner: string;
+}
+```
+
+## HTTP API {#http}
+
+Wird durch das Core-Routes-Plugin bei `/_agent-native/notifications/*` gemountet. Alle Routen beziehen sich auf die E-Mail-Adresse der authentifizierten Sitzung.
+
+| Methode  | Pfad                                                |
+| -------- | --------------------------------------------------- |
+| `GET`    | `/_agent-native/notifications?unread=true&limit=50` |
+| `GET`    | `/_agent-native/notifications/count`                |
+| `POST`   | `/_agent-native/notifications/:id/read`             |
+| `POST`   | `/_agent-native/notifications/read-all`             |
+| `DELETE` | `/_agent-native/notifications/:id`                  |
+
+```an-api title="List notifications" summary="The route behind listNotifications() — scoped to the authenticated session's email."
+{
+  "method": "GET",
+  "path": "/_agent-native/notifications?unread=true&limit=50",
+  "summary": "List recent notifications for the current user",
+  "auth": "Authenticated session; results are scoped to the session's email.",
+  "params": [
+    { "name": "unread", "in": "query", "type": "boolean", "required": false, "description": "When true, returns only unread notifications." },
+    { "name": "limit", "in": "query", "type": "number", "required": false, "description": "Max rows to return." }
+  ],
+  "responses": [
+    { "status": "200", "description": "Owner-scoped notification rows, newest first." }
+  ]
+}
+```
+
+## UI-Komponente {#ui}
+
+```tsx
+import { NotificationsBell } from "@agent-native/core/client/notifications";
+
+export function HeaderBar() {
+  return (
+    <header className="flex items-center gap-2">
+      {/* … */}
+      <NotificationsBell browserNotifications />
+    </header>
+  );
+}
+```
+
+Glockensymbol mit ungelesenem Abzeichen. Durch Klicken auf wird ein Dropdown-Menü mit den letzten Benachrichtigungen geöffnet. Verwendet semantische Shadcn-Token und passt sich dem Hell-/Dunkel-Thema der Host-Vorlage an.
+
+Übergeben Sie `browserNotifications`, um auch System-Popups `new Notification(...)` für jedes neue ungelesene Element auszulösen – nützlich, wenn sich die Registerkarte des Benutzers im Hintergrund befindet. Das Dropdown-Menü gibt eine „Aktivieren“-Eingabeaufforderung aus, bis der Benutzer die Berechtigung erteilt. Duplikate werden pro ID über das Feld „Benachrichtigung `tag`“ verhindert.
+
+## Agent-Tools {#agent-tools}
+
+In jeder Vorlage ist ein einzelnes `manage-notifications`-Tool registriert. Der Parameter `action` wählt die Operation aus:
+
+| Aktion | Parameter                                                                             | Zweck                                                                                          |
+| ------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `send` | `severity` (erforderlich), `title` (erforderlich), `body`, `metadataJson`, `channels` | Senden Sie eine Benachrichtigung an den Posteingang und die registrierten Kanäle des Benutzers |
+| `list` | `unreadOnly`, `limit` (maximal 200, Standard 20)                                      | Letzte Benachrichtigungen für den Kontext auflisten                                            |
+
+Automatisierungen (siehe [Automations](/docs/automations)) können `manage-notifications` mit `action=send` in ihrem Körper aufrufen – dies ist das kanonische Muster, um ein externes Ereignis in eine für den Benutzer sichtbare Warnung umzuwandeln.
+
+## Ereignisbus {#event-bus}
+
+Jede erfolgreiche Lieferung gibt `notification.sent` auf dem [event bus](/docs/automations#event-bus) aus:
+
+```json
+{
+  "notificationId": "n-123",
+  "severity": "critical",
+  "title": "DB offline",
+  "body": "Primary dropped connections",
+  "deliveredChannels": ["inbox", "webhook"]
+}
+```
+
+Automatisierungen können dies verketten – z.B. _"Wenn eine kritische Benachrichtigung ausgelöst wird, rufen Sie auch den Bereitschaftsdienst an."_
+
+## Wie es funktioniert {#internals}
+
+- **Owner Scoping** – jede Zeile hat eine `owner`-Spalte; jede Abfrage filtert danach; Jede Route verwendet die E-Mail-Adresse der authentifizierten Sitzung. Benutzer sehen nie die Benachrichtigungen der anderen.
+- **Umfrageintegration** – jede Mutation ruft `recordChange()` auf, sodass Vorlagen, die [`useDbSync`](/docs/client) verwenden, ohne zusätzliche Verkabelung automatisch ungültig werden.
+- **Best-Effort-Fanout** – Kanalfehler werden abgefangen und protokolliert; Ein ausgefallener Kanal blockiert nicht andere oder das Schreiben in den Posteingang.
+- **Fire-and-Forget** – `notify()` kehrt zurück, nachdem der Posteingangsschreibvorgang abgeschlossen ist; Benutzerdefinierte Kanäle werden im Hintergrund ausgeführt.
+
+## Was kommt als nächstes
+
+- [**Automations**](/docs/automations) – der häufigste Aufrufer von `notify()`
+- [**Security**](/docs/security) – der `${keys.NAME}`-Ersatz, der den Webhook-Kanal betreibt
+- [**Server plugins**](/docs/server) – wo benutzerdefinierte Kanäle beim Start registriert werden