diff --git a/README.md b/README.md
index 2fb2779..5f84f2e 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,38 @@
 # brethil's dotfiles
 
-A set of zsh dotfiles based on antibody and oh-my-zsh
+My own dotfiles. `zsh` configuration based on [antibody](https://github.com/getantibody/antibody) and [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh), `vim` configuration uses [vim-plug](https://github.com/junegunn/vim-plug), [ALE](https://github.com/dense-analysis/ale) and more.
+
+[ci.decapod.one status](https://ci.decapod.one/api/badges/2/status.svg)
+
+[zsh theme](docs/brethil-theme.png "zsh theme")
+[vim theme](docs/vim.png "vim theme")
+[tmux theme](docs/tmux.png "tmux theme")
 
 ## Description
 
     ├── README.md
     ├──────── Main files ────────
-    │ ├── aliases.zsh
-    │ │     └── aliases definitions (sources `~/.dotfiles_aliases`)
+    │ ├── aliases/
+    │ │     └── aliases definitions. Add .zsh files here to include more
+    │ ├── functions/
+    │ │     └── functions definitions. ADD .zsh files here to include more
     │ ├── colors.zsh
     │ │     └── ANSI color escapes
-    │ ├── functions.zsh
-    │ │     └── contains function definitions (sources `~/.dotfiles_functions`)
     │ ├── ansible
     │ │     └── ansible playboooks/config
-    │ └── brethil_dotfile.sh:
-    │       └── This file should be sourced by your `.zshrc`
-    ├──────── antibody plugins ────────
-    │ ├── antibody_plugins_arch.txt
-    │ └── antibody_plugins.txt
+    │ ├── brethil_dotfile.sh:
+    │ │     └── ansible playboooks/config
+    │ ├── antibody_plugins.txt
+    │ │     zsh plugins sourced by antibody
     ├──────── oh-my-zsh themes ────────
-    │ ├── brethil.zsh-theme
-    │ └── brethil-minimal.zsh-theme
+    │ ├── themes
+    │ │     ├─ brethil.zsh-theme
+    │ └     └─ brethil-minimal.zsh-theme
     ├──────── Misc rc files────────
     │ ├── gitconfig
     │ │     └── git configuration
-    │ ├── ipython
-    │ │     ├── profile_default
-    │ │     ├── ipython_config.py
-    │ │     ├── startup
-    │ │     ├── 11-autoreload.py
-    │ │     └── README
+    │ ├── ipython/
+    │ │     ├── ipython configs
     │ ├── vim
     │ │    ├── vimrc
     │ │    │ └── main vim rc
@@ -40,86 +42,53 @@ A set of zsh dotfiles based on antibody and oh-my-zsh
     │ │    │ └── plugins configuration
     │ │    ├── shortcuts.vim
     │ │    │ └── vim shortcuts definitions
-    │ │    ├── functions.vim
-    │ │    │ └── miscellaneous vim function
-    │ │    └── twilight256.vim
-    │ │      └── an old colorscheme
+    │ │    └── functions.vim
+    │ │      └── miscellaneous vim function
     │ └── pdbrc.py
     │      └── pdb++ rc (a drop-in replacement for pdb)
     ├──────── Other ─────────────
-    ├── check_for_update.sh
+    ├── extras/check_for_update.zsh
     │      └── selfupdate script
     └── useful_commands
 
 ## Installation
 
-- With ansible:
+### With ansible:
 
-  ```bash
-  bash dev/add_community.general.sh # only if community.general is not installed
-  ansible-playbook -v -i <hosts file> ansible/playbooks/setup.yml
-  ```
+```bash
+bash dev/add_community.general.sh # only if community.general is not installed
+ansible-playbook -v -i <hosts file> ansible/playbooks/setup.yml
+```
 
-  This playbook can be tested [with a docker container](dev/README.md)
+This playbook can be tested [with a docker container](dev/README.md)
 
-  Use `-e fix_annoyances=true` to fix some small annoyances (only run once)
+### Manually
 
-- Manually (this only installs the zsh configuration):
+This requires [antibody](https://github.com/getantibody/antibody) to be installed.
 
-  ```bash
-  git clone https://git.decapod.one/brethil/dotfiles ~/.dotfiles
-  echo 'DOTFILES=~/.dotfiles' >> ~/.zshrc
-  echo 'source $DOTFILES/brethil_dotfile.sh'
-  ```
+```bash
+git clone https://git.decapod.one/brethil/dotfiles ~/.dotfiles
+echo 'DOTFILES=~/.dotfiles' >> ~/.zshrc
+echo 'source $DOTFILES/brethil_dotfile.sh'
+ln -s ~/.dotfiles ~/.vimrc
+```
+
+## Updating
 
 A self-update mechanism is included. It asks for confirmation to pull the latest changes
 from the git repo every two weeks. This also updates the git-sourced repositories installed
 by the install script. The self-update routine can be called manually by calling
 
-    dotfiles_selfupdate
+```bash
+dotfiles_selfupdate
+```
 
-If you do not want to run the installer script, you can just add source `brethil_dotfile.sh`
-in your `.zshrc`. This requires antibody installed.
+This can be disabling by setting the `DISABLE_DOTFILES_AUTO_UPDATE` env var before before sourcing `brethil_dotfile.sh`
 
-### Available Functions
+## Try it out
 
-0.  `cheat`: show cheat sheet for commands using cheat.sh (`cheat <commandname>`)
-1.  Quickly edit/reload profile (`esource`/`resource`)
-2.  `dockertags` list all tags for a given docker image
-3.  `color` to print colored text (see 3. in the Misc section):
+Docker images are regularly built, and they include a full development environment (hence are quite large)
 
-        color $Red "This will be printed in red"
-        color $Yellow "This will be printed in red"
-
-4.  `git fixup` (`git-fixup`) to create a fixup command and immediately rebase it
-5.  Many more. Use `list_functions` to list defined functions and a small description
-
-### Files/Folders
-
-1. `~/bin`, `~/git`, `~/projects` folders
-2. ssh config (`~/.ssh/config`):
-   - Create ssh keys if not defined already
-   - Keep connections alive by increasing timeout time
-   - Include multiplexer to allow quick multiple connections to the same host
-   - (Optional: Compression, this should allow more responsive shells with slow connections,
-     but will slow things down when copying large files. My suggestion is to have compression enabled
-     on a by-host basis in `~/.ssh/config`)
-3. `brethil.zsh-theme`, `brethil-minimal.zsh-themes`, themes for oh-my-zsh.
-4. `~/.dotfiles_functions`, `~/.dotfiles_aliases` are sourced by this dotfiles, allowing for custom functions/aliases
-5. useful_commands contains a list of useful commands (the first rule of the tautology club...)
-
-### Misc
-
-1.  Colored output (via `grc`) for several commands.
-2.  Easy names for ANSI color escapes (Black, Red, Green, Yellow, Blue, Cyan, Purple, White, CLEAR), for example:
-
-        echo -e "${Green}This text will be green${CLEAR}"
-
-    will result in green text. Use `$CLEAR` to clear previous escape sequences add B before the variable (check `colors.sh`)
-    name to use **bold** and U to underline (examples: `$BRed`, `$UBlack` for bold red and underlined black)
-
-3.  Autoupdate script running every two weeks, autoupdate function: `dotfiles_selfupdate` (or `git pull` from `$DOTFILES`folder)
-4.  Automatic fix of the`SSH_AUTH_SOCK`environment variable:`~/.ssh/rc` is installed run on every ssh login,
-    and updates a symlink pointing (`~/.ssh/ssh_auth_sock`). `SSH_AUTH_SOCK`points to this (set in`brethil_dotfile.sh`).
-    The idea is that if the user is logging in using `ssh -A`, and using tmux, it will be possible to use
-    the remote socket over different sessions by always using the symlink.
+```bash
+docker run -it registry.decapod.one/brethil/dotfiles
+```
diff --git a/docs/brethil-theme.png b/docs/brethil-theme.png
new file mode 100644
index 0000000..98f270b
Binary files /dev/null and b/docs/brethil-theme.png differ
diff --git a/docs/tmux.png b/docs/tmux.png
new file mode 100644
index 0000000..162e986
Binary files /dev/null and b/docs/tmux.png differ
diff --git a/docs/vim.png b/docs/vim.png
new file mode 100644
index 0000000..2f46017
Binary files /dev/null and b/docs/vim.png differ