Dokumentation auf v0.3.0 aktualisiert

- README.md: Neue Features, Changelog und Formeln aktualisiert
- HILFE.md: Präzisions-Anzeige, max_bpm_speed, Version
- CLAUDE.md: Settings-Persistierung, UI-Design, Metronom-Timing
- MIGRATIONS.md: Migration 5fcbe91de50b dokumentiert

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CLAUDE.md

@@ -136,15 +136,23 @@ curl http://localhost:5000/debug
 - Target accuracy: 96% (configurable)
 - Tracks last 50 keystrokes to calculate rolling accuracy
 - Speed increases when accuracy is high, decreases when low
+- Maximum speed configurable (default: 100 BPM) to prevent overwhelming users
+- Runs independently with precise timing (Web Audio API, not setTimeout)
 - Implementiert in `metronome.js` mit zwei Klassen:
-  - `AdaptiveMetronome`: Geschwindigkeitsanpassungslogik
-  - `MetronomePlayer`: Audio-Wiedergabe und Timing
+  - `AdaptiveMetronome`: Geschwindigkeitsanpassungslogik mit `maxSpeed` option
+  - `MetronomePlayer`: Audio-Wiedergabe und präzises Timing
 
 **Visual Feedback**:
 - Green highlighting for correct characters
 - Red highlighting with orange overlay for incorrect characters
 - Blinking cursor shows current typing position
 
+**UI Design (v0.3.0)**:
+- Minimalistic statistics display without colorful badges
+- Right-aligned values with consistent spacing
+- Precision display (100 - error_rate) instead of error rate for positive feedback
+- Uniform button colors: Blue (primary actions), Green (continue), Red (end)
+
 ### Data Storage
 
 **Lessons**: `data/lessons.json`
@@ -191,15 +199,18 @@ Time measurement starts with the first keystroke and runs continuously. All keys
 
 ## Configuration & Settings
 
-**Metronome Settings** (stored in Flask session):
+**Metronome Settings** (stored persistently in UserSettings database table):
 - `metronome_enabled`: Boolean for on/off
 - `metronome_bpm`: Beats per minute
 - `metronome_sound`: Sound type ('beep')
 - `metronome_mode`: 'automatic' or manual
 - `metronome_speed`: Base speed setting
 - `target_error_rate`: Target error percentage (default: 5%)
+- `max_bpm_speed`: Maximum speed for adaptive metronome (default: 100 BPM) - prevents overwhelming users
 - `speed_display`: 'zpm' or 'wpm' for display preference
 
+**Version Display**: Version number from VERSION file is displayed in the header using `APP_VERSION` template variable.
+
 **Secret Key**: Update `app.secret_key` in `app.py:10` for production use.
 
 ## Database Schema Changes

HILFE.md

@@ -139,7 +139,8 @@ Das Metronom reagiert so:
 
 ### Grenzen
 - **Minimum**: 40 BPM (Beats pro Minute)
-- **Maximum**: 200 BPM
+- **Maximum**: Konfigurierbar (Standard: 100 BPM, absolute Obergrenze: 200 BPM)
+- **Einstellbar**: In den Einstellungen als "Maximale Metronom-Geschwindigkeit"
 
 ---
 
@@ -153,7 +154,7 @@ Das Metronom reagiert so:
 | **Falsche Zeichen** | Fehler und Korrekturen | Zähler |
 | **Tastaturanschläge** | Alle Tasten inkl. Backspace | Gesamt |
 | **ZPM** | Zeichen pro Minute | (Korrekte Zeichen / Zeit) × 60 |
-| **Fehler in %** | Fehlerrate | (Falsche / Gesamt) × 100 |
+| **Präzision in %** | Genauigkeit der Eingabe | 100 - (Falsche / Gesamt) × 100 |
 | **WPM** | Wörter pro Minute | (Korrekte / 5) / (Zeit / 60) |
 
 ### Historische Statistiken
@@ -314,6 +315,7 @@ Der Text scrollt **automatisch**, sodass:
 ### Metronom-Einstellungen
 - **Modus**: Automatisch / Manuell
 - **Geschwindigkeit**: BPM-Wert (bei Manuell)
+- **Maximale Geschwindigkeit**: 40-200 BPM (Standard: 100) - verhindert Stress bei fehlerfreiem Tippen
 - **Sound**: Beep / Klick
 - **Ziel-Fehlerrate**: Anpassungsschwelle
 
@@ -422,4 +424,4 @@ Der Text scrollt **automatisch**, sodass:
 
 ---
 
-*Typewriter Trainer v0.2.0 - Mit ❤️ entwickelt für effektives Tipptraining*
+*Typewriter Trainer v0.3.0 - Mit ❤️ entwickelt für effektives Tipptraining*

MIGRATIONS.md

