@polderlabs/bizar 6.2.4 → 6.3.0

package/.claude/skills/embedded-esp-idf/references/logging-discipline.md

@@ -0,0 +1,118 @@
+# Logging discipline
+
+ESP-IDF logging uses `ESP_LOG*` macros. They are cheap when disabled (compile out), acceptable at moderate rates, and dangerous at acquisition-frame rates.
+
+## The macros
+
+```cpp
+ESP_LOGE(TAG, "fmt", ...);   // error — always shown at default verbosity
+ESP_LOGW(TAG, "fmt", ...);   // warning — recoverable issue
+ESP_LOGI(TAG, "fmt", ...);   // info — state transitions
+ESP_LOGD(TAG, "fmt", ...);   // debug — verbose, off by default
+ESP_LOGV(TAG, "fmt", ...);   // verbose — trace, off by default
+```
+
+Each is gated by a per-level compile-time switch (`CONFIG_LOG_DEFAULT_LEVEL`) and a per-tag runtime level (`esp_log_level_set("tag", ESP_LOG_WARN)`).
+
+## Tags
+
+Use a stable per-module tag — a file-scope `static const char *TAG`:
+
+```cpp
+static const char *TAG = "ams7driver";
+ESP_LOGI(TAG, "Start acquisition stack_hw=%lu", (unsigned long)stack_hw);
+```
+
+Tags show up as `[tag]` prefixes in the serial monitor and let you filter:
+
+```bash
+idf.py monitor --print-filter="ams7driver:I espnow_summary:W"
+```
+
+Pick short, stable tags. AMS7 module tags: `ams7driver`, `espnow_summary`, `ble_prph`, `acqsystem`, `dps310`, `ads129x`, `icm42688p`, `sdcard`.
+
+## Format strings
+
+Format strings are validated against arguments at compile time when GCC sees the format attribute:
+
+```cpp
+ESP_LOGI(TAG, "Hold=%lu ms", (unsigned long)ms);   // %lu for unsigned long
+ESP_LOGI(TAG, "Cap=%" PRIu32, cap);               // PRIu32 macro for uint32_t
+ESP_LOGI(TAG, "Ratio=%f", ratio);                 // %f for double, %f for float (promoted)
+```
+
+Common gotchas:
+
+- `%lu` for `uint32_t` is **wrong on platforms where `long` is 64-bit**. Use `%" PRIu32 "` instead.
+- `%d` for `size_t` is wrong on 64-bit hosts; use `%zu`.
+- `%p` for arbitrary pointer; cast to `void *` first.
+
+## Gating with Kconfig
+
+Wrap debug logs in a `CONFIG_*` guard so a release build can drop them entirely:
+
+```cpp
+#if CONFIG_AMS7_RESP_TRIAL_DEBUG_LOG_ENABLE
+    ESP_LOGI(TAG, "resp sample processed src=%d q=%u", src, q);
+#endif
+```
+
+`(AMS7)` AMS7 names these options `*_TRIAL_DEBUG_LOG_ENABLE` and defaults them to `n` (or `y` only during early integration). They are the right toggle for "I want to see this while tuning the algorithm but not in production."
+
+## Universal anti-patterns
+
+- **Per-frame logs in acquisition.** At 125–500 Hz this is unprintable and floods the UART. The host monitor loses the frames you actually need.
+- **Logs in ISRs.** `ESP_LOG*` is not `IRAM_ATTR`; calling it from an ISR pulls the whole logging chain into IRAM. Use `xQueueSendFromISR` to a logging task instead.
+- **Logging from `app_main`'s setup before serial is up.** First few lines can be lost. Wait for `ESP_LOGI(TAG, "boot")` to appear before assuming the console is alive.
+- **Sensitive data in logs.** Avoid logging peer MACs, subject IDs, or anything that crosses a wire to a host that doesn't need it. Add a `LOG_REDACT` flag if the project warrants it.
+
+## AMS7 acquisition-logging rules
+
+`(AMS7)` Acquisition builds must not log per-sample or per-frame. Acceptable log rates:
+
+- **Per event**: BLE connect/disconnect, ESP-NOW peer add/remove, acquisition start/stop, file open/close, error conditions. These are inherently low-rate.
+- **Periodic aggregate**: low-rate counters via a `pl:` (payload) console line every N ms. Example:
+
+```cpp
+// Throttled to 1 Hz regardless of underlying sample rate
+if ((now_ms - last_pl_ms) >= 1000) {
+    last_pl_ms = now_ms;
+    ESP_LOGI(TAG, "pl: beats=%lu rr_ms=%lu q=%u en=%u src=%d",
+             beats, rr_ms, quality, envelope, source);
+}
+```
+
+The `pl:` prefix is grep-friendly — host-side tooling can pluck aggregate lines from the serial stream without parsing every byte.
+
+- **Trial-debug toggles**: `CONFIG_AMS7_RESP_TRIAL_DEBUG_LOG_ENABLE`, `CONFIG_AMS7_HR_FUSED_DEBUG_LOG_ENABLE`, etc. Default `n` for release builds. When enabled, log per-decision but still throttled.
+
+## Tagging aggregate lines
+
+Use a tag prefix that distinguishes aggregate from per-event so the host can filter:
+
+```cpp
+// Aggregate (high-volume, low-rate)
+ESP_LOGI("ams7_pl", "pl: hr=%lu rr_ms=%lu q=%u", hr_bpm, rr_ms, q);
+
+// Per-event (low-volume, descriptive)
+ESP_LOGI(TAG, "Acquisition start mode=%d stack_hw=%lu", mode, stack_hw);
+```
+
+## Runtime level control
+
+`esp_log_level_set` lets you bump a tag's verbosity at runtime:
+
+```cpp
+esp_log_level_set("espnow_summary", ESP_LOG_DEBUG);   // noisy on demand
+esp_log_level_set("ams7driver", ESP_LOG_WARN);         // quiet a noisy module
+```
+
+This is the right tool for "I want to debug one module without rebuilding."
+
+## Common pitfalls
+
+- **Logs in a tight loop.** Symptom: dropouts in other tasks, overflowing the UART ringbuffer. Fix: throttle or remove.
+- **Float in `ESP_LOG*`.** ESP-IDF supports `%f` but pulling in `<stdio.h>` float formatting adds code; consider integer milliunits instead.
+- **Missing format attribute.** ESP-IDF declares `__attribute__((format(printf, ...)))` on `ESP_LOG*` so format mismatches are warnings. Don't bypass with a `static_cast`.
+- **Stale `TAG`.** Renaming a file but leaving the old `TAG`. Tag should match the module name in `idf.py monitor` filters.
+- **Compile-time vs runtime gate confusion.** `CONFIG_LOG_DEFAULT_LEVEL` is compile-time; `esp_log_level_set` is runtime. A tag's level is `min(compile_max, runtime_set, default)`.

