# AGENTS.md

## Code style

- **Linux kernel style**, enforced by `.clang-format` (8-wide tabs, 80 columns).
  Pinned to **clang-format 18** — other versions reformat differently and CI
  will reject them.
- **No long trailing comments.** clang-format can't relocate a trailing `//`
  comment, so a long one either splits the statement or runs past 80 columns.
  Instead put the comment on its own line(s) **above** the statement, with a
  blank line before it for separation:

  ```c
  // why this value matters, at whatever length you need
  static int g_foo = 0;
  ```

  not

  ```c
  static int g_foo = 0; // why this value matters, at whatever length ...
  ```

  Short trailing comments that fit within 80 columns are fine.

## Before pushing

```sh
make format   # auto-format (kernel style)
make check    # what CI gates on: format-check + trailing-comment lint
```

CI rejects a PR immediately if either fails. The lint lives in
`tools/check-trailing-comments.py`.

## Build / compile-check (no hardware needed)

```sh
arduino-cli compile -b adafruit:nrf52:feather52840 \
  --build-property "build.extra_flags=-DNRF52840_XXAA {build.flags.usb} -DCFG_TUD_HID=4" \
  OpenPuck
```

`OpenPuck/git_version.h` is generated by `gen_version.sh` and gitignored —
never commit it.