diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..069cf1982d04d1cda11e682d67a289a476162277
--- /dev/null
+++ b/README.md
@@ -0,0 +1,106 @@
+# Aug\[m\]entile – Augment Matrix rooms with a tile map game
+
+**Augment Matrix rooms with a tile map game**
+
+## Introduction
+
+Aug\[m\]entile is a Matrix-based tile map game player, meaning that
+it uses [Matrix](https://matrix.org) rooms as backend for players
+moving around and playing on a two-dimensional tile map. It is inspired
+[Work Adventure](https://workadventu.re/) and the decentralisation
+efforts by the people around [Fediventure](https://fediventure.net/).
+
+Primarily, Aug\[m\]entile is intended to be added as a
+[widget](https://matrix.org/blog/2017/08/23/introducing-matrix-widgets),
+and the game subsequently be played inside a Matrix client with
+widget support, e.g. the [Element](https://element.io/) web client.
+
+### Use cases
+
+The use cases are basically the same as for Work Adventure. Aug\[m\]entile
+is especially useful and a considerable alternative for groups or events
+that already use Matrix for other parts of their event or infrastructure.
+
+Examples include:
+
+* Hack spaces with virtual spaces and meetups
+* Team or company hangout
+* Conferences, e.g. FOSS or hacker conferences
+
+## Making maps
+
+Maps can be created with the [Tiled](https://www.mapeditor.org/) map
+editor, and Aug\[m\]entile strives for compatibility with
+[Work Adventure map building](https://workadventu.re/map-building)
+features.
+
+### Deviations from Work Adventure maps
+
+In order to integrate better with Matrix, some deviations and extensions
+have been made to the map concepts.
+
+* **Exits**: `exitUrl` can contain a simple name of another map in the
+             same room, if maps are added to the room state
+* **Special zones**: Not supported for now, as this requires interaction
+                     with other widgets in the room
+* **Scripts**: Scripts in `iframe`s are not supported, and instead of
+               the Work Adventure client API, the
+			   [Matrix Widget API](https://github.com/matrix-org/matrix-widget-api)
+			   is available to scripts
+
+## Managing game and maps in a room
+
+For now, there is no frontend for game management. Since Matrix uses a
+simple [HTTP client-server API](https://matrix.org/docs/spec/client_server/latest),
+management can be done using any HTTP client, like [cURL](https://curl.se/).
+
+You will need an access token for a nauthenticated server session and for a user
+that has sufficient power in the room. Normally, this means you need to be a room
+admin, or the room needs to have specific power levels configured for the respective
+events.
+
+Some parts allows users to define their own data in a state by using their Matrix ID
+as state key. By default, these states can be set by each user for themselves.
+
+### Adding maps to a room
+
+Any Matrix room can be augmented with an arbitrary number of maps, by adding the
+[JSON formatted map](https://doc.mapeditor.org/en/stable/reference/json-map-format/)
+to the room state under the `team.auglement.augmentile.maps` event. The state key
+is the map name, which can be used as `exitUrl` in other maps.
+
+To add a Tiled map to a Matrix room, export your map in JSON format (we will assume
+you saved it to `mymap.json`). Then, use cURL to set the state:
+
+```sh
+curl \
+  -X PUT \
+  -H "Authorization: Bearer AccessToken" \
+  -H "Content-Type: application/json" \
+  -d @mymap.json \
+  https://matrix.org/_matrix/client/r0/rooms/%21roomid%3Amatrix.org/state/team.auglement.augmentile.maps/mymap
+```
+
+### Adding the game as room widget
+
+Using the Element client, the widget can be added with the `/addwidget` command.
+
+The Aug\[m\]entile widget can be self-hosted on any webspace (it does not need
+any active server component), or loaded from the central Auglement webserver if
+that does not raise privacy concerns.
+
+Pass the map name to use as GET parameter `map`, and use placeholders for Element
+to pass the widget and user IDs into. For the centrally hosted code, this looks
+like:
+
+```plain
+/addwidget https://augmentile.auglement.team/code/widget.html/#/?map=mymap&widgetId=$matrix_widget_id&userId=$matrix_user_id
+```
+
+## Development and license
+
+Aug\[m\]entile is developed as part of the [Auglement](https://auglement.team)
+collection on the [EduGit](https://edugit.org/auglement/augmentile) platform.
+
+The project is free and open software, licensed under the
+[Apache License, Version 2.0 or newer](https://www.apache.org/licenses/LICENSE-2.0).