# AGENTS.md

## Project Overview

`stk` is a C23 library for reading EdgeTx radio joystick input via
HID. Wired for TDD using Unity and CMock.

## Build System

- **Generator:** Ninja
- **CMake minimum:** 3.21
- **C standard:** C23

### Commands

Configure (default):
```sh
cmake -S . -B build -G Ninja
```

Configure with coverage:
```sh
cmake -S . -B build-cov -G Ninja -DENABLE_COVERAGE=ON
```

Build:
```sh
ninja -C build
```

Run tests (full Unity output, colored):
```sh
ninja -C build check
```

Run tests (CTest summary only):
```sh
ninja -C build test
```

Run tests and generate coverage HTML:
```sh
ninja -C build-cov coverage
```

Run (Linux/macOS):
```sh
./build/main
```

Run (Windows):
```sh
./build/main.exe
```

### Dependencies

Dependencies are managed via custom `Find*.cmake` scripts in `deps/`.
These scripts use `FetchContent` under the hood to download and build
libraries automatically.

To add a new dependency:

1. Add the corresponding `Find<name>.cmake` to `deps/`
2. Add `find_package(<name> REQUIRED)` to `CMakeLists.txt`
3. Link with `<name>::<name>` in `target_link_libraries()`

### CMake Module Path

`deps/` is added to `CMAKE_MODULE_PATH` so `find_package()` resolves
to the custom scripts instead of system-installed packages.

## Coding Conventions

- **Language:** C23
- **4-space indentation**
- **Naming:** `snake_case` for variables, functions, and types
- **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants
- `<>` includes only for system headers (std, OS, etc.)
- `""` includes for project headers
- Include order:
  1. C standard library headers (`<stdlib.h>`, `<string.h>`, etc.)
  2. *(blank line)*
  3. OS-specific headers (Windows API, POSIX, etc.)
  4. *(blank line)*
  5. Third-party dependencies
  6. *(blank line)*
  7. Local/project headers

## Shell Scripts

- Always use `#!/bin/sh` shebang for shell scripts
- Scripts must be POSIX compliant (no bashisms)
- When providing commands to users:
  - Windows/PowerShell: use `` ` `` for line continuation
  - Unix/Linux/macOS: use `\` for line continuation

## Commit Messages

- Follow the 50/72 rule:
  - Subject line: max 50 characters
  - Body lines: wrapped at 72 characters
- Use conventional commit prefixes (`feat:`, `fix:`, `docs:`, `chore:`,
  etc.)
- Separate subject from body with a blank line
- Do **not** add yourself as a co-author (`Co-Authored-By:` trailers are
  forbidden)

## Documentation (Markdown)

- Wrap normal text and lists at **max 80 columns** (for readability in
  terminals and editors).
- **Exceptions**: Tables and code blocks (```` ``` ````) can exceed 80
  columns when formatting requires it (e.g. trees, alignment).
- Use standard Markdown: `**bold**`, `` `inline code` ``, `##` headings,
  `-` or numbered lists, fenced code blocks with language hints.
- Keep examples concise, up-to-date, and self-documenting.
- Do not use em dashes (`—`). Use a colon or rewrite the sentence.
- Each shell command gets its own fenced code block; do **not** combine
  multiple commands into one block. Precede each block with a short
  plain-text label describing what the command does.
- This file (`AGENTS.md`) follows its own rules.

## Source Layout

```text
stk/
  stk.h / stk_win.c   EdgeTX HID radio reader (stub for now)
src/
  main.c              Entry point (hello world)
tests/
  test_stk.c          Unity tests for stk
deps/
  FindUnity.cmake      Fetches Unity v2.6.1 via ZIP
  FindCMock.cmake      Fetches CMock v2.6.0 via ZIP
  Platform.cmake       Detects OS and compiler
  Flags.cmake          Warning flags per compiler
  Coverage.cmake       gcovr coverage support
  Sanitizers.cmake     AddressSanitizer support
  IDE.cmake            VS/Xcode folder grouping
```

## Platform Support

The project supports Windows, Linux, macOS, Emscripten, and Android via
`Platform.cmake` and `Flags.cmake` in `deps/`.