diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7fff460
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+# better
+
+a 2.4.3. addon that tells you what item you can equip at a given slot to improve stat X.
+Written in Fennel (Lisp on Lua).
+
+The basic idea is that you're like level 15 melee and you're barely out of
+the starting zone and are about to tackle your first couple of elite mobs
+and you wnat to for example do most damage possible.
+
+So for melee you need strength, agility, crit etc, and you want to see
+what axe or mace or sword will give you more DPS output at lv 15.
+
+So you run
+
+```
+/better MainHand 3
+```
+
+where 3 means Agility, or
+
+```
+/better MainHand 4
+```
+
+and 4 is Strength. Later on I'll make it accept
+just "/better MainHand agility" or similar, for now there's a list of stats
+in the Fennel source code (they are 0-indexed so nr 3 is actually fourth).
+
+## Known issues
+
+Currently there's a couple of problems and things missing such as
+
+- head/trinket/finger slots report wrong item types
+- items which grant you e.g. like 5 more strength but reduce armor should get disqualified
+- generic querying ("/better MainHand DPS" or "/better Shoulder Heal" or "/better Legs Crit")
+- code cleanup
\ No newline at end of file