diff --git a/README.md b/README.md
index 93299bb..60aae43 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,28 @@
 # Millrace
 
+## Usage
+
+```
+class UsersController
+
+  before_action Millrace::RateLimit.new(
+    name: "follows",
+    rate: 1/60.0, # 1 request per minute
+    window: 1.minute,
+    penalty: 10.minutes,
+  ), only: :create
+
+  rescue_from Millrace::RateLimited do |error|
+    # perhaps record metrics here
+    response.set_header "Retry-After", error.retry_after
+    head :too_many_requests
+  end
+
+...
+
+end
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/millrace. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/millrace/blob/main/CODE_OF_CONDUCT.md).