diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..da4492b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,71 @@
+# darktable-sync — Projektdokumentation für Claude
+
+## Zweck
+Bash-Skripte zur bidirektionalen Synchronisation der Darktable-Datenbank und Fotobibliothek zwischen lokalem Rechner und einem Server via rsync/SSH. Entwickelt für Linux mit systemd.
+
+## Architektur
+
+```
+darktable_wrapper.sh   → Startet Pre-/Post-Sync, dann Darktable
+darktable_sync.sh      → Hauptsync-Engine (Upload + Download)
+darktable_common.sh    → Gemeinsame Hilfsfunktionen (wird per source eingebunden)
+```
+
+### Ablauf darktable_sync.sh
+1. Dependencies prüfen (rsync, ssh, notify-send, darktable)
+2. Config laden und validieren
+3. Lock erwerben (atomares `mkdir`)
+4. Dry-Run-Modus prüfen (Standard: Trockenlauf; `--execute`/`-e` für echten Sync)
+5. Darktable-Prozess prüfen (Sync verboten wenn darktable läuft)
+6. Server-Erreichbarkeit prüfen → `sync_pending` bei Fehler
+7. Active-Marker prüfen (verhindert gleichzeitige Clients)
+8. Darktable-Versionen abgleichen (Major.Minor müssen übereinstimmen)
+9. Sync-Token prüfen (Konflikterkennung bei mehreren Clients)
+10. DB-Backup erstellen (library.db.bak, data.db.bak) — nur bei `--execute`
+11. Backup-Verzeichnisse anlegen (`${LOCAL_PHOTO_DIR}-bak`, `${LOCAL_DARKTABLE_DB_DIR}-bak`)
+12. Upload: DB und Fotos mit `--delete` (lokal gelöscht → Server gelöscht)
+13. Download: DB und Fotos mit `--delete --backup --backup-dir` (lokal gelöscht → ins `-bak`-Verzeichnis)
+14. Sync-Token und Versionsdatei speichern
+15. Alte Backups bereinigen (`cleanup_old_backups`, >730 Tage)
+
+## Konfiguration
+- Datei: `~/.config/darktable-sync/.env` (Permissions: 600)
+- Wichtige Variablen: `SERVER_IP`, `SERVER_USER`, `SERVER_SSH_PORT`, `SERVER_DB_DIR`, `SERVER_PHOTO_DIR`, `LOCAL_DARKTABLE_DB_DIR`, `LOCAL_PHOTO_DIR`, `DARKTABLE_BIN`, `SYNC_BIN`
+- Vorlage: `.env.example`
+
+## rsync-Flags
+| Operation | Flags |
+|---|---|
+| Upload DB | `-uavh --itemize-changes --delete --exclude '*.lock' --exclude 'darktable_version'` |
+| Upload Fotos | `-uavh --itemize-changes --delete --exclude '*.lock'` |
+| Download DB | `-uavh --itemize-changes --delete --backup --backup-dir="${LOCAL_DARKTABLE_DB_DIR}-bak"` |
+| Download Fotos | `-uavh --itemize-changes --delete --backup --backup-dir="${LOCAL_PHOTO_DIR}-bak"` |
+
+Dry-Run: `RSYNC_DRY_FLAG=(--dry-run)` wird zu allen Aufrufen hinzugefügt.
+
+## itemize-changes Format
+- `>f+++++++++` — neue Datei (Upload)
+- `<f+++++++++` — neue Datei (Download)
+- `>f` / `<f` ohne `+` — aktualisiert
+- `*deleting` — gelöscht
+
+## Sicherheitsmechanismen
+- `validate_path`: Blockiert `' " ; | & \` $ ( ) \` und `..` in Pfaden (Server- UND lokale Pfade)
+- `load_config`: Blockiert `; | & \`` in der .env vor dem source
+- Leeres Quellverzeichnis vor Upload → Abbruch (Schutz vor falschem Mount)
+- Atomares Locking via `mkdir`
+- SSH immer mit `BatchMode=yes` und `ConnectTimeout=5`
+
+## Test-Infrastruktur
+- Framework: **BATS** (`tests/*.bats`)
+- Stubs in `tests/stubs/`: `rsync`, `ssh`, `darktable`, `notify-send`, `pgrep`, `zenity`, `kdialog`
+- Stub-Aktivierung: `run_with_stubs` setzt `tests/stubs/` vorne in PATH
+- Steuerung via Env-Variablen: `RSYNC_STUB_FAIL`, `RSYNC_STUB_DRY_LINES`, `RSYNC_STUB_ARGS_FILE`, `SSH_STUB_FAIL`, `SSH_STUB_OUTPUT`, `PGREP_STUB_FOUND`
+- Setup: `create_valid_env` in `tests/helpers/setup.bash`; jeder Test bekommt isoliertes `$HOME` in `$BATS_TMPDIR`
+- Tests ausführen: `bats tests/`
+
+## Installation
+`install.sh` — interaktiv, prüft Dependencies, kopiert Skripte nach `~/.local/bin/`, richtet systemd-Service ein.
+
+## Bekannte offene Punkte
+- **M1 (Security, niedrig):** `validate_path` sieht `$VAR` nicht, da bash beim `source .env` bereits expandiert. Angreifer braucht Schreibzugriff auf `.env` — begrenzter Schaden.