diff --git a/agents/skills/icon-font.md b/agents/skills/icon-font.md
index 333f8752..15585006 100644
--- a/agents/skills/icon-font.md
+++ b/agents/skills/icon-font.md
@@ -70,10 +70,6 @@ magick -background white -fill black -font default/fonts/omarchy/omarchy.ttf \
   -pointsize 110 label:@/tmp/row.txt /tmp/font-row.png
 ```
 
-Then confirm it in the running menu per
-[`visual-verification.md`](visual-verification.md). Fontconfig prefers the
-packaged font over a copy in `~/.local/share/fonts` for the same family, so a
-preview needs either the real file replaced or a `<rejectfont>` rule in
-`~/.config/fontconfig/conf.d/` pointing fontconfig away from the packaged one.
-Restart the shell afterwards — Qt reads the font database at startup, so
-`omarchy menu refresh` alone will not pick up a changed font.
+Then confirm it in the running menu per [`visual-verification.md`](visual-verification.md). Avoid leaving two fonts with the `omarchy` family registered: Qt can use an old copy in `~/.local/share/fonts` even when `fc-match omarchy` reports the packaged font. For a preview, either replace the packaged file in the disposable VM or temporarily exclude it with a `<rejectfont>` rule in `~/.config/fontconfig/conf.d/` before loading the candidate.
+
+Refresh the font cache and restart the shell afterwards — Qt reads the font database at startup, so `omarchy menu refresh` alone will not pick up a changed font. Remove temporary fonts and rules after verification.
diff --git a/bin/omarchy-upgrade-to-quattro b/bin/omarchy-upgrade-to-quattro
index 21691914..e6a27ee6 100755
--- a/bin/omarchy-upgrade-to-quattro
+++ b/bin/omarchy-upgrade-to-quattro
@@ -1569,7 +1569,6 @@ refresh	xournalpp/settings.xml	1c1a9efbf1b6dc7813bf3440fd5bf8409fc283e8d0192ca29
 # fastfetch/config.jsonc -> /etc/fastfetch/config.jsonc
 # fontconfig/fonts.conf -> /usr/share/fontconfig/conf.avail/50-omarchy.conf
 # mimeapps.list -> /usr/share/applications/mimeapps.list
-# omarchy.ttf -> /usr/share/fonts/omarchy/omarchy.ttf
 # systemd/user/bt-agent.service -> /usr/lib/systemd/user/bt-agent.service
 # systemd/user/omarchy-recover-internal-monitor.service -> /usr/lib/systemd/user/omarchy-recover-internal-monitor.service
 # systemd/user/omarchy-sleep-lock.service -> /usr/lib/systemd/user/omarchy-sleep-lock.service
@@ -1602,7 +1601,6 @@ retire	fontconfig/fonts.conf	6dec98b539388b95ecfdb3c7ab951001c712820eb0581002832
 retire	fontconfig/fonts.conf	3545f6c5a8c1465df7a4e251b3c2047d4ba03654c86636794f64cb0d8ea8ef63
 retire	fontconfig/fonts.conf	0f085b449f1cbe8eda3b59a6235bf2a3ddb6e982ab5d22fa642248916e63bafc
 retire	mimeapps.list	3b574cef135b5deb7a8a0c7e17139037cf1fe155300e3809f60bed0e04120975
-retire	omarchy.ttf	e55e67119e82f56f92d90cbf54b7ccc1b2946b32c535a29370439d7ef5215966
 retire	systemd/user/bt-agent.service	0406b577a1225dc2a9f86638d3c346eb3635168576f04050be50ebcc0be6be12
 retire	systemd/user/omarchy-recover-internal-monitor.service	b9b92cedc44cf3cb6216948629be55b53d16746e31896dc6469fd49ba55e82f4
 retire	systemd/user/omarchy-recover-internal-monitor.service	e1483079b9f2aefcd43b4722c75a31643e5f3bb5a2eada5f52f1d7d201e8c289
@@ -2381,6 +2379,8 @@ cleanup_retired_services
 ensure_sleep_lock_service
 remove_retired_default_packages
 run_final_system_package_upgrade
+# This also retires the stock ~/.local/share/fonts/omarchy.ttf missed by the
+# former ~/.config retirement entry, through migration 1788848726.
 run_post_upgrade_migrations
 run_post_upgrade_update_steps
 refresh_current_theme_after_upgrade
diff --git a/migrations/1788848726.sh b/migrations/1788848726.sh
new file mode 100644
index 00000000..ab33ffcc
--- /dev/null
+++ b/migrations/1788848726.sh
@@ -0,0 +1,21 @@
+echo "Retire the stock user icon font missed by the Quattro upgrade"
+
+legacy_font="$HOME/.local/share/fonts/omarchy.ttf"
+
+# The upgrader treated this as ~/.config/omarchy.ttf and left the old family
+# registered alongside the packaged font. Preserve custom fonts and symlinks.
+if [[ -f $legacy_font && ! -L $legacy_font ]]; then
+  legacy_hash=$(sha256sum "$legacy_font")
+  if [[ ${legacy_hash%% *} == "e55e67119e82f56f92d90cbf54b7ccc1b2946b32c535a29370439d7ef5215966" ]]; then
+    if [[ ! -f /usr/share/fonts/omarchy/omarchy.ttf ]]; then
+      echo "Packaged Omarchy icon font is missing; keeping the legacy font." >&2
+      exit 1
+    fi
+
+    rm "$legacy_font"
+  fi
+fi
+
+# Also refresh on retries after removal succeeded but the cache refresh failed.
+# The normal update restarts the shell, which reloads Qt's font database.
+fc-cache -f
diff --git a/test/shell.d/fixtures/legacy-icon-font/README.md b/test/shell.d/fixtures/legacy-icon-font/README.md
new file mode 100644
index 00000000..c773098d
--- /dev/null
+++ b/test/shell.d/fixtures/legacy-icon-font/README.md
@@ -0,0 +1,3 @@
+Stock Omarchy icon font from `config/omarchy.ttf` at `babfafa5^`, before fonts moved into the settings package. SHA-256: `e55e67119e82f56f92d90cbf54b7ccc1b2946b32c535a29370439d7ef5215966`.
+
+The migration test uses the real font so it exercises the exact-content guard without mocking `sha256sum`.
diff --git a/test/shell.d/fixtures/legacy-icon-font/omarchy.ttf b/test/shell.d/fixtures/legacy-icon-font/omarchy.ttf
new file mode 100644
index 00000000..273256d0
Binary files /dev/null and b/test/shell.d/fixtures/legacy-icon-font/omarchy.ttf differ
diff --git a/test/shell.d/legacy-icon-font-migration-test.sh b/test/shell.d/legacy-icon-font-migration-test.sh
new file mode 100644
index 00000000..c042f76c
--- /dev/null
+++ b/test/shell.d/legacy-icon-font-migration-test.sh
@@ -0,0 +1,106 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(dirname "$0")/base-test.sh"
+
+migration="$ROOT/migrations/1788848726.sh"
+fixture="$ROOT/test/shell.d/fixtures/legacy-icon-font/omarchy.ttf"
+test_dir=$(mktemp -d)
+trap 'rm -rf "$test_dir"' EXIT
+
+export FONT_TEST_HOME="$test_dir/home with spaces"
+export FONT_TEST_PACKAGE="$test_dir/packaged-font.ttf"
+export FONT_TEST_CACHE_LOG="$test_dir/cache.log"
+legacy_font="$FONT_TEST_HOME/.local/share/fonts/omarchy.ttf"
+
+# Redirect only the filesystem roots; run the real hash check and removal.
+# Never change the developer's HOME or refresh their real font cache.
+python3 - "$migration" "$test_dir/migration.sh" <<'PY'
+import pathlib
+import sys
+
+source = pathlib.Path(sys.argv[1]).read_text()
+source = source.replace('$HOME', '$FONT_TEST_HOME')
+source = source.replace('/usr/share/fonts/omarchy/omarchy.ttf', '$FONT_TEST_PACKAGE')
+pathlib.Path(sys.argv[2]).write_text(source)
+PY
+
+mkdir -p "$test_dir/bin"
+cat > "$test_dir/bin/fc-cache" <<'SH'
+#!/bin/bash
+printf '%s\n' "$*" >> "$FONT_TEST_CACHE_LOG"
+exit "${FONT_TEST_CACHE_STATUS:-0}"
+SH
+chmod +x "$test_dir/bin/fc-cache"
+
+reset_fonts() {
+  rm -rf "$FONT_TEST_HOME"
+  mkdir -p "$FONT_TEST_HOME/.local/share/fonts" "$FONT_TEST_HOME/.config"
+  cp "$ROOT/default/fonts/omarchy/omarchy.ttf" "$FONT_TEST_PACKAGE"
+  : > "$FONT_TEST_CACHE_LOG"
+}
+
+run_migration() {
+  PATH="$test_dir/bin:$PATH" bash -euo pipefail "$test_dir/migration.sh" > "$test_dir/output" 2>&1
+}
+
+reset_fonts
+cp "$fixture" "$legacy_font"
+cp "$fixture" "$FONT_TEST_HOME/.config/omarchy.ttf"
+run_migration
+[[ ! -e $legacy_font ]] || fail "stock font is removed from the actual user font directory"
+cmp "$fixture" "$FONT_TEST_HOME/.config/omarchy.ttf" || fail "unrelated config path is untouched"
+cmp "$ROOT/default/fonts/omarchy/omarchy.ttf" "$FONT_TEST_PACKAGE" || fail "packaged font is untouched"
+[[ $(cat "$FONT_TEST_CACHE_LOG") == "-f" ]] || fail "font cache is refreshed after retirement"
+pass "retire the known stock font at its real path and refresh the cache"
+
+run_migration
+[[ ! -e $legacy_font ]] || fail "a second run leaves the stock font retired"
+pass "font retirement is idempotent"
+
+reset_fonts
+cp "$fixture" "$legacy_font"
+printf 'custom modification\n' >> "$legacy_font"
+cp "$legacy_font" "$test_dir/custom-font.ttf"
+run_migration
+cmp "$test_dir/custom-font.ttf" "$legacy_font" || fail "custom font is preserved"
+pass "preserve a modified font with the legacy filename"
+
+reset_fonts
+cp "$fixture" "$test_dir/symlink-target.ttf"
+ln -s "$test_dir/symlink-target.ttf" "$legacy_font"
+run_migration
+[[ -L $legacy_font ]] || fail "user font symlink is preserved"
+cmp "$fixture" "$test_dir/symlink-target.ttf" || fail "symlink target is untouched"
+pass "preserve user font symlinks even when they point to the stock font"
+
+reset_fonts
+run_migration
+[[ ! -e $legacy_font ]] || fail "an absent user font is left absent"
+pass "handle installs without a legacy user font"
+
+reset_fonts
+cp "$fixture" "$legacy_font"
+rm "$FONT_TEST_PACKAGE"
+if run_migration; then
+  fail "missing packaged font keeps the repair pending"
+fi
+cmp "$fixture" "$legacy_font" || fail "keep the stock font until its replacement is present"
+[[ ! -s $FONT_TEST_CACHE_LOG ]] || fail "missing replacement stops before cache refresh"
+pass "preserve the stock font and fail when the packaged replacement is missing"
+
+reset_fonts
+cp "$fixture" "$legacy_font"
+if FONT_TEST_CACHE_STATUS=17 run_migration; then
+  fail "font cache failure keeps the repair pending"
+fi
+[[ ! -e $legacy_font ]] || fail "cache failure follows successful retirement"
+run_migration
+(( $(wc -l < "$FONT_TEST_CACHE_LOG") == 2 )) || fail "retry refreshes the cache after the file was removed"
+pass "retry a failed cache refresh after successful font retirement"
+
+if grep -q $'^retire\tomarchy.ttf\t' "$ROOT/bin/omarchy-upgrade-to-quattro"; then
+  fail "upgrader no longer treats the user font as a config file"
+fi
+pass "upgrader leaves font retirement to its post-upgrade migrations"