feat(setup): tag service-side IP resolve with a sentinel + observe SSH cost

The migration-summary preflight always emitted a "resolved from service, not from device" ❌ row whenever the target was a hostname — even when SSH was available and could have answered authoritatively. Two problems compounded: the summary builder passed `nil` for the SSH client (skipping the device-side ping), and resolveIP's service-side fallback returned a bare fmt.Errorf the caller couldn't distinguish from a real failure. Changes: - ErrResolvedFromServiceOnly sentinel; service-side fallback wraps it with fmt.Errorf("%w: ...") so callers can errors.Is()-check. Apply-path callers that pass a real SSH client keep getting the same error shape they always did. - populatePlannedNetworkConfig now takes an SSHClient. GetMigrationSummary opens one when probe.SSHOK is true and passes it through, so the summary's resolve call uses the same device-side authority the apply paths use. Skipping the dial when SSH is known dead keeps a stale handshake-timeout from burning the preflight budget. - MigrationSummary gains ResolveIPSource ("device" / "service") and ResolveIPDurationMS so we can observe the SSH-ping cost in the wild. The historical comment claimed 2-5 s on firmware-27 devices — we now have data instead of a guess. - CLI renderer prints the new source + timing line, and only renders the ❌ ResolveIPError row for hard failures (both SSH ping AND service DNS failed). - Two regression tests cover the sentinel-tagging contract and the device-success-returns-nil-error path. Related to https://github.com/gesellix/Bose-SoundTouch/issues/282. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
test(setup): regression for telnet-only migration detection
2026-08-24 14:47:23 +00:00 · 2026-05-16 15:16:53 +02:00 · 2026-05-16 14:46:04 +02:00 · 2026-05-16 14:46:04 +02:00 · 2026-05-16 14:46:04 +02:00 · 2026-05-16 12:14:18 +02:00
211 changed files with 29951 additions and 3618 deletions
@@ -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 -trimpath -ldflags="-s -w" -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,10 +248,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"

@@ -266,14 +303,28 @@ 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 }}
@@ -281,20 +332,22 @@ jobs:

      - name: Extract metadata (tags, labels) for soundtouch-service
        id: meta-service
-        uses: docker/metadata-action@v6
+        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 soundtouch-service Docker image
-        uses: docker/build-push-action@v7
+        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' }}
+          push: ${{ steps.push-check.outputs.should-push == 'true' }}
          tags: ${{ steps.meta-service.outputs.tags }}
          labels: ${{ steps.meta-service.outputs.labels }}
          cache-from: type=gha
@@ -302,25 +355,64 @@ jobs:

      - name: Extract metadata (tags, labels) for soundtouch-web
        id: meta-web
-        uses: docker/metadata-action@v6
+        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
+            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@v7
+        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: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          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
@@ -355,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 {
@@ -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
@@ -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
@@ -206,7 +206,7 @@ jobs:
          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: |
@@ -223,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
@@ -280,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: |
@@ -291,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/
@@ -305,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
@@ -468,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 }}"
@@ -494,13 +494,13 @@ 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: |
@@ -521,13 +521,13 @@ 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 }}
@@ -535,7 +535,7 @@ jobs:

      - name: Extract metadata (tags, labels) for soundtouch-service
        id: meta-service
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
@@ -544,7 +544,7 @@ jobs:
            type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}

      - name: Build and push soundtouch-service Docker image
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          target: soundtouch-service
@@ -557,7 +557,7 @@ jobs:

      - name: Extract metadata (tags, labels) for soundtouch-web
        id: meta-web
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
        with:
          images: ghcr.io/${{ github.repository }}-web
          tags: |
@@ -566,7 +566,7 @@ jobs:
            type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}

      - name: Build and push soundtouch-web Docker image
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
        with:
          context: .
          target: soundtouch-web
@@ -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
@@ -16,12 +16,14 @@ dist/
 /soundtouch-cli
 /soundtouch-service
 /soundtouch-web
+/dummy-speaker
 /example-mdns
 /example-upnp
 /example-unified
 /mdns-scanner
 /websocket-demo
 /main
+/screenshots

 # Environment configuration
 .env
@@ -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
@@ -169,7 +169,9 @@ test-http-client:
 		/workdir/get_api_versions.http \
 		/workdir/post_musicprovider_is_eligible.http \
 		/workdir/get_full_account.http \
+		/workdir/create_group.http \
 		/workdir/get_group.http \
+		/workdir/rename_device.http \
 		/workdir/unregister_device.http \
 		--report; \
 	EXIT_CODE=$$?; \
@@ -336,6 +338,10 @@ 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"
@@ -356,6 +362,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"
@@ -20,6 +20,8 @@ See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVI

 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**
@@ -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
+}
@@ -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)
@@ -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)
@@ -0,0 +1,315 @@
+package main
+
+import (
+	"fmt"
+	"net"
+	"sync"
+
+	"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 by POSTing /addGroup to both speakers in
+// parallel. LEFT is the master. Addressing each speaker directly (instead of
+// only the master and letting it propagate via marge) sidesteps the
+// inter-device round-trip that surfaced as client timeouts in #252.
+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},
+			},
+		},
+		// SenderIPAddress is intentionally omitted on the base request.
+		// propagateAddGroup adds it to the slave's copy only — see comment there.
+	}
+
+	leftClient, err := clientForHost(c, leftIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client for LEFT: %v", err))
+		return err
+	}
+
+	rightClient, err := clientForHost(c, rightIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client for RIGHT: %v", err))
+		return err
+	}
+
+	leftOut, rightOut := propagateAddGroup(leftClient, rightClient, leftIP, rightIP, req)
+
+	if leftOut.err != nil {
+		PrintError(fmt.Sprintf("LEFT (%s) /addGroup failed: %v", leftIP, leftOut.err))
+	}
+
+	if rightOut.err != nil {
+		PrintError(fmt.Sprintf("RIGHT (%s) /addGroup failed: %v", rightIP, rightOut.err))
+	}
+
+	if leftOut.err != nil || rightOut.err != nil {
+		if (leftOut.err == nil) != (rightOut.err == nil) {
+			succeeded := leftIP
+			if leftOut.err != nil {
+				succeeded = rightIP
+			}
+
+			PrintError(fmt.Sprintf("Partial group state on %s — clean up with `soundtouch-cli --host %s group remove`", succeeded, succeeded))
+		}
+
+		return fmt.Errorf("/addGroup propagation failed")
+	}
+
+	// The LEFT (master) response carries the assigned group ID; use it for display.
+	PrintSuccess(fmt.Sprintf("Stereo pair created (id=%s)", leftOut.group.ID))
+	printGroup(leftOut.group)
+
+	return nil
+}
+
+// addGroupOutcome is the per-speaker result of a parallel /addGroup call.
+type addGroupOutcome struct {
+	host  string
+	group *models.Group
+	err   error
+}
+
+// propagateAddGroup POSTs /addGroup to both speakers concurrently and returns
+// the (LEFT, RIGHT) outcomes. A non-GROUP_OK Status in the response is
+// reported as an error so callers don't have to re-inspect the body.
+//
+// The two POSTs carry different payloads: the master (LEFT) receives the base
+// request with no senderIPAddress so its state machine forms the group as the
+// master, while the slave (RIGHT) receives a copy with senderIPAddress set to
+// the master's IP so its state machine joins as the slave. Sending the same
+// payload to both makes both speakers think they're the slave — they enter
+// AddingSlave, wait for a master that never confirms, time out after 5 s, and
+// revert (issue #252).
+func propagateAddGroup(left, right *client.Client, leftIP, rightIP string, req *models.Group) (addGroupOutcome, addGroupOutcome) {
+	masterReq := *req
+	masterReq.SenderIPAddress = ""
+
+	slaveReq := *req
+	slaveReq.SenderIPAddress = leftIP
+
+	var (
+		wg                sync.WaitGroup
+		leftOut, rightOut addGroupOutcome
+	)
+
+	wg.Add(2)
+
+	go func() {
+		defer wg.Done()
+
+		leftOut = postAddGroup(left, leftIP, &masterReq)
+	}()
+
+	go func() {
+		defer wg.Done()
+
+		rightOut = postAddGroup(right, rightIP, &slaveReq)
+	}()
+
+	wg.Wait()
+
+	return leftOut, rightOut
+}
+
+func postAddGroup(cli *client.Client, host string, req *models.Group) addGroupOutcome {
+	out := addGroupOutcome{host: host}
+
+	g, err := cli.AddGroup(req)
+	if err != nil {
+		out.err = err
+		return out
+	}
+
+	out.group = g
+
+	if g != nil && g.Status != "" && g.Status != "GROUP_OK" {
+		out.err = fmt.Errorf("device returned status %q (want GROUP_OK)", g.Status)
+	}
+
+	return out
+}
+
+// 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()
+	}
+}
@@ -0,0 +1,184 @@
+package main
+
+import (
+	"encoding/xml"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/client"
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+)
+
+// happyAddGroupServer fakes a speaker's /addGroup that echoes the request
+// with an assigned ID and GROUP_OK status, matching real hardware behaviour.
+func happyAddGroupServer(t *testing.T, assignedID string) (*httptest.Server, *[]string) {
+	t.Helper()
+
+	bodies := make([]string, 0)
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/addGroup" || r.Method != http.MethodPost {
+			t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
+			http.NotFound(w, r)
+
+			return
+		}
+
+		body, _ := io.ReadAll(r.Body)
+		bodies = append(bodies, string(body))
+
+		var got models.Group
+		if err := xml.Unmarshal(body, &got); err != nil {
+			t.Fatalf("decode request body: %v", err)
+		}
+
+		got.ID = assignedID
+		got.Status = "GROUP_OK"
+
+		w.Header().Set("Content-Type", "application/xml")
+
+		enc, _ := xml.Marshal(&got)
+		_, _ = w.Write(enc)
+	}))
+
+	return srv, &bodies
+}
+
+func newTestGroupClient(serverURL string) *client.Client {
+	return client.NewClientFromHost(serverURL)
+}
+
+func sampleGroupRequest(leftIP, rightIP string) *models.Group {
+	return &models.Group{
+		Name:           "Living Room",
+		MasterDeviceID: "9070658C9D4A",
+		Roles: models.GroupRoles{
+			Roles: []models.GroupRole{
+				{DeviceID: "9070658C9D4A", Role: "LEFT", IPAddress: leftIP},
+				{DeviceID: "F45EAB3115DA", Role: "RIGHT", IPAddress: rightIP},
+			},
+		},
+		// senderIPAddress is intentionally not set here; propagateAddGroup
+		// adds it to the slave's copy only.
+	}
+}
+
+func TestPropagateAddGroup_BothSucceed(t *testing.T) {
+	leftSrv, leftBodies := happyAddGroupServer(t, "9999999")
+	defer leftSrv.Close()
+
+	rightSrv, rightBodies := happyAddGroupServer(t, "9999999")
+	defer rightSrv.Close()
+
+	leftClient := newTestGroupClient(leftSrv.URL)
+	rightClient := newTestGroupClient(rightSrv.URL)
+
+	req := sampleGroupRequest("192.168.1.131", "192.168.1.134")
+
+	leftOut, rightOut := propagateAddGroup(leftClient, rightClient, "192.168.1.131", "192.168.1.134", req)
+
+	if leftOut.err != nil {
+		t.Errorf("LEFT err = %v, want nil", leftOut.err)
+	}
+
+	if rightOut.err != nil {
+		t.Errorf("RIGHT err = %v, want nil", rightOut.err)
+	}
+
+	if leftOut.group == nil || leftOut.group.ID != "9999999" || leftOut.group.Status != "GROUP_OK" {
+		t.Errorf("LEFT group = %+v, want id=9999999 status=GROUP_OK", leftOut.group)
+	}
+
+	if rightOut.group == nil || rightOut.group.Status != "GROUP_OK" {
+		t.Errorf("RIGHT group = %+v, want status=GROUP_OK", rightOut.group)
+	}
+
+	// Both speakers must have received the roles, but only the slave's payload
+	// carries senderIPAddress — see propagateAddGroup for the why.
+	for label, bodies := range map[string]*[]string{"LEFT": leftBodies, "RIGHT": rightBodies} {
+		if len(*bodies) != 1 {
+			t.Fatalf("%s: expected exactly one POST, got %d", label, len(*bodies))
+		}
+
+		body := (*bodies)[0]
+		for _, want := range []string{"<role>LEFT</role>", "<role>RIGHT</role>"} {
+			if !strings.Contains(body, want) {
+				t.Errorf("%s body missing %q\nbody:\n%s", label, want, body)
+			}
+		}
+	}
+
+	leftBody := (*leftBodies)[0]
+	if strings.Contains(leftBody, "<senderIPAddress>") {
+		t.Errorf("LEFT (master) body must NOT carry <senderIPAddress>, otherwise the master flips into slave mode (issue #252)\nbody:\n%s", leftBody)
+	}
+
+	rightBody := (*rightBodies)[0]
+	if !strings.Contains(rightBody, "<senderIPAddress>192.168.1.131</senderIPAddress>") {
+		t.Errorf("RIGHT (slave) body must carry <senderIPAddress>192.168.1.131</senderIPAddress>\nbody:\n%s", rightBody)
+	}
+}
+
+func TestPropagateAddGroup_RightFails(t *testing.T) {
+	leftSrv, _ := happyAddGroupServer(t, "9999999")
+	defer leftSrv.Close()
+
+	rightSrv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		http.Error(w, "boom", http.StatusInternalServerError)
+	}))
+	defer rightSrv.Close()
+
+	leftClient := newTestGroupClient(leftSrv.URL)
+	rightClient := newTestGroupClient(rightSrv.URL)
+
+	req := sampleGroupRequest("192.168.1.131", "192.168.1.134")
+
+	leftOut, rightOut := propagateAddGroup(leftClient, rightClient, "192.168.1.131", "192.168.1.134", req)
+
+	if leftOut.err != nil {
+		t.Errorf("LEFT err = %v, want nil", leftOut.err)
+	}
+
+	if rightOut.err == nil {
+		t.Error("RIGHT err = nil, want non-nil")
+	}
+}
+
+func TestPostAddGroup_StatusOtherThanGroupOKIsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/xml")
+		_, _ = w.Write([]byte(`<group><status>GROUP_NOT_READY</status></group>`))
+	}))
+	defer srv.Close()
+
+	out := postAddGroup(newTestGroupClient(srv.URL), "test", sampleGroupRequest("1.1.1.1", "2.2.2.2"))
+
+	if out.err == nil {
+		t.Fatal("expected error for non-GROUP_OK status")
+	}
+
+	if !strings.Contains(out.err.Error(), "GROUP_NOT_READY") {
+		t.Errorf("error %q does not mention returned status", out.err)
+	}
+}
+
+func TestPostAddGroup_EmptyStatusIsAccepted(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/xml")
+		_, _ = w.Write([]byte(`<group id="42"><name>n</name></group>`))
+	}))
+	defer srv.Close()
+
+	out := postAddGroup(newTestGroupClient(srv.URL), "test", sampleGroupRequest("1.1.1.1", "2.2.2.2"))
+
+	if out.err != nil {
+		t.Errorf("err = %v, want nil for empty status (some firmware omits it)", out.err)
+	}
+
+	if out.group == nil || out.group.ID != "42" {
+		t.Errorf("group = %+v, want id=42", out.group)
+	}
+}
@@ -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")
+	}
+}
@@ -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)

@@ -484,6 +484,8 @@ func main() {
 				}

 				startHTTPSServer(config.httpsAddr, r, tlsConfig, config.httpsServerURL)
+
+				runHTTPSPreflight(config.httpsServerURL, config.serverURL, config.dnsEnabled, server.ResolveServerURLIPForPreflight)
 			}()

 			return http.ListenAndServe(config.addr, r)
@@ -852,15 +854,32 @@ 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)
@@ -889,11 +908,17 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 			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)
 	})

+	// Orion (LOCAL_INTERNET_RADIO) lives at the top level — the BMX registry
+	// advertises baseUrl `{BMX_SERVER}/core02/svc-bmx-adapter-orion/prod/orion`
+	// (no `/bmx/` prefix; verified against the upstream capture in
+	// pkg/service/handlers/static/bmx_services_ustream.json), so speakers
+	// reach the token + station endpoints at exactly these paths under
+	// either DNS-interception or URL-flip migration.
+	r.Post("/core02/svc-bmx-adapter-orion/prod/orion/token", server.HandleOrionToken)
+	r.Get("/core02/svc-bmx-adapter-orion/prod/orion/station", server.HandleOrionPlayback)
+
 	r.Get("/custom/v1/playback/{encodedURL}", server.HandleCustomPlayback)

 	r.Route("/streaming", func(r chi.Router) {
@@ -911,31 +936,47 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 			r.Get("/presets/all", server.HandleMargeAccountPresets)
 			r.Get("/provider_settings", server.HandleMargeProviderSettings)

+			// All `/device` routes share one chi subrouter. Two
+			// overlapping subrouters (`/device` + `/device/{device}`)
+			// caused chi's radix-tree resolver to bind a runtime
+			// request to the more-specific prefix even when only the
+			// less-specific subrouter had a matching method handler,
+			// producing the [UNHANDLED] → upstream-proxy fall-through
+			// behind issue #285's first-attempted fix. One subrouter
+			// keeps every device-scoped path resolvable; see
+			// TestPUTRenameRoutesToLocalHandler for the regression
+			// against the production router.
 			r.Route("/device", func(r chi.Router) {
 				r.Post("/", server.HandleMargeAddDevice)
 				r.Post("/{device}", server.HandleMargeAddDevice)
+				// PUT is the rename / update path — speakers fire
+				// this against PUT /streaming/account/{a}/device/{d}
+				// when the user renames via Bose App or
+				// `soundtouch-cli name set`. Issue #285.
+				r.Put("/{device}", server.HandleMargeUpdateDevice)
+				r.Delete("/{device}", server.HandleMargeRemoveDevice)
+
+				r.Get("/{device}/presets", server.HandleMargePresets)
+				r.Post("/{device}/presets/{presetNumber}", server.HandleMargeUpdatePreset)
+				r.Put("/{device}/preset/{presetNumber}", server.HandleMargeUpdatePreset)
+				r.Delete("/{device}/preset/{presetNumber}", server.HandleMargeRemovePreset)
+				r.Get("/{device}/recent", server.HandleMargeRecents)
+				r.Get("/{device}/recents", server.HandleMargeRecents)
+				r.Post("/{device}/recent", server.HandleMargeAddRecent)
+
+				r.Get("/{device}/group", server.HandleMargeDeviceGroup)
+				r.Get("/{device}/group/", server.HandleMargeDeviceGroup)
+				r.Get("/{device}/group/server", server.HandleMargeDeviceGroupServer)
+				r.Get("/{device}/group/member", server.HandleMargeDeviceGroupMember)
 			})

-			r.Route("/device/{device}", func(r chi.Router) {
-				r.Get("/presets", server.HandleMargePresets)
-				r.Post("/presets/{presetNumber}", server.HandleMargeUpdatePreset)
-				r.Put("/preset/{presetNumber}", server.HandleMargeUpdatePreset)
-				r.Delete("/preset/{presetNumber}", server.HandleMargeRemovePreset)
-				r.Get("/recent", server.HandleMargeRecents)
-				r.Get("/recents", server.HandleMargeRecents)
-				r.Post("/recent", server.HandleMargeAddRecent)
-
-				r.Get("/group", server.HandleMargeDeviceGroup)
-				r.Get("/group/", server.HandleMargeDeviceGroup)
-				r.Get("/group/server", server.HandleMargeDeviceGroupServer)
-				r.Get("/group/member", server.HandleMargeDeviceGroupMember)
-			})
-
+			// Speakers POST to /group/ (with trailing slash) when forwarding
+			// the addGroup payload to Marge during stereo-pair formation --
+			// see issue #252. Register both forms so chi accepts either.
 			r.Post("/group", server.HandleMargeAddGroup)
+			r.Post("/group/", server.HandleMargeAddGroup)
 			r.Post("/group/{groupId}", server.HandleMargeModifyGroup)
 			r.Delete("/group/{groupId}", server.HandleMargeDeleteGroup)
-
-			r.Delete("/device/{device}", server.HandleMargeRemoveDevice)
 		})

 		r.Get("/device/{device}/streaming_token", server.HandleMargeStreamingToken)
