@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,83 @@
+---
+title: "Blueprint-Installer"
+description: "agent-native add druckt ein kuratiertes Markdown-Integrationsrezept auf stdout – leiten Sie es an Ihren Codierungsagenten weiter, der die Änderungen auf Ihr Live-Repository anwendet."
+---
+
+# Blueprint-Installationsprogramm
+
+> **Für wen ist das gedacht:** Hostautoren und Integratoren, die einen Anbieter, einen Kanal hinzufügen
+> Sandbox-Backend oder Aktion an ein Repo durch Weiterleiten eines Rezepts an den Codierungsagenten.
+
+`agent-native add` ist **kein** dummer Gerüstbauer, der Dateien für Sie schreibt. Es gibt einen kuratierten Markdown-_Integrationsentwurf_ an stdout aus. Sie leiten diesen Entwurf an Ihren eigenen Codierungsagenten weiter (Claude-Code, Codex, …), der die Änderungen mit vollständigem Kontext auf das Live-Repository anwendet.
+
+Dies passt zum Hausstil „Agent wendet Änderungen an, Dateisystem zuerst“: Das Framework liefert das Rezept (die zu berührenden kanonischen Dateien, die zu beachtenden Regeln, den Überprüfungsschritt), und der Codierungsagent übernimmt die Bearbeitung.
+
+```bash
+agent-native add provider stripe | claude
+agent-native add channel discord  | codex
+```
+
+```an-diagram title="add prints a recipe; your coding agent applies it" summary="agent-native emits a Markdown blueprint to stdout (diagnostics to stderr); you pipe it into Claude Code or Codex, which edits your live repo with full context."
+{
+  "html": "<div class=\"diagram-bp\"><div class=\"diagram-node\" data-rough>agent-native add<br><small class=\"diagram-muted\">&lt;kind&gt; &lt;name|URL&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Markdown blueprint<br><small class=\"diagram-muted\">stdout · files to touch · rules · Verify</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>Coding agent<br><small class=\"diagram-muted\">claude · codex</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill ok\">edits your live repo</div></div>",
+  "css": ".diagram-bp{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-bp .diagram-arrow{font-size:22px;line-height:1}.diagram-bp .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Verwendung {#usage}
+
+```bash
+agent-native add <kind> <name>            # print a curated blueprint
+agent-native add <kind> <https://docs…>   # research-and-integrate from a URL
+agent-native add --list                   # list available kinds and blueprints
+```
+
+- Ein bloßer **Name** löst eine kuratierte Blaupause von `blueprints/<kind>/<name>.md` auf.
+- Ein **URL** anstelle eines Namens gibt einen generischen \_Forschungs-und-Integrations-Plan für diese Art aus, mit eingebettetem URL als Forschungsstartpunkt (ein URL ist ein Forschungssamen, kein bekanntes Rezept).
+- Der Blueprint geht an **stdout**; Die Diagnose geht an stderr, sodass `… | claude` immer nur den Bauplan erhält.
+
+## Gesäte Blaupausen {#seeded}
+
+`agent-native add --list` zeigt, was im Lieferumfang enthalten ist:
+
+| Freundlich | Name      | Was es einrichtet                                                                                                 |
+| ---------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `provider` | `stripe`  | Verbinden Sie einen Anbieter mit dem `provider-api`-Substrat (Katalog/Dokumente/Anfrage-Trio).                    |
+| `channel`  | `discord` | Implementieren Sie einen eingehenden Webhook-Kanal `PlatformAdapter` und registrieren Sie ihn.                    |
+| `sandbox`  | `docker`  | Implementieren Sie den `SandboxAdapter`-Seam, um `run-code` in einem Docker-Container auszuführen.                |
+| `action`   | `crud`    | Fügen Sie ein einzelnes `defineAction` mit mehreren Oberflächen und einem Zod-Schema hinzu (ein `update` über N). |
+
+Jeder Blueprint ist in sich geschlossen: Der Codierungsagent, der ihn liest, erhält die Dateien zum Anfassen, die Framework-Regeln zum Einhalten (actions sind die einzige Quelle der Wahrheit, niemals Geheimnisse fest codieren, besitzbare Daten erfassen, einen Änderungssatz für die `packages/*`-Quelle hinzufügen) und einen konkreten Abschnitt **Überprüfen**.
+
+## URL → Forschungsplan {#url}
+
+Wenn Sie einen URL bestehen, für den der Typ kein kuratiertes Rezept hat (oder eine neue Integration wünscht), gibt `add` einen generischen „Forschungs- und Integrations“-Entwurf mit dem URL als Ausgangspunkt aus:
+
+```bash
+agent-native add provider https://docs.example.com/api | claude
+```
+
+Der generierte Blueprint weist den Coding-Agent an, das URL (und die Seiten, auf die es verweist) für die tatsächlichen Endpunkte, das Authentifizierungsmodell, die Nutzlastformen und die Signatur-/Verifizierungsanforderungen abzurufen – _nicht_ aus Trainingsdaten zu erraten – und dann zu implementieren und zu überprüfen. Es verfügt auch über artspezifische Führung (z. B. wird ein `provider` URL auf das `provider-api`-Substrat gelenkt; ein `channel` URL auf ein `PlatformAdapter`).
+
+## Hinzufügen Ihrer eigenen Blaupause {#authoring}
+
+Legen Sie eine Markdown-Datei in `packages/core/blueprints/<kind>/<name>.md` ab. Die Art ist das Unterverzeichnis; Der Name ist der Dateiname ohne `.md`. Es wird automatisch erfasst – `--list`, Namensauflösung und der Katalog lesen das Verzeichnis zur Laufzeit. Für die Registrierung ist keine Codeänderung erforderlich.
+
+Blueprint-`.md`-Dateien werden im veröffentlichten Paket über den `blueprints`-Eintrag in `package.json` `files` ausgeliefert, sodass sie für Endbenutzer bei `node_modules/@agent-native/core/blueprints/**` aufgelöst werden.
+
+Schreiben Sie jeden Blueprint als Befehlssatz für einen Codierungsagenten ohne anderen Kontext. Ein guter Bauplan hat:
+
+1. **Ein einzeiliges Ziel** und die Formulierung „Sie sind ein Programmieragent in einer agentennativen App, wenden Sie diese als echte Quelländerungen an.“
+2. **Zuerst lesen** – die genauen Dateien, die den Vertrag darstellen.
+3. **Dateien zum Anfassen** – konkrete Pfade und was jede Änderung bewirkt.
+4. **Framework-Regeln, die eingehalten werden müssen** – actions-first, keine fest codierten Geheimnisse, besitzbare Daten, einen Änderungssatz für die Quelle des veröffentlichbaren Pakets hinzufügen.
+5. **Verify** – Typprüfung, ein fokussierter `*.spec.ts` und eine End-to-End-Prüfung.
+
+> [!TIP]
+> Ein neuer kuratierter Entwurf unter einem vorhandenen Typ benötigt keinen Code – aber wenn Sie ein brandneues Typverzeichnis erstellen, wird dieser Typ automatisch auch in `--list` angezeigt.
+
+## Was kommt als nächstes?
+
+- [**Sandbox Adapters**](/docs/sandbox-adapters) – die Naht, auf die der `add sandbox docker`-Bauplan abzielt
+- [**Actions**](/docs/actions) – die einzige Quelle der Wahrheit, auf der jede Blaupause aufbaut
+- [**External Agents**](/docs/external-agents) – Verbindung des Codierungsagenten, in den Sie Blaupausen einspeisen

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

@@ -0,0 +1,129 @@
+---
+title: "CLI-Adapter"
+description: "Gewähren Sie dem Agenten strukturierten Zugriff auf jedes CLI-Tool (gh, ffmpeg, Stripe) über eine Standardadapterschnittstelle – eine der beiden im Adapterhandbuch behandelten Adapterschnittstellen."
+---
+
+# CLI-Adapter
+
+> **Wo das passt:** CLI-Adapter sind eine von zwei Adapternähten im
+> -Framework. Der kanonische Leitfaden ist [Adapters](/docs/sandbox-adapters), der
+> deckt sowohl diese Naht als auch die `run-code`-Sandbox-Naht ab – einschließlich der gemeinsamen
+> Edge-/serverlose Einschränkung. Diese Seite ist die Kurzreferenz für die CLI-Seite.
+
+Ein CLI-Adapter umschließt ein einzelnes Befehlszeilentool (`gh`, `ffmpeg`, `stripe`, `aws`), sodass der Agent es erkennen, prüfen kann, ob es installiert ist, und es mit einem konsistenten stdout/stderr/exit-code-Ergebnis ausführen kann. Ohne diese Naht erfindet jedes Skript die Art und Weise neu, wie ein CLI aufgerufen und seine Ausgabe analysiert wird.
+
+```an-diagram title="CLI adapter → registry → action surface" summary="ShellCliAdapter wraps a binary; CliRegistry collects adapters for discovery; defineAction exposes one call on the agent + UI action surface."
+{
+  "html": "<div class=\"diagram-cli\"><div class=\"diagram-node\" data-rough>gh · ffmpeg · stripe<br><small class=\"diagram-muted\">command-line tools</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>ShellCliAdapter<br><small class=\"diagram-muted\">isAvailable · execute</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>CliRegistry<br><small class=\"diagram-muted\">describe() for discovery</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-pill accent\">defineAction</div></div>",
+  "css": ".diagram-cli{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-cli .diagram-arrow{font-size:22px;line-height:1}.diagram-cli .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+## Die Schnittstelle {#the-interface}
+
+Jeder CLI-Adapter implementiert `CliAdapter`:
+
+```ts
+import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+
+interface CliAdapter {
+  name: string; // "gh", "stripe", "ffmpeg"
+  description: string; // What the agent sees during discovery
+  isAvailable(): Promise<boolean>;
+  execute(args: string[]): Promise<CliResult>;
+}
+
+interface CliResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+```
+
+## ShellCliAdapter {#shell-adapter}
+
+Für die meisten CLIs benötigen Sie keine benutzerdefinierte Klasse – `ShellCliAdapter` umschließt jede Binärdatei mit sinnvollen Standardwerten:
+
+```ts
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const gh = new ShellCliAdapter({
+  command: "gh",
+  description: "GitHub CLI — manage repos, PRs, issues, and releases",
+});
+
+const ffmpeg = new ShellCliAdapter({
+  command: "ffmpeg",
+  description: "Audio/video processing and transcoding",
+  timeoutMs: 120_000, // 2 min for long encodes
+  env: { STRIPE_API_KEY: process.env.STRIPE_SECRET_KEY! },
+});
+```
+
+Optionen: `command` (erforderlich), `description` (erforderlich), `name` (standardmäßig `command`), `env` (zusammengeführt mit `process.env`), `cwd` (standardmäßig `process.cwd()`) und `timeoutMs` (standardmäßig `30000`).
+
+Für benutzerdefinierte Authentifizierung, Ausgabeanalyse oder Vor-/Nachbearbeitung implementieren Sie `CliAdapter` direkt, anstatt `ShellCliAdapter` zu verwenden.
+
+## Registrierung {#registry}
+
+`CliRegistry` sammelt Adapter, damit der Agent erkennen kann, was zur Laufzeit verfügbar ist:
+
+```ts
+import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
+
+const cliRegistry = new CliRegistry();
+cliRegistry.register(
+  new ShellCliAdapter({ command: "gh", description: "GitHub CLI" }),
+);
+
+cliRegistry.list(); // all registered
+await cliRegistry.listAvailable(); // only installed
+await cliRegistry.describe(); // [{ name, description, available }] for discovery
+
+const gh = cliRegistry.get("gh");
+const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
+```
+
+## Verwendung von actions {#from-actions}
+
+Einen CLI-Aufruf in `defineAction` einschließen, um ihn auf der Aktionsoberfläche verfügbar zu machen – `defineAction` ist erforderlich, wenn der Code innerhalb der Server-Aktionsoberfläche ausgeführt wird; Andernfalls verwenden Sie einen Adapter direkt in einer `scripts/`-Datei. Rufen Sie niemals `process.exit` in einer Aktion auf; Stattdessen wird ein Fehler ausgegeben.
+
+```ts
+// actions/list-prs.ts
+import { defineAction } from "@agent-native/core/action";
+import { ShellCliAdapter } from "@agent-native/core/adapters/cli";
+import { z } from "zod";
+
+const gh = new ShellCliAdapter({ command: "gh", description: "GitHub CLI" });
+
+export default defineAction({
+  description: "List open pull requests via the GitHub CLI.",
+  schema: z.object({}),
+  async run() {
+    if (!(await gh.isAvailable())) {
+      throw new Error("GitHub CLI not installed. Run: brew install gh");
+    }
+    const result = await gh.execute([
+      "pr",
+      "list",
+      "--json",
+      "title,url,state",
+      "--limit",
+      "10",
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || "gh pr list failed");
+    }
+    return JSON.parse(result.stdout);
+  },
+});
+```
+
+## Edge und serverlos {#edge-serverless}
+
+CLI-Adapter verwenden `node:child_process`, das auf Edge-/Worker-Laufzeiten (Cloudflare Workers, Netlify Edge Functions) nicht vorhanden ist. Führen Sie CLI-Adapterendpunkte und -Aufgaben in einer Standard-Node.js-Umgebung aus. Diese Einschränkung gilt für den Sandbox-Seam – siehe die vollständige Diskussion in [Adapters](/docs/sandbox-adapters#edge-serverless).
+
+## Was kommt als nächstes?
+
+- [**Adapters**](/docs/sandbox-adapters) – die kanonische Anleitung für beide Adapternähte.
+- [**Actions**](/docs/actions) – die Aktionsoberflächen-CLI-Adapter sind normalerweise eingepackt.

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

@@ -0,0 +1,398 @@
+---
+title: "Kunde"
+description: "React-Hooks und Dienstprogramme für agentennative Apps: sendToAgentChat, optionaler Agent-Chat-Kontextstatus, useDbSync, useAgentChatGenerating und cn."
+---
+
+# Kunde
+
+`@agent-native/core` stellt React-Hooks und Dienstprogramme für die Browserseite agentennativer Apps bereit.
+
+Diese Client/React APIs werden sowohl aus `@agent-native/core` als auch aus `@agent-native/core/client` exportiert. Importieren Sie sie aus Gründen der Übersichtlichkeit und korrekten Bündelung aus `@agent-native/core/client` (dem Browsereintrag), da das bloße `@agent-native/core`-Root standardmäßig in den Node-Build aufgelöst wird.
+
+Informationen zum dateibasierten Routing – Hinzufügen von Seiten, dynamischen Parametern und Navigation – siehe [Routing](/docs/routing).
+
+## Daten abrufen und ändern {#fetching-mutating}
+
+Die primäre Möglichkeit, App-Daten vom Browser zu lesen und zu schreiben, sind die Aktions-Hooks. Schreiben Sie `fetch`-Aufrufe an `/_agent-native/*`-Routen niemals handschriftlich – verwenden Sie stattdessen die benannten Helfer (siehe [Actions](/docs/actions)).
+
+```an-diagram title="The browser data loop" summary="Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."
+{
+  "html": "<div class=\"diagram-client\"><div class=\"diagram-col\"><div class=\"diagram-node\">useActionQuery<br><small class=\"diagram-muted\">cached read</small></div><div class=\"diagram-node\">useActionMutation<br><small class=\"diagram-muted\">write + invalidate</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-box\" data-rough>Actions<br><small class=\"diagram-muted\">/_agent-native/actions/*</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-panel\" data-rough><strong>SQL database</strong></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-pill ok\">useDbSync &rarr; refetch on change</div></div>",
+  "css": ".diagram-client{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-client .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-client .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```tsx
+import {
+  useActionQuery,
+  useActionMutation,
+  callAction,
+} from "@agent-native/core/client";
+
+// Read: auto-cached, auto-invalidated on mutations
+const { data, isLoading } = useActionQuery("get-lead", { leadId });
+
+// Mutate: emits a change event so query caches refetch
+const { mutate, isPending } = useActionMutation("create-lead");
+mutate({ name: "Alice", company: "Acme" });
+
+// Imperative: for one-off calls outside a component
+await callAction("archive-lead", { leadId });
+```
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Senden Sie eine Nachricht an den Agenten-Chat über postMessage – die übliche Methode zum Delegieren einer KI-Aufgabe aus einer UI-Interaktion. Übergeben Sie `context` für versteckten Modellkontext und `submit: true`, um es sofort zu senden, oder `submit: false`, um einen Entwurf vorab auszufüllen, den der Benutzer zuerst überprüft.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+In einer mit `embedApp()` erstellten MCP-App-Einbettung werden automatisch Nachrichten übermittelt
+(`submit` weggelassen oder `true`) werden an die MCP App-Host-Bridge weitergeleitet, die
+fordert den enthaltenden Host auf, versteckten Kontext hinzuzufügen und den sichtbaren Benutzerzug zu senden.
+`context` bleibt für das Model sichtbar, ohne als Benutzer-Chat gepostet zu werden.
+`submit: false` behält das lokale Vorausfüll-/Überprüfungsverhalten bei, da MCP-Apps dies nicht tun
+Definieren Sie eine Standard-Entwurfsvorausfüllung API. Intern ist dies der Pfad zum übermittelten Chat
+tauchte manchmal als `agentNative.submitChat` auf; App-Code sollte aufrufen
+`sendToAgentChat()`, anstatt dieses Ereignis direkt zu veröffentlichen.
+
+### Stille Hintergrundsendungen {#background-send}
+
+Verwenden Sie `background: true`, wenn eine UI-Aktion die eigentliche Arbeit eines Agenten einleiten soll.
+Seitenleiste öffnen oder fokussieren. Dadurch wird immer noch ein normaler Chat-Thread/Lauf erstellt,
+verwendet die Tools/actions/context des Agenten und sorgt dafür, dass die Arbeit beobachtbar bleibt
+das Lauffach; Es handelt sich nicht um einen einmaligen Modellaufruf.
+
+```ts
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` soll mit `newTab` gepaart werden, damit die versteckte Arbeit nicht funktioniert
+überschreibt die aktive Konversation des Benutzers. Verwenden Sie das zurückgegebene `tabId`, wenn UI
+muss den Follow-up-Status korrelieren oder später einen Deep-Link zum Lauf erstellen.
+
+### AgentChatMessage {#agentchatmessage}
+
+| Option                | Typ         | Beschreibung                                                                                       |
+| --------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
+| `message`             | `string`    | Die sichtbare Eingabeaufforderung, die an den Chat gesendet wurde                                  |
+| `context`             | `string?`   | Versteckter Kontext angehängt (nicht im Chat UI angezeigt)                                         |
+| `submit`              | `boolean?`  | true = automatische Übermittlung, false = nur Vorabausfüllung                                      |
+| `newTab`              | `boolean?`  | Erstellen Sie einen separaten Chat-Thread für diese Eingabeaufforderung                            |
+| `background`          | `boolean?`  | Mit `newTab` ausführen, ohne die Registerkarte zu fokussieren, und den Lauf in `RunsTray` anzeigen |
+| `openSidebar`         | `boolean?`  | Setzen Sie „false“, um zu senden/vorab auszufüllen, ohne die Seitenleiste zu öffnen                |
+| `projectSlug`         | `string?`   | Optionaler Projekt-Slug für strukturierten Kontext                                                 |
+| `preset`              | `string?`   | Optionaler voreingestellter Name für nachgeschaltete Verbraucher                                   |
+| `referenceImagePaths` | `string[]?` | Optionale Referenzbildpfade                                                                        |
+
+## Agent-Chat-Kontextstatus (Erweitert) {#agent-chat-context-state}
+
+Die Kontextstatus-APIs sind optionale Installationen für UI, die eine bidirektionale Synchronisierung mit erfordern
+Staging-Kontext-Chips: Rendern der aktuell bereitgestellten Elemente außerhalb des Composers
+zeigt an, ob ein Element bereits angehängt ist, oder stellt explizite Angaben bereit
+Steuerelemente entfernen/löschen.
+
+Nehmen Sie diese Helfer nicht für ein einfaches „Senden Sie dies an den Agenten“ oder
+Flows „Diesen Entwurf zur Überprüfung vorab ausfüllen“. Verwenden Sie `sendToAgentChat()` mit `context`
+und `submit` für diese.
+
+| API                               | Verwenden wenn                                                                                                    |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | Eine React-Komponente benötigt die live bereitgestellte Kontextliste                                              |
+| `setAgentChatContextItem(item)`   | Imperativer Code sollte ein Schlüsselkontextelement bereitstellen oder ersetzen                                   |
+| `listAgentChatContext()`          | Nicht-React-Code benötigt einen einmaligen Snapshot des bereitgestellten Kontexts                                 |
+| `removeAgentChatContextItem(key)` | UI sollte ein bereitgestelltes Kontextelement durch sein stabiles `key` entfernen                                 |
+| `clearAgentChatContext()`         | UI sollte den gesamten bereitgestellten Kontext löschen, z. B. nach einem Zurücksetzen der Ansicht oder des Modus |
+| `refreshAgentChatContext()`       | Imperativer Code sollte den neuesten persistenten Kontext-Snapshot erneut lesen                                   |
+
+`useAgentChatContext()` gibt `{ items, set, remove, clear, refresh }` zurück.
+
+## openAgentSettings(Abschnitt?) {#openagentsettings}
+
+Verwenden Sie `openAgentSettings()`, wenn eine App-Einstellungsseite oder eine Setup-Karte geöffnet werden soll
+Registerkarte „Einstellungen“ der Agent-Seitenleiste. Übergeben Sie eine Abschnitts-ID wie `"llm"`, `"secrets"`,
+`"automations"`, `"voice"` oder `"limits"`, um einen bestimmten Abschnitt zu öffnen.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client";
+
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Ziehen Sie diesen Helfer dem direkten Versand von `agent-panel:open-settings` vor.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client";
+
+function SelectionContextButton({ record }: { record: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-record:${record.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Record",
+          context: JSON.stringify(record, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` ist für zwingenden Code, der nur die
+aktuelle bereitgestellte Elemente einmal. `clearAgentChatContext()` ist absichtlich breit gefasst; verwenden
+`removeAgentChatContextItem(key)`, wenn sich nur eine Auswahl geändert hat.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Option        | Typ        | Beschreibung                                                                                  |
+| ------------- | ---------- | --------------------------------------------------------------------------------------------- |
+| `key`         | `string`   | Stabile Kennung, die zum Ersetzen eines vorhandenen Nuggets verwendet wird                    |
+| `title`       | `string`   | Kurzbezeichnung wird im Composer-Chip angezeigt                                               |
+| `context`     | `string`   | Versteckter Kontext in der nächsten übermittelten Eingabeaufforderung enthalten               |
+| `openSidebar` | `boolean?` | Standardmäßig ist true; Übergeben Sie „false“, um den Kontext stillschweigend bereitzustellen |
+
+## askUserQuestion(opts) {#ask-user-question}
+
+Stellen Sie dem Benutzer eine Multiple-Choice-Frage aus dem App-Code und rendern Sie diese inline im
+Agent-Panel und **warten Sie auf ihre Antwort**. Es ist der clientseitige Zwilling von
+Das integrierte `ask-question`-Tool des Agenten: Es schreibt ein `GuidedQuestionPayload` in den
+`"guided-questions"` Anwendungsstatusschlüssel (wo der gemountete
+`GuidedQuestionFlow` rendert es) und zeigt das Agentenfeld an, sodass die Frage lautet
+sichtbar. Im Gegensatz zum Agenten-Tool – dessen Antwort an den Agenten zurückfließt –
+`askUserQuestion()` **wird mit der Antwort an den Anrufer aufgelöst**, sodass UI dies kann
+darauf verzweigen.
+
+Verwenden Sie es, wenn der UI vor ihm genau eine kleine Entscheidung (2–4 Optionen) benötigt.
+startet die Agentenarbeit – anstatt ein benutzerdefiniertes Modal zu erstellen. Greifen Sie nach
+Composer für Freiformdetails und ein Formular/Popover für die Eingabe mehrerer Felder.
+
+```tsx
+import { askUserQuestion, sendToAgentChat } from "@agent-native/core/client";
+
+const length = await askUserQuestion({
+  question: "How long should this deck be?",
+  header: "Deck length", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Short (3–5 slides)", value: "short" },
+    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
+    { label: "Long (11+ slides)", value: "long" },
+  ],
+  allowFreeText: false, // omit the "Other" free-text option (default adds it)
+  allowMultiple: false, // single-select (default)
+});
+
+if (length) {
+  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
+}
+```
+
+Jede Option ist `{ label, value?, description?, preview?, recommended? }`; `value`
+ist standardmäßig `label` und `preview` rendert ein kleines Mockup/Code-Snippet unter
+Option. Das Versprechen wird mit dem ausgewählten `value` (oder `value[]`, wenn
+`allowMultiple`), die Freitextzeichenfolge, wenn der Benutzer „Andere“ auswählt, oder `null`
+Wenn sie überspringen, bleibt es ausstehend, bis der Benutzer antwortet. Erfordert das Agentenpanel
+muss gemountet werden (ist in jeder Vorlage enthalten).
+
+Der Agent erreicht das gleiche UI über sein `ask-question`-Tool: Lassen Sie lieber das
+Agent fragt, wenn _es_ auf einen echten Fork trifft, der nicht aus dem Kontext aufgelöst werden kann; verwenden
+`askUserQuestion()`, wenn der _UI_ eine Aktion für eine Auswahl steuern muss.
+
+## MCP App Host Bridge {#mcp-app-host-bridge}
+
+Routen, die als MCP-Apps eingebettet sind, sollten URL-first sein: Laden Sie das aktuelle Artefakt von
+Pfad-/Abfrageparameter, rendern die echte React-Route oder eine fokussierte gemeinsame Komponente
+und verwenden Sie die Host-Bridge nur für Host-eigenes Verhalten. `@agent-native/core/client`
+exportiert den Aufruf der eingebetteten Routen des Helfers:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client";
+```
+
+`getMcpAppHostContext()` liest den neuesten gepushten Host-Kontext-Snapshot;
+`useMcpAppHostContext()` abonniert React-Komponenten für Änderungen. Die Anfrage
+Helfer (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) geben `false` außerhalb eines eingebetteten MCP-App-Frames zurück, oder
+`Promise<boolean>` innerhalb eines Frames. `sendToAgentChat()` verwendet dieselbe Bridge für
+Automatisch übermittelte Eingabeaufforderungen von eingebetteten Routen.
+
+Die Brücke selbst – die `ui/*` JSON-RPC-Nachrichten, die `agentNative.mcpHost.*`
+Wrapper-Relay, Transplantation vs. Controlled-Frame-Rendering, Host-Kontext und
+Anzeigemodus-Anfragen – ist Eigentum von
+[External Agents](/docs/external-agents#mcp-app-bridge).
+
+## Dynamische Vorschläge {#dynamic-suggestions}
+
+`<AgentSidebar>`, `<AgentPanel>` und `<AssistantChat>` führen standardmäßig statische `suggestions` mit kontextbezogenen Vorschlägen zusammen. Das Framework liest `navigation`, `selection`, `pending-selection-context` und den aktuellen URL aus dem Anwendungsstatus, während ein leerer Chat sichtbar ist, und bietet dann Eingabeaufforderungschips an, die zum aktuellen Bildschirm passen.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+Legen Sie `dynamicSuggestions={false}` fest, um nur statische Chips zu behalten. Übergeben Sie `getSuggestions`, wenn eine App deterministische domänenspezifische Chips aus demselben Anwendungsstatuskontext benötigt.
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+React-Hook, der sendToAgentChat mit der Ladestatusverfolgung umschließt:
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core/client";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+`isGenerating` wird wahr, wenn Sie `send()` aufrufen, und wird automatisch auf falsch zurückgesetzt, wenn der Agent die Generierung abgeschlossen hat.
+
+## useDbSync(Optionen?) {#usedbsync}
+
+React-Hook (früher `useFileWatcher`), der über SSE auf Datenbankänderungen lauscht, auf Abfragen zurückgreift und die Framework-Abfragecaches ungültig macht, die dafür sorgen, dass UI mit Agent-Schreibvorgängen in Einklang steht:
+
+```ts
+import { useDbSync } from "@agent-native/core/client";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### Optionen {#usedbsync-options}
+
+| Option             | Typ                | Beschreibung                                                                                                                         |
+| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `queryClient`      | `QueryClient?`     | React-Abfrage-Client für Cache-Ungültigmachung                                                                                       |
+| `queryKeys`        | `string[]?`        | Veraltet und ignoriert; für alte Anrufseiten beibehalten                                                                             |
+| `pollUrl`          | `string?`          | Poll-Endpunkt URL. Standard: `"/_agent-native/poll"`                                                                                 |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                                               |
+| `interval`         | `number?`          | Abfrageintervall in ms. Standard: `2000`                                                                                             |
+| `fallbackInterval` | `number?`          | Fallback-Abfrageintervall, wenn SSE nicht verfügbar ist. Standard: `15000`                                                           |
+| `pauseWhenHidden`  | `boolean?`         | Pausieren Sie die Abfrage, wenn die Browser-Registerkarte ausgeblendet ist. Standard: `true`                                         |
+| `ignoreSource`     | `string?`          | Anforderungsquelle pro Tab, die ignoriert werden soll, damit ein Tab nicht erneut aus seinen eigenen Schreibvorgängen abgerufen wird |
+| `onEvent`          | `(data) => void`   | Optionaler Rückruf, wenn SSE/polling ein Änderungsereignis empfängt                                                                  |
+
+Für normales CRUD bevorzugen Sie `useActionQuery` und `useActionMutation`; mutierendes actions gibt `source: "action"` aus und diese Hooks werden automatisch erneut abgerufen.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+Das Framework verwendet Änderungsversionen, um React Abfrage-Caches mit Änderungen zu synchronisieren, die von Hintergrundagenten, Cron-Jobs oder anderen Benutzern vorgenommen wurden.
+
+Wenn eine serverseitige Datenbankmutation auftritt, zeichnet der Server ein Änderungsereignis mit einem bestimmten `source`-Schlüssel auf. Der `useDbSync`-Listener des Clients empfängt diese Ereignisse und erhöht den lokalen Änderungsversionszähler für diese Quelle. Indem Sie den Versionszähler in Ihre React-Abfrageschlüssel integrieren, werden Abfragen automatisch erneut abgerufen, wenn das Backend den Client über neue Aktivitäten benachrichtigt.
+
+- **`useChangeVersion(source: string): number`** – gibt einen Zähler zurück, der immer dann erhöht wird, wenn der angegebene `source` mutiert wird.
+- **`useChangeVersions(sources: readonly string[]): number`** – gibt die Summe der Versionszähler für mehrere Quellen zurück.
+
+### Beispiel: Synchronisieren einer Rohabfrage mit der Datenbank
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client";
+
+function DashboardView({ id }) {
+  // Get version for dashboards domain source
+  const v = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+### Latenzmodelle und Invalidierungsverhalten
+
+- **UI-initiierte Mutationen:** Wenn Sie eine Aktion vom UI mit `useActionMutation` ausführen, löst die Mutation bei Erfolg sofort ein lokales Ereignis mit `source: "action"` aus. Dies löst abhängig von dieser Aktion einen **sofortigen, optimistischen erneuten Abruf** aller Abfrageschlüssel aus und vermeidet so visuelle Verzögerungen.
+- **Hintergrund- oder Agent-Mutationen:** Wenn der KI-Agent, ein Webhook oder ein Hintergrund-Worker Daten mutiert, wird das Update an den Client gesendet. Der `useDbSync` des Clients erfasst dies entweder sofort über SSE (vom Server gesendete Ereignisse) oder greift auf den **2-Sekunden-Polling-Tick** zurück. Die Version des Abfrageschlüssels ändert sich dann und löst einen erneuten Abruf im Hintergrund aus.
+
+```an-diagram title="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."
+{
+  "html": "<div class=\"diagram-latency\"><div class=\"diagram-col\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill ok\">This tab</span><strong>useActionMutation</strong><small class=\"diagram-muted\">fires source: \"action\" on success &rarr; instant local refetch</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Agent · webhook · other tab</span><strong>Remote write</strong><small class=\"diagram-muted\">SSE push, or the ~2s polling tick as fallback &rarr; version bumps &rarr; background refetch</small></div></div></div>",
+  "css": ".diagram-latency .diagram-col{display:flex;flex-direction:column;gap:12px}.diagram-latency .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px}"
+}
+```
+
+## cn(...Eingaben) {#cn}
+
+Dienstprogramm zum Zusammenführen von Klassennamen (clsx + tailwind-merge):
+
+```ts
+import { cn } from "@agent-native/core/client";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```