From 9cd3dedc5a73389057cf0af63a0c86b59d4d5548 Mon Sep 17 00:00:00 2001
From: Kristin Martin <kristin@fly.io>
Date: Tue, 6 Oct 2026 18:08:51 +0000
Subject: [PATCH 1/2] Restore --delete to the docs sync

Left out of #5287 because the first sync would have removed 12 pages that
docs.json nav and 15 redirects still pointed at. Those have landed:
superfly/docs#2530 retired the litefs-cloud pages and #2535 the duplicate
root page.

Verified before restoring: generating from master and comparing against
superfly/docs main gives identical page sets, 305 each, and zero changed
pages. So --delete removes nothing today, and from now on a command
removed from flyctl stops being documented.
---
 scripts/generate_docs.sh | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/scripts/generate_docs.sh b/scripts/generate_docs.sh
index d919dfbb16..62852d90b3 100755
--- a/scripts/generate_docs.sh
+++ b/scripts/generate_docs.sh
@@ -21,13 +21,13 @@ if [ "$1" ]
           awk -v lbl="$label" 'NR==2 && /^title:/ {print; print lbl; next} {print}' "$f" > "$f.tmp" && mv "$f.tmp" "$f"
         done
 
-        # --delete is deliberately absent. With it, the first sync after the
-        # MDX switch would also remove the 12 pages the generator no longer
-        # produces: the retired litefs-cloud commands and the duplicate root
-        # page. 12 docs.json nav entries and 15 redirects still point at those,
-        # so they are a reviewable docs change rather than something this bot
-        # should do unannounced. Restore --delete once that has landed, or
-        # removed commands will linger here forever.
+        # --delete so a command removed from flyctl stops being documented.
+        # Without it the pages linger: the litefs-cloud commands went in
+        # #5187 and their eleven pages stayed live for four weeks, telling
+        # readers a retired CLI worked.
+        #
+        # This deletes anything in the destination the generator did not
+        # produce, so nothing hand-written belongs in flyctl/cmd.
         echo "rsync to $1"
-        rsync out/ $1 -r -v
+        rsync out/ $1 --delete -r -v
 fi

From 81e51cb093f0540b94fc48b347ad97becb402973 Mon Sep 17 00:00:00 2001
From: Kristin Martin <kristin@fly.io>
Date: Tue, 6 Oct 2026 18:19:51 +0000
Subject: [PATCH 2/2] Refuse to sync when the generator produced almost nothing

Neither script uses set -e and out/ is cleared before generating, so a
failed generator leaves out/ empty and the rsync, now with --delete, would
remove every page. The review requirement would catch the resulting PR,
but the script should not rely on that.

A floor rather than set -e: set -e would abort the label-preservation loop,
where [ -n "$label" ] && awk ... returns non-zero for the 270 pages that
carry no sidebarTitle.
---
 scripts/generate_docs.sh | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/scripts/generate_docs.sh b/scripts/generate_docs.sh
index 62852d90b3..fe57750de8 100755
--- a/scripts/generate_docs.sh
+++ b/scripts/generate_docs.sh
@@ -6,6 +6,17 @@ rm -f out/*.mdx
 echo "Running doc/main.go"
 go run doc/main.go
 
+# Neither this script nor publish_docs.sh uses set -e, and out/ is cleared
+# before the generator runs. So a generator that fails leaves out/ empty and
+# the rsync below, with --delete, would propagate that and remove every page.
+# Refuse instead. 305 pages today, so 100 is a floor that only a broken run
+# can cross.
+COUNT=$(ls out/*.mdx 2>/dev/null | wc -l)
+if [ "$COUNT" -lt 100 ]; then
+  echo "generator produced $COUNT pages, refusing to sync" >&2
+  exit 1
+fi
+
 if [ "$1" ]
     then
         # Carry sidebarTitle across. On about three dozen pages it is a