@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,171 @@
+---
+title: "Agententeams"
+description: "Der Hauptagent delegiert die Arbeit an Unteragenten, die in ihren eigenen Threads ausgeführt werden und als Live-Vorschau-Chips inline im Chat erscheinen."
+---
+
+# Agententeams
+
+Der Agenten-Chat ist ein **Orchestrator**, kein Monolith. Wenn der Hauptagent auf eine Aufgabe trifft, die besser einem Spezialisten obliegt – „diese E-Mail mit meiner Stimme schreiben“, „eine BigQuery-Analyse durchführen“, „diese PR überprüfen“ –, erzeugt er einen Unteragenten in seinem eigenen Thread, seinen eigenen Tools und seinem eigenen Kontext. Der Subagent wird als Live-Vorschau-**Chip** inline im Hauptchat angezeigt; Klicken Sie darauf, um die vollständige Konversation als Tab zu öffnen.
+
+Dadurch bleibt der Hauptthread fokussiert, Unteragenten können parallel ausgeführt werden und Sie erhalten einen sauberen Prüfpfad für alle delegierten Arbeiten.
+
+Agent Teams läuft auf dem Kern-Run-Manager: Ereignisse werden gestreamt und bleiben bestehen, Abbrüche werden über SQL weitergegeben und Aufgaben überleben serverlose Kaltstarts.
+
+## Das mentale Modell {#mental-model}
+
+- **Hauptchat** – der Orchestrator. Liest Ihre Anfrage, Delegierte. Schwere Arbeit erledigt sich selten von selbst.
+- **Subagenten** – werden mit ihrem eigenen Thread, ihrer eigenen Systemeingabeaufforderung und ihrem eigenen Toolset ausgeführt. Jeder ist einem „benutzerdefinierten Agenten“-Profil im [workspace](/docs/workspace) zugeordnet.
+- **Chips** – die umfangreiche Vorschaukarte, die inline im Hauptchat angezeigt wird und den aktuellen Schritt des Subagenten, die Streaming-Ausgabe und die abschließende Zusammenfassung anzeigt. Standardmäßig minimiert; Wird beim Klicken auf die vollständige Konversation erweitert.
+- **Bidirektionale Nachrichtenübermittlung** – der Hauptagent kann Folgenachrichten an einen laufenden Unteragenten senden; Ein Subagent kann eine Nachricht zurücksenden, wenn er einen unklaren Punkt erreicht.
+
+Der Status des Subagenten wird in der Tabelle `application_state` SQL (unter `agent-task:<taskId>`) beibehalten, sodass Aufgaben serverlose Kaltstarts überleben und über mehrere Prozesse hinweg funktionieren.
+
+```an-diagram title="Orchestrator and specialists" summary="The main chat delegates to sub-agents that run in their own threads and report back as inline chips."
+{
+  "html": "<div class=\"at-orc\"><div class=\"diagram-card main\"><span class=\"diagram-pill accent\">Main chat</span><small class=\"diagram-muted\">orchestrator &mdash; reads your request, delegates</small></div><div class=\"at-fan\"><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"at-subs\"><div class=\"diagram-box\">Code review<br><small class=\"diagram-muted\">own thread &amp; prompt</small></div><div class=\"diagram-box\">BigQuery analysis<br><small class=\"diagram-muted\">own tools</small></div><div class=\"diagram-box\">Email in voice<br><small class=\"diagram-muted\">own context</small></div></div></div><div class=\"diagram-pill\">each appears inline as a live chip &#8635;</div></div>",
+  "css": ".at-orc{display:flex;flex-direction:column;align-items:center;gap:12px}.at-orc .diagram-card{padding:14px 18px;display:flex;flex-direction:column;gap:4px;align-items:center}.at-orc .at-fan{display:flex;flex-direction:column;align-items:center;gap:8px}.at-orc .diagram-arrow{font-size:22px}.at-orc .at-subs{display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.at-orc .diagram-box{text-align:center}"
+}
+```
+
+## Wann soll ein Subagent erzeugt werden? {#when-to-spawn}
+
+Erscheint, wenn die Aufgabe:
+
+- Benötigt eine andere **Systemaufforderung** (eine spezielle Stimme oder einen speziellen Ton, z. B. „Codeüberprüfung“).
+- Verfügt über eine **lang laufende** Toolkette, die den Hauptkontext verunreinigen würde.
+- Kann **parallel** mit anderen Aufgaben ausgeführt werden, die der Hauptagent ausführt.
+- Ist im Besitz eines **anderen Teams**, das bereits über ein benutzerdefiniertes Agentenprofil verfügt.
+
+Spawnen Sie nicht für triviale One-Shot-Arbeiten – rufen Sie die Aktion direkt auf.
+
+## Aufrufen eines Subagenten {#invoking}
+
+Drei Möglichkeiten, einen Subagenten zu starten, von der geringsten bis zur explizitesten:
+
+### 1. `@mention` ein benutzerdefinierter Agent {#mention}
+
+Der Benutzer gibt `@agent-name` im Chat-Composer ein. Ein Dropdown-Menü mit Workspace-Subagenten wird angezeigt. Wenn Sie eines auswählen, wird ein Chip eingefügt. Beim Senden delegiert der Hauptagent die Nachricht an diesen Unteragenten.
+
+Benutzerdefinierte Agenten befinden sich im Arbeitsbereich von `agents/<slug>.md` – einer Markdown-Datei mit YAML-Frontmatter. Informationen zum Format finden Sie unter [Custom Agents](/docs/workspace#custom-agents).
+
+### 2. Der Hauptagent delegiert automatisch {#auto-delegate}
+
+Das Framework stellt dem Hauptagenten ein `agent-teams`-Tool zur Verfügung. Wenn das Modell entscheidet, dass eine Aufgabe zu einem registrierten Subagentenprofil passt, ruft es das Tool mit `action: "spawn"` und einem optionalen `agent`-Parameter auf, der ein Profil von `agents/*.md` benennt. Ein Chip erscheint; Der Subagent wird ausgeführt. Der Hauptagent wartet (oder geht parallel weiter) und übernimmt das Ergebnis, wenn der Unteragent fertig ist.
+
+Der vollständige `agent-teams`-Aktionssatz ist:
+
+| Aktion        | Zweck                                                     |
+| ------------- | --------------------------------------------------------- |
+| `spawn`       | Starten Sie eine neue Subagentenaufgabe                   |
+| `status`      | Überprüfen Sie den Fortschritt eines laufenden Subagenten |
+| `read-result` | Erhalten Sie die Ausgabe eines fertigen Subagenten        |
+| `send`        | Eine Nachricht an einen laufenden Subagenten senden       |
+| `list`        | Alle Aufgaben für den aktuellen Benutzer anzeigen         |
+
+### 3. Programmatischer Spawn {#programmatic-spawn}
+
+Für Integrationen auf Framework-Ebene verwenden Sie `spawnTask()` von `@agent-native/core/server`:
+
+```ts
+import { spawnTask } from "@agent-native/core/server";
+
+const task = await spawnTask({
+  description: "Draft an outreach email to this lead",
+  instructions: "Match Steve's voice from memory/MEMORY.md.",
+  ownerEmail: user.email,
+  systemPrompt: mailAgentSystemPrompt,
+  actions: mailActions,
+  // Pass either apiKey or engine — engine takes precedence.
+  apiKey: process.env.ANTHROPIC_API_KEY, // optional if engine is provided
+  parentSend: emit, // streaming sender for the parent chat response
+});
+```
+
+Der meiste App-Code ruft dies nicht direkt auf – das Framework erledigt dies unter der Haube für `@mentions` und für das `agent-teams`-Tool. Greifen Sie nach `spawnTask()` nur, wenn Sie einen neuen Einstiegspunkt verknüpfen (z. B. eine Schaltfläche, die einen Hintergrundjob startet, der als Subagent ausgeführt wird).
+
+## Aufgabenlebenszyklus {#lifecycle}
+
+```an-diagram title="What spawnTask() does" summary="Each spawn creates a thread, persists state to SQL, and streams chip events through to completion."
+{
+  "html": "<div class=\"at-life\"><div class=\"diagram-box\"><code>spawnTask()</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">create thread</span><small class=\"diagram-muted\">new row in <code>chat_threads</code>, description as first message</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">persist state</span><small class=\"diagram-muted\"><code>agent-task:&lt;id&gt;</code> &rarr; <code>application_state</code>, status=running</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">stream</span><small class=\"diagram-muted\"><code>agent_task_started</code> &rarr; chip appears; <code>agent_task_step</code> &rarr; chip updates live</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card ok\"><span class=\"diagram-pill ok\">complete</span><small class=\"diagram-muted\">status=completed, write summary + preview, emit <code>agent_task_done</code></small></div></div>",
+  "css": ".at-life{display:flex;flex-direction:column;align-items:stretch;gap:6px;max-width:560px}.at-life .diagram-card{display:flex;flex-direction:column;gap:3px;padding:10px 14px}.at-life .diagram-box{align-self:flex-start}.at-life .diagram-arrow{font-size:18px;align-self:center}"
+}
+```
+
+Der übergeordnete Agent kann den Subagenten jederzeit mit einer Nachverfolgung über `sendToTask(taskId, message)` fortsetzen. Wenn der Subagent einen Fehler macht, zeichnet `markTaskErrored(taskId, reason)` den Fehler auf und zeigt ihn dem Benutzer an.
+
+Zwei-Wege-Nachrichtenübermittlung ist dauerhaft. Übergeordnete Folgemaßnahmen für laufende Unteragenten sind
+wird während des Aufgabenlebenszyklus bereitgestellt; wenn der Subagent sie nicht verarbeiten kann
+Im aktuellen Schritt sollten sie in der Warteschlange bleiben und an einem Safe angewendet werden
+Fortsetzungspunkt. Unteragenten können auch eine Nachricht zurückschicken, wenn sie eine Klärung benötigen
+anstatt unsichtbar zu blockieren.
+
+## Aufgabenstatus lesen {#reading-state}
+
+Aus Servercode oder anderem actions:
+
+```ts
+import { getTask, listTasks } from "@agent-native/core/server";
+
+const task = await getTask(taskId); // single task
+const tasks = await listTasks(); // all tasks for the user (sorted newest first)
+```
+
+Schlüsselfelder `AgentTask`:
+
+```ts
+interface AgentTask {
+  taskId: string;
+  threadId: string;
+  description: string;
+  status: "running" | "completed" | "errored";
+  preview: string; // short one-liner for the chip
+  summary: string; // full summary once completed
+  currentStep: string; // latest step label (updated while running)
+  createdAt: number;
+  // Additional fields: parentThreadId, name, updatedAt, startedAt,
+  // completedAt, runId, error
+}
+```
+
+## Benutzerdefinierte Agentenprofile {#profiles}
+
+Subagenten werden benutzerdefinierten Agentenprofilen zugeordnet – Markdown-Dateien unter `agents/<slug>.md` im Arbeitsbereich, die im `@mention`-Dropdown-Menü angezeigt werden und als Delegierungsziele dienen. [Workspace — Custom Agents](/docs/workspace#custom-agents) besitzt das vollständige Format (Frontmatter, `tools`, `delegate-default`, Modellüberschreibungen).
+
+## Delegationstiefenschutz {#depth-guard}
+
+Unteragenten können Unteragenten hervorbringen, was ein unkontrolliertes/Kostenrisiko darstellt: Eine unbegrenzte Kette von Delegationen könnte sich auf unbestimmte Zeit ausbreiten. Das Framework erzwingt eine **feste Obergrenze für die Delegationstiefe**, serverseitig, unabhängig von etwaigen Schutzmaßnahmen auf Toolebene.
+
+Der Chat der obersten Ebene hat die Tiefe `0`. Ein von ihm erzeugter Subagent ist die Tiefe `1`; dieser Subagent kann noch einmal spawnen (Tiefe `2`); Ein Spawn, der einen Depth-`3`-Subagenten erstellen würde, wird **abgelehnt**. Die Standardobergrenze beträgt **2**.
+
+```an-diagram title="Delegation depth guard (default cap 2)" summary="Each level may spawn one deeper until the cap; a spawn past it is refused server-side."
+{
+  "html": "<div class=\"at-depth\"><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 0</span><strong>Top-level chat</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card ok\"><span class=\"diagram-pill\">depth 1</span><strong>Sub-agent</strong><small class=\"diagram-muted ok\">may spawn &darr;</small></div><div class=\"diagram-card warn\"><span class=\"diagram-pill warn\">depth 2</span><strong>Sub-agent's sub-agent</strong><small class=\"diagram-muted\">at the cap &mdash; may NOT spawn</small></div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">depth 3</span><strong>Refused</strong><small class=\"diagram-muted\">server-side error</small></div></div>",
+  "css": ".at-depth{display:flex;flex-direction:column;gap:8px}.at-depth .diagram-card{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.at-depth .rung-1,.at-depth .diagram-card:nth-child(2){margin-inline-start:24px}.at-depth .diagram-card:nth-child(3){margin-inline-start:48px}.at-depth .diagram-card:nth-child(4){margin-inline-start:72px}"
+}
+```
+
+Die Durchsetzung erfolgt in der Umgebung: Jeder Subagent läuft in einem `AsyncLocalStorage`, der seine eigene Tiefe aufzeichnet. Daher liest jeder von diesem Lauf transitiv erreichte `spawnTask` die Tiefe seines übergeordneten Agenten und weigert sich, sobald die Obergrenze erreicht wird – selbst wenn das `agent-teams`-Tool an einen Subagenten übergeben wurde, der es nicht hätte haben sollen. Die Entscheidung wird als reines, einheitlich testbares `evaluateSubagentDepth(parentDepth)` dargestellt. Ein verweigerter Spawn gibt einen eindeutigen Fehler zurück: _"Delegationstiefenlimit erreicht (max. N); es kann kein weiterer Subagent gespawnt werden."_
+
+### Obergrenze konfigurieren {#depth-guard-config}
+
+Überschreiben Sie die Standardeinstellung zum Zeitpunkt der Bereitstellung mit `AGENT_NATIVE_MAX_SUBAGENT_DEPTH`:
+
+| Wert              | Effekt                                                                                                                                                                 |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(nicht gesetzt)_ | Standardobergrenze von `2`.                                                                                                                                            |
+| `0`               | **Es dürfen keine Unteragenten erzeugt werden** – der Agent der obersten Ebene erledigt die gesamte Arbeit.                                                            |
+| `1`…`16`          | So viele Delegationsebenen.                                                                                                                                            |
+| ungültig / `>16`  | Ein nicht ganzzahliger / negativer / NaN-Wert fällt auf `2` zurück; Alles über `16` wird an `16` geklemmt, sodass ein Tippfehler niemals den Schutz deaktivieren kann. |
+
+```bash
+AGENT_NATIVE_MAX_SUBAGENT_DEPTH=1   # sub-agents allowed, but they can't sub-delegate
+```
+
+Wenn ein Subagent die Obergrenze erreicht oder unterschreitet, fügt das Framework eine Zeile in seinen Laufzeitkontext ein, die ihm mitteilt, wie tief er sitzt und ob er weiter delegieren darf, damit das Modell sein Budget angemessen ausgibt.
+
+## Was kommt als nächstes?
+
+- [**Workspace — Custom Agents**](/docs/workspace#custom-agents) – das Profilformat
+- [**A2A Protocol**](/docs/a2a-protocol) – wenn der „Subagent“ vollständig in einer anderen App lebt
+- [**Actions**](/docs/actions) – die Tools, die ein Subagent aufruft

package/corpus/core/docs/content/locales/de-DE/agent-web-surfaces.md

@@ -0,0 +1,161 @@
+---
+title: "Public Agent Web"
+description: "Machen Sie öffentliche Routen crawlbar, lesbar, zitierbar und optional für Agenten aufrufbar – robots.txt, llms.txt, Markdown Mirrors, JSON-LD und eine öffentliche MCP-Oberfläche."
+---
+
+# Public Agent Web
+
+Das öffentliche Agenten-Web erleichtert Agenten das Crawlen, Lesen, Zitieren und Anrufen öffentlicher Agent-Native-Routen. Das Ziel besteht nicht darin, jeden App-Endpunkt öffentlich zu machen. Ziel ist es, eine saubere öffentliche Oberfläche für bereits öffentliche Seiten zu veröffentlichen und gleichzeitig den Zugriff auf private Daten und Tools einer expliziten Kontrolle zu unterziehen.
+
+Die Dokumentationsseite ist die Referenzimplementierung. Heute wird Folgendes ausgeliefert:
+
+- `/robots.txt` mit einer Crawler-Richtlinie, die den Abruf erlaubt, aber das Training standardmäßig nicht zulässt.
+- `/sitemap.xml` mit absolut kanonischen URLs und `lastmod`, wenn die Quelldatei es verfügbar macht.
+- `/llms.txt` und `/llms-full.txt` für agentenfreundliche Inhaltserkennung.
+- Markdown spiegelt wie `/docs/getting-started.md` wider.
+- `Accept: text/markdown`-Antworten für öffentliche Dokumentseiten nach einem Produktions-Build.
+- JSON-LD für Basisorganisation, Website und Seitenmetadaten.
+- Ein Audit CLI (`npx @agent-native/core@latest audit-agent-web`), das alle oben genannten Punkte überprüft.
+
+Durch das Festlegen von `publicMcp: true` wird zusätzlich der optierte actions als öffentlicher MCP-Endpunkt verfügbar gemacht, sodass externe Agenten ihn direkt aufrufen können (siehe [MCP Protocol](/docs/mcp-protocol)).
+
+```an-diagram title="What a public route publishes" summary="A public route fans out into agent-friendly representations. Reading the route is separate from calling tools — tool access stays opt-in."
+{
+  "html": "<div class=\"diagram-web\"><div class=\"diagram-box\" data-rough>Public route<br><small class=\"diagram-muted\">derived from route access settings</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-grid\"><span class=\"diagram-pill\">robots.txt</span><span class=\"diagram-pill\">sitemap.xml</span><span class=\"diagram-pill\">llms.txt</span><span class=\"diagram-pill\">.md mirror</span><span class=\"diagram-pill\">JSON-LD</span><span class=\"diagram-pill\">text/markdown</span></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col gate\"><span class=\"diagram-pill warn\">Tools stay private</span><small class=\"diagram-muted\">publicMcp + publicAgent.expose required</small></div></div>",
+  "css": ".diagram-web{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-web .diagram-arrow{font-size:22px;line-height:1}.diagram-web .diagram-grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px}.diagram-web .gate{display:flex;flex-direction:column;gap:4px;align-items:flex-start}"
+}
+```
+
+## Konfiguration {#config}
+
+Fügen Sie `agentWeb` unter der vorhandenen Workspace-App-Konfiguration hinzu (im `package.json` Ihrer App unter dem Schlüssel `agent-native` – oder entsprechend `workspace.agentWeb`, `agentWeb` oder `root.agentWeb`). Die öffentliche Routenliste wird weiterhin von den Routenzugriffseinstellungen der App abgeleitet; `agentWeb` steuert, wie diese öffentliche Oberfläche den Agenten dargestellt wird.
+
+```json
+{
+  "agent-native": {
+    "workspaceApp": {
+      "audience": "public",
+      "protectedPaths": ["/admin/*"],
+      "agentWeb": {
+        "discoverable": true,
+        "markdownTwins": true,
+        "llmsTxt": true,
+        "jsonLd": true,
+        "publicAgentCard": true,
+        "publicMcp": false,
+        "crawlerPolicy": "discoverable-no-training",
+        "crawlers": {
+          "training": "disallow",
+          "search": "allow",
+          "userTriggered": "allow",
+          "codingAgents": "allow",
+          "autonomousAgents": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+Lassen Sie bei den meisten Apps die Standardeinstellungen unverändert. Wenn eine App über eine öffentliche Route verfügt, ist `discoverable` standardmäßig aktiviert. Die Standard-Crawler-Richtlinie ist „erkennbar, nicht trainierbar“: Suche, vom Benutzer ausgelöster Abruf, Codierungsagenten und autonome Browsing-Agenten sind zulässig; Trainings-Crawler sind nicht zulässig.
+
+## Quelle der Wahrheit weiterleiten {#route-source}
+
+Agent Web Discovery folgt dem Routenzugriffsmodell:
+
+- Öffentliche Apps machen jede Route außer `protectedPaths` verfügbar.
+- Interne Apps machen nur `publicPaths` verfügbar.
+- Öffentliche Freigabe- und Formularseiten können von Agenten gelesen werden.
+- Übermittelte private Daten, authentifizierte Dashboards und Benutzer-/Organisationsstatus werden niemals berücksichtigt, nur weil eine Seite in der Nähe öffentlich ist.
+
+Dadurch bleiben gemischte Apps natürlich. Eine Formular-App kann eine öffentliche Formularseite verfügbar machen und Übermittlungen privat halten. Eine Content-App kann veröffentlichte Beiträge offenlegen und den Herausgeber privat halten. Eine Dokumentenseite kann alles außer Verwaltungstools offenlegen.
+
+## Öffentliche Seiten sind keine öffentlichen Tools {#public-tools}
+
+Der Zugriff auf öffentliche Seiten und der Zugriff auf öffentliche Tools sind getrennt. Eine öffentliche Route bedeutet nur, dass Agenten diese Route als HTML, Markdown, Sitemap-Einträge, LMS-Einträge und strukturierte Daten lesen können.
+
+```an-callout
+{
+  "tone": "warning",
+  "body": "**A public page is not a public tool.** Making a route crawlable never exposes an action. Tool access requires an explicit `publicAgent.expose` opt-in on the action *and* `publicMcp: true` on the app."
+}
+```
+
+Um eine Aktion über ein öffentliches Agentenprotokoll verfügbar zu machen, muss die Aktion Folgendes aktivieren:
+
+```an-annotated-code title="Opting one safe action onto the public surface"
+{
+  "filename": "actions/search-docs.ts",
+  "language": "ts",
+  "code": "export default defineAction({\n  description: \"Search published docs\",\n  readOnly: true,\n  publicAgent: {\n    expose: true,\n    readOnly: true,\n    requiresAuth: false,\n    isConsequential: false,\n    title: \"Search published docs\",\n  },\n  run: async (args) => {\n    // ...\n  },\n});",
+  "annotations": [
+    { "lines": "4", "label": "Explicit opt-in", "note": "Without `publicAgent.expose === true`, the action never appears on any public agent surface — no matter how public its routes are." },
+    { "lines": "5-7", "label": "Self-describe safety", "note": "Mark it read-only, declare whether it needs auth, and flag whether it is consequential. Public MCP excludes consequential/write actions unless policy explicitly allows them." }
+  ]
+}
+```
+
+`agentWeb.publicMcp` bleibt standardmäßig `false`. Wenn öffentliches MCP aktiviert ist, sollte der Server nur actions mit `publicAgent.expose === true` verfügbar machen und weiterhin Folge- oder Schreib-actions ausschließen, es sei denn, die Aktion und die Authentifizierungsrichtlinie erlauben dies ausdrücklich.
+
+## Dateien zur Erstellungszeit {#build-time}
+
+Framework-Dienstprogramme in `@agent-native/core/agent-web` generieren die gemeinsamen Dateien aus einer Seitenliste:
+
+```ts
+import {
+  buildAgentWebStaticFiles,
+  normalizeAgentWebConfig,
+} from "@agent-native/core/agent-web";
+
+const config = normalizeAgentWebConfig(
+  { crawlerPolicy: "discoverable-no-training" },
+  { hasPublicRoutes: true },
+);
+
+const files = buildAgentWebStaticFiles({
+  siteName: "My Agent-Native App",
+  siteUrl: "https://example.com",
+  description: "Public docs for my app.",
+  config,
+  pages: [
+    {
+      path: "/docs",
+      title: "Docs",
+      description: "Start here.",
+      markdown: "# Docs\n\nStart here.\n",
+      markdownPath: "/docs/getting-started.md",
+      lastmod: new Date(),
+    },
+  ],
+});
+```
+
+Vite-Apps können `createAgentWebVitePlugin` von `@agent-native/core/vite` verwenden, um diese Dateien während Produktionsbuilds in `public`, `dist`, `dist/client`, `dist/server/public` oder `build/client` zu schreiben.
+
+## Eine Website prüfen {#audit}
+
+Verwenden Sie die CLI-Prüfung für einen bereitgestellten Standort oder einen lokalen Produktionsserver:
+
+```bash
+npx @agent-native/core@latest audit-agent-web --url https://www.agent-native.com
+```
+
+Die Prüfung prüft auf:
+
+- SSR-sichtbares HTML.
+- Kanonische URLs.
+- JSON-LD.
+- `robots.txt`-Richtlinie und absolute Sitemap URL.
+- Absolute Sitemap-Einträge.
+- `/llms.txt` und `/llms-full.txt`.
+- Markdown Spiegel.
+- `Accept: text/markdown`.
+- Keine versehentlichen 401/403-Blockierungen für allgemeine Agentenabruf-Benutzeragenten.
+
+Die Prüfung endet mit einem Wert ungleich Null, wenn eine erforderliche öffentliche Oberfläche fehlt.
+
+## Was kommt als nächstes?
+
+- [**Actions**](/docs/actions) – So aktivieren Sie actions für das öffentliche Agentenprotokoll
+- [**MCP Protocol**](/docs/mcp-protocol) – die MCP-Oberfläche, die `publicMcp: true` aktiviert
+- [**Deployment**](/docs/deployment) – wohin diese statischen Dateien während Builds geschrieben werden

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

@@ -0,0 +1,111 @@
+---
+title: "Audit-Protokoll"
+description: "Eine dauerhafte, nur anhängbare Aufzeichnung darüber, wer welche App-Daten wann geändert hat und ob Sie oder der Agent es waren – automatisch erfasst, wenn die Aktion ausgeführt wird."
+---
+
+# Audit-Protokoll
+
+Jede agentennative App erhält sofort ein Audit-Protokoll: eine dauerhafte, vollständige, zugriffsbezogene, nur anhängbare Aufzeichnung darüber, wer welche App-Daten wann, von wo und – wenn es der Agent war – in welcher Ausführung geändert hat.\*\* Die Erfassung erfolgt automatisch an der Aktionsstelle; Sie schreiben keinen Code dafür.
+
+Da der Agent Daten in Ihrem Namen ändern kann, lautet die Hauptfrage, die ein Audit-Protokoll hier beantwortet, nicht nur „Wer hat diesen Datensatz bearbeitet?“ – sondern **„War das ich oder der Agent und wer hat das verursacht?“** Kein anderes System im Framework kann das beantworten.
+
+## Audit vs. Beobachtbarkeit vs. Nachverfolgung {#which}
+
+Drei Systeme zeichnen aus drei verschiedenen Gründen auf, „was passiert ist“. Wählen Sie die Frage aus, die Sie stellen:
+
+| System                                   | Die Frage, die es beantwortet                                  | Treue                                 | Zielgruppe                                |
+| ---------------------------------------- | -------------------------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| **Audit-Protokoll** (diese Seite)        | „Wer hat diesen Datensatz wann geändert und war es der Agent?“ | **Vollständig, langlebig, umfassend** | Benutzer, Administrator, der Agent selbst |
+| **[Observability](/docs/observability)** | „Warum hat der Agent das getan und was hat es gekostet?“       | Gesamte Spannentelemetrie             | Entwickler                                |
+| **[Tracking](/docs/tracking)**           | „Wie verwenden die Leute das Produkt?“                         | Fire-and-Forget zu externem SaaS      | PM / Wachstum                             |
+
+Ein Prüfprotokoll, das als Stichprobe erstellt oder an einen Analyseanbieter gesendet wird, ist nutzlos – der springende Punkt ist, dass es vollständig, lokal und abfragbar ist. Es handelt sich also um ein eigenes Subsystem, nicht um einen Modus der anderen beiden.
+
+## Was automatisch erfasst wird {#captured}
+
+Wenn eine **mutierende** Aktion ausgeführt wird (alles, was kein schreibgeschütztes `GET` ist), hängt das Framework eine Zeile an `agent_audit_log` an mit:
+
+- **Aktion** – der Aktionsname (z. B. `delete-recording`).
+- **Akteur** – `agent`, `human` oder `system`, plus die E-Mail-Adresse des Schauspielers – wird **auch für Agentenanrufe** ausgefüllt, sodass Sie „der Agent, der für Alice@ handelt, …“ erhalten.
+- **Run linkage** – der Agent `threadId` / `turnId`, der den Aufruf (einen Tool-Aufruf) ausgelöst hat, sodass eine Mutation auf den genauen Agentenzug zurückgeführt werden kann.
+- **Oberfläche** – `tool` (Agent), `frontend`, `http`, `cli`, `mcp` oder `a2a`.
+- **Ergebnis** – `success`, `error` (mit einem Fehlercode) oder `denied` (durch ein menschliches Genehmigungstor blockiert).
+- **Eingaben** – die Aufrufargumente mit anmeldeinformationsförmigen Werten [redacted](#privacy).
+- **Ziel und Eigentümer** – die Ressource, die durch die Aktion geändert wurde, verwendet für [scope reads](#reading).
+
+Keine Verkabelung erforderlich – die Erfassung wird transparent in `defineAction` eingehängt. Schreibgeschützte actions werden übersprungen, und einige Hochfrequenz-Frameworks actions (App-State-Synchronisierung, Kontext-Röntgen, Navigation) werden standardmäßig übersprungen, um eine Überflutung des Protokolls zu vermeiden.
+
+## Erklären Sie, was eine Aktion geändert hat {#target}
+
+Standardmäßig ist ein Ereignis auf den **Akteur** beschränkt – Sie sehen Ihre eigenen Änderungen und die Änderungen des Agenten in Ihrem Namen. Um eine Änderung an einer _gemeinsamen_ Ressource auch im Trail des **Eigentümers** anzuzeigen und um Ereignisse nach Ressource zu kennzeichnen, deklarieren Sie ein `target`:
+
+```ts
+export default defineAction({
+  description: "Delete a recording.",
+  schema: z.object({ id: z.string() }),
+  audit: {
+    target: (args, result) => ({
+      type: "recording",
+      id: args.id,
+      // Optional — defaults to the actor. Set when editing someone else's resource.
+      ownerEmail: result?.ownerEmail,
+      visibility: "org",
+    }),
+    summary: (args) => `Deleted recording ${args.id}`,
+  },
+  run: async (args, ctx) => {
+    /* ...delete... */
+  },
+});
+```
+
+Alles in `audit` ist optional. Der minimale nützliche Zusatz ist `target: () => ({ type, id })`.
+
+### Tuning-Aufnahme {#tuning}
+
+| Option               | Effekt                                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------ |
+| `audit.target`       | Beschriften Sie das Ereignis mit der Ressource und dem Bereich, den es seinem Besitzer vorliest. |
+| `audit.summary`      | Eine kurze, für Menschen lesbare Zeile für das Ereignis.                                         |
+| `audit.onRead`       | Überprüfen Sie einen vertraulichen **Lesevorgang** (geheimer Zugriff, Massenexport).             |
+| `audit.enabled`      | `true` erzwingt die Erfassung; `false` verzichtet auf eine laute Mutation.                       |
+| `audit.recordInputs` | `false` überspringt die Erfassung der (bereits redigierten) Argumente.                           |
+
+## Die Spur lesen {#reading}
+
+Zwei gelesene actions stehen dem Agenten **und** dem Frontend in jeder App zur Verfügung, in SQL auf den Anrufer beschränkt – sie geben niemals die Zeilen eines anderen Mandanten zurück:
+
+- **`list-audit-events`** – Filter nach `targetType` / `targetId`, `actorKind` (`agent` | `human` | `system`), `status`, `threadId` / `turnId`, `action`, `sinceMs` und `limit`.
+- **`get-audit-event`** – ein Ereignis nach ID, einschließlich seiner redigierten Eingabenutzlast.
+
+Erstellen Sie einen Aktivitäts-Feed oder eine „Wer hat das geändert“-Zeile, indem Sie `list-audit-events` vom UI mit `useActionQuery` aufrufen – schreiben Sie niemals einen Abruf in die Prüftabelle von Hand:
+
+```tsx
+import { useActionQuery } from "@agent-native/core/client";
+
+const { data } = useActionQuery("list-audit-events", {
+  targetType: "recording",
+  targetId: recordingId,
+});
+// data.events → [{ action, actorKind, actorEmail, turnId, status, summary, createdAt }, …]
+```
+
+Der Agent kann dieselbe Aktion aufrufen – fragen Sie ihn: „Was haben Sie an dieser Aufzeichnung geändert?“ und es antwortet von der Spur.
+
+## Datenschutz und Aufbewahrung {#privacy}
+
+- **Redaktion** – bevor Eingaben gespeichert werden, werden anmeldeinformationsförmige Schlüssel und Werte (Tokens, Geheimnisse, Passwörter, Trägerzeichenfolgen) entfernt und übergroße Nutzlasten abgeschnitten. Das Audit-Protokoll wird niemals zu einem sekundären Speicher für Geheimnisse. Halten Sie auch den `summary`-Text frei von sensiblen Daten.
+- **Nur anhängen** – es gibt keine Aktualisierungs- oder Löschaktion für Prüfzeilen. Die einzige Löschung ist die Aufbewahrungsbereinigung, die das Protokoll als Prüfpfad vertrauenswürdig macht.
+- **Mandantenisolation** – Lesevorgänge sind auf die Identität und Organisation des Aufrufers beschränkt; Ohne Identität stimmt nichts überein.
+
+Über Umgebung konfigurieren:
+
+- `AGENT_NATIVE_AUDIT_RETENTION_DAYS` – wie lange Zeilen aufbewahrt werden (Standard `365`; `0` = für immer behalten).
+- `AGENT_NATIVE_AUDIT_ENABLED=false` – globaler Kill-Schalter.
+
+## Was kommt als nächstes?
+
+- [**Actions**](/docs/actions) – die `defineAction`-Naht, an der die Erfassung erfolgt
+- [**Human-in-the-Loop Approvals**](/docs/human-approval) – geschlossenes actions, aufgezeichnet als `denied`
+- [**Security & Data Scoping**](/docs/security) – Die Prüfung des Eigentumsmodells liest Wiederverwendung
+- [**Observability**](/docs/observability) – vom Agenten ausgeführte Telemetrie (das andere „was passiert ist“)