diff --git a/README.md b/README.md
index 72ed14e..2dc7474 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,49 @@
 
 # Plerobuddies
 
-Yay! (TODO)
+Yay! **Working examples** say more than a 1000 words:
+
+- [@acvilagers@chat.brainbaking.com](https://chat.brainbaking.com/@acvillagers)
+- [@gblegacy@chat.brainbaking.com](https://chat.brainbaking.com/@gblegacy)
+
+![Screenshot from a Pleroma instance](https://raw.githubusercontent.com/wgroeneveld/plerobuddies/master/screenshot.jpg)
+
+## Mastodon/Pleroma Buddies (bots)
+
+Execute through `yarn toot` or `yarn node src/chat.js`. It cycles through all configured "buddies" and toots a message accordingly. Use your favorite `crontab` timestamp to fire off toots automatically. 
+
+### Creating a new buddy
+
+Create a directory in `src/buddies/` and add it to `config.js` using the same name. Each buddy should have a `buddy.js` with one exposed method called `chat`, which gets executed with a config parameter. Look at the examples for more information. End the file with something like `module.exports = { chat }`.
+
+The function `chat` should create a "toot", with the following structure:
+
+```js
+{
+    "toot": "hi there buddy!",
+    "attach": [ "file1.jpg", "file2.jpg" ],
+    "attachDescription": `Screenshots of game x`
+}
+```
+
+An `attach` and its description are optional. Newlines using `\n` in a toot are allowed. 
+
+### Configuring the buddies
+
+See `config.sample.js`. A config file should expose `buddies` as an array with the following structure:
+
+```js
+{
+    name: "buddyname", // same as the dir name
+    instance: "https://mastodon.social", // where to post to
+    oauthToken: "my-token" // the oauth token for that server/user to post the status  with
+}
+```
+
+Optional config flags can be used in the chat function if desired. 
+
+## How to get an OAuth token from a Masto?Pleroma instance?
+
+I've prepared a few utility functions in `registerApp.js` for you. First, call `await register()`, which prints an URL to go to. Next, fill in the client id, secret, and returned token, after granting the app access to read and write. Then, call `await fetchToken()`. Paste that token in the config file. Done!
+
+Token refreshing is not (yet) implemented. Most tokens are valid for a year or so. Who knows what'll happen then. 
diff --git a/screenshot.jpg b/screenshot.jpg
new file mode 100644
index 0000000..79d0d81
Binary files /dev/null and b/screenshot.jpg differ