diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f526818
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# Resonanzband Untersuchung
+
+## Überblick
+Untersuchung der Wechselwirkungen zwischen Startkohorten und Resonanzband in einem Testszenario. Diese Studie analysiert die dynamische Veränderung der Band-Lage in Abhängigkeit der Kohortenparameter und visualisiert die Ergebnisse als Heatmap.
+
+**Projekt-Key:** `resonanzband_untersuchung`
+
+**Artikel-Link:** [https://donau2space.de/tag-181-run-27-burst-verschoben-wandert-das-resonanzband-wirklich-mit-der-kohorte/](https://donau2space.de/tag-181-run-27-burst-verschoben-wandert-das-resonanzband-wirklich-mit-der-kohorte/)
+
+**Git-Repository:** [https://git.donau2space.de/Mika/resonanzband_untersuchung](https://git.donau2space.de/Mika/resonanzband_untersuchung)
+
+### Hinweis
+Alle Inhalte wurden per KI generiert. Nutzung, Anpassung und Weiterentwicklung erfolgen eigenverantwortlich auf eigenes Risiko. Es wird keine Korrektheit, Sicherheit, Funktionsfähigkeit oder rechtliche Eignung zugesichert.
+
+## Inhalt des Repositories
+
+### Artefakte
+
+#### 1. `run_data_analysis`
+- **Art:** Python-Skript (`python_script`)
+- **Zielumgebung:** Linux Userspace
+- **Sprache:** Python
+- **Zweck:** Analyse der Runs zur Bestimmung der Band-Lage und relevanter Kennzahlen.
+- **API-Funktion:**
+  - `analyse_run_data(run_data)` → Gibt `analysis_results` zurück.
+- **Datenstruktur:**
+  - `RunData` (JSON): Felder `band_center`, `band_width`, `cluster_score`, `retry_tail`
+
+#### 2. `heatmap_visualization`
+- **Art:** Webanwendung (`web_ui`)
+- **Zielumgebung:** Webbrowser
+- **Sprachen:** HTML, CSS, JavaScript
+- **Zweck:** Darstellung der Heatmap der Resonanzband-Lage über eine Weboberfläche.
+- **API-Routen:**
+  - `GET /heatmap` → Lädt Heatmap-Daten zur Visualisierung.
+- **UI-Komponenten:** CSS-Komponente `heatmap-style`, JS-Modul `heatmap-renderer`
+
+#### 3. `run_metrics_report`
+- **Art:** Datensatz (`csv_dataset`)
+- **Zielumgebung:** Plattformübergreifend
+- **Sprache:** CSV
+- **Zweck:** Export der berechneten Metriken für jede Run-Serie.
+- **API-Funktion:**
+  - `export_metrics(runs)` → Gibt `csv_file_path` zurück.
+- **Datenstruktur:**
+  - `RunMetrics` (Tabelle): `run_id`, `band_center`, `band_width`, `cluster_score`, `retry_tail`
+
+## Voraussetzungen (Webserver)
+- Ein beliebiger Webserver (z. B. Apache oder Nginx)
+- Unterstützt lokale oder modulare JS/CSS-Dateien
+- Zugriff auf die generierten CSV-Dateien für den Heatmap-Datensatz
+
+## Starten der Anwendung
+1. Web-UI-Dateien aus `heatmap_visualization` in den Webserver-Root kopieren.
+2. Server starten und im Browser `http://localhost/heatmap` öffnen.
+3. Heatmap zeigt dynamisch generierte Resonanzband-Ergebnisse.
+
+## Installation & Nutzung (Python-Komponente)
+1. Repository klonen:
+   ```bash
+   git clone https://git.donau2space.de/Mika/resonanzband_untersuchung
+   cd resonanzband_untersuchung
+   ```
+2. Abhängigkeiten installieren (z. B. pandas, numpy):
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. Skript ausführen:
+   ```bash
+   python run_data_analysis.py --input data/runs.json --output results/analysis.json
+   ```
+
+## Typische Use-Cases
+- Analyse und Visualisierung der Resonanzband-Verschiebung über Kohorten hinweg.
+- Vergleich unterschiedlicher Startbedingungen anhand exportierter CSV-Berichte.
+- Experimentelle Validierung der Band-Stabilität unter Testbedingungen.
+
+## Struktur & Erweiterbarkeit
+- `src/` – Python-Analysemodule
+- `web/` – Heatmap-Visualisierungsoberfläche
+- `data/` – Eingabe- und Ergebnisdatensätze im CSV- und JSON-Format
+
+Erweiterbar durch zusätzliche Analysefunktionen oder erweiterte Visualisierungen.
+
+## Lizenz
+Veröffentlicht unter der **MIT-Lizenz**. Nutzung und Weitergabe unter den Bedingungen dieser Lizenz.
+
+**Hinweis:** Dieses Repository enthält KI-generierte Inhalte. Verwendung erfolgt auf eigene Verantwortung.
\ No newline at end of file