@@ 1,146 @@
+# QMK Userspace Wiki
+
+Personal QMK firmware configurations for multiple keyboards, managed via a Nix flake for reproducible builds.
+
+## Keyboards
+
+### ZSA Voyager
+
+Split columnar keyboard with hotswap switches. Uses the [ZSA QMK fork](https://github.com/zsa/qmk_firmware).
+
+Three keymap variants:
+
+- **`pers`** -- Primary layout. Home row mods (GACS), caps word (both shifts), symbol layer, nav/media layer with RGB controls.
+- **`ball`** -- Trackball-enabled variant. Adds Navigator trackball driver with hi-res scroll, auto mouse layer, drag scroll toggle, CPI adjustment, and a numpad layer on hold-B.
+- **`mod`** -- Modifier-focused variant. Similar to `pers` but with tap dance undo (double-tap U for Ctrl+Shift+-), combo caps word (D+K), numpad on hold-E, and a transparent toggle layer for GUI+N override.
+
+All three share: QWERTY base, home row mods, symbol layer (braces/parens/operators), settings layer (RGB, nav arrows, boot), and caps word.
+
+### Keyball39
+
+39-key split keyboard with integrated trackball. Uses the [Holykeebs QMK fork](https://github.com/holykeebs/qmk_firmware).
+
+Keymap: **`init`**
+
+- QWERTY base with home row mods (Alt/Shift/Ctrl on S/D/F and J/K/L)
+- Tap dance undo on U (double-tap for Ctrl+Shift+-)
+- Combo caps word (D+K)
+- Auto mouse layer -- trackball movement activates the mouse/numpad layer
+- Scroll mode auto-enables on the nav layer, with configurable scroll divisor and snap modes (vertical/horizontal/free)
+- OLED display showing key info, ball state, and active layer
+- RGB underglow
+- Gaming layer (strips home row mods)
+- Layers: Base, Transparent, Gaming, Mouse+Numpad, Symbols, Nav/Settings
+
+### BastardKB Charybdis 4x6
+
+Split ergodox-style keyboard with integrated trackball (RP2040/Splinky). Uses the [BastardKB QMK fork](https://github.com/Bastardkb/bastardkb-qmk).
+
+Keymap: **`init`**
+
+- QWERTY base with home row mods (Alt/Shift/Ctrl on S/D/F and J/K/L)
+- Tap dance undo, combo caps word (D+K)
+- Charybdis pointer features: drag scroll (hold/toggle), sniping mode, DPI scaling
+- Auto sniping on the pointer layer
+- Optional auto pointer layer trigger on trackball movement
+- Gaming layer, numpad layer, symbol layer
+- Settings layer with Wayfire tiling shortcuts (half/full), RGB controls, DPI tuning
+- Layers: Base, Transparent, Gaming, Pointer, Symbol, Settings
+
+### Ploopyco Trackball (rev1_005 / rev1_007)
+
+Standalone trackball with 5 buttons. Uses [upstream QMK](https://github.com/qmk/qmk_firmware).
+
+Keymap: **`pers`**
+
+- Button 1 (left click), Button 3 (middle), Button 4 (back), Button 2 (right, hold for layer 1), Button 5 (forward)
+- Layer 1: drag scroll on Button 1, DPI config on Button 4
+- Inverted drag scroll direction (`PLOOPY_DRAGSCROLL_INVERT`)
+- Both rev1_005 and rev1_007 revisions share the same keymap
+
+## Common Features Across Keymaps
+
+- **Home row mods** -- Modifier keys on the home row (GACS or ACS depending on keyboard)
+- **Caps Word** -- Activated by pressing both shifts or combo (D+K); auto-deactivates on non-alpha/number keys
+- **Tap dance undo** -- Double-tap U sends Ctrl+Shift+- (editor undo)
+- **Symbol layer** -- Consistent symbol layout across all split keyboards: backtick/tilde/hash/ampersand on top row, braces/parens on right, operators distributed logically
+- **Wayfire shortcuts** -- GUI+Shift+D (half tile) and GUI+Shift+F (full tile) on nav layers
+- **GUI+N override** -- Transparent toggle layer enabling GUI+N via HR_L tap when GUI is held
+
+## Building with Nix
+
+### Prerequisites
+
+- [Nix](https://nixos.org/download) with flakes enabled
+
+### Build a single keyboard
+
+```sh
+nix build .#<keyboard-name>
+```
+
+Available targets:
+
+| Nix target | Keyboard | Keymap | QMK Fork |
+|---|---|---|---|
+| `voyager-pers` | `zsa/voyager` | `pers` | ZSA |
+| `voyager-ball` | `zsa/voyager` | `ball` | ZSA |
+| `voyager-mod` | `zsa/voyager` | `mod` | ZSA |
+| `keyball39-init` | `keyball/keyball39` | `init` | Holykeebs |
+| `charybdis-init` | `bastardkb/charybdis/4x6` | `init` | BastardKB |
+| `ploopyco-trackball-rev1_005-pers` | `ploopyco/trackball/rev1_005` | `pers` | Upstream |
+| `ploopyco-trackball-rev1_007-pers` | `ploopyco/trackball/rev1_007` | `pers` | Upstream |
+
+### Build all keyboards
+
+```sh
+nix build .#all
+```
+
+Firmware files (`.bin`, `.hex`, `.uf2`) will be in `./result/`.
+
+### Development shell
+
+```sh
+nix develop
+```
+
+Drops into a shell with all QMK toolchains (AVR + ARM), Python dependencies, and flashing utilities pre-configured.
+
+## Flashing
+
+### ZSA Voyager
+
+```sh
+nix run .#flash-voyager
+```
+
+This uses `wally-cli` to flash the `voyager-pers` firmware. To flash manually or use a different keymap, build the target and flash the `.bin` from `./result/` using [Wally](https://www.zsa.io/flash) or `wally-cli`.
+
+### Keyball39 / Charybdis (UF2)
+
+1. Build: `nix build .#keyball39-init` or `nix build .#charybdis-init`
+2. Put the keyboard into bootloader mode (double-tap reset or hold boot button)
+3. Copy the `.uf2` file from `./result/` to the USB mass storage device that appears
+
+### Ploopyco Trackball (AVR)
+
+1. Build: `nix build .#ploopyco-trackball-rev1_005-pers`
+2. Put the trackball into bootloader mode (hold button while plugging in)
+3. Flash using avrdude or copy the `.hex` file:
+ ```sh
+ avrdude -p atmega32u4 -c avr109 -P /dev/ttyACM0 -U flash:w:result/*.hex
+ ```
+
+## How the Nix Flake Works
+
+The flake manages four separate QMK firmware sources as inputs, one per fork:
+
+- **`qmk-firmware`** -- Upstream QMK (Ploopyco)
+- **`zsa-qmk-firmware`** -- ZSA fork (Voyager)
+- **`keyball-qmk-firmware`** -- Holykeebs fork (Keyball39)
+- **`bastardkb-qmk-firmware`** -- BastardKB fork (Charybdis)
+
+Each build target specifies which fork to use. The `setupUserspace` helper copies the fork's source tree, then overlays the keyboards, users, and layouts directories from this userspace repo on top. This lets custom keymaps coexist with the fork's built-in keyboard definitions.
+
+Pin updates are managed through `flake.lock` -- run `nix flake update` to pull the latest from all forks.