diff --git a/sync-files-sh.md b/sync-files-sh.md
new file mode 100644
index 0000000..3337f5d
--- /dev/null
+++ b/sync-files-sh.md
@@ -0,0 +1,211 @@
+# sync-files.sh
+
+**furt Source-Dateien in Installation-Verzeichnis synchronisieren**
+
+## Getestet unter
+- OpenBSD 7.7
+- Debian 12  
+- Arch Linux
+
+## Zweck des Scripts
+
+Das `sync-files.sh` Script kopiert Source-Dateien aus dem Entwicklungsverzeichnis in das System-Installations-Verzeichnis `/usr/local/share/furt`. Es überträgt Lua-Module, Konfigurationsdateien, Scripts und Version-Informationen mit korrekten Berechtigungen.
+
+Das Script eliminiert manuelles Kopieren während der Entwicklung und stellt sicher dass alle furt-Komponenten konsistent im Installations-Verzeichnis verfügbar sind.
+
+## Wie das Script funktioniert
+
+Das Script prüft zunächst ob es im korrekten Source-Verzeichnis ausgeführt wird:
+
+```bash
+if [ ! -f "src/main.lua" ]; then
+    echo "Error: Not in furt source directory (src/main.lua not found)"
+    exit 1
+fi
+```
+
+Diese Validierung verhindert versehentliche Ausführung in falschen Verzeichnissen die zu unvorhersagbaren Kopier-Operationen führen könnte.
+
+Anschließend werden die Haupt-Verzeichnisse systematisch kopiert:
+
+```bash
+cp -r src/ "$TARGET/"
+cp -r config/ "$TARGET/"
+cp -r scripts/ "$TARGET/"
+cp -r integrations/ "$TARGET/"
+```
+
+Das `-r` Flag sorgt für rekursives Kopieren aller Unterverzeichnisse und Dateien. Die Version-Dateien werden optional kopiert falls sie existieren - das macht das Script kompatibel mit verschiedenen Development-Setups.
+
+## Betriebssystem-Philosophien verstehen
+
+Die Berechtigungs-Behandlung berücksichtigt unterschiedliche System-Konventionen:
+
+### BSD-Ansatz (OpenBSD)
+BSD-Systeme verwenden `root:wheel` als Standard-Ownership für System-Dateien. Die `wheel`-Gruppe repräsentiert administrative Berechtigung und ist tief in der BSD-Tradition verwurzelt.
+
+```bash
+# OpenBSD
+chown -R root:wheel "$TARGET"
+```
+
+Diese Konvention stammt aus den frühen Unix-Tagen und spiegelt BSD's Fokus auf bewährte, stabile Administrationsmodelle wider.
+
+### Linux-Ansatz (Debian, Arch, etc.)
+Linux-Distributionen nutzen typisch `root:root` für System-Dateien. Dies vereinfacht das Berechtigungsmodell und ist konsistent über verschiedene Linux-Flavors hinweg.
+
+```bash
+# Linux
+chown -R root:root "$TARGET"
+```
+
+Das einheitliche `root:root` Pattern macht Linux-Administration vorhersagbarer und reduziert betriebssystem-spezifische Variationen.
+
+## Source-zu-Installation Mapping
+
+Das Script kopiert vier Kern-Verzeichnisse die die gesamte furt-Funktionalität repräsentieren:
+
+**src/:** Lua-Module und Core-Logic. Enthält `main.lua`, Service-Module und Bibliotheken die zur Laufzeit geladen werden.
+
+**config/:** Beispiel-Konfigurationen und Templates. Diese Dateien dienen als Ausgangsbasis für System-spezifische Anpassungen.
+
+**scripts/:** Utility-Scripts für Start/Stop, Testing und Wartung. Beinhaltet `start.sh` welches ausführbare Berechtigung erhält.
+
+**integrations/:** Hugo-Shortcodes und andere Framework-Integrationen. Ermöglicht nahtlose Einbindung in bestehende Website-Workflows.
+
+## Berechtigungs-Strategie
+
+Das Script implementiert eine durchdachte Berechtigungs-Hierarchie:
+
+```bash
+chmod -R 644 "$TARGET"                          # Basis: Read-only für alle
+find "$TARGET" -type d -exec chmod 755 {} \;   # Verzeichnisse: Traversierbar
+chmod +x "$TARGET/scripts/start.sh"            # Scripts: Ausführbar
+```
+
+Diese Strategie folgt dem Principle of Least Privilege - Dateien erhalten nur die minimal notwendigen Berechtigungen für ihre Funktion.
+
+## Script praktisch nutzen
+
+### Development-Workflow
+```bash
+# Nach Code-Änderungen synchronisieren
+cd /path/to/furt/source
+sudo ./scripts/sync-files.sh
+```
+
+Ausgabe bestätigt die Synchronisation:
+```
+Copying furt files to /usr/local/share/furt...
+Files synced successfully to /usr/local/share/furt
+```
+
+### Integration in Build-Process
+```bash
+# Als Teil des Development-Cycles
+make build
+./scripts/sync-files.sh
+systemctl restart furt
+```
+
+Das Script fügt sich nahtlos in iterative Development-Workflows ein wo häufige Code-Updates getestet werden müssen.
+
+### Version-Tracking mit merkwerk
+```bash
+# merkwerk Version-Dateien werden automatisch kopiert
+merkwerk bump patch
+./scripts/sync-files.sh
+# VERSION und .version_history sind jetzt synchronisiert
+```
+
+Die Integration mit merkwerk ermöglicht konsistente Versionierung zwischen Source und Installation.
+
+## Installation validieren
+
+Nach der Script-Ausführung kannst du die Synchronisation prüfen:
+
+```bash
+# Verzeichnisstruktur validieren
+ls -la /usr/local/share/furt/
+ls -la /usr/local/share/furt/src/
+ls -la /usr/local/share/furt/scripts/
+
+# Berechtigungen prüfen
+stat -c "%a %n" /usr/local/share/furt/scripts/start.sh
+# Sollte "755" zeigen für ausführbare Scripts
+```
+
+Korrekte Synchronisation zeigt alle Source-Verzeichnisse mit entsprechenden Berechtigungen:
+```
+drwxr-xr-x root wheel  512 src
+drwxr-xr-x root wheel  512 config  
+drwxr-xr-x root wheel  512 scripts
+-rwxr-xr-x root wheel 1234 scripts/start.sh
+```
+
+## Troubleshooting
+
+### "Not in furt source directory"
+```
+Error: Not in furt source directory (src/main.lua not found)
+```
+Das Script muss im furt Source-Root ausgeführt werden:
+```bash
+cd /path/to/furt/source          # Ins richtige Verzeichnis wechseln
+./scripts/sync-files.sh          # Dann ausführen
+```
+
+### "Permission denied" bei chown
+```
+chown: /usr/local/share/furt: Operation not permitted
+```
+Das Script benötigt Root-Rechte für Ownership-Änderungen:
+```bash
+sudo ./scripts/sync-files.sh    # Linux
+doas ./scripts/sync-files.sh    # OpenBSD
+```
+
+### Target-Verzeichnis existiert nicht
+```
+cp: /usr/local/share/furt/: No such file or directory
+```
+Das `setup-directories.sh` Script muss vor `sync-files.sh` ausgeführt werden:
+```bash
+sudo ./scripts/setup-directories.sh  # Erst Verzeichnisse erstellen
+sudo ./scripts/sync-files.sh         # Dann synchronisieren
+```
+
+### Scripts nicht ausführbar
+Wenn `/usr/local/share/furt/scripts/start.sh` nicht ausführbar ist, prüfe die chmod-Operation:
+```bash
+# Manuell korrigieren
+chmod +x /usr/local/share/furt/scripts/start.sh
+```
+
+## Script erweitern
+
+### Zusätzliche Verzeichnisse
+```bash
+# Weitere Source-Verzeichnisse hinzufügen
+[ -d "docs/" ] && cp -r docs/ "$TARGET/"
+[ -d "examples/" ] && cp -r examples/ "$TARGET/"
+```
+
+### Selektive Synchronisation
+```bash
+# Nur bestimmte Verzeichnisse synchronisieren
+SYNC_DIRS="${SYNC_DIRS:-src config scripts integrations}"
+for dir in $SYNC_DIRS; do
+    [ -d "$dir" ] && cp -r "$dir/" "$TARGET/"
+done
+```
+
+### Backup vor Synchronisation
+```bash
+# Backup der bestehenden Installation
+if [ -d "$TARGET" ]; then
+    cp -r "$TARGET" "$TARGET.backup.$(date +%Y%m%d_%H%M%S)"
+fi
+```
+
+Das `sync-files.sh` Script schließt die Lücke zwischen Development und Installation durch automatisierte, sichere Synchronisation aller furt-Komponenten mit betriebssystem-angemessenen Berechtigungen.
\ No newline at end of file