package/.claude/skills/embedded-esp-idf/references/memory-and-iram.md

@@ -0,0 +1,137 @@
+# Memory model and IRAM
+
+ESP32 (Xtensa LX6/LX7, or RISC-V on S3/C3) has distinct address spaces. Code and data are placed into them by the linker based on attributes; getting this wrong is the difference between a working firmware and one that crashes on the first SPI-DMA transfer.
+
+## Address spaces at a glance
+
+| Space     | Size (classic ESP32)        | What lives here                                              |
+|-----------|-----------------------------|--------------------------------------------------------------|
+| IRAM      | ~128 KB (some chips 256 KB) | ISR handlers, `IRAM_ATTR` functions, flash-cache-disabled    |
+| DRAM      | ~120 KB                     | `.data`, `.bss`, heap, stacks, default-code-section RAM     |
+| Flash     | 4–16 MB                     | Program text (XIP), read-only data, filesystems              |
+| PSRAM     | 0–8 MB optional             | Large buffers via `MALLOC_CAP_SPIRAM`                        |
+
+## IRAM (instruction RAM)
+
+IRAM is the tightest budget on most ESP32 firmware because it has to be physically present on-chip and is not expandable. Code in IRAM can run without flash cache, which is required during:
+
+- **ISR handlers** — the cache may be disabled.
+- **SPI / DMA completion paths** — flash-cache-disabled periods when the SPI peripheral is busy.
+- **Time-critical inner loops** — a few hot loops that would be slowed by XIP cache misses.
+
+Mark a function IRAM-resident with the attribute:
+
+```cpp
+#include "esp_attr.h"
+
+void IRAM_ATTR spi_complete_isr(spi_transaction_t *trans) {
+    // runs from IRAM, must be small and avoid non-IRAM APIs
+}
+```
+
+`(AMS7)` Keep IRAM remaining ≥ 20 KiB on AMS7. Below 24 KiB is a warning. Do not add `IRAM_ATTR` unless the function is genuinely on a cache-disabled path. See `docs/firmware/memory_budget.md`.
+
+### What blows the IRAM budget
+
+- **Every `IRAM_ATTR` function** — even a 200-byte routine pulls in 200 bytes of IRAM that flash would otherwise have held.
+- **Logging inside ISRs** — `ESP_LOG*` is not `IRAM_ATTR` by default; if you call it from an ISR, the linker pulls the entire logging chain into IRAM. Use direct `uart_tx` or a deferred task instead.
+- **Format strings in IRAM** — `printf`-style code in IRAM is expensive. Move formatted output to a task.
+- **Per-frame work in IRAM** — even non-IRAM helpers reached only from IRAM functions can end up in IRAM if the linker decides so (`-ffunction-sections` + linker `--gc-sections` reduces but does not eliminate this).
+- **Inlining** — `static inline` in a header used by an IRAM file ends up in IRAM for every consumer.
+
+### Diagnosing IRAM growth
+
+```bash
+idf.py size --format json --output-file size.json
+python3 -c "import json; s=json.load(open('size.json')); print(s['iram_size'], s['dram_size'])"
+```
+
+For per-symbol breakdown:
+
+```bash
+$IDF_PATH/tools/uf2/elf2image.py build/<project>.elf  # if needed
+xtensa-esp32-elf-objdump -d build/<project>.elf | grep '<.*>:' | head
+```
+
+The AMS7-specific gate `tools/check_idf_size_budget.py` (wrapped by `scripts/size_check.sh`) reads the JSON and fails on hard thresholds.
+
+## DRAM (data RAM)
+
+DRAM holds:
+
+- `.data` — initialized globals (`int x = 5;`).
+- `.bss` — zero-initialized globals (`int x;`).
+- **Heap** — `malloc` / `new` returns here by default.
+- **Stacks** — one stack per FreeRTOS task; `app_main`'s stack is fixed.
+
+### Prefer static
+
+Heap fragmentation is severe on ESP32 — there is no `mmap` or `sbrk`, just a fixed free list. Long-running firmware that `malloc`s in a loop will eventually fail with `ESP_ERR_NO_MEM`.
+
+Rules:
+
+- `static const` arrays for lookup tables.
+- `static` (file-scope) for buffers reused across calls.
+- `std::array<T, N>` or `std::span` over `std::vector`.
+- Pool allocators if you really need dynamic.
+
+When you must malloc, prefer `heap_caps_malloc(size, MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL)` and free in matching scope. Always check the returned pointer.
+
+### Stacks
+
+FreeRTOS stacks grow downward; overflow corrupts whatever is below them. Tuning:
+
+- Stack depth is in **words** (4 bytes on Xtensa, 4 bytes on RISC-V too). `4096` = 16 KiB.
+- Over-budget: enable `CONFIG_COMPILER_STACK_CHECK_MODE_NORM` (compiler-instrumented) or `CONFIG_FREERTOS_WATCHPOINT_END_OF_STACK` (hardware watchpoint, only one task at a time).
+- Use `uxTaskGetStackHighWaterMark(handle)` to measure headroom at runtime.
+
+`(AMS7)` AMS7 acquisition stacks are 8–16 KB; command-handler stack on the PRO CPU is 16 KB (`CONFIG_MAIN_TASK_STACK_SIZE=16384`).
+
+### Internal vs PSRAM (DMA-capable)
+
+`MALLOC_CAP_INTERNAL` requests memory in DRAM. `MALLOC_CAP_SPIRAM` requests external PSRAM (slow, no DMA). Combine as needed:
+
+```cpp
+// 8-bit accessible, internal (DMA-capable) — for SPI/I2S buffers
+uint8_t *dma_buf = (uint8_t *)heap_caps_malloc(4096, MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL);
+
+// large, no DMA requirement — JSON caches, log buffers
+char *big_buf = (char *)heap_caps_malloc(64 * 1024, MALLOC_CAP_8BIT | MALLOC_CAP_SPIRAM);
+```
+
+Always check the return value — `MALLOC_CAP_SPIRAM` may fail if PSRAM is not configured, or return NULL if the chip has none.
+
+## Flash
+
+Most code lives in flash and is executed in place (XIP). The flash cache is on-chip and small (~32 KB on classic ESP32). Functions that are not in cache take a flash-read penalty.
+
+To check cache hit rate at runtime:
+
+```cpp
+#include "esp_heap_caps.h"
+ESP_LOGI(TAG, "free 8-bit internal: %u", heap_caps_get_free_size(MALLOC_CAP_8BIT | MALLOC_CAP_INTERNAL));
+```
+
+For static asserts on flash size, see `idf.py size` output. The relevant numbers are:
+
+- **Flash app binary** — total image size.
+- **`bytes free in the smallest app partition`** — partition headroom; matters for OTA.
+
+## `.iram0.lit`, `.iram0.text`, and `.dram0.*`
+
+The default linker script places:
+
+- `.iram0.lit` — literal pools (constants referenced from IRAM).
+- `.iram0.text` — `IRAM_ATTR` functions.
+- `.dram0.data` / `.dram0.bss` — initialized / zero-initialized data.
+- `.flash.text` — all other code.
+
+`idf.py size` aggregates these. Per-section breakdown requires `xtensa-esp32-elf-size -A build/<project>.elf`.
+
+## Common pitfalls
+
+- **Calling a non-IRAM function from an ISR.** Symptom: intermittent crash in the ISR. Fix: mark the called function `IRAM_ATTR` or move the work to a task.
+- **Using `printf` / `ESP_LOG*` from an ISR.** Symptom: large IRAM growth. Fix: use `xQueueSendFromISR` to defer the log to a task.
+- **Malloc with `MALLOC_CAP_SPIRAM` on a chip without PSRAM.** Symptom: NULL return, hard fault on deref. Fix: fall back to internal with a smaller size, or fail loudly.
+- **Stack overflow from deep recursion.** Symptom: hard fault or corruption deep in the call stack. Fix: convert to iteration, or bump the task's stack.
+- **Static buffers in headers.** A `static constexpr` buffer in a header included by many `.cpp` files duplicates per translation unit, then collides at link. Use `inline constexpr` (C++17) or move to a single `.cpp`.

