diff --git a/README.md b/README.md
index 24426ef..8fa699b 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,60 @@
-Emojii picker element - https://github.com/nolanlawson/emoji-picker-element
+![Repo Icon](https://git.bkr.im/repo-avatars/12a182cc6e89ce28b015f68c4cce0af64fc705477d27dd7e3307e3d2a972c119)
+
+# Post → status.lol
+
+A lightweight PWA for posting status updates to [status.lol](https://home.omg.lol/) (part of the omg.lol ecosystem). Pick an emoji, write a message, and optionally cross-post to Mastodon - all from a simple installable web app.
+
+Your credentials are stored only in your browser's local storage and are never sent anywhere except the omg.lol API.
+
+## Screenshot
+
+_Screenshot coming soon_
+
+## Features
+
+- Emoji picker for status icons
+- Up to 5,000 character status messages with live character count
+- Optional URL attachment per status
+- Optional Mastodon cross-posting with configurable visibility
+- Auto/light/dark theme (respects system preference)
+- Installable PWA
+- No build step, no dependencies
+
+## Requirements
+
+- An [omg.lol](https://home.omg.lol/) account
+- Your omg.lol API key (find it at [home.omg.lol/account](https://home.omg.lol/account))
+- Any HTTP server
+
+## Running Locally
+
+1. Clone the repository:
+
+   ```sh
+   git clone https://git.bkr.im/ritual/status-poster.git
+   cd status-poster
+   ```
+
+2. Serve the files over HTTP:
+
+   ```sh
+   python3 -m http.server 8000
+   ```
+
+   Then open `http://localhost:8000` in your browser.
+
+3. Open settings (the gear icon), enter your omg.lol **username** and **API key**, and save.
+
+That's it.
+
+## Deployment
+
+A `deploy.sh` script is included that you can use as a template for your own if you want. I pull directly from git and this script does that and then busts the bloody cache for me.
+
+```sh
+./deploy.sh
+```
+
+## Dependencies
+
+- [emoji-picker-element](https://github.com/nolanlawson/emoji-picker-element) — loaded from CDN, no install required