# AGENTS.md — TOTEM ZMK Config

## Build

Local Docker build (no GitHub Actions needed):

```bash
docker run --rm \
  -v $(pwd):/workspace/zmk-config \
  -w /workspace/zmk-config \
  zmkfirmware/zmk-build-arm:stable \
  bash -c "
    git config --global --add safe.directory '*'
    west zephyr-export
    west build -s zmk/app -d build/left  -b xiao_ble -- -DSHIELD=totem_left  -DZMK_CONFIG=/workspace/zmk-config/config
    west build -s zmk/app -d build/right -b xiao_ble -- -DSHIELD=totem_right -DZMK_CONFIG=/workspace/zmk-config/config
  "

cp build/left/zephyr/zmk.uf2  totem_left.uf2
cp build/right/zephyr/zmk.uf2 totem_right.uf2
```

- Clean build dirs between config changes: `rm -rf build/left build/right`
- The Docker image `zmkfirmware/zmk-build-arm:stable` must be pulled first (~3 GB)
- Board name is `xiao_ble` (not `seeeduino_xiao_ble` — that was the old name)
- `west update` only needed when ZMK/Zephyr deps change (pulls submodules)
- `CONFIG_ZMK_BLE=y` is explicitly set in `config/totem.conf` (board defconfig alone proved unreliable)

## Keymap

The active keymap is `config/totem.keymap`. It overrides the shield default at `config/boards/shields/totem/totem.keymap`.

3 layers: `BASE` (0), `UML` (1), `BT` (2).

## BINDINGS.md

**After every binding change** in `config/totem.keymap`, update `BINDINGS.md` with an ASCII graphic of all three layers and the quick-reference table. The physical key labels in the ASCII art must match the BASE layer positions exactly.