package/.claude/skills/embedded-esp-idf/references/nvs.md

@@ -0,0 +1,121 @@
+# NVS (Non-Volatile Storage) on ESP-IDF
+
+NVS stores small key-value pairs in flash and survives reboot. ESP-IDF provides `nvs_flash.h` (low-level) and `nvs.h` (typed handle API). Most firmware code uses the typed handle API.
+
+## Initialization — once at boot
+
+`nvs_flash_init()` must be called **exactly once at application startup**, not on every operation. Calling it in a getter/setter is an anti-pattern.
+
+```cpp
+// GOOD — in app_main()
+extern "C" void app_main() {
+    esp_err_t ret = nvs_flash_init();
+    if (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        ESP_ERROR_CHECK(nvs_flash_erase());
+        ret = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK(ret);
+    // ... start tasks, services, etc.
+}
+
+// BAD — calling nvs_flash_init() in every Get/Set is wasteful
+esp_err_t Configuration::GetInt(const char* key, int32_t* out) {
+    nvs_flash_init();  // <-- wrong
+    nvs_handle_t h;
+    nvs_open("ns", NVS_READONLY, &h);
+    // ...
+}
+```
+
+For partition-encrypted or large NVS partitions, also handle `ESP_ERR_NVS_NO_FREE_PAGES` and `ESP_ERR_NVS_NEW_VERSION_FOUND` by erase + retry. See `examples/storage/nvs_value_iterator` in ESP-IDF.
+
+## Namespaces and handles
+
+Open a handle per operation or per long-lived component:
+
+```cpp
+// Per-operation (simple, slightly more overhead)
+nvs_handle_t h;
+ESP_ERROR_CHECK(nvs_open("ams7cfg", NVS_READWRITE, &h));
+int32_t val = 42;
+ESP_ERROR_CHECK(nvs_set_i32(h, "ble_adv", val));
+ESP_ERROR_CHECK(nvs_commit(h));
+nvs_close(h);
+
+// Per-component (preferred for hot paths)
+class ConfigStore {
+public:
+    esp_err_t Init() {
+        esp_err_t err = nvs_open("ams7cfg", NVS_READWRITE, &handle_);
+        if (err != ESP_OK) return err;
+        // optional: pre-load known keys
+        return ESP_OK;
+    }
+    ~ConfigStore() { nvs_close(handle_); }
+private:
+    nvs_handle_t handle_{};
+};
+```
+
+`nvs_commit()` is **required** for write durability — `nvs_set_*` only updates the in-memory cache.
+
+## Typed vs blob storage
+
+| Type | Use for |
+|---|---|
+| `nvs_set_i8/u8/i16/u16/i32/u64` | Counters, flags, IDs, durations |
+| `nvs_set_str` | Variable-length strings (max 4000 bytes per key, ~1984 bytes safe) |
+| `nvs_set_blob` | Packed structs, calibration data, JSON payloads |
+| `nvs_set_str` with fixed keys | Persistent default values (e.g., `feature_flag_default` = "on") |
+
+Use **typed keys** for atomic per-field updates; use **blob** only when the data is always written and read as a unit (otherwise partial writes corrupt the format).
+
+## Error handling
+
+`ESP_ERROR_CHECK_WITHOUT_ABORT(nvs_set_*(...))` silently swallows NVS failures. The caller has no way to know the persist operation succeeded. Two patterns:
+
+```cpp
+// 1. Propagate the error to the caller
+esp_err_t ConfigStore::SetInt(const char* key, int32_t val) {
+    esp_err_t err = nvs_set_i32(handle_, key, val);
+    if (err != ESP_OK) return err;
+    return nvs_commit(handle_);
+}
+
+// 2. Log and degrade gracefully
+esp_err_t err = nvs_set_i32(handle_, key, val);
+if (err != ESP_OK) {
+    ESP_LOGE(TAG, "nvs_set_i32(%s) failed: %s", key, esp_err_to_name(err));
+    return;  // caller decides what to do
+}
+```
+
+Avoid bare `ESP_ERROR_CHECK_WITHOUT_ABORT` followed by an assumed-success return value.
+
+## Common pitfalls
+
+- **Forgetting `nvs_commit()`** — `nvs_set_*` is buffered; without commit, values are lost on power cycle
+- **Using the same handle from two tasks** — `nvs_handle_t` is not thread-safe; serialize access or use one handle per task
+- **Hitting the 4-6 KB per-namespace limit** — large blobs need a dedicated namespace; check `nvs_get_stats()` first
+- **Storing `std::string` directly** — NVS stores C strings, convert with `.c_str()` for write and `nvs_get_str` + sized buffer for read
+- **Initializing on every getter** — see "Initialization" above
+- **Hardcoded partition not present** — confirm `partitions.csv` includes an `nvs` entry; default is usually fine but custom layouts can break
+
+## Kconfig gating for NVS debug
+
+Expose NVS internals under a debug option so production builds stay quiet:
+
+```kconfig
+config AMS7_NVS_DEBUG_ENABLE
+    bool "Enable verbose NVS logging"
+    default n
+    help
+        When enabled, every NVS get/set logs a line. Disable in production
+        to avoid per-write console output.
+```
+
+## AMS7-specific patterns
+
+`(AMS7)` The AMS7 firmware uses the namespace `"ams7cfg"` for runtime feature flags and study metadata. The NVS handle is owned by `Configuration` in `main/ams7conf.cpp`. The boot path in `main/ams7_esp32.cpp` calls `nvs_flash_init()` once before any `Configuration` access.
+
+`(AMS7)` Persisted feature-flag defaults are stored as NVS strings (e.g., `ble_adv_snapshot_default = "on"`) — the runtime override is in RAM only. This lets `_SAVE` commands persist while plain `!FEATURE=true` commands stay ephemeral.

