@polderlabs/bizar 2.3.0

package/config/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/config/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/config/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/config/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

package/config/skills/embedded-esp-idf/scripts/size_check.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# size_check.sh — run a project size-budget check.
+# Prefers the AMS7-specific `tools/check_idf_size_budget.py` if present, else falls back to `idf.py size`.
+# Exits 0 on pass, 1 on size violation (AMS7 budget tool) or build failure (fallback).
+# Usage: bash scripts/size_check.sh [--project-dir DIR] [--min-iram-remain BYTES] [--min-dram-remain BYTES]
+
+set -euo pipefail
+
+PROJECT_DIR="."
+MIN_IRAM_REMAIN=""
+MIN_DRAM_REMAIN=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --project-dir)
+            PROJECT_DIR="${2:?--project-dir requires a value}"
+            shift 2
+            ;;
+        --min-iram-remain)
+            MIN_IRAM_REMAIN="${2:?--min-iram-remain requires a value}"
+            shift 2
+            ;;
+        --min-dram-remain)
+            MIN_DRAM_REMAIN="${2:?--min-dram-remain requires a value}"
+            shift 2
+            ;;
+        -h|--help)
+            sed -n '2,6p' "$0" | sed 's/^# \?//'
+            exit 0
+            ;;
+        *)
+            echo "size_check.sh: unknown argument: $1" >&2
+            exit 2
+            ;;
+    esac
+done
+
+# Resolve absolute path so the AMS7 budget tool's argparse sees a clean --project-dir.
+if [[ -d "${PROJECT_DIR}" ]]; then
+    PROJECT_DIR="$(cd "${PROJECT_DIR}" && pwd)"
+fi
+
+AMS7_BUDGET="${PROJECT_DIR}/tools/check_idf_size_budget.py"
+
+if [[ -f "${AMS7_BUDGET}" ]]; then
+    # AMS7-specific path: uses hard thresholds from tools/check_idf_size_budget.py.
+    cmd=(python3 "${AMS7_BUDGET}" --project-dir "${PROJECT_DIR}")
+    if [[ -n "${MIN_IRAM_REMAIN}" ]]; then
+        cmd+=(--min-iram-remain "${MIN_IRAM_REMAIN}")
+    fi
+    if [[ -n "${MIN_DRAM_REMAIN}" ]]; then
+        cmd+=(--min-dram-remain "${MIN_DRAM_REMAIN}")
+    fi
+    echo "size_check: running AMS7 budget tool: ${cmd[*]}"
+    if "${cmd[@]}"; then
+        exit 0
+    else
+        echo "size_check: AMS7 size budget failed" >&2
+        exit 1
+    fi
+fi
+
+# Fallback: plain idf.py size. This prints IRAM/DRAM/flash but does NOT enforce
+# a hard threshold — exit code is whatever idf.py returns.
+if ! command -v idf.py >/dev/null 2>&1; then
+    echo "size_check: idf.py not on PATH and no AMS7 budget tool found." >&2
+    echo "size_check: source esp/esp-idf/export.sh first." >&2
+    exit 1
+fi
+
+echo "size_check: no AMS7 budget tool; running 'idf.py size' as a fallback."
+if idf.py -C "${PROJECT_DIR}" size; then
+    exit 0
+else
+    echo "size_check: idf.py size failed" >&2
+    exit 1
+fi

package/config/skills/self-improvement/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: self-improvement
+description: Use when setting up, configuring, or debugging the project-level self-improvement system. Every task records lessons learned to .bizar/AGENTS_SELF_IMPROVEMENT.md for agent behavior improvement across sessions.
+---
+
+# Self Improvement
+
+Project-level learning system. Every task records what worked, what didn't, and what patterns to follow next time — stored in `.bizar/AGENTS_SELF_IMPROVEMENT.md` at the project root.
+
+## How It Works
+
+1. **Session start**: Odin reads `.bizar/AGENTS_SELF_IMPROVEMENT.md` from project root and factors active rules into routing
+2. **During work**: Agents follow documented patterns and avoid previously-caught mistakes
+3. **Task completion**: Odin dispatches @heimdall to append a structured entry to the file
+4. **Next session**: The cycle repeats — agents get smarter over time
+
+## File Format
+
+The file lives at `<project-root>/.bizar/AGENTS_SELF_IMPROVEMENT.md`. Structure:
+
+```markdown
+# Self Improvement
+
+## Active Rules
+<!-- Keep top 5-10 actionable patterns here. Extract from recent entries. -->
+
+## Log
+
+### 2026-06-16: Brief descriptive title
+- **Context**: What was the task
+- **Lesson**: What we learned
+- **Pattern**: What to do next time
+- **Files**: src/foo.ts, src/bar.ts
+- **Agent**: thor, tyr
+```
+
+## Entry Rules for Agents
+
+When writing an entry:
+
+- **File per project** — `.bizar/AGENTS_SELF_IMPROVEMENT.md` at the root of whatever project you're working in
+- **If file doesn't exist**, create it with the header template
+- **Entry format**: H3 date header, bullet list with Context, Lesson, Pattern, Files, Agent
+- **Active Rules**: At the top, keep 5-10 distilled patterns from recent entries. If adding a new entry makes it necessary, add a rule too or promote a pattern from an entry.
+- **Deduplicate**: Don't repeat the same lesson. If the same lesson comes up again, update the existing entry's date instead.
+- **Be specific**: "Always use strictNullChecks" not "TypeScript is good"
+- **Agent tag**: Use the subagent name (thor, tyr, heimdall, mimir, etc.)
+
+## Setup
+
+For a new project where no such file exists yet, create the initial file:
+
+```
+# Self Improvement
+
+Template for project-specific agent learning. Entries are auto-appended by Odin
+at task completion and read at session start.
+
+## Active Rules
+
+<!-- Top 5-10 actionable patterns extracted from recent entries -->
+
+## Log
+```