esp32-lua-api/AGENTS.md

ESP32 Lua API Guidelines

This is a clean contract for repositories under the same owner's control. Choose the best shared API without preserving old names, signatures, or behavior; consumers migrate to the contract.

Every firmware implements all declarations under lua/api/core/. Optional hardware contracts live under lua/api/features/; sys.hasFeature(name) guarantees the complete matching contract. Lua-language sources stay under lua/; C/C++ and the vendored interpreter stay under native/. Apps are fully trusted; keep permissions and sandboxing out of scope. Firmware commits dirty display content and owns panel refresh policy. Binding annotations under native/src/bindings/ generate matching lua/api/ files; regenerate instead of editing files marked generated. Each @lua-module/@lua-augment directive sits immediately above the luaL_Reg table it describes, which is how one source declares several namespaces. This repository owns portable lua/lib/ modules; shared UI owns theme application and persistence. Use ble for BLE/GATT and reserve bt for a future Classic Bluetooth contract.