@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,142 @@
+---
+title: "FAQ"
+description: "Häufige Fragen zu Agent-Native – was es ist, für wen es ist, was Sie erstellen können und wie es funktioniert."
+---
+
+# FAQ
+
+Häufig gestellte Fragen zu Agent-Native, sortiert von „Ich suche nur“ bis „Ich verkabele gerade die Authentifizierung.“
+
+## Die Grundlagen {#general}
+
+### Was ist Agent-nativ? {#what-is-agent-native}
+
+Agent-native ist ein Framework zum Erstellen von Apps, bei dem der KI-Agent und die ihn umgebende Produktoberfläche gleichberechtigte Partner sind. Diese Oberfläche kann als Headless-Agent mit einer benutzerdefinierten Aktion beginnen, sich zu einem Rich-Chat entwickeln oder zu einem vollwertigen UI werden. Die Invariante besteht darin, dass Agenten und Menschen denselben actions, dieselbe Datenbank und denselben Status teilen. Die vollständige Erklärung finden Sie unter [What Is Agent-Native?](/docs/what-is-agent-native).
+
+### Für wen ist das? {#who-is-this-for}
+
+Agent-native ist für Leute gedacht, die möchten, dass eine echte App und ein KI-Agent mit denselben Daten und actions arbeiten. Die allgemeinen Pfade sind:
+
+- **Verwenden Sie eine gehostete App**, wenn Sie E-Mail, Kalender, Formulare, Pläne oder eine andere fertige Vorlage ohne Einrichtung wünschen – beginnen Sie bei [template gallery](/templates).
+- **Beginnen Sie mit Chat**, wenn Sie eine einfache App wünschen, mit der Benutzer sofort sprechen können, dann erweitern Sie sie mit actions und Bildschirmen – beginnen Sie mit [Getting Started](/docs/getting-started) oder [Chat](/docs/template-chat).
+- **Starten Sie primitiv zuerst**, wenn Sie eine Aktion und eine kopflose App-Agent-Schleife wünschen, bevor Sie sich an UI festlegen – beginnen Sie mit [Getting Started](/docs/getting-started).
+- **Forken und passen Sie eine Vorlage an**, wenn Sie Ihr eigenes SaaS-Produkt mit Authentifizierung, Datenbank, UI und Agent actions bereits verkabelt haben möchten – siehe [Templates](/docs/cloneable-saas).
+- **Erstellen Sie von Grund auf**, wenn Sie die Framework-Grundelemente für ein neues agentengesteuertes Produkt benötigen – beginnen Sie mit [Getting Started](/docs/getting-started).
+- **Verbinden Sie einen anderen Agenten oder ein anderes Code-Tool**, wenn Sie möchten, dass Claude, ChatGPT, Codex, Cursor oder GitHub Copilot/VS-Code eine agentennative App verwenden – siehe [External Agents](/docs/external-agents) und [Skills Guide](/docs/skills-guide).
+
+### Wie unterscheidet sich das vom Hinzufügen von KI zu einer vorhandenen App? {#how-is-this-different}
+
+Bei den meisten Apps wird die KI nachträglich eingebaut, sodass sie in der App eigentlich keine Aufgaben erledigen kann. In einer agentennativen App ist der Agent ein erstklassiger Bürger, der dasselbe actions, dieselbe Datenbank und denselben Status wie UI verwendet, sodass er alles tun kann, was die Schaltflächen können – und den eigenen Code der App ändern kann. Siehe [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder).
+
+```an-diagram title="Bolted-on AI vs. agent-native" summary="A bolted-on chat sidebar lives in its own world. An agent-native agent shares the same actions, database, and state as the UI."
+{
+  "html": "<div class=\"diagram-vs\"><div class=\"diagram-col\"><span class=\"diagram-pill warn\">Bolted-on AI</span><div class=\"diagram-node\">Chat sidebar</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>separate AI world<br><small class=\"diagram-muted\">can't touch the app</small></div><div class=\"diagram-box diagram-muted\">App UI &amp; data</div></div><div class=\"diagram-divider\" aria-hidden=\"true\"></div><div class=\"diagram-col\"><span class=\"diagram-pill ok\">Agent-native</span><div class=\"diagram-row2\"><div class=\"diagram-node\">UI</div><div class=\"diagram-node\">Agent</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>shared actions, DB &amp; state</div></div></div>",
+  "css": ".diagram-vs{display:flex;align-items:stretch;gap:18px;flex-wrap:wrap}.diagram-vs .diagram-col{display:flex;flex-direction:column;gap:8px;align-items:center;flex:1;min-width:200px}.diagram-vs .diagram-row2{display:flex;gap:8px}.diagram-vs .diagram-arrow{font-size:20px;line-height:1}.diagram-vs .diagram-divider{width:1px;align-self:stretch;background:currentColor;opacity:.15}"
+}
+```
+
+### Ist es Open Source? {#is-this-open-source}
+
+Ja. Das Framework und alle Vorlagen sind Open Source. Sie können alles lokal ausführen, selbst hosten oder die Cloud von Builder.io für verwaltetes Hosting, Zusammenarbeit und Teamfunktionen nutzen.
+
+### Wie viel kostet es? {#how-much}
+
+Das Framework selbst ist kostenlos. Die beiden Kosten werden Sie in der Praxis sehen:
+
+- **KI-Nutzung.** Sie bringen Ihren eigenen API-Schlüssel (Anthropic, OpenAI usw.) mit und bezahlen den Modellanbieter direkt. Es gibt keinen Aufschlag von uns.
+- **Hosting.** Was auch immer Ihr Host verlangt. Die meisten Vorlagen laufen problemlos auf kostenlosen Stufen (Netlify, Vercel, Cloudflare) für kleine Arbeitslasten.
+
+Wenn Sie das alles lieber nicht verwalten möchten, bündelt die gehostete Version auf `agent-native.com` (betrieben von Builder.io) Inferenz und Hosting in einem Plan pro Sitzplatz.
+
+### Kann ich das selbst hosten? {#can-i-self-host}
+
+Ja. Wählen Sie einen beliebigen Host aus, auf dem Node ausgeführt wird – Netlify, Vercel, Cloudflare, AWS, Deno Deploy, Ihr eigener Server – und eine beliebige SQL-Datenbank (Postgres, SQLite, Turso, D1). Das Framework ist portabel aufgebaut. Siehe [Deployment](/docs/deployment).
+
+### Welche KI-Modelle werden unterstützt? {#what-models}
+
+Anthropic Claude, OpenAI (GPT-5-Familie), Google Gemini und alle Anbieter, die die Form OpenAI API sprechen (einschließlich lokaler Modelle über Ollama). Sie konfigurieren das Modell in den Einstellungen; Beim Umschalten handelt es sich um eine Konfigurationsänderung, nicht um ein Umschreiben des Codes. Der am häufigsten getestete Pfad des Frameworks ist Claude, daher ist dies die Standardempfehlung.
+
+### Muss ich mich mit KI/ML auskennen? {#do-i-need-to-know-ai}
+
+Nein. Sie trainieren keine Modelle, nehmen keine Feinabstimmung vor und befassen sich nicht mit Einbettungen. Sie erstellen eine normale Web-App – und in der gehosteten Version erstellen Sie kaum etwas. Das Framework übernimmt die Agentenintegration: Weiterleiten von Nachrichten, Ausführen von actions, Synchronisieren des Status.
+
+### Kann ich eine vorhandene App auf Agent-nativ migrieren? {#can-i-use-existing-code}
+
+Das ist möglich, aber Agent-nativ funktioniert am besten, wenn es von Grund auf neu entwickelt wird. Die Architektur – gemeinsam genutzte Datenbank, Polling-Synchronisierung, actions, Anwendungsstatus – muss durchgehend integriert sein. Der empfohlene Weg besteht darin, von einer Vorlage auszugehen und diese anzupassen. Stellen Sie sich das wie den Wechsel von Desktop-First zu Mobile-First vor: Sie _können_ nachrüsten, aber nativ zu bauen ist besser.
+
+## Vorlagen und was Sie erstellen können {#templates}
+
+### Welche Vorlagen sind verfügbar? {#what-templates-are-available}
+
+Das Framework wird mit produktionsbereiten Vorlagen geliefert, darunter [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visuelle Pläne und PR-Zusammenfassungen), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) und mehr. Bei jeder handelt es sich um eine vollständige App mit UI, Agent actions, Datenbankschema und sofort einsatzbereiten KI-Anweisungen. Den vollständigen Katalog finden Sie unter [Templates](/docs/cloneable-saas).
+
+### Kann ich Vorlagen anpassen? {#can-i-customize-templates}
+
+Das ist der springende Punkt. Forken Sie eine Vorlage und passen Sie sie an, indem Sie den Agenten fragen. „Fügen Sie den Formularen ein Prioritätsfeld hinzu.“ „Stellen Sie eine Verbindung zu unserer Salesforce-Instanz her.“ „Ändern Sie das Farbschema, damit es zu unserer Marke passt.“ Der Agent ändert den Code und Ihre App entwickelt sich im Laufe der Zeit weiter.
+
+### Kann ich etwas erstellen, das die Vorlagen nicht abdecken? {#build-from-scratch}
+
+Ja. Wenn Sie eine einfache Chat-App wünschen, führen Sie `npx @agent-native/core@latest create my-chat-app --template chat` aus. Sie erhalten dauerhafte Chat-Threads, actions, Authentifizierung, SQL-gestützten Laufzeitstatus und Platz zum Hinzufügen eigener Bildschirme. Wenn Sie die kleinste Action-First-App ohne UI wünschen, führen Sie `npx @agent-native/core@latest create my-agent --headless` aus. Siehe [Getting Started](/docs/getting-started), [Pure-Agent Apps](/docs/pure-agent-apps) und [Chat](/docs/template-chat).
+
+### Kann ich es ausprobieren, ohne eine Vorlage zu forken? {#try-with-a-skill}
+
+Ja – installieren Sie einen Skill in einem Codierungsagenten, den Sie bereits verwenden, mit einem Befehl und ohne dass ein Gerüst erforderlich ist. Die exemplarische Vorgehensweise finden Sie im [Skills Guide](/docs/skills-guide#app-backed-skills).
+
+## Agentenfunktionen {#agent-capabilities}
+
+### Kann der Agent den eigenen Code der App wirklich ändern? {#can-the-agent-modify-code}
+
+Ja, und es ist eine Funktion. Der Agent kann Komponenten, Routen, Stile und actions sicher bearbeiten. Sie fragen „Kohortenanalysediagramm hinzufügen“ und der Agent erstellt es. Sie fragen „Mit unserem Stripe-Konto verbinden“ und der Agent schreibt die Integration. Alles ist normaler Git-verfolgter Code, sodass fehlerhafte Änderungen leicht rückgängig gemacht werden können.
+
+### Können Benutzer von außerhalb der App mit dem Agenten sprechen? {#external-channels}
+
+Ja. Derselbe Agent läuft in Ihrem Web UI, in Slack, in Telegram, per E-Mail und von anderen Agenten (über [A2A](/docs/a2a-protocol)). Es handelt sich um denselben Agenten mit demselben Speicher und demselben actions, der nur über verschiedene Kanäle erreicht wird. Siehe [Messaging the agent](/docs/messaging).
+
+### Können Agenten miteinander reden? {#can-agents-talk-to-each-other}
+
+Ja, über [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Jede agentennative App erhält automatisch einen A2A-Endpunkt. In der Mail-App können Sie den Analyseagenten markieren, um Daten abzufragen. Ein Agent erkennt, welche anderen Agenten verfügbar sind, ruft sie über das Protokoll auf und zeigt die Ergebnisse im UI an. Keine Konfiguration erforderlich – die Agentenkarte wird automatisch aus actions Ihrer Vorlage generiert.
+
+### Was kann der Agent in der App sehen? {#what-can-the-agent-see}
+
+Der Agent weiß immer, was der Benutzer gerade sieht. Der UI schreibt bei jeder Routenänderung den Navigationsstatus in die Datenbank – welche Ansicht geöffnet ist, welches Element ausgewählt ist. Der Agent liest dies, bevor er Maßnahmen ergreift. Wenn eine E-Mail geöffnet ist, weiß der Agent, um welche E-Mail es sich handelt. Wenn eine Folie ausgewählt ist, weiß der Agent, welche Folie. Siehe [Context Awareness](/docs/context-awareness).
+
+## Entwicklungsfragen {#development}
+
+### Welche KI-Codierungstools funktionieren mit Agent-Native? {#which-ai-tools-work}
+
+Jedes KI-Codierungstool, das Projektanweisungen liest. Das Framework verwendet AGENTS.md als universellen Standard und erstellt automatisch Symlinks für bestimmte Tools:
+
+- **Claude-Code** – liest CLAUDE.md (durch das CLI-Setup mit AGENTS.md verknüpft)
+- **Cursor** – liest AGENTS.md direkt oder `.cursorrules` (der alte Speicherort des Cursors), falls in Ihrem Projekt vorhanden
+- **Windsurf** – liest .windsurfrules (durch das CLI-Setup mit AGENTS.md verknüpft)
+- **Codex, Gemini und andere** – funktionieren über das eingebettete Agent-Panel
+- **Builder.io** – Cloud-gehosteter Agent mit visueller Bearbeitung und Zusammenarbeit
+
+### Kann ich meine eigene Datenbank verwenden? {#can-i-use-my-own-database}
+
+Ja. Legen Sie `DATABASE_URL` fest und das Framework erkennt es automatisch. Zu den unterstützten Datenbanken gehören SQLite, Postgres (Neon, Supabase, Plain), Turso (libSQL) und Cloudflare D1. Alle SQL sind dialektunabhängig über Drizzle ORM – der gleiche Code funktioniert überall.
+
+### Wo kann ich bereitstellen? {#where-can-i-deploy}
+
+Überall. Der Server läuft auf Nitro, das zu jedem Bereitstellungsziel kompiliert wird: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda und Bun. Sie können das Hosting von Builder.io auch für verwaltete Bereitstellungen nutzen. Siehe [Deployment guide](/docs/deployment).
+
+## Architektur {#architecture}
+
+### Warum SSE plus Polling statt WebSockets? {#why-polling-not-websockets}
+
+SSE gibt Schreibvorgängen im selben Prozess einen sofortigen Pfad zum Browser, und eine einfache Abfrage des Versionszählers bleibt der Fallback, da sie in jeder Bereitstellungsumgebung funktioniert – einschließlich serverloser und Edge-Umgebungen, in denen dauerhafte Sockets möglicherweise nicht verfügbar sind. Siehe [Key Concepts — Live sync](/docs/key-concepts#polling-sync).
+
+```an-diagram title="SSE first, polling fallback" summary="Same-process writes stream instantly; a version-counter poll keeps serverless, edge, and cross-process writes convergent."
+{
+  "html": "<div class=\"diagram-transport\"><div class=\"diagram-box\" data-rough>DB write</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-node\">SSE<br><small class=\"diagram-muted\">/_agent-native/events &middot; instant</small></div><div class=\"diagram-node\">Poll<br><small class=\"diagram-muted\">/_agent-native/poll &middot; universal fallback</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Browser refetch</div></div>",
+  "css": ".diagram-transport{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-transport .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-transport .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+### Warum kann der UI einen LLM nicht direkt aufrufen? {#why-no-inline-llm-calls}
+
+KI ist nicht deterministisch, daher benötigen Sie einen Konversationsfluss, um Feedback zu geben und zu iterieren – keine One-Shot-Schaltflächen – und der Agent verfügt bereits über Ihre Codebasis, Anweisungen, skills und den Verlauf, der einem Inline-Anruf fehlt. Durch die Weiterleitung aller Daten über den Agenten kann die App auch von Slack, Telegram oder einem anderen Agenten gesteuert werden. Siehe [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
+
+### Warum ist dies ein Framework und keine Bibliothek? {#why-framework-not-library}
+
+Die gemeinsame Datenbank, die Live-Synchronisierung, das actions-System und der Anwendungsstatus funktionieren nur, weil sie von Grund auf miteinander verbunden sind – der UI reagiert sofort auf Agentenänderungen, Agenten kommunizieren und der Agent versteht, was der Benutzer sieht. Eine Bibliothek gibt Ihnen Stücke; Das ist eine Architektur. Siehe [Key Concepts](/docs/key-concepts).

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

@@ -0,0 +1,122 @@
+---
+title: "Datei-Uploads"
+description: "Datei-Upload-Speicher konfigurieren – SQL-Fallback für Entwickler, Builder.io oder benutzerdefinierte Anbieter für die Produktion."
+---
+
+# Datei-Uploads
+
+Das Framework bietet eine Datei-Upload-Abstraktion, die Uploads über einen konfigurierbaren Anbieter weiterleitet. Vorlagen rufen `uploadFile()` auf und erhalten ein URL zurück – das Speicher-Backend ist austauschbar, ohne dass der Anwendungscode geändert werden muss.
+
+## Wie es funktioniert {#how-it-works}
+
+Upload-Anfragen gehen an `POST /_agent-native/file-upload`, das an den aktiven Anbieter weiterleitet. Welcher Anbieter konfiguriert ist, können Sie unter `GET /_agent-native/file-upload/status`.
+
+Die Reihenfolge der Anbieterauflösung lautet:
+
+1. **Vom Benutzer registrierte Anbieter** – benutzerdefinierte Anbieter, die über `registerFileUploadProvider()` registriert wurden
+2. **Builder.io-Anbieter** – integriert, wird automatisch aktiviert, wenn Builder.io verbunden ist
+3. **SQL Fallback** – speichert Dateien als Base64 in der Datenbank (gut für Entwickler, nicht für Produktion)
+
+```an-diagram title="Provider resolution order" summary="uploadFile() picks the first configured provider in order. The SQL fallback always exists so uploads work with zero setup."
+{
+  "html": "<div class=\"diagram-upload\"><div class=\"diagram-box\" data-rough>uploadFile()<br><small class=\"diagram-muted\">POST /_agent-native/file-upload</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-step\"><span class=\"diagram-pill accent\">1</span><div class=\"diagram-node\">User-registered<br><small class=\"diagram-muted\">registerFileUploadProvider() — S3, R2, GCS…</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill\">2</span><div class=\"diagram-node\">Builder.io<br><small class=\"diagram-muted\">auto when connected — CDN-served</small></div></div><div class=\"diagram-step\"><span class=\"diagram-pill warn\">3</span><div class=\"diagram-node\">SQL fallback<br><small class=\"diagram-muted\">base64 in DB — dev only</small></div></div></div></div>",
+  "css": ".diagram-upload{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-upload .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-upload .diagram-step{display:flex;align-items:center;gap:8px}.diagram-upload .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+```an-api title="The upload endpoint" method="POST" path="/_agent-native/file-upload"
+{
+  "method": "POST",
+  "path": "/_agent-native/file-upload",
+  "summary": "Upload a file through the active provider and get back a public URL.",
+  "description": "Dispatches to the first configured provider in resolution order. Check the active provider at `GET /_agent-native/file-upload/status`.",
+  "request": { "contentType": "multipart/form-data" },
+  "responses": [
+    { "status": "200", "description": "{ url, id?, provider } — the public URL and which provider handled it." }
+  ]
+}
+```
+
+## Standard: SQL Fallback {#sql-fallback}
+
+Wenn kein Anbieter konfiguriert ist, werden Dateien über das Ressourcensystem als Base64-Daten in der SQL-Datenbank gespeichert. Dies funktioniert sofort für die lokale Entwicklung, wird jedoch nicht für die Produktion empfohlen – große Dateien blähen die Datenbank auf und es gibt kein CDN.
+
+Eine einmalige Warnung wird protokolliert, wenn der Fallback verwendet wird.
+
+## Builder.io Hosting {#builder-hosting}
+
+Wenn Ihre App mit Builder.io verbunden ist, werden Datei-Uploads automatisch an das Asset-Hosting von Builder weitergeleitet. Dateien werden von einem CDN bereitgestellt, ohne dass eine Konfiguration erforderlich ist. Dies ist die empfohlene Produktionskonfiguration.
+
+## Benutzerdefinierte Anbieter {#custom-providers}
+
+Registrieren Sie einen benutzerdefinierten Anbieter in einem Server-Plugin, um ein beliebiges Speicher-Backend (S3, Cloudflare R2, GCS usw.) zu verwenden:
+
+```ts
+// server/plugins/file-upload.ts
+import { registerFileUploadProvider } from "@agent-native/core/file-upload";
+
+export default defineNitroPlugin(() => {
+  registerFileUploadProvider({
+    id: "s3",
+    name: "Amazon S3",
+    isConfigured: () => !!process.env.S3_BUCKET,
+    upload: async ({ data, filename, mimeType }) => {
+      const key = `uploads/${Date.now()}-${filename}`;
+      await s3Client.putObject({
+        Bucket: process.env.S3_BUCKET!,
+        Key: key,
+        Body: data,
+        ContentType: mimeType,
+      });
+      return {
+        url: `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`,
+        provider: "s3",
+      };
+    },
+  });
+});
+```
+
+## API hochladen {#upload-api}
+
+Die `FileUploadProvider`-Schnittstelle:
+
+```ts
+interface FileUploadProvider {
+  id: string; // Unique id, e.g. "s3"
+  name: string; // Human-readable name
+  isConfigured: () => boolean; // True when ready (env vars set, etc.)
+  upload: (input: FileUploadInput) => Promise<FileUploadResult>;
+}
+
+interface FileUploadInput {
+  data: Uint8Array | Buffer; // File contents
+  filename?: string; // Original filename
+  mimeType?: string; // MIME type, e.g. "image/png"
+  ownerEmail?: string; // For per-user scoping in fallback
+}
+
+interface FileUploadResult {
+  url: string; // Public URL for the uploaded file
+  id?: string; // Provider-specific id
+  provider: string; // Which provider handled it
+}
+```
+
+Verwenden Sie `uploadFile()` von `@agent-native/core/file-upload` in actions oder Servercode:
+
+```ts
+import { uploadFile } from "@agent-native/core/file-upload";
+
+const result = await uploadFile({
+  data: fileBuffer,
+  filename: "photo.jpg",
+  mimeType: "image/jpeg",
+});
+
+if (result) {
+  // Provider handled it — result.url is the public URL
+} else {
+  // No provider configured — handle SQL fallback yourself, or skip
+}
+```

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

@@ -0,0 +1,153 @@
+---
+title: "Frames"
+description: "Der lokale Entwicklungsrahmen, das eingebettete Agent-Panel und der Cloud-Rahmen – die Art und Weise, wie ein KI-Agent neben Ihrer App ausgeführt wird."
+---
+
+# Frames
+
+Jede agentennative App wird mit einem KI-Agenten neben der App UI ausgeführt. Ein **Frame** ist
+der Wrapper, der beides hostet: Er zeigt Ihre App und gibt dem Agenten einen Platz dafür
+Chatten, ausführen und (im Entwickler) Code bearbeiten. Es gibt drei Frames, die sich eine Laufzeit teilen:
+
+- **Eingebettetes Agent-Panel** – ist in jeder App von `@agent-native/core` enthalten.
+  Dies ist die Seitenleiste, die Ihre App in der Entwicklung und in der Produktion selbst rendert.
+- **Local Dev Frame** – ein Thin Wrapper, der Ihre laufende App in einen Iframe lädt
+  und fügt das gleiche Agentenpanel sowie daneben ein integriertes CLI-Terminal hinzu. Gebraucht
+  für die lokale Entwicklung von Vorlagen in diesem Repo.
+- **Builder.io Cloud Frame** – ein verwalteter, gehosteter Frame mit Zusammenarbeit,
+  visuelle Bearbeitung und parallele Agentenausführungen.
+
+Ihr App-Code ist identisch, unabhängig davon, welcher Frame ihn hostet. Der Agent spricht
+zu Ihrer App in jedem Fall über denselben actions und Anwendungsstatus.
+
+```an-diagram title="Three frames, one runtime" summary="Your app and the agent panel are the same in every frame; only the wrapper around them changes."
+{
+  "html": "<div class=\"diagram-frames\"><div class=\"diagram-card\" data-rough><span class=\"diagram-pill accent\">Embedded panel</span><small class=\"diagram-muted\">ships in every app · dev + prod</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Local dev frame</span><small class=\"diagram-muted\">app in an iframe + panel + CLI terminal</small></div><div class=\"diagram-card\" data-rough><span class=\"diagram-pill\">Builder.io cloud frame</span><small class=\"diagram-muted\">hosted: collaboration · visual edit · parallel runs</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-box\" data-rough>Same runtime<br><small class=\"diagram-muted\">your app · actions · application state</small></div></div>",
+  "css": ".diagram-frames{display:flex;flex-direction:column;gap:10px;align-items:stretch}.diagram-frames .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px}.diagram-frames .diagram-arrow{font-size:22px;line-height:1;align-self:center}"
+}
+```
+
+## Eingebettetes Agentenfeld {#embedded-agent}
+
+Das eingebettete Panel ist die Agent-Seitenleiste, die Ihre App rendert. Im Lieferumfang ist
+`@agent-native/core` – es muss kein separates Paket installiert werden – und ist dasselbe
+Komponente in Entwicklung und Produktion.
+
+- Exportiert als `AgentPanel` von `@agent-native/core/client`, mit einem
+  Nur-Produktionsvariante `ProductionAgentPanel`.
+- Stellt die vollständige Chat-/CLI-/Workspace-Oberfläche bereit, sodass die Agenteneingabe aktiviert bleibt
+  der gemeinsam genutzte Composer-Stack, der überall sonst im Framework verwendet wird.
+- Liest `application_state.navigation` in jeder Runde, sodass es bereits weiß, welches
+  Sehen Sie sich an, in welcher Position Sie sich befinden und was ausgewählt ist – Sie müssen „dies“ nicht noch einmal erklären.
+
+### App vs. Code-Tool-Modi {#tool-modes}
+
+Das Panel läuft in einem von zwei Werkzeugmodi:
+
+- **App-Modus** – der Agent verfügt nur über die eigenen Tools Ihrer App: die actions Ihnen
+  definiert mit `defineAction`, plus Navigation und Kontext. Kein Dateisystem oder
+  Shell-Zugriff. Das bekommen Endbenutzer.
+- **Codemodus** – fügt die gemeinsam genutzten Codierungstools hinzu (`bash`, `read`, `edit`, `write`)
+  und Datenbankzugriff zusätzlich zu den App-Tools, damit der Agent die App ändern kann
+  eigene Quelle. Codeanfragen werden blockiert: wenn eine Nachricht Code erfordert
+  (`type: "code"`) und kein codefähiger Rahmen angeschlossen ist, zeigt das Panel ein
+  Dialog, der erklärt, dass Codeänderungen Agent Native Desktop oder Builder erfordern;
+  Wenn ein Frame verbunden ist, wird die Anfrage an ihn und einen Code-Agenten weitergeleitet
+  -Anzeige wird angezeigt, während es funktioniert (`useSendToAgentChat`). Für das Kanonische
+  Coding-Tool-Liste und gemeinsame UI-Verträge, siehe
+  [Agent-Native Code UI](/docs/code-agents-ui).
+
+```an-diagram title="Code-request gating" summary="A code-typed message needs a code-capable frame. With one connected, the request routes there; without one, the panel explains code changes need Desktop or Builder."
+{
+  "html": "<div class=\"diagram-gate\"><div class=\"diagram-node\" data-rough>message<br><small class=\"diagram-muted\">type: \\\"code\\\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\" data-rough>code-capable frame connected?</div><div class=\"diagram-col\"><div class=\"diagram-pill ok\">yes &rarr; route to frame, show code-agent indicator</div><div class=\"diagram-pill warn\">no &rarr; dialog: needs Desktop or Builder</div></div></div>",
+  "css": ".diagram-gate{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-gate .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-gate .diagram-arrow{font-size:22px;line-height:1}.diagram-gate .center{text-align:center}"
+}
+```
+
+„Code-Modus“ ist der Umschalter der Agent-Fähigkeit – anders als der Umgebungsentwicklungsmodus
+(`NODE_ENV` / Vite). Der Client-Hook ist `useCodeMode()`. (Siehe
+[Compatibility notes](#compatibility) für die abwärtskompatiblen Aliase.)
+
+Im lokalen Entwicklungsrahmen schaltet das Einstellungszahnrad zwischen diesen Modi um. Wechseln
+Aus dem Codemodus wird die eigene Seitenleiste des Frames ausgeblendet und der In-App-Agent der App angezeigt
+Seitenleiste stattdessen im Iframe, damit Sie genau das in der Vorschau sehen können, was Endbenutzer sehen.
+
+## Integriertes Terminal und CLI-Switching {#cli-terminal}
+
+In der Entwicklung enthält das Panel auch ein eingebettetes Terminal (`AgentTerminal`
+von `@agent-native/core/client`), unterstützt von einem PTY-Server. Sie können ein echtes
+Kodieren Sie CLI direkt neben der App und wechseln Sie zwischen ihnen; Das Terminal startet neu
+mit dem ausgewählten CLI.
+
+Die unterstützten CLIs stammen aus der zentralen CLI-Registrierung
+(`packages/core/src/terminal/cli-registry.ts`). Nur diese Befehle sind zulässig
+to spawn – der PTY-Server validiert den angeforderten Befehl anhand der Registrierung
+Zulassungsliste zur Verhinderung der Injektion:
+
+| CLI           | Befehl     | Paket installieren          |
+| ------------- | ---------- | --------------------------- |
+| Claude-Code   | `claude`   | `@anthropic-ai/claude-code` |
+| Builder.io    | `builder`  | (integriert)                |
+| Codex         | `codex`    | `@openai/codex`             |
+| Zwillinge CLI | `gemini`   | `@google/gemini-cli`        |
+| OpenCode      | `opencode` | `opencode-ai`               |
+
+Wenn das ausgewählte CLI nicht auf `PATH` gefunden wird, greift das Terminal auf dessen Ausführung zurück
+bis `npx --yes <install-package>@latest` (wo ein Installationspaket vorhanden ist). Die
+Standardbefehl ist `claude`. Wechseln Sie CLIs jederzeit in den Agent-Panel-Einstellungen
+Zeit.
+
+## Builder.io Wolkenrahmen {#cloud-frame}
+
+[Builder.io](https://www.builder.io) stellt einen verwalteten Frame bereit, der das hostet
+gleiche App und dasselbe Agentenpanel in der Cloud:
+
+- Zusammenarbeit in Echtzeit – mehrere Benutzer können gleichzeitig zuschauen und interagieren.
+- Visuelle Bearbeitung, Rollen und Berechtigungen.
+- Parallele Agentenausführung für schnellere Iteration.
+- Gut für den Teamgebrauch, bei dem sich jeder eine gehostete Umgebung teilt.
+
+Codeanfragen vom eingebetteten Panel werden auf die gleiche Weise an den Builder-Frame weitergeleitet
+Sie leiten an den lokalen Dev-Frame weiter, daher ist das obige Verhalten von dev-vs-prod wie folgt
+über beide hinweg konsistent.
+
+## Laufzeit APIs {#runtime-apis}
+
+Diese werden mit `@agent-native/core` geliefert und dienen Ihrer App zur Kommunikation mit dem
+Agent, unabhängig davon, welcher Frame ihn hostet:
+
+1. **Nachricht senden** – `sendToAgentChat()` sendet eine Nachricht an den Agenten. Die
+   `useSendToAgentChat()`-Hook umschließt es mit dem beschriebenen Code-Request-Gating
+   oben und gibt ein `codeRequiredDialog`-Element zum Rendern zurück. Siehe
+   [Drop-in Agent](/docs/drop-in-agent) für volle Nutzung und Optionen.
+2. **Generierungsstatus** – `useAgentChatGenerating()` verfolgt, wann der Agent ist
+   wird ausgeführt, sodass UI den Fortschritt anzeigen kann, ohne den Agenten direkt abzufragen.
+3. **Polling-Synchronisierung** – Durch die datenbankgestützte Synchronisierung bleiben UI-Caches aktuell, wenn der Agent ausgeführt wird
+   Ändert den Daten- oder Anwendungsstatus.
+4. **Aktionssystem** – `pnpm action <name>` sendet an dasselbe Callable
+   actions Der Agent ruft als Tools auf, sodass Sie alles tun können, was der Agent tun kann
+   Skript.
+
+## Wird ausgeführt {#running}
+
+Das eingebettete Agenten-Panel ist Teil jeder App – erstellen Sie eine Vorlage als Gerüst und fertig
+bereits da:
+
+```bash
+npx @agent-native/core@latest create my-app --template mail --standalone
+cd my-app
+pnpm dev
+```
+
+Der lokale Entwicklungsrahmen (das private `@agent-native/frame`-Paket im Framework-Repository) ist ein internes Toolpaket, das nicht auf npm veröffentlicht wird. Es lädt den Entwicklungsserver der aktiven App in einen Iframe, stellt das eingebettete Panel daneben bereit und wählt die App über den Abfrageparameter `app` aus. Das integrierte CLI-Terminal erfordert den Agent Native-Desktop, der den lokalen Code und den PTY-Zugriff bereitstellt, den das Terminal benötigt; Ohne diese Option zeigt das Panel die Chat-Oberfläche an und fordert Sie auf, Desktop zu öffnen, um CLI zu verwenden.
+
+## Kompatibilitätshinweise {#compatibility}
+
+Das Konzept des „Code-Modus“ wurde früher „Dev-Modus“ genannt, daher einige Rückkompatibilitäten
+Namen bleiben bestehen. Sie können diese ignorieren, es sei denn, Sie behalten eine ältere Integration bei
+Code:
+
+- Die zugrunde liegende `AGENT_MODE`-Umgebungsvariable, die `/_agent-native/agent-chat/mode`
+  Endpunkt (dessen Nutzlastschlüssel immer noch `devMode` ist) und der `agent-chat.mode`
+  Einstellungsschlüssel bleiben unverändert.
+- `useDevMode()` bleibt ein veralteter Alias für `useCodeMode()`.

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

@@ -0,0 +1,199 @@
+---
+title: "Erste Schritte"
+description: "Erstellen Sie eine Agenten-App, verstehen Sie die Anweisungen skills und actions und beobachten Sie dann, wie der Agent seine erste Aktion aufruft."
+---
+
+# Erste Schritte
+
+Agent-Native-Apps geben einem KI-Agenten und Ihrem UI die gleichen actions, Daten und
+Zustand. Ein Basisagent besteht aus Anweisungen, die ihn leiten, skills, die ihn lehren
+wiederholbares Verhalten und actions, mit dem es echte Arbeit leisten kann.
+
+**Möchten Sie eine vollständige App als Ausgangspunkt?** Klonen Sie eine unserer umfangreichen Vorlagen –
+[Chat](/docs/template-chat), [Mail](/docs/template-mail),
+[Calendar](/docs/template-calendar), [Content](/docs/template-content),
+[Analytics](/docs/template-analytics) und [many more](/docs/cloneable-saas) –
+Jede davon ist eine App mit vollem Funktionsumfang, die Sie anpassen können.
+
+Von Grund auf neu bauen? Die einzige Wahl im Voraus ist, ob Sie einen UI möchten –
+alles danach (Anweisungen schreiben, skills hinzufügen, actions definieren, ausführen
+der Agent) ist in beiden Fällen gleich.
+
+```an-file-tree title="A basic Agent-Native agent"
+{
+  "entries": [
+    { "path": "AGENTS.md", "note": "always-on instructions: purpose, rules, tone, and the map of what the agent can do" },
+    { "path": ".agents/skills/customer-research/SKILL.md", "note": "a reusable playbook the agent loads when the task matches" },
+    { "path": "actions/summarize-week.ts", "note": "typed code the agent, UI, CLI, HTTP, MCP, A2A, jobs, and webhooks can run" }
+  ]
+}
+```
+
+Dies gilt unabhängig davon, ob Sie mit einem Chat UI, einem Headless-Agenten oder einer vollständigen App beginnen.
+Der UI verändert die Oberfläche; Anweisungen, skills und actions geben dem Agenten seine
+Anleitung und Verhalten.
+
+## 1. Erstellen Sie Ihre App
+
+Sie benötigen [Node.js 22+](https://nodejs.org) und [pnpm](https://pnpm.io).
+
+Führen Sie `create` ohne Flags aus und Sie werden gefragt, wie Sie beginnen möchten (eine vollständige Vorlage).
+Chat oder Headless) vor allem anderen:
+
+```bash
+npx @agent-native/core@latest create my-app
+```
+
+Oder übergeben Sie ein Flag, um die Eingabeaufforderung zu überspringen:
+
+**Möchten Sie ein UI?** Beginnen Sie mit der Chat-Vorlage. Sie erhalten einen Arbeitsagenten plus ein
+Anpassbarer Chat UI, und jede von Ihnen hinzugefügte Aktion wird automatisch darin angezeigt:
+
+```bash
+npx @agent-native/core@latest create my-app --template chat
+```
+
+**Nur das Headless-Grundelement?** Headless starten – derselbe actions und Agent
+Schleife, keine UI-Shell:
+
+```bash
+npx @agent-native/core@latest create my-agent --headless
+```
+
+Installieren Sie dann aus dem von Ihnen erstellten Ordner:
+
+```bash
+cd my-agent # or my-app if you chose the Chat template
+pnpm install
+```
+
+Von hier an sind die beiden identisch.
+
+## 2. Fügen Sie eine Aktion hinzu
+
+Eine Aktion ist ein Vorgang, den Ihr Agent – und Ihr UI – aufrufen kann. Beide Gerüste
+Versenden Sie mit diesem Beispiel:
+
+```an-annotated-code title="Deine erste Action"
+{
+  "filename": "actions/hello.ts",
+  "language": "ts",
+  "code": "import { defineAction } from \"@agent-native/core/action\";\nimport { z } from \"zod\";\n\nexport default defineAction({\n  description: \"Sage Hallo vom lokalen Agenten.\",\n  schema: z.object({\n    name: z.string().default(\"world\"),\n  }),\n  http: { method: \"GET\" },\n  readOnly: true,\n  run: async ({ name }) => {\n    return { message: `Hello, ${name}!` };\n  },\n});",
+  "annotations": [
+    { "lines": "5", "label": "Tool-Beschreibung", "note": "Der Agent liest `description`, um zu entscheiden, wann er dies als Tool aufruft." },
+    { "lines": "6-8", "label": "Typisierter Vertrag", "note": "Ein zod-`schema` validiert Eingaben von jeder Oberfläche: Agent, UI, HTTP, MCP und A2A." },
+    { "lines": "9", "label": "HTTP verb", "note": "Opt this action into an auto-mounted HTTP endpoint." },
+    { "lines": "10", "label": "Read-only", "note": "`readOnly` marks the action as safe to call without approval and cacheable for queries." },
+    { "lines": "11-13", "label": "One implementation", "note": "The `run` body is the single source of truth that every surface executes." }
+  ]
+}
+```
+
+Ersetzen Sie `hello` durch den ersten echten Vorgang in Ihrer Domäne. Sie definieren es einmal;
+Jede Oberfläche nimmt es auf.
+
+Verwenden Sie `AGENTS.md` als Anleitung, die in jeder Runde gelten sollte. Verwenden Sie eine Fertigkeit, wenn
+Agent benötigt einen wiederverwendbaren Workflow oder eine wiederverwendbare Domänenprozedur. Verwenden Sie eine Aktion, wenn
+Der Agent benötigt eine typisierte, testbare Möglichkeit, Daten zu lesen, Daten zu schreiben, einen API aufzurufen oder
+Führen Sie eine Genehmigung durch.
+
+## 3. Führen Sie es aus
+
+Aktion direkt aufrufen:
+
+```bash
+pnpm action hello --name Steve
+```
+
+Oder bitten Sie den Agenten, für Sie anzurufen:
+
+```bash
+pnpm agent "Call the hello action for Steve and explain what happened."
+```
+
+Wenn Sie mit der Chat-Vorlage begonnen haben, führen Sie die App aus und verwenden Sie denselben Agenten in
+Browser – er kann bereits jede von Ihnen definierte Aktion aufrufen:
+
+```bash
+pnpm dev
+```
+
+Diese eine Aktion ist jetzt über den Chat UI, CLI, HTTP, MCP, A2A, erreichbar.
+geplante Jobs und webhooks. Einmal festlegen, von überall aus anrufen.
+
+```an-diagram title="One action, every surface" summary="A single defineAction file fans out to every consumer with no extra wiring."
+{
+  "html": "<div class=\"diagram-fan\"><div class=\"diagram-box\" data-rough>defineAction</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-surfaces\"><span class=\"diagram-pill\">Chat UI</span><span class=\"diagram-pill\">CLI</span><span class=\"diagram-pill\">HTTP</span><span class=\"diagram-pill\">MCP</span><span class=\"diagram-pill\">A2A</span><span class=\"diagram-pill\">Scheduled jobs</span><span class=\"diagram-pill\">Webhooks</span></div></div>",
+  "css": ".diagram-fan{display:flex;align-items:center;gap:14px;flex-wrap:wrap}.diagram-fan .diagram-surfaces{display:flex;flex-wrap:wrap;gap:8px;max-width:420px}.diagram-fan .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Status ist integriert
+
+Kopflos bedeutet nicht staatenlos. Actions, Sitzungen, Anwendungsstatus, Threads,
+Ausführungsverlauf und Anmeldeinformationen sind alle in SQL gespeichert. Lokal ist das SQLite bei
+`data/app.db`; In der Produktion legen Sie `DATABASE_URL` fest. Siehe
+[Deployment](/docs/deployment).
+
+```an-callout
+{
+  "tone": "info",
+  "body": "**Headless is still a real app.** The app-agent loop persists sessions, threads, runs, settings, and credentials in SQL — it is not a stateless prompt. You can add a UI later without touching your actions or state."
+}
+```
+
+## UI anpassen
+
+Wenn Sie mit der Chat-Vorlage begonnen haben, können Sie UI bearbeiten. Der Chat selbst
+ist eine kleine Route, die auf der `<AgentChatSurface>`-Komponente basiert:
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return <AgentChatSurface mode="page" className="h-full" />;
+}
+```
+
+- **`app/routes/_index.tsx`** – die Chat-Seite. Ändern Sie die Vorschläge, leer
+  Zustand und Layout.
+- **`app/root.tsx`** – die App-Shell. Fügen Sie Ihre eigenen Routen und Bildschirme rund um das
+  Agent.
+- Legen Sie den Agenten mit `<AgentSidebar>` in einen beliebigen Bildschirm und bearbeiten Sie ihn von einem aus
+  mit `sendToAgentChat()` oder führen Sie eine Aktion direkt mit
+  `useActionMutation()`.
+
+Siehe [Drop-in Agent](/docs/drop-in-agent) für den vollständigen Komponentensatz und
+[Native Chat UI](/docs/native-chat-ui) zum Rendern von Aktionsergebnissen als Tabellen
+Diagramme und getippte Karten anstelle von reinem Text.
+
+**Kopflos gestartet und später ein UI wollen?** Die Chat-Vorlage _ist_ die UI-Auffahrt –
+seine `app/`-Schicht (React Router + Vite) ist genau das, was das Headless-Gerüst ist
+lässt weg. Der sauberste Schritt besteht darin, vom Chat aus zu starten (oder ein neues Gerüst zu erstellen)
+Vorlage; Ihr `actions/`-, Agent- und SQL-Status wird unverändert übernommen. Siehe
+[Agent Surfaces](/docs/agent-surfaces) für jede Fläche dazwischen.
+
+## Projektstruktur
+
+```text
+my-app/
+  actions/         # Agent-callable actions
+  app/             # React frontend (UI templates only; omitted when headless)
+  server/          # Nitro API server (routes, plugins)
+  AGENTS.md        # Always-on agent instructions
+  .agents/         # Skills the agent can pull in when relevant
+  data/app.db      # Local SQLite state when DATABASE_URL is unset
+```
+
+## Wohin gehen Sie als nächstes?
+
+- **[Key Concepts](/docs/key-concepts)** – die Kernarchitektur: SQL, actions,
+  Synchronisierung und Kontextbewusstsein.
+- **[Actions](/docs/actions)** – die vollständige Aktion API: Schemata, HTTP, Authentifizierung und
+  Genehmigung.
+- **[Agent Surfaces](/docs/agent-surfaces)** – Headless, Chat, eingebetteter Sidecar,
+  und vollständige App.
+- **[Drop-in Agent](/docs/drop-in-agent)** – Fügen Sie den Agenten-Chat zu jeder React-App hinzu.
+- **[Deployment](/docs/deployment)** – platzieren Sie Ihre App auf Ihrer eigenen Domain.
+- **[FAQ](/docs/faq)** – Fragen zur Einrichtung und zum Produkt.