diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..c056918
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,60 @@
+## Description
+
+`type2` is a slow, but versatile parser for context free languages (type 2 in the Chomsky hierarchy).
+
+Being fed with a JSON file, specifying the language and a string via `stdin`, it decomposes the input, analyzes it and spits out its corresponding abstract syntax tree on `stdout`.
+
+A typical call looks like this: `type2 language.tp2.json < input.txt`
+
+
+## Language specification
+
+A language is specified by a JSON file containing a value of the following type:
+
+```
+record<
+	lexer_rules:list<
+		record<
+			type:string,
+			parameters:map<string,any>
+		>
+	>,
+	parser_rules:list<
+		record<
+			label:string,
+			premise:string,
+			conclusion:list<
+				record<
+					type:string,
+					parameters:map<string,any>
+				>
+			>
+		>
+	>,
+	parser_start:string
+>
+```
+
+The recommended extension for such files is `.tp2.json`.
+
+
+### Lexer rule types
+
+| type | meaning | parameters |
+|-- |-- |-- |
+| `ignore` | disregard matching strings | `pattern` |
+| `void` | do not assign a value to matching strings | `pattern`,`id` |
+| `boolean` | interpret matching strings as boolean values | `pattern`,`id`,`value` |
+| `int` | interpret matching strings as integer number values | `pattern`,`id` |
+| `float` | interpret matching strings as floating point number values | `pattern`,`id` |
+| `string` | interpret matching strings as string values | `pattern`,`id` |
+
+
+### Conclusion element types
+
+| type | meaning | parameters |
+|-- |-- |-- |
+| `terminal` | | `id` |
+| `variable` | | `id` |
+
+
diff --git a/type2.prj.json b/tools/build.prj.json
similarity index 100%
rename from type2.prj.json
rename to tools/build.prj.json