Inital commit

AGENTS.md

@@ -0,0 +1,146 @@
+# 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/`.