ci: pin GitHub Actions to commit SHAs

Replace floating major-tag references (uses: foo/bar@vN) with the
specific commit SHAs they currently resolve to, annotated with the
fully-versioned tag (# vX.Y.Z) for human readability. Pinning to a SHA
makes the action behaviour reproducible across runs and removes the
supply-chain risk of a maintainer (or attacker) moving a tag to a new
commit.

One documented exception: semgrep/semgrep-action does not publish
v1.x.y semver tags — v1 is their only canonical release name on that
line — so it keeps a "# v1" annotation with an inline explanation.

actions/dependency-review-action's previous "@v5" reference would have
failed at run time: that repo only ships fully-versioned tags
(v5.0.0), no moving v5 alias. Pinned to v5.0.0 explicitly.

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

.docsignore

@@ -0,0 +1,5 @@
+# Files intentionally not linked in docs/SUMMARY.md.
+# Paths are relative to the docs/ directory.
+# Lines starting with # and blank lines are ignored.
+
+#analysis/bose-soundtouch-community-tools.md

.env.example

@@ -3,6 +3,7 @@
 
 # Docker/Service Settings
 SOUNDTOUCH_HOSTNAME=soundtouch.local
+SOUNDTOUCH_VERSION=latest
 
 # Discovery Settings
 DISCOVERY_TIMEOUT=5s

.github/markdown-link-check.json

@@ -37,6 +37,12 @@
     },
     {
       "pattern": "https://apkpure.com/bose-soundtouch/com.bose.soundtouch"
+    },
+    {
+      "pattern": "^https://bose\\.fandom\\.com/"
+    },
+    {
+      "pattern": "^https://www\\.reddit\\.com/"
     }
   ],
   "replacementPatterns": [

.github/workflows/ci.yml

@@ -17,15 +17,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
       - name: Cache Go modules
-        uses: actions/cache@v5
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: |
             ~/.cache/go-build
@@ -53,7 +53,7 @@ jobs:
         run: make test-http-client
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
         with:
           file: ./coverage.out
           flags: unittests
@@ -66,10 +66,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
@@ -77,7 +77,7 @@ jobs:
         run: sudo apt-get install -y libpcap-dev
 
       - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@v9
+        uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
         with:
           version: latest
           args: --timeout=5m
@@ -86,39 +86,76 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        goos: [linux, darwin, windows]
-        goarch: [amd64, arm64]
-        exclude:
-          # Windows ARM64 builds are experimental
-          - goos: windows
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
             goarch: arm64
+          - goos: linux
+            goarch: arm
+            goarm: 7
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+          - goos: windows
+            goarch: amd64
+          - goos: freebsd
+            goarch: amd64
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
-      - name: Build CLI
+      - name: Cache Go modules
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.mod') }}-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Build binaries
         env:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
+          GOARM: ${{ matrix.goarm }}
+          CGO_ENABLED: 0
         run: |
-          output_name="soundtouch-cli-${{ matrix.goos }}-${{ matrix.goarch }}"
-          if [ "${{ matrix.goos }}" = "windows" ]; then
-            output_name="${output_name}.exe"
+          ARCH_SUFFIX="${{ matrix.goos }}-${{ matrix.goarch }}"
+          if [[ -n "${{ matrix.goarm }}" ]]; then
+            ARCH_SUFFIX="${ARCH_SUFFIX}v${{ matrix.goarm }}"
           fi
-          go build -o "$output_name" ./cmd/soundtouch-cli
+
+          EXT=""
+          if [[ "${{ matrix.goos }}" == "windows" ]]; then
+            EXT=".exe"
+          fi
+
+          mkdir -p build
+
+          for binary in soundtouch-cli soundtouch-service soundtouch-web soundtouch-backup; do
+            OUTPUT="build/${binary}-${ARCH_SUFFIX}${EXT}"
+            echo "Building $OUTPUT"
+            go build -trimpath -ldflags="-s -w" -o "$OUTPUT" "./cmd/$binary"
+          done
+
+          ls -la build/
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: soundtouch-cli-${{ matrix.goos }}-${{ matrix.goarch }}
-          path: soundtouch-cli-*
+          name: binaries-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goarm }}
+          path: build/
 
   security:
     name: Basic Security Check
@@ -126,10 +163,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
@@ -153,7 +190,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check documentation links
         run: |
@@ -211,16 +248,16 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
       - name: Test CLI build and help
         run: |
-          go build -o soundtouch-cli ./cmd/soundtouch-cli
+          go build -trimpath -ldflags="-s -w" -o soundtouch-cli ./cmd/soundtouch-cli
           ./soundtouch-cli -help
 
       - name: Test library imports
@@ -266,39 +303,116 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      - name: Determine push eligibility
+        id: push-check
+        run: |
+          # Push on main, and on same-repo PRs (forks can't push to GHCR via GITHUB_TOKEN).
+          SHOULD_PUSH="false"
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+            SHOULD_PUSH="true"
+          elif [[ "${{ github.event_name }}" == "pull_request" && \
+                  "${{ github.event.pull_request.head.repo.full_name }}" == "${{ github.repository }}" ]]; then
+            SHOULD_PUSH="true"
+          fi
+          echo "should-push=$SHOULD_PUSH" >> "$GITHUB_OUTPUT"
+          echo "Will push: $SHOULD_PUSH"
 
       - name: Log in to GitHub Container Registry
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v4
+        if: steps.push-check.outputs.should-push == 'true'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v6
+      - name: Extract metadata (tags, labels) for soundtouch-service
+        id: meta-service
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
             type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
-            type=ref,event=pr
+            type=ref,event=pr,prefix=preview-pr-
+            type=sha,prefix=preview-sha-,format=short,enable=${{ github.event_name == 'pull_request' }}
+            type=ref,event=branch,prefix=preview-branch-,enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
 
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v7
+      - name: Build and push soundtouch-service Docker image
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
+          target: soundtouch-service
           platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          push: ${{ steps.push-check.outputs.should-push == 'true' }}
+          tags: ${{ steps.meta-service.outputs.tags }}
+          labels: ${{ steps.meta-service.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
+      - name: Extract metadata (tags, labels) for soundtouch-web
+        id: meta-web
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: ghcr.io/${{ github.repository }}-web
+          tags: |
+            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
+            type=ref,event=pr,prefix=preview-pr-
+            type=sha,prefix=preview-sha-,format=short,enable=${{ github.event_name == 'pull_request' }}
+            type=ref,event=branch,prefix=preview-branch-,enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
+
+      - name: Build and push soundtouch-web Docker image
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          target: soundtouch-web
+          platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
+          push: ${{ steps.push-check.outputs.should-push == 'true' }}
+          tags: ${{ steps.meta-web.outputs.tags }}
+          labels: ${{ steps.meta-web.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Summarize published images
+        if: steps.push-check.outputs.should-push == 'true'
+        env:
+          SERVICE_TAGS: ${{ steps.meta-service.outputs.tags }}
+          WEB_TAGS: ${{ steps.meta-web.outputs.tags }}
+          EVENT_NAME: ${{ github.event_name }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          {
+            echo "## 🐳 Published Docker Images"
+            echo ""
+            if [[ "$EVENT_NAME" == "pull_request" ]]; then
+              echo "**Preview** images for PR #${PR_NUMBER}. These are not release builds."
+            elif [[ "$REF_NAME" == "main" ]]; then
+              echo "**Edge** images from \`main\`."
+            else
+              echo "**Preview** images from branch \`${REF_NAME}\`. These are not release builds."
+            fi
+            echo ""
+            echo "### soundtouch-service"
+            echo ""
+            echo '```bash'
+            while IFS= read -r tag; do
+              [[ -n "$tag" ]] && echo "docker pull $tag"
+            done <<< "$SERVICE_TAGS"
+            echo '```'
+            echo ""
+            echo "### soundtouch-web"
+            echo ""
+            echo '```bash'
+            while IFS= read -r tag; do
+              [[ -n "$tag" ]] && echo "docker pull $tag"
+            done <<< "$WEB_TAGS"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
   notify:
     name: Notify Status
     runs-on: ubuntu-latest
@@ -333,7 +447,7 @@ jobs:
 
       - name: Update commit status
         if: always()
-        uses: actions/github-script@v9
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             try {

.github/workflows/docs.yml

@@ -20,18 +20,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Setup Pages
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
       - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
+        uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
         with:
           source: 'docs/'
           destination: '_site'
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: '_site'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
@@ -64,7 +64,7 @@ jobs:
           fi
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: ${{ env.GO_VERSION_FILE }}
 
@@ -102,15 +102,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: ${{ env.GO_VERSION_FILE }}
 
       - name: Cache Go modules
-        uses: actions/cache@v5
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: |
             ~/.cache/go-build
@@ -151,6 +151,7 @@ jobs:
             rm -f "$OUTPUT_NAME" "$OUTPUT_NAME.sha256" "$OUTPUT_NAME.sha512"
 
             if ! go build \
+              -trimpath \
               -ldflags="-s -w" \
               -o "$OUTPUT_NAME" \
               "$CMD_PATH"; then
@@ -171,6 +172,9 @@ jobs:
 
           # Build Web
           build_binary "soundtouch-web" "./cmd/soundtouch-web"
+
+          # Build Backup
+          build_binary "soundtouch-backup" "./cmd/soundtouch-backup"
         id: build
 
       - name: Generate individual checksums
@@ -178,6 +182,7 @@ jobs:
           CLI_NAME="${{ steps.build.outputs.soundtouch-cli }}"
           SVC_NAME="${{ steps.build.outputs.soundtouch-service }}"
           WEB_NAME="${{ steps.build.outputs.soundtouch-web }}"
+          BCK_NAME="${{ steps.build.outputs.soundtouch-backup }}"
 
           # Use atomic operations to avoid conflicts
           TEMP_DIR=$(mktemp -d)
@@ -194,19 +199,21 @@ jobs:
           generate_checksums "$CLI_NAME"
           generate_checksums "$SVC_NAME"
           generate_checksums "$WEB_NAME"
+          generate_checksums "$BCK_NAME"
 
           # Cleanup
           rm -rf "$TEMP_DIR"
           echo "✅ Checksums generated successfully"
 
       - name: Upload build artifact
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: binaries-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goarm }}
           path: |
             build/soundtouch-cli-v*
             build/soundtouch-service-v*
             build/soundtouch-web-v*
+            build/soundtouch-backup-v*
           retention-days: 1
 
   checksums:
@@ -216,7 +223,7 @@ jobs:
 
     steps:
       - name: Download binary artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: binaries-*
           path: ./binaries
@@ -233,7 +240,7 @@ jobs:
           mkdir -p release-files
 
           # Move all files from subdirectories to the collection directory
-          find . -mindepth 2 -type f \( -name "soundtouch-cli-*" -o -name "soundtouch-service-*" -o -name "soundtouch-web-*" \) -exec mv {} release-files/ \;
+          find . -mindepth 2 -type f \( -name "soundtouch-cli-*" -o -name "soundtouch-service-*" -o -name "soundtouch-web-*" -o -name "soundtouch-backup-*" \) -exec mv {} release-files/ \;
 
           # Remove empty directories
           find . -type d -empty -delete
@@ -248,14 +255,14 @@ jobs:
           # Generate combined checksums (exclude individual .sha256/.sha512 files)
           if ls soundtouch-* 1> /dev/null 2>&1; then
             # Only checksum the actual binaries, not the .sha256/.sha512 files
-            ls soundtouch-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha256sum > checksums.sha256
-            ls soundtouch-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha512sum > checksums.sha512
+            ls soundtouch-cli-* soundtouch-service-* soundtouch-web-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha256sum > checksums.sha256
+            ls soundtouch-cli-* soundtouch-service-* soundtouch-web-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha512sum > checksums.sha512
 
             echo "📋 Generated combined checksums:"
             cat checksums.sha256
 
             # Verify all expected files are present (binaries only, not checksum files)
-            EXPECTED_COUNT=21  # 7 platforms * 3 binaries
+            EXPECTED_COUNT=28  # 7 platforms * 4 binaries
             ACTUAL_COUNT=$(ls soundtouch-* | grep -v '\.sha256$' | grep -v '\.sha512$' | wc -l)
 
             if [[ $ACTUAL_COUNT -ne $EXPECTED_COUNT ]]; then
@@ -273,7 +280,7 @@ jobs:
           fi
 
       - name: Upload checksums
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: checksums
           path: |
@@ -284,7 +291,7 @@ jobs:
           retention-days: 1
 
       - name: Upload all release assets
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: release-assets
           path: binaries/release-files/
@@ -298,12 +305,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
       - name: Download release assets
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: release-assets
           path: ./release-assets
@@ -392,6 +399,12 @@ jobs:
           ./soundtouch-web
           \`\`\`
 
+          ### SoundTouch Backup
+          \`\`\`bash
+          # Back up cloud account and all paired speakers in one go
+          ./soundtouch-backup all
+          \`\`\`
+
           ## 🧪 Tested Hardware
 
           - Bose SoundTouch 10
@@ -410,7 +423,7 @@ jobs:
           - Windows (amd64)
           - FreeBSD (amd64)
 
-          `soundtouch-cli`, `soundtouch-service`, and `soundtouch-web` are included.
+          `soundtouch-cli`, `soundtouch-service`, `soundtouch-web`, and `soundtouch-backup` are included.
 
           ## 🔐 Checksums
 
@@ -455,7 +468,7 @@ jobs:
           echo "release_notes_file=release_notes.md" >> $GITHUB_OUTPUT
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
         with:
           tag_name: ${{ github.event.inputs.tag }}
           name: "Bose SoundTouch Go Library ${{ github.event.inputs.tag }}"
@@ -466,6 +479,7 @@ jobs:
             release-assets/soundtouch-cli-v*
             release-assets/soundtouch-service-v*
             release-assets/soundtouch-web-v*
+            release-assets/soundtouch-backup-v*
             release-assets/checksums.sha256
             release-assets/checksums.sha512
           fail_on_unmatched_files: true
@@ -480,19 +494,20 @@ jobs:
 
     steps:
       - name: Download release assets
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: release-assets
           path: ./release-assets
 
       - name: Upload additional assets to existing release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
         with:
           tag_name: ${{ github.event.release.tag_name }}
           files: |
             release-assets/soundtouch-cli-v*
             release-assets/soundtouch-service-v*
             release-assets/soundtouch-web-v*
+            release-assets/soundtouch-backup-v*
             release-assets/checksums.sha256
             release-assets/checksums.sha512
           fail_on_unmatched_files: true
@@ -506,21 +521,21 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v4
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v6
+      - name: Extract metadata (tags, labels) for soundtouch-service
+        id: meta-service
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
@@ -528,14 +543,37 @@ jobs:
             type=semver,pattern={{major}}.{{minor}},value=v${{ needs.validate.outputs.version }}
             type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}
 
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v7
+      - name: Build and push soundtouch-service Docker image
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
         with:
           context: .
+          target: soundtouch-service
           platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
           push: true
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta-service.outputs.tags }}
+          labels: ${{ steps.meta-service.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Extract metadata (tags, labels) for soundtouch-web
+        id: meta-web
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        with:
+          images: ghcr.io/${{ github.repository }}-web
+          tags: |
+            type=semver,pattern={{version}},value=v${{ needs.validate.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=v${{ needs.validate.outputs.version }}
+            type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}
+
+      - name: Build and push soundtouch-web Docker image
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          target: soundtouch-web
+          platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
+          push: true
+          tags: ${{ steps.meta-web.outputs.tags }}
+          labels: ${{ steps.meta-web.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
@@ -549,7 +587,7 @@ jobs:
       - name: Notify success
         run: |
           echo "🎉 Release ${{ needs.validate.outputs.version }} completed successfully!"
-          echo "📦 Binaries built for 7 platforms (CLI, Service, and Web)"
+          echo "📦 Binaries built for 7 platforms (CLI, Service, Web, and Backup)"
           echo "🐳 Docker image published to ghcr.io"
           echo "🔐 Checksums generated and verified"
           echo "📋 Release notes automatically generated"

.github/workflows/security.yml

@@ -19,10 +19,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
@@ -48,7 +48,7 @@ jobs:
 
       - name: Upload vulnerability scan results
         if: failure()
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: vulnerability-scan-results
           path: |
@@ -63,10 +63,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
         with:
           go-version-file: "go.mod"
 
@@ -84,7 +84,7 @@ jobs:
           echo "::endgroup::"
 
       - name: Run Semgrep security analysis
-        uses: semgrep/semgrep-action@v1
+        uses: semgrep/semgrep-action@713efdd345f3035192eaa63f56867b88e63e4e5d # v1 (no v1.x.y semver tag exists)
         with:
           config: >-
             p/security-audit
@@ -95,7 +95,7 @@ jobs:
 
       - name: Upload Semgrep SARIF results
         if: always()
-        uses: github/codeql-action/upload-sarif@v4
+        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           sarif_file: semgrep.sarif
         continue-on-error: true
@@ -110,22 +110,22 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Install libpcap
         run: sudo apt-get install -y libpcap-dev
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
+        uses: github/codeql-action/init@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           languages: go
           config-file: ./.github/codeql-config.yml
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v4
+        uses: github/codeql-action/autobuild@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
+        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
         with:
           category: "/language:go"
 
@@ -138,10 +138,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@v4
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
         with:
           fail-on-severity: moderate
           allow-ghsas: GHSA-xxxx-xxxx-xxxx  # Add specific allowlisted advisories if needed

.gitignore

@@ -12,15 +12,18 @@ dist/
 #example-upnp
 
 # Root-level binary executables (exclude built binaries in root)
+/soundtouch-backup
 /soundtouch-cli
 /soundtouch-service
 /soundtouch-web
+/dummy-speaker
 /example-mdns
 /example-upnp
 /example-unified
 /mdns-scanner
 /websocket-demo
 /main
+/screenshots
 
 # Environment configuration
 .env
@@ -57,6 +60,15 @@ vendor/
 ehthumbs.db
 Thumbs.db
 
+# Android MITM setup — downloaded/generated artefacts, not committed
+scripts/android/bose.apk
+scripts/android/frida-server
+scripts/android/frida-server.xz
+scripts/android/frida/
+scripts/android/frida-venv/
+scripts/android/captures/
+scripts/android/mitm/
+
 # Temporary files
 *.tmp
 *.temp

Dockerfile

@@ -1,5 +1,5 @@
 # Build stage
-FROM --platform=$BUILDPLATFORM golang:1.26.2-alpine AS builder
+FROM --platform=$BUILDPLATFORM golang:1.26.3-alpine AS builder
 
 # Declare automatic platform ARGs to make them available in build stage
 # See https://docs.docker.com/reference/dockerfile#automatic-platform-args-in-the-global-scope
@@ -24,31 +24,47 @@ RUN if [ "${TARGETARCH}" = "arm" ] && [ -n "${TARGETVARIANT}" ]; then \
       CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /soundtouch-service ./cmd/soundtouch-service; \
     fi
 
-# Final stage
-FROM alpine:3.23
+# Build the soundtouch-web
+RUN if [ "${TARGETARCH}" = "arm" ] && [ -n "${TARGETVARIANT}" ]; then \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} go build -o /soundtouch-web ./cmd/soundtouch-web; \
+    else \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /soundtouch-web ./cmd/soundtouch-web; \
+    fi
+
+# soundtouch-service image
+FROM alpine:3.23 AS soundtouch-service
 
-# Install necessary runtime dependencies
 RUN apk add --no-cache ca-certificates tzdata
 
 WORKDIR /app
 
-# Copy the binary from the builder stage
 COPY --from=builder /soundtouch-service /app/soundtouch-service
 
 # Verify the binary works on the target platform
 RUN /app/soundtouch-service version || echo "Binary verification complete"
 
-# Create data directory for persistence
 RUN mkdir -p /app/data
 
-# Set environment variables with defaults
 ENV PORT=8000
 ENV DATA_DIR=/app/data
 ENV LOG_PROXY_BODY=false
 ENV REDACT_PROXY_LOGS=true
 
-# Expose the service port
 EXPOSE 8000
 
-# Run the service
 ENTRYPOINT ["/app/soundtouch-service"]
+
+# soundtouch-web image
+FROM alpine:3.23 AS soundtouch-web
+
+RUN apk add --no-cache ca-certificates tzdata
+
+WORKDIR /app
+
+COPY --from=builder /soundtouch-web /app/soundtouch-web
+
+ENV PORT=8080
+
+EXPOSE 8080
+
+ENTRYPOINT ["/app/soundtouch-web"]

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build build-cli test test-coverage check fmt vet lint clean dev help
+.PHONY: all build build-cli test test-coverage check fmt vet lint clean dev help screenshots
 
 # Go parameters
 GOCMD=go
@@ -24,81 +24,99 @@ SCANNER_NAME=mdns-scanner
 SCANNER_PATH=./cmd/$(SCANNER_NAME)
 FAVICON_GEN_NAME=favicon-gen
 FAVICON_GEN_PATH=./cmd/$(FAVICON_GEN_NAME)
+BACKUP_NAME=soundtouch-backup
+BACKUP_PATH=./cmd/$(BACKUP_NAME)
 BUILD_DIR=./build
 
-# Version info
-# No ldflags needed - using debug.BuildInfo since Go 1.18
+# Build flags: strip debug info/DWARF for smaller binaries, remove local paths for reproducibility
+BUILDFLAGS=-trimpath -ldflags="-s -w"
 
 all: check build
 
-build: build-cli build-service build-web build-examples build-favicon-gen
+build: build-cli build-service build-web build-examples build-favicon-gen build-backup
 
 build-cli:
 	@echo "Building $(BINARY_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME) $(BINARY_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME) $(BINARY_PATH)
 
 build-service:
 	@echo "Building $(SERVICE_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(SERVICE_NAME) $(SERVICE_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME) $(SERVICE_PATH)
 
 build-web:
 	@echo "Building $(WEB_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(WEB_NAME) $(WEB_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(WEB_NAME) $(WEB_PATH)
 
 build-examples:
 	@echo "Building $(EXAMPLE_MDNS_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME) $(EXAMPLE_MDNS_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME) $(EXAMPLE_MDNS_PATH)
 	@echo "Building $(EXAMPLE_UPNP_NAME)..."
-	$(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME) $(EXAMPLE_UPNP_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME) $(EXAMPLE_UPNP_PATH)
 	@echo "Building $(SCANNER_NAME)..."
-	$(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME) $(SCANNER_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME) $(SCANNER_PATH)
 
 build-favicon-gen:
 	@echo "Building $(FAVICON_GEN_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) -o $(BUILD_DIR)/$(FAVICON_GEN_NAME) $(FAVICON_GEN_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(FAVICON_GEN_NAME) $(FAVICON_GEN_PATH)
 
-build-all: build-linux build-darwin build-windows build-examples-all
+build-backup:
+	@echo "Building $(BACKUP_NAME)..."
+	@mkdir -p $(BUILD_DIR)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME) $(BACKUP_PATH)
+
+build-all: build-linux build-linux-armv7 build-darwin build-windows build-examples-all
 
 build-linux:
 	@echo "Building for Linux..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 $(BINARY_PATH)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SERVICE_NAME)-linux-amd64 $(SERVICE_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 $(BINARY_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-linux-amd64 $(SERVICE_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-linux-amd64 $(BACKUP_PATH)
+
+build-linux-armv7:
+	@echo "Building for Linux ARMv7 (CGO_ENABLED=0 for kernel 3.14+ compatibility)..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-linux-armv7 $(SERVICE_PATH)
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-armv7 $(BINARY_PATH)
+	GOOS=linux GOARCH=arm GOARM=7 CGO_ENABLED=0 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-linux-armv7 $(BACKUP_PATH)
 
 build-darwin:
 	@echo "Building for macOS..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 $(BINARY_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 $(BINARY_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SERVICE_NAME)-darwin-amd64 $(SERVICE_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(SERVICE_NAME)-darwin-arm64 $(SERVICE_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-amd64 $(BINARY_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 $(BINARY_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-darwin-amd64 $(SERVICE_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-darwin-arm64 $(SERVICE_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-darwin-amd64 $(BACKUP_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-darwin-arm64 $(BACKUP_PATH)
 
 build-windows:
 	@echo "Building for Windows..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe $(BINARY_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SERVICE_NAME)-windows-amd64.exe $(SERVICE_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe $(BINARY_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME)-windows-amd64.exe $(SERVICE_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(BACKUP_NAME)-windows-amd64.exe $(BACKUP_PATH)
 
 build-examples-all:
 	@echo "Building examples for all platforms..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-linux-amd64 $(EXAMPLE_MDNS_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-amd64 $(EXAMPLE_MDNS_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-arm64 $(EXAMPLE_MDNS_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-windows-amd64.exe $(EXAMPLE_MDNS_PATH)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-linux-amd64 $(EXAMPLE_UPNP_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-amd64 $(EXAMPLE_UPNP_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-arm64 $(EXAMPLE_UPNP_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-windows-amd64.exe $(EXAMPLE_UPNP_PATH)
-	GOOS=linux GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-linux-amd64 $(SCANNER_PATH)
-	GOOS=darwin GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-amd64 $(SCANNER_PATH)
-	GOOS=darwin GOARCH=arm64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-arm64 $(SCANNER_PATH)
-	GOOS=windows GOARCH=amd64 $(GOBUILD) -o $(BUILD_DIR)/$(SCANNER_NAME)-windows-amd64.exe $(SCANNER_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-linux-amd64 $(EXAMPLE_MDNS_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-amd64 $(EXAMPLE_MDNS_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-darwin-arm64 $(EXAMPLE_MDNS_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_MDNS_NAME)-windows-amd64.exe $(EXAMPLE_MDNS_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-linux-amd64 $(EXAMPLE_UPNP_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-amd64 $(EXAMPLE_UPNP_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-darwin-arm64 $(EXAMPLE_UPNP_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(EXAMPLE_UPNP_NAME)-windows-amd64.exe $(EXAMPLE_UPNP_PATH)
+	GOOS=linux GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-linux-amd64 $(SCANNER_PATH)
+	GOOS=darwin GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-amd64 $(SCANNER_PATH)
+	GOOS=darwin GOARCH=arm64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-darwin-arm64 $(SCANNER_PATH)
+	GOOS=windows GOARCH=amd64 $(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SCANNER_NAME)-windows-amd64.exe $(SCANNER_PATH)
 
 test:
 	@echo "Running tests..."
@@ -124,6 +142,7 @@ test-http-client:
 		--env-file /workdir/http-client.env.json \
 		--env ci \
 		/workdir/spotify_registration.http \
+		/workdir/amazon_registration.http \
 		/workdir/create_account.http \
 		/workdir/register_device.http \
 		/workdir/spotify_full_flow.http \
@@ -135,6 +154,7 @@ test-http-client:
 		/workdir/get_soundtouch_updates.http \
 		/workdir/get_streaming_token.http \
 		/workdir/post_oauth_token.http \
+		/workdir/post_oauth_token_amazon.http \
 		/workdir/get_provider_settings.http \
 		/workdir/tunein_playback_station.http \
 		/workdir/set_preset_6.http \
@@ -155,6 +175,7 @@ test-http-client:
 	EXIT_CODE=$$?; \
 	docker compose -f docker-compose.yml -f docker-compose.ci.yml logs soundtouch-service; \
 	docker compose -f docker-compose.yml -f docker-compose.ci.yml logs spotify-mock; \
+	docker compose -f docker-compose.yml -f docker-compose.ci.yml logs amazon-mock; \
 	docker compose -f docker-compose.yml -f docker-compose.ci.yml down; \
 	exit $$EXIT_CODE
 
@@ -259,6 +280,18 @@ dev-web-port: build-web
 	fi
 	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -port $(PORT)
 
+dev-backup: build-backup
+	@echo "Running backup tool..."
+	$(BUILD_DIR)/$(BACKUP_NAME) --help
+
+dev-backup-cloud: build-backup
+	@echo "Running cloud backup..."
+	$(BUILD_DIR)/$(BACKUP_NAME) cloud
+
+dev-backup-local: build-backup
+	@echo "Running local backup (auto-discover)..."
+	$(BUILD_DIR)/$(BACKUP_NAME) local --discover
+
 dev-web-host: build-web
 	@echo "Starting web UI with specific host..."
 	@if [ -z "$(HOST)" ]; then \
@@ -267,11 +300,12 @@ dev-web-host: build-web
 	fi
 	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -host $(HOST)
 
-install: build-cli build-service build-web
+install: build-cli build-service build-web build-backup
 	@echo "Installing binaries to $(GOPATH)/bin..."
 	cp $(BUILD_DIR)/$(BINARY_NAME) $(GOPATH)/bin/
 	cp $(BUILD_DIR)/$(SERVICE_NAME) $(GOPATH)/bin/
 	cp $(BUILD_DIR)/$(WEB_NAME) $(GOPATH)/bin/
+	cp $(BUILD_DIR)/$(BACKUP_NAME) $(GOPATH)/bin/
 
 clean:
 	@echo "Cleaning..."
@@ -291,7 +325,7 @@ release: clean check build-all
 
 docker-build:
 	@echo "Building Docker image..."
-	docker build -t soundtouch-service .
+	docker build --target soundtouch-service -t soundtouch-service .
 
 docker-run-host:
 	@echo "Running Docker container..."
@@ -302,14 +336,20 @@ docker-run-ports:
 	@echo "Running Docker container with port mapping (discovery will be manual)..."
 	docker run --rm -it -p 8000:8000 -v $$(pwd)/data:/app/data soundtouch-service
 
+screenshots:
+	@echo "Capturing documentation screenshots..."
+	@bash scripts/screenshots/run.sh
+
 help:
 	@echo "Available targets:"
 	@echo "  build         - Build the CLI tool, service, and examples"
 	@echo "  build-cli     - Build only the CLI tool"
 	@echo "  build-service - Build only the service"
+	@echo "  build-backup  - Build only the backup tool"
 	@echo "  build-favicon-gen - Build the favicon generator"
 	@echo "  build-examples - Build only the example programs"
 	@echo "  build-all     - Build for all platforms"
+	@echo "  build-linux-armv7 - Build for Linux ARMv7 (kernel 3.14+ compatible, CGO_ENABLED=0)"
 	@echo "  test          - Run tests"
 	@echo "  test-coverage - Run tests with coverage report"
 	@echo "  check         - Run fmt, vet, and tests"
@@ -320,6 +360,7 @@ help:
 	@echo "  dev           - Build and show CLI help"
 	@echo "  dev-service   - Build and run service locally"
 	@echo "  dev-service-proxy - Build and run service with proxy (PROXY_URL=url required)"
+	@echo "  screenshots   - Capture documentation screenshots (headless Chrome via chromedp)"
 	@echo "  dev-discover  - Build and run device discovery"
 	@echo "  dev-info      - Build and get device info (HOST=ip required)"
 	@echo "  dev-mdns      - Build and run mDNS discovery example"
@@ -331,6 +372,9 @@ help:
 	@echo "  dev-scan-all     - Scan all mDNS services on network"
 	@echo "  dev-scan-soundtouch - Scan specifically for SoundTouch mDNS services"
 	@echo "  dev-scan-http    - Scan for HTTP mDNS services"
+	@echo "  dev-backup       - Build and show backup tool help"
+	@echo "  dev-backup-cloud - Build and run cloud backup (prompts for credentials)"
+	@echo "  dev-backup-local - Build and run local backup (auto-discover speakers)"
 	@echo "  dev-web          - Build and run web UI (default port 8080)"
 	@echo "  dev-web-port     - Build and run web UI on custom port (PORT=8888)"
 	@echo "  dev-web-host     - Build and run web UI with specific device (HOST=ip)"

README.md

@@ -1,549 +1,129 @@
 # Bose SoundTouch Toolkit
 
-A comprehensive solution for controlling and preserving Bose SoundTouch devices, including a Go library, CLI tool, and a local service for cloud emulation.
-
 [![Go Reference](https://pkg.go.dev/badge/github.com/gesellix/bose-soundtouch.svg)](https://pkg.go.dev/github.com/gesellix/bose-soundtouch)
 [![Go Report Card](https://goreportcard.com/badge/github.com/gesellix/bose-soundtouch)](https://goreportcard.com/report/github.com/gesellix/bose-soundtouch)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> **Note**: This is an independent project based on the [official Bose SoundTouch Web API documentation](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf). Not affiliated with or endorsed by Bose Corporation.
+> Independent project. Not affiliated with or endorsed by Bose Corporation.
 
-## Features
+## Context: Cloud Shutdown
 
-- ✅ **Complete API Coverage**: All available SoundTouch Web API endpoints implemented
-- 🎵 **Media Control**: Play, pause, stop, volume, bass, balance, source selection
-- 🔔 **Smart Notifications**: TTS messages, URL audio content, notification beeps (ST-10)
-- 🏠 **Multiroom Support**: Create and manage zones across multiple speakers
-- ⚡ **Real-time Events**: WebSocket connection for live device state monitoring
-- 🔍 **Device Discovery**: Automatic discovery via UPnP/SSDP and mDNS
-- 📻 **Content Navigation**: Browse and search TuneIn, Pandora, Spotify, local music
-- 📻 **Custom Radio**: Play any stream URL via [flexible proxying](docs/guides/CLI-REFERENCE.md#custom-radio-selection-via-soundtouch-service)
-- 📻 **RadioBrowser**: Access thousands of internet radio stations via [radio-browser.info](docs/reference/radio-browser.md)
-- 🎙️ **Station Management**: Add and play radio stations without presets
-- 🖥️ **CLI Tool**: Comprehensive command-line interface
-- 🌐 **SoundTouch Service**: Emulate Bose cloud services for offline device operation
-- 🔧 **Service Migration**: Migrate devices to use local services instead of Bose cloud (XML, Hosts, or DNS redirection)
-- 🔍 **DNS Discovery & Interception**: Dynamic DNS server for intercepting and logging Bose service queries (requires port 53)
-- 📊 **DNS Discovery Analysis**: Track and deduplicate all device DNS queries to discover hidden hostnames
-- 📊 **Traffic Analysis**: Proxy and log device communications
-- 📝 **HTTP Recording**: Persist interactions as re-playable `.http` files
-- 🔄 **Endpoint Mirroring**: Asynchronously mirror local requests to Bose cloud for parity testing
-- ⚖️ **Parity Logging**: Detect and record discrepancies between local and official Bose responses
-- 🧹 **Session Management**: Manage and cleanup recorded interaction sessions
-- 🔒 **Production Ready**: Extensive testing with real SoundTouch hardware
-- 🌐 **Cross-Platform**: Windows, macOS, Linux support
+Bose is shutting down SoundTouch cloud services on **May 6, 2026**. After that, music service browsing, preset sync, and the official SoundTouch app stop working. This toolkit lets you keep your speakers fully functional.
 
-## Quick Start
+See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html) for the full picture.
 
-### Installation
+---
+
+## Tools
+
+### soundtouch-service — AfterTouch
+
+A local server that replaces the Bose cloud ("AfterTouch"). Once your speaker is redirected to it, you have full control without any Bose cloud dependency. The built-in web UI at `http://localhost:8000` handles all setup — no config files needed to get started.
+
+If you want to run a server for this - no problem. The service is small enough to run on the SoundTouch itself. See the [On-Device Installer](./scripts/on-device-install/README.md) for instructions.
+
+**Two scenarios:**
+
+**Before shutdown — migrate your existing setup**
+While the Bose cloud is still running, use `soundtouch-backup` to save your account data. The local service web UI then helps with the migration so your speaker keeps its presets and credentials.
+
+**After shutdown or factory reset — start fresh**
+Create a local account, configure your speakers, and start using them immediately. No Bose infrastructure required.
+
+**Redirecting your speaker**
+
+The service needs a stable address on your local network (e.g. `soundtouch.fritz.box` or `soundtouch.local`). The speaker must then be redirected to resolve the Bose cloud hostnames to that address. Two supported methods:
+
+| Method       | How it works                        | Notes                                                        |
+|--------------|-------------------------------------|--------------------------------------------------------------|
+| XML redirect | Upload a config XML via the Web API | Surgical; covers only registered endpoints; best for testing |
+| DNS/DHCP     | Serve custom DNS on your network    | Covers all devices at once; requires port 53 and TLS         |
+
+The web UI walks you through each method. DNS redirect requires HTTPS — the service manages its own CA certificate and the web UI guides you through trusting it on each speaker.
+
+> **Note:** A hosts-file method (direct SSH edits to `/etc/hosts`) also exists in the codebase but is deprecated and not exposed in the web UI.
+
+**Enabling SSH via USB stick**
+
+Some setup steps require SSH access to the speaker. Enable it once per device: create a file named `remote_services` on a FAT-formatted USB drive (the drive may need its bootable flag set — see [SoundCork issue #172](https://github.com/deborahgu/soundcork/issues/172)), and insert it while the speaker is powered on. After reboot, root SSH is available with no password.
+
+See [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html) and [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-GUIDE.html) for step-by-step instructions.
+
+---
+
+### soundtouch-backup
+
+Backs up your Bose cloud account (presets, paired devices, music sources) and each speaker's local state before the shutdown. Run `soundtouch-backup all` to capture everything in one step; it authenticates with the Bose cloud, then polls each paired speaker over the local network.
+
+See the [soundtouch-backup README](cmd/soundtouch-backup/README.md) for usage.
+
+---
+
+### soundtouch-cli
+
+Command-line control of any SoundTouch device: play/pause/volume, presets, source selection, multiroom zones, device discovery, and more. Works entirely over the local network — no cloud dependency. Well-suited for scripting and home automation.
+
+See the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html) for full usage.
+
+---
+
+### soundtouch-web
+
+A standalone web UI for device control — play, pause, volume, preset selection, real-time status — served from a local Go binary. Complements `soundtouch-service` when you want a dedicated device-control interface separate from the setup/admin UI.
+
+See the [soundtouch-web README](cmd/soundtouch-web/README.md) for usage.
+
+---
+
+### Go library
+
+`pkg/client` provides a Go API for all SoundTouch device endpoints: media control, volume, presets, sources, zones, real-time WebSocket events, and device discovery. Use it to build your own integrations.
 
-#### Install CLI and Service Tools
-```bash
-go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-cli@latest
-go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
 ```
-
-#### Add Library to Your Project
-```bash
 go get github.com/gesellix/bose-soundtouch
 ```
 
-### CLI Usage
+See the [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html) and [pkg.go.dev](https://pkg.go.dev/github.com/gesellix/bose-soundtouch) for documentation.
 
-Find SoundTouch devices on your network:
-```bash
-soundtouch-cli discover devices
-```
-
-Control a device (replace `192.168.1.100` with your speaker's IP):
-```bash
-# Basic information
-soundtouch-cli --host 192.168.1.100 info
-
-# Media controls
-soundtouch-cli --host 192.168.1.100 play start
-soundtouch-cli --host 192.168.1.100 volume set --level 50
-
-# Preset management
-soundtouch-cli --host 192.168.1.100 preset list
-```
-
-For full CLI documentation, see the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html).
-
-### SoundTouch Service (Cloud Shutdown Protection)
-
-The `soundtouch-service` is a local server that emulates Bose's cloud services. This is critical for keeping your speakers functional after the **Bose Cloud Shutdown in May 2026**.
-
-#### Key Features:
-- **🏠 Local Emulation**: BMX and Marge service implementation
-- **🔌 Easy Setup**: Activate SSH via USB stick (`remote_services` file)
-- **🔧 Device Migration**: Seamlessly transition devices to local control
-- **🌐 Web Management UI**: Easy browser-based setup and management
-- **💾 Persistent Data**: Store presets, recents, and sources locally
-- **🔄 Endpoint Mirroring**: Asynchronously mirror local requests to Bose cloud for parity testing
-- **⚖️ Parity Logging**: Detect and record discrepancies between local and official Bose responses
-- **📝 HTTP Recording**: Persist all interactions as re-playable `.http` files
-- **🧹 Session Management**: Manage and cleanup recorded interaction sessions
-
-#### Quick Start:
-```bash
-# Start the service
-soundtouch-service
-```
-Open `http://localhost:8000` in your browser to manage your devices. Documentation is also available directly through the web interface.
-
-For a comprehensive guide on transitioning your system, see the [Bose Cloud Shutdown: Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html).
-
-Detailed service configuration and Docker instructions can be found in [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html).
-
-For professional migration tips and safety measures, see the [Migration & Safety Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-SAFETY.html).
-
-### Library Usage
-
-#### Basic Control
-```go
-package main
-
-import (
-    "fmt"
-    "log"
-
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-)
-
-func main() {
-    // Connect to your SoundTouch device
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-
-    // Get device information
-    info, err := c.GetDeviceInfo()
-    if err != nil {
-        log.Fatal(err)
-    }
-    fmt.Printf("Device: %s\n", info.Name)
-
-    // Control playback
-    err = c.Play()
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Set volume
-    err = c.SetVolume(50)
-    if err != nil {
-        log.Fatal(err)
-    }
-}
-```
-
-#### Device Discovery
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "log"
-    "time"
-
-    "github.com/gesellix/bose-soundtouch/pkg/discovery"
-)
-
-func main() {
-    // Discover SoundTouch devices
-    service := discovery.NewService(5 * time.Second)
-    devices, err := service.DiscoverDevices(context.Background())
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    for _, device := range devices {
-        fmt.Printf("Found: %s at %s:%d\n",
-            device.Name, device.Host, device.Port)
-    }
-}
-```
-
-#### Real-time Events
-```go
-package main
-
-import (
-    "context"
-    "fmt"
-    "log"
-
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-func main() {
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-
-    // Subscribe to device events
-    events, err := c.SubscribeToEvents(context.Background())
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    for event := range events {
-        switch e := event.(type) {
-        case *models.NowPlayingUpdated:
-            fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
-        case *models.VolumeUpdated:
-            fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
-        case *models.ConnectionStateUpdated:
-            fmt.Printf("Connection state: %s\n", e.State)
-        }
-    }
-}
-```
-
-#### Preset Management
-```go
-package main
-
-import (
-    "fmt"
-    "log"
-
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-func main() {
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-
-    // Get current presets
-    presets, err := c.GetPresets()
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    fmt.Printf("Found %d presets\n", len(presets.Preset))
-
-    // Store currently playing content as preset 1
-    err = c.StoreCurrentAsPreset(1)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Store Spotify playlist as preset 2
-    spotifyContent := &models.ContentItem{
-        Source:        "SPOTIFY",
-        Type:          "uri",
-        Location:      "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M",
-        SourceAccount: "your_username",
-        IsPresetable:  true,
-        ItemName:      "Today's Top Hits",
-    }
-    err = c.StorePreset(2, spotifyContent)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Store radio station as preset 3
-    radioContent := &models.ContentItem{
-        Source:       "TUNEIN",
-        Type:         "stationurl",
-        Location:     "/v1/playbook/station/s33828",
-        IsPresetable: true,
-        ItemName:     "K-LOVE Radio",
-    }
-    err = c.StorePreset(3, radioContent)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Select preset 1
-    err = c.SelectPreset(1)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    fmt.Println("Preset management complete!")
-}
-```
-
-#### Multiroom Zones
-```go
-package main
-
-import (
-    "log"
-
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-func main() {
-    master := client.NewClient(&client.Config{
-        Host: "192.168.1.100", // Master speaker
-        Port: 8090,
-    })
-
-    // Create a multiroom zone
-    zone := &models.Zone{
-        Master: "192.168.1.100",
-        Members: []models.ZoneMember{
-            {IPAddress: "192.168.1.101"}, // Living room
-            {IPAddress: "192.168.1.102"}, // Kitchen
-        },
-    }
-
-    err := master.SetZone(zone)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    fmt.Println("Multiroom zone created!")
-}
-```
-
-#### Speaker Notifications (ST-10 only)
-```go
-package main
-
-import (
-    "log"
-
-    "github.com/gesellix/bose-soundtouch/pkg/client"
-)
-
-func main() {
-    c := client.NewClient(&client.Config{
-        Host: "192.168.1.100",
-        Port: 8090,
-    })
-
-    // Play Text-to-Speech message (language code "EN", "DE", etc.)
-    err := c.PlayTTS("Welcome home!", "your-app-key", "EN", 70)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Play audio content from URL
-    err = c.PlayURL(
-        "https://example.com/doorbell.mp3",
-        "your-app-key",
-        "Doorbell",
-        "Front Door",
-        "Visitor Alert",
-        80,
-    )
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Play notification beep
-    err = c.PlayNotificationBeep()
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    fmt.Println("Notifications sent!")
-}
-```
-
-## Supported Devices
-
-This library supports all Bose SoundTouch-compatible devices, including:
-
-- SoundTouch 10, 20, 30 series
-- SoundTouch Portable
-- Wave SoundTouch music system
-- SoundTouch-enabled Bose speakers
-
-**Tested Hardware**:
-- ✅ SoundTouch 10
-- ✅ SoundTouch 20
-
-## API Coverage
-
-| Feature | Status | Description |
-|---------|--------|-------------|
-| Device Info | ✅ Complete | Device details, name, capabilities |
-| Media Control | ✅ Complete | Play/pause/stop, track navigation |
-| Volume & Audio | ✅ Complete | Volume, bass, balance control |
-| Source Selection | ✅ Complete | Spotify, Bluetooth, AUX, etc. |
-| Content Navigation | ✅ Complete | Browse music libraries, radio stations |
-| Station Management | ✅ Complete | Search, add, remove stations |
-| Preset Management | ✅ Complete | Store, select, remove presets |
-| Real-time Events | ✅ Complete | WebSocket event streaming |
-| Multiroom Zones | ✅ Complete | Zone creation and management |
-| Speaker Notifications | ✅ Complete | TTS, URL audio, beep alerts (ST-10) |
-| System Settings | ✅ Complete | Clock, display, network info |
-| Advanced Audio | ✅ Complete | DSP controls, tone controls |
-
-**API Limitations**: None - all documented SoundTouch Web API functionality is implemented, including endpoints discovered via the comprehensive [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API).
+---
 
 ## Documentation
 
-- 📖 [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project
- - 📚 [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html) - Complete endpoint documentation
-- 🔧 [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html) - Command-line tool guide
-- 🌐 [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html) - Local service setup and migration
-- 🎯 [Getting Started](https://gesellix.github.io/Bose-SoundTouch/guides/GETTING-STARTED.html) - Detailed setup and usage
-- 📻 [Preset Quick Start](https://gesellix.github.io/Bose-SoundTouch/PRESET-QUICKSTART.md) - Favorite content management
-- 🧭 [Navigation Guide](https://gesellix.github.io/Bose-SoundTouch/NAVIGATION-GUIDE.md) - Content browsing and station management
-- 📋 [Navigation API Reference](https://gesellix.github.io/Bose-SoundTouch/API-NAVIGATION-REFERENCE.md) - Navigation API documentation
-- ⚙️ [Advanced Features](https://gesellix.github.io/Bose-SoundTouch/reference/SYSTEM-ENDPOINTS.html) - Advanced functionality
-- 🏠 [Multiroom Setup](https://gesellix.github.io/Bose-SoundTouch/reference/ZONE-MANAGEMENT.html) - Zone configuration guide
-- ⚡ [WebSocket Events](https://gesellix.github.io/Bose-SoundTouch/reference/WEBSOCKET-EVENTS.html) - Real-time event handling
-- 🔔 [Speaker Notifications](https://gesellix.github.io/Bose-SoundTouch/reference/SPEAKER-ENDPOINT.html) - TTS and audio notifications guide
-- 🔍 [Device Discovery](https://gesellix.github.io/Bose-SoundTouch/reference/DISCOVERY.html) - Discovery configuration
-- 🛠️ [Troubleshooting](https://gesellix.github.io/Bose-SoundTouch/guides/TROUBLESHOOTING.html) - Common issues and solutions
+- [Getting Started](https://gesellix.github.io/Bose-SoundTouch/guides/GETTING-STARTED.html)
+- [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html)
+- [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-GUIDE.html)
+- [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html)
+- [Migration & Safety Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-SAFETY.html)
+- [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html)
+- [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html)
+- [HTTPS & CA Setup](https://gesellix.github.io/Bose-SoundTouch/guides/HTTPS-SETUP.html)
+- [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html)
 
-## Development
+---
 
-### Prerequisites
-- Go 1.25.6 or later
-- Optional: SoundTouch device for testing
+## Related projects
 
-### Building from Source
-```bash
-# Clone the repository
-git clone https://github.com/gesellix/bose-soundtouch.git
-cd Bose-SoundTouch
+- **[SoundCork](https://github.com/deborahgu/soundcork)** (Deborah Kaplan et al.) — Python service interception; pioneered the cloud emulation approach this project builds on
+- **[SoundCork Stockholm App](https://github.com/krahl/soundcork-stockholm-app)** — Companion app for SoundCork
+- **[SoundTouch Plus](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus)** (Todd Lucas) — Home Assistant integration; extensive undocumented API documentation
+- **[ÜberBöse API](https://github.com/julius-d/ueberboese-api)** (Julius) — API research and advanced endpoint discovery
+- **[Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook)** (Adrian Böckenkamp) — `LD_PRELOAD` hooking for reverse engineering device internals
 
-# Install dependencies
-go mod download
-
-# Build CLI tool
-make build
-
-# Run tests
-make test
-
-# Install CLI locally
-go install ./cmd/soundtouch-cli
-```
-
-### Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
-
-- Setting up your development environment
-- Coding guidelines and best practices
-- Testing with real devices
-- Submitting pull requests
-
-## Examples
-
-Check out the [examples/](examples/) directory for more usage patterns:
-
-- **Basic HTTP Client**: Simple device control
-- **Preset Management**: Store and manage favorite content
-- **Navigation & Stations**: Browse content and manage radio stations
-- **WebSocket Events**: Real-time monitoring
-- **Device Discovery**: Finding devices on your network
-- **Multiroom Management**: Zone operations
-- **Advanced Audio**: DSP and tone controls
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Disclaimer
-
-This is an independent project based on the official Bose SoundTouch Web API documentation provided by Bose Corporation. It is not affiliated with, endorsed by, or supported by Bose Corporation. Use at your own risk.
-
-SoundTouch is a trademark of Bose Corporation.
-
-## SoundTouch End of Life Notice
-
-**Important:** Bose has announced that [SoundTouch cloud support will end on May 6, 2026](https://www.bose.com/soundtouch-end-of-life).
-
-**What will continue to work:**
-- ✅ Local API control (this library's primary functionality)
-- ✅ Bluetooth, AirPlay, Spotify Connect, and AUX streaming
-- ✅ Remote control features (Play, Pause, Skip, Volume)
-- ✅ Multiroom grouping
-
-**What will stop working:**
-- ❌ Cloud-based preset sync between devices and SoundTouch app
-- ❌ Browsing music services directly from the SoundTouch app
-- ❌ Cloud-based features and updates
-
-**What continues to work:**
-- ✅ Local preset management via this API client (store, select, remove)
-- ✅ Direct content playback (stations, playlists, etc.)
-
-This Go library will continue to work as it uses the local Web API for direct device control, which is unaffected by the cloud service discontinuation. The local preset management functionality implemented in this library (discovered through the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)) provides an alternative to the cloud-based preset features that will be discontinued.
-
-**Community Alternatives**: See the [Related Projects & Credits](#related-projects--credits) section below for additional tools like SoundCork that provide cloud service alternatives and the SoundTouch Plus project that offers comprehensive Home Assistant integration.
-
-## Related Projects & Credits
-
-This project builds upon the excellent work of several community projects:
-
-### SoundCork 🍾
-- **Project**: [SoundCork - SoundTouch API Intercept](https://github.com/deborahgu/soundcork)
-- **Authors**: Deborah Kaplan and contributors
-- **Our Implementation**: The `soundtouch-service` in this project is heavily inspired by SoundCork's Python implementation. SoundCork pioneered the approach of intercepting and emulating Bose's cloud services, providing the foundation for offline SoundTouch operation.
-- **Key Contributions**: Service emulation architecture, BMX/Marge endpoint discovery, device migration strategies
-- **License**: MIT License
-
-### ÜberBöse API 🎵
-- **Project**: [ÜberBöse API](https://github.com/julius-d/ueberboese-api)
-- **Author**: Julius
-- **Our Implementation**: This project provided valuable insights into advanced SoundTouch API endpoints and helped make our implementation more complete, particularly for content navigation and advanced device features.
-- **Key Contributions**: Extended API endpoint documentation, advanced feature discovery
-- **License**: MIT License
-
-### SoundTouch Plus 🏠
-- **Project**: [SoundTouch Plus Home Assistant Component](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus)
-- **Wiki**: [SoundTouch WebServices API Documentation](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
-- **Author**: Todd Lucas
-- **Our Implementation**: The comprehensive API documentation in the SoundTouch Plus Wiki provided invaluable insights into undocumented endpoints beyond the official API, enabling our preset management and content navigation features.
-- **Key Contributions**: Extensive API endpoint documentation, real-world usage patterns
-- **License**: MIT License
-
-### SoundTouch Hook 🪝
-- **Project**: [Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook)
-- **Author**: Adrian Böckenkamp
-- **Our Implementation**: This project provides a powerful framework for intercepting and hooking into internal device processes using `LD_PRELOAD`. It was instrumental in verifying internal function calls and understanding how the device validates cloud domains.
-- **Key Contributions**: Reverse engineering framework, process hooking, cross-compilation toolchain
-- **License**: GPL-3.0 License
-
-### Community Ecosystem
-
-These projects together form a comprehensive ecosystem for SoundTouch device management:
-
-- **This Project**: Go library + CLI + service for programmatic control and offline operation
-- **SoundCork**: Python-based service interception and cloud replacement
-- **SoundTouch Plus**: Home Assistant integration with extensive device support
-- **ÜberBöse**: API research and advanced endpoint discovery
-- **SoundTouch Hook**: Advanced reverse engineering and process instrumentation
-
-We are grateful to these projects and their maintainers for paving the way and providing the foundation that made this comprehensive Go implementation possible. The SoundTouch community's collaborative approach to reverse engineering and documentation has been invaluable.
-
-### Contributing Back
-
-If you discover new endpoints, features, or improvements through this library, please consider contributing back to these projects as well. The stronger our community ecosystem becomes, the better we can support SoundTouch devices beyond Bose's official support timeline.
+---
 
 ## Support
 
-- 🐛 **Bug Reports**: [Create an issue](https://github.com/gesellix/bose-soundtouch/issues/new)
-- 💡 **Feature Requests**: [Start a discussion](https://github.com/gesellix/bose-soundtouch/discussions)
-- ❓ **Questions**: Check [existing discussions](https://github.com/gesellix/bose-soundtouch/discussions)
-- 📖 **Documentation**: [Online Documentation](https://gesellix.github.io/Bose-SoundTouch/)
-- 🔍 **New Discoveries**: [Undocumented Community Features](https://gesellix.github.io/Bose-SoundTouch/UNDOCUMENTED-COMMUNITY-FEATURES.md)
-- 🌐 **Upstream Analysis**: [Upstream URLs & Domains](https://gesellix.github.io/Bose-SoundTouch/analysis/UPSTREAM-URLS.html)
-- 🔧 **Redirection Guide**: [Device Redirect Methods](https://gesellix.github.io/Bose-SoundTouch/analysis/DEVICE-REDIRECT-METHODS.html)
-- 🐣 **Initial Setup**: [Device Initial Setup Variants](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html)
-- 📜 **Logging & Debugging**: [Device Logging Guide](https://gesellix.github.io/Bose-SoundTouch/DEVICE-LOGGING.md)
-- 🔒 **HTTPS & CA Setup**: [HTTPS & Custom CA Guide](https://gesellix.github.io/Bose-SoundTouch/guides/HTTPS-SETUP.html)
+- Bug reports: [GitHub Issues](https://github.com/gesellix/bose-soundtouch/issues/new)
+- Questions & discussions: [GitHub Discussions](https://github.com/gesellix/bose-soundtouch/discussions)
 
 ---
 
 **Star this project** ⭐ if you find it useful!
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+SoundTouch is a trademark of Bose Corporation.

cmd/dummy-speaker/main.go

@@ -0,0 +1,107 @@
+// Command dummy-speaker runs an HTTP-only fake SoundTouch speaker and
+// optionally registers it with a running soundtouch-service so the web UI
+// has a device to display.
+//
+// Intended for documentation screenshots and local UI smoke checks. Do not
+// use against a real network — the fixture payload is synthetic and would
+// confuse other tooling that expects live device data.
+//
+// Example:
+//
+//	dummy-speaker --port 8090 --register http://localhost:8000
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/testing/fakespeaker"
+)
+
+func main() {
+	listen := flag.String("listen", "127.0.0.1:8090", "bind address for the fake speaker's HTTP API")
+	telnetListen := flag.String("telnet-listen", "127.0.0.1:17000", "bind address for the fake speaker's telnet diagnostic shell (empty to disable)")
+	register := flag.String("register", "", "service base URL (e.g. http://localhost:8000) to self-register with via POST /setup/devices")
+	registerAs := flag.String("register-as", "", "address to send to /setup/devices (defaults to --listen)")
+
+	flag.Parse()
+
+	s, err := fakespeaker.Start(fakespeaker.Config{
+		HTTPListen:   *listen,
+		TelnetListen: *telnetListen,
+	})
+	if err != nil {
+		log.Fatalf("start fake speaker: %v", err)
+	}
+
+	log.Printf("fake speaker HTTP listening on http://%s", s.HTTPAddr())
+
+	if addr := s.TelnetAddr(); addr != "" {
+		log.Printf("fake speaker telnet listening on tcp://%s", addr)
+	}
+
+	if *register != "" {
+		target := *registerAs
+		if target == "" {
+			target = s.HTTPAddr()
+		}
+
+		if err := registerWithService(*register, target); err != nil {
+			log.Printf("self-register failed: %v (continuing anyway)", err)
+		} else {
+			log.Printf("registered %s with service at %s", target, *register)
+		}
+	}
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
+	<-sig
+
+	log.Printf("shutting down")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	if err := s.Stop(ctx); err != nil {
+		log.Printf("stop: %v", err)
+	}
+}
+
+func registerWithService(serviceURL, deviceAddr string) error {
+	body, err := json.Marshal(map[string]string{"ip": deviceAddr})
+	if err != nil {
+		return err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, serviceURL+"/setup/devices", bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return err
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode >= 300 {
+		return fmt.Errorf("service responded %s", resp.Status)
+	}
+
+	return nil
+}

cmd/mock-amazon/main.go

@@ -0,0 +1,23 @@
+// Package main provides a mock Amazon LWA server for testing purposes.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/gesellix/bose-soundtouch/pkg/testutils/amazon"
+)
+
+func main() {
+	port := flag.Int("port", 8080, "Port to listen on")
+
+	flag.Parse()
+
+	log.Printf("Starting mock Amazon LWA server on port %d", *port)
+
+	if err := http.ListenAndServe(fmt.Sprintf(":%d", *port), amazon.NewAmazonHandler()); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/soundtouch-backup/README.md

@@ -0,0 +1,212 @@
+# soundtouch-backup
+
+A standalone tool for backing up Bose SoundTouch data — both your **cloud account** (presets, devices, sources) and the **local filesystem** of each speaker — before the Bose cloud services shut down on May 6, 2026.
+
+## Overview
+
+| Subcommand | What it backs up                                                                                   |
+|------------|----------------------------------------------------------------------------------------------------|
+| `all`      | Cloud account **and** all paired speakers in one step — the recommended starting point             |
+| `cloud`    | Bose account profile, paired devices, cloud presets, music service sources                         |
+| `local`    | Speaker HTTP API data (presets, sources, volume, …) and optionally device filesystem files via SSH |
+
+Output is a single `.tar.gz` archive (or `.zip`) with a dated root directory.
+
+## Building
+
+```bash
+make build-backup
+# binary: ./build/soundtouch-backup
+```
+
+Or install alongside the other tools:
+
+```bash
+make install
+```
+
+## Usage
+
+### Combined backup (recommended)
+
+The `all` command is the simplest way to capture everything: it authenticates with the Bose cloud, backs up your account data, then reads the IP addresses from `devices.xml` and backs up each reachable speaker over HTTP.
+
+```bash
+# Interactive — prompts for email and password
+soundtouch-backup all
+
+# Non-interactive
+soundtouch-backup all --email you@example.com --password secret
+
+# Include SSH filesystem backup for each speaker
+soundtouch-backup all --ssh
+
+# Environment variables
+BOSE_EMAIL=you@example.com BOSE_PASSWORD=secret soundtouch-backup all --ssh
+```
+
+**Flags**
+
+| Flag         | Short  | Default                               | Description                                            |
+|--------------|--------|---------------------------------------|--------------------------------------------------------|
+| `--email`    | `-e`   | —                                     | Bose account email (`$BOSE_EMAIL`)                     |
+| `--password` | `--pw` | —                                     | Bose account password (`$BOSE_PASSWORD`)               |
+| `--ssh`      |        | on                                    | Also capture filesystem files via SSH for each speaker |
+| `--output`   | `-o`   | `soundtouch-backup-YYYY-MM-DD.tar.gz` | Output archive path                                    |
+| `--format`   |        | `tar.gz`                              | Archive format: `tar.gz` or `zip`                      |
+
+Speakers that are offline or unreachable at the time of backup are skipped with a `✗` warning; the cloud data is still saved.
+
+---
+
+### Cloud backup
+
+Backs up data from your Bose account at `streaming.bose.com`. Credentials are prompted interactively if not supplied as flags.
+
+```bash
+# Interactive — prompts for email, masked password input
+soundtouch-backup cloud
+
+# Non-interactive
+soundtouch-backup cloud --email you@example.com --password secret
+
+# Environment variables (avoids secrets in shell history)
+BOSE_EMAIL=you@example.com BOSE_PASSWORD=secret soundtouch-backup cloud
+
+# Zip output
+soundtouch-backup cloud --format zip --output my-bose-cloud.zip
+```
+
+**Flags**
+
+| Flag         | Short  | Default                               | Description                                       |
+|--------------|--------|---------------------------------------|---------------------------------------------------|
+| `--email`    | `-e`   | —                                     | Bose account email (`$BOSE_EMAIL`)                |
+| `--password` | `--pw` | —                                     | Bose account password (`$BOSE_PASSWORD`)          |
+| `--output`   | `-o`   | `soundtouch-backup-YYYY-MM-DD.tar.gz` | Output archive path (`$SOUNDTOUCH_BACKUP_OUTPUT`) |
+| `--format`   |        | `tar.gz`                              | Archive format: `tar.gz` or `zip`                 |
+
+**What gets fetched**
+
+| File in archive          | Source endpoint                                                                 |
+|--------------------------|---------------------------------------------------------------------------------|
+| `cloud/emailaddress.xml` | `GET /streaming/account/{id}/emailaddress`                                      |
+| `cloud/devices.xml`      | `GET /streaming/account/{id}/devices`                                           |
+| `cloud/sources.xml`      | `GET /streaming/account/{id}/sources`                                           |
+| `cloud/presets.xml`      | `GET /streaming/account/{id}/presets/all`                                       |
+| `cloud/full.xml`         | `GET /streaming/account/{id}/full` (may overlap with the above; skipped if 4xx) |
+
+---
+
+### Local backup
+
+Backs up each speaker over its HTTP API on port 8090. With `--ssh`, also captures key filesystem files via SSH.
+
+```bash
+# Auto-discover all speakers on the local network
+soundtouch-backup local
+
+# Specific speaker
+soundtouch-backup local --host 192.168.178.28
+
+# Multiple speakers
+soundtouch-backup local --host 192.168.178.28 --host 192.168.178.35
+
+# Include SSH filesystem backup
+soundtouch-backup local --ssh
+
+# Longer discovery window on busy networks
+soundtouch-backup local --discover-timeout 10s
+```
+
+**Flags**
+
+| Flag                 | Short | Default                               | Description                                      |
+|----------------------|-------|---------------------------------------|--------------------------------------------------|
+| `--host`             | `-H`  | —                                     | Speaker host/IP, repeatable (`$SOUNDTOUCH_HOST`) |
+| `--port`             | `-p`  | `8090`                                | Speaker HTTP port (`$SOUNDTOUCH_PORT`)           |
+| `--discover`         | `-d`  | auto                                  | Force mDNS/UPnP discovery                        |
+| `--discover-timeout` |       | `5s`                                  | Discovery timeout                                |
+| `--ssh`              |       | on                                    | Also capture filesystem files via SSH            |
+| `--output`           | `-o`  | `soundtouch-backup-YYYY-MM-DD.tar.gz` | Output archive path                              |
+| `--format`           |       | `tar.gz`                              | Archive format: `tar.gz` or `zip`                |
+
+**What gets fetched via HTTP**
+
+| File                | Device endpoint |
+|---------------------|-----------------|
+| `info.xml`          | `/info`         |
+| `name.xml`          | `/name`         |
+| `presets.xml`       | `/presets`      |
+| `sources.xml`       | `/sources`      |
+| `now_playing.xml`   | `/now_playing`  |
+| `volume.xml`        | `/volume`       |
+| `bass.xml`          | `/bass`         |
+| `balance.xml`       | `/balance`      |
+| `capabilities.xml`  | `/capabilities` |
+| `network_info.xml`  | `/networkInfo`  |
+| `clock_display.xml` | `/clockDisplay` |
+| `zone.xml`          | `/getZone`      |
+
+Endpoints that return HTTP 4xx (not supported on the device model) are silently skipped.
+
+**What gets fetched via SSH** (`--ssh`)
+
+SSH connects as `root@<host>:22` with an empty password, which is the default for SoundTouch firmware.
+
+Individual files:
+
+| Remote path               | Notes                                      |
+|---------------------------|--------------------------------------------|
+| `/etc/hosts`              | DNS redirect state                         |
+| `/etc/resolv.conf`        | DNS resolver configuration                 |
+| `/etc/remote_services`    | Service registration (post-migration only) |
+| `/mnt/nv/remote_services` | Alternative location for remote services   |
+
+Directories (all regular files recursively):
+
+| Remote path                      | Contents                                                                   |
+|----------------------------------|----------------------------------------------------------------------------|
+| `/opt/Bose/etc/`                 | Full Bose configuration directory, including `SoundTouchSdkPrivateCfg.xml` |
+| `/mnt/nv/BoseApp-Persistence/1/` | Persisted app state                                                        |
+
+Missing files and directories are silently skipped with a `⚠` warning.
+
+---
+
+## Archive structure
+
+Both subcommands write into a single dated archive:
+
+```
+soundtouch-backup-2026-05-02/
+├── cloud/
+│   ├── emailaddress.xml
+│   ├── devices.xml
+│   ├── sources.xml
+│   └── presets.xml
+└── local/
+    ├── A_Sound_Machine/
+    │   ├── info.xml
+    │   ├── presets.xml
+    │   ├── sources.xml
+    │   ├── volume.xml
+    │   ├── …
+    │   └── ssh/
+    │       ├── etc/
+    │       │   ├── hosts
+    │       │   └── resolv.conf
+    │       ├── opt/Bose/etc/
+    │       │   └── SoundTouchSdkPrivateCfg.xml
+    │       └── mnt/nv/BoseApp-Persistence/1/
+    └── Sound_Machinechen/
+        └── …
+```
+
+Running `cloud` and `local` separately produces two archives. To combine them, use the same `--output` path for both invocations — each adds its own subdirectory so they won't collide (`.tar.gz` does not support appending; use `--format zip` if you need a single archive from two runs, or just keep them separate).
+
+## See also
+
+- [Cloud Shutdown Survival Guide](../../docs/guides/SURVIVAL-GUIDE.md) — full migration context
+- [`soundtouch-cli`](../soundtouch-cli/) — live device control
+- [`soundtouch-service`](../soundtouch-service/) — local cloud replacement

cmd/soundtouch-backup/cmd_all.go

@@ -0,0 +1,119 @@
+package main
+
+import (
+	"encoding/xml"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/urfave/cli/v2"
+)
+
+func allCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "all",
+		Usage: "Back up cloud account then all paired speakers in one go",
+		Description: "Authenticates with the Bose cloud, backs up account data, then reads" +
+			" the device IP addresses from the cloud device list and backs up each reachable" +
+			" speaker over HTTP (and optionally SSH).",
+		Flags: append(outputFlags,
+			&cli.StringFlag{
+				Name:    "email",
+				Aliases: []string{"e"},
+				Usage:   "Bose account email",
+				EnvVars: []string{"BOSE_EMAIL"},
+			},
+			&cli.StringFlag{
+				Name:    "password",
+				Aliases: []string{"pw"},
+				Usage:   "Bose account password",
+				EnvVars: []string{"BOSE_PASSWORD"},
+			},
+			&cli.BoolFlag{
+				Name:  "ssh",
+				Usage: "Also back up device filesystem files via SSH (root@host:22, no password required)",
+				Value: true,
+			},
+		),
+		Action: runAllBackup,
+	}
+}
+
+func runAllBackup(c *cli.Context) error {
+	doSSH := c.Bool("ssh")
+	output := resolveOutputPath(c.String("output"), c.String("format"))
+	format := c.String("format")
+
+	// 1. Cloud backup
+	client, err := setupCloudClient(c.String("email"), c.String("password"))
+	if err != nil {
+		return err
+	}
+
+	root := archiveRoot()
+	files := collectCloudFiles(client, root)
+
+	if len(files) == 0 {
+		return fmt.Errorf("no cloud data fetched")
+	}
+
+	// 2. Resolve speakers from devices.xml, then back each one up
+	devicesData := files[root+"/cloud/devices.xml"]
+	if devicesData == nil {
+		printWarn("devices.xml not available — skipping local backup")
+	} else {
+		targets := parseDevicesXML(devicesData)
+		if len(targets) == 0 {
+			printWarn("no device IP addresses found in devices.xml")
+		} else {
+			fmt.Printf("Found %d device(s) in cloud account, attempting local backup...\n", len(targets))
+		}
+
+		hc := &http.Client{Timeout: 10 * time.Second}
+
+		for k, v := range collectLocalFiles(hc, targets, root, doSSH) {
+			files[k] = v
+		}
+	}
+
+	if err := writeArchive(output, format, files); err != nil {
+		return fmt.Errorf("writing archive: %w", err)
+	}
+
+	fmt.Printf("Archive written: %s (%d files)\n", output, len(files))
+
+	return nil
+}
+
+type xmlDevice struct {
+	Name      string `xml:"name"`
+	IPAddress string `xml:"ipaddress"`
+}
+
+type xmlDevices struct {
+	XMLName xml.Name    `xml:"devices"`
+	Devices []xmlDevice `xml:"device"`
+}
+
+// parseDevicesXML extracts speaker targets from a devices.xml cloud response.
+func parseDevicesXML(data []byte) []speakerTarget {
+	var d xmlDevices
+
+	if err := xml.Unmarshal(data, &d); err != nil {
+		return nil
+	}
+
+	var targets []speakerTarget
+
+	for _, dev := range d.Devices {
+		if dev.IPAddress == "" {
+			continue
+		}
+
+		// Pass name as a hint for error messages; backupSpeakerHTTP re-fetches
+		// from /info to get the current name and include info.xml in the archive.
+		targets = append(targets, speakerTarget{host: dev.IPAddress, port: 8090, name: dev.Name})
+	}
+
+	return targets
+}

cmd/soundtouch-backup/cmd_cloud.go

@@ -0,0 +1,252 @@
+package main
+
+import (
+	"bytes"
+	"encoding/xml"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"time"
+
+	"github.com/urfave/cli/v2"
+)
+
+const (
+	streamingBase  = "https://streaming.bose.com"
+	streamingCT    = "application/vnd.bose.streaming-v1.1+xml"
+	stockholmVer   = "27.0.13-4277+8963611.epdbuild.develop.hepdswbld04.2025-10-02T13:17:00"
+	nativeFrameVer = "27.0.2 -3353+4ae7c78.epdbuild.HEAD.ssgbld02.2023-10-12T15:10Z"
+	protocolVer    = "67"
+	appGUID        = "b94dedd1-a61b-492b-b86b-2bc32c9261f4"
+	appUserAgent   = "Mozilla/5.0 (Linux; Android 13; Android SDK built for arm64 Build/TE1A.220922.034; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/101.0.4951.61 Mobile Safari/537.36 Manufacturer/unknown DeviceModel/Android-SDK-built-for-arm64 SOUNDTOUCH_MOBILE_APP/" + appGUID
+)
+
+func cloudCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "cloud",
+		Usage: "Back up your Bose SoundTouch cloud account (devices, presets, sources)",
+		Flags: append(outputFlags,
+			&cli.StringFlag{
+				Name:    "email",
+				Aliases: []string{"e"},
+				Usage:   "Bose account email",
+				EnvVars: []string{"BOSE_EMAIL"},
+			},
+			&cli.StringFlag{
+				Name:    "password",
+				Aliases: []string{"pw"},
+				Usage:   "Bose account password",
+				EnvVars: []string{"BOSE_PASSWORD"},
+			},
+		),
+		Action: runCloudBackup,
+	}
+}
+
+func runCloudBackup(c *cli.Context) error {
+	output := resolveOutputPath(c.String("output"), c.String("format"))
+	format := c.String("format")
+
+	client, err := setupCloudClient(c.String("email"), c.String("password"))
+	if err != nil {
+		return err
+	}
+
+	root := archiveRoot()
+	files := collectCloudFiles(client, root)
+
+	if len(files) == 0 {
+		return fmt.Errorf("no data fetched")
+	}
+
+	if err := writeArchive(output, format, files); err != nil {
+		return fmt.Errorf("writing archive: %w", err)
+	}
+
+	fmt.Printf("Archive written: %s (%d files)\n", output, len(files))
+
+	return nil
+}
+
+// setupCloudClient prompts for missing credentials, then authenticates with the Bose cloud.
+func setupCloudClient(email, password string) (*cloudClient, error) {
+	if email == "" || password == "" {
+		var err error
+
+		email, password, err = promptCredentials(email)
+		if err != nil {
+			return nil, fmt.Errorf("credentials: %w", err)
+		}
+	}
+
+	if email == "" || password == "" {
+		return nil, fmt.Errorf("email and password are required")
+	}
+
+	fmt.Printf("Authenticating as %s...\n", email)
+
+	client, err := loginToCloud(email, password)
+	if err != nil {
+		return nil, fmt.Errorf("authentication failed: %w", err)
+	}
+
+	printOK(fmt.Sprintf("Authenticated (account ID: %s)", client.accountID))
+
+	return client, nil
+}
+
+// collectCloudFiles fetches all cloud account data and returns a files map ready for
+// archiving. Keys are prefixed with root (e.g. "soundtouch-backup-2026-05-02/cloud/").
+func collectCloudFiles(client *cloudClient, root string) map[string][]byte {
+	type cloudEndpoint struct {
+		label    string
+		filename string
+		fetch    func(*cloudClient) ([]byte, error)
+	}
+
+	endpoints := []cloudEndpoint{
+		{"email address", "emailaddress.xml", fetchEmailAddress},
+		{"devices", "devices.xml", fetchDevices},
+		{"sources", "sources.xml", fetchSources},
+		{"presets", "presets.xml", fetchPresets},
+		{"full account", "full.xml", fetchFull},
+	}
+
+	files := make(map[string][]byte)
+
+	for _, ep := range endpoints {
+		data, err := ep.fetch(client)
+		if err != nil {
+			printFail(fmt.Sprintf("%s: %v", ep.label, err))
+
+			continue
+		}
+
+		files[root+"/cloud/"+ep.filename] = data
+		printOK(fmt.Sprintf("%s (%d bytes)", ep.label, len(data)))
+	}
+
+	return files
+}
+
+type cloudClient struct {
+	http      *http.Client
+	accountID string
+	token     string
+}
+
+type loginXML struct {
+	XMLName  xml.Name `xml:"login"`
+	Username string   `xml:"username"`
+	Password string   `xml:"password"`
+}
+
+var accountIDRe = regexp.MustCompile(`<account\s+id="([^"]+)"`)
+
+func loginToCloud(email, password string) (*cloudClient, error) {
+	loginBody, err := xml.Marshal(loginXML{Username: email, Password: password})
+	if err != nil {
+		return nil, err
+	}
+
+	body := []byte(`<?xml version="1.0" encoding="UTF-8"?>`)
+	body = append(body, loginBody...)
+
+	req, err := http.NewRequest("POST", streamingBase+"/streaming/account/login", bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+
+	setStreamingHeaders(req, "")
+
+	hc := &http.Client{Timeout: 30 * time.Second}
+
+	resp, err := hc.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	token := resp.Header.Get("credentials")
+	if token == "" {
+		return nil, fmt.Errorf("no credentials in response — check your email and password")
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, 64*1024))
+	if err != nil {
+		return nil, err
+	}
+
+	m := accountIDRe.FindSubmatch(data)
+	if len(m) < 2 {
+		return nil, fmt.Errorf("could not extract account ID from login response")
+	}
+
+	return &cloudClient{http: hc, accountID: string(m[1]), token: token}, nil
+}
+
+func setStreamingHeaders(req *http.Request, token string) {
+	req.Header.Set("content-type", streamingCT)
+	req.Header.Set("accept", streamingCT)
+	req.Header.Set("clienttype", "SOUNDTOUCH_MOBILE_APP")
+	req.Header.Set("version_stockholmversion", stockholmVer)
+	req.Header.Set("version_nativeframeversion", nativeFrameVer)
+	req.Header.Set("version_protocolversion", protocolVer)
+	req.Header.Set("user-agent", appUserAgent)
+	req.Header.Set("guid", appGUID)
+	req.Header.Set("x-requested-with", "com.bose.soundtouch")
+	req.Header.Set("pragma", "no-cache")
+	req.Header.Set("cache-control", "no-cache")
+
+	if token != "" {
+		req.Header.Set("authorization", token)
+	}
+}
+
+func (c *cloudClient) get(path string) ([]byte, error) {
+	url := fmt.Sprintf("%s%s?_=%d", streamingBase, path, time.Now().UnixMilli())
+
+	req, err := http.NewRequest("GET", url, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	setStreamingHeaders(req, c.token)
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	return io.ReadAll(io.LimitReader(resp.Body, 2*1024*1024))
+}
+
+func fetchEmailAddress(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/emailaddress")
+}
+
+func fetchDevices(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/devices")
+}
+
+func fetchSources(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/sources")
+}
+
+func fetchPresets(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/presets/all")
+}
+
+func fetchFull(c *cloudClient) ([]byte, error) {
+	return c.get("/streaming/account/" + c.accountID + "/full")
+}

cmd/soundtouch-backup/cmd_local.go

@@ -0,0 +1,288 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/config"
+	"github.com/gesellix/bose-soundtouch/pkg/discovery"
+	"github.com/gesellix/bose-soundtouch/pkg/ssh"
+	"github.com/urfave/cli/v2"
+)
+
+var localEndpoints = []struct {
+	path string
+	file string
+}{
+	{"/info", "info.xml"},
+	{"/name", "name.xml"},
+	{"/presets", "presets.xml"},
+	{"/sources", "sources.xml"},
+	{"/now_playing", "now_playing.xml"},
+	{"/volume", "volume.xml"},
+	{"/bass", "bass.xml"},
+	{"/balance", "balance.xml"},
+	{"/capabilities", "capabilities.xml"},
+	{"/networkInfo", "network_info.xml"},
+	{"/clockDisplay", "clock_display.xml"},
+	{"/getZone", "zone.xml"},
+}
+
+// sshFiles lists individual device filesystem paths captured via SSH.
+// Paths that may not exist on all devices are silently skipped.
+var sshFiles = []string{
+	"/etc/hosts",
+	"/etc/resolv.conf",
+	"/etc/remote_services",
+	"/mnt/nv/remote_services",
+}
+
+// sshDirs lists device directories whose contents are recursively captured via SSH.
+var sshDirs = []string{
+	"/opt/Bose/etc",
+	"/mnt/nv/BoseApp-Persistence/1",
+}
+
+func localCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "local",
+		Usage: "Back up one or more SoundTouch speakers on your local network",
+		Flags: append(outputFlags,
+			&cli.StringSliceFlag{
+				Name:    "host",
+				Aliases: []string{"H"},
+				Usage:   "Speaker host/IP (repeatable for multiple speakers)",
+				EnvVars: []string{"SOUNDTOUCH_HOST"},
+			},
+			&cli.IntFlag{
+				Name:    "port",
+				Aliases: []string{"p"},
+				Usage:   "Speaker HTTP port",
+				Value:   8090,
+				EnvVars: []string{"SOUNDTOUCH_PORT"},
+			},
+			&cli.BoolFlag{
+				Name:    "discover",
+				Aliases: []string{"d"},
+				Usage:   "Auto-discover speakers on the local network",
+			},
+			&cli.DurationFlag{
+				Name:  "discover-timeout",
+				Usage: "Discovery timeout",
+				Value: 5 * time.Second,
+			},
+			&cli.BoolFlag{
+				Name:  "ssh",
+				Usage: "Also back up device filesystem files via SSH (root@host:22, no password required)",
+				Value: true,
+			},
+		),
+		Action: runLocalBackup,
+	}
+}
+
+type speakerTarget struct {
+	host string
+	port int
+	name string
+}
+
+func runLocalBackup(c *cli.Context) error {
+	hosts := c.StringSlice("host")
+	port := c.Int("port")
+	doDiscover := c.Bool("discover") || len(hosts) == 0
+	discoverTimeout := c.Duration("discover-timeout")
+	doSSH := c.Bool("ssh")
+	output := resolveOutputPath(c.String("output"), c.String("format"))
+	format := c.String("format")
+
+	var targets []speakerTarget
+
+	if doDiscover {
+		fmt.Printf("Discovering speakers (timeout: %s)...\n", discoverTimeout)
+
+		ctx, cancel := context.WithTimeout(c.Context, discoverTimeout)
+		defer cancel()
+
+		cfg, _ := config.LoadFromEnv()
+		svc := discovery.NewUnifiedDiscoveryService(cfg)
+
+		found, discErr := svc.DiscoverDevices(ctx)
+		if discErr != nil {
+			printWarn(fmt.Sprintf("Discovery failed: %v", discErr))
+		}
+
+		for _, d := range found {
+			targets = append(targets, speakerTarget{host: d.Host, port: d.Port, name: d.Name})
+			printOK(fmt.Sprintf("Found: %s (%s:%d)", d.Name, d.Host, d.Port))
+		}
+	}
+
+	for _, h := range hosts {
+		targets = append(targets, speakerTarget{host: h, port: port})
+	}
+
+	if len(targets) == 0 {
+		return fmt.Errorf("no speakers found — use --host <ip> or --discover")
+	}
+
+	hc := &http.Client{Timeout: 10 * time.Second}
+	root := archiveRoot()
+	files := collectLocalFiles(hc, targets, root, doSSH)
+
+	if len(files) == 0 {
+		return fmt.Errorf("no data collected")
+	}
+
+	if err := writeArchive(output, format, files); err != nil {
+		return fmt.Errorf("writing archive: %w", err)
+	}
+
+	fmt.Printf("Archive written: %s (%d files)\n", output, len(files))
+
+	return nil
+}
+
+// collectLocalFiles backs up all targets over HTTP (and optionally SSH) and returns
+// a files map ready for archiving. Keys are prefixed with root.
+func collectLocalFiles(hc *http.Client, targets []speakerTarget, root string, doSSH bool) map[string][]byte {
+	files := make(map[string][]byte)
+
+	for _, t := range targets {
+		name, entries, err := backupSpeakerHTTP(hc, t)
+		if err != nil {
+			printFail(fmt.Sprintf("%s:%d — %v", t.host, t.port, err))
+
+			continue
+		}
+
+		dir := root + "/local/" + sanitizeName(name) + "/"
+
+		for filename, data := range entries {
+			files[dir+filename] = data
+		}
+
+		printOK(fmt.Sprintf("%s: %d files via HTTP", name, len(entries)))
+
+		if doSSH {
+			sshEntries := backupSpeakerSSH(t.host, name)
+
+			for filename, data := range sshEntries {
+				files[dir+filename] = data
+			}
+
+			if len(sshEntries) > 0 {
+				printOK(fmt.Sprintf("%s: %d files via SSH", name, len(sshEntries)))
+			}
+		}
+	}
+
+	return files
+}
+
+func backupSpeakerHTTP(hc *http.Client, t speakerTarget) (name string, files map[string][]byte, err error) {
+	base := fmt.Sprintf("http://%s:%d", t.host, t.port)
+	files = make(map[string][]byte)
+	name = t.name
+	infoFetched := false
+
+	if name == "" {
+		data, ferr := fetchRaw(hc, base+"/info")
+		if ferr != nil {
+			return "", nil, fmt.Errorf("cannot reach %s: %w", base, ferr)
+		}
+
+		files["info.xml"] = data
+		infoFetched = true
+
+		if extracted := xmlFirst(data, "name"); extracted != "" {
+			name = extracted
+		} else {
+			name = t.host
+		}
+	}
+
+	for _, ep := range localEndpoints {
+		if ep.path == "/info" && infoFetched {
+			continue
+		}
+
+		data, ferr := fetchRaw(hc, base+ep.path)
+		if ferr != nil {
+			printWarn(fmt.Sprintf("%s: skipped %s (%v)", name, ep.file, ferr))
+			continue
+		}
+
+		files[ep.file] = data
+	}
+
+	return name, files, nil
+}
+
+// backupSpeakerSSH connects to the device via SSH and reads the key filesystem paths.
+// Files that don't exist on the device are silently skipped.
+// Returned map keys are relative paths within the device backup directory (e.g. "ssh/etc/hosts").
+func backupSpeakerSSH(host, deviceName string) map[string][]byte {
+	client := ssh.NewClient(host)
+	files := make(map[string][]byte)
+
+	for _, remotePath := range sshFiles {
+		data, err := client.ReadFile(remotePath)
+		if err != nil {
+			// Most missing files are expected (e.g. /etc/remote_services only exists post-migration)
+			printWarn(fmt.Sprintf("%s: SSH skipped %s (%v)", deviceName, remotePath, err))
+
+			continue
+		}
+
+		if len(data) == 0 {
+			printWarn(fmt.Sprintf("%s: SSH empty file %s", deviceName, remotePath))
+		}
+
+		files["ssh"+remotePath] = data
+	}
+
+	for _, remoteDir := range sshDirs {
+		dirFiles, err := client.ReadDir(remoteDir)
+		if err != nil {
+			printWarn(fmt.Sprintf("%s: SSH skipped dir %s (%v)", deviceName, remoteDir, err))
+			continue
+		}
+
+		for path, data := range dirFiles {
+			files["ssh"+path] = data
+		}
+	}
+
+	return files
+}
+
+func fetchRaw(hc *http.Client, url string) ([]byte, error) {
+	resp, err := hc.Get(url)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	return io.ReadAll(io.LimitReader(resp.Body, 1024*1024))
+}
+
+func xmlFirst(data []byte, field string) string {
+	re := regexp.MustCompile(`<` + regexp.QuoteMeta(field) + `[^>]*>([^<]+)</` + regexp.QuoteMeta(field) + `>`)
+
+	m := re.FindSubmatch(data)
+	if len(m) >= 2 {
+		return strings.TrimSpace(string(m[1]))
+	}
+
+	return ""
+}

cmd/soundtouch-backup/common.go

@@ -0,0 +1,172 @@
+package main
+
+import (
+	"archive/tar"
+	"archive/zip"
+	"bufio"
+	"compress/gzip"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/urfave/cli/v2"
+	"golang.org/x/term"
+)
+
+const (
+	FormatTarGz = "tar.gz"
+	FormatZip   = "zip"
+)
+
+var outputFlags = []cli.Flag{
+	&cli.StringFlag{
+		Name:    "output",
+		Aliases: []string{"o"},
+		Usage:   "Output archive file (default: soundtouch-backup-YYYY-MM-DD.tar.gz)",
+		EnvVars: []string{"SOUNDTOUCH_BACKUP_OUTPUT"},
+	},
+	&cli.StringFlag{
+		Name:  "format",
+		Usage: "Archive format: tar.gz or zip",
+		Value: FormatTarGz,
+	},
+}
+
+func resolveOutputPath(output, format string) string {
+	date := time.Now().Format("2006-01-02")
+
+	ext := ".tar.gz"
+	if format == FormatZip {
+		ext = ".zip"
+	}
+
+	filename := "soundtouch-backup-" + date + ext
+
+	if output == "" {
+		return filename
+	}
+
+	if info, err := os.Stat(output); err == nil && info.IsDir() {
+		return output + string(os.PathSeparator) + filename
+	}
+
+	return output
+}
+
+func archiveRoot() string {
+	return "soundtouch-backup-" + time.Now().Format("2006-01-02")
+}
+
+func writeArchive(outputPath, format string, files map[string][]byte) error {
+	if format == FormatZip {
+		return writeZip(outputPath, files)
+	}
+
+	return writeTarGz(outputPath, files)
+}
+
+func writeTarGz(outputPath string, files map[string][]byte) error {
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	gz := gzip.NewWriter(f)
+	defer gz.Close()
+
+	tw := tar.NewWriter(gz)
+	defer tw.Close()
+
+	now := time.Now()
+	for name, data := range files {
+		hdr := &tar.Header{
+			Name:     name,
+			Mode:     0644,
+			Size:     int64(len(data)),
+			ModTime:  now,
+			Typeflag: tar.TypeReg,
+		}
+		if err := tw.WriteHeader(hdr); err != nil {
+			return fmt.Errorf("tar header %s: %w", name, err)
+		}
+
+		if _, err := tw.Write(data); err != nil {
+			return fmt.Errorf("tar write %s: %w", name, err)
+		}
+	}
+
+	return nil
+}
+
+func writeZip(outputPath string, files map[string][]byte) error {
+	f, err := os.Create(outputPath)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	zw := zip.NewWriter(f)
+	defer zw.Close()
+
+	for name, data := range files {
+		w, err := zw.Create(name)
+		if err != nil {
+			return fmt.Errorf("zip entry %s: %w", name, err)
+		}
+
+		if _, err := w.Write(data); err != nil {
+			return fmt.Errorf("zip write %s: %w", name, err)
+		}
+	}
+
+	return nil
+}
+
+func promptCredentials(emailHint string) (email, password string, err error) {
+	r := bufio.NewReader(os.Stdin)
+
+	if emailHint != "" {
+		email = emailHint
+	} else {
+		fmt.Print("Bose account email: ")
+
+		email, err = r.ReadString('\n')
+		if err != nil {
+			return
+		}
+
+		email = strings.TrimSpace(email)
+	}
+
+	fmt.Print("Password: ")
+
+	raw, termErr := term.ReadPassword(int(os.Stdin.Fd()))
+
+	fmt.Println()
+
+	if termErr != nil {
+		err = fmt.Errorf("reading password: %w (tip: use --password flag or BOSE_PASSWORD env var)", termErr)
+		return
+	}
+
+	password = string(raw)
+
+	return
+}
+
+func sanitizeName(name string) string {
+	r := strings.NewReplacer(
+		"/", "_", "\\", "_", ":", "_",
+		"*", "_", "?", "_", "\"", "_",
+		"<", "_", ">", "_", "|", "_",
+		" ", "_",
+	)
+
+	return r.Replace(name)
+}
+
+func printOK(msg string)   { fmt.Printf("  ✓ %s\n", msg) }
+func printFail(msg string) { fmt.Printf("  ✗ %s\n", msg) }
+func printWarn(msg string) { fmt.Printf("  ⚠ %s\n", msg) }

cmd/soundtouch-backup/main.go

@@ -0,0 +1,37 @@
+// Package main implements the soundtouch-backup tool for backing up Bose SoundTouch
+// cloud account data and local speaker filesystem files.
+package main
+
+import (
+	"log"
+	"os"
+	"runtime/debug"
+
+	"github.com/urfave/cli/v2"
+)
+
+var version = "dev"
+
+func init() {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		if info.Main.Version != "" && info.Main.Version != "(devel)" {
+			version = info.Main.Version
+		}
+	}
+}
+
+func main() {
+	app := &cli.App{
+		Name:    "soundtouch-backup",
+		Usage:   "Back up Bose SoundTouch account and speaker data",
+		Version: version,
+		Commands: []*cli.Command{
+			allCommand(),
+			cloudCommand(),
+			localCommand(),
+		},
+	}
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/soundtouch-cli/cmd_clock.go

@@ -157,6 +157,33 @@ func setClockTimeNow(c *cli.Context) error {
 	return nil
 }
 
+// setClockDisplayTimezone POSTs only the timezoneInfo attribute,
+// leaving format/brightness untouched. Useful after a clock now to
+// make the speaker's logs and front-panel display tick in local time
+// instead of UTC.
+func setClockDisplayTimezone(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	tz := c.String("tz")
+
+	PrintDeviceHeader(fmt.Sprintf("Setting clock timezone to %s", tz), clientConfig.Host, clientConfig.Port)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	request := models.NewClockDisplayRequest().SetTimeZone(tz)
+	if err := client.SetClockDisplay(request); err != nil {
+		PrintError(fmt.Sprintf("Failed to set timezone: %v", err))
+		return err
+	}
+
+	PrintSuccess(fmt.Sprintf("Timezone set to %s", tz))
+
+	return nil
+}
+
 // getClockDisplay retrieves the current clock display settings
 func getClockDisplay(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)

cmd/soundtouch-cli/cmd_events.go

@@ -23,6 +23,12 @@ func eventSubscribe(c *cli.Context) error {
 	filterStr := c.String("filter")
 	filters := parseEventFilters(filterStr)
 
+	debugMode, err := parseDebugMode(c.String("debug"))
+	if err != nil {
+		PrintError(err.Error())
+		return err
+	}
+
 	// Parse duration
 	duration := c.Duration("duration")
 	verbose := c.Bool("verbose")
@@ -60,6 +66,10 @@ func eventSubscribe(c *cli.Context) error {
 	// Set up event handlers
 	setupEventHandlers(wsClient, filters, verbose)
 
+	if debugMode != debugOff {
+		installDebugHook(wsClient, debugMode)
+	}
+
 	// Connect to WebSocket
 	fmt.Println("🔌 Connecting to WebSocket...")
 
@@ -127,11 +137,78 @@ func eventSubscribe(c *cli.Context) error {
 	return nil
 }
 
+// debugMode controls when the WebSocket subscribe loop prints raw frames
+// to stderr. "off" disables debug output entirely (the production default
+// when --debug is unset).
+type debugMode int
+
+const (
+	debugOff debugMode = iota
+	debugAll
+	debugUnknown
+	debugErrors
+)
+
+func parseDebugMode(s string) (debugMode, error) {
+	switch strings.TrimSpace(s) {
+	case "":
+		return debugOff, nil
+	case "all":
+		return debugAll, nil
+	case "unknown":
+		return debugUnknown, nil
+	case "errors":
+		return debugErrors, nil
+	default:
+		return debugOff, fmt.Errorf("invalid --debug value %q (want one of: all, unknown, errors)", s)
+	}
+}
+
+// installDebugHook wires an OnRawMessage handler that prints the raw
+// frame to stderr based on the chosen mode. Stays out of stdout so
+// debug output can be filtered/grep'd independently of normal events.
+func installDebugHook(ws *client.WebSocketClient, mode debugMode) {
+	ws.OnRawMessage(func(data []byte, parseErr error) {
+		switch mode {
+		case debugAll:
+			printRawFrame(data, parseErr, "all")
+		case debugErrors:
+			if parseErr != nil {
+				printRawFrame(data, parseErr, "errors")
+			}
+		case debugUnknown:
+			// "Unknown" = parsed successfully but no known event types
+			// matched. Parse errors also qualify, since they're frames
+			// the client couldn't interpret either.
+			if parseErr != nil {
+				printRawFrame(data, parseErr, "unknown:parse-error")
+				return
+			}
+
+			ev, err := models.ParseWebSocketEvent(data)
+			if err != nil || len(ev.GetEventTypes()) == 0 {
+				printRawFrame(data, err, "unknown")
+			}
+		case debugOff:
+			// nothing
+		}
+	})
+}
+
+func printRawFrame(data []byte, parseErr error, tag string) {
+	prefix := "[ws-debug:" + tag + "]"
+	if parseErr != nil {
+		fmt.Fprintf(os.Stderr, "%s parse-error: %v\n", prefix, parseErr)
+	}
+
+	fmt.Fprintf(os.Stderr, "%s %s\n", prefix, string(data))
+}
+
 // parseEventFilters validates and parses the filter string
 func parseEventFilters(eventFilter string) map[string]bool {
 	validFilters := map[string]bool{
 		"nowPlaying": true, "volume": true, "connection": true,
-		"preset": true, "zone": true, "bass": true,
+		"preset": true, "zone": true, "group": true, "bass": true,
 		"sdkInfo": true, "userActivity": true,
 	}
 
@@ -217,6 +294,13 @@ func setupEventHandlers(wsClient *client.WebSocketClient, filters map[string]boo
 		})
 	}
 
+	// Stereo-pair (group) events — ST-10 only
+	if filters == nil || filters["group"] {
+		wsClient.OnGroupUpdated(func(event *models.GroupUpdatedEvent) {
+			handleGroupEvent(event)
+		})
+	}
+
 	// Bass events
 	if filters == nil || filters["bass"] {
 		wsClient.OnBassUpdated(func(event *models.BassUpdatedEvent) {
@@ -358,6 +442,34 @@ func handleZoneEvent(event *models.ZoneUpdatedEvent) {
 	}
 }
 
+func handleGroupEvent(event *models.GroupUpdatedEvent) {
+	group := &event.Group
+	fmt.Printf("\n🎧 Stereo-Pair Update [%s]:\n", event.DeviceID)
+
+	if group.IsEmpty() {
+		fmt.Println("  ⛓️‍💥 Pair dissolved (no group configured)")
+		return
+	}
+
+	fmt.Printf("  🆔 ID:     %s\n", group.ID)
+	fmt.Printf("  📛 Name:   %s\n", group.Name)
+	fmt.Printf("  👑 Master: %s\n", group.MasterDeviceID)
+
+	if group.Status != "" {
+		fmt.Printf("  ✅ Status: %s\n", group.Status)
+	}
+
+	for _, r := range group.Roles.Roles {
+		fmt.Printf("  %-5s     %s", r.Role, r.DeviceID)
+
+		if r.IPAddress != "" {
+			fmt.Printf(" (IP: %s)", r.IPAddress)
+		}
+
+		fmt.Println()
+	}
+}
+
 func handleBassEvent(event *models.BassUpdatedEvent) {
 	bass := &event.Bass
 	fmt.Printf("\n🎵 Bass Update [%s]:\n", event.DeviceID)

cmd/soundtouch-cli/cmd_group.go

@@ -0,0 +1,218 @@
+package main
+
+import (
+	"fmt"
+	"net"
+
+	"github.com/gesellix/bose-soundtouch/pkg/client"
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/speaker"
+	"github.com/urfave/cli/v2"
+)
+
+// getGroupStatus retrieves and prints the device's current stereo-pair state.
+func getGroupStatus(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	PrintDeviceHeader("Getting group information", clientConfig.Host, clientConfig.Port)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	group, err := client.GetGroup()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to get group: %v", err))
+		return err
+	}
+
+	if group.IsEmpty() {
+		fmt.Println("Device is not in a stereo pair")
+		return nil
+	}
+
+	printGroup(group)
+
+	return nil
+}
+
+// createGroup forms a stereo pair on the LEFT speaker, which becomes the master.
+func createGroup(c *cli.Context) error {
+	leftIP := c.String("left")
+	rightIP := c.String("right")
+	name := c.String("name")
+
+	if net.ParseIP(leftIP) == nil {
+		PrintError(fmt.Sprintf("Invalid left IP address: %s", leftIP))
+		return fmt.Errorf("invalid left IP: %s", leftIP)
+	}
+
+	if net.ParseIP(rightIP) == nil {
+		PrintError(fmt.Sprintf("Invalid right IP address: %s", rightIP))
+		return fmt.Errorf("invalid right IP: %s", rightIP)
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Creating stereo pair: LEFT=%s RIGHT=%s", leftIP, rightIP), leftIP, speaker.HTTPPort)
+
+	leftInfo, err := fetchDeviceInfo(c, leftIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read LEFT device info: %v", err))
+		return err
+	}
+
+	rightInfo, err := fetchDeviceInfo(c, rightIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read RIGHT device info: %v", err))
+		return err
+	}
+
+	if name == "" {
+		name = fmt.Sprintf("%s + %s", leftInfo.Name, rightInfo.Name)
+	}
+
+	req := &models.Group{
+		Name:           name,
+		MasterDeviceID: leftInfo.DeviceID,
+		Roles: models.GroupRoles{
+			Roles: []models.GroupRole{
+				{DeviceID: leftInfo.DeviceID, Role: "LEFT", IPAddress: leftIP},
+				{DeviceID: rightInfo.DeviceID, Role: "RIGHT", IPAddress: rightIP},
+			},
+		},
+	}
+
+	leftClient, err := clientForHost(c, leftIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client for LEFT: %v", err))
+		return err
+	}
+
+	result, err := leftClient.AddGroup(req)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create group: %v", err))
+		return err
+	}
+
+	PrintSuccess(fmt.Sprintf("Stereo pair created (id=%s)", result.ID))
+	printGroup(result)
+
+	return nil
+}
+
+// renameGroup updates the name of the existing stereo pair. The device
+// requires the full structure on every update, so we fetch the current
+// state first.
+func renameGroup(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	newName := c.String("name")
+
+	if newName == "" {
+		PrintError("--name is required")
+		return fmt.Errorf("name is required")
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Renaming stereo pair to %q", newName), clientConfig.Host, clientConfig.Port)
+
+	stClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	current, err := stClient.GetGroup()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read current group: %v", err))
+		return err
+	}
+
+	if current.IsEmpty() {
+		PrintError("Device is not in a stereo pair — nothing to rename")
+		return fmt.Errorf("no group configured")
+	}
+
+	// Status is read-only on the device side; don't echo it back.
+	current.Status = ""
+	current.Name = newName
+
+	result, err := stClient.UpdateGroup(current)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to rename group: %v", err))
+		return err
+	}
+
+	PrintSuccess(fmt.Sprintf("Stereo pair renamed to %q", result.Name))
+	printGroup(result)
+
+	return nil
+}
+
+// removeGroup tears down the device's stereo pair.
+func removeGroup(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	PrintDeviceHeader("Removing stereo pair", clientConfig.Host, clientConfig.Port)
+
+	stClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	if err := stClient.RemoveGroup(); err != nil {
+		PrintError(fmt.Sprintf("Failed to remove group: %v", err))
+		return err
+	}
+
+	PrintSuccess("Stereo pair removed")
+
+	return nil
+}
+
+// fetchDeviceInfo builds a one-off client for the given IP and reads /info.
+// Reused for both halves of a `create` invocation so the caller doesn't have
+// to babysit two host/port pairs.
+func fetchDeviceInfo(c *cli.Context, host string) (*models.DeviceInfo, error) {
+	stClient, err := clientForHost(c, host)
+	if err != nil {
+		return nil, err
+	}
+
+	return stClient.GetDeviceInfo()
+}
+
+// clientForHost mirrors CreateSoundTouchClient but overrides the host so we
+// can talk to a speaker other than the one named in --host.
+func clientForHost(c *cli.Context, host string) (*client.Client, error) {
+	cfg, err := loadConfig(c.Duration("timeout"))
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	return client.NewClient(&client.Config{
+		Host:      host,
+		Port:      speaker.HTTPPort,
+		Timeout:   cfg.HTTPTimeout,
+		UserAgent: cfg.UserAgent,
+	}), nil
+}
+
+func printGroup(g *models.Group) {
+	fmt.Println("Stereo Pair Configuration:")
+	fmt.Printf("  ID:        %s\n", g.ID)
+	fmt.Printf("  Name:      %s\n", g.Name)
+	fmt.Printf("  Master:    %s\n", g.MasterDeviceID)
+
+	if g.Status != "" {
+		fmt.Printf("  Status:    %s\n", g.Status)
+	}
+
+	for _, r := range g.Roles.Roles {
+		fmt.Printf("  %-5s     %s", r.Role, r.DeviceID)
+
+		if r.IPAddress != "" {
+			fmt.Printf(" (IP: %s)", r.IPAddress)
+		}
+
+		fmt.Println()
+	}
+}

cmd/soundtouch-cli/cmd_setup_test.go

@@ -0,0 +1,310 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
+)
+
+// captureStdout runs fn and returns whatever it wrote to os.Stdout.
+// renderSourceTable prints directly via fmt.Print* — this lets us assert
+// on its output without restructuring the renderer to take an io.Writer.
+func captureStdout(t *testing.T, fn func()) string {
+	t.Helper()
+
+	orig := os.Stdout
+
+	r, w, err := os.Pipe()
+	if err != nil {
+		t.Fatalf("pipe: %v", err)
+	}
+
+	os.Stdout = w
+
+	done := make(chan struct{})
+	buf := &bytes.Buffer{}
+
+	go func() {
+		_, _ = io.Copy(buf, r)
+		close(done)
+	}()
+
+	fn()
+	_ = w.Close()
+
+	os.Stdout = orig
+	<-done
+
+	return buf.String()
+}
+
+func TestRenderSourceTable_AlignsColumnsAndDedupsDisplayName(t *testing.T) {
+	items := []models.SourceItem{
+		// displayName != account → kept as "AUX (AUX IN)"
+		{Source: "AUX", SourceAccount: "AUX", DisplayName: "AUX IN", Status: "READY", IsLocal: true, MultiroomAllowed: true},
+		// displayName == account → dropped (would otherwise duplicate the next column)
+		{Source: "AMAZON", SourceAccount: "amzn1.account.AFKTQOUNVZL7ODQCF4STPAAMVMPA", DisplayName: "amzn1.account.AFKTQOUNVZL7ODQCF4STPAAMVMPA", Status: "READY", MultiroomAllowed: true},
+		// No displayName at all, no account
+		{Source: "BLUETOOTH", Status: "UNAVAILABLE", IsLocal: true, MultiroomAllowed: true},
+		// Long source name, no catalog entry → provider#?
+		{Source: "STORED_MUSIC_MEDIA_RENDERER", SourceAccount: "StoredMusicUserName", DisplayName: "StoredMusicUserName", Status: "UNAVAILABLE", MultiroomAllowed: true},
+	}
+
+	out := captureStdout(t, func() { renderSourceTable(items) })
+
+	lines := strings.Split(strings.TrimRight(out, "\n"), "\n")
+	if len(lines) != 4 {
+		t.Fatalf("got %d output lines, want 4:\n%s", len(lines), out)
+	}
+
+	// (1) AUX keeps "(AUX IN)" because it differs from both source and account.
+	if !strings.Contains(lines[0], "AUX (AUX IN)") {
+		t.Errorf("AUX line should keep displayName parenthesis: %q", lines[0])
+	}
+
+	// (2) AMAZON drops "(amzn1…)" because displayName equals sourceAccount.
+	if strings.Contains(lines[1], "(amzn1.account") {
+		t.Errorf("AMAZON line should drop displayName when it duplicates account: %q", lines[1])
+	}
+
+	// (3) provider#? for the uncatalogued source.
+	if !strings.Contains(lines[3], "provider#?") {
+		t.Errorf("uncatalogued source should be tagged provider#?: %q", lines[3])
+	}
+
+	// (4) Column starts must align across all rows — find the column index
+	//     where "status=" appears in each line; they should all match.
+	statusCols := make([]int, len(lines))
+	for i, l := range lines {
+		statusCols[i] = strings.Index(l, "status=")
+		if statusCols[i] < 0 {
+			t.Fatalf("line %d missing status= column: %q", i, l)
+		}
+	}
+
+	for i := 1; i < len(statusCols); i++ {
+		if statusCols[i] != statusCols[0] {
+			t.Errorf("status= column misaligned: line 0 at col %d, line %d at col %d\n%s",
+				statusCols[0], i, statusCols[i], out)
+		}
+	}
+
+	// (5) account= column should likewise align across all rows.
+	accountCols := make([]int, len(lines))
+	for i, l := range lines {
+		accountCols[i] = strings.Index(l, "account=")
+		if accountCols[i] < 0 {
+			t.Fatalf("line %d missing account= column: %q", i, l)
+		}
+	}
+
+	for i := 1; i < len(accountCols); i++ {
+		if accountCols[i] != accountCols[0] {
+			t.Errorf("account= column misaligned: line 0 at col %d, line %d at col %d\n%s",
+				accountCols[0], i, accountCols[i], out)
+		}
+	}
+}
+
+func TestRenderSourceTable_EmptyShowsNonePlaceholder(t *testing.T) {
+	out := captureStdout(t, func() { renderSourceTable(nil) })
+	if !strings.Contains(out, "(none)") {
+		t.Errorf("expected (none) placeholder for empty list, got: %q", out)
+	}
+}
+
+func TestRecommendMigrationMethod_PrefersTelnet(t *testing.T) {
+	method, reason := recommendMigrationMethod("http://aftertouch.local:8000", &setup.MigrationSummary{
+		TelnetReachable: true,
+		SSHSuccess:      true,
+	})
+
+	if method != setup.MigrationMethodTelnet {
+		t.Errorf("method = %q, want telnet (simplest path when telnet works)", method)
+	}
+
+	if !strings.Contains(reason, "Telnet") {
+		t.Errorf("reason should mention Telnet: %q", reason)
+	}
+}
+
+func TestRecommendMigrationMethod_HTTPSAddsCaveatToTelnet(t *testing.T) {
+	_, reason := recommendMigrationMethod("https://aftertouch.local:8443", &setup.MigrationSummary{
+		TelnetReachable: true,
+	})
+
+	if !strings.Contains(reason, "install-ca") {
+		t.Errorf("HTTPS service URL should flag the CA-install caveat in the reason: %q", reason)
+	}
+}
+
+func TestRecommendMigrationMethod_FallsBackToResolvWhenTelnetDown(t *testing.T) {
+	method, _ := recommendMigrationMethod("http://aftertouch.local:8000", &setup.MigrationSummary{
+		TelnetReachable: false,
+		SSHSuccess:      true,
+	})
+
+	if method != setup.MigrationMethodResolvConf {
+		t.Errorf("method = %q, want resolv (DNS redirect via SSH)", method)
+	}
+}
+
+func TestRecommendMigrationMethod_EmptyWhenNoTransport(t *testing.T) {
+	method, _ := recommendMigrationMethod("http://aftertouch.local:8000", &setup.MigrationSummary{
+		TelnetReachable: false,
+		SSHSuccess:      false,
+	})
+
+	if method != "" {
+		t.Errorf("method = %q, want empty when no transport works", method)
+	}
+}
+
+func TestBuildPlanSteps_NoOpWhenAlreadyMigratedAndPaired(t *testing.T) {
+	summary := &setup.MigrationSummary{IsMigrated: true, IsPaired: true, TelnetMigrated: true}
+	inspect := &setup.InspectReport{Info: &setup.DeviceInfoXML{DeviceID: "AABBCCDDEEFF"}}
+
+	steps := buildPlanSteps("192.168.1.42", "http://aftertouch.local:8000", "", true, false, inspect, summary)
+
+	if len(steps) != 0 {
+		t.Errorf("expected no steps for fully-set-up device, got %d:\n%v", len(steps), steps)
+	}
+}
+
+func TestBuildPlanSteps_RecommendsPairWhenMigratedButUnpaired(t *testing.T) {
+	summary := &setup.MigrationSummary{IsMigrated: true, IsPaired: false, TelnetMigrated: true, TelnetReachable: true}
+	inspect := &setup.InspectReport{Info: &setup.DeviceInfoXML{DeviceID: "AABBCCDDEEFF"}}
+
+	steps := buildPlanSteps("192.168.1.42", "http://aftertouch.local:8000", "", true, false, inspect, summary)
+
+	if len(steps) != 1 {
+		t.Fatalf("expected exactly the pair step, got %d:\n%v", len(steps), steps)
+	}
+
+	if !strings.Contains(steps[0].cmd, "setup pair") {
+		t.Errorf("expected pair command, got %q", steps[0].cmd)
+	}
+}
+
+func TestBuildPlanSteps_MigrateRebootThenPairWhenFresh(t *testing.T) {
+	summary := &setup.MigrationSummary{TelnetReachable: true, SSHSuccess: false, IsPaired: false}
+	inspect := &setup.InspectReport{Info: &setup.DeviceInfoXML{DeviceID: "AABBCCDDEEFF"}}
+
+	steps := buildPlanSteps("192.168.1.42", "http://aftertouch.local:8000", "", true, false, inspect, summary)
+
+	// migrate → reboot → pair. The reboot step exists because envswitch's
+	// parallel-persistence layer only fully wins on the next boot, and we
+	// want the new URLs locked in before pairing posts to the speaker.
+	if len(steps) != 3 {
+		t.Fatalf("expected migrate+reboot+pair, got %d steps:\n%v", len(steps), steps)
+	}
+
+	if !strings.Contains(steps[0].cmd, "setup migrate") || !strings.Contains(steps[0].cmd, "method=telnet") {
+		t.Errorf("step 1 should be telnet migrate, got %q", steps[0].cmd)
+	}
+
+	if !strings.Contains(steps[1].cmd, "setup reboot") {
+		t.Errorf("step 2 should be reboot, got %q", steps[1].cmd)
+	}
+
+	if !strings.Contains(steps[2].cmd, "setup pair") {
+		t.Errorf("step 3 should be pair, got %q", steps[2].cmd)
+	}
+}
+
+func TestBuildPlanSteps_DNSMethodPrependsCAInstall(t *testing.T) {
+	// Telnet down, SSH up, CA not yet trusted → plan must install-ca
+	// before applying the resolv migration.
+	summary := &setup.MigrationSummary{
+		TelnetReachable: false,
+		SSHSuccess:      true,
+		CACertTrusted:   false,
+		IsPaired:        false,
+	}
+	inspect := &setup.InspectReport{Info: &setup.DeviceInfoXML{DeviceID: "X"}}
+
+	steps := buildPlanSteps("192.168.1.42", "http://aftertouch.local:8000", "", false, false, inspect, summary)
+
+	if len(steps) < 2 {
+		t.Fatalf("expected at least install-ca + migrate, got %d steps:\n%v", len(steps), steps)
+	}
+
+	if !strings.Contains(steps[0].cmd, "install-ca") {
+		t.Errorf("install-ca should come first when DNS method is chosen and CA is not trusted, got %q", steps[0].cmd)
+	}
+
+	if !strings.Contains(steps[1].cmd, "method=resolv") {
+		t.Errorf("step 2 should be resolv migrate, got %q", steps[1].cmd)
+	}
+}
+
+func TestBuildPlanSteps_ResetModeIncludesManualNetworkSwitches(t *testing.T) {
+	inspect := &setup.InspectReport{
+		Info: &setup.DeviceInfoXML{DeviceID: "506583DE4803"},
+		Network: &models.NetworkInformation{
+			Interfaces: models.NetworkInterfaces{
+				Interfaces: []models.NetworkInterface{
+					{Type: "WIFI_INTERFACE", SSID: "MyHomeNetwork"},
+				},
+			},
+		},
+	}
+	summary := &setup.MigrationSummary{IsMigrated: true, IsPaired: true} // doesn't matter in reset mode
+
+	steps := buildPlanSteps("192.168.1.42", "http://aftertouch.local:8000", "", true, true, inspect, summary)
+
+	// Expected sequence in --reset mode:
+	//   factory-reset, manual AP switch, wait-ap, wifi-push, manual home switch,
+	//   wait-online, migrate, pair (8 steps).
+	if len(steps) < 7 {
+		t.Fatalf("expected at least 7 steps in --reset mode, got %d:\n%v", len(steps), steps)
+	}
+
+	manualCount := 0
+	for _, s := range steps {
+		if s.manual {
+			manualCount++
+		}
+	}
+
+	if manualCount < 2 {
+		t.Errorf("expected at least 2 manual steps for the Wi-Fi switches, got %d", manualCount)
+	}
+
+	if !strings.Contains(steps[0].cmd, "factory-reset") {
+		t.Errorf("step 1 must be factory-reset, got %q", steps[0].cmd)
+	}
+
+	// wifi-push step should default to the inspected SSID
+	foundWiFi := false
+
+	for _, s := range steps {
+		if strings.Contains(s.cmd, "wifi-push") && strings.Contains(s.cmd, "MyHomeNetwork") {
+			foundWiFi = true
+			break
+		}
+	}
+
+	if !foundWiFi {
+		t.Errorf("expected wifi-push step to default to inspected SSID 'MyHomeNetwork'")
+	}
+
+	// wait-online --match should use the deviceID suffix
+	foundMatch := false
+
+	for _, s := range steps {
+		if strings.Contains(s.cmd, "wait-online") && strings.Contains(s.cmd, "--match=DE4803") {
+			foundMatch = true
+			break
+		}
+	}
+
+	if !foundMatch {
+		t.Errorf("expected wait-online step to use --match=DE4803 from deviceID suffix")
+	}
+}

cmd/soundtouch-cli/main.go

@@ -1312,6 +1312,19 @@ func main() {
 								},
 								Before: RequireHost,
 							},
+							{
+								Name:   "timezone",
+								Usage:  "Set display timezone (IANA zone, e.g. Europe/Berlin)",
+								Action: setClockDisplayTimezone,
+								Flags: []cli.Flag{
+									&cli.StringFlag{
+										Name:     "tz",
+										Usage:    "IANA timezone identifier (e.g. Europe/Berlin, America/New_York)",
+										Required: true,
+									},
+								},
+								Before: RequireHost,
+							},
 						},
 					},
 				},
@@ -1478,6 +1491,64 @@ func main() {
 					},
 				},
 			},
+			// Stereo-pair (group) commands — ST-10 only
+			{
+				Name:    "group",
+				Aliases: []string{"g"},
+				Usage:   "ST-10 stereo-pair management (left/right channel pairing)",
+				Subcommands: []*cli.Command{
+					{
+						Name:   "status",
+						Usage:  "Show the device's current stereo-pair configuration",
+						Action: getGroupStatus,
+						Before: RequireHost,
+					},
+					{
+						Name:   "create",
+						Usage:  "Form a stereo pair (LEFT speaker becomes master)",
+						Action: createGroup,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "left",
+								Aliases:  []string{"l"},
+								Usage:    "IP address of the LEFT speaker (will be master)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "right",
+								Aliases:  []string{"r"},
+								Usage:    "IP address of the RIGHT speaker",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Pair name (defaults to \"<left> + <right>\")",
+							},
+						},
+					},
+					{
+						Name:   "rename",
+						Usage:  "Rename the existing stereo pair on the device",
+						Action: renameGroup,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "name",
+								Aliases:  []string{"n"},
+								Usage:    "New pair name",
+								Required: true,
+							},
+						},
+						Before: RequireHost,
+					},
+					{
+						Name:   "remove",
+						Usage:  "Dissolve the device's stereo pair",
+						Action: removeGroup,
+						Before: RequireHost,
+					},
+				},
+			},
 			// Advanced Audio commands
 			{
 				Name:    "audio",
@@ -2093,7 +2164,7 @@ func main() {
 							&cli.StringFlag{
 								Name:    "filter",
 								Aliases: []string{"f"},
-								Usage:   "Filter events by type (comma-separated): nowPlaying,volume,connection,preset,zone,bass,sdkInfo,userActivity",
+								Usage:   "Filter events by type (comma-separated): nowPlaying,volume,connection,preset,zone,group,bass,sdkInfo,userActivity",
 							},
 							&cli.DurationFlag{
 								Name:    "duration",
@@ -2105,6 +2176,10 @@ func main() {
 								Name:  "no-reconnect",
 								Usage: "Disable automatic reconnection on connection loss",
 							},
+							&cli.StringFlag{
+								Name:  "debug",
+								Usage: "Print raw WebSocket frames to stderr — one of: all, unknown, errors",
+							},
 							&cli.BoolFlag{
 								Name:    "verbose",
 								Aliases: []string{"v"},
@@ -2117,6 +2192,10 @@ func main() {
 		},
 	}
 
+	// Speaker provisioning (factory-reset, Wi-Fi, URL rewrite, pairing).
+	// Defined in cmd_setup.go to keep the top-level command list readable.
+	app.Commands = append(app.Commands, setupCommand())
+
 	// Sort commands alphabetically (including subcommands and flags recursively)
 	sortCommands(app.Commands)
 

cmd/soundtouch-service/main.go

@@ -19,6 +19,7 @@ import (
 	"time"
 
 	"github.com/gesellix/bose-soundtouch/pkg/discovery"
+	"github.com/gesellix/bose-soundtouch/pkg/service/amazon"
 	"github.com/gesellix/bose-soundtouch/pkg/service/certmanager"
 	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
 	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
@@ -119,6 +120,58 @@ func initializeDefaultSources(ds *datastore.DataStore) {
 	}
 }
 
+func initMusicServices(config serviceConfig, server *handlers.Server) {
+	if config.spotifyClientID != "" {
+		spotifyService := spotify.NewSpotifyService(
+			config.spotifyClientID,
+			config.spotifyClientSecret,
+			config.spotifyRedirectURI,
+			config.dataDir,
+		)
+		if config.spotifyTokenURL != "" || config.spotifyAPIBase != "" {
+			spotifyService.SetEndpoints(config.spotifyTokenURL, config.spotifyAPIBase)
+		}
+
+		if err := spotifyService.Load(); err != nil {
+			log.Printf("[Spotify] Failed to load accounts: %v", err)
+		}
+
+		server.SetSpotifyService(spotifyService)
+
+		clientIDPrefix := config.spotifyClientID
+		if len(clientIDPrefix) > 8 {
+			clientIDPrefix = clientIDPrefix[:8]
+		}
+
+		log.Printf("Spotify service initialized (client ID: %s...)", clientIDPrefix)
+	}
+
+	if config.amazonClientID != "" {
+		amazonService := amazon.NewAmazonService(
+			config.amazonClientID,
+			config.amazonClientSecret,
+			config.amazonRedirectURI,
+			config.dataDir,
+		)
+		if config.amazonTokenURL != "" || config.amazonProfileURL != "" {
+			amazonService.SetEndpoints(config.amazonTokenURL, config.amazonProfileURL)
+		}
+
+		if err := amazonService.Load(); err != nil {
+			log.Printf("[Amazon] Failed to load accounts: %v", err)
+		}
+
+		server.SetAmazonService(amazonService)
+
+		clientIDPrefix := config.amazonClientID
+		if len(clientIDPrefix) > 8 {
+			clientIDPrefix = clientIDPrefix[:8]
+		}
+
+		log.Printf("Amazon Music service initialized (client ID: %s...)", clientIDPrefix)
+	}
+}
+
 func main() {
 	updateBuildInfo()
 
@@ -187,6 +240,12 @@ func main() {
 				Value:   true,
 				EnvVars: []string{"RECORD_INTERACTIONS"},
 			},
+			&cli.BoolFlag{
+				Name:    "discovery-enabled",
+				Usage:   "Enable periodic device discovery",
+				Value:   true,
+				EnvVars: []string{"DISCOVERY_ENABLED"},
+			},
 			&cli.StringFlag{
 				Name:    "discovery-interval",
 				Usage:   "Device discovery interval",
@@ -222,8 +281,7 @@ func main() {
 			},
 			&cli.StringFlag{
 				Name:    "spotify-redirect-uri",
-				Usage:   "Spotify OAuth redirect URI",
-				Value:   "ueberboese-login://spotify",
+				Usage:   "Spotify OAuth redirect URI (defaults to <server-url>/mgmt/spotify/callback)",
 				EnvVars: []string{"SPOTIFY_REDIRECT_URI"},
 			},
 			&cli.StringFlag{
@@ -236,6 +294,31 @@ func main() {
 				Usage:   "Spotify API base URL (for testing)",
 				EnvVars: []string{"SPOTIFY_API_BASE"},
 			},
+			&cli.StringFlag{
+				Name:    "amazon-client-id",
+				Usage:   "Amazon LWA OAuth client ID",
+				EnvVars: []string{"AMAZON_CLIENT_ID"},
+			},
+			&cli.StringFlag{
+				Name:    "amazon-client-secret",
+				Usage:   "Amazon LWA OAuth client secret",
+				EnvVars: []string{"AMAZON_CLIENT_SECRET"},
+			},
+			&cli.StringFlag{
+				Name:    "amazon-redirect-uri",
+				Usage:   "Amazon LWA OAuth redirect URI (defaults to <server-url>/mgmt/amazon/callback)",
+				EnvVars: []string{"AMAZON_REDIRECT_URI"},
+			},
+			&cli.StringFlag{
+				Name:    "amazon-token-url",
+				Usage:   "Amazon LWA token URL (for testing)",
+				EnvVars: []string{"AMAZON_TOKEN_URL"},
+			},
+			&cli.StringFlag{
+				Name:    "amazon-profile-url",
+				Usage:   "Amazon LWA profile URL (for testing)",
+				EnvVars: []string{"AMAZON_PROFILE_URL"},
+			},
 			&cli.StringFlag{
 				Name:    "mgmt-username",
 				Usage:   "Management API username for HTTP Basic Auth",
@@ -310,7 +393,7 @@ func main() {
 
 			config.domains = getDomains(config.serverURL, config.httpsServerURL, hostname)
 
-			cm := initCertificateManager(config.dataDir)
+			cm := initCertificateManager(config.dataDir, config.hostname)
 			sm := setup.NewManager(config.serverURL, ds, cm)
 			sm.MgmtUsername = config.mgmtUsername
 			sm.MgmtPassword = config.mgmtPassword
@@ -318,37 +401,15 @@ func main() {
 			sm.GetDNSRunning = server.GetDNSRunning
 			server.SetHTTPServerURL(config.httpsServerURL)
 			server.SetVersionInfo(version, commit, date, repoURL)
-			server.SetDiscoverySettings(config.discoveryInterval, persisted.DiscoveryEnabled)
+			server.SetDiscoverySettings(config.discoveryInterval, config.discoveryEnabled)
 			server.SetDNSSettings(persisted.DNSEnabled, strings.Join(persisted.DNSUpstream, ","), persisted.DNSBindAddr)
 			server.SetMirrorSettings(persisted.MirrorEnabled, persisted.MirrorEndpoints, persisted.SkipMirrorEndpoints, persisted.PreferredSource)
 			server.SetInternalPaths(persisted.InternalPaths)
 			server.SetSpotifyConfig(config.spotifyClientID, config.spotifyClientSecret, config.spotifyRedirectURI)
+			server.SetAmazonConfig(config.amazonClientID, config.amazonClientSecret, config.amazonRedirectURI)
 			server.SetMgmtConfig(config.mgmtUsername, config.mgmtPassword)
 
-			if config.spotifyClientID != "" {
-				spotifyService := spotify.NewSpotifyService(
-					config.spotifyClientID,
-					config.spotifyClientSecret,
-					config.spotifyRedirectURI,
-					config.dataDir,
-				)
-				if config.spotifyTokenURL != "" || config.spotifyAPIBase != "" {
-					spotifyService.SetEndpoints(config.spotifyTokenURL, config.spotifyAPIBase)
-				}
-
-				if err := spotifyService.Load(); err != nil {
-					log.Printf("[Spotify] Failed to load accounts: %v", err)
-				}
-
-				server.SetSpotifyService(spotifyService)
-
-				clientIDPrefix := config.spotifyClientID
-				if len(clientIDPrefix) > 8 {
-					clientIDPrefix = clientIDPrefix[:8]
-				}
-
-				log.Printf("Spotify service initialized (client ID: %s...)", clientIDPrefix)
-			}
+			initMusicServices(config, server)
 
 			// Load and set initial DNS discoveries
 			dnsDiscoveries, err := ds.LoadDNSDiscoveries()
@@ -405,20 +466,25 @@ func main() {
 
 			initializeDefaultSources(ds)
 
-			tlsConfig, err := cm.GetServerTLSConfig(config.domains)
-			if err != nil {
-				log.Printf("Warning: Failed to setup TLS: %v", err)
-			}
-
 			startDeviceDiscovery(server)
 
 			r := setupRouter(server)
 
 			log.Printf("Go service starting on %s", config.serverURL)
 
-			if tlsConfig != nil {
+			// TLS cert generation can be slow on constrained hardware; run it in the
+			// background so the HTTP server is available immediately.
+			log.Printf("HTTPS setup running in background; %s will be available shortly", config.httpsServerURL)
+
+			go func() {
+				tlsConfig, err := cm.GetServerTLSConfig(config.domains)
+				if err != nil {
+					log.Printf("Warning: Failed to setup TLS: %v", err)
+					return
+				}
+
 				startHTTPSServer(config.httpsAddr, r, tlsConfig, config.httpsServerURL)
-			}
+			}()
 
 			return http.ListenAndServe(config.addr, r)
 		},
@@ -452,6 +518,7 @@ type serviceConfig struct {
 	bindAddr            string
 	addr                string
 	dataDir             string
+	hostname            string
 	serverURL           string
 	httpsServerURL      string
 	httpsAddr           string
@@ -465,6 +532,7 @@ type serviceConfig struct {
 	mirrorEndpoints     []string
 	skipMirrorEndpoints []string
 	internalPaths       []string
+	discoveryEnabled    bool
 	discoveryInterval   time.Duration
 	domains             []string
 	spotifyClientID     string
@@ -472,6 +540,11 @@ type serviceConfig struct {
 	spotifyRedirectURI  string
 	spotifyTokenURL     string
 	spotifyAPIBase      string
+	amazonClientID      string
+	amazonClientSecret  string
+	amazonRedirectURI   string
+	amazonTokenURL      string
+	amazonProfileURL    string
 	mgmtUsername        string
 	mgmtPassword        string
 	migrationEnabled    bool
@@ -524,6 +597,7 @@ func loadConfig(c *cli.Context) serviceConfig {
 	dnsUpstream := c.String("dns-upstream")
 	dnsBind := c.String("dns-bind")
 
+	discoveryEnabled := c.Bool("discovery-enabled")
 	discoveryIntervalStr := c.String("discovery-interval")
 
 	discoveryInterval, err := time.ParseDuration(discoveryIntervalStr)
@@ -538,6 +612,11 @@ func loadConfig(c *cli.Context) serviceConfig {
 	spotifyRedirectURI := c.String("spotify-redirect-uri")
 	spotifyTokenURL := c.String("spotify-token-url")
 	spotifyAPIBase := c.String("spotify-api-base")
+	amazonClientID := c.String("amazon-client-id")
+	amazonClientSecret := c.String("amazon-client-secret")
+	amazonRedirectURI := c.String("amazon-redirect-uri")
+	amazonTokenURL := c.String("amazon-token-url")
+	amazonProfileURL := c.String("amazon-profile-url")
 	mgmtUsername := c.String("mgmt-username")
 	mgmtPassword := c.String("mgmt-password")
 	mirrorEnabled := c.Bool("mirror-enabled")
@@ -553,6 +632,7 @@ func loadConfig(c *cli.Context) serviceConfig {
 		bindAddr:            bindAddr,
 		addr:                addr,
 		dataDir:             dataDir,
+		hostname:            hostname,
 		serverURL:           serverURL,
 		httpsServerURL:      httpsServerURL,
 		httpsAddr:           httpsAddr,
@@ -566,6 +646,7 @@ func loadConfig(c *cli.Context) serviceConfig {
 		mirrorEndpoints:     mirrorEndpoints,
 		skipMirrorEndpoints: skipMirrorEndpoints,
 		internalPaths:       internalPaths,
+		discoveryEnabled:    discoveryEnabled,
 		discoveryInterval:   discoveryInterval,
 		domains:             domains,
 		spotifyClientID:     spotifyClientID,
@@ -573,6 +654,11 @@ func loadConfig(c *cli.Context) serviceConfig {
 		spotifyRedirectURI:  spotifyRedirectURI,
 		spotifyTokenURL:     spotifyTokenURL,
 		spotifyAPIBase:      spotifyAPIBase,
+		amazonClientID:      amazonClientID,
+		amazonClientSecret:  amazonClientSecret,
+		amazonRedirectURI:   amazonRedirectURI,
+		amazonTokenURL:      amazonTokenURL,
+		amazonProfileURL:    amazonProfileURL,
 		mgmtUsername:        mgmtUsername,
 		mgmtPassword:        mgmtPassword,
 		migrationEnabled:    migrationEnabled,
@@ -598,6 +684,7 @@ func getDomains(serverURL, httpsServerURL, hostname string) []string {
 		"bose.io":                 true,
 		"bose-prod.apigee.net":    true,
 		"bose-test.apigee.net":    true,
+		"downloads.bose.com":      true,
 		// Local service domains
 		setup.TestDomain: true,
 		hostname:         true,
@@ -642,6 +729,7 @@ func applyPersistedSettings(ds *datastore.DataStore, config *serviceConfig) data
 		config.httpsServerURL = persisted.HTTPServerURL
 	}
 
+	config.discoveryEnabled = persisted.DiscoveryEnabled
 	if persisted.DiscoveryInterval != "" {
 		if d, durErr := time.ParseDuration(persisted.DiscoveryInterval); durErr == nil {
 			config.discoveryInterval = d
@@ -667,9 +755,40 @@ func applyPersistedSettings(ds *datastore.DataStore, config *serviceConfig) data
 	config.preferredSource = persisted.PreferredSource
 	config.internalPaths = persisted.InternalPaths
 
+	// CLI/env args take precedence; only apply persisted credentials when not set via CLI.
+	applyPersistedMusicServiceCredentials(config, persisted)
+
 	return persisted
 }
 
+// applyPersistedMusicServiceCredentials fills in music service credentials from persisted
+// settings when they have not been supplied via CLI flags or environment variables.
+func applyPersistedMusicServiceCredentials(config *serviceConfig, persisted datastore.Settings) {
+	if config.spotifyClientID == "" {
+		config.spotifyClientID = persisted.SpotifyClientID
+	}
+
+	if config.spotifyClientSecret == "" {
+		config.spotifyClientSecret = persisted.SpotifyClientSecret
+	}
+
+	if config.spotifyRedirectURI == "" {
+		config.spotifyRedirectURI = persisted.SpotifyRedirectURI
+	}
+
+	if config.amazonClientID == "" {
+		config.amazonClientID = persisted.AmazonClientID
+	}
+
+	if config.amazonClientSecret == "" {
+		config.amazonClientSecret = persisted.AmazonClientSecret
+	}
+
+	if config.amazonRedirectURI == "" {
+		config.amazonRedirectURI = persisted.AmazonRedirectURI
+	}
+}
+
 func createDefaultSettings(ds *datastore.DataStore, config serviceConfig) datastore.Settings {
 	settings := datastore.Settings{
 		ServerURL:           config.serverURL,
@@ -677,8 +796,8 @@ func createDefaultSettings(ds *datastore.DataStore, config serviceConfig) datast
 		RedactLogs:          config.redact,
 		LogBodies:           config.logBody,
 		RecordInteractions:  config.record,
+		DiscoveryEnabled:    config.discoveryEnabled,
 		DiscoveryInterval:   config.discoveryInterval.String(),
-		DiscoveryEnabled:    true,
 		DNSEnabled:          config.dnsEnabled,
 		DNSUpstream:         strings.Split(config.dnsUpstream, ","),
 		DNSBindAddr:         config.dnsBind,
@@ -707,8 +826,10 @@ func initDataStore(dataDir string) *datastore.DataStore {
 	return ds
 }
 
-func initCertificateManager(dataDir string) *certmanager.CertificateManager {
+func initCertificateManager(dataDir, hostname string) *certmanager.CertificateManager {
 	cm := certmanager.NewCertificateManager(filepath.Join(dataDir, "certs"))
+
+	cm.CommonName = hostname
 	if err := cm.EnsureCA(); err != nil {
 		log.Printf("Warning: Failed to ensure CA: %v", err)
 	}
@@ -731,22 +852,42 @@ func startDeviceDiscovery(server *handlers.Server) {
 
 func setupRouter(server *handlers.Server) *chi.Mux {
 	r := chi.NewRouter()
+
+	// TrustedRealIP must run before any handler that reads r.RemoteAddr —
+	// SnapshotMiddleware captures the request, and several handlers
+	// (HandleMargePowerOn, etc.) inspect the source IP. The middleware is
+	// gated on Settings.TrustForwardedHeaders; when off (the safe default),
+	// it returns nil and we skip Use'ing it entirely.
+	if mw := server.TrustedRealIPMiddleware(); mw != nil {
+		r.Use(mw)
+	}
+
 	r.Use(server.SnapshotMiddleware)
 	r.Use(server.OriginMiddleware)
 	r.Use(middleware.Recoverer)
+	r.Use(server.PeerObserverMiddleware)
 	r.Use(server.ShortcutMiddleware)
 	r.Use(server.MirrorMiddleware)
 	r.Use(server.RecordMiddleware)
 
 	r.Get("/", server.HandleRoot)
 	r.Get("/health", server.HandleHealth)
+	// Passive peer-reachability probe. Registers a device IP with the
+	// in-process observer, nudges :8090/swUpdateCheck, and waits for
+	// any inbound from that IP. Used post-migration where the daemon
+	// caches its swUpdateUrl at boot and the active round-trip can't
+	// reach it without a reboot.
+	r.Post("/setup/peer-probe/{deviceId}", server.HandlePeerProbe)
 	r.Get("/favicon.ico", func(w http.ResponseWriter, r *http.Request) {
 		r.URL.Path = "/media/favicon-braille.svg"
 		server.HandleMedia()(w, r)
 	})
 
 	r.Get("/media/*", server.HandleMedia())
+	r.Get("/bmx-icons/*", server.HandleBmxIcons())
+	r.Get("/ced/*", server.HandleCedStatic())
 	r.Get("/web/*", server.HandleWeb())
+	r.Post("/alexa/certificate", server.HandleAlexaCertificate)
 	r.Get("/docs/*", server.HandleDocs)
 
 	r.Route("/bmx", func(r chi.Router) {
@@ -762,9 +903,12 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 			r.Get("/v1/navigate", server.HandleTuneInNavigate)
 			r.Get("/v1/navigate/*", server.HandleTuneInNavigate)
 			r.Get("/v1/search", server.HandleTuneInSearch)
+			r.Post("/v1/favorite/{stationID}", server.HandleTuneInFavorite)
+			r.Delete("/v1/favorite/{stationID}", server.HandleTuneInDeleteFavorite)
 		})
 
 		r.Post("/orion/v1/playback/station/{data}", server.HandleOrionPlayback)
+		r.Post("/core02/svc-bmx-adapter-orion/prod/orion/token", server.HandleOrionToken)
 	})
 
 	r.Get("/custom/v1/playback/{encodedURL}", server.HandleCustomPlayback)
@@ -804,6 +948,10 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 				r.Get("/group/member", server.HandleMargeDeviceGroupMember)
 			})
 
+			r.Post("/group", server.HandleMargeAddGroup)
+			r.Post("/group/{groupId}", server.HandleMargeModifyGroup)
+			r.Delete("/group/{groupId}", server.HandleMargeDeleteGroup)
+
 			r.Delete("/device/{device}", server.HandleMargeRemoveDevice)
 		})
 
@@ -827,6 +975,7 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 		r.Route("/music", func(r chi.Router) {
 			r.Route("/musicprovider/{providerID}", func(r chi.Router) {
 				r.Post("/is_eligible", server.HandleMusicProviderIsEligible)
+				r.Post("/trial/is_eligible", server.HandleMusicProviderIsEligible)
 			})
 		})
 
@@ -846,6 +995,10 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 			r.Get("/devices/{device}/group/", server.HandleMargeDeviceGroup)
 			r.Get("/devices/{device}/group/server", server.HandleMargeDeviceGroupServer)
 			r.Get("/devices/{device}/group/member", server.HandleMargeDeviceGroupMember)
+
+			r.Post("/group", server.HandleMargeAddGroup)
+			r.Post("/group/{groupId}", server.HandleMargeModifyGroup)
+			r.Delete("/group/{groupId}", server.HandleMargeDeleteGroup)
 			r.Get("/devices/{device}/presets", server.HandleMargePresets)
 			r.Get("/devices/{device}/recents", server.HandleMargeRecents)
 
@@ -863,9 +1016,10 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 	})
 
 	r.Route("/oauth", func(r chi.Router) {
-		r.Post("/device/{deviceID}/music/musicprovider/{sourceID}/token/cs3", server.HandleBoseToken)
 		r.Post("/device/{deviceID}/music/musicprovider/{sourceID}/token", server.HandleBoseLegacyToken)
 		r.Post("/account/{account}/music/musicprovider/{sourceID}/token/cs", server.HandleBoseAccountToken)
+		r.Post("/device/{deviceID}/music/musicprovider/{sourceID}/token/cs1", server.HandleBoseToken)
+		r.Post("/device/{deviceID}/music/musicprovider/{sourceID}/token/cs3", server.HandleBoseToken)
 		r.HandleFunc("/*", server.HandleBoseProxy)
 	})
 
@@ -879,10 +1033,11 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 	})
 
 	r.Route("/mgmt", func(r chi.Router) {
-		// Browser OAuth callback — no auth required (Spotify redirects the
+		// Browser OAuth callbacks — no auth required (provider redirects the
 		// user's browser here directly). The authorization code is single-use,
 		// short-lived, and useless without the client_secret.
 		r.Get("/spotify/callback", server.HandleMgmtSpotifyCallback)
+		r.Get("/amazon/callback", server.HandleMgmtAmazonCallback)
 
 		// All other management endpoints require Basic Auth.
 		r.Group(func(r chi.Router) {
@@ -905,6 +1060,14 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 				r.Post("/prime", server.HandleMgmtPrimeDevice)
 			})
 
+			r.Route("/amazon", func(r chi.Router) {
+				r.Post("/init", server.HandleMgmtAmazonInit)
+				r.Post("/confirm", server.HandleMgmtAmazonConfirm)
+				r.Get("/accounts", server.HandleMgmtAmazonAccounts)
+				r.Get("/token", server.HandleMgmtAmazonToken)
+				r.Post("/prime", server.HandleMgmtPrimeDeviceAmazon)
+			})
+
 			r.Get("/devices/{deviceId}/events", server.HandleMgmtDeviceEvents)
 		})
 	})
@@ -924,6 +1087,8 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 		r.Post("/migrate/{deviceId}", server.HandleMigrateDevice)
 		r.Post("/revert/{deviceId}", server.HandleRevertMigration)
 		r.Post("/reboot/{deviceId}", server.HandleRebootDevice)
+		r.Get("/account-id-suggestions/{deviceId}", server.HandleAccountIDSuggestions)
+		r.Post("/pair-account/{deviceId}", server.HandlePairAccount)
 		r.Post("/trust-ca/{deviceId}", server.HandleTrustCACert)
 		r.Post("/ensure-remote-services/{deviceId}", server.HandleEnsureRemoteServices)
 		r.Post("/remove-remote-services/{deviceId}", server.HandleRemoveRemoteServices)

cmd/soundtouch-service/testdata/router_routes.txt

@@ -1,5 +1,7 @@
 CONNECT  /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
 DELETE   /accounts/{account}/devices/{device}                         handlers.(*Server).HandleMargeRemoveDevice-fm
+DELETE   /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeDeleteGroup-fm
+DELETE   /bmx/tunein/v1/favorite/{stationID}                          handlers.(*Server).HandleTuneInDeleteFavorite-fm
 DELETE   /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
 DELETE   /setup/devices/{deviceId}                                    handlers.(*Server).HandleRemoveDevice-fm
 DELETE   /setup/dns-discoveries                                       handlers.(*Server).HandleClearDNSDiscoveries-fm
@@ -7,6 +9,7 @@ DELETE   /setup/interactions/sessions                                 handlers.(
 DELETE   /setup/interactions/sessions/{session}                       handlers.(*Server).HandleDeleteSession-fm
 DELETE   /setup/parity-mismatches                                     handlers.(*Server).HandleClearParityMismatches-fm
 DELETE   /streaming/account/{account}/device/{device}/preset/{presetNumber} handlers.(*Server).HandleMargeRemovePreset-fm
+DELETE   /streaming/account/{account}/group/{groupId}                 handlers.(*Server).HandleMargeDeleteGroup-fm
 GET      /                                                            handlers.(*Server).HandleRoot-fm
 GET      /accounts/{account}/devices                                  handlers.(*Server).HandleMargeAccountDevices-fm
 GET      /accounts/{account}/devices/{device}/group                   handlers.(*Server).HandleMargeDeviceGroup-fm
@@ -17,6 +20,7 @@ GET      /accounts/{account}/devices/{device}/presets                 handlers.(
 GET      /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleMargeRecents-fm
 GET      /accounts/{account}/full                                     handlers.(*Server).HandleMargeAccountFull-fm
 GET      /accounts/{account}/sources                                  handlers.(*Server).HandleMargeAccountSources-fm
+GET      /bmx-icons/*                                                 handlers.(*Server).HandleBmxIcons
 GET      /bmx/registry/v1/services                                    handlers.(*Server).HandleBMXRegistry-fm
 GET      /bmx/registry/v1/servicesAvailability                        handlers.(*Server).HandleBMXServicesAvailability-fm
 GET      /bmx/tunein/v1/navigate                                      handlers.(*Server).HandleTuneInNavigate-fm
@@ -25,6 +29,7 @@ GET      /bmx/tunein/v1/playback/episode/{podcastID}                  handlers.(
 GET      /bmx/tunein/v1/playback/episodes/{podcastID}                 handlers.(*Server).HandleTuneInPodcastInfo-fm
 GET      /bmx/tunein/v1/playback/station/{stationID}                  handlers.(*Server).HandleTuneInPlayback-fm
 GET      /bmx/tunein/v1/search                                        handlers.(*Server).HandleTuneInSearch-fm
+GET      /ced/*                                                       handlers.(*Server).HandleCedStatic
 GET      /custom/v1/playback/{encodedURL}                             handlers.(*Server).HandleCustomPlayback-fm
 GET      /customer/account/{account}                                  handlers.(*Server).HandleMargeAccountProfile-fm
 GET      /docs/*                                                      handlers.(*Server).HandleDocs-fm
@@ -34,12 +39,16 @@ GET      /media/*                                                     handlers.(
 GET      /mgmt/accounts/                                              handlers.(*Server).HandleMgmtListAccounts-fm
 GET      /mgmt/accounts/{accountId}                                   handlers.(*Server).HandleMgmtAccountDetails-fm
 GET      /mgmt/accounts/{accountId}/speakers                          handlers.(*Server).HandleMgmtListSpeakers-fm
+GET      /mgmt/amazon/accounts                                        handlers.(*Server).HandleMgmtAmazonAccounts-fm
+GET      /mgmt/amazon/callback                                        handlers.(*Server).HandleMgmtAmazonCallback-fm
+GET      /mgmt/amazon/token                                           handlers.(*Server).HandleMgmtAmazonToken-fm
 GET      /mgmt/devices/{deviceId}/events                              handlers.(*Server).HandleMgmtDeviceEvents-fm
 GET      /mgmt/spotify/accounts                                       handlers.(*Server).HandleMgmtSpotifyAccounts-fm
 GET      /mgmt/spotify/callback                                       handlers.(*Server).HandleMgmtSpotifyCallback-fm
 GET      /mgmt/spotify/token                                          handlers.(*Server).HandleMgmtSpotifyToken-fm
 GET      /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
 GET      /proxy/*                                                     handlers.(*Server).HandleProxyRequest-fm
+GET      /setup/account-id-suggestions/{deviceId}                     handlers.(*Server).HandleAccountIDSuggestions-fm
 GET      /setup/ca.crt                                                handlers.(*Server).HandleGetCACert-fm
 GET      /setup/devices                                               handlers.(*Server).HandleListDiscoveredDevices-fm
 GET      /setup/devices/{deviceId}/events                             handlers.(*Server).HandleGetDeviceEvents-fm
@@ -84,13 +93,21 @@ PATCH    /oauth/*                                                     handlers.(
 POST     /accounts/{account}/devices                                  handlers.(*Server).HandleMargeAddDevice-fm
 POST     /accounts/{account}/devices/{device}/presets/{presetNumber}  handlers.(*Server).HandleMargeUpdatePreset-fm
 POST     /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleMargeAddRecent-fm
+POST     /accounts/{account}/group                                    handlers.(*Server).HandleMargeAddGroup-fm
+POST     /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeModifyGroup-fm
+POST     /alexa/certificate                                           handlers.(*Server).HandleAlexaCertificate-fm
+POST     /bmx/core02/svc-bmx-adapter-orion/prod/orion/token           handlers.(*Server).HandleOrionToken-fm
 POST     /bmx/orion/v1/playback/station/{data}                        handlers.(*Server).HandleOrionPlayback-fm
+POST     /bmx/tunein/v1/favorite/{stationID}                          handlers.(*Server).HandleTuneInFavorite-fm
 POST     /bmx/tunein/v1/report                                        handlers.(*Server).HandleTuneInReport-fm
 POST     /bmx/tunein/v1/token                                         handlers.(*Server).HandleTuneInToken-fm
 POST     /customer/account/{account}                                  handlers.(*Server).HandleMargeUpdateAccountProfile-fm
 POST     /customer/account/{account}/password                         handlers.(*Server).HandleMargeChangePassword-fm
 POST     /mgmt/accounts/{accountId}/language                          handlers.(*Server).HandleMgmtUpdateAccountLanguage-fm
 POST     /mgmt/accounts/{accountId}/provider-settings                 handlers.(*Server).HandleMgmtUpdateAccountProviderSetting-fm
+POST     /mgmt/amazon/confirm                                         handlers.(*Server).HandleMgmtAmazonConfirm-fm
+POST     /mgmt/amazon/init                                            handlers.(*Server).HandleMgmtAmazonInit-fm
+POST     /mgmt/amazon/prime                                           handlers.(*Server).HandleMgmtPrimeDeviceAmazon-fm
 POST     /mgmt/spotify/confirm                                        handlers.(*Server).HandleMgmtSpotifyConfirm-fm
 POST     /mgmt/spotify/entity                                         handlers.(*Server).HandleMgmtSpotifyEntity-fm
 POST     /mgmt/spotify/init                                           handlers.(*Server).HandleMgmtSpotifyInit-fm
@@ -98,12 +115,15 @@ POST     /mgmt/spotify/prime                                          handlers.(
 POST     /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
 POST     /oauth/account/{account}/music/musicprovider/{sourceID}/token/cs handlers.(*Server).HandleBoseAccountToken-fm
 POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token handlers.(*Server).HandleBoseLegacyToken-fm
+POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token/cs1 handlers.(*Server).HandleBoseToken-fm
 POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token/cs3 handlers.(*Server).HandleBoseToken-fm
 POST     /setup/backup/{deviceId}                                     handlers.(*Server).HandleBackupConfig-fm
 POST     /setup/devices                                               handlers.(*Server).HandleAddManualDevice-fm
 POST     /setup/discover                                              handlers.(*Server).HandleTriggerDiscovery-fm
 POST     /setup/ensure-remote-services/{deviceId}                     handlers.(*Server).HandleEnsureRemoteServices-fm
 POST     /setup/migrate/{deviceId}                                    handlers.(*Server).HandleMigrateDevice-fm
+POST     /setup/pair-account/{deviceId}                               handlers.(*Server).HandlePairAccount-fm
+POST     /setup/peer-probe/{deviceId}                                 handlers.(*Server).HandlePeerProbe-fm
 POST     /setup/proxy-settings                                        handlers.(*Server).HandleUpdateProxySettings-fm
 POST     /setup/reboot/{deviceId}                                     handlers.(*Server).HandleRebootDevice-fm
 POST     /setup/remove-remote-services/{deviceId}                     handlers.(*Server).HandleRemoveRemoteServices-fm
@@ -120,9 +140,12 @@ POST     /streaming/account/{account}/device/                         handlers.(
 POST     /streaming/account/{account}/device/{device}                 handlers.(*Server).HandleMargeAddDevice-fm
 POST     /streaming/account/{account}/device/{device}/presets/{presetNumber} handlers.(*Server).HandleMargeUpdatePreset-fm
 POST     /streaming/account/{account}/device/{device}/recent          handlers.(*Server).HandleMargeAddRecent-fm
+POST     /streaming/account/{account}/group                           handlers.(*Server).HandleMargeAddGroup-fm
+POST     /streaming/account/{account}/group/{groupId}                 handlers.(*Server).HandleMargeModifyGroup-fm
 POST     /streaming/account/{account}/source                          handlers.(*Server).HandleMargeAddSource-fm
 POST     /streaming/device_setting/account/{account}/device/{device}/device_settings handlers.(*Server).HandleMargeUpdateDeviceSettings-fm
 POST     /streaming/music/musicprovider/{providerID}/is_eligible      handlers.(*Server).HandleMusicProviderIsEligible-fm
+POST     /streaming/music/musicprovider/{providerID}/trial/is_eligible handlers.(*Server).HandleMusicProviderIsEligible-fm
 POST     /streaming/stats/error                                       handlers.(*Server).HandleErrorStats-fm
 POST     /streaming/stats/usage                                       handlers.(*Server).HandleUsageStats-fm
 POST     /streaming/support/customersupport                           handlers.(*Server).HandleMargeCustomerSupport-fm

cmd/soundtouch-web/main.go

@@ -4,10 +4,12 @@ package main
 import (
 	"context"
 	"embed"
-	"flag"
+	"fmt"
 	"io/fs"
 	"log"
+	"net"
 	"net/http"
+	"os"
 	"time"
 
 	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/handlers"
@@ -16,56 +18,186 @@ import (
 	"github.com/gesellix/bose-soundtouch/pkg/config"
 	"github.com/gesellix/bose-soundtouch/pkg/discovery"
 	"github.com/go-chi/chi/v5"
+	"github.com/urfave/cli/v2"
 )
 
 //go:embed static
 var staticFS embed.FS
 
-var (
-	port = flag.String("port", "8080", "Web server port")
-	_    = flag.String("host", "", "Specific SoundTouch device host (optional)")
-)
-
 func main() {
-	flag.Parse()
+	app := &cli.App{
+		Name:  "soundtouch-web",
+		Usage: "Web UI for controlling Bose SoundTouch devices",
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "port",
+				Aliases: []string{"p"},
+				Usage:   "HTTP port to listen on",
+				Value:   "8080",
+				EnvVars: []string{"PORT"},
+			},
+			&cli.StringFlag{
+				Name:    "bind",
+				Usage:   "Address for the HTTP listener: host, IP, or local interface name (e.g. eth0). Leave empty to listen on all interfaces",
+				EnvVars: []string{"BIND_ADDR"},
+			},
+			&cli.StringFlag{
+				Name:    "interface",
+				Usage:   "Network interface name (e.g. eth0) for mDNS and UPnP device discovery. Defaults to the --bind interface name when one was given; leave empty otherwise to auto-pick",
+				EnvVars: []string{"DISCOVERY_INTERFACE"},
+			},
+		},
+		Action: func(c *cli.Context) error {
+			port := c.String("port")
+			rawBind := c.String("bind")
 
-	// Create web app without templates (SPA mode)
-	app := handlers.NewWebApp()
+			bindAddr, err := resolveBindAddr(rawBind)
+			if err != nil {
+				log.Fatal(err)
+			}
 
-	// Initialize discovery service
-	cfg, err := config.LoadFromEnv()
-	if err != nil {
-		log.Printf("Failed to load config: %v, using defaults", err)
+			if rawBind != "" && bindAddr != rawBind {
+				log.Printf("Resolved --bind %q to %s", rawBind, bindAddr)
+			}
 
-		cfg = config.DefaultConfig()
+			rawIface := c.String("interface")
+
+			ifaceName := defaultDiscoveryInterface(rawIface, rawBind, bindAddr)
+			if rawIface == "" && ifaceName != "" {
+				log.Printf("Defaulting --interface to %q from --bind", ifaceName)
+			}
+
+			addr := ":" + port
+			if bindAddr != "" {
+				addr = bindAddr + ":" + port
+			}
+
+			// Create web app without templates (SPA mode)
+			webApp := handlers.NewWebApp()
+
+			// Initialize discovery service
+			cfg, err := config.LoadFromEnv()
+			if err != nil {
+				log.Printf("Failed to load config: %v, using defaults", err)
+
+				cfg = config.DefaultConfig()
+			}
+
+			cfg.DiscoveryTimeout = 10 * time.Second
+			cfg.CacheEnabled = true
+
+			if ifaceName != "" {
+				cfg.DiscoveryInterface = ifaceName
+			}
+
+			discoveryService := discovery.NewUnifiedDiscoveryService(cfg)
+
+			// Discover devices on startup
+			go func() {
+				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+				defer cancel()
+
+				webApp.BroadcastDiscoveryStatus("starting", len(webApp.Devices))
+
+				discoverDevices(ctx, webApp, discoveryService)
+
+				webApp.BroadcastDiscoveryStatus("completed", len(webApp.Devices))
+				webApp.BroadcastDeviceList()
+			}()
+
+			r := setupRoutes(webApp, discoveryService)
+
+			log.Printf("SoundTouch Web UI starting on http://%s", addr)
+
+			return http.ListenAndServe(addr, r)
+		},
 	}
 
-	cfg.DiscoveryTimeout = 10 * time.Second
-	cfg.CacheEnabled = true
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}
 
-	discoveryService := discovery.NewUnifiedDiscoveryService(cfg)
+// defaultDiscoveryInterface picks the interface name to use for mDNS/UPnP
+// discovery. An explicit --interface always wins; otherwise, when --bind was
+// given an interface name (i.e. resolveBindAddr substituted an IP for it),
+// that name is reused so the common single-interface case "just works".
+// Returns the empty string when there is nothing to propagate, leaving the
+// discovery service to auto-pick.
+func defaultDiscoveryInterface(rawInterface, rawBind, resolvedBind string) string {
+	if rawInterface != "" {
+		return rawInterface
+	}
 
-	// Discover devices on startup
-	go func() {
-		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-		defer cancel()
+	if rawBind != "" && rawBind != resolvedBind {
+		return rawBind
+	}
 
-		// Broadcast discovery start
-		app.BroadcastDiscoveryStatus("starting", len(app.Devices))
+	return ""
+}
 
-		discoverDevices(ctx, app, discoveryService)
+// resolveBindAddr returns the address to bind the HTTP listener to.
+//
+// If bindAddr names a local network interface, the interface's single IPv4
+// address is returned. When no IPv4 is present, the function falls back to the
+// interface's single non-link-local IPv6 address (wrapped in brackets so it
+// composes correctly with ":port"). Ambiguous interfaces (multiple addresses
+// in the chosen family) or interfaces with no usable address produce an error,
+// so misconfiguration surfaces immediately instead of becoming an obscure DNS
+// lookup failure at listen time.
+//
+// If bindAddr is not an interface name — including the empty string, a host
+// name, or a literal IP — it is returned unchanged.
+func resolveBindAddr(bindAddr string) (string, error) {
+	// A lookup failure here just means bindAddr isn't an interface name
+	// (it's a host, IP, or empty); fall through to pass-through.
+	iface, _ := net.InterfaceByName(bindAddr)
+	if iface == nil {
+		return bindAddr, nil
+	}
 
-		// Broadcast discovery completion and updated device list
-		app.BroadcastDiscoveryStatus("completed", len(app.Devices))
-		app.BroadcastDeviceList()
-	}()
+	addrs, err := iface.Addrs()
+	if err != nil {
+		return "", fmt.Errorf("--bind %q: failed to list addresses for interface: %w", bindAddr, err)
+	}
 
-	// Setup HTTP routes
-	r := setupRoutes(app, discoveryService)
+	var ipv4, ipv6 []net.IP
 
-	// Start web server
-	log.Printf("SoundTouch Web UI starting on http://localhost:%s", *port)
-	log.Fatal(http.ListenAndServe(":"+*port, r))
+	for _, addr := range addrs {
+		var ip net.IP
+
+		switch v := addr.(type) {
+		case *net.IPNet:
+			ip = v.IP
+		case *net.IPAddr:
+			ip = v.IP
+		}
+
+		if ip == nil {
+			continue
+		}
+
+		if v4 := ip.To4(); v4 != nil {
+			ipv4 = append(ipv4, v4)
+		} else if !ip.IsLinkLocalUnicast() {
+			// Skip IPv6 link-local (fe80::); it requires a zone ID and
+			// can't be used as a plain "[ip]:port" listen address.
+			ipv6 = append(ipv6, ip)
+		}
+	}
+
+	switch {
+	case len(ipv4) == 1:
+		return ipv4[0].String(), nil
+	case len(ipv4) > 1:
+		return "", fmt.Errorf("--bind %q: interface has multiple IPv4 addresses (%v); specify one directly", bindAddr, ipv4)
+	case len(ipv6) == 1:
+		return "[" + ipv6[0].String() + "]", nil
+	case len(ipv6) > 1:
+		return "", fmt.Errorf("--bind %q: interface has multiple IPv6 addresses (%v); specify one directly", bindAddr, ipv6)
+	default:
+		return "", fmt.Errorf("--bind %q: interface has no usable IPv4 or IPv6 address", bindAddr)
+	}
 }
 
 func setupRoutes(app *handlers.WebApp, discoveryService *discovery.UnifiedDiscoveryService) *chi.Mux {

cmd/soundtouch-web/resolve_bind_addr_test.go

@@ -0,0 +1,162 @@
+package main
+
+import (
+	"net"
+	"strings"
+	"testing"
+)
+
+func TestResolveBindAddr_PassThrough(t *testing.T) {
+	// Inputs that don't match any local interface name must be returned
+	// unchanged: empty string, hostnames, IPv4/IPv6 literals, and bogus
+	// strings the user might have typed.
+	tests := []string{
+		"",
+		"localhost",
+		"127.0.0.1",
+		"192.168.1.5",
+		"::1",
+		"definitely-not-an-iface-xyz",
+	}
+
+	for _, input := range tests {
+		t.Run(quoted(input), func(t *testing.T) {
+			got, err := resolveBindAddr(input)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			if got != input {
+				t.Errorf("got %q, want %q (input should pass through unchanged)", got, input)
+			}
+		})
+	}
+}
+
+func TestResolveBindAddr_LoopbackInterface(t *testing.T) {
+	loopback, expected, ok := findLoopbackWithSingleIPv4(t)
+	if !ok {
+		t.Skipf("no loopback interface with exactly one IPv4 address found")
+	}
+
+	got, err := resolveBindAddr(loopback)
+	if err != nil {
+		t.Fatalf("unexpected error resolving %q: %v", loopback, err)
+	}
+
+	if got != expected {
+		t.Errorf("got %q, want %q for loopback interface %q", got, expected, loopback)
+	}
+}
+
+// findLoopbackWithSingleIPv4 returns the name of a loopback interface and the
+// single IPv4 address attached to it. If the host has multiple loopback
+// interfaces or the loopback has zero or several IPv4 addresses, it returns
+// ok=false so the caller can skip the test rather than fail on an environment
+// quirk.
+func findLoopbackWithSingleIPv4(t *testing.T) (name, addr string, ok bool) {
+	t.Helper()
+
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		t.Fatalf("net.Interfaces: %v", err)
+	}
+
+	for _, iface := range ifaces {
+		if iface.Flags&net.FlagLoopback == 0 {
+			continue
+		}
+
+		addrs, addrErr := iface.Addrs()
+		if addrErr != nil {
+			continue
+		}
+
+		var ipv4s []string
+
+		for _, a := range addrs {
+			if ipnet, isIPNet := a.(*net.IPNet); isIPNet {
+				if v4 := ipnet.IP.To4(); v4 != nil {
+					ipv4s = append(ipv4s, v4.String())
+				}
+			}
+		}
+
+		if len(ipv4s) == 1 {
+			return iface.Name, ipv4s[0], true
+		}
+	}
+
+	return "", "", false
+}
+
+func TestDefaultDiscoveryInterface(t *testing.T) {
+	tests := []struct {
+		name         string
+		rawInterface string
+		rawBind      string
+		resolvedBind string
+		want         string
+	}{
+		{
+			name:         "explicit interface wins over bind-derived default",
+			rawInterface: "eth1",
+			rawBind:      "eth0",
+			resolvedBind: "192.168.1.5",
+			want:         "eth1",
+		},
+		{
+			name:         "derive from --bind when --bind was an interface name",
+			rawInterface: "",
+			rawBind:      "eth0",
+			resolvedBind: "192.168.1.5",
+			want:         "eth0",
+		},
+		{
+			name:         "no derivation when --bind was an IP literal",
+			rawInterface: "",
+			rawBind:      "192.168.1.5",
+			resolvedBind: "192.168.1.5",
+			want:         "",
+		},
+		{
+			name:         "no derivation when --bind was a hostname (pass-through)",
+			rawInterface: "",
+			rawBind:      "localhost",
+			resolvedBind: "localhost",
+			want:         "",
+		},
+		{
+			name:         "both empty stays empty (auto-pick)",
+			rawInterface: "",
+			rawBind:      "",
+			resolvedBind: "",
+			want:         "",
+		},
+		{
+			name:         "explicit interface alone, --bind empty",
+			rawInterface: "eth1",
+			rawBind:      "",
+			resolvedBind: "",
+			want:         "eth1",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := defaultDiscoveryInterface(tc.rawInterface, tc.rawBind, tc.resolvedBind)
+			if got != tc.want {
+				t.Errorf("got %q, want %q (rawInterface=%q rawBind=%q resolvedBind=%q)",
+					got, tc.want, tc.rawInterface, tc.rawBind, tc.resolvedBind)
+			}
+		})
+	}
+}
+
+func quoted(s string) string {
+	if s == "" {
+		return "(empty)"
+	}
+
+	return strings.ReplaceAll(s, "/", "_")
+}

docker-compose.ci.yml

@@ -1,6 +1,10 @@
 services:
   soundtouch-service:
-    build: .
+    build:
+      context: .
+      target: soundtouch-service
+    networks:
+      - soundtouch-test-net
     volumes:
       - ./tests/integration/testdata:/app/data
     environment:
@@ -8,3 +12,35 @@ services:
       - SPOTIFY_CLIENT_SECRET=mock-secret
       - SPOTIFY_TOKEN_URL=http://spotify-mock:8080/api/token
       - SPOTIFY_API_BASE=http://spotify-mock:8080
+      - AMAZON_CLIENT_ID=mock-amazon-id
+      - AMAZON_CLIENT_SECRET=mock-amazon-secret
+      - AMAZON_TOKEN_URL=http://amazon-mock:8080/auth/o2/token
+      - AMAZON_PROFILE_URL=http://amazon-mock:8080/user/profile
+
+  spotify-mock:
+    image: golang:1.26.3-alpine
+    container_name: spotify-mock
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: go run ./cmd/mock-spotify/main.go -port 8080
+    ports:
+      - "8081:8080"
+    networks:
+      - soundtouch-test-net
+
+  amazon-mock:
+    image: golang:1.26.3-alpine
+    container_name: amazon-mock
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: go run ./cmd/mock-amazon/main.go -port 8080
+    ports:
+      - "8082:8080"
+    networks:
+      - soundtouch-test-net
+
+networks:
+  soundtouch-test-net:
+    name: soundtouch-test-net

docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   soundtouch-service:
-    image: ghcr.io/gesellix/bose-soundtouch:latest
+    image: ghcr.io/gesellix/bose-soundtouch:${SOUNDTOUCH_VERSION:-latest}
     # build: .
     container_name: soundtouch-service
     # Linux only, required for discovery. Swarm requires host network at the task level.
@@ -8,8 +8,6 @@ services:
     ports:
       - "8000:8000"
       - "8443:8443"
-    networks:
-      - soundtouch-test-net
     environment:
       - PORT=8000
       - HTTPS_PORT=8443
@@ -37,22 +35,6 @@ services:
           cpus: '0.25'
           memory: 128M
 
-  spotify-mock:
-    image: golang:1.26.2-alpine
-    container_name: spotify-mock
-    working_dir: /app
-    volumes:
-      - .:/app
-    command: go run ./cmd/mock-spotify/main.go -port 8080
-    ports:
-      - "8081:8080"
-    networks:
-      - soundtouch-test-net
-
-networks:
-  soundtouch-test-net:
-    name: soundtouch-test-net
-
 volumes:
   soundtouch-data:
     # Named volumes are preferred in Swarm. For multi-node persistence,

docs/PARITY-SOUNDCORK.md

@@ -8,34 +8,50 @@ This document provides a comparative analysis of the current Go implementation a
 
 ## 2. Functional Comparison
 
-| Feature              | Bose-SoundTouch (Go)                             | SoundCork (Python)                                                                      |
-|:---------------------|:-------------------------------------------------|:----------------------------------------------------------------------------------------|
-| **Group Management** | Placeholder handlers (return `<group/>` or 404). | Active group management (`groups.py`), supporting `/addGroup` and stereo pairing logic. |
-| **BMX Services**     | Supports TuneIn, Orion, and custom streams.      | More modular `bmx_services.json` registry with broader mock support.                    |
-| **Persistence**      | Mixed JSON/XML datastore.                        | Pure XML-based persistence per device/account.                                          |
-| **Admin UI**         | CLI-based (`soundtouch-cli`) or API-driven.      | Draft Web UI for device discovery and account management (`admin.py`).                  |
-| **Discovery**        | Integrated setup tools and SSDP/MDNS awareness.  | Leverages `bosesoundtouchapi` Python library for active discovery.                      |
+| Feature              | Bose-SoundTouch (Go)                                                                                                  | SoundCork (Python)                                                                      |
+|:---------------------|:----------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------|
+| **Group Management** | Full CRUD: `POST /group`, `POST /group/{id}`, `DELETE /group/{id}` with XML datastore persistence (`Group_{id}.xml`). | Active group management (`groups.py`), supporting `/addGroup` and stereo pairing logic. |
+| **ZeroConf Priming** | Full DH key exchange + encrypted blob; fallback to `tokenType=accesstoken` for older firmware.                        | Simple `tokenType=accesstoken` push only; token expires after ~60 minutes.              |
+| **BMX Services**     | Supports TuneIn, Orion, and custom streams.                                                                           | More modular `bmx_services.json` registry with broader mock support.                    |
+| **Persistence**      | Mixed JSON/XML datastore.                                                                                             | Pure XML-based persistence per device/account.                                          |
+| **Admin UI**         | CLI-based (`soundtouch-cli`) or API-driven.                                                                           | Draft Web UI for device discovery and account management (`admin.py`).                  |
+| **Discovery**        | Integrated setup tools and SSDP/MDNS awareness.                                                                       | Leverages `bosesoundtouchapi` Python library for active discovery.                      |
 
 ## 3. Key Strengths of SoundCork
 - **Group Pairing Logic**: Includes logic to manage master/slave relationships for SoundTouch 10 stereo pairs.
 - **Service Extensibility**: JSON-based registry for BMX services makes it easier to mock multiple providers (SiriusXM, Spotify) without code changes.
-- **Mock Coverage**: Better coverage of "dummy" endpoints that respond with plausible XML (e.g., `customerSupport`).
+- ~~**Mock Coverage**: Better coverage of "dummy" endpoints that respond with plausible XML (e.g., `customerSupport`).~~ **Addressed**: AfterTouch's `HandleNotFound` (registered via `r.NotFound`) logs every unimplemented endpoint as `[UNHANDLED]` and forwards the request to the Bose upstream via `HandleBoseProxy`. This provides at least the same coverage as static dummy responses, while also aiding discovery of new endpoints.
 
 ## 4. Suggested Implementation Steps for Bose-SoundTouch
 
-### A. Implement Full Group Support (High Priority)
-- Add logic to `pkg/service/marge` to handle `/addGroup` and `/updateGroup`.
-- Persist group memberships in the datastore to allow speakers to function as stereo pairs or multi-room zones.
+### ✅ A. Implement Full Group Support (Completed)
+- `POST /group`, `POST /group/{id}`, `DELETE /group/{id}` implemented in `pkg/service/handlers/handlers_marge.go`.
+- Group CRUD persisted in XML datastore (`Group_{id}.xml`) via `pkg/service/datastore/datastore.go`.
+- `GET /group` on device registration reads the group the device belongs to.
 
-### B. Modularize BMX Registry (Medium Priority)
+### ✅ B. Proper ZeroConf Spotify Blob (Completed)
+- Full Spotify Connect ZeroConf protocol implemented in `pkg/service/spotify/zeroconf.go`.
+- Flow: `getInfo` (fetch speaker DH public key) → 768-bit DH key exchange → AES-128-CTR encrypted `LoginCredentials` protobuf blob → `addUser`.
+- Speaker can self-refresh credentials independently; no periodic re-priming needed for token expiry.
+- Automatic fallback to `tokenType=accesstoken` if `getInfo` fails (older firmware without DH support).
+- See `docs/concepts/spotify-priming-strategy.md` for full protocol details.
+- **Remaining gap**: Background watchdog to re-prime devices that lose their session (reboot / power loss). Not required for token expiry on modern firmware; only needed for the "speaker rebooted and lost state" recovery path and for older firmware on the fallback path (~45 min token expiry).
+
+### C. Modularize BMX Registry (Medium Priority)
 - Extract the hardcoded service list in `HandleBMXRegistry` into an external `bmx-services.json` file.
 - Allow users to customize which mocked services are advertised to the speaker.
 
-### C. Enhanced Source Management (Medium Priority)
+### D. Enhanced Source Management (Medium Priority)
 - Refine source learning logic to ensure all `sourceAccount` and `sourceName` metadata is correctly captured during synchronization, using patterns from `soundcork`'s `learnSource`.
 
-### D. Basic Admin Web UI (Low Priority)
+### E. Basic Admin Web UI (Low Priority)
 - Develop a minimal internal status page to list active accounts and connected devices, improving usability over raw API calls.
 
 ## 5. Summary
-While our Go implementation is structurally more consistent with recent reference recordings (e.g., `buttonNumber`, detailed `components`), SoundCork provides better coverage of multi-device coordination (Groups) and service emulation (BMX) that we should adopt for a more complete offline experience.
+
+Group support and ZeroConf Spotify priming are now feature-complete in AfterTouch. The Go implementation is structurally more consistent with recent reference recordings (e.g., `buttonNumber`, detailed `components`). SoundCork's remaining functional advantages are:
+
+- **BMX service extensibility**: the `bmx_services.json` registry makes it trivial to add or mock new streaming providers without code changes (step C above).
+- **Group pairing logic**: master/slave relationship management for SoundTouch 10 stereo pairs goes beyond the CRUD AfterTouch implements.
+
+For the broader ecosystem context (feature matrix across all community projects, AfterTouch open tasks, and cross-project observations) see [docs/analysis/bose-soundtouch-community-tools.md](analysis/bose-soundtouch-community-tools.md).

docs/README.md

@@ -10,6 +10,7 @@ Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive
 
 ### For Existing Users
 - **[Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)** - Prepare for the May 2026 shutdown
+- **[Backup Tool](../cmd/soundtouch-backup/README.md)** - Back up your cloud account and speaker data before shutdown
 - **[SoundTouch Service Guide](guides/SOUNDTOUCH-SERVICE.md)** - Advanced service configuration
 
 ## 📋 Essential Documentation
@@ -40,6 +41,7 @@ The documentation is organized into three main categories:
 ### Advanced Features
 - [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md) - Device identification
 - [CLI Reference](guides/CLI-REFERENCE.md) - Command-line tools
+- [Backup Tool](../cmd/soundtouch-backup/README.md) - Cloud account and speaker data backup
 - [IoT Implementation Guide](guides/IOT-IMPLEMENTATION-GUIDE.md) - IoT integrations
 - [MQTT Integration Design](guides/MQTT-INTEGRATION-DESIGN.md) - MQTT setup
 

docs/SUMMARY.md

@@ -4,11 +4,16 @@
 
 ## User Guides
 * [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
+* [Self-Hosting AfterTouch](guides/SELF-HOSTING.md)
+* [Connecting Music Services](guides/MUSIC-SERVICES.md)
 * [Migration & Safety Guide](guides/MIGRATION-SAFETY.md)
 * [CLI Reference](guides/CLI-REFERENCE.md)
+* [Backup Tool](../cmd/soundtouch-backup/README.md)
 * [Getting Started](guides/GETTING-STARTED.md)
 * [SoundTouch Service](guides/SOUNDTOUCH-SERVICE.md)
 * [Initial Device Setup](guides/DEVICE-INITIAL-SETUP.md)
+* [Capture Device Pairing Traffic](guides/CAPTURE-DEVICE-PAIRING.md)
+* [Capture Migration Traffic](guides/CAPTURE-MIGRATION-TRAFFIC.md)
 * [Device Setup Flow](DEVICE-SETUP.md)
 * [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md)
 * [HTTPS Setup](guides/HTTPS-SETUP.md)
@@ -34,6 +39,7 @@
 * [System Endpoints](reference/SYSTEM-ENDPOINTS.md)
 * [Speaker Endpoint](reference/SPEAKER-ENDPOINT.md)
 * [WebSocket Events](reference/WEBSOCKET-EVENTS.md)
+* [Device Pairing Flow](reference/DEVICE-PAIRING-FLOW.md)
 * [Discovery](reference/DISCOVERY.md)
 * [Zone Management](reference/ZONE-MANAGEMENT.md)
 * [Preset Management](reference/PRESET-MANAGEMENT.md)
@@ -55,12 +61,17 @@
 * [Upstream URLs](analysis/UPSTREAM-URLS.md)
 * [Anonymization Summary](analysis/ANONYMIZATION-SUMMARY.md)
 * [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md)
+* [Telnet (Port 17000) Migration Method](analysis/TELNET-MIGRATION-METHOD.md)
+* [Telnet Command Reference](analysis/TELNET-COMMAND-REFERENCE.md)
+* [Setup WebSocket Experiment](analysis/SETUP-WEBSOCKET-EXPERIMENT.md)
+* [Factory Reset Protocol](analysis/FACTORY-RESET-PROTOCOL.md)
 * [Wiki API Comparison](analysis/WIKI-COMPARISON.md)
 * [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md)
 * [IoT Configuration Analysis](analysis/IOT-CONFIGURATION-ANALYSIS.md)
 * [Bose Lab Runbook](analysis/BOSE-LAB-RUNBOOK.md)
 * [Missing Routes Spotify](analysis/MISSING-ROUTES-SPOTIFY.md)
 * [Bose App ADB Emulator](analysis/BOSE-APP-ADB-Emulator.md)
+* [Community Tools](analysis/bose-soundtouch-community-tools.md)
 
 ## Parity Analysis
 * [Parity Improvements](PARITY-IMPROVEMENTS.md)

docs/analysis/BOSE-APP-ADB-Emulator.md

@@ -2,6 +2,21 @@
 
 Intercept HTTPS/WebSocket traffic from the Bose SoundTouch Android app using an Android emulator, mitmproxy, and Frida. Tested on Apple Silicon (ARM64) Mac.
 
+## Automated Setup
+
+The steps in this document are scripted for reproducibility:
+
+```bash
+scripts/android/setup-mitm-avd.sh   # one-time: create AVD, install cert & APK, save snapshot
+scripts/android/start-mitm-session.sh  # per-session: restore snapshot, refresh proxy, start frida-server
+```
+
+Read on for the full manual walkthrough and the rationale behind each step.
+
+> **Note:** The manual steps below use `/tmp/` for intermediate files and reflect the original approach. The automated scripts supersede them — use the scripts for day-to-day use and refer here only to understand how things work.
+
+---
+
 ## Prerequisites
 
 - Android Studio installed (for SDK tools and emulator)
@@ -9,6 +24,10 @@ Intercept HTTPS/WebSocket traffic from the Bose SoundTouch Android app using an
 - mitmproxy installed (`pip install mitmproxy` or via your preferred method)
 - The Bose SoundTouch APK (extracted from a real device, see below)
 
+> **BLE limitation**: Android emulators do not expose Bluetooth hardware. The Bose app's default setup path (BLE Wi-Fi provisioning) therefore cannot be used to configure a factory-reset speaker from the emulator. Use **AP mode** instead: provision the speaker's Wi-Fi credentials via the Mac command line first (see [DEVICE-INITIAL-SETUP.md § 6](../guides/DEVICE-INITIAL-SETUP.md)), then the app can discover the already-networked speaker via mDNS/SSDP without BLE.
+
+> **Emulator ↔ local network**: The emulator routes all traffic through the Mac's active network interface. Once the speaker is on the same LAN as the Mac, the emulator can reach it at its normal LAN IP (e.g. `192.168.1.50`) — no extra routing is needed. Use `adb shell ping 192.168.1.50` to confirm reachability.
+
 Add Android SDK tools to your PATH (add to `~/.zshrc`):
 
 ```bash
@@ -89,7 +108,8 @@ adb -s emulator-5554 install bose.apk
 
 ```bash
 # Start mitmproxy (generates CA cert on first run)
-mitmweb --port 8080 --mode regular -w bose_traffic.mitm
+# Use the native macOS app — Docker mitmproxy does not work (NAT blocks emulator traffic)
+mitmweb --listen-port 8080 --mode regular -w bose_traffic.mitm
 ```
 
 Extract the CA certificate (without private key):
@@ -214,16 +234,19 @@ grep -A3 "CERT_PEM" /tmp/config.js | head -5
 Make sure mitmweb is running, then:
 
 ```bash
-/tmp/frida-venv/bin/frida \
+scripts/android/frida-venv/bin/frida \
   -U \
   -f com.bose.soundtouch \
-  -l /tmp/config.js \
-  -l /tmp/android-system-certificate-injection.js \
-  -l /tmp/android-proxy-override.js \
-  -l /tmp/android-certificate-unpinning.js \
-  -l /tmp/android-certificate-unpinning-fallback.js
+  -l scripts/android/frida/config.js \
+  -l scripts/android/frida/native-connect-hook.js \
+  -l scripts/android/frida/android/android-system-certificate-injection.js \
+  -l scripts/android/frida/android/android-proxy-override.js \
+  -l scripts/android/frida/android/android-certificate-unpinning.js \
+  -l scripts/android/frida/android/android-certificate-unpinning-fallback.js
 ```
 
+> `native-connect-hook.js` is required — the Bose app uses native networking that bypasses Java proxy settings.
+
 Expected output in the Frida REPL:
 
 ```

docs/analysis/DEVICE-REDIRECT-METHODS.md

@@ -2,6 +2,8 @@
 
 To enable offline operation or use custom services like **SoundCork** or **ÜberBöse API**, SoundTouch devices must be redirected from Bose's official cloud endpoints to a local or custom server. This document outlines the three known methods to achieve this, gathered from community reverse-engineering efforts in the **SoundCork** and **ÜberBöse API** projects.
 
+> A fourth, **SSH-free** path — driving the device's diagnostic shell on TCP port 17000 — is being added as a peer to the XML and DNS methods. See **[TELNET-MIGRATION-METHOD.md](TELNET-MIGRATION-METHOD.md)** for the use cases, community findings, and feasibility analysis. The `/etc/hosts` method documented below is now deprecated and will not be exposed in the web UI.
+
 ## Overview of Redirection Targets
 
 SoundTouch devices primarily communicate with the following domains:
@@ -32,19 +34,25 @@ The most robust and granular method involves modifying the device's private conf
 Requires SSH access to the device.
 ```xml
 <SoundTouchSdkPrivateCfg>
-  <margeServerUrl>http://192.168.1.10:8000/marge</margeServerUrl>
+  <margeServerUrl>http://192.168.1.10:8000</margeServerUrl>
   <statsServerUrl>http://192.168.1.10:8000</statsServerUrl>
   <swUpdateUrl>http://192.168.1.10:8000/updates/soundtouch</swUpdateUrl>
   <bmxRegistryUrl>http://192.168.1.10:8000/bmx/registry/v1/services</bmxRegistryUrl>
 </SoundTouchSdkPrivateCfg>
 ```
 
+> **Note on `margeServerUrl`** — `soundtouch-service` mounts the marge endpoints
+> at the **root** of port 8000, so the URL has no `/marge` suffix.
+> [`deborahgu/soundcork`](https://github.com/deborahgu/soundcork) routes marge
+> under a `/marge` sub-path, so users redirecting to soundcork must append it
+> (`http://192.168.1.10:8000/marge`).
+
 ### Pros & Cons
-| Pros | Cons |
-| :--- | :--- |
-| **Granular Control**: Redirect specific services while leaving others (e.g., updates) intact. | **Requires SSH**: Must have root/SSH access to the device. |
-| **Persistent**: Survives software updates (usually). | **Syntax Sensitive**: Errors in XML can cause boot issues or service failures. |
-| **Native**: Uses the device's built-in configuration mechanism. | |
+| Pros                                                                                          | Cons                                                                           |
+|:----------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------|
+| **Granular Control**: Redirect specific services while leaving others (e.g., updates) intact. | **Requires SSH**: Must have root/SSH access to the device.                     |
+| **Persistent**: Survives software updates (usually).                                          | **Syntax Sensitive**: Errors in XML can cause boot issues or service failures. |
+| **Native**: Uses the device's built-in configuration mechanism.                               |                                                                                |
 
 ---
 
@@ -66,11 +74,11 @@ Requires SSH access. Add entries for the target domains:
 ```
 
 ### Pros & Cons
-| Pros | Cons |
-| :--- | :--- |
-| **Simple**: Easy to understand and implement. | **Requires SSH**: Must have root access. |
+| Pros                                                                                  | Cons                                                                                                                                                                |
+|:--------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Simple**: Easy to understand and implement.                                         | **Requires SSH**: Must have root access.                                                                                                                            |
 | **Universal**: Affects all processes on the device attempting to reach those domains. | **HTTPS Issues**: Redirecting HTTPS domains to a local IP will cause SSL certificate errors unless the device is patched to skip verification or trust a custom CA. |
-| | **Brittle**: Some firmware versions may overwrite `/etc/hosts` on reboot. |
+|                                                                                       | **Brittle**: Some firmware versions may overwrite `/etc/hosts` on reboot.                                                                                           |
 
 ---
 
@@ -104,12 +112,12 @@ sed "s#\^https:....bose.\+apigee..net..#http[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 4. Restore execution permissions and reboot.
 
 ### Pros & Cons
-| Pros | Cons |
-| :--- | :--- |
-| **Bypass Config**: Works even if the firmware ignores XML settings. | **High Risk**: Modifying binaries can lead to permanent bricks or boot loops. |
+| Pros                                                                                | Cons                                                                                  |
+|:------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------|
+| **Bypass Config**: Works even if the firmware ignores XML settings.                 | **High Risk**: Modifying binaries can lead to permanent bricks or boot loops.         |
 | **Hardcoded Redirects**: Can catch URLs that aren't exposed in configuration files. | **Length Constraint**: Custom URLs must fit within the space of the original strings. |
-| | **Firmware Specific**: Patches must be reapplied after every software update. |
-| | **Complexity**: Requires understanding of binary structures and potential checksums. |
+|                                                                                     | **Firmware Specific**: Patches must be reapplied after every software update.         |
+|                                                                                     | **Complexity**: Requires understanding of binary structures and potential checksums.  |
 
 ---
 
@@ -117,11 +125,11 @@ sed "s#\^https:....bose.\+apigee..net..#http[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 
 ### Summary Table
 
-| Method | Primary Use Case | Ease | Safety | Persistence | Granularity |
-| :--- | :--- | :---: | :---: | :---: | :---: |
-| **XML Config** | Logical service redirection | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
-| **`/etc/hosts`** | Quick global DNS override | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
-| **Binary Patch** | Bypassing hardcoded checks | ⭐ | ⭐ | ⭐ | ⭐⭐⭐ |
+| Method           | Primary Use Case            | Ease  | Safety | Persistence | Granularity |
+|:-----------------|:----------------------------|:-----:|:------:|:-----------:|:-----------:|
+| **XML Config**   | Logical service redirection | ⭐⭐⭐⭐  |  ⭐⭐⭐⭐  |    ⭐⭐⭐⭐     |    ⭐⭐⭐⭐⭐    |
+| **`/etc/hosts`** | Quick global DNS override   | ⭐⭐⭐⭐⭐ |  ⭐⭐⭐   |     ⭐⭐      |     ⭐⭐      |
+| **Binary Patch** | Bypassing hardcoded checks  |   ⭐   |   ⭐    |      ⭐      |     ⭐⭐⭐     |
 
 ---
 
@@ -176,9 +184,10 @@ As suggested by community members, you can configure the device to trust your ow
     - **Method B (Symlinks)**: Add the certificate to `/etc/ssl/certs/` and create a hash symlink using `c_rehash` (if available) or manual mapping.
 
 **Pros & Cons**:
-| Pros | Cons |
-| :--- | :--- |
-| **Secure**: Maintains end-to-end encryption. | **Requires SSH**: Must have root access to modify the trust store. |
+
+| Pros                                                   | Cons                                                                   |
+|:-------------------------------------------------------|:-----------------------------------------------------------------------|
+| **Secure**: Maintains end-to-end encryption.           | **Requires SSH**: Must have root access to modify the trust store.     |
 | **Clean**: No binary patching required for SSL bypass. | **Update Risk**: Firmware updates might overwrite the `ca-bundle.crt`. |
 
 ### Option 2: SSL Verification Bypass

docs/analysis/FACTORY-RESET-PROTOCOL.md

@@ -0,0 +1,136 @@
+# What a SoundTouch speaker does during factory reset
+
+Observed live on ST10 firmware `27.0.6.46330.5043500` (build `epdbuild.trunk.hepdswbld04.2022-08-04`) on 2026-05-12, by running `soundtouch-cli setup factory-reset` and tailing the speaker's `logread` over SSH. The trace is preserved at `_/logs/factory-reset.txt` for reference.
+
+## Sequence
+
+1. **Telnet receives `sys factorydefault`.** The diagnostic shell on port 17000 accepts the command and acknowledges. Some firmwares close the socket as part of the reboot — our CLI's `setup factory-reset` tolerates that as success.
+
+2. **Speaker DELETEs itself from its marge account.** Before wiping anything, the firmware does:
+   ```
+   [MargeStateAssociated] HandleRemoveDeviceRequest - Removing this device from the user's Marge account
+   [MargeClient]          RemoveDevice calling Marge Server with https://streaming.bose.com/streaming/account/{accountId}/device/{deviceId}
+   [MargeClient]          RemoveDeviceCB - Device removed from the user's Marge account
+   [MargeStateAssociated] HandleRemoveDeviceRequestSuccessCB, Marge returned: {"ok": true}
+   ```
+   AfterTouch already handles this — `HandleMargeRemoveDevice` (`pkg/service/handlers/handlers_marge.go:633`) routed via `r.Delete("/device/{device}", …)` in `cmd/soundtouch-service/main.go:955`. The handler calls `marge.RemoveDeviceFromAccount(s.ds, account, device)` and prunes the device from the datastore.
+
+3. **Speaker notifies its LAN peers.** Two HTTP POSTs to each known peer at `:8090/notification`:
+   ```
+   [NotificationSender] SendNotifyLisas_: URL: >>http://192.168.123.122:8090/notification<<, m_msgdata.size(58)
+   [SimpleURLFetcher]   multipart/form-data text/xml
+   ```
+   ~58 bytes of `multipart/form-data` carrying `text/xml`. "Lisas" is the firmware's internal term for LAN peers (devices on the same account on the same network segment). AfterTouch is **not** on this path — it's pure peer-to-peer over the LAN. Peers presumably refresh their account info as a result.
+
+4. **Local state teardown.** Bluetooth pairings cleared (`BTRemoteDeviceAccess::ClearPrevPairedList`), zone/group state torn down, all source proxies disconnected (`STSAccountProxy::Disconnect Requested` × many).
+
+5. **Persistence cleanup.** Logs, core dumps wiped (`FactoryDefault: Clearing the CoreDump and BoseLogs … rm -rf /mnt/nv/BoseLog/*`). Notably **NOT wiped**: `/mnt/nv/aftertouch.resolv.conf`, `/mnt/nv/rc.local`'s Aftertouch hook, and `/mnt/nv/BoseApp-Persistence/1/SystemConfigurationDB.xml`. The reset only touches log directories and account-specific persistence under the same `/mnt/nv/BoseApp-Persistence/1/` tree.
+
+6. **Reboot into setup mode.** Speaker drops Wi-Fi, comes back as its own AP `Bose SoundTouch XXXX` on 192.0.2.1.
+
+## Implications for migration ordering
+
+The DELETE in step 2 only reaches AfterTouch if the speaker's `margeURL` already points at AfterTouch *at the moment of reset*. A speaker still pointing at `streaming.bose.com` sends it into the void → AfterTouch keeps a stale `account/{id}/device/{id}` entry until someone manually prunes it.
+
+Therefore for a clean datastore lifecycle on an already-Bose-paired speaker:
+
+1. Migrate URLs first (`setup migrate --method=resolv` or `--method=telnet`).
+2. Reboot to apply.
+3. Factory reset.
+4. Re-provision.
+
+`soundtouch-cli setup plan --reset` currently runs factory-reset first (optimal for already-on-AfterTouch speakers); both `setup plan --reset` and `setup factory-reset` print a one-line note explaining the ordering tradeoff so users can pick the right sequence for their starting state.
+
+## Implications for AfterTouch behaviour
+
+- The DELETE handler is already correct; no changes needed.
+- AfterTouch is invisible to the LAN-peer notification step — that's just LAN HTTP between speakers.
+- If you build a "consolidate account" / "migrate fleet" feature later, the peer-notification channel is the propagation path the firmware uses internally; AfterTouch doesn't need to do anything analogous.
+- The persistence layer at `/mnt/nv/` is **factory-reset-resistant**. Our DNS-redirect migration (`setup migrate --method=resolv`) writes there specifically so AfterTouch routing survives a reset. This is intentional — the user can factory-reset a speaker freely without re-running migration.
+
+## Open questions
+
+- Are there other peer endpoints the firmware POSTs to besides `:8090/notification`? Worth checking on a 3-speaker LAN.
+- Does the `:8090/notification` payload format match the format used for play-as-notification audio pushes, or is it a distinct message shape? The "size(58)" byte count is too small for an audio URL but big enough for an XML envelope with an event type.
+
+If you want either of these answered, capture two synchronised `logread -f` streams from two LAN speakers while one is being reset.
+
+## Runbook — reset & re-provision an ST10 on AfterTouch
+
+End-to-end command sequence used during the 2026-05-12 bare-pairing experiment, recorded verbatim from the test session. Replace IPs, SSID, password, service URL, and account ID with your own. Two manual Wi-Fi switches happen between `factory-reset` and `wifi-push` (host joins the speaker's AP) and again between `wifi-push` and `wait-online` (host re-joins home Wi-Fi).
+
+```bash
+# === 1. Reconnaissance — confirm what state the speaker is in before touching it. ===
+
+# Identity, network, sources, presets.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup inspect
+
+# Green/red status across every migration axis (SSH, telnet, CA, pairing, …).
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup verify \
+  --service-url=https://soundtouch.fritz.box
+
+# What `setup plan --reset` would recommend, so you can preview the sequence.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup plan \
+  --service-url=https://soundtouch.fritz.box --reset
+
+
+# === 2. Reset and Wi-Fi re-provisioning. ===
+
+# Tell the speaker to wipe itself. Speaker drops Wi-Fi and reboots into AP mode.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup factory-reset
+
+# Manual: switch this host to the speaker's setup AP.
+#   macOS: networksetup -setairportnetwork en0 "Bose SoundTouch XXXX"
+
+# Poll 192.0.2.1:8090/info until the speaker answers (interval=2s, timeout=5m).
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup wait-ap
+
+# Push home Wi-Fi credentials. NOTE the single-quoted password: zsh expands `!`
+# inside double quotes as history-expansion and will refuse the command.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup wifi-push \
+  --ssid="wifi-name" --pass='a.secure!password'
+
+# Manual: switch host back to home Wi-Fi.
+#   macOS: networksetup -setairportnetwork en0 "wifi-name" 'a.secure!password'
+
+# mDNS-poll for the speaker on the home network, matched by deviceID suffix
+# (which survives the reset since it's the MAC). Returns the new IP.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup wait-online --match=536A98
+
+
+# === 3. Clock, migrate, pair. From here on use the new IP wait-online reported. ===
+
+# Set the speaker's wall-clock. `clock set --time=now` fails on FW 27;
+# `clock now` is the working subcommand.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 clock now
+
+# Reboot to clear any half-initialized resolver / NTP state from the wifi-push flap.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup reboot
+
+# Apply DNS-redirect migration: routes *.bose.com to AfterTouch and installs its CA.
+# Idempotent; safe to re-run.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup migrate \
+  --service-url=https://soundtouch.fritz.box --method=resolv
+
+# Reboot again so the envswitch parallel-persistence layer and the resolv hook
+# both take effect on the next boot.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup reboot
+
+# Pair the device with an AfterTouch account — bare experiment variant.
+# Drop --mode=bare and add --name=… / --language=… for the full state-machine variant.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup pair \
+  --mode=bare --account=1111111 --service-url='https://soundtouch.fritz.box'
+
+
+# === 4. Verify. ===
+
+# Reboot to verify persistence survives.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup reboot
+
+# Snapshot the result. margeAccountUUID should still equal --account, and Sources
+# should list ~14 entries (TUNEIN, RADIO_BROWSER, LOCAL_INTERNET_RADIO,
+# SPOTIFY slots, AIRPLAY, etc.) materialized by the firmware.
+go run ./cmd/soundtouch-cli --host 192.168.123.123 setup inspect
+```
+
+Total wall-clock for the above on this hardware: roughly 5 minutes including the two manual Wi-Fi switches and three reboots.

docs/analysis/SETUP-WEBSOCKET-EXPERIMENT.md

@@ -0,0 +1,215 @@
+# Experiment: Does bare `setMargeAccount` work outside the SETUP bracket?
+
+## Why we are doing this
+
+Our captured pairing flow (`docs/reference/DEVICE-PAIRING-FLOW.md`) shows the official Bose app always sends `setMargeAccount` *inside* a `SETUP_START` → `SETUP_ENTER` → `SETUP_LEAVE` state-machine bracket over WebSocket. The question this experiment answers:
+
+> If we open a WebSocket to a factory-reset speaker and send **only** `setMargeAccount` — no surrounding setupState messages — does the device honor it and write its persistence files (`SystemConfigurationDB.xml`, `Sources.xml`) cleanly?
+
+The answer determines the shape of `PairAccount`:
+
+- **If YES:** `PairAccount` becomes uniform: WebSocket-first, HTTP `/setMargeAccount` second, telnet `envswitch accountid set` third. One function, one ordering, all callers.
+- **If NO:** WebSocket pairing is only meaningful inside the full state machine. Factory-reset path uses the state machine; re-pair path keeps today's HTTP→telnet ordering.
+
+## Preconditions
+
+- A SoundTouch speaker that has been **factory-reset** and joined to the test Wi-Fi.
+- Speaker reachable on `:8090` (HTTP API) and `:8080` (WebSocket).
+- Speaker's runtime marge URL already points at AfterTouch (run the existing telnet URL rewrite first — otherwise the device's downstream POST will land on the dead Bose cloud and we will not be able to distinguish "WS message refused" from "downstream cloud failed").
+- A free 7-digit account ID — for example, generated via `setup.GenerateAccountID(nil)`.
+
+## Step 0 — Baseline
+
+```bash
+DEVICE=192.168.x.x
+curl -s http://$DEVICE:8090/info     | xmllint --format -
+curl -s http://$DEVICE:8090/sources  | xmllint --format -
+curl -s http://$DEVICE:8090/presets  | xmllint --format -
+```
+
+Record:
+
+- `<margeAccountUUID>` — expect empty on a factory-reset device.
+- `<margeURL>` — expect the AfterTouch URL (preflight already applied).
+- `<sources>` — expect a minimal list.
+- `<presets>` — expect `<presets/>`.
+
+## Step 1 — Send bare `setMargeAccount` over WebSocket
+
+Build the CLI once:
+
+```bash
+make build
+```
+
+Then run the bare path against the speaker:
+
+```bash
+DEVICE=192.168.x.x
+./build/soundtouch-cli setup pair --host=$DEVICE --account=1234567 --mode=bare
+```
+
+What it does:
+
+1. Reads `/info` to discover `deviceID`, logs the pre-state.
+2. Opens a WebSocket to `$DEVICE:8080` with the `gabbo` subprotocol.
+3. Sends exactly one frame — the `setMargeAccount` envelope — **without** any preceding `SETUP_START`/`SETUP_ENTER`.
+4. Reads frames for up to `--step-timeout=8s` (configurable), looking for an ack referencing our `requestID`.
+5. Closes the WebSocket, waits 2 s, re-reads `/info`, prints whether `margeAccountUUID` now equals our supplied ID.
+
+The exact frame sent (built by `setup.SetupSession.SetMargeAccount`):
+
+```xml
+<msg><header deviceID="DEVICE_ID" url="setMargeAccount" method="POST"><request requestID="1"/></header><body>
+  <PairDeviceWithAccount>
+    <accountId>1234567</accountId>
+    <userAuthToken>Bearer aftertouch</userAuthToken>
+  </PairDeviceWithAccount>
+</body></msg>
+```
+
+Outcomes the CLI will surface:
+
+- `Device accepted bare pairing.` (post-`/info` shows our ID) → **bare path works**.
+- `setMargeAccount: device rejected setMargeAccount: …` → device returned an `<error>` body → **bare path refused explicitly**.
+- `setMargeAccount: await ack for setMargeAccount: …` (timeout or EOF) → **bare path refused silently**.
+- `Device did NOT persist the pairing — bare path likely refused silently.` → ack received but persistence didn't follow.
+
+## Step 2 — Record outcome
+
+After step 1 (regardless of which branch happened):
+
+```bash
+sleep 2
+curl -s http://$DEVICE:8090/info | grep margeAccountUUID
+```
+
+| Observed result                                                              | Verdict                     |
+|------------------------------------------------------------------------------|-----------------------------|
+| `<margeAccountUUID>1234567</margeAccountUUID>` appears                       | **YES** — Option 1 wins     |
+| `<margeAccountUUID></margeAccountUUID>` still empty, no error frame received | Refused silently → **NO**   |
+| Error frame returned (e.g. `<error name="UNSUPPORTED_STATE"/>`)              | Refused explicitly → **NO** |
+| Device drops the WebSocket connection without replying                       | Refused → **NO**            |
+
+If verdict is YES, also verify the device wrote persistence cleanly. Reboot the device, then:
+
+```bash
+ssh root@$DEVICE 'cat /mnt/nv/BoseApp-Persistence/1/SystemConfigurationDB.xml'
+ssh root@$DEVICE 'cat /mnt/nv/BoseApp-Persistence/1/Sources.xml'
+curl -s http://$DEVICE:8090/info | grep margeAccountUUID
+```
+
+The UUID must still be present after reboot, and `SystemConfigurationDB.xml` must contain `<AccountUUID>1234567</AccountUUID>`. If it survives reboot, **YES** is confirmed.
+
+## Step 3 — Control: full state machine
+
+Factory-reset the same speaker again and run the full state machine — the same CLI, `--mode=full`:
+
+```bash
+./build/soundtouch-cli setup pair --host=$DEVICE --account=1234567 --mode=full
+```
+
+This drives `setup.Manager.ExecuteInitPlan` with `SkipURLRewrite=true`, which runs:
+
+```
+SETUP_START
+SETUP_IDENTIFY_DEVICE_ENTER
+language sysLanguage=2
+SETUP_ENTER
+SETUP_IDENTIFY_DEVICE_LEAVE
+setMargeAccount …
+SETUP_LEAVE
+pushCustomerSupportInfoToMarge
+```
+
+The CLI logs every step with status. Confirm `/info`, persistence, and reboot-survival checks pass. If the bare path failed but the full path succeeds, the SETUP bracket is load-bearing — a follow-up bisect (e.g. `SETUP_START + setMargeAccount + SETUP_LEAVE` only) tells us *which* surrounding messages the firmware actually requires.
+
+## Full reset-and-rebuild loop
+
+Once the bare/full question is decided, the loop for repeated experiments is:
+
+```bash
+# 0. Speaker is currently on home Wi-Fi at $DEVICE.
+#    Capture deviceID-suffix + current SSID first so wait-online and
+#    wifi-push have the right inputs.
+./build/soundtouch-cli setup inspect --host=$DEVICE
+./build/soundtouch-cli setup factory-reset --host=$DEVICE
+
+# 1. Manually switch this host to the speaker's AP (Bose SoundTouch XXXX).
+#    macOS: networksetup -setairportnetwork en0 "Bose SoundTouch XXXX"
+
+./build/soundtouch-cli setup wait-ap
+./build/soundtouch-cli setup wifi-push --ssid="$HOME_SSID" --pass="$HOME_PASS"
+
+# 2. Manually switch this host back to home Wi-Fi.
+
+./build/soundtouch-cli setup wait-online --match=DE4803          # deviceID suffix from /info before reset
+# (note the new IP from the "Speaker discovered" line)
+
+NEW_IP=192.168.x.y
+./build/soundtouch-cli setup migrate --host=$NEW_IP --service-url=http://aftertouch.local:8000   # default --method=telnet
+
+# Optional, if you want the DNS-redirect path instead of (or alongside) telnet envswitch:
+#   1. ./build/soundtouch-cli setup ssh-check --host=$NEW_IP            # USB-stick procedure if 22 is closed
+#   2. ./build/soundtouch-cli setup install-ca --host=$NEW_IP --service-url=http://aftertouch.local:8000
+#   3. ./build/soundtouch-cli setup migrate --host=$NEW_IP --service-url=http://aftertouch.local:8000 --method=resolv
+./build/soundtouch-cli setup pair --host=$NEW_IP --mode=bare   # or --mode=full
+```
+
+The two manual lines are user-side Wi-Fi switches that can't be automated portably. The `wait-ap` and `wait-online` subcommands poll for the corresponding network state, so timing them is hands-off.
+
+## Recording the result
+
+Append to this file under `## Results`:
+
+```
+- Date: YYYY-MM-DD
+- Firmware: 27.x.x
+- Model: ST10 / ST20 / ST30 / ST300
+- Bare setMargeAccount accepted: yes/no
+- Persistence written: yes/no
+- Survives reboot: yes/no
+- Notes: ...
+```
+
+One row per device tested. Once two devices on different firmware confirm the same verdict, we treat it as decided.
+
+## Results
+
+- Date: 2026-05-13
+- Firmware: 27.0.6.46330.5043500 (build epdbuild.trunk.hepdswbld04.2022-08-04T11:20:29)
+- Model: SoundTouch 10 (deviceID A81B6A536A98)
+- Bare setMargeAccount accepted: **yes** — pre-/info margeAccountUUID="" → post-/info margeAccountUUID="1111111"
+- Persistence written: **yes** — device materialized 14-entry Sources.xml on its own
+- Survives reboot: **yes** — `setup inspect` after `setup reboot` shows margeAccountUUID still 1111111
+- Notes: After bare pairing, the speaker did the full post-pairing handshake against AfterTouch (POST /streaming/support/power_on, GET /streaming/sourceproviders, GET /streaming/account/{id}/full, group/, provider_settings). No SETUP_START/SETUP_ENTER/SETUP_LEAVE was ever sent. Verdict: bare path is functionally equivalent to the full state machine on this firmware.
+
+### Implication for the codebase
+
+- `pkg/service/setup/setup_session.go` keeps the full state machine for completeness, but
+- `pkg/service/setup/init_plan.go`'s default could be simplified to "send setMargeAccount only" once we have one more confirming run on a different model.
+- The OCT issue-167 SSH-XML seeding workaround is **not required**.
+
+### Appendix — SystemConfigurationDB.xml comparison
+
+Post-experiment we compared the device-written `/mnt/nv/BoseApp-Persistence/1/SystemConfigurationDB.xml` from the bare-paired speaker against two SSH backups taken from speakers originally paired by the official Bose app (account 3230304, devices `A_Sound_Machine` and `Sound_Machinechen`). The diff is much smaller than expected — only two fields differ, and neither is set by the pairing protocol itself:
+
+| Field                    | Bare-paired (1111111)                      | Real-Bose-paired (3230304) | Set by                                                                                                    |
+|--------------------------|--------------------------------------------|----------------------------|-----------------------------------------------------------------------------------------------------------|
+| `DeviceName`             | `Bose SoundTouch 536A98` (factory default) | `Sound Machinechen`        | `name` WS message — only sent in `--mode=full`                                                            |
+| `AccountAssociatedEMail` | empty                                      | **empty**                  | Never populated, even by real Bose                                                                        |
+| `AccountUUID`            | `1111111`                                  | `3230304`                  | `setMargeAccount` — both paths set it                                                                     |
+| `Locale`                 | empty                                      | **empty**                  | Never populated, even by real Bose                                                                        |
+| `acctMode`               | `global`                                   | `global`                   | Firmware-default; no protocol path observed to change it                                                  |
+| `isMultiDeviceAccount`   | `false`                                    | `true`                     | Derived from the cloud's `/streaming/account/{id}/full` response — count of `<devices>` > 1 flips it true |
+| `margeAuthServerToken`   | empty                                      | **empty**                  | Never populated, even by real Bose                                                                        |
+| `Password`               | (encrypted blob)                           | (encrypted blob)           | Device-local key; expected to differ                                                                      |
+
+Three of the seven informational fields are empty even after a real-Bose pairing — the firmware simply doesn't populate `AccountAssociatedEMail`, `Locale`, or `margeAuthServerToken` from the pairing flow. So bare pairing isn't missing any field that real pairing fills.
+
+The two genuinely different fields:
+
+- **`DeviceName`** — pure UX. Settable any time post-pair via `name` POST (`soundtouch-cli name set --value=…`) or by sending the `name` WS message during `--mode=full` pairing.
+- **`isMultiDeviceAccount`** — not a pairing concern. It's derived from the account's device count on AfterTouch's side; flips to `true` automatically the next time the speaker refreshes account state if a second speaker has been paired to the same account.
+
+So the experiment's YES verdict stands unqualified: bare `setMargeAccount` produces a `SystemConfigurationDB.xml` functionally equivalent to one written by the official pairing flow.

docs/analysis/TELNET-COMMAND-REFERENCE.md

@@ -0,0 +1,265 @@
+# Bose SoundTouch Telnet (Port 17000) Command Reference
+
+A consolidated reference for the diagnostic shell that listens on TCP port
+17000 across the SoundTouch line. Compiled from multiple community sources
+to give a single map of what's been observed in the wild — useful both for
+implementing automation against it (see
+[TELNET-MIGRATION-METHOD.md](TELNET-MIGRATION-METHOD.md)) and for manual
+recovery / WiFi setup.
+
+> **Important caveat.** The command set is firmware-dependent. Anything that
+> existed in firmware 1.x–7.x (`flarn2006`'s era) was progressively trimmed;
+> some commands listed here have been removed on firmware 27.x. Where a
+> command's availability is known to vary, the **Availability** column says so.
+
+## Sources
+
+| #  | Source                                                                                                                                                                                                             | Era / focus                                                                                                                                                                                            |
+|----|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| S1 | [flarn2006: "Hacking the Bose SoundTouch and its Linux insides"](https://flarn2006.blogspot.com/2014/09/hacking-bose-soundtouch-and-its-linux.html) (2014)                                                         | Firmware 1.x–7.x; root shell discovery, codenames                                                                                                                                                      |
+| S2 | [Sam Hobbs: "Connect Bose SoundTouch 10 to WiFi using Linux Telnet"](https://samhobbs.co.uk/2016/01/connect-bose-soundtouch-10-wifi-using-linux-telnet) (2016)                                                     | ST 10 setup mode; `network`/`sys` families                                                                                                                                                             |
+| S3 | [izndgroup: "Connect Bose SoundTouch 10 to WiFi"](https://technical.izndgroup.com/2021/02/connect-bose-soundtouch-10-to-wifi.html) (2021)                                                                          | Reissue of S2 with later-firmware notes                                                                                                                                                                |
+| S4 | [sijeffrey/SoundTouch — `bose` script](https://github.com/sijeffrey/SoundTouch/blob/master/bose) (2017)                                                                                                            | `nc`-based remote-control script using `sys`/`ws`                                                                                                                                                      |
+| S5 | [r/bose "SoundTouch telnet probing"](https://www.reddit.com/r/bose/comments/1o5zkym/soundtouch_telnet_probing/)                                                                                                    | Recent (post-EOS) probing on ST 10 firmware `27.0.6.46330.5043500 epdbuild.trunk.hepdswbld04.2022-08-04T11:20:29`; comments mirrored in [#221](https://github.com/gesellix/Bose-SoundTouch/issues/221) |
+| S6 | Issue [#221](https://github.com/gesellix/Bose-SoundTouch/issues/221), [#236](https://github.com/gesellix/Bose-SoundTouch/issues/236), [deborahgu/soundcork#141](https://github.com/deborahgu/soundcork/issues/141) | The migration commands we already implement                                                                                                                                                            |
+
+---
+
+## Connecting to the shell
+
+### From an already-on-network device
+
+The shell binds to TCP port 17000 on every device family observed (ST 10/20/300, Wave III/IV, ST 520, SA-5 — see §"Firmware era notes" for caveats). No authentication.
+
+```bash
+# A no-op probe just to verify reach.
+echo '' | nc -w 2 <device-ip> 17000
+
+# Or interactively — works the same.
+telnet <device-ip> 17000
+```
+
+The `bose` script (S4) goes one level lower and writes commands directly to a `/dev/tcp/<ip>/17000` redirection target instead of using `nc`. That's the same wire protocol with no library between.
+
+### From a factory-fresh / WiFi-less device
+
+Per S2/S3 — newer firmware may have closed this on some models:
+
+1. **Enter setup mode.** Press and hold key **2** + **volume down** for 5 seconds until the WiFi LED turns amber.
+2. **Connect your laptop to the speaker's open access point.** The speaker becomes its own AP.
+3. **Telnet to `192.0.2.1` on port 17000.**
+
+Once you've added a WiFi profile (see `network wifi profiles add` below) the speaker reboots into station mode and the AP goes away.
+
+### Hardware key combinations on the device itself
+
+| Combo             | Effect                                   | Source |
+|-------------------|------------------------------------------|--------|
+| `1` + volume-down | Factory reset                            | S2, S3 |
+| `2` + volume-down | Setup mode (open WiFi AP at `192.0.2.1`) | S2, S3 |
+| `3` + volume-down | Toggle WiFi / Bluetooth                  | S2, S3 |
+| `4` + volume-down | Check for software updates               | S2, S3 |
+
+---
+
+## The `network` family — WiFi & interfaces
+
+| Command                                                    | Purpose                                                                                                                   | Availability               | Source |
+|------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|----------------------------|--------|
+| `network wifi status`                                      | Current SSID, state (e.g. `WIFI_STATION_CONNECTED`), signal strength. Returns XML-like `<WiFiStatus SSID="…" state="…">`. | Wide                       | S2, S3 |
+| `network wifi scan [<maxresults>]`                         | Site survey.                                                                                                              | Wide                       | S2     |
+| `network wifi profiles info`                               | Lists stored WiFi profiles (passphrases shown encrypted).                                                                 | Wide                       | S2, S3 |
+| `network wifi profiles add <ssid> <security> [<password>]` | Adds a WiFi network. `<security>` ∈ `none` \| `wep` \| `wpa_or_wpa2`.                                                     | Wide; setup-mode workhorse | S2, S3 |
+| `network wifi profiles clear`                              | Wipes all stored profiles.                                                                                                | Wide                       | S2     |
+| `network status`                                           | All interfaces and IP addresses.                                                                                          | Wide                       | S2, S3 |
+| `network dhcp`                                             | Current DHCP interface info.                                                                                              | Wide                       | S2     |
+| `network mode auto\|wifioff\|wifisetup`                    | Switch radio / setup-AP state.                                                                                            | Wide                       | S2     |
+
+**Example session — adding a network from setup mode (S3):**
+
+```
+network wifi profiles add foobarHub wpa_or_wpa2 topsecret
+```
+
+The speaker stores the profile, drops the setup AP, and reboots into station mode.
+
+---
+
+## The `key` family — front-panel button emulation
+
+Each `key …` command emulates a press of a physical button on the speaker
+or remote. Confirmed working on ST 10 / FW `27.0.6.46330.5043500` (S5);
+also visible on the ST 20/300/Wave captures in #221. Different from the
+`sys presetkey N p` form (S4) — the `key prefix_N` shape on FW 27 is what
+the device's own remote sends.
+
+| Command                         | Effect                                                                                | Source |
+|---------------------------------|---------------------------------------------------------------------------------------|--------|
+| `key prefix_1` … `key prefix_6` | Triggers preset 1–6 (same as a remote preset press).                                  | S5     |
+| `key play`                      | Begin / resume playback.                                                              | S5     |
+| `key pause`                     | Pause playback.                                                                       | S5     |
+| `key stop`                      | Stop playback (does **not** terminate the underlying stream).                         | S5     |
+| `key prev`                      | Restart current song / previous track.                                                | S5     |
+| `key next`                      | Next track.                                                                           | S5     |
+| `key aux`                       | Toggle Bluetooth / AUX input.                                                         | S5     |
+| `key power`                     | Echoes "OK" but no observable effect on FW 27.x — possibly handled at a higher layer. | S5     |
+
+The S4 `bose` script's `sys presetkey N p` form still works, but `key prefix_N` is shorter and matches what the remote already does on FW 27.x.
+
+---
+
+## The `sys` family — system control & service URLs
+
+The `sys` family is the one our migration uses (see §"What we use during migration"). Two distinct sub-syntaxes coexist:
+
+- **Single-token verbs:** `sys reboot`, `sys volume`, `sys power`, etc.
+- **`sys configuration <key> <value>` setters** that modify persisted runtime configuration. Used for the four service URLs (margeServerUrl, statsServerUrl, swUpdateUrl, bmxRegistryUrl).
+
+| Command                                     | Purpose                                                                                                                                                                                       | Availability               | Source     |
+|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|------------|
+| `sys reboot`                                | Restart the device.                                                                                                                                                                           | Wide                       | S2, S6     |
+| `sys factorydefault`                        | Reset to factory defaults.                                                                                                                                                                    | Wide                       | S1, S2     |
+| `sys ver`                                   | Firmware version string, e.g. `BoseApp version: 27.0.6.46330.5043500 …`.                                                                                                                      | Wide; confirmed on FW 27.x | S1, S5     |
+| `sys power`                                 | Toggle power. Confirmed working on older firmware via S2/S4; on FW 27.x ST 10 the response is `OK` but with **no observable effect** — power state may be controlled elsewhere on that build. | Varies                     | S2, S4, S5 |
+| `sys playpause`                             | Toggle playback.                                                                                                                                                                              | Wide                       | S2         |
+| `sys stop`, `sys pause`                     | Accepted (return `OK`) but **no observable effect** on FW 27.x ST 10 — the working stop/pause path on that firmware is `key stop` / `key pause`.                                              | Wide / no-op               | S5         |
+| `sys volume`                                | Print current volume. The S4 script parses the 5th token of the first line.                                                                                                                   | Wide                       | S2, S4, S5 |
+| `sys volume <int>`                          | Set absolute volume to `<int>`.                                                                                                                                                               | Wide                       | S5         |
+| `sys volume up <n>` / `sys volume down <n>` | Adjust volume by `<n>` (steps, not dB).                                                                                                                                                       | Wide                       | S4         |
+| `sys volume <value> updateDisplay`          | Set absolute volume and update the front-panel display.                                                                                                                                       | Wide                       | S2         |
+| `sys presetkey <1-6> p`                     | Trigger a preset (`p` = press). Older shape of `key prefix_<N>`.                                                                                                                              | Wide                       | S4         |
+| `sys timeout inactivity disable` (or `off`) | Stop the auto-shutoff timer. May need to be sent twice.                                                                                                                                       | Wide                       | S1, S2     |
+| `sys configuration` (no args)               | Returns the usage hint `sys configuration <XMLTag> <XMLValue>` — confirms the underlying setter is XML-tag-keyed.                                                                             | FW 27.x                    | S5         |
+| `sys configuration bmxRegistryUrl <url>`    | Set the Bose Media eXchange registry URL.                                                                                                                                                     | Wide; **migration**        | S6         |
+| `sys configuration statsServerUrl <url>`    | Set the telemetry/stats endpoint.                                                                                                                                                             | Wide; **migration**        | S6         |
+| `sys configuration margeServerUrl <url>`    | Set the marge / streaming endpoint.                                                                                                                                                           | Wide; **migration**        | S6         |
+| `sys configuration swUpdateUrl <url>`       | Set the software-update endpoint.                                                                                                                                                             | Wide; **migration**        | S6         |
+
+Each `sys configuration` setter is reported by users to return `OK` on success. Wait for that token between commands (S6, `foob61451`).
+
+---
+
+## The `envswitch` family — parallel persistence layer
+
+`envswitch` writes to a separate, lower-level persistence store that **wins on next reboot** if the corresponding `sys configuration` value differs. So our migration writes both — see TELNET-MIGRATION-METHOD.md §2.1.
+
+| Command                                           | Purpose                                                                                       | Source  |
+|---------------------------------------------------|-----------------------------------------------------------------------------------------------|---------|
+| `envswitch boseurls set <margeUrl> <swUpdateUrl>` | Persist the marge and update URLs. **Two arguments**, in that order.                          | S6      |
+| `envswitch accountid set <numeric-id>`            | Equivalent to the HTTP `/setMargeAccount` POST. Used as fallback in our `PairAccount` helper. | S6      |
+| `envswitch accountid get`                         | Plausible by symmetry but **not yet confirmed** across firmwares; we probe it best-effort.    | (probe) |
+
+---
+
+## The `getpdo` family — read persisted configuration
+
+`getpdo <selector>` prints the contents of a persisted-data-object. We use it as the verification step after writing URLs.
+
+| Selector                            | Purpose                                                                                                                                                               | Source |
+|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|
+| `getpdo CurrentSystemConfiguration` | Echoes the resolved URL set, including margeServerUrl/bmxRegistryUrl/statsServerUrl/swUpdateUrl. We grep our targetURL out of this to confirm a successful migration. | S6     |
+
+---
+
+## The `scm` family — service control
+
+`scm` (System Control / Module manager) lets you inspect and restart internal services.
+
+| Command                 | Purpose                                                                                  | Availability   | Source                                                                       |
+|-------------------------|------------------------------------------------------------------------------------------|----------------|------------------------------------------------------------------------------|
+| `scm list`              | List running services.                                                                   | Older firmware | S1                                                                           |
+| `scm restart <service>` | Restart a service by name.                                                               | Older firmware | S1                                                                           |
+| `scm uboot_ver`         | Print bootloader version (`U-Boot 2013.01.01-…`). Confirmed working on SA-5 with FW 9.x. | Older firmware | [deborahgu/soundcork#141](https://github.com/deborahgu/soundcork/issues/141) |
+
+---
+
+## Shell-unlock commands
+
+These are the commands that gated SSH access on older firmware. Both have been progressively removed; on FW 27.x they generally do nothing useful.
+
+| Command                     | Purpose                                                                                                                                                                                  | Availability     | Source                                                                           |
+|-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------------------------------------------------------------------------------|
+| `remote_services on`        | Enable SSH on port 22. Volatile (re-enter after reboot). Response: `remote services on`. **Removed in FW 7.x+**.                                                                         | Old              | S1                                                                               |
+| `local_services on`         | Alternative enablement; works on some firmware where `remote_services` was removed. SA-5 FW 9.x reports `local services on`, but this alone does not appear to grant SSH on most models. | Old, hit-or-miss | S1, [deborahgu/soundcork#141](https://github.com/deborahgu/soundcork/issues/141) |
+| `demo enter` / `mode enter` | Unlocks demo / button-test mode (used historically to recover bricked units).                                                                                                            | Old              | S1                                                                               |
+
+---
+
+## The `ws` and `swupdate` families
+
+| Command          | Purpose                                                                                                 | Availability | Source |
+|------------------|---------------------------------------------------------------------------------------------------------|--------------|--------|
+| `ws getpresets`  | Returns an XML list of presets — the S4 script parses the `<itemName>…<text>…` blocks to extract names. | Wide         | S4     |
+| `swupdate abort` | Cancel a software update in progress.                                                                   | Wide         | S1     |
+
+---
+
+## `help`
+
+Lists the commands available on the running firmware. **Frequently removed** on later firmware — returns `Command not found` on FW 27.x in many of the captures we have. Still worth probing once during preflight: a successful response is a quick way to enumerate what this specific build supports without trial-and-error.
+
+---
+
+## Device codenames (S1)
+
+These show up in `getpdo`, `network status`, and SSH-side hostnames. Useful for matching captures to hardware.
+
+| Codename | Hardware                                       |
+|----------|------------------------------------------------|
+| `lisa`   | Adapter (older speakers running Bose firmware) |
+| `spotty` | SoundTouch 20                                  |
+| `rhino`  | SoundTouch 10                                  |
+| `mojo`   | SoundTouch 30                                  |
+| `taigan` | SoundTouch Portable                            |
+
+---
+
+## Firmware era notes
+
+- **Firmware 1.x–7.x** (S1 era): everything — `help`, `remote_services on`, full `scm`, and an in-shell login prompt. `flarn2006` documents the original Linux insides.
+- **Firmware 8.x–14.x** (S2 era): `remote_services on` removed; `network`, `sys`, `envswitch`, `getpdo` still present. `local_services on` works on some Wave/SA-5 models.
+- **Firmware 27.x** (S5/S6 era — the long-lived "frozen" build that survived through EOS): `help`, `remote_services on`, and `sys ver` removed in some builds; `sys configuration …` and `envswitch …` confirmed working on ST 10, ST 20, ST 300, Wave III, Wave IV. **This is the firmware our migration targets**. The Portable on more recent firmware drops further commands and is the hardest target.
+
+  S5 enumerated the **top-level command roots** that don't return "Command not found" on a vanilla ST 10 (`rhino`) running `27.0.6.46330.5043500`:
+
+  ```
+  key
+  net
+  sys
+  getpdo
+  ```
+
+  Notably absent from that probe: `network`, `envswitch`, `scm`, `ws`, `swupdate`, `remote_services`, `local_services`, `demo`, `mode`, `help`. **However**, other captures on the same firmware family (S6, ST 20 / Wave III / Wave IV) accept `envswitch …`, suggesting either per-model variation in the shipped command table or an SSH/role gate the S5 author didn't trip. Implementations that use `envswitch` should treat its absence as a recoverable preflight outcome (we already do).
+
+  `net` is observed as a valid root by S5 but its sub-commands aren't enumerated; it may be a shorthand alias for `network` on FW 27.x ST 10.
+
+---
+
+## What we use during migration
+
+For quick reference, the exact sequence our `pkg/service/setup.migrateViaTelnet` issues, all on the same connection, in this order:
+
+```
+sys configuration bmxRegistryUrl <serverURL>/bmx/registry/v1/services
+sys configuration statsServerUrl <serverURL>
+sys configuration margeServerUrl <serverURL>
+sys configuration swUpdateUrl    <serverURL>/updates/soundtouch
+envswitch boseurls set <serverURL> <serverURL>/updates/soundtouch
+getpdo CurrentSystemConfiguration
+```
+
+Plus, when pairing a fresh device whose `:8090/setMargeAccount` is missing or wedged, the helper falls back to:
+
+```
+envswitch accountid set <7-digit-id>
+```
+
+Reboot is **not** part of these sequences — it stays a user-initiated action via the existing reboot button, which now accepts `?method=telnet|ssh` and sends `sys reboot` when telnet is picked.
+
+---
+
+## Out of scope here, but worth recording
+
+- **Setup-mode WiFi onboarding via 192.0.2.1.** The community uses this to add a fresh device to a network without the Bose app. Our `soundtouch-service` does not currently automate this, but `network wifi profiles add` is the entry point if we ever do.
+- **Direct preset / playback control via `sys`.** The S4 `bose` script demonstrates a viable headless remote-control path that does not need our marge emulation at all. Useful as a fallback for tooling on devices that refuse to talk to any cloud.
+- **`scm restart <service>`.** Not used today, but a possible recovery primitive on older firmware where a stuck service blocks streaming.

docs/analysis/TELNET-MIGRATION-METHOD.md

@@ -0,0 +1,730 @@
+# Telnet (Port 17000) Migration Method — Analysis
+
+This document captures the use cases, community findings, and feasibility analysis
+for adding a **Telnet/port 17000** migration path to `soundtouch-service` as a
+peer of the existing XML and DNS-based methods. The `/etc/hosts` method stays
+deprecated and is intentionally kept off the visible UI options.
+
+> **Sources** — community discussion synthesised from
+> [gesellix/Bose-SoundTouch#221](https://github.com/gesellix/Bose-SoundTouch/issues/221),
+> [gesellix/Bose-SoundTouch#236](https://github.com/gesellix/Bose-SoundTouch/issues/236),
+> [scheilch/opencloudtouch#167](https://github.com/scheilch/opencloudtouch/issues/167),
+> [deborahgu/soundcork#228](https://github.com/deborahgu/soundcork/issues/228),
+> [deborahgu/soundcork#141](https://github.com/deborahgu/soundcork/issues/141),
+> the post-EOS walkthrough PDF in `docs/`,
+> [Bose SoundTouch Telnet Probing thread](https://www.reddit.com/r/bose/comments/1o5zkym/soundtouch_telnet_probing/),
+> and [flarn2006's blog post on hacking SoundTouch](https://flarn2006.blogspot.com/2014/09/hacking-bose-soundtouch-and-its-linux.html).
+
+---
+
+## 1. Why a third method is needed
+
+The two currently shipped methods both have hard preconditions that block real
+users:
+
+| Method                                  | Preconditions                                                | Failure modes seen in the wild                                                                                                                                                         |
+|-----------------------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **XML** (`SoundTouchSdkPrivateCfg.xml`) | SSH/root access — needs `remote_services` USB unlock first   | Some firmware revisions (e.g. SA-5, ST520, latest ST Portable) refuse the USB unlock entirely; `remote_services on` was removed from the telnet command set in firmware 7.x and later. |
+| **DNS** (`resolv.conf` priority hook)   | SSH/root access; service must own port 53 on the LAN gateway | Won't fit users behind ISP routers they can't reconfigure; still requires the device to be SSH-reachable to write the hook.                                                            |
+
+The community has demonstrated a **third path that needs no SSH at all**:
+the device's built-in **diagnostic Telnet shell on TCP port 17000** accepts
+configuration commands that change exactly the same fields the XML method would.
+
+### 1.1 Confirmed user reports (firmware 27.0.6.46330.5043500 unless noted)
+
+| Reporter           | Hardware                  | Outcome                                                                                                     |
+|--------------------|---------------------------|-------------------------------------------------------------------------------------------------------------|
+| `foob61451` (#221) | ST 10, ST 20 (non-rooted) | All four URLs persisted via `sys configuration …`; `envswitch boseurls set …` survived `sys reboot`.        |
+| `bveenker` (#221)  | Wave III                  | URLs accepted; presets work after pairing via `/setMargeAccount` (see §3).                                  |
+| `stephan48` (#221) | Wave IV                   | Telnet:1700 + USB stick `remote_services` did **not** work; **port 17000 telnet** worked for all four URLs. |
+| `mcdona1d` (#141)  | ST 20, ST 300             | Confirmed working with `sys configuration …` + `envswitch …` + `sys reboot`.                                |
+| `TJGigs` (#228)    | ST 20 ×2, ST 10           | Wraps telnet:17000 into an admin "Smart Inject" tool; uses `sys reboot` over telnet to nudge devices.       |
+
+So the method is plausible across **at least ST 10/20/300 and Wave III/IV** on
+the most common firmware that survived the EOS cut, **without the USB unlock
+dance** that newer firmware refuses.
+
+---
+
+## 2. The Telnet:17000 command set we rely on
+
+> For a broader catalogue of every telnet command the community has documented
+> across firmware eras (the `key`, `network`, `sys`, `envswitch`, `getpdo`,
+> `scm`, `ws`, `swupdate`, and shell-unlock families), see
+> **[TELNET-COMMAND-REFERENCE.md](TELNET-COMMAND-REFERENCE.md)**. This
+> section only lists the subset our migration actually drives.
+
+
+### 2.1 URL configuration (the migration payload)
+
+The sequence we send for `soundtouch-service` (community-validated in #221, #141):
+
+```
+sys configuration bmxRegistryUrl http://<service-host>:8000/bmx/registry/v1/services
+sys configuration statsServerUrl http://<service-host>:8000
+sys configuration margeServerUrl http://<service-host>:8000
+sys configuration swUpdateUrl    http://<service-host>:8000/updates/soundtouch
+envswitch boseurls set http://<service-host>:8000 http://<service-host>:8000/updates/soundtouch
+getpdo CurrentSystemConfiguration
+```
+
+`sys reboot` is **not** part of this sequence. The migration flow only writes
+configuration — the reboot is user-initiated via the existing reboot button in
+the web UI, mirroring what XML/DNS migration already does. See §6.2 for how
+that button gains a `?method=ssh|telnet` selector.
+
+Three important details from the discussion:
+
+1. **`sys configuration` alone is not enough.** `stephan48` reported that
+   without the `envswitch boseurls set …` line his typo in `bmxRegistryUrl` was
+   silently restored on reboot — i.e. there is a parallel "envswitch" persistence
+   layer that wins on next boot if you don't also write to it. **We must always
+   issue both.**
+2. **margeServerUrl path is bare for `soundtouch-service`.** We mount the marge
+   endpoints at the **root** of port 8000, matching what the existing XML
+   migration writes (`Manager.migrateViaXML` in `pkg/service/setup/setup.go`
+   sets `MargeServerUrl: targetURL` without any suffix). Some community
+   recipes appended `/marge` because they were targeting
+   [`deborahgu/soundcork`](https://github.com/deborahgu/soundcork), which
+   routes marge under that sub-path. **For our service: bare URL. For users
+   redirecting to soundcork: append `/marge`** to both `margeServerUrl` and
+   the first argument of `envswitch boseurls set`.
+3. **Each command must be sent one at a time, waiting for the device's `OK`
+   response** before sending the next one (`foob61451`'s explicit warning).
+
+### 2.2 Account pairing fallback
+
+`envswitch accountid set <numeric-id>` was reported by `bveenker` (#221) as an
+in-band equivalent to the HTTP `/setMargeAccount` call, useful when the
+`/setMargeAccount` endpoint is missing on the firmware (see §3).
+
+### 2.3 Probing / preflight
+
+- A bare TCP connect to `<deviceIP>:17000` answers (no auth) on devices we care
+  about.
+- Useful read-only verification command: `getpdo CurrentSystemConfiguration` —
+  prints the URLs after the changes have been applied so we can verify before
+  rebooting.
+- `sys reboot` is the trigger that re-reads both layers.
+
+### 2.4 What Telnet:17000 cannot do
+
+- It does **not** install a custom CA. So if a user wants HTTPS rather than HTTP
+  redirection to our service (the DNS-method scenario, where `resolv.conf`
+  redirection collides with the device's TLS validation unless our root CA is
+  trusted on the device), telnet alone won't cover it. This is fine for our
+  default flow, which uses plain `http://` URLs to the service's port 8000.
+- It does not give us a way to read or write `Sources.xml` (third-party
+  account credentials) — that still requires SSH, but for a migration we don't
+  actually need it.
+
+---
+
+## 3. The `/setMargeAccount` problem (issue #236, #228)
+
+### 3.1 What it is
+
+A factory-reset speaker has an empty `<margeAccountUUID/>` in `:8090/info`. The
+marge endpoints fail with 502 / unhandled until that field is populated, which
+is why several users (#221, #236) saw **everything except AUX** broken after
+migration:
+
+```
+POST http://<deviceIP>:8090/setMargeAccount
+Content-Type: application/xml
+
+<PairDeviceWithAccount>
+  <accountId>1234567</accountId>
+  <userAuthToken>soundcorkdoesntcare</userAuthToken>
+</PairDeviceWithAccount>
+```
+
+The values are not validated by the local service, so any numeric `accountId`
+will work — soundcork's runbook (#228) literally calls the token
+`soundcorkdoesntcare` to make the point.
+
+### 3.2 Why it's broken in practice
+
+There are **three independent failure modes** observed:
+
+| Symptom                                                         | Cause                                                                                                                 | Detection                                                                                                           |
+|-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
+| Endpoint returns 404 / "not implemented"                        | Newer firmware (e.g. some BST20 Portable, latest ST Portable) drops the endpoint entirely.                            | `GET /supportedURLs` does **not** list `/setMargeAccount` in `<URL location="…"/>`.                                 |
+| Endpoint hangs (no response / socket stays open)                | "Broken state" the user explicitly called out — endpoint advertised, but handler is wedged.                           | Caller has to time out; we currently have no timeout, so the request appears to hang the migration UI indefinitely. |
+| `POST /marge/streaming/support/power_on` → 502 unhandled (#236) | Device keeps polling marge after migration but no `margeAccountUUID` was ever assigned, so all subsequent calls fail. | `:8090/info` shows `<margeAccountUUID/>` empty after reboot.                                                        |
+
+### 3.3 Required handling
+
+Per the user's brief, the migration logic must:
+
+1. **Probe** `GET http://<deviceIP>:8090/supportedURLs` and check whether
+   `/setMargeAccount` is in the list **before** trying to POST it.
+2. **Time-bound** the POST aggressively (e.g. ≤5s connect + ≤10s read) and treat
+   anything over the budget as a failure rather than waiting indefinitely.
+3. On either failure mode, **fall back** to the telnet equivalent
+   `envswitch accountid set <id>` over the same `pkg/telnet` connection used
+   for the URL flip. Reboot stays a user-initiated action (§6.2).
+4. If telnet:17000 is **also** unreachable, surface a clear "your firmware does
+   not support unattended pairing — please pair manually via the official Bose
+   app *before* it goes EOS, or open SSH and use the XML method" error rather
+   than leaving the device in a half-migrated state.
+
+### 3.4 Where the `<id>` comes from
+
+The device's current account ID is already discoverable through endpoints we
+control:
+
+- **`GET :8090/info`** returns `<margeAccountUUID>…</margeAccountUUID>`. If it
+  is non-empty the device is already paired — **reuse that ID**, do not
+  reassign. Our local marge accepts any ID, so the existing one is fine.
+- If it is empty (factory reset), the user picks one in the UI:
+  1. **Pick from existing accounts.** The setup UI lists IDs returned by
+     `DataStore.ListAccounts()` so a user can re-attach a fresh device to an
+     account that already has presets/recents/sources.
+  2. **Enter manually.** Free-form text input, validated as **exactly 7
+     numeric digits** (the format every Bose-cloud-issued ID has had in the
+     captures we've seen, and the format the wider community uses in their
+     recipes).
+  3. **Randomize.** A "Generate" button that picks a 7-digit number and
+     re-rolls if it collides with an existing account in the local datastore.
+- **Telnet read-back (best-effort).** `envswitch accountid get` is plausible by
+  symmetry with `envswitch accountid set` (#221) but is not yet confirmed
+  across firmwares. We will probe it during preflight; if it returns a value
+  we cross-check it against `:8090/info` and warn on mismatch.
+
+This means the user is never *forced* to invent a number — the common path is
+"the device already has an ID, reuse it" — and the manual/randomize controls
+only show up when the device is genuinely fresh.
+
+---
+
+## 4. Port 17000 availability
+
+The diagnostic shell is gated by firmware build and product family. Anecdotally:
+
+- ST 10 / ST 20 / ST 300 / Wave III / Wave IV on FW 27.0.6 → **open**.
+- SA-5 with FW 9.x → some commands present (`local_services on`) but
+  **no `remote_services on`** and no SSH on FW 9.0.43.23466 (#141).
+- Modern firmware on some Portables → endpoint set has shrunk further.
+
+Because of this, we cannot assume port 17000 is reachable. The migration flow
+must:
+
+1. **Probe** with a TCP connect to `<deviceIP>:17000`, with a tight timeout
+   (≤2s). A successful TCP handshake is necessary but not sufficient — some
+   hardened firmware closes the port immediately.
+2. **Banner check.** After connecting, read whatever the device sends within
+   ~1s. The diagnostic shell prints a small banner (firmware-dependent); a
+   blank read or an immediate close means we should treat it as "telnet not
+   usable" and disable the option.
+3. **Capability check.** Issue a no-op like `getpdo CurrentSystemConfiguration`
+   and look for any non-empty response. If the device replies "Command not
+   found" we abort and suggest XML or DNS instead.
+4. **Surface state to the UI.** The migration form should grey out the Telnet
+   option when the probe fails and show *why* (closed, banner missing,
+   command rejected) instead of letting the user click into a dead end.
+
+---
+
+## 5. Implementation feasibility — Telnet client in Go
+
+This is a feasibility check only; no code is written yet.
+
+### 5.1 Protocol
+
+"Telnet" on port 17000 is effectively a line-oriented plain-TCP shell. The
+device prints a small prompt (`->` in the SA-5 captures from #141) and reads
+newline-terminated commands. There is **no** real Telnet option negotiation
+(no `IAC`/`DO`/`WILL` exchanges visible in the wild captures), so we don't
+need `golang.org/x/crypto/ssh`-class machinery.
+
+### 5.2 Standard-library only
+
+A minimal client is just `net.DialTimeout("tcp", host+":17000", 2*time.Second)` +
+`bufio.Scanner` + `time.Time`-based deadlines on `Conn`. No third-party Telnet
+library is needed; `github.com/reiver/go-telnet` would be overkill and adds
+maintenance surface for no benefit. This matches the project's KISS principle
+in `docs/CLAUDE.md` §3.
+
+### 5.3 Cross-platform compatibility
+
+`net.Dial` over TCP works identically on Windows, macOS, Linux and (with
+limitations on listening) WASM. WASM-side: `soundtouch-service` runs server-side
+anyway, so this only matters for `soundtouch-cli`, where TCP dial works in any
+target other than browser-WASM — an acceptable carve-out documented separately.
+
+### 5.4 Concurrency / safety
+
+Each migration is a single goroutine driving one device. The client must:
+
+- enforce per-command response deadlines so a wedged device cannot stall the
+  migration UI (mirrors the `/setMargeAccount` requirement);
+- abort the rest of the sequence on the first non-`OK` response so we don't
+  half-write configuration;
+- always close the socket on error.
+
+### 5.5 Testing strategy
+
+We can test without a real speaker by spinning up a `net.Listen("tcp", "127.0.0.1:0")`
+in the test, scripting it to consume our commands and emit canned `OK`/error
+responses. That gives us deterministic coverage for:
+
+- happy path (all four URLs accepted),
+- single-command failure → sequence aborts, no further commands sent,
+- "command not found" on `envswitch …` → fallback path exercised,
+- TCP closed mid-stream → migration aborts cleanly,
+- read deadline triggers when the device hangs (the broken-state simulation).
+
+The repo already follows the "real device responses preferred, mock servers
+otherwise" rule (see `docs/CLAUDE.md` §1, §8). The tests above are the mock-server
+half of that pattern.
+
+### 5.6 Where it lives
+
+The protocol client is **a standalone package**, not buried inside
+`pkg/service/setup`, so it can be reused from CLI tools, future setup wizards,
+and tests without dragging the migration manager in:
+
+```
+pkg/telnet/                        # NEW reusable package
+  client.go                        #   Dial / SendCommand / Probe / Close
+  client_test.go                   #   mock-server tests against a net.Listen
+
+pkg/service/setup/
+  telnet_migration.go              # NEW thin wrapper that imports pkg/telnet
+                                   # and runs the URL config sequence
+  marge_pairing.go                 # NEW /setMargeAccount probe + post + telnet
+                                   # `envswitch accountid set` fallback
+  setup.go                         # add MigrationMethodTelnet const + case
+```
+
+UI plumbing is `pkg/service/handlers/web/index.html` (option list) and
+`pkg/service/handlers/web/js/script.js` (`toggleMigrationMethod()`). The
+deprecated `hosts` option is already hidden from the dropdown when we ship
+this; we just add a `telnet` option next to `xml`/`resolv`.
+
+### 5.7 Verdict
+
+**Feasible and small.** Estimated scope: ~200 lines of client code in
+`pkg/telnet`, ~300 lines of tests, plus a `MigrationMethodTelnet` branch in
+`Manager.MigrateSpeaker`, plus the preflight probe described in §4 and the
+`/setMargeAccount` guarding described in §3.
+
+---
+
+## 6. Decisions made (was: open questions)
+
+1. **Account-ID generation.** Resolved — see §3.4. The migration form reads
+   `:8090/info` first; if `margeAccountUUID` is non-empty it is reused.
+   Otherwise the UI offers (a) pick from `DataStore.ListAccounts()`,
+   (b) manual entry validated as 7 numeric digits, (c) a "Generate" button
+   that randomizes a 7-digit number and re-rolls on collision.
+2. **Reboot policy.** Migration writes configuration only — it does **not**
+   issue `sys reboot` itself. Reboot stays user-initiated via the existing
+   reboot button in the web UI, the same way XML/DNS migration already works.
+   That button's endpoint (`POST /setup/reboot/{deviceId}`,
+   `Manager.Reboot(deviceIP)`) gains an optional `?method=ssh|telnet` query
+   parameter; default stays `ssh` so existing behavior is preserved. The
+   button itself uses a plain `confirm()` dialog before firing.
+3. **CA / HTTPS story.** Telnet has no way to install a custom CA. Documented
+   as an explicit limitation: telnet method = HTTP-only redirect to our
+   service. Users who need end-to-end TLS must use the XML or DNS method.
+   *Possible future enhancement* — a hybrid "install CA via SSH/XML, then drive
+   the URL flip via Telnet" path. Feasibility unknown; not in this iteration.
+
+---
+
+> **See §9 for the as-shipped state.** Section 7 below records the
+> original forecast; the wizard grew larger during implementation and
+> §9 documents what actually landed.
+
+## 7. Summary of what changes when this lands
+
+- **New reusable package `pkg/telnet`** — sibling of `pkg/ssh`, line-oriented
+  TCP client with `Dial`, `SendCommand`, `Probe`, `Close`, all deadline-driven.
+  No external dependencies, usable from CLI, service, and tests.
+- **New `MigrationMethodTelnet = "telnet"`** constant in `pkg/service/setup/setup.go`
+  plus a `migrateViaTelnet` branch in `Manager.MigrateSpeaker`.
+- **New `pkg/service/setup/telnet_migration.go`** orchestrating the URL
+  configuration sequence (§2.1) on top of `pkg/telnet`. Configuration only —
+  no `sys reboot` here.
+- **New `pkg/service/setup/marge_pairing.go`** with `PairAccount(deviceIP, id)`:
+  probes `/supportedURLs`, time-bounded `POST /setMargeAccount`, falls back to
+  telnet `envswitch accountid set <id>` on missing/wedged endpoint.
+- **`Manager.Reboot` and `HandleRebootDevice` gain a method selector** —
+  signature changes to `Reboot(deviceIP string, method RebootMethod) (string, error)`
+  with `RebootMethodSSH` (default, today's behavior) and `RebootMethodTelnet`
+  (sends `sys reboot` over a fresh `pkg/telnet` connection). Handler reads
+  `?method=ssh|telnet` from the query string.
+- **`MigrationSummary` gains** `TelnetReachable`, `TelnetBanner`,
+  `TelnetCommandsAccepted`, `SetMargeAccountSupported`, `CurrentAccountID`,
+  `KnownAccountIDs` so the UI can show preflight outcomes and offer reuse.
+- **UI** — `web/index.html` dropdown gets a `telnet` option (greyed out when
+  preflight fails) and a new pane for picking/entering/randomizing a 7-digit
+  account ID when `:8090/info` reports an empty `margeAccountUUID`. The
+  existing reboot button gets a method selector (radio or dropdown) wired to
+  the new query param, with `confirm()` before firing. The legacy `hosts`
+  option stays out of the dropdown (deprecated).
+
+---
+
+## 8. Device compatibility today
+
+What follows is the current best read on which devices our `migrateViaTelnet`
+flow handles end-to-end, derived from the same six sources catalogued in
+[TELNET-COMMAND-REFERENCE.md](TELNET-COMMAND-REFERENCE.md) plus the issue
+threads cited above. This is migration-outcome perspective; for per-command
+availability see the reference doc.
+
+### 8.1 Proven to work end-to-end
+
+All on the firmware-27.0.6 family, which is what survived through Bose's
+end-of-service cut. Multi-reporter agreement on every row.
+
+| Device   | Reporter(s)                 | Source           | Confirmed                                                                  |
+|----------|-----------------------------|------------------|----------------------------------------------------------------------------|
+| ST 10    | foob61451, TJGigs           | #221, #228       | All four URLs persist; `envswitch boseurls set` survives `sys reboot`      |
+| ST 20    | foob61451, mcdona1d, TJGigs | #221, #141, #228 | Same; multiple independent reports                                         |
+| ST 300   | mcdona1d                    | #141             | `sys configuration` + `envswitch` + `sys reboot` round-trip                |
+| Wave III | bveenker                    | #221             | URLs accepted; presets work after pairing fallback (§3)                    |
+| Wave IV  | stephan48                   | #221             | Port-17000 path **was the only one that worked** — USB-stick unlock failed |
+
+The exact sequence each reporter ran by hand is the sequence our migration
+sends (§2.1). So the migration's happy path is exercised against five
+hardware variants in independent captures.
+
+### 8.2 Proven to need the pairing fallback
+
+Migration of the URLs themselves works on these models, but
+`POST /setMargeAccount` is missing or wedged on the firmware build, so
+pairing has to go through the telnet `envswitch accountid set <id>` path
+that `setup.PairAccount` already implements.
+
+| Device                         | Reporter | Source                      | Why fallback is needed                                                                                                                                   |
+|--------------------------------|----------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
+| ST Portable / FW 27.0.6        | jmosen   | #236                        | After migration: `POST /marge/streaming/support/power_on` → 502; `<margeAccountUUID/>` empty. Time-bounded HTTP path fails; envswitch fallback succeeds. |
+| BST20 Portable (factory reset) | ubittner | scheilch/opencloudtouch#167 | `<margeAccountUUID/>` empty; `/setMargeAccount` not in `/supportedURLs`. HTTP path skipped entirely; only the telnet fallback works.                     |
+
+### 8.3 Likely to fail (but the failure is clean)
+
+Our preflight + abort-on-first-rejection design (`TestMigrateViaTelnet_CommandNotFoundAborts`)
+means none of these scenarios leave a device half-configured. The user is
+told what failed and pointed to the XML or DNS method.
+
+| Device                                     | Source          | Likely cause                                                                                                                                                                                                                             |
+|--------------------------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **SA-5** (sound amplifier) on FW 9.0.43.x  | soundcork#141   | FW 9.x has a different shell generation: `->` prompt, `local_services on`, `scm uboot_ver`. **`sys configuration` and `envswitch` are not documented as working there.** Migration fails on command #1.                                  |
+| **Recent ST Portable** (post-27.0.6.46330) | #236 (indirect) | `/setMargeAccount` removal points to broader command-set shrinkage. If `envswitch accountid set` is also gone, both migration and pairing fallback fail; user is told to pair via the official Bose app before EOS, or use XML over SSH. |
+
+### 8.4 Unknown — would benefit from real-device verification
+
+| Device                     | Why unknown                                                         | What we'd want to confirm                                                |
+|----------------------------|---------------------------------------------------------------------|--------------------------------------------------------------------------|
+| **ST 30** (`mojo`)         | No concrete capture in any of the six sources                       | Almost certainly works — same FW family as ST 10/20/300 — but unverified |
+| **ST 520 / Home Cinema**   | USB-unlock reports failing (#141), no port-17000 capture either way | Whether `sys configuration` and `envswitch` are exposed at all           |
+| **Wave Music System I/II** | `flarn2006`-era hardware, not seen in 27.x reports                  | Whether port 17000 is even open on those models                          |
+
+### 8.5 The S5 "valid roots" tension
+
+S5 (the r/bose telnet-probing thread) lists only `key`, `net`, `sys`,
+`getpdo` as command roots that don't return "Command not found" on its
+ST 10 / FW 27.0.6 — which would seem to rule out `envswitch`. But foob61451
+on the same hardware/firmware ran `envswitch boseurls set` successfully
+(#221).
+
+The most plausible reading is that **S5 is a non-exhaustive probe**, not a
+negative claim: the author writes "I've made some educated guesses and come
+up with the following valid commands" and never says they tested
+`envswitch`. We do not down-weight `envswitch` availability on the strength
+of S5 alone — but if a real-device run ever shows `envswitch` rejected on
+an ST 10, our preflight catches it, the migration aborts on the first
+non-OK response, and the user gets a clear error rather than partial state.
+
+### 8.6 Failure-mode matrix
+
+What `migrateViaTelnet` does in each failure mode (verified by
+`pkg/telnet` and `pkg/service/setup` unit tests):
+
+| Failure                                        | Outcome                                                                                           | Test                                                                                                               |
+|------------------------------------------------|---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
+| Port 17000 closed / TCP unreachable            | `Dial` errors before any command is sent; UI shows the error; nothing persisted                   | `TestMigrateViaTelnet_DialFailureReturnsError`                                                                     |
+| `sys configuration` rejected (cmd #1)          | Sequence aborts; verification not sent; rest of commands not attempted                            | `TestMigrateViaTelnet_CommandNotFoundAborts` (envswitch variant — generalises)                                     |
+| `envswitch boseurls set` rejected              | Sequence aborts; runtime-only `sys configuration` state reverts on reboot — no permanent damage   | `TestMigrateViaTelnet_CommandNotFoundAborts`                                                                       |
+| Verification mismatch (URLs not echoed back)   | Loud "verification failed" error; live state may persist until reboot but UI never claims success | `TestMigrateViaTelnet_VerifyMismatchFails`                                                                         |
+| `/setMargeAccount` 502 / hang                  | 5s connect + 12s total budget enforced; falls through to telnet `envswitch accountid set`         | `TestPairAccount_FallsBackWhenHTTPReturnsServerError`                                                              |
+| `/setMargeAccount` missing in `/supportedURLs` | HTTP path skipped; goes straight to telnet `envswitch accountid set`                              | `TestPairAccount_FallsBackWhenSetMargeAccountMissing`                                                              |
+| Both pairing paths unavailable                 | Structured error: "use the official Bose app before EOS, or open SSH and use the XML method"      | `TestPairAccount_NoTelnetAndHTTPMissingReturnsClearError`, `TestPairAccount_TelnetCommandNotFoundReportsBothPaths` |
+
+### 8.7 TL;DR
+
+- **Green light** — ST 10, ST 20, ST 300, Wave III, Wave IV on FW 27.0.6 (multi-reporter agreement).
+- **Yellow** — ST Portable and BST20 Portable: migration works, pairing needs our fallback (already implemented).
+- **Red, but fails cleanly** — SA-5 on FW 9.x, possibly newer ST Portable builds.
+- **Unverified but expected to work** — ST 30, ST 520, Wave Music System I/II.
+
+The most useful next verification step is touching a real ST 30 and ST 520
+— those are the two "expected to work" models with zero concrete captures.
+Beyond that, every behaviour the doc predicts is exercised by the unit
+tests in `pkg/telnet` and `pkg/service/setup`.
+
+---
+
+## 9. What actually shipped (post-implementation addendum)
+
+§7 forecast the surface area roughly; the wizard ended up larger. This
+section is the present-day map of the migration tab and the supporting
+backend pieces — kept appended rather than rewritten in place so the
+feasibility analysis above stays a faithful design record.
+
+### 9.1 Three-axis state model
+
+`MigrationSummary` now exposes the four mechanism-specific booleans
+that `checkIsMigrated` writes individually:
+
+- `XMLMigrated` — parsed SoundTouchSdkPrivateCfg.xml's URLs point at us.
+- `HostsMigrated` — `/etc/hosts` carries Bose-domain redirects (the
+  deprecated method, kept detectable for legacy speakers).
+- `ResolvMigrated` — the `/etc/resolv.conf` priority-nameserver hook
+  is in place (with CA trusted).
+- `TelnetMigrated` — `getpdo CurrentSystemConfiguration` reports the
+  service hostname.
+
+`IsMigrated` is the OR. Plus `IsPaired` from the live
+`:8090/info.margeAccountUUID` value.
+
+The frontend opens with a state card that surfaces three orthogonal
+axes derived from these flags:
+
+| Axis              | Verdict semantics                                                                                                     |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------|
+| URL Configuration | URL flip active → ✅; original Bose URLs + DNS hook active → ✅ (intercepted); original + no DNS → ❌ (not intercepted). |
+| DNS Interception  | None / resolv.conf hook / /etc/hosts (with deprecated badge).                                                         |
+| CA / TLS          | Local root CA installed yes/no.                                                                                       |
+
+Plus a Preconditions row: `remote_services` persistence, account
+pairing state, XML config backup presence. Action affordances
+(`Trust CA Now`, `Download CA cert`) live inline next to their verdicts.
+
+### 9.2 Plan card with per-field URL editor
+
+Replaces the XML method's `self/proxied/original` dropdowns and the
+duplicate URL inputs that used to live inside the telnet method pane:
+
+- Target service URL input with `Save as default` (POSTs to
+  `/setup/settings`, preserving the `***` secret-unchanged convention).
+- Capabilities header: detected transports (SSH / Telnet:17000) and
+  the recipes AfterTouch can offer given those transports.
+- Service URLs table: four free-form URL inputs (Marge / Stats /
+  SwUpdate / BmxRegistry) with on-keystroke validation
+  (`validatePlanURLs`), a Soundcork-mode checkbox that flips `/marge`
+  on `margeServerUrl`, and a `Reset to defaults` button.
+- Account pairing section: ID input + Generate + datastore picker;
+  the implicit intent (`readPlanPairTarget`) queues a pair step at
+  Apply when the input differs from the current `account_id`.
+- Suggested plan box: one-click conservative default — XML + HTTP
+  when SSH works, Telnet + HTTP otherwise; "Already migrated" info
+  state when `IsMigrated` is already true.
+
+The per-field URLs feed both XML and Telnet migrations via the
+`marge_url` / `stats_url` / `sw_update_url` / `bmx_url` option family
+(see §9.6). Live preview rewrites `#planned-config` purely client-side
+on every keystroke — optimistic; the backend's perspective gates the
+write via §9.4's pre-flight.
+
+### 9.3 Customize three-axis form
+
+The `<details>` "Customize this migration" section replaces the old
+migration-method dropdown with three independent radio groups:
+
+1. **URL flip transport**: XML / Telnet:17000 / Skip.
+2. **DNS interception**: None / `/etc/resolv.conf` hook.
+3. **Local CA install**: checkbox.
+
+Each option carries a per-axis availability hint
+(`(SSH unreachable)`, `(already trusted)`, etc.) so users see *why*
+an option is disabled. `applyCustomPlan` orchestrates the chosen
+combination as a sequence of existing backend calls
+(`/setup/migrate?method=…` for each flip/resolv step plus
+`/setup/trust-ca` for standalone CA install, and the queued pair
+step from §9.2). Resolv already bundles a CA install, so a redundant
+standalone CA step is skipped. First failure aborts the rest.
+
+### 9.4 Pre-flight panel
+
+Both Apply paths run a visible pre-flight panel before any backend
+operation touches the speaker. Each check renders inline with the
+🕐 / ⟳ / ✅ / ❌ / — idiom. On all-green the panel holds for ~700ms so
+the success state registers, then auto-proceeds. On any failure the
+panel surfaces `Proceed Anyway` / `Cancel` buttons; default is to
+abort.
+
+Checks:
+
+| Check                                 | When                                                       | Backend route                  |
+|---------------------------------------|------------------------------------------------------------|--------------------------------|
+| Backend summary re-check              | always                                                     | `GET /setup/summary`           |
+| HTTPS connection from device          | `ssh_success && server_https_url`                          | `POST /setup/test-connection`  |
+| Reachability check (passive observer) | `telnet_reachable && is_migrated` (see §9.8)               | `POST /setup/peer-probe`       |
+| Round-trip skip explainer             | `telnet_reachable && !is_migrated` — runs after reboot     | _none_ (UI-side skip row)      |
+| DNS redirection from device           | `methods.includes("resolv") && ssh_success`                | `POST /setup/test-dns`         |
+
+The HTTPS check uses `use_explicit_ca=true` so it exercises the trust
+path even when CA install is part of the plan (i.e. forward-looking).
+The reachability skip row is explicit ("neither SSH nor Telnet:17000
+is reachable") rather than silently dropped, per the user's
+"feedback always visible" requirement.
+
+### 9.5 Telnet round-trip probe — the SSH-less reachability check
+
+> **REMOVED — see §9.8.** Empirical testing showed the swUpdate
+> daemon caches its target URL at boot and ignores live config
+> writes, so the active flip described below could never reach the
+> running daemon. The section is retained as a historical record of
+> what was tried; the running code uses the passive observer in §9.8.
+
+The reachability gap §7 left open for USB-unlock-refusing speakers is
+closed by `Manager.RunTelnetRoundTripProbe`
+(`pkg/service/setup/telnet_probe.go`). Sequence:
+
+1. Telnet `getpdo CurrentSystemConfiguration` to capture the
+   speaker's current `swUpdateUrl`.
+2. Generate a random 24-hex-char token; register a one-shot signal
+   channel under it on the new `probeRegistry` (sibling field on
+   `handlers.Server`).
+3. Telnet `sys configuration swUpdateUrl <targetURL>/probe/<token>`
+   — **runtime layer only, deliberately not `envswitch boseurls set
+   …`**. The persistence layer keeps the original URL, so a reboot
+   heals the device naturally if our restore step fails.
+4. `HTTP GET <deviceIP>:8090/swUpdateCheck` — the cleanest
+   `:8090` endpoint that triggers exactly one outbound to the
+   configured `swUpdateUrl`. Read-only on the cloud side
+   (doesn't initiate an update); independent of `margeAccountUUID`
+   so it works on factory-reset speakers.
+5. Wait on the registered channel up to `telnetProbeTimeout` (6s).
+6. Telnet `sys configuration swUpdateUrl <originalURL>` — deferred
+   restore so it runs even on the failure path.
+
+The new `/probe/{token}[/*]` catch-all on the root router signals the
+matching channel when the speaker's outbound lands. The response is
+a minimal `<swUpdateIndex/>` so the speaker's `swUpdateCheck`
+doesn't choke on a missing structure. The `/*` sub-path is
+registered because some firmware appends a path component to the
+configured `swUpdateUrl`.
+
+### 9.6 Backend additions worth knowing
+
+| Addition                                                               | Where                                        | Why                                                                                                                                                                          |
+|------------------------------------------------------------------------|----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `applyURLOverrides(cfg, options)`                                      | `pkg/service/setup/setup.go`                 | Per-field literal `marge_url` / `stats_url` / `sw_update_url` / `bmx_url` overrides win over `applyProxyOptions`. Honored by both `GetMigrationSummary` and `migrateViaXML`. |
+| `telnetURLsFromOptions(targetURL, options)`                            | `pkg/service/setup/telnet_migration.go`      | Same option family as above, plus envswitch arg derivation rule (arg1 = final Marge verbatim; the soundcork-suffix case drops out).                                          |
+| Per-axis booleans + `IsPaired` + `Warnings`                            | `MigrationSummary`                           | Surfaces partial-state cells and SSH-XML ⇄ telnet-getpdo cross-check disagreements.                                                                                          |
+| `parseGetpdoConfig`                                                    | `pkg/service/setup/preflight_crosscheck.go`  | Parses the Protobuf-text-like nested-block reply (`key { text: "..." }`) FW 27.0.6 actually sends, plus the legacy `key=value` shape as a tolerance path.                    |
+| `peerObserver` + `RunPeerReachabilityProbe` + `/setup/peer-probe`      | `pkg/service/handlers` / `pkg/service/setup` | §9.8. Replaces the removed `probeRegistry` + `RunTelnetRoundTripProbe` + `/setup/telnet-probe` from §9.5.                                                                     |
+| `migrationOptionKeys` allow-list                                       | `pkg/service/handlers/migration_options.go`  | Unknown query keys never reach the manager. Both XML mode keys and `*_url` keys are recognised.                                                                              |
+| Telnet client default timeouts: dial 4s, read 7s, write 3s, idle 600ms | `pkg/telnet/telnet.go`                       | Bumped from the original 2s/5s/2s/400ms after observing transient i/o-timeout flakes on healthy speakers that recovered on retry.                                            |
+
+### 9.7 Future probe candidates
+
+- `:8090/pushCustomerSupportInfoToMarge` — flagged as a potential
+  "ask the device about itself" probe that could feed a richer
+  device-info pane (firmware build dates, hardware revisions). Not
+  implemented.
+- Running the round-trip probe on SSH-capable speakers too (as
+  additional validation alongside the curl-from-device HTTPS test),
+  not just as the SSH-less fallback it is today. **Subsumed by §9.8
+  — the round-trip probe is being removed; the passive observer is
+  transport-agnostic and replaces it for migrated speakers.**
+
+### 9.8 The swUpdate daemon-cache finding and removal of §9.5
+
+The §9.5 round-trip probe was retired after empirical testing on a
+fully-migrated speaker (FW 27.0.6) revealed that the `swUpdate`
+daemon **caches its target URL at boot and ignores live config
+writes**. The diagnostic sequence:
+
+1. Manual telnet flip of both layers — `sys configuration swUpdateUrl
+   <probe-url>` (runtime) **and** `envswitch boseurls set <marge>
+   <probe-url>` (persistence). `getpdo CurrentSystemConfiguration`
+   confirmed both writes stuck.
+2. HTTP GET `:8090/swUpdateCheck` to trigger fan-out.
+3. Service access log showed the device outbound landed on
+   `/updates/soundtouch` (the **previous** `swUpdateUrl` value, current
+   at the last daemon boot) and `/streaming/software/update/account/<id>`
+   (a separate Bose URL the daemon hits, routed to this service by DNS
+   interception). The probe URL was never dialed.
+
+This falsifies the original NEXT.md hypothesis that the persistence
+layer would override the runtime layer for the daemon's fan-out, and
+points instead at daemon-level URL caching. Two consequences:
+
+- **The §9.5 probe cannot work on migrated speakers without a
+  reboot.** The cached URL is set when the daemon starts; flipping
+  config after that point has no effect on what the daemon dials.
+- **The §9.5 probe likely cannot work on unmigrated speakers
+  either**, for the same reason — the daemon caches whatever URL it
+  read at startup, which on an unmigrated speaker is the Bose cloud
+  URL. We have no service running with the probe URL registered on
+  unmigrated speakers, so the original "it worked in testing" claim
+  has no empirical basis; it likely failed silently because nothing
+  was watching.
+
+The honest replacement is a **passive observer** (see
+`pkg/service/setup/peer_probe.go`):
+
+1. Register the device IP with an in-process observer
+   (`handlers.peerObserver`, wired via `PeerObserverMiddleware`).
+2. Nudge `:8090/swUpdateCheck` to make the daemon fan out *something*
+   sooner than its ~5min timer.
+3. Wait up to 30s for any inbound from that IP. On a migrated
+   speaker, DNS interception means the daemon's outbounds (update
+   fan-out, marge polls, BMX registry calls) all funnel through this
+   service regardless of which URL the daemon resolved internally —
+   so reachability reduces to *"did the device dial us at all."*
+
+Endpoint: `POST /setup/peer-probe/{deviceId}`. No device-state
+mutation; safe to re-run. Returns `{ok, result: {reached,
+observed_path, elapsed_ms}, error}` with the same UI keying as the
+old probe (`result.reached`).
+
+#### 9.8.1 The pre-flight panel branch
+
+The web UI's pre-flight orchestrator (`runApplyPreflight` in
+`script.js`) branches on `summary.is_migrated`:
+
+| Migration state                   | Reachability row                                                                                                             |
+|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| Migrated (`is_migrated=true`)     | "Reachability check (passive observer)" — calls `POST /setup/peer-probe/{deviceId}`.                                         |
+| Not migrated (incl. partial)      | Skip row "Round-trip validation runs after Apply + reboot" with the rationale "daemon caches swUpdateUrl at boot".           |
+
+Per-axis booleans (`xml_migrated`, `hosts_migrated`, `resolv_migrated`,
+`telnet_migrated`) remain visible in the State card, so the user can
+see which parts of the migration are already in place even when the
+overall flag is false. The skip row does not attempt the active probe
+on unmigrated speakers — the canonical telnet flow is:
+
+```
+Apply telnet config → user-initiated reboot → re-run pre-flight on
+the now-migrated speaker → passive observer confirms fan-out.
+```
+
+#### 9.8.2 Removal trail
+
+Removed (or scheduled for removal in a follow-up commit) at the time
+of §9.8 landing:
+
+- `pkg/service/setup/telnet_probe.go` — `RunTelnetRoundTripProbe`,
+  `ProbeRegistrar`, `TelnetProbeResult`, `generateProbeToken`.
+- `pkg/service/handlers/handlers_telnet_probe.go` — `HandleTelnetProbe`,
+  `HandleProbeInbound`, `telnetProbeTimeout`, `telnetProbeResponse`.
+- `pkg/service/handlers/probe_registry.go` — `probeRegistry` + tests.
+- `Server.probes` field.
+- Routes `/probe/{token}`, `/probe/{token}/*`, `/setup/telnet-probe/{deviceId}`.
+- The `target_url` query-param plumbing on the deprecated endpoint.
+- `script.js` — `checkTelnetRoundTrip` (orchestrator call site removed
+  in the commit that added the branch; function itself removed later).
+
+`isCommandNotFound` and `parseGetpdoConfig` stay — they are also used
+by the migration writer (`telnet_migration.go`), preflight reader
+(`telnet_preflight.go`), pairing path (`marge_pairing.go`), and
+cross-check (`preflight_crosscheck.go`).

docs/analysis/bose-soundtouch-community-tools.md

@@ -0,0 +1,297 @@
+# Bose SoundTouch — Community Tools for Post-EOL Preservation
+
+> **Context:** Bose announced the shutdown of SoundTouch cloud services, extended to **May 6, 2026**. On that date the official SoundTouch app will update to a local-only version. Bose has released the [SoundTouch Web API documentation](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf) as open-source to enable community-driven development. This document surveys the active community projects, their feature coverage, and open development opportunities.
+
+---
+
+## What Bose Is Doing
+
+After the May 6, 2026 shutdown, the following will **continue to work**:
+
+- Streaming via Bluetooth, AirPlay, Spotify Connect, and AUX
+- Local device control and grouping via an updated SoundTouch app
+- Remote control features (play, pause, skip, volume)
+- HDMI/optical connections on soundbars
+
+The following will **stop working**:
+
+- Physical and app-based presets
+- In-app music service browsing (TuneIn, Pandora, etc.)
+- Stereo pairing for SoundTouch 10
+- Security and firmware updates
+
+---
+
+## Community Projects
+
+### 1. soundcork
+**[github.com/deborahgu/soundcork](https://github.com/deborahgu/soundcork)**
+| | |
+|---|---|
+| Language | Python |
+| License | MIT |
+| Stars | 111 |
+| Contributors | 8 |
+| Commits | 287 |
+| Status | Pre-alpha, actively developed |
+
+A reverse-engineered intercept API that replaces the Bose cloud servers locally. Works by redirecting the speaker's internal `SoundTouchSdkPrivateCfg.xml` to a self-hosted FastAPI server, emulating the `marge` server (required for basic network functionality) and the `bmx` server (required for TuneIn). Deployable as a Docker container or systemd daemon. The most community-engaged project, with a dedicated discussion thread tracking Bose cloud service status.
+
+---
+
+### 2. Überböse API
+**[github.com/julius-d/ueberboese-api](https://github.com/julius-d/ueberboese-api)**
+| | |
+|---|---|
+| Language | Java (Spring Boot) |
+| License | MIT |
+| Stars | 10 |
+| Contributors | 1 |
+| Commits | 224 |
+| Tags/Releases | 163 |
+| Documentation | [julius-d.github.io/ueberboese-api](https://julius-d.github.io/ueberboese-api/) |
+
+Reverse-engineers and rebuilds the Bose streaming HTTP API. Unique in publishing a machine-readable OpenAPI specification (`ueberboese-api.yaml`) and comprehensive request logging — making it the best research instrument for understanding what speakers actually call upstream. Implements Spotify OAuth integration and TuneIn. Companion to the Überböse App.
+
+---
+
+### 3. Überböse App
+**[github.com/julius-d/ueberboese-app](https://github.com/julius-d/ueberboese-app)**
+| | |
+|---|---|
+| Language | Flutter (Dart) |
+| License | MIT |
+| Latest version | 0.26.0 (March 2026) |
+| Distribution | [F-Droid](https://f-droid.org/en/packages/io.github.juliusd.ueberboese.app/) |
+| Platform | Android |
+
+The only native installable phone app in the ecosystem. Pairs with the Überböse API server. Features: preset view/play/reprogram, multi-room zone management, volume control, now-playing display, Spotify authentication setup. Controls speakers directly via the local SoundTouch WebServices API (no server required for basic control).
+
+---
+
+### 4. SoundTouch Hybrid 2026
+**[github.com/TJGigs/Bose-SoundTouch-Hybrid-2026](https://github.com/TJGigs/Bose-SoundTouch-Hybrid-2026)**
+| | |
+|---|---|
+| Language | Node.js (JavaScript) |
+| License | — |
+| Stars | 1 |
+| Commits | 3 (V1) / 12 (V3) |
+| Status | Experimental / testing |
+
+A self-hosted private cloud that emulates and replaces the Bose Cloud Service. Runs locally on a NAS or PC, intercepts the complex server handshakes needed to keep the SoundTouch infrastructure functional. Relies on **Music Assistant** for backend audio routing and provider aggregation. Features a setup wizard including USB config generation (`OverrideSdkPrivateCfg.xml`) and an on-screen Bose Cloud Emulation Setup guide. Targets users who want the broadest streaming provider support via Music Assistant's ecosystem.
+
+---
+
+### 5. OpenCloudTouch (OCT)
+**[github.com/scheilch/opencloudtouch](https://github.com/scheilch/opencloudtouch)**
+| | |
+|---|---|
+| Language | Python (FastAPI) + TypeScript (React) |
+| License | Apache 2.0 |
+| Stars | 9 |
+| Commits | 313 |
+| Latest release | v1.1.1 (April 12, 2026) |
+| Documentation | GitHub Wiki (EN/DE) |
+
+A single Docker container combining a FastAPI backend and React frontend. The most production-ready project in the ecosystem in terms of release discipline and deployment accessibility. Features: internet radio with full hardware preset support (buttons 1–6), responsive web UI, device discovery via SSDP/UPnP, multi-room zone management, BMX-compatible endpoints, TuneIn stream resolver, RadioBrowser as a built-in first-class search provider, and pre-built Raspberry Pi SD card images for Pi 3/4/5. Deployable on amd64, arm64, and arm/v7. Documented in English and German. Spotify and Music Assistant integration are on the roadmap.
+
+---
+
+### 6. AfterTouch
+**[github.com/gesellix/Bose-SoundTouch](https://github.com/gesellix/Bose-SoundTouch)** by gesellix
+| | |
+|---|---|
+| Language | Go |
+| License | MIT |
+| Stars | 16 |
+| Contributors | 2 |
+| Commits | 217 |
+| Releases | 51 (latest: v0.28.0, Feb 15, 2026) |
+| Documentation | [gesellix.github.io/Bose-SoundTouch](https://gesellix.github.io/Bose-SoundTouch/) |
+
+The most comprehensive single toolkit in the ecosystem. Comprises three components: a Go library (importable package), a CLI (`soundtouch-cli`), and a local cloud emulation service (`soundtouch-service`). Covers the widest range of dimensions of any single project. Implements the complete Bose Spotify OAuth relay including surrogate secret generation and token refresh proxy. Includes a built-in DNS server for device redirection without SSH, HTTPS/custom CA injection, HTTP session recording, traffic proxy/logging, and a web management UI. Tested on real SoundTouch 10 and 20 hardware. Has a Patreon for ongoing support.
+
+---
+
+### 7. soundcork-stockholm-app
+**[github.com/krahl/soundcork-stockholm-app](https://github.com/krahl/soundcork-stockholm-app)**
+| | |
+|---|---|
+| Language | Java |
+| License | — |
+| Stars | 2 |
+| Commits | 21 |
+| Status | Active development, bugs expected |
+
+A Java-based middleware that hosts the original Bose Stockholm frontend (extracted from the APK) in a local web browser at `http://127.0.0.1:8088/`. Bridges the Stockholm UI to local speakers via an HTTP proxy that resolves cross-origin issues, with SSDP-based device discovery and JSON state persistence. Unlike every other tool in the ecosystem, it runs the **official Bose UI** rather than a custom replacement — preserving the familiar Bose UX at the cost of requiring the Stockholm APK. Notable limitations: OAuth flows are unreliable, and WebSocket connections to speakers over HTTPS have blocking issues. Works alongside soundcork's backend for full cloud emulation.
+
+---
+
+### 8. jaas666/bose-soundtouch-web-api (Reference)
+**[github.com/jaas666/bose-soundtouch-web-api](https://github.com/jaas666/bose-soundtouch-web-api)**
+
+Community-maintained Markdown conversion of the official Bose SoundTouch Web API PDF (v1.0, January 7, 2026). Useful as a developer reference. Not a deployable tool.
+
+---
+
+## Feature Coverage Matrix
+
+Legend: ● Yes/complete · ◑ Partial/planned · ○ No
+
+| Dimension                                          | soundcork | Überböse API | Überböse App | ST Hybrid 2026 | OpenCloudTouch | AfterTouch | Stockholm App |
+|----------------------------------------------------|:---------:|:------------:|:------------:|:--------------:|:--------------:|:----------:|:-------------:|
+| **① App layer — local HTTP/WS control**            |           |              |              |                |                |            |               |
+| Playback control (play/pause/vol)                  |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Preset view & trigger                              |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Preset write / reprogram                           |     ○     |      ○       |      ●       |       ●        |       ◑        |     ●      |       ●       |
+| Multi-room zone management                         |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Now playing / status display                       |     ○     |      ○       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Device discovery (SSDP/mDNS)                       |     ○     |      ○       |      ●       |       ○        |       ●        |     ●      |       ●       |
+| WebSocket real-time events                         |     ○     |      ○       |      ◑       |       ●        |       ◑        |     ●      |       ◑       |
+| **② Cloud/service layer — replaces Bose upstream** |           |              |              |                |                |            |               |
+| Marge server emulation                             |     ●     |      ●       |      ○       |       ●        |       ○        |     ●      |       ○       |
+| BMX / content registry                             |     ◑     |      ◑       |      ○       |       ●        |       ●        |     ●      |       ○       |
+| Account / OAuth token relay                        |     ○     |      ●       |      ○       |       ◑        |       ○        |     ●      |       ◑       |
+| Preset sync (cloud-side)                           |     ●     |      ●       |      ○       |       ●        |       ○        |     ●      |       ○       |
+| Recents sync                                       |     ●     |      ◑       |      ○       |       ◑        |       ○        |     ●      |       ○       |
+| Sources / device info persistence                  |     ●     |      ●       |      ○       |       ●        |       ○        |     ●      |       ○       |
+| Stereo group CRUD (ST10 pairs)                     |     ●     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| **③ Device redirection — USB/SSH setup**           |           |              |              |                |                |            |               |
+| Setup wizard / guided redirect                     |     ◑     |      ◑       |      ○       |       ●        |       ●        |     ●      |       ○       |
+| USB image / config generation                      |     ○     |      ○       |      ○       |       ●        |       ○        |     ◑      |       ○       |
+| HTTPS / custom CA support                          |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| **④ Streaming provider integration**               |           |              |              |                |                |            |               |
+| Internet radio (RadioBrowser)                      |     ○     |      ◑       |      ◑       |       ◑        |       ●        |     ◑      |       ○       |
+| TuneIn stream resolver                             |     ●     |      ●       |      ●       |       ●        |       ●        |     ●      |       ●       |
+| Spotify OAuth / Connect                            |     ○     |      ●       |      ●       |       ◑        |       ◑        |     ●      |       ◑       |
+| Pandora                                            |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ◑       |
+| Music Assistant backend                            |     ○     |      ○       |      ○       |       ●        |       ◑        |     ○      |       ○       |
+| **⑤ Mobile / native app**                          |           |              |              |                |                |            |               |
+| Android app (installable)                          |     ○     |      ○       |      ●       |       ○        |       ○        |     ○      |       ○       |
+| iOS app                                            |     ○     |      ○       |      ○       |       ○        |       ○        |     ○      |       ○       |
+| Mobile-responsive web UI                           |     ○     |      ○       |      ○       |       ●        |       ●        |     ●      |       ●       |
+| **⑥ Smart home / ecosystem integration**           |           |              |              |                |                |            |               |
+| Home Assistant integration                         |     ○     |      ○       |      ○       |       ○        |       ○        |     ◑      |       ○       |
+| Music Assistant integration                        |     ○     |      ○       |      ○       |       ●        |       ◑        |     ○      |       ○       |
+| **⑦ CLI / automation tools**                       |           |              |              |                |                |            |               |
+| CLI for scripting / automation                     |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| Traffic proxy / API logging                        |     ◑     |      ●       |      ○       |       ○        |       ○        |     ●      |       ◑       |
+| HTTP session recording                             |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| **⑧ Library / SDK**                                |           |              |              |                |                |            |               |
+| Importable library / package                       |     ○     |      ○       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| Published API spec / docs                          |     ○     |      ●       |      ○       |       ○        |       ○        |     ●      |       ○       |
+| Docker deployment                                  |     ●     |      ●       |      ○       |       ●        |       ●        |     ●      |       ●       |
+| Raspberry Pi SD card image                         |     ○     |      ○       |      ○       |       ○        |       ●        |     ○      |       ○       |
+
+---
+
+## Making AfterTouch the One-Stop Solution — Open Tasks
+
+AfterTouch is the strongest single project across the service and developer layers. Its remaining gaps are on the consumer-facing and ecosystem-integration sides.
+
+### Priority 1 — PWA installability
+
+The web UI is already fully responsive — it has Bootstrap grid columns, `@media (max-width: 768px)` and `@media (max-width: 576px)` breakpoints, and a proper viewport meta tag. It works on iPhone and Android browsers today. What's missing is **installability**: no `manifest.json` and no service worker, so it cannot be added to the home screen as a standalone app. Adding these would close the iOS app gap ecosystem-wide (no project has an iOS app) at minimal effort.
+
+### Priority 2 — RadioBrowser as a first-class provider
+
+AfterTouch can proxy and play any stream URL, but there is no built-in station search. OpenCloudTouch's RadioBrowser integration is the reference. Tasks:
+- Wire the [RadioBrowser API](https://www.radio-browser.info/) into the `soundtouch-web` web UI as a browsable/searchable source.
+- Make discovered stations directly presetable to hardware buttons.
+- This is the most common replacement for TuneIn for users who listened to internet radio via presets.
+
+### Priority 3 — Raspberry Pi SD card image
+
+OpenCloudTouch ships a flashable Pi image and it dramatically lowers the barrier for the most common "always-on local server" deployment. AfterTouch already has Docker and a web management UI; this is largely a CI/packaging task:
+- Build a Pi image (using e.g. `pi-gen` or `rpi-imager`-compatible tooling) that boots directly into `soundtouch-service`.
+- Auto-starts on boot, auto-discovers devices, opens the web UI on a known port.
+- Target Pi 3/4/5 with amd64/arm64/arm/v7 variants (mirroring OCT's approach).
+
+### Priority 4 — USB config generation in the web UI
+
+AfterTouch modifies `SoundTouchSdkPrivateCfg.xml` via SSH (`pkg/service/setup/setup.go`) and documents the redirect process thoroughly, but does not yet generate the USB stick content for users without SSH access. A "prepare USB stick" button in the web UI would remove the last manual step:
+- Generate `OverrideSdkPrivateCfg.xml` pre-populated with the running server's URL.
+- Optionally include the custom CA certificate for HTTPS-capable devices.
+- Surface alongside the existing guided migration wizard.
+
+### Priority 5 — Music Assistant integration
+
+SoundTouch Hybrid 2026 uses Music Assistant as its streaming backend, giving access to Apple Music, Deezer, local libraries, and many other providers. A formal Music Assistant **player provider** for AfterTouch would give power users a path to sources beyond Spotify, TuneIn, Pandora, and RadioBrowser. The Music Assistant community has an open discussion thread on this ([#4766](https://github.com/orgs/music-assistant/discussions/4766)).
+
+### Priority 6 — DNS-based migration documentation
+
+AfterTouch includes a built-in DNS server (`ENABLE_DNS_DISCOVERY`, `DNS_BIND_ADDR`, `DNS_UPSTREAM`) that intercepts `*.bose.com` queries and forwards everything else upstream — no Pi-hole, AdGuard, or any other external tool required. The ResolvConf migration path already treats DNS as a first-class option. The remaining gap is awareness: users unfamiliar with the project may not realise no external DNS infrastructure is needed. Tasks:
+- Surface the built-in DNS server more prominently in the getting-started documentation.
+- Document Pi-hole / AdGuard Home as an *alternative* for users who already run those, not a requirement.
+
+### Priority 7 — MQTT integration
+
+A design document exists (`docs/guides/MQTT-INTEGRATION-DESIGN.md`) but no code has been written. Implementing it would unlock home automation use cases without requiring the full Home Assistant stack — enabling triggers like "play preset 1 when front door opens" via any MQTT-capable automation platform.
+
+---
+
+## soundcork ↔ AfterTouch
+
+soundcork and AfterTouch share the most functional overlap of any two projects in the ecosystem. For the implementation-level parity analysis and remaining tasks see [docs/PARITY-SOUNDCORK.md](../PARITY-SOUNDCORK.md).
+
+### Architectural differences (not gaps)
+
+These exist in soundcork but are deliberate architectural choices in AfterTouch, not missing features:
+
+| Area                     | soundcork                             | AfterTouch                                                |
+|--------------------------|---------------------------------------|-----------------------------------------------------------|
+| Web UI                   | FastAPI + Jinja2 miniapp and admin UI | Separate `soundtouch-web` component (Go + plain HTML/JS)  |
+| Direct device management | SSH/SCP access into speakers          | HTTP API only; no SSH                                     |
+| Device discovery client  | Python `upnpclient` library           | mDNS + UPnP in Go, with dedicated DNS interception server |
+| Token delivery           | Push (ZeroConf priming to port 8200)  | Pull (device calls back to fetch)                         |
+| Persistence format       | Flat files                            | XML flat files + atomic writes                            |
+
+### AfterTouch capabilities soundcork lacks
+
+| Feature                                   | Notes                                                           |
+|-------------------------------------------|-----------------------------------------------------------------|
+| DNS server for device redirect            | Intercepts Bose domain queries; no Pi-hole required             |
+| HTTPS / custom CA injection               | Full TLS with certificate generation and trust workflow         |
+| HTTP interaction recording & replay       | Captures real device traffic for debugging and regression tests |
+| Device migration (serial → MAC path)      | Handles legacy device ID formats automatically                  |
+| Transparent proxy mode with upstream sync | Can mirror to real Bose cloud while running locally             |
+| CLI (`soundtouch-cli`)                    | Scriptable control of speakers                                  |
+| Importable Go library                     | `github.com/gesellix/bose-soundtouch/pkg/client`                |
+
+---
+
+
+
+### Ecosystem fragmentation vs. convergence
+
+The community is currently covering different parts of the problem in parallel rather than converging. AfterTouch explicitly credits soundcork, Überböse, and SoundTouch Plus in its README and describes its `soundtouch-service` as "heavily inspired by SoundCork". There is an opportunity — and arguably a need — for these projects to formally coordinate: shared test fixtures, a common compatibility matrix against specific firmware versions, and agreed-on API contracts would all reduce duplicated effort.
+
+### Firmware version sensitivity
+
+The SoundTouch 10 is most dependent on Marge for basic network functionality; the 20 and 30 are somewhat more tolerant. Compatibility across firmware versions is not systematically documented anywhere. A community firmware compatibility matrix (model × firmware version × which emulation features work) would be high value and is currently missing.
+
+### Security posture
+
+All projects warn that speakers should only be used on a private, firewalled network after cloud shutdown. AfterTouch is the only project to implement HTTPS/custom CA, which matters if devices are ever on a network where traffic could be inspected. soundcork's SECURITY.md explicitly warns against running on open networks.
+
+### No iOS app — a structural gap
+
+The original SoundTouch app was iOS-first. Every community replacement is Android-only (Überböse App) or browser-based. This is the largest unaddressed user segment in the ecosystem.
+
+### Bose's open-source move as a precedent
+
+Bose's decision to release API documentation rather than simply shutting down is notable — it mirrors what Pebble users did themselves with Rebble after that shutdown, but here the manufacturer initiated it. This sets a useful precedent and gives the community a solid legal and technical foundation to build on.
+
+### Related community resources
+
+- [Bose SoundTouch Plus (Home Assistant component)](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus) — comprehensive HA integration by Todd Lucas, extensive API wiki
+- [Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook) — `LD_PRELOAD`-based reverse engineering framework used by AfterTouch for protocol research
+- [Bose SoundTouch Web API (community Markdown)](https://github.com/jaas666/bose-soundtouch-web-api) — official API PDF converted to Markdown
+- [Bose Wiki — SoundTouch App Alternatives](https://bose.fandom.com/wiki/SoundTouch_app_alternatives) — community-maintained living list of workarounds and projects
+- [Reddit megathread — Bose alternatives](https://www.reddit.com/r/bose) — ongoing community discussion
+- [Radio Browser](https://www.radio-browser.info/) — the free, community-maintained internet radio directory used as a TuneIn replacement
+
+---
+
+*Document compiled April 2026. Project details sourced directly from GitHub repositories and official documentation. Star counts, commit counts, and release dates reflect the state at time of writing and will change as projects evolve. soundcork-stockholm-app added April 2026.*

docs/concepts/amazon-music-oauth.md

@@ -0,0 +1,369 @@
+# Amazon Music OAuth Integration
+
+This document describes the plan and specification for adding Amazon Music OAuth support to the SoundTouch service, enabling continued Amazon Music playback after the Bose cloud shutdown (May 2026).
+
+The implementation mirrors the [Spotify OAuth integration](spotify-oauth.md) closely. Read that document first — this one calls out only the differences.
+
+## Status
+
+**Infrastructure complete — streaming blocked by API access.**
+
+All eight implementation steps are done. The OAuth flow (account linking, token storage, token refresh) works end-to-end with a standard Login with Amazon app. Token exchange (`/oauth/device/.../token/cs1`) succeeds and the speaker receives a valid `Atza|` access token.
+
+However, real-world testing shows that the speaker then calls `https://music-api.amazon.com/` with that token and receives a `401 Unauthorized` (no redirect to a regional endpoint). This means the token does not carry the scopes required to access the Amazon Music streaming API.
+
+**Root cause (confirmed):** Amazon Music streaming requires the `amazon_music:access` scope, which is only available to **device client IDs** — a separate credential type obtained through Amazon's Music partner programme. Standard Login with Amazon application client IDs (`amzn1.application-oa2-client.*`) cannot request this scope: attempting to include it in the authorization URL returns `lwa-invalid-parameter-bad-scope` (HTTP 400) from the LWA authorization endpoint. Bose would have held a device client ID as a registered Amazon Music partner.
+
+**What still works:**
+- Account linking and token storage
+- Token refresh (the service correctly exchanges the refresh token for a fresh access token)
+- Marge source registration (the speaker sees Amazon Music as a configured source)
+
+**What does not work:**
+- Actual music playback — the speaker's `AmazonClient` cannot authenticate to `music-api.amazon.com` with a standard LWA token
+
+**Path forward:** Obtaining a device client ID requires registering with Amazon's Music partner programme. If such a credential is obtained, the only code change needed is swapping the `client_id`/`client_secret` for the device credentials and adding `amazon_music:access` to `AmazonScopes` in `pkg/service/amazon/service.go` — everything else is already in place. The `site_id` field is a secondary open question that may also affect regional routing once the scope issue is resolved.
+
+---
+
+## Secret Format (confirmed from a live Bose system)
+
+A real Amazon source entry from a migrated device's `Sources.xml`:
+
+```xml
+<source secretType="token">
+    <credential type="token">{"AmazonSecret":{"refresh_token":"Atzr|...","site_id":"1464855981"}}</credential>
+    <sourceKey type="AMAZON" account="user@example.com"/>
+</source>
+```
+
+Key observations:
+
+- **Secret envelope**: `{"AmazonSecret":{"refresh_token":"...","site_id":"..."}}` — JSON-encoded, HTML-entity-escaped in XML attributes, stored as the credential value.
+- **`Atzr|` prefix**: This is the standard Amazon LWA (Login with Amazon) refresh token prefix from the **authorization code grant** — confirming that Web OAuth is the correct flow, not CBL.
+- **`site_id`**: A numeric string (`"1464855981"`). Origin is not yet fully confirmed; candidates are:
+  - A static Bose partner identifier baked into the Bose app/firmware (same value for all users), or
+  - A per-user Amazon Music identifier returned by a Music API device registration call.
+  - Needs verification — possibly obtained by calling the Amazon Music API after initial authentication.
+- **`account` field**: The user's Amazon email address (obtained from the LWA `/user/profile` endpoint).
+
+When `HandleBoseAmazonToken` receives a refresh request from the speaker, it must:
+1. Parse the `AmazonSecret` JSON from the stored credential to extract `refresh_token`.
+2. Call the LWA token endpoint with a `refresh_token` grant.
+3. Return the fresh `access_token` to the speaker.
+4. Persist the rotated `refresh_token` back into the `AmazonSecret` envelope.
+
+---
+
+## How the Speaker Uses This
+
+When the SoundTouch firmware tries to play Amazon Music after migration, it sends a token refresh request to the local service:
+
+```
+POST /oauth/device/{deviceID}/music/musicprovider/20/token/cs1
+```
+
+The service must respond with a fresh Amazon access token. The speaker then uses that token directly with Amazon's playback infrastructure.
+
+The `cs1` suffix (credential schema 1) is Amazon-specific; Spotify uses `cs3`. This route is already registered.
+
+> **DNS note:** The speaker constructs the OAuth hostname by appending `oauth` to the streaming service subdomain. If the service is reachable at `myhost.local`, the speaker will call `myhostoauth.local`. A DNS alias pointing `myhostoauth.<domain>` to the same IP as the service is required.
+
+---
+
+## OAuth Flows
+
+### 1. Browser-based Flow
+
+```mermaid
+sequenceDiagram
+    participant Client as Client (curl/app)
+    participant Service as Service
+    participant Amazon as Amazon Auth Server (LWA)
+    participant Browser as User's Browser
+
+    Client->>Service: POST /mgmt/amazon/init [Basic Auth]
+    Service-->>Client: {"redirectUrl": "https://www.amazon.com/ap/oa?..."}
+
+    Client->>Browser: User opens URL
+    Browser->>Amazon: User logs in & grants access
+    Amazon-->>Browser: Redirect to /mgmt/amazon/callback?code=abc
+
+    Browser->>Service: GET /mgmt/amazon/callback?code=abc
+    Note over Service: No auth needed for callback
+
+    Service->>Amazon: POST /auth/o2/token (exchange code)
+    Amazon-->>Service: {access_token, refresh_token}
+
+    Service->>Amazon: GET /user/profile (fetch profile)
+    Amazon-->>Service: {user_id, name, email}
+
+    Note over Service: Store account to disk
+
+    Service-->>Browser: HTML: "Amazon Music Connected. You can close this window."
+```
+
+### 2. Mobile App Flow (ueberboese)
+
+```mermaid
+sequenceDiagram
+    participant App as ueberboese Flutter App
+    participant Service as Service
+    participant Amazon as Amazon Auth Server (LWA)
+
+    App->>Service: POST /mgmt/amazon/init [Basic Auth]
+    Service-->>App: {"redirectUrl": "https://www.amazon.com/ap/oa?..."}
+
+    App->>Amazon: Open in-app browser (User authorizes)
+    Amazon-->>App: Deep link redirect: ueberboese-login://amazon?code=abc
+
+    App->>Service: POST /mgmt/amazon/confirm?code=abc [Basic Auth]
+
+    Service->>Amazon: POST /auth/o2/token (exchange code)
+    Amazon-->>Service: {access_token, refresh_token}
+
+    Service->>Amazon: GET /user/profile (fetch profile)
+    Amazon-->>Service: {profile}
+
+    Service-->>App: {"ok": true}
+```
+
+### 3. Token Retrieval (Speaker Token Refresh)
+
+```mermaid
+sequenceDiagram
+    participant Speaker as SoundTouch Speaker
+    participant Service as Service
+    participant Amazon as Amazon Token API (LWA)
+
+    Speaker->>Service: POST /oauth/device/{deviceID}/music/musicprovider/20/token/cs1
+    Note over Service: Body contains stored AmazonSecret JSON;<br/>extract refresh_token from {"AmazonSecret":{...}}
+
+    alt Token expired or near expiry
+        Service->>Amazon: POST /auth/o2/token (refresh_token grant, body credentials)
+        Amazon-->>Service: {access_token, refresh_token, expires_in}
+        Note over Service: Persist rotated refresh_token back into AmazonSecret envelope
+    end
+
+    Service-->>Speaker: {"access_token": "...", "token_type": "Bearer", "expires_in": 3600}
+```
+
+---
+
+## Implementation Steps
+
+### Step 1 — Extract ZeroConf into a shared package
+
+**Why first:** The DH-blob encryption in `pkg/service/spotify/zeroconf.go` is entirely provider-agnostic. Extracting it to `pkg/service/zeroconf/` before adding Amazon avoids duplicating ~200 lines of crypto code.
+
+**What changes:**
+- Create `pkg/service/zeroconf/zeroconf.go` — move `generateDHKeyPair`, `computeSharedSecret`, `deriveKeys`, `buildCredentialsBlob`, `encryptBlob` and helpers. Expose `authType` as a parameter (Spotify and Amazon both use `AuthTypeOAuthToken = 4`, but this makes it explicit).
+- Update `pkg/service/spotify/zeroconf.go` — delete moved code; `PushSpotifyCredentials` becomes a one-line wrapper calling `zeroconf.PushCredentials(...)`.
+
+### Step 2 — Create `pkg/service/amazon/service.go`
+
+Mirror `pkg/service/spotify/service.go`. The `Account` struct is identical; copy it unchanged.
+
+**Amazon-specific differences:**
+
+| Item                      | Spotify                                  | Amazon                                          |
+|---------------------------|------------------------------------------|-------------------------------------------------|
+| Authorization URL         | `https://accounts.spotify.com/authorize` | `https://www.amazon.com/ap/oa`                  |
+| Token endpoint            | `https://accounts.spotify.com/api/token` | `https://api.amazon.com/auth/o2/token`          |
+| Profile endpoint          | `https://api.spotify.com/v1/me`          | `https://api.amazon.com/user/profile`           |
+| Token request credentials | HTTP Basic Auth (clientID:clientSecret)  | POST body fields `client_id` / `client_secret`  |
+| Profile fields            | `id`, `display_name`, `email`            | `user_id`, `name`, `email`                      |
+| Scopes                    | `streaming user-read-private ...`        | `profile` (expand to `music::*` when available) |
+| Entity resolution         | `ResolveEntity()` via Spotify API        | Not implemented (API in closed beta)            |
+
+Accounts persist to `{dataDir}/amazon/accounts.json`.
+
+The token request credential difference (body vs. Basic Auth) is the most important implementation detail.
+
+### Step 3 — Create `pkg/service/amazon/zeroconf.go`
+
+A single exported function `PushAmazonCredentials(zcBaseURL, username, accessToken string) error` delegating to the shared `zeroconf.PushCredentials(...)`.
+
+### Step 4 — Implement `HandleBoseAmazonToken`
+
+Replace the 501 stub in `pkg/service/handlers/handlers_oauth.go` with the full mirror of `HandleBoseSpotifyToken`:
+- Parse body for `refresh_token` / `code`
+- Look up account by BoseSecret; refresh and return token
+- Fall back to first account via `GetFreshToken()` if no matching account
+- Fall back to `HandleBoseProxy` if no Amazon service is configured
+- **Omit `scope` from the response** — Amazon Music scopes are undocumented; sending invented values risks firmware rejection
+
+### Step 5 — Add Amazon fields to `Server`
+
+In `pkg/service/handlers/server.go`, add alongside the Spotify fields:
+
+```go
+amazonClientID     string
+amazonClientSecret string
+amazonRedirectURI  string
+amazonService      *amazon.Service
+```
+
+Add methods: `SetAmazonConfig`, `SetAmazonService`, `IsAmazonConfigured`, `PrimeDeviceWithAmazon`.
+
+### Step 6 — Add management handlers
+
+In `pkg/service/handlers/handlers_mgmt.go`, add six handlers mirroring Spotify:
+
+| Handler                       | Notes                                   |
+|-------------------------------|-----------------------------------------|
+| `HandleMgmtAmazonInit`        | Returns LWA authorize URL               |
+| `HandleMgmtAmazonCallback`    | No auth; calls `bridgeAmazonToMarge`    |
+| `HandleMgmtAmazonConfirm`     | Basic Auth; calls `bridgeAmazonToMarge` |
+| `HandleMgmtAmazonAccounts`    | Returns account list (tokens stripped)  |
+| `HandleMgmtAmazonToken`       | Returns fresh access token              |
+| `HandleMgmtPrimeDeviceAmazon` | Pushes token to speaker via ZeroConf    |
+
+`bridgeAmazonToMarge` must encode the stored secret as `{"AmazonSecret":{"refresh_token":"<token>","site_id":"<id>"}}` and use `CredentialTypeToken` ("token") — **not** `CredentialTypeTokenV3`. Amazon uses `cs1` semantics.
+
+### Step 7 — Wire CLI flags and router
+
+**`main.go` flags** (env vars in parentheses):
+- `--amazon-client-id` (`AMAZON_CLIENT_ID`)
+- `--amazon-client-secret` (`AMAZON_CLIENT_SECRET`)
+- `--amazon-redirect-uri` (`AMAZON_REDIRECT_URI`, default: `ueberboese-login://amazon`)
+- `--amazon-token-url` (`AMAZON_TOKEN_URL`, for testing overrides)
+- `--amazon-profile-url` (`AMAZON_PROFILE_URL`, for testing overrides)
+
+**Router** (`setupRouter`): Add `/mgmt/amazon/*` sub-routes next to the Spotify block. The `/oauth/.../token/cs1` route is already registered and dispatches to `HandleBoseAmazonToken`.
+
+**`pkg/service/marge/marge.go`**: Extend the `AddSource` provider-label branch to map `AmazonProviderID (20) → "AMAZON"` so stored sources carry the correct type string rather than the raw numeric ID.
+
+**`pkg/models/account.go`**: Add `NewAmazonOAuthCredentials` with `Source: "AMAZON"`, `Version: "token"`.
+
+### Step 8 — Tests
+
+Mirror the Spotify test suite for the Amazon package:
+
+- `TestBuildAuthorizeURL` — verify LWA URL structure
+- `TestExchangeCodeAndStore` — mock token + profile servers; assert POST body credentials (not Basic Auth)
+- `TestRefreshAccessToken` — verify body credentials, token rotation
+- `TestGetFreshToken*` — copy Spotify variants verbatim
+- `TestSaveAndLoad` — verify persistence under `amazon/accounts.json`
+
+Add `pkg/testutils/amazon/handlers.go` and `tests/integration/mocks/amazon.go` mock servers mirroring the Spotify equivalents.
+
+Update `cmd/soundtouch-service/testdata/router_routes.txt` snapshot after wiring.
+
+---
+
+## Trying It Out
+
+### 1. Create a Login with Amazon (LWA) app
+
+Go to [developer.amazon.com](https://developer.amazon.com) → **Login with Amazon** → **Create a New Security Profile**.
+
+You will receive a **Client ID** and **Client Secret**. Under *Web Settings*, add an **Allowed Return URL** that matches `--amazon-redirect-uri`:
+
+- **Browser flow** (easiest to test): `http://<your-host>:8000/mgmt/amazon/callback`
+- **Mobile deep-link flow**: `ueberboese-login://amazon` (the default)
+
+The `profile` scope is sufficient — `music::` scopes are in closed beta and not required. The service only brokers tokens; the speaker communicates with Amazon's playback infrastructure directly.
+
+### 2. Start the service
+
+```bash
+./soundtouch-service \
+  --amazon-client-id  amzn1.application-oa2-client.xxx \
+  --amazon-client-secret yyy \
+  --amazon-redirect-uri http://<your-host>:8000/mgmt/amazon/callback
+```
+
+Or set the equivalent environment variables: `AMAZON_CLIENT_ID`, `AMAZON_CLIENT_SECRET`, `AMAZON_REDIRECT_URI`.
+
+### 3. Trigger the OAuth flow
+
+```bash
+# Get the LWA authorization URL
+curl -u admin:change_me! -X POST http://localhost:8000/mgmt/amazon/init
+# → {"redirectUrl":"https://www.amazon.com/ap/oa?client_id=...&scope=profile&..."}
+```
+
+Open the `redirectUrl` in a browser, log in with your Amazon account, and authorize the app. Amazon redirects back to `/mgmt/amazon/callback`, which responds with an HTML page saying "Amazon Music Connected".
+
+### 4. Verify the account is linked
+
+```bash
+curl -u admin:change_me! http://localhost:8000/mgmt/amazon/accounts
+# → {"accounts":[{"user_id":"amzn1.account.xxx","display_name":"Your Name","email":"you@example.com",...}]}
+```
+
+### 5. Prime a speaker
+
+```bash
+# Discover device IDs first
+curl -u admin:change_me! http://localhost:8000/mgmt/accounts/default/speakers
+
+# Push the token to a specific speaker via ZeroConf
+curl -u admin:change_me! -X POST \
+  "http://localhost:8000/mgmt/amazon/prime?deviceId=<deviceId>"
+# → {"status":"Priming triggered"}
+```
+
+### 6. Verify token refresh from the speaker
+
+Once a speaker has Amazon Music as a source, it will periodically POST to:
+
+```
+POST /oauth/device/{deviceID}/music/musicprovider/20/token/cs1
+```
+
+The service looks up the account by refresh token, refreshes it via LWA, and returns a fresh `access_token`. Check the service logs for `[Amazon]` entries confirming this flow.
+
+### DNS requirement
+
+The speaker derives the OAuth hostname by appending `oauth` to its configured streaming subdomain. If the service is at `myhost.local`, the speaker calls `myhostoauth.local`. A DNS alias pointing `myhostoauth.<domain>` to the same IP is required — the built-in DNS discovery server handles this automatically when `--dns-discovery` is enabled.
+
+### Open question: `site_id`
+
+The `AmazonSecret` credential envelope contains a `site_id` field (e.g. `"1464855981"` seen in a real migrated device). Its origin is unconfirmed — it may be a static Bose partner ID or a per-user Amazon Music identifier. The service currently stores an empty string.
+
+Real-world testing shows the device's `AmazonClient` calls `CheckBaseUrlRedirect` with empty `data` (the `site_id`) and then tries `https://music-api.amazon.com/` directly, receiving a 401 with no redirect to a regional endpoint (e.g. `music-api.amazon.de` for a German account). This suggests that:
+
+1. A correct `site_id` might cause the device to use the right regional endpoint instead of the US default.
+2. Even so, the token scope issue (see Status above) would still block playback — resolving `site_id` alone is not sufficient.
+
+`site_id` is likely secondary to the partner scope problem. It remains an open question for the post-scope-resolution phase.
+
+---
+
+## Endpoints
+
+| Method | Path                                                        | Auth  | Purpose                                            |
+|--------|-------------------------------------------------------------|-------|----------------------------------------------------|
+| `POST` | `/oauth/device/{deviceID}/music/musicprovider/20/token/cs1` | None  | Token refresh from speaker                         |
+| `GET`  | `/mgmt/amazon/callback`                                     | None  | Browser OAuth callback (redirect from Amazon LWA)  |
+| `POST` | `/mgmt/amazon/init`                                         | Basic | Start OAuth flow, returns authorization URL        |
+| `POST` | `/mgmt/amazon/confirm`                                      | Basic | Mobile app confirm (deep link delivers code)       |
+| `GET`  | `/mgmt/amazon/accounts`                                     | Basic | List linked Amazon accounts (tokens stripped)      |
+| `GET`  | `/mgmt/amazon/token`                                        | Basic | Get fresh access token (auto-refreshes if expired) |
+| `POST` | `/mgmt/amazon/prime`                                        | Basic | Push token to speaker via ZeroConf                 |
+
+## Security
+
+Same model as Spotify:
+- `/mgmt/amazon/callback` is intentionally outside Basic Auth to allow direct redirects from Amazon's authorization server.
+- All other `/mgmt/*` endpoints require Basic Auth.
+- Accounts persist to `{dataDir}/amazon/accounts.json` with `0600` permissions.
+- `GetAccounts` strips `AccessToken` and `RefreshToken` from responses.
+
+## Key Design Decisions
+
+**Secret is a JSON envelope, not a bare token.** The stored credential is `{"AmazonSecret":{"refresh_token":"Atzr|...","site_id":"..."}}`, HTML-entity-escaped when written to XML attributes. This was confirmed from a real migrated device's `Sources.xml`. `HandleBoseAmazonToken` must parse this structure to extract the `refresh_token`, and `bridgeAmazonToMarge` must produce it when storing after OAuth.
+
+**`site_id` origin is unconfirmed.** It may be a static Bose partner ID or a per-user Amazon Music identifier. Needs verification — likely obtained by calling the Amazon Music API or the LWA profile endpoint post-authentication.
+
+**Credential type is `token`, not `token_version_3`.** `CredentialTypeTokenV3` is Spotify-specific (`cs3`). Amazon uses `cs1`, which maps to the plain `CredentialTypeToken` ("token") constant. Do not upgrade Amazon credentials to v3 in `marge.go`.
+
+**POST body credentials, not Basic Auth.** The Amazon LWA token endpoint (`/auth/o2/token`) expects `client_id` and `client_secret` as POST body fields, not as an HTTP Basic Auth header. This is the single most important difference from the Spotify implementation.
+
+**No entity resolution.** `ResolveEntity()` is not implemented for Amazon — the Amazon Music API is in closed beta. Return HTTP 501 if an entity endpoint is ever requested.
+
+**`scope` omitted from token response.** The Spotify handler returns a hardcoded scope string. Amazon Music scopes for playback are undocumented; returning an empty or absent `scope` is safer than inventing values.
+
+**ZeroConf extraction is a prerequisite.** The DH-blob crypto in `spotify/zeroconf.go` should be extracted to a shared package before Amazon is added to avoid duplicating cryptographic code.

docs/concepts/spotify-priming-strategy.md

@@ -4,7 +4,31 @@ This document outlines the strategy for ensuring Bose SoundTouch devices are cor
 
 ## Overview
 
-To enable Spotify Connect for SoundTouch devices, especially for remote availability outside the local network, the speaker must be associated with a Spotify account via a process called "priming." This involves sending an `addUser` command to the speaker's ZeroConf API (port 8200) containing a valid Spotify username and OAuth access token.
+To enable Spotify Connect for SoundTouch devices, especially for remote availability outside the local network, the speaker must be associated with a Spotify account via a process called "priming." This involves a two-step exchange with the speaker's ZeroConf API (port 8200):
+
+1. **`getInfo`** — retrieve the speaker's Diffie-Hellman public key and device metadata.
+2. **`addUser`** — push encrypted Spotify credentials using the shared DH secret.
+
+This is the standard Spotify Connect ZeroConf protocol. Once the speaker holds a properly encrypted credential blob it can independently authenticate with Spotify's servers and refresh its own session without any further involvement from AfterTouch.
+
+### ZeroConf Protocol
+
+The current implementation follows the full Spotify Connect ZeroConf protocol (`pkg/service/spotify/zeroconf.go`):
+
+1. `GET http://{ip}:8200/zc?action=getInfo` → parse `publicKey` (base64 DH key, 768-bit Oakley Group 1 prime) from the response.
+2. Generate a client DH key pair using the same group parameters.
+3. Compute `sharedSecret = DH(clientPrivate, speakerPublicKey)`.
+4. Derive keys: `baseKey = SHA1(sharedSecret)[:16]`, then HMAC-SHA1 with labels `"encryption"` and `"checksum"`.
+5. Encrypt a protobuf-encoded `LoginCredentials` blob (username, `AUTHENTICATION_SPOTIFY_TOKEN=4`, access token) using AES-128-CTR + HMAC-SHA1 checksum.
+6. `POST http://{ip}:8200/zc?action=addUser` with `blob={encryptedBlob}`, `clientKey={clientPublicKeyBase64}`.
+
+The speaker decrypts the blob, stores long-lived credentials, and can handle token refresh with Spotify independently. No periodic re-priming is required for token expiry.
+
+The algorithm is based on [librespot](https://github.com/librespot-org/librespot) (Rust reference implementation).
+
+### Fallback for Older Firmware
+
+If `getInfo` fails (e.g. firmware that does not implement the DH exchange), `PushSpotifyCredentials` automatically falls back to the simplified `tokenType=accesstoken` approach: the raw OAuth access token is sent as the `blob` with an empty `clientKey`. This token expires after ~60 minutes and the speaker cannot self-refresh, so periodic re-priming is required in that case.
 
 AfterTouch adopts a **Server-Centric Hybrid Model** that prioritizes device cleanliness and user intent while providing automated self-healing.
 
@@ -14,7 +38,7 @@ AfterTouch adopts a **Server-Centric Hybrid Model** that prioritizes device clea
 AfterTouch replicates the native Bose "Add Source" experience. No Spotify priming occurs until a user explicitly links their Spotify account through the AfterTouch Management Dashboard. This ensures privacy and respects users who do not wish to use Spotify.
 
 ### 2. Device Cleanliness (Minimalist Footprint)
-We avoid invasive modifications to the speaker's filesystem. 
+We avoid invasive modifications to the speaker's filesystem.
 - **No On-Device Scripts:** We deprecate the use of internal boot-primer scripts.
 - **Native Communication:** We rely on the speaker's native ability to talk to Bose services, which are intercepted via DNS to point to the AfterTouch server.
 
@@ -53,6 +77,8 @@ The logic for account management and device interaction remains decoupled:
 4. AfterTouch pushes a fresh token from the Spotify Service.
 5. UI reflects that the device is "Managed by AfterTouch" and healthy.
 
+> **Note:** With the proper encrypted-blob flow now in place, the watchdog is only needed for the "speaker reboots and loses state" case — not for token expiry. Speakers running older firmware that trigger the `tokenType=accesstoken` fallback still require periodic re-priming (~45 min) because the raw access token expires.
+
 ### Manual Override
 Users can manually trigger a "Re-prime" or "Refresh Link" from the device list in the UI if they suspect the automated self-healing is delayed or if they want to force a specific account onto a device.
 
@@ -76,9 +102,11 @@ As AfterTouch moves to the Server-Centric model, we will:
 2.  **Consolidated Directory:** We maintain the `/mnt/nv/soundtouch-service/` base directory for other configuration needs (e.g., `aftertouch.resolv.conf`), but it will no longer contain Spotify-specific credentials or scripts.
 3.  **No On-Device Credentials:** The `/mnt/nv/soundtouch-service/spotify-primer.conf` will be removed, ensuring that no sensitive AfterTouch login details are stored on the speaker in plain text.
 
-## Implementation Roadmap (Conceptual)
+## Implementation Roadmap
 
-1. **Revert On-Device Migration:** Update the Setup Manager to remove legacy scripts and `rc.local` hooks.
-2. **Server-Side Priming Logic:** Implement a `PrimeDevice(ip)` method in the server that fetches a fresh token and calls the ZeroConf API.
-3. **Discovery Hook:** Integrate `PrimeDevice` into the discovery handler (`handleDiscoveredDevice`) with a check for unprimed state.
-4. **UI Enhancements:** Update the Speaker List to show "Spotify Linked" status and provide manual refresh buttons.
+1. ✅ **Server-Side Priming Logic:** `PrimeDeviceWithSpotify(ip)` and `pushSpotifyTokenToDevice` in `pkg/service/handlers/server.go`. Triggered on device registration (marge handlers) and via the manual `HandleMgmtPrimeDevice` endpoint.
+2. ✅ **Discovery Hook:** `handleDiscoveredDevice` calls `PrimeDeviceWithSpotify` when a speaker is found.
+3. ✅ **Proper ZeroConf Blob:** Full DH key exchange + AES-128-CTR encrypted `LoginCredentials` blob implemented in `pkg/service/spotify/zeroconf.go`. Automatically falls back to `tokenType=accesstoken` if `getInfo` fails (older firmware).
+4. ⬜ **Watchdog / Session Refresh:** Background timer to re-prime all known devices on a schedule. Only strictly needed for older firmware (fallback path) or "speaker lost state" recovery; not required for token expiry on modern firmware.
+5. ⬜ **Revert On-Device Migration:** Update the Setup Manager to remove legacy `spotify-boot-primer` scripts and `rc.local` hooks from the speakers.
+6. ⬜ **UI Enhancements:** Update the Speaker List to show "Spotify Linked" status and provide manual refresh buttons.

docs/guides/CAPTURE-DEVICE-PAIRING.md

@@ -0,0 +1,432 @@
+# Capture Device Pairing Traffic
+
+Step-by-step runbook for factory-resetting a SoundTouch speaker, pairing it to a Bose cloud account, and capturing every cloud request via mitmproxy. Tested on Apple Silicon Mac.
+
+**Goal:** obtain a full `.mitm` recording of the account-pairing flow (streaming.bose.com) triggered by the official Android app.
+
+---
+
+## Overview
+
+```
+Phase 0  Pre-flight checks
+Phase 1  Factory reset speaker
+Phase 2  Provision speaker Wi-Fi (AP mode, console)
+Phase 3  Start mitmproxy + emulator + Frida
+Phase 4  Pair speaker via Bose app (adb-driven)
+Phase 5  Save & inspect recording
+```
+
+The Android emulator does not have Bluetooth, so the standard BLE setup path is unavailable. Instead:
+
+1. Provision Wi-Fi directly over the speaker's AP web server (Phase 2).
+2. Once the speaker is on the LAN, the Bose app discovers it via mDNS — no BLE needed.
+
+---
+
+## Phase 0 — Pre-flight
+
+The emulator setup is fully scripted. Run once per machine:
+
+```bash
+# Place the Bose APK at scripts/android/bose.apk first (see BOSE-APP-ADB-Emulator.md § 1)
+# Run mitmweb once to generate the CA: mitmweb --listen-port 8080 (Ctrl-C after it starts)
+
+scripts/android/setup-mitm-avd.sh
+```
+
+This installs the system image, creates an AVD named `bose-mitm`, installs the
+mitmproxy cert and Bose APK, and saves an emulator snapshot `mitm-ready` — so
+subsequent sessions never repeat the cert/reboot cycle.
+
+For subsequent sessions, Phase 3 below is replaced by a single command:
+
+```bash
+scripts/android/start-mitm-session.sh
+```
+
+Manual steps are only needed if you want to understand the internals; see
+[BOSE-APP-ADB-Emulator.md](../analysis/BOSE-APP-ADB-Emulator.md) for the
+full manual walkthrough.
+
+---
+
+## Phase 1 — Factory Reset Speaker
+
+Perform the reset for your model (see
+[DEVICE-INITIAL-SETUP.md § 5](DEVICE-INITIAL-SETUP.md) for full table):
+
+| Model                       | Sequence                                                                |
+|-----------------------------|-------------------------------------------------------------------------|
+| SoundTouch 10               | Power on; hold **Preset 1** + **Vol −** ~10 s → solid amber Wi-Fi LED   |
+| SoundTouch 20               | Power on; hold **Preset 1** + **Vol −** ~10 s → lights blink L→R, amber |
+| SoundTouch 20/30 Series III | Hold **Preset 1** + **Preset 6** ~10 s                                  |
+| SoundTouch 300              | Hold **Vol −** ~15 s until light bar blinks                             |
+
+Wait until the white LED sweep / restart animation completes (~30 s). The speaker
+is now in setup mode and broadcasting its own Wi-Fi AP.
+
+---
+
+## Phase 2 — Provision Speaker Wi-Fi (AP Mode)
+
+### 2.1 Connect Mac to Speaker AP
+
+```bash
+# Find the SSID — use System Settings → Wi-Fi or:
+#   sudo wdutil info   (macOS Sequoia+, airport command removed)
+
+# Connect (replace SSID with actual value)
+SPEAKER_SSID="Bose SoundTouch XXXX"
+networksetup -setairportnetwork en0 "$SPEAKER_SSID"
+
+# Confirm: speaker web UI reachable at 192.0.2.1 (client gets 192.0.2.2)
+curl -s --connect-timeout 5 http://192.0.2.1/ | head -3
+```
+
+### 2.2 Push Home Wi-Fi Credentials
+
+The setup UI at `http://192.0.2.1/` uses the SoundTouch API on **port 8090**. Push credentials directly:
+
+```bash
+HOME_SSID="MyHomeNetwork"
+HOME_PASS="MyPassword"
+
+# Optional: trigger a site survey first so the speaker finds your SSID
+curl -s -X POST http://192.0.2.1:8090/performWirelessSiteSurvey \
+  -H 'Content-Type: text/xml' \
+  --data-raw '<PerformWirelessSiteSurvey timeout="5"/>'
+
+curl -s -X POST http://192.0.2.1:8090/addWirelessProfile \
+  -H 'Content-Type: text/xml' \
+  --data-raw "<AddWirelessProfile><profile ssid=\"${HOME_SSID}\" password=\"${HOME_PASS}\" securityType=\"wpa_or_wpa2\" /></AddWirelessProfile>"
+```
+
+Expected response: `<AddWirelessProfileResponse />`
+
+### 2.3 Reconnect Mac to Home Network
+
+```bash
+HOME_SSID="MyHomeNetwork"
+HOME_PASS="MyPassword"
+
+networksetup -setairportnetwork en0 "$HOME_SSID" "$HOME_PASS"
+```
+
+### 2.4 Wait for Speaker to Join LAN
+
+```bash
+# Poll mDNS until the speaker appears (~15-30 s)
+echo "Waiting for speaker on LAN..."
+until dns-sd -B _soundtouch._tcp local 2>&1 | grep -m1 "Add"; do sleep 2; done
+echo "Speaker is online"
+
+# Resolve its IP
+dns-sd -L "$(dns-sd -B _soundtouch._tcp local 2>&1 | grep Add | awk '{print $7}')" \
+  _soundtouch._tcp local 2>&1 | grep -o '[0-9]\{1,3\}\.[0-9]\{1,3\}\.[0-9]\{1,3\}\.[0-9]\{1,3\}'
+```
+
+Or just scan for open port 8090:
+
+```bash
+# Quick scan of your /24 subnet for port 8090
+SUBNET="192.168.1"   # adjust to your local subnet
+for i in $(seq 1 254); do
+  (ping -c1 -W1 ${SUBNET}.$i &>/dev/null && \
+   nc -z -w1 ${SUBNET}.$i 8090 2>/dev/null && \
+   echo "${SUBNET}.$i") &
+done
+wait
+```
+
+---
+
+## Phase 3 — Start mitmproxy, Emulator, Frida
+
+Run each block in a separate terminal tab.
+
+### 3.1 Start mitmweb (native macOS app)
+
+> **Note:** Docker mitmproxy does not work here — its NAT layer prevents the emulator from reaching it. Use the native macOS app instead (download: `https://downloads.mitmproxy.org/12.2.2/mitmproxy-12.2.2-macos-arm64.tar.gz`).
+
+```bash
+CAPTURE="bose-pairing-$(date +%Y%m%d-%H%M%S).mitm"
+/Applications/mitmproxy.app/Contents/MacOS/mitmweb \
+  --web-host 0.0.0.0 --listen-port 8080 --mode regular \
+  --set web_password=bose \
+  -w "scripts/android/captures/${CAPTURE}"
+# Captures → scripts/android/captures/
+# Web UI   → http://127.0.0.1:8081/?token=bose
+```
+
+### 3.2 Start Emulator
+
+```bash
+~/Library/Android/sdk/emulator/emulator -avd Pixel_6_API33 -writable-system &
+echo "Waiting for emulator boot..."
+adb wait-for-device
+adb -s emulator-5554 wait-for-device shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 1; done'
+echo "Emulator ready"
+```
+
+Enable root and install certificate (only needed once per emulator session):
+
+```bash
+adb -s emulator-5554 root
+adb -s emulator-5554 shell avbctl disable-verification
+adb -s emulator-5554 reboot
+adb -s emulator-5554 wait-for-device
+adb -s emulator-5554 root
+
+HASH=$(openssl x509 -inform PEM -subject_hash_old \
+  -in ~/.mitmproxy/mitmproxy-ca-cert.pem | head -1)
+
+adb -s emulator-5554 push ~/.mitmproxy/mitmproxy-ca-cert.pem /data/local/tmp/mitmproxy.pem
+adb -s emulator-5554 shell su 0 mkdir -p /data/misc/user/0/cacerts-added
+adb -s emulator-5554 shell su 0 \
+  cp /data/local/tmp/mitmproxy.pem /data/misc/user/0/cacerts-added/${HASH}.0
+adb -s emulator-5554 shell su 0 \
+  chmod 644 /data/misc/user/0/cacerts-added/${HASH}.0
+```
+
+Set proxy to Mac IP:
+
+```bash
+MAC_IP=$(ipconfig getifaddr en0)
+adb -s emulator-5554 shell settings put global http_proxy "${MAC_IP}:8080"
+echo "Proxy set to ${MAC_IP}:8080"
+```
+
+Confirm emulator can reach the speaker:
+
+```bash
+SPEAKER_IP=192.168.1.50   # adjust to your speaker's LAN IP
+adb -s emulator-5554 shell ping -c 3 "$SPEAKER_IP"
+```
+
+### 3.3 Start frida-server
+
+```bash
+adb -s emulator-5554 push scripts/android/frida-server /data/local/tmp/frida-server
+adb -s emulator-5554 shell su 0 chmod 755 /data/local/tmp/frida-server
+adb -s emulator-5554 shell su 0 "nohup /data/local/tmp/frida-server > /dev/null 2>&1 &"
+sleep 2
+echo "frida-server running"
+```
+
+### 3.4 Configure config.js
+
+`start-mitm-session.sh` patches `scripts/android/frida/config.js` automatically with the current Mac IP and mitmproxy cert. No manual step needed.
+
+### 3.5 Launch App with SSL Unpinning
+
+```bash
+scripts/android/frida-venv/bin/frida \
+  -U \
+  -f com.bose.soundtouch \
+  -l scripts/android/frida/config.js \
+  -l scripts/android/frida/native-connect-hook.js \
+  -l scripts/android/frida/android/android-system-certificate-injection.js \
+  -l scripts/android/frida/android/android-proxy-override.js \
+  -l scripts/android/frida/android/android-certificate-unpinning.js \
+  -l scripts/android/frida/android/android-certificate-unpinning-fallback.js
+```
+
+> `native-connect-hook.js` is required — the Bose app uses native networking that bypasses Java proxy settings.
+
+Expected Frida output:
+
+```
+== System certificate trust injected ==
+== Proxy system configuration overridden to <IP>:8080 ==
+== Proxy configuration overridden to <IP>:8080 ==
+== Certificate unpinning completed ==
+== Unpinning fallback auto-patcher installed ==
+```
+
+---
+
+## Phase 4 — Pair Speaker via App
+
+The Bose app should now be running in the emulator with all traffic going through mitmproxy.
+
+### 4.1 Inspect UI to Find Interactive Elements
+
+```bash
+# Dump current screen
+adb -s emulator-5554 shell uiautomator dump /sdcard/ui.xml
+adb -s emulator-5554 pull /sdcard/ui.xml /tmp/ui.xml
+
+# Helper: list all clickable elements with their text + bounds
+grep -o 'text="[^"]*" resource-id="[^"]*" \.\.\. clickable="true"[^/]*' /tmp/ui.xml \
+  || python3 -c "
+import xml.etree.ElementTree as ET
+tree = ET.parse('/tmp/ui.xml')
+for n in tree.iter('node'):
+    if n.get('clickable') == 'true' and n.get('text'):
+        print(n.get('bounds'), n.get('resource-id'), repr(n.get('text')))
+"
+```
+
+### 4.2 Navigate Setup Flow (adb)
+
+```bash
+# Take a screenshot at any point to see current state
+adb -s emulator-5554 shell screencap /sdcard/screen.png
+adb -s emulator-5554 pull /sdcard/screen.png /tmp/screen.png
+open /tmp/screen.png
+
+# Tap by resource-id (find IDs from ui.xml dump)
+adb -s emulator-5554 shell uiautomator runtest ... # or input tap
+
+# Tap by screen coordinates
+adb -s emulator-5554 shell input tap X Y
+
+# Type into the focused field
+adb -s emulator-5554 shell input text "your@email.com"
+
+# Press Enter / Next
+adb -s emulator-5554 shell input keyevent 66
+```
+
+### 4.3 Expected Setup Steps in the App
+
+Follow the on-screen flow; mitmproxy captures everything automatically.
+
+1. **Sign in** — enter email + password → triggers `POST /streaming/account/login`
+2. **Add speaker** — tap "Set Up a New Speaker" or equivalent
+3. **App discovers speaker** via mDNS on LAN (no BLE required)
+4. **Wi-Fi already configured** — app skips the Wi-Fi step since speaker is online
+5. **Name speaker** — type a name → WebSocket `name` message to speaker port 8080
+6. **Pairing** — app sends `setMargeAccount` WebSocket to speaker → speaker POSTs to `streaming.bose.com/{accountId}/devices`
+
+All cloud requests (steps 1, 6) will appear in mitmweb at `http://127.0.0.1:8081`.
+
+---
+
+## Phase 5 — Save & Inspect Recording
+
+```bash
+# Stop mitmweb (Ctrl-C in its terminal) — file is already written continuously
+
+# Inspect offline in the web UI
+mitmweb -r "$CAPTURE"
+
+# Filter to streaming.bose.com only
+mitmdump -r "$CAPTURE" --flow-filter '~u streaming.bose.com' -w bose-cloud-only.mitm
+
+# Quick text summary
+mitmdump -r "$CAPTURE" --flow-filter '~u streaming.bose.com' 2>/dev/null \
+  | grep -E "POST|GET" | head -30
+```
+
+### Convert to .http files (IntelliJ-compatible)
+
+Use `scripts/convert_mitm_script.py` to extract each flow as a `.http` file, organized by path:
+
+```bash
+NAME=$(basename "$CAPTURE" .mitm)
+OUT="scripts/android/mitm/${NAME}"
+
+/Applications/mitmproxy.app/Contents/MacOS/mitmdump \
+  -n -r "$CAPTURE" \
+  -s scripts/convert_mitm_script.py \
+  --set out_dir="${OUT}"
+```
+
+Output lands in `scripts/android/mitm/<name>/mirror/` as numbered `.http` files
+plus `*-websocket/` subdirectories for WebSocket frames. The directory is gitignored.
+
+---
+
+## Cleanup
+
+```bash
+# Remove proxy from emulator
+adb -s emulator-5554 shell settings delete global http_proxy
+
+# Kill emulator
+adb -s emulator-5554 emu kill
+```
+
+Frida artefacts live in `scripts/android/` (gitignored) and persist between sessions — no cleanup needed unless you want to force a fresh setup.
+
+---
+
+## Troubleshooting
+
+| Symptom                             | Likely cause                                     | Fix                                                                               |
+|-------------------------------------|--------------------------------------------------|-----------------------------------------------------------------------------------|
+| `curl http://192.0.2.1` times out   | Mac not on speaker AP                            | Re-run `networksetup -setairportnetwork`; speaker AP gateway is `192.0.2.1`       |
+| `addWirelessProfile` returns error  | Speaker not in AP mode or wrong IP               | Confirm speaker AP is active; use `http://192.0.2.1:8090/addWirelessProfile`      |
+| Speaker not found via mDNS          | Speaker still on AP (not home LAN yet)           | Wait ~30 s, retry; check router DHCP leases                                       |
+| Emulator can't ping speaker         | Different subnet or emulator proxy misconfigured | `adb shell ping` the Mac IP first; check proxy setting                            |
+| App shows "No speakers found"       | App not detecting mDNS                           | Ensure emulator is on same `/24` as speaker; disable emulator Wi-Fi and re-enable |
+| No traffic in mitmweb               | Frida not running or cert mismatch               | Check Frida output for `== Certificate unpinning ==`; verify issuer in config.js  |
+
+## See Also
+
+- [BOSE-APP-ADB-Emulator.md](../analysis/BOSE-APP-ADB-Emulator.md) — full MITM + Frida setup
+- [DEVICE-INITIAL-SETUP.md](DEVICE-INITIAL-SETUP.md) — factory reset sequences + AP mode detail
+- [DEVICE-SETUP.md](../DEVICE-SETUP.md) — WebSocket and cloud pairing protocol reference
+
+---
+
+## Session Trace (2026-05-02, ST10)
+
+Raw log of the first interactive run. To be cleaned up into the runbook above.
+
+### Setup
+- Ran `scripts/android/setup-mitm-avd.sh` — all 9 steps completed:
+  - Steps 1–5 were already done from a prior session (idempotent skips)
+  - Step 6: Docker image built, `frida-server` extracted to `scripts/android/frida-server`
+  - Steps 7–9: Emulator started fresh (`-no-snapshot-load`), AVB disabled, rebooted, cert + APK + frida-server installed, snapshot `mitm-ready` saved
+- Emulator running at `emulator-5554`
+
+### Factory Reset (ST10)
+- Correct sequence confirmed from official Bose guide (`firmware/FirmwareUpdateGuide/`):
+  **Power on → hold Preset 1 + Volume − for 10 s → Wi-Fi LED glows solid amber**
+- Note: original docs said "Vol− + Mute" — corrected in DEVICE-INITIAL-SETUP.md and this file
+
+### Pre-reset note
+- User inserted USB device containing `remote_services` before rebooting — device needs to be on home Wi-Fi before the USB config takes effect
+
+### Wi-Fi Provisioning (AP mode)
+- `airport` command not available on this macOS version (removed in recent releases)
+- Connect Mac to speaker AP via **System Settings → Wi-Fi** (SSID: "Bose SoundTouch XXXX")
+- Speaker AP gateway confirmed: `192.0.2.1` (client gets `192.0.2.2`), not `192.168.1.1` as previously assumed
+- `/gabbo_wifi` endpoint was hallucinated — actual endpoint verified from browser network capture (`_/device-reset/wifi-setup.txt`):
+  - Site survey: `POST http://192.0.2.1:8090/performWirelessSiteSurvey` with `<PerformWirelessSiteSurvey timeout="5"/>`
+  - Add profile: `POST http://192.0.2.1:8090/addWirelessProfile` with XML body, `securityType="wpa_or_wpa2"`
+  - Both use the standard SoundTouch API port 8090, same as normal device operation
+  - Response: `<AddWirelessProfileResponse />`
+- Reconnect Mac to home Wi-Fi; emulator stays running throughout (routes through Mac interface)
+
+### Wi-Fi Provisioning Result
+- `POST http://192.0.2.1:8090/addWirelessProfile` succeeded → `<AddWirelessProfileResponse />`
+- Speaker joined home LAN at `192.168.x.y`
+- SSH access confirmed: `ssh -oHostKeyAlgorithms=ssh-rsa root@192.168.x.y`
+- Device name: `Bose SoundTouch XXXXXX`
+- Network interfaces on device:
+  - `wlan0` → `192.168.x.y` (home LAN)
+  - `wlan1` → `192.0.2.1` (AP mode interface, stays up after provisioning)
+  - `usb0` → `203.0.113.1` (USB gadget — remote_services USB device inserted before reboot)
+
+### MITM Session Start
+- `start-mitm-session.sh` run: snapshot restored, proxy set, frida-server started, config.js patched
+- Issues encountered and fixed:
+  - frida-server start command hung (`adb shell su 0 ... &`) → fixed with `nohup ... > /dev/null 2>&1 &`
+  - Frida SSL scripts download via `curl` from GitHub timed out → moved to Dockerfile (extracted alongside frida-server)
+  - Python heredoc cert injection syntax error (multiline cert in string) → fixed using env vars + single-quoted `'PYEOF'` heredoc
+  - `mitmweb --port` deprecated → `--listen-port`
+  - frida script paths missing `android/` subdirectory → fixed in session script
+- Docker mitmproxy (`-p 8080:8080`) received no traffic from emulator — Docker NAT layer prevented the emulator reaching it
+- **Fix: use native macOS mitmproxy app** (`/Users/gesellix/Downloads/mitmproxy.app`) — binds directly to Mac's real network interfaces, traffic flows immediately
+- Android system traffic visible (connectivity checks to gstatic.com, www.google.com) — TLS failures for system processes expected since only Bose app has Frida cert injection
+
+### Capture Working
+- Full flow confirmed working with:
+  - Native mitmproxy app (`~/Downloads/mitmproxy.app`, v12.2.2)
+  - `native-connect-hook.js` added to Frida launch (required for Bose app's native networking)
+  - All 5 Frida scripts loaded: config.js, native-connect-hook.js, android-system-certificate-injection.js, android-proxy-override.js, android-certificate-unpinning.js, android-certificate-unpinning-fallback.js
+- Bose app traffic visible in mitmweb — pairing flow captured successfully

docs/guides/CAPTURE-MIGRATION-TRAFFIC.md

@@ -0,0 +1,378 @@
+# Capture Speaker Migration Traffic
+
+Runbook for migrating a SoundTouch speaker to `soundtouch-service` and capturing
+all traffic (App→Service and Speaker→Service) to identify unimplemented endpoints.
+
+**Goal:** obtain a complete picture of every cloud request a speaker and the Bose
+app make after migration, so missing endpoint implementations can be tracked down.
+
+**Pre-requisites:** the MITM pipeline is already set up and working. See
+[CAPTURE-DEVICE-PAIRING.md](CAPTURE-DEVICE-PAIRING.md) for the one-time AVD setup
+and the pairing capture runbook.
+
+---
+
+## Overview
+
+```
+Step 1  Start soundtouch-service locally (with interaction recording)
+Step 2  Start a fresh mitmproxy + Frida session (captures App traffic)
+Step 3  Discover or register the speaker in the service UI
+Step 4  Migrate the speaker (modifies SoundTouchSdkPrivateCfg.xml via SSH)
+Step 5  Operate the Bose app — everything now flows through local service
+Step 6  Inspect captured interactions for unimplemented endpoints
+Step 7  Revert (optional) / clean up
+```
+
+Traffic sources:
+- **App → Service** — captured by mitmproxy + Frida (same as pairing capture)
+- **Speaker → Service** — captured by the service's built-in interaction recorder
+
+---
+
+## Step 1 — Start soundtouch-service
+
+Build and start the service. Recording is on by default; add `--server-url` so the
+service knows its own public address (the speaker needs it for redirections).
+
+```bash
+# Determine Mac LAN IP first
+MAC_IP=$(ipconfig getifaddr en0)
+echo "Mac IP: ${MAC_IP}"
+
+# Build + run with explicit server-url so the service embeds the correct address
+make build-service
+./build/soundtouch-service \
+  --server-url "http://${MAC_IP}:8000" \
+  --record-interactions \
+  --log-bodies
+```
+
+Service listens on `:8000` by default. Web UI: `http://localhost:8000`
+
+> To also enable mirror mode (forward unhandled requests to official Bose servers
+> for comparison), add: `--mirror-enabled --mirror-endpoints /streaming/`
+
+---
+
+## Step 2 — Start mitmproxy + Frida (new capture)
+
+In a separate terminal:
+
+```bash
+scripts/android/start-mitm-session.sh
+```
+
+The script prints ready-to-run commands for mitmweb and Frida. Run each in its own
+terminal tab as instructed.
+
+New capture file lands in `scripts/android/captures/`.
+
+---
+
+## Step 3 — Discover the Speaker
+
+Open the service web UI at `http://localhost:8000`.
+
+The service discovers speakers via mDNS automatically on startup. If the speaker
+does not appear within ~30 s, add it manually:
+
+```bash
+# Via API (replace IP with speaker's current LAN IP)
+curl -s -X POST http://localhost:8000/setup/devices \
+  -H 'Content-Type: application/json' \
+  -d '{"ip": "192.168.x.y"}'
+
+# Confirm it's registered
+curl -s http://localhost:8000/setup/devices | python3 -m json.tool
+```
+
+Note the `device_id` from the response — you need it for migration.
+
+```bash
+# List all known devices and their IDs
+curl -s http://localhost:8000/setup/devices | python3 -m json.tool
+
+# Extract device_id for the speaker by matching its IP
+DEVICE_ID=$(curl -s http://localhost:8000/setup/devices \
+  | python3 -c "import sys,json; devs=json.load(sys.stdin); \
+    [print(d['device_id']) for d in devs if '35' in d.get('ip_address','')]")
+echo "Device ID: ${DEVICE_ID}"
+```
+
+---
+
+## Step 4 — Migrate the Speaker
+
+The migration modifies `SoundTouchSdkPrivateCfg.xml` on the speaker via SSH,
+redirecting `margeServerUrl` (and optionally other service URLs) to the local
+service.
+
+### 4.1 Review the Migration Plan
+
+```bash
+# Dry-run: see what will be changed
+curl -s "http://localhost:8000/setup/summary/${DEVICE_ID}" | python3 -m json.tool
+```
+
+Key fields to check:
+- `margeServerUrl` — should become `http://<MAC_IP>:8000/streaming`
+- `remoteServicesEnabled` — must be `true` for the speaker to make cloud calls
+- `is_migrated` — `false` before, `true` after
+
+### 4.2 Run Migration
+
+```bash
+MAC_IP=$(ipconfig getifaddr en0)
+TARGET_URL="http://${MAC_IP}:8000"
+
+curl -s -X POST \
+  "http://localhost:8000/setup/migrate/${DEVICE_ID}" \
+  -G --data-urlencode "target_url=${TARGET_URL}" \
+  | python3 -m json.tool
+```
+
+Expected response: `{"ok": true, "message": "Migration started", "output": "..."}`.
+The output field contains the SSH transcript of the changes made.
+
+### 4.3 Reboot the Speaker
+
+A reboot applies the new config:
+
+```bash
+curl -s -X POST "http://localhost:8000/setup/reboot/${DEVICE_ID}"
+```
+
+Wait ~30 s for the speaker to come back online. Verify it's back:
+
+```bash
+dns-sd -B _soundtouch._tcp local 2>&1 | grep Add
+# or
+curl -s http://192.168.x.y:8090/info | head -5
+```
+
+### 4.4 Verify Migration
+
+```bash
+# Check migration summary again — is_migrated should now be true
+curl -s "http://localhost:8000/setup/summary/${DEVICE_ID}" \
+  | python3 -c "import sys,json; s=json.load(sys.stdin); print('migrated:', s.get('is_migrated'))"
+```
+
+You should also see incoming connections from the speaker in the service logs once
+it resumes normal operation.
+
+---
+
+## Step 5 — Operate the Bose App
+
+With the speaker migrated and Frida running, every app action triggers traffic
+through the service:
+
+1. **Sign in** — `POST /streaming/account/login`
+2. **Speaker shows as linked** — speaker has called the service to register/sync
+3. **Play music** — BMX registry lookup, playback control
+4. **Set presets** — `POST /streaming/account/{id}/device/{id}/presets/{n}`
+5. **Adjust volume, switch source** — direct speaker API (port 8090, not cloud)
+6. **Check "Now Playing"** — speaker WebSocket events + marge sync
+
+For each action, both mitmweb and the service's recorder capture the request.
+
+---
+
+## Step 6 — Inspect Captured Interactions
+
+### 6.1 Service Interaction Recorder
+
+The service records all incoming requests to `data/interactions/` (configurable via
+`--data-dir`). Browse them via:
+
+```bash
+# List recorded sessions
+curl -s http://localhost:8000/setup/interactions | python3 -m json.tool
+
+# Download a session as HAR
+curl -s "http://localhost:8000/setup/interactions/sessions/<session>/download" \
+  -o session.har
+
+# Find 404/500 responses (unimplemented endpoints)
+curl -s "http://localhost:8000/setup/interaction-content" \
+  | python3 -c "
+import sys, json
+for entry in json.load(sys.stdin).get('entries', []):
+    status = entry.get('response', {}).get('status', 0)
+    if status >= 400:
+        print(status, entry.get('request', {}).get('method'), entry.get('request', {}).get('url'))
+"
+```
+
+### 6.2 mitmproxy Recording
+
+```bash
+# Inspect app→service traffic offline
+CAPTURE="scripts/android/captures/<filename>.mitm"
+mitmweb -r "${CAPTURE}"
+
+# Filter to local service only
+mitmdump -r "${CAPTURE}" \
+  --flow-filter "~u ${MAC_IP}:8000" \
+  2>/dev/null | grep -E "POST|GET"
+
+# Convert to .http files (IntelliJ-compatible, organized by path)
+NAME=$(basename "${CAPTURE}" .mitm)
+OUT="scripts/android/mitm/${NAME}"
+
+/Applications/mitmproxy.app/Contents/MacOS/mitmdump \
+  -n -r "${CAPTURE}" \
+  -s scripts/convert_mitm_script.py \
+  --set out_dir="${OUT}"
+# Output → scripts/android/mitm/<name>/mirror/
+```
+
+### 6.3 Identify Unimplemented Endpoints
+
+Endpoints the service doesn't handle return `404 Not Found`. Check:
+
+```bash
+# From service stats
+curl -s http://localhost:8000/setup/interaction-stats | python3 -m json.tool
+
+# List parity mismatches (local vs upstream divergence, if mirror enabled)
+curl -s http://localhost:8000/setup/parity-mismatches | python3 -m json.tool
+```
+
+---
+
+## Step 7 — Revert Migration (Optional)
+
+To restore the speaker to its original config (pointing back to Bose cloud):
+
+```bash
+curl -s -X POST "http://localhost:8000/setup/revert/${DEVICE_ID}" | python3 -m json.tool
+```
+
+Then reboot the speaker:
+
+```bash
+curl -s -X POST "http://localhost:8000/setup/reboot/${DEVICE_ID}"
+```
+
+---
+
+## Cleanup
+
+```bash
+# Stop mitmweb (Ctrl-C in its terminal)
+# Stop Frida (Ctrl-C in its terminal)
+# Stop soundtouch-service (Ctrl-C in its terminal)
+
+# Remove emulator proxy (if not running another session)
+adb -s emulator-5554 shell settings delete global http_proxy
+```
+
+---
+
+## Troubleshooting
+
+| Symptom                                   | Cause                                      | Fix                                                                       |
+|-------------------------------------------|--------------------------------------------|---------------------------------------------------------------------------|
+| Speaker not in service device list        | mDNS discovery hasn't fired yet            | Trigger manually: `POST /setup/discover` or add via `POST /setup/devices` |
+| Migration fails with SSH error            | Speaker SSH key not trusted                | Run `POST /setup/trust-ca/{deviceId}` first, or check SSH connectivity    |
+| Speaker can't reach service after reboot  | Firewall blocking port 8000 from LAN       | Allow inbound TCP 8000 on Mac firewall                                    |
+| `is_migrated: false` after migration      | Wrong `target_url` or config not written   | Check SSH output in migration response; re-run with `--method xml`        |
+| Service logs show no speaker requests     | `remote_services` not enabled on speaker   | Run `POST /setup/ensure-remote-services/{deviceId}` and reboot            |
+| App shows speaker offline after migration | Speaker config not pointing to correct URL | Check `margeServerUrl` via `GET /setup/summary/{deviceId}`                |
+
+---
+
+## Session Trace (2026-05-02, ST10)
+
+Raw log of the first interactive migration run.
+
+### Service Configuration
+
+Settings applied in the web UI before migration:
+
+| Setting             | Value                                                               |
+|---------------------|---------------------------------------------------------------------|
+| Target Domain       | `soundtouch.local` (resolvable from speaker to `192.168.x.z`)       |
+| DNS Discovery       | enabled                                                             |
+| Upstream DNS        | home Wi-Fi gateway                                                  |
+| Mirroring           | enabled (for tracing while Bose cloud is still up)                  |
+| Mirrored endpoints  | `/bmx/*`, `/streaming/*`, `/accounts/*`, `/v1/scmudc/*`, `/oauth/*` |
+| Proxy logging       | enabled, including bodies                                           |
+| Record interactions | enabled                                                             |
+| Skip recording      | `/setup/*`, `/web/*`                                                |
+
+Settings saved and service restarted.
+
+### Navigation Flow
+
+1. **Tab 1 — Settings**: entered all settings above, clicked **Save Settings**, restarted service
+2. **Tab 2 — Devices**: speaker appeared via mDNS discovery; clicked **Sync Data**
+3. **Tab 3 — Data Sync**: clicked **Start Sync** to pull account/device data from Bose cloud
+4. **Tab 2 — Devices**: clicked **Migrate** on the speaker entry
+5. In the Migrate panel: selected **Migration Method → `/etc/resolv.conf`**
+6. Ran pre-migration checks (see below)
+7. Ran migration steps (see below)
+8. Rebooted speaker
+9. Paired and configured speaker via the Bose app
+
+### Pre-Migration Checks
+
+All tests run from the **Devices → Migrate** panel after selecting the speaker (`192.168.x.y`, SoundTouch 10):
+
+- **HTTPS test (explicit CA.crt)**: ✅ passed (result not recorded in detail)
+- **HTTPS test (shared trust store)**: ✅ passed
+  - Speaker connected to `soundtouch.local:443` → `192.168.x.z`
+  - TLS: TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256, cert issued by `SoundTouch Local Root CA`
+  - CA already in speaker's system trust store (`/etc/pki/tls/certs/ca-bundle.crt`)
+- **Preliminary DNS Test**: ✅ passed
+  - Raw DNS query for `aftertouch.test` returned `192.168.x.z` via the service DNS at `192.168.x.z:53`
+- **Planned `/etc/resolv.conf`**:
+  ```
+  # Created by Aftertouch/SoundTouch-Service
+  # Priority nameserver for Bose service redirection
+  nameserver 192.168.x.z
+  ```
+
+### Migration Steps
+
+1. **Enable Persistent Remote Services** → `Successfully ensured remote services for SoundTouch 10 (192.168.x.y)`
+   - Note: `touch /etc/remote_services (with rw): sh: rw: command not found` — safe to ignore, `touch` succeeded
+2. Reloaded migration view by deselecting and reselecting the speaker in the dropdown
+3. **Backup Config Now** → `✅ Found .original config at /opt/Bose/etc/SoundTouchSdkPrivateCfg.xml.original`
+4. **Confirm Migration** → `Successfully started migration for SoundTouch 10 (192.168.x.y). Please reboot the device to activate the changes.`
+
+   Command output:
+   - Off-device backup created ✅
+   - Write access verified ✅
+   - `soundtouch.local` resolved to `192.168.x.z` ✅
+   - `/mnt/nv/soundtouch-service/aftertouch.resolv.conf` uploaded ✅
+   - `rc.local` already contains Aftertouch hook logic ✅
+   - `(rw || mount -o remount,rw /): sh: rw: command not found` — safe to ignore (same shell quirk as above)
+   - `/etc/udhcpc.d/50default` patched and verified ✅
+   - `/opt/Bose/udhcpc.script` patched and verified ✅
+   - CA certificate already trusted, skipping injection ✅
+
+5. **Reboot Speaker** → speaker came back online after ~30 s
+
+### Post-Migration
+
+- Paired speaker to Bose account via app — succeeded ✅
+- Set presets via app — worked ✅
+- Mirroring active and functional during session ✅
+- No visible errors in app behaviour; service logs and interaction recordings not yet reviewed in detail
+
+### Known Shell Warning (safe to ignore)
+
+Two commands produced `sh: rw: command not found`. This occurs because the service wraps commands with `(rw || ...)` as a fallback pattern, but the shell on the ST10 interprets `rw` as a bare command rather than a shell variable/flag. The primary command (`touch`, `mount`) still succeeds. This is a known cosmetic issue in the migration output.
+
+---
+
+## See Also
+
+- [CAPTURE-DEVICE-PAIRING.md](CAPTURE-DEVICE-PAIRING.md) — MITM setup and pairing capture
+- [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md) — full migration reference
+- [SOUNDTOUCH-SERVICE.md](SOUNDTOUCH-SERVICE.md) — service architecture and configuration
+- [BOSE-APP-ADB-Emulator.md](../analysis/BOSE-APP-ADB-Emulator.md) — Frida + mitmproxy setup

docs/guides/DEVICE-INITIAL-SETUP.md

@@ -25,13 +25,17 @@ Used by most modern SoundTouch devices (ST-10, ST-20/30 Series III, SoundTouch 3
 The classic "failover" or "alternate" setup method.
 
 - **Mechanism**: The device creates its own Wi-Fi network (SSID: `Bose SoundTouch ...` or `Bose Home Speaker ...`).
-- **IP Address**: Typically `192.168.1.1` or `10.0.0.1` (device-side).
+- **IP Address**: Typically `192.0.2.1` (device-side, verified on ST10).
 - **Web Interface**: The device hosts a web server on port 80.
 - **Process**:
   1. Connect a PC/Phone to the device's Wi-Fi.
-  2. Open a browser to `http://192.168.1.1`.
-  3. The device serves `setup.html`, which redirects to a setup wizard (`setup/index.html`).
-  4. Use the `gabbo_wifi` form to select a network and enter credentials.
+  2. Open a browser to `http://192.0.2.1`.
+  3. The device serves a Wi-Fi setup form — enter your home network SSID and password and click Submit.
+  4. The device disconnects from AP mode and joins your home network within ~15–30 seconds.
+
+![Speaker AP mode Wi-Fi setup page at 192.0.2.1](../images/speaker-ap-wifi-setup.png)
+
+For command-line provisioning (without a browser), see §6 below.
 
 ---
 
@@ -69,12 +73,96 @@ While the `soundtouch-service` focuses on migrating existing devices, a truly "c
 
 ---
 
+---
+
+## 5. Factory Reset Button Sequences
+
+A factory reset wipes Wi-Fi credentials, account pairing, and all presets, returning the device to out-of-box state. The exact sequence varies by hardware generation.
+
+> Sequences verified against official Bose reset guides in `firmware/FirmwareUpdateGuide/`. Confirm the reset succeeded by watching the status LEDs and by verifying the Wi-Fi indicator glows solid amber (setup mode).
+
+| Model                    | Factory Restore Sequence                                            | Confirm                            |
+|--------------------------|---------------------------------------------------------------------|------------------------------------|
+| SoundTouch 10            | Power on; hold **Preset 1** + **Volume −** for 10 s                 | Wi-Fi indicator glows solid amber  |
+| SoundTouch 20            | Power on; hold **Preset 1** + **Volume −** for 10 s                 | Lights blink L→R, then solid amber |
+| SoundTouch 20 Series III | Hold **Preset 1** + **Preset 6** simultaneously for ~10 s           | White LED sweep                    |
+| SoundTouch 30 Series III | Hold **Preset 1** + **Preset 6** simultaneously for ~10 s           | White LED sweep                    |
+| SoundTouch 300           | Hold **Volume −** until light bar blinks rapidly (~15 s)            | Rapid blink → off → on             |
+| SoundTouch 10 (alt)      | Press and hold the back recessed **Reset** pinhole for 10 s         | Status LED restarts                |
+| SoundTouch 20 (soft)     | Hold **AUX** for 15 s until display goes blank (settings preserved) | Display blanks                     |
+
+After factory restore the speaker enters setup mode automatically; no power-cycle is needed.
+
+---
+
+## 6. AP Mode Wi-Fi Provisioning via Console
+
+When BLE is unavailable (e.g. when using an Android emulator), use AP mode to push Wi-Fi credentials from the Mac command line.
+
+### 6.1 Connect Mac to Speaker AP
+
+After factory reset the speaker broadcasts an SSID like `Bose SoundTouch XXXX`. Connect the Mac to it:
+
+```bash
+# List nearby SSIDs — use System Settings → Wi-Fi (the airport command was removed in macOS Sequoia+)
+# Connect (replace with actual SSID)
+networksetup -setairportnetwork en0 "Bose SoundTouch XXXX"
+```
+
+The speaker's web UI gateway is at `192.0.2.1` (verified: ST10 assigns `192.0.2.2` to the client via DHCP).
+
+```bash
+# Confirm reachability
+curl -sv http://192.0.2.1/ 2>&1 | head -40
+```
+
+### 6.2 Trigger Wi-Fi Site Survey (Optional)
+
+The setup web UI at `http://192.0.2.1/` uses the SoundTouch API on **port 8090** — the same API as normal device operation. Trigger a network scan first so the speaker finds your SSID:
+
+```bash
+curl -s -X POST http://192.0.2.1:8090/performWirelessSiteSurvey \
+  -H 'Content-Type: text/xml' \
+  --data-raw '<PerformWirelessSiteSurvey timeout="5"/>'
+```
+
+### 6.3 Push Home Wi-Fi Credentials
+
+```bash
+HOME_SSID="MyHomeNetwork"
+HOME_PASS="MyPassword"
+
+curl -s -X POST http://192.0.2.1:8090/addWirelessProfile \
+  -H 'Content-Type: text/xml' \
+  --data-raw "<AddWirelessProfile><profile ssid=\"${HOME_SSID}\" password=\"${HOME_PASS}\" securityType=\"wpa_or_wpa2\" /></AddWirelessProfile>"
+```
+
+Expected response: `<?xml version="1.0" encoding="UTF-8" ?><AddWirelessProfileResponse />`
+
+The speaker will disconnect from AP mode and join the home network within ~15–30 s.
+
+### 6.4 Reconnect Mac to Home Network
+
+```bash
+networksetup -setairportnetwork en0 "MyHomeNetwork" "MyPassword"
+```
+
+Wait ~15 s for the speaker to join the home network, then verify:
+
+```bash
+# Discover the speaker's new IP via mDNS
+dns-sd -B _soundtouch._tcp local &
+sleep 5 ; kill %1
+```
+
+---
+
 ## Comparison: Initial Setup vs. Migration
 
-| Feature | Initial Setup | Migration (soundtouch-service) |
-| :--- | :--- | :--- |
-| **Connectivity** | BLE, AP Mode, USB, WAC | Ethernet/Wi-Fi (existing) |
-| **Credentials** | Required (SSID/Pass) | Not required (uses existing) |
-| **Access** | Web UI / App protocol | SSH (root) |
-| **Primary File** | `setup/index.html` | `SoundTouchSdkPrivateCfg.xml` |
-| **Use Case** | Out-of-the-box / Reset | Redirecting active devices |
+| Feature          | Initial Setup          | Migration (soundtouch-service) |
+|:-----------------|:-----------------------|:-------------------------------|
+| **Connectivity** | BLE, AP Mode, USB, WAC | Ethernet/Wi-Fi (existing)      |
+| **Credentials**  | Required (SSID/Pass)   | Not required (uses existing)   |
+| **Access**       | Web UI / App protocol  | SSH (root)                     |
+| **Primary File** | `setup/index.html`     | `SoundTouchSdkPrivateCfg.xml`  |
+| **Use Case**     | Out-of-the-box / Reset | Redirecting active devices     |

docs/guides/HTTPS-SETUP.md

@@ -1,81 +1,64 @@
-# HTTPS Setup & Custom CA Certificate
+# HTTPS & Custom CA Certificate
 
-To use the `/etc/hosts` redirection method safely, SoundTouch devices must communicate over HTTPS. This requires the device to trust the AfterTouch Root CA certificate used by the local service.
+SoundTouch speakers communicate with cloud services over HTTPS. For the local service to work over HTTPS, speakers must trust the AfterTouch Root CA. The service manages this automatically — it generates a CA on first start and the web UI guides you through installing it on each speaker as part of the migration flow.
 
-## 1. Automated Migration (Hosts Method)
+---
 
-The `soundtouch-service` can automatically configure a device to use the `/etc/hosts` method:
+## How TLS works in AfterTouch
 
-```bash
-curl -X POST "http://localhost:8000/setup/migrate/{deviceIP}?method=hosts"
+The service includes a built-in HTTPS listener (default port `8443`) that presents a certificate covering all Bose cloud hostnames. The certificate is signed by the AfterTouch Root CA, which is generated automatically on first start and stored in `data/certs/`.
+
+**Domain coverage** — the certificate covers:
+- Wildcard: `*.api.bose.io`, `*.api.bosecm.com`
+- Specific: `streaming.bose.com`, `bmx.bose.com`, `stats.bose.com`, `updates.bose.com`, `worldwide.bose.com`, `bose-prod.apigee.net`, `media.bose.io`, `downloads.bose.com`, `voice.api.bose.io`, and more
+
+> **Note**: The hostname you configure as `HTTPS_SERVER_URL` (e.g. `https://soundtouch.fritz.box:8443`) is also added as a Subject Alternative Name, ensuring valid TLS for direct browser or API access.
+
+---
+
+## CA trust installation (via web UI)
+
+The migration flow in the web UI includes a CA trust step that:
+1. Uploads the Root CA to the speaker via SSH
+2. Appends it to the speaker's shared trust store (`/etc/pki/tls/certs/ca-bundle.crt`)
+3. Verifies connectivity over HTTPS
+
+This is handled automatically — you don't need to manage CA files manually unless you're doing an advanced or manual setup.
+
+---
+
+## Downloading the CA certificate
+
+You can download the Root CA for manual installation on other devices (phones, PCs, additional speakers):
+
+```
+http://<server>:8000/setup/ca.crt
 ```
 
-This command will:
-1.  Connect to the device via SSH.
-2.  Update `/etc/hosts` to point Bose domains to the service IP.
-3.  Inject the auto-generated AfterTouch Root CA into the device's trust store (`/etc/pki/tls/certs/ca-bundle.crt`).
-4.  Reboot the device.
+---
 
-## 2. Managing the Root CA
+## Binding to port 443
 
-The AfterTouch service automatically generates a Root CA when it first starts.
+Speakers expect HTTPS on the default port 443. Since binding to port 443 requires elevated privileges, you have three options:
 
-- **CA Certificate**: `data/certs/ca.crt`
-- **CA Private Key**: `data/certs/ca.key`
+1. **Port forwarding (recommended)**: Run the service on port 8443 and forward port 443 to it using `iptables` or your firewall/router.
+2. **Capabilities**: Grant the binary permission to bind low ports: `sudo setcap 'cap_net_bind_service=+ep' ./soundtouch-service`
+3. **Reverse proxy**: Use Nginx or Caddy in front of the service (see below).
 
-### Downloading the CA Certificate
-You can download the CA certificate for manual installation on other devices (like your phone or PC) from:
-`http://<server-ip>:8000/setup/ca.crt`
+---
 
-### 3. Built-in HTTPS Support
+## Reverse proxy (optional)
 
-The `soundtouch-service` now includes a built-in HTTPS listener. This simplifies the `/etc/hosts` redirection method by automatically presenting the correct certificates for Bose domains.
-
-- **HTTPS Port**: Configurable via `HTTPS_PORT` environment variable (defaults to `8443`).
-- **HTTPS Server URL**: Configurable via `HTTPS_SERVER_URL` (e.g., `https://mysoundtouch.local:8443`). If not set, the service attempts to guess it using the system hostname.
-- **Domain Coverage**: Automatically presents a certificate with comprehensive coverage using wildcard certificates (`*.api.bose.io`, `*.api.bosecm.com`) plus specific domains (`streaming.bose.com`, `updates.bose.com`, `stats.bose.com`, `bmx.bose.com`, `worldwide.bose.com`, `bose-prod.apigee.net`, etc.).
-- **Wildcard Support**: Uses RFC-compliant wildcard certificates for automatic coverage of all API subdomains, including event analytics endpoints like `events.api.bosecm.com`, `eventsdev.api.bosecm.com`, and future API services.
-- **TLS Error Logging**: Comprehensive logging of TLS handshake attempts, certificate matching, and connection failures for debugging DNS redirection issues.
-- **Automatic Setup**: On first start, it generates a server certificate signed by your AfterTouch local Root CA.
-
-#### TLS Security & Debugging
-
-The built-in HTTPS listener is configured to use modern and secure TLS settings while maintaining compatibility with SoundTouch devices (which support up to TLS 1.2 with OpenSSL 1.0.2).
-
-- **Minimum TLS Version**: TLS 1.2
-- **Preferred Cipher Suites**:
-  - `ECDHE-RSA-AES128-GCM-SHA256`
-- **TLS Debugging**: Detailed logging of:
-  - Certificate requests by domain (`[TLS] Certificate request for ServerName: events.api.bosecm.com`)
-  - Wildcard certificate matching (`[TLS] ✅ Serving certificate for events.api.bosecm.com (matched *.api.bosecm.com)`)
-  - Handshake failures (`[TLS] ❌ Handshake failed from 192.168.1.50: tls: certificate not found`)
-  - Successful connections (`[TLS] ✅ Successful connection from 192.168.1.50`)
-  - `ECDHE-RSA-AES256-GCM-SHA384`
-  - `ECDHE-RSA-CHACHA20-POLY1305`
-  - `RSA-AES128-GCM-SHA256` (Legacy support)
-  - `RSA-AES256-GCM-SHA384` (Legacy support)
-
-#### Binding to Port 443
-SoundTouch devices expect HTTPS on the default port 443. Since binding to port 443 usually requires root privileges, you have two options:
-
-1.  **Port Forwarding (Recommended)**: Run the service on a high port (e.g., 8443) and use `iptables` or your firewall to forward traffic from 443 to 8443.
-2.  **Capabilities**: Grant the binary permission to bind to low ports: `sudo setcap 'cap_net_bind_service=+ep' ./soundtouch-service`.
-3.  **Reverse Proxy**: Use Nginx or Caddy as described below.
-
-### 4. Reverse Proxy (Optional)
-
-1.  **Generate a certificate** for the Bose domains signed by your Root CA.
-2.  **Configure Nginx** to use this certificate and proxy requests to `soundtouch-service`.
+If you prefer to use Nginx or another proxy for TLS termination:
 
 ```nginx
 server {
     listen 443 ssl;
     server_name streaming.bose.com bmx.bose.com stats.bose.com updates.bose.com;
 
-    ssl_certificate /path/to/generated-cert.crt;
-    ssl_certificate_key /path/to/generated-cert.key;
+    ssl_certificate /path/to/data/certs/server.crt;
+    ssl_certificate_key /path/to/data/certs/server.key;
 
-    # Secure TLS configuration (matches soundtouch-service defaults)
     ssl_protocols TLSv1.2;
     ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:AES128-GCM-SHA256:AES256-GCM-SHA384';
 
@@ -87,23 +70,41 @@ server {
 }
 ```
 
-## 5. Manual CA Injection (Legacy/Manual)
+> **Tell the service to honour `X-Real-IP`/`X-Forwarded-For`.** When deploying
+> behind a reverse proxy on the same host as above, set
+> `"trust_forwarded_headers": true` in `data/settings.json`. With that flag
+> on, the service rewrites `r.RemoteAddr` from the proxy-supplied headers,
+> so handlers that act on the source IP (e.g. the Spotify priming triggered
+> by `/marge/streaming/support/power_on`) see the speaker's real address
+> instead of the proxy's loopback peer.
+>
+> By default only `127.0.0.0/8` and `::1/128` are trusted to set those
+> headers. If your reverse proxy lives on a different host, list its CIDR(s)
+> in `"trusted_proxy_cidrs"` (e.g. `["10.0.0.0/8"]`). Do **not** enable
+> `trust_forwarded_headers` on a flat LAN deployment without a proxy: a
+> malicious speaker on the LAN can send the headers itself and spoof its
+> source IP.
 
-If you prefer to inject the CA certificate manually:
+---
 
-1.  Copy `ca.crt` to the device:
-    ```bash
-    scp data/certs/ca.crt root@{deviceIP}:/tmp/
-    ```
-2.  Append it to the trust store on the device:
-    ```bash
-    ssh root@{deviceIP} "(rw || mount -o remount,rw /) && cat /tmp/ca.crt >> /etc/pki/tls/certs/ca-bundle.crt"
-    ```
+## Manual CA injection (advanced)
 
-    ## 6. Verifying Connectivity
+If you need to inject the CA manually (e.g. without the web UI migration flow):
 
-    You can verify that your device can correctly reach the `soundtouch-service` over HTTPS using the management web UI.
+```bash
+# Copy the CA to the speaker
+scp data/certs/ca.crt root@<SPEAKER-IP>:/tmp/
 
-    In the **Migration Summary** for a device, you will find an **HTTPS Connection Test** section:
-    - **Test with Explicit CA.crt**: Uploads a temporary copy of the Root CA to the device and uses `curl --cacert` to verify the connection. Use this to verify your HTTPS setup *before* modifying the device's shared trust store.
-    - **Test with Shared Trust Store**: Uses the device's default trust store. Use this to verify that your CA injection was successful and the device now natively trusts your local server.
+# Make the filesystem writable and append the CA to the trust store
+ssh root@<SPEAKER-IP> "(rw || mount -o remount,rw /) && cat /tmp/ca.crt >> /etc/pki/tls/certs/ca-bundle.crt"
+```
+
+---
+
+## TLS compatibility
+
+SoundTouch speakers run OpenSSL 1.0.2, supporting up to TLS 1.2. The service is configured accordingly:
+
+- **Minimum TLS version**: TLS 1.2
+- **Preferred cipher suites**: `ECDHE-RSA-AES128-GCM-SHA256`, `ECDHE-RSA-AES256-GCM-SHA384`, `ECDHE-RSA-CHACHA20-POLY1305`
+- **Legacy support**: `RSA-AES128-GCM-SHA256`, `RSA-AES256-GCM-SHA384`

docs/guides/MIGRATION-GUIDE.md

@@ -1,418 +1,224 @@
-# THIS IS A PLANNED TO BE THE MIGRATION GUIDE
+# Migration Guide: From Bose Cloud to AfterTouch
 
-> This migration guide is not finalized, yet.
-> We're using it as an orientation for the required implementation.
+This guide walks through the complete process of migrating your SoundTouch speakers from Bose's cloud services to **AfterTouch**, the local replacement provided by `soundtouch-service`. By the end, your speakers will work fully independently of Bose's servers.
+
+For a shorter overview, see the [Survival Guide](SURVIVAL-GUIDE.md). For safety considerations and rollback options, see the [Migration & Safety Guide](MIGRATION-SAFETY.md).
 
 ---
 
-# Complete Migration Guide - From Bose Cloud to Local SoundTouch Service
+## What you need
 
-## Overview
+- A machine that is **always on** (Raspberry Pi, NAS, home server, or similar) to run the service
+- A **USB drive** (FAT-formatted) to enable SSH on each speaker
+- Your speakers must be on the **same network** as the service host
+- About **15–30 minutes per speaker**
 
-This guide will walk you through migrating your Bose SoundTouch speakers from Bose's cloud services to AfterTouch, your own local SoundTouch service. By the end of this process, your speakers will be completely independent of Bose's servers while retaining all their functionality.
+---
 
-> **💡 Why Migrate?** Bose announced the shutdown of their SoundTouch cloud services in May 2026. This migration ensures your speakers continue working indefinitely with enhanced local control and monitoring.
+## Step 1: Install and start the service
 
-## What You'll Need
+Choose the option that fits your setup.
 
-### Hardware Requirements
-- **Raspberry Pi 4 or similar** (minimum: Raspberry Pi Zero 2W)
-- **MicroSD card** (16GB or larger)
-- **USB drive** (for device preparation)
-- **Network connection** for your Raspberry Pi
-
-### Before You Start
-- **List all your SoundTouch devices** and their current locations
-- **Note your current presets and favorites** (they will be preserved)
-- **Ensure devices are on the same network** as your future SoundTouch service
-- **Basic computer skills** (following instructions, using a web browser)
-
-### Time Estimate
-- **Setup**: 30-60 minutes for the service installation
-- **Per Device**: 10-15 minutes for each speaker migration
-- **Total**: 1-3 hours depending on number of devices
-
-## Step 1: Install SoundTouch Service
-
-### Option A: Raspberry Pi Installation (Recommended)
-
-#### 1.1 Prepare Your Raspberry Pi
-
-1. **Flash Raspberry Pi OS** to your SD card using Raspberry Pi Imager (see the raspberrypi.com documentation)
-2. **Enable SSH** during imaging or create an empty `ssh` file on the boot partition
-3. **Boot your Pi** and connect it to your network
-4. **Find your Pi's IP address** (check your router or use `ping raspberrypi.local`)
-
-#### 1.2 Install SoundTouch Service
-
-Connect to your Pi via SSH and run:
+### Binary (go install)
 
 ```bash
-# Download and install
-curl -sSL https://github.com/gesellix/Bose-SoundTouch/releases/latest/download/install.sh | bash
-
-# Start the service
-sudo systemctl enable soundtouch-service
-sudo systemctl start soundtouch-service
+go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
+soundtouch-service
 ```
 
-#### 1.3 Verify Installation
+The service starts on port 8000. Open `http://localhost:8000` in your browser.
 
-1. Open your web browser
-2. Go to `http://[PI_IP_ADDRESS]:8000` (replace with your Pi's IP)
-3. You should see the **SoundTouch Service Dashboard**
+### Docker Compose (recommended for home servers and VMs)
 
-![SoundTouch Service Dashboard](../images/dashboard-home.png)
-*Example: SoundTouch Service main dashboard*
+The repository ships a `docker-compose.yml` ready for this use case. Clone or download it, copy the example config, then edit `.env` before starting:
 
-### Option B: Docker Installation
+```bash
+cp .env.example .env
+# Edit .env:
+#   SOUNDTOUCH_HOSTNAME=192.168.1.100   ← your server's address
+#   SOUNDTOUCH_VERSION=v0.70.0          ← pin to a release tag instead of 'latest'
+docker compose up -d
+```
 
-If you prefer Docker, run:
+`SOUNDTOUCH_HOSTNAME` is the address your speakers will use to reach the service — use a hostname or IP reachable from the speaker, not `localhost`.
+
+On **Linux** (Debian, Proxmox VE, Raspberry Pi OS, etc.) you can enable host networking for automatic speaker discovery. Uncomment the `network_mode: host` line in `docker-compose.yml` and remove the `ports:` section (they conflict with host networking). Without host networking, add your speakers by IP address in Step 4 instead.
+
+For local overrides (e.g. switching to `build: .` during development), create a `docker-compose.override.yml` — Docker Compose picks it up automatically and it is not tracked in version control.
+
+> **Note on `docker-compose.ci.yml`**: this file contains mock services used only for automated integration tests. It is not needed for your own deployment.
+
+### Docker run (Linux — with host networking for device discovery)
 
 ```bash
 docker run -d \
   --name soundtouch-service \
-  --restart unless-stopped \
-  -p 8000:8000 \
-  -p 8443:8443 \
-  -v soundtouch-data:/data \
-  gesellix/soundtouch-service:latest
+  --network host \
+  -v $(pwd)/data:/app/data \
+  ghcr.io/gesellix/bose-soundtouch:latest
 ```
 
-## Step 2: Create Your Account
+### Docker run (macOS / Windows — manual device IP required)
 
-### 2.1 Initial Setup
-
-1. **Open the dashboard** at `http://[SERVICE_IP]:8000`
-2. Click **"Create New Account"**
-3. **Fill in your details**:
-   - Account Name: `My Home Audio`
-   - Email: `your@email.com` (optional, for notifications)
-   - Migration Strategy: `Gradual` (recommended)
-
-![Account Creation](../images/account-creation.png)
-*Example: Account creation form*
-
-### 2.2 Account Configuration
-
-After creation, you'll see your **Account Dashboard**:
-- **Account ID**: Unique identifier (e.g., `acc_home_audio_001`)
-- **Status**: `Active - Ready for Migration`
-- **Device Count**: Initially 0
-- **Migration Status**: `Prepared`
-
-![Account Dashboard](../images/account-dashboard.png)
-*Example: Fresh account dashboard ready for device migration*
-
-### 2.3 Initial Settings
-
-Once your account is created, configure the global settings:
-1. **Settings**:
-   - Check **Target Domain**: Ensure it's reachable from the speaker (e.g., `soundtouch.fritz.box`).
-   - **DNS Discovery**: Enable DNS discovery on port `:53`. This is crucial for the DNS hook migration method.
-2. **Devices**:
-   - Go to the **"Device Discovery"** tab.
-   - Click **"Scan Network"** or manually add a speaker via IP address.
-   - Your devices should appear with **SSH Status**: `Enabled`.
-
-![Device Discovery](../images/device-discovery.png)
-*Example: Discovered devices with remote access enabled*
-
-## Step 3: Prepare Your Devices
-
-> **⚠️ Important**: This step temporarily enables SSH access on your speakers. SSH will be automatically disabled after migration unless you choose to keep it enabled.
-
-### 3.1 Enable Remote Services
-
-For each SoundTouch device:
-
-1. **Prepare a USB drive**:
-   - Format as FAT32
-   - Create an empty file named `remote_services` (no extension)
-   - (Optional) Firmware update/reset, see [Bose SoundTouch USB Update](https://downloads.bose.com/ced/soundtouch/soundtouch_usb/index.html)
-
-2. **Insert USB drive** into your SoundTouch speaker
-3. **Power cycle** the device (unplug for 10 seconds, then reconnect)
-
-![USB Preparation](../images/usb-remote-services.png)
-*Example: USB drive setup for enabling remote services*
-
-## Step 4: Discover and Register Devices
-
-### 4.1 Automatic Discovery
-
-The service automatically scans for SoundTouch devices every 5 minutes. To trigger immediate discovery:
-
-1. **Dashboard** → **"Devices"** → **"Discover Devices"**
-2. **Wait 30-60 seconds** for scan completion
-3. **Review discovered devices** in the list
-
-### 4.2 Register Devices to Your Account
-
-For each discovered device:
-
-1. **Click device name** in the discovery list
-2. **Verify device information**:
-   - Name: `Living Room Speaker`
-   - Model: `SoundTouch 30`
-   - MAC Address: `A8:1B:6A:53:6A:98`
-   - IP Address: `192.168.1.100`
-   - Status: `Discovered - Ready for Registration`
-
-3. **Click "Register to Account"**
-4. **Choose registration type**:
-   - **Fresh Setup**: For new or factory-reset devices
-   - **Migrate from Bose**: For devices with existing Bose account (recommended)
-
-![Device Registration](../images/device-registration.png)
-*Example: Device registration dialog with migration options*
-
-### 4.3 Device Registration Results
-
-After registration, you'll see:
-- **Device Status**: `Registered - Active`
-- **Account Association**: Your account name
-- **Lifecycle State**: `Active`
-- **Data Sources**: `Mirror Primary` (initially uses Bose, falls back to local)
-
-## Step 5: Migrate Individual Devices
-
-### 5.1 Step 3: Data Sync
-
-1. **Dashboard** → **"Devices"** → Select your device
-2. Click **"Data Sync"**
-3. This fetches configuration (presets, recents, sources) from the speaker to the SoundTouch service.
-
-### 5.2 Step 4: Migration
-
-Once data is synced, proceed to the migration tab for the device:
-
-1. **Backup XML**: Create an off-device backup of the current configuration.
-2. **Enable Persistent Remote Service**: This ensures SSH remains available after reboots.
-   - *Note*: If you see `'rw: command not found'`, you can safely ignore it.
-3. **CA Certificate Configuration**:
-   - **Test with explicit CA**: Verify the speaker can communicate using the local CA.
-   - **Trust CA now**: Inject the local Root CA into the speaker's trust store.
-   - **Test with shared trust store**: Verify general HTTPS communication.
-4. **Migration Method**:
-   - Select **"Redirect via DNS hook"**.
-   - **Test DNS Redirection**: Ensure the speaker correctly resolves the service domain.
-5. **Confirm Migration**: Apply the final changes to the speaker.
-
-#### Example Migration Output:
-```text
-Successfully created off-device backup of current configuration.
-Pre-flight: Write access verified.
-Resolved soundtouch.fritz.box to 192.168.1.100
-Uploaded /mnt/nv/soundtouch-service/aftertouch.resolv.conf
-/mnt/nv/rc.local already contains Aftertouch hook logic
-(rw || mount -o remount,rw /): sh: rw: command not found
-
-cp /etc/udhcpc.d/50default /etc/udhcpc.d/50default.original:
-Applied patch to /etc/udhcpc.d/50default
-Verified patch on /etc/udhcpc.d/50default
-cp /opt/Bose/udhcpc.script /opt/Bose/udhcpc.script.original:
-Applied patch to /opt/Bose/udhcpc.script
-Verified patch on /opt/Bose/udhcpc.script
-CA certificate already trusted, skipping injection
+```bash
+docker run -d \
+  --name soundtouch-service \
+  -p 8000:8000 -p 8443:8443 \
+  -v $(pwd)/data:/app/data \
+  --env SERVER_URL=http://soundtouch.local:8000 \
+  --env HTTPS_SERVER_URL=https://soundtouch.local:8443 \
+  ghcr.io/gesellix/bose-soundtouch:latest
 ```
 
-## Step 7: Complete Account Migration
+On macOS/Windows, device discovery via mDNS won't work inside the container — you'll add devices by IP address in Step 4.
 
-### 7.1 Migrate All Devices
-
-Repeat the migration process for each of your SoundTouch devices. You can migrate multiple devices simultaneously, but we recommend doing 1-2 at a time to monitor progress.
-
-**Migration Dashboard** shows overall progress:
-- **Devices Migrated**: `2 of 4 completed`
-- **Currently Migrating**: `Living Room Speaker, Kitchen Speaker`
-- **Pending Migration**: `Bedroom Speaker, Office Speaker`
-- **Estimated Completion**: `3 days remaining`
-
-![Account Migration Status](../images/account-migration.png)
-*Example: Account-wide migration progress*
-
-### 7.2 Verify Complete Migration
-
-When all devices are migrated:
-
-1. **Account Status**: `Active - Fully Migrated`
-2. **Bose Dependency**: `None`
-3. **Local Control**: `100%`
-4. **Device Health**: All devices show `Healthy - Local Only`
-
-![Migration Complete](../images/migration-complete.png)
-*Example: Completed migration dashboard*
-
-## Step 8: Post-Migration Tasks
-
-1. **Remove USB stick** from the speaker.
-2. **Reboot** the device to apply all changes.
-
-### 8.1 Disable Remote Services (Optional)
-
-For enhanced security, you can disable SSH on migrated devices. However, keeping it enabled allows for easier future maintenance or reverts.
-
-### 8.2 Configure Backups
-
-Set up automatic backups of your device configurations:
-
-1. **Dashboard** → **"Settings"** → **"Backup"**
-2. **Enable Automatic Backups**: ✅
-3. **Backup Schedule**: `Daily at 2 AM`
-4. **Retention**: `Keep 30 days`
-5. **Export Location**: `/data/backups` or external storage
-
-![Backup Configuration](../images/backup-setup.png)
-*Example: Backup configuration settings*
-
-### 8.3 Set Up Monitoring Alerts (Optional)
-
-Configure notifications for important events:
-
-1. **Dashboard** → **"Settings"** → **"Notifications"**
-2. **Email Notifications**: Enter your email
-3. **Alert Types**:
-   - ✅ Device goes offline
-   - ✅ Migration failures
-   - ✅ Service errors
-   - ✅ Daily health summary
-
-## Troubleshooting Common Issues
-
-### Device Not Discovered
-
-**Problem**: Device doesn't appear in discovery scan
-
-**Solutions**:
-1. **Check network**: Ensure device and service are on same network
-2. **Verify USB setup**: Confirm `remote_services` file was processed
-3. **Power cycle**: Unplug device for 30 seconds, reconnect
-4. **Manual add**: Dashboard → "Devices" → "Add Manually" with IP address
-
-### Migration Stuck
-
-**Problem**: Device stuck in "Migrating" status
-
-**Solutions**:
-1. **Check device health**: Dashboard → Device → "Health Status"
-2. **Review logs**: Dashboard → Device → "View Logs"
-3. **Restart migration**: Device → "Migration" → "Restart Process"
-4. **Rollback**: Device → "Migration" → "Rollback to Bose"
-
-### Presets Not Working
-
-**Problem**: Saved presets don't work after migration
-
-**Solutions**:
-1. **Verify sources**: Check configured sources are still available
-2. **Re-authenticate**: Re-login to music services (Spotify, etc.)
-3. **Rebuild presets**: Dashboard → Device → "Presets" → "Rebuild from Backup"
-
-### Service Unreachable
-
-**Problem**: Cannot access SoundTouch Service dashboard
-
-**Solutions**:
-1. **Check service status**: `sudo systemctl status soundtouch-service`
-2. **Restart service**: `sudo systemctl restart soundtouch-service`
-3. **Check network**: Verify Pi is connected and accessible
-4. **Check ports**: Ensure ports 8000 and 8443 are not blocked
-
-## Advanced Features
-
-### Multi-Zone Management
-
-After migration, your multi-zone setups work seamlessly:
-
-1. **Dashboard** → **"Zones"**
-2. **Create Zone**: Select primary device and slaves
-3. **Zone Control**: Play, pause, volume control for entire zone
-4. **Individual Control**: Override individual speakers in zone
-
-### Custom Sources
-
-Add custom streaming sources:
-
-1. **Dashboard** → **"Sources"** → **"Add Custom"**
-2. **Configure**:
-   - Name: `Local Radio Station`
-   - Stream URL: `http://stream.example.com:8000`
-   - Image URL: `http://example.com/logo.png`
-3. **Assign to devices**: Select which devices can access this source
-
-### API Access
-
-For developers and advanced users:
-
-- **REST API**: `http://[SERVICE_IP]:8000/api/v1/`
-- **Documentation**: `http://[SERVICE_IP]:8000/docs`
-- **WebSocket Events**: Real-time device status updates
-- **Export Data**: JSON/XML export of all device configurations
-
-## Maintenance and Monitoring
-
-### Daily Monitoring
-
-Check your **Dashboard Summary**:
-- **All Devices Online**: ✅ Green indicators
-- **Response Times**: < 100ms average
-- **Error Rate**: < 1%
-- **Storage Usage**: Monitor disk space
-
-### Weekly Tasks
-
-1. **Review Health Reports**: Check weekly device health summaries
-2. **Update Service**: Check for SoundTouch service updates
-3. **Backup Verification**: Ensure backups are completing successfully
-4. **Log Review**: Check for any recurring issues or warnings
-
-### Monthly Tasks
-
-1. **Full System Backup**: Export complete account and device data
-2. **Performance Review**: Analyze response times and error patterns
-3. **Security Update**: Update Raspberry Pi OS and service
-4. **Capacity Planning**: Monitor storage and consider expansion
-
-## Getting Help
-
-### Documentation Resources
-
-- **Technical Reference**: `/docs/reference/` - Detailed API and configuration docs
-- **Troubleshooting Guide**: `/docs/guides/TROUBLESHOOTING.md` - Common issues and solutions
-- **Community Forum**: GitHub Discussions for community support
-
-### Diagnostic Information
-
-When seeking help, provide:
-
-1. **System Information**: Dashboard → "System" → "Download Diagnostic Report"
-2. **Device Logs**: Dashboard → Device → "Export Logs"
-3. **Migration History**: Dashboard → "Migration" → "Export Timeline"
-4. **Current Status**: Screenshot of main dashboard
-
-### Support Channels
-
-- **GitHub Issues**: Technical bugs and feature requests
-- **Community Discussions**: User questions and experiences
-- **Documentation Updates**: Corrections and improvements
+See [Raspberry Pi Setup](RASPBERRY-PI.md) and the [SoundTouch Service Guide](SOUNDTOUCH-SERVICE.md) for more deployment options.
 
 ---
 
-## Summary
+## Step 2: Configure the service URL
 
-Congratulations! 🎉 You've successfully migrated your SoundTouch speakers to local control. Your devices are now:
+Open `http://<server>:8000` and go to the **Settings** tab.
 
-- ✅ **Independent** of Bose cloud services
-- ✅ **Fully functional** with all original features preserved
-- ✅ **Enhanced** with better monitoring and control
-- ✅ **Future-proof** against service shutdowns
+![AfterTouch Settings tab](../images/ui-settings.png)
 
-**What's Next?**
+Set the **Target Domain** to the address your speakers can reach — for example `https://soundtouch.fritz.box` or `http://192.168.1.100:8000`. This must be the host's address on your local network, not `localhost`.
 
-- **Enjoy your music** with enhanced local control
-- **Monitor your system** through the dashboard
-- **Share your experience** with the community
-- **Explore advanced features** as you become more comfortable
+If you plan to use DNS/DHCP redirect, enable the **DNS Discovery Server** and set the **DNS Bind Address** to `:53`. The upstream DNS should be your router's IP, not the service's own address.
 
-Your SoundTouch speakers will now continue working indefinitely, regardless of external service availability. Welcome to true audio independence! 🔊
+> **Tip**: If you change settings and they don't seem to take effect, check `data/settings.json` — settings saved in the UI take precedence over environment variables.
+
+---
+
+## Step 3: Enable shell access on each speaker
+
+The wizard supports **two transports** for talking to the speaker. Pick whichever your device exposes:
+
+### SSH (recommended — required for XML migration, DNS interception, and CA install)
+
+The XML migration writes updated configuration to the speaker's filesystem, which requires SSH access. Enable it once per device:
+
+1. Format a USB drive as FAT (FAT32). Some speakers require the **bootable flag** to be set on the partition — see [SoundCork issue #172](https://github.com/deborahgu/soundcork/issues/172) for details.
+2. Create an empty file named **`remote_services`** (no extension) in the root of the drive.
+3. Insert the drive into the speaker's USB port while it is powered on.
+4. Power-cycle the speaker (unplug the power cable, wait 10 seconds, reconnect).
+5. After boot, root SSH is available with no password: `ssh -oHostKeyAlgorithms=+ssh-rsa root@<SPEAKER-IP>`
+
+You only need to do this once per speaker. SSH can remain enabled for future maintenance or be disabled after migration — your choice.
+
+### Telnet:17000 (fallback when SSH isn't possible)
+
+If the USB-stick unlock doesn't work on your speaker (some firmware revisions refuse it — notably SA-5, ST520, and recent ST Portables), the wizard falls back to the speaker's **built-in diagnostic shell on TCP port 17000**. No setup required — most SoundTouch firmware exposes it automatically. The wizard detects which transports are available and picks the right one; you don't have to choose manually.
+
+Telnet-only migrations are limited to HTTP (no CA install possible without SSH). The wizard surfaces this clearly when it applies.
+
+---
+
+## Step 4: Add and sync your speaker
+
+### Discover
+
+The service scans for SoundTouch devices automatically every few minutes. Check the **Devices** tab in the web UI. If your speaker doesn't appear, click **Scan Again** to trigger an immediate scan, or enter the IP address manually and click **Add Device**.
+
+![AfterTouch Devices tab showing discovered speakers](../images/ui-devices.png)
+
+### Sync
+
+Once the speaker appears, click **Sync Data**. This connects to the speaker and pulls its current presets, recently played items, and configured sources into the local service's datastore. It also creates an off-device backup of the speaker's configuration.
+
+![Data Sync tab showing a successful sync](../images/ui-sync.png)
+
+If the Bose cloud is still running, Sync also fetches your account data from Bose's servers. This is your preservation step — do it before the cloud shuts down.
+
+---
+
+## Step 5: Migrate
+
+Click **Migrate** next to a device on the Devices tab to open the Migration tab. The tab opens with a **Migration Summary** that shows where your speaker currently stands, then offers a one-click suggested plan and a fully customizable form underneath.
+
+![Migration tab showing the state card and Plan card](../images/ui-migration.png)
+
+### What you see at the top — the state card
+
+Three rows tell you the speaker's current state at a glance:
+
+- **Transports** — whether SSH and Telnet:17000 are reachable. The wizard's choices are driven by these.
+- **Migration State** — three orthogonal axes:
+  - *URL Configuration* — original Bose URLs or AfterTouch URLs (with a special "intercepted via DNS" verdict when the resolv.conf hook is doing the redirect).
+  - *DNS Interception* — none, or `/etc/resolv.conf` hook active.
+  - *CA / TLS* — local root CA installed on the device, with `Trust CA Now` and `Download CA cert` actions inline.
+- **Preconditions** — `remote_services` persistence, account pairing state, and XML config backup presence.
+
+### The Plan card — the happy path
+
+Below the state card is the **Plan** card. For most users this is the only thing you'll touch:
+
+1. **Target service URL** — pre-filled from your Settings. Edit inline and click *Save as default* to update Settings without bouncing tabs.
+2. **Capabilities** — what transports the speaker exposes and what AfterTouch can offer given those.
+3. **Service URLs** — four URL inputs (margeServerUrl, statsServerUrl, swUpdateUrl, bmxRegistryUrl) pre-filled with canonical defaults. Most users leave them as-is; soundcork users tick the *Soundcork mode* checkbox to append `/marge` to `margeServerUrl`. URL validation runs on every keystroke.
+4. **Account pairing** — pre-filled with the speaker's current account ID. Leave it to keep the existing pairing, change it to re-pair, or click *Generate* to assign a new 7-digit ID on a factory-reset device.
+5. **Suggested plan** — one big green button: *Apply Suggested Plan*. The wizard picks the most conservative recipe for your speaker (XML over SSH with HTTP when SSH works; telnet URL flip with HTTP when only telnet works) and runs it.
+
+### What happens when you click Apply
+
+The wizard switches to a visible **Pre-flight checks** panel and runs every applicable verification before touching the speaker:
+
+- **Backend summary re-check** — confirms transports, hostname resolution, and that the URLs you plan to write match what the backend would produce.
+- **HTTPS connection from device** (SSH-capable speakers) — uploads a temporary CA and runs `curl` from the speaker to your service.
+- **Reachability check (passive observer)** (already-migrated speakers) — nudges `:8090/swUpdateCheck` on the device and watches for *any* request from the speaker to land on the service. Used when the speaker is already migrated and the service is the natural target of its outbounds.
+- **"Round-trip validation runs after Apply + reboot"** (not-yet-migrated speakers) — surfaced as a skip row with a rationale. The speaker's swUpdate daemon caches its URL at boot, so there is no useful no-reboot round-trip check pre-migration; the canonical telnet flow is Apply → reboot → re-run pre-flight on the migrated speaker.
+- **DNS redirection from device** — when DNS interception is part of the plan.
+
+On all-green, the wizard auto-proceeds. On any failure, it pauses with *Proceed Anyway* / *Cancel* buttons so you can override on a known-false-positive (slow DNS, etc.) or fix the underlying issue and retry.
+
+### Customize this migration — for mix-and-match
+
+Expand the `▸ Customize this migration` section to pick any combination of three independent axes:
+
+- **URL flip transport** — XML over SSH / Telnet (Port 17000) / Skip
+- **DNS interception** — None / `/etc/resolv.conf` hook
+- **Local CA install** — checkbox (SSH-only)
+
+Each option carries a per-axis availability hint (e.g. *(SSH unreachable)*, *(already trusted)*) so you see why an option is disabled before you pick. *Apply Custom Plan* runs the chosen combination as a sequence; the same pre-flight panel gates the execution.
+
+> **Note**: DNS interception bundles the CA install on the backend, so a standalone CA-install step is skipped automatically when DNS is part of the plan. The wizard handles this for you.
+
+---
+
+## Step 6: Reboot and verify
+
+After a successful Apply the wizard auto-expands the Customize section and highlights the **Reboot Speaker** button. Click it (or power-cycle the speaker manually) to apply all configuration changes. The reboot transport is picked automatically from your URL flip choice — telnet reboot for SSH-less speakers, SSH reboot otherwise.
+
+After reboot:
+- The speaker should appear as **migrated** in the Devices tab
+- The state card on the Migration tab should now show ✅ for URL Configuration (or "intercepted via DNS" if you used the resolv.conf hook)
+- Presets should load and play (served from the local service)
+- TuneIn browsing should work
+- Recently played items should appear
+
+If something doesn't work, check the **Interactions** tab in the web UI for failed requests, and the **Troubleshooting** section in the [SoundTouch Service Guide](SOUNDTOUCH-SERVICE.md).
+
+---
+
+## Repeat for each speaker
+
+Each speaker is migrated independently. You can run multiple migrations in parallel, but migrating one at a time makes it easier to diagnose issues.
+
+---
+
+## Rollback
+
+If you need to undo a migration:
+
+- **From the web UI**: Use the **Revert to Defaults** action on the device — this restores the `.original` backup files created on the speaker during the XML migration.
+- **Telnet-only migrations**: the wizard writes both the runtime configuration layer (`sys configuration …`) and the persistent layer (`envswitch boseurls set …`) so the migration survives reboot. If you want to revert quickly, the cleanest path is to re-run the wizard with the original Bose URLs in the URL editor.
+- **Via SSH**: The original XML config is backed up on the speaker with a `.original` suffix. Restore it manually if the UI is unreachable.
+- **Factory reset**: As a last resort, perform a factory reset (see [Device Initial Setup](DEVICE-INITIAL-SETUP.md) for button sequences). This wipes all configuration and returns the speaker to out-of-box state.
+
+---
+
+## Post-migration
+
+Once all speakers are migrated, the `data/` directory is the source of truth for your presets, recents, and device state. Back it up periodically. The web UI at `http://<server>:8000` is your management interface from this point on.
+
+For the Bose cloud backup you created in Step 4, keep the `.tar.gz` archive in case you need to restore credentials or presets later.

docs/guides/MIGRATION-SAFETY.md

@@ -1,4 +1,4 @@
-### Professional Migration & Safety Guide
+# Migration & Safety Guide
 
 Starting a migration on real hardware requires a "Safety First" approach. This guide outlines the safety features implemented in the `soundtouch-service` and provides a checklist for a successful migration.
 
@@ -14,8 +14,8 @@ The following features are built into the `soundtouch-service` to ensure stabili
 
 Before you proceed with the actual migration, follow these steps:
 
-1.  **Enable SSH Access (Prerequisite)**: This toolkit requires SSH access to your speakers, which is not enabled by default. 
-    - Create an empty file named `remote_services` on a USB stick.
+1.  **Enable SSH Access (Prerequisite)**: This toolkit requires SSH access to your speakers, which is not enabled by default.
+    - Create a file named `remote_services` on a FAT-formatted USB drive. The drive may need its bootable flag set — see [SoundCork issue #172](https://github.com/deborahgu/soundcork/issues/172) for details.
     - Insert the USB stick into the SoundTouch speaker's **SERVICE** port.
     - Reboot the speaker (unplug and replug).
     - The speaker will now allow SSH connections as `root` with no password.
@@ -27,10 +27,11 @@ Before you proceed with the actual migration, follow these steps:
 4.  **Validate SSH Access**: Confirm the device responds to SSH without a password. 
     - In the Web UI **Migration** tab, select your speaker and verify that the "SSH Connection" status shows ✅ Success.
     - This toolkit automatically handles the necessary SSH parameters (ciphers and key exchanges) required by older Bose firmware.
-5.  **Migration Methods**: 
-    - **XML Migration (Default)**: Less invasive, only changes the application config. Best for simple redirection.
-    - **Hosts Migration**: Modifies `/etc/hosts` on the device. Good for system-wide redirection of specific domains.
-    - **ResolvConf Migration**: Points the device to the AfterTouch DNS server. Best for discovering unknown Bose endpoints and dynamic interception. **Note**: This method requires the DNS Discovery Server to be running on port 53. The service includes a pre-flight check to ensure the server is properly bound before allowing this migration.
+5.  **Migration Methods**:
+    - **XML redirect (default)**: Uploads a config file to the speaker via the Web API. Less invasive — only changes the application-level service URLs. Best for testing or single-device migration.
+    - **DNS/DHCP redirect**: Configures the speaker to use a custom DNS server that resolves Bose hostnames to the local service. Best for all-device coverage; requires the AfterTouch DNS server running on port 53. The service includes a pre-flight check before applying this method.
+    
+    The web UI walks you through both methods. Both require the CA certificate to be trusted on the speaker for HTTPS to work — the web UI handles this as part of the migration flow.
 6.  **Monitor Logs**: Run the `soundtouch-service` with `DEBUG` or `INFO` logging to see the step-by-step progress of the migration.
 
 #### 🔄 Rollback Strategy

docs/guides/MUSIC-SERVICES.md

@@ -0,0 +1,130 @@
+# Connecting Music Services (Spotify & Amazon Music)
+
+This guide explains how to link your Spotify or Amazon Music account to AfterTouch so your speakers can stream music from those services.
+
+---
+
+## How it works
+
+Connecting a music service happens in three separate steps, each done once:
+
+1. **Register a developer app** with Spotify or Amazon (one-time setup by the person running AfterTouch).
+2. **Authorize your personal account** so AfterTouch can access your music library.
+3. **Prime your speaker** so the speaker itself learns about the source.
+
+Each step is described below. If someone else is hosting AfterTouch for you, step 1 may already be done — ask them.
+
+---
+
+## Who registers the developer app?
+
+The developer app is what allows AfterTouch to talk to Spotify's or Amazon's servers on behalf of users. It requires registering an account on a developer portal.
+
+**If you run AfterTouch for yourself only:** You register one app and use it yourself.
+
+**If you run AfterTouch for a group** (e.g., your household): You register one app, configure it in AfterTouch, and everyone who uses your AfterTouch instance shares it. They never see your app credentials — those stay on your server. However, they do need to trust you, since their music account tokens are stored by your AfterTouch installation.
+
+**If you don't trust the AfterTouch operator:** Run your own AfterTouch instance and register your own app. That way everything stays under your control.
+
+---
+
+## Spotify
+
+### Step 1: Register a Spotify developer app
+
+1. Go to [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard) and log in with your Spotify account.
+2. Click **Create app**.
+3. Give it any name and description (e.g., "My AfterTouch").
+4. Under **Redirect URIs**, add:
+   ```
+   http://<your-aftertouch-ip>:8000/mgmt/spotify/callback
+   ```
+   Replace `<your-aftertouch-ip>:8000` with the address of your AfterTouch server.
+5. Save the app.
+6. Open the app's settings and note down the **Client ID** and **Client Secret**.
+
+### Step 2: Enter credentials in AfterTouch
+
+1. Open the AfterTouch web interface and go to the **Settings** tab.
+2. Scroll to **Spotify Integration**.
+3. Enter your **Client ID**, **Client Secret**, and the **Redirect URI** you registered above.
+4. Click **Save Settings**.
+
+The status should change to **Active**.
+
+### Step 3: Authorize your Spotify account
+
+1. Go to the **Local Account** tab (tab 7).
+2. Click **Connect Spotify to this Account**.
+3. A Spotify login window opens. Log in and grant permission.
+4. When the window closes, your account is linked. You should see your Spotify username appear.
+
+### Step 4: Prime your speaker
+
+After authorizing, each speaker needs to be told about the Spotify source.
+
+1. Go to the **Devices** tab (tab 2).
+2. Find your speaker and click **Prime Spotify**.
+3. The speaker will now show Spotify as an available source.
+
+Repeat step 4 for each speaker.
+
+---
+
+## Amazon Music
+
+> **Current status: account linking works, streaming does not.**
+>
+> The OAuth flow and token storage are fully functional. However, the speaker's `AmazonClient` contacts `music-api.amazon.com` directly with the access token and receives a 401. Amazon Music's streaming API requires scopes that are only available to registered Amazon Music partners — a standard Login with Amazon app does not qualify. The infrastructure is in place and will work if those scopes ever become available, but following these steps will not result in working Amazon Music playback today.
+
+### Step 1: Register an Amazon developer app (LWA)
+
+1. Go to [developer.amazon.com/loginwithamazon/console/site/lwa/overview.html](https://developer.amazon.com/loginwithamazon/console/site/lwa/overview.html) and log in with your Amazon account.
+2. Click **Create a New Security Profile**.
+3. Give it any name and description (e.g., "My AfterTouch").
+4. In the security profile's **Web Settings**, add under **Allowed Return URLs**:
+   ```
+   http://<your-aftertouch-ip>:8000/mgmt/amazon/callback
+   ```
+   Replace `<your-aftertouch-ip>:8000` with the address of your AfterTouch server.
+5. Save and note down the **Client ID** and **Client Secret**.
+
+### Step 2: Enter credentials in AfterTouch
+
+1. Open the AfterTouch web interface and go to the **Settings** tab.
+2. Scroll to **Amazon Music Integration**.
+3. Enter your **Client ID**, **Client Secret**, and the **Redirect URI** you registered above.
+4. Click **Save Settings**.
+
+The status should change to **Active**.
+
+### Step 3: Authorize your Amazon account
+
+1. Go to the **Local Account** tab (tab 7).
+2. Click **Connect Amazon Music to this Account**.
+3. An Amazon login window opens. Log in and grant permission.
+4. When the window closes, your account is linked.
+
+### Step 4: Prime your speaker
+
+1. Go to the **Devices** tab (tab 2).
+2. Find your speaker and click **Prime Amazon**.
+3. The speaker will now show Amazon Music as an available source.
+
+Repeat step 4 for each speaker.
+
+---
+
+## Troubleshooting
+
+**"Failed to initialize" when clicking Connect:**
+The app credentials in Settings are missing or incorrect. Double-check the Client ID, Client Secret, and Redirect URI. The Redirect URI in AfterTouch must exactly match the one registered in the developer portal.
+
+**The login window opens but redirects to an error page:**
+The Redirect URI registered with Spotify/Amazon does not match what AfterTouch is sending. Make sure the address (including the port) is identical in both places.
+
+**The speaker doesn't show the new source after priming:**
+Try rebooting the speaker. It may take a minute to update its source list after priming.
+
+**The login window doesn't open (popup blocked):**
+Allow popups from the AfterTouch address in your browser settings, then try again. Alternatively, the status message will show a direct link you can click.

docs/guides/SELF-HOSTING.md

@@ -0,0 +1,132 @@
+# Self-Hosting AfterTouch
+
+This guide walks you through running AfterTouch on your own computer or server. No programming knowledge required.
+
+---
+
+## What is self-hosting?
+
+AfterTouch is software that runs on a computer in your home and takes over the role of Bose's cloud servers. Your speakers talk to it instead of Bose.
+
+For this to work, the computer running AfterTouch must be:
+
+- **Always on** (or at least on whenever you want to use your speakers)
+- **On the same local network** as your speakers
+- **Reachable by a stable IP address** (see [Stable IP Address](#stable-ip-address) below)
+
+Good choices: a Raspberry Pi, a NAS (like Synology or QNAP), an always-on PC or Mac, or a small server. A laptop that you close and put away is not ideal.
+
+---
+
+## Step 1: Get the software
+
+Go to the [AfterTouch releases page](https://github.com/gesellix/Bose-SoundTouch/releases) and download the latest release for your operating system:
+
+| Your system           | File to download                         |
+|-----------------------|------------------------------------------|
+| Raspberry Pi (64-bit) | `soundtouch-service_linux_arm64.tar.gz`  |
+| Raspberry Pi (32-bit) | `soundtouch-service_linux_arm.tar.gz`    |
+| Linux (64-bit PC)     | `soundtouch-service_linux_amd64.tar.gz`  |
+| macOS (Apple Silicon) | `soundtouch-service_darwin_arm64.tar.gz` |
+| macOS (Intel)         | `soundtouch-service_darwin_amd64.tar.gz` |
+| Windows               | `soundtouch-service_windows_amd64.zip`   |
+
+Extract the archive. You will find a single file called `soundtouch-service` (or `soundtouch-service.exe` on Windows).
+
+### Alternative: Docker
+
+If you already use Docker, you can run AfterTouch as a container instead. See the [Deployment Guide](DEPLOYMENT.md) for Docker instructions.
+
+---
+
+## Step 2: Run it
+
+Open a terminal (or Command Prompt on Windows), navigate to the folder where you extracted the file, and run:
+
+```
+./soundtouch-service
+```
+
+On Windows:
+```
+soundtouch-service.exe
+```
+
+You should see log output like:
+```
+Starting AfterTouch service on :8000
+```
+
+AfterTouch is now running on port 8000.
+
+---
+
+## Step 3: Open the web interface
+
+In a web browser on any device on your network, go to:
+
+```
+http://<your-server-ip>:8000
+```
+
+Replace `<your-server-ip>` with the actual IP address of the computer running AfterTouch. For example: `http://192.168.1.100:8000`.
+
+If you are on the same computer that is running AfterTouch, you can use `http://localhost:8000`.
+
+You should see the AfterTouch web interface with tabs: Overview, Settings, Devices, and so on.
+
+---
+
+## Step 4: Configure the server URL
+
+This is the most important setting. Go to the **Settings** tab and set the **Target Domain** to the full address of your AfterTouch server — the same address you used to open the web interface:
+
+```
+http://192.168.1.100:8000
+```
+
+Use the IP address of your server, **not** `localhost`. Your speakers need to reach this address over the network, and they cannot resolve `localhost`.
+
+Click **Save Settings**.
+
+---
+
+## Step 5: Proceed with migration
+
+You are now ready to migrate your speakers. Follow the main [Migration Guide](MIGRATION-GUIDE.md) for the remaining steps (discovering devices, syncing data, and redirecting your speakers to AfterTouch).
+
+---
+
+## Keeping AfterTouch running
+
+By default, AfterTouch stops when you close the terminal. To keep it running permanently:
+
+**Raspberry Pi / Linux:** See the [Raspberry Pi Guide](RASPBERRY-PI.md) for instructions on running AfterTouch as a background service using `systemd`.
+
+**NAS devices:** Most NAS systems support Docker. Use the Docker instructions in the [Deployment Guide](DEPLOYMENT.md).
+
+**macOS:** You can use `launchd` to run AfterTouch at login. Creating a `launchd` plist is beyond this guide, but the [Deployment Guide](DEPLOYMENT.md) has a systemd example you can adapt.
+
+**Windows:** You can use Task Scheduler to run AfterTouch at startup.
+
+---
+
+## Stable IP address
+
+AfterTouch must always be reachable at the same address, because your speakers will be configured to point to it. If the IP changes, your speakers will stop working until you reconfigure them.
+
+The easiest solution is to assign a **static (fixed) IP address** to the computer running AfterTouch in your router's settings. Look for "DHCP reservation" or "static IP" in your router's administration interface, and bind the server's MAC address to a fixed IP.
+
+---
+
+## Security note
+
+AfterTouch's web interface and management API have no login by default. On a typical home network this is fine, since only devices on your local network can reach it.
+
+If you want to restrict access — for example, on a shared network — start the service with a username and password:
+
+```
+./soundtouch-service --mgmt-username admin --mgmt-password yourpassword
+```
+
+This protects the Settings tab (where your Spotify and Amazon credentials are stored) from being read or changed by others on the network.

docs/guides/SOUNDTOUCH-SERVICE.md

@@ -7,7 +7,7 @@ The `soundtouch-service` is a comprehensive local server that emulates Bose's cl
 The service provides:
 
 - **🏠 Local Service Emulation**: Complete BMX (Bose Media eXchange) and Marge service implementation
-- **🔧 Device Migration**: Seamlessly migrate devices from Bose cloud to local services via XML config, `/etc/hosts`, or `/etc/resolv.conf`
+- **🔧 Device Migration**: Migrate devices from Bose cloud to local services via XML redirect or DNS/DHCP redirect
 - **🔍 DNS Discovery & Interception**: Built-in DNS server to discover unknown Bose endpoints and selectively intercept cloud traffic
 - **📊 Traffic Proxying**: Inspect and log all device communications for debugging
 - **🌐 Web Management UI**: Browser-based interface for device management
@@ -169,7 +169,7 @@ The service supports multiple ways to configure its behavior. When multiple sour
 | `DISCOVERY_INTERVAL`               | `--discovery-interval`     | Device discovery interval                                                                               | `5m`                      |
 | `ENABLE_DNS_DISCOVERY`             | `--dns-discovery`          | Enable DNS discovery server                                                                             | `false`                   |
 | `DNS_UPSTREAM`                     | `--dns-upstream`           | Upstream DNS server for non-Bose queries                                                                | `8.8.8.8`                 |
-| `DNS_BIND_ADDR`                    | `--dns-bind`               | Bind address for the DNS discovery server (standard port `:53` is required for `resolv.conf` migration) | `:53`                     |
+| `DNS_BIND_ADDR`                    | `--dns-bind`               | Bind address for the DNS discovery server (standard port `:53` is required for DNS/DHCP migration)      | `:53`                     |
 | `MIRROR_ENABLED`                   |                            | Enable background mirroring of specific endpoints to Bose cloud                                         | `false`                   |
 | `MIRROR_ENDPOINTS`                 |                            | Comma-separated list of path patterns to mirror (e.g., `/streaming/account/*/device/*/recent`)          | `[]`                      |
 | `INTERNAL_PATHS`                   | `--internal-paths`         | Paths for internal requests to exclude from recording (e.g., `/setup/*`, `/web/*`)                      | `[]`                      |
@@ -225,13 +225,21 @@ curl http://localhost:8000/setup/devices
 #### Advanced Migration Options
 
 ```bash
-# Migration with proxy fallback for original services
-curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?proxy_url=http://localhost:8000&marge=original&stats=original"
-
 # Migration with custom target URL
 curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?target_url=https://my-server.com:8000"
+
+# Per-field literal URL overrides (preferred — used by the web wizard)
+curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=xml&target_url=http://server:8000&marge_url=http://server:8000/marge"
+
+# SSH-less migration over the device's port-17000 diagnostic shell
+curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=telnet&target_url=http://server:8000"
+
+# Legacy proxy-fallback for selected fields (kept for API back-compat)
+curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?proxy_url=http://localhost:8000&marge=original&stats=original"
 ```
 
+See the full parameter reference at `POST /setup/migrate/{deviceIP}` below for `method`, `target_url`, `*_url`, and the legacy mode selectors.
+
 ### Post-Migration Verification
 
 After migration, verify the device is working correctly:
@@ -247,7 +255,7 @@ curl "http://192.168.1.100:8090/presets"
 curl "http://localhost:8000/events/192.168.1.100"
 ```
 
-#### ResolvConf Migration (DHCP-Aware DNS Redirection)
+#### DNS/DHCP Migration (DHCP-Aware DNS Redirection)
 
 The most robust and flexible DNS-based migration method. It utilizes the device's persistent `/mnt/nv/rc.local` script to inject a priority DNS hook into the system's DHCP configuration.
 
@@ -393,12 +401,73 @@ Analyzes device configuration and provides migration preview.
 Migrates device to use local services.
 
 **Query Parameters:**
-- `target_url`: Custom service URL (optional)
-- `proxy_url`: Proxy URL for fallback (optional)
-- `marge`: Set to "original" to proxy Marge requests (optional)
-- `stats`: Set to "original" to proxy stats requests (optional)
-- `sw_update`: Set to "original" to proxy update requests (optional)
-- `bmx`: Set to "original" to proxy BMX requests (optional)
+
+| Parameter    | Values                                                    | Notes                                                                                                                                                                                                                                                    |
+|--------------|-----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `method`     | `xml` (default), `telnet`, `resolv`, `hosts` (deprecated) | Picks the redirect mechanism. `xml` writes `SoundTouchSdkPrivateCfg.xml` via SSH; `telnet` flips the four URLs via the device's port-17000 diagnostic shell; `resolv` installs the `/etc/resolv.conf` priority-nameserver hook and the local CA via SSH. |
+| `target_url` | Any URL, e.g. `http://soundtouch.local:8000`              | Service base URL the per-field defaults derive from. Falls back to the service's configured `ServerURL` when omitted.                                                                                                                                    |
+| `proxy_url`  | Any URL                                                   | Proxy base used when the legacy `marge=proxied` / `stats=proxied` / `sw_update=proxied` / `bmx=proxied` modes are set. Defaults to `target_url`.                                                                                                         |
+
+**Per-field implementation mode** (XML method's legacy semantics — kept for API back-compat, UI no longer sets them):
+
+| Parameter   | Values                                  | Effect on the matching `*ServerUrl` / `*RegistryUrl` field                                                                                        |
+|-------------|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| `marge`     | `self` (default), `proxied`, `original` | `self`: write `target_url` (canonical). `proxied`: write `<proxy_url>/proxy/<original-marge-url>`. `original`: keep the speaker's existing value. |
+| `stats`     | same                                    | same                                                                                                                                              |
+| `sw_update` | same                                    | same                                                                                                                                              |
+| `bmx`       | same                                    | same                                                                                                                                              |
+
+**Per-field literal URL overrides** (preferred — used by the wizard's Plan card; honored for both `xml` and `telnet` methods):
+
+| Parameter       | Effect                                                                                                                                                                |
+|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `marge_url`     | Writes the exact URL to `<margeServerUrl>` regardless of `target_url` derivation or `marge` mode. Empty / missing → fall back to canonical default from `target_url`. |
+| `stats_url`     | Same shape for `<statsServerUrl>`.                                                                                                                                    |
+| `sw_update_url` | Same for `<swUpdateUrl>`.                                                                                                                                             |
+| `bmx_url`       | Same for `<bmxRegistryUrl>`.                                                                                                                                          |
+
+**Precedence**: `*_url` overrides win over the `marge / stats / sw_update / bmx` mode selectors. The setup package applies `applyProxyOptions` first, then `applyURLOverrides` clobbers any field where a literal `*_url` was supplied. So if you send both `marge=proxied&marge_url=http://x:8000/marge`, the literal `http://x:8000/marge` is written.
+
+**Soundcork redirect**: append `/marge` to `marge_url`. The telnet method derives `envswitch boseurls set <margeServerUrl> <swUpdateUrl>` from the final URLs verbatim, so the suffix propagates to the parallel persistence layer automatically — no separate flag needed.
+
+**Examples**:
+
+```bash
+# Canonical XML migration over SSH to the default service URL
+curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=xml"
+
+# Telnet migration with the soundcork redirect (only marge gets the /marge suffix)
+curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=telnet&target_url=http://soundcork.local:8000&marge_url=http://soundcork.local:8000/marge"
+
+# DNS interception (writes /etc/resolv.conf hook + installs CA) — *_url overrides are ignored
+curl -X POST "http://localhost:8000/setup/migrate/192.168.1.100?method=resolv&target_url=https://my-server.com:8443"
+```
+
+#### `POST /setup/telnet-probe/{deviceIP}`
+SSH-less reachability check. Temporarily flips the speaker's `swUpdateUrl` via the port-17000 diagnostic shell, triggers `:8090/swUpdateCheck` on the device, and observes whether the resulting outbound lands on this service's `/probe/{token}` handler within 6 s. Always attempts to restore the original `swUpdateUrl` even on failure.
+
+**Query Parameters:**
+- `target_url` (optional): defaults to the service's configured `ServerURL`. The probe URL written to the device is `<target_url>/probe/<token>`.
+
+**Response:**
+```json
+{
+  "ok": true,
+  "result": {
+    "reached": true,
+    "restored": true,
+    "original_url": "https://worldwide.bose.com/updates/soundtouch",
+    "probe_url": "http://soundtouch.local:8000/probe/abc123…",
+    "elapsed_ms": 412,
+    "logs": "…"
+  }
+}
+```
+
+`reached=true` means the device's outbound landed on our `/probe/{token}` route within the timeout. `restored=true` means the runtime `swUpdateUrl` was reverted to its captured original (the envswitch persistence layer is left untouched throughout, so a reboot heals the device naturally if our restore step fails).
+
+#### `GET /probe/{token}[/*]`
+Catch-all endpoint that signals the matching pre-flight probe channel. Used internally by `/setup/telnet-probe/{deviceIP}`; not intended to be called directly by API consumers. Returns a minimal `<swUpdateIndex/>` XML so the device's `swUpdateCheck` doesn't choke on a missing structure.
 
 ### BMX Services (Bose Media eXchange)
 
@@ -665,7 +734,7 @@ find data/stats/ -name "*.json" -mtime +90 -delete
 - `GET /setup/discovery-status`: Check if a scan is currently in progress.
 - `POST /setup/sync/{deviceIP}`: Fetch presets, recents, and sources from a device.
 - `GET /setup/summary/{deviceIP}`: Get a detailed migration readiness summary.
-- `POST /setup/migrate/{deviceIP}`: Migrate a device using the specified method (XML/Hosts).
+- `POST /setup/migrate/{deviceIP}`: Migrate a device using the specified method (XML or DNS).
 - `GET /setup/ca.crt`: Download the Root CA certificate for manual installation.
 
 #### `GET /setup/interactions`
@@ -836,6 +905,7 @@ fi
 - **SSH Access**: Migration requires SSH access to devices. Ensure your network security policies allow this.
 - **Proxy Logging**: Disable `REDACT_PROXY_LOGS` only in development environments.
 - **Data Protection**: The data directory contains device configurations and usage patterns. Secure appropriately.
+- **Spotify / Amazon Music credential push (zeroconf)**: outbound credential-push requests are restricted to literal IP hosts on local-network ranges (loopback, RFC1918 private, IPv4/IPv6 link-local). Hostname-style URLs (DNS, mDNS `*.local`) are rejected at runtime; if you have a hostname, resolve it first (`getent hosts <name>` or `dig +short <name>`) and pass the resolved IP. This guards against a malicious LAN-resident speaker pointing the credential push at a non-speaker host (server-side request forgery).
 
 ## Performance Tuning
 

docs/guides/SURVIVAL-GUIDE.md

@@ -1,85 +1,107 @@
-### Bose Cloud Shutdown: Survival Guide for SoundTouch
+# Bose Cloud Shutdown: Survival Guide
 
-With Bose's announcement of discontinuing cloud support for SoundTouch devices in May 2026, this project provides the necessary tools to keep your speakers fully functional using a local emulation service.
+Bose is shutting down SoundTouch cloud services on **May 6, 2026**. After that date, the following stop working:
 
-This guide explains how to set up the `soundtouch-service` to run your devices independently of Bose's servers.
+- Music service browsing (TuneIn, Spotify connect via app, etc.)
+- Preset and recently-played sync
+- The official SoundTouch app
+- Software update checks
+
+What **continues to work** regardless:
+- Local playback controls via `soundtouch-cli`, `soundtouch-web`, or any app that uses the local Web API
+- Bluetooth, AUX, and AirPlay inputs
+- Multiroom zones (local, peer-to-peer)
+
+**AfterTouch** — the `soundtouch-service` — restores everything in the first list by running a local replacement for the Bose cloud on your own network.
 
 ---
 
-### Supported Use Cases
+## How it works
 
-1.  **Local Service Emulation**: The service emulates Bose's BMX (Bose Media eXchange) and Marge services, which handle content registries, presets, recents, and software update checks.
-2.  **Traffic Redirection**: Tools are provided to redirect your speakers to this local service instead of `*.bose.com`.
-3.  **Offline Operation**: Once redirected, the speakers function without needing to reach Bose's servers.
-4.  **Preset & Recent Management**: Captures and stores presets and "recently played" items locally.
+The service emulates the Bose cloud endpoints that speakers call for music service browsing, device registration, preset sync, and update checks. Once a speaker is redirected to point at the local service instead of Bose's servers, it operates independently. The built-in web UI at `http://<server>:8000` handles all setup steps.
 
 ---
 
-### Setup Steps
+## Prerequisites
 
-To set up your SoundTouch system for local-only operation, follow these steps:
+### 1. A machine that's always on
 
-#### 1. Install and Start the Service
-Run the `soundtouch-service` on a machine that is always on (like a Raspberry Pi or a NAS) within your local network.
+The service must run on a host that's available whenever your speakers are in use — a Raspberry Pi, NAS, home server, or similar. The host needs a stable local address (e.g. `soundtouch.fritz.box` or a fixed IP) reachable from your speakers.
 
-```bash
-# Install the service
-go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
+See [Raspberry Pi Setup](RASPBERRY-PI.md) and the [SoundTouch Service Guide](SOUNDTOUCH-SERVICE.md) for deployment options, including Docker.
 
-# Start the service (defaults to http://localhost:8000)
-soundtouch-service
-```
+### 2. SSH access on your speakers (for migration)
 
-#### 2. Access the Management UI
-Open your web browser and navigate to the service's web interface:
-`http://<your-server-ip>:8000/`, e.g. `http://localhost:8000/`
+Redirecting a speaker's service URLs requires writing to its configuration. This is done via SSH. Enable it once per device:
 
-*Note: The service also supports a `/web/` path for management.*
+1. Create a file named `remote_services` on a FAT-formatted USB drive. The drive may need its bootable flag set — see [SoundCork issue #172](https://github.com/deborahgu/soundcork/issues/172) for details.
+2. Insert the drive into the speaker's USB port while it's powered on.
+3. Power-cycle the speaker (unplug and replug). After boot, root SSH is available with no password.
 
-#### 3. Enable SSH on Your Speakers
-To migrate your speakers, the service needs SSH access. You can enable it by:
-1. Creating an empty file named `remote_services` on a USB stick.
-2. Inserting the USB stick into the SoundTouch speaker's service port.
-3. Rebooting the speaker (unplug/replug).
-
-**Verify SSH Access:**
-- Confirm the device responds to SSH without a password: `ssh -o HostKeyAlgorithms=+ssh-rsa -o PubkeyAcceptedAlgorithms=+ssh-rsa root@<IP>`
-- Or use the **Migration** tab in the Web UI to see if the device shows a "✅ Success" status for SSH.
-Once enabled, you can log in as `root` (no password).
-
-#### 4. Setup Through the Web UI
-The web interface handles the entire process in a guided flow. Before proceeding, we strongly recommend reviewing the [Migration & Safety Guide](MIGRATION-SAFETY.md).
-
-*   **Step 1: Settings**: Configure your server's IP or domain. This ensures the speakers know where to find the local services.
-*   **Step 2: Devices**: The service automatically scans for SoundTouch devices on your network. If a device is not found, you can manually add its IP address.
-*   **Step 3: Data Sync**: Select your device and click "Start Sync". This will automatically fetch your presets, recents, and configured sources from the speaker and store them in the local `data/` directory.
-*   **Step 4: Migration**: Choose your redirection method (XML Recommended) and click "Confirm Migration". After the migration, reboot your speaker to apply the changes.
-
-#### 5. Verify Your Local Data
-Once migrated, your speaker will use the data captured during the Sync step.
-*   The service stores data in the `data/` directory, organized by device serial number (e.g., `data/default/devices/<SERIAL>/`).
-*   **Automatic Capture**: As you use the device (changing presets, playing new music), the service continues to "learn" and update your local files.
+You can leave SSH enabled for future maintenance, or disable it once migration is complete.
 
 ---
 
-### Comparison with other implementations (soundcork)
-Our implementation (`soundtouch-service`) is largely compatible with the Python-based `soundcork` project but offers several advantages:
-- **Web UI**: Integrated management interface for discovery and migration.
-- **Surgical Migration**: Uses XML-based redirection by default, which is less invasive than `/etc/hosts`.
-- **Automated SSL**: Handles Root CA injection automatically for secure communication.
-- **Proxy Support**: Can proxy requests to original Bose servers while "learning" your configuration.
+## Scenario A: Migrate before the shutdown
+
+Do this while the Bose cloud is still running. Your existing presets and listening history are preserved.
+
+**Step 1 — Back up your data.**
+Run `soundtouch-backup all` to save your Bose account data (presets, paired devices, music sources) and each speaker's local state. See the [soundtouch-backup README](../../cmd/soundtouch-backup/README.md) for usage.
+
+**Step 2 — Start the service and open the web UI** at `http://<server>:8000`.
+
+**Step 3 — Configure the server URL.**
+In the Settings tab, set the server URL to the address your speakers can reach (e.g. `http://soundtouch.fritz.box:8000`). If you plan to use DNS/DHCP redirect, also configure the HTTPS server URL.
+
+**Step 4 — Add your speaker.**
+The service discovers devices on your network automatically. If a speaker doesn't appear, add it manually by IP address.
+
+**Step 5 — Sync device data.**
+Click "Sync" on the device to pull its current presets, recents, and sources from the Bose cloud into the local service's datastore.
+
+**Step 6 — Migrate.**
+The web UI offers two redirect methods and walks you through each step:
+
+| Method       | How it works                                           | When to use                                              |
+|--------------|--------------------------------------------------------|----------------------------------------------------------|
+| XML redirect | Uploads a config file to the speaker via the Web API   | Testing; simpler setup; covers only registered endpoints |
+| DNS/DHCP     | Custom DNS resolves Bose hostnames to the local server | All devices at once; full coverage                       |
+
+Both methods require TLS when the speaker uses HTTPS to contact the service. The web UI guides you through installing the service's CA certificate on the speaker (requires SSH).
+
+**Step 7 — Reboot the speaker.**
+Power-cycle the speaker to apply the changes. After reboot it contacts the local service instead of Bose's cloud.
 
 ---
 
-### Alternative: DNS Redirection (No SSH)
-If you prefer not to modify your speakers via SSH, you can use a local DNS server (like Pi-hole, AdGuard Home, or Unbound) to point the following domains to your local server's IP:
+## Scenario B: Set up after the shutdown (or after a factory reset)
 
-*   `bmx.bose.com`
-*   `streaming.bose.com`
-*   `updates.bose.com`
-*   `stats.bose.com`
-*   `content.api.bose.io`
+If the Bose cloud is gone, or you've factory-reset a speaker, there's no existing account to migrate from. You start fresh with a local account.
 
-*Note: DNS redirection for HTTPS services requires the speakers to trust your local service's SSL certificate. The SSH-based migration handles this automatically by injecting the CA.*
+**Step 1 — Set up DNS/DHCP redirect first** (recommended).
+Configure your network's DNS to resolve the Bose cloud hostnames to the local service's address before the speaker tries to register. This way, when the speaker boots and attempts to register, it reaches AfterTouch automatically instead of failing to reach Bose.
+
+See the [SoundTouch Service Guide](SOUNDTOUCH-SERVICE.md) for the built-in DNS server configuration and the list of hostnames to redirect.
+
+**Step 2 — Connect the speaker to Wi-Fi.**
+Use the speaker's built-in AP mode or BLE setup flow. See [Device Initial Setup](DEVICE-INITIAL-SETUP.md) for factory reset button sequences and Wi-Fi provisioning.
+
+**Step 3 — Start the service and open the web UI** at `http://<server>:8000`.
+
+**Step 4 — Add the speaker.**
+After connecting to Wi-Fi, the speaker should appear in the web UI automatically (or add it manually by IP). If DNS redirect is already in place, the speaker is already communicating with AfterTouch.
+
+**Step 5 — Migrate** (if not already using DNS redirect).
+If you didn't set up DNS first, use the XML redirect method from the web UI to update the speaker's service URLs. The web UI walks you through the steps including CA certificate setup.
+
+**Step 6 — Reboot the speaker.**
+Power-cycle to ensure all changes take effect.
 
 ---
+
+## After migration
+
+Once migrated, your speaker uses the local service for music browsing, preset sync, and device registration. The web UI at `http://<server>:8000` is your management interface going forward. Back up the `data/` directory periodically in case you need to restore.
+
+For the complete step-by-step walkthrough with commands and troubleshooting, see the [Migration Guide](MIGRATION-GUIDE.md). For safety measures and rollback options, see the [Migration & Safety Guide](MIGRATION-SAFETY.md).

docs/guides/TROUBLESHOOTING.md

@@ -853,6 +853,85 @@ cat data/accounts/3230304/devices/*/DeviceInfo.xml | grep macAddress
 
 ---
 
+## 🌐 **Hostname Resolution** {#hostname-resolution}
+
+### Why the service resolves the hostname from the device
+
+When you migrate a speaker using the resolv.conf method, the service needs to write a raw IP address into the speaker's network configuration. That IP must be the address the *speaker itself* can reach — which is not necessarily the same address your computer resolves.
+
+In environments with NAT, split-horizon DNS, or Docker/container networking, `soundtouch.local` (or whatever you set as `SERVER_URL`) may resolve to a different IP depending on who is asking. The service therefore resolves the hostname by running `ping -c 1 <hostname>` over SSH on the speaker and extracting the IP from the output. This is the authoritative result: it is exactly what the speaker would use.
+
+If that SSH ping fails, migration is aborted. Writing an unresolvable or incorrectly resolved hostname into `aftertouch.resolv.conf` would silently break the speaker's DNS config and prevent it from reaching the service after reboot.
+
+**The XML migration method is different.** It writes the full URL (e.g. `http://soundtouch.local:8000`) into `SoundTouchSdkPrivateCfg.xml`. The speaker resolves the hostname at connect time, not at migration time. This means migration can proceed even if the hostname is not yet reachable — for example, when the service will be deployed under that hostname but is not running yet. A warning is still shown in the UI so you are aware, but the Confirm Migration button remains enabled.
+
+### ❌ "Cannot resolve target hostname for migration"
+
+**Symptoms** (migration log or web UI warning):
+```
+cannot resolve target hostname for migration: cannot resolve "soundtouch.local":
+SSH ping from device failed and service-side DNS lookup also failed
+```
+or:
+```
+resolved "soundtouch.local" to 192.168.1.100 from service, not from device —
+result may be wrong if NAT or split-DNS is in use
+```
+
+**What this means:**
+
+The service could not confirm the IP by running `ping` on the speaker via SSH. Either:
+- the `ping` binary is not available or not in `$PATH` on this firmware, or
+- the hostname is not resolvable from the speaker's network context.
+
+**Diagnosis — run manually over SSH:**
+
+```bash
+# SSH into the speaker
+ssh root@<speaker-ip>
+
+# Try to resolve the service hostname
+ping -c 1 soundtouch.local
+# or use the IP directly to verify connectivity
+ping -c 1 192.168.1.100
+
+# Check the speaker's current DNS config
+cat /etc/resolv.conf
+
+# Check if ping is available
+which ping
+busybox ping --help
+```
+
+**Solutions:**
+
+#### 1. Use an IP address as SERVER_URL
+
+The most reliable fix. If the hostname cannot be resolved from the device, use a raw IP instead. Resolution is skipped entirely when `SERVER_URL` contains an IP.
+
+```bash
+# In your .env
+SERVER_URL=http://192.168.1.100:8000
+HTTPS_SERVER_URL=https://192.168.1.100:8443
+```
+
+HTTPS works correctly with IP addresses — the service certificate includes the IP as a Subject Alternative Name (SAN).
+
+#### 2. Ensure the hostname resolves on the speaker's network segment
+
+If you use `soundtouch.local`, verify mDNS is working from another device on the same subnet:
+
+```bash
+avahi-resolve -n soundtouch.local    # Linux
+dns-sd -G v4 soundtouch.local        # macOS
+```
+
+#### 3. Use the XML migration method
+
+Select the XML method in the migration UI. It writes the full URL and the speaker resolves it at connect time, so hostname resolution is not required during migration. This also allows migrating to a hostname that is not yet live.
+
+---
+
 ## 🛟 **Getting More Help**
 
 ### Information to Gather

docs/images/README.md

@@ -1,90 +1,17 @@
-# Images for Migration Guide
+# docs/images
 
-This directory contains images, screenshots, and diagrams referenced in the migration guide and other documentation.
+Screenshots and diagrams referenced by the documentation.
 
-## Required Images for Migration Guide
+## Current screenshots
 
-The following images need to be created to complete the migration guide:
+| File | Shows | Used in |
+|------|-------|---------|
+| `ui-settings.png` | AfterTouch web UI — Settings tab (Target Domain, DNS Discovery, Mirroring) | Migration Guide |
+| `ui-devices.png` | AfterTouch web UI — Devices tab (discovered speakers with Sync/Migrate actions) | Migration Guide |
+| `ui-sync.png` | AfterTouch web UI — Data Sync tab (successful sync result) | Migration Guide |
+| `ui-migration.png` | AfterTouch web UI — Migration tab (HTTPS test, DNS test, method selector) | Migration Guide |
+| `speaker-ap-wifi-setup.png` | Speaker AP mode Wi-Fi setup page at `http://192.0.2.1` | Device Initial Setup |
 
-### Dashboard Screenshots
-- **dashboard-home.png** - Main SoundTouch Service dashboard homepage
-- **account-creation.png** - Account creation form with fields filled
-- **account-dashboard.png** - Fresh account dashboard showing ready state
-- **device-discovery.png** - Device discovery page showing found speakers
-- **device-registration.png** - Device registration dialog with options
-- **migration-setup.png** - Migration configuration dialog
-- **migration-progress.png** - Migration progress tracker showing phases
-- **migration-health.png** - Migration health monitoring dashboard
-- **account-migration.png** - Account-wide migration progress overview
-- **migration-complete.png** - Completed migration dashboard view
-- **backup-setup.png** - Backup configuration settings page
+## Adding new screenshots
 
-### Setup and Preparation
-- **usb-remote-services.png** - USB drive setup showing file structure
-- **raspberry-pi-setup.png** - Raspberry Pi with connected cables (optional)
-
-### Process Diagrams
-- **migration-flow-diagram.png** - Flow chart showing migration phases
-- **network-topology.png** - Network diagram showing Pi, router, speakers
-- **data-flow-diagram.png** - How data flows between components
-
-## Image Requirements
-
-### Technical Specifications
-- **Format**: PNG preferred for screenshots, SVG for diagrams
-- **Resolution**: Minimum 1200px width for screenshots
-- **File Size**: Keep under 500KB when possible for fast loading
-- **Naming**: Use descriptive kebab-case names as shown above
-
-### Content Guidelines
-- **Clean Interface**: Show realistic but clean interface states
-- **Consistent Styling**: Use consistent colors and styling across images
-- **Readable Text**: Ensure all text in screenshots is legible
-- **Example Data**: Use realistic example data (Living Room Speaker, etc.)
-- **Status Indicators**: Show clear success/error states with appropriate colors
-
-### Placeholder Content
-Until real screenshots are available, consider:
-- **Mockups**: Create simple mockups showing the expected interface
-- **Wireframes**: Basic wireframes indicating layout and content
-- **Diagrams**: Technical diagrams can be created immediately
-- **Text Placeholders**: Use `[Image: Description]` in documentation
-
-## Creating the Images
-
-### For Dashboard Screenshots
-1. Set up the enhanced SoundTouch service
-2. Create sample account and register devices
-3. Take screenshots at key points in the migration process
-4. Edit for clarity (highlight important elements, add annotations)
-
-### For Diagrams
-1. Use tools like Lucidchart, draw.io, or similar
-2. Follow consistent color scheme:
-   - Blue: SoundTouch Service components
-   - Green: Healthy/successful states
-   - Orange: Warning/in-progress states
-   - Red: Error/problematic states
-   - Gray: External/third-party components
-
-### For Physical Setup
-1. Take photos of actual hardware setup
-2. Show USB drive preparation process
-3. Demonstrate network connections if helpful
-
-## Alternative Text Requirements
-
-Each image should have appropriate alt text for accessibility:
-
-```markdown
-![Alt text describing the image content](../images/image-name.png)
-*Caption: Additional context or explanation*
-```
-
-## Future Enhancements
-
-Consider adding:
-- **Video Walkthroughs**: Screen recordings of key processes
-- **Interactive Demos**: Web-based interactive guides
-- **Troubleshooting Screenshots**: Common error states and solutions
-- **Mobile Views**: How to access from mobile devices
+PNG format, 1200 px or wider. Use descriptive kebab-case names. Update this README when adding files.

docs/reference/DEVICE-PAIRING-FLOW.md

@@ -0,0 +1,521 @@
+# SoundTouch Device WebSocket API — Pairing & Operation Flow
+
+Reference document derived from mitmproxy captures of the Bose SoundTouch Android app
+(`bose-pairing-20260502-155542`, `bose-pairing-20260502-165549`).
+
+> **Why this matters:** With Bose cloud services shutting down on 2026-05-06, the original
+> app may stop working for pairing and playback control. This document captures the exact
+> WebSocket message sequences needed to replicate those flows independently.
+
+---
+
+## Connection
+
+All interactions use the SoundTouch WebSocket API on the speaker's local IP, port **8090**
+(the same port as the REST API). Connect with the `Gabbo` sub-protocol:
+
+```
+GET ws://192.168.x.y:8090/
+Upgrade: websocket
+Sec-WebSocket-Protocol: Gabbo
+```
+
+Upon connection the server immediately sends an identification banner:
+
+```xml
+<SoundTouchSdkInfo serverVersion="4" serverBuild="trunk r46330 v4 epdbuild hepdswbld04" />
+```
+
+---
+
+## Message Envelope
+
+All subsequent messages (except `selectLastWiFiSource`, see below) use this envelope:
+
+**Client → Server request:**
+```xml
+<msg>
+  <header deviceID="{device_id}" url="{endpoint}" method="{GET|POST}">
+    <request requestID="{n}">
+      <info type="new"/>                <!-- or type="update" -->
+      <!-- optional: <sourceItem source="TUNEIN"/> -->
+    </request>
+  </header>
+  <body>
+    <!-- payload, may be empty -->
+  </body>
+</msg>
+```
+
+**Server → Client response:**
+```xml
+<?xml version="1.0" encoding="UTF-8" ?>
+<msg>
+  <header deviceID="{device_id}" url="{endpoint}" method="{GET|POST}">
+    <request requestID="{n}" msgType="RESPONSE">
+      <info type="new"/>
+    </request>
+  </header>
+  <body>
+    <!-- response payload -->
+  </body>
+</msg>
+```
+
+**Server → Client push (unsolicited):**
+```xml
+<updates deviceID="{device_id}">
+  <nowPlayingUpdated>...</nowPlayingUpdated>
+</updates>
+```
+
+`requestID` is a monotonically increasing integer per connection (client-side sequence).
+`{device_id}` is the speaker's MAC address with colons removed (e.g. `08DF1F0BA325`).
+
+---
+
+## Phase 1 — Discovery: Is the Speaker Already Paired?
+
+```xml
+<!-- C→S: fetch device info -->
+<msg><header deviceID="{device_id}" url="info" method="GET">
+  <request requestID="1"><info type="new"/></request>
+</header></msg>
+
+<!-- S→C: response -->
+<info deviceID="{device_id}">
+  <name>SoundTouch 10</name>
+  <type>SoundTouch 10</type>
+  <margeAccountUUID>9569497</margeAccountUUID>   <!-- empty = unpaired -->
+  <margeURL>https://streaming.bose.com</margeURL>
+  ...
+</info>
+```
+
+- **Empty `margeAccountUUID`** → device is unpaired, proceed to Phase 2
+- **Populated `margeAccountUUID`** → already paired with that account ID
+
+---
+
+## Phase 2 — Pairing a New Speaker
+
+### 2.1 Setup State Machine
+
+The pairing flow uses a setup state machine on the device. States must be sent in order.
+
+```xml
+<!-- 1. Start setup -->
+<msg><header deviceID="{device_id}" url="setup" method="POST">
+  <request requestID="21"></request>
+</header><body><setupState state="SETUP_START"/></body></msg>
+
+<!-- 2. Enter identify mode — device flashes/beeps; 300 000 ms timeout -->
+<msg><header deviceID="{device_id}" url="setup" method="POST">
+  <request requestID="22"></request>
+</header><body><setupState state="SETUP_IDENTIFY_DEVICE_ENTER" timeout="300000"/></body></msg>
+
+<!-- Server pushes: -->
+<updates deviceID="{device_id}">
+  <soundTouchConfigurationUpdated>
+    <soundTouchConfigurationStatus status="SOUNDTOUCH_CONFIGURING"/>
+  </soundTouchConfigurationUpdated>
+</updates>
+
+<!-- 3. Set language (3 = German; adjust as needed) -->
+<msg><header deviceID="{device_id}" url="language" method="POST">
+  <request requestID="23"></request>
+</header><body><sysLanguage>3</sysLanguage></body></msg>
+
+<!-- 4. Enter setup (user has confirmed identification) -->
+<msg><header deviceID="{device_id}" url="setup" method="POST">
+  <request requestID="24"></request>
+</header><body><setupState state="SETUP_ENTER"/></body></msg>
+
+<!-- 5. Leave identify mode -->
+<msg><header deviceID="{device_id}" url="setup" method="POST">
+  <request requestID="25"></request>
+</header><body><setupState state="SETUP_IDENTIFY_DEVICE_LEAVE"/></body></msg>
+
+<!-- 6. Set device name -->
+<msg><header deviceID="{device_id}" url="name" method="POST">
+  <request requestID="26"></request>
+</header><body><name>My SoundTouch 10</name></body></msg>
+```
+
+### 2.2 Account Pairing — The Critical Step
+
+```xml
+<!-- C→S: pair device with account -->
+<msg><header deviceID="{device_id}" url="setMargeAccount" method="POST">
+  <request requestID="27"></request>
+</header><body>
+  <PairDeviceWithAccount>
+    <accountId>{accountId}</accountId>
+    <userAuthToken>Bearer {token}</userAuthToken>
+  </PairDeviceWithAccount>
+</body></msg>
+
+<!-- S→C: device info response with margeAccountUUID now set -->
+<info deviceID="{device_id}">
+  ...
+  <margeAccountUUID>{accountId}</margeAccountUUID>
+  ...
+</info>
+```
+
+The server also pushes several `sourcesUpdated` events after successful pairing.
+
+**`{accountId}`** — the numeric Bose account ID (e.g. `9569497`), obtainable from
+`GET /streaming/account/login` on soundtouch-service.
+
+**`{token}`** — a Bearer token issued by Bose authentication (or soundtouch-service).
+The full token from the captures:
+```
+Bearer NtJDRbNtY3hDhm5K8FC2JprRhRQNH3QdZjG6aR4ASwYQg4rvZMY6dPLc3Bm6zvWNciWzCpMWZ/dbITRQoVdClOdssgDO+Nlh4ZJWp2w3tZiGzB8Flho0c+ipXnT/0Yg5
+```
+(session-specific; obtain a fresh one from the service's account login flow)
+
+### 2.3 Finish Setup and Telemetry
+
+```xml
+<!-- Leave setup state machine -->
+<msg><header deviceID="{device_id}" url="setup" method="POST">
+  <request requestID="28"></request>
+</header><body><setupState state="SETUP_LEAVE"/></body></msg>
+
+<!-- Trigger device to sync customer support info to Marge cloud -->
+<msg><header deviceID="{device_id}" url="pushCustomerSupportInfoToMarge" method="GET">
+  <request requestID="29"></request>
+</header></msg>
+
+<!-- S→C: -->
+<status>/pushCustomerSupportInfoToMarge</status>
+```
+
+---
+
+## Phase 3 — Unpairing
+
+```xml
+<!-- C→S: remove device from account -->
+<msg><header deviceID="{device_id}" url="setMargeAccount" method="POST">
+  <request requestID="24">
+    <info mainNode="removeDevice" type="new"/>
+    <sourceItem source="SETTINGS" sourceAccount="{device_id}"/>
+  </request>
+</header><body><UnPairDeviceWithAccount/></body></msg>
+
+<!-- S→C: response with device info showing empty margeAccountUUID -->
+<!-- Server also pushes: <updates><infoUpdated/></updates> -->
+```
+
+---
+
+## Phase 4 — App Initialization (Bulk State Fetch)
+
+When the app connects to an already-paired device it sends these in rapid parallel sequence:
+
+```
+info          (GET)  — device metadata, check pairing
+sources       (GET)  — available input sources
+presets       (GET)  — saved presets 1–6
+swUpdateQuery (POST) — check if update is in progress
+capabilities  (GET)  — hardware capabilities, network config
+bassCapabilities (GET) — bass range and defaults
+now_playing   (GET)  — current playback state
+volume        (GET)  — current volume
+getZone       (GET)  — multi-room zone membership
+clockDisplay  (POST) — set clock timezone/format
+```
+
+Then a second wave:
+
+```
+swUpdateCheck   (POST) — check for new firmware
+systemtimeout   (GET)  — power-saving timeout
+rebroadcastlatencymode (GET) — zone latency mode
+getGroup        (GET)  — stereo-pair group
+language        (GET, sourceItem source="settings") — UI language
+bass            (GET)  — current bass level
+serviceAvailability (GET, sourceItem source="add_service" or "settings")
+webserver/pingRequest (GET) — keepalive
+pushCustomerSupportInfoToMarge (GET) — telemetry
+netStats        (GET, sourceItem source="settings") — network statistics
+introspect      (POST, sourceItem source="AIRPLAY") — AirPlay2 capabilities
+```
+
+`clockDisplay` example with timezone:
+```xml
+<clockDisplay>
+  <clockConfig timezoneInfo="Europe/Berlin" timeFormat="TIME_FORMAT_12HOUR_ID"/>
+</clockDisplay>
+```
+
+`serviceAvailability` response lists availability of all service types (PANDORA, AIRPLAY,
+AMAZON, DEEZER, SPOTIFY, TUNEIN, SIRIUSXM_EVEREST, BLUETOOTH, etc.) with `isAvailable`
+and optional `reason` attributes.
+
+---
+
+## Playback Control
+
+### Start Playback via `playbackRequest` (preferred — bypasses source checks)
+
+```xml
+<msg><header deviceID="{device_id}" url="playbackRequest" method="POST">
+  <request requestID="{n}"><info type="new"/></request>
+</header><body>
+  <playbackRequest source="TUNEIN" sourceAccount="">
+    <container type="stationurl"
+               location="/v1/playback/station/s25260"
+               isPresetable="true"
+               source="TUNEIN"
+               sourceAccount="">
+      <itemName>1LIVE</itemName>
+    </container>
+  </playbackRequest>
+</body></msg>
+
+<!-- S→C response: -->
+<playbackResponse source="TUNEIN" sourceAccount=""/>
+
+<!-- S→C pushes: nowPlayingUpdated, recentsUpdated -->
+```
+
+For a TuneIn podcast episode, use `type="tracklisturl"` and
+`location="/v1/playback/episodes/{id}?encoded_name={base64}"`.
+
+### Select Content via `select` (triggers preset/recents UI highlight)
+
+```xml
+<msg><header deviceID="{device_id}" url="select" method="POST">
+  <request requestID="{n}"><info type="new"/></request>
+</header><body>
+  <ContentItem source="TUNEIN"
+               type="stationurl"
+               location="/v1/playback/station/s25260"
+               sourceAccount="TUNEIN"
+               isPresetable="true">
+    <itemName>1LIVE</itemName>
+  </ContentItem>
+</body></msg>
+```
+
+Note: `select` with a TUNEIN item that the device can't resolve directly may return
+`error value="1005" name="UNKNOWN_SOURCE_ERROR"`. Use `playbackRequest` instead for
+reliable playback.
+
+### Special: Select Last Wi-Fi Source
+
+A plain-text (non-XML) client message:
+```
+selectLastWiFiSource
+```
+
+Server responds with plain text:
+```
+<?xml version="1.0" encoding="UTF-8" ?><status>/selectLastWiFiSource</status>
+```
+
+### Key Presses
+
+```xml
+<!-- press -->
+<msg><header deviceID="{device_id}" url="key" method="POST">
+  <request requestID="{n}"><info mainNode="keyPress" type="new"/><sourceItem source="TUNEIN"/></request>
+</header><body><key state="press" sender="Gabbo">{KEY}</key></body></msg>
+
+<!-- release (required for POWER — not for STOP/PAUSE) -->
+<msg><header deviceID="{device_id}" url="key" method="POST">
+  <request requestID="{n}"><info mainNode="keyRelease" type="new"/><sourceItem source="TUNEIN"/></request>
+</header><body><key state="release" sender="Gabbo">{KEY}</key></body></msg>
+```
+
+Key names observed: `POWER`, `STOP`, `PAUSE`, `ADD_FAVORITE`
+
+`sender="Gabbo"` is the app identifier string used by all Bose mobile apps.
+
+### Volume
+
+```xml
+<!-- Set volume (0–100) -->
+<msg><header deviceID="{device_id}" url="volume" method="POST">
+  <request requestID="{n}"><info mainNode="volume" type="new"/><sourceItem source="TUNEIN"/></request>
+</header><body><volume>30</volume></body></msg>
+
+<!-- S→C push: -->
+<updates deviceID="{device_id}">
+  <volumeUpdated>
+    <volume><targetvolume>30</targetvolume><actualvolume>30</actualvolume><muteenabled>false</muteenabled></volume>
+  </volumeUpdated>
+</updates>
+```
+
+### Bass
+
+```xml
+<!-- Get -->
+<msg><header deviceID="{device_id}" url="bass" method="GET">
+  <request requestID="{n}"><info type="new"/></request>
+</header></msg>
+
+<!-- Set (range: bassMin to bassMax from bassCapabilities, typically -9 to 0) -->
+<msg><header deviceID="{device_id}" url="bass" method="POST">
+  <request requestID="{n}"><info mainNode="bassSet" type="new"/><sourceItem source="SETTINGS"/></request>
+</header><body><bass>-2</bass></body></msg>
+
+<!-- S→C push: <updates><bassUpdated/></updates> -->
+```
+
+---
+
+## Browse & Navigate
+
+```xml
+<!-- Open recents menu -->
+<msg><header deviceID="{device_id}" url="navigate" method="POST">
+  <request requestID="{n}"><info mainNode="navigateMenu" type="new"/><sourceItem source="RECENTS"/></request>
+</header><body><navigate menu="recents"/></body></msg>
+
+<!-- S→C response: -->
+<navigateResponse menu="recents">
+  <totalItems>4</totalItems>
+  <items>
+    <item type="stationurl" source="TUNEIN" location="/v1/playback/station/s25260"
+          sourceAccount="TUNEIN" isPresetable="true" id="0">
+      <itemName>1LIVE</itemName>
+    </item>
+    ...
+  </items>
+</navigateResponse>
+```
+
+Use `type="update"` on `<info>` for subsequent refresh calls on the same menu.
+
+---
+
+## Settings
+
+### System Timeout (Power-Saving)
+
+```xml
+<!-- Read -->
+<msg><header deviceID="{device_id}" url="systemtimeout" method="GET">
+  <request requestID="{n}"><info type="new"/></request>
+</header></msg>
+
+<!-- Write: disable auto power-off -->
+<msg><header deviceID="{device_id}" url="systemtimeout" method="POST">
+  <request requestID="{n}"><info mainNode="systemtimeout" type="new"/><sourceItem source="SETTINGS"/></request>
+</header><body><systemtimeout><powersaving_enabled>false</powersaving_enabled></systemtimeout></body></msg>
+```
+
+### Clock Display
+
+```xml
+<msg><header deviceID="{device_id}" url="clockDisplay" method="POST">
+  <request requestID="{n}"><info mainNode="clockDisplayBypass" type="new"/></request>
+</header><body>
+  <clockDisplay>
+    <clockConfig timezoneInfo="Europe/Berlin" timeFormat="TIME_FORMAT_12HOUR_ID"/>
+  </clockDisplay>
+</body></msg>
+```
+
+---
+
+## Keepalive
+
+The app sends a ping roughly every 30 seconds:
+
+```xml
+<!-- C→S -->
+<msg><header deviceID="{device_id}" url="webserver/pingRequest" method="GET">
+  <request requestID="{n}"><info type="new"/></request>
+</header></msg>
+
+<!-- S→C -->
+<pingRequest pong="true"/>
+```
+
+---
+
+## Server Push Events (Unsolicited)
+
+The server wraps push events in `<updates deviceID="{device_id}">`:
+
+| Event element                    | Trigger                                                                                             |
+|----------------------------------|-----------------------------------------------------------------------------------------------------|
+| `nowPlayingUpdated`              | Source/track changed, playback state changed                                                        |
+| `nowSelectionUpdated`            | Preset slot highlighted (UI selection changed)                                                      |
+| `recentsUpdated`                 | Recents list changed                                                                                |
+| `presetsUpdated`                 | Preset saved or modified                                                                            |
+| `volumeUpdated`                  | Volume changed (any source)                                                                         |
+| `bassUpdated`                    | Bass level changed                                                                                  |
+| `connectionStateUpdated`         | Wi-Fi signal strength changed (`EXCELLENT_SIGNAL`, `GOOD_SIGNAL`, `MARGINAL_SIGNAL`, `POOR_SIGNAL`) |
+| `soundTouchConfigurationUpdated` | Setup state changed (e.g. `SOUNDTOUCH_CONFIGURING`)                                                 |
+| `infoUpdated`                    | Device info changed (e.g. after un-pairing)                                                         |
+| `sourcesUpdated`                 | Available sources list changed                                                                      |
+
+Separate push (not inside `<updates>`):
+```xml
+<userActivityUpdate deviceID="{device_id}"/>
+```
+Sent after any physical or app-initiated user action.
+
+---
+
+## Notification (Client → Device Push)
+
+Used by the app to notify the device of data that has changed on the service side
+(e.g. after syncing presets from cloud). Header uses `propagate="false"`:
+
+```xml
+<msg>
+  <header deviceID="{device_id}" url="notification" method="POST" propagate="false">
+    <request requestID="{n}"><info mainNode="presetsUpdated" type="new"/></request>
+  </header>
+  <body>
+    <updates deviceID="{device_id}"><presetsUpdated/></updates>
+  </body>
+</msg>
+
+<!-- S→C response: -->
+<status>/notification</status>
+```
+
+---
+
+## Complete Pairing Sequence (Minimal)
+
+To pair a freshly factory-reset speaker to a Bose account (soundtouch-service must be
+running and authenticated):
+
+```
+1.  Connect WebSocket to ws://{speakerIP}:8090/
+2.  Receive: <SoundTouchSdkInfo .../>
+3.  GET info  → confirm margeAccountUUID is empty
+4.  POST setup SETUP_START
+5.  POST setup SETUP_IDENTIFY_DEVICE_ENTER (timeout=300000)
+    (user physically presses button on speaker to confirm identity)
+6.  POST language <sysLanguage>3</sysLanguage>
+7.  POST setup SETUP_ENTER
+8.  POST setup SETUP_IDENTIFY_DEVICE_LEAVE
+9.  POST name  <name>{desired name}</name>
+10. POST setMargeAccount <PairDeviceWithAccount>
+      <accountId>{accountId}</accountId>
+      <userAuthToken>Bearer {token}</userAuthToken>
+    </PairDeviceWithAccount>
+    → device responds with info, margeAccountUUID is now set
+11. POST setup SETUP_LEAVE
+12. GET  pushCustomerSupportInfoToMarge   (telemetry, safe to skip)
+```
+
+---
+
+## Source References
+
+- `bose-pairing-20260502-155542` — Session 1: initial pairing of SoundTouch 10 to account 9569497
+- `bose-pairing-20260502-165549` — Session 2: re-pairing and full operation (TuneIn, Spotify, presets)
+- Raw WebSocket files: `scripts/android/mitm/{session}/mirror/{n}-websocket/*.txt`
+- Companion HTTP upgrade files: `scripts/android/mitm/{session}/mirror/{n}-*.http`

examples/navigation-station-demo/go.mod

@@ -1,8 +1,8 @@
 module navigation-station-demo
 
-go 1.26.2
+go 1.26.3
 
-require github.com/gesellix/bose-soundtouch v0.57.0
+require github.com/gesellix/bose-soundtouch v0.71.2
 
 require github.com/gorilla/websocket v1.5.3 // indirect
 

examples/preset-management/go.mod

@@ -1,8 +1,8 @@
 module preset-management-example
 
-go 1.26.2
+go 1.26.3
 
-require github.com/gesellix/bose-soundtouch v0.57.0
+require github.com/gesellix/bose-soundtouch v0.71.2
 
 require github.com/gorilla/websocket v1.5.3 // indirect
 

go.mod

@@ -1,8 +1,9 @@
 module github.com/gesellix/bose-soundtouch
 
-go 1.26.2
+go 1.26.3
 
 require (
+	github.com/chromedp/chromedp v0.15.1
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/google/gopacket v1.1.19
 	github.com/gorilla/websocket v1.5.3
@@ -13,17 +14,24 @@ require (
 	github.com/srwiley/oksvg v0.0.0-20221011165216-be6e8873101c
 	github.com/srwiley/rasterx v0.0.0-20220730225603-2ab79fcdd4ef
 	github.com/urfave/cli/v2 v2.27.7
-	golang.org/x/crypto v0.50.0
+	golang.org/x/crypto v0.51.0
+	golang.org/x/net v0.54.0
+	golang.org/x/term v0.43.0
 )
 
 require (
+	github.com/chromedp/cdproto v0.0.0-20260427013145-5737772c319b // indirect
+	github.com/chromedp/sysutil v1.1.0 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
+	github.com/go-json-experiment/json v0.0.0-20260505212615-e40f80bf6836 // indirect
+	github.com/gobwas/httphead v0.1.0 // indirect
+	github.com/gobwas/pool v0.2.1 // indirect
+	github.com/gobwas/ws v1.4.0 // indirect
 	github.com/xrash/smetrics v0.0.0-20250705151800-55b8f293f342 // indirect
-	golang.org/x/image v0.39.0 // indirect
-	golang.org/x/mod v0.35.0 // indirect
-	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/image v0.40.0 // indirect
+	golang.org/x/mod v0.36.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.43.0 // indirect
-	golang.org/x/text v0.36.0 // indirect
-	golang.org/x/tools v0.44.0 // indirect
+	golang.org/x/sys v0.44.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/tools v0.45.0 // indirect
 )

go.sum

@@ -1,3 +1,9 @@
+github.com/chromedp/cdproto v0.0.0-20260427013145-5737772c319b h1:fpvdcCAe2z3H8OvVY00iKOp3Wapbs/Gy375Fn6l/XM4=
+github.com/chromedp/cdproto v0.0.0-20260427013145-5737772c319b/go.mod h1:cbyjALe67vDvlvdiG9369P8w5U2w6IshwtyD2f2Tvag=
+github.com/chromedp/chromedp v0.15.1 h1:EJWiPm7BNqDqjYy6U0lTSL5wNH+iNt9GjC3a4gfjNyQ=
+github.com/chromedp/chromedp v0.15.1/go.mod h1:CdTHtUqD/dqaFw/cvFWtTydoEQS44wLBuwbMR9EkOY4=
+github.com/chromedp/sysutil v1.1.0 h1:PUFNv5EcprjqXZD9nJb9b/c9ibAbxiYo4exNWZyipwM=
+github.com/chromedp/sysutil v1.1.0/go.mod h1:WiThHUdltqCNKGc4gaU50XgYjwjYIhKWoHGPTUfWTJ8=
 github.com/cpuguy83/go-md2man/v2 v2.0.7 h1:zbFlGlXEAKlwXpmvle3d8Oe3YnkKIK4xSRTd3sHPnBo=
 github.com/cpuguy83/go-md2man/v2 v2.0.7/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -5,6 +11,14 @@ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
 github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
+github.com/go-json-experiment/json v0.0.0-20260505212615-e40f80bf6836 h1:5KGUhXZFTN1PrCY4zUZLe1J8n7uBNmPDbCLCn78EbPQ=
+github.com/go-json-experiment/json v0.0.0-20260505212615-e40f80bf6836/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
+github.com/gobwas/httphead v0.1.0 h1:exrUm0f4YX0L7EBwZHuCF4GDp8aJfVeBrlLQrs6NqWU=
+github.com/gobwas/httphead v0.1.0/go.mod h1:O/RXo79gxV8G+RqlR/otEwx4Q36zl9rqC5u12GKvMCM=
+github.com/gobwas/pool v0.2.1 h1:xfeeEhW7pwmX8nuLVlqbzVc7udMDrwetjEv+TZIz1og=
+github.com/gobwas/pool v0.2.1/go.mod h1:q8bcK0KcYlCgd9e7WYLm9LpyS+YeLd8JVDW6WezmKEw=
+github.com/gobwas/ws v1.4.0 h1:CTaoG1tojrh4ucGPcoJFiAQUAsEWekEWvLy7GsVNqGs=
+github.com/gobwas/ws v1.4.0/go.mod h1:G3gNqMNtPppf5XUz7O4shetPpcZ1VJ7zt18dlUeakrc=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gopacket v1.1.19 h1:ves8RnFZPGiFnTS0uPQStjwru6uO6h+nlr9j6fL7kF8=
@@ -16,9 +30,13 @@ github.com/hashicorp/mdns v1.0.6/go.mod h1:X4+yWh+upFECLOki1doUPaKpgNQII9gy4bUdC
 github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo=
 github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80 h1:6Yzfa6GP0rIo/kULo2bwGEkFvCePZ3qHDDTC3/J9Swo=
+github.com/ledongthuc/pdf v0.0.0-20220302134840-0c2507a12d80/go.mod h1:imJHygn/1yfhB7XSJJKlFZKl/J+dCPAknuiaGOshXAs=
 github.com/miekg/dns v1.1.55/go.mod h1:uInx36IzPl7FYnDcMeVWxj9byh7DutNykX4G9Sj60FY=
 github.com/miekg/dns v1.1.72 h1:vhmr+TF2A3tuoGNkLDFK9zi36F2LS+hKTRW0Uf8kbzI=
 github.com/miekg/dns v1.1.72/go.mod h1:+EuEPhdHOsfk6Wk5TT2CzssZdqkmFhf8r+aVyDEToIs=
+github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde h1:x0TT0RDC7UhAVbbWWBzr41ElhJx5tXPWkIHA2HWPRuw=
+github.com/orisano/pixelmatch v0.0.0-20220722002657-fb0b55479cde/go.mod h1:nZgzbfBr3hhjoZnS66nKrHmduYNpc34ny7RK4z5/HM0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
@@ -44,10 +62,10 @@ golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliY
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
-golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
-golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
-golang.org/x/image v0.39.0 h1:skVYidAEVKgn8lZ602XO75asgXBgLj9G/FE3RbuPFww=
-golang.org/x/image v0.39.0/go.mod h1:sIbmppfU+xFLPIG0FoVUTvyBMmgng1/XAMhQ2ft0hpA=
+golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
+golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
+golang.org/x/image v0.40.0 h1:Tw4GyDXMo+daZN1znreBRC3VayR1aLFUyUEOLUdW1a8=
+golang.org/x/image v0.40.0/go.mod h1:uIc348UZMSvS5Z65CVZ7iDPaNobNFEPeJ4kbqTOszmA=
 golang.org/x/lint v0.0.0-20200302205851-738671d3881b/go.mod h1:3xt1FjdF8hUf6vQPIChWIBhFzV8gjjsPE/fR3IyQdNY=
 golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
@@ -56,8 +74,8 @@ golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
-golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
+golang.org/x/mod v0.36.0 h1:JJjpVx6myfUsUdAzZuOSTTmRE0PfZeNWzzvKrP7amb4=
+golang.org/x/mod v0.36.0/go.mod h1:moc6ELqsWcOw5Ef3xVprK5ul/MvtVvkIXLziUOICjUQ=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
@@ -69,8 +87,8 @@ golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
 golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
 golang.org/x/net v0.34.0/go.mod h1:di0qlW3YNM5oh6GqDGQr92MyTozJPmybPK4Ev/Gm31k=
-golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
-golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/net v0.54.0 h1:2zJIZAxAHV/OHCDTCOHAYehQzLfSXuf/5SoL/Dv6w/w=
+golang.org/x/net v0.54.0/go.mod h1:Sj4oj8jK6XmHpBZU/zWHw3BV3abl4Kvi+Ut7cQcY+cQ=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -88,13 +106,14 @@ golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.2.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
-golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
@@ -105,8 +124,8 @@ golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
 golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
 golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek=
-golang.org/x/term v0.42.0 h1:UiKe+zDFmJobeJ5ggPwOshJIVt6/Ft0rcfrXZDLWAWY=
-golang.org/x/term v0.42.0/go.mod h1:Dq/D+snpsbazcBG5+F9Q1n2rXV8Ma+71xEjTRufARgY=
+golang.org/x/term v0.43.0 h1:S4RLU2sB31O/NCl+zFN9Aru9A/Cq2aqKpTZJ6B+DwT4=
+golang.org/x/term v0.43.0/go.mod h1:lrhlHNdQJHO+1qVYiHfFKVuVioJIheAc3fBSMFYEIsk=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
@@ -117,8 +136,8 @@ golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
-golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
-golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20200130002326-2f3ba24bd6e7/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
@@ -127,8 +146,8 @@ golang.org/x/tools v0.3.0/go.mod h1:/rWhSS2+zyEVwoJf8YAX6L2f0ntZ7Kn/mGgAWcipA5k=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
-golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
-golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
+golang.org/x/tools v0.45.0 h1:18qN3FAooORvApf5XjCXgsuayZOEtXf6JK18I3+ONa8=
+golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

pkg/client/bass_integration_test.go

@@ -6,6 +6,7 @@ import (
 	"time"
 
 	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/speaker"
 )
 
 // Integration tests for bass control functionality
@@ -426,7 +427,7 @@ func BenchmarkClient_Bass_Integration(b *testing.B) {
 // This is a simple version for test use
 func parseBassHostPort(hostPort string) (string, int) {
 	if !containsSubstring(hostPort, ":") {
-		return hostPort, defaultSoundTouchPort
+		return hostPort, speaker.HTTPPort
 	}
 
 	// Simple parsing - in real use, we'd use net.SplitHostPort
@@ -448,7 +449,7 @@ func parseBassHostPort(hostPort string) (string, int) {
 
 	if len(parts) == 2 {
 		// Try to parse port
-		port := defaultSoundTouchPort
+		port := speaker.HTTPPort
 		portStr := parts[1]
 		portInt := 0
 
@@ -468,5 +469,5 @@ func parseBassHostPort(hostPort string) (string, int) {
 		return parts[0], port
 	}
 
-	return hostPort, defaultSoundTouchPort
+	return hostPort, speaker.HTTPPort
 }

pkg/client/client.go

@@ -153,11 +153,9 @@ import (
 	"time"
 
 	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/speaker"
 )
 
-// defaultSoundTouchPort is the standard port for SoundTouch devices
-const defaultSoundTouchPort = 8090
-
 // Client represents a SoundTouch API client
 type Client struct {
 	baseURL    string
@@ -204,7 +202,7 @@ func NewClient(config *Config) *Client {
 		// Fallback for invalid URLs
 		port := config.Port
 		if port == 0 {
-			port = 8090
+			port = speaker.HTTPPort
 		}
 
 		return &Client{
@@ -223,7 +221,7 @@ func NewClient(config *Config) *Client {
 		// No port in the host string, use the one from config or default
 		port := config.Port
 		if port == 0 {
-			port = 8090
+			port = speaker.HTTPPort
 		}
 
 		u.Host = net.JoinHostPort(u.Host, fmt.Sprintf("%d", port))
@@ -231,7 +229,7 @@ func NewClient(config *Config) *Client {
 		// Empty port, use config or default
 		port := config.Port
 		if port == 0 {
-			port = 8090
+			port = speaker.HTTPPort
 		}
 
 		u.Host = net.JoinHostPort(u.Hostname(), fmt.Sprintf("%d", port))
@@ -783,7 +781,11 @@ func (c *Client) SelectSource(source, sourceAccount string) error {
 	case "BLUETOOTH":
 		contentItem.ItemName = "Bluetooth"
 	case "AUX":
-		contentItem.ItemName = "AUX Input"
+		contentItem.ItemName = "AUX IN"
+		// The speaker rejects AUX with empty sourceAccount as INVALID_SOURCE.
+		if contentItem.SourceAccount == "" {
+			contentItem.SourceAccount = "AUX"
+		}
 	case "TUNEIN":
 		contentItem.ItemName = "TuneIn"
 	case "PANDORA":
@@ -818,7 +820,7 @@ func (c *Client) SelectBluetooth() error {
 	return c.SelectSource("BLUETOOTH", "")
 }
 
-// SelectAux is a convenience method to select AUX input
+// SelectAux is a convenience method to select AUX input.
 func (c *Client) SelectAux() error {
 	return c.SelectSource("AUX", "")
 }
@@ -1376,6 +1378,58 @@ func (c *Client) GetZoneMembers() ([]string, error) {
 	return zone.GetAllDeviceIDs(), nil
 }
 
+// GetGroup retrieves the current stereo-pair configuration from the device.
+// An empty <group/> response is reported as a zero-value Group; callers can
+// distinguish with (*Group).IsEmpty().
+//
+// ST-10 is the only product that supports stereo pairs; on other devices
+// the call is harmless but will always return an empty group. The endpoint
+// is named /getGroup on the device (mirroring /getZone), even though some
+// third-party wikis document it as plain /group.
+func (c *Client) GetGroup() (*models.Group, error) {
+	var g models.Group
+
+	err := c.get("/getGroup", &g)
+
+	return &g, err
+}
+
+// AddGroup creates a new stereo pair on the device addressed by this client,
+// which becomes the master. The supplied group must contain both LEFT and
+// RIGHT roles; the device assigns the group ID and echoes the full state
+// in the response.
+func (c *Client) AddGroup(group *models.Group) (*models.Group, error) {
+	var result models.Group
+	if err := c.postWithResponse("/addGroup", group, &result); err != nil {
+		return nil, err
+	}
+
+	return &result, nil
+}
+
+// UpdateGroup renames or otherwise updates an existing stereo pair. The
+// device requires the full group structure on every update, not just the
+// changed fields.
+func (c *Client) UpdateGroup(group *models.Group) (*models.Group, error) {
+	var result models.Group
+	if err := c.postWithResponse("/updateGroup", group, &result); err != nil {
+		return nil, err
+	}
+
+	return &result, nil
+}
+
+// RemoveGroup tears down the device's stereo pair. The device returns an
+// empty <group/> on success — surfaced here as a non-error nil.
+//
+// Note: the wiki specifies GET (not DELETE) for this endpoint, so we honour
+// that despite the state-mutating semantics.
+func (c *Client) RemoveGroup() error {
+	var g models.Group
+
+	return c.get("/removeGroup", &g)
+}
+
 // SetName sets the device name
 func (c *Client) SetName(name string) error {
 	nameRequest := models.Name{

pkg/client/group_test.go

@@ -0,0 +1,234 @@
+package client
+
+import (
+	"encoding/xml"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+)
+
+func TestClient_GetGroup_Configured(t *testing.T) {
+	responseXML := `<?xml version="1.0" encoding="UTF-8" ?>
+<group id="1234567">
+  <name>Living Room Pair</name>
+  <masterDeviceId>9070658C9D4A</masterDeviceId>
+  <roles>
+    <groupRole>
+      <deviceId>9070658C9D4A</deviceId>
+      <role>LEFT</role>
+      <ipAddress>192.168.1.131</ipAddress>
+    </groupRole>
+    <groupRole>
+      <deviceId>F45EAB3115DA</deviceId>
+      <role>RIGHT</role>
+      <ipAddress>192.168.1.134</ipAddress>
+    </groupRole>
+  </roles>
+  <senderIPAddress>192.168.1.131</senderIPAddress>
+  <status>GROUP_OK</status>
+</group>`
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/getGroup" {
+			t.Errorf("path = %q, want /getGroup", r.URL.Path)
+		}
+
+		if r.Method != http.MethodGet {
+			t.Errorf("method = %s, want GET", r.Method)
+		}
+
+		w.Header().Set("Content-Type", "application/xml")
+		_, _ = w.Write([]byte(responseXML))
+	}))
+	defer server.Close()
+
+	g, err := createTestClient(server.URL).GetGroup()
+	if err != nil {
+		t.Fatalf("GetGroup: %v", err)
+	}
+
+	if g.ID != "1234567" {
+		t.Errorf("ID = %q, want 1234567", g.ID)
+	}
+
+	if g.Name != "Living Room Pair" {
+		t.Errorf("Name = %q, want Living Room Pair", g.Name)
+	}
+
+	if g.MasterDeviceID != "9070658C9D4A" {
+		t.Errorf("MasterDeviceID = %q", g.MasterDeviceID)
+	}
+
+	if g.Status != "GROUP_OK" {
+		t.Errorf("Status = %q, want GROUP_OK", g.Status)
+	}
+
+	if len(g.Roles.Roles) != 2 {
+		t.Fatalf("roles = %d, want 2", len(g.Roles.Roles))
+	}
+
+	if g.Roles.Roles[0].Role != "LEFT" || g.Roles.Roles[1].Role != "RIGHT" {
+		t.Errorf("role order LEFT/RIGHT not preserved: %+v", g.Roles.Roles)
+	}
+
+	if g.IsEmpty() {
+		t.Errorf("IsEmpty = true for populated group")
+	}
+}
+
+func TestClient_GetGroup_Empty(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/xml")
+		_, _ = w.Write([]byte(`<group />`))
+	}))
+	defer server.Close()
+
+	g, err := createTestClient(server.URL).GetGroup()
+	if err != nil {
+		t.Fatalf("GetGroup: %v", err)
+	}
+
+	if !g.IsEmpty() {
+		t.Errorf("IsEmpty = false for <group/>, got %+v", g)
+	}
+}
+
+func TestClient_AddGroup(t *testing.T) {
+	var capturedBody string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/addGroup" {
+			t.Errorf("path = %q, want /addGroup", r.URL.Path)
+		}
+
+		if r.Method != http.MethodPost {
+			t.Errorf("method = %s, want POST", r.Method)
+		}
+
+		body, _ := io.ReadAll(r.Body)
+		capturedBody = string(body)
+
+		// Echo the request back with an assigned ID and GROUP_OK status —
+		// matches real device behaviour.
+		var got models.Group
+		if err := xml.Unmarshal(body, &got); err != nil {
+			t.Fatalf("decode request body: %v", err)
+		}
+
+		got.ID = "9999999"
+		got.Status = "GROUP_OK"
+		got.SenderIPAddress = "192.168.1.131"
+
+		w.Header().Set("Content-Type", "application/xml")
+
+		enc, _ := xml.Marshal(&got)
+		_, _ = w.Write(enc)
+	}))
+	defer server.Close()
+
+	req := &models.Group{
+		Name:           "Living Room",
+		MasterDeviceID: "9070658C9D4A",
+		Roles: models.GroupRoles{
+			Roles: []models.GroupRole{
+				{DeviceID: "9070658C9D4A", Role: "LEFT", IPAddress: "192.168.1.131"},
+				{DeviceID: "F45EAB3115DA", Role: "RIGHT", IPAddress: "192.168.1.134"},
+			},
+		},
+	}
+
+	resp, err := createTestClient(server.URL).AddGroup(req)
+	if err != nil {
+		t.Fatalf("AddGroup: %v", err)
+	}
+
+	if resp.ID != "9999999" {
+		t.Errorf("response ID = %q, want 9999999", resp.ID)
+	}
+
+	if resp.Status != "GROUP_OK" {
+		t.Errorf("response Status = %q, want GROUP_OK", resp.Status)
+	}
+
+	// Wire-shape sanity: the request body must carry both roles and the
+	// master ID (the device validates these on the wire).
+	for _, want := range []string{"<role>LEFT</role>", "<role>RIGHT</role>", "9070658C9D4A"} {
+		if !strings.Contains(capturedBody, want) {
+			t.Errorf("request body missing %q\nbody:\n%s", want, capturedBody)
+		}
+	}
+}
+
+func TestClient_UpdateGroup_RenameRoundtrip(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/updateGroup" {
+			t.Errorf("path = %q, want /updateGroup", r.URL.Path)
+		}
+
+		body, _ := io.ReadAll(r.Body)
+
+		var got models.Group
+		if err := xml.Unmarshal(body, &got); err != nil {
+			t.Fatalf("decode: %v", err)
+		}
+
+		got.Status = "GROUP_OK"
+
+		w.Header().Set("Content-Type", "application/xml")
+
+		enc, _ := xml.Marshal(&got)
+		_, _ = w.Write(enc)
+	}))
+	defer server.Close()
+
+	req := &models.Group{
+		ID:             "1234567",
+		Name:           "Kitchen Pair",
+		MasterDeviceID: "AAAA",
+		Roles: models.GroupRoles{
+			Roles: []models.GroupRole{
+				{DeviceID: "AAAA", Role: "LEFT"},
+				{DeviceID: "BBBB", Role: "RIGHT"},
+			},
+		},
+	}
+
+	resp, err := createTestClient(server.URL).UpdateGroup(req)
+	if err != nil {
+		t.Fatalf("UpdateGroup: %v", err)
+	}
+
+	if resp.Name != "Kitchen Pair" {
+		t.Errorf("Name = %q, want Kitchen Pair", resp.Name)
+	}
+
+	if resp.ID != "1234567" {
+		t.Errorf("ID = %q, want 1234567", resp.ID)
+	}
+}
+
+func TestClient_RemoveGroup(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/removeGroup" {
+			t.Errorf("path = %q, want /removeGroup", r.URL.Path)
+		}
+
+		// The wiki specifies GET (not DELETE) for /removeGroup. We honour
+		// that, surprising as it is for a state-mutating endpoint.
+		if r.Method != http.MethodGet {
+			t.Errorf("method = %s, want GET", r.Method)
+		}
+
+		w.Header().Set("Content-Type", "application/xml")
+		_, _ = w.Write([]byte(`<group />`))
+	}))
+	defer server.Close()
+
+	if err := createTestClient(server.URL).RemoveGroup(); err != nil {
+		t.Fatalf("RemoveGroup: %v", err)
+	}
+}

pkg/client/source_selection_integration_test.go

@@ -4,6 +4,8 @@ import (
 	"os"
 	"testing"
 	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/speaker"
 )
 
 // Integration tests for source selection functionality
@@ -386,7 +388,7 @@ func BenchmarkClient_SelectSource_Integration(b *testing.B) {
 // This is a simple version for test use
 func parseHostPort(hostPort string) (string, int) {
 	if !containsSubstring(hostPort, ":") {
-		return hostPort, defaultSoundTouchPort
+		return hostPort, speaker.HTTPPort
 	}
 
 	// Simple parsing - in real use, we'd use net.SplitHostPort
@@ -408,7 +410,7 @@ func parseHostPort(hostPort string) (string, int) {
 
 	if len(parts) == 2 {
 		// Try to parse port
-		port := defaultSoundTouchPort
+		port := speaker.HTTPPort
 		portStr := parts[1]
 		portInt := 0
 
@@ -428,5 +430,5 @@ func parseHostPort(hostPort string) (string, int) {
 		return parts[0], port
 	}
 
-	return hostPort, defaultSoundTouchPort
+	return hostPort, speaker.HTTPPort
 }

pkg/client/source_selection_test.go

@@ -38,7 +38,7 @@ func TestClient_SelectSource(t *testing.T) {
 		{
 			name:          "Valid AUX source",
 			source:        "AUX",
-			sourceAccount: "",
+			sourceAccount: "AUX",
 			wantError:     false,
 		},
 		{
@@ -305,7 +305,7 @@ func TestClient_ConvenienceSourceMethods(t *testing.T) {
 			method:          "aux",
 			sourceAccount:   "",
 			expectedSource:  "AUX",
-			expectedAccount: "",
+			expectedAccount: "AUX",
 		},
 		{
 			name:            "SelectTuneIn",
@@ -530,7 +530,7 @@ func getExpectedItemName(source string) string {
 	case "BLUETOOTH":
 		return "Bluetooth"
 	case "AUX":
-		return "AUX Input"
+		return "AUX IN"
 	case "TUNEIN":
 		return "TuneIn"
 	case "PANDORA":

pkg/client/system_test.go

@@ -95,9 +95,7 @@ func TestClient_SetClockTime(t *testing.T) {
 		{
 			name: "Successful clock time set",
 			request: &models.ClockTimeRequest{
-				UTC:   1609459200,
-				Value: "2021-01-01 00:00:00",
-				Zone:  "UTC",
+				UTCTime: 1609459200,
 			},
 			statusCode:  http.StatusOK,
 			expectError: false,
@@ -112,8 +110,7 @@ func TestClient_SetClockTime(t *testing.T) {
 		{
 			name: "Server error",
 			request: &models.ClockTimeRequest{
-				UTC:   1609459200,
-				Value: "2021-01-01 00:00:00",
+				UTCTime: 1609459200,
 			},
 			statusCode:  http.StatusInternalServerError,
 			expectError: true,

pkg/client/websocket.go

@@ -140,6 +140,17 @@ func (ws *WebSocketClient) OnZoneUpdated(handler models.TypedEventHandler[*model
 	ws.handlers.OnZoneUpdated = handler
 }
 
+// OnGroupUpdated sets a handler for ST-10 stereo-pair update events.
+// The device fans these out to both LEFT and RIGHT speakers whenever the
+// pair is created, renamed, or removed, so callers will see one event per
+// affected device.
+func (ws *WebSocketClient) OnGroupUpdated(handler models.TypedEventHandler[*models.GroupUpdatedEvent]) {
+	ws.mu.Lock()
+	defer ws.mu.Unlock()
+
+	ws.handlers.OnGroupUpdated = handler
+}
+
 // OnBassUpdated sets a handler for bass update events
 func (ws *WebSocketClient) OnBassUpdated(handler models.TypedEventHandler[*models.BassUpdatedEvent]) {
 	ws.mu.Lock()
@@ -156,6 +167,18 @@ func (ws *WebSocketClient) OnUnknownEvent(handler models.EventHandler) {
 	ws.handlers.OnUnknownEvent = handler
 }
 
+// OnRawMessage sets a handler that fires for every incoming frame with
+// the raw bytes and the result of attempting to XML-parse them. The
+// typed handlers (OnNowPlaying, OnGroupUpdated, ...) still run
+// afterwards on successful parses, so OnRawMessage is purely additive —
+// intended for debug/observability tooling.
+func (ws *WebSocketClient) OnRawMessage(handler models.RawMessageHandler) {
+	ws.mu.Lock()
+	defer ws.mu.Unlock()
+
+	ws.handlers.OnRawMessage = handler
+}
+
 // OnSpecialMessage sets a handler for special (non-updates) messages
 func (ws *WebSocketClient) OnSpecialMessage(handler models.SpecialMessageHandler) {
 	ws.mu.Lock()
@@ -379,26 +402,45 @@ func (ws *WebSocketClient) attemptReconnect(config *WebSocketConfig) {
 
 // handleMessage processes incoming WebSocket messages
 func (ws *WebSocketClient) handleMessage(data []byte) {
-	// Check if this is a SoundTouchSdkInfo or other non-updates message
+	// Special (non-updates) messages take their own decode path and
+	// surface raw payloads to the OnRawMessage hook from there, so
+	// observers see exactly one notification per frame.
 	if !ws.isUpdatesMessage(data) {
 		ws.handleSpecialMessage(data)
 		return
 	}
 
-	// Parse the WebSocket event
-	event, err := models.ParseWebSocketEvent(data)
-	if err != nil {
-		ws.logger.Printf("Failed to parse WebSocket message: %v", err)
+	event, parseErr := models.ParseWebSocketEvent(data)
+
+	ws.fireRawMessage(data, parseErr)
+
+	if parseErr != nil {
+		ws.logger.Printf("Failed to parse WebSocket message: %v", parseErr)
 		return
 	}
 
-	// Process each event type in the message
 	ws.handleEvent(event)
 }
 
+// fireRawMessage invokes the OnRawMessage hook if one is registered.
+// Kept separate so the read path doesn't have to repeat the locking
+// dance for every frame.
+func (ws *WebSocketClient) fireRawMessage(data []byte, parseErr error) {
+	ws.mu.RLock()
+	handler := ws.handlers.OnRawMessage
+	ws.mu.RUnlock()
+
+	if handler != nil {
+		handler(data, parseErr)
+	}
+}
+
 // handleSpecialMessage processes special (non-updates) WebSocket messages
 func (ws *WebSocketClient) handleSpecialMessage(data []byte) {
 	specialMessage, err := models.ParseSpecialMessage(data)
+
+	ws.fireRawMessage(data, err)
+
 	if err != nil {
 		ws.logger.Printf("Unknown special message type: %v", err)
 		ws.logger.Printf("Raw message: %s", string(data))
@@ -468,6 +510,13 @@ func (ws *WebSocketClient) dispatchTypedEventContinued(handlers *models.WebSocke
 
 		return true
 
+	case models.EventTypeGroupUpdated:
+		if handlers.OnGroupUpdated != nil && event.GroupUpdated != nil {
+			handlers.OnGroupUpdated(event.GroupUpdated)
+		}
+
+		return true
+
 	case models.EventTypeBassUpdated:
 		if handlers.OnBassUpdated != nil && event.BassUpdated != nil {
 			handlers.OnBassUpdated(event.BassUpdated)

pkg/config/config.go

@@ -19,6 +19,10 @@ type Config struct {
 	DiscoveryTimeout time.Duration `env:"DISCOVERY_TIMEOUT" default:"5s"`
 	UPnPEnabled      bool          `env:"UPNP_ENABLED" default:"true"`
 	MDNSEnabled      bool          `env:"MDNS_ENABLED" default:"true"`
+	// DiscoveryInterface restricts mDNS and UPnP/SSDP discovery to a single
+	// network interface (e.g. "eth0"). Empty means "auto-pick the first
+	// suitable interface", which is the historical behaviour.
+	DiscoveryInterface string `env:"DISCOVERY_INTERFACE" default:""`
 
 	// Preferred devices from .env file
 	PreferredDevices []DeviceConfig `env:"PREFERRED_DEVICES"`
@@ -81,6 +85,10 @@ func LoadFromEnv() (*Config, error) {
 		config.MDNSEnabled = mdns == "true" || mdns == "1"
 	}
 
+	if iface := os.Getenv("DISCOVERY_INTERFACE"); iface != "" {
+		config.DiscoveryInterface = iface
+	}
+
 	if timeout := os.Getenv("HTTP_TIMEOUT"); timeout != "" {
 		if d, err := time.ParseDuration(timeout); err == nil {
 			config.HTTPTimeout = d

pkg/discovery/dns.go

@@ -171,6 +171,7 @@ func (d *DNSDiscovery) shouldIntercept(hostname string) bool {
 		"music.api.bose.com",
 		"bosecm.com",
 		"bose.io",
+		"downloads.bose.com",
 	}
 
 	for _, service := range interceptList {

pkg/discovery/mdns.go

@@ -14,17 +14,26 @@ import (
 
 // MDNSDiscoveryService handles mDNS/Bonjour discovery of SoundTouch devices
 type MDNSDiscoveryService struct {
-	timeout time.Duration
+	timeout   time.Duration
+	ifaceName string
 }
 
 // NewMDNSDiscoveryService creates a new mDNS discovery service
 func NewMDNSDiscoveryService(timeout time.Duration) *MDNSDiscoveryService {
+	return NewMDNSDiscoveryServiceWithInterface(timeout, "")
+}
+
+// NewMDNSDiscoveryServiceWithInterface creates a new mDNS discovery service
+// pinned to the given network interface (e.g. "eth0"). An empty ifaceName
+// falls back to the historical auto-pick behaviour.
+func NewMDNSDiscoveryServiceWithInterface(timeout time.Duration, ifaceName string) *MDNSDiscoveryService {
 	if timeout == 0 {
 		timeout = defaultTimeout
 	}
 
 	return &MDNSDiscoveryService{
-		timeout: timeout,
+		timeout:   timeout,
+		ifaceName: ifaceName,
 	}
 }
 
@@ -218,8 +227,27 @@ func (m *MDNSDiscoveryService) serviceEntryToDevice(entry *mdns.ServiceEntry) *m
 	return device
 }
 
-// getIPv4Interface returns the first suitable IPv4 network interface
+// getIPv4Interface returns the network interface to use for mDNS queries.
+// If an explicit name was configured, it is resolved and validated; otherwise
+// the first suitable, up, non-loopback IPv4 interface is returned.
 func (m *MDNSDiscoveryService) getIPv4Interface() *net.Interface {
+	if m.ifaceName != "" {
+		iface, err := net.InterfaceByName(m.ifaceName)
+		if err != nil {
+			log.Printf("mDNS: Configured interface %q not found: %v", m.ifaceName, err)
+			return nil
+		}
+
+		if !interfaceHasIPv4(iface) {
+			log.Printf("mDNS: Configured interface %q has no usable IPv4 address", m.ifaceName)
+			return nil
+		}
+
+		log.Printf("mDNS: Using configured IPv4 interface: %s", iface.Name)
+
+		return iface
+	}
+
 	interfaces, err := net.Interfaces()
 	if err != nil {
 		log.Printf("mDNS: Failed to get network interfaces: %v", err)
@@ -234,30 +262,42 @@ func (m *MDNSDiscoveryService) getIPv4Interface() *net.Interface {
 			continue
 		}
 
-		// Check if this interface has IPv4 addresses
-		addrs, err := iface.Addrs()
-		if err != nil {
+		if !interfaceHasIPv4(&iface) {
 			continue
 		}
 
-		hasIPv4 := false
+		log.Printf("mDNS: Using IPv4 interface: %s", iface.Name)
 
-		for _, addr := range addrs {
-			if ipNet, ok := addr.(*net.IPNet); ok {
-				if ipNet.IP.To4() != nil && !ipNet.IP.IsLoopback() {
-					hasIPv4 = true
-					break
-				}
-			}
-		}
-
-		if hasIPv4 {
-			log.Printf("mDNS: Using IPv4 interface: %s", iface.Name)
-			return &iface
-		}
+		return &iface
 	}
 
 	log.Printf("mDNS: No suitable IPv4 interface found")
 
 	return nil
 }
+
+// interfaceHasIPv4 reports whether iface has at least one non-loopback IPv4
+// address assigned and is administratively up.
+func interfaceHasIPv4(iface *net.Interface) bool {
+	if iface.Flags&net.FlagUp == 0 {
+		return false
+	}
+
+	addrs, err := iface.Addrs()
+	if err != nil {
+		return false
+	}
+
+	for _, addr := range addrs {
+		ipNet, ok := addr.(*net.IPNet)
+		if !ok {
+			continue
+		}
+
+		if ipNet.IP.To4() != nil && !ipNet.IP.IsLoopback() {
+			return true
+		}
+	}
+
+	return false
+}

pkg/discovery/mdns_test.go

@@ -92,6 +92,34 @@ func TestMDNSDiscoveryTimeout(t *testing.T) {
 	_ = err
 }
 
+func TestMDNSGetIPv4InterfaceUnknownName(t *testing.T) {
+	service := NewMDNSDiscoveryServiceWithInterface(5*time.Second, "definitely-not-a-real-iface-xyz")
+	if iface := service.getIPv4Interface(); iface != nil {
+		t.Errorf("Expected nil for unknown interface name, got %q", iface.Name)
+	}
+}
+
+func TestMDNSGetIPv4InterfaceExplicitMatchesAutoPick(t *testing.T) {
+	auto := NewMDNSDiscoveryService(5 * time.Second).getIPv4Interface()
+	if auto == nil {
+		t.Skip("No suitable IPv4 interface available on this host")
+	}
+
+	explicit := NewMDNSDiscoveryServiceWithInterface(5*time.Second, auto.Name).getIPv4Interface()
+	if explicit == nil {
+		t.Fatalf("Expected explicit lookup of %q to succeed", auto.Name)
+	}
+
+	if explicit.Name != auto.Name {
+		t.Errorf("Expected explicit interface %q, got %q", auto.Name, explicit.Name)
+	}
+
+	// Sanity: the resolved interface really has an IPv4 we could bind to.
+	if !interfaceHasIPv4(explicit) {
+		t.Errorf("Resolved interface %q has no IPv4 address", explicit.Name)
+	}
+}
+
 func TestMDNSDiscoveryWithCancelledContext(t *testing.T) {
 	service := NewMDNSDiscoveryService(5 * time.Second)
 

pkg/discovery/unified.go

@@ -142,7 +142,7 @@ func NewUnifiedDiscoveryService(cfg *config.Config) *UnifiedDiscoveryService {
 
 	return &UnifiedDiscoveryService{
 		ssdpService: NewServiceWithConfig(cfg),
-		mdnsService: NewMDNSDiscoveryService(timeout),
+		mdnsService: NewMDNSDiscoveryServiceWithInterface(timeout, cfg.DiscoveryInterface),
 		config:      cfg,
 		cache:       make(map[string]*models.DiscoveredDevice),
 		cacheTTL:    cacheTTL,

pkg/discovery/upnp.go

@@ -16,6 +16,7 @@ import (
 
 	"github.com/gesellix/bose-soundtouch/pkg/config"
 	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"golang.org/x/net/ipv4"
 )
 
 // Service handles UPnP SSDP discovery of SoundTouch devices
@@ -26,6 +27,7 @@ type Service struct {
 	mutex      sync.RWMutex
 	config     *config.Config
 	httpClient *http.Client
+	ifaceName  string
 }
 
 // NewService creates a new UPnP discovery service
@@ -63,6 +65,7 @@ func NewServiceWithConfig(cfg *config.Config) *Service {
 		mutex:      sync.RWMutex{},
 		config:     cfg,
 		httpClient: &http.Client{Timeout: 5 * time.Second},
+		ifaceName:  cfg.DiscoveryInterface,
 	}
 }
 
@@ -189,15 +192,16 @@ func (d *Service) PerformDiscovery(ctx context.Context) ([]*models.DiscoveredDev
 }
 
 func (d *Service) setupUDPListener() (*net.UDPConn, error) {
-	listenAddr, err := net.ResolveUDPAddr("udp4", ":0")
+	listenIP, iface, err := d.resolveListenInterface()
 	if err != nil {
-		log.Printf("UPnP: Failed to resolve listen address: %v", err)
-		return nil, fmt.Errorf("failed to resolve listen address: %w", err)
+		return nil, err
 	}
 
+	listenAddr := &net.UDPAddr{IP: listenIP, Port: 0}
+
 	listener, err := net.ListenUDP("udp4", listenAddr)
 	if err != nil {
-		log.Printf("UPnP: Failed to create UDP listener: %v", err)
+		log.Printf("UPnP: Failed to create UDP listener on %s: %v", listenAddr, err)
 		return nil, fmt.Errorf("failed to create UDP listener: %w", err)
 	}
 
@@ -212,11 +216,62 @@ func (d *Service) setupUDPListener() (*net.UDPConn, error) {
 		return nil, fmt.Errorf("failed to cast local address to UDPAddr: %v", addr)
 	}
 
+	// Pin the outgoing multicast packets to the configured interface so the
+	// M-SEARCH leaves through the right NIC on multi-homed hosts.
+	if iface != nil {
+		if err := ipv4.NewPacketConn(listener).SetMulticastInterface(iface); err != nil {
+			log.Printf("UPnP: Failed to set multicast interface to %q: %v", iface.Name, err)
+			// Continue regardless — the kernel will fall back to its own routing decision.
+		}
+	}
+
 	log.Printf("UPnP: Created UDP listener on %s", localAddr.String())
 
 	return listener, nil
 }
 
+// resolveListenInterface returns the source IP to bind the UDP listener to and
+// the interface to use for outgoing multicast. When no interface is configured,
+// the IP is nil (wildcard) and the iface is nil, preserving the historical
+// behaviour where the kernel picks a route.
+func (d *Service) resolveListenInterface() (net.IP, *net.Interface, error) {
+	if d.ifaceName == "" {
+		return nil, nil, nil
+	}
+
+	iface, err := net.InterfaceByName(d.ifaceName)
+	if err != nil {
+		log.Printf("UPnP: Configured interface %q not found: %v", d.ifaceName, err)
+		return nil, nil, fmt.Errorf("configured interface %q not found: %w", d.ifaceName, err)
+	}
+
+	addrs, err := iface.Addrs()
+	if err != nil {
+		log.Printf("UPnP: Failed to read addresses for interface %q: %v", d.ifaceName, err)
+		return nil, nil, fmt.Errorf("read addresses for interface %q: %w", d.ifaceName, err)
+	}
+
+	for _, addr := range addrs {
+		ipNet, ok := addr.(*net.IPNet)
+		if !ok {
+			continue
+		}
+
+		ipv4Addr := ipNet.IP.To4()
+		if ipv4Addr == nil || ipNet.IP.IsLoopback() {
+			continue
+		}
+
+		log.Printf("UPnP: Binding UDP listener to interface %q (%s)", iface.Name, ipv4Addr)
+
+		return ipv4Addr, iface, nil
+	}
+
+	log.Printf("UPnP: Configured interface %q has no usable IPv4 address", d.ifaceName)
+
+	return nil, nil, fmt.Errorf("interface %q has no usable IPv4 address", d.ifaceName)
+}
+
 func (d *Service) sendMSearch(listener *net.UDPConn, multicastAddr *net.UDPAddr) error {
 	msearchRequest := d.buildMSearchRequest()
 	log.Printf("UPnP: Sending M-SEARCH request to %s:\n%s", ssdpAddr, strings.TrimSpace(msearchRequest))

pkg/models/account.go

@@ -135,6 +135,22 @@ func NewSpotifyOAuthCredentials(user, code, displayName string) *OAuthCredential
 	}
 }
 
+// NewAmazonOAuthCredentials creates OAuth credentials for Amazon Music (cs1 / "token").
+// code is the AmazonSecret JSON envelope stored as the credential in Sources.xml.
+func NewAmazonOAuthCredentials(user, code, displayName string) *OAuthCredentials {
+	if displayName == "" {
+		displayName = user
+	}
+
+	return &OAuthCredentials{
+		Source:      "AMAZON",
+		DisplayName: displayName,
+		User:        user,
+		Code:        code,
+		Version:     "token",
+	}
+}
+
 // MusicServiceAccountResponse represents the response from account management operations
 type MusicServiceAccountResponse struct {
 	XMLName xml.Name `xml:"status"`

pkg/models/clockdisplay.go

@@ -2,20 +2,155 @@ package models
 
 import (
 	"encoding/xml"
+	"errors"
 	"fmt"
+	"io"
+	"strconv"
 	"strings"
 )
 
-// ClockDisplay represents the device's clock display settings
+// ClockDisplay represents the device's clock display settings.
+//
+// Wire format (confirmed against ST10/ST20 firmware 27.0.6 — flat
+// attributes on the outer <clockDisplay> are rejected with
+// "Error parsing request"):
+//
+//	<clockDisplay deviceID="…">
+//	  <clockConfig timezoneInfo="Europe/Berlin"
+//	               userEnable="true"
+//	               timeFormat="TIME_FORMAT_24HOUR_ID"
+//	               userOffsetMinute="0"
+//	               brightnessLevel="70"
+//	               userUtcTime="0"/>
+//	</clockDisplay>
+//
+// The struct keeps its historical flat-field public API so the CLI and
+// other callers don't have to be rewritten; custom MarshalXML /
+// UnmarshalXML methods bridge to the nested format on the wire.
 type ClockDisplay struct {
 	XMLName    xml.Name `xml:"clockDisplay"`
-	DeviceID   string   `xml:"deviceID,attr,omitempty"`
-	Enabled    bool     `xml:"enabled,attr,omitempty"`
-	Format     string   `xml:"format,attr,omitempty"`
-	Brightness int      `xml:"brightness,attr,omitempty"`
-	AutoDim    bool     `xml:"autoDim,attr,omitempty"`
-	TimeZone   string   `xml:"timeZone,attr,omitempty"`
-	Value      string   `xml:",chardata"`
+	DeviceID   string
+	Enabled    bool
+	Format     string // public-facing values: "12", "24", "auto"
+	Brightness int
+	AutoDim    bool // not on the device's wire format; preserved for API compat
+	TimeZone   string
+	Value      string // kept for API compat — older fixtures stored chardata here
+}
+
+// Wire constants for clockConfig/@timeFormat.
+const (
+	wireTimeFormat12Hour = "TIME_FORMAT_12HOUR_ID"
+	wireTimeFormat24Hour = "TIME_FORMAT_24HOUR_ID"
+	wireTimeFormatAuto   = "TIME_FORMAT_AUTO_ID"
+)
+
+func mapToWireFormat(f string) string {
+	switch strings.ToLower(f) {
+	case "12":
+		return wireTimeFormat12Hour
+	case "24":
+		return wireTimeFormat24Hour
+	case "auto":
+		return wireTimeFormatAuto
+	default:
+		return ""
+	}
+}
+
+func mapFromWireFormat(wire string) string {
+	switch wire {
+	case wireTimeFormat12Hour:
+		return "12"
+	case wireTimeFormat24Hour:
+		return "24"
+	case wireTimeFormatAuto:
+		return "auto"
+	default:
+		return ""
+	}
+}
+
+// UnmarshalXML decodes the nested <clockDisplay><clockConfig …/></clockDisplay>
+// into ClockDisplay's flat fields. Tolerates the older flat shape too —
+// either because it appears in legacy captures or for forward-compat with
+// firmwares that may revert.
+func (c *ClockDisplay) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
+	applyClockDisplayOuterAttrs(c, start.Attr)
+
+	for {
+		tok, err := d.Token()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+
+		if err != nil {
+			return err
+		}
+
+		switch t := tok.(type) {
+		case xml.StartElement:
+			if t.Name.Local == "clockConfig" {
+				applyClockConfigAttrs(c, t.Attr)
+			}
+
+			if err := d.Skip(); err != nil {
+				return err
+			}
+
+		case xml.CharData:
+			if text := strings.TrimSpace(string(t)); text != "" {
+				c.Value = text
+			}
+
+		case xml.EndElement:
+			return nil
+		}
+	}
+
+	return nil
+}
+
+// applyClockDisplayOuterAttrs handles the legacy flat-attribute format
+// (deviceID, enabled, format, brightness, autoDim, timeZone) that older
+// fixtures used directly on the <clockDisplay> element.
+func applyClockDisplayOuterAttrs(c *ClockDisplay, attrs []xml.Attr) {
+	for _, attr := range attrs {
+		switch attr.Name.Local {
+		case "deviceID":
+			c.DeviceID = attr.Value
+		case "enabled":
+			c.Enabled = attr.Value == "true"
+		case "format":
+			c.Format = attr.Value
+		case "brightness":
+			c.Brightness, _ = strconv.Atoi(attr.Value)
+		case "autoDim":
+			c.AutoDim = attr.Value == "true"
+		case "timeZone":
+			c.TimeZone = attr.Value
+		}
+	}
+}
+
+// applyClockConfigAttrs handles the nested <clockConfig> attributes
+// (timezoneInfo, userEnable, timeFormat, brightnessLevel) — the shape
+// FW 27 emits and accepts.
+func applyClockConfigAttrs(c *ClockDisplay, attrs []xml.Attr) {
+	for _, attr := range attrs {
+		switch attr.Name.Local {
+		case "timezoneInfo":
+			c.TimeZone = attr.Value
+		case "userEnable":
+			c.Enabled = attr.Value == "true"
+		case "timeFormat":
+			if mapped := mapFromWireFormat(attr.Value); mapped != "" {
+				c.Format = mapped
+			}
+		case "brightnessLevel":
+			c.Brightness, _ = strconv.Atoi(attr.Value)
+		}
+	}
 }
 
 // ClockFormat represents supported clock display formats
@@ -108,14 +243,16 @@ func (c *ClockDisplay) IsEmpty() bool {
 	return !c.Enabled && c.Format == "" && c.Brightness == 0 && c.TimeZone == ""
 }
 
-// ClockDisplayRequest represents a request to configure clock display settings
+// ClockDisplayRequest represents a request to configure clock display
+// settings. Fields use the same public names as the response struct;
+// MarshalXML produces the nested wire format the device requires.
 type ClockDisplayRequest struct {
 	XMLName    xml.Name `xml:"clockDisplay"`
-	Enabled    *bool    `xml:"enabled,attr,omitempty"`
-	Format     string   `xml:"format,attr,omitempty"`
-	Brightness *int     `xml:"brightness,attr,omitempty"`
-	AutoDim    *bool    `xml:"autoDim,attr,omitempty"`
-	TimeZone   string   `xml:"timeZone,attr,omitempty"`
+	Enabled    *bool
+	Format     string
+	Brightness *int
+	AutoDim    *bool
+	TimeZone   string
 }
 
 // NewClockDisplayRequest creates a new clock display configuration request
@@ -184,3 +321,62 @@ func (r *ClockDisplayRequest) Validate() error {
 func (r *ClockDisplayRequest) HasChanges() bool {
 	return r.Enabled != nil || r.Format != "" || r.Brightness != nil || r.AutoDim != nil || r.TimeZone != ""
 }
+
+// MarshalXML emits the nested <clockDisplay><clockConfig …/></clockDisplay>
+// envelope the device accepts. Empty fields are omitted so partial updates
+// (e.g. "set only the timezone") don't accidentally clear other settings.
+//
+// AutoDim has no counterpart in the captured wire format; we still accept
+// it in the public API for backward-compat but it is not emitted.
+func (r ClockDisplayRequest) MarshalXML(e *xml.Encoder, _ xml.StartElement) error {
+	display := xml.StartElement{Name: xml.Name{Local: "clockDisplay"}}
+	if err := e.EncodeToken(display); err != nil {
+		return err
+	}
+
+	cfg := xml.StartElement{Name: xml.Name{Local: "clockConfig"}}
+
+	if r.TimeZone != "" {
+		cfg.Attr = append(cfg.Attr, xml.Attr{
+			Name:  xml.Name{Local: "timezoneInfo"},
+			Value: r.TimeZone,
+		})
+	}
+
+	if r.Enabled != nil {
+		cfg.Attr = append(cfg.Attr, xml.Attr{
+			Name:  xml.Name{Local: "userEnable"},
+			Value: strconv.FormatBool(*r.Enabled),
+		})
+	}
+
+	if r.Format != "" {
+		if wire := mapToWireFormat(r.Format); wire != "" {
+			cfg.Attr = append(cfg.Attr, xml.Attr{
+				Name:  xml.Name{Local: "timeFormat"},
+				Value: wire,
+			})
+		}
+	}
+
+	if r.Brightness != nil {
+		cfg.Attr = append(cfg.Attr, xml.Attr{
+			Name:  xml.Name{Local: "brightnessLevel"},
+			Value: strconv.Itoa(*r.Brightness),
+		})
+	}
+
+	if err := e.EncodeToken(cfg); err != nil {
+		return err
+	}
+
+	if err := e.EncodeToken(xml.EndElement{Name: cfg.Name}); err != nil {
+		return err
+	}
+
+	if err := e.EncodeToken(xml.EndElement{Name: display.Name}); err != nil {
+		return err
+	}
+
+	return e.Flush()
+}

pkg/models/clockdisplay_test.go

@@ -641,7 +641,7 @@ func TestClockDisplayRequest_MarshalXML(t *testing.T) {
 		Enabled:    &[]bool{true}[0],
 		Format:     "24",
 		Brightness: &[]int{75}[0],
-		AutoDim:    &[]bool{false}[0],
+		AutoDim:    &[]bool{false}[0], // not on the wire format — must be silently dropped
 		TimeZone:   "America/New_York",
 	}
 
@@ -650,8 +650,57 @@ func TestClockDisplayRequest_MarshalXML(t *testing.T) {
 		t.Fatalf("Failed to marshal XML: %v", err)
 	}
 
-	expected := `<clockDisplay enabled="true" format="24" brightness="75" autoDim="false" timeZone="America/New_York"></clockDisplay>`
+	// Must match the device's captured POST shape — firmware 27 rejects
+	// the legacy flat <clockDisplay enabled="…" format="…" .../> with
+	// "Error parsing request".
+	expected := `<clockDisplay><clockConfig timezoneInfo="America/New_York" userEnable="true" timeFormat="TIME_FORMAT_24HOUR_ID" brightnessLevel="75"></clockConfig></clockDisplay>`
 	if string(data) != expected {
 		t.Errorf("Expected XML %q, got %q", expected, string(data))
 	}
 }
+
+func TestClockDisplayRequest_MarshalXML_TimezoneOnly(t *testing.T) {
+	// Partial update: only set the timezone. Unset fields must be
+	// omitted so we don't clobber the device's other settings.
+	request := ClockDisplayRequest{TimeZone: "Europe/Berlin"}
+
+	data, err := xml.Marshal(request)
+	if err != nil {
+		t.Fatalf("Failed to marshal XML: %v", err)
+	}
+
+	expected := `<clockDisplay><clockConfig timezoneInfo="Europe/Berlin"></clockConfig></clockDisplay>`
+	if string(data) != expected {
+		t.Errorf("Expected XML %q, got %q", expected, string(data))
+	}
+}
+
+func TestClockDisplay_UnmarshalXML_NestedClockConfig(t *testing.T) {
+	// The real wire format — what firmware-27 devices emit and accept.
+	xmlData := `<clockDisplay deviceID="A81B6A536A98"><clockConfig timezoneInfo="Europe/Berlin" userEnable="true" timeFormat="TIME_FORMAT_24HOUR_ID" userOffsetMinute="0" brightnessLevel="70" userUtcTime="0"/></clockDisplay>`
+
+	var got ClockDisplay
+	if err := xml.Unmarshal([]byte(xmlData), &got); err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+
+	if got.DeviceID != "A81B6A536A98" {
+		t.Errorf("DeviceID = %q, want A81B6A536A98", got.DeviceID)
+	}
+
+	if got.TimeZone != "Europe/Berlin" {
+		t.Errorf("TimeZone = %q, want Europe/Berlin", got.TimeZone)
+	}
+
+	if !got.Enabled {
+		t.Error("Enabled = false, want true (from userEnable=true)")
+	}
+
+	if got.Format != "24" {
+		t.Errorf("Format = %q, want 24 (from timeFormat=TIME_FORMAT_24HOUR_ID)", got.Format)
+	}
+
+	if got.Brightness != 70 {
+		t.Errorf("Brightness = %d, want 70 (from brightnessLevel)", got.Brightness)
+	}
+}

pkg/models/clocktime.go

@@ -182,44 +182,44 @@ func (c *ClockTime) SetUTC(utc int64) {
 	}
 }
 
-// ClockTimeRequest represents a request to set the device time
+// ClockTimeRequest represents a request to set the device time.
+//
+// The POST body mirrors the device's GET /clockTime response shape —
+// firmware 27 expects `utcTime` as the attribute name, not `utc`, and
+// rejects any chardata or zone attribute with "Error parsing request"
+// (confirmed against ST10/ST20/ST30 in live testing 2026-05-12).
+//
+// We deliberately do NOT send TimeFormat / Brightness in the request:
+// those belong to /clockDisplay and including them here either gets
+// ignored or rejected depending on firmware revision.
 type ClockTimeRequest struct {
 	XMLName xml.Name `xml:"clockTime"`
-	Zone    string   `xml:"zone,attr,omitempty"`
-	UTC     int64    `xml:"utc,attr,omitempty"`
-	Value   string   `xml:",chardata"`
+	UTCTime int64    `xml:"utcTime,attr"`
 }
 
-// NewClockTimeRequest creates a new clock time request from a time.Time
+// NewClockTimeRequest creates a new clock time request from a time.Time.
+// The input may be in any zone — we always send Unix-seconds, which the
+// device interprets as UTC and renders according to its own clockDisplay
+// configuration.
 func NewClockTimeRequest(t time.Time) *ClockTimeRequest {
-	return &ClockTimeRequest{
-		Zone:  t.Location().String(),
-		UTC:   t.Unix(),
-		Value: t.UTC().Format("2006-01-02 15:04:05"),
-	}
+	return &ClockTimeRequest{UTCTime: t.Unix()}
 }
 
-// NewClockTimeRequestUTC creates a new clock time request from UTC timestamp
+// NewClockTimeRequestUTC creates a new clock time request from a Unix
+// timestamp in seconds.
 func NewClockTimeRequestUTC(utc int64) *ClockTimeRequest {
-	t := time.Unix(utc, 0).UTC()
-
-	return &ClockTimeRequest{
-		UTC:   utc,
-		Value: t.Format("2006-01-02 15:04:05"),
-	}
+	return &ClockTimeRequest{UTCTime: utc}
 }
 
-// Validate checks if the clock time request is valid
+// Validate checks if the clock time request is valid.
 func (r *ClockTimeRequest) Validate() error {
-	if r.UTC <= 0 && r.Value == "" {
-		return fmt.Errorf("either UTC timestamp or time value must be provided")
+	if r.UTCTime <= 0 {
+		return fmt.Errorf("UTC timestamp must be provided")
 	}
 
-	if r.UTC > 0 {
-		// Validate UTC timestamp is reasonable (after year 2000, before year 2100)
-		if r.UTC < 946684800 || r.UTC > 4102444800 {
-			return fmt.Errorf("UTC timestamp %d is outside reasonable range", r.UTC)
-		}
+	// Plausibility window: after year 2000, before year 2100.
+	if r.UTCTime < 946684800 || r.UTCTime > 4102444800 {
+		return fmt.Errorf("UTC timestamp %d is outside reasonable range", r.UTCTime)
 	}
 
 	return nil

pkg/models/clocktime_test.go

@@ -284,16 +284,8 @@ func TestNewClockTimeRequest(t *testing.T) {
 
 	request := NewClockTimeRequest(testTime)
 
-	if request.UTC != testTime.Unix() {
-		t.Errorf("Expected UTC %d, got %d", testTime.Unix(), request.UTC)
-	}
-
-	if request.Value != "2021-01-01 12:00:00" {
-		t.Errorf("Expected Value %q, got %q", "2021-01-01 12:00:00", request.Value)
-	}
-
-	if request.Zone != "UTC" {
-		t.Errorf("Expected Zone %q, got %q", "UTC", request.Zone)
+	if request.UTCTime != testTime.Unix() {
+		t.Errorf("Expected UTCTime %d, got %d", testTime.Unix(), request.UTCTime)
 	}
 }
 
@@ -302,13 +294,8 @@ func TestNewClockTimeRequestUTC(t *testing.T) {
 
 	request := NewClockTimeRequestUTC(utcTimestamp)
 
-	if request.UTC != utcTimestamp {
-		t.Errorf("Expected UTC %d, got %d", utcTimestamp, request.UTC)
-	}
-
-	expectedValue := time.Unix(utcTimestamp, 0).UTC().Format("2006-01-02 15:04:05")
-	if request.Value != expectedValue {
-		t.Errorf("Expected Value %q, got %q", expectedValue, request.Value)
+	if request.UTCTime != utcTimestamp {
+		t.Errorf("Expected UTCTime %d, got %d", utcTimestamp, request.UTCTime)
 	}
 }
 
@@ -319,25 +306,8 @@ func TestClockTimeRequest_Validate(t *testing.T) {
 		wantErr bool
 	}{
 		{
-			name: "Valid UTC request",
-			request: ClockTimeRequest{
-				UTC: 1609459200,
-			},
-			wantErr: false,
-		},
-		{
-			name: "Valid value request",
-			request: ClockTimeRequest{
-				Value: "2021-01-01 12:00:00",
-			},
-			wantErr: false,
-		},
-		{
-			name: "Valid request with both",
-			request: ClockTimeRequest{
-				UTC:   1609459200,
-				Value: "2021-01-01 12:00:00",
-			},
+			name:    "Valid UTC request",
+			request: ClockTimeRequest{UTCTime: 1609459200},
 			wantErr: false,
 		},
 		{
@@ -346,17 +316,13 @@ func TestClockTimeRequest_Validate(t *testing.T) {
 			wantErr: true,
 		},
 		{
-			name: "UTC too old",
-			request: ClockTimeRequest{
-				UTC: 946684799, // Before year 2000
-			},
+			name:    "UTC too old",
+			request: ClockTimeRequest{UTCTime: 946684799}, // Before year 2000
 			wantErr: true,
 		},
 		{
-			name: "UTC too far in future",
-			request: ClockTimeRequest{
-				UTC: 4102444801, // After year 2100
-			},
+			name:    "UTC too far in future",
+			request: ClockTimeRequest{UTCTime: 4102444801}, // After year 2100
 			wantErr: true,
 		},
 	}
@@ -377,18 +343,16 @@ func TestClockTimeRequest_Validate(t *testing.T) {
 }
 
 func TestClockTimeRequest_MarshalXML(t *testing.T) {
-	request := ClockTimeRequest{
-		Zone:  "UTC",
-		UTC:   1609459200,
-		Value: "2021-01-01 00:00:00",
-	}
+	request := ClockTimeRequest{UTCTime: 1609459200}
 
 	data, err := xml.Marshal(request)
 	if err != nil {
 		t.Fatalf("Failed to marshal XML: %v", err)
 	}
 
-	expected := `<clockTime zone="UTC" utc="1609459200">2021-01-01 00:00:00</clockTime>`
+	// Must match the device's GET /clockTime response attribute name
+	// — firmware 27 rejects `utc=` (no Time suffix) with "Error parsing request".
+	expected := `<clockTime utcTime="1609459200"></clockTime>`
 	if string(data) != expected {
 		t.Errorf("Expected XML %q, got %q", expected, string(data))
 	}

pkg/models/group.go

@@ -0,0 +1,34 @@
+package models
+
+import "encoding/xml"
+
+// Group represents a stereo pair of two ST10 SoundTouch speakers.
+type Group struct {
+	XMLName         xml.Name   `xml:"group"`
+	ID              string     `xml:"id,attr,omitempty"`
+	Name            string     `xml:"name"`
+	MasterDeviceID  string     `xml:"masterDeviceId"`
+	Roles           GroupRoles `xml:"roles"`
+	SenderIPAddress string     `xml:"senderIPAddress,omitempty"`
+	// Status is populated by the device on GET /group (e.g. "GROUP_OK")
+	// and omitted from requests we send back.
+	Status string `xml:"status,omitempty"`
+}
+
+// IsEmpty reports whether the device returned an empty <group/> element,
+// which is the speaker's way of saying "no stereo pair configured".
+func (g *Group) IsEmpty() bool {
+	return g.ID == "" && g.MasterDeviceID == "" && len(g.Roles.Roles) == 0
+}
+
+// GroupRoles contains the role assignments for devices in a group.
+type GroupRoles struct {
+	Roles []GroupRole `xml:"groupRole"`
+}
+
+// GroupRole describes the role (LEFT or RIGHT) of a single device in a group.
+type GroupRole struct {
+	DeviceID  string `xml:"deviceId"`
+	Role      string `xml:"role"`
+	IPAddress string `xml:"ipAddress,omitempty"`
+}

pkg/models/models.go

@@ -755,6 +755,7 @@ type FullResponseSource struct {
 	Username         string `json:"username" xml:"username"`
 	Account          string `json:"account,omitempty" xml:"account,attr,omitempty"`
 	SourceLabel      string `json:"source_label" xml:"-"`
+	ProviderLabel    string `json:"provider_label,omitempty" xml:"-"`
 }
 
 // FullResponsePreset represents a preset specifically for the /full response.

pkg/models/websocket.go

@@ -21,6 +21,10 @@ const (
 	EventTypePresetUpdated WebSocketEventType = "presetsUpdated"
 	// EventTypeZoneUpdated indicates a zone configuration change
 	EventTypeZoneUpdated WebSocketEventType = "zoneUpdated"
+	// EventTypeGroupUpdated is emitted to both ROLE devices when an ST-10
+	// stereo pair is created, renamed, or removed via /addGroup,
+	// /updateGroup, or /removeGroup.
+	EventTypeGroupUpdated WebSocketEventType = "groupUpdated"
 	// EventTypeBassUpdated indicates a bass level change
 	EventTypeBassUpdated WebSocketEventType = "bassUpdated"
 	// EventTypeClockTimeUpdated indicates a clock time change
@@ -56,6 +60,8 @@ func (e WebSocketEventType) String() string {
 		return "Preset Updated"
 	case EventTypeZoneUpdated:
 		return "Zone Updated"
+	case EventTypeGroupUpdated:
+		return "Stereo Pair Updated"
 	case EventTypeBassUpdated:
 		return "Bass Updated"
 	case EventTypeClockTimeUpdated:
@@ -88,6 +94,7 @@ type WebSocketEvent struct {
 	ConnectionStateUpdated *ConnectionStateUpdatedEvent `xml:"connectionStateUpdated,omitempty"`
 	PresetUpdated          *PresetUpdatedEvent          `xml:"presetsUpdated,omitempty"`
 	ZoneUpdated            *ZoneUpdatedEvent            `xml:"zoneUpdated,omitempty"`
+	GroupUpdated           *GroupUpdatedEvent           `xml:"groupUpdated,omitempty"`
 	BassUpdated            *BassUpdatedEvent            `xml:"bassUpdated,omitempty"`
 	ClockTimeUpdated       *ClockTimeUpdatedEvent       `xml:"clockTimeUpdated,omitempty"`
 	ClockDisplayUpdated    *ClockDisplayUpdatedEvent    `xml:"clockDisplayUpdated,omitempty"`
@@ -122,6 +129,10 @@ func (e *WebSocketEvent) GetEvents() []interface{} {
 		events = append(events, e.ZoneUpdated)
 	}
 
+	if e.GroupUpdated != nil {
+		events = append(events, e.GroupUpdated)
+	}
+
 	if e.BassUpdated != nil {
 		events = append(events, e.BassUpdated)
 	}
@@ -215,6 +226,16 @@ type ZoneUpdatedEvent struct {
 	Zone     Zone     `xml:"zone"`
 }
 
+// GroupUpdatedEvent represents an ST-10 stereo-pair update notification.
+// The device fans this event out to both LEFT and RIGHT speakers whenever
+// the pair is created, renamed, or removed. Group will be the zero value
+// for a teardown notification — see (*Group).IsEmpty.
+type GroupUpdatedEvent struct {
+	XMLName  xml.Name `xml:"groupUpdated"`
+	DeviceID string   `xml:"deviceID,attr"`
+	Group    Group    `xml:"group"`
+}
+
 // Zone represents multiroom zone information
 type Zone struct {
 	XMLName xml.Name     `xml:"zone"`
@@ -373,6 +394,7 @@ type WebSocketEventHandlers struct {
 	OnConnectionState     TypedEventHandler[*ConnectionStateUpdatedEvent]
 	OnPresetUpdated       TypedEventHandler[*PresetUpdatedEvent]
 	OnZoneUpdated         TypedEventHandler[*ZoneUpdatedEvent]
+	OnGroupUpdated        TypedEventHandler[*GroupUpdatedEvent]
 	OnBassUpdated         TypedEventHandler[*BassUpdatedEvent]
 	OnClockTimeUpdated    TypedEventHandler[*ClockTimeUpdatedEvent]
 	OnClockDisplayUpdated TypedEventHandler[*ClockDisplayUpdatedEvent]
@@ -382,8 +404,19 @@ type WebSocketEventHandlers struct {
 	OnLanguageUpdated     TypedEventHandler[*LanguageUpdatedEvent]
 	OnUnknownEvent        EventHandler
 	OnSpecialMessage      SpecialMessageHandler
+	// OnRawMessage fires for every received frame before any parsing
+	// happens. Use it for debug/observability tooling that wants to see
+	// exactly what the device sent on the wire — the typed handlers
+	// above still run afterwards, independently. parseErr is the result
+	// of the XML parse: nil for messages that decoded cleanly, non-nil
+	// for malformed payloads. The slice is owned by the caller; copy
+	// before retaining.
+	OnRawMessage RawMessageHandler
 }
 
+// RawMessageHandler defines the signature for raw-frame handlers.
+type RawMessageHandler func(data []byte, parseErr error)
+
 // ParseWebSocketEvent attempts to parse a WebSocket message into a specific event type
 func ParseWebSocketEvent(data []byte) (*WebSocketEvent, error) {
 	var event WebSocketEvent
@@ -411,6 +444,8 @@ func (e *WebSocketEvent) getFieldByEventType(eventType WebSocketEventType) inter
 		field = e.PresetUpdated
 	case EventTypeZoneUpdated:
 		field = e.ZoneUpdated
+	case EventTypeGroupUpdated:
+		field = e.GroupUpdated
 	case EventTypeBassUpdated:
 		field = e.BassUpdated
 	case EventTypeClockTimeUpdated:
@@ -462,6 +497,8 @@ func isNil(i interface{}) bool {
 		return v == nil
 	case *ZoneUpdatedEvent:
 		return v == nil
+	case *GroupUpdatedEvent:
+		return v == nil
 	case *BassUpdatedEvent:
 		return v == nil
 	case *ClockTimeUpdatedEvent:
@@ -508,6 +545,8 @@ func (e *WebSocketEvent) HasEventType(eventType WebSocketEventType) bool {
 		return e.PresetUpdated != nil
 	case EventTypeZoneUpdated:
 		return e.ZoneUpdated != nil
+	case EventTypeGroupUpdated:
+		return e.GroupUpdated != nil
 	case EventTypeBassUpdated:
 		return e.BassUpdated != nil
 	case EventTypeClockTimeUpdated:
@@ -551,6 +590,10 @@ func (e *WebSocketEvent) GetEventTypes() []WebSocketEventType {
 		types = append(types, EventTypeZoneUpdated)
 	}
 
+	if e.GroupUpdated != nil {
+		types = append(types, EventTypeGroupUpdated)
+	}
+
 	if e.BassUpdated != nil {
 		types = append(types, EventTypeBassUpdated)
 	}

pkg/models/websocket_test.go

@@ -16,6 +16,7 @@ func TestWebSocketEventType_String(t *testing.T) {
 		{"ConnectionState", EventTypeConnectionState, "Connection State Updated"},
 		{"PresetUpdated", EventTypePresetUpdated, "Preset Updated"},
 		{"ZoneUpdated", EventTypeZoneUpdated, "Zone Updated"},
+		{"GroupUpdated", EventTypeGroupUpdated, "Stereo Pair Updated"},
 		{"BassUpdated", EventTypeBassUpdated, "Bass Updated"},
 		{"ClockTimeUpdated", EventTypeClockTimeUpdated, "Clock Time Updated"},
 		{"ClockDisplayUpdated", EventTypeClockDisplayUpdated, "Clock Display Updated"},
@@ -187,6 +188,89 @@ func TestParseWebSocketEvent(t *testing.T) {
 			t.Error("Expected error for invalid XML, got nil")
 		}
 	})
+
+	t.Run("ValidGroupUpdatedEvent", func(t *testing.T) {
+		// The device fans this out to both ROLE devices when a stereo
+		// pair is created via POST /addGroup.
+		xmlData := `<?xml version="1.0" encoding="UTF-8" ?>
+<updates deviceID="9070658C9D4A">
+	<groupUpdated deviceID="9070658C9D4A">
+		<group id="1234567">
+			<name>Living Room Pair</name>
+			<masterDeviceId>9070658C9D4A</masterDeviceId>
+			<roles>
+				<groupRole>
+					<deviceId>9070658C9D4A</deviceId>
+					<role>LEFT</role>
+					<ipAddress>192.168.1.131</ipAddress>
+				</groupRole>
+				<groupRole>
+					<deviceId>F45EAB3115DA</deviceId>
+					<role>RIGHT</role>
+					<ipAddress>192.168.1.134</ipAddress>
+				</groupRole>
+			</roles>
+			<status>GROUP_OK</status>
+		</group>
+	</groupUpdated>
+</updates>`
+
+		event, err := ParseWebSocketEvent([]byte(xmlData))
+		if err != nil {
+			t.Fatalf("ParseWebSocketEvent: %v", err)
+		}
+
+		if !event.HasEventType(EventTypeGroupUpdated) {
+			t.Fatal("HasEventType(EventTypeGroupUpdated) = false, want true")
+		}
+
+		if event.GroupUpdated == nil {
+			t.Fatal("GroupUpdated is nil")
+		}
+
+		g := event.GroupUpdated.Group
+
+		if g.ID != "1234567" {
+			t.Errorf("group ID = %q, want 1234567", g.ID)
+		}
+
+		if g.MasterDeviceID != "9070658C9D4A" {
+			t.Errorf("MasterDeviceID = %q", g.MasterDeviceID)
+		}
+
+		if len(g.Roles.Roles) != 2 || g.Roles.Roles[0].Role != "LEFT" || g.Roles.Roles[1].Role != "RIGHT" {
+			t.Errorf("roles not parsed as LEFT/RIGHT: %+v", g.Roles.Roles)
+		}
+
+		if g.Status != "GROUP_OK" {
+			t.Errorf("status = %q, want GROUP_OK", g.Status)
+		}
+	})
+
+	t.Run("GroupUpdatedTeardown", func(t *testing.T) {
+		// On /removeGroup, the device emits a groupUpdated with an empty
+		// <group/> body. Parsing must surface that as IsEmpty=true so the
+		// UI can render "pair dissolved" cleanly.
+		xmlData := `<?xml version="1.0" encoding="UTF-8" ?>
+<updates deviceID="9070658C9D4A">
+	<groupUpdated deviceID="9070658C9D4A">
+		<group/>
+	</groupUpdated>
+</updates>`
+
+		event, err := ParseWebSocketEvent([]byte(xmlData))
+		if err != nil {
+			t.Fatalf("ParseWebSocketEvent: %v", err)
+		}
+
+		if event.GroupUpdated == nil {
+			t.Fatal("GroupUpdated is nil")
+		}
+
+		if !event.GroupUpdated.Group.IsEmpty() {
+			t.Errorf("Group.IsEmpty() = false on teardown; got %+v", event.GroupUpdated.Group)
+		}
+	})
 }
 
 func TestWebSocketEvent_HasEventType(t *testing.T) {

pkg/service/amazon/service.go

@@ -0,0 +1,456 @@
+// Package amazon provides Amazon Music (Login with Amazon) OAuth integration
+// and token management for the SoundTouch service.
+package amazon
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+)
+
+const (
+	// AmazonAuthorizeURL is the Login with Amazon (LWA) authorization endpoint.
+	AmazonAuthorizeURL = "https://www.amazon.com/ap/oa"
+	// AmazonTokenURL is the LWA token endpoint.
+	AmazonTokenURL = "https://api.amazon.com/auth/o2/token"
+	// AmazonProfileURL is the LWA user profile endpoint.
+	AmazonProfileURL = "https://api.amazon.com/user/profile"
+	// AmazonScopes are the OAuth scopes for account linking.
+	// amazon_music:access is required for music-api.amazon.com but is only available
+	// to device client IDs (Amazon Music partner apps), not standard application
+	// client IDs (amzn1.application-oa2-client.*). Requesting it returns a 400
+	// lwa-invalid-parameter-bad-scope error from the LWA authorization endpoint.
+	AmazonScopes = "profile"
+)
+
+// Account represents a stored Amazon account with tokens.
+type Account struct {
+	UserID       string `json:"user_id"`
+	DisplayName  string `json:"display_name"`
+	Email        string `json:"email"`
+	AccessToken  string `json:"access_token"`
+	RefreshToken string `json:"refresh_token"`
+	ExpiresAt    int64  `json:"expires_at"`
+	BoseSecret   string `json:"bose_secret,omitempty"`
+	// SiteID is written into the AmazonSecret credential envelope. Its origin is
+	// unconfirmed (may be a static Bose partner ID or a per-user Music API value).
+	SiteID string `json:"site_id,omitempty"`
+}
+
+// Service manages Amazon OAuth flow and token lifecycle.
+type Service struct {
+	clientID     string
+	clientSecret string
+	redirectURI  string
+	dataDir      string
+	mu           sync.RWMutex
+	accounts     map[string]*Account
+
+	// Overridable URLs for testing
+	tokenURL   string
+	profileURL string
+}
+
+// NewAmazonService creates a new Service and loads any persisted accounts.
+func NewAmazonService(clientID, clientSecret, redirectURI, dataDir string) *Service {
+	return &Service{
+		clientID:     clientID,
+		clientSecret: clientSecret,
+		redirectURI:  redirectURI,
+		dataDir:      dataDir,
+		accounts:     make(map[string]*Account),
+		tokenURL:     AmazonTokenURL,
+		profileURL:   AmazonProfileURL,
+	}
+}
+
+// Load loads persisted accounts from disk.
+func (s *Service) Load() error {
+	return s.load()
+}
+
+// SetEndpoints allows overriding default Amazon API endpoints (for testing).
+func (s *Service) SetEndpoints(tokenURL, profileURL string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.tokenURL = tokenURL
+	s.profileURL = profileURL
+}
+
+// BuildAuthorizeURL constructs the LWA OAuth authorization URL.
+func (s *Service) BuildAuthorizeURL(state string) string {
+	params := url.Values{
+		"client_id":     {s.clientID},
+		"response_type": {"code"},
+		"redirect_uri":  {s.redirectURI},
+		"scope":         {AmazonScopes},
+	}
+	if state != "" {
+		params.Set("state", state)
+	}
+
+	return AmazonAuthorizeURL + "?" + params.Encode()
+}
+
+// ExchangeCodeAndStore exchanges an authorization code for tokens,
+// fetches the user profile, and stores the account.
+func (s *Service) ExchangeCodeAndStore(code string) error {
+	tokenResp, err := s.exchangeCode(code)
+	if err != nil {
+		return fmt.Errorf("token exchange: %w", err)
+	}
+
+	accessToken, _ := tokenResp["access_token"].(string)
+	refreshToken, _ := tokenResp["refresh_token"].(string)
+
+	expiresIn, _ := tokenResp["expires_in"].(float64)
+	if expiresIn == 0 {
+		expiresIn = 3600
+	}
+
+	profile, err := s.getUserProfile(accessToken)
+	if err != nil {
+		return fmt.Errorf("fetch profile: %w", err)
+	}
+
+	// LWA profile uses "user_id" and "name" (not "id" and "display_name" like Spotify).
+	userID, _ := profile["user_id"].(string)
+	displayName, _ := profile["name"].(string)
+	email, _ := profile["email"].(string)
+
+	boseSecret := s.generateBoseSecret()
+
+	account := &Account{
+		UserID:       userID,
+		DisplayName:  displayName,
+		Email:        email,
+		AccessToken:  accessToken,
+		RefreshToken: refreshToken,
+		ExpiresAt:    time.Now().Unix() + int64(expiresIn),
+		BoseSecret:   boseSecret,
+	}
+
+	s.mu.Lock()
+	s.accounts[userID] = account
+	s.mu.Unlock()
+
+	if err := s.save(); err != nil {
+		return fmt.Errorf("save accounts: %w", err)
+	}
+
+	log.Printf("[Amazon] Account linked: %s (%s)", displayName, userID)
+
+	return nil
+}
+
+// exchangeCode exchanges an authorization code for tokens.
+// Amazon LWA requires client_id and client_secret as POST body fields,
+// not as HTTP Basic Auth (unlike Spotify).
+func (s *Service) exchangeCode(code string) (map[string]interface{}, error) {
+	data := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {s.redirectURI},
+		"client_id":     {s.clientID},
+		"client_secret": {s.clientSecret},
+	}
+
+	req, err := http.NewRequest(http.MethodPost, s.tokenURL, strings.NewReader(data.Encode()))
+	if err != nil {
+		return nil, err
+	}
+
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("token request: %w", err)
+	}
+
+	defer func() {
+		_ = resp.Body.Close()
+	}()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("token exchange failed (%d): %s", resp.StatusCode, string(body))
+	}
+
+	var result map[string]interface{}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("parse response: %w", err)
+	}
+
+	return result, nil
+}
+
+func (s *Service) getUserProfile(accessToken string) (map[string]interface{}, error) {
+	req, err := http.NewRequest(http.MethodGet, s.profileURL, nil)
+	if err != nil {
+		return nil, err
+	}
+
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("profile request: %w", err)
+	}
+
+	defer func() {
+		_ = resp.Body.Close()
+	}()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("profile fetch failed (%d): %s", resp.StatusCode, string(body))
+	}
+
+	var result map[string]interface{}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("parse profile: %w", err)
+	}
+
+	return result, nil
+}
+
+// RefreshAccessToken refreshes the access token for the given account.
+// Amazon LWA requires client credentials as POST body fields.
+func (s *Service) RefreshAccessToken(account *Account) error {
+	data := url.Values{
+		"grant_type":    {"refresh_token"},
+		"refresh_token": {account.RefreshToken},
+		"client_id":     {s.clientID},
+		"client_secret": {s.clientSecret},
+	}
+
+	req, err := http.NewRequest(http.MethodPost, s.tokenURL, strings.NewReader(data.Encode()))
+	if err != nil {
+		return err
+	}
+
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("refresh request: %w", err)
+	}
+
+	defer func() {
+		_ = resp.Body.Close()
+	}()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("token refresh failed (%d): %s", resp.StatusCode, string(body))
+	}
+
+	var result map[string]interface{}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return fmt.Errorf("parse response: %w", err)
+	}
+
+	s.mu.Lock()
+	account.AccessToken, _ = result["access_token"].(string)
+
+	expiresIn, _ := result["expires_in"].(float64)
+	if expiresIn == 0 {
+		expiresIn = 3600
+	}
+
+	account.ExpiresAt = time.Now().Unix() + int64(expiresIn)
+	if newRefresh, ok := result["refresh_token"].(string); ok && newRefresh != "" {
+		account.RefreshToken = newRefresh
+	}
+	s.mu.Unlock()
+
+	if err := s.save(); err != nil {
+		return fmt.Errorf("save accounts: %w", err)
+	}
+
+	return nil
+}
+
+// GetFreshToken returns a valid access token and username, refreshing if needed.
+func (s *Service) GetFreshToken() (accessToken, username string, err error) {
+	s.mu.RLock()
+
+	if len(s.accounts) == 0 {
+		s.mu.RUnlock()
+		return "", "", fmt.Errorf("no Amazon accounts linked")
+	}
+
+	var account *Account
+	for _, a := range s.accounts {
+		account = a
+		break
+	}
+
+	s.mu.RUnlock()
+
+	// Check if token needs refresh (expired or within 60s of expiry)
+	if account.ExpiresAt < time.Now().Unix()+60 {
+		if err := s.RefreshAccessToken(account); err != nil {
+			return "", "", fmt.Errorf("refresh token: %w", err)
+		}
+	}
+
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return account.AccessToken, account.UserID, nil
+}
+
+// GetAccounts returns a copy of all accounts with tokens stripped for API responses.
+func (s *Service) GetAccounts() []Account {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	result := make([]Account, 0, len(s.accounts))
+	for _, a := range s.accounts {
+		result = append(result, Account{
+			UserID:      a.UserID,
+			DisplayName: a.DisplayName,
+			Email:       a.Email,
+			ExpiresAt:   a.ExpiresAt,
+			BoseSecret:  a.BoseSecret,
+			// AccessToken and RefreshToken deliberately omitted
+		})
+	}
+
+	return result
+}
+
+// GetAccountBySecret retrieves an Amazon account by its Bose surrogate secret.
+func (s *Service) GetAccountBySecret(secret string) (*Account, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	for _, a := range s.accounts {
+		if a.BoseSecret == secret {
+			return a, true
+		}
+	}
+
+	return nil, false
+}
+
+// GetAllAccounts returns all accounts including tokens. Used internally by
+// bridgeAmazonToMarge to build the AmazonSecret credential envelope.
+func (s *Service) GetAllAccounts() []*Account {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	result := make([]*Account, 0, len(s.accounts))
+	for _, a := range s.accounts {
+		result = append(result, a)
+	}
+
+	return result
+}
+
+// GetAccountByRefreshToken retrieves an Amazon account by its current refresh token.
+// Used by the token handler because the speaker sends back the actual LWA refresh token
+// (extracted from the AmazonSecret JSON in Sources.xml), not a surrogate.
+func (s *Service) GetAccountByRefreshToken(refreshToken string) (*Account, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	for _, a := range s.accounts {
+		if a.RefreshToken == refreshToken {
+			return a, true
+		}
+	}
+
+	return nil, false
+}
+
+func (s *Service) generateBoseSecret() string {
+	prefix := "ba-"
+
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		return fmt.Sprintf("%s%d", prefix, time.Now().UnixNano())
+	}
+
+	return prefix + hex.EncodeToString(b)
+}
+
+// save persists accounts to disk as JSON.
+func (s *Service) save() error {
+	s.mu.RLock()
+
+	data := make(map[string]*Account, len(s.accounts))
+	for k, v := range s.accounts {
+		data[k] = v
+	}
+
+	s.mu.RUnlock()
+
+	dir := filepath.Join(s.dataDir, "amazon")
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return fmt.Errorf("create directory: %w", err)
+	}
+
+	jsonData, err := json.MarshalIndent(data, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshal accounts: %w", err)
+	}
+
+	path := filepath.Join(dir, "accounts.json")
+	if err := os.WriteFile(path, jsonData, 0600); err != nil {
+		return fmt.Errorf("write file: %w", err)
+	}
+
+	return nil
+}
+
+// load reads persisted accounts from disk.
+func (s *Service) load() error {
+	path := filepath.Join(s.dataDir, "amazon", "accounts.json")
+
+	jsonData, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil // No accounts file yet, not an error
+		}
+
+		return fmt.Errorf("read file: %w", err)
+	}
+
+	var accounts map[string]*Account
+	if err := json.Unmarshal(jsonData, &accounts); err != nil {
+		return fmt.Errorf("unmarshal accounts: %w", err)
+	}
+
+	s.mu.Lock()
+	s.accounts = accounts
+	s.mu.Unlock()
+
+	log.Printf("[Amazon] Loaded %d account(s)", len(accounts))
+
+	return nil
+}

pkg/service/amazon/service_test.go

@@ -0,0 +1,366 @@
+package amazon
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestBuildAuthorizeURL(t *testing.T) {
+	svc := NewAmazonService("test-client-id", "test-secret", "ueberboese-login://amazon", t.TempDir())
+
+	state := "test-state"
+	gotURL := svc.BuildAuthorizeURL(state)
+
+	if !strings.Contains(gotURL, "client_id=test-client-id") {
+		t.Errorf("URL should contain client_id, got: %s", gotURL)
+	}
+	if !strings.Contains(gotURL, "redirect_uri=") {
+		t.Errorf("URL should contain redirect_uri, got: %s", gotURL)
+	}
+	if !strings.Contains(gotURL, "scope=") {
+		t.Errorf("URL should contain scope, got: %s", gotURL)
+	}
+	if !strings.Contains(gotURL, "response_type=code") {
+		t.Errorf("URL should contain response_type=code, got: %s", gotURL)
+	}
+	if !strings.Contains(gotURL, "state=test-state") {
+		t.Errorf("URL should contain state=test-state, got: %s", gotURL)
+	}
+	if !strings.HasPrefix(gotURL, AmazonAuthorizeURL) {
+		t.Errorf("URL should start with %s, got: %s", AmazonAuthorizeURL, gotURL)
+	}
+}
+
+func TestGetAccountsStripsTokens(t *testing.T) {
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", t.TempDir())
+
+	svc.mu.Lock()
+	svc.accounts["amzn1.account.EXAMPLE"] = &Account{
+		UserID:       "amzn1.account.EXAMPLE",
+		DisplayName:  "Test User",
+		Email:        "test@example.com",
+		AccessToken:  "secret-access-token",
+		RefreshToken: "secret-refresh-token",
+		ExpiresAt:    time.Now().Add(1 * time.Hour).Unix(),
+	}
+	svc.mu.Unlock()
+
+	accounts := svc.GetAccounts()
+
+	if len(accounts) != 1 {
+		t.Fatalf("expected 1 account, got %d", len(accounts))
+	}
+
+	if accounts[0].AccessToken != "" {
+		t.Errorf("AccessToken should be stripped, got: %s", accounts[0].AccessToken)
+	}
+	if accounts[0].RefreshToken != "" {
+		t.Errorf("RefreshToken should be stripped, got: %s", accounts[0].RefreshToken)
+	}
+	if accounts[0].UserID != "amzn1.account.EXAMPLE" {
+		t.Errorf("UserID should be preserved, got: %s", accounts[0].UserID)
+	}
+	if accounts[0].DisplayName != "Test User" {
+		t.Errorf("DisplayName should be preserved, got: %s", accounts[0].DisplayName)
+	}
+}
+
+func TestExchangeCodeAndStore(t *testing.T) {
+	// Mock token endpoint — Amazon uses POST body credentials, not Basic Auth.
+	tokenServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseForm(); err != nil {
+			t.Fatal(err)
+		}
+
+		switch r.Form.Get("grant_type") {
+		case "authorization_code":
+			if r.Form.Get("code") != "test-auth-code" {
+				t.Errorf("expected code=test-auth-code, got %s", r.Form.Get("code"))
+			}
+
+			// Amazon uses POST body credentials, not HTTP Basic Auth.
+			if r.Form.Get("client_id") != "cid" {
+				t.Errorf("expected client_id=cid in POST body, got %q", r.Form.Get("client_id"))
+			}
+			if r.Form.Get("client_secret") != "csecret" {
+				t.Errorf("expected client_secret=csecret in POST body, got %q", r.Form.Get("client_secret"))
+			}
+			_, _, hasBasicAuth := r.BasicAuth()
+			if hasBasicAuth {
+				t.Error("Amazon token endpoint must NOT use HTTP Basic Auth")
+			}
+
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(map[string]interface{}{
+				"access_token":  "new-at",
+				"refresh_token": "new-rt",
+				"expires_in":    3600,
+			})
+		default:
+			t.Errorf("unexpected grant_type: %s", r.Form.Get("grant_type"))
+			http.Error(w, "bad request", 400)
+		}
+	}))
+	defer tokenServer.Close()
+
+	// Mock profile endpoint — LWA returns "user_id" and "name" (not "id" / "display_name").
+	profileServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		auth := r.Header.Get("Authorization")
+		if auth != "Bearer new-at" {
+			t.Errorf("expected Bearer new-at, got %s", auth)
+		}
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"user_id": "amzn1.account.TESTUSER123",
+			"name":    "Amazon User",
+			"email":   "user@amazon.com",
+		})
+	}))
+	defer profileServer.Close()
+
+	dir := t.TempDir()
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", dir)
+	svc.SetEndpoints(tokenServer.URL, profileServer.URL)
+
+	err := svc.ExchangeCodeAndStore("test-auth-code")
+	if err != nil {
+		t.Fatalf("ExchangeCodeAndStore failed: %v", err)
+	}
+
+	svc.mu.RLock()
+	account, ok := svc.accounts["amzn1.account.TESTUSER123"]
+	svc.mu.RUnlock()
+
+	if !ok {
+		t.Fatal("account not found after exchange")
+	}
+	if account.DisplayName != "Amazon User" {
+		t.Errorf("expected Amazon User, got %s", account.DisplayName)
+	}
+	if account.Email != "user@amazon.com" {
+		t.Errorf("expected user@amazon.com, got %s", account.Email)
+	}
+	if account.AccessToken != "new-at" {
+		t.Errorf("expected new-at, got %s", account.AccessToken)
+	}
+	if account.RefreshToken != "new-rt" {
+		t.Errorf("expected new-rt, got %s", account.RefreshToken)
+	}
+
+	// Verify saved to disk under amazon/ (not spotify/).
+	accountsFile := filepath.Join(dir, "amazon", "accounts.json")
+	data, err := os.ReadFile(accountsFile)
+	if err != nil {
+		t.Fatalf("failed to read accounts file: %v", err)
+	}
+	if !strings.Contains(string(data), "amzn1.account.TESTUSER123") {
+		t.Error("accounts file should contain the user ID")
+	}
+}
+
+func TestRefreshAccessToken(t *testing.T) {
+	tokenServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			t.Errorf("expected POST, got %s", r.Method)
+		}
+		if err := r.ParseForm(); err != nil {
+			t.Fatal(err)
+		}
+		if r.Form.Get("grant_type") != "refresh_token" {
+			t.Errorf("expected grant_type=refresh_token, got %s", r.Form.Get("grant_type"))
+		}
+		if r.Form.Get("refresh_token") != "my-refresh-token" {
+			t.Errorf("expected refresh_token=my-refresh-token, got %s", r.Form.Get("refresh_token"))
+		}
+
+		// Amazon uses POST body credentials.
+		if r.Form.Get("client_id") != "cid" {
+			t.Errorf("expected client_id=cid in POST body, got %q", r.Form.Get("client_id"))
+		}
+		if r.Form.Get("client_secret") != "csecret" {
+			t.Errorf("expected client_secret=csecret in POST body, got %q", r.Form.Get("client_secret"))
+		}
+		_, _, hasBasicAuth := r.BasicAuth()
+		if hasBasicAuth {
+			t.Error("Amazon token endpoint must NOT use HTTP Basic Auth")
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"access_token":  "new-access-token",
+			"token_type":    "Bearer",
+			"expires_in":    3600,
+			"refresh_token": "new-refresh-token",
+		})
+	}))
+	defer tokenServer.Close()
+
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", t.TempDir())
+	svc.tokenURL = tokenServer.URL
+
+	account := &Account{
+		UserID:       "amzn1.account.USER",
+		AccessToken:  "old-expired-token",
+		RefreshToken: "my-refresh-token",
+		ExpiresAt:    time.Now().Add(-1 * time.Hour).Unix(),
+	}
+
+	svc.mu.Lock()
+	svc.accounts[account.UserID] = account
+	svc.mu.Unlock()
+
+	if err := svc.RefreshAccessToken(account); err != nil {
+		t.Fatalf("RefreshAccessToken: %v", err)
+	}
+
+	if account.AccessToken != "new-access-token" {
+		t.Errorf("expected new-access-token, got %s", account.AccessToken)
+	}
+	if account.RefreshToken != "new-refresh-token" {
+		t.Errorf("expected new-refresh-token, got %s", account.RefreshToken)
+	}
+}
+
+func TestGetFreshTokenRefreshesExpired(t *testing.T) {
+	tokenServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseForm(); err != nil {
+			t.Fatal(err)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]interface{}{
+			"access_token":  "new-access-token",
+			"token_type":    "Bearer",
+			"expires_in":    3600,
+			"refresh_token": "new-refresh-token",
+		})
+	}))
+	defer tokenServer.Close()
+
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", t.TempDir())
+	svc.tokenURL = tokenServer.URL
+
+	svc.mu.Lock()
+	svc.accounts["amzn1.account.USER"] = &Account{
+		UserID:       "amzn1.account.USER",
+		AccessToken:  "old-expired-token",
+		RefreshToken: "my-refresh-token",
+		ExpiresAt:    time.Now().Add(-1 * time.Hour).Unix(),
+	}
+	svc.mu.Unlock()
+
+	accessToken, username, err := svc.GetFreshToken()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if accessToken != "new-access-token" {
+		t.Errorf("expected new-access-token, got %s", accessToken)
+	}
+	if username != "amzn1.account.USER" {
+		t.Errorf("expected amzn1.account.USER, got %s", username)
+	}
+
+	svc.mu.RLock()
+	account := svc.accounts["amzn1.account.USER"]
+	svc.mu.RUnlock()
+
+	if account.RefreshToken != "new-refresh-token" {
+		t.Errorf("refresh token should be updated, got %s", account.RefreshToken)
+	}
+}
+
+func TestGetFreshTokenNoAccounts(t *testing.T) {
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", t.TempDir())
+
+	_, _, err := svc.GetFreshToken()
+	if err == nil {
+		t.Error("expected error when no accounts exist")
+	}
+}
+
+func TestGetFreshTokenNotExpired(t *testing.T) {
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", t.TempDir())
+
+	svc.mu.Lock()
+	svc.accounts["amzn1.account.USER"] = &Account{
+		UserID:       "amzn1.account.USER",
+		AccessToken:  "valid-token",
+		RefreshToken: "rt",
+		ExpiresAt:    time.Now().Add(1 * time.Hour).Unix(),
+	}
+	svc.mu.Unlock()
+
+	token, username, err := svc.GetFreshToken()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if token != "valid-token" {
+		t.Errorf("expected valid-token, got %s", token)
+	}
+	if username != "amzn1.account.USER" {
+		t.Errorf("expected amzn1.account.USER, got %s", username)
+	}
+}
+
+func TestSaveAndLoad(t *testing.T) {
+	dir := t.TempDir()
+
+	svc := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", dir)
+	svc.mu.Lock()
+	svc.accounts["amzn1.account.USER1"] = &Account{
+		UserID:       "amzn1.account.USER1",
+		DisplayName:  "Test User",
+		Email:        "test@example.com",
+		AccessToken:  "at",
+		RefreshToken: "rt",
+		ExpiresAt:    1234567890,
+	}
+	svc.accounts["amzn1.account.USER2"] = &Account{
+		UserID:       "amzn1.account.USER2",
+		DisplayName:  "User Two",
+		Email:        "two@example.com",
+		AccessToken:  "at2",
+		RefreshToken: "rt2",
+		ExpiresAt:    9876543210,
+	}
+	svc.mu.Unlock()
+
+	if err := svc.save(); err != nil {
+		t.Fatalf("save failed: %v", err)
+	}
+
+	accountsFile := filepath.Join(dir, "amazon", "accounts.json")
+	if _, err := os.Stat(accountsFile); os.IsNotExist(err) {
+		t.Fatal("amazon/accounts.json was not created")
+	}
+
+	svc2 := NewAmazonService("cid", "csecret", "ueberboese-login://amazon", dir)
+	if err := svc2.Load(); err != nil {
+		t.Fatalf("load failed: %v", err)
+	}
+
+	svc2.mu.RLock()
+	defer svc2.mu.RUnlock()
+
+	if len(svc2.accounts) != 2 {
+		t.Fatalf("expected 2 accounts after load, got %d", len(svc2.accounts))
+	}
+
+	u1, ok := svc2.accounts["amzn1.account.USER1"]
+	if !ok {
+		t.Fatal("USER1 not found after load")
+	}
+	if u1.DisplayName != "Test User" {
+		t.Errorf("expected Test User, got %s", u1.DisplayName)
+	}
+	if u1.AccessToken != "at" {
+		t.Errorf("expected at, got %s", u1.AccessToken)
+	}
+	if u1.ExpiresAt != 1234567890 {
+		t.Errorf("expected ExpiresAt 1234567890, got %d", u1.ExpiresAt)
+	}
+}

pkg/service/amazon/zeroconf.go

@@ -0,0 +1,11 @@
+package amazon
+
+import "github.com/gesellix/bose-soundtouch/pkg/service/zeroconf"
+
+// PushAmazonCredentials pushes Amazon Music credentials to a speaker using the
+// ZeroConf DH key exchange protocol. Falls back to simplified token push if
+// the speaker does not support DH (older firmware).
+// zcBaseURL is the base URL of the ZeroConf endpoint, e.g. "http://192.168.1.10:8200/zc".
+func PushAmazonCredentials(zcBaseURL, username, accessToken string) error {
+	return zeroconf.PushCredentials(zcBaseURL, username, accessToken)
+}

pkg/service/amazon/zeroconf_test.go

@@ -0,0 +1,176 @@
+package amazon
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/zeroconf"
+)
+
+func TestPushAmazonCredentials_FullRoundTrip(t *testing.T) {
+	speakerPrivate, speakerPublicBytes, err := zeroconf.GenerateDHKeyPair()
+	if err != nil {
+		t.Fatalf("speaker keygen: %v", err)
+	}
+
+	type received struct {
+		username string
+		authData string
+		authType int
+	}
+	var got received
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Query().Get("action") {
+		case "getInfo":
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(map[string]interface{}{
+				"status":       101,
+				"statusString": "OK",
+				"publicKey":    base64.StdEncoding.EncodeToString(speakerPublicBytes),
+			})
+
+		case "addUser":
+			if err := r.ParseForm(); err != nil {
+				http.Error(w, err.Error(), http.StatusBadRequest)
+				return
+			}
+
+			blobBytes, err := base64.StdEncoding.DecodeString(r.FormValue("blob"))
+			if err != nil {
+				http.Error(w, "bad blob base64: "+err.Error(), http.StatusBadRequest)
+				return
+			}
+			clientKeyBytes, err := base64.StdEncoding.DecodeString(r.FormValue("clientKey"))
+			if err != nil {
+				http.Error(w, "bad clientKey base64: "+err.Error(), http.StatusBadRequest)
+				return
+			}
+
+			shared := zeroconf.ComputeSharedSecret(speakerPrivate, clientKeyBytes)
+			encKey, macKey := zeroconf.DeriveKeys(shared)
+
+			plaintext, err := zeroconf.DecryptBlob(encKey, macKey, blobBytes)
+			if err != nil {
+				http.Error(w, "decrypt failed: "+err.Error(), http.StatusBadRequest)
+				return
+			}
+
+			// Minimal protobuf parse: field 1 = username, field 4 = authData, field 5 = authType
+			i := 0
+			for i < len(plaintext) {
+				tag := plaintext[i]
+				i++
+				fieldNum := tag >> 3
+				wireType := tag & 0x07
+				switch wireType {
+				case 0:
+					val, n := readVarint(plaintext[i:])
+					i += n
+					if fieldNum == 5 {
+						got.authType = int(val)
+					}
+				case 2:
+					length, n := readVarint(plaintext[i:])
+					i += n
+					value := plaintext[i : i+int(length)]
+					i += int(length)
+					switch fieldNum {
+					case 1:
+						got.username = string(value)
+					case 4:
+						got.authData = string(value)
+					}
+				default:
+					http.Error(w, "unexpected wire type", http.StatusBadRequest)
+					return
+				}
+			}
+			w.WriteHeader(http.StatusOK)
+
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+
+	const wantUsername = "amazonuser@example.com"
+	const wantToken = "Atza|access-token"
+
+	if err := PushAmazonCredentials(srv.URL+"/zc", wantUsername, wantToken); err != nil {
+		t.Fatalf("PushAmazonCredentials: %v", err)
+	}
+
+	if got.username != wantUsername {
+		t.Errorf("username = %q, want %q", got.username, wantUsername)
+	}
+	if got.authData != wantToken {
+		t.Errorf("authData = %q, want %q", got.authData, wantToken)
+	}
+	if uint64(got.authType) != zeroconf.AuthTypeOAuthToken {
+		t.Errorf("authType = %d, want %d (AuthTypeOAuthToken)", got.authType, zeroconf.AuthTypeOAuthToken)
+	}
+}
+
+func TestPushAmazonCredentials_FallbackOnGetInfoFailure(t *testing.T) {
+	var receivedForm map[string]string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Query().Get("action") {
+		case "getInfo":
+			http.Error(w, "not supported", http.StatusNotFound)
+		case "addUser":
+			if err := r.ParseForm(); err != nil {
+				http.Error(w, err.Error(), http.StatusBadRequest)
+				return
+			}
+			receivedForm = map[string]string{
+				"userName":  r.FormValue("userName"),
+				"blob":      r.FormValue("blob"),
+				"clientKey": r.FormValue("clientKey"),
+				"tokenType": r.FormValue("tokenType"),
+			}
+			w.WriteHeader(http.StatusOK)
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+
+	const wantUsername = "amazonuser@example.com"
+	const wantToken = "Atza|raw-access-token"
+
+	if err := PushAmazonCredentials(srv.URL+"/zc", wantUsername, wantToken); err != nil {
+		t.Fatalf("PushAmazonCredentials: %v", err)
+	}
+
+	if receivedForm == nil {
+		t.Fatal("addUser was never called")
+	}
+	if receivedForm["userName"] != wantUsername {
+		t.Errorf("userName = %q, want %q", receivedForm["userName"], wantUsername)
+	}
+	if receivedForm["blob"] != wantToken {
+		t.Errorf("blob = %q, want raw token %q", receivedForm["blob"], wantToken)
+	}
+	if receivedForm["tokenType"] != "accesstoken" {
+		t.Errorf("tokenType = %q, want %q", receivedForm["tokenType"], "accesstoken")
+	}
+	if receivedForm["clientKey"] != "" {
+		t.Errorf("clientKey = %q, want empty for simplified fallback", receivedForm["clientKey"])
+	}
+}
+
+func readVarint(data []byte) (uint64, int) {
+	var val uint64
+	for i, b := range data {
+		val |= uint64(b&0x7f) << (7 * uint(i))
+		if b&0x80 == 0 {
+			return val, i + 1
+		}
+	}
+	return 0, len(data)
+}

pkg/service/bmx/bmx.go

@@ -42,6 +42,41 @@ func isTuneInURL(rawURL string) bool {
 	return allowedTuneInHosts[u.Hostname()]
 }
 
+// isTuneInOpmlURI returns true when the URL's host is opml.radiotime.com,
+// used to select the OPML/ashx parser over the JSON API parser.
+func isTuneInOpmlURI(rawURL string) bool {
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return false
+	}
+
+	return strings.EqualFold(u.Hostname(), "opml.radiotime.com")
+}
+
+// tuneInRenderJSONURI returns the URL with render=json set as a query parameter,
+// replacing any existing render value instead of appending a duplicate.
+func tuneInRenderJSONURI(rawURL string) string {
+	if rawURL == "" {
+		return ""
+	}
+
+	u, err := url.Parse(rawURL)
+	if err != nil {
+		return rawURL
+	}
+
+	q := u.Query()
+	q.Set("render", "json")
+	u.RawQuery = q.Encode()
+
+	return u.String()
+}
+
+// tuneInSearchURI returns the TuneIn search API URL with the query properly URL-encoded.
+func tuneInSearchURI(query string) string {
+	return TuneInSearchAPI + url.QueryEscape(query)
+}
+
 func fetchJSON(fetchURL string) (map[string]interface{}, error) {
 	if !isTuneInURL(fetchURL) {
 		return nil, fmt.Errorf("URL not in allowed list: %s", fetchURL)
@@ -110,7 +145,7 @@ func TuneInNavigate(encodedURI string, subsection *int) (*models.BmxNavResponse,
 		err      error
 	)
 
-	if strings.HasPrefix(tuneInURI, "http://opml.radiotime.com/") {
+	if isTuneInOpmlURI(tuneInURI) {
 		sections, err = tuneInSectionsAshx(tuneInURI, subsection)
 	} else {
 		sections, err = tuneInSectionsJSONAPI(tuneInURI, subsection)
@@ -291,7 +326,7 @@ func tuneInNavigateLink(item map[string]interface{}) models.BmxNavItem {
 	text, _ := item["text"].(string)
 	subtext, _ := item["subtext"].(string)
 
-	encURL := base64.URLEncoding.EncodeToString([]byte(rawURL + "&render=json"))
+	encURL := base64.URLEncoding.EncodeToString([]byte(tuneInRenderJSONURI(rawURL)))
 
 	return models.BmxNavItem{
 		Links:    &models.Links{BmxNavigate: &models.Link{Href: fmt.Sprintf("/v1/navigate/%s", encURL)}},
@@ -303,7 +338,7 @@ func tuneInNavigateLink(item map[string]interface{}) models.BmxNavItem {
 
 // TuneInSearch returns live search results from TuneIn for the given query.
 func TuneInSearch(query string) (*models.BmxNavResponse, error) {
-	tuneInURI := TuneInSearchAPI + url.QueryEscape(query)
+	tuneInURI := tuneInSearchURI(query)
 
 	templated := true
 	bmxSearchLink := &models.Link{
@@ -336,7 +371,7 @@ func TuneInSearch(query string) (*models.BmxNavResponse, error) {
 
 	return &models.BmxNavResponse{
 		Links: &models.Links{
-			Self:      &models.Link{Href: fmt.Sprintf("/v1/search?q=%s", query)},
+			Self:      &models.Link{Href: fmt.Sprintf("/v1/search?q=%s", url.QueryEscape(query))},
 			BmxSearch: bmxSearchLink,
 		},
 		BmxSections: sections,
@@ -353,7 +388,7 @@ func tuneInSearchSection(item map[string]interface{}, idx int, query, layout str
 	if pivotURL != "" {
 		href = fmt.Sprintf("/v1/navigate/%s", base64.URLEncoding.EncodeToString([]byte(pivotURL)))
 	} else {
-		encodedQuery := base64.URLEncoding.EncodeToString([]byte(TuneInSearchAPI + query))
+		encodedQuery := base64.URLEncoding.EncodeToString([]byte(tuneInSearchURI(query)))
 		href = fmt.Sprintf("/v1/navigate/sub/%d/%s", idx, encodedQuery)
 	}
 

pkg/service/bmx/bmx_test.go

@@ -3,9 +3,155 @@ package bmx
 import (
 	"encoding/base64"
 	"encoding/json"
+	"strings"
 	"testing"
 )
 
+func TestTuneInRenderJSONURI(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  string
+	}{
+		{
+			name:  "empty URL returns empty",
+			input: "",
+			want:  "",
+		},
+		{
+			name:  "URL with no query params gets render=json added",
+			input: "http://opml.radiotime.com/Browse.ashx",
+			want:  "http://opml.radiotime.com/Browse.ashx?render=json",
+		},
+		{
+			name:  "URL with other params gets render=json appended",
+			input: "http://opml.radiotime.com/Browse.ashx?c=news",
+			want:  "http://opml.radiotime.com/Browse.ashx?c=news&render=json",
+		},
+		{
+			name:  "URL already containing render=json is not duplicated",
+			input: "http://opml.radiotime.com/?render=json",
+			want:  "http://opml.radiotime.com/?render=json",
+		},
+		{
+			name:  "URL with render=xml gets render replaced with json",
+			input: "http://opml.radiotime.com/Browse.ashx?c=podcast&render=xml",
+			want:  "http://opml.radiotime.com/Browse.ashx?c=podcast&render=json",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := tuneInRenderJSONURI(tt.input)
+			if got != tt.want {
+				t.Errorf("tuneInRenderJSONURI(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsTuneInOpmlURI(t *testing.T) {
+	tests := []struct {
+		input string
+		want  bool
+	}{
+		{"http://opml.radiotime.com/Browse.ashx", true},
+		{"https://opml.radiotime.com/Browse.ashx", true},
+		{"http://opml.radiotime.com/?render=json", true},
+		{"http://api.radiotime.com/profiles?fulltextsearch=true", false},
+		{"http://example.com", false},
+		{"not-a-url", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := isTuneInOpmlURI(tt.input)
+			if got != tt.want {
+				t.Errorf("isTuneInOpmlURI(%q) = %v, want %v", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestTuneInSearchURI(t *testing.T) {
+	tests := []struct {
+		name  string
+		query string
+		check func(string) bool
+	}{
+		{
+			name:  "spaces are percent-encoded",
+			query: "radio paradise",
+			check: func(u string) bool { return !strings.Contains(u, " ") && strings.Contains(u, "radio+paradise") },
+		},
+		{
+			name:  "ampersand is encoded",
+			query: "news & talk",
+			check: func(u string) bool { return !strings.Contains(u, " ") && strings.Contains(u, "%26") },
+		},
+		{
+			name:  "plain query is appended to base URL",
+			query: "jazz",
+			check: func(u string) bool { return u == TuneInSearchAPI+"jazz" },
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := tuneInSearchURI(tt.query)
+			if !tt.check(got) {
+				t.Errorf("tuneInSearchURI(%q) = %q: check failed", tt.query, got)
+			}
+		})
+	}
+}
+
+func TestTuneInNavigateLinkEncodesRenderJSON(t *testing.T) {
+	item := map[string]interface{}{
+		"URL":     "http://opml.radiotime.com/Browse.ashx?c=news",
+		"text":    "News",
+		"subtext": "Latest",
+		"image":   "http://example.com/news.png",
+	}
+
+	result := tuneInNavigateLink(item)
+
+	href := result.Links.BmxNavigate.Href
+	encoded := strings.TrimPrefix(href, "/v1/navigate/")
+	decoded, err := base64.URLEncoding.DecodeString(encoded)
+	if err != nil {
+		t.Fatalf("failed to decode navigate href: %v", err)
+	}
+
+	got := string(decoded)
+	if !strings.Contains(got, "render=json") {
+		t.Errorf("navigate href %q missing render=json", got)
+	}
+	if strings.Count(got, "render=json") > 1 {
+		t.Errorf("navigate href %q has duplicate render=json", got)
+	}
+}
+
+func TestTuneInNavigateLinkNoDuplicateRenderJSON(t *testing.T) {
+	item := map[string]interface{}{
+		"URL": "http://opml.radiotime.com/Browse.ashx?c=podcast&render=json",
+	}
+
+	result := tuneInNavigateLink(item)
+
+	href := result.Links.BmxNavigate.Href
+	encoded := strings.TrimPrefix(href, "/v1/navigate/")
+	decoded, err := base64.URLEncoding.DecodeString(encoded)
+	if err != nil {
+		t.Fatalf("failed to decode navigate href: %v", err)
+	}
+
+	got := string(decoded)
+	if strings.Count(got, "render=json") != 1 {
+		t.Errorf("navigate href %q should contain render=json exactly once", got)
+	}
+}
+
 func TestPlayCustomStream(t *testing.T) {
 	// Simple test for custom stream XML generation
 	dataObj := struct {

pkg/service/certmanager/certmanager.go

@@ -17,7 +17,8 @@ import (
 
 // CertificateManager handles CA and certificate generation.
 type CertificateManager struct {
-	CertsDir string
+	CertsDir   string
+	CommonName string // CN for generated server certs; defaults to "localhost" if empty
 }
 
 // NewCertificateManager creates a new CertificateManager.
@@ -137,7 +138,7 @@ func (cm *CertificateManager) GetServerTLSConfig(domains []string) (*tls.Config,
 
 // GenerateCA generates a new CA certificate and key.
 func (cm *CertificateManager) GenerateCA() error {
-	priv, err := rsa.GenerateKey(rand.Reader, 4096)
+	priv, err := rsa.GenerateKey(rand.Reader, 2048)
 	if err != nil {
 		return err
 	}
@@ -255,11 +256,16 @@ func (cm *CertificateManager) GenerateCertificate(domains []string) ([]byte, []b
 		}
 	}
 
+	cn := cm.CommonName
+	if cn == "" {
+		cn = "localhost"
+	}
+
 	template := x509.Certificate{
 		SerialNumber: serialNumber,
 		Subject: pkix.Name{
 			Organization: []string{"AfterTouch"},
-			CommonName:   domains[0],
+			CommonName:   cn,
 		},
 		NotBefore:   notBefore,
 		NotAfter:    notAfter,

pkg/service/certmanager/certmanager_test.go

@@ -16,6 +16,7 @@ func TestCertificateManager(t *testing.T) {
 	defer os.RemoveAll(tempDir)
 
 	cm := NewCertificateManager(filepath.Join(tempDir, "certs"))
+	cm.CommonName = "test.local"
 
 	// Test CA generation
 	if err := cm.EnsureCA(); err != nil {
@@ -67,8 +68,8 @@ func TestCertificateManager(t *testing.T) {
 		t.Fatalf("Failed to parse certificate: %v", err)
 	}
 
-	if cert.Subject.CommonName != domains[0] {
-		t.Errorf("Expected CommonName %s, got %s", domains[0], cert.Subject.CommonName)
+	if cert.Subject.CommonName != cm.CommonName {
+		t.Errorf("Expected CommonName %s, got %s", cm.CommonName, cert.Subject.CommonName)
 	}
 
 	// Check DNS names

pkg/service/constants/constants.go

@@ -265,6 +265,22 @@ func GetProviderName(providerID string) string {
 	return providerID
 }
 
+// GetProviderLabel returns the user-friendly label for a provider ID (e.g. "TuneIn Radio", "Spotify").
+func GetProviderLabel(providerID string) string {
+	id, err := strconv.Atoi(providerID)
+	if err != nil {
+		return ""
+	}
+
+	for _, p := range StaticProviders {
+		if p.ID == id {
+			return p.Label
+		}
+	}
+
+	return ""
+}
+
 // GetProviders returns a list of known source provider names.
 func GetProviders() []string {
 	var providers []string
@@ -283,11 +299,10 @@ const (
 	RecentsFile    = "Recents.xml"
 	SourcesFile    = "Sources.xml"
 
-	SpeakerHTTPPort            = 8090
-	SpeakerDeviceInfoPath      = "/info"
-	SpeakerRecentsPath         = "/recents"
-	SpeakerPresetsPath         = "/presets"
-	SpeakerSourcesFileLocation = "/mnt/nv/BoseApp-Persistence/1/Sources.xml"
+	// Speaker-protocol constants (HTTP port, paths, on-device file
+	// locations) moved to github.com/gesellix/bose-soundtouch/pkg/speaker
+	// so the client library and CLI can share them without depending on
+	// the service package.
 
 	// DateStr is the hardcoded date used in many Bose XML responses
 	DateStr = "2012-09-19T12:43:00.000+00:00"

pkg/service/constants/constants_test.go

@@ -9,10 +9,6 @@ func TestConstants(t *testing.T) {
 		t.Error("DateStr should not be empty")
 	}
 
-	if SpeakerHTTPPort != 8090 {
-		t.Errorf("Expected SpeakerHTTPPort 8090, got %d", SpeakerHTTPPort)
-	}
-
 	if len(GetProviders()) == 0 {
 		t.Error("Providers should not be empty")
 	}

pkg/service/datastore/datastore.go

@@ -8,8 +8,10 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"encoding/xml"
+	"errors"
 	"fmt"
 	"io"
+	"math/rand"
 	"os"
 	"path/filepath"
 	"sort"
@@ -22,6 +24,9 @@ import (
 	"github.com/gesellix/bose-soundtouch/pkg/service/constants"
 )
 
+// ErrGroupNotFound is returned when no group is found for a given device.
+var ErrGroupNotFound = errors.New("group not found")
+
 func exists(path string) bool {
 	_, err := os.Stat(path)
 	return err == nil
@@ -64,6 +69,15 @@ type DataStore struct {
 	// baseDir is the absolute, normalized base directory used for path safety checks.
 	baseDir string
 
+	// rootMu guards lazy initialisation of root.
+	rootMu sync.Mutex
+	// root is an os.Root anchored at baseDir. All filesystem operations within
+	// the datastore go through it, so ".." or absolute paths in
+	// caller-supplied components cannot escape the root — the Go runtime
+	// enforces containment regardless of what safeJoin's output looks like.
+	// Lazily opened so NewDataStore stays a pure constructor.
+	root *os.Root
+
 	eventMutex     sync.RWMutex
 	deviceEvents   map[string][]models.DeviceEvent
 	idMutex        sync.RWMutex
@@ -108,10 +122,31 @@ func NewDataStore(dataDir string) *DataStore {
 }
 
 // safeJoin joins the given path elements to the datastore baseDir and ensures
-// that the resulting absolute path stays within baseDir. If the check fails,
-// baseDir is returned to prevent directory traversal.
+// that the resulting absolute path stays within baseDir. If any element would
+// escape baseDir (absolute path, "..", or — on Windows — a drive/colon), the
+// function falls back to baseDir to prevent directory traversal.
+//
+// The validation up-front uses filepath.IsLocal, which CodeQL recognises as a
+// path-traversal sanitiser, so taint analysis at call sites that subsequently
+// hand the result to os.ReadFile / os.Open / os.Remove etc. propagates safely.
+// The post-join prefix check below stays as belt-and-suspenders for any
+// unusual platform behaviour IsLocal does not cover.
 func (ds *DataStore) safeJoin(elem ...string) string {
-	// Join the base directory with the provided elements.
+	for _, e := range elem {
+		if e == "" {
+			// filepath.Join silently skips empty elements, but IsLocal
+			// returns false for "" — treat empties as a no-op.
+			continue
+		}
+
+		if !filepath.IsLocal(e) {
+			// Element is absolute, contains ".." or a reserved Windows
+			// component. Refuse to join.
+			return ds.baseDir
+		}
+	}
+
+	// Join the base directory with the (now sanitised) elements.
 	path := filepath.Join(append([]string{ds.baseDir}, elem...)...)
 
 	absPath, err := filepath.Abs(path)
@@ -126,7 +161,8 @@ func (ds *DataStore) safeJoin(elem ...string) string {
 		return absPath
 	}
 
-	// Ensure the resolved path is within the base directory.
+	// Belt-and-suspenders: ensure the resolved path is within the base
+	// directory even if filepath.IsLocal somehow misjudged a component.
 	baseWithSep := base
 	if !strings.HasSuffix(baseWithSep, string(os.PathSeparator)) {
 		baseWithSep += string(os.PathSeparator)
@@ -145,6 +181,277 @@ func (ds *DataStore) SafeJoin(elem ...string) string {
 	return ds.safeJoin(elem...)
 }
 
+// getRoot returns the lazily-opened *os.Root anchored at baseDir. The root is
+// created on first call after MkdirAll-ing baseDir; subsequent calls return
+// the cached handle. Filesystem operations performed via the returned root
+// cannot escape baseDir even if the relative path passed to them is malicious.
+func (ds *DataStore) getRoot() (*os.Root, error) {
+	ds.rootMu.Lock()
+	defer ds.rootMu.Unlock()
+
+	if ds.root != nil {
+		return ds.root, nil
+	}
+
+	if ds.baseDir == "" {
+		return nil, fmt.Errorf("datastore: baseDir not configured")
+	}
+
+	if err := os.MkdirAll(ds.baseDir, 0755); err != nil {
+		return nil, fmt.Errorf("datastore: ensure baseDir %s: %w", ds.baseDir, err)
+	}
+
+	r, err := os.OpenRoot(ds.baseDir)
+	if err != nil {
+		return nil, fmt.Errorf("datastore: open root at %s: %w", ds.baseDir, err)
+	}
+
+	ds.root = r
+
+	return r, nil
+}
+
+// Close releases any open filesystem handles held by the datastore. Safe to
+// call on a never-used DataStore.
+func (ds *DataStore) Close() error {
+	ds.rootMu.Lock()
+	defer ds.rootMu.Unlock()
+
+	if ds.root == nil {
+		return nil
+	}
+
+	err := ds.root.Close()
+	ds.root = nil
+
+	return err
+}
+
+// rootRel converts a path produced by safeJoin (or by filepath.Join over
+// ds.DataDir) into the form expected by *os.Root methods — relative to
+// baseDir, no leading separator. Tolerates both absolute paths and paths
+// whose root is the relative ds.DataDir.
+//
+// Returns "." for baseDir itself.
+func (ds *DataStore) rootRel(absPath string) (string, error) {
+	// If the input is relative, absolutise so the comparison with baseDir
+	// works regardless of how DataDir was originally configured.
+	if !filepath.IsAbs(absPath) {
+		a, err := filepath.Abs(absPath)
+		if err != nil {
+			return "", fmt.Errorf("datastore: absolutise %s: %w", absPath, err)
+		}
+
+		absPath = a
+	}
+
+	if absPath == ds.baseDir {
+		return ".", nil
+	}
+
+	rel, err := filepath.Rel(ds.baseDir, absPath)
+	if err != nil {
+		return "", fmt.Errorf("datastore: %s is outside baseDir: %w", absPath, err)
+	}
+
+	if rel == "." || rel == "" {
+		return ".", nil
+	}
+
+	if strings.HasPrefix(rel, "..") {
+		return "", fmt.Errorf("datastore: %s is outside baseDir", absPath)
+	}
+
+	return rel, nil
+}
+
+// rootStat is the os.Stat equivalent for a path under baseDir.
+func (ds *DataStore) rootStat(absPath string) (os.FileInfo, error) {
+	r, err := ds.getRoot()
+	if err != nil {
+		return nil, err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return nil, err
+	}
+
+	return r.Stat(rel)
+}
+
+// rootReadFile is the os.ReadFile equivalent.
+func (ds *DataStore) rootReadFile(absPath string) ([]byte, error) {
+	r, err := ds.getRoot()
+	if err != nil {
+		return nil, err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return nil, err
+	}
+
+	return r.ReadFile(rel)
+}
+
+// rootWriteFile is the os.WriteFile equivalent.
+func (ds *DataStore) rootWriteFile(absPath string, data []byte, perm os.FileMode) error {
+	r, err := ds.getRoot()
+	if err != nil {
+		return err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return err
+	}
+
+	return r.WriteFile(rel, data, perm)
+}
+
+// rootMkdirAll is the os.MkdirAll equivalent.
+func (ds *DataStore) rootMkdirAll(absPath string, perm os.FileMode) error {
+	r, err := ds.getRoot()
+	if err != nil {
+		return err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return err
+	}
+
+	if rel == "." {
+		return nil
+	}
+
+	return r.MkdirAll(rel, perm)
+}
+
+// rootRemove is the os.Remove equivalent.
+func (ds *DataStore) rootRemove(absPath string) error {
+	r, err := ds.getRoot()
+	if err != nil {
+		return err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return err
+	}
+
+	return r.Remove(rel)
+}
+
+// rootRemoveAll is the os.RemoveAll equivalent.
+func (ds *DataStore) rootRemoveAll(absPath string) error {
+	r, err := ds.getRoot()
+	if err != nil {
+		return err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return err
+	}
+
+	return r.RemoveAll(rel)
+}
+
+// rootRename is the os.Rename equivalent. Both paths must be under baseDir.
+func (ds *DataStore) rootRename(oldAbs, newAbs string) error {
+	r, err := ds.getRoot()
+	if err != nil {
+		return err
+	}
+
+	oldRel, err := ds.rootRel(oldAbs)
+	if err != nil {
+		return err
+	}
+
+	newRel, err := ds.rootRel(newAbs)
+	if err != nil {
+		return err
+	}
+
+	return r.Rename(oldRel, newRel)
+}
+
+// rootReadDir lists the entries in absPath. Equivalent to os.ReadDir,
+// including the same alphabetical-by-name sort order — *os.File.ReadDir(-1)
+// returns entries in directory order, but callers (and existing tests)
+// depend on the sorted contract that os.ReadDir documents.
+func (ds *DataStore) rootReadDir(absPath string) ([]os.DirEntry, error) {
+	r, err := ds.getRoot()
+	if err != nil {
+		return nil, err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return nil, err
+	}
+
+	f, err := r.Open(rel)
+	if err != nil {
+		return nil, err
+	}
+
+	defer func() { _ = f.Close() }()
+
+	entries, err := f.ReadDir(-1)
+	if err != nil {
+		return entries, err
+	}
+
+	sort.Slice(entries, func(i, j int) bool { return entries[i].Name() < entries[j].Name() })
+
+	return entries, nil
+}
+
+// rootExists is true when absPath exists under baseDir.
+func (ds *DataStore) rootExists(absPath string) bool {
+	_, err := ds.rootStat(absPath)
+	return err == nil
+}
+
+// ReadDirUnderBase lists the entries in absPath, which must resolve to a
+// directory under the datastore baseDir. Cross-package callers (marge,
+// handlers, …) use this instead of os.ReadDir so that the underlying
+// *os.Root sanitises the path against traversal.
+func (ds *DataStore) ReadDirUnderBase(absPath string) ([]os.DirEntry, error) {
+	return ds.rootReadDir(absPath)
+}
+
+// MkdirAllUnderBase creates a directory tree under baseDir.
+func (ds *DataStore) MkdirAllUnderBase(absPath string, perm os.FileMode) error {
+	return ds.rootMkdirAll(absPath, perm)
+}
+
+// WriteFileUnderBase atomically writes data to absPath, which must be under
+// baseDir.
+func (ds *DataStore) WriteFileUnderBase(absPath string, data []byte, perm os.FileMode) error {
+	return ds.rootWriteFile(absPath, data, perm)
+}
+
+// rootOpen is the os.Open equivalent for a path under baseDir. The caller
+// owns the returned *os.File and must Close it.
+func (ds *DataStore) rootOpen(absPath string) (*os.File, error) {
+	r, err := ds.getRoot()
+	if err != nil {
+		return nil, err
+	}
+
+	rel, err := ds.rootRel(absPath)
+	if err != nil {
+		return nil, err
+	}
+
+	return r.Open(rel)
+}
+
 // ListAccounts returns a list of all account IDs (directories in the data root).
 func (ds *DataStore) ListAccounts() ([]string, error) {
 	ds.fileMutex.RLock()
@@ -152,11 +459,11 @@ func (ds *DataStore) ListAccounts() ([]string, error) {
 
 	// Account data is stored in 'accounts' subdirectory within the data root.
 	accountsDir := filepath.Join(ds.baseDir, "accounts")
-	if !exists(accountsDir) {
+	if !ds.rootExists(accountsDir) {
 		return []string{"default"}, nil
 	}
 
-	entries, err := os.ReadDir(accountsDir)
+	entries, err := ds.rootReadDir(accountsDir)
 	if err != nil {
 		return nil, err
 	}
@@ -194,7 +501,7 @@ func (ds *DataStore) AccountDeviceDir(account, device string) string {
 	// First, check if the device directory exists directly with the given deviceID
 	// This prioritizes MAC-based deviceIDs over legacy mappings
 	directPath := ds.safeJoin("accounts", account, constants.DevicesDir, device)
-	if _, err := os.Stat(directPath); err == nil {
+	if _, err := ds.rootStat(directPath); err == nil {
 		// Directory exists, use the direct deviceID (preferred for MAC-based IDs)
 		return directPath
 	}
@@ -214,7 +521,7 @@ func (ds *DataStore) AccountDeviceDir(account, device string) string {
 	if ok {
 		// Use the mapped device only if it exists and the direct path doesn't
 		mappedPath := ds.safeJoin("accounts", account, constants.DevicesDir, mappedDevice)
-		if _, err := os.Stat(mappedPath); err == nil {
+		if _, err := ds.rootStat(mappedPath); err == nil {
 			return mappedPath
 		}
 	}
@@ -236,7 +543,7 @@ func (ds *DataStore) getDeviceInfoNoLock(account, device string) (*models.Servic
 	path := ds.AccountDeviceDir(account, device)
 	deviceInfoPath := filepath.Join(path, constants.DeviceInfoFile)
 
-	data, err := os.ReadFile(deviceInfoPath)
+	data, err := ds.rootReadFile(deviceInfoPath)
 	if err != nil {
 		return nil, err
 	}
@@ -528,7 +835,7 @@ func (ds *DataStore) GetPresets(account, device string) ([]models.ServicePreset,
 
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.PresetsFile)
 
-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return []models.ServicePreset{}, nil
@@ -592,7 +899,7 @@ func (ds *DataStore) SavePresets(account, device string, presets []models.Servic
 	defer ds.fileMutex.Unlock()
 
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.PresetsFile)
-	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+	if err := ds.rootMkdirAll(filepath.Dir(path), 0755); err != nil {
 		return err
 	}
 
@@ -656,11 +963,11 @@ func (ds *DataStore) atomicWriteFile(filename string, data []byte) error {
 	perm := os.FileMode(0644)
 
 	tempFile := filename + ".tmp"
-	if err := os.WriteFile(tempFile, data, perm); err != nil {
+	if err := ds.rootWriteFile(tempFile, data, perm); err != nil {
 		return err
 	}
 
-	return os.Rename(tempFile, filename)
+	return ds.rootRename(tempFile, filename)
 }
 
 // GetRecents returns the list of recently played items for the specified account and device.
@@ -670,7 +977,7 @@ func (ds *DataStore) GetRecents(account, device string) ([]models.ServiceRecent,
 
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.RecentsFile)
 
-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return []models.ServiceRecent{}, nil
@@ -765,7 +1072,7 @@ func (ds *DataStore) SaveRecents(account, device string, recents []models.Servic
 	defer ds.fileMutex.Unlock()
 
 	dir := ds.AccountDeviceDir(account, device)
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return err
 	}
 
@@ -864,7 +1171,7 @@ func (ds *DataStore) SaveDeviceInfo(account, device string, info *models.Service
 	ds.mergeWithExistingDeviceInfo(account, device, info)
 
 	dir := ds.AccountDeviceDir(account, device)
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return err
 	}
 
@@ -1026,7 +1333,7 @@ func (ds *DataStore) SaveAccountInfo(accountID string, info *models.ServiceAccou
 	}
 
 	dir := ds.AccountDir(accountID)
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return err
 	}
 
@@ -1048,11 +1355,11 @@ func (ds *DataStore) GetAccountInfo(accountID string) (*models.ServiceAccountInf
 
 	// Try account root (canonical location)
 	path := filepath.Join(ds.AccountDir(accountID), "account.json")
-	if !exists(path) {
+	if !ds.rootExists(path) {
 		return &models.ServiceAccountInfo{AccountID: accountID, IsPlaceholder: true}, nil
 	}
 
-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		return nil, err
 	}
@@ -1072,7 +1379,7 @@ func (ds *DataStore) RemoveDevice(account, device string) error {
 
 	dir := ds.AccountDeviceDir(account, device)
 
-	return os.RemoveAll(dir)
+	return ds.rootRemoveAll(dir)
 }
 
 // RemoveDeviceDir is an alias for RemoveDevice for backwards compatibility.
@@ -1103,7 +1410,7 @@ func (ds *DataStore) collectDeducedIDs(account, device string) map[string]string
 
 	// Check recents and presets to find source IDs for provider IDs 2, 9, 11, 25
 	for _, filename := range []string{constants.RecentsFile, constants.PresetsFile} {
-		fileContent, err := os.ReadFile(filepath.Join(ds.AccountDeviceDir(account, device), filename))
+		fileContent, err := ds.rootReadFile(filepath.Join(ds.AccountDeviceDir(account, device), filename))
 		if err != nil {
 			continue
 		}
@@ -1209,7 +1516,7 @@ func (ds *DataStore) GetConfiguredSources(account, device string) ([]models.Conf
 
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
 
-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
 			sources := ds.getDefaultSources()
@@ -1249,6 +1556,17 @@ func (ds *DataStore) GetConfiguredSources(account, device string) ([]models.Conf
 	}
 
 	sources := make([]models.ConfiguredSource, len(sourcesWrap.Sources))
+	defaults := ds.getDefaultSources()
+
+	// Pre-claim IDs already explicitly set in the file so the canonical fill
+	// below doesn't reuse them when multiple entries share a SourceKey.Type.
+	claimedIDs := make(map[string]bool, len(sourcesWrap.Sources))
+	for i := range sourcesWrap.Sources {
+		if id := sourcesWrap.Sources[i].ID; id != "" {
+			claimedIDs[id] = true
+		}
+	}
+
 	for i := range sourcesWrap.Sources {
 		ps := &sourcesWrap.Sources[i]
 		s := &sources[i]
@@ -1288,11 +1606,9 @@ func (ds *DataStore) GetConfiguredSources(account, device string) ([]models.Conf
 			s.SourceKeyAccount = s.SourceKey.Account
 		}
 
-		// Ensure Type is populated from SourceKey if missing
-		if s.Type == "" && s.SourceKey.Type != "" {
-			s.Type = s.SourceKey.Type
-		}
+		applyCanonicalDefaults(s, defaults, claimedIDs)
 
+		// Last-resort ID for unknown providers.
 		if s.ID == "" {
 			s.ID = strconv.Itoa(2000001 + i)
 		}
@@ -1301,13 +1617,58 @@ func (ds *DataStore) GetConfiguredSources(account, device string) ([]models.Conf
 	return sources, nil
 }
 
+// applyCanonicalDefaults fills missing canonical ID/Type/SourceProviderID for
+// known providers and repairs Type that was previously synthesized from
+// SourceKey.Type (e.g. "AUX") rather than the canonical value (e.g. "Audio").
+// Without this, the on-device Sources.xml — which carries only displayName +
+// sourceKey — would round-trip as id="2000001+i" type="<sourceKey.Type>" and
+// be rejected by the speaker as INVALID_SOURCE after migration.
+//
+// claimedIDs tracks which canonical IDs are already in use so that multiple
+// entries with the same SourceKey.Type don't collide on the same ID.
+func applyCanonicalDefaults(s *models.ConfiguredSource, defaults []models.ConfiguredSource, claimedIDs map[string]bool) {
+	def := findCanonicalSource(defaults, s.SourceKey.Type)
+	if def == nil {
+		return
+	}
+
+	if s.ID == "" && !claimedIDs[def.ID] {
+		s.ID = def.ID
+		claimedIDs[def.ID] = true
+	}
+
+	if s.Type == "" || s.Type == s.SourceKey.Type {
+		s.Type = def.Type
+	}
+
+	if s.SourceProviderID == "" {
+		s.SourceProviderID = def.SourceProviderID
+	}
+}
+
+// findCanonicalSource returns the default source matching the given
+// SourceKey.Type, or nil if it's not one of our known providers.
+func findCanonicalSource(defaults []models.ConfiguredSource, sourceKeyType string) *models.ConfiguredSource {
+	if sourceKeyType == "" {
+		return nil
+	}
+
+	for i := range defaults {
+		if defaults[i].SourceKey.Type == sourceKeyType {
+			return &defaults[i]
+		}
+	}
+
+	return nil
+}
+
 // SaveConfiguredSources saves the configured sources list for the specified account and device.
 func (ds *DataStore) SaveConfiguredSources(account, device string, sources []models.ConfiguredSource) error {
 	ds.fileMutex.Lock()
 	defer ds.fileMutex.Unlock()
 
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
-	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+	if err := ds.rootMkdirAll(filepath.Dir(path), 0755); err != nil {
 		return err
 	}
 
@@ -1330,6 +1691,25 @@ func (ds *DataStore) SaveConfiguredSources(account, device string, sources []mod
 		} `xml:"sourceKey"`
 	}
 
+	// Deduplicate by ID before saving; first occurrence wins to preserve established data
+	seen := make(map[string]bool)
+
+	deduped := make([]models.ConfiguredSource, 0, len(sources))
+	for i := range sources {
+		s := &sources[i]
+		if s.ID != "" {
+			if seen[s.ID] {
+				continue
+			}
+
+			seen[s.ID] = true
+		}
+
+		deduped = append(deduped, *s)
+	}
+
+	sources = deduped
+
 	// Ensure SourceKey is populated from legacy fields if necessary before saving
 	// and map to persistentSource to avoid custom MarshalXML for disk storage
 	persistSources := make([]persistentSource, len(sources))
@@ -1583,7 +1963,7 @@ func (ds *DataStore) Initialize() error {
 func (ds *DataStore) GetETagForPresets(account, device string) int64 {
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.PresetsFile)
 
-	info, err := os.Stat(path)
+	info, err := ds.rootStat(path)
 	if err != nil {
 		return 0
 	}
@@ -1591,11 +1971,19 @@ func (ds *DataStore) GetETagForPresets(account, device string) int64 {
 	return info.ModTime().UnixNano() / int64(time.Millisecond)
 }
 
+// HasConfiguredSources reports whether a Sources.xml file exists for the given account and device.
+func (ds *DataStore) HasConfiguredSources(account, device string) bool {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
+	_, err := ds.rootStat(path)
+
+	return err == nil
+}
+
 // GetETagForSources returns the ETag (modification time) for the sources file for a specific device.
 func (ds *DataStore) GetETagForSources(account, device string) int64 {
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
 
-	info, err := os.Stat(path)
+	info, err := ds.rootStat(path)
 	if err != nil {
 		return 0
 	}
@@ -1607,7 +1995,7 @@ func (ds *DataStore) GetETagForSources(account, device string) int64 {
 func (ds *DataStore) GetETagForRecents(account, device string) int64 {
 	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.RecentsFile)
 
-	info, err := os.Stat(path)
+	info, err := ds.rootStat(path)
 	if err != nil {
 		return 0
 	}
@@ -1615,34 +2003,32 @@ func (ds *DataStore) GetETagForRecents(account, device string) int64 {
 	return info.ModTime().UnixNano() / int64(time.Millisecond)
 }
 
-// contentHashForFiles returns a SHA-256 hex digest over the concatenated contents of the given file paths.
-func contentHashForFiles(paths ...string) string {
-	h := sha256.New()
-
-	for _, p := range paths {
-		f, err := os.Open(p)
-		if err != nil {
-			continue
-		}
-
-		_, _ = io.Copy(h, f)
-		_ = f.Close()
-	}
-
-	return hex.EncodeToString(h.Sum(nil))
-}
-
 // GetETagForAccount returns a content hash (SHA-256) over presets, sources, and recents for the account and device.
 // If device is empty, it hashes across all devices in the account.
+// The default sources fingerprint is always included so that newly added defaults (e.g. Amazon)
+// invalidate cached responses even when the stored Sources.xml has not changed.
 func (ds *DataStore) GetETagForAccount(account, device string) string {
+	h := sha256.New()
+
+	// Include the default sources fingerprint so mergeDefaultSources changes are visible.
+	defaults := ds.GetDefaultSources()
+	for i := range defaults {
+		_, _ = io.WriteString(h, defaults[i].ID+defaults[i].SourceKeyType+defaults[i].DisplayName)
+	}
+
 	if device != "" {
 		deviceDir := ds.AccountDeviceDir(account, device)
+		for _, name := range []string{constants.PresetsFile, constants.SourcesFile, constants.RecentsFile} {
+			f, err := ds.rootOpen(filepath.Join(deviceDir, name))
+			if err != nil {
+				continue
+			}
 
-		return contentHashForFiles(
-			filepath.Join(deviceDir, constants.PresetsFile),
-			filepath.Join(deviceDir, constants.SourcesFile),
-			filepath.Join(deviceDir, constants.RecentsFile),
-		)
+			_, _ = io.Copy(h, f)
+			_ = f.Close()
+		}
+
+		return hex.EncodeToString(h.Sum(nil))
 	}
 
 	devicesDir := ds.AccountDevicesDir(account)
@@ -1650,15 +2036,13 @@ func (ds *DataStore) GetETagForAccount(account, device string) string {
 	// Ignore error: missing directory is treated as no devices, producing a
 	// stable non-empty hash rather than "" which would false-match an absent
 	// If-None-Match header and return 304 on the first request.
-	entries, _ := os.ReadDir(devicesDir)
-
-	h := sha256.New()
+	entries, _ := ds.rootReadDir(devicesDir)
 
 	for _, entry := range entries {
 		if entry.IsDir() {
 			deviceDir := ds.AccountDeviceDir(account, entry.Name())
 			for _, name := range []string{constants.PresetsFile, constants.SourcesFile, constants.RecentsFile} {
-				f, err := os.Open(filepath.Join(deviceDir, name))
+				f, err := ds.rootOpen(filepath.Join(deviceDir, name))
 				if err != nil {
 					continue
 				}
@@ -1690,6 +2074,34 @@ type Settings struct {
 	PreferredSource     string         `json:"preferred_source,omitempty"`
 	InternalPaths       []string       `json:"internal_paths,omitempty"`
 	Shortcuts           map[string]int `json:"shortcuts,omitempty"`
+	SpotifyClientID     string         `json:"spotify_client_id,omitempty"`
+	SpotifyClientSecret string         `json:"spotify_client_secret,omitempty"`
+	SpotifyRedirectURI  string         `json:"spotify_redirect_uri,omitempty"`
+	AmazonClientID      string         `json:"amazon_client_id,omitempty"`
+	AmazonClientSecret  string         `json:"amazon_client_secret,omitempty"`
+	AmazonRedirectURI   string         `json:"amazon_redirect_uri,omitempty"`
+
+	// AllowInsecureUpstreamTLS, when true, disables TLS certificate verification
+	// for the upstream Bose-cloud proxy and mirror traffic. The default (false)
+	// keeps verification on; opt in only when the upstream certificate chain is
+	// broken (post end-of-service) and a temporary unblock is required.
+	AllowInsecureUpstreamTLS bool `json:"allow_insecure_upstream_tls,omitempty"`
+
+	// TrustForwardedHeaders enables proxy-aware client IP resolution: when the
+	// immediate TCP peer is one of the TrustedProxyCIDRs, the X-Real-IP /
+	// X-Forwarded-For / True-Client-IP headers are honoured and replace
+	// r.RemoteAddr. Required when the service is fronted by nginx, Caddy, or
+	// any other reverse proxy. Default false — direct LAN deployments must
+	// not enable this, otherwise a malicious LAN-resident client could spoof
+	// its source IP via these headers.
+	TrustForwardedHeaders bool `json:"trust_forwarded_headers,omitempty"`
+
+	// TrustedProxyCIDRs is the list of CIDR blocks whose immediate TCP peers
+	// are allowed to set X-Forwarded-* headers when TrustForwardedHeaders is
+	// true. Defaults to loopback (127.0.0.0/8 and ::1/128) — i.e. only a
+	// reverse proxy on the same host. Override only if the proxy lives on a
+	// different host within a known-good private subnet.
+	TrustedProxyCIDRs []string `json:"trusted_proxy_cidrs,omitempty"`
 }
 
 // GetSettings retrieves the global service settings.
@@ -1699,11 +2111,11 @@ func (ds *DataStore) GetSettings() (Settings, error) {
 	}
 
 	path := filepath.Join(ds.DataDir, "settings.json")
-	if !exists(path) {
+	if !ds.rootExists(path) {
 		return Settings{}, nil
 	}
 
-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		return Settings{}, err
 	}
@@ -1722,7 +2134,7 @@ func (ds *DataStore) SaveSettings(settings Settings) error {
 		return nil
 	}
 
-	if err := os.MkdirAll(ds.DataDir, 0755); err != nil {
+	if err := ds.rootMkdirAll(ds.DataDir, 0755); err != nil {
 		return fmt.Errorf("failed to create data directory: %w", err)
 	}
 
@@ -1739,7 +2151,7 @@ func (ds *DataStore) SaveSettings(settings Settings) error {
 // SaveUsageStats saves usage statistics to the datastore.
 func (ds *DataStore) SaveUsageStats(stats models.UsageStats) error {
 	dir := filepath.Join(ds.DataDir, "stats", "usage")
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return err
 	}
 
@@ -1757,7 +2169,7 @@ func (ds *DataStore) SaveUsageStats(stats models.UsageStats) error {
 // SaveErrorStats saves error statistics to the datastore.
 func (ds *DataStore) SaveErrorStats(stats models.ErrorStats) error {
 	dir := filepath.Join(ds.DataDir, "stats", "error")
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return err
 	}
 
@@ -1823,7 +2235,7 @@ func (ds *DataStore) SaveDNSDiscoveries(discoveries []DNSDiscoveryEntry) error {
 	}
 
 	dir := filepath.Join(ds.DataDir, "dns")
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return fmt.Errorf("failed to create dns directory: %w", err)
 	}
 
@@ -1849,11 +2261,11 @@ func (ds *DataStore) LoadDNSDiscoveries() ([]DNSDiscoveryEntry, error) {
 	}
 
 	path := filepath.Join(ds.DataDir, "dns", "discoveries.json")
-	if !exists(path) {
+	if !ds.rootExists(path) {
 		return []DNSDiscoveryEntry{}, nil
 	}
 
-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		return nil, err
 	}
@@ -1873,9 +2285,164 @@ func (ds *DataStore) ClearDNSDiscoveries() error {
 	}
 
 	path := filepath.Join(ds.DataDir, "dns", "discoveries.json")
-	if !exists(path) {
+	if !ds.rootExists(path) {
 		return nil
 	}
 
-	return os.Remove(path)
+	return ds.rootRemove(path)
+}
+
+// groupFilePath returns the on-disk path for a group file.
+func (ds *DataStore) groupFilePath(account, groupID string) string {
+	return filepath.Join(ds.AccountDevicesDir(account), "Group_"+groupID+".xml")
+}
+
+// generateGroupID returns a unique 7-digit group ID that has no existing file.
+func (ds *DataStore) generateGroupID(account string) string {
+	for {
+		id := fmt.Sprintf("%07d", rand.Int63n(10_000_000)) //nolint:gosec
+		if !ds.rootExists(ds.groupFilePath(account, id)) {
+			return id
+		}
+	}
+}
+
+// GetGroupForDevice returns the group containing the given device, or nil if ungrouped.
+func (ds *DataStore) GetGroupForDevice(account, deviceID string) (*models.Group, error) {
+	ds.fileMutex.RLock()
+	defer ds.fileMutex.RUnlock()
+
+	dir := ds.AccountDevicesDir(account)
+
+	entries, err := ds.rootReadDir(dir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, ErrGroupNotFound
+		}
+
+		return nil, err
+	}
+
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasPrefix(e.Name(), "Group_") || !strings.HasSuffix(e.Name(), ".xml") {
+			continue
+		}
+
+		data, readErr := ds.rootReadFile(filepath.Join(dir, e.Name()))
+		if readErr != nil {
+			continue
+		}
+
+		var g models.Group
+		if unmarshalErr := xml.Unmarshal(data, &g); unmarshalErr != nil {
+			continue
+		}
+
+		for _, role := range g.Roles.Roles {
+			if role.DeviceID == deviceID {
+				return &g, nil
+			}
+		}
+	}
+
+	return nil, ErrGroupNotFound
+}
+
+// AddGroup saves a new group to disk and returns its generated ID.
+func (ds *DataStore) AddGroup(account string, group *models.Group) (string, error) {
+	ds.fileMutex.Lock()
+	defer ds.fileMutex.Unlock()
+
+	dir := ds.AccountDevicesDir(account)
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
+		return "", err
+	}
+
+	id := ds.generateGroupID(account)
+	group.ID = id
+
+	data, err := xml.MarshalIndent(group, "", "    ")
+	if err != nil {
+		return "", err
+	}
+
+	return id, ds.atomicWriteFile(ds.groupFilePath(account, id), append([]byte(xml.Header), data...))
+}
+
+// ModifyGroup updates the name of an existing group and returns the updated group.
+func (ds *DataStore) ModifyGroup(account, groupID, newName string) (*models.Group, error) {
+	ds.fileMutex.Lock()
+	defer ds.fileMutex.Unlock()
+
+	path := ds.groupFilePath(account, groupID)
+
+	data, err := ds.rootReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("group %s not found", groupID)
+		}
+
+		return nil, err
+	}
+
+	var g models.Group
+	if xmlErr := xml.Unmarshal(data, &g); xmlErr != nil {
+		return nil, xmlErr
+	}
+
+	g.Name = newName
+
+	updated, err := xml.MarshalIndent(&g, "", "    ")
+	if err != nil {
+		return nil, err
+	}
+
+	if err := ds.atomicWriteFile(path, append([]byte(xml.Header), updated...)); err != nil {
+		return nil, err
+	}
+
+	return &g, nil
+}
+
+// DeleteGroup removes a group from disk.
+func (ds *DataStore) DeleteGroup(account, groupID string) error {
+	ds.fileMutex.Lock()
+	defer ds.fileMutex.Unlock()
+
+	err := ds.rootRemove(ds.groupFilePath(account, groupID))
+	if os.IsNotExist(err) {
+		return fmt.Errorf("group %s not found", groupID)
+	}
+
+	return err
+}
+
+// SaveTuneInFavorite records a TuneIn station as favorited by creating a marker file.
+// File presence indicates the station is a favorite; no content is stored.
+func (ds *DataStore) SaveTuneInFavorite(stationID string) error {
+	if ds == nil || ds.DataDir == "" || stationID == "" {
+		return nil
+	}
+
+	dir := ds.safeJoin("tunein", "favorites")
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
+		return err
+	}
+
+	return ds.rootWriteFile(ds.safeJoin("tunein", "favorites", stationID), nil, 0644)
+}
+
+// DeleteTuneInFavorite removes a previously saved TuneIn favorite marker file.
+// Returns nil if the station was not favorited.
+func (ds *DataStore) DeleteTuneInFavorite(stationID string) error {
+	if ds == nil || ds.DataDir == "" || stationID == "" {
+		return nil
+	}
+
+	err := ds.rootRemove(ds.safeJoin("tunein", "favorites", stationID))
+	if os.IsNotExist(err) {
+		return nil
+	}
+
+	return err
 }

pkg/service/datastore/sources_regression_test.go

@@ -98,3 +98,155 @@ func TestSaveSources_Format(t *testing.T) {
 		t.Errorf("Sources.xml should not contain <sourceSettings> tag")
 	}
 }
+
+// TestGetConfiguredSources_MinimalAuxEntryNormalized covers the migration case from
+// issue #195: the device's on-disk Sources.xml carries only displayName + sourceKey
+// for AUX (no id, no type). When read back, the AUX entry must surface as the
+// canonical id="10001" type="Audio" sourceproviderid="9", not synthesized values.
+func TestGetConfiguredSources_MinimalAuxEntryNormalized(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "st-sources-min-aux-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = os.RemoveAll(tempDir) }()
+
+	ds := NewDataStore(tempDir)
+	account := "1234567"
+	device := "001122334455"
+
+	deviceDir := ds.AccountDeviceDir(account, device)
+	if err := os.MkdirAll(deviceDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	minimalSourcesXML := `<sources>
+    <source displayName="AUX IN" secret="">
+        <sourceKey type="AUX" account="AUX" />
+    </source>
+</sources>`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Sources.xml"), []byte(minimalSourcesXML), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	sources, err := ds.GetConfiguredSources(account, device)
+	if err != nil {
+		t.Fatalf("GetConfiguredSources failed: %v", err)
+	}
+
+	if len(sources) != 1 {
+		t.Fatalf("expected 1 source, got %d", len(sources))
+	}
+
+	s := sources[0]
+	if s.ID != "10001" {
+		t.Errorf("expected canonical AUX id 10001, got %q", s.ID)
+	}
+	if s.Type != "Audio" {
+		t.Errorf("expected canonical AUX type 'Audio', got %q", s.Type)
+	}
+	if s.SourceKey.Type != "AUX" || s.SourceKey.Account != "AUX" {
+		t.Errorf("expected sourceKey type/account AUX/AUX, got %q/%q", s.SourceKey.Type, s.SourceKey.Account)
+	}
+}
+
+// TestGetConfiguredSources_DuplicateProviderUniqueIDs ensures that when a file
+// contains multiple entries for the same SourceKey.Type (e.g. two AUX entries),
+// only one gets the canonical ID; the rest fall back to synthesized IDs so they
+// don't collide.
+func TestGetConfiguredSources_DuplicateProviderUniqueIDs(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "st-sources-dup-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = os.RemoveAll(tempDir) }()
+
+	ds := NewDataStore(tempDir)
+	account := "1234567"
+	device := "001122334455"
+
+	deviceDir := ds.AccountDeviceDir(account, device)
+	if err := os.MkdirAll(deviceDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	dupXML := `<sources>
+    <source displayName="AUX IN" secret="">
+        <sourceKey type="AUX" account="AUX" />
+    </source>
+    <source displayName="AUX 2" secret="">
+        <sourceKey type="AUX" account="AUX" />
+    </source>
+</sources>`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Sources.xml"), []byte(dupXML), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	sources, err := ds.GetConfiguredSources(account, device)
+	if err != nil {
+		t.Fatalf("GetConfiguredSources failed: %v", err)
+	}
+
+	if len(sources) != 2 {
+		t.Fatalf("expected 2 sources, got %d", len(sources))
+	}
+
+	if sources[0].ID == sources[1].ID {
+		t.Errorf("duplicate AUX entries must not share an ID, got %q for both", sources[0].ID)
+	}
+
+	// Both should still have Type repaired to the canonical "Audio".
+	for i, s := range sources {
+		if s.Type != "Audio" {
+			t.Errorf("source %d: expected Type 'Audio', got %q", i, s.Type)
+		}
+	}
+}
+
+// TestGetConfiguredSources_PoisonedAuxEntryRepaired covers the case where a previous
+// version of the datastore already persisted bad synthesized values (type="AUX",
+// id="2000001"). On read, those values must be repaired to the canonical defaults.
+func TestGetConfiguredSources_PoisonedAuxEntryRepaired(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "st-sources-poisoned-aux-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = os.RemoveAll(tempDir) }()
+
+	ds := NewDataStore(tempDir)
+	account := "1234567"
+	device := "001122334455"
+
+	deviceDir := ds.AccountDeviceDir(account, device)
+	if err := os.MkdirAll(deviceDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	poisonedXML := `<sources>
+    <source displayName="AUX IN" id="2000001" secret="" secretType="" type="AUX">
+        <credential type=""></credential>
+        <sourceKey type="AUX" account="AUX"></sourceKey>
+    </source>
+</sources>`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Sources.xml"), []byte(poisonedXML), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	sources, err := ds.GetConfiguredSources(account, device)
+	if err != nil {
+		t.Fatalf("GetConfiguredSources failed: %v", err)
+	}
+
+	if len(sources) != 1 {
+		t.Fatalf("expected 1 source, got %d", len(sources))
+	}
+
+	s := sources[0]
+	if s.Type != "Audio" {
+		t.Errorf("expected Type to be repaired to 'Audio', got %q", s.Type)
+	}
+	// ID repair is intentionally not aggressive — only empty IDs are filled
+	// from canonical defaults to avoid breaking references in recents/presets.
+	if s.ID != "2000001" {
+		t.Errorf("expected ID preserved as 2000001, got %q", s.ID)
+	}
+}

pkg/service/datastore/upnp_integration_test.go

@@ -381,10 +381,28 @@ func TestMACMappingPerformance(t *testing.T) {
 
 	t.Logf("  Total mappings stored: %d (includes normalized versions)", totalMappings)
 
+	// Update is a pure in-memory map write; keep an absolute cap as a backstop
+	// against catastrophic regressions in that hot path.
 	if updateDuration > time.Millisecond*100 {
 		t.Errorf("Update performance too slow: %v", updateDuration)
 	}
-	if lookupDuration > time.Millisecond*70 {
-		t.Errorf("Lookup performance too slow: %v", lookupDuration)
+
+	// Lookup does up to two Stat() syscalls and is dominated by filesystem
+	// latency, which varies wildly on shared CI runners. Compare it to the
+	// in-memory update cost instead of an absolute bound: the ratio captures
+	// "lookup got disproportionately slower" (an algorithmic regression in the
+	// lookup path) while staying stable under uniform host slowdown.
+	if updateDuration <= 0 {
+		t.Fatalf("Update duration is non-positive (%v); cannot compute lookup/update ratio", updateDuration)
+	}
+
+	const maxLookupUpdateRatio = 30.0
+
+	ratio := float64(lookupDuration) / float64(updateDuration)
+	t.Logf("  Lookup/Update ratio: %.2fx (threshold %.0fx)", ratio, maxLookupUpdateRatio)
+
+	if ratio > maxLookupUpdateRatio {
+		t.Errorf("Lookup is %.2fx slower than update (>%.0fx threshold) — possible regression in AccountDeviceDir lookup path. Update=%v Lookup=%v",
+			ratio, maxLookupUpdateRatio, updateDuration, lookupDuration)
 	}
 }