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.
Lets Claude Code offer the "versapad" MCP server automatically when this
project is opened, instead of requiring a manual `claude mcp add -s user`
per machine. Note: the script path is currently absolute (this machine's
checkout location) rather than relative -- .mcp.json doesn't reliably
support workspace-relative variables across Claude Code environments, so
this only works as-is on this specific checkout path for now.
Double-click-to-rename already existed but silently no-op'd unless
Programmiermodus was on, and even there it only updated the in-memory
self.combined without saving -- the name was lost unless some later button
edit happened to trigger an autosave. Since profile_names lives purely in
the combined JSON and never touches the board, there's no reason to gate it
behind the heavier editing mode: it now works from any mode, loading/saving
the combined file directly (auto-creating it if needed) when not already in
an active Programmiermodus session, and always persists immediately.
versapad_combined.DEFAULT_PATH was hardcoded to this one machine's OneDrive
desktop, which made the tool unusable anywhere else. versapad_data.app_dir()
now resolves to the running .exe's own folder when frozen, or the project
directory when run from source, and DEFAULT_PATH hangs off that instead.
load_or_fetch() previously raised when both the file was missing and the
board unreachable, blocking a fresh install with no config and no board
attached. It now falls back to an empty default_combined() in that case, so
the tool is immediately usable either way. desktop_viewer's
_current_profile_view() picks up the same fallback instead of re-implementing
a narrower version of it.
Also drop the hardcoded PROFILE_NAMES dict, which had drifted out of sync
with the profile_names already stored in the combined JSON -- renaming a
profile in Programmiermodus never showed up in the read-only/browser views.
server.py and desktop_viewer.py now read names from the same JSON everywhere.
versapad_data.CONFIG_PATHS (read-only interop with the official C# VersaGUI's
JSON export) is intentionally left on the OneDrive desktop -- nothing in
this codebase writes there, it's not part of this tool's own config.
pip install of pyinstaller/pystray/pillow was a separate manual step the
README only mentioned in prose, so the script silently died on missing
packages -- especially bad on Explorer double-click, where the window
closes before any error is visible. Consolidate all dependencies into
requirements.txt (also used by README's plain "pip install -r" flow), have
the script install it itself, wrap the whole build in try/catch with
exit-code checks after every native call, and pause on both success and
failure unless -NoPause is passed.
Also move the build output from %LOCALAPPDATA% into dist/ next to the
script, so it's easy to find and matches the already-gitignored dist/ entry.
AGENTS.md now follows the mandated section structure (Project Goal,
Aktuell unterstützte Architektur, Kritische Domänenregeln,
Existing-Codebase-Regel, Implementierungsdisziplin, Naming, Deferred
Work, Dokumentation und Verifikation) instead of an organically grown
set of headings. Folds in all prior technical notes (protocol
validation, network-drive build/runtime gotchas, threading rules)
under the appropriate section, and fixes a stale "no tray icon yet"
line that no longer matched the code. README gets an explicit honest
status paragraph (what's tested, what's not: no automated tests, no
prebuilt exe download, hardcoded paths).
No docs/ tree: project has no database or persistent multi-user
service, so the full doc structure isn't warranted per the standard.
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.
