diff --git a/docs/plugin-caller-template.md b/docs/plugin-caller-template.md
index 9b4c52a..c5fbd9c 100644
--- a/docs/plugin-caller-template.md
+++ b/docs/plugin-caller-template.md
@@ -29,7 +29,7 @@ Damit der Reusable Workflow durchläuft, müssen im Plugin-Repo vorhanden sein:
 2. **Versions-Konstante** in einer PHP-Datei des Plugins:
    `define('IDF_<UPPER_SLUG_OHNE_IDF_>_VERSION', 'X.Y.Z');`
    Beispiel: Für `idf-login-branding` → `IDF_LOGIN_BRANDING_VERSION`.
-3. **`readme.txt`** im Repo-Root im WordPress-Standard-Format mit mindestens den folgenden Feldern und Abschnitten:
+3. **`readme.txt`** im Repo-Root im WordPress-Standard-Format. Nur die WP-Metadaten pflegen — der Changelog-Abschnitt wird vom Release-Workflow automatisch aus `CHANGELOG.md` gefüllt:
    ```
    === Plugin Name ===
    Contributors: ideenfabrik
@@ -44,16 +44,29 @@ Damit der Reusable Workflow durchläuft, müssen im Plugin-Repo vorhanden sein:
    Kurzbeschreibung des Plugins.
 
    == Changelog ==
+   (wird beim Release automatisch aus CHANGELOG.md generiert)
+   ```
+4. **`CHANGELOG.md`** im Repo-Root — SSOT für den Changelog. Format:
+   ```markdown
+   # Changelog
 
-   = 1.2.3 =
-   * Neu: Feature xyz
-   * Fix: Bug abc
+   ## v1.2.3 — 2026-04-23
 
-   = 1.2.2 =
-   * …
+   ### Neu
+   - Feature xyz
+
+   ### Gefixt
+   - Bug abc
+
+   ---
+
+   ## v1.2.2 — 2026-04-10
+   …
    ```
 
-Alle vier Werte (Tag, Plugin-Header, PHP-Konstante, `Stable tag:` in `readme.txt`) müssen identisch sein. Der Pre-Flight-Check im Reusable bricht sonst ab.
+Alle vier Werte (Tag, Plugin-Header-`Version:`, PHP-Konstante, `Stable tag:` in `readme.txt`) müssen identisch sein. Der Pre-Flight-Check im Reusable bricht sonst ab.
+
+**Pflege-Aufteilung:** Changelog-Einträge nur in `CHANGELOG.md` pflegen. `readme.txt` bekommt seine `== Changelog ==` beim Release automatisch generiert — manuelle Einträge dort werden überschrieben.
 
 ## Release-Ablauf (Agent/Mensch)
 
@@ -61,7 +74,7 @@ Auf `main`, nachdem alles für die Version gemergt ist:
 
 ```bash
 # 1. Plugin-Header-Version, Versions-Konstante und Stable tag in readme.txt auf X.Y.Z setzen
-# 2. Neuen Block in readme.txt unter == Changelog == ergänzen (neueste Version oben)
+# 2. Neuen Block in CHANGELOG.md ergänzen (neueste Version oben)
 # 3. Commit
 git add -A
 git commit -m "Release v1.2.3"
@@ -72,7 +85,7 @@ git tag v1.2.3
 git push --tags
 ```
 
-Danach läuft die Action automatisch durch. Bei Erfolg liegt auf Gitea ein Release `v1.2.3` mit dem ZIP `idf-<slug>_v1.2.3.zip` als Asset und dem Changelog-Block als Body.
+Danach läuft die Action automatisch durch. Bei Erfolg liegt auf Gitea ein Release `v1.2.3` mit dem ZIP `idf-<slug>_v1.2.3.zip` als Asset und dem Changelog-Block als Body. Das ZIP enthält `readme.txt` mit der automatisch befüllten `== Changelog ==`-Section.
 
 ## Pinning-Empfehlung
 
@@ -89,10 +102,11 @@ Breaking Changes am Reusable Workflow → neuer Major (`v2`). Plugin-Repos müss
 Bei abgebrochenem Release:
 
 - **„Tag entspricht nicht vMAJOR.MINOR.PATCH"** → Tag falsch formatiert. Alten Tag löschen (`git tag -d vX && git push origin :refs/tags/vX`), neu taggen.
+- **„Pflichtdateien fehlen: CHANGELOG.md / readme.txt"** → Datei im Repo-Root anlegen, Commit, Tag neu setzen.
 - **„Plugin-Header-Version ≠ Tag"** → `<slug>.php` Version-Zeile korrigieren, Commit, Tag neu setzen.
 - **„Konstante ≠ Tag"** → Versions-Konstante im PHP anpassen, Commit, Tag neu setzen.
-- **„readme.txt fehlt" / „Stable tag ≠ Tag"** → `readme.txt` im Repo-Root anlegen bzw. `Stable tag:` korrigieren, Commit, Tag neu setzen.
-- **„Kein Changelog-Block für v…"** → Block `= X.Y.Z =` unter `== Changelog ==` in `readme.txt` anlegen, Commit, Tag neu setzen.
+- **„Stable tag ≠ Tag"** → `Stable tag:` in `readme.txt` korrigieren, Commit, Tag neu setzen.
+- **„Kein Changelog-Block für v…"** → Block `## v1.2.3 — <Datum>` in `CHANGELOG.md` anlegen, Commit, Tag neu setzen.
 - **Release-Anlage fehlgeschlagen** → Wahrscheinlich fehlende Token-Berechtigung. `GITEA_TOKEN`-Secret prüfen oder den Standard `github.token` nutzen.
 
 Wichtig: Ein Tag, unter dem ein Release bereits existiert, kann nicht erneut einen Release erzeugen. Bei Korrekturen eine PATCH-Version höher tagen, nicht denselben Tag neu setzen.