@@ -980,6 +1021,7 @@ func setupRouter(server *handlers.Server) *chi.Mux {
 			r.Get("/devices/{device}/group/member", server.HandleMargeDeviceGroupMember)

 			r.Post("/group", server.HandleMargeAddGroup)
+			r.Post("/group/", server.HandleMargeAddGroup)
 			r.Post("/group/{groupId}", server.HandleMargeModifyGroup)
 			r.Delete("/group/{groupId}", server.HandleMargeDeleteGroup)
 			r.Get("/devices/{device}/presets", server.HandleMargePresets)
@@ -1070,6 +1112,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)
@@ -1160,6 +1204,45 @@ func startHTTPSServer(httpsAddr string, r http.Handler, tlsConfig *tls.Config, h
 	}()
 }

+// runHTTPSPreflight checks whether speakers' implicit :443 target reaches
+// AfterTouch. Runs after the HTTPS listener has had a moment to come up; if
+// the listener is already on :443 the check is skipped. Emits a single WARN
+// log line with actionable guidance when either probe fails.
+//
+// Only runs when dnsEnabled is true: the :443 reachability only matters when
+// speakers are reaching AfterTouch via intercepted Bose hostnames (i.e. the
+// DNS migration method). For direct SDK-override migration the speaker
+// connects to the configured https-port directly, so :443 is irrelevant.
+// Users with external DNS interception (Pi-hole, router rules) can still see
+// the live result on /setup/settings even when this startup warn is silent.
+func runHTTPSPreflight(httpsServerURL, serverURL string, dnsEnabled bool, resolver func(string) (string, error)) {
+	if !dnsEnabled {
+		return
+	}
+
+	port := handlers.PortFromHTTPSServerURL(httpsServerURL)
+	if port == 0 {
+		// Can't determine the listener port — be silent rather than misleading.
+		return
+	}
+
+	// Give the listener a head start so a successful bind beats the probe.
+	time.Sleep(2 * time.Second)
+
+	res := handlers.Check443Reachability(port, serverURL, resolver, handlers.ProbeDialTimeoutStartup)
+
+	guidance := handlers.FormatPreflightGuidance(port, res)
+	if guidance == "" {
+		if !res.Skipped {
+			log.Printf("HTTPS pre-flight: :443 reachable at localhost and %s ✓", res.LANHost)
+		}
+
+		return
+	}
+
+	log.Print(guidance)
+}
+
 // matchesDomain checks if a certificate domain (which may be a wildcard) matches a server name
 func matchesDomain(certDomain, serverName string) bool {
 	if certDomain == serverName {
@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"reflect"
 	"runtime"
@@ -10,6 +11,7 @@ import (
 	"strings"
 	"testing"

+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
 	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
 	"github.com/go-chi/chi/v5"
 )
@@ -102,3 +104,56 @@ func TestPrintRoutes(t *testing.T) {
 		t.Errorf("Router routes changed! Diff the snapshot at %s with %s", snapshotPath, actualPath)
 	}
 }
+
+// TestPUTRenameRoutesToLocalHandler reproduces the runtime routing
+// behaviour the user saw on their deployed v0.80.0: a PUT to
+// /streaming/account/{a}/device/{d} should land on
+// HandleMargeUpdateDevice, not fall through to the [UNHANDLED]
+// proxy. The handlers-package test (TestIssue285_*) uses a simplified
+// router that doesn't have the overlapping `/device` and
+// `/device/{device}` route groups, so it can't catch a chi radix-
+// tree resolution that prefers the more-specific subrouter.
+//
+// This test exercises the actual production setupRouter so a
+// regression in the route topology is caught against the same chi
+// behaviour speakers will see.
+func TestPUTRenameRoutesToLocalHandler(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "router-rename-")
+	if err != nil {
+		t.Fatalf("mkdir temp: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ds := datastore.NewDataStore(tempDir)
+	_ = ds.Initialize()
+
+	server := handlers.NewServer(ds, nil, "http://localhost:8000", false, false, false)
+	r := setupRouter(server)
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	body := `<?xml version="1.0" encoding="UTF-8" ?><device deviceid="A81B6A536A98"><name>Sound Machinechen</name><macaddress>A81B6A536A98</macaddress></device>`
+
+	req, err := http.NewRequest(http.MethodPut,
+		ts.URL+"/streaming/account/1111111/device/A81B6A536A98",
+		strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("build request: %v", err)
+	}
+
+	req.Header.Set("Content-Type", "application/xml")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("PUT: %v", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	// 200 means our local HandleMargeUpdateDevice handled it.
+	// 401 / 502 / anything else means the request fell through to
+	// the [UNHANDLED] proxy and got the upstream response — which
+	// is exactly the failure mode #285 was supposed to fix.
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("PUT status = %d, want 200 (local handler). Anything else means the request fell through to [UNHANDLED] proxy — chi is routing to a different subrouter than the PUT registration intended.", resp.StatusCode)
+	}
+}
@@ -8,6 +8,7 @@ DELETE   /setup/dns-discoveries                                       handlers.(
 DELETE   /setup/interactions/sessions                                 handlers.(*Server).HandleCleanupSessions-fm
 DELETE   /setup/interactions/sessions/{session}                       handlers.(*Server).HandleDeleteSession-fm
 DELETE   /setup/parity-mismatches                                     handlers.(*Server).HandleClearParityMismatches-fm
+DELETE   /streaming/account/{account}/device/{device}                 handlers.(*Server).HandleMargeRemoveDevice-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
@@ -30,6 +31,7 @@ GET      /bmx/tunein/v1/playback/episodes/{podcastID}                 handlers.(
 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      /core02/svc-bmx-adapter-orion/prod/orion/station             handlers.(*Server).HandleOrionPlayback-fm
 GET      /custom/v1/playback/{encodedURL}                             handlers.(*Server).HandleCustomPlayback-fm
 GET      /customer/account/{account}                                  handlers.(*Server).HandleMargeAccountProfile-fm
 GET      /docs/*                                                      handlers.(*Server).HandleDocs-fm
@@ -48,6 +50,7 @@ GET      /mgmt/spotify/callback                                       handlers.(
 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
@@ -93,13 +96,13 @@ POST     /accounts/{account}/devices                                  handlers.(
 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/                                   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     /core02/svc-bmx-adapter-orion/prod/orion/token               handlers.(*Server).HandleOrionToken-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
@@ -121,6 +124,8 @@ POST     /setup/devices                                               handlers.(
 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
@@ -138,6 +143,7 @@ POST     /streaming/account/{account}/device/{device}                 handlers.(
 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/                          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
@@ -150,5 +156,6 @@ POST     /streaming/support/power_on                                  handlers.(
 POST     /v1/scmudc/{deviceId}                                        handlers.(*Server).HandleAppEvents-fm
 POST     /v1/stapp/{deviceId}                                         handlers.(*Server).HandleAppEvents-fm
 PUT      /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+PUT      /streaming/account/{account}/device/{device}                 handlers.(*Server).HandleMargeUpdateDevice-fm
 PUT      /streaming/account/{account}/device/{device}/preset/{presetNumber} handlers.(*Server).HandleMargeUpdatePreset-fm
 TRACE    /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
@@ -0,0 +1,648 @@
+// Package handlers contains HTTP handlers for the SoundTouch web UI.
+package handlers
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+
+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/webtypes"
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	bmxpkg "github.com/gesellix/bose-soundtouch/pkg/service/bmx"
+	"github.com/go-chi/chi/v5"
+	"github.com/gorilla/websocket"
+)
+
+// WebApp holds the application state and dependencies
+type WebApp struct {
+	Devices   map[string]*webtypes.DeviceConnection
+	Upgrader  websocket.Upgrader
+	WSClients map[*websocket.Conn]bool
+	WSMutex   sync.RWMutex
+}
+
+// NewWebApp creates a new WebApp instance for SPA mode
+func NewWebApp() *WebApp {
+	return &WebApp{
+		Devices:   make(map[string]*webtypes.DeviceConnection),
+		WSClients: make(map[*websocket.Conn]bool),
+		Upgrader: websocket.Upgrader{
+			CheckOrigin: func(_ *http.Request) bool { return true },
+		},
+	}
+}
+
+// HandleAPIDevices returns all devices as JSON
+func (app *WebApp) HandleAPIDevices(w http.ResponseWriter, _ *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+
+	// Return all devices as JSON
+	devices := make(map[string]interface{})
+	for id, device := range app.Devices {
+		devices[id] = map[string]interface{}{
+			"info":     device.DeviceInfo,
+			"status":   device.Status,
+			"lastSeen": device.LastSeen,
+		}
+	}
+
+	response := webtypes.APIResponse{
+		Success: true,
+		Data:    devices,
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// HandleAPIDevice returns a specific device as JSON
+func (app *WebApp) HandleAPIDevice(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+	if deviceID == "" {
+		app.sendError(w, "Device ID required", http.StatusBadRequest)
+		return
+	}
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	// Update device status to get fresh power state
+	app.UpdateDeviceStatus(deviceID, device)
+
+	// Connect WebSocket for real-time updates if not already connected
+	if device.WebSocket == nil {
+		go app.ConnectDeviceWebSocket(deviceID, device)
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	response := webtypes.APIResponse{
+		Success: true,
+		Data: map[string]interface{}{
+			"info":   device.DeviceInfo,
+			"status": device.Status,
+		},
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// HandleAPIControl handles device control commands
+func (app *WebApp) HandleAPIControl(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+	action := chi.URLParam(r, "action")
+
+	if deviceID == "" {
+		app.sendError(w, "Device ID required", http.StatusBadRequest)
+		return
+	}
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	// Connect WebSocket for real-time updates if not already connected
+	if device.WebSocket == nil {
+		go app.ConnectDeviceWebSocket(deviceID, device)
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	app.handleControlAction(w, r, action, device)
+}
+
+// handleControlAction processes different control actions
+func (app *WebApp) handleControlAction(w http.ResponseWriter, r *http.Request, action string, device *webtypes.DeviceConnection) {
+	switch action {
+	case "play":
+		if device.Client == nil {
+			app.sendError(w, "Device client not available", http.StatusInternalServerError)
+			return
+		}
+
+		err := device.Client.Play()
+		app.sendControlResponse(w, err, "Started playback")
+	case "pause":
+		if device.Client == nil {
+			app.sendError(w, "Device client not available", http.StatusInternalServerError)
+			return
+		}
+
+		err := device.Client.Pause()
+		app.sendControlResponse(w, err, "Paused playback")
+	case "stop":
+		if device.Client == nil {
+			app.sendError(w, "Device client not available", http.StatusInternalServerError)
+			return
+		}
+
+		err := device.Client.Stop()
+		app.sendControlResponse(w, err, "Stopped playback")
+	case "next":
+		if device.Client == nil {
+			app.sendError(w, "Device client not available", http.StatusInternalServerError)
+			return
+		}
+
+		err := device.Client.NextTrack()
+		app.sendControlResponse(w, err, "Next track")
+	case "previous":
+		if device.Client == nil {
+			app.sendError(w, "Device client not available", http.StatusInternalServerError)
+			return
+		}
+
+		err := device.Client.PrevTrack()
+		app.sendControlResponse(w, err, "Previous track")
+	case "volume":
+		app.handleVolumeControl(w, r, device)
+	case "mute":
+		if device.Client == nil {
+			app.sendError(w, "Device client not available", http.StatusInternalServerError)
+			return
+		}
+
+		err := device.Client.SendKey(models.KeyMute)
+		app.sendControlResponse(w, err, "Toggled mute")
+	case "preset":
+		app.handlePresetControl(w, r, device)
+	case "bass":
+		app.handleBassControl(w, r, device)
+	case "source":
+		app.handleSourceControl(w, r, device)
+	default:
+		app.sendError(w, "Unknown action", http.StatusBadRequest)
+	}
+}
+
+// handleVolumeControl processes volume control requests
+func (app *WebApp) handleVolumeControl(w http.ResponseWriter, r *http.Request, device *webtypes.DeviceConnection) {
+	if r.Method != http.MethodPost {
+		app.sendError(w, "POST required for volume control", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var volumeReq webtypes.VolumeRequest
+	if err := json.NewDecoder(r.Body).Decode(&volumeReq); err != nil {
+		app.sendError(w, "Invalid volume data", http.StatusBadRequest)
+		return
+	}
+
+	if volumeReq.Level < 0 || volumeReq.Level > 100 {
+		app.sendError(w, "Volume must be between 0 and 100", http.StatusBadRequest)
+		return
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	err := device.Client.SetVolume(volumeReq.Level)
+	app.sendControlResponse(w, err, fmt.Sprintf("Volume set to %d", volumeReq.Level))
+}
+
+// handlePresetControl processes preset control requests
+func (app *WebApp) handlePresetControl(w http.ResponseWriter, r *http.Request, device *webtypes.DeviceConnection) {
+	presetParam := r.URL.Query().Get("id")
+	if presetParam == "" {
+		app.sendError(w, "Preset ID required", http.StatusBadRequest)
+		return
+	}
+
+	presetID, err := strconv.Atoi(presetParam)
+	if err != nil {
+		app.sendError(w, "Invalid preset ID", http.StatusBadRequest)
+		return
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	err = device.Client.SelectPreset(presetID)
+	app.sendControlResponse(w, err, fmt.Sprintf("Selected preset %d", presetID))
+}
+
+// handleBassControl processes bass control requests
+func (app *WebApp) handleBassControl(w http.ResponseWriter, r *http.Request, device *webtypes.DeviceConnection) {
+	if r.Method != http.MethodPost {
+		app.sendError(w, "POST required for bass control", http.StatusMethodNotAllowed)
+		return
+	}
+
+	var bassReq webtypes.BassRequest
+	if err := json.NewDecoder(r.Body).Decode(&bassReq); err != nil {
+		app.sendError(w, "Invalid bass data", http.StatusBadRequest)
+		return
+	}
+
+	if bassReq.Level < -9 || bassReq.Level > 9 {
+		app.sendError(w, "Bass must be between -9 and 9", http.StatusBadRequest)
+		return
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	err := device.Client.SetBass(bassReq.Level)
+	app.sendControlResponse(w, err, fmt.Sprintf("Bass set to %d", bassReq.Level))
+}
+
+// handleSourceControl processes source control requests
+func (app *WebApp) handleSourceControl(w http.ResponseWriter, r *http.Request, device *webtypes.DeviceConnection) {
+	sourceParam := r.URL.Query().Get("name")
+	if sourceParam == "" {
+		app.sendError(w, "Source name required", http.StatusBadRequest)
+		return
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	err := device.Client.SelectSource(sourceParam, "")
+	app.sendControlResponse(w, err, fmt.Sprintf("Selected source %s", sourceParam))
+}
+
+// sendControlResponse sends a control command response
+func (app *WebApp) sendControlResponse(w http.ResponseWriter, err error, successMessage string) {
+	if err != nil {
+		app.sendError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	response := webtypes.APIResponse{
+		Success: true,
+		Data:    map[string]string{"message": successMessage},
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// sendError sends an error response
+func (app *WebApp) sendError(w http.ResponseWriter, message string, statusCode int) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(statusCode)
+
+	response := webtypes.APIResponse{
+		Success: false,
+		Error:   message,
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		http.Error(w, "Failed to encode error response", http.StatusInternalServerError)
+	}
+}
+
+// HandleDeviceKey handles sending key commands to devices
+func (app *WebApp) HandleDeviceKey(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+	key := chi.URLParam(r, "key")
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	// Connect WebSocket for real-time updates if not already connected
+	if device.WebSocket == nil {
+		go app.ConnectDeviceWebSocket(deviceID, device)
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	err := device.Client.SendKey(key)
+	app.sendControlResponse(w, err, fmt.Sprintf("Sent key command: %s", key))
+}
+
+// HandleDirectVolumeControl handles direct volume setting via URL parameter
+func (app *WebApp) HandleDirectVolumeControl(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+
+	volumeLevel, err := strconv.Atoi(chi.URLParam(r, "volume"))
+	if err != nil || volumeLevel < 0 || volumeLevel > 100 {
+		app.sendError(w, "Invalid volume level (0-100)", http.StatusBadRequest)
+		return
+	}
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	// Connect WebSocket for real-time updates if not already connected
+	if device.WebSocket == nil {
+		go app.ConnectDeviceWebSocket(deviceID, device)
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	err = device.Client.SetVolume(volumeLevel)
+	app.sendControlResponse(w, err, fmt.Sprintf("Volume set to %d", volumeLevel))
+}
+
+// HandleDevicePower handles power toggle commands for devices
+func (app *WebApp) HandleDevicePower(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	// Connect WebSocket for real-time updates if not already connected
+	if device.WebSocket == nil {
+		go app.ConnectDeviceWebSocket(deviceID, device)
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	// Send POWER key command to toggle device power
+	err := device.Client.SendKey("POWER")
+	app.sendControlResponse(w, err, "Power toggle command sent")
+}
+
+// HandleDevicePowerStatus handles lightweight power status check
+func (app *WebApp) HandleDevicePowerStatus(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	if device.Client == nil {
+		app.sendError(w, "Device client not available", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	// Quick power status check by getting now playing
+	nowPlaying, err := device.Client.GetNowPlaying()
+	if err != nil {
+		app.sendControlResponse(w, err, "Failed to get power status")
+		return
+	}
+
+	isPoweredOn := nowPlaying != nil && nowPlaying.Source != "STANDBY"
+
+	response := webtypes.APIResponse{
+		Success: true,
+		Data: map[string]interface{}{
+			"deviceId":    deviceID,
+			"isPoweredOn": isPoweredOn,
+			"source":      nowPlaying.Source,
+		},
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// BroadcastDeviceList sends updated device list to all connected WebSocket clients
+func (app *WebApp) BroadcastDeviceList() {
+	app.WSMutex.RLock()
+	defer app.WSMutex.RUnlock()
+
+	devices := make(map[string]interface{})
+	for id, device := range app.Devices {
+		devices[id] = map[string]interface{}{
+			"info":     device.DeviceInfo,
+			"status":   device.Status,
+			"lastSeen": device.LastSeen,
+		}
+	}
+
+	message := webtypes.WebSocketMessage{
+		Type: "devices",
+		Data: devices,
+	}
+
+	// Send to all connected clients
+	var failedClients []*websocket.Conn
+
+	for client := range app.WSClients {
+		if err := client.WriteJSON(message); err != nil {
+			log.Printf("Failed to send device update to WebSocket client: %v", err)
+			// Mark for removal to avoid modifying map during iteration
+			failedClients = append(failedClients, client)
+		}
+	}
+
+	// Remove failed clients
+	for _, client := range failedClients {
+		delete(app.WSClients, client)
+		client.Close()
+	}
+}
+
+// BroadcastDiscoveryStatus sends discovery progress updates to all connected WebSocket clients
+func (app *WebApp) BroadcastDiscoveryStatus(status string, deviceCount int) {
+	app.WSMutex.RLock()
+	defer app.WSMutex.RUnlock()
+
+	message := webtypes.WebSocketMessage{
+		Type: "discovery_status",
+		Data: map[string]interface{}{
+			"status":      status,
+			"deviceCount": deviceCount,
+		},
+	}
+
+	// Send to all connected clients
+	var failedClients []*websocket.Conn
+
+	for client := range app.WSClients {
+		if err := client.WriteJSON(message); err != nil {
+			log.Printf("Failed to send discovery status to WebSocket client: %v", err)
+			// Mark for removal to avoid modifying map during iteration
+			failedClients = append(failedClients, client)
+		}
+	}
+
+	// Remove failed clients
+	for _, client := range failedClients {
+		delete(app.WSClients, client)
+		client.Close()
+	}
+}
+
+// HandleTuneInSearch handles TuneIn search requests, proxying directly to the bmx package.
+func (app *WebApp) HandleTuneInSearch(w http.ResponseWriter, r *http.Request) {
+	query := r.URL.Query().Get("q")
+	if query == "" {
+		app.sendError(w, "query parameter 'q' is required", http.StatusBadRequest)
+		return
+	}
+
+	resp, err := bmxpkg.TuneInSearch(query)
+	if err != nil {
+		app.sendError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if encErr := json.NewEncoder(w).Encode(webtypes.APIResponse{Success: true, Data: resp}); encErr != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// HandleTuneInNavigate handles TuneIn browse/navigate requests, proxying directly to the bmx package.
+// Supported path suffixes (relative to /api/tunein/navigate):
+//   - (empty)                             → top-level browse
+//   - /{encodedURI}                       → browse the given TuneIn URI
+//   - /sub/{n}/{encodedURI}               → single subsection
+//   - /profiles/{type}/{id}/{encodedURI}  → artist/program profile
+func (app *WebApp) HandleTuneInNavigate(w http.ResponseWriter, r *http.Request) {
+	wildcard := chi.URLParam(r, "*")
+
+	var (
+		resp interface{}
+		err  error
+	)
+
+	if wildcard == "" {
+		resp, err = bmxpkg.TuneInNavigate("", nil)
+	} else {
+		firstSlash := strings.Index(wildcard, "/")
+		if firstSlash == -1 {
+			resp, err = bmxpkg.TuneInNavigate(wildcard, nil)
+		} else {
+			pfx := wildcard[:firstSlash]
+			rest := wildcard[firstSlash+1:]
+
+			switch pfx {
+			case "sub":
+				secondSlash := strings.Index(rest, "/")
+				if secondSlash == -1 {
+					resp, err = bmxpkg.TuneInNavigate(rest, nil)
+				} else {
+					n, parseErr := strconv.Atoi(rest[:secondSlash])
+					if parseErr != nil {
+						resp, err = bmxpkg.TuneInNavigate(wildcard, nil)
+					} else {
+						resp, err = bmxpkg.TuneInNavigate(rest[secondSlash+1:], &n)
+					}
+				}
+			case "profiles":
+				parts := strings.SplitN(rest, "/", 3)
+				if len(parts) < 3 {
+					resp, err = bmxpkg.TuneInNavigate(wildcard, nil)
+				} else {
+					resp, err = bmxpkg.TuneInNavigateProfile(parts[2])
+				}
+			default:
+				resp, err = bmxpkg.TuneInNavigate(wildcard, nil)
+			}
+		}
+	}
+
+	if err != nil {
+		app.sendError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if encErr := json.NewEncoder(w).Encode(webtypes.APIResponse{Success: true, Data: resp}); encErr != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// HandlePlayTuneIn plays a TuneIn content item on a specific device via POST /select.
+func (app *WebApp) HandlePlayTuneIn(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "id")
+	if deviceID == "" {
+		app.sendError(w, "Device ID required", http.StatusBadRequest)
+		return
+	}
+
+	device, exists := app.Devices[deviceID]
+	if !exists {
+		app.sendError(w, fmt.Sprintf("Device '%s' not found", deviceID), http.StatusNotFound)
+		return
+	}
+
+	var req struct {
+		Location     string `json:"location"`
+		Name         string `json:"name"`
+		Type         string `json:"type"`
+		ContainerArt string `json:"containerArt"`
+	}
+
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		app.sendError(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	if req.Location == "" {
+		app.sendError(w, "location is required", http.StatusBadRequest)
+		return
+	}
+
+	itemType := req.Type
+	if itemType == "" {
+		itemType = "stationurl"
+	}
+
+	contentItem := &models.ContentItem{
+		Source:       "TUNEIN",
+		Type:         itemType,
+		Location:     req.Location,
+		ItemName:     req.Name,
+		IsPresetable: true,
+		ContainerArt: req.ContainerArt,
+	}
+
+	if err := device.Client.SelectContentItem(contentItem); err != nil {
+		app.sendError(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if encErr := json.NewEncoder(w).Encode(webtypes.APIResponse{Success: true, Data: map[string]string{"message": "Playing " + req.Name}}); encErr != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
@@ -1,4 +1,5 @@
-package soundtouchweb
+// Package handlers contains tests for HTTP handlers.
+package handlers

 import (
 	"context"
@@ -9,9 +10,9 @@ import (
 	"testing"
 	"time"

+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/webtypes"
 	"github.com/gesellix/bose-soundtouch/pkg/client"
 	"github.com/gesellix/bose-soundtouch/pkg/models"
-	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb/webtypes"
 	"github.com/go-chi/chi/v5"
 )

@@ -1,4 +1,5 @@
-package soundtouchweb
+// Package handlers contains WebSocket handlers for real-time communication.
+package handlers

 import (
 	"encoding/json"
@@ -6,13 +7,13 @@ import (
 	"net/http"
 	"time"

+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/webtypes"
 	"github.com/gesellix/bose-soundtouch/pkg/models"
-	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb/webtypes"
 	"github.com/go-chi/chi/v5"
 	"github.com/gorilla/websocket"
 )

-// HandleWebSocket handles browser WebSocket connections for real-time updates.
+// HandleWebSocket handles WebSocket connections for real-time updates
 func (app *WebApp) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
 	conn, err := app.Upgrader.Upgrade(w, r, nil)
 	if err != nil {
@@ -21,16 +22,19 @@ func (app *WebApp) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
 	}

 	defer func() {
+		// Unregister client
 		app.WSMutex.Lock()
 		delete(app.WSClients, conn)
 		app.WSMutex.Unlock()
 		conn.Close()
 	}()

+	// Register client
 	app.WSMutex.Lock()
 	app.WSClients[conn] = true
 	app.WSMutex.Unlock()

+	// Send initial device list
 	devices := make(map[string]interface{})
 	for id, device := range app.Devices {
 		devices[id] = map[string]interface{}{
@@ -40,20 +44,30 @@ func (app *WebApp) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
 		}
 	}

-	if err := conn.WriteJSON(webtypes.WebSocketMessage{Type: "devices", Data: devices}); err != nil {
+	initialMessage := webtypes.WebSocketMessage{
+		Type: "devices",
+		Data: devices,
+	}
+
+	if err := conn.WriteJSON(initialMessage); err != nil {
 		log.Printf("Failed to send initial data: %v", err)
 		return
 	}

+	// Keep connection alive and send updates
 	ticker := time.NewTicker(5 * time.Second)
 	defer ticker.Stop()

+	// Set up ping handler to detect client disconnects
 	conn.SetPongHandler(func(string) error {
 		conn.SetReadDeadline(time.Now().Add(60 * time.Second))
 		return nil
 	})
+
+	// Set initial read deadline
 	conn.SetReadDeadline(time.Now().Add(60 * time.Second))

+	// Handle incoming messages in a separate goroutine
 	go func() {
 		defer conn.Close()

@@ -65,19 +79,24 @@ func (app *WebApp) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
 		}
 	}()

+	// Main loop for sending periodic updates
 	for range ticker.C {
+		// Send ping to check if client is still connected
 		if err := conn.WriteMessage(websocket.PingMessage, []byte{}); err != nil {
 			log.Printf("Failed to send ping: %v", err)
 			return
 		}

+		// Send periodic status updates
 		for id, device := range app.Devices {
 			if device.Status.IsConnected {
-				if err := conn.WriteJSON(webtypes.WebSocketMessage{
+				statusMessage := webtypes.WebSocketMessage{
 					Type:     "status_update",
 					DeviceID: id,
 					Data:     device.Status,
-				}); err != nil {
+				}
+
+				if err := conn.WriteJSON(statusMessage); err != nil {
 					log.Printf("Failed to send status update: %v", err)
 					return
 				}
@@ -86,31 +105,36 @@ func (app *WebApp) HandleWebSocket(w http.ResponseWriter, r *http.Request) {
 	}
 }

-// HandleAPIDiscover acknowledges a discovery request (actual discovery is triggered by Mount).
+// HandleAPIDiscover triggers device discovery
 func (app *WebApp) HandleAPIDiscover(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		app.sendError(w, "Method not allowed", http.StatusMethodNotAllowed)
 		return
 	}

+	// Discovery will be triggered by the main app
 	w.Header().Set("Content-Type", "application/json")

-	if err := json.NewEncoder(w).Encode(webtypes.APIResponse{
+	response := webtypes.APIResponse{
 		Success: true,
 		Data:    map[string]string{"message": "Discovery started"},
-	}); err != nil {
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 	}
 }

-// ConnectDeviceWebSocket establishes a WebSocket connection to a SoundTouch device.
+// ConnectDeviceWebSocket establishes a WebSocket connection to a device
 func (app *WebApp) ConnectDeviceWebSocket(deviceID string, conn *webtypes.DeviceConnection) {
+	// Skip WebSocket connection if client is not available (e.g., in tests)
 	if conn.Client == nil {
 		return
 	}

 	wsClient := conn.Client.NewWebSocketClient(nil)

+	// Setup event handlers
 	wsClient.OnNowPlaying(func(event *models.NowPlayingUpdatedEvent) {
 		conn.Status.NowPlaying = &event.NowPlaying
 		conn.Status.LastActivity = time.Now()
@@ -131,6 +155,7 @@ func (app *WebApp) ConnectDeviceWebSocket(deviceID string, conn *webtypes.Device
 		conn.Status.LastActivity = time.Now()
 	})

+	// Connect WebSocket
 	if err := wsClient.Connect(); err != nil {
 		log.Printf("Failed to connect WebSocket for device %s: %v", deviceID, err)
 		return
@@ -141,6 +166,7 @@ func (app *WebApp) ConnectDeviceWebSocket(deviceID string, conn *webtypes.Device

 	log.Printf("WebSocket connected for device %s", deviceID)

+	// Wait for disconnection
 	wsClient.Wait()

 	conn.Status.IsConnected = false
@@ -148,46 +174,55 @@ func (app *WebApp) ConnectDeviceWebSocket(deviceID string, conn *webtypes.Device
 	log.Printf("WebSocket disconnected for device %s", deviceID)
 }

-// UpdateDeviceStatus fetches current status from a device.
+// UpdateDeviceStatus fetches current status from device
 func (app *WebApp) UpdateDeviceStatus(_ string, conn *webtypes.DeviceConnection) {
+	// Skip status update if client is not available (e.g., in tests)
 	if conn.Client == nil {
 		return
 	}

 	statusUpdated := false

+	// Get current now playing
 	if nowPlaying, err := conn.Client.GetNowPlaying(); err == nil {
 		conn.Status.NowPlaying = nowPlaying
 		statusUpdated = true
 	}

+	// Get current volume
 	if volume, err := conn.Client.GetVolume(); err == nil {
 		conn.Status.Volume = volume
 		statusUpdated = true
 	}

+	// Get presets
 	if presets, err := conn.Client.GetPresets(); err == nil {
 		conn.Status.Presets = presets
 		statusUpdated = true
 	}

+	// Update last activity if any status was updated
 	if statusUpdated {
 		conn.Status.LastActivity = time.Now()
 	}
-
+	// Get sources
 	if sources, err := conn.Client.GetSources(); err == nil {
 		conn.Status.Sources = sources
+		statusUpdated = true
 	}

+	// Get bass (if available)
 	if bass, err := conn.Client.GetBass(); err == nil {
 		conn.Status.Bass = bass
+		statusUpdated = true
 	}

+	// Mark as connected if we successfully got at least one status
 	conn.Status.IsConnected = statusUpdated
 	conn.Status.LastActivity = time.Now()
 }

-// HandleDeviceWebSocket handles per-device WebSocket connections for real-time device-specific updates.
+// HandleDeviceWebSocket handles individual device WebSocket connections for real-time device-specific updates
 func (app *WebApp) HandleDeviceWebSocket(w http.ResponseWriter, r *http.Request) {
 	deviceID := chi.URLParam(r, "id")
 	if deviceID == "" {
@@ -210,21 +245,31 @@ func (app *WebApp) HandleDeviceWebSocket(w http.ResponseWriter, r *http.Request)

 	log.Printf("Device WebSocket connected for %s", deviceID)

-	if err := conn.WriteJSON(webtypes.WebSocketMessage{
+	// Send initial device status
+	initialMessage := webtypes.WebSocketMessage{
 		Type:     "device_status",
 		DeviceID: deviceID,
-		Data:     map[string]interface{}{"info": device.DeviceInfo, "status": device.Status},
-	}); err != nil {
+		Data: map[string]interface{}{
+			"info":   device.DeviceInfo,
+			"status": device.Status,
+		},
+	}
+
+	if err := conn.WriteJSON(initialMessage); err != nil {
 		log.Printf("Failed to send initial device status: %v", err)
 		return
 	}

+	// Set up ping handler to detect client disconnects
 	conn.SetPongHandler(func(string) error {
 		conn.SetReadDeadline(time.Now().Add(60 * time.Second))
 		return nil
 	})
+
+	// Set initial read deadline
 	conn.SetReadDeadline(time.Now().Add(60 * time.Second))

+	// Handle incoming messages in a separate goroutine
 	go func() {
 		defer conn.Close()

@@ -236,26 +281,36 @@ func (app *WebApp) HandleDeviceWebSocket(w http.ResponseWriter, r *http.Request)
 		}
 	}()

+	// Send periodic device status updates
 	ticker := time.NewTicker(10 * time.Second)
 	defer ticker.Stop()

 	for range ticker.C {
+		// Send ping to check if client is still connected
 		if err := conn.WriteMessage(websocket.PingMessage, []byte{}); err != nil {
 			log.Printf("Failed to send ping to device WebSocket %s: %v", deviceID, err)
 			return
 		}

-		if err := conn.WriteJSON(webtypes.WebSocketMessage{
+		// Send device status update
+		statusMessage := webtypes.WebSocketMessage{
 			Type:     "device_status",
 			DeviceID: deviceID,
-			Data:     map[string]interface{}{"info": device.DeviceInfo, "status": device.Status},
-		}); err != nil {
+			Data: map[string]interface{}{
+				"info":   device.DeviceInfo,
+				"status": device.Status,
+			},
+		}
+
+		if err := conn.WriteJSON(statusMessage); err != nil {
 			log.Printf("Failed to send device status update for %s: %v", deviceID, err)
 			return
 		}

+		// If device has active WebSocket connection to SoundTouch device,
+		// also send any real-time updates from that connection
 		if device.WebSocket != nil && device.Status.IsConnected {
-			if err := conn.WriteJSON(webtypes.WebSocketMessage{
+			realtimeMessage := webtypes.WebSocketMessage{
 				Type:     "device_realtime",
 				DeviceID: deviceID,
 				Data: map[string]interface{}{
@@ -263,57 +318,12 @@ func (app *WebApp) HandleDeviceWebSocket(w http.ResponseWriter, r *http.Request)
 					"volume":     device.Status.Volume,
 					"timestamp":  time.Now(),
 				},
-			}); err != nil {
+			}
+
+			if err := conn.WriteJSON(realtimeMessage); err != nil {
 				log.Printf("Failed to send realtime update for %s: %v", deviceID, err)
 				return
 			}
 		}
 	}
 }
-
-// BroadcastDeviceList sends the updated device list to all connected browser WebSocket clients.
-func (app *WebApp) BroadcastDeviceList() {
-	app.WSMutex.RLock()
-	defer app.WSMutex.RUnlock()
-
-	devices := make(map[string]interface{})
-	for id, device := range app.Devices {
-		devices[id] = map[string]interface{}{
-			"info":     device.DeviceInfo,
-			"status":   device.Status,
-			"lastSeen": device.LastSeen,
-		}
-	}
-
-	app.broadcast(webtypes.WebSocketMessage{Type: "devices", Data: devices})
-}
-
-// BroadcastDiscoveryStatus sends discovery progress to all connected browser WebSocket clients.
-func (app *WebApp) BroadcastDiscoveryStatus(status string, deviceCount int) {
-	app.WSMutex.RLock()
-	defer app.WSMutex.RUnlock()
-
-	app.broadcast(webtypes.WebSocketMessage{
-		Type: "discovery_status",
-		Data: map[string]interface{}{"status": status, "deviceCount": deviceCount},
-	})
-}
-
-// broadcast sends a message to all registered WS clients, removing failed ones.
-// Caller must hold at least a read lock on WSMutex.
-func (app *WebApp) broadcast(msg webtypes.WebSocketMessage) {
-	var failed []*websocket.Conn
-
-	for client := range app.WSClients {
-		if err := client.WriteJSON(msg); err != nil {
-			log.Printf("Failed to broadcast to WebSocket client: %v", err)
-
-			failed = append(failed, client)
-		}
-	}
-
-	for _, client := range failed {
-		delete(app.WSClients, client)
-		client.Close()
-	}
-}
@@ -2,15 +2,28 @@
 package main

 import (
+	"context"
+	"embed"
+	"fmt"
+	"io/fs"
 	"log"
+	"net"
 	"net/http"
 	"os"
+	"time"

-	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/handlers"
+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/webtypes"
+	"github.com/gesellix/bose-soundtouch/pkg/client"
+	"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
+
 func main() {
 	app := &cli.App{
 		Name:  "soundtouch-web",
@@ -25,23 +38,74 @@ func main() {
 			},
 			&cli.StringFlag{
 				Name:    "bind",
-				Usage:   "Network interface to bind to",
+				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")
-			bindAddr := c.String("bind")
+			rawBind := c.String("bind")
+
+			bindAddr, err := resolveBindAddr(rawBind)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if rawBind != "" && bindAddr != rawBind {
+				log.Printf("Resolved --bind %q to %s", rawBind, bindAddr)
+			}
+
+			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
 			}

-			webApp := soundtouchweb.New()
+			// Create web app without templates (SPA mode)
+			webApp := handlers.NewWebApp()

-			r := chi.NewRouter()
-			webApp.Mount(r)
+			// 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)

@@ -53,3 +117,208 @@ func main() {
 		log.Fatal(err)
 	}
 }
+
+// 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
+	}
+
+	if rawBind != "" && rawBind != resolvedBind {
+		return rawBind
+	}
+
+	return ""
+}
+
+// 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
+	}
+
+	addrs, err := iface.Addrs()
+	if err != nil {
+		return "", fmt.Errorf("--bind %q: failed to list addresses for interface: %w", bindAddr, err)
+	}
+
+	var ipv4, ipv6 []net.IP
+
+	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 {
+	r := chi.NewRouter()
+
+	// Static assets (embedded in binary)
+	subFS, _ := fs.Sub(staticFS, "static")
+	r.Get("/static/*", http.StripPrefix("/static", http.FileServer(http.FS(subFS))).ServeHTTP)
+
+	// Serve index.html for SPA routes
+	serveIndex := func(w http.ResponseWriter, _ *http.Request) {
+		data, _ := staticFS.ReadFile("static/index.html")
+
+		w.Header().Set("Content-Type", "text/html")
+		_, _ = w.Write(data)
+	}
+
+	// WebSocket endpoint
+	r.Get("/ws", app.HandleWebSocket)
+
+	// API endpoints
+	r.Get("/api/devices", app.HandleAPIDevices)
+	r.Get("/api/device/{id}", app.HandleAPIDevice)
+	r.Post("/api/discover", func(w http.ResponseWriter, r *http.Request) {
+		app.HandleAPIDiscover(w, r)
+		// Trigger discovery
+		//nolint:contextcheck // Context is created within goroutine
+		go func() {
+			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+			defer cancel()
+
+			// Broadcast discovery start
+			app.BroadcastDiscoveryStatus("starting", len(app.Devices))
+
+			discoverDevices(ctx, app, discoveryService)
+
+			// Broadcast discovery completion and updated device list
+			app.BroadcastDiscoveryStatus("completed", len(app.Devices))
+			app.BroadcastDeviceList()
+		}()
+	})
+
+	// Device control endpoints (GET for most actions, POST for volume/bass)
+	r.Get("/api/control/{id}/{action}", app.HandleAPIControl)
+	r.Post("/api/control/{id}/{action}", app.HandleAPIControl)
+
+	// TuneIn browse, search, and playback
+	r.Get("/api/tunein/search", app.HandleTuneInSearch)
+	r.Get("/api/tunein/navigate", app.HandleTuneInNavigate)
+	r.Get("/api/tunein/navigate/*", app.HandleTuneInNavigate)
+	r.Post("/api/tunein/play/{id}", app.HandlePlayTuneIn)
+
+	// Enhanced device control endpoints
+	r.Post("/api/device-key/{id}/{key}", app.HandleDeviceKey)
+	r.Post("/api/device-volume/{id}/{volume}", app.HandleDirectVolumeControl)
+	r.Post("/api/device-power/{id}", app.HandleDevicePower)
+	r.Get("/api/device-power-status/{id}", app.HandleDevicePowerStatus)
+	r.Get("/api/device-ws/{id}", app.HandleDeviceWebSocket)
+
+	// SPA routes - serve index.html for client-side routing
+	r.Get("/", serveIndex)
+	r.Get("/devices", serveIndex)
+	r.Get("/device/*", serveIndex)
+
+	return r
+}
+
+func discoverDevices(ctx context.Context, app *handlers.WebApp, discoveryService *discovery.UnifiedDiscoveryService) {
+	log.Println("Starting device discovery...")
+
+	devices, err := discoveryService.DiscoverDevices(ctx)
+	if err != nil {
+		log.Printf("Discovery failed: %v", err)
+		app.BroadcastDiscoveryStatus("failed", len(app.Devices))
+
+		return
+	}
+
+	log.Printf("Found %d devices", len(devices))
+
+	for _, device := range devices {
+		deviceID := device.Host // Use host as unique ID for now
+
+		// Skip if we already have this device
+		if _, exists := app.Devices[deviceID]; exists {
+			app.Devices[deviceID].LastSeen = time.Now()
+			continue
+		}
+
+		// Create new device connection
+		clientConfig := &client.Config{
+			Host:    device.Host,
+			Port:    device.Port,
+			Timeout: 10 * time.Second,
+		}
+
+		soundTouchClient := client.NewClient(clientConfig)
+
+		// Get device info
+		deviceInfo, err := soundTouchClient.GetDeviceInfo()
+		if err != nil {
+			log.Printf("Failed to get device info for %s: %v", device.Host, err)
+			continue
+		}
+
+		// Create device connection
+		conn := &webtypes.DeviceConnection{
+			Client:     soundTouchClient,
+			DeviceInfo: deviceInfo,
+			LastSeen:   time.Now(),
+			Status: webtypes.DeviceStatus{
+				IsConnected:  false,
+				LastActivity: time.Now(),
+			},
+		}
+
+		// Initial status fetch asynchronously to avoid blocking discovery
+		go app.UpdateDeviceStatus(deviceID, conn)
+
+		app.Devices[deviceID] = conn
+
+		log.Printf("Added device: %s (%s) at %s", deviceInfo.Name, deviceInfo.Type, device.Host)
+	}
+}
@@ -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, "/", "_")
+}
@@ -9,9 +9,9 @@ import (
 	"testing"
 	"time"

+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/handlers"
+	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/webtypes"
 	"github.com/gesellix/bose-soundtouch/pkg/models"
-	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
-	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb/webtypes"
 	"github.com/go-chi/chi/v5"
 )

@@ -55,19 +55,22 @@ func TestSPARouting(t *testing.T) {
 			req := httptest.NewRequest("GET", tt.path, nil)
 			w := httptest.NewRecorder()

+			// Simulate SPA routing handler
 			spaHandler := func(w http.ResponseWriter, r *http.Request) {
+				// If it's an API route, let it pass through
 				if strings.HasPrefix(r.URL.Path, "/api/") || strings.HasPrefix(r.URL.Path, "/static/") || strings.HasPrefix(r.URL.Path, "/ws") {
 					http.NotFound(w, r)
 					return
 				}

+				// Serve the SPA index.html content (simulated)
 				w.Header().Set("Content-Type", "text/html")
 				w.WriteHeader(http.StatusOK)
 				w.Write([]byte(`<!doctype html>
 <html lang="en">
 <head>
    <meta charset="UTF-8" />
-    <title>SoundTouch Web</title>
+    <title>SoundTouch Control Center</title>
 </head>
 <body>
    <div id="app">SPA Content</div>
@@ -97,7 +100,7 @@ func TestSPARouting(t *testing.T) {
 }

 func TestAPIEndpoints(t *testing.T) {
-	app := soundtouchweb.NewWebApp()
+	app := handlers.NewWebApp()

 	tests := []struct {
 		name           string
@@ -124,7 +127,7 @@ func TestAPIEndpoints(t *testing.T) {
 			name:           "device API with ID",
 			path:           "/api/device/test-device",
 			method:         "GET",
-			expectedStatus: http.StatusNotFound,
+			expectedStatus: http.StatusNotFound, // Device won't exist in test
 			expectedJSON:   true,
 		},
 	}
@@ -157,6 +160,7 @@ func TestAPIEndpoints(t *testing.T) {
 					t.Errorf("Expected JSON content type, got %s", contentType)
 				}

+				// Validate JSON response structure
 				var response webtypes.APIResponse
 				if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
 					t.Errorf("Invalid JSON response: %v", err)
@@ -167,7 +171,7 @@ func TestAPIEndpoints(t *testing.T) {
 }

 func TestAPIResponseFormat(t *testing.T) {
-	app := soundtouchweb.NewWebApp()
+	app := handlers.NewWebApp()

 	req := httptest.NewRequest("GET", "/api/devices", nil)
 	w := httptest.NewRecorder()
@@ -179,6 +183,7 @@ func TestAPIResponseFormat(t *testing.T) {
 		t.Fatalf("Failed to decode JSON response: %v", err)
 	}

+	// Check API response structure
 	if !response.Success {
 		t.Errorf("Expected success=true, got success=%v", response.Success)
 	}
@@ -187,6 +192,7 @@ func TestAPIResponseFormat(t *testing.T) {
 		t.Errorf("Expected data field to be present")
 	}

+	// Data should be an empty map for no devices
 	dataMap, ok := response.Data.(map[string]interface{})
 	if !ok {
 		t.Errorf("Expected data to be a map, got %T", response.Data)
@@ -198,7 +204,7 @@ func TestAPIResponseFormat(t *testing.T) {
 }

 func TestControlAPIValidation(t *testing.T) {
-	app := soundtouchweb.NewWebApp()
+	app := handlers.NewWebApp()

 	tests := []struct {
 		name           string
@@ -243,6 +249,7 @@ func TestControlAPIValidation(t *testing.T) {
 		},
 	}

+	// Add a mock device for testing unknown action validation
 	mockDevice := &webtypes.DeviceConnection{
 		Client:     nil,
 		DeviceInfo: &models.DeviceInfo{Name: "Test Device"},
@@ -271,6 +278,7 @@ func TestControlAPIValidation(t *testing.T) {
 				t.Errorf("Test %s: Expected status %d, got %d. Response: %s", tt.name, tt.expectedStatus, w.Code, w.Body.String())
 			}

+			// Validate error response format
 			contentType := w.Header().Get("Content-Type")
 			if !strings.Contains(contentType, "application/json") {
 				t.Errorf("Expected JSON content type, got %s", contentType)
@@ -293,8 +301,9 @@ func TestControlAPIValidation(t *testing.T) {
 }

 func TestWebSocketUpgrade(t *testing.T) {
-	app := soundtouchweb.NewWebApp()
+	app := handlers.NewWebApp()

+	// Test WebSocket upgrade request
 	req := httptest.NewRequest("GET", "/ws", nil)
 	req.Header.Set("Connection", "upgrade")
 	req.Header.Set("Upgrade", "websocket")
@@ -303,11 +312,16 @@ func TestWebSocketUpgrade(t *testing.T) {

 	w := httptest.NewRecorder()

+	// The actual WebSocket upgrade will fail in test environment,
+	// but we can check that the handler exists and accepts the request
 	app.HandleWebSocket(w, req)
+
+	// In a real test environment, this would fail with a websocket upgrade error
+	// We're just checking the handler doesn't panic and processes the request
 }

 func TestJSONAPIConsistency(t *testing.T) {
-	app := soundtouchweb.NewWebApp()
+	app := handlers.NewWebApp()

 	endpoints := []string{
 		"/api/devices",
@@ -330,16 +344,19 @@ func TestJSONAPIConsistency(t *testing.T) {
 				}
 			}

+			// All API endpoints should return JSON
 			contentType := w.Header().Get("Content-Type")
 			if !strings.Contains(contentType, "application/json") {
 				t.Errorf("Endpoint %s should return JSON, got %s", endpoint, contentType)
 			}

+			// All responses should follow APIResponse structure
 			var response webtypes.APIResponse
 			if err := json.NewDecoder(w.Body).Decode(&response); err != nil {
 				t.Errorf("Endpoint %s returned invalid JSON: %v", endpoint, err)
 			}

+			// Response should have either data or error
 			if response.Success && response.Data == nil {
 				t.Errorf("Endpoint %s: success response should have data", endpoint)
 			}
@@ -0,0 +1,200 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>SoundTouch Control Center</title>
+        <link
+            href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
+            rel="stylesheet"
+        />
+        <link
+            href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.0/font/bootstrap-icons.css"
+            rel="stylesheet"
+        />
+        <link href="/static/css/app.css" rel="stylesheet" />
+    </head>
+    <body>
+        <nav class="navbar navbar-expand-lg navbar-dark">
+            <div class="container">
+                <a class="navbar-brand" href="#" onclick="showPage('devices')">
+                    <i class="bi bi-speaker"></i>
+                    SoundTouch Control
+                </a>
+                <div class="navbar-nav ms-auto">
+                    <a
+                        class="nav-link"
+                        href="#"
+                        onclick="showPage('devices')"
+                        title="Home"
+                    >
+                        <i class="bi bi-house"></i>
+                    </a>
+                    <a
+                        class="nav-link tunein-nav-link"
+                        href="#"
+                        onclick="showPage('tunein')"
+                        title="TuneIn Browse"
+                    >
+                        <img
+                            src="/static/img/tunein-mono.svg"
+                            alt="TuneIn"
+                            class="tunein-nav-icon"
+                        />
+                    </a>
+                    <a
+                        class="nav-link"
+                        href="#"
+                        onclick="discoverDevices()"
+                        title="Discover Devices"
+                    >
+                        <i class="bi bi-search"></i>
+                    </a>
+                    <button
+                        class="theme-toggle nav-link"
+                        onclick="toggleTheme()"
+                        title="Toggle Dark Mode"
+                    >
+                        <i id="theme-icon" class="bi bi-moon"></i>
+                    </button>
+                </div>
+            </div>
+        </nav>
+
+        <div class="container mt-4">
+            <!-- Device List Page -->
+            <div id="devices-page" class="page active">
+                <div
+                    class="d-flex justify-content-between align-items-center mb-4"
+                >
+                    <h2>Your SoundTouch Devices</h2>
+                    <button class="btn btn-primary" onclick="discoverDevices()">
+                        <i class="bi bi-search"></i>
+                        Discover Devices
+                    </button>
+                </div>
+
+                <div id="devices-loading" class="loading-spinner"></div>
+
+                <div id="devices-list" class="row">
+                    <!-- Device cards will be inserted here by JavaScript -->
+                </div>
+
+                <div
+                    id="no-devices"
+                    style="display: none"
+                    class="text-center py-5"
+                >
+                    <i class="bi bi-speaker display-1 text-muted"></i>
+                    <h4 class="mt-3">No Devices Found</h4>
+                    <p class="text-muted">
+                        Click "Discover Devices" to search for SoundTouch
+                        speakers on your network.
+                    </p>
+                    <button class="btn btn-primary" onclick="discoverDevices()">
+                        <i class="bi bi-search"></i>
+                        Start Discovery
+                    </button>
+                </div>
+            </div>
+
+            <!-- TuneIn Browse Page -->
+            <div id="tunein-page" class="page">
+                <div class="d-flex justify-content-between align-items-center mb-3">
+                    <h2><img src="/static/img/tunein-dark.svg" alt="TuneIn" class="tunein-heading-icon me-2" />TuneIn Browse</h2>
+                </div>
+
+                <div class="tunein-search-bar mb-3">
+                    <div class="input-group">
+                        <input
+                            type="text"
+                            id="tunein-search-input"
+                            class="form-control"
+                            placeholder="Search stations, podcasts..."
+                        />
+                        <button
+                            class="btn btn-primary"
+                            onclick="tuneInSearch(document.getElementById('tunein-search-input').value)"
+                        >
+                            <i class="bi bi-search"></i>
+                            Search
+                        </button>
+                        <button
+                            class="btn btn-outline-secondary"
+                            onclick="tuneInBrowse()"
+                            title="Browse top level"
+                        >
+                            <i class="bi bi-house"></i>
+                        </button>
+                    </div>
+                </div>
+
+                <nav id="tunein-breadcrumb" class="mb-3" style="display: none">
+                    <!-- filled by JavaScript -->
+                </nav>
+
+                <div id="tunein-results">
+                    <!-- filled by JavaScript -->
+                </div>
+            </div>
+
+            <!-- Device Control Page -->
+            <div id="device-page" class="page">
+                <div class="back-button">
+                    <button
+                        class="btn btn-outline-secondary"
+                        onclick="showPage('devices')"
+                    >
+                        <i class="bi bi-arrow-left"></i>
+                        Back to Devices
+                    </button>
+                </div>
+
+                <div id="device-content">
+                    <!-- Device control content will be inserted here by JavaScript -->
+                </div>
+            </div>
+        </div>
+
+        <footer class="footer">
+            <div class="container text-center">
+                <small>
+                    SoundTouch Web Control Interface -
+                    <a
+                        href="https://github.com/gesellix/Bose-SoundTouch"
+                        target="_blank"
+                        class="text-decoration-none"
+                    >
+                        Open Source Project
+                    </a>
+                </small>
+            </div>
+        </footer>
+
+        <!-- Toast container for notifications -->
+        <div class="toast-container"></div>
+
+        <!-- Device picker for TuneIn playback -->
+        <div class="modal fade" id="devicePickerModal" tabindex="-1" aria-labelledby="devicePickerLabel" aria-hidden="true">
+            <div class="modal-dialog modal-sm">
+                <div class="modal-content">
+                    <div class="modal-header py-2">
+                        <h6 class="modal-title" id="devicePickerLabel">
+                            <i class="bi bi-speaker me-2"></i>Play on device
+                        </h6>
+                        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+                    </div>
+                    <div class="modal-body p-2" id="devicePickerList">
+                        <!-- device buttons filled by JavaScript -->
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!-- Bootstrap JS -->
+        <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
+
+        <!-- Application JavaScript -->
+        <script src="/static/js/app.js"></script>
+    </body>
+</html>
@@ -1,5 +1,4 @@
 accounts/
-backend/
 certs/
 default/
 dns/
@@ -48,6 +48,12 @@ logread -f | grep -Ei '(marge|preset)'
 ```
 This is particularly useful for debugging preset synchronization and service redirection issues.

+For HTTPS / connection-refused debugging (e.g. `Curl 7, http 0`), drop the speaker's loopback chatter so only outbound calls remain visible:
+```bash
+logread -f | grep -v '127.0.0.1'
+```
+The speaker generates a steady stream of localhost-to-localhost HTTP traffic between its internal services; filtering it out makes the actual cloud / AfterTouch attempts (the ones that matter when diagnosing redirect or TLS issues) easy to read in real time.
+
 ---

 ## 2. Traffic Logging & Interception
@@ -35,7 +35,7 @@ soundtouch-cli --host 192.168.1.100 preset store \
 soundtouch-cli --host 192.168.1.100 preset store \
  --slot 3 \
  --source TUNEIN \
-  --location "/v1/playbook/station/s33828" \
+  --location "/v1/playback/station/s33828" \
  --name "K-LOVE Radio"
 ```

@@ -103,7 +103,7 @@ Just replace `https://open.spotify.com/` with `spotify:` and `/` with `:`.
 ### Radio Stations
 ```bash
 # TuneIn Radio
--source TUNEIN --location "/v1/playbook/station/s33828"
+--source TUNEIN --location "/v1/playback/station/s33828"

 # Internet Radio Stream
 --source LOCAL_INTERNET_RADIO --location "https://stream.example.com/jazz"
@@ -249,7 +249,7 @@ soundtouch-cli --host 192.168.1.100 preset store \
 # Kids' bedtime stories
 soundtouch-cli --host 192.168.1.100 preset store \
  --slot 3 --source TUNEIN \
-  --location "/v1/playbook/station/bedtime-stories" \
+  --location "/v1/playback/station/bedtime-stories" \
  --name "Bedtime Stories"
 ```

@@ -54,6 +54,7 @@
 * [Request Recording](REQUEST_RECORDING_CONCEPT.md)
 * [Spotify Priming Strategy](concepts/spotify-priming-strategy.md)
 * [Spotify OAuth](concepts/spotify-oauth.md)
+* [soundtouch-web Roadmap](soundtouch-web-roadmap.md)

 ## Analysis & Research
 * [API Coverage Analysis](analysis/API-COVERAGE.md)
@@ -61,6 +62,10 @@
 * [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)
@@ -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
@@ -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.
@@ -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.
@@ -0,0 +1,271 @@
+# 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.
+
+### Telnet via Docker (when not installed locally)
+
+```shell
+docker run --rm --name telnet -it --env IP=192.168.123.123 alpine:edge ash -c 'apk add -U busybox-extras && telnet $IP 17000'
+```
+
+## 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.
@@ -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`).
@@ -139,7 +139,7 @@ soundtouch-cli --host 192.168.1.10 preset store \
 soundtouch-cli --host 192.168.1.10 preset store \
  --slot 2 \
  --source TUNEIN \
-  --location "/v1/playbook/station/s33828" \
+  --location "/v1/playback/station/s33828" \
  --name "K-LOVE Radio"

 # Store internet radio
@@ -956,7 +956,7 @@ soundtouch-cli --host 192.168.1.10 station add \
 # Remove a station (use location from browse/search results)
 soundtouch-cli --host 192.168.1.10 station remove \
  --source TUNEIN \
-  --location "/v1/playbook/station/s33828"
+  --location "/v1/playback/station/s33828"
 ```

 **Workflow Example - Discover and Play New Content:**
@@ -2,6 +2,14 @@

 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.

+> ### ⚠️ Speakers connect to `:443`, AfterTouch defaults to `:8443`
+>
+> Speakers build their target URLs from Bose hostnames *without* an explicit port, so they connect on the default HTTPS port **443**. AfterTouch's built-in HTTPS listener defaults to **8443** because port 443 is privileged on most Unix systems.
+>
+> **If you do nothing, speakers will fail with `Curl 7` / connection refused and nothing will appear in the AfterTouch HTTP log.**
+>
+> Pick one of the three options under [Binding to port 443](#binding-to-port-443) below. The settings page in the web UI shows a ✅ / ❌ indicator for `:443` reachability so you can confirm the routing is in place.
+
 ---

 ## How TLS works in AfterTouch
@@ -41,9 +49,40 @@ http://<server>:8000/setup/ca.crt

 Speakers expect HTTPS on the default port 443. Since binding to port 443 requires elevated privileges, you have three options:

-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).
+1. **Port forwarding (recommended)**: Run the service on port 8443 and forward port 443 to it using `iptables` or your firewall/router. Inside an LXC/Docker container or on the host:
+
+    ```bash
+    iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 8443
+    iptables -t nat -A OUTPUT     -p tcp --dport 443 -j REDIRECT --to-port 8443
+    ```
+
+    The first rule covers traffic arriving from speakers; the second covers loopback connections from the host itself (useful for the in-built pre-flight probe).
+
+2. **Capabilities**: Grant the binary permission to bind low ports and start the listener directly on `:443`:
+
+    ```bash
+    sudo setcap 'cap_net_bind_service=+ep' ./soundtouch-service
+    ./soundtouch-service --https-port=443
+    ```
+
+3. **Reverse proxy**: Use Nginx or Caddy on `:443` in front of the service (see below).
+
+### Confirming `:443` is reachable
+
+After applying any of the options above, open the AfterTouch web UI → **Settings**. The Target Domain row will show a second line:
+
+* ✅ `:443 reachable on localhost and <IP> (forwarded to :8443)` — you're good.
+* ❌ `Speakers connect to :443 but AfterTouch listens on :8443.` — the routing is missing or not yet active.
+
+A third line follows from the browser itself, which sits on the LAN exactly where the speakers do. The browser can't distinguish an untrusted-CA TLS error from a connection refusal, so it uses timing as a heuristic: a fast error means "no listener / firewall reset", a slower one means "something answered TCP". When the server-side and browser-side checks disagree, the UI flags it — that almost always means NAT, split-horizon DNS, or a host firewall sitting between AfterTouch and the LAN.
+
+The same check runs once at service startup and prints a `[WARN]` log line if `:443` is unreachable, with the exact iptables/setcap commands for your current listener port.
+
+#### When this check is shown
+
+The `:443` indicator is only displayed when **AfterTouch's DNS interception is enabled** (Settings → "Enable DNS Discovery Server"). The check is only meaningful for the **DNS migration method**, where speakers reach AfterTouch via intercepted Bose hostnames and therefore on the implicit `:443`. The other migration method — writing direct `https://<host>:8443/...` URLs into the speaker's private config via SSH — uses the port that's literally in the URL, so `:443` is irrelevant and the check would only add noise.
+
+If you intercept Bose hostnames **outside** AfterTouch (Pi-hole, router DNS rule, `/etc/hosts` on a gateway), the UI gate above will hide the indicator. The data is still in the `GET /setup/settings` JSON response (`https_443_localhost_reachable`, `https_443_lan_reachable`, `https_443_lan_host`) if you want to inspect it directly, or you can briefly enable AfterTouch's DNS server to see the indicator render.

 ---

@@ -70,6 +109,21 @@ server {
 }
 ```

+> **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.
+
 ---

 ## Manual CA injection (advanced)
@@ -90,9 +90,13 @@ If you plan to use DNS/DHCP redirect, enable the **DNS Discovery Server** and se

 ---

-## Step 3: Enable SSH on each speaker
+## Step 3: Enable shell access on each speaker

-The migration writes updated configuration to the speaker's filesystem, which requires SSH access. Enable it once per device:
+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.
@@ -102,6 +106,12 @@ The migration writes updated configuration to the speaker's filesystem, which re

 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
@@ -124,44 +134,64 @@ If the Bose cloud is still running, Sync also fetches your account data from Bos

 ## Step 5: Migrate

-Click **Migrate** next to a device on the Devices tab to open the Migration tab. It shows SSH status, CA trust status, and connection test results before letting you apply the redirect.
+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 HTTPS and DNS connection tests](../images/ui-migration.png)
+![Migration tab showing the state card and Plan card](../images/ui-migration.png)

-Two redirect methods are available:
+### What you see at the top — the state card

-### XML redirect (recommended for first-time / testing)
+Three rows tell you the speaker's current state at a glance:

-Uploads a configuration file to the speaker via the SoundTouch Web API. This changes the application-level service URLs without touching the speaker's network configuration. It's the least invasive option.
+- **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 web UI guides you through:
-1. Previewing the config change (current vs. planned XML)
-2. Optionally installing the AfterTouch CA certificate on the speaker (requires SSH; needed for HTTPS)
-3. Applying the XML redirect
-4. Verifying the speaker can reach the local service
+### The Plan card — the happy path

-### DNS/DHCP redirect (recommended for permanent / all-device setup)
+Below the state card is the **Plan** card. For most users this is the only thing you'll touch:

-Configures the speaker to use a custom DNS server that resolves Bose cloud hostnames to the local service. This is the most robust method — it covers all Bose endpoints automatically and survives reboots.
+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.

-Requirements:
- The AfterTouch DNS server must be running and bound to **port 53** on your network. Enable it in the **Settings** tab (`DNS Discovery` → enabled).
- HTTPS is required. The web UI walks you through trusting the CA certificate on the speaker (via SSH).
+### What happens when you click Apply

-The web UI guides you through:
-1. Verifying the DNS server is running and reachable
-2. Installing the CA certificate on the speaker
-3. Configuring the speaker to use the AfterTouch DNS server
-4. Verifying DNS resolution and HTTPS connectivity
+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 migration, **power-cycle the speaker** (unplug and replug). This applies all configuration changes.
+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
@@ -176,12 +206,89 @@ Each speaker is migrated independently. You can run multiple migrations in paral

 ---

+## Alternative: CLI-driven factory-reset workflow
+
+If you prefer scripting the migration, or the wizard isn't an option (headless server, automation, batch onboarding of many speakers), `soundtouch-cli` exposes the same building blocks. The flow below is **not** an in-place migration — it factory-resets the speaker and brings it up fresh against AfterTouch, so any data Bose preserved on the device is wiped. Use this when:
+
+- You're starting from a factory-reset speaker anyway.
+- The wizard's in-place migration didn't take and you want a clean slate.
+- You're scripting setup for many speakers and want a reproducible recipe.
+
+### Prerequisites
+
+- AfterTouch service running and reachable at a stable URL (e.g., `https://soundtouch.local` from your `.env`).
+- The speaker reachable on its current IP (passed as `--host`).
+- For the AP-mode handover step, your laptop must be able to join the speaker's `Bose SoundTouch` Wi-Fi (you'll switch between home Wi-Fi and the speaker's AP).
+
+### The full sequence
+
+```bash
+# 1. Plan what the reset+pair pipeline will write (dry run, no changes yet).
+soundtouch-cli --host 192.168.1.50 setup plan \
+  --reset=true --include-pair=false \
+  --service-url='https://soundtouch.local'
+
+# 2. Trigger the factory reset. The speaker reboots into AP mode.
+soundtouch-cli --host 192.168.1.50 setup factory-reset
+
+# --- Manual step: join the speaker's Wi-Fi AP (SSID "Bose SoundTouch ...") ---
+
+# 3. Wait for the AP-mode endpoint to answer.
+soundtouch-cli setup wait-ap
+
+# 4. Push your home Wi-Fi credentials to the speaker.
+#    Run twice if the first attempt's ACK races the AP teardown — the second
+#    one is a no-op if the first succeeded.
+soundtouch-cli setup wifi-push --ssid="YourHomeSSID" --pass='your-wifi-password'
+
+# --- Manual step: switch your laptop back to the home Wi-Fi network ---
+
+# 5. Wait for the speaker to come back online on the home network.
+#    --match takes the last 4-6 hex chars of the speaker's MAC (visible on
+#    the bottom of the device).
+soundtouch-cli setup wait-online --match=42CAFE
+
+# 6. Pair the speaker with an AfterTouch account.
+#    --mode=full runs the canonical WebSocket SETUP sequence (matches the
+#    Bose app's flow); --account is the 7-digit account ID AfterTouch
+#    should attach the speaker to.
+soundtouch-cli --host 192.168.1.50 setup pair \
+  --mode=full --account=1111111 \
+  --service-url='https://soundtouch.local'
+```
+
+### Verifying the result
+
+After pairing completes:
+
+- The speaker should appear on the **Devices** tab in the web UI.
+- AUX should switch and play audio when selected.
+- Pressing presets should fetch their content from AfterTouch (the `[LOG]` rows on the service confirm).
+- TuneIn search and playback should work end-to-end.
+
+If any of these fail post-pair, see [Troubleshooting](TROUBLESHOOTING.md) — most commonly the speaker just needs a power cycle to pick up everything cleanly.
+
+### Differences vs the wizard
+
+| Aspect                              | Wizard (in-place migration)                             | CLI factory-reset workflow                              |
+|-------------------------------------|---------------------------------------------------------|---------------------------------------------------------|
+| Preserves speaker's existing state  | yes (Presets, recents, attached account)                | **no** — wipes everything                               |
+| Requires Wi-Fi-network switching    | no                                                      | yes (laptop joins speaker AP, then home network)        |
+| Scriptable / reproducible           | clickable, not scriptable                               | full bash recipe                                        |
+| Cloud-side data (Bose Marge backup) | preserved if Sync ran while cloud was alive             | not relevant — fresh account on AfterTouch              |
+| Best for                            | "I want this speaker to keep working with what's on it" | "I want a clean, reproducible setup against AfterTouch" |
+
+The wizard is still the recommended path for a one-off migration of an existing setup. The CLI workflow is the right choice when you're scripting, batching, or already starting from a reset.
+
+---
+
 ## Rollback

 If you need to undo a migration:

- **From the web UI**: Use the **Revert** action on the device — this restores the `.original` backup files created on the speaker during migration.
- **Via SSH**: The original config is backed up on the speaker with a `.original` suffix. Restore it manually if the UI is unreachable.
+- **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.

 ---
@@ -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:
@@ -393,19 +401,80 @@ 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)

 #### `GET /bmx/registry/v1/services`
 Returns available media services for device registration.

-#### `GET /bmx/tunein/v1/playbook/station/{stationID}`
+#### `GET /bmx/tunein/v1/playback/station/{stationID}`
 Provides TuneIn station playback information.

 #### `GET /bmx/tunein/v1/podcast/{podcastID}`
@@ -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

@@ -105,6 +105,62 @@ iperf3 -c 192.168.1.1  # If iperf server available

 ## 🌐 **Connection Issues**

+### ❌ Speaker logs `Curl 7, http 0` and AfterTouch sees no HTTP requests
+
+**Symptoms:**
+
+In the speaker's log (see [DEVICE-LOGGING.md](../DEVICE-LOGGING.md#1-accessing-system-logs-requires-root) for the SSH/`logread` setup — the filtered command `logread -f | grep -v '127.0.0.1'` is what you want here):
+
+```
+SimpleURLFetcher: retry needed, Curl 7, http 0
+```
+
+In the AfterTouch service log: plenty of `[DNS] Intercepted query …` lines but **zero** HTTP requests after each DNS lookup.
+
+**Cause:** speakers connect to Bose hostnames over implicit HTTPS, i.e. port **443**. AfterTouch's built-in HTTPS listener defaults to **8443** because 443 is privileged. The speaker resolves the right IP, dials `:443`, and gets connection refused — which is what `Curl 7` reports.
+
+**Verify:**
+
+```bash
+curl -ksS -o /dev/null -w "443=%{http_code}\n"  https://localhost:443/
+curl -ksS -o /dev/null -w "8443=%{http_code}\n" https://localhost:8443/
+```
+
+Expected when the misconfiguration is present: `443=000` plus a `curl: (7) Failed to connect …` line, `8443=200` (or any 3-digit code).
+
+**Fix:** route `:443` to AfterTouch's HTTPS listener — see [HTTPS-SETUP.md → Binding to port 443](HTTPS-SETUP.md#binding-to-port-443). The AfterTouch settings page shows a ✅ / ❌ indicator for `:443` reachability once the routing is in place.
+
+### ❌ Presets flash then revert to "Select a preset" after a factory reset
+
+**Symptoms:**
+
+- You factory-reset a SoundTouch (Wave / 10 / 20 / 30 / …) that was previously migrated.
+- After reconnecting it to Wi-Fi, AfterTouch sees the speaker again, but pressing a preset on the device or in the app makes the display briefly show the preset name and then revert to *"Select a preset or explore music in the SoundTouch App"*.
+- Spotify presets show the same revert unless Spotify Connect is started from the mobile app first.
+- The speaker's `/sources` is missing TUNEIN / LOCAL_INTERNET_RADIO / DEEZER / your linked Spotify account — only AUX, BLUETOOTH, AIRPLAY, the SpotifyConnectUserName placeholder, NOTIFICATION, and QPLAY appear.
+
+**Cause:**
+
+A factory reset wipes `/mnt/nv/BoseApp-Persistence/1/Marge.xml` — the file that carries the speaker's auth token for the AfterTouch (or Bose) cloud service. The migrated URL configuration is preserved (it lives in `envswitch`), so the speaker keeps talking to AfterTouch, but with no token it can't authenticate for preset playback. Separately, the device's `/sources` cache is reduced until it receives a `<sourcesUpdated/>` notification.
+
+**Fix:**
+
+1. **Re-open the Migration tab** in the AfterTouch UI. The wizard reads `/info`, sees `margeAccountUUID` is empty, and renders:
+
+   > **Current: ❌ Not paired (factory-reset or never paired) — set an ID to pair as part of Apply**
+
+   The devices list now also shows a `⚠ Not paired — re-pair` badge next to such speakers, so you don't have to remember to open the Migration tab cold.
+
+2. **Pick the previously-used account ID** from the "pick from datastore" dropdown (if AfterTouch remembers it), or click **Generate** for a fresh one.
+
+3. **Click Apply.** The wizard runs `pair-account` along with the rest, recreating `Marge.xml` on the device with the chosen ID.
+
+4. **Click Data Sync** (Tab 3). AfterTouch persists the speaker's presets/recents/sources and posts a `<sourcesUpdated/>` notification to the device — the missing TUNEIN / LOCAL_INTERNET_RADIO / DEEZER / linked Spotify entries reappear in `/sources` automatically.
+
+5. Press a preset. It should play normally.
+
+If presets still won't play after step 5, capture `logread -f | grep -v '127.0.0.1:'` on the speaker (see [DEVICE-LOGGING.md](../DEVICE-LOGGING.md#1-accessing-system-logs-requires-root)) while pressing the preset and file an issue with the snippet — the lines around the failed playback name the deeper cause.
+
 ### ❌ "Connection refused"

 **Symptoms:**
@@ -309,7 +309,7 @@ Now Playing:
  Track: K-LOVE Radio
  
 Content Details:
-  Location: /v1/playbook/station/s33828
+  Location: /v1/playback/station/s33828
 ```

 **LOCAL_INTERNET_RADIO:**
@@ -341,7 +341,7 @@ go run ./cmd/soundtouch-cli --host 192.168.1.100 play now --verbose
 Shows additional information:
 ```
 Content Details:
-  Location: /v1/playbook/station/s33828
+  Location: /v1/playback/station/s33828
  Content Type: stationurl
  Item Name: K-LOVE Radio
  Presetable: true
@@ -367,7 +367,7 @@ Content Details:
 | **Spotify Album** | `spotify:album:ID` | `spotify:album:4aawyAB9vmqN3uQ7FjRGTy` |
 | **Spotify Artist** | `spotify:artist:ID` | `spotify:artist:6APm8EjxOHSYM5B4i3vT3q` |
 | **Spotify Track** | `spotify:track:ID` | `spotify:track:17GmwQ9Q3MTAz05OokmNNB` |
-| **TUNEIN Radio** | `/v1/playbook/station/ID` | `/v1/playbook/station/s33828` |
+| **TUNEIN Radio** | `/v1/playback/station/ID` | `/v1/playback/station/s33828` |
 | **Internet Radio** | `URL or encoded URL` | `https://stream.example.com/radio` |
 | **STORED_MUSIC** | `Container ID` | `6_a2874b5d_4f83d999` |
 | **LOCAL_MUSIC** | `album:ID` or `track:ID` | `album:983`, `track:2579` |
@@ -0,0 +1,139 @@
+# soundtouch-web: remaining features
+
+Four features complete the parity gap between soundtouch-web and the Stockholm
+app's local-control functionality. Everything else in Stockholm (OAuth flows,
+setup wizard, service account linking, onboarding, analytics) is cloud
+infrastructure that is either shut down or already handled by soundtouch-service.
+
+---
+
+## 1. Seek / scrub
+
+The progress bar already renders `NowPlaying.Time.Position` / `NowPlaying.Time.Total`
+with a live 1 s ticker. What's missing is the ability to click or drag it to seek.
+
+**Device API:** `POST /seek` with body `<seek deviceID="…" type="TIME_VALUE"><time>30</time></seek>`
+
+**Backend:**
+- Add `POST /api/device-seek/{id}/{seconds}` handler in `handler.go`
+- Guard on `NowPlaying.SeekSupported.Value` — return 400 if the stream doesn't
+  support seeking (radio, for example)
+
+**Frontend (`NowPlaying.js`):**
+- Replace the static `<div class="progress-bar">` with a `<input type="range">`
+- `onInput` updates local state for smooth scrubbing; `onChange` (pointer up)
+  fires `api.seek(deviceId, seconds)`
+- Pause the 1 s ticker while the user is dragging to avoid fighting the input
+
+**Client method to add (or verify exists):**
+```go
+func (c *Client) Seek(positionSeconds int) error {
+    // POST /seek
+}
+```
+
+---
+
+## 2. Favorites
+
+Mark or unmark the currently playing track as a favourite directly from the
+Now Playing card.
+
+**Device API:**
+- `GET /favorites` — returns `<favorites>` list
+- `POST /favorites` — adds current content item as a favourite
+- `DELETE /favorites/{id}` — removes a favourite by ID
+
+**Backend:**
+- `GET /api/device-favorites/{id}` — fetch favourites list
+- `POST /api/device-favorites/{id}` — add current now-playing item as favourite
+- `DELETE /api/device-favorites/{id}/{favId}` — remove a favourite
+
+**Frontend:**
+- Heart button (♡ / ♥) in `NowPlaying.js`, next to the source label
+- On mount (or when `nowPlaying` changes) fetch favourites and check whether
+  the current `ContentItem.Location` is already in the list
+- Toggle on click; optimistic UI update before the round-trip
+
+**Note:** Not all sources support favourites. Check
+`NowPlaying.FavoriteEnabled` — if the field is nil/absent, hide the button.
+
+---
+
+## 3. Device settings panel
+
+A lightweight settings page per device covering the two most useful knobs:
+rename and network/firmware info.
+
+**Device API:**
+- `GET /info` — device info (already fetched; stored as `DeviceInfo`)
+- `POST /name` with body `<name>New Name</name>` — rename the device
+- `GET /networkInfo` — IP, MAC, SSID, signal strength
+- `GET /swUpdateStatus` — current firmware version and whether an update is
+  available (not all devices expose this)
+
+**Backend:**
+- `POST /api/device-rename/{id}` — body `{"name":"…"}`; calls `POST /name`
+- `GET /api/device-network/{id}` — proxies `GET /networkInfo`
+- Optionally `GET /api/device-update-status/{id}` — proxies `GET /swUpdateStatus`
+
+**Frontend:**
+- Small ⚙ icon button in `DeviceDetail`'s page header (next to the power button)
+- Navigates to a new `page === 'settings'` state in `App`; passes `deviceId`
+- `DeviceSettings.js` component: editable name field (save on blur/Enter),
+  read-only network info card, optional firmware version badge
+- Back button returns to `'device'` page
+
+---
+
+## 4. Render stereo pairs as a single device
+
+Today soundtouch-web shows the two halves of a stereo pair (formed via
+`/addGroup` — see issue #252) as independent entries in the device list. The
+Bose app collapsed a paired ST10 set into one "L+R" entry; restoring that
+presentation closes the perception gap BirdyBA flagged at
+<https://github.com/gesellix/Bose-SoundTouch/issues/252#issuecomment-4458140305>.
+
+**Device API:**
+- `GET /getGroup` on each speaker — returns the current `<group>` with
+  `<masterDeviceId>` + `<roles>` (each `<groupRole>` carries the speaker's
+  deviceId, role `LEFT|RIGHT`, and ipAddress)
+- Empty `<group/>` means the speaker is standalone
+- Querying the master and slave returns the same `<group>` payload, so either
+  side is sufficient to detect the pair
+
+**Backend:**
+- During device-list assembly, call `GET /getGroup` for each discovered device
+  in parallel (matches the propagation pattern already used by
+  `soundtouch-cli group create` in `cmd/soundtouch-cli/cmd_group.go`)
+- Bucket devices by `<masterDeviceId>` — each bucket emits one entry in the
+  list response. Standalone devices stay as their own bucket-of-one
+- Expose pair metadata on the list entry so the UI can render role chips
+  (`L`/`R`) and resolve role → physical device for actions
+
+**Frontend:**
+- Device list collapses paired devices into one card titled with both names
+  (e.g. `"Wohnzimmer L+R"`) and role chips
+- Clicking the card opens a device-detail page that exposes both per-role
+  status and a "Dissolve pair" action (DELETE flow, already wired in
+  `soundtouch-cli group remove` and in fakespeaker's `/removeGroup` GET)
+- Standalone speakers continue to render as today
+
+**Note:** Pair lifecycle (create / rename / remove) already works
+end-to-end — `pkg/client` group endpoints + `cmd/soundtouch-cli/cmd_group.go`,
+covered by tests in `cmd/soundtouch-cli/cmd_group_test.go` and exercisable
+against the fake speaker's group routes
+(`pkg/service/testing/fakespeaker/fakespeaker.go`). This task is purely about
+presentation in soundtouch-web's device list — no protocol work required.
+
+---
+
+## Decide later
+
+| Feature                                | Reason                                                             |
+|----------------------------------------|--------------------------------------------------------------------|
+| Spotify / Pandora / Amazon browsing UI | Requires Bose cloud (shutting down); handled by soundtouch-service |
+| Setup wizard (WiFi, Marge migration)   | Already in soundtouch-service setup flows                          |
+| OAuth / login flows                    | Cloud-dependent; not needed for local network access               |
+| AirPlay / Bluetooth pairing UI         | Device handles this independently; no SoundTouch Web API           |
+| Onboarding, help, analytics            | Not relevant for a local control tool                              |
@@ -83,7 +83,7 @@ go run main.go 192.168.1.100
  🎯 Using generic ContentItem selection...
      Content: K-LOVE Radio
      Source: TUNEIN
-      Location: /v1/playbook/station/s33828
+      Location: /v1/playback/station/s33828
  ✅ Successfully selected content using ContentItem

 ✅ Content selection demo completed!
@@ -209,7 +209,7 @@ func demoGenericContentItem(c *client.Client) error {
 	contentItem := &models.ContentItem{
 		Source:        "TUNEIN",
 		Type:          "stationurl",
-		Location:      "/v1/playbook/station/s33828", // K-LOVE Radio
+		Location:      "/v1/playback/station/s33828", // K-LOVE Radio
 		SourceAccount: "",
 		IsPresetable:  true,
 		ItemName:      "K-LOVE Radio",
@@ -140,7 +140,7 @@ err := client.AddStation("TUNEIN", "", "c121508", "Jazz FM")
 // Remove station from collection
 contentItem := &models.ContentItem{
    Source:   "TUNEIN",
-    Location: "/v1/playbook/station/s33828",
+    Location: "/v1/playback/station/s33828",
 }
 err := client.RemoveStation(contentItem)
 ```
@@ -2,7 +2,7 @@ module navigation-station-demo

 go 1.26.3

-require github.com/gesellix/bose-soundtouch v0.71.2
+require github.com/gesellix/bose-soundtouch v0.78.0

 require github.com/gorilla/websocket v1.5.3 // indirect

@@ -71,7 +71,7 @@ go run . 192.168.1.100

    2. K-LOVE Radio
       Source: TUNEIN
-       Location: /v1/playbook/station/s33828
+       Location: /v1/playback/station/s33828
       Created: 2024-01-15 09:15:00

  🆓 Available slots: [3 4 5 6]
@@ -179,7 +179,7 @@ Location: "spotify:track:17GmwQ9Q3MTAz05OokmNNB"

 ```go
 // TuneIn
-Location: "/v1/playbook/station/s33828"
+Location: "/v1/playback/station/s33828"

 // Internet Radio
 Location: "https://stream.example.com/radio"
@@ -2,7 +2,7 @@ module preset-management-example

 go 1.26.3

-require github.com/gesellix/bose-soundtouch v0.71.2
+require github.com/gesellix/bose-soundtouch v0.78.0

 require github.com/gorilla/websocket v1.5.3 // indirect

@@ -226,7 +226,7 @@ func storeRadioStation(c *client.Client) error {
 	radioContent := &models.ContentItem{
 		Source:        "TUNEIN",
 		Type:          "stationurl",
-		Location:      "/v1/playbook/station/s33828", // K-LOVE
+		Location:      "/v1/playback/station/s33828", // K-LOVE
 		SourceAccount: "",
 		IsPresetable:  true,
 		ItemName:      "K-LOVE Radio",
@@ -329,7 +329,7 @@ func demonstrateWebSocketEvents(c *client.Client) error {
 		testContent := &models.ContentItem{
 			Source:        "TUNEIN",
 			Type:          "stationurl",
-			Location:      "/v1/playbook/station/s25111", // BBC Radio 1
+			Location:      "/v1/playback/station/s25111", // BBC Radio 1
 			SourceAccount: "",
 			IsPresetable:  true,
 			ItemName:      "BBC Radio 1",
@@ -3,6 +3,7 @@ module github.com/gesellix/bose-soundtouch
 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,18 +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/term v0.42.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
 )
@@ -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=
@@ -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
 }
@@ -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))
@@ -1380,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{
@@ -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)
+	}
+}
@@ -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
 }
@@ -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,
@@ -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)
@@ -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
@@ -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
+}
@@ -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)

@@ -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,
@@ -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))
@@ -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()
+}
@@ -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)
+	}
+}
@@ -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
@@ -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))
 	}
@@ -10,6 +10,15 @@ type Group struct {
 	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.
@@ -597,6 +597,16 @@ type ServiceDeviceInfo struct {
 	DiscoveryMethod     string             `json:"discovery_method,omitempty"`
 	AccountID           string             `json:"account_id,omitempty"`
 	Components          []ServiceComponent `json:"components,omitempty" xml:"-"`
+	// CreatedOn is the ISO8601 timestamp the device was first
+	// registered against the account. Preserved across renames so
+	// AfterTouch's PUT response matches real Bose's "first paired
+	// in 2017" semantics rather than rewriting `now()` on every
+	// update. Empty for never-persisted records.
+	CreatedOn string `json:"created_on,omitempty" xml:"-"`
+	// UpdatedOn is the ISO8601 timestamp of the most recent change
+	// to the device record (rename, IP refresh, …). Refreshed by
+	// every SaveDeviceInfo write that mutates a known device.
+	UpdatedOn string `json:"updated_on,omitempty" xml:"-"`
 }

 // ServiceComponent represents a hardware or software component of a device.
@@ -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)
 	}
@@ -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) {
@@ -20,7 +20,7 @@ import (
 // TuneIn endpoint templates used to resolve station and stream URLs.
 const (
 	TuneInDescribe     = "https://opml.radiotime.com/describe.ashx?id=%s"
-	TuneInStream       = "http://opml.radiotime.com/Tune.ashx?id=%s&formats=mp3,aac,ogg"
+	TuneInStream       = "http://opml.radiotime.com/Tune.ashx?id=%s&formats=mp3,aac,ogg,hls"
 	TuneInNavigateAshx = "http://opml.radiotime.com/?render=json"
 	TuneInSearchAPI    = "https://api.radiotime.com/profiles?fulltextsearch=true&version=1.3&query="
 )
@@ -299,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"
@@ -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")
 	}
@@ -69,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
@@ -113,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)
@@ -131,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)
@@ -150,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()
@@ -157,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
 	}
@@ -199,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
 	}
@@ -219,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
 		}
 	}
@@ -241,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
 	}
@@ -263,6 +565,8 @@ func (ds *DataStore) getDeviceInfoNoLock(account, device string) (*models.Servic
 			MacAddress string `xml:"macAddress"`
 		} `xml:"networkInfo"`
 		DiscoveryMethod string `xml:"discoveryMethod"`
+		CreatedOn       string `xml:"createdOn,omitempty"`
+		UpdatedOn       string `xml:"updatedOn,omitempty"`
 	}

 	if err := xml.Unmarshal(data, &info); err != nil {
@@ -275,6 +579,8 @@ func (ds *DataStore) getDeviceInfoNoLock(account, device string) (*models.Servic
 		ProductCode:     fmt.Sprintf("%s %s", info.Type, info.ModuleType),
 		Name:            info.Name,
 		DiscoveryMethod: info.DiscoveryMethod,
+		CreatedOn:       info.CreatedOn,
+		UpdatedOn:       info.UpdatedOn,
 	}

 	for _, comp := range info.Components {
@@ -487,6 +793,8 @@ func (ds *DataStore) parseDeviceInfoFile(path string) (*models.ServiceDeviceInfo
 			MacAddress string `xml:"macAddress"`
 		} `xml:"networkInfo"`
 		DiscoveryMethod string `xml:"discoveryMethod"`
+		CreatedOn       string `xml:"createdOn,omitempty"`
+		UpdatedOn       string `xml:"updatedOn,omitempty"`
 	}

 	if err := xml.Unmarshal(data, &info); err != nil {
@@ -533,7 +841,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
@@ -597,7 +905,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
 	}

@@ -661,11 +969,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.
@@ -675,7 +983,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
@@ -770,7 +1078,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
 	}

@@ -869,7 +1177,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
 	}

@@ -890,6 +1198,8 @@ func (ds *DataStore) SaveDeviceInfo(account, device string, info *models.Service
 		Components      []componentXML   `xml:"components>component"`
 		NetworkInfo     []NetworkInfoXML `xml:"networkInfo"`
 		DiscoveryMethod string           `xml:"discoveryMethod,omitempty"`
+		CreatedOn       string           `xml:"createdOn,omitempty"`
+		UpdatedOn       string           `xml:"updatedOn,omitempty"`
 	}

 	// Parsing product code back to type and moduleType (best effort)
@@ -901,6 +1211,8 @@ func (ds *DataStore) SaveDeviceInfo(account, device string, info *models.Service
 		Type:            devType,
 		ModuleType:      moduleType,
 		DiscoveryMethod: info.DiscoveryMethod,
+		CreatedOn:       info.CreatedOn,
+		UpdatedOn:       info.UpdatedOn,
 	}

 	if ix.DiscoveryMethod == "" {
@@ -964,6 +1276,21 @@ func (ds *DataStore) mergeWithExistingDeviceInfo(account, device string, info *m
 	if info.DiscoveryMethod == "" {
 		info.DiscoveryMethod = existing.DiscoveryMethod
 	}
+
+	// CreatedOn is set once at first persistence and never re-derived
+	// from inbound data — preserve unconditionally so the
+	// "first-paired" timestamp survives renames, IP refreshes, etc.
+	// UpdatedOn is the opposite: every write that reaches here is by
+	// definition an update, so callers that want it refreshed must
+	// set it explicitly. If they didn't, fall back to the existing
+	// value (better than a regression to empty).
+	if existing.CreatedOn != "" {
+		info.CreatedOn = existing.CreatedOn
+	}
+
+	if info.UpdatedOn == "" {
+		info.UpdatedOn = existing.UpdatedOn
+	}
 }

 func (ds *DataStore) parseProductCode(productCode string) (string, string) {
@@ -1031,7 +1358,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
 	}

@@ -1053,11 +1380,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
 	}
@@ -1077,7 +1404,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.
@@ -1108,7 +1435,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
 		}
@@ -1214,7 +1541,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()
@@ -1254,6 +1581,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]
@@ -1293,11 +1631,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)
 		}
@@ -1306,13 +1642,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
 	}

@@ -1607,7 +1988,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
 	}
@@ -1618,7 +1999,7 @@ func (ds *DataStore) GetETagForPresets(account, device string) int64 {
 // 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 := os.Stat(path)
+	_, err := ds.rootStat(path)

 	return err == nil
 }
@@ -1627,7 +2008,7 @@ func (ds *DataStore) HasConfiguredSources(account, device string) bool {
 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
 	}
@@ -1639,7 +2020,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
 	}
@@ -1663,7 +2044,7 @@ func (ds *DataStore) GetETagForAccount(account, device string) string {
 	if device != "" {
 		deviceDir := ds.AccountDeviceDir(account, device)
 		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
 			}
@@ -1680,13 +2061,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)
+	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
 				}
@@ -1724,6 +2105,28 @@ type Settings struct {
 	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.
@@ -1733,11 +2136,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
 	}
@@ -1756,7 +2159,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)
 	}

@@ -1773,7 +2176,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
 	}

@@ -1791,7 +2194,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
 	}

@@ -1857,7 +2260,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)
 	}

@@ -1883,11 +2286,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
 	}
@@ -1907,11 +2310,11 @@ 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.
@@ -1923,7 +2326,7 @@ func (ds *DataStore) groupFilePath(account, groupID string) string {
 func (ds *DataStore) generateGroupID(account string) string {
 	for {
 		id := fmt.Sprintf("%07d", rand.Int63n(10_000_000)) //nolint:gosec
-		if !exists(ds.groupFilePath(account, id)) {
+		if !ds.rootExists(ds.groupFilePath(account, id)) {
 			return id
 		}
 	}
@@ -1936,7 +2339,7 @@ func (ds *DataStore) GetGroupForDevice(account, deviceID string) (*models.Group,

 	dir := ds.AccountDevicesDir(account)

-	entries, err := os.ReadDir(dir)
+	entries, err := ds.rootReadDir(dir)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return nil, ErrGroupNotFound
@@ -1950,7 +2353,7 @@ func (ds *DataStore) GetGroupForDevice(account, deviceID string) (*models.Group,
 			continue
 		}

-		data, readErr := os.ReadFile(filepath.Join(dir, e.Name()))
+		data, readErr := ds.rootReadFile(filepath.Join(dir, e.Name()))
 		if readErr != nil {
 			continue
 		}
@@ -1976,7 +2379,7 @@ func (ds *DataStore) AddGroup(account string, group *models.Group) (string, erro
 	defer ds.fileMutex.Unlock()

 	dir := ds.AccountDevicesDir(account)
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return "", err
 	}

@@ -1998,7 +2401,7 @@ func (ds *DataStore) ModifyGroup(account, groupID, newName string) (*models.Grou

 	path := ds.groupFilePath(account, groupID)

-	data, err := os.ReadFile(path)
+	data, err := ds.rootReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
 			return nil, fmt.Errorf("group %s not found", groupID)
@@ -2031,7 +2434,7 @@ func (ds *DataStore) DeleteGroup(account, groupID string) error {
 	ds.fileMutex.Lock()
 	defer ds.fileMutex.Unlock()

-	err := os.Remove(ds.groupFilePath(account, groupID))
+	err := ds.rootRemove(ds.groupFilePath(account, groupID))
 	if os.IsNotExist(err) {
 		return fmt.Errorf("group %s not found", groupID)
 	}
@@ -2047,11 +2450,11 @@ func (ds *DataStore) SaveTuneInFavorite(stationID string) error {
 	}

 	dir := ds.safeJoin("tunein", "favorites")
-	if err := os.MkdirAll(dir, 0755); err != nil {
+	if err := ds.rootMkdirAll(dir, 0755); err != nil {
 		return err
 	}

-	return os.WriteFile(ds.safeJoin("tunein", "favorites", stationID), nil, 0644)
+	return ds.rootWriteFile(ds.safeJoin("tunein", "favorites", stationID), nil, 0644)
 }

 // DeleteTuneInFavorite removes a previously saved TuneIn favorite marker file.
@@ -2061,7 +2464,7 @@ func (ds *DataStore) DeleteTuneInFavorite(stationID string) error {
 		return nil
 	}

-	err := os.Remove(ds.safeJoin("tunein", "favorites", stationID))
+	err := ds.rootRemove(ds.safeJoin("tunein", "favorites", stationID))
 	if os.IsNotExist(err) {
 		return nil
 	}
@@ -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)
+	}
+}
@@ -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)
 	}
 }
@@ -21,7 +21,7 @@ func TestHandleBMXRegistry_DNSDependent(t *testing.T) {
 	ds := datastore.NewDataStore(tempDir)
 	_ = ds.Initialize()

-	localURL := "https://soundtouch.local"
+	localURL := "https://127.0.0.1"
 	server := NewServer(ds, nil, localURL, false, false, false)

 	t.Run("DNSEnabled_UsesBoseURL", func(t *testing.T) {
@@ -25,6 +25,7 @@ func TestDNSSettingsValidation(t *testing.T) {

 	// Test Case 1: Enable DNS with empty upstream (should fallback to system DNS)
 	update := map[string]interface{}{
+		"server_url":    "http://localhost:8001",
 		"dns_enabled":   true,
 		"dns_upstream":  "",
 		"dns_bind_addr": ":5353",
@@ -55,6 +56,7 @@ func TestDNSSettingsValidation(t *testing.T) {
 	// Test Case 2: Enable DNS with valid upstream
 	// Using a random port to avoid conflicts and ensure it's fast
 	updateValid := map[string]interface{}{
+		"server_url":    "http://localhost:8001",
 		"dns_enabled":   true,
 		"dns_upstream":  "8.8.8.8",
 		"dns_bind_addr": "127.0.0.1:0", // Random port
@@ -173,14 +173,28 @@ func (s *Server) HandleOrionToken(w http.ResponseWriter, _ *http.Request) {
 	}
 }

-// HandleOrionPlayback returns Orion playback information.
+// HandleOrionPlayback returns Orion playback information for the
+// /core02/svc-bmx-adapter-orion/prod/orion/station?data=... endpoint
+// the speaker reaches by following its stored LOCAL_INTERNET_RADIO
+// preset's `location` attribute. The `data` query string is the
+// base64-encoded JSON blob (streamUrl/imageUrl/name) that the speaker
+// constructed when the preset was first saved; we just decode and
+// rewrap it into the Bose BmxPlaybackResponse shape via
+// bmx.PlayCustomStream.
+//
+// Requires a Bearer token in the `Authorization` header — same as
+// the rest of the BMX playback surface (TuneIn variants and the
+// orion token endpoint). Real speakers obtain the token via
+// POST /core02/svc-bmx-adapter-orion/prod/orion/token (HandleOrionToken)
+// before they ever follow a LOCAL_INTERNET_RADIO preset, so this
+// check shouldn't cost any legitimate caller.
 func (s *Server) HandleOrionPlayback(w http.ResponseWriter, r *http.Request) {
 	if r.Header.Get("Authorization") == "" {
 		s.writeBMXUnauthorized(w)
 		return
 	}

-	data := chi.URLParam(r, "data")
+	data := r.URL.Query().Get("data")

 	resp, err := bmx.PlayCustomStream(data)
 	if err != nil {
@@ -87,7 +87,13 @@ func TestOrionPlayback(t *testing.T) {
 	// Base64 encoded: {"streamUrl": "http://example.com/stream", "imageUrl": "http://example.com/img.jpg", "name": "Test Orion"}
 	data := "eyJzdHJlYW1VcmwiOiAiaHR0cDovL2V4YW1wbGUuY29tL3N0cmVhbSIsICJpbWFnZVVybCI6ICJodHRwOi8vZXhhbXBsZS5jb20vaW1nLmpwZyIsICJuYW1lIjogIlRlc3QgT3Jpb24ifQ=="

-	req, _ := http.NewRequest("POST", ts.URL+"/bmx/orion/v1/playback/station/"+data, nil)
+	// Speakers reach this endpoint by following the `location` attribute
+	// stored in a LOCAL_INTERNET_RADIO preset's contentItem — a GET to
+	// the upstream path with `data` as a query string. The data is
+	// already base64-URL-safe; passing it raw mirrors what the speaker
+	// emits (Go's url package re-encodes any `=` padding for transport).
+	req, _ := http.NewRequest("GET",
+		ts.URL+"/core02/svc-bmx-adapter-orion/prod/orion/station?data="+url.QueryEscape(data), nil)
 	req.Header.Set("Authorization", "Bearer mock-token")
 	res, err := http.DefaultClient.Do(req)
 	if err != nil {
@@ -165,7 +171,7 @@ func TestBMXUnauthorized(t *testing.T) {
 		{"GET", "/bmx/tunein/v1/playback/station/s123"},
 		{"GET", "/bmx/tunein/v1/playback/episodes/p123"},
 		{"GET", "/bmx/tunein/v1/playback/episode/p123"},
-		{"POST", "/bmx/orion/v1/playback/station/data"},
+		{"GET", "/core02/svc-bmx-adapter-orion/prod/orion/station?data=AAAA"},
 	}

 	for _, tc := range paths {
@@ -2,14 +2,38 @@ package handlers

 import (
 	"fmt"
+	"html"
 	"net/http"
 	"os"
-	"path/filepath"
 	"strings"
+	"sync"

 	"github.com/russross/blackfriday/v2"
 )

+var (
+	docsRootOnce sync.Once
+	docsRoot     *os.Root
+)
+
+// docsRootHandle returns a *os.Root anchored at the on-disk "docs" directory.
+// All file reads from HandleDocs go through it so the Go runtime guarantees
+// containment regardless of what HTTP path the caller sends — CodeQL also
+// recognises *os.Root.* as a path-traversal sanitiser.
+func docsRootHandle() *os.Root {
+	docsRootOnce.Do(func() {
+		r, err := os.OpenRoot("docs")
+		if err != nil {
+			// Fall back to nil; HandleDocs degrades to 404 below.
+			return
+		}
+
+		docsRoot = r
+	})
+
+	return docsRoot
+}
+
 // HandleDocs returns a handler for serving documentation files as HTML.
 func (s *Server) HandleDocs(w http.ResponseWriter, r *http.Request) {
 	path := strings.TrimPrefix(r.URL.Path, "/docs")
@@ -19,21 +43,23 @@ func (s *Server) HandleDocs(w http.ResponseWriter, r *http.Request) {
 		path = "guides/SURVIVAL-GUIDE.md"
 	}

-	// Ensure we only serve files from the docs directory
-	filePath := filepath.Join("docs", path)
-	if !strings.HasPrefix(filepath.Clean(filePath), "docs") {
-		http.Error(w, "Forbidden", http.StatusForbidden)
+	root := docsRootHandle()
+	if root == nil {
+		http.Error(w, "Documentation not available", http.StatusServiceUnavailable)
 		return
 	}

-	content, err := os.ReadFile(filePath)
+	content, err := root.ReadFile(path)
 	if err != nil {
+		// *os.Root.ReadFile rejects absolute paths and ".." segments at the
+		// runtime level, so any failure here is either "not found" or
+		// "traversal attempt blocked" — both 404 from the user's view.
 		http.Error(w, "File not found", http.StatusNotFound)
 		return
 	}

 	// Load sidebar (SUMMARY.md)
-	summaryContent, _ := os.ReadFile(filepath.Join("docs", "SUMMARY.md"))
+	summaryContent, _ := root.ReadFile("SUMMARY.md")

 	sidebar := ""
 	if len(summaryContent) > 0 {
@@ -52,7 +78,12 @@ func (s *Server) HandleDocs(w http.ResponseWriter, r *http.Request) {
 	// Render markdown to HTML
 	output := blackfriday.Run(content)

-	// Wrap in a documentation template with sidebar
+	// Wrap in a documentation template with sidebar. The user-supplied path
+	// is escaped before interpolation; the sidebar and rendered markdown
+	// output are server-controlled (loaded from local files) and may
+	// legitimately contain HTML.
+	titleSafe := html.EscapeString(path)
+
 	w.Header().Set("Content-Type", "text/html")
 	_, _ = fmt.Fprintf(w, `<!DOCTYPE html>
 <html>
@@ -91,7 +122,7 @@ func (s *Server) HandleDocs(w http.ResponseWriter, r *http.Request) {
        </div>
   	</div>
 </body>
-</html>`, path, sidebar, output)
+</html>`, titleSafe, sidebar, output)
 }

 // fixSidebarLinks ensures that relative links in the SUMMARY.md (sidebar)
@@ -289,13 +289,32 @@ func (s *Server) HandleMargePowerOn(w http.ResponseWriter, r *http.Request) {
 		}
 	}

-	if deviceIP != "" {
-		go s.PrimeDeviceWithSpotify(deviceIP)
-	} else {
-		// Fallback to remote address if IP is missing from XML
-		if host, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
-			go s.PrimeDeviceWithSpotify(host)
-		}
+	// Prefer the TCP source address over the body's self-reported IP for
+	// any outbound credential push. The body field is attacker-controllable
+	// (a malicious LAN-resident speaker can set it to any value), while
+	// r.RemoteAddr is the actual peer — and if the service runs behind a
+	// trusted reverse proxy, the TrustedRealIP middleware has already
+	// rewritten it from X-Real-IP / X-Forwarded-For. We log when the two
+	// disagree so the discrepancy is investigable but never trust the body.
+	remoteHost := ""
+	if h, _, err := net.SplitHostPort(r.RemoteAddr); err == nil {
+		remoteHost = h
+	}
+
+	if deviceIP != "" && remoteHost != "" && deviceIP != remoteHost {
+		log.Printf("[Marge] power_on body IP %q differs from TCP source %q for device %s — using TCP source for credential push",
+			deviceIP, remoteHost, deviceID)
+	}
+
+	target := remoteHost
+	if target == "" {
+		// RemoteAddr was unparseable (shouldn't happen under net/http) —
+		// fall back to the body so we don't silently skip the push.
+		target = deviceIP
+	}
+
+	if target != "" {
+		go s.PrimeDeviceWithSpotify(target)
 	}

 	w.WriteHeader(http.StatusOK)
@@ -569,7 +588,7 @@ func (s *Server) HandleMargeAddDevice(w http.ResponseWriter, r *http.Request) {
 		return
 	}

-	deviceID, data, err := marge.AddDeviceToAccount(s.ds, account, body)
+	deviceID, data, err := marge.AddDeviceToAccount(s.ds, account, body, r.RemoteAddr)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
@@ -581,6 +600,74 @@ func (s *Server) HandleMargeAddDevice(w http.ResponseWriter, r *http.Request) {
 	_, _ = w.Write(data)
 }

+// HandleMargeUpdateDevice handles the speaker's rename PUT against
+// /streaming/account/{account}/device/{device}. The speaker fires
+// this whenever the user renames it via the Bose App or via
+// `soundtouch-cli name set`; before this handler existed AfterTouch
+// returned 502, the speaker retried in a loop, and the App showed
+// the rename hanging indefinitely (issue #285).
+//
+// The expected payload mirrors the POST shape:
+//
+//	<device deviceid="DEVID"><name>NEW</name><macaddress>DEVID</macaddress></device>
+//
+// AddDeviceToAccount is already an upsert via ds.SaveDeviceInfo, so
+// rather than introduce a parallel UpdateDevice function we route
+// the PUT through the same persistence path. The semantic delta is
+// purely in the HTTP envelope: 200 (not 201), no Location header,
+// and the deviceID in the body has to match the URL — a mismatch
+// means the speaker is targeting the wrong record and we refuse
+// rather than silently re-key.
+func (s *Server) HandleMargeUpdateDevice(w http.ResponseWriter, r *http.Request) {
+	account := chi.URLParam(r, "account")
+	if !validatePathID(account) {
+		http.Error(w, "Invalid account ID", http.StatusBadRequest)
+		return
+	}
+
+	device := chi.URLParam(r, "device")
+	if !validatePathID(device) {
+		http.Error(w, "Invalid device ID", http.StatusBadRequest)
+		return
+	}
+
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "Failed to read body", http.StatusInternalServerError)
+		return
+	}
+
+	// Validate body deviceID against the URL segment *before* the
+	// upsert in AddDeviceToAccount runs — otherwise a mismatched PUT
+	// would still persist a row for the body's deviceID before the
+	// 400 response, leaving spurious state in the datastore.
+	var probe struct {
+		DeviceID string `xml:"deviceid,attr"`
+	}
+	if xmlErr := xml.Unmarshal(body, &probe); xmlErr != nil {
+		http.Error(w, xmlErr.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if probe.DeviceID != device {
+		http.Error(w,
+			fmt.Sprintf("device ID in body (%q) does not match URL (%q)", probe.DeviceID, device),
+			http.StatusBadRequest)
+
+		return
+	}
+
+	_, data, err := marge.AddDeviceToAccount(s.ds, account, body, r.RemoteAddr)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/vnd.bose.streaming-v1.2+xml")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write(data)
+}
+
 // HandleMargeRemovePreset removes a preset for the specified account and device.
 func (s *Server) HandleMargeRemovePreset(w http.ResponseWriter, r *http.Request) {
 	account := chi.URLParam(r, "account")
@@ -64,12 +64,16 @@ func TestMargeCreateAccount(t *testing.T) {
 		t.Errorf("Expected 7-digit ID, got %v", resp.ID)
 	}

-	// Verify it has default sources
-	if len(resp.Sources) != 5 {
-		t.Errorf("Expected 5 default sources, got %d", len(resp.Sources))
+	// Verify default sources. AUX (id=10001, sourceproviderid=9) is
+	// intentionally excluded from cloud responses — real Bose never
+	// emitted AUX in /full; the speaker enumerates AUX from its own
+	// hardware via isLocal=true in :8090/sources. See
+	// pkg/service/marge/marge.go getAccountSources.
+	if len(resp.Sources) != 4 {
+		t.Errorf("Expected 4 cloud default sources (AUX excluded), got %d", len(resp.Sources))
 	} else {
-		if resp.Sources[0].ID != "10001" {
-			t.Errorf("Expected first source ID 10001, got %s", resp.Sources[0].ID)
+		if resp.Sources[0].ID != "10002" {
+			t.Errorf("Expected first cloud source ID 10002 (INTERNET_RADIO), got %s", resp.Sources[0].ID)
 		}
 	}

@@ -380,10 +384,12 @@ func TestMargeAccountFullExcludesEmptyAmazonSource(t *testing.T) {
 		t.Errorf("/full response must not include an empty-credential Amazon source; body:\n%s", bodyStr)
 	}

-	// The 6 sources from lastDeviceID's stored Sources.xml must all be present.
-	// Checked by sourceproviderid since <name> may hold a display name rather than the type string.
+	// The cloud-visible sources from lastDeviceID's stored Sources.xml
+	// must all be present. AUX (sourceproviderid=9) is intentionally
+	// excluded — real Bose never emitted AUX in /full; the speaker
+	// enumerates AUX from its own hardware via isLocal=true. See
+	// pkg/service/marge/marge.go getAccountSources.
 	for _, wantProviderID := range []string{
-		"<sourceproviderid>9</sourceproviderid>",  // AUX
 		"<sourceproviderid>2</sourceproviderid>",  // INTERNET_RADIO
 		"<sourceproviderid>11</sourceproviderid>", // LOCAL_INTERNET_RADIO
 		"<sourceproviderid>25</sourceproviderid>", // TUNEIN
@@ -394,6 +400,11 @@ func TestMargeAccountFullExcludesEmptyAmazonSource(t *testing.T) {
 			t.Errorf("/full response is missing source with %s; body:\n%s", wantProviderID, bodyStr)
 		}
 	}
+
+	// And explicitly assert AUX is NOT present.
+	if strings.Contains(bodyStr, "<sourceproviderid>9</sourceproviderid>") {
+		t.Errorf("/full response must not include AUX (sourceproviderid=9); body:\n%s", bodyStr)
+	}
 }

 func TestMargeAccountSources(t *testing.T) {
@@ -627,13 +638,16 @@ func TestMargeAccountSourcesNoDevices(t *testing.T) {
 	body, _ := io.ReadAll(res.Body)
 	bodyStr := string(body)

-	// Verify that we get the default sources with correct IDs and empty display names
+	// Verify that we get the default cloud sources with correct IDs. AUX
+	// (id=10001) is intentionally excluded — real Bose never emitted AUX
+	// in cloud responses; the speaker enumerates AUX from its own
+	// hardware (isLocal=true on :8090/sources). See
+	// pkg/service/marge/marge.go getAccountSources.
 	expectedSnippets := []string{
 		"<sources>",
 		"<source id=\"10004\" type=\"Audio\"",
 		"<source id=\"10003\" type=\"Audio\"",
 		"<source id=\"10002\" type=\"Audio\"",
-		"<source id=\"10001\" type=\"Audio\"",
 	}

 	for _, snippet := range expectedSnippets {
@@ -642,6 +656,10 @@ func TestMargeAccountSourcesNoDevices(t *testing.T) {
 		}
 	}

+	if strings.Contains(bodyStr, "<source id=\"10001\"") {
+		t.Errorf("Response must not include AUX (id=10001); body:\n%s", bodyStr)
+	}
+
 	// Verify that no sources have empty display names
 	if strings.Count(bodyStr, "displayName=\"\"") != 0 {
 		t.Errorf("Expected no sources with empty displayName, got %d: %s", strings.Count(bodyStr, "displayName=\"\""), bodyStr)
@@ -1855,3 +1873,108 @@ func TestMargeGroupCRUD(t *testing.T) {
 		}
 	})
 }
+
+// TestMargeAddGroup_FromSpeakerCapture replays the exact request a SoundTouch
+// 10 master sends when it forwards an addGroup to its configured Marge server
+// while forming a stereo pair. The shape is taken verbatim from a live capture
+// in issue #252; account ID and device IDs are anonymised:
+//
+//	POST /streaming/account/{account}/group/
+//	Authorization: Bearer <token>
+//	Content-Type:  application/vnd.bose.streaming-v1.2+xml
+//	<group><masterDeviceId>...</masterDeviceId><name>TEST</name>
+//	  <roles>
+//	    <groupRole><deviceId>{master}</deviceId><role>LEFT</role></groupRole>
+//	    <groupRole><deviceId>{slave}</deviceId><role>RIGHT</role></groupRole>
+//	  </roles>
+//	</group>
+//
+// Notable differences from CLI-side requests this codebase already tests:
+//   - URL has a trailing slash ("/group/", not "/group")
+//   - <groupRole> elements have no <ipAddress>
+//   - <senderIPAddress> is absent (correct for the master-bound payload)
+//   - Content-Type is the vendor-specific media type
+//
+// The speaker retries this POST every 15 s while in AddingMaster state; if
+// AfterTouch doesn't accept it the group never completes and reverts to
+// NoGroup after a timeout. This test pins down the exact wire contract so
+// any future change that breaks it fails loudly.
+func TestMargeAddGroup_FromSpeakerCapture(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "st-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer func() { _ = os.RemoveAll(tempDir) }()
+
+	ds := datastore.NewDataStore(tempDir)
+	r, _ := setupRouter("http://localhost:8001", ds)
+
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	const (
+		account     = "1234567"
+		masterDevID = "001122334455"
+		slaveDevID  = "AABBCCDDEEFF"
+	)
+
+	// Body matches the captured MargeClient payload structure verbatim --
+	// no <senderIPAddress>, no per-role <ipAddress>, no <status>, no group id.
+	reqBody := `<?xml version="1.0" encoding="UTF-8" ?><group><masterDeviceId>` + masterDevID +
+		`</masterDeviceId><name>TEST</name><roles><groupRole><deviceId>` + masterDevID +
+		`</deviceId><role>LEFT</role></groupRole><groupRole><deviceId>` + slaveDevID +
+		`</deviceId><role>RIGHT</role></groupRole></roles></group>`
+
+	url := ts.URL + "/streaming/account/" + account + "/group/"
+
+	req, err := http.NewRequest(http.MethodPost, url, strings.NewReader(reqBody))
+	if err != nil {
+		t.Fatalf("build request: %v", err)
+	}
+
+	// Headers copied from the captured CMargeHttpInterface::Post lines.
+	req.Header.Set("Authorization", "Bearer test-token")
+	req.Header.Set("Content-Type", "application/vnd.bose.streaming-v1.2+xml")
+
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("do request: %v", err)
+	}
+	defer func() { _ = res.Body.Close() }()
+
+	if res.StatusCode != http.StatusCreated {
+		respBody, _ := io.ReadAll(res.Body)
+		t.Fatalf("POST %s: expected 201 Created, got %d. Body: %s", url, res.StatusCode, respBody)
+	}
+
+	if got := res.Header.Get("Content-Type"); got != "application/vnd.bose.streaming-v1.2+xml" {
+		t.Errorf("response Content-Type = %q, want %q", got, "application/vnd.bose.streaming-v1.2+xml")
+	}
+
+	location := res.Header.Get("Location")
+	if !strings.Contains(location, "/account/"+account+"/group/") {
+		t.Errorf("Location header should reference the new group under account %s, got %q", account, location)
+	}
+
+	respBody, err := io.ReadAll(res.Body)
+	if err != nil {
+		t.Fatalf("read response: %v", err)
+	}
+
+	var got models.Group
+	if err := xml.Unmarshal(respBody, &got); err != nil {
+		t.Fatalf("decode response: %v\nbody: %s", err, respBody)
+	}
+
+	if got.MasterDeviceID != masterDevID {
+		t.Errorf("response masterDeviceId = %q, want %q", got.MasterDeviceID, masterDevID)
+	}
+
+	if got.Name != "TEST" {
+		t.Errorf("response name = %q, want %q", got.Name, "TEST")
+	}
+
+	if len(got.Roles.Roles) != 2 {
+		t.Fatalf("response roles = %d, want 2", len(got.Roles.Roles))
+	}
+}
@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"html"
 	"io"
 	"log"
 	"net/http"
@@ -144,7 +145,9 @@ func (s *Server) HandleMgmtSpotifyCallback(w http.ResponseWriter, r *http.Reques
 	if errMsg := r.URL.Query().Get("error"); errMsg != "" {
 		w.Header().Set("Content-Type", "text/html")
 		w.WriteHeader(http.StatusBadRequest)
-		_, _ = w.Write([]byte(`<html><body><h1>Spotify Authorization Failed</h1><p>Error: ` + errMsg + `</p></body></html>`))
+		// html.EscapeString neutralises any HTML metacharacters in the
+		// caller-supplied error string before it lands in the response.
+		_, _ = w.Write([]byte(`<html><body><h1>Spotify Authorization Failed</h1><p>Error: ` + html.EscapeString(errMsg) + `</p></body></html>`))

 		return
 	}
@@ -487,7 +490,9 @@ func (s *Server) HandleMgmtAmazonCallback(w http.ResponseWriter, r *http.Request
 	if errMsg := r.URL.Query().Get("error"); errMsg != "" {
 		w.Header().Set("Content-Type", "text/html")
 		w.WriteHeader(http.StatusBadRequest)
-		_, _ = w.Write([]byte(`<html><body><h1>Amazon Authorization Failed</h1><p>Error: ` + errMsg + `</p></body></html>`))
+		// html.EscapeString neutralises any HTML metacharacters in the
+		// caller-supplied error string before it lands in the response.
+		_, _ = w.Write([]byte(`<html><body><h1>Amazon Authorization Failed</h1><p>Error: ` + html.EscapeString(errMsg) + `</p></body></html>`))

 		return
 	}
@@ -0,0 +1,138 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
+	"github.com/go-chi/chi/v5"
+)
+
+// accountIDSuggestionsResponse is the body of GET /setup/account-id-suggestions/{deviceId}.
+// `current` is the device's existing margeAccountUUID (empty when the device is fresh / factory-reset).
+// `known` is the list of accountIDs already present in the local datastore, so the UI can offer
+// the user a way to re-attach a fresh device to an existing account.
+type accountIDSuggestionsResponse struct {
+	Current string   `json:"current"`
+	Known   []string `json:"known"`
+}
+
+// HandleAccountIDSuggestions returns the device's current account ID (from
+// :8090/info, empty if unset) plus the list of account IDs already present
+// in the local datastore.
+func (s *Server) HandleAccountIDSuggestions(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "deviceId")
+	if deviceID == "" {
+		writeJSONError(w, http.StatusBadRequest, "Device ID is required")
+		return
+	}
+
+	deviceIP, err := s.resolveDeviceIDToIP(deviceID)
+	if err != nil {
+		writeJSONError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	resp := accountIDSuggestionsResponse{}
+
+	if info, err := s.sm.GetLiveDeviceInfo(deviceIP); err == nil {
+		resp.Current = info.MargeAccountUUID
+	}
+
+	if known, err := s.ds.ListAccounts(); err == nil {
+		resp.Known = known
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(resp); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// pairAccountResponse is the body of POST /setup/pair-account/{deviceId}.
+type pairAccountResponse struct {
+	OK     bool                    `json:"ok"`
+	Result setup.PairAccountResult `json:"result"`
+	Output string                  `json:"output"`
+	Error  string                  `json:"error,omitempty"`
+}
+
+// HandlePairAccount associates the device with the supplied 7-digit account ID,
+// trying HTTP /setMargeAccount first and falling back to telnet
+// `envswitch accountid set`.
+//
+// Query params:
+//   - account_id (required) — must pass setup.IsValidAccountID
+func (s *Server) HandlePairAccount(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "deviceId")
+	if deviceID == "" {
+		writeJSONError(w, http.StatusBadRequest, "Device ID is required")
+		return
+	}
+
+	accountID := r.URL.Query().Get("account_id")
+	if !setup.IsValidAccountID(accountID) {
+		writeJSONError(w, http.StatusBadRequest, "account_id must be exactly 7 digits")
+		return
+	}
+
+	deviceIP, err := s.resolveDeviceIDToIP(deviceID)
+	if err != nil {
+		writeJSONError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	var t setup.TelnetClient
+
+	if s.sm.NewTelnet != nil {
+		t = s.sm.NewTelnet(deviceIP)
+		if dialErr := t.Dial(); dialErr != nil {
+			// Telnet not reachable — fall through with t=nil so PairAccount
+			// can decide based on HTTP availability alone.
+			t = nil
+		} else {
+			defer func() { _ = t.Close() }()
+		}
+	}
+
+	result, output, err := s.sm.PairAccount(deviceIP, accountID, t)
+
+	w.Header().Set("Content-Type", "application/json")
+
+	body := pairAccountResponse{
+		OK:     err == nil,
+		Result: result,
+		Output: output,
+	}
+
+	if err != nil {
+		body.Error = err.Error()
+
+		w.WriteHeader(http.StatusInternalServerError)
+	}
+
+	if encErr := json.NewEncoder(w).Encode(body); encErr != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// jsonErrorBody is the static shape of error responses from this file.
+// Avoiding map[string]interface{} keeps errchkjson satisfied: the typed
+// struct guarantees encoding can't fail with a runtime type error.
+type jsonErrorBody struct {
+	OK      bool   `json:"ok"`
+	Message string `json:"message"`
+}
+
+// writeJSONError is a small helper for the handlers in this file to keep
+// error wiring out of the happy path. It mirrors what the rest of the
+// package does inline.
+func writeJSONError(w http.ResponseWriter, status int, message string) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+
+	if err := json.NewEncoder(w).Encode(jsonErrorBody{OK: false, Message: message}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
@@ -0,0 +1,66 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+// peerProbeTimeout caps how long the passive observer waits for any
+// inbound from the device IP after the :8090/swUpdateCheck nudge. 30s
+// is comfortable for daemon wake-up latency on slow devices while still
+// keeping the panel responsive; result.ElapsedMs surfaces the actual
+// observed latency so the budget can be tuned from real data.
+const peerProbeTimeout = 30 * time.Second
+
+// peerProbeResponse is the body of POST /setup/peer-probe/{deviceId}.
+type peerProbeResponse struct {
+	OK     bool   `json:"ok"`
+	Result any    `json:"result,omitempty"`
+	Error  string `json:"error,omitempty"`
+}
+
+// HandlePeerProbe runs the post-migration passive reachability check.
+// Registers interest in the device's IP, nudges :8090/swUpdateCheck,
+// and reports whether any inbound from that IP landed within
+// peerProbeTimeout. Any inbound counts — on a migrated speaker, DNS
+// interception routes the daemon's outbounds (update fan-out, marge,
+// BMX) through this service regardless of which URL the daemon
+// resolved internally, so the question reduces to "did the device
+// dial us at all."
+//
+// Unlike the deprecated round-trip probe, this handler does not mutate
+// device state. It presupposes the speaker is already migrated; the
+// pre-flight orchestrator is responsible for only calling it in that
+// state.
+func (s *Server) HandlePeerProbe(w http.ResponseWriter, r *http.Request) {
+	deviceID := chi.URLParam(r, "deviceId")
+	if deviceID == "" {
+		writeJSONError(w, http.StatusBadRequest, "Device ID is required")
+		return
+	}
+
+	deviceIP, err := s.resolveDeviceIDToIP(deviceID)
+	if err != nil {
+		writeJSONError(w, http.StatusNotFound, err.Error())
+		return
+	}
+
+	result, err := s.sm.RunPeerReachabilityProbe(deviceIP, s.peerObserver, peerProbeTimeout)
+
+	w.Header().Set("Content-Type", "application/json")
+
+	body := peerProbeResponse{
+		OK:     err == nil && result != nil && result.Reached,
+		Result: result,
+	}
+	if err != nil {
+		body.Error = err.Error()
+	}
+
+	if err := json.NewEncoder(w).Encode(body); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
@@ -62,6 +62,13 @@ func (s *Server) ServeProxy(target *url.URL) http.HandlerFunc {
 			r.Body = io.NopCloser(bytes.NewBuffer(reqBody))
 		}

+		// AllowInsecureUpstreamTLS is opt-in via settings.json — defaults to
+		// false so the upstream certificate chain is verified normally. The
+		// opt-in exists for deployments stuck behind a broken Bose-cloud
+		// chain post end-of-service.
+		settings, _ := s.ds.GetSettings()
+		insecure := settings.AllowInsecureUpstreamTLS
+
 		rp := &httputil.ReverseProxy{
 			Rewrite: func(pr *httputil.ProxyRequest) {
 				pr.SetURL(target)
@@ -77,7 +84,7 @@ func (s *Server) ServeProxy(target *url.URL) http.HandlerFunc {
 				lp.LogRequest(pr.Out)
 			},
 			Transport: &http.Transport{
-				TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
+				TLSClientConfig: &tls.Config{InsecureSkipVerify: insecure},
 			},
 		}

@@ -172,6 +172,17 @@ func (s *Server) HandleGetSettings(w http.ResponseWriter, _ *http.Request) {

 	dnsRunning, actualBind := s.GetDNSRunning()

+	var serverURLResolvedIP, serverURLResolveError string
+
+	if ip, err := s.resolveServerURLIP(serverURL); err == nil {
+		serverURLResolvedIP = ip
+	} else {
+		serverURLResolveError = err.Error()
+	}
+
+	httpsListenerPort := PortFromHTTPSServerURL(httpsServerURL)
+	probe443 := Check443Reachability(httpsListenerPort, serverURL, s.resolveServerURLIP, ProbeDialTimeoutInline)
+
 	// Mask secrets: return "***" if set so the UI can show "configured" without exposing the value.
 	if spotifyClientSecret != "" {
 		spotifyClientSecret = "***"
@@ -182,32 +193,41 @@ func (s *Server) HandleGetSettings(w http.ResponseWriter, _ *http.Request) {
 	}

 	if err := json.NewEncoder(w).Encode(map[string]interface{}{
-		"server_url":            serverURL,
-		"https_server_url":      httpsServerURL,
-		"discovery_interval":    discoveryInterval,
-		"discovery_enabled":     discoveryEnabled,
-		"dns_enabled":           dnsEnabled,
-		"dns_running":           dnsRunning,
-		"dns_actual_bind":       actualBind,
-		"dns_upstream":          strings.Join(dnsUpstream, ","),
-		"dns_bind_addr":         dnsBindAddr,
-		"mirror_enabled":        mirrorEnabled,
-		"mirror_endpoints":      mirrorEndpoints,
-		"skip_mirror_endpoints": skipMirrorEndpoints,
-		"preferred_source":      preferredSource,
-		"internal_paths":        internalPaths,
-		"redact_logs":           redact,
-		"log_bodies":            logBody,
-		"record_interactions":   record,
-		"shortcuts":             shortcuts,
-		"spotify_configured":    spotifyConfigured,
-		"spotify_client_id":     spotifyClientID,
-		"spotify_client_secret": spotifyClientSecret,
-		"spotify_redirect_uri":  spotifyRedirectURI,
-		"amazon_configured":     amazonConfigured,
-		"amazon_client_id":      amazonClientID,
-		"amazon_client_secret":  amazonClientSecret,
-		"amazon_redirect_uri":   amazonRedirectURI,
+		"server_url":                    serverURL,
+		"server_url_resolved_ip":        serverURLResolvedIP,
+		"server_url_resolve_error":      serverURLResolveError,
+		"https_server_url":              httpsServerURL,
+		"https_listener_port":           httpsListenerPort,
+		"https_443_check_skipped":       probe443.Skipped,
+		"https_443_localhost_reachable": probe443.Localhost.Reachable,
+		"https_443_localhost_error":     probe443.Localhost.Error,
+		"https_443_lan_reachable":       probe443.LAN.Reachable,
+		"https_443_lan_error":           probe443.LAN.Error,
+		"https_443_lan_host":            probe443.LANHost,
+		"discovery_interval":            discoveryInterval,
+		"discovery_enabled":             discoveryEnabled,
+		"dns_enabled":                   dnsEnabled,
+		"dns_running":                   dnsRunning,
+		"dns_actual_bind":               actualBind,
+		"dns_upstream":                  strings.Join(dnsUpstream, ","),
+		"dns_bind_addr":                 dnsBindAddr,
+		"mirror_enabled":                mirrorEnabled,
+		"mirror_endpoints":              mirrorEndpoints,
+		"skip_mirror_endpoints":         skipMirrorEndpoints,
+		"preferred_source":              preferredSource,
+		"internal_paths":                internalPaths,
+		"redact_logs":                   redact,
+		"log_bodies":                    logBody,
+		"record_interactions":           record,
+		"shortcuts":                     shortcuts,
+		"spotify_configured":            spotifyConfigured,
+		"spotify_client_id":             spotifyClientID,
+		"spotify_client_secret":         spotifyClientSecret,
+		"spotify_redirect_uri":          spotifyRedirectURI,
+		"amazon_configured":             amazonConfigured,
+		"amazon_client_id":              amazonClientID,
+		"amazon_client_secret":          amazonClientSecret,
+		"amazon_redirect_uri":           amazonRedirectURI,
 	}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
@@ -247,6 +267,15 @@ func (s *Server) HandleUpdateSettings(w http.ResponseWriter, r *http.Request) {
 		log.Printf("[DNS] DNS Discovery enabled without explicit upstreams, will try system DNS.")
 	}

+	// Validate server_url: the same value the DNS server uses to derive its
+	// intercept IP. Reject anything that does not resolve to a routable IP so
+	// users see the error in the UI instead of getting a silently-broken setup
+	// where DNS replies with `CNAME .` for every Bose hostname.
+	if _, err := s.resolveServerURLIP(settings.ServerURL); err != nil {
+		http.Error(w, "Invalid server_url: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+
 	interval, err := time.ParseDuration(settings.DiscoveryInterval)
 	if err != nil && settings.DiscoveryInterval != "" {
 		http.Error(w, "Invalid discovery interval: "+err.Error(), http.StatusBadRequest)
@@ -411,13 +440,7 @@ func (s *Server) HandleGetMigrationSummary(w http.ResponseWriter, r *http.Reques
 	targetURL := r.URL.Query().Get("target_url")
 	proxyURL := r.URL.Query().Get("proxy_url")

-	options := make(map[string]string)
-
-	for k, v := range r.URL.Query() {
-		if len(v) > 0 && (k == "marge" || k == "stats" || k == "sw_update" || k == "bmx") {
-			options[k] = v[0]
-		}
-	}
+	options := parseMigrationOptions(r.URL.Query())

 	summary, err := s.sm.GetMigrationSummary(deviceIP, targetURL, proxyURL, options)
 	if err != nil {
@@ -465,13 +488,7 @@ func (s *Server) HandleMigrateDevice(w http.ResponseWriter, r *http.Request) {
 	proxyURL := r.URL.Query().Get("proxy_url")
 	method := setup.MigrationMethod(r.URL.Query().Get("method"))

-	options := make(map[string]string)
-
-	for k, v := range r.URL.Query() {
-		if len(v) > 0 && (k == "marge" || k == "stats" || k == "sw_update" || k == "bmx") {
-			options[k] = v[0]
-		}
-	}
+	options := parseMigrationOptions(r.URL.Query())

 	output, err := s.sm.MigrateSpeaker(deviceIP, targetURL, proxyURL, options, method)
 	if err != nil {
@@ -1066,7 +1083,9 @@ func (s *Server) HandleRebootDevice(w http.ResponseWriter, r *http.Request) {
 		return
 	}

-	output, err := s.sm.Reboot(deviceIP)
+	method := setup.RebootMethod(r.URL.Query().Get("method"))
+
+	output, err := s.sm.Reboot(deviceIP, method)
 	if err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusInternalServerError)
@@ -101,7 +101,7 @@ func TestProxySettingsAPI(t *testing.T) {

 	// 3. Test System Settings POST
 	sysUpdate := map[string]string{
-		"server_url": "http://new-server:8000",
+		"server_url": "http://127.0.0.1:8000",
 	}

 	sysBody, err := json.Marshal(sysUpdate)
@@ -122,13 +122,13 @@ func TestProxySettingsAPI(t *testing.T) {

 	// Verify server state
 	sURL, _ := server.GetSettings()
-	if sURL != "http://new-server:8000" {
+	if sURL != "http://127.0.0.1:8000" {
 		t.Errorf("POST /setup/settings: Server state did not update: serverURL=%s", sURL)
 	}

 	// 4. Test Mirror Settings persistence
 	mirrorUpdate := map[string]interface{}{
-		"server_url":       "http://mirror-test:8000",
+		"server_url":       "http://127.0.0.1:8000",
 		"mirror_enabled":   true,
 		"mirror_endpoints": []string{"/test/*"},
 		"internal_paths":   []string{"/setup/*"},
@@ -410,6 +410,11 @@ func TestRemoveDevice(t *testing.T) {
 type mockSSH struct {
 	host     string
 	runCount int
+
+	// uploaded mirrors UploadContent calls so that a subsequent
+	// `cat <path>` (notably the tmp-readback step in
+	// TrustCACertFromBytes) returns what we just wrote there.
+	uploaded map[string][]byte
 }

 func (m *mockSSH) Run(command string) (string, error) {
@@ -427,7 +432,21 @@ func (m *mockSSH) Run(command string) (string, error) {
 	if strings.HasPrefix(command, "grep -F") {
 		return "matched", nil // CA trusted
 	}
+	if strings.HasPrefix(command, "cat ") {
+		path := strings.TrimPrefix(command, "cat ")
+		if body, ok := m.uploaded[path]; ok {
+			return string(body), nil
+		}
+	}
 	return "", nil
 }

-func (m *mockSSH) UploadContent(content []byte, remotePath string) error { return nil }
+func (m *mockSSH) UploadContent(content []byte, remotePath string) error {
+	if m.uploaded == nil {
+		m.uploaded = make(map[string][]byte)
+	}
+
+	m.uploaded[remotePath] = append([]byte(nil), content...)
+
+	return nil
+}
@@ -0,0 +1,128 @@
+package handlers
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+)
+
+// TestIssue218_OrionStationResolvesPresetStreamURL closes the loop on
+// the issue #218 regression: it takes the exact preset location URL the
+// reporter pasted, follows it against the real router, and asserts the
+// returned BmxPlaybackResponse exposes the speaker-playable streamUrl.
+//
+// Pairs with pkg/service/setup/issue218_regression_test.go, which
+// verifies the preset survives device sync verbatim. Together they
+// prove that:
+//
+//  1. The sync step preserves the cloud URL embedded in
+//     LOCAL_INTERNET_RADIO presets.
+//  2. Hitting that URL against AfterTouch's router resolves it to the
+//     speaker-playable stream — no rewrite required on the persisted
+//     preset itself.
+//
+// Before commit f3a4658, this test would have 404'd: the orion routes
+// were wrongly nested under `/bmx/` while the BMX registry advertises
+// the un-prefixed path. See the matching doc-comment on
+// HandleOrionPlayback for the protocol detail.
+func TestIssue218_OrionStationResolvesPresetStreamURL(t *testing.T) {
+	// Verbatim from pkg/service/setup/testdata/issue218/presets.xml's
+	// ContentItem `location` attribute (issue #218 body). Decoded
+	// query payload is:
+	//   {"name":"OPB","imageUrl":"","streamUrl":"http://ais-sa3.cdnstream1.com/2440_128.aac"}
+	const presetLocation = "https://content.api.bose.io/core02/svc-bmx-adapter-orion/prod/orion/station?data=eyJuYW1lIjoiT1BCIiwiaW1hZ2VVcmwiOiIiLCJzdHJlYW1VcmwiOiJodHRwOi8vYWlzLXNhMy5jZG5zdHJlYW0xLmNvbS8yNDQwXzEyOC5hYWMifQ%3D%3D"
+
+	const wantStreamURL = "http://ais-sa3.cdnstream1.com/2440_128.aac"
+
+	// Sanity: the base64 payload really does encode wantStreamURL.
+	// If the fixture ever diverges from this expectation the test
+	// would silently keep passing on whatever the new payload says;
+	// pin it explicitly.
+	parsedLocation, err := url.Parse(presetLocation)
+	if err != nil {
+		t.Fatalf("parse preset location: %v", err)
+	}
+
+	data := parsedLocation.Query().Get("data")
+	if data == "" {
+		t.Fatalf("preset location has no `data` query param: %s", presetLocation)
+	}
+
+	decoded, err := base64.URLEncoding.DecodeString(data)
+	if err != nil {
+		// Some captures use RawURLEncoding (no padding); fall back.
+		decoded, err = base64.RawURLEncoding.DecodeString(strings.TrimRight(data, "="))
+		if err != nil {
+			t.Fatalf("decode data blob: %v", err)
+		}
+	}
+
+	if !strings.Contains(string(decoded), wantStreamURL) {
+		t.Fatalf("fixture data does not encode the expected streamUrl.\ndecoded:\n%s\nwant substring:\n%s",
+			decoded, wantStreamURL)
+	}
+
+	// Drive the real router. Use only the path+query from the preset
+	// URL — host is what DNS interception or URL-flip would have
+	// substituted at runtime, not what the test server bound to.
+	r, _ := setupRouter("http://localhost:8001", nil)
+	ts := httptest.NewServer(r)
+
+	t.Cleanup(ts.Close)
+
+	resolved := ts.URL + parsedLocation.RequestURI()
+
+	// Real speakers retrieve an orion token from
+	// POST /core02/svc-bmx-adapter-orion/prod/orion/token before they
+	// ever follow a LOCAL_INTERNET_RADIO preset; the playback handler
+	// rejects an empty Authorization header for parity with the other
+	// BMX playback routes. Use a sentinel Bearer token to match that
+	// shape — HandleOrionPlayback doesn't validate the token contents,
+	// only its presence.
+	req, _ := http.NewRequest("GET", resolved, nil)
+	req.Header.Set("Authorization", "Bearer mock-token")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("GET %s: %v", resolved, err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		t.Fatalf("GET %s → %d, want 200; body:\n%s", resolved, resp.StatusCode, body)
+	}
+
+	var got models.BmxPlaybackResponse
+	if err := json.NewDecoder(resp.Body).Decode(&got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+
+	if got.Audio.StreamUrl != wantStreamURL {
+		t.Errorf("audio.streamUrl = %q, want %q", got.Audio.StreamUrl, wantStreamURL)
+	}
+
+	if got.Name != "OPB" {
+		t.Errorf("name = %q, want %q", got.Name, "OPB")
+	}
+
+	if got.StreamType != "liveRadio" {
+		t.Errorf("streamType = %q, want %q", got.StreamType, "liveRadio")
+	}
+
+	// The streams array should mirror the top-level streamUrl —
+	// PlayCustomStream sets both for parity with what real Bose emits.
+	if len(got.Audio.Streams) == 0 {
+		t.Errorf("audio.streams empty, want at least one entry with streamUrl=%q", wantStreamURL)
+	} else if got.Audio.Streams[0].StreamUrl != wantStreamURL {
+		t.Errorf("audio.streams[0].streamUrl = %q, want %q", got.Audio.Streams[0].StreamUrl, wantStreamURL)
+	}
+}
--- a/Show More
+++ b/Show More