diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..954d3c3e1dbe43ebf3890cc1097925635d7e19a2
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,12 @@
+CalCat proxy server to help make detector corrections reproducible
+
+Detector corrections have to query `CalCat <https://in.xfel.eu/calibration/>`_
+to find calibration constants. This might be an issue for reproducibility, if
+CalCat's APIs change, or if it selects different constants to correct the same
+data. CalParrot stores CalCat responses in an SQLite database for each
+correction, and replays them if the same queries are made again, so reproducing
+a correction doesn't need to talk to CalCat again.
+
+This only affects code that works by querying the CalCat REST API, using the
+settings from ``cal_tools.restful_config``. Code that queries over ZeroMQ, using
+iCalibrationDB and calDBRemote, will bypass CalParrot.
diff --git a/pyproject.toml b/pyproject.toml
index 40d21bbe399c6999b924f93648b22fe285c62d7d..71302b4b59a23e583f77dd6719db6fa0431e9a2d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,6 +5,7 @@ build-backend = "flit_core.buildapi"
 [project]
 name = "calparrot"
 authors = [{name = "EuXFEL Calibration Team"}]
+readme = "README.rst"
 dynamic = ["version", "description"]
 dependencies = [
     "oauthlib",