diff --git a/Gopkg.lock b/Gopkg.lock
index 09c5758..7ba9474 100644
--- a/Gopkg.lock
+++ b/Gopkg.lock
@@ -99,6 +99,12 @@
   packages = ["."]
   revision = "fc61389e27c71d120f87031ca8c88a3428f372dd"
 
+[[projects]]
+  branch = "master"
+  name = "github.com/heroku/herald"
+  packages = ["."]
+  revision = "fbd3cb7ab5f340ee558156704a87c479cedff809"
+
 [[projects]]
   name = "github.com/jmespath/go-jmespath"
   packages = ["."]
@@ -186,6 +192,6 @@
 [solve-meta]
   analyzer-name = "dep"
   analyzer-version = 1
-  inputs-digest = "66f216da55122e2bdeccb44d15182200ff48bee768ba3ab20b617c7a06af102d"
+  inputs-digest = "baacdf83216b959d4c87dc791bda3a16d71fa347ea289c13d5bb1c3823994084"
   solver-name = "gps-cdcl"
   solver-version = 1
diff --git a/README.md b/README.md
index 46c9905..a0cb8f4 100644
--- a/README.md
+++ b/README.md
@@ -19,10 +19,25 @@ This system is written in the Go programming language.
 
 - [heroku-herald GitHub profile](https://github.com/heroku-herald)
 
-## Buildpack API
+## Add a Check to Herald
 
-- Each builpack contains a `versions` directory, containing executables that print out, one per line, available version numbers.
-- Each executable provided is a "target" that the buildpack needs to track versions of.
+Herald assumes that you have a buildpack in a git repo that contains a `versions` branch, and in that versions branch there is a `versions` folder. In that folder it will look for executables. For example in the Ruby buildpack https://github.com/heroku/heroku-buildpack-ruby/tree/versions/versions.
+
+When the executable is run, it should print out an available version number. One per line. For example in the Ruby buildpack:
+
+```term
+$ versions/ruby
+2.5.1
+2.4.4
+2.3.7
+2.2.10
+2.6.0-preview1
+#...
+```
+
+The list of buildpacks is in a go "map" like a dict in Python or a hash in Ruby in `herald.go`.
+
+Once every 15 minutes the `herald/cmd/version-scraper/main.go` script will execute against all buildpacks and record the result in Redis. When it is detected that there is a new entry, then a new issue will be opened up on that buildpack.
 
 ☤