Add Project Guidance For Agents

docs/agent/architecture.md

@@ -0,0 +1,190 @@
+# Architecture
+
+## Purpose and system shape
+
+This ESP32-S3 firmware exposes one MAX3243-backed UART1 RS-232 port through three bounded transport families:
+
+- native USB CDC-ACM, which is local and unauthenticated;
+- authenticated HTTPS with a browser WebSocket terminal;
+- authenticated SSH.
+
+UART0 remains a separate trusted administration and recovery console. A local OLED and three buttons provide status and a deliberately limited control surface. Persistent application configuration and security material are stored in versioned NVS blobs.
+
+The central data-path invariant is one serial writer with multiple observers:
+
+```text
+USB CDC ---------\
+WebSocket --------> session broker <--> serial service <--> UART1 <--> MAX3243
+SSH role=user ---/       |                         
+                         +-- one writer lease
+                         +-- bounded output per observer
+
+SSH role=admin ------> shared administration dispatcher <------ UART0
+                       (does not join the broker)
+```
+
+## Startup and initialization
+
+`app_main()` in `src/main.c` is the composition root. The implemented order matters:
+
+1. Report PSRAM and initialize the sole secure DRBG before Wi-Fi or other radio use.
+2. Initialize boot-critical RGB LED state, RS-232 ownership/static-safe hardware, diagnostics, and the shared administration dispatcher resources.
+3. Attempt optional OLED initialization and a bounded boot animation. Display failure is nonfatal; a working display can delay later recovery services by about five seconds.
+4. Initialize button diagnostics and load local-UI and serial configurations, falling back to RAM defaults on load failure.
+5. Initialize the serial service, session broker, and permanent USB transport task. UART1 is not started automatically here.
+6. Load/generate HTTPS material, then initialize the user database using the legacy web credential for first migration when available. User-database failure makes network authentication fail closed.
+7. Initialize the HTTPS runtime, SSH host-key material, and permanent SSH owner task.
+8. Load Wi-Fi configuration, persist generated first-boot defaults when appropriate, initialize its manager, and start it when configured for boot.
+9. Start HTTPS and SSH only when their startup gates pass. Current code requires Wi-Fi and HTTPS security readiness for both; SSH additionally requires its own security/runtime readiness. The HTTPS-security gate on SSH is an implemented dependency even though SSH has a separate host key.
+10. Start the local status/control task if button initialization succeeded.
+11. Construct ESP-IDF's UART REPL to initialize `esp_console`, but do not start the stock REPL task. Register command groups, install completion, and start the custom UART frontend that feeds the shared dispatcher.
+
+Several core initializers use `ESP_ERROR_CHECK`; optional display and network/security paths generally log failure while retaining UART0 administrative recovery and network-independent UART1 access through USB.
+
+## Serial service and physical ownership
+
+`serial_service` owns the UART1 driver while running. It exposes bounded RX/TX streams and a task that:
+
+- continuously drains UART RX, even if UART event notification is incomplete;
+- moves pending TX to the UART FIFO without blocking indefinitely on CTS;
+- discards and accounts queued traffic during shutdown/reconfiguration.
+
+`rs232_port_owner` separately protects the physical UART/MAX3243 resource:
+
+- `NONE`: available;
+- `PHASE0`: hardware diagnostics own it;
+- `SERVICE`: serial service owns it;
+- `FAULT`: cleanup could not establish a safe state; reboot is required.
+
+Diagnostics and the production service must claim this owner before manipulating UART/GPIO state. Unsafe cleanup keeps the transceiver disabled and marks a fault rather than attempting continued operation.
+
+Serial configuration is a working RAM value. Applying it while running performs a stop/restart and attempts rollback on failure; queued data may be discarded. Persistence is explicit through save/reset commands.
+
+## Session broker and data flow
+
+The permanent `session_broker` task is the intended sole consumer/producer of serial-service data.
+
+### RS-232 to clients
+
+```text
+UART RX -> serial-service RX stream -> broker task
+        -> independent bounded output stream for every connected client
+        -> USB / WebSocket / SSH transport output
+```
+
+The broker drains serial input even with no clients. A full client output stream drops only that client's copy and updates drop counters; it does not block UART reception or other clients.
+
+### Clients to RS-232
+
+```text
+transport input -> broker write check -> serial-service TX stream -> UART TX
+```
+
+Only the generation-safe client ID holding the current writer lease may enqueue input. All connected clients, including the writer, observe UART output. Normal requests acquire the lease only when free; disconnect releases it. Administrative APIs can force reassignment or compare-and-release an expected writer.
+
+Broker events are advisory bounded notifications. Transports reconcile against authoritative snapshots because an event queue can overflow. `DTR_ON_CONNECT` follows whether any broker client is connected, not writer ownership.
+
+## Transport architecture
+
+### USB CDC
+
+`usb_cdc_transport` has a permanent transport task and TinyUSB callbacks. Attached plus host DTR asserted is treated as open. Opening starts the serial service if necessary, creates the `usb-cdc` broker client, and opportunistically requests writer ownership; otherwise USB observes.
+
+TinyUSB callbacks enqueue/copy data and state; the transport task owns broker lifecycle and forwarding. Supported host line coding can update the RAM serial configuration only while USB is writer, the serial service is running, and TX is empty. It is not automatically persisted.
+
+### HTTPS, WebSocket, and web serial
+
+`web_server` runs HTTPS only on port 443 using the device-specific self-signed P-256 certificate from `web_security`. Current routes provide the UI, static assets, status, ticket issuance, and serial WebSocket upgrade.
+
+HTTP Basic authentication uses `user_database`, not the legacy recovery credential. Both `user` and `admin` roles currently receive the same web status/terminal experience; web administration is not implemented.
+
+A WebSocket connection requires a one-time, 30-second, principal-bound ticket. Ticket issuance and upgrade also validate a supplied `Origin` against `https://<Host>`; absence of `Origin` is accepted for non-browser clients. Tickets are stored as digests, consumed before currentness validation, and are never persisted. An admitted session starts the serial service if necessary, creates a broker client, and opportunistically requests writer ownership. The web transport has two fixed session slots. Binary frames carry serial data; small text messages request or release writer ownership. HTTPD owns socket send/close operations, while the web transport task mediates broker work through bounded scheduling.
+
+Web serial initialization is failure-isolated from the base HTTPS service: if the transport cannot initialize, `web_server_init()` can still succeed and serve authenticated non-WebSocket routes.
+
+`web_ui.c` contains authored index/application strings. `web_assets_data.c` contains checked-in generated arrays for vendored compressed xterm assets and the logo. Normal builds compile these arrays directly; they do not regenerate assets.
+
+### SSH
+
+`ssh_transport` uses wolfSSH on port 22 with two fixed session/handshake slots. One owner task pinned to core 1 is the only project task that calls wolfSSH APIs. It enforces bounded handshakes, authentication attempts, receive work, and session buffers.
+
+Authentication uses user-database passwords or stored Ed25519/ECDSA-P256 public keys. Public-key lookup authorizes a username/key pair, while wolfSSH verifies signed proof of possession. SSH host identity is a separate persisted P-256 key managed by `ssh_security`.
+
+Routing follows the authenticated role:
+
+- `user`: start the serial service if necessary, then create a broker-backed binary-transparent serial stream and opportunistically request writer ownership;
+- `admin`: bounded administration console, with no broker client or writer lease.
+
+There is no `exec`, SFTP, SCP, subsystem, agent forwarding, or TCP forwarding support.
+
+## Authentication, authorization, and revocation
+
+`user_database` is a fixed-capacity, mutex-protected store: at most eight accounts and three authorized keys per account. Accounts have `user` or `admin` role, random account ID, and authentication generation. Passwords are salted PBKDF2-HMAC-SHA256 verifiers; plaintext passwords are not retained in the database.
+
+Network code holds copied, secret-free principals rather than pointers into database records. Principal currentness requires matching username, account ID, role, and authentication generation. Password, role, or key changes increment the generation; deletion/recreation also changes the account ID.
+
+Revocation has two layers:
+
+1. command-layer account mutations explicitly request targeted WebSocket/SSH revocation;
+2. transports periodically and at sensitive boundaries recheck principal currentness, providing fail-safe closure if notification fails.
+
+The final administrator cannot be deleted or demoted. UART0 is trusted for initial administrator bootstrap and explicit unavailable-database recovery. Authenticated admin SSH can run the operational registry but is denied those two recovery operations. The legacy `web_sec` username/password remains migration/recovery material after bootstrap and no longer authenticates HTTPS or SSH.
+
+NVS is not encrypted. Password verifiers improve password storage, but Wi-Fi credentials, legacy recovery credentials, and TLS/SSH private keys remain recoverable under physical flash extraction.
+
+## Console architecture
+
+UART0 and admin SSH share canonical command implementations:
+
+```text
+UART0 linenoise frontend --\
+                          > fixed request queue -> one dispatcher -> esp_console_run()
+admin SSH line editor ----/                              |
+                                                        +-> registered *_console handlers
+```
+
+`admin_ssh_console` creates the dispatcher before network services but marks command dispatch ready only after ESP-IDF console registration. An admin SSH connection during that boot window is rejected rather than racing an incomplete registry.
+
+The dispatcher is the sole caller of `esp_console_run()`, serializing UART0 and all admin SSH commands. This is required because the console registry is treated as non-reentrant, but it also means a long command or interactive prompt blocks all administration entry routes.
+
+For SSH, standard output/error is redirected to the invoking session's bounded output ring. `console_input` routes visible or hidden prompts to UART0 or the active SSH session. Session tokens include slot and generation so late queued work cannot attach to a reused SSH slot. Only the SSH owner task moves ring output through wolfSSH.
+
+Self-affecting remote actions such as reboot, stopping SSH, disconnecting sessions, or replacing the host key are deferred until acknowledgement output drains. UART0 invokes these synchronously. Completion candidates are manually maintained and can drift from command registration.
+
+## Wi-Fi and persistence
+
+`wifi_config` owns a fixed-width versioned NVS schema with four prioritized station profiles and AP policy `off`, `fallback`, or `always`. Missing configuration generates per-device defaults including a random AP password. Invalid stored data is generally left untouched while RAM defaults are used.
+
+`wifi_manager` is a permanent task with one bounded command/event queue. ESP-IDF callbacks only copy compact events into the queue. The task owns association, DHCP deadlines, profile failover, AP policy, retries/backoff, and next-profile requests. It also reconciles against authoritative driver/netif state so dropped events do not permanently wedge policy. ESP-IDF Wi-Fi storage is RAM-only; the application blob is authoritative, and edits require explicit save.
+
+Persistent namespaces/blobs include:
+
+- `serial/config`;
+- `wifi_app/config`;
+- `local_ui/config`;
+- `web_sec/material`;
+- `user_db/database`;
+- `ssh_sec/material`.
+
+Configuration modules generally choose RAM defaults without erasing incompatible storage. Security-material modules fail closed on malformed existing material and require explicit reset. OTA slots, coredump space, an NVS-key partition, and storage are reserved in `partitions.csv`; OTA, NVS encryption, coredump handling, and filesystem mounting are not implemented.
+
+## Local UI and hardware boundaries
+
+`board_pins.h` centralizes GPIO/UART/I2C assignments. `local_display` solely owns I2C0, the SSD1315-compatible OLED, its static framebuffer, and display mutex. Display frames belong to the initiating task. Dirty-page commits and I2C transactions are bounded.
+
+`local_status_ui` is a permanent low-priority task that polls/debounces buttons, renders copied public snapshots, implements aging/wake behavior, and invokes a constrained set of public service APIs for local controls. It collects snapshots before opening a display frame, so service/broker locks are not held across I2C. It never parses CLI output, becomes a broker client, edits credentials, or assigns a writer; emergency action can only release the expected current writer.
+
+A missing or failed OLED is nonfatal. A fresh button press can request one bounded reprobe. Long confirmation holds protect disruptive local actions, and stuck buttons are quarantined.
+
+Hardware diagnostics are synchronous console commands. RS-232 tests own the physical port exclusively and restore safe GPIO state; OLED tests reuse the display service rather than taking independent I2C ownership.
+
+## Concurrency and lifecycle constraints
+
+- Broker, USB, web-transport, Wi-Fi, local-UI, and SSH owner tasks are firmware-lifetime tasks; stopping a service generally stops its runtime/listener, not the owner task.
+- Bounded queues, stream buffers, work bursts, and drop counters are part of slow-client and watchdog isolation.
+- Transport slot generations and account authentication generations solve different stale-reference problems; preserve both.
+- Library/hardware ownership is centralized: serial task owns UART1 while running, display service owns I2C/framebuffer, SSH owner task owns wolfSSH calls, and the console dispatcher owns `esp_console_run()`.
+- Password authentication performs PBKDF2 outside the user-database mutex and revalidates afterward. Some password mutation paths currently derive verifiers while holding the mutation lock; do not generalize the authentication locking pattern without checking the exact path.
+- Avoid holding service/database/broker locks across I2C, network sends, or other potentially long operations unless the existing contract explicitly requires it.
+- Broker and selected cryptographic allocations prefer PSRAM but can fall back to internal RAM. FreeRTOS control structures and task stacks intentionally remain internal where flash/cache-disable safety matters.
+- The build disables wolfSSL ESP32 AES/SHA acceleration, and the HTTPS path uses software AES for PSRAM-backed records. This preserves the validated workaround for uncoordinated mbedTLS/wolfSSL hardware-crypto locks and a prior mbedTLS external-RAM DMA watchdog stall.

