# AGENTS

ALWAYS COMPACT YOUR CONTEXT FIRST!

## Map

- Root has workspace files.
- `examples/` has one crate per demo.
- `docs/hardware/` has board and wiring notes.
- `memory.x` is shared.
- `justfile` is source of truth for commands.

## Rules

- Read before edit.
- Keep fixes small.
- No broad refactor.
- No dependency upgrade unless asked.
- Keep examples independent.
- Keep demo reliability first.
- Use simple code.
- No hidden IDE steps.
- No fake hardware claims.

## Preserve

- `nix develop`
- `just fmt`
- `just check`
- `just build`

## Hardware

- Blue Pill first.
- `thumbv7m-none-eabi` first.
- Do not mix STM32F0 with STM32F103.
- If hardware detail is unclear:
  - write the assumption
  - add a TODO
  - keep build green

## Style

- Caveman style.
- Short names.
- Short comments.
- Explain embedded idea.
- Every Rust function we write except the main must have a short description header comment following rust best practice
- Do not explain obvious Rust syntax.
- No heap.
- No dynamic dispatch unless teaching needs it.
- No async before Embassy examples.
- `unsafe` only if required and justified.

## Commands

- `just build`
- `just build-blinky`
- `just build-timer`
- `just build-button`
- `just build-embassy-blinky`
- `just build-embassy-button`
- `just flash-blinky`
- `just flash-timer`
- `just flash-button`
- `just flash-embassy-blinky`
- `just flash-embassy-button`
- `just run-blinky`
- `just run-embassy-blinky`
- `just fmt`
- `just clippy`
- `just check`
- `just clean`

## Do Not

- Do not invent board output.
- Do not claim flash or debug worked on hardware unless tested.
- Do not hide chip mismatches.
- Do not add abstractions for one use.