diff --git a/README.md b/README.md
index 604cc56a..6353e2c7 100644
--- a/README.md
+++ b/README.md
@@ -24,12 +24,11 @@ A package will be written for XBPS so stay tuned.
A C++ compiler with C++14 support. For example `clang`.
-- lemonbar (obviously)
- - NOTE: The application has only been tested against the `single-mon` fork.
- If you have trouble with your version of lemonbar, install the fork which is
- included in the `contrib` folder.
-
- There are plans to integrate `lemonbar` into the project.
+- lemonbar
+ > **NOTE:** The application has only been tested against the `single-mon` fork.
+ > If you have trouble running it with your current version, install the one
+ > included in `contrib/lemonbar-sm-git`.
+ > Plans are to make `lemonbar` an internal module.
- cmake
- boost
- libx11
@@ -39,80 +38,765 @@ A C++ compiler with C++14 support. For example `clang`.
- libmpdclient _(optional: used by the mpd module)_
- libsigc++ _(optional: used by the i3 module)_
-**Installing using pacman:**
+**Install dependencies using pacman:**
~~~ sh
-$ pacman -S cmake boost libx11 libxrandr wireless_tools alsa-lib libmpdclient libsigc++ i3-wm
+$ sudo pacman -S cmake boost libx11 libxrandr wireless_tools alsa-lib libmpdclient libsigc++ i3-wm
~~~
-**Installing using xbps-install:**
+**Install dependencies using xbps-install:**
~~~ sh
-$ xbps-install -S cmake alsa-lib-devel boost-devel i3-devel libX11-devel libXrandr-devel libmpdclient-devel libsigc++-devel wireless_tools-devel
+$ sudo xbps-install -S cmake alsa-lib-devel boost-devel i3-devel libX11-devel libXrandr-devel libmpdclient-devel libsigc++-devel wireless_tools-devel
~~~~
-**Installing using apt-get:**
+**Install dependencies using apt-get:**
-> NOTE: `libmpdclient-dev` and `i3-wm` are located in the `universe` repository, so if you want support for the
-> mpd/i3 modules you need to make sure it's included in the list of sources in `/etc/apt/sources.list`.
-> For example:
+> **NOTE:** To get support for the mpd and i3 modules, the `universe` repository
+> needs to be added to the list of sources in `/etc/apt/sources.list`.
>
-> `deb http://archive.ubuntu.com/ubuntu/ xenial main restricted universe`
+> Packages in the `universe` repository: `libmpdclient-dev` `i3-wm`
~~~ sh
-$ apt-get install cmake libx11-dev libxrandr-dev libboost-dev libiw-dev libmpdclient-dev libsigc++-dev i3-wm
+$ sudo apt-get install cmake libx11-dev libxrandr-dev libboost-dev libiw-dev libmpdclient-dev libsigc++-dev i3-wm
~~~~
-
+### Building from source
-## Building from source
-
-#### Automatic installation using ./build.sh
-
-If you haven't worked with builds before you could try to run the following
-command chain:
-
-~~~ sh
-$ git clone --branch 0.1.2 --recursive https://github.com/jaagr/lemonbuddy.git
-$ cd lemonbuddy
-$ ./build.sh
-~~~
-
-> NOTE: `git-perl` is required for submodules to work in **Void Linux**
-
-#### It is of course recommended that you control the build process yourself.
+> **NOTE:** In Void Linux you will need to install `git-perl` to get support for submodules.
~~~ sh
$ git clone --branch 0.1.2 --recursive https://github.com/jaagr/lemonbuddy.git
$ mkdir lemonbuddy/build
$ cd lemonbuddy/build
$ cmake ..
- # Optionally list and edit build variables
- $ make edit_cache
+ # Optionally list and edit build settings before compiling
+ # $ make edit_cache
$ sudo make install
~~~
----
-
+## Running
+
+Before customizing the bar, make sure everything works as expected by trying
+out one of the example configurations installed with the application.
+The following code will get you started:
+
+ ~~~ sh
+ # Create the config root directory
+ $ mkdir -p ${XDG_CONFIG_HOME:-$HOME/.config}/lemonbuddy
+ $ cd ${XDG_CONFIG_HOME:-$HOME/.config}/lemonbuddy
+
+ # Copy sample config for the running wm (uses a wm agnostic config as fallback)
+ $ __wm=$(pgrep -l "(bspwm|i3)")
+ $ cp /usr/share/examples/lemonbuddy/config${__wm:+.${__wm##* }} config
+
+ # Launch the bar
+ # (where "example" is the name of the bar as defined by [bar/NAME] in the config)
+ $ lemonbuddy_wrapper.sh example
+
+ # When making changes to the configuration, make sure to try it out using
+ # only the lemonbuddy executable, before launching it with the wrapper:
+ $ lemonbuddy example
+ (Ctrl-C to terminate)
+
+ # "lemonbuddy_wrapper.sh" is just a simple shell script that takes care
+ # of redirecting the in-/output streams between "lemonbuddy" and "lemonbar".
+ # It should be considered experimental and needs more assertions, but if
+ # it the above command doesn't report any error it is generally safe to
+ # assume that the wrapper will launch the bar successfully as well.
+ ~~~
+
+**It is recommended** to always use `lemonbuddy_wrapper.sh` when launching the bars.
+
+If you handle the in-/output stream redirection's manually, the internal command
+handlers (e.g. mpd or volume controls) might stop working. It won't change the
+output of the bar but you will miss out on the internal API calls, which is one
+of the main advantages of using the application.
+
+The `lemonbuddy_wrapper.sh` will be deprecated once `lemonbar` is integrated
+into the project.
+
+
+## Launching the bar in your wm's bootstrap routine
+
+When using the wrapper to start the bar in in your wm's autostart routine, make sure to include
+a kill directive before launching the bar. This is done to make sure that any previously spawned
+processes gets terminated before before we launch the new ones. For example in
+`$HOME/.config/bspwmrc`:
+
+ ~~~ sh
+ # Terminate already running bar instances
+ pgrep -f '(lemonbuddy_wrapper.sh|^lemonb(uddy|ar))' | xargs kill -9 >/dev/null 2>&1
+
+ # Launch bar1 and bar2
+ lemonbuddy_wrapper.sh bar1 &
+ lemonbuddy_wrapper.sh bar2 &
+
+ echo "Bars launched..."
+ ~~~
+
+
+## Configuration
+
+The configuration syntax is very much **WIP**. If you have any feedback or suggestions, please
+[create an issue ticket](https://github.com/jaagr/lemonbuddy/issues).
+
+When working with unicode symbols, remember that fonts render them differently. Changing font
+can change the quality of your generated output drastically. One must-have font
+is [Unifont](http://unifoundry.com/unifont.html), which has great unicode coverage.
+
+Also try different icon fonts, such as [Font Awesome](http://fontawesome.io/icons/) and [Material Icons](https://design.google.com/icons/).
+
+The values used in the examples below are to be considered placeholder values, and
+the resulting output might not be award-winning.
+
+`🟊 = module is still flagged as work in progress`
+
+
+### Module `internal/backlight`
+ ~~~ ini
+ [module/backlight]
+ type = internal/backlight
+
+ ; Use the following command to list available cards:
+ ; $ ls -1 /sys/class/backlight/
+ card = intel_backlight
+ ~~~
+
+##### Extra formatting (example)
+ ~~~ ini
+ ; Available tags:
+ ;