package/.claude/skills/embedded-esp-idf/references/packed-structs.md

@@ -0,0 +1,192 @@
+# Packed binary protocols
+
+Wire-format frames over ESP-NOW, BLE characteristic writes, or any byte-oriented transport must have deterministic layout. ESP32 is little-endian natively, but `__attribute__((packed))` structs are still required to lock field offsets across compilers and configurations.
+
+## The canonical AMS7 frame shape
+
+Every AMS7 wire frame lives in `main/connectivity/espnow_*_frame.hpp` and follows the same pattern. The IMU frame is the cleanest example:
+
+```cpp
+// main/connectivity/espnow_imu_frame.hpp
+#pragma once
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define CORE_ESPNOW_IMU_MAGIC     0x494dU   // ASCII 'I','M'
+#define CORE_ESPNOW_IMU_VERSION   1U
+#define CORE_ESPNOW_FRAME_IMU_RAW 1U
+
+typedef struct __attribute__((packed)) {
+    uint16_t magic;         // identifies the frame family on the wire
+    uint8_t  version;       // protocol version of this struct
+    uint8_t  frame_type;    // sub-type within the family
+    uint16_t id;            // sender / subject id
+    uint16_t seq;           // monotonic sequence
+    uint16_t age_ms;        // capture age in ms (sender-stamped)
+    int16_t  accel_x, accel_y, accel_z;
+    int16_t  gyro_x,  gyro_y,  gyro_z;
+} core_espnow_imu_frame_v1_t;
+
+void espnow_imu_frame_init(core_espnow_imu_frame_v1_t *frame,
+                           uint16_t id,
+                           uint16_t seq,
+                           uint16_t age_ms,
+                           int16_t accel_x,
+                           int16_t accel_y,
+                           int16_t accel_z,
+                           int16_t gyro_x,
+                           int16_t gyro_y,
+                           int16_t gyro_z);
+
+#ifdef __cplusplus
+}
+static_assert(sizeof(core_espnow_imu_frame_v1_t) == 22,
+              "core_espnow_imu_frame_v1_t must be 22 bytes");
+#else
+_Static_assert(sizeof(core_espnow_imu_frame_v1_t) == 22,
+               "core_espnow_imu_frame_v1_t must be 22 bytes");
+#endif
+```
+
+This pattern is **load-bearing** for the project:
+
+- `magic` is the first 16 bits so the receiver can reject foreign frames in O(1) before parsing.
+- `version` distinguishes `_v1_t` from `_v2_t` so the receiver can dispatch to the right decoder.
+- `frame_type` distinguishes sub-types within the same magic family (e.g., `IMU_RAW` vs a future `IMU_QUAT`).
+- A trailing `static_assert` locks the on-wire size — adding a field is a build error, not a silent wire-format drift.
+
+`(AMS7)` Naming convention is `core_<transport>_<family>_frame_v<N>_t`. Static asserts are mandatory on every wire struct.
+
+## The universal five rules
+
+1. **`__attribute__((packed))`** on every wire struct. Never rely on natural alignment.
+2. **`static_assert(sizeof(T) == N)`** for every wire struct. The assertion fires at compile time, not over the air.
+3. **Fixed-width types** only: `uint16_t`, `int16_t`, `uint32_t`, `int32_t`. Never `int`, `long`, `short`.
+4. **Magic byte first**, then version, then frame_type. Let the receiver reject foreign frames cheaply.
+5. **Length-prefixed framing** on the wire: 2 bytes little-endian length, then that many bytes of payload. No delimiter scanning, no escape bytes.
+
+## Byte order
+
+ESP32 is little-endian natively; a `uint16_t` written via `memcpy` lands as low-byte-then-high-byte. When porting to a big-endian host (or a future big-endian SoC), use explicit byte-swap helpers instead of leaving `<<` chains:
+
+```cpp
+// Bad: silent byte-order dependence
+uint32_t be = (raw[0] << 24) | (raw[1] << 16) | (raw[2] << 8) | raw[3];
+
+// Good: explicit and obvious
+#include <endian.h>
+uint32_t value = le32toh(*reinterpret_cast<const uint32_t *>(raw));
+```
+
+Most ESP-IDF code uses the native LE order and stays put — the explicit byte swap is only needed when a host tool expects BE or when you genuinely don't know the SoC.
+
+## Versioning and capability bits
+
+When you need to evolve a frame without breaking old receivers, **bump the version** and add a `_v2_t`. Old receivers see the new magic and ignore it; new receivers see the version byte and dispatch:
+
+```cpp
+typedef struct __attribute__((packed)) {
+    uint16_t magic;
+    uint8_t  version;       // 2
+    uint8_t  frame_type;
+    uint16_t id;
+    uint16_t seq;
+    uint32_t timestamp_us;  // new in v2
+    /* ... existing fields ... */
+} core_espnow_imu_frame_v2_t;
+
+static_assert(sizeof(core_espnow_imu_frame_v2_t) == 30,
+              "core_espnow_imu_frame_v2_t must be 30 bytes");
+```
+
+For optional fields, use a `capability_bits` bitmask after the header:
+
+```cpp
+typedef struct __attribute__((packed)) {
+    uint16_t magic;
+    uint8_t  version;
+    uint8_t  frame_type;
+    uint16_t id;
+    uint16_t seq;
+    uint32_t cap_bits;      // bit 0 = has_quaternion, bit 1 = has_temperature, ...
+    /* ... variable ... */
+} core_espnow_capability_frame_v1_t;
+```
+
+Receivers mask-and-test `cap_bits` to know which optional fields are present.
+
+## Wire framing (length-prefixed)
+
+ESP-NOW itself has a 250-byte MTU per packet and 6-byte receiver MAC; AMS7 adds a 2-byte length prefix and a magic-byte envelope:
+
+```
++--------+--------+--------------+----------+
+| length | magic  |   payload    | (rounded |
+| (u16)  | (u16)  |  (frame_t)   |  to MTU) |
++--------+--------+--------------+----------+
+```
+
+The receiver reads `length`, then reads exactly `length` bytes. If `length` exceeds the packet, the packet is dropped. If `magic` does not match a known family, drop.
+
+For ESP-NOW specifically, AMS7 frames use a per-frame structure with sender-stamped `age_ms` so receivers can detect stale samples without keeping state.
+
+## Init functions
+
+Always provide an `_init` function that fills the struct from named arguments. This is the only thing that touches the wire struct's bytes, so the layout can change without callers changing:
+
+```cpp
+void espnow_imu_frame_init(core_espnow_imu_frame_v1_t *frame,
+                           uint16_t id, uint16_t seq, uint16_t age_ms,
+                           int16_t ax, int16_t ay, int16_t az,
+                           int16_t gx, int16_t gy, int16_t gz) {
+    frame->magic      = CORE_ESPNOW_IMU_MAGIC;
+    frame->version    = CORE_ESPNOW_IMU_VERSION;
+    frame->frame_type = CORE_ESPNOW_FRAME_IMU_RAW;
+    frame->id         = id;
+    frame->seq        = seq;
+    frame->age_ms     = age_ms;
+    frame->accel_x    = ax;  frame->accel_y = ay;  frame->accel_z = az;
+    frame->gyro_x     = gx;  frame->gyro_y  = gy;  frame->gyro_z  = gz;
+}
+```
+
+The init function is the seam — add a field, the init function gets a new argument, every caller updates. The wire size assertion catches a missed caller at compile time.
+
+## Sending and receiving
+
+```cpp
+// Send: copy struct bytes into a flat buffer, prefix with length, hand to ESP-NOW.
+core_espnow_imu_frame_v1_t f{};
+espnow_imu_frame_init(&f, id, seq, age_ms, ax, ay, az, gx, gy, gz);
+uint8_t wire[2 + sizeof(f)];
+wire[0] = sizeof(f) & 0xff;
+wire[1] = (sizeof(f) >> 8) & 0xff;
+memcpy(wire + 2, &f, sizeof(f));
+esp_now_send(peer, wire, sizeof(wire));
+```
+
+```cpp
+// Receive: validate length, magic, version; then consume fields.
+void on_recv(const uint8_t *data, size_t len) {
+    if (len < 2 + sizeof(core_espnow_imu_frame_v1_t)) return;
+    uint16_t want = (uint16_t)data[0] | ((uint16_t)data[1] << 8);
+    if (want != sizeof(core_espnow_imu_frame_v1_t)) return;
+    core_espnow_imu_frame_v1_t f;
+    memcpy(&f, data + 2, sizeof(f));
+    if (f.magic != CORE_ESPNOW_IMU_MAGIC || f.version != CORE_ESPNOW_IMU_VERSION) return;
+    handle_imu(&f);
+}
+```
+
+## Common pitfalls
+
+- **No `static_assert`.** A field added in one header silently breaks every receiver. Always lock `sizeof`.
+- **`int` or `long` fields.** Their size varies across compilers and platforms; never use them on the wire.
+- **Natural alignment assumed.** Without `__attribute__((packed))`, the compiler may insert padding that you cannot see at the source level.
+- **Magic-byte collision.** Two frame families accidentally using the same 2-byte magic. Pick from a sparse range; document in `docs/transport_payload_reference.md`.
+- **Sending the struct directly via ESP-NOW.** ESP-NOW needs a flat byte buffer and a length prefix; sending `&frame, sizeof(frame)` skips the length prefix and confuses the receiver's parser.
+- **Endianness assumptions on the host.** If a host-side tool (Rust gateway, Python decoder) reads the bytes, it must apply the same byte order. Document in `docs/transport_payload_reference.md`.

