docs: project documentation — architecture, getting-started, packs, mcp, regtest

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/moonlander.md

@@ -0,0 +1,54 @@
+# Flashing the ZSA Moonlander
+
+How to flash firmware to the ZSA Moonlander Mark I on bohm.
+
+## What's wired into the config
+
+Two pieces, both committed:
+
+- `configuration.nix` → `hardware.keyboard.zsa.enable = true;` — installs
+  ZSA's udev rules. Required so the keyboard is reachable for flashing and
+  for Oryx in-browser live-training **without root**.
+- `home.nix` → `keymapp` in `home.packages` — ZSA's official flashing GUI.
+
+After editing those you must `omni-rebuild switch` (a system switch, not
+just home-manager — the udev rules live at the NixOS layer).
+
+> **Gotcha:** after the rebuild that first enables the udev rules, **unplug
+> and replug** the keyboard so the new rules bind to the device. Otherwise
+> Keymapp won't see it.
+
+## Flashing flow (normal path)
+
+The Moonlander runs **QMK**. You don't compile anything locally for the
+normal path — ZSA's Oryx configurator produces the firmware.
+
+1. Build/edit your layout in **Oryx** (https://configure.zsa.io) and
+   download the firmware `.bin`.
+2. Launch `keymapp`.
+3. Press the small **reset button** on the keyboard (top-left, reachable
+   with the included tool or a paperclip).
+4. Flash the `.bin` from Keymapp.
+
+## CLI alternative
+
+`wally-cli` (nixpkgs attribute `wally-cli`, **not** `wally` — that's a
+Roblox package manager) flashes from the terminal:
+
+```bash
+nix-shell -p wally-cli --run 'wally-cli firmware.bin'
+```
+
+Same reset-button step applies. Add `wally-cli` to `home.packages` if you
+want it permanently.
+
+## Troubleshooting
+
+- **Keyboard not detected** — confirm the rebuild applied
+  (`hardware.keyboard.zsa.enable`), then unplug/replug. Check the device
+  shows up: `lsusb | grep -i zsa` (or look for `3297:` vendor id).
+- **Permission denied on flash** — udev rules aren't active for this
+  plug-in; replug, or `sudo udevadm control --reload && sudo udevadm
+  trigger`.
+- **Reset button does nothing** — it's recessed; use the keycap-puller
+  tool ZSA ships, or a straightened paperclip.