@polderlabs/bizar 9.0.0 → 10.0.7

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

@@ -1,118 +0,0 @@
-# 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/worktrees/kanban-overhaul/.claude/skills/embedded-esp-idf/references/memory-and-iram.md

@@ -1,137 +0,0 @@
-# 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/worktrees/kanban-overhaul/.claude/skills/embedded-esp-idf/references/nvs.md

@@ -1,121 +0,0 @@
-# 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/worktrees/kanban-overhaul/.claude/skills/embedded-esp-idf/references/packed-structs.md

@@ -1,192 +0,0 @@
-# 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/worktrees/kanban-overhaul/.claude/skills/embedded-esp-idf/scripts/idf_env.sh

@@ -1,47 +0,0 @@
-#!/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