@polderlabs/bizar 10.7.2 → 10.10.0

package/.claude/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/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/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.

package/.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)`.