diff --git a/docs/readme.md b/docs/readme.md
index ef9bec5..d9d9c54 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -16,20 +16,65 @@ cd q
 go build
 ```
 
+This will place the compiler inside the repository.
+Either use `./q` for the following examples or get access to the shorter `q` in any directory via symlink:
+
+```shell
+ln -s $PWD/q ~/.local/bin/q
+```
+
+This assumes that your shell loads `~/.local/bin`.
+
 ## Usage
 
 ```shell
-./q run examples/hello
+q [command] [options]
 ```
 
-Builds an executable from `examples/hello` and runs it.
+The `build` command creates an executable:
 
-## Links
+```shell
+q build examples/hello
+```
 
-- [Chat](https://matrix.to/#/#community:akyoto.dev)
-- [Donate](https://buy.stripe.com/4gw7vf5Jxflf83m7st)
-- [License](https://akyoto.dev/license)
-- [Todo](todo.md)
+The `run` command does everything `build` does but also executes it:
+
+```shell
+q run examples/hello
+```
+
+You don't have to use physical directories, it's perfectly valid to use a list of files:
+
+```shell
+q build hello.q world.q
+```
+
+To show verbose compiler output use `-v` or `--verbose`:
+
+```shell
+q build examples/hello -v
+```
+
+For more information see `q help`.
+
+## Platforms
+
+You can cross-compile executables for Linux, Mac and Windows.
+
+```shell
+q build examples/hello --os linux
+q build examples/hello --os mac
+q build examples/hello --os windows
+```
+
+## Status
+
+This project is under heavy development.
+Feel free to [get in touch](https://akyoto.dev/contact) if you are interested in helping out.
+
+## License
+
+Please see the [license documentation](https://akyoto.dev/license).
 
 ## Copyright