docs/agent/code-map.md

@@ -0,0 +1,162 @@
+# Code map
+
+This is a semantic map, not a complete file inventory. Start here, then read the listed headers and only the implementation paths relevant to the task.
+
+## Bootstrap and system composition
+
+**Responsibility:** establish startup order, recovery behavior, configuration loading, service dependencies, and command registration.
+
+- Files: `src/main.c`, `src/CMakeLists.txt`, root `CMakeLists.txt`, `platformio.ini`, `partitions.csv`, `src/idf_component.yml`; inspect targeted settings in `sdkconfig.defaults` when crypto, PSRAM, HTTPS/HTTPD, USB, or socket capacity matters
+- Entry point: `app_main()`
+- Called by: ESP-IDF runtime
+- Dependencies: every subsystem initializer
+- Lifecycle constraint: optional display/network failures should not remove UART0 administrative recovery or USB UART1 access; the custom administration frontend starts only after command registration.
+
+## Secure randomness
+
+**Responsibility:** provide the sole mutex-serialized device DRBG, seeded before Wi-Fi/radio use.
+
+- Files: `src/secure_random.{h,c}`
+- Interfaces: `secure_random_init()`, random-byte helpers, `secure_wipe()`
+- Called by: HTTPS material, SSH keys, users, Wi-Fi defaults, tickets and authentication cache
+- Constraint: initialization order is security-significant; do not add independent weak RNGs or radio-dependent early entropy paths.
+
+## Physical RS-232 and serial service
+
+**Responsibility:** protect the MAX3243/UART resource, own UART1 while running, buffer binary RX/TX, apply serial configuration, and expose status/counters.
+
+- Files: `src/rs232_port_owner.{h,c}`, `src/serial_service.{h,c}`, `src/serial_config.{h,c}`, `src/serial_console.{h,c}`
+- Interfaces: owner claim/release/fault; serial init/start/stop/read/write/configuration/snapshots; versioned NVS load/save
+- Normal data caller: `session_broker`; USB, WebSocket, role-`user` SSH, console, and local UI also call serial lifecycle/configuration APIs as appropriate
+- Dependencies: ESP-IDF UART driver, `board_pins.h`, NVS
+- Ownership: diagnostics use `PHASE0`; service uses `SERVICE`; unsafe cleanup marks `FAULT` until reboot.
+- Lifecycle: runtime reconfiguration stops/restarts UART and may discard bounded queued data.
+
+## Session broker
+
+**Responsibility:** mediate all transport access to the serial service; provide one writer lease and multiple isolated observers.
+
+- Files: `src/session_broker.{h,c}`, `src/session_console.{h,c}`
+- Interfaces: connect/disconnect, request/release/force writer, nonblocking read/write/event APIs, snapshots and counters
+- Called by: USB, web serial, role-`user` SSH, console tests, local UI snapshots/actions
+- Dependencies: `serial_service`
+- Data path: `transport -> broker -> serial service -> UART1`; reverse data is fanned out per client.
+- Ownership: client IDs are slot/generation-safe; events are advisory and can drop, so use snapshots as authority.
+- Lifecycle: one permanent task and eight preallocated client slots; slow output drops only for the affected client.
+
+## Native USB CDC
+
+**Responsibility:** adapt TinyUSB CDC host state/data to one broker client.
+
+- Files: `src/usb_cdc_transport.{h,c}`, `src/usb_console.{h,c}`
+- Interfaces: `usb_cdc_transport_init()`, snapshots/counters, queued writer request/release
+- Called by: startup, TinyUSB callbacks, console/local UI
+- Dependencies: TinyUSB, broker, serial service
+- Flow: `USB host <-> USB task <-> broker`
+- Lifecycle: permanent owner task; broker client exists only while attached with host DTR asserted.
+- Constraint: host line coding is accepted only while USB is writer and is RAM-only.
+
+## Web and WebSocket serial
+
+**Responsibility:** serve authenticated HTTPS UI/API, issue WebSocket tickets, and adapt browser serial sessions to broker clients.
+
+- Files: `src/web_server.{h,c}`, `src/web_serial_transport.{h,c}`, `src/web_ui.{h,c}`, `src/web_console.{h,c}`
+- Security files: `src/web_security.{h,c}`
+- Asset files: authored/generated boundary in `src/web_assets_data.{h,c}`, `web_assets/SOURCES.md`, `web_assets/generate_embedded_assets.py`
+- Interfaces: web init/start/stop/snapshots; HTTP handlers; ticket mint/consume; attach/detach; targeted session revocation
+- Called by: startup, ESP-IDF HTTPS server, user administration revocation, console/local UI
+- Dependencies: user database, secure random, broker, Wi-Fi reachability, mbedTLS/HTTPS server
+- Flow: `browser -> HTTPS Basic auth -> ticket -> WebSocket -> web transport -> broker`
+- Ownership: HTTPD owns socket send/close work; transport task owns broker mediation; two fixed WebSocket slots.
+- Asset constraint: `web_assets_data.c` is checked-in generated input to the build; do not hand-edit or regenerate casually.
+
+## SSH
+
+**Responsibility:** authenticate SSH, route users to serial and administrators to the command dispatcher, and own wolfSSH lifecycle.
+
+- Files: `src/ssh_transport.{h,c}`, `src/ssh_security.{h,c}`, `src/ssh_console.{h,c}`
+- Interfaces: init/start/stop, session snapshots/disconnect/revocation, host-key replacement, counters
+- Called by: startup, network clients, user revocation, console/local UI
+- Dependencies: user database, broker, admin SSH console, secure random, wolfSSH/wolfSSL; current boot start gate also depends on `web_security` readiness
+- Flow: role `user` -> broker; role `admin` -> `admin_ssh_console`
+- Ownership: one task pinned to core 1 is the sole wolfSSH caller; two fixed generation-tagged slots.
+- Security constraint: shell/PTY only; no exec, file transfer, forwarding, or subsystems.
+
+## Users, authentication, and authorization
+
+**Responsibility:** persist bounded accounts, verify passwords/SSH keys, issue secret-free principals, and enforce account invariants.
+
+- Files: `src/user_database.{h,c}`, `src/user_console.{h,c}`, `src/admin_command_gate.{h,c}`
+- Interfaces: init/migration/recovery, authenticate, principal-currentness, account/password/role/key mutations, snapshots
+- Called by: web and SSH authentication; console administration; transport revocation checks
+- Dependencies: NVS, secure random, mbedTLS cryptography, web/SSH revocation hooks at command layer
+- Ownership: database mutex protects live records; password authentication runs PBKDF2 outside it and revalidates afterward, while mutation locking must be checked per operation.
+- Authorization: UART0 owns bootstrap/recovery; current admins may use admin SSH for operational commands; HTTPS currently treats both roles alike.
+- Constraint: final administrator cannot be deleted or demoted; transport principals must be rechecked after mutations.
+
+## Administration console infrastructure
+
+**Responsibility:** provide one canonical command registry and serialized execution for UART0 and admin SSH.
+
+- Files: `src/admin_ssh_console.{h,c}`, `src/console_input.{h,c}`, `src/console_completion.{h,c}`, `src/system_console.{h,c}`, `src/network_console.{h,c}` and all `*_console.{h,c}` modules
+- Entry points: `admin_ssh_console_init()`, `admin_ssh_console_start_uart_frontend()`, command registration functions
+- Called by: startup, UART0 frontend, role-`admin` SSH transport
+- Dependencies: ESP-IDF console/linenoise, all command handlers, user-principal currentness
+- Flow: `UART0/admin SSH -> bounded request queue -> one dispatcher -> esp_console_run()`
+- Ownership: dispatcher is sole `esp_console_run()` caller; SSH owner remains sole wolfSSH caller.
+- Lifecycle: remote session tokens include slot generation; output/history/prompt buffers are fixed and wiped on close.
+- Constraint: one slow command or prompt serializes all administration. Remote self-affecting actions use deferred control after output drain.
+
+## Wi-Fi
+
+**Responsibility:** persist station/AP policy and own asynchronous ESP-NETIF/Wi-Fi state transitions.
+
+- Files: `src/wifi_config.{h,c}`, `src/wifi_manager.{h,c}`, `src/wifi_console.{h,c}`, `src/network_console.{h,c}`
+- Interfaces: config defaults/validate/load/save; manager init/start/stop/apply/reconnect/next-profile/snapshot
+- Called by: startup, console, local UI, ESP event callbacks
+- Dependencies: secure random for default AP password, NVS, ESP-NETIF/Wi-Fi/events, lwIP diagnostics
+- Lifecycle: permanent manager task and bounded queue; callbacks enqueue compact events only.
+- Constraint: application NVS is authoritative (`WIFI_STORAGE_RAM`); working edits are not persisted until save.
+
+## Local display and controls
+
+**Responsibility:** own OLED I2C/framebuffer operations and present read-only status plus constrained button actions.
+
+- Files: `src/local_display.{h,c}`, `src/local_status_ui.{h,c}`, `src/local_boot_animation.{h,c}`, `src/local_ui_config.{h,c}`, `src/local_ui_console.{h,c}`
+- Interfaces: display init/frame/draw/commit/snapshot; UI start/activity/config; versioned NVS settings
+- Called by: startup, local UI task, diagnostics, display console
+- Dependencies: copied snapshots/public APIs from serial, broker, USB, Wi-Fi, web, SSH
+- Ownership: `local_display` solely owns I2C0 and framebuffer mutex; a frame belongs to its initiating task.
+- Lifecycle: low-priority permanent UI task; optional OLED failures are nonfatal and recover through a bounded reprobe.
+- Constraint: collect service snapshots before I2C; local UI never joins broker or handles secrets.
+
+## Hardware and diagnostics
+
+**Responsibility:** centralize board wiring and provide bounded electrical tests with safe cleanup.
+
+- Files: `src/board_pins.h`, `src/rs232_hw_test.{h,c}`, `src/local_ui_hw_test.{h,c}`, `src/status_led.{h,c}`
+- Documentation: `docs/wiring.md`, `docs/electrical_tests.md`
+- Called by: startup and `debug`/`status` commands
+- Dependencies: physical RS-232 owner, serial/display services, ESP-IDF GPIO/UART/I2C/LED drivers
+- Ownership: RS-232 diagnostics refuse to run while the service owns the port; display diagnostics reuse `local_display`.
+- Constraint: wiring and voltage assumptions are safety-relevant; verify target hardware before running diagnostics.
+
+## Where should I look?
+
+| Task | Start here |
+|---|---|
+| Change boot order or failure behavior | `src/main.c`, then affected subsystem `init/start` contracts |
+| Change serial framing, flow control, or persistence | `serial_config.*`, `serial_service.*`, `serial_console.*` |
+| Change writer/observer policy | `session_broker.*`, then all three transports |
+| Debug missing or duplicated serial bytes | `serial_service.c` -> `session_broker.c` -> relevant transport task |
+| Change USB open/DTR or line coding | `usb_cdc_transport.*` |
+| Change browser terminal protocol | `web_serial_transport.*`, `web_ui.c`, `web_server.c` |
+| Change HTTPS endpoints/authentication | `web_server.*`, `web_security.*`, `user_database.*` |
+| Change SSH login or role routing | `ssh_transport.*`, `ssh_security.*`, `user_database.*` |
+| Add or change a command | relevant `*_console.c`, `console_completion.c`, `admin_ssh_console.c` policy/deferred handling |
+| Change account roles/passwords/keys | `user_database.*`, `user_console.c`, transport revocation APIs |
+| Change Wi-Fi policy or profile persistence | `wifi_manager.*`, `wifi_config.*`, `wifi_console.c` |
+| Change OLED rendering or buttons | `local_status_ui.c`, `local_display.*`, `local_ui_config.*` |
+| Change board GPIO or electrical tests | `board_pins.h`, hardware test module, `docs/wiring.md` |
+| Change embedded browser assets | `web_assets/SOURCES.md`, generator, then generated data only as an explicit regeneration task |
+| Investigate memory/watchdog regressions | broker/web/SSH bounded loops, allocation placement, root `CMakeLists.txt`, relevant roadmap Phase 6 history |

