Add user-facing README (install, usage, architecture overview)

AGENTS.md is agent-facing session notes, not a proper intro for
someone landing on the repo cold. README covers: what this is,
requirements, how to run from source or build the .exe (and why no
prebuilt .exe is committed -- network-drive build/runtime gotchas),
file overview, MCP server usage, known limitations.

README.md

@@ -0,0 +1,131 @@
+# VersaPad Viewer
+
+Ein eigenständiges Tool für das [VersaPad](https://git.jappel.io/jappel/VersaMCU)-Makropad
+(4×5-Button-Grid + 4 Encoder, SAMD21-Firmware von jappel). Zeigt die aktuelle
+Belegung an, kann sie live mit dem Board synchronisieren und komplett neu
+programmieren — als Ergänzung zur offiziellen [VersaGUI](https://git.jappel.io/jappel/VersaGUI)
+(C#/.NET), nicht als Ersatz.
+
+## Features
+
+- **Steuermatrix-Anzeige** — 4×5-Button-Grid + 4 Encoder, farbige LED-Vorschau,
+  lesbare Beschriftung (z.B. "Strg+S" statt Rohwerten)
+- **Zwei Anzeige-Wege:** Browser (`server.py`, `localhost:8765`) oder natives
+  Desktop-Fenster (`desktop_viewer.py`, Tkinter)
+- **Live-Sync** — pollt per Serial, welches Profil gerade am Board aktiv ist,
+  und schaltet die Ansicht automatisch mit
+- **Programmiermodus** — Zellen anklicken und bearbeiten (Taste, Medientaste,
+  Makro, Profilwechsel, LED-Farbe/Animation), direkt aufs Board schreiben
+  oder als Datei speichern
+- **Makro-Editor** — bis zu 8 Schritte pro Slot, liest/schreibt die echte
+  Makro-Tabelle vom Board
+- **MCP-Server** — lässt eine KI (Claude o.ä.) die Belegung direkt per
+  Tool-Aufruf ändern, ohne Klicks in der GUI (siehe unten)
+- **Tray-Icon** — minimiert/schließt ins Tray statt in die Taskleiste, wie
+  die offizielle VersaGUI
+
+## Voraussetzungen
+
+- Python 3.11 oder neuer
+- Pakete: `pyserial` (Board-Kommunikation), `pystray` + `pillow`
+  (Tray-Icon/Desktop-App), optional `mcp` (nur für den MCP-Server)
+
+```bash
+pip install pyserial pystray pillow mcp
+```
+
+Für den Browser-Modus (`server.py`) reicht die Python-Standardbibliothek —
+keine zusätzlichen Pakete nötig.
+
+## Starten
+
+**Aus dem Quellcode:**
+
+```bash
+py server.py            # Browser-Ansicht: http://127.0.0.1:8765
+py desktop_viewer.py     # natives Fenster (Konsole sichtbar, zum Debuggen)
+pyw desktop_viewer.py    # natives Fenster ohne Konsolenfenster
+```
+
+**Als eigenständige `.exe` (Windows):** Es liegt keine fertige `.exe` im
+Repo (Build-Artefakte sind bewusst nicht eingecheckt — sie sind groß und pro
+Maschine/Python-Version unterschiedlich). Selbst bauen:
+
+```powershell
+.\build_and_deploy.ps1
+```
+
+Das Skript baut mit PyInstaller (`--onedir --windowed`, eigenes Icon) und
+kopiert das Ergebnis nach `%LOCALAPPDATA%\VersaPadViewer\VersaPadViewer.exe`.
+**Wichtig:** Sowohl Bauen als auch Ausführen müssen auf einem lokalen
+Laufwerk passieren — von einem Netzlaufwerk (SMB-Share) aus scheitert
+PyInstaller beim Bauen (Pfadlängen-Problem mit Tcl/Tk-Zeitzonendaten) und
+die fertige `.exe` startet zur Laufzeit gar nicht erst (Windows blockiert
+das Nachladen der Bundle-DLLs von einem Netzwerkpfad, ohne jede
+Fehlermeldung). `build_and_deploy.ps1` kopiert den Quellcode deshalb
+automatisch zuerst nach `%TEMP%` und baut nur dort.
+
+Voraussetzung: `pip install pyinstaller` zusätzlich zu den obigen Paketen.
+
+## Aufbau
+
+| Datei | Zweck |
+|---|---|
+| `versapad_data.py` | Decoding für die Anzeige: JSON laden, HID-Keycodes/Consumer-IDs/Modifier → lesbarer Text |
+| `versapad_protocol.py` | Binäres NVM-Layout des Boards (740B Config + 512B Makros), CRC16 — pack/unpack |
+| `versapad_serial.py` | Serial-Client: liest/schreibt Config + Makros per 8-Byte-Paket-Protokoll |
+| `versapad_combined.py` | Ein-Datei-Format für alle 3 Profile + Makros + lokale Profilnamen |
+| `server.py` | Browser-Frontend (nur lesend) |
+| `desktop_viewer.py` | Tkinter-Frontend (lesend, Live-Sync, Programmiermodus, Tray) |
+| `action_dialog.py` | Bearbeiten-Dialoge für den Programmiermodus |
+| `versapad_mcp_server.py` | MCP-Server für KI-Tool-Aufrufe |
+
+Das Binärformat (`versapad_protocol.py`) ist 1:1 aus den
+VersaMCU-Firmware-Quellen übernommen und gegen ein echtes Board validiert
+(Read → unpack → pack ist bytegenau identisch zum Original, inklusive CRC).
+
+Config-Dateien liegen standardmäßig auf dem Desktop
+(`versapad_config1/2/3.json` für den reinen Lesemodus,
+`versapad_config_all.json` für den Programmiermodus — Pfade sind aktuell
+hartkodiert für eine bestimmte Windows-Maschine, siehe `CONFIG_PATHS` in
+`versapad_data.py` bzw. `DEFAULT_PATH` in `versapad_combined.py`).
+
+## MCP-Server
+
+`versapad_mcp_server.py` macht die Config per Tool-Aufruf statt Hand-JSON
+programmierbar — nutzbar von jeder MCP-fähigen KI-Anwendung (Claude Code,
+Claude Desktop, andere). In der MCP-Server-Liste der jeweiligen Anwendung
+eintragen: Kommando `python`/`py`, Argument der Pfad zu
+`versapad_mcp_server.py`.
+
+Werkzeuge (Auszug): `list_profiles`, `get_profile`, `get_macro`,
+`get_board_status` (lesen) · `set_button_key`/`_consumer`/`_macro`/
+`_profile_switch`/`_none`/`_led`, dieselben `set_encoder_*`, `set_macro`,
+`rename_profile` (bearbeiten) · `save_local`/`load_local` (Datei),
+`load_from_board`/`write_to_board` (Board). `set_*`-Aufrufe ändern nur
+einen In-Memory-Zustand — erst `save_local()` oder `write_to_board()` macht
+die Änderung dauerhaft. Volle Liste mit Details: Info-Button (ⓘ) oben
+rechts im Fenster, oder direkt in `versapad_mcp_server.py`.
+
+## Bekannte Einschränkungen
+
+- Der COM-Port ist exklusiv — Live-Sync/Programmiermodus können nicht
+  gleichzeitig mit der offiziellen VersaGUI laufen (die läuft dauerhaft als
+  Tray-App weiter, auch wenn nur ihr Konfigurationsfenster geschlossen wird
+  — für Parallelbetrieb muss sie über ihr Tray-Menü beendet werden)
+- HID-Tasten-Auswahl im Programmiermodus ist ein Dropdown, kein
+  Tastendruck-Capture (bewusst, um keinen WinAPI-Hook zu brauchen)
+- Zeichentasten-Labels zeigen eine US-Layout-Näherung, nicht das tatsächlich
+  aktive Tastatur-Layout
+- Unsignierte `.exe` — kann von Antivirus/Smart App Control blockiert
+  werden; `--onedir` (statt `--onefile`) verringert das Risiko, verhindert
+  es aber nicht
+
+## Weiterentwicklung
+
+Tiefere technische Notizen (Protokoll-Details, bekannte Stolpersteine beim
+Bauen, Design-Entscheidungen) stehen in [`AGENTS.md`](AGENTS.md).
+
+## Lizenz / Herkunft
+
+Eigenständiges Begleit-Tool, kein Teil der offiziellen VersaGUI/VersaMCU-Repos.