# Arbeitsanweisungen für Coding-Agents

Diese Datei gilt für das gesamte VersaGUI-Repository.

## Ziel und Nachbar-Repository

VersaGUI ist die Windows-/WinForms-Konfigurationsanwendung für VersaPad v2.
Sie läuft auf .NET 7 und kommuniziert über feste 8-Byte-CDC-Pakete mit der
Firmware im benachbarten, eigenständigen Repository `../VersaMCU`.

`DelphiGUI` gehört nicht zum gepflegten Scope und darf bei Änderungen nicht
als Referenz oder Ziel verwendet werden.

## Vor Änderungen lesen

1. `README.md`
2. `doc/INDEX.md`
3. `doc/00_architecture.md`
4. `doc/07_known_limitations.md`
5. bei Protokoll-/Layoutänderungen zusätzlich:
   - `src/Protocol.cs`
   - `src/DeviceConfig.cs`
   - `../VersaMCU/AGENTS.md`
   - `../VersaMCU/doc/06_nvm_config.md`
   - `../VersaMCU/doc/07_serial_protocol.md`

## Gemeinsame Binärverträge

- `DeviceConfig` muss exakt `SDeviceConfig` entsprechen: Config v3, 740 Byte.
- `MacroTable` muss exakt `SMacroTable` entsprechen: 512 Byte.
- Enum-Werte, Packing, Offsets, CRC-Bereich, Chunkgrößen und USB-IDs sind
  gemeinsame Verträge mit VersaMCU.
- Änderungen daran in beiden Repositories implementieren, dokumentieren,
  bauen und getrennt committen.
- Host-Command-IDs niemals ungeprüft als Shellkommando ausführen. Eine spätere
  Host-Aktionsfunktion benötigt ein explizites sicheres Mapping.
- Das Binärmodell akzeptiert alle Firmware-Animationen `0..6`; der aktuelle
  `ActionDialog` bietet davon nur Static, Blink, Pulse und ColorCycle an.
  Bestehende, im Dialog nicht angebotene Werte nicht stillschweigend
  überschreiben.

## Threading und Transfers

- WinForms-Controls ausschließlich auf dem UI-Thread anfassen.
- `SerialManager.ReadLoop()` läuft im Hintergrund und postet Events über den
  `SynchronizationContext`.
- SerialPort-Pakete müssen unter dem Write-Lock vollständig geschrieben werden.
- Config-/Makrotransfers nicht parallel ausführen.
- Dumps und Uploads nur akzeptieren, wenn Chunkzahl, Indizes und
  Vollständigkeit stimmen.
- DTR muss vor `SerialPort.Open()` aktiviert sein.

## Verifikation

Mindestens:

```bash
dotnet build src/VersaGUI.csproj --no-restore
dotnet run --project tests/VersaGUI.ContractTests/VersaGUI.ContractTests.csproj
git diff --check
```

Bei gemeinsamen Vertragsänderungen zusätzlich:

```bash
pio run -d ../VersaMCU -e versapad
```

Die Contract-Tests prüfen Config-/Makrogrößen, CRC, Feldvalidierung,
Chunkvollständigkeit und Host-Command-Payloads. Sie ersetzen keinen Test mit
angeschlossenem Board.