docs/agent/current-state.md

@@ -0,0 +1,79 @@
+# Current project state
+
+This file is working memory. Update it during active work and before handoff; do not treat it as a permanent design record.
+
+## Development state
+
+Based on current source plus `README.md` and `docs/roadmap.md`:
+
+- Hardware characterization, serial service, session broker, USB CDC, Wi-Fi, HTTPS/WebSocket, SSH serial transport, and local display/control are implemented and documented as target-hardware validated.
+- Phase 8A role-based user storage/UART0 administration and Phase 8B role-aware HTTPS/SSH authentication and targeted revocation are documented as target-hardware validated.
+- Phase 8C admin SSH is implemented in source and uses the shared `esp_console` registry. Target-hardware validation is explicitly pending.
+- Phase 8D web user administration and Phase 8E browser login/session integration are planned, not implemented.
+- Security/production hardening, OTA, BLE evaluation, advanced networking, and optional filesystem features remain future roadmap work.
+- Reserved OTA, coredump, NVS-key, and storage partitions do not imply those runtime features are implemented.
+
+The normal build is `pio run`. No automated host/unit-test command is defined in the repository; important validation is hardware-oriented.
+
+## Implemented capability summary
+
+- One UART1/MAX3243 RS-232 service with RAM working configuration, explicit persistence commands, and explicit start/stop.
+- Generation-safe broker with up to eight clients, one writer, multiple observers, bounded per-client output/events, and drop accounting.
+- Native USB CDC-ACM, two browser WebSocket sessions over HTTPS, and two SSH slots.
+- SSH role routing: users receive serial; administrators receive the shared bounded administration shell.
+- Four-profile station Wi-Fi plus off/fallback/always AP policies and network diagnostics.
+- Eight-user role database, three Ed25519/P-256 keys per user, PBKDF2 password verifiers, copied principals, and targeted revocation.
+- Self-signed HTTPS identity, separate SSH host key, one-time WebSocket tickets, and fail-closed authentication when user storage is unavailable.
+- UART0/admin SSH serialized command registry with transport-aware prompts, bounded remote output/history, and deferred self-affecting SSH actions.
+- Optional SSD1315-compatible OLED status/control interface with persisted inactivity settings and bounded failure recovery.
+- Hardware diagnostics for MAX3243/UART flow control and OLED/buttons.
+
+## Clearly incomplete or transitional areas
+
+- Phase 8C hardware-validation matrix remains pending. It includes route separation, shared command serialization, history/completion, prompts, output backpressure, revocation during queued work, deferred SSH lifecycle/reboot actions, and full concurrent transport operation.
+- Current HTTPS has no web-based user administration and gives both roles the same status/terminal routes.
+- Browser authentication still uses HTTP Basic; integrated login/logout sessions are planned.
+- NVS encryption, secure boot/flash encryption review, authentication rate limiting, production certificate/provisioning policy, and OTA are not implemented.
+
+## TODO/FIXME survey
+
+No authored `src/*.{c,h}` `TODO`, `FIXME`, `XXX`, or `HACK` markers were found during the initial architecture analysis. A TODO inside vendored `web_assets/xterm.css` is upstream asset content and not project work.
+
+## Known inconsistencies
+
+These observations should be checked when touching the relevant area; they are not automatically bugs requiring unrelated cleanup.
+
+- `src/main.c` logs a Phase 7E startup banner although the implementation/roadmap is at Phase 8C.
+- `docs/command_reference.md` calls `web credentials show` physical-console-only in one row, while current source and surrounding text allow it to authenticated admin SSH.
+- The same reference describes interactive `user key add <username>` as a physical UART0 prompt, but transport-neutral prompt code allows it over admin SSH.
+- Historical Phase 7 electrical-test steps expect Select to remain read-only and describe a powered state before automatic OLED initialization; current firmware has local controls and initializes the display during boot.
+- `README.md`'s NVS partition-purpose list omits the `local_ui/config` blob.
+- `README.md` links Adafruit product 6253, while `src/board_pins.h` and `docs/wiring.md` identify product 5988. **Needs verification:** whether this is an intentional male/female breakout distinction.
+- `docs/user_administration_tests.md` contains historical Phase 8A/8B behavior that differs from current Phase 8C admin SSH routing. Treat phase-specific sections as historical procedures.
+- Manual completion candidates omit implemented `wifi next-profile`.
+- Some source comments still call shared commands UART0-only or call the current local status/control task read-only.
+- `USER_DATABASE_LOAD_EMPTY` and the corresponding `main.c` log branch appear reserved or vestigial; the current missing-storage success path migrates valid legacy credentials. **Needs verification** before removing or repurposing.
+- SSH startup is currently gated on successful `web_security` initialization even though SSH uses separate host-key material. **Needs verification:** whether this coupling is intentional recovery policy or an accidental startup dependency.
+
+## Items to verify in future work
+
+- Complete the documented Phase 8C target-hardware validation before marking it complete.
+- Confirm task-local Newlib standard-stream behavior if ESP-IDF/Newlib configuration changes; admin SSH command output relies on dispatcher-task stream redirection.
+- Revalidate software-crypto/watchdog behavior before changing crypto acceleration or PSRAM placement.
+- Verify the Adafruit breakout product identity and reconcile hardware documentation.
+- If HTTPD concurrency configuration changes, verify whether the boot-local Basic-authentication cache needs explicit locking.
+- Treat serial-service exclusivity as an architectural contract: its public read/write APIs do not themselves prove that only the broker calls them.
+
+## Active Task
+
+No active task recorded.
+
+### Handoff template
+
+- **Objective:**
+- **Relevant files:**
+- **Findings:**
+- **Decisions made:**
+- **Changes completed:**
+- **Remaining work:**
+- **Risks / things to remember:**

