diff --git a/hooks/README.md b/hooks/README.md
index 251d6fa..9b98269 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -1,2 +1,8 @@
-# replreg hooks api serer
+# replreg hooks
+
+This is the hooks server that also has the reaper for replreg.is.
+
+The webhooks from the registry are terminated in [src/controllers/HookAPI.ts](https://github.com/replicatedhq/replreg/blob/master/hooks/src/controllers/HookAPI.ts). The reaper runs on a cron and executes [src/commands/reap.ts](https://github.com/replicatedhq/replreg/blob/master/hooks/src/commands/reap.ts).
+
+
 
diff --git a/registry/README.md b/registry/README.md
new file mode 100644
index 0000000..2f3b8c6
--- /dev/null
+++ b/registry/README.md
@@ -0,0 +1,4 @@
+# replreg registry
+
+This is the registry server that runs in replreg.is. It's a configured Docker registry, using the registry:2 image. There the confguration installs a hook into the registry, that will fire notifications when an image is pushed. The work to expire and delete images happens in the hook directory.
+