ZephCore/AGENTS.md

# AGENTS.md

Rules for AI-assisted contributions to ZephCore. They apply to human contributors too. Read the section of
`docs/DESIGN.md` (invariants, layer rules) and `docs/ARCHITECTURE.md` (component reference) for the area you
touch before writing code. Decisions are in `docs/adr/`.

## How a change is judged

1. **Find the root cause.** The PR states the cause and the evidence for it (datasheet section, register dump,
   log, trace). If the cause is not known, say so; do not ship a guess.
2. **No band-aids.** Do not add a retry, delay, timeout, re-init, read-back check or watchdog to make a symptom
   go away. Recovery code is accepted only for a named, understood hardware failure, in the layer that owns the
   state, with its bound (`docs/DESIGN.md` §8.7). There is no hardware watchdog and none will be added.
3. **The smallest change that fixes it.** Close what is reachable today, not what might be reachable later. No
   speculative guards, build asserts, new abstractions, options or refactors riding along. One concern per PR.
   If the diff is larger than the bug, expect to be asked to cut it.
4. **Do what upstream MeshCore does** when it already solves the problem, unless ours can be more accurate at no
   compatibility cost (`docs/DESIGN.md` §9).
5. **Comment diet.** A comment says what the code does or the invariant it keeps, in a few lines. Rationale,
   history, incidents, measurements and rejected alternatives go in the PR description and `docs/`, not in code.
   Do not comment the obvious.
6. **Fix it for every board.** A fix or feature that concerns behaviour goes in the common path, for all
   platforms and roles. Do not scope it to the board or SoC family where it was found or tested, and do not
   exclude a platform because the problem cannot happen there today; a later port or Zephyr bump can make it
   real. Untested boards still get the change; the PR says which hardware it ran on.
7. **Gate on the capability, never on the name.** The only reason to gate code is that the hardware is absent,
   and the test for that is a devicetree node or property, or a Kconfig symbol for the feature. Never
   `CONFIG_SOC_*`, `CONFIG_BOARD_*` or a board name as a stand-in for "has this part" or "has this bug". A board
   that lacks the hardware then carries no code for it, and a new board that has it gets the behaviour for free.
8. **A real platform difference is stated as one.** If something truly is specific to one SoC or chip (an
   erratum, a vendor blob, a peripheral that exists nowhere else), it lives in that platform's layer and the PR
   cites the source that makes it specific. "Only seen on X" is not that.

## Invariants: do not change without an ADR

- Byte compatibility with Arduino MeshCore on the air and on the companion protocol; `prefs.json` format.
- The wall clock only moves forward.
- Mesh, GPS state and UI run on the main thread; loops are event-driven, no polling.
- No heap in the packet path. Companion builds are RAM-bound.
- Never write to a peripheral that was not cleanly identified first.
- BLE: no proactive SMP Security Request, keep `BT_LE_ADV_OPT_USE_IDENTITY` (ADR 0004), leave connection
  parameters alone.
- Files ported from MeshCore (listed in `.editorconfig`) keep upstream's text verbatim; every change in them is
  fenced `// ZEPHCORE:`. Do not restyle or de-duplicate them.
- `zephcore/patches/zephyr`: one patch owns each Zephyr file.
- `board.conf` does not repeat what a parent conf or the devicetree already provides.

## Mechanics

- Branch from `dev`, target `dev`, rebase instead of merging.
- Tabs for indentation, except the upstream-ported files.
- Build with `--pristine` when the board or role changes; ESP32 S3/C-series repeaters need `--sysbuild`.
- Host tests: `python3 tests/run.py run --profile quick` (Linux or WSL). A new case needs a
  `tests/catalog.json` entry.
- New board: `zephcore.yml` without `release:`, then `python zephcore/scripts/board_manifest.py check` and
  `... docs`.
- Docs in the same PR: a clause in `docs/ARCHITECTURE.md` when behaviour, an interface or a limit changes;
  `docs/CLI_commands.md` for any CLI change; an ADR when a decision is taken or reversed.

## PR description

- Cause, fix, and what was deliberately left out.
- Which boards it was built for, and which hardware it actually ran on. Never claim hardware verification that
  was not done.
- Flash and RAM delta when code is added to a common path.