First version of Readme

README.md

@@ -1,3 +1,59 @@
 # octal_cookie
 
-A Chip 8 emulator written in Odin
+A CHIP-8 emulator / simulator written in [Odin](https://odin-lang.org/) using [Raylib](https://www.raylib.com/).
+
+![showcase](assets/showcase.png)
+
+---
+
+## Features
+
+- Full CHIP-8 instruction set emulation
+- Simulator GUI with dedicated panels for the screen, CPU state, keypad, file loader, memory viewer, and control bar
+- Built-in collection of classic game ROMs (Pong, Tetris, Space Invaders, Brix, and more)
+- Load your own ROMs via the file loader panel
+- Dev and release build modes via `make`
+
+---
+
+## Dependencies
+
+- [Odin compiler](https://odin-lang.org/docs/install/)
+- [Raylib](https://www.raylib.com/) (used via Odin's vendor bindings)
+- [tinyfiledialogs](https://sourceforge.net/projects/tinyfiledialogs/) (included under `external/`)
+
+---
+
+## Building
+
+```sh
+# Run directly in dev mode
+make
+
+# Build a dev binary
+make dev
+
+# Build an optimised release binary
+make release
+
+# Clean build output
+make clean
+```
+
+The output binary is named `my_app` by default. You can change `APP_NAME` in the `Makefile`.
+
+---
+
+## Included ROMs
+
+A set of public domain game ROMs is bundled under `assets/game_roms/`:
+
+`15PUZZLE` · `BLINKY` · `BLITZ` · `BRIX` · `CONNECT4` · `GUESS` · `HIDDEN` · `INVADERS` · `KALEID` · `MAZE` · `MERLIN` · `MISSILE` · `PONG` · `PONG2` · `PUZZLE` · `SYZYGY` · `TANK` · `TETRIS` · `TICTAC` · `UFO` · `VBRIX` · `VERS` · `WIPEOFF`
+
+Test ROMs are available under `assets/test_roms/` for development and debugging.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).