@polderlabs/bizar 9.0.0 → 10.0.7

package/.claude/worktrees/kanban-overhaul/config/skills/embedded-esp-idf/references/freertos-patterns.md

@@ -1,214 +0,0 @@
-# FreeRTOS patterns
-
-ESP-IDF v5 uses FreeRTOS. Most of these patterns are the same as FreeRTOS elsewhere; the ESP32-specific bits are task pinning, ISR rules (no blocking), and `portTICK_PERIOD_MS`.
-
-## Task lifecycle
-
-Create, run, delete:
-
-```cpp
-void acquisition_task(void *arg) {
-    while (true) {
-        // ... do work, sleep, wait on a queue ...
-    }
-    vTaskDelete(nullptr);  // never reached in a normal acquisition loop
-}
-
-void start() {
-    xTaskCreatePinnedToCore(
-        acquisition_task,            // task function
-        "acq",                       // name (shown in runtime stats)
-        4096,                        // stack depth in WORDS (not bytes) on ESP32
-        nullptr,                     // arg
-        20,                          // priority (0 = idle, higher = more preemptive)
-        nullptr,                     // optional task handle
-        1                            // core ID (0 = APP CPU on classic ESP32, 1 = PRO CPU)
-    );
-}
-```
-
-Notes:
-
-- Stack depth is in **words**, not bytes. On ESP32 (32-bit) `4096` = 16 KB. Allocate generously for tasks with deep call chains; oversized stack wastes DRAM but undersized stack corrupts memory silently.
-- Pass `nullptr` if you do not need the handle. Use the handle later for `vTaskSuspend` / `vTaskResume` / `vTaskDelete`.
-- Pinning is mandatory for acquisition paths — non-pinned tasks can bounce between cores and lose cache locality.
-
-`(AMS7)` AMS7 acquisition tasks run at priority 20+, pinned to core 0 (APP CPU). The PRO CPU (core 1) handles BLE/Wi-Fi by default.
-
-## Priorities
-
-| Range  | Use for                                                    |
-|--------|------------------------------------------------------------|
-| 0      | Idle task only — do not use                                |
-| 1–4    | Normal app tasks, command handling, BLE host               |
-| 5–19   | Latency-sensitive but not real-time (rate control, queues) |
-| 20–24  | Real-time acquisition, time-critical ISRs                  |
-
-Do not stack many tasks at priority 20+ — round-robin between them defeats the point.
-
-## Pinning to cores
-
-ESP32 dual-core (Xtensa LX6):
-
-- **Core 0 (APP CPU)** — protocol stacks (Wi-Fi, BLE), low-level drivers.
-- **Core 1 (PRO CPU)** — `app_main` runs here by default.
-
-Pick a split that puts time-critical work on the under-used core. `xTaskCreatePinnedToCore(handle, name, stack, arg, prio, handle_out, core_id)`.
-
-ESP32-S3 / C3 / H2 are single-core: pinning is a no-op but the API still works.
-
-## Queues
-
-Producer/consumer with bounded queues. Decouples ISR rate from task rate.
-
-```cpp
-QueueHandle_t evt_q = xQueueCreate(16, sizeof(uint32_t));
-
-// Producer (task context)
-uint32_t pin = read_pin();
-xQueueSend(evt_q, &pin, pdMS_TO_TICKS(10));
-
-// Consumer
-uint32_t pin;
-if (xQueueReceive(evt_q, &pin, portMAX_DELAY) == pdTRUE) {
-    handle(pin);
-}
-```
-
-Use `portMAX_DELAY` only when the consumer must never return. Use `pdMS_TO_TICKS(N)` when the consumer should time out (e.g., to check a "stop" flag).
-
-## ISR → task handoff
-
-ISRs must not block. The standard handoff uses `xQueueSendFromISR` and the higher-priority-task-woken flag:
-
-```cpp
-static QueueHandle_t gpio_evt_q;
-
-void IRAM_ATTR gpio_isr(void *arg) {
-    uint32_t pin = (uint32_t)arg;
-    BaseType_t hpw = pdFALSE;
-    xQueueSendFromISR(gpio_evt_q, &pin, &hpw);
-    if (hpw == pdTRUE) portYIELD_FROM_ISR();
-}
-
-void consumer_task(void *arg) {
-    uint32_t pin;
-    while (true) {
-        if (xQueueReceive(gpio_evt_q, &pin, portMAX_DELAY) == pdTRUE) {
-            // process pin (NOT in ISR context — can block here)
-        }
-    }
-}
-```
-
-Alternatives:
-
-- `xTaskNotifyFromISR` / `xTaskNotifyWait` — single-task notifications, very fast.
-- `xTimerPendFunctionCallFromISR` — defer a callback into the timer service task (useful for one-shot IRAM work).
-- Direct event bits with `xEventGroupSetBitsFromISR` — broadcast to multiple waiters.
-
-## Stream and ring buffers
-
-For variable-length byte streams (e.g., SPI DMA into a parser):
-
-```cpp
-StreamBufferHandle_t sb = xStreamBufferCreate(2048, 256);   // total, trigger
-// Producer (DMA ISR)
-xStreamBufferSendFromISR(sb, data, len, &hpw);
-// Consumer task
-uint8_t buf[256];
-size_t got = xStreamBufferReceive(sb, buf, sizeof(buf), pdMS_TO_TICKS(100));
-```
-
-`xRingbufferCreate` (IDF) is the lock-free variant — better for high-rate ISR streams where the producer must never wait.
-
-## Semaphores and mutexes
-
-```cpp
-SemaphoreHandle_t ready = xSemaphoreCreateBinary();
-xSemaphoreGive(ready);
-xSemaphoreTake(ready, portMAX_DELAY);
-
-SemaphoreHandle_t in_flight = xSemaphoreCreateCounting(4, 0);   // max 4, starts empty
-```
-
-Mutexes for shared resources:
-
-```cpp
-SemaphoreHandle_t cfg_lock = xSemaphoreCreateMutex();
-if (xSemaphoreTake(cfg_lock, pdMS_TO_TICKS(100)) == pdTRUE) {
-    // ... access shared resource ...
-    xSemaphoreGive(cfg_lock);
-}
-```
-
-**Recursive mutexes** (`xSemaphoreCreateRecursiveMutex`) for code that may take the same lock twice in a call chain.
-
-## Timers
-
-```cpp
-TimerHandle_t t = xTimerCreate("rate", pdMS_TO_TICKS(1000), pdTRUE, nullptr, [](TimerHandle_t x) {
-    // fired every 1000 ms; called in the timer service task (NOT ISR context)
-});
-xTimerStart(t, 0);
-```
-
-One-shot for delayed work:
-
-```cpp
-TimerHandle_t oneshot = xTimerCreate("once", pdMS_TO_TICKS(50), pdFALSE, nullptr, cb);
-xTimerStart(oneshot, 0);
-```
-
-## Event groups
-
-Useful when a task must wait for several subsystems to be ready before proceeding:
-
-```cpp
-EventGroupHandle_t eg = xEventGroupCreate();
-xEventGroupSetBits(eg, BIT_SD_READY | BIT_BLE_READY | BIT_ACQ_READY);
-
-EventBits_t bits = xEventGroupWaitBits(
-    eg,
-    BIT_SD_READY | BIT_BLE_READY | BIT_ACQ_READY,
-    pdFALSE,                  // don't clear on exit
-    pdTRUE,                   // wait for ALL bits
-    portMAX_DELAY
-);
-```
-
-## Watchdog
-
-The IDF task watchdog resets the system if a task does not feed it within a window. Always feed:
-
-```cpp
-void heavy_task(void *arg) {
-    while (true) {
-        // chunk of work
-        vTaskDelay(pdMS_TO_TICKS(10));          // yields — watchdog is fed by idle
-        // OR if you spin:
-        // vTaskDelay(1);                          // minimum yield
-    }
-}
-```
-
-If a task really must spin for >1 second (rare), subscribe it to the watchdog and call `esp_task_wdt_reset()` periodically. Long ISR-disabled windows also trip the watchdog — keep them < one tick (`portTICK_PERIOD_MS` = 10 ms by default).
-
-## portTICK_PERIOD_MS
-
-Always convert via `pdMS_TO_TICKS(ms)`:
-
-```cpp
-vTaskDelay(pdMS_TO_TICKS(100));      // 100 ms regardless of tick rate
-xQueueReceive(q, &x, pdMS_TO_TICKS(50));
-```
-
-Never multiply by hand (`ms * portTICK_PERIOD_MS`) — it lies when the tick rate changes.
-
-## Common pitfalls
-
-- **Blocking in an ISR.** Symptom: hard fault or watchdog reset. Fix: defer to a task via `xQueueSendFromISR` / `xTaskNotifyFromISR`.
-- **Stack too small.** Symptom: random crashes after a few minutes, often deep in call chains. Fix: bump stack depth, or enable `CONFIG_COMPILER_STACK_CHECK_MODE_NORM` to catch overflows at runtime.
-- **Priority inversion.** Symptom: low-priority task holds a mutex, blocks a high-priority task. Fix: `xSemaphoreCreateRecursiveMutex` and keep critical sections short.
-- **Forgetting `portYIELD_FROM_ISR`.** Symptom: producer wakes the consumer but the consumer doesn't run until the next tick. Fix: check the `xHigherPriorityTaskWoken` returned from `*FromISR` and yield.
-- **Non-pinned tasks bouncing cores.** Symptom: jittery timing, occasional cache misses. Fix: pin acquisition and protocol tasks explicitly.

