docs: DUART2 modelled; Terminal Manager reached; the bare run's old level-1 pass was a latch artefact (honest failure now)

harness/mame/README.md

@@ -63,24 +63,43 @@ to be a six-variable incantation; it is now the default, and a bare
   port **IP4–IP6 held high** — that is how the driver reads the VR150 monitor
   switch (`0x70`). The level-1 host-port transmit is **ISR-driven**, so a real
   DUART is required here, not a convenience.
+* MAME's `SCN2681` at **DUART2** (`0x0620000`, keyboard/mouse). This one is a
+  *faithfulness* fix, not a convenience — the real board has one. Without it the
+  board write-back latch answers a read of DUART2's **write-only** IMR with its
+  own written value, so the OS services a phantom interrupt that can never clear.
 * A mono palette (pens 0/1 = black/white) and an active-pixel scanline renderer
   that reads VRAM. See `RENDER_REPORT.md`.
 
-A bare run progresses through POST and level 1 and stops at `HOST PORT - 15`,
-then **wedges in the system-board LED loop** — a level-1 failure is *fatal*, not
-merely reported, so the OS is unreachable while it fails.
+A bare run gets through POST and then **fails level 0's I/O data path test**, so it
+lands in the interactive diagnostics menu (`VERSION 2.08 - SELECTED TEST TYPE:`)
+instead of reaching level 1.
 
-### What is not modelled
+That test wants **10 bytes** on DUART2 channel A and nothing is attached, so this
+is an honest failure. **It used to "pass" by accident:** the write-back latch
+returned `0x0099` from DUART2's status register, and bit 0 of `0x99` is `RXRDY` —
+stuck asserted — so the firmware's drain loop counted ten phantom bytes. An LK401
+model cannot fix it either (the keyboard's `FD` reply is 4 bytes, not 10). See
+`reference/level1-test-sequence.md`, where the `0xE1` + 10-byte question was first
+raised and where it remains open.
 
-**It gets further than "not modelled" suggests.** With `VT1200_SKIP_LEVEL1=1`
-(below), the OS boots to a **running X11 server**: the root-window weave renders,
-and the cursor is handed over to the terminal's own mouse cursor. Confirmed in the
-GUI *and* from a frame dump — `skip_frame3000.png`, taken from a headless skip run
-at frame 3000. The real terminal shows the same weave during boot.
+### How far the OS gets
 
-Not modelled, and therefore still untested: DUART2 (keyboard/mouse input) and
-LANCE Ethernet. They do not block the X11 bring-up — the server draws its root
-window without a client — but input almost certainly needs DUART2.
+With `VT1200_SKIP_LEVEL1=1` (below) the OS boots to a **running X11 server** and on
+to the **Terminal Manager**: the root-window weave renders, the cursor is handed
+over to the terminal's own mouse cursor, and the V2.2 box appears — title bar,
+Messages, Ethernet/IP/LAT, a **Memory bar**, and "All Diagnostics Passed".
+
+Confirmed in the GUI and from frame dumps: `skip_frame3000.png` (the weave) and
+`duart2_default_tm_frame3000.png` (the Terminal Manager). The real terminal shows
+the same sequence — see `reference/vt1200-boot-video/`.
+
+The OS's keyboard and mouse drivers **initialise and speak the real protocol**: it
+programs DUART2 (`MR1A=0x13`, `MR2A=0x07`, `CSRA/CSRB=0x99`, `ACR=0x60`,
+`IMR=0x33`) and sends `FD` plus LED/click/bell/auto-repeat to the keyboard and `'T'`
+to the mouse. **Input does not work** — nothing is attached — and nothing is faked
+to pretend otherwise.
+
+Not modelled: **LANCE Ethernet**. It does not block the X11 bring-up.
 
 ### Getting past level 1
 
@@ -93,27 +112,38 @@ behaviour**, and is **not** evidence about the real terminal's POST.
 The skip is deliberately **not** the default: the real machine runs level 1, so
 the faithful configuration stays the default and the switch is how we diverge.
 
-## Environment knobs (14; down from 33)
+## Environment knobs (16; down from 33)
+
+All opt-in, and all off by default — there is no longer a "working incantation" to
+remember, because everything the firmware needs to run is now the default.
 
-All opt-in, all off by default, so a bare run is the working configuration.
 Instrumentation: `VT1200_DUARTLOG`, `VT1200_BOARD_LOG`, `VT1200_BOARD_MAP`,
 `VT1200_IRQLOG`, `VT1200_LOG_UNMAPPED`, `VT1200_DPYLOG` (+`_FRAMES`),
-`VT1200_DUMP_FRAME`, `VT1200_DUMP_RAM`, `VT1200_DUMP_VRAM`, `VT1200_DUMP_DIR`,
-`VT1200_NO_RENDER`. Behaviour switches: `VT1200_SKIP_LEVEL1`, `VT1200_DUART2`.
+`VT1200_DUMP_FRAME` (+`_FRAMES`), `VT1200_DUMP_RAM` (+`_FRAMES`),
+`VT1200_DUMP_VRAM` (+`_FRAMES`), `VT1200_DUMP_DIR`, `VT1200_NO_RENDER`.
+Behaviour switch: `VT1200_SKIP_LEVEL1`.
 
 ## Regression baseline
 
 `progress.lua` at 200 frames, **no env**:
 
 ```
-PC=3FDCE400 samples=53 (78 distinct PCs)
+PC=3FDCE400 samples=198 (3 distinct PCs)
 ```
 
-This value **changed** when the working config became the default — previously
-`PC=3FDCE400 samples=199` (a single PC), because a no-env run used to wedge at
-the hardware-ready gate. The new value is *better*: a bare run now executes real
-POST work. It is a change detector, not a specification — if it moves without
-you meaning it to, find out why.
+This has moved **twice**, both deliberately:
+
+1. `samples=199` (1 PC) → `samples=53` (78 PCs): the working configuration became
+   the default, so a bare run stopped wedging at the hardware-ready gate and began
+   executing real POST work.
+2. `samples=53` (78 PCs) → `samples=198` (3 PCs): DUART2 became a real `SCN2681`.
+   Level 0's I/O data path test now **fails honestly** instead of being satisfied
+   by the write-back latch's phantom `RXRDY`, so the run parks in the diagnostics
+   menu. That looks like a regression and is not one — it is the removal of a
+   false pass.
+
+It is a change detector, not a specification. If it moves without you meaning it
+to, find out why.
 
 ## Build
 

harness/mame/run.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # run.sh -- launch the VT1200 MAME harness.
 #
-#   ./run.sh                 faithful boot: POST + level 1, stops at HOST PORT - 15
+#   ./run.sh                 faithful boot: POST, then fails level 0's I/O data path
+#                            test (nothing attached) -> diagnostics menu
 #   ./run.sh skip            skip ALL 15 level-1 tests (DUART1 IP3 high) -> OS
 #   ./run.sh pie             runtime-patch the failing checks -> level 1 RUNS (pie graph)
 #   ./run.sh headless [N]    no window; dump frame N (default 600) into this directory