docs: record project lessons that are not derivable from code or ADRs

docs/agents/lessons.md

@@ -0,0 +1,46 @@
+# Was man sonst zweimal lernt
+
+Projektwissen, das weder aus dem Code noch aus den ADRs hervorgeht. Kurz halten — hier steht nur, was beim ersten Mal Zeit gekostet hat.
+
+## Das Referenz-Wiki ist nicht abrufbar
+
+Das [Fandom-Wiki zu „The Tower — Idle Tower Defense"](https://the-tower-idle-tower-defense.fandom.com/wiki/The_Tower_-_Idle_Tower_Defense_Wiki) antwortet auf **jede** Unterseite mit `HTTP 402`; Mirrors (`game-vault.net`, `en.namu.wiki`, `tower-hub.com`) laufen in Timeout, 403 oder 502. Das gilt für automatisierte Abrufe, nicht für den Browser.
+
+Der Primärtext liegt deshalb von Hand gesammelt in **`docs/WikiData.md`**. Wer mehr braucht, öffnet die Seite im Browser und hängt sie dort an — Suchmaschinen-Snippets sind es nicht wert: die erste Recherche lief nur über sie und hatte vier Fehler, darunter einen Boss-HP-Wert, der in Wahrheit zu den Fleet-Gegnern gehörte.
+
+**Zwei Seiten existieren nicht** — im Browser gegengeprüft, nicht bloß nicht gefunden:
+
+- die HP-/Schadens-Skalierungsformel pro Welle
+- die Workshop-Kurven (Level-Zahlen, Kosten, Softcaps)
+
+Beides ist damit **Design-Freiheitsgrad, nicht fehlender Beleg**. Nicht noch einmal danach suchen lassen.
+
+## `examples/perf_spike.rs` ist die beste Bevy-0.19-Referenz im Repo
+
+Bevy 0.19 ist neuer als der Wissensstand gängiger Sprachmodelle, und die API hat sich in mehreren Bereichen geändert. Der Perf-Spike ist verifizierter, laufender Code aus diesem Repo: Fenster, Kamera, Sprites, Spawn, Bewegung, Kollision, Diagnostics.
+
+Wer gegen Bevy baut, schaut zuerst dort nach, dann in `src/`, dann auf docs.rs — und rekonstruiert die API nicht aus dem Gedächtnis. Widersprechen sich Gedächtnis und Compiler, hat der Compiler recht.
+
+Der Spike bleibt deshalb liegen, obwohl seine Messung abgeschlossen ist.
+
+## Die Perf-Zahlen sind eine untere Schranke, kein Versprechen
+
+Gemessen auf einer **Notebook-iGPU** (Intel Core Ultra 7 265U) mit **untexturierten, gleichfarbigen Sprites**, ohne UI und ohne Audio. Bevy batcht das optimal — die 0,25 µs pro Sprite sind ein Best-Case.
+
+Die Obergrenze von 10 000 gleichzeitigen Gegnern hat darauf 3–7× Reserve. **Nach dem Wechsel auf echte Texturen und mit dem HUD ist neu zu messen**, nicht zu hoffen. Der Spike ist genau dafür reproduzierbar gehalten; die Kommandos stehen in seinem Kopfkommentar.
+
+## Werkzeuge
+
+**`tea` muss ≥ 0.15.0 sein.** Ältere Builds kennen weder `--labels` beim Anlegen noch `issues edit`, `comment` oder `close` — damit fällt die halbe Konvention in `issue-tracker.md` aus, und der Fehler sieht aus wie ein Konfigurationsproblem. `tea --version` prüfen, bevor man lange sucht.
+
+**Der Rebuild ist schneller im Release-Profil als im Debug** (9–10 s gegen 22–26 s) — das Linken der Debug-Info dominiert. ADR-0001 stützt sich darauf. Die Zahl gilt für ein **warmes** Target-Verzeichnis; auf einer frischen Maschine kompiliert der erste Build die gesamte Bevy-Toolchain.
+
+## Die Widersprüche in der Spec sind Absicht
+
+`docs/spec-vertical-slice.md` schließt mit einem Abschnitt „Widersprüche und Lücken" — sechzehn Einträge. Das ist kein liegengebliebener Entwurf, sondern das Ergebnis davon, dass beim Schreiben zum ersten Mal alle Quellen gleichzeitig gelesen wurden. Ein Eintrag hat einen Formelfehler in ADR-0002 aufgedeckt, der Crit Chance auf null rechnete; ein anderer, dass das geplante Debug-Panel den Spielstand hätte zerstören können.
+
+Wer dort aufräumt, ohne zu entscheiden, löscht die Fundstelle und nicht das Problem. Einträge werden von *offen* auf *entschieden, siehe X* umgestellt — nicht entfernt.
+
+## Widerspricht der Code einer ADR, gewinnt nicht der Code
+
+Fällt beim Bauen auf, dass eine Entscheidung nicht trägt, wird **die ADR geändert** und der Fund am zuständigen Ticket vermerkt. Der Code wird nicht daran vorbeigebaut. Das steht so in beiden Karten und ist der Grund, warum die ADRs nach der ersten Bauphase noch etwas wert sind.