Projektregeln und Modul-Anleitungen ergänzen

AGENTS.md

@@ -15,6 +15,11 @@ Versorgung und Sicherheit im Plan.
 - Auf Deutsch, klar und knapp kommunizieren.
 - `PLAN.md` als Arbeitsplan pflegen; erledigte Punkte, offene Entscheidungen
   und verifizierte Ergebnisse getrennt dokumentieren.
+- Diese `AGENTS.md` nach dauerhaften Änderungen an Architektur, Betrieb,
+  Sicherheit oder Werkzeugen im selben Arbeitsgang aktualisieren.
+- Vor Änderungen in `halloween/`, `tools/`, `tests/` oder `preview/` die dortige
+  `instructions.md` lesen und bei geänderten Verträgen oder Abläufen
+  aktualisieren. Neue Modulordner erhalten eine eigene `instructions.md`.
 - Vor Änderungen vorhandene Dateien und tatsächliche Hardware prüfen.
 - Vorschläge und Annahmen ausdrücklich kennzeichnen; keine Kameramodelle,
   Motorleistungen, Anschlüsse, Netzwerkadressen oder Preise erfinden.

halloween/instructions.md

@@ -0,0 +1,23 @@
+# Modul `halloween/`
+
+Hier liegt die erste Pi-WebUI. `run.py` im Projektstamm startet sie.
+
+- `camera.py` liefert ein gemeinsames MJPEG-Bild für mehrere Betrachter.
+  `--demo` erzeugt ausdrücklich gekennzeichnete Testbilder; echte Kamera
+  läuft nur über Picamera2 auf dem Pi. Kamerafehler sichtbar melden.
+- `controller.py` enthält bislang ausschließlich die simulierte
+  Effekt-Zustandslogik. Stopp bleibt bis zum Rücksetzen bestehen; nach Start
+  oder Rücksetzen muss erst der Bereich frei sein und dann ein neuer Trigger
+  kommen. Beschädigte Einstellungen schalten auf `aus`.
+- `web.py` bietet WebUI und API; `index.html` ist die Oberfläche. `run.py`
+  bindet an `127.0.0.1`, Zugriff vom Laptop erfolgt per SSH-Tunnel.
+- Der Header `X-Halloween-UI` ist nur eine einfache Schranke für
+  Schreibaufrufe, kein echter Zugangsschutz. Vor Betrieb mit anderen
+  Netzfreigaben Authentifizierung entwerfen und prüfen.
+- Laufzeitdaten liegen standardmäßig unter `data/` und werden weder
+  hochgeladen noch in Git aufgenommen.
+- Echte GPIO-/Aktorsteuerung erst nach geklärter Mechanik, Versorgung,
+  sicherem Stopp und den Hardwaretests aus `PLAN.md` ergänzen.
+
+Bei Änderungen an Zustandsübergängen oder Endpunkten die zugehörigen Tests
+unter `tests/` und die Bedienhinweise in `SOFTWARE.md` prüfen.

preview/instructions.md

@@ -0,0 +1,15 @@
+# Modul `preview/`
+
+Die Blender-Szenen illustrieren das Konzept; sie sind kein Nachweis für
+echte Mechanik oder Personenerkennung.
+
+- `README.md` und die Unterordner `v2/`, `v3/`, `v4/` beschreiben die
+  jeweiligen Fassungen. Neue Fassungen mit Ziel, Änderungen und tatsächlich
+  geprüften Bildern/Videos dokumentieren.
+- Bearbeitbare `.blend`-Szenen sind Git-Quellen. Gerenderte Bilder, Videos,
+  Tondateien und `.blend1`-Backups liegen nur lokal; sie werden durch
+  `.gitignore` ausgeschlossen.
+- Reproduktions- und Prüfscripte liegen unter `tools/`; Pfade in den
+  README-Dateien aktuell halten.
+- Bildprüfung, vollständigen Videorender und reale Hardwareprüfung klar
+  getrennt ausweisen. Ein Standbild belegt keine Bewegung im fertigen Video.

tests/instructions.md

@@ -0,0 +1,13 @@
+# Modul `tests/`
+
+Automatische Tests prüfen die aktuelle Software ohne Pi-Hardware.
+
+- `test_controller.py` prüft Zustandswechsel, Stopp, Neustartvoraussetzungen
+  und gespeicherten Modus mit kontrollierter Uhr und temporären Daten.
+- `test_web.py` prüft Demo-Bild und Webendpunkte über einen ASGI-Client.
+- Lokal ausführen: `python3 -m unittest discover -s tests -v`; für Webtests
+  wird zusätzlich `requirements-dev.txt` benötigt.
+- Hardwareverhalten, echte Pi-Kamera, WLAN, SSH-Tunnel und Außeneinsatz nicht
+  aus einem grünen Host-Test ableiten; diese Prüfungen getrennt berichten.
+- Tests für neue Sicherheits- oder Zustandsregeln an beobachtbarem Verhalten
+  ausrichten, nicht bloß interne Implementierung spiegeln.

tools/instructions.md

@@ -0,0 +1,21 @@
+# Modul `tools/`
+
+Hier liegen Pi-Transfer/Einrichtung und die reproduzierbaren Blender-Werkzeuge.
+
+- `upload_to_pi.sh` zeigt ohne `--apply` nur eine Vorschau. Beim Übertragen
+  keine Dateien auf dem Pi löschen; `.git`, `.venv`, `data`, Vorschauen,
+  Referenzen und Schlüsseldateien ausgeschlossen lassen. SSH-Hostschlüssel
+  weiterhin prüfen.
+- `install_pi_service.sh` richtet den optionalen systemd-Autostart ein.
+  Die Python-Umgebung muss vorher auf dem Pi eingerichtet sein. Der Dienst
+  bindet über `run.py` nur an `127.0.0.1`; `sudo` nur bei `--apply`.
+- Render-, Ton- und Prüfscripte unter `tools/` erzeugen Dateien in
+  `preview/`. Bearbeitbare `.blend`-Szenen werden versioniert, gerenderte
+  Medien und `.blend1`-Backups bleiben lokal.
+- Keine Pi-Adressen, Zugangsdaten, WLAN-Schlüssel oder Gerätemodelle in
+  Skripten fest eintragen. Zielwerte kommen aus Argumenten oder werden am
+  tatsächlichen Gerät geprüft.
+
+Änderungen an Upload- und Installationsbefehlen in `UPLOAD.md` und
+`SOFTWARE.md` nachführen; Renderabläufe in den jeweiligen README-Dateien
+unter `preview/` dokumentieren.