diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..009c9c8
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,58 @@
+# dlist ~ one-dimensional flat CMS
+
+This is a prototype for a small software pubblication format.
+The idea is to use a single text file written as a list as Content Managment System. 
+
+The syntax of this file is really minimal, and it works together with the linear nature of the list to organize the contents. There are just a couple of level of hierarchy, hence the idea of 1D or flat structure and the `.1dl` extension (1-dimension list)(lame name!)
+
+Wait, maybe 1D is just a point and to be flat one needs at least two dimensions? If so noooooo now i need to rename everything xox
+
+``` 
+(title)
+[section]
+--> Notes
+>>comment (TBD)
+Normal text
+```
+
+To work with some syntax highlighting i tried to set upt a file format and a syntax file for the vim text editor.
+
+Ideally this cms could be parsed line by line, mapping for every `(title)` all the `[sections]` till the next title, as well as their contents. 
+
+The `-->` note tag could be used either as more chatty discussion inside the cms (that is meant to be multi-player) or to address and highlight certain parts.
+
+## Example
+
+This is a test for the situated-doc list prototype. The idea is to write several software we developed like `(padliography2) (workbook) (si16)`, and for each of them give an overview or a way to navigate all their scattered contents. 
+
+Blank lines should not be a problem: future parsers could just ignore them. And visually it helps to have spaces in the text file. 
+
+Here an example for the treatment of one tool, the Padliography:
+
+```
+(padliography2)
+
+[what]
+an interface to archive links on the wiki
+mainly used for pads
+several instances of the archive can be initialized
+directly from the tool
+so multiple archives can coexhist together
+
+[where]
+https://hub.xpub.nl/soupboat/padliography
+
+[doc]
+https://git.xpub.nl/kamo/pad-bis
+https://pzwiki.wdka.nl/mediadesign/Padliography
+
+Notes on the doc
+--> I’d like to see more memes, they help me understanding the process more
+--> I like the toads
+--> more images please!
+--> I think the syntax could be more accessible by writing shorter sentences, or sentences that only focus on 1 thing. I'll elaborate after lunch
+
+[dev]
+v2 -- current
+https://git.xpub.nl/kamo/pad-bis
+```