diff --git a/README.md b/README.md
new file mode 100644
index 0000000..500495e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# riverguile
+
+Layout generator for the [river](https://github.com/riverwm/river) Wayland
+server which uses [Guile Scheme](https://www.gnu.org/software/guile/) for
+layouts. Its layout namespace is `riverguile`.
+
+Uppon launch, riverguile tries to eval a scheme script and checks the following
+paths for it in the given order:
+
+* `layout.scm`
+* `$XDG_CONFIG_HOME/river/layout.scm`
+* `$HOME/.config/river/layout.scm`
+* `/etc/riverguile/layout.scm`
+
+This script must contain the definition of a function
+`(layout-demand-handler view-count usable-width usable-height)` and may contain
+any other code the user desires. The function must return a list containing
+exactly as many lists as `view-count`. Each of those sublists must contains
+exactly four numerical values for `x` and `y` position of the windows as well as
+their width and height. Window positions and dimensions get applied to rivers
+window list top to bottom.
+
+Example of valid output:
+
+```scheme
+scheme@(guile-user)> (display (layout-demand-handler 3 1080 1920))
+((0 0 594.0 1920) (594.0 0 486.0 960) (594.0 960 486.0 960))
+```
+
+Note that the numerical values do not need to be exact, riverguile takes care
+of rounding and casting for you.
+
+You can send riverguile layout-commands, which it will try to eval as scheme code.
+
+```sh
+riverctl map normal Super U send-layout-cmd riverguile "(define gaps 20)"
+```
+
+Here is an example `layout.scm` file replicating rivertiles behavior of having
+a main window and a stack of windows aside:
+
+```scheme
+(define split 0.55)
+
+(define (layout:rows n x y w h)
+        (letrec ((height (/ h n))
+                 (rows (lambda (n)
+                               (if (eq? n 0)
+                                   '()
+                                   (let ((Y (- (+ y h) (* n height))))
+                                        (append (list (list x Y w height))
+                                                (rows (- n 1))))))))
+                (rows n)))
+
+(define (layout:split n x y w h)
+        (if (eq? n 1)
+            (list (list x y w h))
+            (letrec* ((left (* split w))
+                      (right (- w left)))
+                     (append (list (list x y left h))
+                             (layout:rows (- n 1) (+ x left) y right h)))))
+
+(define (layout-demand-handler view-count width height)
+        (layout:split view-count 0 0 width height))
+```