diff --git a/README.md b/README.md
index c354744..2f78caf 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,89 @@
-![](intro.gif)
+
+# Octopus Carnival
+
+Octpus Carnival is an environment for playing the [Machiavelli card game](https://en.wikipedia.org/wiki/Machiavelli_(Italian_card_game)) inside the terminal.
+It features a solver in order to play against the computer.
+
+![](ono_sendai/animation/intro.gif)
+
+## Getting Started
+
+### Prerequisites
+
+The Machiavelli solver is written in Ocaml:
+
+```
+opam install corebuild dune yojson core
+```
+
+The TUI is written in python:
+
+```
+pip3 install --user colorama picotui
+```
+
+## The game
+
+In order to play the game first build the solver:
+
+```
+cd octopus_carnival
+make
+```
+
+Then run the executable
+
+```
+./ono_sendai/start
+```
+
+
+
+## Contributing
+
+The folder structure follows a non standard layout for personal reasons.
+
+```
+.
+├── hosaka
+│   ├── cards.ml
+│   ├── dune
+│   ├── dune-project
+│   ├── hashset.ml
+│   ├── main.ml
+│   ├── printer.ml
+│   ├── table.ml
+│   ├── tcards.ml
+│   └── tests.ml
+├── makefile
+├── metro_holografix
+│   ├── cardtypes.py
+│   └── scrapes
+│       ├── alg.py
+│       ├── cardtypes.py
+│       ├── test.py
+│       └── vecchio.py
+├── ono_sendai
+│   ├── animation/
+│   ├── start
+│   ├── state.py
+│   ├── symbols.py
+│   └── widgets.py
+```
+
+* *hosaka* contains the code related to the solver
+* *metro_holografix* contains the python definitions for the cards and some prototypes
+* *ono_sendai* contains all the python code related to the game TUI
+
+
+## Authors
+
+* **Francesco Mecca** - [blog](https://francescomecca.eu)
+
+## License
+
+This project is licensed under the GPLv3 License - see the [LICENSE.md](LICENSE.md) file for details
+
+## Acknowledgments
+
+Thanks to my friend [Daniele](https://github.com/danseraf) that helped me to write the algorithm for the solver. 
diff --git a/ono_sendai/__pycache__/broker.cpython-36.pyc b/ono_sendai/__pycache__/broker.cpython-36.pyc
deleted file mode 100644
index befcfc3..0000000
Binary files a/ono_sendai/__pycache__/broker.cpython-36.pyc and /dev/null differ
diff --git a/ono_sendai/__pycache__/symbols.cpython-36.pyc b/ono_sendai/__pycache__/symbols.cpython-36.pyc
deleted file mode 100644
index 873a917..0000000
Binary files a/ono_sendai/__pycache__/symbols.cpython-36.pyc and /dev/null differ
diff --git a/ono_sendai/animation/__pycache__/octopus.cpython-36.pyc b/ono_sendai/animation/__pycache__/octopus.cpython-36.pyc
deleted file mode 100644
index fe60c53..0000000
Binary files a/ono_sendai/animation/__pycache__/octopus.cpython-36.pyc and /dev/null differ
diff --git a/intro.gif b/ono_sendai/animation/intro.gif
similarity index 100%
rename from intro.gif
rename to ono_sendai/animation/intro.gif
diff --git a/ono_sendai/animation/rec.ogv b/ono_sendai/animation/rec.ogv
new file mode 100644
index 0000000..52b9e4a
Binary files /dev/null and b/ono_sendai/animation/rec.ogv differ
diff --git a/ono_sendai/main.py b/ono_sendai/start
old mode 100644
new mode 100755
similarity index 99%
rename from ono_sendai/main.py
rename to ono_sendai/start
index 655ecd5..61b7c2f
--- a/ono_sendai/main.py
+++ b/ono_sendai/start
@@ -1,3 +1,4 @@
+#!/usr/bin/python3
 from picotui.context import Context
 from picotui.screen import Screen