serial: headless mode tying serial port to stdio for OS debugging

- --headless: no rendering/TUI; serial TX -> stdout, RX <- stdin (nonblocking)
- generalize serial: serial_out_fd/serial_in_fd on the GB; internal-clock
  transfer now shifts in a real RX byte (from stdin) instead of always 0xFF
- paced to native speed by default, --uncapped for turbo; pipes/scripts cleanly
- README: document headless serial console

1 files changed, 27 insertions, 1 deletions

diff --git a/README.md b/README.md
index b93446d..e03aedc 100644
--- a/README.md
+++ b/README.md
@@ -18,12 +18,38 @@ over 2 s (~108×). Terminal resize (`SIGWINCH`) triggers a full repaint.
 ```sh
 make
 ./build/gbc path/to/rom.gb        # interactive
-./build/gbc rom.gb --test 30      # headless: run 30s, log serial (test roms)
+./build/gbc rom.gb --test 30      # run 30s, log serial to stderr (test roms)
 ./build/gbc rom.gb --shot 60 out.ppm   # run 60 frames, dump a PPM screenshot
 ./build/gbc rom.gb --sixel 3      # sixel graphics output at 3x zoom
 ./build/gbc rom.gb --sock         # open a control/debug socket (/tmp/gbc.sock)
+./build/gbc rom.gb --headless     # no video; serial <-> stdio (OS console)
 ```
 
+### Headless serial console (`--headless`)
+
+For bring-up and debugging of an OS/monitor running on the emulated Game Boy,
+`--headless` disables all rendering and the terminal UI and instead wires the
+**serial port straight to stdio**:
+
+- transmitted bytes (the GB writing `SB`/`SC` with the internal clock) go to **stdout**
+- **stdin** is fed back as the received byte on each transfer (non-blocking;
+  `0xFF` open-bus when nothing is waiting)
+
+Emulation is paced to native speed by default; add `--uncapped` to run flat out.
+Because it's plain stdio it pipes and scripts cleanly:
+
+```sh
+./build/gbc os.gb --headless                 # interactive byte console
+./build/gbc os.gb --headless --uncapped       # as fast as possible
+printf 'ls\n' | ./build/gbc os.gb --headless  # feed input, capture output
+./build/gbc os.gb --headless | tee session.log
+```
+
+The serial console model matches what a GB program expects: write the byte to
+`SB` (`$FF01`), then kick a transfer with `SC = $81` (`$FF02`, start + internal
+clock). Output appears immediately; the transfer-complete serial interrupt still
+fires. (`--test` keeps its old behavior, logging serial to **stderr**.)
+
 Requires a truecolor-capable terminal (`COLORTERM=truecolor`) at least
 160 columns wide.