chore: initial import

plugins/trainingsplan/TOOL-README.md

@@ -0,0 +1,107 @@
+# Trainingsplan- & Rezept-Editor 2.0
+
+Der Editor verwaltet Trainingspläne und Rezeptsammlungen innerhalb von boehmitools. Trainingspläne sind zugleich die verbindliche Datenquelle für den `trainingstracker`.
+
+## Planlebenszyklus
+
+Jede Plandatei enthält eine veröffentlichte Fassung und einen bearbeitbaren Entwurf:
+
+```json
+{
+  "plan_id": "phase-1",
+  "revision": 4,
+  "published_revision": 2,
+  "config": {},
+  "draft": {}
+}
+```
+
+- **Entwurf speichern** erhöht die Bearbeitungsrevision, verändert aber nicht den vom Tracker gelesenen Plan.
+- **Plan prüfen** validiert IDs, Progressionsbezüge, Ergebnisschemata und feste Intervalle.
+- **Entwurf veröffentlichen** erzeugt eine neue veröffentlichte Planrevision.
+- Bereits dokumentierte Sessions speichern die Planrevision, nach der sie ausgeführt wurden.
+- Vor dem Ersetzen einer Plandatei wird atomisch geschrieben und ein Backup unter `data/trainingsplan/backups/` angelegt.
+- Gleichzeitige Bearbeitungen werden über eine Revisionsprüfung erkannt und nicht still überschrieben.
+
+## Stabiler Datenvertrag
+
+Trainingspläne verwenden:
+
+```text
+schema_version: 3
+contract_version: 2
+```
+
+Phasen, Tage, Rotationen, Übungsplatzierungen, Bewegungen, Progressionen und Progressionsstufen besitzen dauerhafte IDs. Beim Verschieben im Editor bleiben diese IDs erhalten.
+
+Progressionsstufen sind Objekte und keine parallelen Text-/Schema-Arrays mehr:
+
+```json
+{
+  "id": "step-squat-hold-...",
+  "name": "Deep Squat Hold",
+  "phase_id": "phase-start-...",
+  "movement_cluster": "knee_dominant",
+  "factor": 1.0,
+  "result_schema": {
+    "mode": "seconds",
+    "weight_mode": "optional",
+    "laterality": "bilateral",
+    "sides_mode": "same"
+  }
+}
+```
+
+Dadurch reisen Stufenname, Eingabeformat und Analysefaktor immer gemeinsam.
+
+## Ergebniserfassung
+
+Eine Übung besitzt ein Standardformat. Jede Progressionsstufe kann es überschreiben.
+
+Priorität im Tracker:
+
+```text
+manuelle Anpassung der aktuellen Session
+→ Schema der gewählten Progressionsstufe
+→ Standard der Übung
+→ automatische Erkennung als Fallback
+```
+
+Unterstützt werden Wiederholungen, Sekunden, Minuten, keine Zahl, optionales oder verpflichtendes Gewicht sowie gemeinsame oder getrennte Seitenwerte.
+
+## Tabata und feste Intervalle
+
+Das Trainingsformat wird ausdrücklich gespeichert:
+
+```json
+{
+  "mode": "tabata",
+  "fixed_interval": true,
+  "work_seconds": 20,
+  "rest_seconds": 10,
+  "rounds": 8,
+  "rounds_scope": "block"
+}
+```
+
+`rounds` bezeichnet Intervalle pro Block. Bei acht Intervallen und vier Übungen entstehen zwei Durchgänge pro Übung. Eine zusätzlich im Rotationstitel angegebene Satzanzahl wird damit multipliziert. Ist die Intervallzahl nicht gleichmäßig durch die Übungszahl teilbar, meldet die Validierung einen Hinweis und verlangt eine feste Wertezahl im Ergebnisschema.
+
+## Übungsbibliothek und Analysefaktoren
+
+Aus den Übungen und Progressionen wird eine planbezogene `exercise_catalog` erzeugt. Sie enthält stabile Bewegungs-IDs, Cluster, Varianten, Ergebnisschemata und Faktoren. Diese Angaben haben im Tracker Vorrang vor Namens- und Regex-Erkennung.
+
+## Prüfung und Tracker-Vorschau
+
+Der Tab **Prüfung & Vorschläge** zeigt:
+
+- Validierungsfehler und Hinweise,
+- das vom Tracker erwartete Ergebnisformat pro Übung,
+- stufenabhängige Überschreibungen,
+- die berechneten Durchgänge fester Intervallblöcke,
+- strukturierte KI-Vorschläge aus dem Tracker mit stabilen Ziel-IDs.
+
+Vorschläge werden niemals automatisch in den Plan geschrieben. Über **Ziel im Entwurf öffnen** springt der Editor anhand der stabilen IDs direkt zur betroffenen Übung oder Progression. Nach der manuellen Änderung kann der Vorschlag als übernommen oder abgelehnt markiert werden.
+
+## Kompatibilität
+
+Ältere Pläne werden beim Laden in das neue Schema überführt. Fehlende Ergebnisschemata erhalten dabei einmalig explizite, im Editor korrigierbare Migrationswerte. Die veröffentlichten Beispielpläne liegen bereits in Version 3 vor. Rezeptsammlungen bleiben vom Trainingsvertrag unberührt.