diff --git a/README.md b/README.md
new file mode 100644
index 0000000..08184fd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# tci
+> tiny custom CI runner for your selfhosted just-git repositories 
+
+## why
+continuous integration is really convenient when you have quite some tiny projects which you'd like to keep updated.
+
+this one has its doc page, that one compiles to a minified js file that i should serve, this one has a demo instance that i should restart...
+
+i don't want to bother doing these things every time i write some fixes!
+
+also, i really like the idea of keeping CI configuration committed with the repository itself
+
+## how
+git natively supports [hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks). they are extremely convenient and pleasant to use (just a shell script!), but aren't version-controlled in the repository they belong to.
+
+i use them on my client to validate my commits and sometimes configure/cleanup projects
+
+because i self-host my git repositories (did you know you just need to `git init --bare <name>` in your home and you can pull/push from there! `git clone <user>@<host>:<repo-path>` just works), i can't just use github/gitlab, and would rather not go mad configuring jenkins
+
+most of my CIs are super simple: `cargo doc; cp * /srv/http/docs/`, configuring something complex like jenkins seems overkill
+
+# introducing tci!
+`tci` is a Tiny CI runner
+
+just set it as `post-update` hook in your repository and, each time such repository gets updated, tci will:
+ * make sure repo is allowed to run CI: checks said repo git config for `tci.allow == true`
+ * create a temp dir (under `/tmp`) with unique name
+ * clone your repository in that dir
+ * change current working directory to be inside your freshly cloned repo
+ * run `.tci` script (you can change it by setting git config `tci.script`)
+ * print script's `STDOUT` to console
+ * delete temporary directory
+
+and that's it! could not be simpler
+
+# using tci
+a very simple example: i'd like to auto-update cargo documentation for my project
+
+first step is enabling tci for such repo: `git config tci.allow true` on my server
+
+then i can just add a `.tci` script in the project root:
+```
+#!/bin/bash
+
+cargo doc
+rm -rf /srv/http/docs/*
+cp ./build/* /srv/http/docs/
+```
+
+just commit and push!
+
+### setting tci as default runner for every repository
+configuring tci as post-update hook for *each repository* is definitely annoying
+
+luckily, git allows us to configure a default hook location valid for every repository!
+inside your `~/.gitconfig` just insert:
+```
+[core]
+	hooksPath = /path/to/some/directory/
+```
+inside such directory, place `tci` and rename it to `post-update`
+
+and done! should enable tci for all repos (if they are configured to allow it)