package/.claude/worktrees/kanban-overhaul/config/skills/embedded-esp-idf/references/host-tests.md

@@ -1,164 +0,0 @@
-# Host-side tests
-
-ESP-IDF firmware that depends on FreeRTOS, drivers, and NVS cannot run on the host. But policy modules, payload encoders/decoders, pure-C++ algorithms, and protocol parsers can — and should — be unit-tested on the host with a normal C++ toolchain.
-
-`(AMS7)` AMS7's host tests are deliberately lightweight: one `.cpp` test file + one `run_*_test.sh` shell wrapper. No CMake host build, no fakes library, no GoogleTest. The whole test is `g++ -std=c++17 ... && ./a.out`.
-
-For larger projects with GoogleTest / Catch2 / fakes, see the **`cpp-testing`** skill.
-
-## AMS7 pattern (test + run script)
-
-A typical test file in `tests/connectivity/`:
-
-```cpp
-// tests/connectivity/espnow_imu_frame_test.cpp
-#include <cassert>
-#include <cstdio>
-
-#include "espnow_imu_frame.hpp"
-
-int main() {
-    core_espnow_imu_frame_v1_t frame = {};
-    espnow_imu_frame_init(&frame, 0x1234U, 9U, 55U,
-                          1, -2, 3, -4, 5, -6);
-
-    assert(frame.magic == CORE_ESPNOW_IMU_MAGIC);
-    assert(frame.version == CORE_ESPNOW_IMU_VERSION);
-    assert(frame.frame_type == CORE_ESPNOW_FRAME_IMU_RAW);
-    assert(frame.id == 0x1234U);
-    assert(frame.seq == 9U);
-    assert(frame.age_ms == 55U);
-    assert(frame.accel_x == 1);
-    assert(frame.accel_y == -2);
-    assert(frame.accel_z == 3);
-    assert(frame.gyro_x == -4);
-    assert(frame.gyro_y == 5);
-    assert(frame.gyro_z == -6);
-
-    std::puts("espnow_imu_frame_test: ok");
-    return 0;
-}
-```
-
-And the wrapper `tests/connectivity/run_espnow_imu_frame_test.sh`:
-
-```bash
-#!/usr/bin/env bash
-set -euo pipefail
-
-g++ -std=c++17 \
-  tests/connectivity/espnow_imu_frame_test.cpp \
-  main/connectivity/espnow_imu_frame.cpp \
-  -I main/connectivity \
-  -o /tmp/espnow_imu_frame_test
-
-/tmp/espnow_imu_frame_test
-```
-
-Run it:
-
-```bash
-bash tests/connectivity/run_espnow_imu_frame_test.sh
-```
-
-The wrapper does three things: compile, link, run. Add `g++` flags (`-Wall -Wextra -Werror`) for stricter checking.
-
-## What can be host-tested
-
-- **Packed structs and frame encoders** — `espnow_*_frame_*`, `gateway_command_*`, `marker_*`. Pure data marshalling.
-- **Policy modules** — `connectivity_mode_policy`, `electrode_detach_gate`, `acquisition_command_policy`. Pure decision logic.
-- **Pure algorithms** — `hr_fused`, `resp_fallback`, `summary_metrics`. Make sure they don't `malloc` or call FreeRTOS and they're trivially host-testable.
-- **State machines** — anything that's a transition table plus a few event handlers.
-
-## What must NOT be host-tested
-
-- Anything that includes `<freertos/FreeRTOS.h>`.
-- Anything that includes `esp_log.h` (unless you fake it).
-- Anything that includes driver headers (`driver/spi_master.h`, `driver/i2c.h`).
-- Anything that pulls in NVS, BLE, Wi-Fi, ESP-NOW stacks.
-
-If a header you want to test transitively includes one of these, factor the pure logic out into a separate translation unit. The split is usually: `policy.hpp/cpp` for pure logic, `policy_runtime.cpp` for the FreeRTOS-aware glue.
-
-## Fakes for FreeRTOS (when you need them)
-
-If you have a real CMake host project (not the AMS7 minimal pattern) and want to test code that touches FreeRTOS, use the **`cpp-testing`** skill's fakes recipe. The minimum useful fakes:
-
-- `fake_freertos.h` — declares the FreeRTOS API surface used by the code under test, with hooks (`xQueueCreate` returns a recorded handle, etc.).
-- `fake_log.h` — empty `ESP_LOG*` macros or a recorded message list.
-
-Keep fakes local to the test, not in `main/`. Use `BUILD_ONLY_FAKES` or a separate `tests/host/` CMake target.
-
-## CMake host project (alternative to per-test shell scripts)
-
-For larger suites:
-
-```cmake
-# tests/host/CMakeLists.txt
-cmake_minimum_required(VERSION 3.16)
-project(ams7_host_tests CXX)
-
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-
-add_executable(test_espnow_imu
-    ../../main/connectivity/espnow_imu_frame.cpp
-    espnow_imu_frame_test.cpp
-)
-target_include_directories(test_espnow_imu PRIVATE
-    ${CMAKE_SOURCE_DIR}/../../main/connectivity
-)
-```
-
-```bash
-cmake -S tests/host -B tests/host/build
-cmake --build tests/host/build
-./tests/host/build/test_espnow_imu
-```
-
-Tradeoffs vs the AMS7 minimal pattern:
-
-| Aspect           | AMS7 shell wrapper              | CMake host project        |
-|------------------|---------------------------------|---------------------------|
-| Setup cost       | Zero — one shell script per test| One CMakeLists to maintain |
-| Linking firmware | Direct `g++ ... file.cpp`       | Same, via CMake rules     |
-| Adding fakes     | None                            | Add a `fake/` directory   |
-| Test discovery   | Manual                          | `ctest`                   |
-| CI integration   | `find tests -name run_*.sh`     | `ctest --output-on-failure` |
-| Build parallelism| Sequential                      | Parallel via `cmake --build` |
-
-Both are valid. AMS7 picks the shell wrapper because every test is one file and one assertion set — `ctest` overhead is not worth it.
-
-## Tests vs fixtures
-
-AMS7 has `tests/fixtures/` for replay inputs (recorded sensor traces used to drive host tests):
-
-```cpp
-// tests/fixtures/replay/ecg_2024-09-12.bin  — raw bytes recorded from a real run
-```
-
-Load fixtures in tests via `std::ifstream` rather than copy-pasting bytes into the test source.
-
-## Common pitfalls
-
-- **Including `<esp_log.h>` from a header that's host-tested.** Fix: forward-declare the log macros in the header, include the real one only in `.cpp`. Or include the AMS7 fake `tests/support/host_include/esp_log.h` if one exists.
-- **`malloc` in pure logic.** Symptom: host test runs fine but firmware crashes from fragmentation. Fix: allocate in the wrapper, pass a buffer in.
-- **Globals with static initialization.** Symptom: works on host, fails on target because init order is different. Fix: prefer explicit `init()` calls.
-- **Asserting on floating-point equality.** Use a tolerance: `assert(std::abs(a - b) < 1e-3)`.
-- **Forgetting `-Werror` in CI.** Compile-only warnings become ship-time bugs. The AMS7 host tests are silent on warnings by default; consider adding `-Wall -Wextra` to your shell wrappers.
-- **Test passes on host, fails on firmware.** The two are usually equivalent for pure logic, but always cross-check with a firmware-side integration test (a debug print, a recorded trace, or an ESP-NOW roundtrip).
-
-## When to grow beyond the minimal pattern
-
-Stay with the shell wrapper while:
-
-- Test count is < ~30.
-- Each test is one `.cpp` plus one shell script.
-- No fakes needed.
-- CI just iterates `tests/ -name run_*.sh`.
-
-Migrate to a CMake host project when:
-
-- You need `ctest` for CI parallelism and reporting.
-- You need fakes (FreeRTOS, log, drivers).
-- A test needs to link multiple firmware modules together.
-- You want fixtures automatically discovered.

