feat: Add important layout directory guidelines and best practices to README.md

README.md

@@ -670,6 +670,60 @@ Neue Felder in einer Entity erfordern Änderungen in **drei Bereichen**:
 - `detailSmall.json` - Seitenleisten-Ansicht
 - `filters.json` - Filter-Felder
 
+---
+
+### ⚠️ WICHTIG: Zwei verschiedene Layout-Verzeichnisse!
+
+**EspoCRM verwendet zwei verschiedene Layout-Verzeichnisse mit unterschiedlichen Zwecken:**
+
+#### 1. **Frontend-Layouts** (PRIMÄR - meistens benötigt)
+**Pfad:** `custom/Espo/Custom/Resources/layouts/{Entity}/{LayoutType}.json`
+
+✅ **Verwenden für:**
+- Liste-Ansichten: `list.json`, `listSmall.json`
+- Detail-Ansichten: `detail.json`, `detailSmall.json`
+- Bottom-Panels: `bottomPanelsDetail.json`
+- Relationship-Panels (werden über `listSmall.json` definiert)
+- Alle UI-bezogenen Layouts
+
+**Beispiel:**
+```
+custom/Espo/Custom/Resources/layouts/
+├── CBeteiligte/
+│   ├── list.json
+│   ├── listSmall.json         ← Wird in Relationship-Panels verwendet!
+│   ├── detail.json
+│   └── bottomPanelsDetail.json
+```
+
+#### 2. **Metadata-Layouts** (SEKUNDÄR - selten benötigt)
+**Pfad:** `custom/Espo/Custom/Resources/metadata/layouts/{Entity}/{LayoutType}.json`
+
+⚠️ **Nur verwenden für:**
+- Backend-spezifische Layout-Definitionen
+- Erweiterte Konfigurationen
+- In den meisten Fällen NICHT benötigt!
+
+**Regel:**
+> **Relationship-Panels in Bottom-Views nutzen IMMER `listSmall.json` aus dem `layouts/` Verzeichnis (NICHT `metadata/layouts/`)!**
+
+**Häufiger Fehler:**
+```bash
+# ❌ FALSCH - wird ignoriert!
+custom/Espo/Custom/Resources/metadata/layouts/CBeteiligte/listSmall.json
+
+# ✅ RICHTIG - wird verwendet!
+custom/Espo/Custom/Resources/layouts/CBeteiligte/listSmall.json
+```
+
+**Best Practice:**
+- Layouts IMMER in `custom/Espo/Custom/Resources/layouts/` erstellen
+- Das `metadata/layouts/` Verzeichnis nur verwenden, wenn explizit dokumentiert
+- Nach Änderungen: `./custom/scripts/check_and_rebuild.sh`
+- Browser Hard Refresh (Ctrl+Shift+R) durchführen
+
+---
+
 ### clientDefs/{EntityType}.json
 
 **Format-Beispiel:**