From 2cfb8929a62b10b0e47b6d4548c03043d67e0b80 Mon Sep 17 00:00:00 2001
From: Alex <15167344+frostmorn@users.noreply.github.com>
Date: Tue, 21 Apr 2026 15:18:39 +0300
Subject: [PATCH] Add agents md for ai agents to better orient in repository

---
 AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ea9d644
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,45 @@
+# AGENTS.md
+
+> This file is read automatically by AI coding agents before making any changes to the codebase.
+
+## What this repo is
+
+The Lilka SDK — a PlatformIO library (`lib/lilka/`) that provides hardware abstractions for the Lilka console (ESP32-S3/C3). It is consumed by [KeiraOS](https://github.com/lilka-dev/keira) as a sibling directory dependency.
+
+## Non-obvious conventions
+
+- `String` (Arduino) is the only Arduino type allowed — use it for all string handling; prefer esp-idf for everything else
+- Use `#pragma once` — never `#ifndef` include guards (some legacy headers still use `#ifndef`, don't copy that pattern)
+- All SDK subsystems are exposed as `extern` singletons (e.g. `lilka::board`, `lilka::audio`, `lilka::resources`) — never instantiate them manually
+- Hardware pin numbers must come from `lilka/config.h` `LILKA_GPIO_*` / `LILKA_*` defines — never hardcode GPIO numbers
+- Images loaded via `lilka::resources.loadImage()` are heap-allocated — always `delete` them after use
+- Always use C-style file API (`fopen`, `fread`, `fwrite`, `fclose`) with canonical paths (`/sd/...`, `/spiffs/...`) — never use `SD.open()`, `SPIFFS.open()`, or any Arduino filesystem wrappers
+- Use `vTaskDelay()` instead of `delay()`
+
+## What not to touch
+
+- `lib/lilka/src/lilka/version_auto_gen.h` — auto-generated at build time
+- `lib/lilka/src/contrib/` — vendored third-party code, don't reformat
+- `.pio/` — generated by PlatformIO
+
+## Adding a new subsystem
+
+- Add header to `lib/lilka/src/lilka/`
+- Expose a single `extern` singleton instance
+- Include it in `lib/lilka/src/lilka.h`
+- Initialize in `lilka::begin()` (`lib/lilka/src/lilka/sdk.cpp`)
+- Document public API with Doxygen (`///` comments)
+
+## Adding icons/images
+
+- Place PNG in `lib/lilka/src/lilka/icons/`
+- Run `make icons` — it converts PNGs to `.h` files via `tools/image2code/image2code.py`
+- Never hand-edit generated `.h` image files
+
+## Code quality
+
+- clang-format-20 enforced in CI
+- Run `make clang-format` and `make cppcheck` before committing — both must pass
+- Run `make check` to run both at once
+- `make todo` lists all `TODO` / `FIXME` / `XXX` in the codebase
+- `make guidelines` lists all `GUIDELINE` comments — read them before changing related code