docs: initialize project

.planning/PROJECT.md

@@ -0,0 +1,96 @@
+# Zauberwald
+
+## What This Is
+
+Zauberwald ist eine Webapplikation, die einem 7-jährigen Kind das 10-Finger-Tastaturschreiben beibringt. Die App verbindet strukturiertes Tipptraining mit einer dynamisch wachsenden, KI-generierten Waldwelt. Fester Übungsrahmen, überraschende Belohnungen — Neugier statt Leistungsdruck.
+
+## Core Value
+
+Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt oder Sterne verdient.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Mikro-Einheiten: 3 Phasen (Entdecken → Üben → Wörter bauen), je 90–120 Sekunden
+- [ ] Kein sichtbarer Leistungsdruck: Keine Scores, Timer, Fehler-Zähler. Fortschritt nur über wachsenden Wald
+- [ ] Bildschirmtastatur: QWERTZ-Layout (DE/CH), Fingerfarben-Zonen, aktive Taste pulsiert
+- [ ] Progressionssystem: 15 Stufen (Grundreihe → Ober → Unter → Sonderzeichen), Stufen 1–6 im MVP
+- [ ] Begleitfigur: 4 Charaktere (Fee Lila, Einhorn Stella, Fuchs Finn, Eule Elsa) mit KI-generierten Dialogen
+- [ ] Waldwelt: KI-generierte Bilder (Gemini) als Belohnung nach jeder Einheit, dauerhaft gecacht
+- [ ] Visuelle Konsistenz: Character Sheets als Referenzbilder, Stil-Referenzbild für alle Generierungen
+- [ ] Adaptives Tempo: Heuristik ±200/500ms, Bereich 1.5–4s, kein sichtbarer Timer
+- [ ] Fehler sind unsichtbar: Falscher Tastendruck → nichts passiert, richtige Taste blinkt sanft
+- [ ] Review-Mechanik: Jede 3. Einheit mischt Buchstaben der letzten 2–3 Stufen
+- [ ] Perfektionismus-Schutz: Nach 2× Wiederholung Ermutigung + Neugier-Trigger
+- [ ] Elternbereich: Ctrl+Shift+E + Code "1234", Fortschrittsstatistik, Export/Import, Einstellungen
+- [ ] Audio: Web Audio API Sounds (Tastendruck, Belohnung, Waldelement), optionale Sprachausgabe via Web Speech API
+- [ ] Pre-Generation: Belohnungsbild wird während Übung im Hintergrund generiert
+- [ ] Fallback-System: Statische Bilder + Texte wenn API nicht verfügbar
+
+### Out of Scope
+
+- Stufen 7–15 (untere Reihe, Grossbuchstaben, Zahlen, Sonderzeichen) — MVP fokussiert auf Stufen 1–6
+- Ganze Sätze tippen — erst relevant nach allen Buchstaben
+- "Freies Schreiben"-Modus — späterer Milestone
+- Saisonale Wald-Themen — nice-to-have, nicht MVP
+- Begleitfigur reagiert auf längere Abwesenheit — späterer Milestone
+- Druckbare Urkunden — nicht MVP
+- Mobile Support — Desktop-only, Kind nutzt Linux-Laptop
+- OAuth/Social Login — kein Nutzersystem nötig, eine Nutzerin
+- Echtzeit-Chat — irrelevant für Einzelnutzung
+- Video-Inhalte — Storage/Bandwidth, unnötig
+
+## Context
+
+- **Primäre Nutzerin**: 7 Jahre, 1. Klasse, vermuteter ADHS-Hintergrund (nicht diagnostiziert). Niedrige Frustrationstoleranz, impulsiv, Perfektionismus-Neigung. Max. 5 Min. Übungsdauer. Interessen: Tiere, Feen, Einhörner, Magie, Natur.
+- **Technischer Kontext**: Linux-Laptop, Desktop-Browser, stabile Internetverbindung. Einzige Nutzerin.
+- **Entwicklungsumgebung**: VPS (kein lokaler Rechner). Vite Dev-Server muss auf 0.0.0.0 lauschen, Port 5173. Papa testet via `http://<vps-ip>:5173`.
+- **Pädagogisches Prinzip**: Genauigkeit vor Geschwindigkeit. Kein negatives Feedback jeglicher Art. Neugier als Motor.
+- **Gemini API**: Key in `public/config.json` (nicht in Git). Text: gemini-2.5-flash. Bild: gemini-3.1-flash-image-preview (Nano Banana 2). Character Consistency via Referenzbilder.
+- **Asset-Pipeline**: Character Sheets + Avatare werden vorab per Build-Script generiert und eingecheckt. Kein Onboarding-Warten.
+
+## Constraints
+
+- **Tech Stack**: Vanilla TypeScript, Vite 6.x, kein Framework. Einzelne main.css mit CSS Custom Properties. Biome für Lint. Vitest für Tests.
+- **API**: Gemini REST via fetch(), kein Google SDK. Key im Frontend akzeptabel (private Nutzung).
+- **Datenhaltung**: IndexedDB (Bilder als Blobs). Kein Backend, kein Server.
+- **Layout**: QWERTZ DE + CH. Unterschiede erst ab Stufe 14+ relevant.
+- **Styling**: Pastellfarben, Aquarell-Stil, Quicksand + Nunito Fonts, min. 16px. Sanfte Animationen.
+- **VPS-Deployment**: `--host 0.0.0.0`, Port 5173 (dev) / 4173 (preview). Kein HTTPS nötig.
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Vanilla TypeScript statt Framework | Minimale Komplexität, kein Framework-Overhead | — Pending |
+| DOM-basierte Waldszene (img über SVG) | Einfachste Lösung für generierte PNGs, kein Canvas/WebGL | — Pending |
+| Raster 4×3 mit ±20px Variation für Bildplatzierung | Vorhersehbar, kein Overlap | — Pending |
+| Gemini 3.1 Flash Image Preview für Bilder | Neuestes Modell, Character Consistency, wird nicht abgeschaltet | — Pending |
+| Web Speech API statt Gemini TTS | Gratis, offline-fähig, kein extra API-Call | — Pending |
+| Vorab-generierte Character Assets | Kein Onboarding-Warten, volle Kontrolle über Qualität | — Pending |
+| Adaptives Tempo Heuristik statt ML | Einfach implementierbar, ausreichend für den Zweck | — Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-03-29 after initialization*