package/.claude/skills/embedded-esp-idf/scripts/idf_env.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# idf_env.sh — print the source line for the ESP-IDF environment and verify idf.py is reachable.
+# Run as: bash scripts/idf_env.sh
+# Exits 0 if `idf.py` is on PATH after a (dry-run) env probe; 1 otherwise.
+
+set -euo pipefail
+
+# Find the repo root from the skill directory. We resolve the script's real
+# path so it works whether invoked from the skill dir or anywhere else.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Heuristic: the project root is two levels up from scripts/ inside the skill.
+# Skill layout: <repo>/scripts/<this>.sh  →  PROJECT_ROOT is SCRIPT_DIR's parent.
+PROJECT_ROOT_DEFAULT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+PROJECT_ROOT="${PROJECT_ROOT:-${PROJECT_ROOT_DEFAULT}}"
+
+# The vendored ESP-IDF is conventionally at <repo>/esp/esp-idf.
+IDF_DIR_CANDIDATE="${PROJECT_ROOT}/esp/esp-idf"
+EXPORT_LINE="source ${IDF_DIR_CANDIDATE}/export.sh"
+
+if [[ ! -d "${IDF_DIR_CANDIDATE}" ]]; then
+    echo "Run: ${EXPORT_LINE}    # (note: esp-idf not found at ${IDF_DIR_CANDIDATE})" >&2
+    echo "info: set PROJECT_ROOT to override the discovery path" >&2
+    echo "info: set IDF_PATH to a different ESP-IDF checkout" >&2
+    exit 1
+fi
+
+if [[ ! -x "${IDF_DIR_CANDIDATE}/tools/idf.py" ]] && [[ ! -f "${IDF_DIR_CANDIDATE}/tools/idf.py" ]]; then
+    echo "Run: ${EXPORT_LINE}    # (note: idf.py not present at expected path)" >&2
+    exit 1
+fi
+
+# Probe: source the env in a subshell, then check whether idf.py is on PATH.
+# We avoid printing the env's own banner by sending output to /dev/null.
+if (
+    set +e
+    # shellcheck disable=SC1091
+    source "${IDF_DIR_CANDIDATE}/export.sh" >/dev/null 2>&1
+    command -v idf.py >/dev/null 2>&1
+) ; then
+    echo "Run: ${EXPORT_LINE}"
+    exit 0
+else
+    echo "Run: ${EXPORT_LINE}    # (env probe failed; check IDF_PATH and Python)" >&2
+    exit 1
+fi