# Agent instructions

## Start with project memory

1. Read `docs/agent/code-map.md` before broad repository exploration.
2. Read the relevant sections of `docs/agent/architecture.md` and `docs/agent/design-decisions.md` before changing cross-cutting behavior.
3. Read `docs/agent/current-state.md` when resuming work or investigating recent changes.
4. Use these files to identify the smallest relevant source set before searching or reading code.
5. Verify stored knowledge against implementation whenever it may be stale or correctness depends on exact behavior. Source code is authoritative.
6. Do not repeatedly scan unrelated modules. Prefer targeted symbol searches and representative header/implementation reads.
7. Update durable agent documentation only when architecture, contracts, ownership, or module responsibilities genuinely change.
8. During long-running tasks, keep `docs/agent/current-state.md` current and update it before handoff or context compaction.
9. Keep temporary debugging notes and speculative hypotheses out of `architecture.md` and `design-decisions.md`; use `current-state.md` instead.
10. Treat `GPT-logs/` as non-authoritative history. Confirm any useful claim against current source.
11. Avoid `managed_components/`, `third_party/`, generated `src/web_assets_data.*`, compressed assets, minified libraries, `compile_commands.json`, `dependencies.lock`, and broad `sdkconfig.*` inspection unless the task specifically requires them.

## Project constraints

- This is ESP-IDF firmware for one physical UART1/MAX3243 RS-232 port shared through USB CDC, HTTPS/WebSocket, and SSH.
- Preserve the broker model: exactly one writer, multiple isolated observers.
- Preserve UART0 as the administrative recovery path and native USB as network-independent UART1 access when network services fail.
- Keep serial transport binary-transparent; do not add in-band control sequences.
- Treat bounded queues, buffers, task ownership, generation tokens, and failure isolation as correctness properties, not incidental implementation details.
- Never expose passwords, private keys, Wi-Fi secrets, ticket values, or verifier material through routine status, logs, completion, or the local display.
- Do not regenerate embedded web assets unless the task explicitly requires it. See `web_assets/SOURCES.md` for provenance and generation policy.

## Build and device commands

The normal build, verified from `platformio.ini` and `README.md`, is:

```sh
pio run
```

Upload and monitor commands documented by the project are:

```sh
pio run --target upload
pio device monitor -b 115200
```

The first migration from the former default/factory layout to the custom partition table requires `pio run --target erase`. Erasing destroys persisted configuration and credentials; never run it without explicit user approval.

No automated host test command is defined in the repository. Hardware validation procedures live in `docs/electrical_tests.md` and `docs/user_administration_tests.md`; do not claim they passed unless actually performed.