diff --git a/README.md b/README.md
new file mode 100644
index 0000000..650cc69
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# frontpage (name pending)
+
+The front page of your self-hosted server.
+
+This app fits the use case of having multiple applications with access gated by
+an OIDC provider, and showing a user what applications they have access to.
+
+## Usage
+
+```sh
+frontpage -c CONFIG.TOML
+```
+
+where a minimal config file looks like:
+
+```toml
+[oidc]
+client_id = "some_id"
+client_secret = "some_secret"
+issuer = "https://auth.example.com/oauth"
+scopes = [ "groups" ]
+```
+
+Applications are defined using the `apps` keys:
+
+```toml
+[apps.login]
+name = "Login portal"
+url = "https://auth.example.com"
+description = "Update your user details"
+groups = [ "users" ]
+```
+
+In this example, only users whose OIDC groups claim includes `users` will be
+allowed to see a link to the login portal. Protection of the link, should a user
+gain access to it otherwise, is expected to be done externall (e.g., via an
+ingress controller).