package/.claude/worktrees/kanban-overhaul/config/skills/embedded-esp-idf/references/idf-py-commands.md

@@ -1,157 +0,0 @@
-# idf.py commands
-
-`idf.py` is the single entry point to ESP-IDF v5. All commands assume the IDF environment is sourced:
-
-```bash
-source esp/esp-idf/export.sh
-```
-
-If `idf.py` is not on PATH, `scripts/idf_env.sh` will print the source line and tell you whether the env is healthy.
-
-## Core workflow
-
-```bash
-idf.py build                       # compile (incremental)
-idf.py -p /dev/ttyUSB0 flash       # write image to board
-idf.py -p /dev/ttyUSB0 monitor     # serial console (Ctrl-] to exit)
-idf.py -p /dev/ttyUSB0 flash monitor   # flash then monitor in one shot
-```
-
-`-p` is the serial port. Linux: `/dev/ttyUSB0` or `/dev/ttyACM0`. macOS: `/dev/cu.usbserial-*`. Windows: `COM3`.
-
-## Configuration
-
-```bash
-idf.py menuconfig                  # TUI Kconfig editor
-idf.py menuconfig --no-target      # don't ask to set target
-idf.py save-defconfig              # write minimal defconfig from current settings
-```
-
-`menuconfig` writes the result to `sdkconfig`. To apply a layered profile:
-
-```bash
-idf.py -B build_espnow_flow -C . \
-       --sdkconfig sdkconfig.espnow_flow \
-       build flash
-```
-
-The `-B build_<name>` puts the build output in `build_<name>/`, leaving the default `build/` clean.
-
-## Build inspection
-
-```bash
-idf.py size                        # text: app partition + IRAM + DRAM
-idf.py size --format json          # machine-readable for tooling
-idf.py size --format csv           # spreadsheet-friendly
-idf.py size --output-file size.json
-idf.py size-components             # per-component breakdown
-```
-
-`idf.py size` exit code is 0 on success regardless of size; size policy lives in project-specific tools.
-
-## Cleaning
-
-```bash
-idf.py clean                       # remove build artifacts but keep config
-idf.py fullclean                   # remove build/ AND sdkconfig (then menuconfig again)
-idf.py -B build_espnow_flow clean  # clean a specific build dir
-```
-
-`fullclean` is destructive — it deletes your local `sdkconfig` overrides. Commit your `sdkconfig` and any profile files first.
-
-## Target and project
-
-```bash
-idf.py set-target esp32            # esp32 / esp32s2 / esp32s3 / esp32c3 / esp32h2
-idf.py create-project foo          # scaffold a new project from a template
-idf.py add-dependency "owner/repo^1.2.3"   # pull into managed_components/
-```
-
-After `set-target`, ESP-IDF regenerates component configs — clean build artifacts:
-
-```bash
-idf.py set-target esp32s3 && idf.py build
-```
-
-## Partition table
-
-```bash
-idf.py partition-table             # regenerate partition_table/*.bin from partitions.csv
-idf.py erase-flash                 # erase entire flash (use with care)
-```
-
-`partitions.csv` is at the project root; `idf.py menuconfig → Partition Table` selects which CSV to use. Common layouts:
-
-- `partitions_singleapp.csv` — single OTA-less app partition
-- `partitions_two_ota.csv` — A/B OTA slots (default for OTA-enabled projects)
-- A custom CSV — declare `app`, `data`, `nvs`, `phy_init`, `storage` partitions with explicit sizes
-
-`(AMS7)` The AMS7 partition table reserves a large `storage` partition for SD-aware OTA staging.
-
-## Monitor filters
-
-```bash
-idf.py -p /dev/ttyUSB0 monitor --print-filter="*:I"          # only INFO and above
-idf.py monitor --print-filter="ams7driver:I espnow_summary:W" # per-tag levels
-idf.py monitor --elf <elf_path>                             # decode panic backtraces
-```
-
-`-d` disables line-ending conversion (binary output). `-t` adds a timestamp prefix.
-
-Inside the monitor, useful key bindings:
-
-- `Ctrl-]` — exit
-- `Ctrl-T` — toggle menu (send break, change filter, etc.)
-
-## Build flags
-
-```bash
-idf.py -DCMAKE_BUILD_TYPE=Debug build          # Debug / Release / RelWithDebInfo / MinSizeRel
-idf.py -DCONFIG_COMPILER_OPTIMIZATION_PERF=y build   # enable IDF performance optimizations
-idf.py -DSDKCONFIG_DEFAULTS=sdkconfig.espnow_flow build
-```
-
-`-DSDKCONFIG_DEFAULTS` is equivalent to the `--sdkconfig` CLI flag and is useful for CI.
-
-## OpenOCD / debugging
-
-```bash
-idf.py openocd                     # start OpenOCD for JTAG debugging
-idf.py gdb                         # start xtensa-esp32-elf-gdb
-idf.py gdbgui                      # GDB with a frontend
-idf.py app-flash                   # flash only the app partition
-idf.py bootloader-flash            # flash only the bootloader
-```
-
-GDB requires an `openocd` server on the default port (3333).
-
-## OTA
-
-```bash
-idf.py app                         # build the app, ready for OTA push
-idf.py ota                         # ... or `idf.py app` then push via HTTP
-```
-
-For SD-card OTA staging: copy `build/<project>.bin` to the SD card under the OTA path your bootloader expects, then reboot.
-
-## Useful exit-code patterns
-
-```bash
-# CI: build, then size check
-idf.py build && idf.py size
-
-# AMS7: full CI gate
-source esp/esp-idf/export.sh
-idf.py build
-tools/check_idf_size_budget.py
-```
-
-`scripts/size_check.sh` wraps the AMS7-specific size policy and falls back to `idf.py size` when run in a non-AMS7 project.
-
-## Common pitfalls
-
-- **Forgot to source the env.** Symptom: `idf.py: command not found`. Fix: `source esp/esp-idf/export.sh` per shell session.
-- **Wrong target.** Symptom: linker errors about `esp_image_header_t` size mismatches or missing `esp_hw_support`. Fix: `idf.py set-target esp32` then rebuild.
-- **`sdkconfig` drift.** Symptom: subtle behavior changes after a `git pull`. Fix: `idf.py menuconfig` to re-resolve, or `git checkout sdkconfig` and re-apply.
-- **`-B build_<flow>` left stale.** Symptom: build picks up old sources. Fix: `idf.py -B build_<flow> fullclean`.
-- **Monitor hangs on macOS.** Use `/dev/cu.usbserial-*` not `/dev/tty.usbserial-*` (the `tty.` node blocks open while the driver holds it).

