Halloween/AGENTS.md

# Halloween – Projektregeln

## Ziel und aktueller Auftrag

Interaktives atmendes Grab für Halloween im Vorgarten der Schwester bauen.
Gewünscht sind ein kräftiger Schreckeffekt, Kamera, Weboberfläche und lokal
gespeicherte Bilder/Videoclips. Der Nutzer hat nun eine erste Pi-Software mit
Liveansicht und simuliertem Effektablauf beauftragt; das allgemeine
Uploadskript und die Blender-Konzeptvorschau wurden ebenfalls freigegeben.
Hardwarebau und Anschluss echter Aktoren folgen nach Klärung der Mechanik,
Versorgung und Sicherheit im Plan.

## Arbeitsweise

- 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.
- Klein anfangen: einen vollständigen Effektablauf zuverlässig umsetzen,
  anschließend zusätzliche Effekte ergänzen.
- Dokumentation übersichtlich halten; diese Datei unter 400 Zeilen halten.
- Im lokalen Git Code, Planung und bearbeitbare Blender-Szenen versionieren;
  Renderdateien, Referenzclip, `.venv` und `data/` bleiben unversioniert.

## Hardware und Architektur

- Vorhanden laut Nutzer: Raspberry Pis 3–5; Pi 5 auf Nutzerfoto bestätigt,
  RAM vermutlich 8 GB laut Nutzer, noch nicht am Gerät geprüft;
  außerdem „2mini“ (genaue Geräte unbekannt), Camera Module 3 NoIR
  (Beschriftung auf Nutzerfoto bestätigt), eventuell Display,
  LEDs, Servos und Lötwerkzeug. Weitere Teile dürfen vorgeschlagen werden.
- Vorgeschlagene Aufteilung: Pi 5 für Kamera/WebUI/Ereignisse und Pi 3/4
  für Effektsteuerung. Noch keine verbindliche Hardwareentscheidung.
- Für die NoIR-Kamera IR-Beleuchtung bei Dunkelheit und ein passendes
  Standard-auf-Mini-Kamerakabel für Pi 5 einplanen; vorhandenes Kabel prüfen.
- GPIOs steuern geeignete Treiber; Motoren, Servos und größere LED-Lasten
  erhalten eine passend dimensionierte Versorgung.
- Mechanik erst nach Klärung von Abmessungen, Gewicht, Hub und Bewegungsraum
  auswählen. Atembewegung und kurzer Schreckimpuls getrennt bewerten.

## Betriebsregeln

- Bewegung bleibt im Grab und außerhalb des Besucherwegs; Quetschstellen
  abdecken. Leichte bewegte Bauteile und mechanische Anschläge vorsehen.
- Elektronik für Außeneinsatz geschützt planen; Kleinspannung am Grab,
  Zugentlastung und geeignete Stromversorgung vorsehen.
- Bei Start, Verbindungsverlust oder Fehler keine neue Schrecksequenz
  auslösen; definierte sichere Zustände und lokalen Stopp vorsehen.
- Sperrzeit und belegten Auslösebereich berücksichtigen.
- Kinder-/Sanftmodus anbieten. Kamerabasierte Größenhinweise sind unsicher
  und dürfen nicht als zuverlässige Altersbestimmung gelten.
- Nutzerwunsch: „voller Schreck“ ist der anfängliche Standard und wird nach
  neuem gültigem Trigger automatisch ausgelöst, ohne Einzelfreigabe.
  Modi sind in der WebUI umstellbar; eine gewählte Einstellung soll einen
  normalen Neustart überdauern. Nach Start erst freien Auslösebereich
  abwarten; nach Stopp oder Fehler bewusst zurücksetzen. Kamerahinweise
  gelten nicht als verlässliche Altersentscheidung; automatische Reaktion
  auf Hinweise zu kleinen Besuchern vor Implementierung abstimmen.

## Kamera, Aufnahmen und Zugriff

- Personen als Ereignisse erkennen, ohne Identitäten zu bestimmen.
- Keine Gesichtserkennung oder automatische Wiedererkennung konkreter
  Personen über getrennte Videos hinweg implementieren.
- Clips mit Zeit, Vorschaubild und Ereignistyp zum manuellen Prüfen anbieten.
- Aufnahmebereich auf den vorgesehenen privaten Bereich begrenzen;
  Maskierung, Aufbewahrung und Löschfrist vor Umsetzung festlegen.
- Tonwiedergabe und Tonaufnahme unterscheiden; Tonaufnahme standardmäßig aus.
- WebUI zunächst nur im lokalen Netz; keine öffentliche Freigabe ohne
  ausdrücklichen Auftrag. Zugangsschutz einplanen.

## Erste Softwareversion

- `run.py` startet die FastAPI-WebUI nur auf `127.0.0.1`; Laptop-Zugriff
  erfolgt per SSH-Tunnel. `--demo` kennzeichnet ein synthetisches Bild.
- Picamera2 liefert das MJPEG-Livebild; auf dem Entwicklungsrechner wurde
  nur der Demo-Feed geprüft, nicht die echte Pi-Kamera.
- Moduswahl und simulierte Sequenz sind implementiert. GPIO, automatische
  Personenauslösung und Clip-Speicherung sind noch offen.
- Laufzeitdaten unter `data/` nicht mit dem Uploadskript überschreiben.
- Optionaler systemd-Autostart der WebUI wird mit `--install-service` beim
  Upload eingerichtet; auf einem echten Pi noch nicht geprüft.

## Prüfung

- Softwareprüfungen, Hardwaretests und Außentests getrennt berichten.
- Erst ohne angeschlossene Aktoren simulieren, dann einzelne Aktoren testen,
  anschließend Gesamtablauf und Fehlerfälle prüfen.
- Kamera bei tatsächlicher Dunkelheit, Beleuchtung und Verkleidungen testen.
- Sicheren Zustand bei Netzwerkausfall, Neustart und Stopp verifizieren.
- Dokumentationsänderungen erfordern keine zusätzlichen Softwaretests.