diff --git a/LICENSE.md b/LICENSE
similarity index 100%
rename from LICENSE.md
rename to LICENSE
diff --git a/README.md b/README.md
index f18ab08..0d2117d 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,60 @@
-# wallpaper
+<div align="center">
+  <h1>pihkaal's wallpaper</h1>
+  <img src="docs/demo.gif" alt="demo" />
+</div>
+
+An animated and interactive wallpaper I'm building for myself, designed to run on [Hyprland](https://hyprland.org/).
+
+## What it does
+
+- Animated stars
+- Metaballs-like effect with the "clouds"
+
+## Limitations
+
+- The wallpaper will only work on one monitor and on 1920x1080px for now
+
+## Stack
+
+- [C](https://en.wikipedia.org/wiki/C_(programming_language))
+- [Raylib](https://www.raylib.com/)
+- [Hyprland](https://hypr.land/)
 
 ## Quick start
 
+### Build and install
+
 ```console
 $ make
 
-# generate distance field with 50px search radius
-# note that i already ship a generated distance field
-$ ./distance_field_generator ./resources/textures/background_mask.png ./resources/textures/background_distance_field.png 50
-
-# run wallpaper, image paths are customizables
-$ ./wallpaper
+# generate distance field with 100px ball radius (needed to offset vertically the effect)
+# NOTE:  I already ship a generated distance field
+# USAGE: distance_field_generator <mask_path> <output_path> <ball_radius>
+$ ./distance_field_generator ./assets/textures/background_mask.png ./assets/textures/background_distance_field.png 100
 
 # install
 $ make install
+
+# uninstall
+$ make uninstall
+```
+
+### Run as wallpaper
+
+You'll need to install [hyprwinwrap](https://code.hyprland.org/hyprwm/hyprland-plugins/src/branch/main/hyprwinwrap), then add this to your hyprland configuration:
+
+```ini
+plugin {
+    hyprwinwrap {
+        class = pkl-wallpaper
+    }
+}
+```
+
+### Run as debug
+
+Even if you've configured the app to always run as wallpaper using hyprwinwrap, you can still run it in debug mode:
+
+```console
+$ DEBUG=1 ./pkl-wallpaper
 ```
diff --git a/docs/demo.gif b/docs/demo.gif
new file mode 100644
index 0000000..09935fb
Binary files /dev/null and b/docs/demo.gif differ