Commit e4be11412efe

@@ -0,0 +1,247 @@
+#+title: ZSA Moonlander QMK Config
+
+* Overview
+
+This is a custom QMK firmware configuration for the ZSA Moonlander keyboard - a split ergonomic keyboard with 72 keys, thumb clusters, and RGB backlighting.
+
+** Hardware
+
+- *Keyboard*: ZSA Moonlander
+- *MCU*: STM32 ARM Cortex
+- *Keys*: 72 keys (36 per side) with hot-swap sockets
+- *Thumb Cluster*: 6 keys per side
+- *Features*: RGB backlighting, USB-C, adjustable tenting
+
+** Firmware Features
+
+- Multiple keyboard layouts: Bépo (primary), ErgoL, QWERTY
+- Home row mods with custom timing (280ms tapping term)
+- Smart numword layer for efficient number entry
+- Extensive combos for frequently used keys and symbols
+- Key overrides for context-sensitive behavior
+- Leader key support for text macros
+- Layer lock for sustained layer access
+- Tap dance for multi-function keys
+- French accent macros using US International layout
+- Repeat key support for efficiency
+
+* Building and Flashing
+
+** Build Firmware
+
+From the =keyboards/moonlander= directory:
+
+#+begin_src bash
+./go.sh build
+#+end_src
+
+This script will:
+1. Clone QMK firmware if not present
+2. Symlink the config directory
+3. Build the firmware using QMK
+
+The compiled firmware will be in =build/qmk_firmware/.build/=.
+
+** Flash Firmware
+
+To build and flash the keyboard:
+
+#+begin_src bash
+./go.sh flash
+#+end_src
+
+This will build the firmware and enter flashing mode. Press the reset button on the keyboard when prompted.
+
+** Update QMK
+
+To update the QMK firmware submodules:
+
+#+begin_src bash
+./go.sh update
+#+end_src
+
+** Clean Build
+
+To clean build artifacts:
+
+#+begin_src bash
+./go.sh clean
+#+end_src
+
+* Keyboard Layouts
+
+** Bépo (Layer 0)
+
+Primary French-optimized layout based on [[https://bepo.fr][bépo]] with adaptations:
+- Works with US International keyboard layout on the host OS
+- Home row mods: A (GUI), U (Alt), I (Shift), E (Ctrl) on left; C (Hyper), T (Ctrl), S (Shift), R (Alt), N (GUI) on right
+- Number row with key overrides (Shift for numbers 0-9)
+- French accents via custom macros (é, è, à, ê, etc.)
+- Smart numword layer activation
+- Thumb keys for layer access and common modifiers
+
+** ErgoL (Layer 1)
+
+Alternative French layout based on [[https://ergol.org][ErgoL]] optimized for ergonomics and efficiency.
+
+** QWERTY (Layer 2)
+
+Standard QWERTY layout for compatibility and shared use, with home row mods.
+
+** Symbol Layer (Layer 3)
+
+Programming-focused symbols and special characters:
+- Brackets, braces, parentheses
+- Math operators
+- Special characters accessible via layer toggle
+
+** Number Layer (Layer 4)
+
+Dedicated numpad-style number layer with smart numword activation:
+- Calculator-style layout
+- Auto-disable after 5 seconds of inactivity
+- Quick access to numeric symbols
+
+** Navigation Layer (Layer 5)
+
+Arrow keys, page navigation, home/end, and media controls.
+
+** Mouse Layer (Layer 6)
+
+Mouse emulation for cursor control without leaving the keyboard.
+
+** Modifier Layer (Layer 7)
+
+Additional modifiers and function keys.
+
+* Configuration Details
+
+** Timing Settings
+
+- *Tapping Term*: 280ms - Time to distinguish tap from hold
+- *Quick Tap Term*: 100ms - Quick successive taps
+- *Flow Tap Term*: 150ms - For home row mod flow
+- *Combo Term*: 40ms - Time window for combo activation
+- *Numword Timeout*: 5000ms - Auto-disable numword after inactivity
+
+** Home Row Mods
+
+Home row mods are configured for both QWERTY and Bépo layouts:
+
+*Left hand (QWERTY)*: A (GUI), S (Alt), D (Shift), F (Ctrl), G (Hyper)
+*Right hand (QWERTY)*: H (Hyper), J (Ctrl), K (Shift), L (Alt), ; (GUI)
+
+*Left hand (Bépo)*: A (GUI), U (Alt), I (Shift), E (Ctrl), , (Hyper)
+*Right hand (Bépo)*: C (Hyper), T (Ctrl), S (Shift), R (Alt), N (GUI)
+
+** Combos
+
+Extensive combo system for:
+- Layer switching (Bépo, ErgoL, QWERTY)
+- Escape key
+- Special characters (|, @, #, $, /, \, &, -, _, =)
+- Brackets and parentheses
+- Leader key activation
+
+** Key Overrides
+
+Context-sensitive key behavior:
+- Shift + ^ = ! (Bépo)
+- Shift + . = : (Bépo)
+- Shift + , = ; (Bépo)
+- Shift + number row keys = numbers (Bépo)
+- RAlt + B = | (Bépo)
+- RAlt + Space = _ (Bépo)
+
+** French Accents
+
+Macros for French accented characters using US International layout:
+- é, è, ê (e with acute, grave, circumflex)
+- à, â (a with grave, circumflex)
+- ù, û (u with grave, circumflex)
+- î, ô (i, o with circumflex)
+- ë, ï (e, i with trema)
+- ç (c with cedilla)
+- € (euro symbol)
+
+All accents support both lowercase and uppercase variants.
+
+** QMK Features Enabled
+
+- *Combos*: Key combinations for special functions
+- *Key Overrides*: Context-sensitive key behavior
+- *Leader Key*: Text expansion and macros
+- *Repeat Key*: Repeat last key press
+- *Tap Dance*: Multiple functions per key
+- *Layer Lock*: Lock layers for sustained access
+
+** QMK Features Disabled
+
+- Audio
+- Caps Word
+- Auto Shift
+- Command
+- Console
+- Space Cadet
+- Most RGB matrix effects (for firmware size optimization)
+
+* Build Configuration
+
+The firmware uses custom =rules.mk= and =config.h= files:
+- Optimized for size with LTO (Link Time Optimization)
+- Custom layer modes for numword functionality
+- Chordal hold for better home row mod behavior
+
+* Usage Tips
+
+** Switching Layouts
+
+Use combos to switch between layouts:
+- Bépo: Nav (Backspace) + Shift
+- ErgoL: Num (Space) + Sym (Enter)
+- QWERTY: Delete + RAlt
+
+** Numword Layer
+
+Activate with the Space key on the Bépo layer (hold). Auto-disables after 5 seconds of inactivity.
+
+** Leader Key
+
+Access via combo (D + F on QWERTY). Example sequence:
+- Leader + F: Types "QMK is awesome."
+
+** Mouse Toggle
+
+Toggle mouse layer with Q + R combo.
+
+* Development
+
+** File Structure
+
+- =config/config.h= - Configuration constants and macros
+- =config/keymap.c= - Main keymap definition
+- =config/layermodes.c= - Custom layer mode implementations
+- =config/layermodes.h= - Layer mode headers
+- =config/rules.mk= - QMK feature toggles
+- =go.sh= - Build and flash script
+
+** Adding Custom Keycodes
+
+1. Add enum to =custom_keycodes= in =keymap.c=
+2. Implement handling in =process_record_user()=
+3. Use in keymap definition
+
+** Modifying Combos
+
+1. Add combo definition in =combos= enum
+2. Define key sequence in =PROGMEM= array
+3. Add to =combo_events[]= array
+
+* Inspirations and References
+
+- [[https://docs.qmk.fm/][QMK Documentation]]
+- [[https://configure.zsa.io/][ZSA Oryx Configurator]]
+- [[https://github.com/manna-harbour/miryoku][Miryoku layout]]
+- [[https://sunaku.github.io/home-row-mods.html][Home row mods guide]]
+- [[https://bepo.fr][Bépo keyboard layout]]
+- [[https://ergol.org][ErgoL keyboard layout]]

@@ -1,11 +1,52 @@
+.PHONY: help moonlander/build moonlander/flash moonlander/clean moonlander/update
+.PHONY: eyelash_corne/build eyelash_corne/flash corne/build corne/flash
+.PHONY: all clean
 
-.PHONY: eyelash_corne
-eyelash_corne: firmwares/eyelash_corne_left.uf2 firmwares/eyelash_corne_right.uf2
+# Default target
+help:
+	@echo "Keyboard Build Targets:"
+	@echo ""
+	@echo "Moonlander (QMK):"
+	@echo "  moonlander/build     - Build Moonlander firmware"
+	@echo "  moonlander/flash     - Build and flash Moonlander firmware"
+	@echo "  moonlander/update    - Update QMK submodules"
+	@echo "  moonlander/clean     - Clean Moonlander build artifacts"
+	@echo ""
+	@echo "Eyelash Corne (ZMK):"
+	@echo "  eyelash_corne/build  - Build Eyelash Corne firmware (aliases: corne/build)"
+	@echo "  eyelash_corne/flash  - Build and flash Eyelash Corne firmware (aliases: corne/flash)"
+	@echo ""
+	@echo "Other:"
+	@echo "  all                  - Build all keyboards"
+	@echo "  clean                - Clean all build artifacts"
 
-firmwares/eyelash_corne_left.uf2: eyelash_corne/config/* eyelash_corne/Dockerfile
-	docker build --target output_collector --output type=local,dest="firmwares" -f eyelash_corne/Dockerfile eyelash_corne
-	touch firmwares/eyelash_corne_*.uf2
+# Moonlander targets
+moonlander/build:
+	cd moonlander && ./go.sh build
 
-firmwares/eyelash_corne_right.uf2: eyelash_corne/config/* eyelash_corne/Dockerfile
-	docker build --target output_collector --output type=local,dest="firmwares" -f eyelash_corne/Dockerfile eyelash_corne
-	touch firmwares/eyelash_corne_*.uf2
+moonlander/flash:
+	cd moonlander && ./go.sh flash
+
+moonlander/update:
+	cd moonlander && ./go.sh update
+
+moonlander/clean:
+	cd moonlander && ./go.sh clean
+
+# Eyelash Corne targets
+eyelash_corne/build:
+	cd eyelash_corne && ./go.sh build
+
+eyelash_corne/flash:
+	cd eyelash_corne && ./go.sh flash
+
+# Convenient aliases for eyelash_corne
+corne/build: eyelash_corne/build
+
+corne/flash: eyelash_corne/flash
+
+# Composite targets
+all: moonlander/build eyelash_corne/build
+
+clean: moonlander/clean
+	rm -rf eyelash_corne/firmwares

@@ -1,13 +1,116 @@
-#+title: My Keyboard setup
+#+title: My Keyboard Setup
 
-This folder contains my keyboard setup, and everything required to
-build and flash them.
+This folder contains my keyboard configurations and everything required to build and flash them.
 
-Today, there is 2 keyboards:
-- ZSA Moonlander, using QMK
-- Eyelash Corne (wireless), using zmk (with some updates)
+* Keyboards
 
-* Notes
+** ZSA Moonlander
+
+QMK-based firmware for the Moonlander split ergonomic keyboard.
+- Location: =moonlander/=
+- Firmware: QMK
+- Features: 72 keys, RGB backlighting, wired USB-C
+- See [[file:moonlander/README.org][moonlander/README.org]] for details
+
+** Eyelash Corne
+
+ZMK-based firmware for the wireless Corne (crkbd) keyboard.
+- Location: =eyelash_corne/=
+- Firmware: ZMK (with custom modifications)
+- Features: 42 keys, wireless (Bluetooth), nice!view display, RGB underglow
+- See [[file:eyelash_corne/README.org][eyelash_corne/README.org]] for details
+
+* Quick Start
+
+** Building Firmware
+
+From the =keyboards/= directory, use the Makefile:
+
+#+begin_src bash
+# Build Moonlander firmware
+make moonlander/build
+
+# Build Eyelash Corne firmware
+make eyelash_corne/build
+# or use the shorter alias
+make corne/build
+#+end_src
+
+** Flashing Firmware
+
+#+begin_src bash
+# Flash Moonlander (wired)
+make moonlander/flash
+
+# Flash Eyelash Corne (wireless)
+make eyelash_corne/flash
+# or use the shorter alias
+make corne/flash
+#+end_src
+
+** Other Targets
+
+#+begin_src bash
+# Build all keyboards
+make all
+
+# Update QMK (Moonlander only)
+make moonlander/update
+
+# Clean build artifacts
+make clean
+make moonlander/clean
+
+# Show help
+make help
+#+end_src
+
+** From Repository Root
+
+All keyboard targets are also available from the repository root Makefile:
+
+#+begin_src bash
+cd /path/to/home
+make moonlander/build
+make eyelash_corne/flash
+#+end_src
+
+* Common Layouts
+
+Both keyboards share similar layout philosophies:
+
+** Primary Layout: Bépo
+
+French-optimized layout based on [[https://bepo.fr][bépo]] with adaptations for split ergonomic keyboards.
+- Works with US International layout on the host OS
+- Home row mods for modifiers
+- Layer-based access to symbols, numbers, and navigation
+
+** Alternative Layouts
+
+- *ErgoL*: Alternative French layout based on [[https://ergol.org][ErgoL]]
+- *QWERTY*: Standard layout for compatibility
+
+** Shared Features
+
+- Home row mods (GUI, Alt, Shift, Ctrl, Hyper)
+- Smart numword layer for efficient number entry
+- Combos for frequently used keys
+- French accent support via macros/Unicode
+- Multiple layers: Base, Symbols, Numbers, Navigation, Function
+
+* Configuration Philosophy
+
+- Minimize finger movement with home row mods
+- Layer-based approach for symbols and numbers
+- French language support as first-class citizen
+- Optimized for programming and text editing
+- Wireless option (Corne) and wired option (Moonlander) for different use cases
+
+* Additional Resources
+
+- [[file:moonlander/README.org][Moonlander detailed documentation]]
+- [[file:eyelash_corne/README.org][Eyelash Corne detailed documentation]]
+- [[https://docs.qmk.fm/][QMK Firmware Documentation]]
+- [[https://zmk.dev/][ZMK Firmware Documentation]]
 
-- Clone =zmk=: https://github.com/zmkfirmware/zmk
-- Clone =new_corne=: https://github.com/krisalcordo/zmk-new_corne 

@@ -70,6 +70,37 @@ fmt:
 dots:
 	@$(MAKE) -C dots
 
+# Keyboards
+.PHONY: keyboards moonlander/build moonlander/flash moonlander/update moonlander/clean
+.PHONY: eyelash_corne/build eyelash_corne/flash corne/build corne/flash
+
+moonlander/build:
+	@$(MAKE) -C keyboards moonlander/build
+
+moonlander/flash:
+	@$(MAKE) -C keyboards moonlander/flash
+
+moonlander/update:
+	@$(MAKE) -C keyboards moonlander/update
+
+moonlander/clean:
+	@$(MAKE) -C keyboards moonlander/clean
+
+eyelash_corne/build:
+	@$(MAKE) -C keyboards eyelash_corne/build
+
+eyelash_corne/flash:
+	@$(MAKE) -C keyboards eyelash_corne/flash
+
+corne/build:
+	@$(MAKE) -C keyboards corne/build
+
+corne/flash:
+	@$(MAKE) -C keyboards corne/flash
+
+keyboards:
+	@$(MAKE) -C keyboards help
+
 # Maintenance
 .PHONY: clean
 clean: clean-system clean-results

@@ -83,19 +83,29 @@
 - Tekton development environment
 
 ** =/keyboards=
-Hardware keyboard configurations:
+Hardware keyboard configurations with complete build and flash tooling.
 
-*** Corne Keyboard (Eyelash Corne)
-Located in =/keyboards/keyboards/eyelash_corne=:
-- ZMK-based configuration for the Corne keyboard
+See [[file:keyboards/README.org][keyboards/README.org]] for detailed keyboard documentation and usage.
 
 *** Moonlander
-Located in =/keyboards/keyboards/zsa/moonlander=:
+Located in =/keyboards/moonlander=:
 - QMK-based configuration for the ZSA Moonlander keyboard
+- 72-key split ergonomic keyboard with RGB backlighting
+- Wired USB-C connectivity
+- See [[file:keyboards/moonlander/README.org][keyboards/moonlander/README.org]] for full documentation
+
+*** Eyelash Corne
+Located in =/keyboards/eyelash_corne=:
+- ZMK-based configuration for the wireless Corne (crkbd) keyboard
+- 42-key split ergonomic keyboard with nice!view display
+- Wireless Bluetooth connectivity with nice!nano v2
+- RGB underglow and custom animations
+- See [[file:keyboards/eyelash_corne/README.org][keyboards/eyelash_corne/README.org]] for full documentation
 
 *** Kanata (software)
 Located in =systems/kyushu/main.kbd=:
-- Software keyboard remapper configuration, to mimic the mechanic keyboards
+- Software keyboard remapper configuration to mimic mechanical keyboards
+- System-level key remapping for non-keyboard hardware
 
 * Usage
 
@@ -148,6 +158,18 @@
 - =make fmt= - Format Nix files using nixpkgs-fmt
 - =make pre-commit= - Run pre-commit checks
 
+*** Keyboards
+- =make moonlander/build= - Build Moonlander QMK firmware
+- =make moonlander/flash= - Build and flash Moonlander firmware
+- =make moonlander/update= - Update QMK submodules
+- =make moonlander/clean= - Clean Moonlander build artifacts
+- =make eyelash_corne/build= - Build Eyelash Corne ZMK firmware
+- =make eyelash_corne/flash= - Build and flash Eyelash Corne firmware
+- =make corne/build= - Alias for eyelash_corne/build
+- =make corne/flash= - Alias for eyelash_corne/flash
+
+See [[file:keyboards/README.org][keyboards/README.org]] for detailed keyboard documentation.
+
 *** Maintenance
 - =make clean= - Clean up old system generations and results
 - =make clean-system= - Remove system generations older than 15 days