@polderlabs/bizar 6.2.5 → 6.3.0

package/.claude/skills/embedded-esp-idf/references/freertos-patterns.md

@@ -0,0 +1,214 @@
+# 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/skills/embedded-esp-idf/references/host-tests.md

@@ -0,0 +1,164 @@
+# 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/skills/embedded-esp-idf/references/idf-py-commands.md

@@ -0,0 +1,157 @@
+# 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/skills/embedded-esp-idf/references/kconfig.md

@@ -0,0 +1,159 @@
+# 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.