diff --git a/brew.sh b/bin/install-brew.sh
similarity index 100%
rename from brew.sh
rename to bin/install-brew.sh
diff --git a/npm.sh b/bin/install-npm.sh
similarity index 100%
rename from npm.sh
rename to bin/install-npm.sh
diff --git a/ruby.sh b/bin/install-ruby.sh
similarity index 100%
rename from ruby.sh
rename to bin/install-ruby.sh
diff --git a/bin/install.sh b/bin/install.sh
index c67e735..0d0b980 100755
--- a/bin/install.sh
+++ b/bin/install.sh
@@ -7,16 +7,23 @@
 # https://github.com/michaeljsmalley/dotfiles/blob/master/makesymlinks.sh
 ########################################################################
 
+set e
+
 # ----------------------------------------------------------------------
 # Variables
 # ----------------------------------------------------------------------
 
 # dotfiles directory
-dir=$DOTFILES_DIR
+cd ../
 
 # list of files/folders to symlink in homedir
 files="aliases bashrc bash_profile bash_paths bash_prompt exports gemrc gitconfig gitignore hushlogin inputrc private npmrc bin tmux.conf"
 
+# ----------------------------------------------------------------------
+# create the private file first, will be symlinked but ignored by git
+# ----------------------------------------------------------------------
+
+touch private
 
 # ----------------------------------------------------------------------
 # create symlinks from the homedir to any files in the dotfiles directory
@@ -24,18 +31,16 @@ files="aliases bashrc bash_profile bash_paths bash_prompt exports gemrc gitconfi
 # ----------------------------------------------------------------------
 
 for file in $files; do
-    ln -s $dir/$file ~/.$file
+    ln -s $file ~/.$file
     echo "$(tput setaf 64)✓$(tput sgr0) Created symlink to $(tput setaf 37)$file$(tput sgr0)"
 done
 
-
 # ----------------------------------------------------------------------
 # source what we just created
 # ----------------------------------------------------------------------
 
 source ~/.bash_profile
 
-
 # ----------------------------------------------------------------------
 # Homebrew
 # ----------------------------------------------------------------------
@@ -45,14 +50,13 @@ echo "           Brewing all the things. "
 echo "============================================="
 echo "$(tput sgr0)" # reset
 
-$dir/brew.sh
+bin/install-brew.sh
 
 echo "$(tput setaf 64)" # green
 echo "---------------------------------------------"
 echo "                 ✓ done"
 echo "$(tput sgr0)" # reset
 
-
 # ----------------------------------------------------------------------
 # npm
 # ----------------------------------------------------------------------
@@ -62,14 +66,13 @@ echo "             npm all the things. "
 echo "============================================="
 echo "$(tput sgr0)" # reset
 
-$dir/npm.sh
+bin/install-npm.sh
 
 echo "$(tput setaf 64)" # green
 echo "---------------------------------------------"
 echo "                 ✓ done"
 echo "$(tput sgr0)" # reset
 
-
 # ----------------------------------------------------------------------
 # Ruby
 # ----------------------------------------------------------------------
@@ -79,14 +82,13 @@ echo "             Ruby all the things. "
 echo "============================================="
 echo "$(tput sgr0)" # reset
 
-$dir/ruby.sh
+bin/install-ruby.sh
 
 echo "$(tput setaf 64)" # green
 echo "---------------------------------------------"
 echo "                 ✓ done"
 echo "$(tput sgr0)" # reset
 
-
 echo "$(tput setaf 64)" # green
 echo "============================================="
 echo "                 ✓ all done"
diff --git a/bin/update-dotfiles.sh b/bin/update-dotfiles.sh
index 6a952e0..b86b4e7 100755
--- a/bin/update-dotfiles.sh
+++ b/bin/update-dotfiles.sh
@@ -12,7 +12,7 @@
 # ----------------------------------------------------------------------
 
 # dotfiles directory
-dir=$DOTFILES_DIR
+cd ../
 
 # list of files/folders to symlink in homedir
 files="aliases bashrc bash_profile bash_paths bash_prompt editorconfig exports gemrc gitconfig gitignore hushlogin inputrc private npmrc bin tmux.conf"
@@ -33,7 +33,7 @@ done
 # ----------------------------------------------------------------------
 
 for file in $files; do
-    ln -s $dir/$file ~/.$file
+    ln -s $file ~/.$file
     echo "$(tput setaf 64)✓$(tput sgr0) Created symlink to $(tput setaf 37)$file$(tput sgr0)"
 done
 
diff --git a/bin/updaterepos.sh b/bin/updaterepos.sh
index 55d278e..22a43ac 100755
--- a/bin/updaterepos.sh
+++ b/bin/updaterepos.sh
@@ -1,10 +1,10 @@
 #!/usr/bin/env bash
 # 
 # Usage:
-# ./update_git_repos.sh [parent_directory] 
+# ./updaterepos.sh [parent_directory] 
 #
 #   example usage:
-#   ./update_git_repos.sh projects/ [MAKE SURE YOU USE / SLASHES]
+#   ./updaterepos.sh projects/ [MAKE SURE YOU USE / SLASHES]
 #
 # stolen from:
 # http://stackoverflow.com/a/36800741/733677
diff --git a/npmrc b/npmrc
index 503bed2..b5fed97 100644
--- a/npmrc
+++ b/npmrc
@@ -1,8 +1,2 @@
-
-# Use european registry to be faster
-#registry = http://registry.npmjs.eu
-
-# Make npm less noisy
-# If only it would work...
-# https://github.com/npm/npm/issues/4186
-loglevel = warn
\ No newline at end of file
+loglevel=warn
+sign-git-tag=true
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..b37e272
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,35 @@
+# dotfiles
+
+> 👩‍🎤 personal dotfiles, scrambled together from the interwebz. Highly macOS oriented.
+
+![hackerman](https://cloud.githubusercontent.com/assets/90316/26279873/9240a9d8-3dc0-11e7-9353-783b36ae6aff.jpg)
+
+## Installation
+
+Clone this repository and execute the install script to symlink respective dotfiles into `~/` and run installation of Homebrew, Ruby & npm:
+
+```bash
+git clone git@github.com:kremalicious/dotfiles.git
+cd dotfiles
+./bin/install.sh
+```
+
+Have a look at the [install.sh](bin/install.sh) script to see what's happening. Installation assumes macOS and will fail on other systems.
+
+## Update
+
+Will update the symlinked dotfiles, useful if new dotfiles have been added:
+
+```bash
+git pull
+./bin/update-dotfiles.sh
+```
+
+## Custom scripts
+
+Script | Description
+---    | ---
+`colors.sh` | print out all available colors with their values in the Terminal
+`tor.sh` | start Tor and switch the system-wide proxy settings in macOS. [More info](https://kremalicious.com/simple-tor-setup-on-mac-os-x/)
+`updaterepos.sh` | recursively updates all git repositories within the given folder
+`update-everything.sh` | update macOS, Mac App Store apps, Homebrew packages, (global) npm packages, Ruby via rvm, and refresh GPG keys all in one command. Aliased to `update`