ESP32_Serial_Swiss_Army_Knife/AGENTS.md

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:

pio run

Upload and monitor commands documented by the project are:

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.