diff --git a/docs/dev/pinned-coreos.md b/docs/dev/pinned-coreos.md
new file mode 100644
index 00000000000..177c48a2cbd
--- /dev/null
+++ b/docs/dev/pinned-coreos.md
@@ -0,0 +1,52 @@
+# CoreOS and the installer
+
+A key decision made before the release of OpenShift 4 is to pin the CoreOS bootimage in
+the installer: https://github.com/openshift/installer/commit/e080f0494708b2674fe37af02f670c8030c32bf6
+
+That is still the case today; when one gets an `openshift-install` binary, that
+binary contains the 2-tuple `(CoreOS, release image)`, meaning the result of an
+install will be the same thing each time.
+
+More background:
+
+ - https://github.com/openshift/enhancements/pull/201
+ - https://github.com/openshift/machine-config-operator/blob/master/docs/OSUpgrades.md
+
+## Stream metadata
+
+As of 4.8 the [stream metadata enhancement](https://github.com/openshift/enhancements/blobmaster/enhancements/coreos-bootimages.md)
+is in progress which provides a standardized JSON format and injects
+that data into the cluster as well.
+
+### Updating pinned stream metadata
+
+
+To update the bootimage for one or more architectures, use e.g.
+
+```
+$ plume cosa2stream --target data/data/rhcos-stream.json --distro rhcos  x86_64=48.83.202102230316-0 s390x=47.83.202102090311-0 ppc64le=47.83.202102091015-0
+```
+
+For more information on this command, see:
+
+- https://github.com/coreos/coreos-assembler/pull/2000 
+- https://github.com/coreos/coreos-assembler/pull/2052
+
+### Updating pinned legacy metadata
+
+To update the legacy metadata, use:
+
+```
+./hack/update-rhcos-bootimage.py https://releases-art-rhcos.svc.ci.openshift.org/art/storage/releases/rhcos-4.6/46.82.202008260918-0/x86_64/meta.json amd64
+```
+
+This will hopefully be removed soon.
+
+### Origin of stream metadata
+
+
+For historical reference, the initial file `data/data/rhcos-stream.json` was generated this way:
+
+```
+$ plume cosa2stream --name rhcos-4.8 --distro rhcos  x86_64=48.83.202102230316-0 s390x=47.83.202102090311-0 ppc64le=47.83.202102091015-0 > data/data/rhcos-stream.json
+```
diff --git a/hack/update-rhcos-bootimage.py b/hack/update-rhcos-bootimage.py
index 9be44086c35..c236c50d057 100755
--- a/hack/update-rhcos-bootimage.py
+++ b/hack/update-rhcos-bootimage.py
@@ -1,24 +1,6 @@
 #!/usr/bin/env python3
-# As of 4.8 we are aiming to switch to stream metadata:
-# https://github.com/openshift/enhancements/pull/679
-# That transition hasn't yet fully completed; there are two copies of the
-# RHCOS metadata:
-# 
-# - data/data/rhcos-4.8.json (stream format, 4.8+)
-# - data/data/rhcos-$arch.json (openshift/installer specific, 4.7 and below)
-# 
-# See https://github.com/coreos/coreos-assembler/pull/2000 in particular.
-# 
-# The initial file data/data/rhcos-4.8 was generated this way:
-# 
-# $ plume cosa2stream --name rhcos-4.8 --distro rhcos  x86_64=48.83.202102230316-0 s390x=47.83.202102090311-0 ppc64le=47.83.202102091015-0 > data/data/rhcos-4.8.json
-# 
-# To update the bootimage for one or more architectures, use e.g.
-# 
-# $ plume cosa2stream --target data/data/rhcos-4.8.json --distro rhcos  x86_64=48.83.202102230316-0 s390x=47.83.202102090311-0 ppc64le=47.83.202102091015-0
-#
-# To update the legacy metadata, use:
-# Usage: ./hack/update-rhcos-bootimage.py https://releases-art-rhcos.svc.ci.openshift.org/art/storage/releases/rhcos-4.6/46.82.202008260918-0/x86_64/meta.json amd64
+# This script updates the legacy metadata.  We hope to remove it soon.
+# See docs/dev/pinned-coreos.md for more information.
 import codecs,os,sys,json,argparse
 import urllib.parse
 import urllib.request
diff --git a/pkg/rhcos/builds.go b/pkg/rhcos/builds.go
index 6bcdb68a797..089a340c363 100644
--- a/pkg/rhcos/builds.go
+++ b/pkg/rhcos/builds.go
@@ -1,7 +1,6 @@
 // package rhcos contains APIs for interacting with the RHEL (or Fedora) CoreOS
 // bootimages embedded as stream metadata JSON with the installer
-// For more information, see
-// https://github.com/openshift/enhancements/pull/679
+// For more information, see docs/dev/pinned-coreos.md
 
 package rhcos