diff --git a/README.md b/README.md
new file mode 100644
index 0000000..abc56d3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,14 @@
+# spam management for forgejo
+
+## Usage
+
+- create an API token for your admin account, and write it in an `api_token`
+  file at the root of the repo
+- remove `model.json` if you want to start with no pre-existing model of what is
+  spam or not. Or keep it to use the current classifier. The file gets updated
+  when using the tool: the classifier learns from spam/legit decisions and
+  should get progressively better at identifying spam.
+- run: `cargo run`
+- classify users as spam/not spam. Right now the classification is stored
+  locally in `db.json`, no concrete action is taken. (Ultimately we will want to
+  lock/delete accounts, etc.)