diff --git a/README.md b/README.md
index 32fb4d0..c89d36f 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,8 @@
-# 🐕 doggo
+
+
+ 
+
+
@@ -8,18 +12,52 @@
-## ⚙️ Run
+**Doggo** is a basic dog AI developed in Python, using pygame as a rendering engine. The dog just walks around the screen, changing states and direction randomly and dog's fur color is also picked randomly at start. State changes are based on a [Markov chain](https://en.wikipedia.org/wiki/Markov_chain), which is a simple model to represent a sequence of possible events in which the probability of each event depends only on the state attained in the previous event.
+
+Here is a list of the dog states: *idle*, *idle and bark*, *walk*, *walk and bark*, *sit*, *sit and bark*, *lie down*, *lie down and bark*., *run*, *run and bark*, *stand*, *stand and bark*, *sleep*.
+
+
+ 
+
+
+**Project context**: A colleague of mine wanted to have a dog, but he couldn't because of lots of reasons. So I decided to make him a virtual dog and it was the opportunity for me to play with Markov chains.
+
+
+ 📦 Download latest release 📦
+
+
+## Run
-**doggo** use [poetry](https://python-poetry.org/) to manage dependencies and virtual environment.
+**Doggo** use [poetry](https://python-poetry.org/) to manage dependencies and virtual environment.
```bash
poetry install
poetry run python -m doggo
```
-## 📝 Licenses
+### Interactions
+
+The project is designed as a simple pet widget to keep on your desktop. It's an always-on-top borderless window, so you need to click on it to get the focus before interacting with it.
+
+* `ESC` to quit.
+* `Left Click` to move the window around.
+
+## Packaging
+
+If you want to package the project locally, you can use the script in `scripts/build.py`. It uses [PyInstaller](https://www.pyinstaller.org/) under the hood. Don't hesitate to update the script to fit your needs.
+
+```bash
+# Available os options: win32 , win64
+poetry run python scripts/build.py --os
+```
+
+## Development
+
+For now, only one biome (mountain) is available. The feature to pick a biome randomly at start is already implemented, so I wish to add more in the future. Otherwise, I don't plan to add more features, like weathers or interactions, but the project is open to contributions. Just open a discussion before to make sure your idea fits the project.
+
+## Licenses
* Code source under [GPL-3.0 License](https://www.gnu.org/licenses/gpl-3.0.en.html)
* Assets:
- * Dog sprites in `src/doggo/assets/dogs` by [Benvictus](https://benvictus.itch.io/pixel-dogs)
- * Landscape sprites in `src/doggo/assets/landscapes` under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+ * All assets under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+ * Excepting dog sprites in `src/doggo/assets/dogs` by [Benvictus](https://benvictus.itch.io/pixel-dogs)
diff --git a/images/demo.gif b/images/demo.gif
new file mode 100644
index 0000000..826cbbc
Binary files /dev/null and b/images/demo.gif differ