device-envoy AGENTS.md

Coding Notes for Agents

This file contains both shared workspace rules and crate-specific rules for this repository.

General Policies

• When autonomous work is interrupted or reaches a stopping point, report the current status, what remains, and the recommended next step. If the next step is within the current task and safe to perform, perform it rather than stopping merely to recommend it.

• In this repository, devolve means inlining a code element's behavior at its call sites (or into its containing function) and deleting the original struct, enum, helper, or other abstraction. Prefer the clearer term inline in prose when there is no need for the project-specific shorthand.

• Never silently skip required build targets in xtask/CI. Every supported target (e.g., ESP32-C6, ESP32-S3, Pico 1, Pico 2) must be built on every check-all run. If a required toolchain component is missing, fail loudly with a clear error message and instructions to install it — do not skip or silently ignore the missing target. Silent skips hide real breakage.

• When loading data from flash (or any other storage) into a local variable, name the variable after the concrete type. Example: DeviceConfig data should live in variables like device_config, not generic config or flash0.

• Avoid introducing unsafe blocks. If a change truly requires unsafe, call it out explicitly and explain the justification so the user can review it carefully.

• Avoid silent clamping; prefer asserts or typed ranges so out-of-range inputs fail fast.

• Prefer no_run doctests; use ignore only when absolutely necessary (and call out why). Running doctests is best when possible, but rarely feasible for embedded code.

• Always use rust,no_run in doctest fences, not just no_run.

• For programs that should run forever, use pending().await instead of a timer loop.

• Hide boilerplate in doctests using the # prefix (e.g., # #![no_std]). Hide lines that are noise to the reader but required for compilation: #![no_std], #![no_main], and standard imports like use embassy_executor::Spawner;. Keep only the essential code showing how to use the API. See the crate-specific sections below for platform-specific imports to hide or show.

• When adding docs for modules or public items, link readers to the primary struct and keep the single compilable example on that struct; other items should point back to it rather than duplicating examples.

• Prefer const values defined in the local context (inside the function/example) rather than at module scope when they're only used there.

• Do not add redundant just recipes that only mirror an existing cargo alias/command. If the behavior is the same, keep only the cargo command.

• For cargo aliases that target embedded triples, include --no-default-features unless there is an explicit, documented reason to keep default features enabled.