docs: correct stale README - DUARTs/VRAM are modelled, fix memory_access template args, add gate list and new baseline

harness/mame/README.md

@@ -13,18 +13,28 @@ tree is disposable and lives outside the project
 harness/mame/
 ├── vt1200.cpp        # the MAME driver (symlinked into the MAME tree)
 ├── build.sh          # clone-safe build wrapper
-├── trace.lua         # Lua: trace execution from the reset vector
-├── overflow.lua      # Lua: exercise the pcfReadBitmaps n*4 overflow
-├── FINDINGS.md       # results, evidence, and what was learned
+├── *.lua             # probe / capture / dump scripts (many; see the reports)
 └── roms/vt1200/      # MAME ROM dir (symlink to ../../vt1200_v22.bin)
 ```
 
+Reports in this directory:
+
+| file | what it records |
+|---|---|
+| `GATE_CLEANUP_REPORT.md` | promoting the working config to the default; retiring the settled env gates |
+| `RENDER_REPORT.md` | the active-pixel scanline renderer, and the geometry it derived |
+| `DUART_REPORT.md` | the DUARTs: wiring, the ISR-driven transmit, the datasheet-verified model edits |
+| `BRINGUP_LOG.md` | the whole bring-up narrative, **including withdrawn claims** — read it sceptically |
+| `ROMPATCH_REPORT.md` | runtime ROM patching (debug only — see the caveat) |
+
 ## Address model (the important part)
 
 The TMS34010 is **bit-addressed**: a register/PC holds a bit address, and a
 pointer `P` refers to physical byte `P >> 3`. MAME models this with a program
-space of `memory_access<32, 16, 3>`, i.e. the **address-map unit is 1 bit**
-(a 16-bit word spans 16 address units). Therefore:
+space of `memory_access<32, 1, 3>`, i.e. the **address-map unit is 1 bit**
+(a 16-bit word spans 16 address units). Source: `tms34010.h` — note the
+TMS34020 differs (`memory_access<32, 2, 3>`), so this is *not* interchangeable
+with the 34020. Therefore:
 
 * Address-map entries here are **bit addresses**, not byte addresses.
 * `read_word(0x3f200000)` returns ROM bytes 0..1 (physical byte 0x07e40000).
@@ -39,10 +49,65 @@ The driver maps:
 | ROM | `0x3f200000`–`0x3fffffff` | 1.75 MiB at byte 0x07e40000 |
 | ROM aliases | `0x7f…`, `0xbf…`, `0xff200000`–`0xffffffff` | same ROM (top 2 logical bits not decoded) |
 
-The `0xff…` alias is what makes the reset-vector page resolve. Board
-peripherals (LANCE Ethernet, DUARTs) are **not** modelled; their reads return
-`0xffff` and writes are dropped. The terminal will therefore not boot to the
-X server — that is expected and not the goal.
+The `0xff…` alias is what makes the reset-vector page resolve.
+
+### What is modelled by default
+
+This **changed** — see `GATE_CLEANUP_REPORT.md`. The working configuration used
+to be a six-variable incantation; it is now the default, and a bare
+`vt1200 vt1200` with **no environment** runs it.
+
+* Video RAM at bit `0x04000000` — required for the level-1 VIDEO MEMORY test.
+* The board-window handshake model (two-tick busy bit).
+* MAME's `SCN2681` DUART at **DUART1** (`0x0640000`, host/printer), with input
+  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.
+* 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.
+
+### What is not modelled
+
+**LANCE Ethernet**, and **DUART2** (`0x0620000`, keyboard/mouse — opt in with
+`VT1200_DUART2=1`). The OS is therefore not usable yet: it is reached, but it
+does not paint.
+
+### Getting past level 1
+
+`VT1200_SKIP_LEVEL1=1` drives DUART1's **IP3** high, which the firmware takes as
+a signal to jump to the OS cold-start and skip **all 15** level-1 tests. Note
+what this is: a *modelled board input*, and the real machine reads IP3 **low**.
+So a level-1-skipped run is evidence about the **OS, graphics and crash
+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)
+
+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`.
+
+## Regression baseline
+
+`progress.lua` at 200 frames, **no env**:
+
+```
+PC=3FDCE400 samples=53 (78 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.
 
 ## Build