package/.claude/worktrees/kanban-overhaul/config/skills/embedded-esp-idf/references/kconfig.md

@@ -1,159 +0,0 @@
-# Kconfig
-
-Kconfig is the build-time configuration system ESP-IDF inherits from the Linux kernel. Options live in `Kconfig` files, are presented through `idf.py menuconfig`, and resolve to `CONFIG_*` macros visible in C/C++.
-
-## Where Kconfig files live
-
-ESP-IDF automatically sources a `Kconfig` file from every registered component. The top-level `Kconfig.projbuild` is required and seeds the project menu. Conventions:
-
-- `main/Kconfig` — app-level options. Always include `main "AMS7 Project Options"` style menus.
-- `components/<name>/Kconfig` — component-private options; only visible if the component is included in the build.
-- `Kconfig.projbuild` — root-level options that gate top-of-tree decisions.
-
-`(AMS7)` AMS7 puts its entire menu under `main/Kconfig` (single file, ~430 lines), with the menu title `"AMS7 Project Options"`. Every project-defined option uses the `AMS7_*` prefix.
-
-## Adding a simple bool option
-
-```kconfig
-menu "Connectivity Workflow"
-
-config AMS7_SUMMARY_ENABLE
-    bool "Enable ESP-NOW summary workflow"
-    default n
-    help
-        Master switch for the recording workflow that starts with BLE
-        control and then switches to ESP-NOW summary mode after
-        acquisition begins. Keep disabled to preserve the BLE-only
-        workflow.
-
-endmenu
-```
-
-The `CONFIG_AMS7_SUMMARY_ENABLE` macro is then visible everywhere in C/C++:
-
-```cpp
-#if CONFIG_AMS7_SUMMARY_ENABLE
-    init_espnow_summary();
-#endif
-```
-
-## Types
-
-| Type        | C macro                              | Notes                                  |
-|-------------|--------------------------------------|----------------------------------------|
-| `bool`      | `CONFIG_FOO` (1 or undefined)        | `default y` or `default n`             |
-| `int`       | `CONFIG_FOO` (int literal)           | `range MIN MAX` is recommended         |
-| `hex`       | `CONFIG_FOO` (hex literal)           | Useful for bitmasks and addresses      |
-| `string`    | `CONFIG_FOO` (string literal)        | `default "literal"`                    |
-| `choice`    | selects one of several values        | Use for mutually-exclusive options     |
-
-```kconfig
-config AMS7_HR_HOLD_MS
-    int "Hold time for fused HR before fallback (ms)"
-    depends on AMS7_VITALS_ENABLE
-    range 0 60000
-    default 10000
-    help
-        How long to keep reporting fused HR after the fused pipeline
-        reports a confident beat, before falling back to the simple
-        backend. 0 disables the hold.
-```
-
-In code:
-
-```cpp
-#if CONFIG_AMS7_HR_HOLD_MS > 0
-    const TickType_t kHoldTicks = pdMS_TO_TICKS(CONFIG_AMS7_HR_HOLD_MS);
-#endif
-```
-
-`menuconfig` values are stored in `sdkconfig` as `CONFIG_<NAME>=<value>` lines. `idf.py menuconfig` is the editor.
-
-## Dependencies and implications
-
-```kconfig
-config AMS7_BLE_VITALS_ENABLE
-    bool "Enable custom BLE vitals characteristic"
-    depends on AMS7_VITALS_ENABLE
-    default y
-```
-
-- `depends on AMS7_VITALS_ENABLE` — option is **invisible** unless `AMS7_VITALS_ENABLE=y`. Selecting it auto-selects the dep.
-- `select AMS7_ESPNOW_ENABLE` — when **this** option is enabled, force `AMS7_ESPNOW_ENABLE=y`.
-- `imply AMS7_ESPNOW_LIVE_ECG_ENABLE` — when **this** option is enabled, set `AMS7_ESPNOW_LIVE_ECG_ENABLE=y` unless the user explicitly disabled it (softer than `select`).
-
-`select` chains can cause cycles if used carelessly — prefer `depends on` for prerequisites.
-
-## Ranges
-
-```kconfig
-config AMS7_ESPNOW_WIFI_CHANNEL
-    int "ESP-NOW Wi-Fi channel"
-    range 1 13
-    default 6
-```
-
-The value is validated by menuconfig; `range` rejects out-of-range entries.
-
-## Choices
-
-```kconfig
-choice AMS7_HR_BACKEND
-    prompt "Heart-rate backend"
-    default AMS7_HR_BACKEND_FUSED
-    depends on AMS7_VITALS_ENABLE
-
-config AMS7_HR_BACKEND_SIMPLE
-    bool "Simple R-peak detector"
-
-config AMS7_HR_BACKEND_FUSED
-    bool "Fused multi-source pipeline"
-
-endchoice
-```
-
-Only one of the listed `config`s can be `y` at a time. Use `# CONFIG_AMS7_HR_BACKEND_FUSED is not set` to switch.
-
-## Sourcing custom Kconfig files
-
-In a component's top-level `Kconfig` (sourced automatically), include sub-files:
-
-```kconfig
-mainmenu "My Component"
-
-menu "Sensor Options"
-source "Kconfig.sensor"
-endmenu
-```
-
-Or in `CMakeLists.txt`, register the file as part of the component:
-
-```cmake
-idf_component_register(
-    ...
-    KCONFIG
-        "Kconfig"
-)
-```
-
-For project-wide overlays, create `sdkconfig.espnow_flow` (or similar) and pass `--sdkconfig` to `idf.py`. Layers are applied in order: defaults, then `sdkconfig`, then any `--sdkconfig` files.
-
-## Help text
-
-Always include a `help` block. menuconfig shows it on the option's help line; the project documentation pulls it from `Kconfig` when generating reference. Keep it under ~10 lines.
-
-## AMS7 conventions (project-specific)
-
-- Prefix every project-defined option with `AMS7_`. Never use `CONFIG_FOO` for an AMS7-introduced symbol.
-- Group options by feature in `menu "..."` blocks. AMS7 groups: Connectivity Workflow, Vitals, ESP-NOW, Logging, etc.
-- Default to `n` for any feature that increases IRAM/flash — acquisition builds are size-sensitive.
-- For "trial debug" toggles, name them `*_TRIAL_DEBUG_LOG_ENABLE` and gate `ESP_LOG*` calls behind them — never compile trial-debug logs into release by default.
-- Add a `help` block on every option. AMS7 reviewers check for missing help text.
-
-## Common pitfalls
-
-- **Forgetting `default`.** menuconfig prompts for a value on first use; this is annoying. Always set a sensible default.
-- **`select` cycle.** `A select B; B select A` causes menuconfig to error. Use `depends on` instead.
-- **Component Kconfig included in disabled component.** If a component's Kconfig has options, that component must be discoverable. Check `EXTRA_COMPONENT_DIRS` in `CMakeLists.txt`.
-- **Renaming an option without a migration.** Renaming `AMS7_X` to `AMS7_Y` leaves `sdkconfig` referring to the old name. `menuconfig` will silently drop the new option. Fix: add a `config AMS7_Y` with `default AMS7_X` then remove `AMS7_X`.
-- **`range` on a `bool`.** Doesn't make sense — Kconfig will refuse. Use a `choice` instead.