diff --git a/README.md b/README.md
index 28071d9..edc5ac3 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,86 @@
-# pong_raylib
+# PONG 2026
 
-Classic pong implemented in Odin and Raylib
\ No newline at end of file
+A deliberately over engineered Pong clone in [Odin](https://odin-lang.org) with [raylib](https://www.raylib.com).
+
+Retro line-based graphics with a CRT post-processing shader.
+
+## Screenshots
+
+![Main menu](screenshots/main_menu.png)
+
+![Settings menu](screenshots/settings_menu.png)
+
+![Gameplay](screenshots/gameplay.png)
+
+## Why Over-Engineered?
+
+While the game could have been done in a single file, the goal was to structure the project like a small production game instead:
+
+- **Manager-per-subsystem**: audio, input, event, level, particle, and scene managers, each in its own file
+- **Event system**: decoupled communication between systems (`event_manager.odin`) instead of direct calls
+- **Scene management**: state/scene stack for menus, gameplay, etc. (`scene_manager.odin`)
+- **Entity layer**: shared base entity with ball, player, and opponent specializations
+- **Input abstraction**: keyboard and gamepad behind one interface
+- **Data-driven assets**: audio and shaders loaded from `assets/`, not embedded
+
+The idea behind breaking it into systems is so that it can help build my foundations into more complex games.
+
+## Features
+
+- Single-player vs AI opponent
+- CRT fragment shader (`assets/shaders/crt.fs`)
+- Particle effects, sound effects, music
+- Gamepad support via SDL controller mappings
+
+## Controls
+
+| Action | Keyboard | Gamepad |
+|--------|----------|---------|
+| Move   | W(up) S(down)   | Left Joystick  |
+| Select | Enter   | A button  |
+| Pause  | Spacebar   | Start button  |
+
+## Requirements
+
+Please note, I have not built this on MacOs or Windows, only linux.
+While in theory if you have the odin compiler it should just work as there is no external libs besides those bundled with Odin.
+
+- Odin compiler (version dev-2026-10:e87445a58)
+- raylib (bundled with Odin as `vendor:raylib`)
+- GPU/driver with OpenGL 3.3 support (shader uses `#version 330`)
+
+## Build & Run
+
+    ./build.sh          # see build.sh for flags and options
+    ./out/pong
+
+## Project Layout
+
+    assets/
+      audio/            music, SFX, UI sounds
+      shaders/          crt.fs
+    screenshots/        README images
+    src/
+      main.odin         entry point
+      game.odin         game state and loop
+      *_manager.odin    audio, event, input, level, particle, scene
+      entity*.odin      base entity, ball, player, opponent
+    out/                build output
+    build.sh            build script
+
+## Credits
+Sourced from the web, not mine.
+
+| File | Title | Author | Source | License |
+|------|-------|--------|--------|---------|
+| `...` | TODO | TODO | URL | TODO |
+
+
+### Third-Party
+- `gamecontrollerdb.txt`: [SDL_GameControllerDB](https://github.com/mdqinc/SDL_GameControllerDB) (zlib)
+- [raylib](https://github.com/raysan5/raylib) by Ramon Santamaria (@raysan5), zlib
+- [Odin](https://github.com/odin-lang/Odin), BSD-3-Clause
+
+## License
+MIT, see [LICENSE](LICENSE).
+Any third-party assets retain their original licenses, listed above.