Add Phase 1 UART service foundation

Add versioned NVS-backed configuration, buffered UART1 I/O, modem
monitoring, counters, and serial console controls. Coordinate UART1
ownership with Phase 0 diagnostics and document loopback verification.

README.md

@@ -12,7 +12,7 @@ Universal wireless serial adaptor firmware for the ESP32-S3.
 - 8 MB octal PSRAM
 - Adafruit MAX3243 full-pinout RS-232 breakout, product 5988
 
-The current firmware is a command-driven **Phase 0 hardware-characterization harness**. It validates the MAX3243 breakout, its three drivers, its five receivers, valid-signal detection, active-low shutdown, and UART1 loopback before development of the wireless serial firmware begins. Tests run only when explicitly requested at the console; booting the board does not start an electrical test.
+The firmware has completed **Phase 0 hardware characterization** and now includes the **Phase 1 serial-core foundation**. The MAX3243 diagnostics remain available, alongside a versioned NVS-backed serial configuration and a buffered UART1 service with modem-state monitoring and error counters. Neither the UART service nor an electrical test starts automatically at boot.
 
 ## Hardware wiring
 
@@ -33,7 +33,48 @@ pio run --target upload
 pio device monitor -b 115200
 ```
 
-The firmware starts an interactive console on UART0. Type `help` to display command descriptions. The Phase 0 commands are:
+The firmware starts an interactive console on UART0 with the prompt `serial-tool>`. Type `help` to display command descriptions.
+
+### Phase 1 serial service
+
+The `serial` command manages the working configuration and UART1 service:
+
+```text
+serial status
+serial start
+serial stop
+serial set <baud|data-bits|parity|stop-bits|flow|dtr|rts-threshold> <value>
+serial save
+serial load
+serial defaults
+serial reset
+serial counters
+serial clear-counters
+serial send-hex <hex-bytes>
+serial read [maximum-bytes]
+```
+
+Safe defaults are 115200 baud, 8 data bits, no parity, one stop bit, no flow control, and inactive DTR. Supported configuration values are:
+
+| Parameter | Values |
+|---|---|
+| `baud` | 110–1000000 |
+| `data-bits` | `7`, `8` |
+| `parity` | `none`, `even`, `odd` |
+| `stop-bits` | `1`, `2` |
+| `flow` | `none`, `rts-cts` |
+| `dtr` | `inactive`, `active`, `on-connect` |
+| `rts-threshold` | 1–127 bytes |
+
+`serial set` changes the working configuration and safely restarts UART1 if the service is running. It does not write flash; use `serial save` to commit the current configuration to NVS. `serial defaults` changes RAM only, while `serial reset` applies and persists defaults. The firmware never erases the shared NVS partition automatically when storage is incompatible or unavailable.
+
+The service uses independent software RX and TX streams. Calls into those streams are nonblocking, and a deasserted CTS cannot block service shutdown. `serial send-hex` and `serial read` are temporary binary-safe console clients for validation before the session broker and USB/network clients are added.
+
+UART1 has exclusive ownership while the service runs. Phase 0 commands will refuse to touch the port until `serial stop` releases it.
+
+### Phase 0 diagnostics
+
+The retained hardware-characterization commands are:
 
 ```text
 status
@@ -50,6 +91,8 @@ rts-flow-test
 
 `uart-loopback` defaults to `8N1` and 256 bytes. Its accepted payload range is 1–512 bytes. `uart-suite` covers 300 through 250000 baud and all supported frame formats. `cts-flow-test` verifies transmit gating and exact resumption, while `rts-flow-test` uses UART2 as an internal traffic generator to verify automatic receive backpressure. Follow the command-specific loopback wiring in [`wiring.md`](wiring.md) before invoking any test.
 
+A mutex-protected port lease prevents diagnostics, UART1 service startup, and future clients from reconfiguring the same GPIOs concurrently. If a UART driver cannot be removed during cleanup, the firmware keeps the MAX3243 shut down and marks the port faulted until reboot rather than exposing an ambiguous hardware state.
+
 The onboard RGB LED reports the most recent test-harness state:
 
 | Color | Meaning |