@agent-native/core 0.76.5 → 0.76.6

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

@@ -0,0 +1,155 @@
+---
+title: "CI-Evaluierungstor"
+description: "Schreiben Sie *.eval.ts-Testfälle, die den echten Agenten anhand fester Eingaben ausführen, die Ausgabe mit zusammensetzbaren Scorern bewerten und CI/Bereitstellungen auf einen Schwellenwert beschränken."
+---
+
+# CI-Evaluierungstor
+
+Auswertungen sind ein erstklassiges Testprimitiv: Sie deklarieren eine Eingabeaufforderung und das von Ihnen erwartete Verhalten. Der Läufer **führt tatsächlich die Agentenschleife aus** für diese Eingabe, bewertet die Ausgabe mit zusammensetzbaren Bewertungspunkten und wird mit einem Wert ungleich Null beendet, wenn ein Fall einen Wert unter seinem Schwellenwert aufweist. Dieser Exit ungleich Null macht `agent-native eval` zu einem Drop-in-CI-Deploy-Gate.
+
+Dies ist eine Ergänzung zur Post-hoc-Bewertung in [Observability](/docs/observability):
+
+- **Observability evals** (`observability/evals.ts`) – _„Wie hat dieser echte Lauf abgeschnitten?“_ Passiv, abgetastet, lebt neben Spuren.
+- **`*.eval.ts` (dieses Grundelement)** – _„Tut der Agent bei dieser festen Eingabe das Richtige?“_ Aktiv, deterministisch, ein CI-Gate, das über CLI ausgeführt wird.
+
+Der Runner löst eine anbieterunabhängige Engine/ein anbieterunabhängiges Modell aus der vorhandenen Registrierung auf – kein Modell ist fest codiert – sodass dieselbe Suite für jede Engine ausgeführt wird, für die die App konfiguriert ist.
+
+```an-diagram title="From fixed input to deploy gate" summary="The runner actually runs the agent loop on each case, scores the output, and exits non-zero if any scorer falls below threshold — making it a drop-in CI gate."
+{
+  "html": "<div class=\"eval-flow\"><div class=\"diagram-node\">*.eval.ts<br><small class=\"diagram-muted\">prompt + expected behavior</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Run the agent loop<br><small class=\"diagram-muted\">real engine/model</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-node\">Scorers<br><small class=\"diagram-muted\">every one must pass threshold</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box ok\">exit 0 &rarr; deploy</div><div class=\"diagram-box warn\">exit 1 &rarr; block</div></div></div>",
+  "css": ".eval-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.eval-flow .diagram-node{display:flex;flex-direction:column;gap:2px;padding:10px 14px}.eval-flow .diagram-col{display:flex;flex-direction:column;gap:8px}.eval-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
+## Eine Bewertung schreiben {#writing}
+
+Legen Sie eine `*.eval.ts`-Datei an einer beliebigen Stelle in der App ab (oder eine `evals/*.ts`-Datei). Jede Datei `export default defineEval(...)` (oder exportiert ein Array davon):
+
+```ts
+// evals/greeting.eval.ts
+import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
+
+export default defineEval({
+  name: "greets the user by name",
+  input: { prompt: "Say hi to Ada." },
+  threshold: 0.7, // per-scorer pass bar; default 0.5
+  scorers: [
+    contains("Ada"),
+    llmJudge({ criteria: "friendliness", rubric: "1.0 = warm greeting" }),
+  ],
+});
+```
+
+Eine Bewertung ist nur dann erfolgreich, wenn **jeder** Scorer den Schwellenwert erreicht. Schlüsselfelder `defineEval`:
+
+| Feld        | Typ                   | Notizen                                                                             |
+| ----------- | --------------------- | ----------------------------------------------------------------------------------- |
+| `name`      | Zeichenfolge          | Erforderlich. Wird im Bericht angezeigt.                                            |
+| `input`     | `{ prompt, history }` | Erforderlich `prompt`; optionale vorherige `{ role, text }`-Runden.                 |
+| `scorers`   | `Scorer[]`            | Erforderlich, mindestens einer.                                                     |
+| `threshold` | Nummer `0..1`         | Passleiste pro Torschütze. Standard `0.5`; überschreibbar vom CLI.                  |
+| `run`       | Funktion              | Optionale Überschreibung für benutzerdefinierte Einrichtung (Saatdaten, Multiturn). |
+
+Der den Bewertern übergebene Agentenlauf ist klein und transportunabhängig:
+
+```ts
+interface AgentRunOutput {
+  text: string; // concatenated assistant text
+  toolCalls: readonly string[]; // tool/action names, in call order
+  ok: boolean; // completed without a terminal error
+  error?: string;
+  runId: string;
+  durationMs: number;
+}
+```
+
+## Eingebaute Scorer {#built-in}
+
+Importiert von `@agent-native/core/eval`:
+
+| Scorer                   | Punktzahl                                                                                             | Modell? |
+| ------------------------ | ----------------------------------------------------------------------------------------------------- | ------- |
+| `exactMatch(expected)`   | `1.0`, wenn der Text gleich `expected` ist (gekürzt, ohne Berücksichtigung der Groß-/Kleinschreibung) | Nein    |
+| `contains(needles)`      | Anteil der erforderlichen Teilzeichenfolgen vorhanden (so dass Teiltreffer sichtbar sind)             | Nein    |
+| `usesTool(toolName)`     | `1.0`, wenn der Agent dieses Tool/diese Aktion mindestens einmal aufgerufen hat                       | Nein    |
+| `llmJudge({ criteria })` | LLM-als-Richter punktete anhand einer Rubrik in natürlicher Sprache, → `0..1`                         | Ja      |
+
+`exactMatch` und `contains` benötigen einen optionalen `{ caseSensitive }`. `llmJudge` übernimmt `{ criteria, rubric?, name?, scoreRange? }` – seine Ausgabe wird auf `[0, 1]` normalisiert, und das Richtermodell ist das, was der Läufer aufgelöst hat (niemals ein fest codierter Anbieter).
+
+## Benutzerdefinierte Scorer: die 4-stufige Pipeline {#custom}
+
+`createScorer` erstellt einen Scorer aus einer 4-stufigen Pipeline im Mastra-Stil. Es ist nur `generateScore` erforderlich:
+
+```an-diagram title="The 4-step scorer pipeline" summary="preprocess and analyze default to identity; only generateScore is required. analyze can run plain JS or call an LLM judge via ctx."
+{
+  "html": "<div class=\"scorer\"><div class=\"diagram-card\"><span class=\"diagram-pill\">preprocess(run)</span><small class=\"diagram-muted\">transform the run/output &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">analyze(x, ctx)</span><small class=\"diagram-muted\">plain JS or LLM judge &middot; optional</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">generateScore(a)</span><small class=\"diagram-muted\">&rarr; 0..1 normalized &middot; <strong>required</strong></small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">generateReason</span><small class=\"diagram-muted\">human-readable why &middot; optional</small></div></div>",
+  "css": ".scorer{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.scorer .diagram-card{display:flex;flex-direction:column;gap:2px;padding:8px 12px}.scorer .diagram-arrow{font-size:20px;line-height:1}"
+}
+```
+
+```text
+preprocess(run)     → x          transform the run/output (optional)
+analyze(x, ctx)     → analysis   plain JS OR an LLM judge (optional)
+generateScore(a)    → 0..1       REQUIRED, normalized
+generateReason(...) → string     human-readable why (optional)
+```
+
+`preprocess` und `analyze` sind standardmäßig identisch (der Scorer sieht den rohen `AgentRunOutput`). Der Schritt `analyze` erhält einen `ctx` mit einem anbieterunabhängigen `judge()`-Helfer für die von LLM unterstützte Bewertung:
+
+```ts
+import { createScorer, clamp01 } from "@agent-native/core/eval";
+
+// A scorer that rewards short, tool-using answers.
+const concise = createScorer({
+  name: "concise_with_tool",
+  analyze(run) {
+    return {
+      words: run.text.trim().split(/\s+/).length,
+      usedTool: run.toolCalls.length > 0,
+    };
+  },
+  generateScore({ words, usedTool }) {
+    if (!usedTool) return 0;
+    return clamp01(1 - Math.max(0, words - 40) / 200);
+  },
+  generateReason({ analysis }) {
+    return `${analysis.words} words, tool used: ${analysis.usedTool}`;
+  },
+});
+```
+
+## Das Tor laufen lassen {#cli}
+
+```bash
+agent-native eval                    # run every *.eval.ts; non-zero exit on failure
+agent-native eval billing            # only files whose path contains "billing"
+agent-native eval --json             # machine-readable report (for CI)
+agent-native eval --threshold 0.8    # override every eval's pass threshold (0..1)
+```
+
+Der Befehl erkennt `**/*.eval.ts` und `evals/*.ts` unter der aktuellen App, führt den Agenten für jede Eingabe aus, bewertet sie, druckt eine lesbare Tabelle (oder JSON) und **wird ungleich Null beendet, wenn eine Bewertung unter ihrem Schwellenwert liegt**.
+
+Exit-Codes:
+
+| Code | Bedeutung                                                                                           |
+| ---- | --------------------------------------------------------------------------------------------------- |
+| `0`  | Alle Evaluierungen bestanden – _oder_ es wurden keine Evaluierungsdateien gefunden (CI-freundlich). |
+| `1`  | Mindestens eine Bewertung lag unter dem Schwellenwert oder die Suite ist fehlerhaft.                |
+| `2`  | Ungültige Argumente (z. B. `--threshold` außerhalb von `[0, 1]`).                                   |
+
+### Als CI-Deploy-Gate {#ci}
+
+Fügen Sie es der Pipeline hinzu, die vor einer Bereitstellung ausgeführt wird:
+
+```yaml
+# .github/workflows/deploy.yml (excerpt)
+- run: npx agent-native eval --json
+```
+
+Eine Regression, die einen Scorer unter den Schwellenwert fallen lässt, schlägt den Schritt fehl und blockiert die Bereitstellung. Eine App ohne Evaluierungsdateien wird `0` beendet, daher ist die Übernahme von Evals eine Opt-in-Aktion pro App.
+
+## Was kommt als nächstes?
+
+- [**Observability**](/docs/observability) – Post-hoc-Bewertung realer Produktionsläufe (die ergänzende Ebene)
+- [**Actions**](/docs/actions) – die tools/actions, die in `toolCalls` angezeigt werden
+- [**Agent Teams**](/docs/agent-teams) – Subagenten, die eine Bewertung ausführen könnte

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

@@ -0,0 +1,360 @@
+---
+title: "Erweiterungen"
+description: "Mini-Apps, die Ihre Benutzer in Ihrer Vorlage erstellen – eine benutzerdefinierte KPI-Kachel in Analytics, eine Checkliste zur Besprechungsvorbereitung in Kalender, ein Kontakt-CRM-Widget in Mail. Keine Bereitstellungen, keine Codebearbeitungen, keine Schemaänderungen."
+---
+
+# Erweiterungen
+
+Erweiterungen sind **Mini-Apps, die Ihre Benutzer innerhalb Ihrer Vorlage erstellen**.
+
+Wenn Sie QuickBooks Online verwendet haben, haben Sie das Modell gesehen: QBO liefert ein zentrales Buchhaltungsprodukt und Benutzer überlagern kleine benutzerdefinierte Widgets – einen benutzerdefinierten Bericht, einen Gehaltsabrechnungsrechner, einen Steuerregelprüfer –, die in derselben App gespeichert sind und dieselben Daten verwenden. Erweiterungen sind die agentennative Version dieser Idee, mit der Ausnahme, dass Ihre Benutzer keinen Code schreiben. Sie beschreiben, was sie wollen, und der Agent baut es auf.
+
+Der Rahmen ist wichtig: Eine Erweiterung ist keine generische Sandbox „Machen Sie, was Sie wollen“. Es handelt sich um eine **Mini-App, die eine bestimmte Vorlage** – Mail, Analytics, Kalender, Clips, Design – erweitert und die actions und Daten dieser Vorlage verwendet. Eine Mail-Erweiterung liest E-Mails. Eine Analytics-Erweiterung liest die Metriken eines Dashboards. Eine Kalendererweiterung wirkt auf das offene Ereignis. Sie fühlen sich als Teil des Host-Produkts, weil sie Teil des Host-Produkts sind.
+
+Drei Dinge sorgen dafür, dass Erweiterungen funktionieren:
+
+- **Kein Code, keine Bereitstellung.** Der Agent schreibt sie und sie sind in Sekundenschnelle live. Wird in der Datenbank gespeichert, nicht im Repo.
+- **Voller Zugriff auf die Daten der Vorlage.** Erweiterungen können denselben actions aufrufen, den der Agent aufruft – `list-emails` in Mail, `list-decks` in Folien, `list-recordings` in Clips – sodass sie über alles verfügen, was die Host-App hat.
+- **Integrierter Speicher.** Jede Erweiterung verfügt über einen eigenen Schlüsselwertspeicher pro Benutzer/pro Organisation, sodass der Status gespeichert werden kann, ohne dass Sie eine neue SQL-Tabelle hinzufügen müssen.
+
+Wenn eine Vorlage keine vom Benutzer erstellten Erweiterungen verfügbar machen soll, legen Sie fest
+`extensionTools: false` auf `createAgentChatPlugin()`. Dadurch wird das
+agentenseitige Erweiterung actions und schnelle Anleitung beim Verlassen des Rests
+App-Agent intakt.
+
+```an-diagram title="The sandbox bridge" summary="Extension HTML runs in an isolated iframe and reaches the host only through a fixed set of bridge helpers — every call is scoped and access-checked."
+{
+  "html": "<div class=\"ext-bridge\"><div class=\"diagram-card sandbox\" data-rough><span class=\"diagram-pill warn\">Sandboxed iframe</span><small class=\"diagram-muted\">Alpine.js HTML &middot; no host cookies, session, or DOM</small><div class=\"ext-helpers\"><span class=\"diagram-pill\">appAction</span><span class=\"diagram-pill\">appFetch</span><span class=\"diagram-pill\">dbQuery / dbExec</span><span class=\"diagram-pill\">extensionData</span><span class=\"diagram-pill\">extensionFetch</span></div></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Host template<br><small class=\"diagram-muted\">actions, auto-scoped SQL</small></div><div class=\"diagram-box\">Secret proxy<br><small class=\"diagram-muted\"><code>${keys.NAME}</code>, domain-locked</small></div><div class=\"diagram-box\">External APIs<br><small class=\"diagram-muted\">via extensionFetch only</small></div></div></div>",
+  "css": ".ext-bridge{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ext-bridge .sandbox{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:240px}.ext-bridge .ext-helpers{display:flex;flex-wrap:wrap;gap:6px;margin-top:4px}.ext-bridge .diagram-col{display:flex;flex-direction:column;gap:8px}.ext-bridge .diagram-arrow{font-size:24px}"
+}
+```
+
+Erweiterungen können auch **im lokalen Dateimodus** per Repo gesichert werden. In diesem Workflow
+`agent-native.json` deklariert einen `extensions`-Ordner, jede Erweiterung hat eine
+`extension.json`-Manifest plus eine HTML-Eintragsdatei, und die App rendert diese
+Dateien über dieselbe Sandbox. Dateigestützte Erweiterungen werden durch Ändern
+die Repo-Dateien; Datenbankgestützte Erweiterungen sorgen dafür, dass die Laufzeit erstellt/bearbeitet/freigegeben wird
+Erfahrung unten beschrieben.
+
+## Eine kurze Galerie {#gallery}
+
+Echte Erweiterungen, die Menschen tatsächlich bauen würden, gruppiert nach der Vorlage, in der sie leben. Jede einzelne ist eine fokussierte Sache – kein Schweizer Taschenmesser.
+
+### Mail
+
+Ein Benutzer liest eine E-Mail von `priya@acme.com`. Welche Art von Widget würde da helfen?
+
+- **Kontaktnotizen** – ein Haftnotizblock, der an denjenigen geheftet wird, dem der Benutzer eine E-Mail sendet. Lädt Notizen für diesen Kontakt und ermöglicht dem Benutzer, weitere Notizen zu machen.
+- **Neueste Threads mit dieser Person** – eine kleine Liste der letzten fünf Threads mit dem offenen Kontakt, getrennt von der Posteingangsansicht.
+- **CRM-Anreicherung** – ruft die Unternehmensgröße des Kontakts, das letzte Besprechungsdatum oder offene Geschäfte aus Ihrem CRM ab.
+- **Verknüpfung zum Terminplaner** – verwandelt „Nächste Woche einen Termin finden“ in ein One-Click-Widget „Diese Termine senden“.
+
+Skizze – Kontaktnotizen (speichert eine Notiz, die an die Person gebunden ist, der Sie eine E-Mail senden):
+
+```html
+<div
+  class="p-4"
+  x-data="{
+    contactEmail: window.slotContext?.contactEmail,
+    note: '',
+    async init() {
+      if (!this.contactEmail) return;
+      const saved = await extensionData.get('notes', this.contactEmail);
+      if (saved) this.note = JSON.parse(saved.data).text;
+    },
+    async save() {
+      await extensionData.set('notes', this.contactEmail, { text: this.note });
+    }
+  }"
+>
+  <p class="text-xs text-muted-foreground mb-2" x-text="contactEmail"></p>
+  <textarea
+    x-model="note"
+    @blur="save()"
+    class="w-full rounded-md border bg-background p-2 text-sm"
+    rows="4"
+    placeholder="Notes about this contact..."
+  ></textarea>
+</div>
+```
+
+### Analysen
+
+Ein Benutzer starrt auf ein Dashboard. Was ist die fehlende Kachel?
+
+- **Benutzerdefiniertes KPI-Feld** – eine einzelne große Zahl für eine Metrik, die kein integriertes Panel ist. „Die Tests haben diese Woche begonnen“, „MRR Delta im Vergleich zum letzten Monat.“
+- **Ziel-Tracker** – ruft eine vom Benutzer ausgewählte Metrik ab und zeigt den Fortschritt im Vergleich zu einem vom Benutzer eingegebenen Ziel an.
+- **Top-Kunden-Bestenliste** – verbindet eine Metrik mit einer Kundentabelle und ordnet die Top 10 ein.
+
+Skizze – Benutzerdefiniertes KPI-Feld (ruft eine der `appAction`-Abfragen der Analysevorlage auf):
+
+```html
+<div
+  class="p-4"
+  x-data="{
+  value: null,
+  async init() {
+    const result = await appAction('query-agent-native-analytics', {
+      metric: 'trials_started',
+      range: '7d'
+    });
+    this.value = result?.total ?? 0;
+  }
+}"
+>
+  <p class="text-xs uppercase tracking-wider text-muted-foreground">
+    Trials this week
+  </p>
+  <p class="text-3xl font-bold mt-1" x-text="value ?? '—'"></p>
+</div>
+```
+
+### Kalender
+
+Der Benutzer hat eine offene Veranstaltung. Was würde in diesem Moment helfen?
+
+- **Checkliste für die Besprechungsvorbereitung** – lädt automatisch Tagesordnungspunkte, Teilnehmer und frühere Thread-Zusammenfassungen für die offene Veranstaltung.
+- **Reisezeit** – „Sie haben 35 Minuten bis zu Ihrem nächsten Treffen am Missionsort.“
+- **Zeitzonen-Helfer** – zeigt auf einen Blick die Besprechungszeit in der Ortszeit jedes Teilnehmers an.
+
+### Clips
+
+Ein Benutzer überprüft eine Bildschirmaufzeichnung. Was verbessert diese Ansicht?
+
+- **Action Item Extractor** – liest das Clip-Transkript (der Agent ruft es über `appAction` ab) und listet die Aufgaben auf.
+- **Auto-Share** – mit einem Klick „Link dieses Clips auf meinem #recordings Slack-Kanal posten“
+- **Highlight Reel** – ruft die vom Agenten generierten Kapitel ab und wandelt sie in ein Schnellnavigationsmenü um.
+
+### Design
+
+Ein Benutzer hat einen Entwurf einer Alpine/Tailwind-Seite geöffnet. Was würde die Prototyping-Schleife glätten?
+
+- **Markenfarbfeld** – Palette aus der Markenkonfiguration des Benutzers. Klicken Sie hier, um eine Farbe in den Editor zu kopieren.
+- **Asset-Auswahl** – listet Bilder auf, die der Benutzer hochgeladen hat, und löscht das URL beim Klicken.
+- **Abstandsinspektor** – zeigt die Abstands-/Abstands-/Rand-Tokens an, die die aktive Seite verwendet, damit der Benutzer konsistent bleiben kann.
+
+Muster in all diesen Punkten: Bei Erweiterungen geht es um **den Moment**, in dem sich der Benutzer in der Host-Vorlage befindet. Der Agent weiß bereits, welcher Kontakt, welches Dashboard, welches Ereignis, welcher Clip – die Erweiterung verwendet diesen Kontext.
+
+## Wie ein Benutzer eines erstellt {#building}
+
+Der einfache Pfad:
+
+1. **Klicken Sie in der Seitenleiste auf „Neue Erweiterung“** (oder fragen Sie einfach im Chat).
+2. **Beschreiben Sie in einem Satz, was Sie möchten.** „Ein Haftnotizblock für den Kontakt, dem ich eine E-Mail sende.“ „Eine KPI-Box für Testversionen ist diese Woche gestartet.“
+3. **Der Agent schreibt es und es erscheint in Ihrer Erweiterungsliste und ist einsatzbereit.**
+
+Keine Datei zum Bearbeiten, keine Bereitstellung. Der Agent wählt die richtigen Helfer aus (`appAction`, `extensionData`, `extensionFetch`) und schreibt die Alpine.js HTML.
+
+Wenn die Erweiterung einen API-Schlüssel benötigt – ein CRM-Token, ein Wetter-API – teilt Ihnen der Agent mit, was und wo Sie ihn hinzufügen müssen. Schlüssel werden verschlüsselt gespeichert und für bestimmte Domänen gesperrt.
+
+Wenn Sie später etwas ändern möchten, sagen Sie es einfach: „Fügen Sie ein Suchfeld zu meinen Kontaktnotizen hinzu.“ Der Agent bearbeitet das HTML an Ort und Stelle – keine Neugenerierung des Ganzen.
+
+Jede Änderung wird versioniert. Öffnen Sie das Verlaufssteuerelement des Erweiterungs-Viewers, um
+gespeicherte Versionen, überprüfen Sie den Unterschied zur vorherigen Version und stellen Sie eine
+älterer Name/Beschreibung/Symbol/Inhalts-Snapshot ohne Eigentümerwechsel oder
+Teilen.
+
+## Was eine Erweiterung bewirken kann {#capabilities}
+
+Innerhalb der Iframe-Sandbox verfügt jede Erweiterung über diese Helfer auf `window`:
+
+| Helfer                                           | Zweck                                                               | Beispiel                                                  |
+| ------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------------------------- |
+| `appAction(name, params)`                        | Rufen Sie einen beliebigen actions der Host-Vorlage auf             | `appAction('list-emails', { view: 'inbox' })`             |
+| `appFetch(path, options)`                        | Zulässige Framework-Endpunkte unter `/_agent-native/*` aufrufen     | `appFetch('/_agent-native/application-state/navigation')` |
+| `dbQuery(sql, args)`                             | Lesen aus SQL (automatisch auf den Benutzer beschränkt)             | `dbQuery('SELECT id, name FROM tools')`                   |
+| `dbExec(sql, args)`                              | In SQL schreiben                                                    | `dbExec('INSERT INTO ...')`                               |
+| `extensionFetch(url, options)`                   | Treffen Sie externe APIs über einen sicheren Proxy mit Geheimnissen | `extensionFetch('https://api.github.com/user')`           |
+| `extensionData.set(collection, id, data, opts?)` | Daten pro Erweiterung beibehalten (Benutzer-/Organisationsbereich)  | `extensionData.set('notes', id, { text: '...' })`         |
+| `extensionData.list(collection, opts?)`          | Persistente Elemente auflisten                                      | `extensionData.list('notes', { scope: 'all' })`           |
+| `extensionData.get(collection, id, opts?)`       | Einen einzelnen Artikel erhalten                                    | `extensionData.get('notes', 'note-1')`                    |
+| `extensionData.remove(collection, id, opts?)`    | Ein persistentes Element löschen                                    | `extensionData.remove('notes', 'note-1')`                 |
+
+Drei Faustregeln:
+
+- **Bevorzugen Sie `appAction` gegenüber `dbQuery`.** Actions sind die offizielle Oberfläche der Vorlage – sie übernehmen die Zugriffskontrolle, das Scoping und die Validierung für Sie. Greifen Sie nur dann zum rohen SQL, wenn keine Aktion passt.
+- **Verwenden Sie `appAction` für Vorlagendaten.** Die Erweiterung `appFetch` ist auf Framework-`/_agent-native/*`-Endpunkte beschränkt; Vorlage `/api/*`-Routen werden von der Iframe-Brücke blockiert.
+- **Bevorzugen Sie `extensionData` gegenüber dem Erstellen neuer Tabellen.** Jede Erweiterung erhält ihren eigenen isolierten Schlüsselwertspeicher. Kein Schema, keine Migration. Stellen Sie `{ scope: 'org' }` so ein, dass es mit der Organisation des Benutzers geteilt wird, und `'user'` (Standard) auf „Privat“.
+
+```html
+<script>
+  // Private to me
+  await extensionData.set('notes', 'note-1', { title: 'My note' });
+
+  // Shared with my org
+  await extensionData.set('notes', 'team-note', { title: 'Team note' }, { scope: 'org' });
+
+  // List everything visible to me (mine + org)
+  const all = await extensionData.list('notes', { scope: 'all' });
+</script>
+```
+
+Externe APIs durchlaufen `extensionFetch`, das die Anrufserverseite weiterleitet und Geheimnisse über die `${keys.NAME}`-Vorlage ersetzt:
+
+```html
+<script>
+  const res = await extensionFetch('https://api.github.com/user', {
+    headers: { Authorization: 'Bearer ${keys.GITHUB_TOKEN}' },
+  });
+</script>
+```
+
+Der eigentliche Schlüssel erreicht nie den Browser. Jeder Schlüssel ist an eine Zulassungsliste von Domänen gebunden, sodass eine durchgesickerte Erweiterung ihn nicht anderswo herausfiltern kann.
+
+## Slots – Einfügen einer Erweiterung in den Host UI {#slots}
+
+In der Galerie oben wird beschrieben, was eine Erweiterung bewirkt. Slots beschreiben, _wo_ es erscheint.
+
+Standardmäßig befindet sich eine Erweiterung auf einer eigenen Seite in der Erweiterungsliste – öffnen Sie sie wie eine kleine App. Das ist für Dashboards, Taschenrechner und eigenständige Widgets in Ordnung.
+
+Aber der QBO-typischste Anwendungsfall ist anders: Der Benutzer möchte, dass sein Widget _innerhalb_ des UI der Vorlage angeheftet wird – unter den Kontaktinformationen in der Seitenleiste von Mail, in der Ecke eines Analytics-Dashboards, auf der rechten Seite eines Kalenderereignisses. Dafür sind **Slots** da.
+
+Ein Slot ist ein benannter Widget-Bereich, den eine Vorlage enthält:
+
+| Vorlage      | Beispielslot                   | Wo es angezeigt wird                                  |
+| ------------ | ------------------------------ | ----------------------------------------------------- |
+| **Mail**     | `mail.contact-sidebar.bottom`  | Unter den Kontaktinformationen in jedem E-Mail-Thread |
+| **Analysen** | `analytics.dashboard.tiles`    | Neben den integrierten Panels des Dashboards          |
+| **Kalender** | `calendar.event-detail.bottom` | Unterhalb der offenen Veranstaltung                   |
+| **Clips**    | `clips.right-panel.tabs`       | Eine neue Registerkarte im Clip-Überprüfungsfenster   |
+
+Wenn eine Erweiterung **in einem Steckplatz installiert** wird, schiebt der Host den relevanten Kontext – die E-Mail-Adresse des Kontakts, die Dashboard-ID, die Ereignis-ID – in den Iframe. Die Erweiterung lautet `window.slotContext`, um zu wissen, was der Benutzer sieht.
+
+```an-diagram title="Slots push context into the widget" summary="The host template owns named slots; installing an extension into one feeds it window.slotContext for whatever the user is currently viewing."
+{
+"html": "<div class=\"slot\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Mail thread</span><small class=\"diagram-muted\">slot <code>mail.contact-sidebar.bottom</code></small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box accent\"><code>window.slotContext</code><br><small class=\"diagram-muted\">{ contactEmail }</small></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Contact notes</span><small class=\"diagram-muted\">loads notes for that contact &mdash; same widget, different context</small></div></div>",
+"css": ".slot{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.slot .diagram-card{display:flex;flex-direction:column;gap:4px;padding:14px 16px;min-width:180px}.slot .diagram-arrow{font-size:22px}"
+}
+
+```
+
+### Ein konkretes Beispiel
+
+Stellen Sie sich die Erweiterung „Kontaktnotizen“ aus der Galerie vor. Für sich genommen handelt es sich um ein eigenständiges Widget. Damit es in der Seitenleiste des E-Mail-Kontakts angezeigt wird:
+
+1. Erstellen Sie die Erweiterung einmal. Verwenden Sie `window.slotContext.contactEmail`, damit es weiß, bei welchem Kontakt sich der Benutzer befindet.
+2. Sagen Sie ihm den Steckplatz, den es füllen kann: `add-extension-slot-target { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
+3. Installieren Sie es: `install-extension { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
+
+Wenn Sie das nächste Mal einen E-Mail-Thread öffnen, befindet sich Ihr Haftnotizblock direkt unter den Kontaktinformationen – gefüllt mit Notizen für die Person, der Sie eine E-Mail senden. Wechseln Sie zu einem anderen Thread, die Notizen für _diesen_ Kontakt werden geladen. Gleiche Erweiterung, anderer Kontext, kein Umschreiben.
+
+In der Praxis führen Sie diese drei Befehle nicht manuell aus. Sagen Sie einfach „Dieses Widget an meine Kontaktseitenleiste anheften“ und der Agent kümmert sich um Targeting und Installation für Sie.
+
+> **Slots sind eine _zusätzliche_ Funktion, keine Voraussetzung.** Viele nützliche Erweiterungen werden nie in einem Slot installiert – sie leben glücklich auf ihrer eigenen Seite. Greifen Sie nach Slots, wenn das Widget _neben_ dem sein muss, was der Benutzer in der Host-Vorlage sieht.
+
+Ausführlichere Informationen zu Slots – wie Sie sie in Ihrer Vorlage deklarieren, wie der Kontextvertrag funktioniert, wie Installationen festgelegt werden – finden Sie im `extension-points`-Skill. Skills wird in jeder Gerüstvorlage unter `.agents/skills/` geliefert; Informationen zur Funktionsweise finden Sie unter [Skills Guide](/docs/skills-guide).
+
+## Lokale Dateierweiterungen {#local-file-extensions}
+
+Der lokale Dateimodus ermöglicht es einem Arbeitsbereich, Erweiterungen im Repo zu behalten:
+
+```text
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+Fügen Sie den Ordner zur entsprechenden App in `agent-native.json` hinzu:
+
+```json
+{
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [{ "name": "Docs", "path": "docs", "extensions": [".mdx"] }],
+      "components": "components",
+      "extensions": "extensions"
+    }
+  }
+}
+```
+
+Die App listet dateigestützte Erweiterungen neben datenbankgestützten Erweiterungen auf und rendert
+sie über den normalen Sandbox-Iframe. Slot-Deklarationen in `extension.json`
+mounten Sie die Erweiterung automatisch in passende `ExtensionSlot`s; Es gibt keine pro Benutzer
+SQL Installationszeile für lokale Erweiterungen.
+
+Lokale Erweiterungen haben ein strengeres v1-Berechtigungsmodell:
+
+- `extensionData` ist für den kleinen Laufzeitstatus verfügbar, sofern es nicht deaktiviert ist.
+- `appAction`-Aufrufe müssen explizit in `permissions.appActions` aufgeführt werden.
+- `dbQuery`, `dbExec` und `extensionFetch` sind vorerst blockiert.
+- SQL-gestützte Aktualisierung, Löschung, Freigabe und Verlauf actions geben eine Meldung zurück, die
+  zeigt zurück auf die lokale Eintragsdatei.
+
+Verwenden Sie datenbankgestützte Erweiterungen, wenn Benutzer Widgets erstellen/teilen/bearbeiten sollen
+Laufzeit. Verwenden Sie zuerst lokale Dateierweiterungen, wenn die Erweiterung Teil eines Repositorys ist
+Arbeitsbereich und sollte mit dem Rest überprüfbar, patchbar und versionierbar sein
+die Dateien.
+
+## Teilen {#sharing}
+
+Erweiterungen sind standardmäßig privat für den Benutzer, der sie erstellt hat. Zum Teilen:
+
+- **Organisationssichtbar** – jeder in der Organisation kann es sehen und verwenden.
+- **Zuschüsse pro Benutzer** – Laden Sie bestimmte Personen als Betrachter/Redakteur/Administrator ein.
+
+Freigegebene Erweiterungen haben ihre eigenen URLs und werden in denselben Freigabedialog eingebunden wie Dokumente, Decks und Dashboards. Slot-Installationen sind immer persönlich – das Teilen einer Erweiterung bedeutet, dass andere sie installieren können; Es wird nicht automatisch an UI angeheftet.
+
+## Erweiterungen vs. Bearbeiten des App-Codes {#vs-app-code}
+
+Mit dem Framework kann der Agent den Quellcode der App direkt bearbeiten – Komponenten, Routen, Stile. Wann sollten Sie stattdessen zu einer Erweiterung greifen?
+
+|                                   | Erweiterung                                                                   | App-Code bearbeiten                                      |
+| --------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **Erstellt von**                  | Agent (oder Benutzer) zur Laufzeit                                            | Agent bearbeitet Quelldateien                            |
+| **Gespeichert in**                | Die Datenbank                                                                 | Das Git-Repository                                       |
+| **Erfordert einen Build**         | Nein                                                                          | Ja                                                       |
+| **Erfordert eine Bereitstellung** | Nein                                                                          | Ja                                                       |
+| **Umfang**                        | Ein Benutzer (oder mit der Organisation geteilt)                              | Das gesamte Produkt, jeder Benutzer                      |
+| **Am besten für**                 | Persönliche Widgets, benutzerdefinierte KPIs, teamspezifische Dienstprogramme | Kernfunktionen, die allen Benutzern zur Verfügung stehen |
+
+Faustregel: **Wenn es für einen Benutzer oder ein Team ist, handelt es sich um eine Erweiterung.** Wenn jeder Benutzer der Vorlage sie erhalten soll, liefern Sie sie als echtes Feature aus.
+
+## Sicherheit {#security}
+
+```an-callout
+{ "tone": "success", "body": "**The raw secret never reaches the browser.** `extensionFetch` substitutes `${keys.NAME}` server-side and each key is locked to a URL allowlist, so even a leaked extension can't exfiltrate it elsewhere." }
+```
+
+Erweiterungen werden in einem Sandbox-Iframe ausgeführt:
+
+- **Isoliert** von den Cookies, der Sitzung und DOM der übergeordneten App.
+- **Serverseitige geheime Injektion** über die `${keys.NAME}`-Vorlage – der tatsächliche Schlüsselwert erreicht nie den Browser.
+- **Domänengesperrte Geheimnisse** – jeder Schlüssel ist an eine URL-Zulassungsliste gebunden; Der Proxy lehnt Anfragen an andere Hosts ab.
+- **Privater Netzwerkschutz** – Erweiterungen können interne Adressen nicht erreichen.
+- **Authentifizierung erforderlich** – Erweiterungen werden nur für angemeldete Benutzer ausgeführt und `dbQuery`-/`dbExec`-Aufrufe werden automatisch eingeschränkt.
+
+## Ein paar Dinge, die Sie über die Benennung wissen sollten {#naming-back-compat}
+
+Wenn Sie im SQL oder in der Quelle herumstöbern, werden Sie eine Mischung aus „Erweiterungs“- und „Tool“-Namen sehen. Schnelldecoder:
+
+- Das dem Benutzer zugewandte Grundelement hieß früher „Tools“. Es heißt jetzt **Erweiterungen**.
+- Die physischen SQL-Tabellen (`tools`, `tool_data`, `tool_shares`, `tool_slots`, `tool_slot_installs`) behalten ihre ursprünglichen Namen – das Umbenennen einer Tabelle ist eine destruktive Migration, und das Framework liefert keine destruktiven Migrationen aus.
+- Die Drizzle-/TypeScript-Exporte verwenden die neuen Namen: `extensions`, `extensionData`, `extensionShares`, `extensionSlots`, `extensionSlotInstalls`.
+- Im Iframe einer Erweiterung sind die kanonischen Helfer `extensionFetch` und `extensionData`. Die alten Namen `toolFetch` und `toolData` werden weiterhin aufgelöst, sodass die ältere Erweiterung HTML weiterhin funktioniert.
+
+Sie werden dies auch bei normaler Verwendung nicht sehen, aber der Agent verfügt über ein drittes verwandtes Konzept namens „LLM-Tools“ – die Funktionsaufrufoberfläche auf einer Modelldrehung (definiert über `defineAction`, MCP usw.). Dabei handelt es sich um das funktionsaufrufende Grundelement, nicht um die benutzerorientierten Widgets. Wenn auf dieser Seite „Erweiterung“ steht, ist damit das für den Benutzer sichtbare Widget gemeint. Wenn andere Dokumente neben `defineAction` „Tool“ sagen, ist das das LLM-Konzept.
+
+## Was kommt als nächstes?
+
+- [**Templates**](/docs/cloneable-saas) – die Host-App-Erweiterungen werden erweitert
+- [**Actions**](/docs/actions) – die Vorgänge, die eine Erweiterung über `appAction` aufruft
+- [**Sharing & Privacy**](/docs/sharing) – wie Erweiterungssichtbarkeit, Organisationsfreigabe und benutzerspezifische Gewährungen funktionieren
+- [**Onboarding & API Keys**](/docs/onboarding) – wie Geheimnisse in den Einstellungen ans Licht kommen UI
+- [**Security**](/docs/security) – das Datenbereichs- und Zugriffsmodell des Frameworks