Refresh agent documentation for current behavior

docs/agent/code-map.md

@@ -14,12 +14,12 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 
 ## Secure randomness
 
-**Responsibility:** provide the sole mutex-serialized device DRBG, seeded before Wi-Fi/radio use.
+**Responsibility:** provide the sole project-owned, mutex-serialized application 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.
+- Called by: HTTPS material, SSH keys, users, Wi-Fi defaults, tickets, the HTTPS authentication cache, and the wolfCrypt seed callback
+- Constraint: initialization order is security-significant; the DRBG deliberately avoids post-radio reseeding and fails closed at its generation limit. Do not add independent weak RNGs or radio-dependent early entropy paths.
 
 ## Physical RS-232 and serial service
 
@@ -29,8 +29,8 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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.
+- Ownership: the cooperative owner arbitrates active diagnostics (`PHASE0`) against the service (`SERVICE`); boot-time static-safe GPIO initialization and service-owned static-mode restoration are explicit exceptions. Unsafe cleanup marks `FAULT` until reboot.
+- Lifecycle: stop/reconfiguration discards serial-service RX/TX and task-local pending bytes, but leaves broker clients, writer ownership, events, and already-fanned output intact.
 
 ## Session broker
 
@@ -54,7 +54,7 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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.
+- Constraint: callbacks cache the latest host line coding; the task applies it only while USB is writer, UART is running, and TX is empty. It is RAM-only and is discarded when the CDC session closes.
 
 ## Web and WebSocket serial
 
@@ -65,9 +65,10 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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
+- Dependencies: user database, secure random, broker, successful Wi-Fi manager initialization at boot, mbedTLS/HTTPS server; actual network reachability is an operational prerequisite, not an initializer invariant
 - 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.
+- Ownership: HTTPD owns socket send/close work; transport task owns broker mediation; two fixed WebSocket slots and four outstanding tickets.
+- Security constraints: Basic-auth cache hits still revalidate principal currentness; changes to the authored inline loader must update its hard-coded CSP hash in the same change.
 - Asset constraint: `web_assets_data.c` is checked-in generated input to the build; do not hand-edit or regenerate casually.
 
 ## SSH
@@ -79,19 +80,19 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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.
+- Ownership: after caller-side library initialization, one task pinned to core 1 owns runtime wolfSSH contexts/sessions; two fixed generation-tagged slots.
+- Security constraint: an interactive shell request is required; exec and subsystems are rejected, and no project file-transfer or forwarding route exists. PTY is not explicitly required.
 
 ## 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}`
+- Files: `src/user_database.{h,c}`, `src/user_console.{h,c}`; `src/admin_command_gate.{h,c}` is currently a narrow recursive wrapper used only by the `user` command handler, not the global command serializer
 - 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
+- Called by: web and SSH authentication/currentness checks and console administration
+- Dependencies: NVS, secure random, mbedTLS cryptography; after a committed command-layer mutation, best-effort web/SSH revocation calls supplement authoritative transport currentness checks
 - 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.
+- Authorization: UART0 exclusively owns initial administrator bootstrap and unavailable-database recovery; current admins may use admin SSH for other commands unless handler policy denies them. HTTPS currently treats both roles alike.
 - Constraint: final administrator cannot be deleted or demoted; transport principals must be rechecked after mutations.
 
 ## Administration console infrastructure
@@ -103,9 +104,9 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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.
+- Ownership: dispatcher is sole `esp_console_run()` caller; the SSH owner exclusively performs post-initialization wolfSSH runtime calls.
+- Lifecycle: remote session tokens include slot generation; fixed output/history/prompt state is wiped immediately on idle close or after an executing handler returns.
+- Constraint: one slow command or prompt serializes all administration. Admin SSH is unavailable until command registration and UART frontend creation complete; supported deferred actions wait only for a bounded application-buffer drain heuristic.
 
 ## Wi-Fi
 
@@ -116,18 +117,18 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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.
+- Constraint: application NVS is authoritative (`WIFI_STORAGE_RAM`); working edits are not persisted until save. Start/stop, including local controls, intentionally update the RAM `enabled_at_boot` field. Working-config copies contain PSKs and must be tightly scoped and wiped; routine status/local UI must use secret-free snapshots.
 
 ## Local display and controls
 
-**Responsibility:** own OLED I2C/framebuffer operations and present read-only status plus constrained button actions.
+**Responsibility:** own OLED I2C/framebuffer operations and present 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.
+- Lifecycle: the low-priority task is firmware-lifetime only if button GPIO initialization succeeds; it still runs with an absent panel so a press can reprobe after successful I2C bus setup. Failed bus creation is not recoverable by that reprobe, and `display` configuration commands depend on the UI task.
 - Constraint: collect service snapshots before I2C; local UI never joins broker or handles secrets.
 
 ## Hardware and diagnostics
@@ -139,7 +140,7 @@ This is a semantic map, not a complete file inventory. Start here, then read the
 - 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.
+- Constraint: wiring and voltage assumptions are safety-relevant; verify target hardware before running diagnostics. RGB LED initialization is currently boot-fatal, and its colors report diagnostic state rather than aggregate firmware health.
 
 ## Where should I look?