docs/agent/design-decisions.md

@@ -0,0 +1,163 @@
+# Durable design constraints and decisions
+
+Only constraints supported by implementation or current project documentation belong here. When original rationale is unknown, the entry describes the observable constraint without inventing intent.
+
+## One broker mediates all production serial transports
+
+**Decision:** USB CDC, WebSocket, and role-`user` SSH access UART1 through `session_broker`; transports do not independently own the serial service.
+
+**Rationale/evidence:** The broker is initialized after the serial service and all transport implementations connect broker clients. It is the normal serial RX consumer and TX gate. Project documentation requires one writer and multiple observers.
+
+**Consequence for future changes:** New serial transports must become broker clients. Do not bypass writer checks or consume `serial_service` RX directly. Preserve binary transparency and avoid in-band ownership control.
+
+**Relevant files:** `src/session_broker.{h,c}`, `src/serial_service.{h,c}`, `src/usb_cdc_transport.c`, `src/web_serial_transport.c`, `src/ssh_transport.c`
+
+## Slow clients are isolated by bounded per-client storage
+
+**Decision:** UART RX is drained and copied into independent bounded broker output streams; a full observer loses only its own copy.
+
+**Rationale/evidence:** `session_broker` accounts per-client dropped bytes instead of blocking fan-out. The roadmap records slow-client isolation as a project-wide constraint.
+
+**Consequence for future changes:** Do not replace fan-out with a blocking shared queue. Any added transport must tolerate partial/no-progress reads and expose drop/backpressure counters.
+
+**Relevant files:** `src/session_broker.c`, `src/session_broker.h`, `docs/roadmap.md`
+
+## Physical UART ownership and logical writer ownership remain separate
+
+**Decision:** `rs232_port_owner` controls whether diagnostics or the serial service may manipulate UART/MAX3243 hardware; the broker separately controls which connected client may write.
+
+**Rationale/evidence:** The code has explicit `NONE`, `PHASE0`, `SERVICE`, and `FAULT` hardware states plus broker client/writer IDs.
+
+**Consequence for future changes:** A writer lease never authorizes direct UART/GPIO access. Hardware tests must claim `PHASE0`; production service must claim `SERVICE`. Ambiguous cleanup must keep the transceiver safe and require reboot rather than clearing fault casually.
+
+**Relevant files:** `src/rs232_port_owner.{h,c}`, `src/rs232_hw_test.c`, `src/serial_service.c`, `src/session_broker.c`
+
+## Resource IDs are generation-safe
+
+**Decision:** Broker clients, SSH/WebSocket slots, queued admin work, and user principals carry generations or random stable IDs to reject stale references and slot reuse.
+
+**Rationale/evidence:** Broker IDs encode slot generation; transports track slot generations; admin tokens include session/slot generation; user principal currentness includes account ID and authentication generation.
+
+**Consequence for future changes:** Preserve transport-slot generations and account-authentication generations as distinct concepts. Validate tokens immediately before side effects and discard late work after disconnect/reuse/revocation.
+
+**Relevant files:** `src/session_broker.{h,c}`, `src/ssh_transport.c`, `src/web_serial_transport.c`, `src/admin_ssh_console.c`, `src/user_database.{h,c}`
+
+## UART0 is the physical recovery authority
+
+**Decision:** UART0 remains independent of UART1 and networking. Initial administrator bootstrap and explicit unavailable-user-database recovery are restricted to UART0.
+
+**Rationale/evidence:** `main.c` configures UART0 separately; command policy and user handlers deny these operations remotely. README/roadmap identify UART0 as the trusted recovery console.
+
+**Consequence for future changes:** Network failures or credential corruption must not remove UART0 recovery. Do not expose bootstrap/recovery through web or admin SSH without an explicit security redesign.
+
+**Relevant files:** `src/main.c`, `src/admin_ssh_console.c`, `src/user_console.c`, `docs/roadmap.md`
+
+## Admin SSH and user SSH are different routes
+
+**Decision:** A role-`user` SSH session becomes a broker serial client. A role-`admin` session enters the administration console and never obtains a broker client/writer lease.
+
+**Rationale/evidence:** Role routing is explicit after SSH authentication. The administrative shell is intended for command execution, not multiplexed serial data.
+
+**Consequence for future changes:** Do not silently give administrators both streams or infer that higher privilege means UART1 ownership. A route-switch feature would require explicit protocol, lifecycle, and authorization design.
+
+**Relevant files:** `src/ssh_transport.c`, `src/admin_ssh_console.{h,c}`, `src/session_broker.c`
+
+## One dispatcher executes the canonical command registry
+
+**Decision:** UART0 and admin SSH submit complete lines to one fixed queue; one task is the sole caller of `esp_console_run()`.
+
+**Rationale/evidence:** The implementation treats ESP-IDF console execution as non-reentrant and removes the need for separate remote command implementations.
+
+**Consequence for future changes:** Register one canonical handler rather than creating a second SSH dispatcher. Long commands/prompts block all administration, so keep handlers bounded or explicitly asynchronous. Preserve output routing and remote principal checks.
+
+**Relevant files:** `src/admin_ssh_console.c`, `src/main.c`, `src/console_input.c`, all `src/*_console.c`
+
+## Self-affecting admin SSH actions drain output before execution
+
+**Decision:** Remote reboot, SSH stop/disconnect, and host-key replacement are deferred until acknowledgement output leaves the administration and transport buffers.
+
+**Rationale/evidence:** `admin_ssh_console` has a separate bounded control task and pending-action state. Immediate execution would sever the session before confirmation is delivered.
+
+**Consequence for future changes:** Commands that invalidate their own transport/session must integrate with deferred control rather than acting synchronously from the dispatcher. Prevent new input while the action is pending.
+
+**Relevant files:** `src/admin_ssh_console.c`, `src/system_console.c`, `src/ssh_console.c`, `src/ssh_transport.c`
+
+## Authentication uses copied principals and fail-safe currentness checks
+
+**Decision:** Network sessions retain secret-free copied principals. Account mutations invalidate generations/IDs, explicitly request targeted transport revocation at the command layer, and rely on ongoing currentness checks as the fail-safe.
+
+**Rationale/evidence:** `user_database` issues principals without secrets; web/SSH check currentness during admission and active sessions. Mutating console paths call transport revocation hooks.
+
+**Consequence for future changes:** Do not retain pointers to database records or treat login as permanently authoritative. New authenticated sessions/transports must revalidate at admission, before sensitive input, and periodically or on relevant events. Database mutation APIs alone do not perform transport notification.
+
+**Relevant files:** `src/user_database.{h,c}`, `src/user_console.c`, `src/web_server.c`, `src/web_serial_transport.c`, `src/ssh_transport.c`
+
+## Security material and configuration use bounded, versioned NVS records
+
+**Decision:** Application settings, users, and identities use separate fixed/versioned NVS blobs. Serial, Wi-Fi, and local-UI working edits are RAM-only until explicitly saved. User mutations and HTTPS/SSH identity changes commit directly as part of the operation. Invalid ordinary configuration generally selects RAM defaults without erasing storage; malformed security material fails closed and needs explicit reset.
+
+**Rationale/evidence:** Serial, Wi-Fi, local UI, web security, users, and SSH security each validate schema/size and own their namespace. User/security mutations build and validate candidate state before committing it; security modules avoid silently replacing an established identity.
+
+**Consequence for future changes:** Add schema versions and transactional candidate validation. Do not overwrite unknown records automatically; provide explicit migration/reset behavior. Preserve the distinct persistence contracts: explicit save/load/default/reset for working configuration, atomic commit-or-fail for user and identity mutation.
+
+**Relevant files:** `src/serial_config.c`, `src/wifi_config.c`, `src/local_ui_config.c`, `src/web_security.c`, `src/user_database.c`, `src/ssh_security.c`
+
+## NVS is persistence, not a physical security boundary
+
+**Decision:** The current firmware stores Wi-Fi credentials, recovery credentials, and TLS/SSH private keys in unencrypted application NVS. The reserved NVS-key partition does not enable encryption.
+
+**Rationale/evidence:** `partitions.csv`, README security notes, and current code show no NVS-encryption setup. Original rationale for deferring encryption is outside the implementation; the observable limitation is explicit.
+
+**Consequence for future changes:** Do not claim resistance to flash extraction. Avoid increasing stored secret exposure. Enabling encryption requires migration/recovery planning, not just changing the partition table.
+
+**Relevant files:** `partitions.csv`, `README.md`, `src/web_security.c`, `src/ssh_security.c`, `src/wifi_config.c`
+
+## Wi-Fi callbacks enqueue; the manager owns policy
+
+**Decision:** ESP event callbacks copy bounded event data into the Wi-Fi manager queue. A permanent manager task performs driver operations, profile/AP policy, deadlines, and reconciliation.
+
+**Rationale/evidence:** Callback paths avoid blocking, NVS, and policy work. Manager deadlines consult authoritative driver/netif state so dropped events are recoverable.
+
+**Consequence for future changes:** Keep callbacks short and nonblocking. Add state transitions to the manager rather than directly invoking Wi-Fi policy from consoles, UI, or callbacks. Preserve queue-drop observability.
+
+**Relevant files:** `src/wifi_manager.{h,c}`, `src/wifi_config.{h,c}`
+
+## Optional local UI cannot become a core dependency
+
+**Decision:** The OLED/display may fail without stopping serial, UART0, USB, or networking. The UI consumes copied snapshots and calls public APIs; it never parses CLI output or joins the broker.
+
+**Rationale/evidence:** `main.c` logs display failures and continues. `local_status_ui` collects snapshots before display frames and exposes limited confirmed controls.
+
+**Consequence for future changes:** Keep OLED/I2C work bounded and outside service locks. Do not put credentials or core ownership into UI state. A missing display must remain nonfatal.
+
+**Relevant files:** `src/main.c`, `src/local_display.{h,c}`, `src/local_status_ui.c`, `src/local_ui_config.c`
+
+## Hardware and library access has designated owners
+
+**Decision:** The serial task owns UART1 while active, `local_display` owns I2C/framebuffer access, the SSH owner task alone calls wolfSSH, and the console dispatcher alone runs registered commands.
+
+**Rationale/evidence:** These constraints are enforced by module structure, mutex/task assertions, and transport indirection. Original rationale varies; the observable effect is serialized library/hardware access.
+
+**Consequence for future changes:** Cross-task requests should use existing queues/public APIs. Do not call wolfSSH, mutate display frames, or run console handlers from arbitrary tasks.
+
+**Relevant files:** `src/serial_service.c`, `src/local_display.c`, `src/ssh_transport.c`, `src/admin_ssh_console.c`
+
+## Software cryptography settings are a validated concurrency workaround
+
+**Decision:** wolfSSL ESP32 AES/SHA acceleration is disabled, and HTTPS uses software AES for PSRAM-backed TLS records. Internal task stacks are retained where cache-disable safety matters.
+
+**Rationale/evidence:** Root `CMakeLists.txt` disables wolfSSL hardware crypto. The roadmap records a reproduced watchdog stall in mbedTLS external-RAM hardware-AES DMA and uncoordinated mbedTLS/wolfSSL hardware locks; the software-crypto build passed the documented concurrency retest.
+
+**Consequence for future changes:** Do not remove these definitions as a performance cleanup. Any re-enablement needs target-hardware concurrency testing with simultaneous USB, WebSocket, SSH, and serial traffic plus watchdog/stack telemetry.
+
+**Relevant files:** `CMakeLists.txt`, `src/CMakeLists.txt`, `docs/roadmap.md`, relevant `sdkconfig.defaults` crypto settings
+
+## Embedded web assets are checked-in generated artifacts
+
+**Decision:** Vendored xterm assets are compressed and embedded ahead of the normal firmware build; `src/web_assets_data.c` is compiled directly.
+
+**Rationale/evidence:** `src/CMakeLists.txt` lists generated data as a source, and `web_assets/SOURCES.md` documents pinned versions, hashes, and deterministic gzip inputs.
+
+**Consequence for future changes:** Edit authored web UI separately. When dependency assets change, follow the documented provenance/generation process and review generated diffs; do not hand-edit arrays or regenerate assets during unrelated work.
+
+**Relevant files:** `web_assets/SOURCES.md`, `web_assets/generate_embedded_assets.py`, `src/web_assets_data.{h,c}`, `src/web_ui.c`