docs(troubleshooting): radio sources not activating after in-place migration (refs #521)

After an in-place migration the firmware sometimes does not activate the
radio source types (LOCAL_INTERNET_RADIO, TUNEIN, RADIO_BROWSER) even
though the entries are present in the device's own Sources.xml; a reboot
and a sourcesUpdated notification do not help. The root cause is not yet
understood, so this documents the user-confirmed workaround (factory
reset + re-migrate) rather than changing migration behaviour:

- New troubleshooting section with a stable anchor, linked from the
  sources_xml_diff health check and the Radio Browser reference.
- Capture the speaker's on-device /mnt/nv/BoseApp-Persistence/1/Sources.xml
  in the diagnostic export (when SSH is available), so a future report
  taken before a factory reset carries the evidence to pin down the cause.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/content/docs/guides/TROUBLESHOOTING.md

@@ -465,6 +465,30 @@ Once the source plays once, it gets persisted to `/mnt/nv/BoseApp-Persistence/1/
 
 If `soundtouch-cli source content --source TUNEIN ...` returns `1005` on a reset device that has never had TuneIn, the speaker is refusing because the source isn't registered yet — chicken-and-egg. The SoundTouch app is then the only practical path to register it; we can't write `Sources.xml` directly over telnet on most models.
 
+### ❌ Radio sources never activate after an in-place migration {#radio-sources-after-migration}
+
+**Symptoms:**
+
+- The speaker was migrated **in place** (not factory-reset first) and is reachable; account-bound sources (for example a music-streaming login) work and presets for them play.
+- **Every** radio-type source fails: selecting any `LOCAL_INTERNET_RADIO`, `TUNEIN`, or `RADIO_BROWSER` content returns `1005`, including the Health tab's "Play ding" test.
+- `curl http://<speaker-ip>:8090/sources` lists no radio source types at all.
+- The Health check warns that the speaker is "missing N source type(s) the service advertises".
+- The entries are present on disk in **both** the service-side `Sources.xml` **and** the speaker's own `/mnt/nv/BoseApp-Persistence/1/Sources.xml`, yet a reboot and a `sourcesUpdated` notification do not make them activate.
+
+**Cause:**
+
+Not fully understood. After an in-place migration the firmware does not activate the radio source **types** in its runtime, even though the entries exist in the speaker's persisted `Sources.xml`. This is firmware behaviour and we have not confirmed the exact trigger. (If you hit this, an [encrypted diagnostic report](#getting-more-help) taken **before** you reset the speaker is very helpful — it now includes the speaker's on-device `Sources.xml`.)
+
+**Workaround (confirmed by users):**
+
+Factory reset the speaker, then re-migrate it:
+
+1. Factory reset (on most models: hold `1` + `−` for ~10 seconds).
+2. Reconnect the speaker to your network.
+3. Re-migrate it in AfterTouch.
+
+After this the radio sources activate normally. Note the factory reset rewrites the speaker's `Sources.xml` to defaults, so any **account-bound** source (for example a music-streaming login) has to be re-added afterwards; your presets for it come back once the source is present again.
+
 ## 🔊 **Volume & Audio Issues**
 
 ### ❌ "Volume control not working"

docs/content/docs/reference/radio-browser.md

@@ -43,6 +43,8 @@ curl -v -X POST http://<speaker-ip>:8090/notification \
 
 Replace `<speaker-ip>` with your speaker's IP address and `<deviceID>` with its device ID (visible in `/info`). After this call the speaker re-fetches its sources from the service. Step 2 (source-type registration) still requires a reboot.
 
+> **If a reboot doesn't help after an in-place migration:** on some speakers the radio source types (`LOCAL_INTERNET_RADIO`, `TUNEIN`, `RADIO_BROWSER`) never activate after an in-place migration, even though the entries are present in the device-local `Sources.xml` and you have rebooted and sent `sourcesUpdated`. The cause isn't fully understood; the confirmed remedy is a factory reset + re-migrate. See [Troubleshooting: Radio sources never activate after an in-place migration](../../guides/TROUBLESHOOTING/#radio-sources-after-migration).
+
 ### Search for stations
 
 - Go to https://www.radio-browser.info and find a station you like.

pkg/service/handlers/handlers_export.go

@@ -22,6 +22,7 @@ import (
 	"github.com/gesellix/bose-soundtouch/pkg/service/export"
 	"github.com/gesellix/bose-soundtouch/pkg/service/health"
 	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
+	"github.com/gesellix/bose-soundtouch/pkg/speaker"
 	speakerssh "github.com/gesellix/bose-soundtouch/pkg/ssh"
 	"github.com/gesellix/bose-soundtouch/pkg/telnet"
 )
@@ -312,6 +313,11 @@ var speakerSSHPaths = []string{
 	"/etc/pki/tls/certs/ca-bundle.crt",
 	"/etc/pki/tls/certs/ca-bundle.crt.original", // pre-migration CA bundle backup
 	"/etc/ssl/certs/ca-certificates.crt",
+	// The speaker's own persisted source list. The firmware registers source
+	// types from this file at boot; comparing it against the service's
+	// Sources.xml (and the runtime /sources) is the key evidence when radio
+	// source types won't activate after an in-place migration.
+	speaker.SourcesFileLocation,
 	// Redirection-relevant state: where the speaker resolves Bose hostnames
 	// and what it had before migration. (The live marge/BMX URL config in
 	// SoundTouchSdkPrivateCfg.xml is handled by collectSpeakerRedirectConfig,

pkg/service/health/checks_sources_diff.go

@@ -155,7 +155,7 @@ func diffSourcesForDeviceWithURL(ds *datastore.DataStore, account, deviceID, ipA
 				"Speaker is missing %d source type(s) the service advertises: %s.",
 				len(missingOnSpeaker), strings.Join(missingOnSpeaker, ", "),
 			),
-			Details: "After a power-cycle the speaker fetches /full from the service and re-registers its source list. Forcing a sourcesUpdated notification triggers the same refresh without rebooting.",
+			Details: "After a power-cycle the speaker fetches /full from the service and re-registers its source list. Forcing a sourcesUpdated notification triggers the same refresh without rebooting. If radio source types still won't activate after an in-place migration (a reboot and this notification don't help), see the troubleshooting guide; the confirmed remedy is a factory reset + re-migrate: https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/#radio-sources-after-migration",
 			ManualCommands: []ManualCommand{{
 				Label:   "Trigger a sources refresh on the speaker:",
 				Command: notifyCmd,