@polderlabs/bizar 2.3.0

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

package/config/skills/embedded-esp-idf/references/logging-discipline.md

@@ -0,0 +1,118 @@
+# 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)`.