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

@ -156,10 +156,22 @@ rechts im Fenster, oder direkt in `versapad_mcp_server.py`.
werden; `--onedir` (statt `--onefile`) verringert das Risiko, verhindert
es aber nicht
## Dokumentation
Ausführlichere technische Doku im [`docs/`](docs/)-Ordner:
- [`docs/architecture.md`](docs/architecture.md) — Schichtenmodell,
Prozessmodell, Modi, Config-Speicherort, Nebenläufigkeit
- [`docs/data-model.md`](docs/data-model.md) — JSON-Formate (kombiniert +
Legacy), binäres NVM-Layout, Geometrie, Enums
- [`docs/protocol.md`](docs/protocol.md) — Serial-Wire-Protokoll (Befehle,
Events, Paketformat, CRC16)
## Weiterentwicklung
Tiefere technische Notizen (Protokoll-Details, bekannte Stolpersteine beim
Bauen, Design-Entscheidungen) stehen in [`AGENTS.md`](AGENTS.md).
Agentenseitige Notizen (Domänenregeln, bekannte Bugs und ihre Fixes,
Implementierungsdisziplin, Design-Entscheidungen) stehen in
[`AGENTS.md`](AGENTS.md).
## Lizenz / Herkunft