docs(bazzite): fix the "rpm-ostree upgrade doesn't update punktfunk" trap

`rpm-ostree upgrade` re-resolves layered packages only when the BASE image
changes; on a frozen Bazzite base (pinned :stable tag / paused rebase) it
reports "No updates available" and never bumps the layered punktfunk even
when newer RPMs are live in the repo — observed on the .41 host stuck at
0.6.0 while 0.7.x sat in the registry.

- Add packaging/bazzite/update-punktfunk.sh: detects the layered punktfunk
  packages, refreshes rpmmd, and forces a re-resolve via
  `rpm-ostree update --uninstall <pkg> --install <pkg>` (the one-transaction
  idiom that actually pulls a new layered version on a static base).
- Document the trap + the fix in packaging/bazzite/README.md, including the
  channel gotcha: an enabled punktfunk-canary.repo (<next-minor>.0-0.ciN)
  outranks stable X.Y.Z-1, so the box silently tracks canary — enable one
  channel only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packaging/bazzite/README.md

@@ -62,6 +62,38 @@ systemctl reboot
 > The **reboot is mandatory** — `rpm-ostree install` stages a new deployment that only takes
 > effect on the next boot. This is normal atomic-distro behavior, not a punktfunk quirk.
 
+#### Updating a Path-A host — `rpm-ostree upgrade` is NOT enough
+
+> ⚠️ **`rpm-ostree upgrade` will not update punktfunk on its own.** `upgrade` bumps the **base
+> image** and only re-resolves *layered* packages **when the base changes**. A Bazzite base can
+> sit frozen for months (a pinned `:stable` tag, a paused rebase), so `rpm-ostree upgrade` keeps
+> reporting *"No updates available"* and your layered `punktfunk` stays put even after new RPMs
+> land in the repo. (Diagnose: `rpm-ostree status` shows the base `Version:` unchanged, while
+> `dnf -q repoquery --upgrades punktfunk` lists newer builds.)
+
+To actually pull a newer host on a static base, force rpm-ostree to re-resolve just the punktfunk
+layer — remove + re-add the same names in one transaction:
+
+```sh
+sudo rpm-ostree refresh-md --force
+sudo rpm-ostree update \
+  --uninstall punktfunk --uninstall punktfunk-web \
+  --install   punktfunk --install   punktfunk-web
+systemctl reboot
+```
+
+Or just run the helper, which detects what's layered and does the above:
+
+```sh
+sudo bash packaging/bazzite/update-punktfunk.sh          # stage; reboot when ready
+sudo bash packaging/bazzite/update-punktfunk.sh --reboot # stage + reboot now
+```
+
+> **Channel gotcha:** the re-resolve picks the highest version across **every enabled**
+> `/etc/yum.repos.d/punktfunk*.repo`. If `punktfunk-canary.repo` is enabled alongside the stable
+> `punktfunk.repo`, canary's `<next-minor>.0-0.ciN` **outranks** the stable `X.Y.Z-1` and the box
+> silently tracks canary. Enable exactly one channel — set `enabled=0` in the other repo file.
+
 ### Path B — bootc image (`FROM bazzite-nvidia`)
 
 The image is built **off-host** (on any machine with `podman`) from

packaging/bazzite/update-punktfunk.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Update the layered punktfunk packages on a Bazzite / Fedora-Atomic host.
+#
+# Why this exists: `rpm-ostree upgrade` upgrades the *base image* and only re-resolves
+# layered packages WHEN THE BASE CHANGES. Bazzite bases can sit frozen for months (a pinned
+# `:stable` tag, a paused rebase), so `rpm-ostree upgrade` keeps reporting "No updates
+# available" and your layered punktfunk never moves even though newer RPMs are in the repo.
+# The fix is to force rpm-ostree to re-resolve just the punktfunk layer against the latest
+# repo metadata — an `--uninstall … --install …` of the same package names in one
+# transaction. This script does that for whichever of punktfunk / punktfunk-web are layered.
+#
+# Usage:  sudo bash update-punktfunk.sh          # stage the newest; you reboot when ready
+#         sudo bash update-punktfunk.sh --reboot # stage, then reboot immediately
+#
+# Channel note: it re-resolves against every ENABLED punktfunk repo. If both
+# `punktfunk.repo` (stable) and `punktfunk-canary.repo` are enabled, canary's version sorts
+# higher and WINS — the box silently tracks canary. Enable exactly the channel you want
+# (set `enabled=0` in the other `/etc/yum.repos.d/punktfunk*.repo`).
+set -euo pipefail
+
+if [[ $EUID -ne 0 ]]; then
+  echo "run as root: sudo bash $0 ${*:-}" >&2
+  exit 1
+fi
+
+# Which punktfunk packages are actually layered right now (host, web, or both).
+mapfile -t layered < <(rpm-ostree status --json 2>/dev/null \
+  | grep -oE '"punktfunk(-web)?"' | tr -d '"' | sort -u)
+if [[ ${#layered[@]} -eq 0 ]]; then
+  # Fall back to the rpm db if the JSON shape ever changes.
+  mapfile -t layered < <(rpm -qa --qf '%{NAME}\n' 'punktfunk' 'punktfunk-web' 2>/dev/null | sort -u)
+fi
+if [[ ${#layered[@]} -eq 0 ]]; then
+  echo "no punktfunk packages are layered — install first (see packaging/bazzite/README.md)" >&2
+  exit 1
+fi
+echo "layered punktfunk packages: ${layered[*]}"
+
+# Fresh repo metadata, else the re-resolve can pick a stale 'newest'.
+rpm-ostree refresh-md --force >/dev/null
+
+# Force the re-resolve: remove + re-add the same names in ONE transaction so the box is never
+# left without the host, and rpm-ostree picks the newest available version.
+args=()
+for p in "${layered[@]}"; do args+=(--uninstall "$p"); done
+for p in "${layered[@]}"; do args+=(--install "$p"); done
+echo "+ rpm-ostree update ${args[*]}"
+rpm-ostree update "${args[@]}"
+
+echo
+echo "Staged. The new version activates on the next boot."
+if [[ "${1:-}" == "--reboot" ]]; then
+  echo "rebooting now…"
+  systemctl reboot
+else
+  echo "Reboot when ready:  systemctl reboot"
+fi