diff --git a/ui/IconButton.gd b/ui/IconButton.gd
index c6af89c..85abcba 100644
--- a/ui/IconButton.gd
+++ b/ui/IconButton.gd
@@ -8,21 +8,21 @@ extends Control
 
 signal pressed
 
-# Scenes store `icon` as a plain int, so NEW ENTRIES MUST BE APPENDED -
-# inserting one would silently repoint every button after it.
+# Scenes store `icon` as a plain int, so NEW ENTRIES MUST BE APPENDED.
+# Inserting one anywhere but the end silently repoints every button after
+# it, in every scene file that already names an icon by number. The entries
+# below are therefore in the order they were added, not in any sensible one.
 enum Icon {
 	MAP, CLOSE, SHIP, DOWN_ARROW, UP_ARROW, BUILD, ROTATE_CW, ROTATE_CCW,
 	# One per building, each a miniature of what actually gets placed. The
 	# build menu used to pick from the generic set, which left the mothership
-	# and the command centre sharing a folded-map glyph and neither of them
-	# looking anything like the structure they build.
+	# and the command centre sharing a folded-map glyph.
 	MOTHERSHIP, CRAFTER, COMMAND_CENTER, EXTRACTOR, TRANSPORT_HUB, SHIP_LAB,
-	# Moving ore between the fleet and a building (#24). Two arrows passing
-	# each other: the single up/down arrows already mean "load" and "store"
-	# one way each, and this button is the place where both live.
+	# Two arrows passing each other. The single up/down arrows already mean
+	# "load" and "store" one way each, and this is where both live.
 	TRANSFER,
-	# Ship-lab upgrade glyphs. These deliberately describe the effect rather
-	# than the building hosting it, so cards remain scannable at a glance.
+	# Ship-lab upgrades, drawn as the EFFECT rather than the building that
+	# sells it, so a card full of them stays scannable.
 	UPGRADE_DAMAGE, UPGRADE_RATE, UPGRADE_RANGE, UPGRADE_THRUSTERS,
 	UPGRADE_SHIELD_HITS, UPGRADE_SHIELD_RECHARGE, UPGRADE_CARGO,
 	UPGRADE_ENGINES, UPGRADE_UNLOCK_SHIELD,
@@ -31,44 +31,30 @@ enum Icon {
 	LEFT_ARROW, RIGHT_ARROW,
 	MINUS, PLUS,
 	SHIELD_VESSEL,
+	# The ship and the thing it drops - the same two-icon split as
+	# LASER_VESSEL/LASER_SHOT below.
 	GAS_BOMBER, GAS_BOMB,
-	# Appended, not inserted alongside the other building icons above -
-	# inserting there would silently renumber every icon int already
-	# stored in existing scenes (#54).
 	GAS_BURNER,
-	# Same append-only rule (#57): a wide hauler hull, distinct from every
-	# vessel glyph above.
+	# A wide hauler hull, distinct from every vessel glyph above.
 	CARRIER_VESSEL,
-	# #58: LASER_VESSEL is the ship glyph, LASER_SHOT the action button -
-	# same two-icon split as GAS_BOMBER/GAS_BOMB above.
 	LASER_VESSEL, LASER_SHOT,
-	# #59 drew this as a warped ring, for a vessel then called a space-time
-	# distorder. #77 renamed it the Energy Propulser and the glyph is now an
-	# engine bell; the enum name stays put because renumbering it would
-	# silently renumber every icon int stored in every scene.
+	# Drawn as an engine bell, not the warped ring the name suggests: this
+	# was a "space-time distorder" before it became the Energy Propulser.
+	# The name cannot follow the art without renumbering everything after it.
 	DISTORDER_VESSEL,
-	# #78: switching a converter off and on. Appended, like everything above -
-	# inserting anywhere earlier renumbers every icon int already stored in a
-	# scene file.
+	# Switching a converter off and on.
 	PAUSE, RESUME,
-	# #102: appended, like everything above - inserting anywhere earlier
-	# renumbers every icon int already stored in every scene.
 	OUTPOST,
-	# #106: appended, same rule.
 	PLANNING_CENTER,
-	# #116: the workshop and the drone it sends out. Appended, same rule.
+	# The workshop and the drone it sends out.
 	WORKSHOP, REPAIR_DRONE,
-	# #140: the standing objective. Appended, same rule as everything above -
-	# inserting anywhere earlier renumbers every icon int already stored in
-	# every scene.
+	# The standing objective.
 	QUEST,
-	# #179: a fleet-wide thrust burst, distinct from the Propulser vessel icon.
+	# A fleet-wide thrust burst, distinct from the Propulser vessel icon.
 	DASH,
-	# Development tools: three sliders, used only by the editor-only sandbox
-	# button. Appended to preserve every serialized icon number above.
+	# Three sliders. Used only by the editor-only sandbox button.
 	DEV_TOOLS,
-	# #193: a directional sensor dish. Appended: scene files store these as
-	# integers, so insertion would change every icon after it.
+	# A directional sensor dish.
 	SCANNER,
 }