@@ -79,6 +79,18 @@ alembic history --verbose
    alembic upgrade head
    ```
 
+## Migration History
+
+### 5fcbe91de50b - Add max_bpm_speed to UserSettings (v0.3.0)
+- **Datum**: 2025-10-28
+- **Beschreibung**: Fügt `max_bpm_speed` Spalte zur `user_settings` Tabelle hinzu
+- **Typ**: Column Addition
+- **Default**: 100 (BPM)
+- **Zweck**: Ermöglicht Konfiguration der maximalen Metronom-Geschwindigkeit
+
+### 8f83d622eb4b - Initial migration
+- **Beschreibung**: Initiale Datenbank-Struktur
+
 ## Best Practices
 
 - Immer vor einer Migration ein Backup der Datenbank erstellen

README.md

@@ -1,6 +1,6 @@
 # 🎹 Typewriter Tutor - Adaptiver Tipptrainer
 
-**Version:** v0.2.0 _(siehe [VERSION](VERSION) Datei)_
+**Version:** v0.3.0 _(siehe [VERSION](VERSION) Datei)_
 
 Ein moderner, webbasierter Tipptrainer mit **adaptivem Metronom** und umfangreichen Statistiken. Das Programm passt sich automatisch Ihrer Tippgeschwindigkeit an und hilft Ihnen, das Zehnfingerschreiben systematisch zu erlernen.
 
@@ -12,13 +12,16 @@ Ein moderner, webbasierter Tipptrainer mit **adaptivem Metronom** und umfangreic
 - **Automatische Geschwindigkeitsanpassung**: Das Metronom passt sich dynamisch Ihrer Tippgeschwindigkeit an
 - **5 intelligente Anpassungsregeln**: Beschleunigt bei hoher Genauigkeit, bremst bei Fehlern
 - **Zielgenauigkeit**: Hält Sie im optimalen Bereich von 91-95% Genauigkeit
+- **Konfigurierbare Obergrenze**: Maximale Geschwindigkeit einstellbar (Standard: 100 BPM)
+- **Präzises Timing**: Läuft unabhängig von Tastatureingaben mit Web Audio API
 - **Zwei Modi**:
   - **Automatisch**: Adaptives Metronom (empfohlen)
   - **Explizit**: Feste Geschwindigkeit (40-200 BPM)
 - **Streak-Bonus**: Belohnt fehlerfreies Tippen mit höherer Geschwindigkeit
 
 ### 📊 **Umfangreiche Statistiken**
-- **Echtzeit-Metriken**: ZPM (Zeichen/Minute), WPM (Wörter/Minute), Fehlerrate
+- **Echtzeit-Metriken**: ZPM (Zeichen/Minute), WPM (Wörter/Minute), Präzision in %
+- **Positive Darstellung**: Präzisions-Anzeige statt Fehlerrate für motivierendes Feedback
 - **Detaillierte Diagramme**: Visualisierung Ihrer Fortschritte mit Chart.js
 - **Lektionsbasierte Auswertung**: Separate Statistiken für jede Lektion
 - **Historische Daten**: Verfolgen Sie Ihre Entwicklung über die Zeit
@@ -30,6 +33,8 @@ Ein moderner, webbasierter Tipptrainer mit **adaptivem Metronom** und umfangreic
   - ✅ Grün für korrekte Zeichen
   - ❌ Rot für Fehler mit orangefarbener Anzeige des falsch eingegebenen Zeichens
   - 📍 Blinkender Cursor zeigt Ihre Position
+- **Dezentes Design**: Schlichte, ablenkungsfreie Statistik-Anzeige ohne bunte Badges
+- **Versionsnummer**: Im Header sichtbar für bessere Nachvollziehbarkeit
 - **Dark/Light Mode**: Komfortable Arbeit bei Tag und Nacht
 - **Responsive Design**: Funktioniert auf Desktop und mobilen Geräten
 - **Hilfe-System**: Integrierte Hilfe mit detaillierten Erklärungen
@@ -165,6 +170,7 @@ typewriter/
 - **Modus**: Automatisch (adaptiv) oder Explizit (feste Geschwindigkeit)
 - **Geschwindigkeit**: 40-200 ZPM (nur im Explizit-Modus)
 - **Ziel-Fehlerrate**: 1-20% (nur im Automatik-Modus)
+- **Maximale Geschwindigkeit**: 40-200 BPM (Standard: 100) - verhindert Überforderung bei fehlerfreiem Tippen
 
 **Statistik-Anzeige:**
 - **ZPM** (Zeichen pro Minute) oder **WPM** (Wörter pro Minute)
@@ -180,7 +186,7 @@ Wörter pro Minute (WPM) = (Korrekte Zeichen / 5) / (Zeit in Minuten)
 
 Fehlerrate (%) = (Falsche Tastenanschläge / Gesamte Tastenanschläge) × 100
 
-Genauigkeit (%) = 100 - Fehlerrate
+Präzision (%) = 100 - Fehlerrate
 ```
 
 ### Statistik-Seite
@@ -363,7 +369,16 @@ Contributions sind willkommen! Bitte:
 
 > **Hinweis:** Die aktuelle Versionsnummer wird zentral in der [VERSION](VERSION) Datei verwaltet.
 
-### Version 0.2.0 (Aktuell)
+### Version 0.3.0 (Aktuell)
+- ✅ **Maximale Metronom-Geschwindigkeit**: Konfigurierbar (Standard: 100 BPM) zur Vermeidung von Überforderung
+- ✅ **Präzisions-Anzeige**: Positive Darstellung (Präzision statt Fehlerrate) für motivierendes Feedback
+- ✅ **Persistente Settings**: Einstellungen werden in Datenbank gespeichert (nicht nur Session)
+- ✅ **Metronom-Timing**: Web Audio API für präzises, unterbrechungsfreies Timing
+- ✅ **UI-Verbesserungen**: Dezente Statistik-Anzeige ohne bunte Badges, einheitliches Button-Design
+- ✅ **Versionsnummer**: Im Header sichtbar
+- ✅ **Alembic-Migration**: `max_bpm_speed` zur UserSettings-Tabelle hinzugefügt
+
+### Version 0.2.0
 - ✅ **Streak-Statistik**: 30-Tage Balkendiagramm mit täglicher Übungszeit
 - ✅ **Persistente Einstellungen**: Alle Einstellungen und Lektion werden gespeichert
 - ✅ **Session-Ende**: Übersichtsseite mit Statistiken beim Beenden