diff --git a/persoconf/README b/persoconf/README
new file mode 100644
index 0000000..cc58296
--- /dev/null
+++ b/persoconf/README
@@ -0,0 +1,90 @@
+persoconf
+=========
+
+*persoconf* is a python script intended to keep track of all your personal
+configuration files (also known as dotfiles).
+
+Usage
+-----
+
+If you want to skip this and get to the point: there's a 'help' command
+available, and +--help/-h+ options for every other command.
+
+
+Add an app to your persoconf repo:
+
+----
+$> persoconf add myapp
+----
+
+
+Add dotfiles and config directories to this app:
+
+----
+$> persoconf add myapp ~/.myapp.config
+$> persoconf add myapp ~/.config/myapp/
+----
+
+
+List the files and dirs saved in persoconf for an app:
+
+----
+$> persoconf list -f
+tmux
+        tmux.conf
+awesome
+        rc.lua
+vim
+        vimrc
+myapp
+        myapp.config
+        myapp/
+----
+
+
+Check if modifications occured on your config files:
+
+----
+$> echo "some change in my conf" >> ~/.myapp.config
+$> persoconf check
+persoconf:WARNING: File ~/.myapp.config was modified
+----
+
+
+Update persoconf saved files with the latest configuration available:
+
+----
+$> persoconf update
+----
+
+
+Package your dotfiles to move them on another machine:
+
+----
+$> persoconf package --pkgtype tgz
+$> ls
+persoconf.20160602.tgz
+$> tar tzf persoconf.20160602.tgz
+.config/awesome/rc.lua
+.config/myapp/somefile
+.config/myapp/someotherfile
+.myapp.config
+.tmux.conf
+.vimrc
+----
+
+
+Internals
+---------
+
+All persoconf data is by default saved in a '.config/persoconf' directory. You
+can override this location with the global +--rootdir+ option. If the rootdir
+location does not exist when you first try to use persoconf, persoconf will ask
+if you want to create it.
+
+Basically, data is saved as is (which means textfiles and dirs, mostly), and
+metadata is saved as json files.
+
+
+
+// vim: set ft=asciidoc :