diff --git a/README.md b/README.md
index 4a42cdc..d1327b8 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,99 @@
-# observations-on-the-sublime-dynamics-of-eroding-matter
+# Observations on the Sublime Dynamics of Eroding Matter
+
+A C++ project using SDL2 for graphics and window management.
+
+## Prerequisites
+
+### macOS
+Install SDL2 using Homebrew:
+```bash
+brew install sdl2
+```
+
+### Ubuntu/Debian
+```bash
+sudo apt-get install libsdl2-dev
+```
+
+### Windows
+Download SDL2 development libraries from [SDL2 website](https://www.libsdl.org/download-2.0.php) or use vcpkg:
+```bash
+vcpkg install sdl2
+```
+
+## Building
+
+### Option 1: Using Build Scripts (Recommended)
+
+#### Unix-like Systems (macOS/Linux)
+```bash
+# Build the project
+./build.sh
+
+# Clean and rebuild
+./build.sh -c
+
+# Check dependencies only
+./build.sh --check-only
+
+# Show help
+./build.sh -h
+```
+
+#### Windows
+```cmd
+# Build the project
+build.bat
+
+# Clean and rebuild
+build.bat -c
+
+# Check dependencies only
+build.bat --check-only
+
+# Show help
+build.bat -h
+```
+
+### Option 2: Manual Build
+
+1. Create a build directory:
+```bash
+mkdir build
+cd build
+```
+
+2. Configure with CMake:
+```bash
+cmake ..
+```
+
+3. Build the project:
+```bash
+make
+```
+
+## Running
+
+From the build directory:
+```bash
+./observations-on-the-sublime-dynamics-of-eroding-matter
+```
+
+## Build Script Features
+
+The build scripts provide:
+- **Dependency checking**: Automatically verifies CMake, C++ compiler, and SDL2
+- **Cross-platform support**: Works on macOS, Linux, and Windows
+- **Smart SDL2 detection**: Finds SDL2 installed via Homebrew, package managers, or system paths
+- **Build optimization**: Uses parallel compilation and Release configuration
+- **Error handling**: Clear error messages and helpful installation instructions
+- **Flexible options**: Clean builds, dependency checks, and future test/install support
+
+## Features
+
+- SDL2 window with 800x600 resolution
+- Black background
+- Proper event handling (close window to exit)
+- Clean resource management