diff --git a/scripts/sweeps/estate-pin-integrity.sh b/scripts/sweeps/estate-pin-integrity.sh
index 1a51df73..727f9178 100755
--- a/scripts/sweeps/estate-pin-integrity.sh
+++ b/scripts/sweeps/estate-pin-integrity.sh
@@ -111,6 +111,11 @@ known_good_version_for() {
 # `# v4.38.0 (4.38.1 blocked estate-wide; nexia-list#100)` — and prose that
 # merely mentions a version mid-sentence is never rewritten.
 #
+# Takes the comment and a replacement version without `v`; writes the result
+# to stdout without a newline. A rewritten comment has one leading `#`;
+# a bare claim gains `# `, and existing spacing after `#` is preserved.
+# An empty version or the literal `null` returns the comment unchanged.
+#
 # This must stay byte-for-byte identical in spirit to PinIntegrity.relabel/2 in
 # lib/rules/pin_integrity.ex. Two readers, one policy, same edit.
 relabel_comment() {