45 lines
3.0 KiB
Markdown
45 lines
3.0 KiB
Markdown
# 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
|
|
```
|
|
|
|
A first migration to the custom partition table may require `pio run --target erase`, but 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.
|