docs: add README with build, usage and verification gate instructions

README.md

@@ -0,0 +1,79 @@
+# gameboy-sharp
+
+A Game Boy (DMG) emulator written in C# (.NET 6). The core is a pure library with
+no frontend dependency, so the whole machine runs and is verified headless.
+
+## Status - wave 1
+
+Working, test-verified core that runs real DMG software:
+
+- CPU LR35902: full opcode set + CB prefix, cycle-accurate M-cycle timing, Z/N/H/C
+  flags, interrupts (VBlank/LCD/Timer/Serial/Joypad), HALT + HALT bug, STOP (minimal),
+  delayed EI, DI, RETI.
+- MMU: full memory map, I/O registers, echo RAM, OAM DMA.
+- Cartridge: header parse, MBC1 (ROM/RAM banking), MBC3 and MBC5 banking (no RTC yet),
+  plain ROM.
+- PPU: per-scanline mode 2/3/0 + VBlank timing, LCDC/STAT/SCX/SCY/LY/LYC/WX/WY/BGP/OBP0/OBP1,
+  background + window (with the window internal line counter) + sprites (8x8 and 8x16,
+  X/OAM priority, 10-per-line limit, BG priority), 160x144 framebuffer, STAT/LYC interrupts.
+- Timer: DIV/TIMA/TMA/TAC via the internal 16-bit counter, falling-edge detection and the
+  TIMA overflow reload delay.
+- Joypad and serial (serial output is captured, which is how the Blargg tests are scored).
+- APU: register-level stub (open-bus read masks, NR52 power). No synthesis yet - wave 2.
+
+## Layout
+
+- `src/GameBoy.Core` - the machine (no frontend dependency).
+- `src/GameBoy.Cli` - headless runner: loads a ROM, runs frames, dumps the framebuffer.
+- `tests/GameBoy.Core.Tests` - the verification gate.
+
+## Verification gate
+
+`dotnet test` runs, headless:
+
+- `cpu_instrs` (Blargg) - asserts the serial log reports `Passed` and never `Failed`.
+- `instr_timing` (Blargg) - same serial assertion.
+- `dmg-acid2` - decodes the reference PNG and asserts the rendered framebuffer matches it
+  pixel for pixel (0 mismatches out of 23040).
+- CPU micro tests (flags, DAA, push/pop, CB swap).
+
+```
+dotnet test -c Release
+```
+
+## Running a ROM (headless)
+
+```
+dotnet run --project src/GameBoy.Cli -c Release -- <rom.gb> [options]
+  --frames N        run N frames (default 60)
+  --serial          run until the serial log says Passed/Failed, then print it
+  --png <path>      write the framebuffer as an 8-bit grayscale PNG
+  --ascii           print the framebuffer as ASCII art
+  --ascii-out <p>   write the ASCII art to a file
+```
+
+Examples:
+
+```
+dotnet run --project src/GameBoy.Cli -c Release -- tests/roms/cpu_instrs.gb --serial
+dotnet run --project src/GameBoy.Cli -c Release -- tests/roms/dmg-acid2.gb --frames 200 --png acid2.png
+```
+
+## Test ROMs and licenses
+
+Vendored under `tests/roms/` purely to run the verification gate:
+
+- `cpu_instrs.gb`, `instr_timing.gb` - Blargg's Game Boy hardware test ROMs by Shay Green
+  (blargg), released for free distribution. Fetched from
+  https://github.com/retrio/gb-test-roms
+- `dmg-acid2.gb` and `dmg-acid2-ref.png` - the DMG variant of the PPU acid test by
+  Matt Currie, MIT licensed. Fetched from https://github.com/mattcurrie/dmg-acid2
+
+These are third-party artifacts kept only for testing; their own licenses apply.
+
+## Not covered yet (wave 2+)
+
+APU synthesis (4 channels + mixdown), MBC3 RTC + MBC5 corner cases, battery RAM save
+(`.sav`), Game Boy Color, a windowed frontend (Raylib-cs/SDL - needs a display, so it was
+left out of this headless wave), a debugger (breakpoints, disassembler, tile/OAM viewers)
+and save states.