From baebd79cc82689de136c828b8390d6af55c39559 Mon Sep 17 00:00:00 2001
From: Claude Fable 5 <fable-5@waidele.info>
Date: Sun, 12 Jul 2026 19:28:50 +0200
Subject: [PATCH] German translations of the seven user-facing docs under
 docs/de/

Mirrors the English tree (docs/de/{features.md,manual/*,developer/
extending.md}) so relative links between translated guides resolve
within the German set; links into untranslated areas (self-hosting,
architecture, deploy) point at the English files and say so. Every
quoted UI label matches the actual German interface strings. Each
pair of files cross-links the other language; English stays
authoritative when the two diverge.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
---
 README.md                          |   3 +-
 docs/de/developer/extending.md     | 167 +++++++++++++++++++++++++++++
 docs/de/features.md                | 125 +++++++++++++++++++++
 docs/de/manual/README.md           |  20 ++++
 docs/de/manual/api-guide.md        | 142 ++++++++++++++++++++++++
 docs/de/manual/mcp-guide.md        | 105 ++++++++++++++++++
 docs/de/manual/pond-admin-guide.md | 120 +++++++++++++++++++++
 docs/de/manual/site-admin-guide.md | 149 +++++++++++++++++++++++++
 docs/de/manual/user-guide.md       | 136 +++++++++++++++++++++++
 docs/developer/extending.md        |   2 +
 docs/features.md                   |   2 +
 docs/manual/README.md              |   5 +-
 docs/manual/api-guide.md           |   2 +
 docs/manual/mcp-guide.md           |   2 +
 docs/manual/pond-admin-guide.md    |   2 +
 docs/manual/site-admin-guide.md    |   2 +
 docs/manual/user-guide.md          |   2 +
 17 files changed, 983 insertions(+), 3 deletions(-)
 create mode 100644 docs/de/developer/extending.md
 create mode 100644 docs/de/features.md
 create mode 100644 docs/de/manual/README.md
 create mode 100644 docs/de/manual/api-guide.md
 create mode 100644 docs/de/manual/mcp-guide.md
 create mode 100644 docs/de/manual/pond-admin-guide.md
 create mode 100644 docs/de/manual/site-admin-guide.md
 create mode 100644 docs/de/manual/user-guide.md

diff --git a/README.md b/README.md
index fddca47..dceeb8f 100644
--- a/README.md
+++ b/README.md
@@ -36,7 +36,8 @@ offline support.
 
 - **What is Dorfteich?** — [`docs/features.md`](docs/features.md)
 - **Manuals** (user / pond admin / site admin / API / MCP) —
-  [`docs/manual/`](docs/manual/README.md)
+  [`docs/manual/`](docs/manual/README.md), auf Deutsch:
+  [`docs/de/`](docs/de/manual/README.md)
 - **Extending it** (plugins, core) —
   [`docs/developer/extending.md`](docs/developer/extending.md)
 - **Running it** — [`docs/self-hosting/`](docs/self-hosting/README.md)
diff --git a/docs/de/developer/extending.md b/docs/de/developer/extending.md
new file mode 100644
index 0000000..1eacdea
--- /dev/null
+++ b/docs/de/developer/extending.md
@@ -0,0 +1,167 @@
+# Entwicklerhandbuch — Dorfteich erweitern
+
+_Englisches Original: [docs/developer/extending.md](../../developer/extending.md)_
+
+Zwei Wege, Dorfteich mehr beizubringen: ein **Plugin** schreiben (kein
+Fork, kein Redeploy, konstruktionsbedingt sicher) oder am **Kern**
+mitarbeiten. Beginne mit einem Plugin, außer du musst ändern, wie das
+Produkt selbst funktioniert.
+
+## Ein Plugin schreiben
+
+Lies einmal
+[`docs/architecture/plugin-architecture.md`](../../architecture/plugin-architecture.md)
+(englisch) — das ist der Vertrag. Die Kurzfassung:
+
+Ein Plugin ist ein ZIP mit einer `manifest.json`, einem einzelnen
+ES-Modul-Bundle `plugin.js`, optional `styles.css`, `i18n/*.json` und
+`assets/…`. Es steuert einen oder mehrere **Erweiterungspunkte** bei:
+
+| Typ            | Du baust                                                       | Beispiel               |
+| -------------- | -------------------------------------------------------------- | ---------------------- |
+| `sectionStyle` | benannte CSS-Stile für Inhaltsabschnitte (ganz ohne Code)      | `section-styles-basic` |
+| `pageTool`     | ein Nur-Lese-Widget im Seiten-Werkzeuge-Panel                  | `toc`, `page-index`    |
+| `block`        | ein eigener Editor-Block mit eigenen Daten und Bearbeitungs-UI | `mermaid`, `drawio`    |
+
+### Die Sandbox — was dein Code kann und was nicht
+
+Dein `plugin.js` läuft in einem `<iframe sandbox="allow-scripts">` mit
+opakem Origin und strikter CSP: **keine Cookies, kein Storage, kein
+Eltern-DOM, Netzwerk/Frames nur zu deinen eigenen gebündelten Assets** —
+nie zur API oder einem externen Host. Alles andere läuft über die
+typisierte RPC des SDK, ausgeführt mit den Berechtigungen der
+_betrachtenden Person_:
+
+```ts
+import { createPlugin, windowTransport } from '@dorfteich/plugin-sdk';
+
+const { host } = createPlugin({
+  transport: windowTransport({
+    target: { postMessage: (m) => window.parent.postMessage(m, '*') },
+    source: window,
+  }),
+  onRender: async (ctx) => {
+    const outline = await host.readCurrentPage.getOutline();
+    document.body.textContent = outline.map((e) => e.text).join('\n');
+    void host.ui.resize(document.body.scrollHeight + 16);
+  },
+  onEdit: async (ctx) => {
+    /* Block-Plugins: Bearbeitungs-UI; persistieren via host.blockData.setData(...) */
+  },
+});
+```
+
+Fähigkeiten, die du im Manifest unter `permissions` deklarieren kannst,
+und was sie freischalten: `readCurrentPage` (Gliederung/Inhalt/
+Metadaten), `readPond` (Seitenlisten + Inhalte), `readBlock`
+(Block-Lesezugriffe über Seiten hinweg), `blockData`
+(`getData`/`setData` deines Blocks — Schreibzugriffe werden normale
+Dokumentänderungen, repliziert und versioniert), `ui` (`resize`,
+`openPage`, `toast`, `scrollToHeading`,
+`enterFullscreen`/`exitFullscreen`). Aufrufe außerhalb des deklarierten
+Satzes werden zur Laufzeit abgelehnt.
+
+### Block-Plugins in drei Sätzen
+
+Der Host mountet deinen Frame pro Block und ruft `render` (Ansicht)
+oder `edit` (die Person hat den Bearbeiten-Knopf des Blocks gedrückt).
+Persistiere `{ …deineDaten }` via `host.blockData.setData` — die Frames
+der Mitarbeitenden rendern live neu, wenn sich die Daten unter ihnen
+ändern. Lege neben deinen Quelldaten einen statischen Schnappschuss ab
+(z. B. einen `svg`-String): Exporte und die öffentliche Ansicht zeigen
+ihn über die `fallback`-Mechanik des Manifests, ohne je Plugin-Code
+auszuführen.
+
+### Gebündelte Apps und Vollbild
+
+Ein Plugin darf eine ganze Unter-Anwendung als Assets mitbringen und in
+einem Kind-iframe seines eigenen Asset-Pfads ausführen — so bettet das
+`drawio`-Plugin den echten draw.io-Editor ein. Kombiniere das mit
+`host.ui.enterFullscreen()` für Editoren, die den ganzen Bildschirm
+brauchen. Größen-Limits: 64 MiB ZIP, 256 MiB entpackt.
+
+### Entwickeln und ausliefern
+
+Die Referenz-Plugins unter `packages/plugins/` sind die Vorlagen —
+kopiere das nächstliegende. Jedes hat ein `build.mjs`, das
+`src/plugin.ts` mit esbuild bündelt und das installierbare ZIP nach
+`dist/` packt:
+
+```sh
+cd packages/plugins/<dein-plugin>
+pnpm build          # → dist/<id>-<version>.zip
+```
+
+Installiere das ZIP über Admin → Plugins (oder die Dropzone), öffne die
+gesandboxte Vorschau unter `/admin/plugins/<id>/preview`, iteriere. Das
+Install-Gate validiert Struktur, Manifest, Größe und CSS-Scoping und
+lehnt mit einem präzisen Fehlercode ab. Ein Update veröffentlichen =
+gleiche ID, höhere Version.
+
+Konventionen, die im Review durchgesetzt werden: UI-Strings über die
+`i18n/`-Dateien des Plugins in **beiden** Sprachen `de` und `en`; der
+Fallback muss in einem gedruckten Dokument Sinn ergeben.
+
+## Am Kern arbeiten
+
+### Der Stack auf einen Blick
+
+TypeScript-Monorepo (pnpm-Workspaces): `apps/api` (NestJS + Prisma,
+PostgreSQL), `apps/collab` (Hocuspocus/Yjs-Echtzeit-Server), `apps/web`
+(React + Vite + TipTap), `apps/backup` (Backup-Sidecar),
+`packages/shared` (Typen, Schemas, Editor-Schema, i18n-Kataloge),
+`packages/plugin-sdk`, `packages/plugins/*`.
+Architektur-Entscheidungen liegen in
+[`docs/architecture/adr/`](../../architecture/adr/) — lies das
+zutreffende ADR, bevor du ein Subsystem anfasst; `docs/architecture/`
+hat die Tiefenbohrungen (Berechtigungen, Datenmodell,
+Echtzeit-Zusammenarbeit, Sicherheit, Plugins; alles englisch).
+
+### Eine Entwicklungsumgebung bekommen
+
+```sh
+pnpm install
+cd deploy/compose && cp .env.example .env
+# Voll containerisierter Dev-Stack (Hot Reload; der erste Start installiert die Abhängigkeiten):
+docker compose -f docker-compose.yml -f compose.dev.yml up
+#   → web http://localhost:5173, api :3001, db :5434
+```
+
+Schnellstes Feedback: nur die Datenbank in Docker, web/api nativ — das
+genaue Rezept steht am Kopf von
+[`deploy/compose/compose.dev.yml`](../../../deploy/compose/compose.dev.yml).
+Fixture-Nutzer/-Teiche einspielen mit
+`pnpm --filter @dorfteich/api db:seed` (Fixture-Passwort: siehe
+`apps/api/prisma/seed.ts`).
+
+### Die Gates, die jede Änderung bestehen muss
+
+```sh
+pnpm lint        # ESLint + Prettier — keine Pipes, die Exit-Codes verschlucken
+pnpm typecheck
+pnpm test        # überall vitest; DB-gestützte Suiten brauchen TEST_DATABASE_URL
+pnpm i18n:check  # jeder UI-String in de UND en
+```
+
+DB-gestützte Tests laufen gegen die Compose-Dev-Datenbank:
+`TEST_DATABASE_URL=postgresql://dorfteich:dorfteich@localhost:5434/dorfteich pnpm test`.
+Playwright-e2e-Packs liegen in `apps/web/e2e/` und laufen gegen einen
+lokal geseedeten Stack (das genaue Rezept: `.gitea/workflows/ci.yml`).
+
+### Hausregeln, die du vor deinem ersten PR kennen solltest
+
+- **Berechtigungen**: Beantworte eine Zugriffsfrage nie außerhalb des
+  `PermissionService`/der Routen-Dekoratoren; verweigertes Lesen ist
+  404, verweigertes Schreiben auf Lesbarem ist 403
+  ([permissions.md](../../architecture/permissions.md)).
+- **i18n**: keine hart codierten UI-Strings; Keys nach
+  `packages/shared/i18n/{de,en}/…` (ADR 0012).
+- **Keine Anfragen an Dritte** aus dem Produkt, niemals — Schriften,
+  Editoren, alles wird selbst gehostet ausgeliefert (ADR 0016 setzt den
+  Präzedenzfall).
+- **Migrationen**: additiv und innerhalb eines Minor-Releases
+  umkehrbar; das QA-Gate der Release-Pipeline spielt ein Upgrade vom
+  vorherigen Release gegen echte Daten nach.
+- **Verträge dokumentieren**: Alles, was zwei Services teilen
+  (Status-Dateien, NOTIFY-Kanäle, Wire-Typen), lebt in
+  `packages/shared` mit einem Kommentar, wer liest und wer schreibt.
diff --git a/docs/de/features.md b/docs/de/features.md
new file mode 100644
index 0000000..1b722b9
--- /dev/null
+++ b/docs/de/features.md
@@ -0,0 +1,125 @@
+# Dorfteich — was es ist und warum du es haben willst
+
+_Englisches Original: [docs/features.md](../features.md)_
+
+Dorfteich ist ein Open-Source-Wiki für Menschen, die gemeinsam denken
+und schreiben wollen — in Echtzeit, auf dem eigenen Server, ohne ihr
+Wissen einem Cloud-Konzern zu überlassen.
+
+Der Name kommt vom Dorfteich: dem Ort, an dem das ganze Dorf
+zusammenkommt. Dein Wiki ist in **Teiche** gegliedert — ein persönlicher
+Teich für jedes Mitglied, dazu gemeinsame Teiche für Teams, Vereine,
+Familien oder Projekte.
+
+## Gemeinsam schreiben, live
+
+- **Echtzeit-Zusammenarbeit.** Öffne dieselbe Seite wie deine Kollegin
+  und seht euch gegenseitig tippen — mit benannten Cursorn und einer
+  Anwesenheitsleiste, die zeigt, wer auf der Seite ist. Kein Sperren,
+  keine „Jemand anderes bearbeitet gerade"-Dialoge, keine verlorenen
+  Änderungen.
+- **Funktioniert offline.** Tippe weiter, wenn die Verbindung abreißt;
+  deine Änderungen fließen automatisch wieder ein, sobald du online bist.
+- **Ein freundlicher Editor.** Überschriften, Listen, Aufgabenlisten,
+  Tabellen, Zitate, Code-Blöcke und Bilder — mit vollem
+  **Markdown**-Roundtrip: Was du schreibst, kann das System jederzeit
+  wieder als sauberes Markdown verlassen.
+- **Wikilinks.** Tippe `[[seiten-name]]`, um Seiten zu verlinken. Links
+  auf Seiten, die es noch nicht gibt, werden für dich gesammelt — ein
+  Klick legt sie an. „Verlinkt von" zeigt dir, wo jede Seite referenziert
+  wird.
+
+## Nie wieder etwas verlieren
+
+- **Versionsverlauf.** Jede Seite behält automatische Schnappschüsse und
+  zusätzlich benannte Versionen, die du selbst speicherst. Vergleiche,
+  sieh, wer beigetragen hat, und stelle jeden früheren Stand wieder her —
+  Wiederherstellungen erscheinen live in jedem offenen Editor.
+- **Papierkorb mit Schonfrist.** Gelöschte Seiten liegen in einem
+  Papierkorb pro Teich und lassen sich wochenlang wiederherstellen,
+  bevor sie endgültig entfernt werden.
+- **Echte Backups.** Nächtliche Datenbank- und Datei-Backups, optional
+  externe Kopien auf eine **Nextcloud** deiner Wahl und eine getestete
+  Ein-Klick-Wiederherstellung — inklusive dokumentiertem Weg, eine
+  Instanz aus dem Nichts wieder aufzubauen.
+
+## Organisieren, wie du denkst
+
+- **Labels**, auf Wunsch hierarchisch, um einen Teich beliebig zu
+  gliedern — und um Zugriffsregeln zu begrenzen (siehe unten).
+- **Schnelle Volltextsuche** über alles, was du lesen darfst —
+  unempfindlich gegen Akzente und Umlaute, mit Teilwort-Treffern.
+- **Inhaltsverzeichnis, Seitenindizes, Diagramme** und mehr über
+  mitgelieferte Plugins (siehe „Erweiterbar" unten).
+
+## Teile genau so viel, wie du willst
+
+- **Feingranulare Berechtigungen.** Vergib Lese- oder Schreibrechte pro
+  Teich, pro Label oder pro Seite — an einzelne Personen, an alle
+  angemeldeten Mitglieder oder ans öffentliche Internet. Deny-Regeln
+  schneiden Ausnahmen heraus. Ein eingebauter Inspektor („Effektive
+  Rechte") erklärt, _warum_ jemand eine Seite sehen kann oder nicht.
+- **Öffentliche Seiten.** Veröffentliche ausgewählte Seiten schreibgeschützt
+  für die Welt, mit sauberen URLs — der Rest des Teichs bleibt privat.
+- **Kommentare.** Diskutiere in Threads direkt neben dem Inhalt, erledige,
+  was geklärt ist, und entscheide pro Teich, ob alle Lesenden oder nur
+  Bearbeitende kommentieren dürfen.
+- **Benachrichtigungen unter deiner Kontrolle.** Beobachte Seiten oder
+  ganze Teiche, nutze den In-App-Posteingang und wähle E-Mail-Digests
+  (stündlich, täglich oder aus) — mit funktionierendem Abmeldelink.
+
+## Deine Dokumente kommen und gehen frei
+
+- **Import** von Word- (`.docx`), LibreOffice- (`.odt`) und
+  Markdown-Dateien — eingebettete Bilder inklusive.
+- **Export** jeder Seite als Markdown, Word, LibreOffice oder **PDF**
+  (mit der Typografie deines Teichs) und jedes Teichs als ZIP aus
+  Markdown-Dateien. Kein Lock-in, niemals.
+
+## Maschinen sind auch willkommen — zu deinen Bedingungen
+
+- **REST-API.** Eine saubere, token-authentifizierte öffentliche API zum
+  Lesen, Schreiben, Suchen, Labeln und Kommentieren — mit
+  OpenAPI-Beschreibung. Tokens tragen exakt die Berechtigungen ihrer
+  Besitzerin, nie mehr.
+- **Eingebauter MCP-Endpoint.** Verbinde Claude Code oder einen anderen
+  MCP-fähigen KI-Assistenten direkt mit deinem Wiki — er kann suchen,
+  lesen und (wenn du es erlaubst) Seiten schreiben. Beide Schnittstellen
+  sind **standardmäßig aus**, und jeder Teich stimmt separat zu.
+
+## Erweiterbar, aber sicher
+
+- **Plugins** ergänzen Block-Typen (Mermaid-Diagramme, vollwertiges
+  **draw.io**-Bearbeiten), Seiten-Werkzeuge (Inhaltsverzeichnis,
+  Seitenindex) und Abschnitts-Stile. Jedes Plugin läuft in einer strikten
+  Sandbox: keine Cookies, kein Storage, kein Netzwerk — es kann nie mehr
+  lesen als die Person, die es gerade ansieht.
+- Referenz-Plugins werden mitgeliefert und dienen zugleich als
+  dokumentierte Vorlagen für eigene Plugins.
+
+## Privat by design
+
+- **Selbst gehostet.** Ein `docker compose up`, ein freundlicher
+  Einrichtungsassistent beim ersten Start — und es gehört dir. Alles,
+  Schriften eingeschlossen, wird von deiner eigenen Domain ausgeliefert:
+  Seiten stellen **null Anfragen an Dritte**.
+- **DSGVO-freundlich.** Impressums- und Datenschutzseiten sind eingebaut
+  (mit Vorlagen), persönliche Daten als ZIP exportierbar, Konto-Löschung
+  mit inhaltserhaltender Pseudonymisierung und ein Audit-Log der
+  administrativen Aktionen.
+- **Zweisprachig.** Die gesamte Oberfläche spricht Deutsch und Englisch;
+  jede Person wählt ihre Sprache selbst.
+
+## Ehrlicher Betrieb
+
+- Health-Endpoints, die „down" von „degraded" unterscheiden, ein
+  Admin-System-Panel mit Job-Status, Backup-Zustand, Audit-Log und
+  Speicherübersicht, monatliche automatisierte Restore-Übungen — der
+  Betreiber kann _beweisen_, dass die Backups funktionieren, statt nur
+  zu hoffen.
+
+---
+
+_Dorfteich ist MIT-lizenzierte Open-Source-Software. Wer Docker
+betreiben kann, kann Dorfteich betreiben — siehe
+[Self-Hosting](../self-hosting/README.md) (englisch)._
diff --git a/docs/de/manual/README.md b/docs/de/manual/README.md
new file mode 100644
index 0000000..4c2b0e4
--- /dev/null
+++ b/docs/de/manual/README.md
@@ -0,0 +1,20 @@
+# Dorfteich-Handbücher
+
+_Englisches Original: [docs/manual/README.md](../../manual/README.md)_
+
+Nutzer-Dokumentation, nach Zielgruppe. (Das englische Original ist bei
+Abweichungen maßgeblich.)
+
+| Handbuch                                        | Für                                             |
+| ----------------------------------------------- | ----------------------------------------------- |
+| [Feature-Überblick](../features.md)             | alle, die wissen wollen, was Dorfteich ist      |
+| [Benutzerhandbuch](user-guide.md)               | Mitglieder im Alltag                            |
+| [Teich-Admin-Handbuch](pond-admin-guide.md)     | Personen, die einen Teich verwalten             |
+| [Site-Admin-Handbuch](site-admin-guide.md)      | Instanz-Administratorinnen und -Administratoren |
+| [API-Handbuch](api-guide.md)                    | Skripte und Integrationen                       |
+| [MCP-Handbuch](mcp-guide.md)                    | KI-Assistenten anbinden                         |
+| [Entwicklerhandbuch](../developer/extending.md) | Plugin-Autoren und Kern-Mitwirkende             |
+
+Eine Instanz betreiben (Installation, Update, Backup, Monitoring):
+[Self-Hosting](../../self-hosting/README.md) (englisch). Interna:
+[Architektur](../../architecture/README.md) (englisch).
diff --git a/docs/de/manual/api-guide.md b/docs/de/manual/api-guide.md
new file mode 100644
index 0000000..1c11bde
--- /dev/null
+++ b/docs/de/manual/api-guide.md
@@ -0,0 +1,142 @@
+# API-Handbuch
+
+_Englisches Original: [docs/manual/api-guide.md](../../manual/api-guide.md)_
+
+Wie du aus Skripten und Integrationen mit Dorfteich sprichst. Die
+öffentliche REST-API liegt unter `/api/public/v1`; ihre
+maschinenlesbare Beschreibung wird unter `/api/public/v1/openapi.json`
+ausgeliefert.
+
+## Einschalten
+
+Die API ist **standardmäßig aus**, und zwar doppelt:
+
+1. Ein **Site-Admin** aktiviert den Instanz-Schalter (Admin →
+   Einstellungen → Öffentliche API).
+2. Jeder **Teich**, der erreichbar sein soll, stimmt zu
+   (Teich-Einstellungen → „Diesen Teich über die öffentliche API
+   freigeben").
+
+Alles Nicht-Freigeschaltete antwortet mit `404` — ununterscheidbar von
+einer Instanz ohne dieses Feature.
+
+## Persönliche API-Tokens
+
+Tokens legst du unter **Einstellungen → API-Tokens** an: ein Name, ein
+Scope (`read` oder `read+write`), ein optionales Ablaufdatum und
+optional eine Beschränkung auf ausgewählte Teiche. Das Geheimnis
+(`dt_pat_…`) wird **ein einziges Mal** angezeigt — sofort kopieren.
+Tokens sind widerrufbar und zeigen ihre letzte Verwendung.
+
+Ein Token handelt **als du**: Es kann exakt lesen und schreiben, was du
+kannst, eingeengt durch seinen Scope und die Teich-Beschränkung — nie
+mehr. Die Token-Verwaltung selbst verlangt immer die Browser-Sitzung;
+ein geleaktes Token kann keine neuen Tokens erzeugen.
+
+Authentifiziere dich mit einem Bearer-Header:
+
+```sh
+curl -H "Authorization: Bearer dt_pat_..." \
+  https://wiki.example.com/api/public/v1/me
+```
+
+`GET /me` ist der Smoke-Test — er liefert dein Benutzerkonto, den
+Token-Scope und eine etwaige Teich-Beschränkung.
+
+## Lesen
+
+```sh
+# Die Teiche, die dieses Token erreicht
+curl -H "$AUTH" https://wiki.example.com/api/public/v1/ponds
+
+# Seiten eines Teichs: Slug, Titel, Labels, Zeitstempel
+curl -H "$AUTH" https://wiki.example.com/api/public/v1/ponds/team/pages
+
+# Eine Seite — Markdown-Quelle UND gerendertes, bereinigtes HTML
+curl -H "$AUTH" https://wiki.example.com/api/public/v1/ponds/team/pages/meeting-notes
+
+# Volltextsuche (optional ?pond=<slug>&label=<labelId>)
+curl -H "$AUTH" "https://wiki.example.com/api/public/v1/search?q=seerose"
+
+# Der ganze Teich als Markdown-ZIP
+curl -H "$AUTH" -o team.zip \
+  https://wiki.example.com/api/public/v1/ponds/team/export/markdown
+```
+
+Such-Snippets markieren Treffer mit `**…**`; Ergebnisse tragen Teich-
+und Seiten-Slugs für Folgeaufrufe.
+
+## Schreiben (braucht den `write`-Scope)
+
+```sh
+# Eine Seite aus Markdown anlegen
+curl -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"title": "Meeting notes", "markdown": "# Agenda\n\n- Enten\n"}' \
+  https://wiki.example.com/api/public/v1/ponds/team/pages
+
+# Umbenennen und/oder den Inhalt ERSETZEN
+curl -X PATCH -H "$AUTH" -H 'Content-Type: application/json' \
+  -d '{"markdown": "Neuer Inhalt."}' \
+  https://wiki.example.com/api/public/v1/ponds/team/pages/meeting-notes
+
+# Eine Seite in den Papierkorb verschieben
+curl -X DELETE -H "$AUTH" \
+  https://wiki.example.com/api/public/v1/ponds/team/pages/meeting-notes
+```
+
+Ein Inhalts-`PATCH` **ersetzt** die ganze Seite. Er wird durch das
+lebendige kollaborative Dokument angewandt: Wer die Seite in diesem
+Moment bearbeitet, sieht die Änderung erscheinen, nichts spaltet sich
+ab, und der vorherige Stand bleibt als wiederherstellbarer
+Schnappschuss im Versionsverlauf (das Update selbst erscheint als
+Version namens „API update").
+
+## Labels
+
+```sh
+GET    /ponds/{pond}/labels                       # der Label-Baum
+POST   /ponds/{pond}/labels                       # {name, color?, parentId?}
+PATCH  /ponds/{pond}/labels/{labelId}             # umbenennen/umfärben/verschieben in einem Aufruf
+DELETE /ponds/{pond}/labels/{labelId}
+PUT    /ponds/{pond}/pages/{page}/labels/{labelId}   # zuweisen
+DELETE /ponds/{pond}/pages/{page}/labels/{labelId}   # entfernen
+```
+
+Die Verwaltung des Label-Baums braucht Teich-Admin-Rechte (wie in der
+App).
+
+## Kommentare
+
+```sh
+GET    /ponds/{pond}/pages/{page}/comments?filter=all|open|resolved
+POST   /ponds/{pond}/pages/{page}/comments        # {body, parentId?} — Markdown
+POST   /ponds/{pond}/pages/{page}/comments/{id}/resolve
+DELETE /ponds/{pond}/pages/{page}/comments/{id}/resolve   # wieder öffnen
+```
+
+Die Kommentar-Richtlinie des Teichs gilt exakt wie in der App.
+
+## Fehler, Limits, Semantik
+
+- Fehler tragen den einheitlichen Body `{ "code": "...", "message":
+"...", "details": {...} }`. Der `code` ist stabil und maschinell
+  prüfbar.
+- **404 vs. 403**: Was du nicht _lesen_ darfst, antwortet 404 (die
+  Existenz bleibt verborgen — auch Teiche ohne API-Freigabe); ein
+  Schreibzugriff auf etwas, das du lesen, aber nicht ändern darfst,
+  antwortet 403. Ein Token ohne `write`-Scope bekommt auf jeder
+  Schreibroute `403 scope_required`.
+- **Rate-Limit** pro Token; `429`-Antworten tragen einen
+  `Retry-After`-Header.
+- Nirgendwo sind Cookies im Spiel — es gibt keine CSRF-Angriffsfläche,
+  und Browser-Sitzungen können die öffentliche API nicht aufrufen.
+
+## (Noch) außerhalb des Umfangs
+
+Anhang-Upload, Versions-Endpoints und Webhooks sind bewusst nicht Teil
+von v1.
+
+_Die Betreiber-Sicht auf dasselbe Feature (Schalter,
+Sicherheitshinweise):
+[`docs/self-hosting/public-api.md`](../../self-hosting/public-api.md)
+(englisch)._
diff --git a/docs/de/manual/mcp-guide.md b/docs/de/manual/mcp-guide.md
new file mode 100644
index 0000000..7de5a72
--- /dev/null
+++ b/docs/de/manual/mcp-guide.md
@@ -0,0 +1,105 @@
+# MCP-Handbuch — deine KI mit Dorfteich verbinden
+
+_Englisches Original: [docs/manual/mcp-guide.md](../../manual/mcp-guide.md)_
+
+Dorfteich bringt seinen eigenen [MCP](https://modelcontextprotocol.io)-
+Endpoint unter `/api/mcp` mit (Streamable HTTP). Jeder MCP-fähige
+Assistent — Claude Code, Claude Desktop über eine Bridge und andere —
+kann dein Wiki durchsuchen, lesen und (wenn du es erlaubst) beschreiben,
+mit **exakt deinen Berechtigungen**. Es läuft kein zusätzlicher Server:
+Der Endpoint ist Teil der Instanz.
+
+## Einschalten
+
+Wie die REST-API ist MCP **standardmäßig aus** und hat **eigene,
+unabhängige Schalter**:
+
+1. **Site-Admin**: Admin → Einstellungen → Öffentliche API →
+   „Eingebauten MCP-Endpoint aktivieren".
+2. **Jeder Teich**, den der Assistent sehen soll: Teich-Einstellungen →
+   „Diesen Teich für KI-Assistenten freigeben (MCP)".
+
+Ein Teich ohne Freigabe ist für MCP-Clients unsichtbar — selbst für
+dein eigenes Token.
+
+## Ein Token besorgen
+
+MCP nutzt dieselben **persönlichen API-Tokens** wie die REST-API: Lege
+eins unter **Einstellungen → API-Tokens** an. Wähle den Scope bewusst:
+
+- `read` — der Assistent kann auflisten, lesen und suchen, sonst nichts.
+- `read+write` — er darf zusätzlich Seiten anlegen/ändern, kommentieren
+  und Labels setzen.
+
+Erwäge, das Token auf genau die Teiche zu beschränken, in denen der
+Assistent arbeiten soll.
+
+## Claude Code verbinden
+
+```sh
+claude mcp add --transport http dorfteich https://wiki.example.com/api/mcp \
+  --header "Authorization: Bearer dt_pat_..."
+```
+
+Das war's — Claude Code listet die Tools beim nächsten Start. Reine
+Stdio-Clients überbrücken mit `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "dorfteich": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://wiki.example.com/api/mcp",
+        "--header",
+        "Authorization: Bearer dt_pat_..."
+      ]
+    }
+  }
+}
+```
+
+## Was der Assistent kann
+
+| Tool                                         | Tut                                           |
+| -------------------------------------------- | --------------------------------------------- |
+| `list_ponds`                                 | die Teiche, die dieses Token erreicht         |
+| `list_pages(pond)`                           | Seiten mit Slug, Titel, Labels, Zeitstempeln  |
+| `read_page(pond, page)`                      | eine Seite als Markdown plus Metadaten        |
+| `search(query, pond?, label?)`               | Volltextsuche mit Snippets                    |
+| `create_page(pond, title, markdown)`         | neue Seite aus Markdown _(write)_             |
+| `update_page(pond, page, markdown?, title?)` | umbenennen und/oder Inhalt ersetzen _(write)_ |
+| `add_comment(pond, page, text)`              | eine Seite kommentieren _(write)_             |
+| `list_labels(pond)`                          | der Label-Baum des Teichs                     |
+| `set_page_labels(pond, page, labelIds)`      | die Labels einer Seite ersetzen _(write)_     |
+| `export_pond(pond)`                          | ein Download-Link für den Markdown-ZIP-Export |
+
+Inhalts-Updates nehmen denselben kollaborativen Weg wie menschliche
+Bearbeitungen: Offene Editoren konvergieren live, und der vorherige
+Stand bleibt im Versionsverlauf — eine KI-Änderung lässt sich immer wie
+jede andere Änderung prüfen und zurücknehmen.
+
+## Gut zu wissen
+
+- **Die Berechtigungen sind deine.** Der Assistent sieht genau die
+  Seiten, die dein Konto lesen darf; Label-Regeln,
+  öffentlich/privat — alles gilt unverändert.
+- **Jeder Schreibzugriff wird audit-geloggt**, dem Token zugeordnet —
+  im Audit-Log des Site-Admins steht, was der Assistent geändert hat.
+- **Rate-limitiert** pro Token; ein außer Kontrolle geratener Agent
+  bekommt `429`, keine geschmolzene Instanz.
+- **Zustandslos**: Jede Anfrage steht für sich; das Widerrufen des
+  Tokens unter Einstellungen → API-Tokens schneidet den Assistenten
+  sofort ab.
+- Der Endpoint spricht MCP über Streamable HTTP (POST). GET/SSE-
+  Session-Resumption wird nicht angeboten — Clients fallen auf reines
+  Request/Response zurück, was jeder aktuelle Client unterstützt.
+
+## Eine sinnvolle erste Sitzung
+
+Bitte deinen Assistenten um `list_ponds`, dann `search` nach etwas, von
+dem du weißt, dass es da ist, `read_page` darauf — und mit einem
+Write-Token: eine neue Seite entwerfen. Sieh dir danach den
+Versionsverlauf der Seite an: Du findest die Änderung des Assistenten
+als normale, wiederherstellbare Version.
diff --git a/docs/de/manual/pond-admin-guide.md b/docs/de/manual/pond-admin-guide.md
new file mode 100644
index 0000000..e63a732
--- /dev/null
+++ b/docs/de/manual/pond-admin-guide.md
@@ -0,0 +1,120 @@
+# Teich-Admin-Handbuch
+
+_Englisches Original: [docs/manual/pond-admin-guide.md](../../manual/pond-admin-guide.md)_
+
+Was du an einem Teich konfigurieren kannst, den du verwaltest.
+Teich-Admin bist du auf deinem persönlichen Teich und auf jedem Teich,
+auf dem du die Rolle `pond_admin` hast. All das liegt hinter dem
+**Zahnrad-Symbol** in der Kopfleiste (sichtbar auf Teich-Routen, wenn
+du den Teich verändern darfst).
+
+## Teiche in einer Minute
+
+Jedes Mitglied bekommt automatisch einen **persönlichen Teich**.
+Zusätzliche **gemeinsame Teiche** legst du über **„+ Neuer Teich"** am
+unteren Ende des Teich-Umschalters in der Kopfleiste an (oder über die
+API, `POST /api/v1/ponds`); sie unterliegen dem Pro-Person-Kontingent
+des Site-Admins („Zusätzliche geteilte Teiche pro Person", Standard 0).
+Wer den Teich anlegt, wird sein Teich-Admin.
+
+## Name, Beschreibung, Darstellung
+
+- **Name und Beschreibung** des Teichs.
+- **Schriften**: Wähle pro Teich Schriften für Überschriften, Fließtext
+  und Code aus dem eingebauten, selbst gehosteten Katalog (stöbern unter
+  `/fonts`) — sie gelten für die App-Ansicht, öffentliche Seiten und
+  PDF-Exporte.
+- **Seitenleisten-Sortierung** für alle: A–Z, Erstellungsdatum oder
+  manuelle Reihenfolge.
+
+## Mitglieder und Rollen
+
+Der Abschnitt **Mitglieder** verwaltet, wer im Teich ist:
+
+| Rolle        | Darf                                                       |
+| ------------ | ---------------------------------------------------------- |
+| `reader`     | Seiten lesen (soweit die Regeln es erlauben)               |
+| `editor`     | Seiten lesen + schreiben, Dateien hochladen                |
+| `pond_admin` | alles, einschließlich Einstellungen, Mitglieder und Labels |
+
+Die Mitgliederzahl begrenzen die Instanz-Kontingente (Bearbeiter/Leser
+pro Teich). Auch persönliche Teiche nehmen Mitglieder auf — genau so
+teilst du deinen.
+
+## Zugriffsregeln (das Kleingedruckte)
+
+Über die reine Mitgliedschaft hinaus bearbeitet der Abschnitt
+**Zugriffsregeln** die Berechtigungen direkt. Eine Regel besteht aus:
+_Subjekt_ (eine Person, alle Angemeldeten oder die Öffentlichkeit) +
+_Recht_ (Leser/Bearbeiter/Teich-Admin) + _Geltungsbereich_ (ganzer
+Teich, ein Label oder eine Seite) + _Wirkung_ (erlauben oder verbieten).
+
+- **Label-Regeln** sind das Power-Tool: Gib den vertraulichen Seiten das
+  Label „Vorstand" und erlaube nur den Vorstandsmitgliedern dieses
+  Label — oder verbiete ein Label jemandem, der sonst alles lesen darf.
+- **Öffentliche Seiten:** Eine _Erlauben, Leser, öffentlich_-Regel auf
+  einer Seite (oder einem Label) veröffentlicht sie schreibgeschützt
+  unter `/public/<teich>/<seite>`.
+- Verbieten schlägt Erlauben; verweigertes Lesen sieht aus wie „nicht
+  gefunden" (das System verrät nie, was existiert).
+- Der Inspektor **„Effektive Rechte"** auf einer Seite erklärt das
+  wirksame Ergebnis für jede Person — nutze ihn immer, wenn dich eine
+  Regel-Kombination überrascht.
+
+## Labels
+
+Verwalte den Label-Baum des Teichs (anlegen, umbenennen, umfärben,
+verschachteln, verschieben, löschen). Das Löschen eines Labels, das
+noch auf Seiten liegt, fragt nach. Labels erscheinen auch im
+Label-Wähler der Seiten; dort ist das Anlegen neuer Labels dir
+vorbehalten.
+
+## Kommentar-Richtlinie
+
+Wähle, ob **alle mit Lesezugriff** kommentieren dürfen oder **nur
+Bearbeitende**. Bestehende Kommentare bleiben so oder so lesbar.
+
+## Den Teich beobachten
+
+Die Glocke im Kopf der Teich-Einstellungen beobachtet den ganzen Teich
+— du wirst über jede Seitenänderung und jeden Kommentar darin
+benachrichtigt.
+
+## Plugins
+
+Plugins, die der Site-Admin mit Modus _Optional_ installiert hat,
+erscheinen hier mit einem Schalter pro Teich. _Erforderliche_ Plugins
+sind immer aktiv; _deaktivierte_ tauchen gar nicht auf. (Welche Plugins
+es gibt und was sie tun:
+[Site-Admin-Handbuch](site-admin-guide.md#plugins).)
+
+## Maschinenzugriff: API- und MCP-Freigabe
+
+Zwei getrennte Schalter geben diesen Teich für Token-Zugriff frei —
+**beide standardmäßig aus**, und beide nur wirksam, wenn der Site-Admin
+den passenden Instanz-Schalter aktiviert hat:
+
+- **Öffentliche REST-API** (`apiEnabled`): Skripte und Integrationen
+  erreichen den Teich mit persönlichen API-Tokens — mit exakt den
+  Berechtigungen der Token-Besitzerin.
+- **MCP / KI-Assistenten** (`mcpEnabled`): MCP-Clients wie Claude Code
+  erreichen den Teich auf demselben Weg.
+
+Ein Teich ohne Freigabe ist über diese Schnittstellen unsichtbar —
+selbst für die Tokens der eigenen Mitglieder.
+
+## Dateien
+
+Die **Dateiverwaltung** listet die Uploads des Teichs mit ihrer
+Verwendung (welche Seite sie referenziert) und lässt dich verwaiste
+Dateien löschen. Der Speicher zählt gegen das Kontingent des Teichs;
+die aktuelle Nutzung wird angezeigt.
+
+## Export und Löschung
+
+- **Export**: der ganze Teich als ZIP aus Markdown-Dateien plus Medien.
+- **Teich löschen**: Die Gefahren-Sektion am Ende der
+  Teich-Einstellungen verschiebt einen gemeinsamen Teich in den
+  Instanz-Papierkorb (zur Bestätigung den Teichnamen eintippen); ein
+  Site-Admin kann ihn wiederherstellen. Dein persönlicher Teich lässt
+  sich nicht löschen — er ist das Zuhause deines Kontos.
diff --git a/docs/de/manual/site-admin-guide.md b/docs/de/manual/site-admin-guide.md
new file mode 100644
index 0000000..0b7b013
--- /dev/null
+++ b/docs/de/manual/site-admin-guide.md
@@ -0,0 +1,149 @@
+# Site-Admin-Handbuch
+
+_Englisches Original: [docs/manual/site-admin-guide.md](../../manual/site-admin-guide.md)_
+
+Wie du eine Dorfteich-Instanz aus dem Browser verwaltest. Installation,
+Updates und Betrieb auf Host-Ebene behandelt das
+[Self-Hosting-Handbuch](../../self-hosting/README.md) (englisch); hier
+geht es um die beiden Admin-Seiten: **Admin → Einstellungen** (`/admin`)
+und **Admin → System** (`/admin/system`).
+
+Ein Site-Admin sieht und darf alles — nutze für die tägliche Arbeit ein
+normales Konto.
+
+## Erster Kontakt: der Einrichtungsassistent
+
+Eine frische Instanz begrüßt dich mit einem Assistenten in sechs
+Schritten: Sprache → das Site-Admin-Konto → Instanzname und
+Standardsprache → SMTP-Relay (mit Live-Testmail; überspringbar) →
+Registrierungsmodus → fertig. Bis er abgeschlossen ist, antwortet die
+Instanz auf alles mit `503 setup_required`. Unbeaufsichtigte
+Installationen befüllen den Assistenten vorab über
+`SETUP_ADMIN_*`-Umgebungsvariablen.
+
+## Admin → Einstellungen
+
+### Instanz
+
+- **Name** (erscheint in der Kopfleiste und in Mails) und
+  **Standardsprache** (gilt für anonyme Besucher und server-gerenderte
+  Seiten).
+- **Registrierungsmodus**: `open` (jeder darf sich registrieren, mit
+  E-Mail-Bestätigung) oder `closed` (nur bestehende Konten melden sich
+  an).
+
+### Kontingente
+
+Instanzweite Standardwerte: Bearbeiter/Leser pro Teich, zusätzliche
+geteilte Teiche pro Person (Standard 0 — erhöhe ihn oder vergib
+Pro-Person-Overrides, damit Leute gemeinsame Teiche anlegen können),
+Speicher pro Teich, maximale Dateigröße. Der **Kontingent-Manager**
+darunter setzt Overrides pro Person/Teich, die die Standardwerte
+überstimmen.
+
+### Uploads
+
+Die Allow-Liste der Nicht-Bild-Dateiendungen, die Nutzer anhängen
+dürfen, und die SVG-Richtlinie (`sanitize` entfernt Skripte aus
+hochgeladenen SVGs, `reject` lehnt sie ab).
+
+### Öffentliche API und MCP
+
+Zwei unabhängige Hauptschalter, beide **standardmäßig aus**:
+
+- **Öffentliche REST-API**: erlaubt Nutzern, persönliche API-Tokens
+  anzulegen und `/api/public/v1` zu verwenden (siehe das
+  [API-Handbuch](api-guide.md)).
+- **Eingebauter MCP-Endpoint**: stellt `/api/mcp` für KI-Assistenten
+  bereit ([MCP-Handbuch](mcp-guide.md)).
+
+Keiner der Schalter wirkt allein pro Teich — jeder Teich stimmt
+zusätzlich über seine Teich-Einstellungen zu. Aus heißt: Die Endpoints
+antworten mit 404.
+
+### Rechtsseiten
+
+Impressum und Datenschutzerklärung als Markdown, veröffentlicht unter
+`/legal/imprint` und `/legal/privacy` und aus jeder Fußzeile verlinkt.
+Eine Vorlage mit Prüf-Checkliste liegt in
+[`docs/self-hosting/legal-template.md`](../../self-hosting/legal-template.md).
+Bis sie konfiguriert sind, zeigen die Seiten einen Hinweis (und dir ein
+Warnbanner).
+
+### Backups
+
+Siehe **Admin → System → Backups** unten.
+
+### Plugins
+
+Installiere Plugins per ZIP-Upload (alternativ: das ZIP in den
+`_dropzone/`-Ordner auf dem Plugins-Volume legen — ein Watcher
+installiert es binnen Sekunden und verschiebt abgelehnte Pakete mit
+Begründung nach `_quarantine/`).
+
+Jedes installierte Plugin hat einen **Instanz-Modus**:
+
+| Modus      | Bedeutung                                            |
+| ---------- | ---------------------------------------------------- |
+| `disabled` | überall inaktiv (der Standard nach dem Installieren) |
+| `optional` | Teich-Admins entscheiden pro Teich                   |
+| `required` | in jedem Teich aktiv, kein Opt-out                   |
+
+Jedes Plugin hat eine gesandboxte **Vorschau**-Seite zum Ausprobieren
+vor dem Aktivieren. Deinstallieren ist blockiert, solange ein Plugin
+`required` ist; Dokumente behalten ihre Plugin-Blöcke in jedem Fall und
+zeigen den Fallback-Text des Plugins, wenn es fehlt.
+
+Mitgelieferte Referenz-Plugins: `toc` (Inhaltsverzeichnis),
+`page-index` (label-gefilterte Seitenliste), `mermaid`
+(Diagramm-Blöcke), `drawio` (vollwertiges draw.io-Bearbeiten),
+`section-styles-basic` (farbige Hinweiskästen).
+
+### Personen
+
+Die Personenverwaltung: Konten suchen, deaktivieren/aktivieren,
+Bestätigungsmails erneut senden, Site-Admins ernennen/absetzen und
+Konten löschen. Die Löschung bietet **Pseudonymisierung** an: Das Konto
+und seine persönlichen Daten verschwinden, aber geteilte Inhalte
+überleben, einem neutralen Platzhalter zugeschrieben. Schutzmechanismen
+verhindern, dich selbst zu deaktivieren oder den letzten Site-Admin zu
+entfernen.
+
+## Admin → System
+
+Der Blick des Betreibers auf einen Schirm:
+
+- **Wartungsjobs**: jeder Wartungsjob (Papierkorb-Bereinigung,
+  Versions-Ausdünnung, Seiten-Kompaktierung, Datenexport-Bereinigung,
+  Benachrichtigungs-Digests) mit Takt, letztem Lauf, Dauer und Ergebnis
+  — plus manuellem **Ausführen**-Knopf (selbst audit-geloggt).
+- **Backups**: Die Status-Karte spiegelt den letzten Lauf des Sidecars
+  und sein Frische-Urteil, mit einem **Jetzt sichern**-Knopf. Darunter:
+  - **Backup-Einstellungen**: lokale Aufbewahrung (überstimmt den
+    Container-Standard) und das **Nextcloud-Ziel** — Server-Adresse,
+    Benutzername, App-Passwort (liegt im dateibasierten Secret-Store auf
+    dem Secrets-Volume, nie in der Datenbank), Ordner, Upload-Zeitplan
+    (nach jedem Backup / wöchentlich / manuell), entfernte Aufbewahrung
+    und ein **Verbindung testen**-Knopf, der die Zugangsdaten prüft und
+    den Ordner anlegt.
+  - **Wiederherstellung**: listet lokale und Nextcloud-Sets; beim
+    Wiederherstellen tippst du die Backup-ID zur Bestätigung ein, dann
+    geht die Instanz in den Wartungsmodus, stellt sich wieder her und
+    startet neu. Alles Weitere zu Backups (Spiegel auf einen privaten
+    Host, Disaster Recovery) steht im
+    [Self-Hosting-Handbuch](../../self-hosting/README.md#backups--restore)
+    und im [Restore-Runbook](../../operations/restore-runbook.md)
+    (beide englisch).
+- **Audit-Log**: administrative und Auth-Ereignisse (Zugriffsregeln,
+  Mitglieder, Personenverwaltung, Kontingente, Plugins, Einstellungen,
+  Einrichtung, Tokens, API-Schreibzugriffe, Backup-Aktionen) mit
+  Filtern nach Akteur/Aktion/Zeit, 50 pro Seite.
+- **Speicher**: die zwanzig größten Teiche und die Instanz-Summe.
+
+## Health, Monitoring, Go-Live
+
+- `GET /api/v1/readyz` ist die Eigendiagnose der Instanz; überwache sie
+  (Down-vs.-Degraded-Semantik und ein fertiges Monitor-Set:
+  [`deploy/monitoring.md`](../../../deploy/monitoring.md)).
+- Go-Live-Checkliste für eine frische Produktionsinstanz:
+  [`deploy/go-live.md`](../../../deploy/go-live.md).
diff --git a/docs/de/manual/user-guide.md b/docs/de/manual/user-guide.md
new file mode 100644
index 0000000..0e07222
--- /dev/null
+++ b/docs/de/manual/user-guide.md
@@ -0,0 +1,136 @@
+# Benutzerhandbuch
+
+_Englisches Original: [docs/manual/user-guide.md](../../manual/user-guide.md)_
+
+Wie du dich als normales Mitglied im Dorfteich zurechtfindest. Für die
+Teich-Konfiguration siehe das
+[Teich-Admin-Handbuch](pond-admin-guide.md), für die Verwaltung der
+Instanz das [Site-Admin-Handbuch](site-admin-guide.md).
+
+## Registrieren und anmelden
+
+- **Registrieren** (sofern die Instanz die offene Registrierung
+  erlaubt): Benutzername, E-Mail, Anzeigename, Passwort, Sprache. Du
+  bestätigst deine E-Mail über den Link in der Bestätigungsmail; dabei
+  entsteht auch dein **persönlicher Teich** — dein eigener Raum, den nur
+  du siehst, bis du ihn teilst.
+- **Anmelden** mit Benutzername _oder_ E-Mail. Passwort vergessen? Die
+  Anmeldeseite hat einen Link zum Zurücksetzen (setzt voraus, dass die
+  Instanz Mail-Versand konfiguriert hat).
+- Deine Sitzungen findest du unter **Einstellungen → Aktive Sitzungen**;
+  dort kannst du jedes Gerät abmelden.
+
+## Teiche und Seiten
+
+- Der **Teich-Umschalter** in der Kopfleiste bringt dich zwischen den
+  Teichen hin und her, die du sehen kannst — und **„+ Neuer Teich"** an
+  seinem unteren Ende legt einen neuen gemeinsamen Teich an (begrenzt
+  durch ein Kontingent, das der Site-Admin setzt). Die **Seitenleiste**
+  listet die Seiten des aktuellen Teichs — sortiere sie A–Z, nach
+  Erstellungsdatum oder ziehe sie in eine manuelle Reihenfolge (der
+  Sortiermodus ist eine Teich-Einstellung).
+- **+ Neue Seite** am unteren Ende der Seitenleiste legt eine Seite an.
+  Seiten-Adressen sind lesbar: `/p/<teich>/<seite>`.
+- Der **Papierkorb**-Link sitzt ganz unten in der Seitenleiste:
+  Gelöschte Seiten lassen sich dort wiederherstellen, bis die
+  Aufbewahrungsfrist endet.
+
+## Der Editor
+
+Klicke auf das **Stift-Symbol** in der Kopfleiste, um eine Seite
+zwischen Lesen und Bearbeiten umzuschalten. Im Bearbeitungsmodus bietet
+eine Werkzeugleiste Absatz-Stile (Überschrift 1–4),
+fett/kursiv/durchgestrichen/Inline-Code, Aufzählungs-, nummerierte und
+Aufgabenlisten, Zitate, Code-Blöcke, Trennlinien, Bilder und Tabellen.
+Die Werkzeugleiste bleibt beim Scrollen sichtbar.
+
+- **Alle bearbeiten gemeinsam.** Andere Personen auf der Seite
+  erscheinen in der Anwesenheitsleiste in der Kopfleiste und als
+  benannte Cursor im Text. Es gibt keinen Speichern-Knopf für den Inhalt
+  — jeder Tastendruck wird gespeichert und live repliziert.
+- **Offline?** Das Status-Symbol in der Fußzeile (unten links) zeigt
+  deine Verbindung. Du kannst offline weitertippen; die Änderungen
+  synchronisieren sich beim Wiederverbinden.
+- **Markdown rein, Markdown raus.** Du kannst Markdown einfügen oder
+  tippen; die Seite lässt sich jederzeit wieder als Markdown kopieren
+  oder herunterladen (**…**-Menü → Als Markdown kopieren/herunterladen).
+- **Wikilinks:** Tippe `[[seiten-slug]]` oder
+  `[[seiten-slug|angezeigter Text]]`. Links auf Seiten, die es noch
+  nicht gibt, listet die Teich-Startseite unter „Fehlende Seiten" — ein
+  Klick legt das Ziel an. Das Panel **„Verlinkt von"** einer Seite zeigt
+  jede Seite, die auf sie verweist.
+- **Bilder und Anhänge:** Füge Bilder direkt per Einfügen oder Ziehen in
+  den Text ein. Andere Dateitypen (PDFs usw., soweit die Instanz sie
+  erlaubt) hängst du über das **Büroklammer-Symbol** an die Seite.
+- **Benannte Versionen:** Das **Speichern-Symbol** im Bearbeitungsmodus
+  legt einen benannten Schnappschuss an („vor dem großen Umbau"). Das
+  **Verlauf-Symbol** listet alle Versionen — automatische und benannte —
+  mit ihren Mitwirkenden; du kannst jede Version ansehen und
+  wiederherstellen. Wiederherstellen löscht nie den Verlauf.
+
+## Die Seiten-Aktionen in der Kopfleiste
+
+Bei geöffneter Seite findest du neben dem Stift: **Beobachten** (Glocke
+für diese Seite), **Kommentare** (mit Zähler für Ungelesenes),
+**Anhänge**, **Seiten-Werkzeuge** (Inhaltsverzeichnis, Seitenindex —
+sofern aktiviert), **Labels**, **Verlauf** und das **…**-Menü (Markdown
+kopieren/herunterladen, Export nach Word/LibreOffice/PDF, Löschen).
+
+## Labels
+
+Öffne das **Label-Symbol**, um die Seite zu verschlagworten. Du kannst
+bestehende Labels wählen oder direkt ein neues anlegen (das Anlegen ist
+Teich-Admins vorbehalten). Labels ordnen Seiten und können
+Zugriffsregeln tragen — eine Seite erbt jede Regel ihrer Labels.
+
+## Suche
+
+Das Suchfeld in der Kopfleiste durchsucht jede Seite, die du lesen
+darfst, über alle Teiche hinweg — tolerant gegenüber Akzenten („Baume"
+findet „Bäume") und Teilwörtern. Letzte Suchen werden gemerkt (und
+lassen sich löschen).
+
+## Kommentare
+
+Das **Sprechblasen-Symbol** öffnet das Kommentar-Panel: Threads mit
+einer Antwort-Ebene, Markdown möglich, Bearbeiten und Löschen für
+eigene Kommentare, **Erledigen** klappt abgeschlossene Diskussionen
+weg. Ob alle Lesenden oder nur Bearbeitende kommentieren dürfen, ist
+eine Teich-Einstellung.
+
+## Beobachten, Benachrichtigungen, Digests
+
+- **Beobachte** eine Seite (Glocke in den Seiten-Aktionen) oder einen
+  ganzen Teich (Glocke im Kopf der Teich-Einstellungen), um über
+  Änderungen und Kommentare benachrichtigt zu werden. Standardmäßig
+  beobachtest du automatisch Seiten, die du anlegst oder kommentierst —
+  beide Schalter liegen unter **Einstellungen → Profil**.
+- Die **Glocke in der Kopfleiste** ist dein
+  Benachrichtigungs-Posteingang; Einträge verlinken direkt auf die
+  Änderung (Kommentar-Benachrichtigungen öffnen das Panel).
+- **E-Mail-Digests** bündeln ungelesene Benachrichtigungen stündlich
+  oder täglich — einstellbar unter Einstellungen, abbestellbar direkt
+  aus jeder Digest-Mail.
+
+## Import und Export
+
+- **Dokument importieren** (Link in der Seitenleiste): `.docx`, `.odt`
+  oder `.md` wird zu einer neuen Seite, eingebettete Bilder inklusive.
+- **Seite exportieren**: „…"-Menü → Markdown / Word / LibreOffice /
+  PDF. **Teich exportieren**: Teich-Einstellungen → ZIP aller Seiten,
+  die du lesen darfst, als Markdown plus Medien.
+
+## Deine Einstellungen (oben rechts → Einstellungen)
+
+Profil (Anzeigename, E-Mail, Sprache, Beobachten-Voreinstellungen,
+Digest-Frequenz), Passwort, aktive Sitzungen, deine beobachteten Seiten
+und Teiche, **API-Tokens** (für Skripte und KI-Assistenten — siehe das
+[API-Handbuch](api-guide.md) und das [MCP-Handbuch](mcp-guide.md)) und
+**Meine Daten exportieren**: ein ZIP mit deinen Profildaten und dem
+vollständigen Inhalt deiner eigenen Teiche.
+
+## Öffentliche Seiten
+
+Hat ein Teich-Admin eine Seite öffentlich geschaltet, ist sie ohne Konto
+unter `/public/<teich>/<seite>` lesbar — mit der Typografie des Teichs
+und einem Link auf die Rechtsseiten der Instanz.
diff --git a/docs/developer/extending.md b/docs/developer/extending.md
index 2592df9..5e8b615 100644
--- a/docs/developer/extending.md
+++ b/docs/developer/extending.md
@@ -1,5 +1,7 @@
 # Developer guide — extending Dorfteich
 
+_Deutsche Fassung: [docs/de/developer/extending.md](../de/developer/extending.md)_
+
 Two ways to make Dorfteich do more: write a **plugin** (no fork, no
 redeploy, safe by construction) or contribute to the **core**. Start
 with a plugin unless you need to change how the product itself works.
diff --git a/docs/features.md b/docs/features.md
index 587cc66..4a9444f 100644
--- a/docs/features.md
+++ b/docs/features.md
@@ -1,5 +1,7 @@
 # Dorfteich — what it is and why you might want it
 
+_Deutsche Fassung: [docs/de/features.md](de/features.md)_
+
 Dorfteich is an open-source wiki for people who want to think and write
 together — in real time, on their own server, without handing their
 knowledge to a cloud company.
diff --git a/docs/manual/README.md b/docs/manual/README.md
index 4ec78b8..99af3e5 100644
--- a/docs/manual/README.md
+++ b/docs/manual/README.md
@@ -1,7 +1,8 @@
 # Dorfteich manuals
 
-User-facing documentation, by audience. (German translations are
-planned; English is authoritative for now.)
+User-facing documentation, by audience. German translations live in
+[`docs/de/`](../de/manual/README.md); English is authoritative when the
+two diverge.
 
 | Guide                                        | For                                  |
 | -------------------------------------------- | ------------------------------------ |
diff --git a/docs/manual/api-guide.md b/docs/manual/api-guide.md
index 33a3b2c..acbe31e 100644
--- a/docs/manual/api-guide.md
+++ b/docs/manual/api-guide.md
@@ -1,5 +1,7 @@
 # API guide
 
+_Deutsche Fassung: [docs/de/manual/api-guide.md](../de/manual/api-guide.md)_
+
 How to talk to Dorfteich from scripts and integrations. The public REST
 API lives at `/api/public/v1`; its machine-readable description is
 served at `/api/public/v1/openapi.json`.
diff --git a/docs/manual/mcp-guide.md b/docs/manual/mcp-guide.md
index d768629..2a85718 100644
--- a/docs/manual/mcp-guide.md
+++ b/docs/manual/mcp-guide.md
@@ -1,5 +1,7 @@
 # MCP guide — connecting your AI to Dorfteich
 
+_Deutsche Fassung: [docs/de/manual/mcp-guide.md](../de/manual/mcp-guide.md)_
+
 Dorfteich ships its own [MCP](https://modelcontextprotocol.io) endpoint
 at `/api/mcp` (Streamable HTTP). Any MCP-capable assistant — Claude
 Code, Claude Desktop via a bridge, and others — can search, read, and
diff --git a/docs/manual/pond-admin-guide.md b/docs/manual/pond-admin-guide.md
index bc40772..5346702 100644
--- a/docs/manual/pond-admin-guide.md
+++ b/docs/manual/pond-admin-guide.md
@@ -1,5 +1,7 @@
 # Pond-admin guide
 
+_Deutsche Fassung: [docs/de/manual/pond-admin-guide.md](../de/manual/pond-admin-guide.md)_
+
 What you can configure on a pond you administer. You are a pond admin on
 your own personal pond and on every pond where you hold the
 `pond_admin` role. All of this lives behind the **gear icon** in the top
diff --git a/docs/manual/site-admin-guide.md b/docs/manual/site-admin-guide.md
index d6d777e..5837dcd 100644
--- a/docs/manual/site-admin-guide.md
+++ b/docs/manual/site-admin-guide.md
@@ -1,5 +1,7 @@
 # Site-admin guide
 
+_Deutsche Fassung: [docs/de/manual/site-admin-guide.md](../de/manual/site-admin-guide.md)_
+
 How to administer a Dorfteich instance from the browser. Installation,
 updates, and host-level operations are covered by the
 [self-hosting guide](../self-hosting/README.md); this guide is about the
diff --git a/docs/manual/user-guide.md b/docs/manual/user-guide.md
index cec088b..9d6ede8 100644
--- a/docs/manual/user-guide.md
+++ b/docs/manual/user-guide.md
@@ -1,5 +1,7 @@
 # User guide
 
+_Deutsche Fassung: [docs/de/manual/user-guide.md](../de/manual/user-guide.md)_
+
 How to find your way around Dorfteich as a regular member. For pond
 configuration see the [pond-admin guide](pond-admin-guide.md); for
 instance administration the [site-admin guide](site-admin-guide.md).