diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2b71392
--- /dev/null
+++ b/README.md
@@ -0,0 +1,155 @@
+# Edu Boardgame Generator
+
+Web-Baukasten, mit dem Schülerinnen und Schüler eigene Lernbrettspiele zusammenstellen: Spielfeld, Story-Elemente, Quiz-Fragen und Mini-Games. Das fertige Spiel läuft direkt im Browser und lässt sich per Link oder sechsstelligem Kurz-Code teilen.
+
+**Live:** https://franke-lab.de/edu-boardgame-generator
+**Kontext:** Pädagogische Hochschule Weingarten, BoysDay / Informatik-Unterricht
+
+## Features
+
+- **Fünf-Schritte-Editor:** Spielidee, Design (Figur, Weltkulisse, Feldanzahl), Spielfeld-Bestückung (Mini-Games pro Feld), Story- und Quiz-Karten, Veröffentlichung.
+- **Player:** Würfel, animierte Figur, Konsequenzen (Felder vor/zurück, Leben, Punkte, Zug aussetzen, nochmal), Sieg-/Verlust-Bildschirm.
+- **Vierzehn Mini-Games:** Snake, Flappy, Memory, Quiz, Reaction, Basketball, Catch, Maze, Simon, Puzzle, Spot-Diff, Typing sowie 2-Spieler-Varianten von Snake und Flappy.
+- **Zwei Wege zum Teilen:** komprimierter URL-Hash (kein Backend nötig) und sechsstelliger Kurz-Code (via API auf dem Server persistiert).
+- **Python-Code-Vorschau:** Die Konfiguration wird als lesbarer Python-Pseudocode ausgegeben – Bindeglied zwischen Baukasten und Programmierunterricht.
+- **PDF-Export** des Spielfelds für den Druck.
+- **QR-Code** zum Aufrufen des Spiels vom Handy.
+
+## Architektur
+
+Reines Frontend, keine Build-Kette. Ein kleiner Node-HTTP-Server dient nur zum Ablegen und Ausliefern der Kurz-Codes.
+
+```
+Browser
+  editor.html   Editor (Wizard, Vorschau, Sharing)
+  game.html    Player
+  play/         Landing-Seite für Kurz-Code-Aufruf
+    |
+    | fetch /api/boardgame-play/{code}
+    v
+nginx (franke-lab.de) --> Node.js :3009 --> play/codes/{code}.json
+```
+
+- Der Editor speichert Zwischenstände in `localStorage`.
+- Beim Teilen wird die Konfiguration mit pako gzip-komprimiert und base64-kodiert. Kleine Spiele passen in einen URL-Fragment (`#z:…`), größere werden über den Kurz-Code-Endpunkt abgelegt.
+- Der Player liest wahlweise Hash-Fragment oder holt sich das JSON per Kurz-Code.
+
+## Verzeichnisstruktur
+
+```
+edu-boardgame-generator/
+  index.html             Weiterleitung auf editor.html
+  editor.html            Editor-Grundgerüst
+  editor.css
+  game.html              Player-Grundgerüst
+  game.css
+  codegen.js             Python-Code-Vorschau
+  js/
+    state.js             globaler Editor-Zustand + localStorage
+    data.js              Konstanten (Figuren, Welten, Mini-Game-IDs), esc()
+    wizard.js            Schritt-Navigation, Validierung
+    board.js             Spielfeld-Editor, Drag&Drop, Story-Karten
+    quiz.js              Quiz-Editor
+    world.js             Canvas-Rendering des Spielbretts
+    share.js             Serialisierung, URL-Hash, Kurz-Code-Request
+    minigame-test.js     Testlauf einzelner Mini-Games im Editor
+    tour.js              erste Nutzer-Tour
+    game.js              Player-Logik (Würfel, Bewegung, Konsequenzen)
+  minigames/
+    _api.js              MGAPI: onResult, Farb-Themes
+    snake.js, snake2p.js
+    flappy.js, flappy2p.js
+    memory.js, quiz.js, reaction.js
+    basketball.js, catch.js, maze.js
+    simon.js, puzzle.js, spotdiff.js
+    typing.js
+  play/
+    index.html           Landing für /play/{CODE}
+    codes/*.json         persistierte Spiel-Konfigurationen
+```
+
+## Kurz-Code-API
+
+Node-HTTP-Server, hört auf `127.0.0.1:3009`, wird von nginx unter
+`/api/boardgame-play/*` durchgereicht.
+
+| Route | Methode | Beschreibung |
+|---|---|---|
+| `/api/boardgame-play` | POST | Nimmt eine JSON-Konfiguration entgegen, vergibt einen freien Kurz-Code und antwortet mit `{code}` |
+| `/api/boardgame-play/{code}` | GET | Liefert die zugehörige JSON-Konfiguration |
+
+- **Alphabet:** `23456789ABCDEFGHJKLMNPQRSTUVWXYZ` (verwechslungsarm, ohne 0/O/1/I/L)
+- **Code-Länge:** 6 Zeichen
+- **Nutzlast:** maximal 50 KB pro Spiel
+- **Speicherort:** flache JSON-Dateien unter `play/codes/`
+
+## Abhängigkeiten
+
+**Backend:** Node.js (nur Standardbibliothek: `http`, `fs`, `path`) - kein `package.json`, keine externen Pakete.
+
+**Frontend (über CDN eingebunden):**
+- pako 2.1.0 - Komprimierung für URL-Hash-Sharing
+- qrcodejs 1.0.0 - QR-Code zum Spiel
+- jsPDF 2.5.1 - PDF-Export des Spielfelds
+
+## Entwicklung
+
+Es gibt keine Build-Schritte und keine Bundler. Direkt am Live-Server oder lokal editieren.
+
+```bash
+# statisch servieren (im Projektordner)
+python3 -m http.server 8000
+
+# Kurz-Code-Server lokal
+node server.js
+```
+
+Für Test mit lokalem Backend die API-Basis in `js/share.js` anpassen.
+
+## Deployment (Produktions-Setup)
+
+Datei-Ablage:
+
+```
+/var/www/franke-lab/edu-boardgame-generator/    Frontend
+/opt/boardgame-play/server.js                   Kurz-Code-Server
+```
+
+systemd-Unit `boardgame-play.service`:
+
+```
+[Service]
+ExecStart=/usr/bin/node /opt/boardgame-play/server.js
+WorkingDirectory=/opt/boardgame-play
+```
+
+nginx-Snippet:
+
+```
+location ~ ^/api/boardgame-play(/.*)?$ {
+    proxy_pass http://127.0.0.1:3009$1;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+}
+```
+
+## Sicherheit
+
+- Nutzer-Eingaben (Name, Story-Texte, Quiz-Fragen/Antworten, Feld-IDs) werden beim Laden in `sanitizeCfg` gegen Whitelists geprüft und Länge/Bereich geklemmt.
+- Rendering im Player nutzt `textContent` bzw. `esc()` statt roher `innerHTML`-Interpolation.
+- Kurz-Code-Endpunkt akzeptiert nur Codes im definierten Alphabet und lehnt Payloads > 50 KB ab.
+
+## Roadmap
+
+Kurzfristig geplant (aus Nutzer-Beobachtungen 7./8. Klasse):
+
+- Startseite mit „Meine Spiele", Vorlagen und Kurz-Tutorial
+- Zwei-Spieler-Modus für den kompletten Spielablauf (bislang nur pro Mini-Game)
+- Melde-Funktion für problematische Inhalte, IP-Log am Kurz-Code-Endpunkt, Wort-Filter
+- Optionales Nutzerkonto zur Verwaltung eigener Spielcodes
+
+## Lizenz
+
+Interne Nutzung, PH Weingarten. Klärung mit den Autoren vor Weitergabe.