Add architecture/data-model/protocol reference docs

Human-facing reference documentation, split from AGENTS.md's agent-facing
domain rules and bug history (which stays there, not duplicated here):

- docs/architecture.md: layer diagram, module responsibilities, config
  storage location, the three GUI modes, and the port-exclusivity /
  multi-process caveats around concurrent access
- docs/data-model.md: the combined and legacy JSON formats, the binary
  SDeviceConfig/SDeviceProfile/SMacroTable NVM layout byte-for-byte, action
  types, LED fields, macro-slot conventions, button grid geometry
- docs/protocol.md: the 8-byte serial packet format, command/event tables,
  the read/write/status-poll flows, connection lifecycle, and error states

README.md now links to all three from a new "Dokumentation" section, and
AGENTS.md's outdated "docs/ tree isn't warranted yet" note is removed now
that it exists on explicit user request.
This commit is contained in:
Julian Appel 2026-08-14 23:19:13 +02:00
parent 7d40fdaa60
commit 83429363c1
5 changed files with 550 additions and 11 deletions

View file

@ -242,8 +242,6 @@ selbst vorgegeben (`SAction.data`), dort beibehalten statt umzubenennen.
## Deferred Work
- Volle `docs/`-Baumstruktur (siehe Dokumentation und Verifikation unten —
Projektgröße rechtfertigt das aktuell nicht, kein DB-/API-Dienst)
- Board-seitiges Umschalten des aktiven Profils per Button in der GUI —
explizit vom User abgelehnt ("lass uns weg"), Live-Sync bleibt read-only
- Profilnamen aufs Board schreiben — technisch unmöglich (kein Platz im
@ -262,13 +260,16 @@ Nicht an diesen Punkten arbeiten, ohne dass der User es explizit anfragt.
- `README.md` ist der Einstiegspunkt (Installation, Nutzung, Architektur-
Überblick).
- `AGENTS.md` (diese Datei) ist die agentenseitige Quelle der Wahrheit für
Domänenregeln und Architekturgrenzen — jede Session aktualisieren, die
daran etwas ändert oder etwas Wichtiges lernt.
- Größeneinschätzung nach Projekt-Dokumentationsstandard: kleines/mittleres
Tool ohne eigene Datenbank und ohne persistenten API-Dienst (der
Browser-Server ist ein einfacher lokaler Lese-Viewer, kein
Mehrbenutzer-Backend) → `README.md` + `AGENTS.md` sind Pflicht und
vorhanden, ein voller `docs/`-Baum ist nicht angemessen.
Domänenregeln, Architekturgrenzen und Bug-Historie — jede Session
aktualisieren, die daran etwas ändert oder etwas Wichtiges lernt.
- `docs/` (seit 2026-08-14, auf expliziten User-Wunsch) enthält die
menschenlesbare Referenzdoku: `architecture.md` (Schichten, Prozess-/
Nebenläufigkeitsmodell, Config-Speicherort), `data-model.md` (JSON-
Formate, binäres NVM-Layout, Geometrie, Enums), `protocol.md`
(Serial-Wire-Protokoll). Bug-Historie/Domänenregeln bleiben bewusst nur
in `AGENTS.md`, nicht dupliziert in `docs/`. Bei Änderungen am
Binärformat/Protokoll/Datenmodell `docs/data-model.md` bzw.
`docs/protocol.md` mitpflegen.
Prüfungen vor einem Commit an Binärformat/Protokoll:
```bash