diff --git a/README.org b/README.org
new file mode 100644
index 00000000..1a1a94a3
--- /dev/null
+++ b/README.org
@@ -0,0 +1,78 @@
+* 0k-charms
+
+This package provides charms, which are special system recipes, that are
+meant to be executable and mangled together to allow managing a wide set
+of services.
+
+Inspired by [[https://discourse.juju.is/t/introduction-to-juju-charms/1188][juju charms]], these are mostly bash scripts organized by
+service and meant to automate all administration tasks, from
+installation, to connection with other services, or any other task a
+service would need.
+
+Several tools are able to read the current state of this repository to
+effectively deploy full production grade services on different type of
+platform.
+
+The only real fully functional implementation is =0k-compose=. It will
+use these charms to drive, prepare, and build in =docker=, complete sets
+of services.
+
+Another old solution called =lxc-deploy= was used actively before to deploy
+services on LXC tool set until 2016 using these charms.
+
+Bare hosts can also replay some recipes to install services directly
+on them via the =0k-charm= project using the =charm apply=
+command. Note that actually, as most recipes are bash executable, it
+is still a viable option to copy-paste parts of source-code of these
+scripts. These last two options are still used very often to bootstrap
+installs of =docker-hosts= for instance.
+
+
+* Maturity
+
+Charms in these repository are in a wide set of maturity, from simple note
+taking of shell commands, not even executable, to full charm allowing to
+deploy services and manage the full life cycle of the service.
+
+The repository in a whole is thus NOT considered as mature at all, and will
+require some thorough cleaning and decisions to furthermore structure to reach
+a state where it'll make sense to go full public.
+
+* Usage
+
+** TODO Through =compose= for full deployment of sets of services
+
+Requires =0k-compose= package that contains the =compose= command line tool.
+
+TBD
+
+** TODO Through =lxc-deploy= for full install and deployment of services
+
+Requires =lxc-scripts= package that holds several tools for LXC
+management, amongst them is =lxc-deploy=.
+
+TBD
+
+** TODO Through =docker-build-charm= for docker image creation
+
+Requires =0k-docker= package that holds several tools for docker
+management, amongst them is =docker-build-charm=.
+
+=docker-build-charm= will use the =install= recipes in a charm to
+basically mimic the =Dockerfile= purpose and create a docker image for
+a specific service.
+
+TBD
+
+** TODO Through =0k-charm= for bare hosts installs
+
+Requires =0k-charm= package to get the =charm= command line util.
+
+TBD
+
+
+* Installation
+
+Most tools should check the =CHARM_STORE= bash environment variable
+that should be the path to reach the root of this repository. If not
+defined, most tools will look in =/srv/charm-store= by default.
diff --git a/README.rst b/README.rst
deleted file mode 100644
index cbb624d0..00000000
--- a/README.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-0k-charms
-=========
-
-This package provides charms for the ``lxc-deploy`` and
-``docker-build-charm`` commands respectively from ``lxc-scripts`` and
-``0k-docker`` packages.
-
-A charm is basically a set of metadata and a shell script that will be
-executed to create an image for lxc or docker.
-
-
-Installation
-============
-
-Be sure to install ``lxc-scripts`` and ``0k-docker`` packages and that
-their binaries are accessible to user 'root'.
-
-By default, ``lxc-deploy`` and ``docker-build-charm`` will look for the
-charm store to be located in ``/srv/charm-store``. This can be a symbolic
-link.
-
-For instance, if ``0k-charms`` is installed in ``/opt/apps/0k-charms``, 
-you would do::
-
-    ln -sf /opt/apps/0k-charms/precise /srv/charm-store
-