feat(service): add a deprecation signal on the legacy /setup and /mgmt paths (refs #451)

So the eventual 1.x removal of the legacy admin paths can be data-driven (cut a
route only once it has gone quiet across real deployments), record usage of the
pre-/api paths without changing their behavior.

- New DeprecatedRouteMiddleware: after serving, counts the hit keyed by
  "METHOD <route-pattern>" and logs a one-time warning per route pointing at the
  /api equivalent. Wired onto the legacy /setup and /mgmt mounts only — NOT the
  /api/* twins, NOT the externally-pinned OAuth callbacks, NOT the Stockholm
  setup-wizard catch-all.
- Counts are exposed in the diagnostic export (deprecated_route_hits), so the
  shared bundles show whether the old paths are still in use.

Legacy paths keep working unchanged. make test-http-client: 95 requests, 0
failed (the suite still exercises /mgmt directly and now emits the one-time
warnings). go test + golangci-lint clean.

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

.claude/commands/blog-update.md

@@ -0,0 +1,87 @@
+Draft a "News & Updates" blog post for AfterTouch covering recent git activity, then open a draft PR for review.
+
+## Step 1 — Determine lookback window
+
+Run:
+```
+git log --format="%ad" --date=short -- docs/content/blog/ | grep -v '_index' | head -1
+```
+
+If a date is returned, use it as SINCE.
+If the output is empty (no posts yet), compute SINCE = 30 days before today:
+- macOS: `date -v-30d +%Y-%m-%d`
+- Linux: `date -d '30 days ago' +%Y-%m-%d`
+
+## Step 2 — Collect commits since SINCE
+
+Run:
+```
+git log --format="%ad %h %s" --date=short --since="$SINCE" --no-merges
+```
+
+Exclude these (they are noise):
+- Subjects matching: `^(ci|chore|deps|bump|Bump|test|lint|style|code style|debug)`
+- Dependabot bumps (subject contains "bump" and includes a package name pattern)
+- Routine doc link/URL fixes
+
+Group the remaining commits into categories:
+- **NEW FEATURES** — subjects starting with `feat(` or `feat:`
+- **BUG FIXES** — subjects starting with `fix(` or `fix:`
+- **SECURITY** — subjects starting with `sec` or containing "security", "inject", "path expression"
+- **DOCS** — user-visible doc changes only (new guides, major restructures)
+- **MAINTENANCE** — everything else that passed the filter
+
+Omit empty categories entirely.
+
+## Step 3 — Current version
+
+Run: `git tag --sort=-version:refname | head -1`
+
+## Step 4 — Determine the period label
+
+Use the first and last commit dates from Step 2 to produce a human-readable label,
+e.g. "May 2026" or "April – May 2026".
+
+## Step 5 — Write the blog post
+
+Create the file at: `docs/content/blog/YYYY-MM-slug.md`
+- YYYY-MM = today's year-month
+- slug = short kebab-case summary of the biggest theme
+
+Use this exact frontmatter shape:
+```yaml
+---
+title: "AfterTouch PERIOD: <one-line theme>"
+date: YYYY-MM-DD
+description: "<one sentence, ≤200 chars, suitable as a standalone teaser>"
+tags:
+  - <up to 4 tags from: security, tls, discovery, docs, cli, web, spotify, amazon, health, migration, fixes, ci>
+sidebar:
+  exclude: true
+---
+```
+
+Body structure:
+1. Opening paragraph (3–5 sentences) explaining what happened and why it matters to someone running AfterTouch.
+2. One `##` section per non-empty category. Use bullet points written for an operator audience — no raw git subjects, no internal Go package paths.
+3. End with: `**Current release:** vX.Y.Z`
+
+Target length: 300–600 words. Never include real IPs, MAC addresses, account IDs, or device names.
+
+## Step 6 — Create a branch and open a draft PR
+
+```bash
+git checkout -b blog/YYYY-MM-update
+git add docs/content/blog/YYYY-MM-slug.md
+git commit -m "docs(blog): add PERIOD update post"
+git push -u origin blog/YYYY-MM-update
+gh pr create --draft \
+  --title "Blog: PERIOD update post" \
+  --body "Automated draft from /blog-update skill. Review content before merging — deployment is automatic on merge to main."
+```
+
+If the `documentation` label exists on the repo, add `--label documentation`.
+
+## Step 7 — Done
+
+Report the PR URL. Do not merge, approve, or request review.

.env.example

@@ -5,6 +5,24 @@
 SOUNDTOUCH_HOSTNAME=soundtouch.local
 SOUNDTOUCH_VERSION=latest
 
+# Stockholm frontend (used by make prepare-stockholm and by the Go service at startup)
+# BACKEND_URL is the base URL your speakers and browser can reach the service at.
+# Corresponds to SERVER_URL in the Go service.
+# BACKEND_URL=http://soundtouch.local:8000
+#
+# STREAMING_URL is used for streaming.bose.com rewrites (defaults to BACKEND_URL).
+# Set to $(BACKEND_URL)/marge only when routing through a soundcork backend.
+# STREAMING_URL=http://soundtouch.local:8000
+#
+# AUTH_SERVICE_URL is written into config.json as the auth endpoint (defaults to BACKEND_URL).
+# A trailing slash is added automatically; the JS appends paths like "oauth/account/..." directly.
+# AUTH_SERVICE_URL=http://soundtouch.local:8000
+#
+# STOCKHOLM_BASE_PATH mounts the Stockholm UI under a URL prefix, freeing / for the management UI.
+# The bridge API (/api/native/*, /api/http-proxy) remains at root regardless of this setting.
+# Defaults to /stockholm. Set to empty to serve at root.
+# STOCKHOLM_BASE_PATH=/stockholm
+
 # Discovery Settings
 DISCOVERY_TIMEOUT=5s
 UPNP_ENABLED=true
@@ -25,23 +43,23 @@ CACHE_TTL=30s
 
 # Examples:
 # Single device with default port:
-# PREFERRED_DEVICES="192.168.1.100"
+# PREFERRED_DEVICES="192.0.2.100"
 
 # Single device with custom name:
-# PREFERRED_DEVICES="Living Room@192.168.1.100"
+# PREFERRED_DEVICES="Living Room@192.0.2.100"
 
 # Single device with custom port:
-# PREFERRED_DEVICES="192.168.1.100:8091"
+# PREFERRED_DEVICES="192.0.2.100:8091"
 
 # Multiple devices with mixed configurations:
-PREFERRED_DEVICES="Living Room@192.168.1.100:8090;Kitchen@192.168.1.101;192.168.1.102:8091"
+PREFERRED_DEVICES="Living Room@192.0.2.100:8090;Kitchen@192.0.2.101;192.0.2.102:8091"
 
-# Real example based on your devices:
-# PREFERRED_DEVICES="Sound Machinechen@192.168.178.35;A Sound Machine@192.168.178.28"
+# Example — replace with your speakers' names and IPs:
+# PREFERRED_DEVICES="Living Room SoundTouch@192.0.2.10;Kitchen SoundTouch@192.0.2.11"
 
 # Alternative format examples:
-# PREFERRED_DEVICES="192.168.178.35;192.168.178.28"
-# PREFERRED_DEVICES="SoundTouch 10@192.168.178.35;SoundTouch 20@192.168.178.28"
+# PREFERRED_DEVICES="192.0.2.10;192.0.2.11"
+# PREFERRED_DEVICES="SoundTouch 10@192.0.2.10;SoundTouch 20@192.0.2.11"
 
 # Spotify Integration
 # Create an app at https://developer.spotify.com/dashboard

.github/ISSUE_TEMPLATE/bug_report.md

@@ -30,7 +30,7 @@ A clear and concise description of what you expected to happen.
 **Command/Code that failed**
 ```bash
 # If using CLI tool, provide the exact command
-soundtouch-cli --host 192.168.1.100 info get
+soundtouch-cli --host 192.0.2.100 info get
 
 # If using Go library, provide minimal code example
 ```

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -163,7 +163,7 @@ body:
       label: Network Configuration
       description: Details about your network setup (if relevant to the issue)
       placeholder: |
-        - Device IP: 192.168.1.100
+        - Device IP: 192.0.2.100
         - Network type: WiFi/Ethernet
         - Router model:
         - Any firewalls or network restrictions:

.github/ISSUE_TEMPLATE/device_compatibility.md

@@ -69,8 +69,8 @@ List any features that don't work or behave unexpectedly:
 **Testing Commands Used**
 ```bash
 # List the specific commands you used for testing
-soundtouch-cli --host 192.168.1.100 info get
-soundtouch-cli --host 192.168.1.100 play start
+soundtouch-cli --host 192.0.2.100 info get
+soundtouch-cli --host 192.0.2.100 play start
 # ... etc
 ```
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -50,7 +50,7 @@ client.NewFeature(parameters)
 
 ```bash
 # CLI example
-soundtouch-cli --host 192.168.1.100 new-feature --param value
+soundtouch-cli --host 192.0.2.100 new-feature --param value
 ```
 
 **Priority**

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -131,7 +131,7 @@ body:
       render: go
       placeholder: |
         // Example of how you envision using this feature
-        client := soundtouch.New("192.168.1.100", 8090)
+        client := soundtouch.New("192.0.2.100", 8090)
 
         // Your desired API call
         result, err := client.NewFeature(options)

.github/codeql-config.yml

@@ -1,74 +1,29 @@
-# CodeQL configuration for enhanced security analysis
-# See: https://docs.github.com/en/code-security/codeql-cli/using-the-codeql-cli/creating-codeql-query-suites
+# CodeQL configuration
+# https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning
 
 name: "Go Security Analysis"
 
 disable-default-queries: false
 
 queries:
-  # Include default security queries
   - uses: security-extended
   - uses: security-and-quality
 
-  # Additional Go-specific security queries
-  - name: go-security-extra
-    uses:
-      - go/bad-redirect-check
-      - go/clear-text-logging
-      - go/incorrect-integer-conversion
-      - go/log-injection
-      - go/missing-regexp-anchor
-      - go/path-injection
-      - go/request-forgery
-      - go/sensitive-package-import
-      - go/sql-injection
-      - go/uncontrolled-allocation-size
-      - go/unsafe-quoting
-      - go/useless-regexp-character-escape
-      - go/zip-slip
-
-# Configure paths to exclude from analysis
-paths-ignore:
-  - "**/*.pb.go"          # Generated protobuf files
-  - "**/*_gen.go"         # Generated code
-  - "**/vendor/**"        # Vendor dependencies
-  - "**/build/**"         # Build artifacts
-  - "**/scripts/**"       # Build scripts
-  - "**/*_test.go"        # Test files (optional - remove if you want to analyze tests)
-
-# Configure paths to include (if not specified, all Go files are included)
+# Paths to include
 paths:
   - "cmd/**/*.go"
   - "pkg/**/*.go"
   - "*.go"
 
-# Query filters to reduce noise
+# Paths to exclude from analysis
+paths-ignore:
+  - "**/*.pb.go"       # Generated protobuf files
+  - "**/*_gen.go"      # Generated code
+  - "**/vendor/**"     # Vendor dependencies
+  - "**/build/**"      # Build artifacts
+  - "**/scripts/**"    # Build scripts
+  - "**/*_test.go"     # Test files
+
 query-filters:
-  - exclude:
-      id: go/unused-variable
-      reason: "Can be noisy in development"
   - exclude:
       id: go/hardcoded-credentials
-      reason: "Will be handled by separate secret scanning"
-
-# Configuration for specific query packs
-packs:
-  # Use the official CodeQL Go queries
-  - codeql/go-queries
-
-  # Additional community query packs for enhanced security
-  - codeql/go-queries@~0.0.0  # Latest version
-
-# Custom configuration for specific queries
-query-config:
-  go/path-injection:
-    # Configure severity levels
-    severity: "error"
-  go/sql-injection:
-    severity: "error"
-  go/request-forgery:
-    severity: "warning"
-  go/log-injection:
-    severity: "warning"
-  go/clear-text-logging:
-    severity: "note"

.github/dependabot.yml

@@ -38,6 +38,69 @@ updates:
         patterns:
           - "golang.org/*"
 
+  # Hugo module dependency updates (docs site)
+  - package-ecosystem: "gomod"
+    directory: "/docs"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "gesellix"
+    assignees:
+      - "gesellix"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "go"
+      - "docs"
+    rebase-strategy: "auto"
+
+  # Example module dependency updates
+  - package-ecosystem: "gomod"
+    directory: "/examples/navigation-station-demo"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "gesellix"
+    assignees:
+      - "gesellix"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "go"
+    rebase-strategy: "auto"
+
+  - package-ecosystem: "gomod"
+    directory: "/examples/preset-management"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "gesellix"
+    assignees:
+      - "gesellix"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "go"
+    rebase-strategy: "auto"
+
   # GitHub Actions workflow dependency updates
   - package-ecosystem: "github-actions"
     directory: "/"
@@ -98,3 +161,25 @@ updates:
       - "dependencies"
       - "docker"
     rebase-strategy: "auto"
+
+  # npm dependency updates
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "thursday"
+      time: "09:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 3
+    reviewers:
+      - "gesellix"
+    assignees:
+      - "gesellix"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+    labels:
+      - "dependencies"
+      - "npm"
+      - "frontend"
+    rebase-strategy: "auto"

.github/markdown-link-check.json

@@ -3,7 +3,7 @@
   "retryOn429": true,
   "retryCount": 3,
   "fallbackRetryDelay": "30s",
-  "aliveStatusCodes": [200, 206],
+  "aliveStatusCodes": [200, 202, 206],
   "ignorePatterns": [
     {
       "pattern": "^http://localhost"
@@ -27,7 +27,7 @@
       "pattern": "^https://pkg.go.dev.*badge"
     },
     {
-      "pattern": "^\\.\\./images/(dashboard-home|account-creation|account-dashboard|usb-remote-services|device-discovery|device-registration|account-migration|migration-setup|migration-progress|migration-health|migration-complete|backup-setup)\\.png$"
+      "pattern": "^/images/"
     },
     {
       "pattern": "https://www.contributor-covenant.org/version/2/0/code_of_conduct.html"

.github/pull_request_template.md

@@ -50,7 +50,7 @@ Please check the type of change your PR introduces:
 
 **Device(s) tested with:**
 - Device model: [e.g. SoundTouch 10]
-- Device IP: [e.g. 192.168.1.100]
+- Device IP: [e.g. 192.0.2.100]
 - Test results: [brief description]
 
 ### Test Commands
@@ -58,7 +58,7 @@ Please check the type of change your PR introduces:
 # Commands used to test this change
 make test
 go test ./pkg/client -v -run TestNewFeature
-soundtouch-cli --host 192.168.1.100 new-command
+soundtouch-cli --host 192.0.2.100 new-command
 ```
 
 ## Documentation

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -53,7 +53,7 @@ jobs:
         run: make test-http-client
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
         with:
           file: ./coverage.out
           flags: unittests
@@ -66,7 +66,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -77,7 +77,7 @@ jobs:
         run: sudo apt-get install -y libpcap-dev
 
       - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
+        uses: golangci/golangci-lint-action@82606bf257cbaff209d206a39f5134f0cfbfd2ee # v9.2.1
         with:
           version: latest
           args: --timeout=5m
@@ -107,7 +107,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -163,7 +163,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -190,7 +190,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Check documentation links
         run: |
@@ -215,8 +215,8 @@ jobs:
           )
 
           for img in "${IMAGES[@]}"; do
-            if [ ! -f "docs/images/$img" ]; then
-              echo "::warning file=docs/guides/MIGRATION-GUIDE.md::Pending image '$img' is missing from docs/images/"
+            if [ ! -f "docs/static/images/$img" ]; then
+              echo "::warning file=docs/content/docs/guides/MIGRATION-GUIDE.md::Pending image '$img' is missing from docs/static/images/"
             fi
           done
 
@@ -226,7 +226,7 @@ jobs:
           echo "Validating API documentation consistency..."
 
           # Check API cookbook
-          if [ -f "docs/reference/API-COOKBOOK.md" ]; then
+          if [ -f "docs/content/docs/reference/API-COOKBOOK.md" ]; then
             echo "✓ API Cookbook exists"
           else
             echo "✗ API Cookbook missing"
@@ -234,7 +234,7 @@ jobs:
           fi
 
           # Check getting started guide
-          if [ -f "docs/guides/GETTING-STARTED.md" ]; then
+          if [ -f "docs/content/docs/guides/GETTING-STARTED.md" ]; then
             echo "✓ Getting Started guide exists"
           else
             echo "✗ Getting Started guide missing"
@@ -248,7 +248,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -275,7 +275,7 @@ jobs:
 
           func main() {
               // Test basic client creation
-              c := client.NewClientFromHost("192.168.1.100")
+              c := client.NewClientFromHost("192.0.2.100")
               fmt.Printf("Client created for %s\n", c.BaseURL())
 
               // Test models can be imported
@@ -303,10 +303,14 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+
+      - name: Set build date
+        id: build_date
+        run: echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
 
       - name: Determine push eligibility
         id: push-check
@@ -324,7 +328,7 @@ jobs:
 
       - name: Log in to GitHub Container Registry
         if: steps.push-check.outputs.should-push == 'true'
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -332,7 +336,7 @@ jobs:
 
       - name: Extract metadata (tags, labels) for soundtouch-service
         id: meta-service
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
@@ -342,7 +346,7 @@ jobs:
             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@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           context: .
           target: soundtouch-service
@@ -350,12 +354,15 @@ jobs:
           push: ${{ steps.push-check.outputs.should-push == 'true' }}
           tags: ${{ steps.meta-service.outputs.tags }}
           labels: ${{ steps.meta-service.outputs.labels }}
+          build-args: |
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
       - name: Extract metadata (tags, labels) for soundtouch-web
         id: meta-web
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ghcr.io/${{ github.repository }}-web
           tags: |
@@ -365,7 +372,7 @@ jobs:
             type=ref,event=branch,prefix=preview-branch-,enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
 
       - name: Build and push soundtouch-web Docker image
-        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           context: .
           target: soundtouch-web
@@ -373,6 +380,9 @@ jobs:
           push: ${{ steps.push-check.outputs.should-push == 'true' }}
           tags: ${{ steps.meta-web.outputs.tags }}
           labels: ${{ steps.meta-web.outputs.labels }}
+          build-args: |
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 

.github/workflows/codeql.yml

@@ -0,0 +1,56 @@
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '36 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: go
+            build-mode: manual
+          - language: javascript-typescript
+            build-mode: none
+          - language: python
+            build-mode: none
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Install libpcap (required for Go build)
+        if: matrix.language == 'go'
+        run: sudo apt-get install -y libpcap-dev
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@87557b9c84dde89fdd9b10e88954ac2f4248e463 # v4.36.1
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          config-file: ${{ matrix.language == 'go' && './.github/codeql-config.yml' || '' }}
+
+      - name: Build Go (required for manual build-mode)
+        if: matrix.language == 'go'
+        run: go build ./...
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@87557b9c84dde89fdd9b10e88954ac2f4248e463 # v4.36.1
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/docs.yml

@@ -20,14 +20,20 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
       - name: Setup Pages
+        id: pages
         uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@2752ce1d29631191ea3f27c23495fa06139a5b78 # v3.2.1
         with:
-          source: 'docs/'
-          destination: '_site'
+          hugo-version: 'latest'
+          extended: true
+      - name: Build with Hugo
+        run: hugo --source docs/ --minify --destination ../_site --baseURL "${{ steps.pages.outputs.base_url }}"
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_PARAMS_GITHASH: ${{ github.sha }}
       - name: Upload artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:

.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 
@@ -102,7 +102,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -305,7 +305,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
 
@@ -358,7 +358,7 @@ jobs:
 
           func main() {
               // Create client
-              c := client.New("192.168.1.100", 8090)
+              c := client.New("192.0.2.100", 8090)
 
               // Get device info
               info, err := c.GetInfo()
@@ -521,13 +521,17 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set build date
+        id: build_date
+        run: echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -535,7 +539,7 @@ jobs:
 
       - name: Extract metadata (tags, labels) for soundtouch-service
         id: meta-service
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
@@ -544,7 +548,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@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           context: .
           target: soundtouch-service
@@ -552,12 +556,16 @@ jobs:
           push: true
           tags: ${{ steps.meta-service.outputs.tags }}
           labels: ${{ steps.meta-service.outputs.labels }}
+          build-args: |
+            VERSION=v${{ needs.validate.outputs.version }}
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
       - name: Extract metadata (tags, labels) for soundtouch-web
         id: meta-web
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9 # v6.1.0
         with:
           images: ghcr.io/${{ github.repository }}-web
           tags: |
@@ -566,7 +574,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@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
         with:
           context: .
           target: soundtouch-web
@@ -574,6 +582,10 @@ jobs:
           push: true
           tags: ${{ steps.meta-web.outputs.tags }}
           labels: ${{ steps.meta-web.outputs.labels }}
+          build-args: |
+            VERSION=v${{ needs.validate.outputs.version }}
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 

.github/workflows/security.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -29,10 +29,8 @@ jobs:
       - name: Install libpcap
         run: sudo apt-get install -y libpcap-dev
 
-      - name: Install security scanning tools
-        run: |
-          go install golang.org/x/vuln/cmd/govulncheck@latest
-          go install github.com/sonatypecommunity/nancy@latest
+      - name: Install govulncheck
+        run: go install golang.org/x/vuln/cmd/govulncheck@latest
 
       - name: Run govulncheck (Official Go vulnerability scanner)
         run: |
@@ -40,21 +38,6 @@ jobs:
           govulncheck ./...
           echo "::endgroup::"
 
-      - name: Run Nancy vulnerability scanner
-        run: |
-          echo "::group::Running Nancy dependency scanner"
-          go list -json -deps ./... | nancy sleuth
-          echo "::endgroup::"
-
-      - name: Upload vulnerability scan results
-        if: failure()
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: vulnerability-scan-results
-          path: |
-            vulnerability-report.json
-            nancy-report.json
-
   static-analysis:
     name: Static Security Analysis
     runs-on: ubuntu-latest
@@ -63,7 +46,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Set up Go
         uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
@@ -95,40 +78,11 @@ jobs:
 
       - name: Upload Semgrep SARIF results
         if: always()
-        uses: github/codeql-action/upload-sarif@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
+        uses: github/codeql-action/upload-sarif@87557b9c84dde89fdd9b10e88954ac2f4248e463 # v4.36.1
         with:
           sarif_file: semgrep.sarif
         continue-on-error: true
 
-  codeql-analysis:
-    name: CodeQL Analysis
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    steps:
-      - name: Checkout code
-        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@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
-        with:
-          languages: go
-          config-file: ./.github/codeql-config.yml
-
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@68bde559dea0fdcac2102bfdf6230c5f70eb485e # v4.35.4
-        with:
-          category: "/language:go"
-
   dependency-review:
     name: Dependency Review
     runs-on: ubuntu-latest
@@ -138,7 +92,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
 
       - name: Dependency Review
         uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
@@ -150,7 +104,7 @@ jobs:
   security-summary:
     name: Security Summary
     runs-on: ubuntu-latest
-    needs: [vulnerability-scan, static-analysis, codeql-analysis]
+    needs: [vulnerability-scan, static-analysis]
     if: always()
     permissions:
       contents: read
@@ -173,17 +127,11 @@ jobs:
             echo "❌ **Static Analysis**: FAILED" >> $GITHUB_STEP_SUMMARY
           fi
 
-          if [[ "${{ needs.codeql-analysis.result }}" == "success" ]]; then
-            echo "✅ **CodeQL Analysis**: PASSED" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "❌ **CodeQL Analysis**: FAILED" >> $GITHUB_STEP_SUMMARY
-          fi
-
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "For detailed results, check the individual job logs above." >> $GITHUB_STEP_SUMMARY
 
       - name: Fail on security issues
-        if: needs.vulnerability-scan.result == 'failure' || needs.static-analysis.result == 'failure' || needs.codeql-analysis.result == 'failure'
+        if: needs.vulnerability-scan.result == 'failure' || needs.static-analysis.result == 'failure'
         run: |
           echo "Security scan detected issues. Please review the results above."
           exit 1

.github/workflows/update-static-deps.yml

@@ -0,0 +1,50 @@
+name: Update Static Dependencies
+
+on:
+  pull_request:
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  update-deps:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]' || github.event_name == 'workflow_dispatch'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '24'
+          cache: 'npm'
+
+      - name: Update static dependencies
+        run: make update-static-deps
+
+      - name: Check for changes
+        id: git-check
+        run: |
+          git status --short pkg/service/soundtouchweb/static/lib/
+          if [ -n "$(git status --short pkg/service/soundtouchweb/static/lib/)" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Commit and push changes
+        if: steps.git-check.outputs.changed == 'true'
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add pkg/service/soundtouchweb/static/lib/
+          git commit -m "chore: sync static dependencies with package.json"
+          git push

.gitignore

@@ -43,10 +43,14 @@ go.work.sum
 
 # Dependency directories
 vendor/
+node_modules/
 
 # IDE and editor files
 .vscode/
 .idea/
+.claude/*
+!.claude/commands/
+.junie/
 *.swp
 *.swo
 *~
@@ -98,3 +102,34 @@ pids
 
 # dotenv environment variables file (but keep .env.example)
 !.env.example
+
+# Stockholm frontend — generated by `make prepare-stockholm`, not committed
+stockholm/
+
+!pkg/service/stockholm/
+
+# Stockholm source zip — large binary, place manually at stockholm_zip/stockholm.zip
+stockholm_zip/*.zip
+
+# Local working-tree notes — running pickup-here log (NEXT) + archive of
+# resolved items (DONE). Both are session-local scratch, not project docs.
+NEXT.md
+DONE.md
+
+# Code-scanning working notes — snapshot + remediation plan; not committed
+# until the sweep is complete and the notes are stable.
+CODE-SCANNING-NOTES.md
+
+# Plan/tracking note for the Health-tab debug-utility programme.
+# Living document; commit history of the checks themselves is the
+# source of truth for what shipped.
+SERVICE-HEALTH.md
+
+# Diagnostic encryption keys — private key stays local with the maintainer
+keys/private/
+
+# Hugo (docs site)
+# Hugo build artifacts (docs site)
+docs/.hugo_build.lock
+docs/public/
+docs/resources/

.golangci.yml

@@ -78,6 +78,13 @@ linters:
         linters:
           - errcheck
 
+      # Carry-over from cmd/soundtouch-web/handlers relocation: same code,
+      # same waiver. Tighten in a follow-up if/when the package is reviewed.
+      - path: pkg/service/soundtouchweb/.*\.go
+        text: "Error return value of.*is not checked"
+        linters:
+          - errcheck
+
   settings:
     errcheck:
       check-type-assertions: true

CLAUDE.md

@@ -0,0 +1,244 @@
+# CLAUDE.md
+
+Entry point for any Claude Code (or human) session working on this
+repository. Read it before touching code.
+
+## What this project is
+
+Go library and toolset for controlling Bose SoundTouch speakers via
+the local network API, plus a local cloud-service emulator. Bose
+discontinued the SoundTouch cloud — this project keeps existing
+speakers usable without it.
+
+**Module:** `github.com/gesellix/bose-soundtouch`
+
+Key binaries:
+
+- `soundtouch-cli` — command-line control of one or more speakers
+  (status, play, presets, groups, migration, …).
+- `soundtouch-service` — replacement for `streaming.bose.com`
+  and the `bmx` services, default port `8000`.
+- `soundtouch-web` — Web UI for Radio browsing and device control.
+- `soundtouch-backup` — Helper for on-device backup and restore.
+
+Per-session pickup notes live in two local files at the repo root (they are `.gitignore`d and only exist if created during a session):
+
+- `NEXT.md` — current "pick up here" log of open items.
+- `DONE.md` — archive of recently resolved items.
+
+## How a new session should start
+
+1. Read this file.
+2. Read `NEXT.md` if it's present — that's where running context lives.
+3. Skim `README.md` for the user-facing pitch.
+4. Skim `docs/` for the area you're touching. Long-form notes
+   (analysis, guides, troubleshooting) live there, not in the code.
+5. Run `make check` once to confirm the local environment compiles,
+   vets, and tests cleanly.
+
+## Build, test, run
+
+```bash
+# Build
+make build          # All binaries
+make build-cli      # Just CLI
+make build-service  # Just service
+make build-web      # Just web UI
+make build-all      # Cross-platform builds (Linux, macOS, Windows)
+make install        # Install to $GOPATH/bin
+
+# Quality
+make test           # Unit tests
+make test-coverage  # Coverage reports
+make check          # fmt + vet + test
+make lint           # golangci-lint
+make update-static-deps # Update frontend libraries (preact, htm) from node_modules
+
+# Automation
+A GitHub Action automatically runs `make update-static-deps` on Dependabot PRs that modify `package.json` to keep the vendored `.js` files in sync. Note: This requires `npm` to be installed.
+
+# Development
+make dev-service    # Run local service on port 8000
+make dev-discover   # Discover devices on the LAN
+make dev-info HOST=<ip>  # Get device info
+
+# Docker
+make docker-build
+make docker-run-host
+```
+
+**Pre-push quality gate:** `make lint` (golangci-lint) must be clean
+before `git push`. CI runs it on every PR; running it locally first
+saves a round-trip. `make check` covers `lint` is its own target —
+combine as needed.
+
+## Integration tests
+
+The `.http` integration tests under `tests/integration/http-client/`
+run via `make test-http-client`, which spins up the service plus
+support mocks (`spotify-mock`, `amazon-mock`) using
+`docker-compose.yml` + `docker-compose.ci.yml`, executes the suite
+through the JetBrains HTTP client image, then tears the stack down.
+Requires Docker.
+
+The compose CI override mounts `tests/integration/testdata/` into the
+service container as its persistent data dir. That directory is
+listed in `tests/.gitignore` — it's local developer state, not source.
+
+**Treat the testdata dir as debug evidence, not disposable scratch.**
+When a fixture or schema change makes the old state stale (e.g.
+post-anonymisation, the previous run's IPs no longer match the
+assertions), don't `rm -rf` it — archive it:
+
+```bash
+make test-http-client-rotate   # renames testdata/ → testdata_<timestamp>/
+make test-http-client          # fresh run on a clean slate
+```
+
+The rotate target is non-destructive (it moves, never deletes) and
+opt-in (no other target invokes it). Old archives stay around for
+retrospective diffing whenever something goes sideways.
+
+## Project structure
+
+```
+cmd/
+  soundtouch-cli/      # CLI tool for device control
+  soundtouch-service/  # Local cloud service emulator
+  soundtouch-web/      # Web UI (TuneIn browser, device control)
+  soundtouch-backup/   # On-device backup helper
+  example-*/           # Usage examples
+pkg/
+  client/              # HTTP + WebSocket client for the SoundTouch Web API
+  models/              # XML/JSON data structures
+  discovery/           # Device discovery (mDNS + UPnP, unified interface)
+  config/              # Configuration management
+  service/
+    bmx/               # Bose Media eXchange service emulation
+    marge/             # Device-management service emulation
+    handlers/          # HTTP request handlers (pkg/service/handlers/)
+    proxy/             # HTTP proxy with request recording
+    datastore/         # Persistent device data storage
+    certmanager/       # TLS certificate management
+    setup/             # Device migration and configuration
+    spotify/           # Spotify integration
+    stockholm/         # Optional Stockholm frontend bridge
+    soundtouchweb/     # SoundTouch Web UI service logic
+examples/              # Feature demonstration programs
+docs/                  # Long-form analysis, guides, troubleshooting
+.junie/                # Communication-style guidelines (see below)
+```
+
+## Key technologies
+
+- **Go 1.26.3+**
+- **chi v5** — HTTP router
+- **gorilla/websocket** — WebSocket for real-time events
+- **hashicorp/mdns** — mDNS device discovery
+- **miekg/dns** — DNS operations and a custom DNS server
+- **urfave/cli/v2** — CLI framework
+
+## Architecture notes
+
+- `pkg/client` is the core library for device API calls (HTTP + WebSocket).
+- `pkg/service` is the local cloud replacement; routes wire to the
+  handlers in `pkg/service/handlers/` via chi middleware.
+- Discovery supports both mDNS and UPnP/SSDP behind a unified interface.
+- The SoundTouch Web API uses XML on the wire; internal service-to-service
+  messages use JSON.
+- Tests cover unit, integration, parity (local vs. official Bose API
+  recordings), and regression. Reproducer tests should be refactored
+  into permanent regression or documentation tests rather than deleted.
+
+## Load-bearing gotchas
+
+### `ETag` header literal must stay capitalised
+
+Bose speakers emit the response header with exact capitalisation
+`ETag`. Go's `http.Header.Set` canonicalises to `Etag` (lowercase `t`).
+Real speakers parse strictly — `Etag` is rejected. The codebase
+deliberately bypasses the canonicalisation path; do **not** rewrite
+the string literal `"ETag"` to `"Etag"` anywhere in `pkg/service/handlers/`
+or in tests.
+
+The contrast is encoded in two named constants in
+`pkg/service/handlers/handlers_etag_test.go`:
+
+```go
+const normalizedEtag    = "Etag" // what http.Header.Set produces
+const caseSensitiveETag = "ETag" // what the speaker actually expects
+```
+
+Linter suppressions on the canonical-header check live alongside the
+test code. Static-analysis warnings about `"ETag"` are expected;
+don't "fix" them.
+
+### Destructive git or filesystem actions need explicit confirmation
+
+`git reset --hard`, `git checkout` that would overwrite local changes,
+`git clean -fd`, `rm -rf` on non-build paths, `git stash drop` — all
+should be proposed in writing with their consequences before running,
+unless the user has already authorised that specific action in this
+session. Prefer reversible alternatives (`git stash` over
+`git reset --hard`).
+
+**Force-flags also require explicit approval.** `git add -f` (force-add
+a gitignored file), `git push --force`, `git push --force-with-lease`,
+and any other flag that overrides a git safety mechanism must be
+proposed and confirmed before running, for the same reason: they
+bypass protections that exist intentionally.
+
+## What never goes into this repo
+
+This repository is public. The following must never be committed:
+
+- **Real LAN IPs** of personal networks. Use RFC-5737 documentation
+  ranges in examples and fixtures: `192.0.2.0/24`, `198.51.100.0/24`,
+  `203.0.113.0/24`.
+- **Real MAC addresses** or speaker device IDs from anyone's actual
+  hardware. Use `AA:BB:CC:DD:EE:FF` or `DEVICEID01` style placeholders.
+- **Bose account IDs**, serial numbers, or tokens belonging to anyone
+  other than the committer's own test devices — and even those should
+  be sanitised before publication when feasible.
+- **Bose firmware binaries, NAND dumps, or decompiled Bose code.**
+- **Wi-Fi SSIDs or credentials**, captured or otherwise.
+- **Network captures, traces, or logs** that include data from
+  accounts or devices other than your own test hardware.
+- **Personal identifiers**: real names of speakers ("LivingRoom",
+  custom device names), private email addresses, household member
+  names visible in source IDs.
+
+If you spot any of the above already in the tree, treat it as a
+sanitisation task: stop, flag it to the maintainer, propose a
+remediation commit before continuing.
+
+## Disclaimers
+
+"SoundTouch" and "Bose" are registered trademarks of Bose Corporation.
+This project is an unofficial, community-built effort, not affiliated
+with, endorsed by, or authorised by Bose.
+
+## Communication style
+
+When working with a human user in this repo:
+
+- **Prioritise direct answers** to the question being asked, even when
+  it sits outside the current task or project context. Don't divert
+  back to whatever you were doing when the user asks something else.
+- **Don't substitute assumptions for real information.** When something
+  is unclear, ask or check, rather than guessing and proceeding.
+- **An issue is only "resolved" once the reporter confirms.** Prefer
+  "candidate fix, awaiting reporter confirmation" over "fixed" or
+  "closed" until the person who reported it says it works. A merged PR
+  or a shipped release is not confirmation.
+- **Mind GitHub's `#<id>` auto-linking.** `#<id>` links to issues and
+  pull requests only — it does **not** resolve to discussions. For a
+  discussion, write the full URL
+  (`https://github.com/gesellix/Bose-SoundTouch/discussions/<id>`). For
+  security alerts, write e.g. "CodeQL alert 280" (no `#`) or the full
+  URL, since `#280` would point at an unrelated issue/PR.
+
+These principles also apply to other AI assistants pointed at this
+repo. Tool-specific config dirs (e.g. `.junie/`, `.claude/`) should
+defer to this file as the source of truth instead of carrying their
+own copies.

CONTRIBUTING.md

@@ -2,6 +2,17 @@
 
 Thank you for your interest in contributing to the Bose SoundTouch API Client! This project aims to provide a comprehensive, reliable, and well-tested Go library for controlling Bose SoundTouch devices.
 
+## Ways to Contribute
+
+All contributions are welcome — large or small:
+
+- **Code suggestions** — bug fixes, new features, refactoring, performance improvements.
+- **Documentation updates** — README, guides, examples, troubleshooting notes, inline doc comments.
+- **Bug fixes** — even just a clear reproducer in an issue is a real contribution.
+- **Donations** — if the project kept a speaker (or several) of yours alive past the Bose cloud shutdown and you want to give back, [GitHub Sponsors](https://github.com/sponsors/gesellix) is open. No expectation; everything in this repo stays MIT regardless.
+
+By submitting a code or documentation contribution you agree to license it under MIT. The detailed guides below cover the mechanics.
+
 ## Table of Contents
 
 - [Code of Conduct](#code-of-conduct)
@@ -15,6 +26,7 @@ Thank you for your interest in contributing to the Bose SoundTouch API Client! T
 - [Reporting Issues](#reporting-issues)
 - [Device Testing](#device-testing)
 - [Community](#community)
+- [Support the Project](#support-the-project)
 
 ## Code of Conduct
 
@@ -76,7 +88,7 @@ When filing a bug report, include:
 Feature requests are welcome! Please:
 
 1. **Check if the feature already exists** in documentation
-2. **Verify it's supported by the SoundTouch API** (see [official API docs](docs/reference/API-ENDPOINTS.md))
+2. **Verify it's supported by the SoundTouch API** (see [official API docs](docs/content/docs/reference/API-ENDPOINTS.md))
 3. **Explain the use case** and how it benefits users
 
 ### 🔧 Contributing Code
@@ -145,7 +157,7 @@ golangci-lint run --fix
 go install ./cmd/soundtouch-cli
 
 # Run integration tests (requires real device)
-make test-integration HOST=192.168.1.100
+make test-integration HOST=192.0.2.100
 ```
 
 ### Environment Setup
@@ -154,7 +166,7 @@ For development with real devices, create a `.env` file:
 
 ```env
 # Optional: Pre-configured device for testing
-SOUNDTOUCH_HOST=192.168.1.100
+SOUNDTOUCH_HOST=192.0.2.100
 SOUNDTOUCH_PORT=8090
 
 # Optional: Enable debug logging
@@ -328,7 +340,7 @@ When possible, test with real SoundTouch devices:
 
 ```bash
 # Set device IP for integration tests
-export SOUNDTOUCH_HOST=192.168.1.100
+export SOUNDTOUCH_HOST=192.0.2.100
 go test -tags integration ./pkg/client/
 ```
 
@@ -349,7 +361,7 @@ go test -tags integration ./pkg/client/
 // Basic usage:
 //
 //     client := client.NewClient(&client.Config{
-//         Host: "192.168.1.100",
+//         Host: "192.0.2.100",
 //         Port: 8090,
 //     })
 //     
@@ -398,8 +410,8 @@ If you have access to other SoundTouch models:
 
 2. **Test basic functionality**:
    ```bash
-   ./soundtouch-cli -h 192.168.1.100 info get
-   ./soundtouch-cli -h 192.168.1.100 now-playing get
+   ./soundtouch-cli -h 192.0.2.100 info get
+   ./soundtouch-cli -h 192.0.2.100 now-playing get
    ```
 
 3. **Report compatibility** in your PR or issue
@@ -465,12 +477,20 @@ Contributors will be:
 - **Mentioned in release notes** for significant contributions
 - **Credited in documentation** where appropriate
 
+## Support the Project
+
+If you want to support the maintenance effort beyond code:
+
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/gesellix?label=Sponsor%20on%20GitHub&logo=GitHub&color=ea4aaa)](https://github.com/sponsors/gesellix)
+
+Sponsorship is entirely optional. Code, docs, and bug reports remain the most useful contributions for the project itself.
+
 ## Additional Resources
 
 - [Go Documentation](https://golang.org/doc/)
 - [Effective Go](https://golang.org/doc/effective_go.html)
-- [Bose SoundTouch API Documentation](docs/reference/API-ENDPOINTS.md)
-- [Project Architecture](docs/PROJECT-PATTERNS.md)
+- [Bose SoundTouch API Documentation](docs/content/docs/reference/API-ENDPOINTS.md)
+- [Project Architecture](docs/content/docs/appendix/PROJECT-PATTERNS.md)
 - [Development Status](docs/archive/STATUS.md)
 
 ---

Dockerfile

@@ -1,5 +1,5 @@
 # Build stage
-FROM --platform=$BUILDPLATFORM golang:1.26.3-alpine AS builder
+FROM --platform=$BUILDPLATFORM golang:1.26.4-alpine AS builder
 
 # Declare automatic platform ARGs to make them available in build stage
 # See https://docs.docker.com/reference/dockerfile#automatic-platform-args-in-the-global-scope
@@ -8,6 +8,12 @@ ARG TARGETARCH
 ARG TARGETOS
 ARG TARGETVARIANT
 
+# Version info injected at build time; defaults keep local builds working.
+# The release workflow passes VERSION, COMMIT, and DATE via --build-arg.
+ARG VERSION=dev
+ARG COMMIT=unknown
+ARG DATE=unknown
+
 WORKDIR /app
 
 # Copy go mod and sum files
@@ -19,16 +25,24 @@ COPY . .
 
 # Build the soundtouch-service
 RUN if [ "${TARGETARCH}" = "arm" ] && [ -n "${TARGETVARIANT}" ]; then \
-      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} go build -o /soundtouch-service ./cmd/soundtouch-service; \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} \
+      go build -trimpath -ldflags="-s -w -X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}" \
+      -o /soundtouch-service ./cmd/soundtouch-service; \
     else \
-      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /soundtouch-service ./cmd/soundtouch-service; \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+      go build -trimpath -ldflags="-s -w -X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}" \
+      -o /soundtouch-service ./cmd/soundtouch-service; \
     fi
 
 # Build the soundtouch-web
 RUN if [ "${TARGETARCH}" = "arm" ] && [ -n "${TARGETVARIANT}" ]; then \
-      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} go build -o /soundtouch-web ./cmd/soundtouch-web; \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} GOARM=${TARGETVARIANT#v} \
+      go build -trimpath -ldflags="-s -w -X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}" \
+      -o /soundtouch-web ./cmd/soundtouch-web; \
     else \
-      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /soundtouch-web ./cmd/soundtouch-web; \
+      CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
+      go build -trimpath -ldflags="-s -w -X main.version=${VERSION} -X main.commit=${COMMIT} -X main.date=${DATE}" \
+      -o /soundtouch-web ./cmd/soundtouch-web; \
     fi
 
 # soundtouch-service image

Dockerfile.stockholm

@@ -0,0 +1,40 @@
+# Dockerfile.stockholm — builds the Stockholm frontend preparation image.
+#
+# This image clones krahl/soundcork-stockholm-app, installs the required tools
+# (prettier, patch, unzip, jq), and is used exclusively to run the entrypoint
+# preparation step that extracts and patches the Stockholm frontend.
+#
+# Java is NOT included — we stop before `exec java`.
+#
+# Usage (see Makefile targets build-stockholm-image / prepare-stockholm):
+#
+#   docker build --build-arg STOCKHOLM_APP_REF=main \
+#       -f Dockerfile.stockholm -t soundcork-stockholm-app .
+#
+#   docker run --rm \
+#       -v "$PWD/stockholm_zip:/app/stockholm_zip:ro" \
+#       -v "$PWD/stockholm:/app/stockholm" \
+#       --entrypoint bash soundcork-stockholm-app \
+#       -c 'awk "/^exec java/{exit} {print}" /app/docker-entrypoint.sh | bash'
+
+FROM debian:bookworm-slim
+
+ARG STOCKHOLM_APP_REF=main
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        git \
+        jq \
+        unzip \
+        nodejs \
+        npm \
+        patch && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g prettier@3.8.3 && npm cache clean --force
+
+RUN git clone --depth 1 --branch "${STOCKHOLM_APP_REF}" \
+    https://github.com/krahl/soundcork-stockholm-app /app
+
+WORKDIR /app

Makefile

@@ -1,4 +1,7 @@
-.PHONY: all build build-cli test test-coverage check fmt vet lint clean dev help screenshots
+.PHONY: all build build-cli test test-coverage test-http-client test-http-client-rotate check fmt vet lint clean dev help screenshots build-stockholm-image prepare-stockholm update-static-deps dev-docs dev-docs-tidy hugo
+
+# Load .env if present (simple KEY=VALUE format, no shell quoting)
+-include .env
 
 # Go parameters
 GOCMD=go
@@ -31,6 +34,22 @@ BUILD_DIR=./build
 # Build flags: strip debug info/DWARF for smaller binaries, remove local paths for reproducibility
 BUILDFLAGS=-trimpath -ldflags="-s -w"
 
+# Stockholm frontend preparation (see Dockerfile.stockholm and docs/stockholm-port-guide.md)
+# STOCKHOLM_APP_REF can be overridden to pin a specific commit: make build-stockholm-image STOCKHOLM_APP_REF=<sha>
+STOCKHOLM_IMAGE    ?= soundcork-stockholm-app
+STOCKHOLM_APP_REF  ?= main
+STOCKHOLM_ZIP_DIR  ?= $(CURDIR)/stockholm_zip
+STOCKHOLM_DIR      ?= $(CURDIR)/stockholm
+# URLs baked into stockholm/json/config.json during prepare-stockholm.
+# The Go service rewrites these again at startup using SERVER_URL / MARGE_URL,
+# so these only matter for static-file-only deployments or when pre-baking is desired.
+# Default to localhost:8000 (matches the Go service default).
+BACKEND_URL        ?= http://localhost:8000
+# STREAMING_URL defaults to BACKEND_URL (no /marge suffix — set to $(BACKEND_URL)/marge for soundcork).
+STREAMING_URL      ?= $(BACKEND_URL)
+# AUTH_SERVICE_URL defaults to BACKEND_URL; override to point at a different auth endpoint.
+AUTH_SERVICE_URL   ?= $(BACKEND_URL)
+
 all: check build
 
 build: build-cli build-service build-web build-examples build-favicon-gen build-backup
@@ -130,11 +149,23 @@ test-coverage:
 
 check: fmt vet test test-http-client
 
+# Archive any existing tests/integration/testdata/ to a timestamped sibling
+# so the next `make test-http-client` starts from a clean slate. Keeps the
+# old state around for retrospective debugging — never destructive.
+# Run BEFORE test-http-client when fixtures or schemas have changed and
+# stale state would otherwise be reused via the compose volume mount.
+test-http-client-rotate:
+	@if [ -d tests/integration/testdata ]; then \
+		archive=tests/integration/testdata_$$(date +%Y%m%d-%H%M%S); \
+		mv tests/integration/testdata "$$archive"; \
+		echo "Archived existing testdata to $$archive"; \
+	else \
+		echo "No tests/integration/testdata/ to archive — already fresh."; \
+	fi
+
 test-http-client:
-	@echo "Starting services with docker compose..."
-	@docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --build
-	@echo "Waiting for services to start..."
-	@sleep 10
+	@echo "Starting services with docker compose (waiting for healthchecks)..."
+	@docker compose -f docker-compose.yml -f docker-compose.ci.yml up -d --build --wait
 	@echo "Running .http tests..."
 	@docker run --rm --network soundtouch-test-net \
 		-v "$(PWD)/tests/integration/http-client:/workdir" \
@@ -144,11 +175,22 @@ test-http-client:
 		/workdir/spotify_registration.http \
 		/workdir/amazon_registration.http \
 		/workdir/create_account.http \
+		/workdir/get_emailaddress.http \
+		/workdir/get_customer_profile.http \
+		/workdir/post_customer_profile.http \
 		/workdir/register_device.http \
+		/workdir/post_scmudc_event.http \
+		/workdir/get_speaker_auth.http \
+		/workdir/get_blacklist.http \
+		/workdir/post_alexa_certificate.http \
+		/workdir/unsupported_routes.http \
 		/workdir/spotify_full_flow.http \
 		/workdir/customer_support.http \
 		/workdir/power_on.http \
 		/workdir/get_bmx_services.http \
+		/workdir/get_bmx_services_availability.http \
+		/workdir/get_bmx_service_descriptors.http \
+		/workdir/get_ced_index.http \
 		/workdir/get_sourceproviders.http \
 		/workdir/get_software_update.http \
 		/workdir/get_soundtouch_updates.http \
@@ -157,8 +199,15 @@ test-http-client:
 		/workdir/post_oauth_token_amazon.http \
 		/workdir/get_provider_settings.http \
 		/workdir/tunein_playback_station.http \
+		/workdir/post_tunein_report.http \
+		/workdir/tunein_favorite.http \
+		/workdir/get_orion_station.http \
+		/workdir/get_custom_playback.http \
+		/workdir/get_media_ding.http \
+		/workdir/get_bmx_icon.http \
 		/workdir/set_preset_6.http \
 		/workdir/get_presets.http \
+		/workdir/get_presets_conditional.http \
 		/workdir/delete_preset_6.http \
 		/workdir/set_preset_5.http \
 		/workdir/post_recent.http \
@@ -166,10 +215,15 @@ test-http-client:
 		/workdir/get_account_presets.http \
 		/workdir/get_account_devices.http \
 		/workdir/get_account_sources.http \
+		/workdir/delete_source.http \
 		/workdir/get_api_versions.http \
 		/workdir/post_musicprovider_is_eligible.http \
 		/workdir/get_full_account.http \
+		/workdir/get_full_account_conditional.http \
+		/workdir/create_group.http \
 		/workdir/get_group.http \
+		/workdir/delete_group.http \
+		/workdir/rename_device.http \
 		/workdir/unregister_device.http \
 		--report; \
 	EXIT_CODE=$$?; \
@@ -212,6 +266,18 @@ dev-service-proxy: build-service
 	fi
 	PYTHON_BACKEND_URL=$(PROXY_URL) $(BUILD_DIR)/$(SERVICE_NAME)
 
+# Run the service with the Stockholm frontend enabled. Requires that
+# `make prepare-stockholm` has been run at least once (the check below
+# avoids re-running the Docker container on every dev launch).
+dev-service-stockholm: build-service
+	@if [ ! -f "$(STOCKHOLM_DIR)/index.html" ]; then \
+		echo "Error: Stockholm not prepared at $(STOCKHOLM_DIR)."; \
+		echo "Run 'make prepare-stockholm' first (needs stockholm_zip/stockholm.zip)."; \
+		exit 1; \
+	fi
+	@echo "Starting development service with Stockholm enabled from $(STOCKHOLM_DIR)..."
+	STOCKHOLM_DIR=$(STOCKHOLM_DIR) $(BUILD_DIR)/$(SERVICE_NAME)
+
 dev-discover: build-cli
 	@echo "Running device discovery..."
 	$(BUILD_DIR)/$(BINARY_NAME) -discover
@@ -219,7 +285,7 @@ dev-discover: build-cli
 dev-info: build-cli
 	@echo "Getting device info (requires -host flag)..."
 	@if [ -z "$(HOST)" ]; then \
-		echo "Usage: make dev-info HOST=192.168.1.10"; \
+		echo "Usage: make dev-info HOST=192.0.2.10"; \
 		exit 1; \
 	fi
 	$(BUILD_DIR)/$(BINARY_NAME) -host $(HOST) -info
@@ -295,7 +361,7 @@ dev-backup-local: build-backup
 dev-web-host: build-web
 	@echo "Starting web UI with specific host..."
 	@if [ -z "$(HOST)" ]; then \
-		echo "Usage: make dev-web-host HOST=192.168.1.10"; \
+		echo "Usage: make dev-web-host HOST=192.0.2.10"; \
 		exit 1; \
 	fi
 	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -host $(HOST)
@@ -307,6 +373,10 @@ install: build-cli build-service build-web build-backup
 	cp $(BUILD_DIR)/$(WEB_NAME) $(GOPATH)/bin/
 	cp $(BUILD_DIR)/$(BACKUP_NAME) $(GOPATH)/bin/
 
+update-static-deps:
+	@echo "Updating static frontend dependencies..."
+	@./scripts/update-static-deps.sh
+
 clean:
 	@echo "Cleaning..."
 	$(GOCLEAN)
@@ -327,6 +397,69 @@ docker-build:
 	@echo "Building Docker image..."
 	docker build --target soundtouch-service -t soundtouch-service .
 
+# Stockholm frontend preparation.
+# Requires: Docker, internet access (clones github.com/krahl/soundcork-stockholm-app).
+# No pre-built image is published; the image must be built locally before running prepare-stockholm.
+build-stockholm-image:
+	@echo "Building Stockholm preparation image (clones upstream, installs prettier/patch)..."
+	docker build \
+		--build-arg STOCKHOLM_APP_REF=$(STOCKHOLM_APP_REF) \
+		-f Dockerfile.stockholm \
+		-t $(STOCKHOLM_IMAGE) \
+		.
+
+# Extracts and patches the Stockholm frontend using the upstream container image.
+# Requires: build-stockholm-image to have been run, and stockholm_zip/stockholm.zip to be present.
+# The resulting stockholm/ directory is used by the soundtouch-service at runtime.
+prepare-stockholm:
+	@mkdir -p "$(STOCKHOLM_DIR)"
+	@[ -f "$(STOCKHOLM_ZIP_DIR)/stockholm.zip" ] || { \
+		echo "Error: $(STOCKHOLM_ZIP_DIR)/stockholm.zip not found."; \
+		echo "Download the Stockholm zip and place it at stockholm_zip/stockholm.zip first."; \
+		exit 1; }
+	docker run --rm \
+		-e BACKEND_URL=$(BACKEND_URL) \
+		-e STREAMING_URL=$(STREAMING_URL) \
+		-e AUTH_SERVICE_URL=$(AUTH_SERVICE_URL) \
+		-v "$(STOCKHOLM_ZIP_DIR):/app/stockholm_zip:ro" \
+		-v "$(STOCKHOLM_DIR):/app/stockholm" \
+		--entrypoint bash \
+		$(STOCKHOLM_IMAGE) \
+		-c 'awk "/^exec java/{exit} {print}" /app/docker-entrypoint.sh | bash'
+	@# Patch update-urls.sh: replace the hardcoded ${BACKEND_URL}/marge with
+	@# ${STREAMING_URL:-${BACKEND_URL}} so the streaming URL is configurable and
+	@# defaults to BACKEND_URL (no /marge suffix) rather than the soundcork convention.
+	@script="$(STOCKHOLM_DIR)/json/update-urls.sh"; \
+	 awk '{ gsub(/\$$\{BACKEND_URL\}\/marge/, "$${STREAMING_URL:-$${BACKEND_URL}}"); print }' \
+	     "$$script" > "$$script.tmp" && mv "$$script.tmp" "$$script"
+	@# Restore config.json from the backup that update-urls.sh created.
+	@# The Go service rewrites URLs at startup via RewriteConfigURLs, so we start
+	@# from the original Bose URLs rather than whatever update-urls.sh produced.
+	@[ ! -f "$(STOCKHOLM_DIR)/json/backup.json" ] || \
+		cp "$(STOCKHOLM_DIR)/json/backup.json" "$(STOCKHOLM_DIR)/json/config.json"
+	@# Patch browse.js: guard against empty browse-path array so that
+	@# funcObj.browse.getPath() returning undefined does not throw when the user
+	@# has not browsed yet (causes "Now playing error: topLevel" console spam and
+	@# aborts the now-playing update handler).
+	@sed -i.bak \
+		-e 's/: (l()\.topLevel/: ((l() || {}).topLevel/' \
+		-e 's/var a = l()\.topLevel,/var a = (l() || {}).topLevel,/' \
+		-e 's/E() === 0 || funcObj\.browse\.getPath()\.topLevel/E() === 0 || (funcObj.browse.getPath() || {}).topLevel/' \
+		"$(STOCKHOLM_DIR)/js/browse.js" && \
+		rm -f "$(STOCKHOLM_DIR)/js/browse.js.bak"
+	@# Patch bridge JS: replace hardcoded /api/* paths with __stockholmBase-prefixed
+	@# versions so the bridge works when Stockholm is mounted under a base path.
+	@# browser_http_proxy.js declares the proxy URL as a top-level constant;
+	@# without patching it, requests from a /stockholm/* page hit /api/http-proxy
+	@# directly and 404 because the proxy is mounted under the base path.
+	@# Also fix resolveWebviewUrl to include the base path when resolving relative URLs.
+	@python3 scripts/patch-stockholm-bridge.py \
+		"$(STOCKHOLM_DIR)/js/browser_http_proxy.js" \
+		"$(STOCKHOLM_DIR)/js/browser_native_bridge.js" \
+		"$(STOCKHOLM_DIR)/js/app_comm.js" \
+		"$(STOCKHOLM_DIR)/setup/js/app_comm.js"
+	@echo "Stockholm frontend prepared at $(STOCKHOLM_DIR)"
+
 docker-run-host:
 	@echo "Running Docker container..."
 	@echo "Note: --network host is used for discovery (Linux only). For macOS/Windows use port mapping."
@@ -340,6 +473,22 @@ screenshots:
 	@echo "Capturing documentation screenshots..."
 	@bash scripts/screenshots/run.sh
 
+# Documentation site (Hugo + Hextra via Docker)
+# First run: make dev-docs-tidy  (downloads Hextra, writes docs/go.sum)
+# Then:      make dev-docs        (http://localhost:1313, live reload)
+dev-docs:
+	HUGO_PARAMS_GITHASH=$(shell git rev-parse HEAD) docker compose -f docker-compose.docs.yml up
+
+dev-docs-tidy:
+	docker compose -f docker-compose.docs.yml run --rm hugo mod tidy --source docs/
+
+# Run any hugo CLI command inside the docs container:
+#   make hugo ARGS="version"
+#   make hugo ARGS="new content/docs/guides/my-guide.md"
+ARGS ?=
+hugo:
+	docker compose -f docker-compose.docs.yml run --rm hugo --source docs/ $(ARGS)
+
 help:
 	@echo "Available targets:"
 	@echo "  build         - Build the CLI tool, service, and examples"
@@ -352,6 +501,8 @@ help:
 	@echo "  build-linux-armv7 - Build for Linux ARMv7 (kernel 3.14+ compatible, CGO_ENABLED=0)"
 	@echo "  test          - Run tests"
 	@echo "  test-coverage - Run tests with coverage report"
+	@echo "  test-http-client         - Run .http integration tests via Docker Compose"
+	@echo "  test-http-client-rotate  - Archive tests/integration/testdata/ before a fresh run (non-destructive)"
 	@echo "  check         - Run fmt, vet, and tests"
 	@echo "  fmt           - Format code"
 	@echo "  vet           - Run go vet"
@@ -360,7 +511,11 @@ 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 "  dev-service-stockholm - Build and run service with Stockholm frontend (requires prior 'make prepare-stockholm')"
 	@echo "  screenshots   - Capture documentation screenshots (headless Chrome via chromedp)"
+	@echo "  dev-docs      - Serve documentation site locally via Docker (http://localhost:1313)"
+	@echo "  dev-docs-tidy - Run hugo mod tidy (first run, or after hugo.toml module changes)"
+	@echo "  hugo ARGS=... - Run any hugo CLI command via Docker (e.g. make hugo ARGS=version)"
 	@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"
@@ -384,13 +539,16 @@ help:
 	@echo "  docker-build  - Build Docker image"
 	@echo "  docker-run-host  - Run container with host networking (Linux discovery)"
 	@echo "  docker-run-ports - Run container with port mapping (macOS/Windows/No discovery)"
+	@echo "  build-stockholm-image - Build Stockholm prep image (requires Docker + internet)"
+	@echo "  prepare-stockholm     - Extract and patch Stockholm frontend (requires build-stockholm-image"
+	@echo "                          and stockholm_zip/stockholm.zip; see docs/stockholm-port-guide.md)"
 	@echo "  help          - Show this help message"
 	@echo ""
 	@echo "Examples:"
 	@echo "  make dev-service"
-	@echo "  make dev-service-proxy PROXY_URL=http://192.168.1.50:8001"
+	@echo "  make dev-service-proxy PROXY_URL=http://192.0.2.50:8001"
 	@echo "  make dev-discover"
-	@echo "  make dev-info HOST=192.168.1.10"
+	@echo "  make dev-info HOST=192.0.2.10"
 	@echo "  make dev-mdns"
 	@echo "  make dev-mdns-verbose"
 	@echo "  make dev-mdns-timeout TIMEOUT=10s"
@@ -401,6 +559,6 @@ help:
 	@echo "  make dev-scan-soundtouch"
 	@echo "  make dev-web"
 	@echo "  make dev-web-port PORT=8888"
-	@echo "  make dev-web-host HOST=192.168.1.10"
+	@echo "  make dev-web-host HOST=192.0.2.10"
 	@echo "  make test"
 	@echo "  make build-all"

README.md

@@ -1,16 +1,21 @@
-# Bose SoundTouch Toolkit
+# <img src="media/favicon-braille.svg" width="32" height="32" valign="middle"> AfterTouch
+<p style="margin-top: -10px; font-style: italic; color: #666;">Bose SoundTouch Toolkit</p>
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/gesellix/bose-soundtouch.svg)](https://pkg.go.dev/github.com/gesellix/bose-soundtouch)
 [![Go Report Card](https://goreportcard.com/badge/github.com/gesellix/bose-soundtouch)](https://goreportcard.com/report/github.com/gesellix/bose-soundtouch)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> Independent project. Not affiliated with or endorsed by Bose Corporation.
+> Independent project. **Not affiliated with, endorsed by, sponsored
+> by, or otherwise connected to Bose Corporation.** See
+> [Disclaimer](#disclaimer) for the full statement.
 
-## Context: Cloud Shutdown
+## The Bose Cloud Has Shut Down
 
-Bose is shutting down SoundTouch cloud services on **May 6, 2026**. After that, music service browsing, preset sync, and the official SoundTouch app stop working. This toolkit lets you keep your speakers fully functional.
+Bose shut down SoundTouch cloud services on **May 6, 2026**. Presets, music service browsing, and stereo pairing no longer work through Bose's infrastructure. AfterTouch restores all of these — no Bose infrastructure required.
 
-See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html) for the full picture.
+See the [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/) for the full picture.
+
+[![AfterTouch docs homepage](media/docs-homepage.png)](https://gesellix.github.io/Bose-SoundTouch/)
 
 ---
 
@@ -20,15 +25,13 @@ 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.
+Not sure which approach fits your situation? See the [Deployment Overview](./docs/content/docs/guides/DEPLOYMENT-OVERVIEW.md) — it compares running AfterTouch on a Raspberry Pi or other always-on host against running it directly on the SoundTouch speaker, with links to step-by-step walkthroughs for each path.
 
-**Two scenarios:**
+**Getting started:**
 
-**Before shutdown — migrate your existing setup**
-While the Bose cloud is still running, use `soundtouch-backup` to save your account data. The local service web UI then helps with the migration so your speaker keeps its presets and credentials.
+**Already migrated before May 6** — your presets and credentials are preserved. AfterTouch picks up where the Bose cloud left off.
 
-**After shutdown or factory reset — start fresh**
-Create a local account, configure your speakers, and start using them immediately. No Bose infrastructure required.
+**Starting fresh (or after a factory reset)** — create a local account, configure your speakers, and start using them immediately.
 
 **Redirecting your speaker**
 
@@ -47,7 +50,7 @@ The web UI walks you through each method. DNS redirect requires HTTPS — the se
 
 Some setup steps require SSH access to the speaker. Enable it once per device: create a file named `remote_services` on a FAT-formatted USB drive (the drive may need its bootable flag set — see [SoundCork issue #172](https://github.com/deborahgu/soundcork/issues/172)), and insert it while the speaker is powered on. After reboot, root SSH is available with no password.
 
-See [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html) and [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-GUIDE.html) for step-by-step instructions.
+See [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/docs/guides/DEVICE-INITIAL-SETUP/) and [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/MIGRATION-GUIDE/) for step-by-step instructions.
 
 ---
 
@@ -63,7 +66,7 @@ See the [soundtouch-backup README](cmd/soundtouch-backup/README.md) for usage.
 
 Command-line control of any SoundTouch device: play/pause/volume, presets, source selection, multiroom zones, device discovery, and more. Works entirely over the local network — no cloud dependency. Well-suited for scripting and home automation.
 
-See the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html) for full usage.
+See the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/docs/guides/CLI-REFERENCE/) for full usage.
 
 ---
 
@@ -83,21 +86,21 @@ See the [soundtouch-web README](cmd/soundtouch-web/README.md) for usage.
 go get github.com/gesellix/bose-soundtouch
 ```
 
-See the [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html) and [pkg.go.dev](https://pkg.go.dev/github.com/gesellix/bose-soundtouch) for documentation.
+See the [API Reference](https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-ENDPOINTS/) and [pkg.go.dev](https://pkg.go.dev/github.com/gesellix/bose-soundtouch) for documentation.
 
 ---
 
 ## Documentation
 
-- [Getting Started](https://gesellix.github.io/Bose-SoundTouch/guides/GETTING-STARTED.html)
-- [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html)
-- [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-GUIDE.html)
-- [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html)
-- [Migration & Safety Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-SAFETY.html)
-- [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html)
-- [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html)
-- [HTTPS & CA Setup](https://gesellix.github.io/Bose-SoundTouch/guides/HTTPS-SETUP.html)
-- [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html)
+- [Getting Started](https://gesellix.github.io/Bose-SoundTouch/docs/guides/GETTING-STARTED/)
+- [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/)
+- [Migration Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/MIGRATION-GUIDE/)
+- [Device Initial Setup](https://gesellix.github.io/Bose-SoundTouch/docs/guides/DEVICE-INITIAL-SETUP/)
+- [Migration & Safety Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/MIGRATION-SAFETY/)
+- [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/docs/guides/CLI-REFERENCE/)
+- [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SOUNDTOUCH-SERVICE/)
+- [HTTPS & CA Setup](https://gesellix.github.io/Bose-SoundTouch/docs/guides/HTTPS-SETUP/)
+- [API Reference](https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-ENDPOINTS/)
 
 ---
 
@@ -122,8 +125,35 @@ See the [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API
 
 ---
 
+## Contributing
+
+Issues and pull requests welcome — code, documentation, bug reports, and feature ideas all land in the same place. By submitting a contribution you agree to license it under MIT. For significant changes please open an issue first to discuss the approach. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+## Support the project
+
+If this toolkit kept a speaker (or several) of yours alive past the Bose cloud shutdown and you want to give back, [GitHub Sponsors](https://github.com/sponsors/gesellix) is open. No expectation — everything in this repo stays MIT regardless.
+
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/gesellix?label=Sponsor%20on%20GitHub&logo=GitHub&color=ea4aaa)](https://github.com/sponsors/gesellix)
+
+## Disclaimer
+
+This is an independent open-source project. **Bose** and **SoundTouch**
+are registered trademarks of Bose Corporation in the United States and
+other countries. This project is **not affiliated with, endorsed by,
+sponsored by, or otherwise connected to** Bose Corporation.
+
+The toolkit exists solely to restore functionality of Bose SoundTouch
+speakers after the official cloud service shutdown on May 6, 2026.
+Reverse engineering for the sole purpose of interoperability is
+permitted under [EU Directive 2009/24/EC, Article 6](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32009L0024)
+("Decompilation"), and comparable provisions in other jurisdictions.
+
+The optional Stockholm frontend integration (`STOCKHOLM_DIR`) requires
+the user to supply the Stockholm web-app sources themselves; no Bose
+code is redistributed in this repository.
+
+The software is provided AS IS, without warranty. Use at your own risk.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).
-
-SoundTouch is a trademark of Bose Corporation.

cmd/dummy-speaker/logutil.go

@@ -0,0 +1,13 @@
+package main
+
+import "strings"
+
+// sanitizeLog strips newline characters from s to prevent log-injection
+// (CodeQL go/log-injection). Values from speakers, HTTP requests, and
+// external APIs may contain attacker-controlled newlines.
+func sanitizeLog(s string) string {
+	s = strings.ReplaceAll(s, "\n", `\n`)
+	s = strings.ReplaceAll(s, "\r", `\r`)
+
+	return s
+}

cmd/dummy-speaker/main.go

@@ -43,10 +43,10 @@ func main() {
 		log.Fatalf("start fake speaker: %v", err)
 	}
 
-	log.Printf("fake speaker HTTP listening on http://%s", s.HTTPAddr())
+	log.Printf("fake speaker HTTP listening on http://%s", sanitizeLog(s.HTTPAddr()))
 
 	if addr := s.TelnetAddr(); addr != "" {
-		log.Printf("fake speaker telnet listening on tcp://%s", addr)
+		log.Printf("fake speaker telnet listening on tcp://%s", sanitizeLog(addr))
 	}
 
 	if *register != "" {
@@ -58,7 +58,7 @@ func main() {
 		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)
+			log.Printf("registered %s with service at %s", sanitizeLog(target), sanitizeLog(*register))
 		}
 	}
 

cmd/mdns-scanner/logutil.go

@@ -0,0 +1,13 @@
+package main
+
+import "strings"
+
+// sanitizeLog strips newline characters from s to prevent log-injection
+// (CodeQL go/log-injection). Values from speakers, HTTP requests, and
+// external APIs may contain attacker-controlled newlines.
+func sanitizeLog(s string) string {
+	s = strings.ReplaceAll(s, "\n", `\n`)
+	s = strings.ReplaceAll(s, "\r", `\r`)
+
+	return s
+}

cmd/mdns-scanner/main.go

@@ -116,7 +116,7 @@ func main() {
 		defer close(entries)
 
 		if *verbose {
-			log.Printf("mDNS: Starting scan for service '%s' with timeout %v", *service, *timeout)
+			log.Printf("mDNS: Starting scan for service '%s' with timeout %v", sanitizeLog(*service), *timeout)
 		}
 
 		// Query for services
@@ -196,7 +196,7 @@ func parseServiceEntry(entry *mdns.ServiceEntry, verbose bool) *ServiceInfo {
 
 	if verbose {
 		log.Printf("mDNS: Received service entry: Name='%s', Host='%s', Port=%d, AddrV4=%v, AddrV6=%v",
-			entry.Name, entry.Host, entry.Port, entry.AddrV4, entry.AddrV6)
+			sanitizeLog(entry.Name), sanitizeLog(entry.Host), entry.Port, entry.AddrV4, entry.AddrV6)
 	}
 
 	service := &ServiceInfo{

cmd/mock-amazon/main.go

@@ -17,6 +17,9 @@ func main() {
 
 	log.Printf("Starting mock Amazon LWA server on port %d", *port)
 
+	// Plaintext HTTP is intentional: this is a throwaway test mock that only
+	// runs on the loopback / CI compose network, never in production.
+	// nosemgrep: go.lang.security.audit.net.use-tls.use-tls
 	if err := http.ListenAndServe(fmt.Sprintf(":%d", *port), amazon.NewAmazonHandler()); err != nil {
 		log.Fatal(err)
 	}

cmd/mock-spotify/main.go

@@ -17,6 +17,9 @@ func main() {
 
 	log.Printf("Starting mock Spotify server on port %d", *port)
 
+	// Plaintext HTTP is intentional: this is a throwaway test mock that only
+	// runs on the loopback / CI compose network, never in production.
+	// nosemgrep: go.lang.security.audit.net.use-tls.use-tls
 	if err := http.ListenAndServe(fmt.Sprintf(":%d", *port), spotify.NewSpotifyHandler()); err != nil {
 		log.Fatal(err)
 	}

cmd/mock-tunein/main.go

@@ -0,0 +1,26 @@
+// Package main provides a mock TuneIn (radiotime.com) server for testing.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+
+	"github.com/gesellix/bose-soundtouch/pkg/testutils/tunein"
+)
+
+func main() {
+	port := flag.Int("port", 8080, "Port to listen on")
+
+	flag.Parse()
+
+	log.Printf("Starting mock TuneIn server on port %d", *port)
+
+	// Plaintext HTTP is intentional: this is a throwaway test mock that only
+	// runs on the loopback / CI compose network, never in production.
+	// nosemgrep: go.lang.security.audit.net.use-tls.use-tls
+	if err := http.ListenAndServe(fmt.Sprintf(":%d", *port), tunein.NewTuneInHandler()); err != nil {
+		log.Fatal(err)
+	}
+}

cmd/soundtouch-backup/README.md

@@ -107,10 +107,10 @@ Backs up each speaker over its HTTP API on port 8090. With `--ssh`, also capture
 soundtouch-backup local
 
 # Specific speaker
-soundtouch-backup local --host 192.168.178.28
+soundtouch-backup local --host 192.0.2.11
 
 # Multiple speakers
-soundtouch-backup local --host 192.168.178.28 --host 192.168.178.35
+soundtouch-backup local --host 192.0.2.11 --host 192.0.2.10
 
 # Include SSH filesystem backup
 soundtouch-backup local --ssh
@@ -207,6 +207,6 @@ Running `cloud` and `local` separately produces two archives. To combine them, u
 
 ## See also
 
-- [Cloud Shutdown Survival Guide](../../docs/guides/SURVIVAL-GUIDE.md) — full migration context
+- [Cloud Shutdown Survival Guide](../../docs/content/docs/guides/SURVIVAL-GUIDE.md) — full migration context
 - [`soundtouch-cli`](../soundtouch-cli/) — live device control
 - [`soundtouch-service`](../soundtouch-service/) — local cloud replacement

cmd/soundtouch-cli/cmd_cloud.go

@@ -0,0 +1,128 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/urfave/cli/v2"
+)
+
+// cloudCommand assembles the `soundtouch-cli cloud …` command group.
+// All subcommands talk to the AfterTouch service (not the speaker directly)
+// and require --service-url.
+func cloudCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "cloud",
+		Usage: "Manage AfterTouch service data (sources, accounts, devices)",
+		Subcommands: []*cli.Command{
+			cloudSourceCmd(),
+		},
+	}
+}
+
+func cloudSourceCmd() *cli.Command {
+	return &cli.Command{
+		Name:  "source",
+		Usage: "Manage sources stored in AfterTouch",
+		Subcommands: []*cli.Command{
+			cloudSourceRemoveCmd(),
+		},
+	}
+}
+
+func cloudSourceRemoveCmd() *cli.Command {
+	return &cli.Command{
+		Name:  "remove",
+		Usage: "Remove a source from AfterTouch's datastore for a specific device",
+		Flags: append(CloudCommonFlags,
+			&cli.StringFlag{
+				Name:     "account",
+				Aliases:  []string{"a"},
+				Usage:    "Account ID",
+				Required: true,
+			},
+			&cli.StringFlag{
+				Name:     "device",
+				Aliases:  []string{"d"},
+				Usage:    "Device ID",
+				Required: true,
+			},
+			&cli.StringFlag{
+				Name:  "id",
+				Usage: "Source ID to remove (e.g. 10002)",
+			},
+			&cli.StringFlag{
+				Name:    "type",
+				Aliases: []string{"t"},
+				Usage:   "Source type to remove (e.g. INTERNET_RADIO). Resolved to a canonical ID; fails if multiple sources share the type.",
+			},
+		),
+		Action: cloudSourceRemove,
+	}
+}
+
+// canonicalSourceID maps well-known SourceKeyType values to their canonical IDs.
+// Used to resolve --type to an ID without requiring a round-trip GET.
+// TODO We need to ensure that ids here are consistent with the ones used in the AfterTouch service.
+var canonicalSourceID = map[string]string{
+	"AUX":                  "10001",
+	"INTERNET_RADIO":       "10002",
+	"LOCAL_INTERNET_RADIO": "10003",
+	"TUNEIN":               "10004",
+	"RADIO_BROWSER":        "10005",
+}
+
+func cloudSourceRemove(c *cli.Context) error {
+	serviceURL := strings.TrimRight(c.String("service-url"), "/")
+	account := c.String("account")
+	device := c.String("device")
+	sourceID := c.String("id")
+	sourceType := strings.ToUpper(c.String("type"))
+
+	if sourceID == "" && sourceType == "" {
+		return fmt.Errorf("one of --id or --type is required")
+	}
+
+	if sourceID != "" && sourceType != "" {
+		return fmt.Errorf("only one of --id or --type may be given")
+	}
+
+	if sourceType != "" {
+		id, ok := canonicalSourceID[sourceType]
+		if !ok {
+			return fmt.Errorf("unknown source type %q; use --id for non-canonical sources", sourceType)
+		}
+
+		sourceID = id
+	}
+
+	url := fmt.Sprintf("%s/setup/sources/%s/%s/%s", serviceURL, account, device, sourceID)
+
+	req, err := http.NewRequest(http.MethodDelete, url, nil)
+	if err != nil {
+		return fmt.Errorf("build request: %w", err)
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("request failed: %w", err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode == http.StatusNoContent {
+		PrintSuccess(fmt.Sprintf("Removed source %s from device %s (account %s)", sourceID, device, account))
+
+		if sourceType != "" {
+			fmt.Printf("  Type: %s\n", sourceType)
+		}
+
+		return nil
+	}
+
+	body, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<10))
+
+	return fmt.Errorf("service returned %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+}

cmd/soundtouch-cli/cmd_discover.go

@@ -15,6 +15,11 @@ import (
 func discoverDevices(c *cli.Context) error {
 	fmt.Printf("Discovering SoundTouch devices...\n")
 
+	// CLI discovery is interactive — flip on verbose protocol logging
+	// so operators can see per-packet / per-header detail. The service
+	// binary leaves this off so its log stays terse.
+	discovery.SetVerbose(c.Bool("verbose"))
+
 	// Load configuration
 	cfg, err := config.LoadFromEnv()
 	if err != nil {

cmd/soundtouch-cli/cmd_events.go

@@ -413,9 +413,11 @@ func handlePresetEvent(event *models.PresetUpdatedEvent, verbose bool) {
 	for _, preset := range presets.Preset {
 		fmt.Printf("  📻 Preset %d:", preset.ID)
 
-		if preset.ContentItem != nil {
-			fmt.Printf(" %s", preset.ContentItem.ItemName)
-			fmt.Printf(" (%s)", preset.ContentItem.Source)
+		// IsEmpty catches both <preset/> and INVALID_SOURCE
+		// placeholders; using the nil-safe helpers below means the
+		// inner Printf never dereferences a nil ContentItem.
+		if !preset.IsEmpty() {
+			fmt.Printf(" %s (%s)", preset.GetDisplayName(), preset.GetSource())
 		}
 
 		fmt.Println()
@@ -566,7 +568,7 @@ type VerboseLogger struct{}
 
 func (v *VerboseLogger) Printf(format string, args ...interface{}) {
 	timestamp := time.Now().Format("15:04:05")
-	fmt.Printf("[%s] [WebSocket] %s\n", timestamp, fmt.Sprintf(format, args...))
+	fmt.Printf("[%s] [WebSocket] %s\n", timestamp, sanitizeLog(fmt.Sprintf(format, args...)))
 }
 
 type SilentLogger struct{}

cmd/soundtouch-cli/cmd_group.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"net"
+	"sync"
 
 	"github.com/gesellix/bose-soundtouch/pkg/client"
 	"github.com/gesellix/bose-soundtouch/pkg/models"
@@ -37,7 +38,10 @@ func getGroupStatus(c *cli.Context) error {
 	return nil
 }
 
-// createGroup forms a stereo pair on the LEFT speaker, which becomes the master.
+// 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")
@@ -80,6 +84,8 @@ func createGroup(c *cli.Context) error {
 				{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)
@@ -88,18 +94,109 @@ func createGroup(c *cli.Context) error {
 		return err
 	}
 
-	result, err := leftClient.AddGroup(req)
+	rightClient, err := clientForHost(c, rightIP)
 	if err != nil {
-		PrintError(fmt.Sprintf("Failed to create group: %v", err))
+		PrintError(fmt.Sprintf("Failed to create client for RIGHT: %v", err))
 		return err
 	}
 
-	PrintSuccess(fmt.Sprintf("Stereo pair created (id=%s)", result.ID))
-	printGroup(result)
+	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.
@@ -147,7 +244,10 @@ func renameGroup(c *cli.Context) error {
 	return nil
 }
 
-// removeGroup tears down the device's stereo pair.
+// removeGroup tears down the device's stereo pair by sending /removeGroup to
+// every member in parallel. Sending it only to the master (as the old code
+// did) leaves the slave stuck in GroupSlave state indefinitely — mirrors the
+// same symmetry as createGroup (see issue #252 comment there).
 func removeGroup(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)
 	PrintDeviceHeader("Removing stereo pair", clientConfig.Host, clientConfig.Port)
@@ -158,11 +258,76 @@ func removeGroup(c *cli.Context) error {
 		return err
 	}
 
-	if err := stClient.RemoveGroup(); err != nil {
-		PrintError(fmt.Sprintf("Failed to remove group: %v", err))
+	// Fetch current group to learn every member's IP before tearing down.
+	group, err := stClient.GetGroup()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read current group: %v", err))
 		return err
 	}
 
+	if group.IsEmpty() {
+		fmt.Println("Device is not in a stereo pair — nothing to remove")
+		return nil
+	}
+
+	// Collect the unique set of member IPs. The master is always reachable
+	// via clientConfig.Host; the roles carry all members including slaves.
+	type memberResult struct {
+		ip  string
+		err error
+	}
+
+	members := make([]string, 0, len(group.Roles.Roles))
+	seen := map[string]bool{}
+
+	for _, role := range group.Roles.Roles {
+		if role.IPAddress != "" && !seen[role.IPAddress] {
+			seen[role.IPAddress] = true
+			members = append(members, role.IPAddress)
+		}
+	}
+
+	// Always include the addressed host even if the group response omitted IPs.
+	if !seen[clientConfig.Host] {
+		members = append(members, clientConfig.Host)
+	}
+
+	results := make([]memberResult, len(members))
+
+	var wg sync.WaitGroup
+
+	for i, ip := range members {
+		wg.Add(1)
+
+		go func(idx int, host string) {
+			defer wg.Done()
+
+			mc, mcErr := clientForHost(c, host)
+			if mcErr != nil {
+				results[idx] = memberResult{ip: host, err: mcErr}
+				return
+			}
+
+			results[idx] = memberResult{ip: host, err: mc.RemoveGroup()}
+		}(i, ip)
+	}
+
+	wg.Wait()
+
+	anyErr := false
+
+	for _, r := range results {
+		if r.err != nil {
+			PrintError(fmt.Sprintf("%s /removeGroup failed: %v", r.ip, r.err))
+
+			anyErr = true
+		}
+	}
+
+	if anyErr {
+		return fmt.Errorf("/removeGroup propagation failed")
+	}
+
 	PrintSuccess("Stereo pair removed")
 
 	return nil

cmd/soundtouch-cli/cmd_group_test.go

@@ -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.0.2.131", "192.0.2.134")
+
+	leftOut, rightOut := propagateAddGroup(leftClient, rightClient, "192.0.2.131", "192.0.2.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.0.2.131</senderIPAddress>") {
+		t.Errorf("RIGHT (slave) body must carry <senderIPAddress>192.0.2.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.0.2.131", "192.0.2.134")
+
+	leftOut, rightOut := propagateAddGroup(leftClient, rightClient, "192.0.2.131", "192.0.2.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)
+	}
+}

cmd/soundtouch-cli/cmd_info.go

@@ -177,23 +177,36 @@ func getPresets(c *cli.Context) error {
 
 	fmt.Printf("Device Presets:\n")
 
-	if len(presets.Preset) == 0 {
+	// Filter out placeholder presets the firmware emits for unconfigured
+	// slots (issue #308): self-closing <preset/> after factory reset,
+	// or <ContentItem source="INVALID_SOURCE"/> on healthy devices.
+	// IsEmpty covers both shapes; accessing fields like ContentItem.Source
+	// directly on the first shape panics.
+	configured := make([]models.Preset, 0, len(presets.Preset))
+
+	for _, p := range presets.Preset {
+		if !p.IsEmpty() {
+			configured = append(configured, p)
+		}
+	}
+
+	if len(configured) == 0 {
 		fmt.Printf("  No presets configured\n")
 		return nil
 	}
 
 	fmt.Printf("  Configured Presets:\n")
 
-	for _, preset := range presets.Preset {
+	for _, preset := range configured {
 		fmt.Printf("    %d. %s\n", preset.ID, preset.GetDisplayName())
-		fmt.Printf("       Source: %s\n", preset.ContentItem.Source)
+		fmt.Printf("       Source: %s\n", preset.GetSource())
 
-		if preset.ContentItem.SourceAccount != "" && preset.ContentItem.SourceAccount != preset.ContentItem.Source {
-			fmt.Printf("       Account: %s\n", preset.ContentItem.SourceAccount)
+		if account := preset.GetSourceAccount(); account != "" && account != preset.GetSource() {
+			fmt.Printf("       Account: %s\n", account)
 		}
 
-		if preset.ContentItem.Location != "" {
-			fmt.Printf("       Location: %s\n", preset.ContentItem.Location)
+		if location := preset.GetLocation(); location != "" {
+			fmt.Printf("       Location: %s\n", location)
 		}
 
 		// Show preset creation time if available

cmd/soundtouch-cli/cmd_introspect_test.go

@@ -17,7 +17,7 @@ func TestIntrospectCommands(t *testing.T) {
 	}{
 		{
 			name: "introspect service with source flag",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect", "--source", "SPOTIFY"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "source", "introspect", "--source", "SPOTIFY"},
 			expectedOutput: []string{
 				"Getting introspect data for SPOTIFY",
 				"=== SPOTIFY Service Introspect Data ===",
@@ -47,7 +47,7 @@ func TestIntrospectCommands(t *testing.T) {
 		},
 		{
 			name: "introspect spotify convenience command",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect-spotify"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "source", "introspect-spotify"},
 			expectedOutput: []string{
 				"Getting Spotify introspect data",
 				"=== Spotify Service Introspect Data ===",
@@ -60,7 +60,7 @@ func TestIntrospectCommands(t *testing.T) {
 		},
 		{
 			name: "introspect with account parameter",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect", "--source", "SPOTIFY", "--account", "my_spotify_account"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "source", "introspect", "--source", "SPOTIFY", "--account", "my_spotify_account"},
 			expectedOutput: []string{
 				"Getting introspect data for SPOTIFY",
 				"Source Account: my_spotify_account",
@@ -68,7 +68,7 @@ func TestIntrospectCommands(t *testing.T) {
 		},
 		{
 			name:        "introspect missing source flag",
-			args:        []string{"soundtouch-cli", "--host", "192.168.1.100", "source", "introspect"},
+			args:        []string{"soundtouch-cli", "--host", "192.0.2.100", "source", "introspect"},
 			expectError: true,
 		},
 		{

cmd/soundtouch-cli/cmd_preset.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"strings"
 
+	bmxpkg "github.com/gesellix/bose-soundtouch/pkg/service/bmx"
+
 	"github.com/gesellix/bose-soundtouch/pkg/models"
 	"github.com/urfave/cli/v2"
 )
@@ -85,6 +87,7 @@ type presetParams struct {
 	name          string
 	itemType      string
 	artwork       string
+	serviceURL    string
 }
 
 // extractPresetParams extracts parameters from CLI context
@@ -97,9 +100,16 @@ func extractPresetParams(c *cli.Context) *presetParams {
 		name:          c.String("name"),
 		itemType:      c.String("type"),
 		artwork:       c.String("artwork"),
+		serviceURL:    strings.TrimRight(c.String("service-url"), "/"),
 	}
 }
 
+// isOrionLocation reports whether location is already an Orion station URL so
+// we don't double-wrap it.
+func isOrionLocation(location string) bool {
+	return strings.Contains(location, "/core02/svc-bmx-adapter-orion/")
+}
+
 // resolveLocationAndMetadata resolves location and fetches metadata if needed
 func resolveLocationAndMetadata(params *presetParams) error {
 	originalLocation := params.location
@@ -108,6 +118,24 @@ func resolveLocationAndMetadata(params *presetParams) error {
 	params.source = resolvedSource
 	params.location = resolvedLocation
 
+	// For LOCAL_INTERNET_RADIO, the speaker's BMX module calls GET on the stored
+	// location expecting a BmxPlaybackResponse JSON (the Orion station format).
+	// A direct stream URL returns raw audio, which BMX cannot parse, so playback
+	// silently stays on the previous source.
+	if params.source == "LOCAL_INTERNET_RADIO" &&
+		!isOrionLocation(params.location) &&
+		(strings.HasPrefix(params.location, "http://") || strings.HasPrefix(params.location, "https://")) {
+		if params.serviceURL != "" {
+			params.location = bmxpkg.BuildOrionLocation(params.serviceURL, params.name, params.artwork, resolvedLocation)
+
+			fmt.Printf("  Wrapped stream URL in Orion location for LOCAL_INTERNET_RADIO\n")
+		} else {
+			fmt.Printf("  ⚠️  --service-url not set: storing raw stream URL as location.\n")
+			fmt.Printf("     The speaker's BMX module expects an Orion station URL, not raw audio.\n")
+			fmt.Printf("     Re-run with --service-url <https://your-aftertouch-host> to fix this.\n")
+		}
+	}
+
 	// If metadata (name or artwork) is missing, try to fetch it
 	if params.name == "" || params.artwork == "" {
 		var (

cmd/soundtouch-cli/cmd_recents_test.go

@@ -17,7 +17,7 @@ func TestRecentsCommands(t *testing.T) {
 	}{
 		{
 			name: "recents list command",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "list"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "recents", "list"},
 			expectedOutput: []string{
 				"Getting recently played content",
 				"Recent Items Summary:",
@@ -26,7 +26,7 @@ func TestRecentsCommands(t *testing.T) {
 		},
 		{
 			name: "recents filter by source",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "filter", "--source", "SPOTIFY"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "recents", "filter", "--source", "SPOTIFY"},
 			expectedOutput: []string{
 				"Getting filtered recent content",
 				"filtered by source: SPOTIFY",
@@ -34,7 +34,7 @@ func TestRecentsCommands(t *testing.T) {
 		},
 		{
 			name: "recents latest command",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "latest"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "recents", "latest"},
 			expectedOutput: []string{
 				"Getting most recent item",
 				"Most Recent Item:",
@@ -42,7 +42,7 @@ func TestRecentsCommands(t *testing.T) {
 		},
 		{
 			name: "recents stats command",
-			args: []string{"soundtouch-cli", "--host", "192.168.1.100", "recents", "stats"},
+			args: []string{"soundtouch-cli", "--host", "192.0.2.100", "recents", "stats"},
 			expectedOutput: []string{
 				"Getting recent items statistics",
 				"Recent Items Statistics",

cmd/soundtouch-cli/cmd_setup.go

@@ -48,6 +48,7 @@ func setupCommand() *cli.Command {
 			setupWaitAPCmd(),
 			setupWaitOnlineCmd(),
 			setupSSHCheckCmd(),
+			setupRemoteServicesCmd(),
 			setupInstallCACmd(),
 			setupMigrateCmd(),
 			setupRebootCmd(),
@@ -404,7 +405,7 @@ func setupWiFiPushCmd() *cli.Command {
 			&cli.StringFlag{Name: "pass", Required: true, Usage: "Home Wi-Fi password"},
 			&cli.StringFlag{Name: "security", Value: setup.DefaultWiFiSecurity, Usage: "Security type (wpa_or_wpa2, wep, open)"},
 			&cli.StringFlag{Name: "ap-host", Value: setup.SpeakerSetupAP, Usage: "Speaker's setup-mode IP"},
-			&cli.DurationFlag{Name: "request-timeout", Value: 10 * time.Second},
+			&cli.DurationFlag{Name: "request-timeout", Value: 30 * time.Second, Usage: "Per-request timeout (the speaker can be slow to ACK before tearing down AP mode; 10 s often races)"},
 		},
 		Action: func(c *cli.Context) error {
 			params := setup.PushWiFiCredentialsParams{
@@ -536,6 +537,51 @@ func setupSSHCheckCmd() *cli.Command {
 	}
 }
 
+func setupRemoteServicesCmd() *cli.Command {
+	return &cli.Command{
+		Name:   "remote-services",
+		Usage:  "Enable (default) or disable the remote_services SSH-enablement marker on the speaker",
+		Before: RequireHost,
+		Flags: []cli.Flag{
+			&cli.BoolFlag{
+				Name:  "remove",
+				Usage: "Remove all remote_services marker files (disables SSH after next reboot)",
+			},
+		},
+		Action: func(c *cli.Context) error {
+			cfg := GetClientConfig(c)
+			m := setup.NewManager("", nil, nil)
+
+			var (
+				logs string
+				err  error
+			)
+			if c.Bool("remove") {
+				logs, err = m.RemoveRemoteServices(cfg.Host)
+			} else {
+				logs, err = m.EnsureRemoteServices(cfg.Host)
+			}
+
+			if logs != "" {
+				fmt.Print(logs)
+			}
+
+			if err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
+			if c.Bool("remove") {
+				PrintSuccess("remote_services removed — SSH will no longer be enabled after next reboot")
+			} else {
+				PrintSuccess("remote_services enabled at a persistent location")
+			}
+
+			return nil
+		},
+	}
+}
+
 func setupInstallCACmd() *cli.Command {
 	return &cli.Command{
 		Name:   "install-ca",
@@ -549,13 +595,18 @@ func setupInstallCACmd() *cli.Command {
 			cfg := GetClientConfig(c)
 			serviceURL := strings.TrimRight(c.String("service-url"), "/")
 
+			if err := validateServiceURL(serviceURL); err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
 			certPEM, err := fetchCACert(serviceURL, c.String("auth"))
 			if err != nil {
 				PrintError(err.Error())
 				return err
 			}
 
-			fmt.Printf("Fetched %d bytes of CA PEM from %s/setup/ca.crt\n", len(certPEM), serviceURL)
+			fmt.Printf("Fetched %d bytes of CA PEM from %s/api/setup/ca.crt\n", len(certPEM), serviceURL)
 
 			m := setup.NewManager(serviceURL, nil, nil)
 
@@ -576,11 +627,11 @@ func setupInstallCACmd() *cli.Command {
 	}
 }
 
-// fetchCACert pulls AfterTouch's CA bundle from /setup/ca.crt. On HTTP 401
+// fetchCACert pulls AfterTouch's CA bundle from /api/setup/ca.crt. On HTTP 401
 // it prompts interactively for basic-auth credentials (or accepts --auth)
 // and retries once.
 func fetchCACert(serviceURL, authFlag string) ([]byte, error) {
-	url := serviceURL + "/setup/ca.crt"
+	url := serviceURL + "/api/setup/ca.crt"
 
 	doRequest := func(user, pass string) (*http.Response, error) {
 		req, err := http.NewRequest(http.MethodGet, url, nil)
@@ -698,11 +749,17 @@ func setupMigrateCmd() *cli.Command {
 			method := setup.MigrationMethod(c.String("method"))
 			serviceURL := c.String("service-url")
 
-			// For DNS-redirect methods, prove AfterTouch's DNS listener
-			// is alive by sending it a real query — that's the truth,
-			// regardless of what its settings claim.
+			if err := validateServiceURL(serviceURL); err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
+			m := setup.NewManager(serviceURL, nil, nil)
+
+			// For DNS-redirect methods check that AfterTouch's DNS listener
+			// is reachable — both from this machine and from the speaker.
 			if !c.Bool("skip-preflight") && (method == setup.MigrationMethodResolvConf || method == setup.MigrationMethodHosts) {
-				if err := requireAfterTouchDNSReachable(serviceURL); err != nil {
+				if err := runDNSPreflight(cfg.Host, serviceURL, m.NewSSH); err != nil {
 					PrintError(err.Error())
 					return err
 				}
@@ -720,8 +777,6 @@ func setupMigrateCmd() *cli.Command {
 
 			fmt.Printf("Migrating %s → %s using method=%s\n", cfg.Host, serviceURL, method)
 
-			m := setup.NewManager(serviceURL, nil, nil)
-
 			logs, err := m.MigrateSpeaker(cfg.Host, serviceURL, c.String("proxy-url"), nil, method)
 			if logs != "" {
 				fmt.Print(logs)
@@ -762,31 +817,53 @@ func preInstallCAForCLI(deviceIP, serviceURL string) error {
 	return nil
 }
 
-// requireAfterTouchDNSReachable sends a real DNS query to AfterTouch's
-// port-53 listener and confirms it responds. This is the ground-truth
-// preflight for DNS-redirect migration methods — config inspection (the
-// previous approach via GET /setup/settings) can lag the actual listener
-// state and can't tell us whether queries succeed end-to-end.
-//
-// We query a known-intercepted hostname (streaming.bose.com). Any IP in
-// the response proves AfterTouch's DNS is alive on :53; if the listener
-// is down the custom Dial just times out and the user gets a clear error.
-func requireAfterTouchDNSReachable(serviceURL string) error {
+// validateServiceURL returns an error if serviceURL cannot be parsed or has no
+// hostname. A common mistake is a single-slash scheme (https:/host instead of
+// https://host); the error message hints at the correction in that case.
+func validateServiceURL(serviceURL string) error {
 	parsed, err := url.Parse(serviceURL)
 	if err != nil {
-		return fmt.Errorf("preflight: parse service URL %q: %w", serviceURL, err)
+		return fmt.Errorf("invalid --service-url %q: %w", serviceURL, err)
 	}
 
-	host := parsed.Hostname()
-	if host == "" {
-		return fmt.Errorf("preflight: service URL %q has no hostname", serviceURL)
+	if parsed.Hostname() == "" {
+		hint := ""
+		if parsed.Scheme != "" && parsed.Opaque != "" {
+			hint = fmt.Sprintf(" (did you mean %s://%s?)", parsed.Scheme, strings.TrimPrefix(parsed.Opaque, "/"))
+		}
+
+		return fmt.Errorf("invalid --service-url %q: no hostname found%s", serviceURL, hint)
 	}
 
+	return nil
+}
+
+// dnsCheckResult holds the outcome of one DNS reachability probe.
+type dnsCheckResult struct {
+	ok      bool
+	unknown bool   // SSH unavailable or nslookup not present — result indeterminate
+	detail  string // "works" on success, error reason otherwise
+}
+
+func (r dnsCheckResult) label() string {
+	switch {
+	case r.ok:
+		return "✓ works"
+	case r.unknown:
+		return "? " + r.detail
+	default:
+		return "✗ " + r.detail
+	}
+}
+
+// cliDNSCheck sends a real DNS query for streaming.bose.com through the
+// AfterTouch DNS listener to verify it is alive from this machine.
+func cliDNSCheck(dnsHost string) dnsCheckResult {
 	resolver := &net.Resolver{
 		PreferGo: true,
 		Dial: func(ctx context.Context, _, _ string) (net.Conn, error) {
 			d := net.Dialer{Timeout: 3 * time.Second}
-			return d.DialContext(ctx, "udp", net.JoinHostPort(host, "53"))
+			return d.DialContext(ctx, "udp", net.JoinHostPort(dnsHost, "53"))
 		},
 	}
 
@@ -795,14 +872,91 @@ func requireAfterTouchDNSReachable(serviceURL string) error {
 
 	ips, err := resolver.LookupHost(ctx, "streaming.bose.com")
 	if err != nil {
-		return fmt.Errorf(
-			"preflight: DNS query to %s:53 failed: %w. AfterTouch's DNS listener is unreachable or not bound to port 53. Use --skip-preflight to bypass once you've verified DNS some other way",
-			host, err,
-		)
+		return dnsCheckResult{detail: err.Error()}
 	}
 
 	if len(ips) == 0 {
-		return fmt.Errorf("preflight: %s:53 returned no answers for streaming.bose.com — listener may be misconfigured", host)
+		return dnsCheckResult{detail: "no answers for streaming.bose.com — listener may be misconfigured"}
+	}
+
+	return dnsCheckResult{ok: true, detail: "works"}
+}
+
+// speakerDNSCheck SSHes into the speaker and runs nslookup streaming.bose.com
+// against the AfterTouch DNS server to verify reachability from the device.
+func speakerDNSCheck(deviceIP, dnsHost string, newSSH func(string) setup.SSHClient) dnsCheckResult {
+	addrs, err := net.LookupHost(dnsHost)
+	if err != nil || len(addrs) == 0 {
+		return dnsCheckResult{unknown: true, detail: fmt.Sprintf("cannot resolve %s locally to run speaker-side check", dnsHost)}
+	}
+
+	dnsIP := addrs[0]
+
+	client := newSSH(deviceIP)
+
+	out, sshErr := client.Run(fmt.Sprintf("nslookup streaming.bose.com %s", dnsIP))
+	if sshErr != nil {
+		if strings.Contains(out, "not found") || strings.Contains(out, "No such file") {
+			return dnsCheckResult{unknown: true, detail: "nslookup not available on speaker"}
+		}
+
+		if strings.Contains(sshErr.Error(), "dial") || strings.Contains(sshErr.Error(), "connect") {
+			return dnsCheckResult{unknown: true, detail: fmt.Sprintf("SSH unavailable: %s", sshErr)}
+		}
+
+		msg := strings.TrimSpace(out)
+		if msg == "" {
+			msg = sshErr.Error()
+		}
+
+		return dnsCheckResult{detail: msg}
+	}
+
+	return dnsCheckResult{ok: true, detail: "works"}
+}
+
+// runDNSPreflight checks AfterTouch DNS reachability from both the CLI machine
+// and the speaker, prints a table, and returns an error only when the speaker
+// side definitively cannot reach the DNS listener (CLI-only failures are
+// informational — the speaker's perspective is authoritative).
+func runDNSPreflight(deviceIP, serviceURL string, newSSH func(string) setup.SSHClient) error {
+	parsed, _ := url.Parse(serviceURL)
+	dnsHost := parsed.Hostname()
+
+	type result struct {
+		cli     dnsCheckResult
+		speaker dnsCheckResult
+	}
+
+	ch := make(chan result, 1)
+	go func() {
+		cliCh := make(chan dnsCheckResult, 1)
+		speakerCh := make(chan dnsCheckResult, 1)
+
+		go func() { cliCh <- cliDNSCheck(dnsHost) }()
+		go func() { speakerCh <- speakerDNSCheck(deviceIP, dnsHost, newSSH) }()
+
+		ch <- result{cli: <-cliCh, speaker: <-speakerCh}
+	}()
+
+	r := <-ch
+
+	if r.cli.ok && r.speaker.ok {
+		fmt.Printf("DNS preflight (%s:53)   ✓ works\n", dnsHost)
+		return nil
+	}
+
+	fmt.Printf("DNS preflight (%s:53)\n", dnsHost)
+	fmt.Printf("  CLI host  %s\n", r.cli.label())
+	fmt.Printf("  Speaker   %s\n", r.speaker.label())
+	fmt.Println()
+
+	if !r.speaker.ok && !r.speaker.unknown {
+		return fmt.Errorf("AfterTouch DNS unreachable from speaker — %s migration would fail", serviceURL)
+	}
+
+	if r.speaker.unknown && !r.cli.ok {
+		return fmt.Errorf("cannot confirm DNS reachability (SSH unavailable from speaker, CLI probe also failed) — use --skip-preflight to bypass")
 	}
 
 	return nil
@@ -822,6 +976,11 @@ func setupVerifyCmd() *cli.Command {
 			cfg := GetClientConfig(c)
 			serviceURL := c.String("service-url")
 
+			if err := validateServiceURL(serviceURL); err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
 			m := setup.NewManager(serviceURL, nil, nil)
 
 			summary, err := m.GetMigrationSummary(cfg.Host, serviceURL, c.String("proxy-url"), nil)
@@ -921,21 +1080,6 @@ func renderMigrationSummary(deviceIP, serviceURL string, s *setup.MigrationSumma
 	fmt.Printf("  %s resolv  (/etc/resolv.conf via DHCP hook)\n", checkmark(s.ResolvMigrated))
 	fmt.Println()
 
-	if s.MirrorEnabled || len(s.MirrorEndpoints) > 0 {
-		fmt.Println("Mirroring")
-		fmt.Printf("  %s enabled\n", checkmark(s.MirrorEnabled))
-
-		if len(s.MirrorEndpoints) > 0 {
-			fmt.Printf("        endpoints: %s\n", strings.Join(s.MirrorEndpoints, ", "))
-		}
-
-		if len(s.SkipMirrorEndpoints) > 0 {
-			fmt.Printf("        skip:      %s\n", strings.Join(s.SkipMirrorEndpoints, ", "))
-		}
-
-		fmt.Println()
-	}
-
 	if len(s.Warnings) > 0 {
 		fmt.Println("Warnings")
 
@@ -949,6 +1093,17 @@ func renderMigrationSummary(deviceIP, serviceURL string, s *setup.MigrationSumma
 	if s.ResolveIPError != "" {
 		PrintError("Resolve IP error: " + s.ResolveIPError)
 	}
+
+	// Observability for the IP-resolve path. Source tells the user whether
+	// the speaker itself was consulted (authoritative) or only the service
+	// (best-effort). DurationMS lets us watch the SSH-ping cost trend in
+	// the wild — historical comment claimed 2-5 s on firmware 27, worth
+	// re-evaluating as data accumulates.
+	if s.ResolveIPSource != "" {
+		fmt.Printf("Resolve IP source : %s (%d ms)\n", s.ResolveIPSource, s.ResolveIPDurationMS)
+	} else if s.ResolveIPDurationMS > 0 {
+		fmt.Printf("Resolve IP        : %d ms\n", s.ResolveIPDurationMS)
+	}
 }
 
 func setupRebootCmd() *cli.Command {
@@ -1017,6 +1172,11 @@ func setupPlanCmd() *cli.Command {
 			wifiSSID := c.String("wifi-ssid")
 			includePair := c.Bool("include-pair")
 
+			if err := validateServiceURL(serviceURL); err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
 			m := setup.NewManager(serviceURL, nil, nil)
 
 			fmt.Printf("Probing %s …\n\n", cfg.Host)
@@ -1040,7 +1200,7 @@ func setupPlanCmd() *cli.Command {
 				renderPreResetNote()
 			}
 
-			renderPlanSteps(steps)
+			renderPlanSteps(steps, includePair)
 
 			return nil
 		},
@@ -1097,6 +1257,10 @@ func renderPlanState(deviceIP string, inspect *setup.InspectReport, summary *set
 		check(summary.IsPaired), check(summary.IsMigrated),
 		yesNo(summary.TelnetMigrated), yesNo(summary.XMLMigrated),
 		yesNo(summary.HostsMigrated), yesNo(summary.ResolvMigrated))
+
+	if summary.RemoteServicesEnabled && !summary.RemoteServicesPersistent {
+		fmt.Println("  [⚠] remote_services   enabled but not persistent (will be lost on reboot)")
+	}
 }
 
 func firmwareOf(info *setup.DeviceInfoXML) string {
@@ -1139,7 +1303,19 @@ func buildPlanSteps(
 		host = "<NEW_IP>" // subsequent commands target the discovered IP
 	}
 
-	if !reset && summary != nil && summary.IsMigrated && (!includePair || summary.IsPaired) {
+	// Persist remote_services before anything else when it's only in /tmp.
+	// SSH is reachable now, but the marker would be lost on the next reboot —
+	// which could happen mid-migration if power is cut or the reboot step runs
+	// before persistence is confirmed.
+	if !reset && summary != nil && summary.RemoteServicesEnabled && !summary.RemoteServicesPersistent {
+		steps = append(steps, planStep{
+			title:  "Persist remote_services so SSH survives a reboot",
+			cmd:    fmt.Sprintf("soundtouch-cli --host=%s setup remote-services", host),
+			reason: "Marker is currently in /tmp only — lost on next reboot, which would break SSH mid-migration.",
+		})
+	}
+
+	if !reset && summary != nil && summary.IsMigrated && (!includePair || summary.IsPaired) && len(steps) == 0 {
 		return steps
 	}
 
@@ -1150,7 +1326,7 @@ func buildPlanSteps(
 	if includePair && (reset || (summary != nil && !summary.IsPaired)) {
 		steps = append(steps, planStep{
 			title:  "Pair the device with an AfterTouch account",
-			cmd:    fmt.Sprintf("soundtouch-cli setup pair --host=%s --service-url=%s", host, serviceURL),
+			cmd:    fmt.Sprintf("soundtouch-cli --host=%s setup pair --service-url=%s", host, serviceURL),
 			reason: "Required for preset persistence, streaming services, multi-room zones.",
 		})
 	}
@@ -1182,7 +1358,7 @@ func resetSteps(host, wifiSSID string, inspect *setup.InspectReport) []planStep
 	return []planStep{
 		{
 			title:  "Factory-reset the speaker",
-			cmd:    fmt.Sprintf("soundtouch-cli setup factory-reset --host=%s", host),
+			cmd:    fmt.Sprintf("soundtouch-cli --host=%s setup factory-reset", host),
 			reason: "Wipes account pairing, presets, Wi-Fi — gives a clean baseline for the SETUP state machine.",
 		},
 		{
@@ -1240,20 +1416,20 @@ func migrationSteps(host, serviceURL string, summary *setup.MigrationSummary, re
 	if dnsRedirect && summary != nil && !summary.CACertTrusted {
 		steps = append(steps, planStep{
 			title:  "Install AfterTouch's CA cert on the speaker",
-			cmd:    fmt.Sprintf("soundtouch-cli setup install-ca --host=%s --service-url=%s", host, serviceURL),
+			cmd:    fmt.Sprintf("soundtouch-cli --host=%s setup install-ca --service-url=%s", host, serviceURL),
 			reason: "DNS-redirect methods keep using https://*.bose.com URLs — the device needs to trust AfterTouch's cert.",
 		})
 	}
 
 	steps = append(steps, planStep{
 		title:  fmt.Sprintf("Apply URL migration using method=%s", method),
-		cmd:    fmt.Sprintf("soundtouch-cli setup migrate --host=%s --service-url=%s --method=%s", host, serviceURL, method),
+		cmd:    fmt.Sprintf("soundtouch-cli --host=%s setup migrate --service-url=%s --method=%s", host, serviceURL, method),
 		reason: methodReason,
 	})
 
 	steps = append(steps, planStep{
 		title:  "Reboot the speaker",
-		cmd:    fmt.Sprintf("soundtouch-cli setup reboot --host=%s", host),
+		cmd:    fmt.Sprintf("soundtouch-cli --host=%s setup reboot", host),
 		reason: "The envswitch parallel-persistence layer only fully wins on next boot; reboot now to lock the new URLs in before pairing.",
 	})
 
@@ -1318,9 +1494,14 @@ func renderPreResetNote() {
 	fmt.Println()
 }
 
-func renderPlanSteps(steps []planStep) {
+func renderPlanSteps(steps []planStep, includePair bool) {
 	if len(steps) == 0 {
-		PrintSuccess("Speaker is already migrated and paired. No action required.")
+		if includePair {
+			PrintSuccess("Speaker is already migrated and paired. No action required.")
+		} else {
+			PrintSuccess("Speaker is already migrated. No action required.")
+		}
+
 		return
 	}
 
@@ -1353,10 +1534,11 @@ func setupPairCmd() *cli.Command {
 		Flags: []cli.Flag{
 			&cli.StringFlag{Name: "account", Usage: "7-digit account ID (empty = generate)"},
 			&cli.StringFlag{Name: "mode", Value: "full", Usage: "full (state machine) or bare (setMargeAccount only — experimental)"},
-			&cli.StringFlag{Name: "service-url", Value: "http://aftertouch.local:8000", Usage: "AfterTouch base URL (used by mode=full for defaults)"},
+			&cli.StringFlag{Name: "service-url", Value: "http://aftertouch.local:8000", Usage: "AfterTouch base URL (also populates <boseServer>/<updateServer> in setMargeAccount)"},
 			&cli.StringFlag{Name: "name", Usage: "Speaker name to set during pairing (empty = keep current)"},
 			&cli.IntFlag{Name: "language", Value: setup.LanguageEnglish, Usage: "sysLanguage code (2 = English)"},
 			&cli.DurationFlag{Name: "step-timeout", Value: 8 * time.Second},
+			&cli.StringFlag{Name: "token", Usage: "userAuthToken value (empty = use built-in placeholder matching the Bose app token shape)"},
 		},
 		Action: func(c *cli.Context) error {
 			cfg := GetClientConfig(c)
@@ -1401,8 +1583,20 @@ func runPairBare(c *cli.Context, deviceIP, accountID string) error {
 	fmt.Printf("pre  /info deviceID=%s margeAccountUUID=%q margeURL=%q\n",
 		info.DeviceID, info.MargeAccountUUID, info.MargeURL)
 
+	// Service URL drives the extended <PairDeviceWithAccount> payload
+	// (boseServer/updateServer/accountEmail). When empty, the session
+	// falls back to the minimal historical shape (accountId +
+	// userAuthToken only).
+	serviceURL := c.String("service-url")
+
+	var extras setup.MargePairingExtras
+	if serviceURL != "" {
+		extras = setup.MargePairingExtras{BoseServer: serviceURL}
+	}
+
 	session, err := setup.DialSession(deviceIP, info.DeviceID, setup.SessionConfig{
-		StepTimeout: c.Duration("step-timeout"),
+		StepTimeout:   c.Duration("step-timeout"),
+		PairingExtras: extras,
 	})
 	if err != nil {
 		return fmt.Errorf("dial WS: %w", err)
@@ -1413,9 +1607,13 @@ func runPairBare(c *cli.Context, deviceIP, accountID string) error {
 	ctx, cancel := context.WithTimeout(c.Context, c.Duration("step-timeout")+2*time.Second)
 	defer cancel()
 
-	fmt.Printf("→ setMargeAccount accountID=%s (no SETUP bracket)\n", accountID)
+	if serviceURL != "" {
+		fmt.Printf("→ setMargeAccount accountID=%s (extended: boseServer=%s)\n", accountID, serviceURL)
+	} else {
+		fmt.Printf("→ setMargeAccount accountID=%s (minimal payload, no SETUP bracket)\n", accountID)
+	}
 
-	if pairErr := session.SetMargeAccount(ctx, accountID, ""); pairErr != nil {
+	if pairErr := session.SetMargeAccount(ctx, accountID, c.String("token")); pairErr != nil {
 		PrintError(fmt.Sprintf("setMargeAccount: %v", pairErr))
 		return pairErr
 	}

cmd/soundtouch-cli/cmd_setup_test.go

@@ -169,7 +169,7 @@ 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)
+	steps := buildPlanSteps("192.0.2.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)
@@ -180,7 +180,7 @@ 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)
+	steps := buildPlanSteps("192.0.2.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)
@@ -195,7 +195,7 @@ 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)
+	steps := buildPlanSteps("192.0.2.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
@@ -228,7 +228,7 @@ func TestBuildPlanSteps_DNSMethodPrependsCAInstall(t *testing.T) {
 	}
 	inspect := &setup.InspectReport{Info: &setup.DeviceInfoXML{DeviceID: "X"}}
 
-	steps := buildPlanSteps("192.168.1.42", "http://aftertouch.local:8000", "", false, false, inspect, summary)
+	steps := buildPlanSteps("192.0.2.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)
@@ -256,7 +256,7 @@ func TestBuildPlanSteps_ResetModeIncludesManualNetworkSwitches(t *testing.T) {
 	}
 	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)
+	steps := buildPlanSteps("192.0.2.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,

cmd/soundtouch-cli/cmd_source.go

@@ -3,6 +3,8 @@ package main
 import (
 	"encoding/base64"
 	"fmt"
+	"io"
+	"net/http"
 	"net/url"
 	"strings"
 
@@ -685,3 +687,51 @@ func boolToStatus(b bool) string {
 
 	return "❌ No"
 }
+
+// notifySourcesUpdated POSTs a sourcesUpdated notification directly to the
+// speaker's :8090/notification endpoint. The speaker re-fetches its source
+// list from AfterTouch immediately. Requires network access to the speaker.
+func notifySourcesUpdated(c *cli.Context) error {
+	if err := RequireHost(c); err != nil {
+		return err
+	}
+
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	info, err := client.GetDeviceInfo()
+	if err != nil {
+		return fmt.Errorf("failed to get device info from %s: %w", clientConfig.Host, err)
+	}
+
+	body := fmt.Sprintf(`<updates deviceID="%s"><sourcesUpdated/></updates>`, info.DeviceID)
+	notifyURL := fmt.Sprintf("http://%s:8090/notification", clientConfig.Host)
+
+	req, err := http.NewRequest(http.MethodPost, notifyURL, strings.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("build request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/xml")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("post to speaker: %w", err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode >= 300 {
+		respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<10))
+
+		return fmt.Errorf("speaker returned %d: %s", resp.StatusCode, strings.TrimSpace(string(respBody)))
+	}
+
+	PrintSuccess(fmt.Sprintf("Sent sourcesUpdated to %s (%s)", info.DeviceID, clientConfig.Host))
+
+	return nil
+}

cmd/soundtouch-cli/cmd_station.go

@@ -2,14 +2,23 @@ package main
 
 import (
 	"fmt"
+	"net/url"
+	"path"
 	"strings"
 
 	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/stations"
 	"github.com/urfave/cli/v2"
 )
 
 // searchStations handles searching for stations across different sources
 func searchStations(c *cli.Context) error {
+	PrintDeprecation(
+		"station search",
+		"It asks the speaker to search, which fails when the speaker's cloud is gone.",
+		`soundtouch-cli station find --provider tunein --query "<your search>"`,
+	)
+
 	source := c.String("source")
 	sourceAccount := c.String("source-account")
 	searchTerm := c.String("query")
@@ -49,6 +58,12 @@ func searchStations(c *cli.Context) error {
 
 // searchTuneIn handles searching TuneIn specifically
 func searchTuneIn(c *cli.Context) error {
+	PrintDeprecation(
+		"station search-tunein",
+		"It asks the speaker to search, which fails when the speaker's cloud is gone.",
+		`soundtouch-cli station find-tunein --query "<your search>"`,
+	)
+
 	searchTerm := c.String("query")
 
 	if searchTerm == "" {
@@ -84,6 +99,12 @@ func searchTuneIn(c *cli.Context) error {
 
 // searchPandora handles searching Pandora specifically
 func searchPandora(c *cli.Context) error {
+	PrintDeprecation(
+		"station search-pandora",
+		"There is no built-in Pandora search yet (it requires the speaker and your account).",
+		"",
+	)
+
 	sourceAccount := c.String("source-account")
 	searchTerm := c.String("query")
 
@@ -125,6 +146,12 @@ func searchPandora(c *cli.Context) error {
 
 // searchSpotify handles searching Spotify specifically
 func searchSpotify(c *cli.Context) error {
+	PrintDeprecation(
+		"station search-spotify",
+		"There is no built-in Spotify search yet (it requires the speaker and your account).",
+		"",
+	)
+
 	sourceAccount := c.String("source-account")
 	searchTerm := c.String("query")
 
@@ -473,3 +500,182 @@ func printStationList(response *models.NavigateResponse, source string) {
 	fmt.Printf("   • To play a station: Use the location value with 'play content' command\n")
 	fmt.Printf("   • To save as preset: Use 'preset set' command with the location\n")
 }
+
+// playbackID returns the bare station/episode id from a playback href,
+// e.g. "/v1/playback/station/s228737" -> "s228737" and
+// "/v1/playback/episodes/p1864248?encoded_name=…" -> "p1864248".
+// Returns "" when href is empty.
+func playbackID(href string) string {
+	if href == "" {
+		return ""
+	}
+
+	if i := strings.IndexByte(href, '?'); i >= 0 {
+		href = href[:i]
+	}
+
+	return path.Base(href)
+}
+
+// printBmxNavResults renders a *models.BmxNavResponse to stdout.
+// For each section it prints the section name as a header, then each item as a
+// leading id column followed by the name, with subtitle and playback location
+// indented below. The bare id sits alone in its own column so it is easy to
+// copy-paste.
+func printBmxNavResults(resp *models.BmxNavResponse) {
+	if len(resp.BmxSections) == 0 {
+		fmt.Println("  No results found")
+		return
+	}
+
+	for _, section := range resp.BmxSections {
+		if section.Name != "" {
+			fmt.Printf("\n  [%s]\n", section.Name)
+		}
+
+		if len(section.Items) == 0 {
+			fmt.Println("    (empty)")
+			continue
+		}
+
+		// Width of the leading id column = widest id in this section.
+		maxID := 0
+
+		for _, item := range section.Items {
+			if item.Links != nil && item.Links.BmxPlayback != nil {
+				maxID = max(maxID, len(playbackID(item.Links.BmxPlayback.Href)))
+			}
+		}
+
+		// Continuation lines align under the name: 4 leading spaces
+		// + id column + 2-space gap.
+		indent := strings.Repeat(" ", 4+maxID+2)
+
+		for _, item := range section.Items {
+			id := ""
+			if item.Links != nil && item.Links.BmxPlayback != nil {
+				id = playbackID(item.Links.BmxPlayback.Href)
+			}
+
+			fmt.Printf("    %-*s  %s\n", maxID, id, item.Name)
+
+			if item.Subtitle != "" {
+				fmt.Printf("%s%s\n", indent, item.Subtitle)
+			}
+
+			if item.Links != nil && item.Links.BmxPlayback != nil {
+				fmt.Printf("%sLocation: %s\n", indent, item.Links.BmxPlayback.Href)
+			}
+		}
+	}
+}
+
+// bmxNavCursor extracts the opaque cursor value from a section's BmxNext link.
+// The Href looks like "...?cursor=<value>"; this returns the cursor query param.
+// Returns "" when no next link is present.
+func bmxNavCursor(section *models.BmxNavSection) string {
+	if section == nil || section.Links == nil || section.Links.BmxNext == nil {
+		return ""
+	}
+
+	href := section.Links.BmxNext.Href
+	if href == "" {
+		return ""
+	}
+
+	// The cursor is the query parameter named "cursor".
+	parsed, err := url.Parse(href)
+	if err != nil {
+		return ""
+	}
+
+	return parsed.Query().Get("cursor")
+}
+
+// runFind performs a built-in station search for the given provider and
+// prints the results. The search runs inside the CLI itself, querying the
+// radio provider's public API directly — it needs neither the speaker's
+// cloud nor a running soundtouch-service. When more is true it follows up
+// to three additional result pages while a next cursor is available.
+func runFind(provider stations.Provider, label, query string, more bool) error {
+	if query == "" {
+		PrintError("Search query is required")
+		return fmt.Errorf("search query cannot be empty")
+	}
+
+	fmt.Printf("Searching %s for: %s\n", label, query)
+
+	resp, err := stations.Search(provider, query)
+	if err != nil {
+		PrintError(fmt.Sprintf("Search failed: %v", err))
+		return err
+	}
+
+	printBmxNavResults(resp)
+
+	if !more {
+		return nil
+	}
+
+	const maxExtraPages = 3
+	for page := 0; page < maxExtraPages; page++ {
+		// Find a cursor from any section that has one.
+		cursor := ""
+		for i := range resp.BmxSections {
+			cursor = bmxNavCursor(&resp.BmxSections[i])
+			if cursor != "" {
+				break
+			}
+		}
+
+		if cursor == "" {
+			break
+		}
+
+		fmt.Printf("\n  -- page %d --\n", page+2)
+
+		resp, err = stations.SearchNext(provider, cursor)
+		if err != nil {
+			PrintError(fmt.Sprintf("Failed to fetch next page: %v", err))
+			return err
+		}
+
+		printBmxNavResults(resp)
+	}
+
+	return nil
+}
+
+// findStations is the action for the unified `station find` with
+// --provider / --query / --more.
+func findStations(c *cli.Context) error {
+	providerStr := c.String("provider")
+
+	var (
+		provider stations.Provider
+		label    string
+	)
+
+	switch strings.ToLower(providerStr) {
+	case "tunein":
+		provider, label = stations.ProviderTuneIn, "TuneIn"
+	case "radiobrowser":
+		provider, label = stations.ProviderRadioBrowser, "Radio Browser"
+	default:
+		PrintError(fmt.Sprintf("Unknown provider %q: must be 'tunein' or 'radiobrowser'", providerStr))
+		return fmt.Errorf("unknown provider: %s", providerStr)
+	}
+
+	return runFind(provider, label, c.String("query"), c.Bool("more"))
+}
+
+// findTuneIn is the action for `station find-tunein` (built-in TuneIn search).
+func findTuneIn(c *cli.Context) error {
+	return runFind(stations.ProviderTuneIn, "TuneIn", c.String("query"), c.Bool("more"))
+}
+
+// findRadioBrowser is the action for `station find-radiobrowser`
+// (built-in Radio Browser search).
+func findRadioBrowser(c *cli.Context) error {
+	return runFind(stations.ProviderRadioBrowser, "Radio Browser", c.String("query"), c.Bool("more"))
+}

cmd/soundtouch-cli/cmd_tts.go

@@ -0,0 +1,127 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/urfave/cli/v2"
+)
+
+// ttsCloudCmd is the `speaker tts-cloud` subcommand. Unlike `speaker tts`
+// (which sends a Google Translate URL straight to the speaker), this routes
+// through the AfterTouch service, which synthesizes the audio with the
+// configured provider (e.g. Google Cloud TTS), hosts it, and plays it on the
+// speaker. It therefore needs --service-url. Target the speaker with the global
+// --host, or with --device (resolved to an IP by the service).
+func ttsCloudCmd() *cli.Command {
+	return &cli.Command{
+		Name:  "tts-cloud",
+		Usage: "Speak text via the AfterTouch service (Google Cloud TTS), synthesized server-side",
+		Description: "Routes through the AfterTouch service (requires --service-url), which\n" +
+			"synthesizes the audio with the configured provider, hosts it, and plays it\n" +
+			"on the speaker. Target the speaker with the global --host or with --device.\n\n" +
+			"Contrast with 'speaker tts', which sends a Google Translate URL directly to\n" +
+			"the speaker without involving the service.",
+		Flags: append(CloudCommonFlags,
+			&cli.StringFlag{
+				Name:     "text",
+				Aliases:  []string{"t"},
+				Usage:    "Text to speak",
+				Required: true,
+			},
+			&cli.StringFlag{
+				Name:    "device",
+				Aliases: []string{"d"},
+				Usage:   "Target device ID (the service resolves it to an IP); alternative to --host",
+			},
+			&cli.StringFlag{
+				Name:    "language",
+				Aliases: []string{"l"},
+				Usage:   "Language code (provider-specific; defaults to the service setting)",
+			},
+			&cli.StringFlag{
+				Name:  "voice",
+				Usage: "Voice name (Google Cloud TTS; ignored by the translate provider)",
+			},
+			&cli.IntFlag{
+				Name:    "volume",
+				Aliases: []string{"v"},
+				Usage:   "Playback volume (0-100, 0 = service default; only honoured by --method speaker)",
+			},
+			&cli.StringFlag{
+				Name:  "method",
+				Usage: "Playback method: 'speaker' (/speaker notification, ducks+resumes, supports volume) or 'radio' (LOCAL_INTERNET_RADIO, no app_key, replaces source)",
+				Value: "speaker",
+			},
+		),
+		Action: ttsCloud,
+	}
+}
+
+func ttsCloud(c *cli.Context) error {
+	serviceURL := strings.TrimRight(c.String("service-url"), "/")
+	device := c.String("device")
+	host := c.String("host") // global flag
+
+	if device == "" && host == "" {
+		return fmt.Errorf("one of --host or --device is required")
+	}
+
+	payload := map[string]interface{}{"text": c.String("text")}
+	if device != "" {
+		payload["deviceId"] = device
+	}
+
+	if host != "" {
+		payload["host"] = host
+	}
+
+	if l := c.String("language"); l != "" {
+		payload["language"] = l
+	}
+
+	if v := c.String("voice"); v != "" {
+		payload["voice"] = v
+	}
+
+	if c.IsSet("volume") {
+		payload["volume"] = c.Int("volume")
+	}
+
+	if m := c.String("method"); m != "" {
+		payload["method"] = m
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+
+	req, err := http.NewRequest(http.MethodPost, serviceURL+"/api/setup/tts/speak", bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("build request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("request failed: %w", err)
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	respBody, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<12))
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("service returned %d: %s", resp.StatusCode, strings.TrimSpace(string(respBody)))
+	}
+
+	PrintSuccess(fmt.Sprintf("Spoke %q", c.String("text")))
+
+	return nil
+}

cmd/soundtouch-cli/cmd_tunein.go

@@ -0,0 +1,152 @@
+// Package main — `soundtouch-cli source tunein` subcommand.
+//
+// Convenience shortcut for the verbose `source content --source TUNEIN
+// --type … --location …` pattern. Picks the right Type + location template
+// from the TuneIn guide-ID prefix, optionally fetches name + artwork from
+// TuneIn's describe endpoint, then calls the same SelectContentItem path
+// the generic `source content` command uses.
+//
+// Implements #226.
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/bmx"
+	"github.com/urfave/cli/v2"
+)
+
+// tuneInKind captures the three guide-ID shapes the SoundTouch firmware
+// distinguishes; each picks a different Bose `/v1/playback/...` location
+// template and a different ContentItem Type.
+type tuneInKind struct {
+	flag      string // CLI flag name (`station`, `episode`, `program`)
+	prefix    string // single-letter guide-ID prefix (`s`, `e`, `p`)
+	location  string // printf template, %s = guide ID
+	itemType  string // ContentItem.Type the speaker expects
+	humanName string // user-facing kind label for log lines
+}
+
+var tuneInKinds = []tuneInKind{
+	{flag: "station", prefix: "s", location: "/v1/playback/station/%s", itemType: "stationurl", humanName: "live station"},
+	{flag: "episode", prefix: "e", location: "/v1/playback/episode/%s", itemType: "stationurl", humanName: "podcast episode"},
+	{flag: "program", prefix: "p", location: "/v1/playback/episodes/%s", itemType: "tracklisturl", humanName: "podcast program"},
+}
+
+// resolveTuneInKind picks a kind from the CLI flags. Exactly one of
+// --station / --episode / --program must be set, OR --id with a prefix we
+// recognise. Returns the kind plus the bare guide ID.
+func resolveTuneInKind(c *cli.Context) (*tuneInKind, string, error) {
+	// Explicit kind flags take precedence over --id.
+	var picked *tuneInKind
+
+	var id string
+
+	for i, k := range tuneInKinds {
+		v := c.String(k.flag)
+		if v == "" {
+			continue
+		}
+
+		if picked != nil {
+			return nil, "", fmt.Errorf("only one of --station, --episode, --program may be set")
+		}
+
+		picked = &tuneInKinds[i]
+		id = v
+	}
+
+	if picked != nil {
+		return picked, strings.TrimSpace(id), nil
+	}
+
+	// Fall back to --id with prefix auto-detect.
+	raw := strings.TrimSpace(c.String("id"))
+	if raw == "" {
+		return nil, "", fmt.Errorf("one of --station, --episode, --program, or --id is required")
+	}
+
+	if raw == "" {
+		return nil, "", fmt.Errorf("--id is empty")
+	}
+
+	for i, k := range tuneInKinds {
+		if strings.HasPrefix(raw, k.prefix) {
+			return &tuneInKinds[i], raw, nil
+		}
+	}
+
+	return nil, "", fmt.Errorf("--id %q has no recognised TuneIn prefix; use --station/--episode/--program explicitly", raw)
+}
+
+// playTuneIn is the action wired into `soundtouch-cli source tunein`.
+func playTuneIn(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		return err
+	}
+
+	kind, id, err := resolveTuneInKind(c)
+	if err != nil {
+		return err
+	}
+
+	name := c.String("name")
+	artwork := c.String("artwork")
+
+	// Optional metadata enrichment — only fetch if the user hasn't already
+	// supplied both, and they haven't asked us to skip it.
+	if !c.Bool("no-lookup") && (name == "" || artwork == "") {
+		fetchedName, fetchedLogo, lookupErr := bmx.TuneInDescribeMeta(id)
+		if lookupErr != nil {
+			// Non-fatal: the speaker can resolve the title itself; just
+			// note the failure so an operator sees what went wrong.
+			fmt.Printf("  Note: TuneIn describe lookup failed (%v); proceeding without enrichment.\n", lookupErr)
+		} else {
+			if name == "" {
+				name = fetchedName
+			}
+
+			if artwork == "" {
+				artwork = fetchedLogo
+			}
+		}
+	}
+
+	if name == "" {
+		// Fall back to a sensible non-empty default so the speaker's
+		// now-playing UI doesn't show a blank source label.
+		name = "TuneIn"
+	}
+
+	contentItem := &models.ContentItem{
+		Source:       "TUNEIN",
+		Type:         kind.itemType,
+		Location:     fmt.Sprintf(kind.location, id),
+		ItemName:     name,
+		ContainerArt: artwork,
+		IsPresetable: true,
+	}
+
+	PrintDeviceHeader("Playing TuneIn "+kind.humanName, clientConfig.Host, clientConfig.Port)
+	fmt.Printf("  ID:       %s\n", id)
+	fmt.Printf("  Location: %s\n", contentItem.Location)
+	fmt.Printf("  Type:     %s\n", contentItem.Type)
+	fmt.Printf("  Name:     %s\n", contentItem.ItemName)
+
+	if contentItem.ContainerArt != "" {
+		fmt.Printf("  Artwork:  %s\n", contentItem.ContainerArt)
+	}
+
+	if err := client.SelectContentItem(contentItem); err != nil {
+		return fmt.Errorf("failed to select TuneIn content: %w", err)
+	}
+
+	PrintSuccess("TuneIn content selected")
+
+	return nil
+}

cmd/soundtouch-cli/cmd_tunein_test.go

@@ -0,0 +1,157 @@
+package main
+
+import (
+	"flag"
+	"strings"
+	"testing"
+
+	"github.com/urfave/cli/v2"
+)
+
+// newCtx wires a *cli.Context with the kind-selection flags the resolver
+// reads, plus whatever values the test wants set. Empty-string values are
+// the default (flag not provided).
+func newCtx(t *testing.T, kv map[string]string) *cli.Context {
+	t.Helper()
+
+	fs := flag.NewFlagSet("test", flag.ContinueOnError)
+	for _, name := range []string{"station", "episode", "program", "id"} {
+		fs.String(name, "", "")
+	}
+
+	for k, v := range kv {
+		if err := fs.Set(k, v); err != nil {
+			t.Fatalf("fs.Set(%q, %q): %v", k, v, err)
+		}
+	}
+
+	return cli.NewContext(nil, fs, nil)
+}
+
+func TestResolveTuneInKind_Station(t *testing.T) {
+	c := newCtx(t, map[string]string{"station": "s14991"})
+
+	k, id, err := resolveTuneInKind(c)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if k.flag != "station" || k.itemType != "stationurl" {
+		t.Errorf("wrong kind: %+v", k)
+	}
+
+	if id != "s14991" {
+		t.Errorf("wrong id: %q", id)
+	}
+}
+
+func TestResolveTuneInKind_Episode(t *testing.T) {
+	c := newCtx(t, map[string]string{"episode": "e789012"})
+
+	k, id, err := resolveTuneInKind(c)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if k.flag != "episode" || k.itemType != "stationurl" {
+		t.Errorf("wrong kind: %+v", k)
+	}
+
+	if id != "e789012" {
+		t.Errorf("wrong id: %q", id)
+	}
+
+	if !strings.Contains(k.location, "/v1/playback/episode/") {
+		t.Errorf("wrong location template: %q", k.location)
+	}
+}
+
+func TestResolveTuneInKind_Program(t *testing.T) {
+	c := newCtx(t, map[string]string{"program": "p123456"})
+
+	k, id, err := resolveTuneInKind(c)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if k.flag != "program" || k.itemType != "tracklisturl" {
+		t.Errorf("wrong kind: %+v", k)
+	}
+
+	if id != "p123456" {
+		t.Errorf("wrong id: %q", id)
+	}
+
+	if !strings.Contains(k.location, "/v1/playback/episodes/") {
+		t.Errorf("wrong location template: %q", k.location)
+	}
+}
+
+func TestResolveTuneInKind_IDPrefixAutoDetect(t *testing.T) {
+	cases := []struct {
+		id       string
+		wantFlag string
+	}{
+		{"s14991", "station"},
+		{"e789012", "episode"},
+		{"p123456", "program"},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.id, func(t *testing.T) {
+			c := newCtx(t, map[string]string{"id": tc.id})
+
+			k, id, err := resolveTuneInKind(c)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			if k.flag != tc.wantFlag {
+				t.Errorf("auto-detect picked %q; want %q", k.flag, tc.wantFlag)
+			}
+
+			if id != tc.id {
+				t.Errorf("id round-tripped wrong: got %q want %q", id, tc.id)
+			}
+		})
+	}
+}
+
+func TestResolveTuneInKind_NoFlags(t *testing.T) {
+	c := newCtx(t, nil)
+
+	_, _, err := resolveTuneInKind(c)
+	if err == nil {
+		t.Fatal("expected error when no flags are set")
+	}
+
+	if !strings.Contains(err.Error(), "required") {
+		t.Errorf("error message should mention required flag: %v", err)
+	}
+}
+
+func TestResolveTuneInKind_ConflictingFlags(t *testing.T) {
+	c := newCtx(t, map[string]string{"station": "s14991", "episode": "e789012"})
+
+	_, _, err := resolveTuneInKind(c)
+	if err == nil {
+		t.Fatal("expected error when conflicting flags are set")
+	}
+
+	if !strings.Contains(err.Error(), "only one of") {
+		t.Errorf("error message should mention exclusivity: %v", err)
+	}
+}
+
+func TestResolveTuneInKind_UnknownPrefix(t *testing.T) {
+	c := newCtx(t, map[string]string{"id": "x999"})
+
+	_, _, err := resolveTuneInKind(c)
+	if err == nil {
+		t.Fatal("expected error for unknown ID prefix")
+	}
+
+	if !strings.Contains(err.Error(), "no recognised TuneIn prefix") {
+		t.Errorf("error message should explain prefix mismatch: %v", err)
+	}
+}

cmd/soundtouch-cli/common.go

@@ -19,6 +19,16 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
+// CloudCommonFlags defines flags for commands that talk to the AfterTouch service.
+var CloudCommonFlags = []cli.Flag{
+	&cli.StringFlag{
+		Name:     "service-url",
+		Usage:    "AfterTouch service URL",
+		Required: true,
+		EnvVars:  []string{"AFTERTOUCH_URL"},
+	},
+}
+
 // CommonFlags defines flags that are shared across multiple commands
 var CommonFlags = []cli.Flag{
 	&cli.StringFlag{
@@ -322,7 +332,7 @@ func PrintSuccess(message string) {
 
 // PrintError prints a standard error message
 func PrintError(message string) {
-	fmt.Printf("✗ %s\n", message)
+	fmt.Printf("✗ %s\n", sanitizeLog(message))
 }
 
 // PrintWarning prints a standard warning message
@@ -330,6 +340,22 @@ func PrintWarning(message string) {
 	fmt.Printf("⚠️  %s\n", message)
 }
 
+// PrintDeprecation prints a deprecation notice to stderr (so it does not
+// pollute piped stdout output). reason explains why the command is going
+// away; newUsage is an optional replacement example — pass "" when there
+// is no replacement yet.
+func PrintDeprecation(command, reason, newUsage string) {
+	fmt.Fprintf(os.Stderr, "⚠️  '%s' is deprecated and will be removed in a future release.\n", command)
+
+	if reason != "" {
+		fmt.Fprintf(os.Stderr, "    %s\n", reason)
+	}
+
+	if newUsage != "" {
+		fmt.Fprintf(os.Stderr, "    Use instead:\n      %s\n", newUsage)
+	}
+}
+
 // showVersionInfo displays detailed version information including build details
 func showVersionInfo(_ *cli.Context) error {
 	fmt.Printf("%s version %s\n", os.Args[0], version)

cmd/soundtouch-cli/logutil.go

@@ -0,0 +1,13 @@
+package main
+
+import "strings"
+
+// sanitizeLog strips newline characters from s to prevent log-injection
+// (CodeQL go/log-injection). Values from speakers, HTTP requests, and
+// external APIs may contain attacker-controlled newlines.
+func sanitizeLog(s string) string {
+	s = strings.ReplaceAll(s, "\n", `\n`)
+	s = strings.ReplaceAll(s, "\r", `\r`)
+
+	return s
+}

cmd/soundtouch-cli/main.go

@@ -132,6 +132,11 @@ func main() {
 								Aliases: []string{"a"},
 								Usage:   "Show detailed information for all devices",
 							},
+							&cli.BoolFlag{
+								Name:    "verbose",
+								Aliases: []string{"v"},
+								Usage:   "Print per-packet/per-header SSDP and mDNS trace logs",
+							},
 						},
 					},
 				},
@@ -380,6 +385,11 @@ func main() {
 								Name:  "artwork",
 								Usage: "Artwork URL",
 							},
+							&cli.StringFlag{
+								Name:    "service-url",
+								Usage:   "AfterTouch service HTTPS URL (e.g. https://soundtouch.local). Required for LOCAL_INTERNET_RADIO: the speaker's BMX module calls GET on the preset location and expects an Orion JSON response, not raw audio. When provided, the stream URL is automatically wrapped in the Orion station endpoint.",
+								EnvVars: []string{"SOUNDTOUCH_SERVICE_URL"},
+							},
 						},
 						Before: RequireHost,
 					},
@@ -579,9 +589,72 @@ func main() {
 				Aliases: []string{"st"},
 				Usage:   "Search and manage stations",
 				Subcommands: []*cli.Command{
+					// Built-in search ("find" family): runs inside the CLI,
+					// querying the radio provider's public API directly. No
+					// speaker cloud and no soundtouch-service required.
+					{
+						Name:   "find",
+						Usage:  "Find stations directly (built-in tunein or radiobrowser search; no speaker needed)",
+						Action: findStations,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:  "provider",
+								Usage: "Station provider: tunein or radiobrowser",
+								Value: "tunein",
+							},
+							&cli.StringFlag{
+								Name:     "query",
+								Aliases:  []string{"q"},
+								Usage:    "Search query",
+								Required: true,
+							},
+							&cli.BoolFlag{
+								Name:  "more",
+								Usage: "Follow up to 3 additional result pages when available",
+							},
+						},
+					},
+					{
+						Name:   "find-tunein",
+						Usage:  "Find TuneIn stations directly (built-in search; no speaker needed)",
+						Action: findTuneIn,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "query",
+								Aliases:  []string{"q"},
+								Usage:    "Search query",
+								Required: true,
+							},
+							&cli.BoolFlag{
+								Name:  "more",
+								Usage: "Follow up to 3 additional result pages when available",
+							},
+						},
+					},
+					{
+						Name:   "find-radiobrowser",
+						Usage:  "Find Radio Browser stations directly (built-in search; no speaker needed)",
+						Action: findRadioBrowser,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "query",
+								Aliases:  []string{"q"},
+								Usage:    "Search query",
+								Required: true,
+							},
+							&cli.BoolFlag{
+								Name:  "more",
+								Usage: "Follow up to 3 additional result pages when available",
+							},
+						},
+					},
+					// Deprecated speaker-based search commands. They ask the
+					// speaker to search, which fails once its cloud is gone.
+					// Prefer the "find" family above. Kept for now; each emits
+					// a deprecation notice on stderr.
 					{
 						Name:   "search",
-						Usage:  "Search for stations and content",
+						Usage:  "[DEPRECATED] Search via the speaker; use 'station find' instead",
 						Action: searchStations,
 						Flags: []cli.Flag{
 							&cli.StringFlag{
@@ -604,7 +677,7 @@ func main() {
 					},
 					{
 						Name:   "search-tunein",
-						Usage:  "Search TuneIn stations",
+						Usage:  "[DEPRECATED] Search TuneIn via the speaker; use 'station find-tunein' instead",
 						Action: searchTuneIn,
 						Flags: []cli.Flag{
 							&cli.StringFlag{
@@ -618,7 +691,7 @@ func main() {
 					},
 					{
 						Name:   "search-pandora",
-						Usage:  "Search Pandora stations",
+						Usage:  "[DEPRECATED] Search Pandora via the speaker (no built-in equivalent yet)",
 						Action: searchPandora,
 						Flags: []cli.Flag{
 							&cli.StringFlag{
@@ -637,7 +710,7 @@ func main() {
 					},
 					{
 						Name:   "search-spotify",
-						Usage:  "Search Spotify content",
+						Usage:  "[DEPRECATED] Search Spotify via the speaker (no built-in equivalent yet)",
 						Action: searchSpotify,
 						Flags: []cli.Flag{
 							&cli.StringFlag{
@@ -1054,6 +1127,43 @@ func main() {
 							},
 						},
 					},
+					{
+						Name:   "tunein",
+						Usage:  "Play a TuneIn station / episode / program by guide ID (#226)",
+						Action: playTuneIn,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:  "station",
+								Usage: "TuneIn live-station guide ID (e.g. s14991)",
+							},
+							&cli.StringFlag{
+								Name:  "episode",
+								Usage: "TuneIn single-episode guide ID (e.g. e789012)",
+							},
+							&cli.StringFlag{
+								Name:  "program",
+								Usage: "TuneIn podcast/program guide ID (e.g. p123456)",
+							},
+							&cli.StringFlag{
+								Name:  "id",
+								Usage: "TuneIn guide ID; kind auto-detected from s/e/p prefix",
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Override the display name (skips name lookup)",
+							},
+							&cli.StringFlag{
+								Name:  "artwork",
+								Usage: "Override the artwork URL (skips artwork lookup)",
+							},
+							&cli.BoolFlag{
+								Name:  "no-lookup",
+								Usage: "Skip the TuneIn describe lookup; send the bare ContentItem",
+							},
+						},
+					},
 					{
 						Name:   "availability",
 						Usage:  "Show service availability",
@@ -1104,6 +1214,12 @@ func main() {
 						Action: introspectAllServices,
 						Before: RequireHost,
 					},
+					{
+						Name:   "notify-updated",
+						Usage:  "Tell the speaker to re-fetch its source list from AfterTouch",
+						Action: notifySourcesUpdated,
+						Before: RequireHost,
+					},
 				},
 			},
 			// Bass commands
@@ -1825,6 +1941,7 @@ func main() {
 						Action: playNotificationBeep,
 						Before: RequireHost,
 					},
+					ttsCloudCmd(),
 					{
 						Name:   "help",
 						Usage:  "Show detailed help about speaker functionality",
@@ -2196,6 +2313,10 @@ func main() {
 	// Defined in cmd_setup.go to keep the top-level command list readable.
 	app.Commands = append(app.Commands, setupCommand())
 
+	// AfterTouch service management (sources, accounts, devices).
+	// Defined in cmd_cloud.go.
+	app.Commands = append(app.Commands, cloudCommand())
+
 	// Sort commands alphabetically (including subcommands and flags recursively)
 	sortCommands(app.Commands)
 

cmd/soundtouch-cli/main_test.go

@@ -14,16 +14,16 @@ func TestParseHostPort(t *testing.T) {
 	}{
 		{
 			name:        "IPv4 with port",
-			input:       "192.168.1.10:8090",
+			input:       "192.0.2.10:8090",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8090,
 		},
 		{
 			name:        "IPv4 without port",
-			input:       "192.168.1.10",
+			input:       "192.0.2.10",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8080,
 		},
 		{
@@ -63,30 +63,30 @@ func TestParseHostPort(t *testing.T) {
 		},
 		{
 			name:        "invalid port - non-numeric",
-			input:       "192.168.1.10:abc",
+			input:       "192.0.2.10:abc",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8080,
 		},
 		{
 			name:        "invalid port - too high",
-			input:       "192.168.1.10:99999",
+			input:       "192.0.2.10:99999",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8080,
 		},
 		{
 			name:        "invalid port - zero",
-			input:       "192.168.1.10:0",
+			input:       "192.0.2.10:0",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8080,
 		},
 		{
 			name:        "invalid port - negative",
-			input:       "192.168.1.10:-123",
+			input:       "192.0.2.10:-123",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8080,
 		},
 		{
@@ -105,37 +105,37 @@ func TestParseHostPort(t *testing.T) {
 		},
 		{
 			name:        "multiple colons - malformed",
-			input:       "192.168.1.100:8090:extra",
+			input:       "192.0.2.100:8090:extra",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.100:8090:extra",
+			wantHost:    "192.0.2.100:8090:extra",
 			wantPort:    8080,
 		},
 		{
 			name:        "standard SoundTouch default",
-			input:       "192.168.1.10",
+			input:       "192.0.2.10",
 			defaultPort: 8090,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8090,
 		},
 		{
 			name:        "valid high port",
-			input:       "192.168.1.100:65535",
+			input:       "192.0.2.100:65535",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.100",
+			wantHost:    "192.0.2.100",
 			wantPort:    65535,
 		},
 		{
 			name:        "valid low port",
-			input:       "192.168.1.100:1",
+			input:       "192.0.2.100:1",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.100",
+			wantHost:    "192.0.2.100",
 			wantPort:    1,
 		},
 		{
 			name:        "real SoundTouch device example",
-			input:       "192.168.1.10:8090",
+			input:       "192.0.2.10:8090",
 			defaultPort: 8080,
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8090,
 		},
 		{
@@ -166,8 +166,8 @@ func BenchmarkParseHostPort(b *testing.B) {
 		name  string
 		input string
 	}{
-		{"with_port", "192.168.1.100:8090"},
-		{"without_port", "192.168.1.100"},
+		{"with_port", "192.0.2.100:8090"},
+		{"without_port", "192.0.2.100"},
 		{"hostname_with_port", "soundtouch.local:8090"},
 		{"ipv6_with_port", "[::1]:8090"},
 	}
@@ -193,26 +193,26 @@ func TestParseHostPortSoundTouchScenarios(t *testing.T) {
 	}{
 		{
 			name:        "typical_cli_usage",
-			input:       "192.168.1.10:8091",
+			input:       "192.0.2.10:8091",
 			defaultPort: 8090,
 			description: "User specifies full host:port",
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8091,
 		},
 		{
 			name:        "discovery_result_host_only",
-			input:       "192.168.1.10",
+			input:       "192.0.2.10",
 			defaultPort: 8090,
 			description: "Discovery returns IP, CLI uses default port",
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8090,
 		},
 		{
 			name:        "custom_port_override",
-			input:       "192.168.1.100:9000",
+			input:       "192.0.2.100:9000",
 			defaultPort: 8090,
 			description: "User overrides default SoundTouch port",
-			wantHost:    "192.168.1.100",
+			wantHost:    "192.0.2.100",
 			wantPort:    9000,
 		},
 		{
@@ -225,10 +225,10 @@ func TestParseHostPortSoundTouchScenarios(t *testing.T) {
 		},
 		{
 			name:        "invalid_port_fallback",
-			input:       "192.168.1.10:invalid",
+			input:       "192.0.2.10:invalid",
 			defaultPort: 8090,
 			description: "Malformed port should fallback to default",
-			wantHost:    "192.168.1.10",
+			wantHost:    "192.0.2.10",
 			wantPort:    8090,
 		},
 	}

cmd/soundtouch-service/coverage_guard_test.go

@@ -0,0 +1,200 @@
+package main
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
+	"github.com/go-chi/chi/v5"
+)
+
+// frozenFirstSegments are the top-level path prefixes that belong to the frozen
+// speaker / app contract (category 1a/1b in
+// docs/content/docs/architecture/API-ROUTE-LAYOUT.md). Routes under these must
+// not change shape across the issue #451 refactor, so each should have at least
+// one .http contract test (the suite under tests/integration/http-client/, run
+// by `make test-http-client`). Movable surfaces (/setup, /mgmt, /web) and infra
+// (/, /health, /docs, /favicon.ico) are intentionally excluded.
+var frozenFirstSegments = map[string]bool{
+	"streaming": true,
+	"accounts":  true,
+	"customer":  true,
+	"bmx":       true,
+	"bmx-icons": true,
+	"core02":    true,
+	"oauth":     true,
+	"custom":    true,
+	"media":     true,
+	"updates":   true,
+	"v1":        true,
+	"alexa":     true,
+	"ced":       true,
+}
+
+func coverageFirstSegment(p string) string {
+	p = strings.TrimPrefix(p, "/")
+	if i := strings.IndexByte(p, '/'); i >= 0 {
+		return p[:i]
+	}
+
+	return p
+}
+
+// patternToRegexp converts a chi route pattern into an anchored regexp:
+// `{param}` becomes a single path segment (`[^/]+`) and `*` becomes `.*`.
+func patternToRegexp(pattern string) *regexp.Regexp {
+	var b strings.Builder
+
+	b.WriteString("^")
+
+	for i, seg := range strings.Split(pattern, "/") {
+		if i > 0 {
+			b.WriteString("/")
+		}
+
+		switch {
+		case seg == "*":
+			b.WriteString(".*")
+		case strings.HasPrefix(seg, "{") && strings.HasSuffix(seg, "}"):
+			b.WriteString("[^/]+")
+		default:
+			b.WriteString(regexp.QuoteMeta(seg))
+		}
+	}
+
+	b.WriteString("$")
+
+	return regexp.MustCompile(b.String())
+}
+
+// loadHTTPClientRequests extracts (method, path) pairs from every .http file in
+// the integration suite. `{{host}}` is stripped (leaving a leading `/`), query
+// strings are dropped, and `{{var}}` template segments are left intact (they
+// contain no slash, so they match a `[^/]+` route segment).
+func loadHTTPClientRequests(t *testing.T, dir string) [][2]string {
+	t.Helper()
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("read http-client dir %s: %v", dir, err)
+	}
+
+	reqLine := regexp.MustCompile(`^\s*(GET|POST|PUT|DELETE|PATCH|HEAD)\s+(\S+)`)
+
+	var out [][2]string
+
+	for _, e := range entries {
+		if e.IsDir() || !strings.HasSuffix(e.Name(), ".http") {
+			continue
+		}
+
+		data, err := os.ReadFile(filepath.Join(dir, e.Name()))
+		if err != nil {
+			t.Fatalf("read %s: %v", e.Name(), err)
+		}
+
+		for _, line := range strings.Split(string(data), "\n") {
+			m := reqLine.FindStringSubmatch(line)
+			if m == nil {
+				continue
+			}
+
+			url := strings.ReplaceAll(m[2], "{{host}}", "")
+			if i := strings.IndexByte(url, '?'); i >= 0 {
+				url = url[:i]
+			}
+
+			if !strings.HasPrefix(url, "/") {
+				continue
+			}
+
+			out = append(out, [2]string{m[1], url})
+		}
+	}
+
+	return out
+}
+
+// TestFrozenRouteContractCoverage enforces that every frozen-contract route the
+// service registers is exercised by at least one .http integration test. The
+// set of *uncovered* frozen routes is golden-filed: adding a new frozen route
+// without a test (or adding a test that newly covers one) changes the set and
+// fails this test, forcing a conscious update of the golden file. It is the
+// machine-checked companion to tests/integration/http-client/COVERAGE.md.
+func TestFrozenRouteContractCoverage(t *testing.T) {
+	server := handlers.NewServer(nil, nil, "http://localhost:8000", true, true, true)
+	r := setupRouter(server, nil)
+
+	httpRequests := loadHTTPClientRequests(t, filepath.Join("..", "..", "tests", "integration", "http-client"))
+
+	// Only the request methods the contract suite actually exercises. Routes
+	// registered via chi HandleFunc carry every method (CONNECT/TRACE/...); those
+	// extra verbs are noise for coverage purposes.
+	meaningfulMethods := map[string]bool{
+		http.MethodGet: true, http.MethodPost: true, http.MethodPut: true, http.MethodDelete: true,
+	}
+
+	var uncovered []string
+
+	walkFunc := func(method, route string, _ http.Handler, _ ...func(http.Handler) http.Handler) error {
+		if !meaningfulMethods[method] {
+			return nil
+		}
+
+		if !frozenFirstSegments[coverageFirstSegment(route)] {
+			return nil
+		}
+
+		re := patternToRegexp(route)
+		for _, req := range httpRequests {
+			if req[0] == method && re.MatchString(req[1]) {
+				return nil
+			}
+		}
+
+		uncovered = append(uncovered, fmt.Sprintf("%-7s %s", method, route))
+
+		return nil
+	}
+
+	if err := chi.Walk(r, walkFunc); err != nil {
+		t.Fatalf("walk routes: %v", err)
+	}
+
+	sort.Strings(uncovered)
+	output := strings.Join(uncovered, "\n") + "\n"
+
+	const goldenPath = "testdata/frozen_routes_uncovered.txt"
+
+	actualPath := "testdata/frozen_routes_uncovered.actual.txt"
+	if err := os.WriteFile(actualPath, []byte(output), 0644); err != nil {
+		t.Fatalf("write actual: %v", err)
+	}
+
+	golden, err := os.ReadFile(goldenPath)
+	if os.IsNotExist(err) {
+		if err := os.WriteFile(goldenPath, []byte(output), 0644); err != nil {
+			t.Fatalf("create golden: %v", err)
+		}
+
+		t.Logf("created golden %s with %d uncovered frozen routes", goldenPath, len(uncovered))
+
+		return
+	}
+
+	if err != nil {
+		t.Fatalf("read golden: %v", err)
+	}
+
+	if string(golden) != output {
+		t.Errorf("Frozen-route contract coverage changed.\n"+
+			"A frozen route either lost its .http test or a new one was added without one.\n"+
+			"Review and, if intended, update %s from %s.", goldenPath, actualPath)
+	}
+}

cmd/soundtouch-service/deprecated_routes_test.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
+)
+
+// TestDeprecatedRouteSignal verifies the legacy admin paths are counted (and the
+// new /api/* twins are not), so the diagnostic export can show whether the old
+// paths are still in use before they are removed in a future major release.
+func TestDeprecatedRouteSignal(t *testing.T) {
+	ds := datastore.NewDataStore(t.TempDir())
+	_ = ds.Initialize()
+
+	server := handlers.NewServer(ds, nil, "http://localhost:8000", true, false, false)
+	r := setupRouter(server, nil)
+
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	hit := func(path string) {
+		resp, err := http.Get(ts.URL + path)
+		if err != nil {
+			t.Fatalf("GET %s: %v", path, err)
+		}
+
+		_ = resp.Body.Close()
+	}
+
+	hit("/setup/version")     // legacy — counted
+	hit("/setup/version")     // legacy again — count increments
+	hit("/api/setup/version") // new canonical — must NOT be counted
+
+	hits := server.DeprecatedRouteHits()
+
+	if got := hits["GET /setup/version"]; got != 2 {
+		t.Errorf("legacy GET /setup/version hits = %d, want 2", got)
+	}
+
+	if _, tracked := hits["GET /api/setup/version"]; tracked {
+		t.Errorf("/api/setup/version must not be tracked as deprecated; hits=%v", hits)
+	}
+}

cmd/soundtouch-service/dual_route_equivalence_test.go

@@ -0,0 +1,86 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
+)
+
+// TestDualRouteEquivalence verifies the issue #451 step-1 aliasing invariant:
+// each admin-tier route served at both its legacy path and the new /api/* path
+// returns an identical response (same handler, same middleware). It fires the
+// same request at the old and new path and asserts equal status + body.
+//
+// The cases use endpoints whose body does not embed per-request time/random
+// values, so the only thing that can differ is the routing — which is exactly
+// what we want to pin while the routes are dual-mounted.
+func TestDualRouteEquivalence(t *testing.T) {
+	ds := datastore.NewDataStore(t.TempDir())
+	_ = ds.Initialize()
+
+	server := handlers.NewServer(ds, nil, "http://localhost:8000", true, false, false)
+	r := setupRouter(server, nil)
+
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	cases := []struct {
+		method  string
+		oldPath string
+		newPath string
+	}{
+		{http.MethodGet, "/setup/version", "/api/setup/version"},
+		{http.MethodGet, "/setup/settings", "/api/setup/settings"},
+		{http.MethodGet, "/setup/tts/config", "/api/setup/tts/config"},
+		{http.MethodGet, "/setup/logging-settings", "/api/setup/logging-settings"},
+		{http.MethodGet, "/setup/interaction-stats", "/api/setup/interaction-stats"},
+		{http.MethodGet, "/setup/dns-discoveries", "/api/setup/dns-discoveries"},
+		// /mgmt is Basic-Auth'd; without credentials both paths must reject
+		// identically — that pins the auth gate is mirrored onto /api/mgmt too.
+		{http.MethodGet, "/mgmt/accounts/", "/api/mgmt/accounts/"},
+		{http.MethodGet, "/mgmt/spotify/accounts", "/api/mgmt/spotify/accounts"},
+		{http.MethodGet, "/mgmt/amazon/accounts", "/api/mgmt/amazon/accounts"},
+	}
+
+	for _, c := range cases {
+		t.Run(c.method+" "+c.newPath, func(t *testing.T) {
+			oldStatus, oldBody := doEquivReq(t, ts.URL, c.method, c.oldPath)
+			newStatus, newBody := doEquivReq(t, ts.URL, c.method, c.newPath)
+
+			if oldStatus != newStatus {
+				t.Errorf("status mismatch for %s vs %s: old=%d new=%d", c.oldPath, c.newPath, oldStatus, newStatus)
+			}
+
+			if !bytes.Equal(oldBody, newBody) {
+				t.Errorf("body mismatch for %s vs %s:\n old=%q\n new=%q", c.oldPath, c.newPath, oldBody, newBody)
+			}
+		})
+	}
+}
+
+func doEquivReq(t *testing.T, base, method, path string) (int, []byte) {
+	t.Helper()
+
+	req, err := http.NewRequest(method, base+path, nil)
+	if err != nil {
+		t.Fatalf("build request %s: %v", path, err)
+	}
+
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("request %s: %v", path, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		t.Fatalf("read body %s: %v", path, err)
+	}
+
+	return resp.StatusCode, body
+}

cmd/soundtouch-service/logutil.go

@@ -0,0 +1,13 @@
+package main
+
+import "strings"
+
+// sanitizeLog strips newline characters from s to prevent log-injection
+// (CodeQL go/log-injection). Values from speakers, HTTP requests, and
+// external APIs may contain attacker-controlled newlines.
+func sanitizeLog(s string) string {
+	s = strings.ReplaceAll(s, "\n", `\n`)
+	s = strings.ReplaceAll(s, "\r", `\r`)
+
+	return s
+}

cmd/soundtouch-service/main_test.go

@@ -90,3 +90,100 @@ func TestApplyPersistedSettings(t *testing.T) {
 		}
 	})
 }
+
+func TestMergeTLSExtraHosts(t *testing.T) {
+	cases := []struct {
+		name      string
+		cli       []string
+		persisted []string
+		want      []string
+	}{
+		{
+			name:      "CLI only",
+			cli:       []string{"a.example"},
+			persisted: nil,
+			want:      []string{"a.example"},
+		},
+		{
+			name:      "Persisted only",
+			cli:       nil,
+			persisted: []string{"b.example"},
+			want:      []string{"b.example"},
+		},
+		{
+			name:      "CLI wins ordering, persisted appended",
+			cli:       []string{"a.example"},
+			persisted: []string{"b.example"},
+			want:      []string{"a.example", "b.example"},
+		},
+		{
+			name:      "Dedupes overlap",
+			cli:       []string{"a.example", "b.example"},
+			persisted: []string{"b.example", "c.example"},
+			want:      []string{"a.example", "b.example", "c.example"},
+		},
+		{
+			name:      "Drops empty + whitespace",
+			cli:       []string{"  ", "a.example", ""},
+			persisted: []string{"", "  b.example  "},
+			want:      []string{"a.example", "b.example"},
+		},
+		{
+			name:      "Both empty",
+			cli:       nil,
+			persisted: nil,
+			want:      []string{},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := mergeTLSExtraHosts(tc.cli, tc.persisted)
+			if len(got) != len(tc.want) {
+				t.Fatalf("len mismatch: got %v, want %v", got, tc.want)
+			}
+
+			for i := range got {
+				if got[i] != tc.want[i] {
+					t.Errorf("index %d: got %q, want %q (full: %v vs %v)", i, got[i], tc.want[i], got, tc.want)
+				}
+			}
+		})
+	}
+}
+
+func TestGetDomains_IncludesOAuthDerivation(t *testing.T) {
+	// Hostname-based serverURL: the derived OAuth variant must end up
+	// in the served TLS cert SAN list, otherwise the speaker rejects
+	// the TLS handshake on Spotify / Amazon Music token refresh.
+	got := getDomains("http://mac.fritz.box:8000", "https://mac.fritz.box:8443", "mac.fritz.box", nil)
+
+	want := "macoauth.fritz.box"
+	if !contains(got, want) {
+		t.Errorf("expected SAN list to include %q (derived from serverURL), got: %v", want, got)
+	}
+}
+
+func TestGetDomains_IPServerURLProducesNoOAuthDerivation(t *testing.T) {
+	// IP-based serverURL deliberately yields no derivation (the speaker's
+	// `<first-label>oauth.<rest>` construction would be malformed for an
+	// IP and no DNS resolver can answer for it). The cert SAN list must
+	// not pretend to cover something that can never be queried.
+	got := getDomains("http://192.168.0.30:8000", "https://192.168.0.30:8443", "192.168.0.30", nil)
+
+	for _, h := range got {
+		if h == "192oauth.168.0.30" {
+			t.Errorf("SAN list must not include malformed IP-derived OAuth name, got: %v", got)
+		}
+	}
+}
+
+func contains(haystack []string, needle string) bool {
+	for _, h := range haystack {
+		if h == needle {
+			return true
+		}
+	}
+
+	return false
+}

cmd/soundtouch-service/router_test.go

@@ -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"
 )
@@ -17,7 +19,7 @@ import (
 func TestPrintRoutes(t *testing.T) {
 	// Initialize a minimal server to get the router
 	server := handlers.NewServer(nil, nil, "http://localhost:8000", true, true, true)
-	r := setupRouter(server)
+	r := setupRouter(server, nil)
 
 	var routes []string
 	walkFunc := func(method string, route string, handler http.Handler, middlewares ...func(http.Handler) http.Handler) error {
@@ -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, nil)
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	body := `<?xml version="1.0" encoding="UTF-8" ?><device deviceid="AABBCCDDEEFF"><name>Living Room SoundTouch</name><macaddress>AABBCCDDEEFF</macaddress></device>`
+
+	req, err := http.NewRequest(http.MethodPut,
+		ts.URL+"/streaming/account/1111111/device/AABBCCDDEEFF",
+		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)
+	}
+}

cmd/soundtouch-service/testdata/frozen_routes_uncovered.txt

@@ -0,0 +1,35 @@
+DELETE  /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter
+DELETE  /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/*
+DELETE  /streaming/account/{account}/group
+GET     /bmx-icons/*
+GET     /bmx/tunein/v1/navigate
+GET     /bmx/tunein/v1/navigate/*
+GET     /bmx/tunein/v1/playback/episode/{podcastID}
+GET     /bmx/tunein/v1/playback/episodes/{podcastID}
+GET     /bmx/tunein/v1/search
+GET     /bmx/tunein/v1/search/next
+GET     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter
+GET     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/*
+GET     /media/tts/{id}
+GET     /streaming/account/{account}/device/{device}/group
+GET     /streaming/account/{account}/device/{device}/group/member
+GET     /streaming/account/{account}/device/{device}/group/server
+GET     /streaming/account/{account}/device/{device}/recent
+GET     /streaming/account/{account}/presets
+GET     /streaming/device_setting/account/{account}/device/{device}/device_settings
+POST    /core02/svc-bmx-adapter-orion/prod/orion/token
+POST    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter
+POST    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/*
+POST    /oauth/account/{account}/music/musicprovider/{sourceID}/token/cs
+POST    /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token
+POST    /streaming/account/{account}/device/{device}
+POST    /streaming/account/{account}/device/{device}/presets/{presetNumber}
+POST    /streaming/account/{account}/group
+POST    /streaming/account/{account}/group/{groupId}
+POST    /streaming/device_setting/account/{account}/device/{device}/device_settings
+POST    /streaming/music/musicprovider/{providerID}/trial/is_eligible
+POST    /streaming/stats/error
+POST    /streaming/stats/usage
+POST    /v1/stapp/{deviceId}
+PUT     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter
+PUT     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/*

cmd/soundtouch-service/testdata/router_routes.txt

@@ -1,41 +1,91 @@
-CONNECT  /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
-DELETE   /accounts/{account}/devices/{device}                         handlers.(*Server).HandleMargeRemoveDevice-fm
-DELETE   /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeDeleteGroup-fm
+CONNECT  /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+CONNECT  /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm
+DELETE   /accounts/{account}/devices/{device}                         handlers.(*Server).HandleUnsupported-fm
+DELETE   /accounts/{account}/group                                    handlers.(*Server).HandleUnsupported-fm
+DELETE   /accounts/{account}/group/                                   handlers.(*Server).HandleUnsupported-fm
+DELETE   /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleUnsupported-fm
+DELETE   /api/setup/devices/{deviceId}                                handlers.(*Server).HandleRemoveDevice-fm
+DELETE   /api/setup/dns-discoveries                                   handlers.(*Server).HandleClearDNSDiscoveries-fm
+DELETE   /api/setup/interactions/sessions                             handlers.(*Server).HandleCleanupSessions-fm
+DELETE   /api/setup/interactions/sessions/{session}                   handlers.(*Server).HandleDeleteSession-fm
+DELETE   /api/setup/sources/{account}/{device}/{sourceID}             handlers.(*Server).HandleDeleteSource-fm
 DELETE   /bmx/tunein/v1/favorite/{stationID}                          handlers.(*Server).HandleTuneInDeleteFavorite-fm
-DELETE   /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+DELETE   /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+DELETE   /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm
 DELETE   /setup/devices/{deviceId}                                    handlers.(*Server).HandleRemoveDevice-fm
 DELETE   /setup/dns-discoveries                                       handlers.(*Server).HandleClearDNSDiscoveries-fm
 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   /setup/sources/{account}/{device}/{sourceID}                 handlers.(*Server).HandleDeleteSource-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                           handlers.(*Server).HandleMargeDeleteAccountGroups-fm
+DELETE   /streaming/account/{account}/group/                          handlers.(*Server).HandleMargeDeleteAccountGroups-fm
 DELETE   /streaming/account/{account}/group/{groupId}                 handlers.(*Server).HandleMargeDeleteGroup-fm
+DELETE   /streaming/account/{account}/source/{sourceID}               handlers.(*Server).HandleMargeDeleteSource-fm
 GET      /                                                            handlers.(*Server).HandleRoot-fm
-GET      /accounts/{account}/devices                                  handlers.(*Server).HandleMargeAccountDevices-fm
-GET      /accounts/{account}/devices/{device}/group                   handlers.(*Server).HandleMargeDeviceGroup-fm
-GET      /accounts/{account}/devices/{device}/group/                  handlers.(*Server).HandleMargeDeviceGroup-fm
-GET      /accounts/{account}/devices/{device}/group/member            handlers.(*Server).HandleMargeDeviceGroupMember-fm
-GET      /accounts/{account}/devices/{device}/group/server            handlers.(*Server).HandleMargeDeviceGroupServer-fm
-GET      /accounts/{account}/devices/{device}/presets                 handlers.(*Server).HandleMargePresets-fm
-GET      /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleMargeRecents-fm
-GET      /accounts/{account}/full                                     handlers.(*Server).HandleMargeAccountFull-fm
-GET      /accounts/{account}/sources                                  handlers.(*Server).HandleMargeAccountSources-fm
+GET      /accounts/{account}/devices                                  handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/devices/{device}/group                   handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/devices/{device}/group/                  handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/devices/{device}/group/member            handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/devices/{device}/group/server            handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/devices/{device}/presets                 handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/full                                     handlers.(*Server).HandleUnsupported-fm
+GET      /accounts/{account}/sources                                  handlers.(*Server).HandleUnsupported-fm
+GET      /api/mgmt/accounts/                                          handlers.(*Server).HandleMgmtListAccounts-fm
+GET      /api/mgmt/accounts/{accountId}                               handlers.(*Server).HandleMgmtAccountDetails-fm
+GET      /api/mgmt/accounts/{accountId}/speakers                      handlers.(*Server).HandleMgmtListSpeakers-fm
+GET      /api/mgmt/amazon/accounts                                    handlers.(*Server).HandleMgmtAmazonAccounts-fm
+GET      /api/mgmt/amazon/token                                       handlers.(*Server).HandleMgmtAmazonToken-fm
+GET      /api/mgmt/devices/{deviceId}/events                          handlers.(*Server).HandleMgmtDeviceEvents-fm
+GET      /api/mgmt/spotify/accounts                                   handlers.(*Server).HandleMgmtSpotifyAccounts-fm
+GET      /api/mgmt/spotify/token                                      handlers.(*Server).HandleMgmtSpotifyToken-fm
+GET      /api/setup/account-id-suggestions/{deviceId}                 handlers.(*Server).HandleAccountIDSuggestions-fm
+GET      /api/setup/ca.crt                                            handlers.(*Server).HandleGetCACert-fm
+GET      /api/setup/device-summary/{deviceId}                         handlers.(*Server).HandleDeviceSummary-fm
+GET      /api/setup/devices                                           handlers.(*Server).HandleListDiscoveredDevices-fm
+GET      /api/setup/devices/{deviceId}/events                         handlers.(*Server).HandleGetDeviceEvents-fm
+GET      /api/setup/discovery-status                                  handlers.(*Server).HandleGetDiscoveryStatus-fm
+GET      /api/setup/dns-discoveries                                   handlers.(*Server).HandleGetDNSDiscoveries-fm
+GET      /api/setup/dns-discoveries/download                          handlers.(*Server).HandleDownloadDNSDiscoveries-fm
+GET      /api/setup/export/diagnostic                                 handlers.(*Server).HandleExportDiagnostic-fm
+GET      /api/setup/health                                            handlers.(*Server).HandleHealthChecks-fm
+GET      /api/setup/info/{deviceId}                                   handlers.(*Server).HandleGetDeviceInfo-fm
+GET      /api/setup/interaction-content                               handlers.(*Server).HandleGetInteractionContent-fm
+GET      /api/setup/interaction-stats                                 handlers.(*Server).HandleGetInteractionStats-fm
+GET      /api/setup/interactions                                      handlers.(*Server).HandleListInteractions-fm
+GET      /api/setup/interactions/sessions/{session}/download          handlers.(*Server).HandleDownloadSession-fm
+GET      /api/setup/logging-settings                                  handlers.(*Server).HandleGetLoggingSettings-fm
+GET      /api/setup/logs                                              handlers.(*Server).HandleGetLogs-fm
+GET      /api/setup/settings                                          handlers.(*Server).HandleGetSettings-fm
+GET      /api/setup/summary/{deviceId}                                handlers.(*Server).HandleGetMigrationSummary-fm
+GET      /api/setup/tts/config                                        handlers.(*Server).HandleTTSConfig-fm
+GET      /api/setup/version                                           handlers.(*Server).HandleGetVersionInfo-fm
 GET      /bmx-icons/*                                                 handlers.(*Server).HandleBmxIcons
 GET      /bmx/registry/v1/services                                    handlers.(*Server).HandleBMXRegistry-fm
 GET      /bmx/registry/v1/servicesAvailability                        handlers.(*Server).HandleBMXServicesAvailability-fm
+GET      /bmx/tunein/                                                 handlers.(*Server).HandleTuneInService-fm
 GET      /bmx/tunein/v1/navigate                                      handlers.(*Server).HandleTuneInNavigate-fm
 GET      /bmx/tunein/v1/navigate/*                                    handlers.(*Server).HandleTuneInNavigate-fm
 GET      /bmx/tunein/v1/playback/episode/{podcastID}                  handlers.(*Server).HandleTuneInPlaybackPodcast-fm
 GET      /bmx/tunein/v1/playback/episodes/{podcastID}                 handlers.(*Server).HandleTuneInPodcastInfo-fm
 GET      /bmx/tunein/v1/playback/station/{stationID}                  handlers.(*Server).HandleTuneInPlayback-fm
 GET      /bmx/tunein/v1/search                                        handlers.(*Server).HandleTuneInSearch-fm
+GET      /bmx/tunein/v1/search/next                                   handlers.(*Server).HandleTuneInSearchNext-fm
 GET      /ced/*                                                       handlers.(*Server).HandleCedStatic
+GET      /core02/svc-bmx-adapter-orion/prod/orion                     handlers.(*Server).HandleOrionService-fm
+GET      /core02/svc-bmx-adapter-orion/prod/orion/station             handlers.(*Server).HandleOrionPlayback-fm
+GET      /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+GET      /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm
 GET      /custom/v1/playback/{encodedURL}                             handlers.(*Server).HandleCustomPlayback-fm
 GET      /customer/account/{account}                                  handlers.(*Server).HandleMargeAccountProfile-fm
 GET      /docs/*                                                      handlers.(*Server).HandleDocs-fm
 GET      /favicon.ico                                                 setupRouter
 GET      /health                                                      handlers.(*Server).HandleHealth-fm
 GET      /media/*                                                     handlers.(*Server).HandleMedia
+GET      /media/aftertouch-ding.wav                                   handlers.(*Server).HandleDing-fm
+GET      /media/tts/{id}                                              handlers.(*Server).HandleTTSMedia-fm
 GET      /mgmt/accounts/                                              handlers.(*Server).HandleMgmtListAccounts-fm
 GET      /mgmt/accounts/{accountId}                                   handlers.(*Server).HandleMgmtAccountDetails-fm
 GET      /mgmt/accounts/{accountId}/speakers                          handlers.(*Server).HandleMgmtListSpeakers-fm
@@ -46,24 +96,26 @@ GET      /mgmt/devices/{deviceId}/events                              handlers.(
 GET      /mgmt/spotify/accounts                                       handlers.(*Server).HandleMgmtSpotifyAccounts-fm
 GET      /mgmt/spotify/callback                                       handlers.(*Server).HandleMgmtSpotifyCallback-fm
 GET      /mgmt/spotify/token                                          handlers.(*Server).HandleMgmtSpotifyToken-fm
-GET      /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
-GET      /proxy/*                                                     handlers.(*Server).HandleProxyRequest-fm
 GET      /setup/account-id-suggestions/{deviceId}                     handlers.(*Server).HandleAccountIDSuggestions-fm
 GET      /setup/ca.crt                                                handlers.(*Server).HandleGetCACert-fm
+GET      /setup/device-summary/{deviceId}                             handlers.(*Server).HandleDeviceSummary-fm
 GET      /setup/devices                                               handlers.(*Server).HandleListDiscoveredDevices-fm
 GET      /setup/devices/{deviceId}/events                             handlers.(*Server).HandleGetDeviceEvents-fm
 GET      /setup/discovery-status                                      handlers.(*Server).HandleGetDiscoveryStatus-fm
 GET      /setup/dns-discoveries                                       handlers.(*Server).HandleGetDNSDiscoveries-fm
 GET      /setup/dns-discoveries/download                              handlers.(*Server).HandleDownloadDNSDiscoveries-fm
+GET      /setup/export/diagnostic                                     handlers.(*Server).HandleExportDiagnostic-fm
+GET      /setup/health                                                handlers.(*Server).HandleHealthChecks-fm
 GET      /setup/info/{deviceId}                                       handlers.(*Server).HandleGetDeviceInfo-fm
 GET      /setup/interaction-content                                   handlers.(*Server).HandleGetInteractionContent-fm
 GET      /setup/interaction-stats                                     handlers.(*Server).HandleGetInteractionStats-fm
 GET      /setup/interactions                                          handlers.(*Server).HandleListInteractions-fm
 GET      /setup/interactions/sessions/{session}/download              handlers.(*Server).HandleDownloadSession-fm
-GET      /setup/parity-mismatches                                     handlers.(*Server).HandleListParityMismatches-fm
-GET      /setup/proxy-settings                                        handlers.(*Server).HandleGetProxySettings-fm
+GET      /setup/logging-settings                                      handlers.(*Server).HandleGetLoggingSettings-fm
+GET      /setup/logs                                                  handlers.(*Server).HandleGetLogs-fm
 GET      /setup/settings                                              handlers.(*Server).HandleGetSettings-fm
 GET      /setup/summary/{deviceId}                                    handlers.(*Server).HandleGetMigrationSummary-fm
+GET      /setup/tts/config                                            handlers.(*Server).HandleTTSConfig-fm
 GET      /setup/version                                               handlers.(*Server).HandleGetVersionInfo-fm
 GET      /streaming/account/{account}/device/{device}/group           handlers.(*Server).HandleMargeDeviceGroup-fm
 GET      /streaming/account/{account}/device/{device}/group/          handlers.(*Server).HandleMargeDeviceGroup-fm
@@ -85,22 +137,57 @@ GET      /streaming/resources/api_versions.xml                        handlers.(
 GET      /streaming/software/update/account/{account}                 handlers.(*Server).HandleMargeSoftwareUpdate-fm
 GET      /streaming/sourceproviders                                   handlers.(*Server).HandleMargeSourceProviders-fm
 GET      /updates/soundtouch                                          handlers.(*Server).HandleMargeSoftwareUpdate-fm
+GET      /v1/auth                                                     handlers.(*Server).HandleSpeakerAuth-fm
 GET      /v1/blacklist/{deviceId}                                     setupRouter
 GET      /web/*                                                       setupRouter.(*Server).HandleWeb
-HEAD     /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
-OPTIONS  /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
-PATCH    /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
-POST     /accounts/{account}/devices                                  handlers.(*Server).HandleMargeAddDevice-fm
-POST     /accounts/{account}/devices/{device}/presets/{presetNumber}  handlers.(*Server).HandleMargeUpdatePreset-fm
-POST     /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleMargeAddRecent-fm
-POST     /accounts/{account}/group                                    handlers.(*Server).HandleMargeAddGroup-fm
-POST     /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeModifyGroup-fm
+HEAD     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+HEAD     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm
+OPTIONS  /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+OPTIONS  /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm
+PATCH    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+PATCH    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm
+POST     /accounts/{account}/devices                                  handlers.(*Server).HandleUnsupported-fm
+POST     /accounts/{account}/devices/{device}/presets/{presetNumber}  handlers.(*Server).HandleUnsupported-fm
+POST     /accounts/{account}/devices/{device}/recents                 handlers.(*Server).HandleUnsupported-fm
+POST     /accounts/{account}/group                                    handlers.(*Server).HandleUnsupported-fm
+POST     /accounts/{account}/group/                                   handlers.(*Server).HandleUnsupported-fm
+POST     /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleUnsupported-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     /api/mgmt/accounts/{accountId}/language                      handlers.(*Server).HandleMgmtUpdateAccountLanguage-fm
+POST     /api/mgmt/accounts/{accountId}/provider-settings             handlers.(*Server).HandleMgmtUpdateAccountProviderSetting-fm
+POST     /api/mgmt/amazon/confirm                                     handlers.(*Server).HandleMgmtAmazonConfirm-fm
+POST     /api/mgmt/amazon/init                                        handlers.(*Server).HandleMgmtAmazonInit-fm
+POST     /api/mgmt/amazon/prime                                       handlers.(*Server).HandleMgmtPrimeDeviceAmazon-fm
+POST     /api/mgmt/spotify/confirm                                    handlers.(*Server).HandleMgmtSpotifyConfirm-fm
+POST     /api/mgmt/spotify/entity                                     handlers.(*Server).HandleMgmtSpotifyEntity-fm
+POST     /api/mgmt/spotify/init                                       handlers.(*Server).HandleMgmtSpotifyInit-fm
+POST     /api/mgmt/spotify/prime                                      handlers.(*Server).HandleMgmtPrimeDevice-fm
+POST     /api/setup/backup/{deviceId}                                 handlers.(*Server).HandleBackupConfig-fm
+POST     /api/setup/devices                                           handlers.(*Server).HandleAddManualDevice-fm
+POST     /api/setup/discover                                          handlers.(*Server).HandleTriggerDiscovery-fm
+POST     /api/setup/ensure-remote-services/{deviceId}                 handlers.(*Server).HandleEnsureRemoteServices-fm
+POST     /api/setup/health/dns-path-probe                             handlers.(*Server).HandleDNSPathProbe-fm
+POST     /api/setup/health/fix                                        handlers.(*Server).HandleHealthFix-fm
+POST     /api/setup/logging-settings                                  handlers.(*Server).HandleUpdateLoggingSettings-fm
+POST     /api/setup/migrate/{deviceId}                                handlers.(*Server).HandleMigrateDevice-fm
+POST     /api/setup/pair-account/{deviceId}                           handlers.(*Server).HandlePairAccount-fm
+POST     /api/setup/peer-probe/{deviceId}                             handlers.(*Server).HandlePeerProbe-fm
+POST     /api/setup/reboot/{deviceId}                                 handlers.(*Server).HandleRebootDevice-fm
+POST     /api/setup/remove-remote-services/{deviceId}                 handlers.(*Server).HandleRemoveRemoteServices-fm
+POST     /api/setup/revert/{deviceId}                                 handlers.(*Server).HandleRevertMigration-fm
+POST     /api/setup/settings                                          handlers.(*Server).HandleUpdateSettings-fm
+POST     /api/setup/sync/{deviceId}                                   handlers.(*Server).HandleInitialSync-fm
+POST     /api/setup/test-connection/{deviceId}                        handlers.(*Server).HandleTestConnection-fm
+POST     /api/setup/test-dns/{deviceId}                               handlers.(*Server).HandleTestDNSRedirection-fm
+POST     /api/setup/test-hosts/{deviceId}                             handlers.(*Server).HandleTestHostsRedirection-fm
+POST     /api/setup/trust-ca/{deviceId}                               handlers.(*Server).HandleTrustCACert-fm
+POST     /api/setup/tts/speak                                         handlers.(*Server).HandleTTSSpeak-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     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+POST     /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-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
@@ -112,7 +199,6 @@ POST     /mgmt/spotify/confirm                                        handlers.(
 POST     /mgmt/spotify/entity                                         handlers.(*Server).HandleMgmtSpotifyEntity-fm
 POST     /mgmt/spotify/init                                           handlers.(*Server).HandleMgmtSpotifyInit-fm
 POST     /mgmt/spotify/prime                                          handlers.(*Server).HandleMgmtPrimeDevice-fm
-POST     /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
 POST     /oauth/account/{account}/music/musicprovider/{sourceID}/token/cs handlers.(*Server).HandleBoseAccountToken-fm
 POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token handlers.(*Server).HandleBoseLegacyToken-fm
 POST     /oauth/device/{deviceID}/music/musicprovider/{sourceID}/token/cs1 handlers.(*Server).HandleBoseToken-fm
@@ -121,10 +207,12 @@ POST     /setup/backup/{deviceId}                                     handlers.(
 POST     /setup/devices                                               handlers.(*Server).HandleAddManualDevice-fm
 POST     /setup/discover                                              handlers.(*Server).HandleTriggerDiscovery-fm
 POST     /setup/ensure-remote-services/{deviceId}                     handlers.(*Server).HandleEnsureRemoteServices-fm
+POST     /setup/health/dns-path-probe                                 handlers.(*Server).HandleDNSPathProbe-fm
+POST     /setup/health/fix                                            handlers.(*Server).HandleHealthFix-fm
+POST     /setup/logging-settings                                      handlers.(*Server).HandleUpdateLoggingSettings-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
 POST     /setup/revert/{deviceId}                                     handlers.(*Server).HandleRevertMigration-fm
@@ -134,6 +222,7 @@ POST     /setup/test-connection/{deviceId}                            handlers.(
 POST     /setup/test-dns/{deviceId}                                   handlers.(*Server).HandleTestDNSRedirection-fm
 POST     /setup/test-hosts/{deviceId}                                 handlers.(*Server).HandleTestHostsRedirection-fm
 POST     /setup/trust-ca/{deviceId}                                   handlers.(*Server).HandleTrustCACert-fm
+POST     /setup/tts/speak                                             handlers.(*Server).HandleTTSSpeak-fm
 POST     /streaming/account                                           handlers.(*Server).HandleMargeCreateAccount-fm
 POST     /streaming/account/login                                     handlers.(*Server).HandleMargeLogin-fm
 POST     /streaming/account/{account}/device/                         handlers.(*Server).HandleMargeAddDevice-fm
@@ -141,6 +230,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
@@ -152,6 +242,9 @@ POST     /streaming/support/customersupport                           handlers.(
 POST     /streaming/support/power_on                                  handlers.(*Server).HandleMargePowerOn-fm
 POST     /v1/scmudc/{deviceId}                                        handlers.(*Server).HandleAppEvents-fm
 POST     /v1/stapp/{deviceId}                                         handlers.(*Server).HandleAppEvents-fm
-PUT      /oauth/*                                                     handlers.(*Server).HandleBoseProxy-fm
+PUT      /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+PUT      /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-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
+TRACE    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+TRACE    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-fm

cmd/soundtouch-web/README.md

@@ -88,16 +88,43 @@ go build -o soundtouch-web
 ./soundtouch-web -port 8888
 
 # Connect to specific device
-./soundtouch-web -host 192.168.1.100
+./soundtouch-web -host 192.0.2.100
 ```
 
 ### Command Line Options
 ```
--port string    Web server port (default "8080")
--host string    Specific SoundTouch device host (optional, enables single-device mode)
--help          Show help information
+--port, -p string    HTTP port to listen on (default "8080", env PORT)
+--bind string        Address for the HTTP listener: host, IP, or interface name (env BIND_ADDR)
+--interface string   Network interface name for mDNS/UPnP discovery (env DISCOVERY_INTERFACE)
+--devices strings    SoundTouch device IP(s) to add manually, repeatable (env SOUNDTOUCH_DEVICES)
+--service-url string AfterTouch service base URL, e.g. https://soundtouch.local (env SERVICE_URL)
+--service-ca string  Path to the AfterTouch service CA certificate (PEM) to trust (env SERVICE_CA)
+--help, -h           Show help information
 ```
 
+### Text-to-Speech (TTS)
+
+TTS synthesis and the Bose `app_key` live in the AfterTouch service, not in
+soundtouch-web, so the "Speak" feature proxies to the service's
+`/setup/tts/speak` endpoint. To use it, point soundtouch-web at the service
+with `--service-url`.
+
+When the service is served over HTTPS with its own self-signed certificate
+(the default), soundtouch-web also needs to trust the service's CA, or the
+proxied call fails with `x509: certificate signed by unknown authority`. Pass
+the CA with `--service-ca`; it is the service's `<dataDir>/certs/ca.crt`:
+
+```bash
+soundtouch-web \
+  --service-url https://soundtouch.fritz.box \
+  --service-ca /path/to/certs/ca.crt
+```
+
+The CA is appended to the system trust store, so a service URL that uses a
+publicly trusted certificate keeps working without the flag. The target
+speaker must be known to the service (it resolves the speaker against its own
+device datastore).
+
 ## Usage
 
 ### Accessing the Interface

cmd/soundtouch-web/handlers/handlers.go

@@ -1,648 +0,0 @@
-// 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)
-	}
-}

cmd/soundtouch-web/handlers/websocket.go

@@ -1,329 +0,0 @@
-// Package handlers contains WebSocket handlers for real-time communication.
-package handlers
-
-import (
-	"encoding/json"
-	"log"
-	"net/http"
-	"time"
-
-	"github.com/gesellix/bose-soundtouch/cmd/soundtouch-web/webtypes"
-	"github.com/gesellix/bose-soundtouch/pkg/models"
-	"github.com/go-chi/chi/v5"
-	"github.com/gorilla/websocket"
-)
-
-// 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 {
-		log.Printf("WebSocket upgrade failed: %v", err)
-		return
-	}
-
-	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{}{
-			"info":     device.DeviceInfo,
-			"status":   device.Status,
-			"lastSeen": device.LastSeen,
-		}
-	}
-
-	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()
-
-		for {
-			if _, _, err := conn.NextReader(); err != nil {
-				log.Printf("WebSocket read error: %v", err)
-				return
-			}
-		}
-	}()
-
-	// 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 {
-				statusMessage := webtypes.WebSocketMessage{
-					Type:     "status_update",
-					DeviceID: id,
-					Data:     device.Status,
-				}
-
-				if err := conn.WriteJSON(statusMessage); err != nil {
-					log.Printf("Failed to send status update: %v", err)
-					return
-				}
-			}
-		}
-	}
-}
-
-// 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")
-
-	response := webtypes.APIResponse{
-		Success: true,
-		Data:    map[string]string{"message": "Discovery started"},
-	}
-
-	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 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()
-	})
-
-	wsClient.OnVolumeUpdated(func(event *models.VolumeUpdatedEvent) {
-		conn.Status.Volume = &event.Volume
-		conn.Status.LastActivity = time.Now()
-	})
-
-	wsClient.OnConnectionState(func(event *models.ConnectionStateUpdatedEvent) {
-		conn.Status.IsConnected = event.ConnectionState.IsConnected()
-		conn.Status.LastActivity = time.Now()
-	})
-
-	wsClient.OnPresetUpdated(func(event *models.PresetUpdatedEvent) {
-		conn.Status.Presets = &event.Presets
-		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
-	}
-
-	conn.WebSocket = wsClient
-	conn.Status.IsConnected = true
-
-	log.Printf("WebSocket connected for device %s", deviceID)
-
-	// Wait for disconnection
-	wsClient.Wait()
-
-	conn.Status.IsConnected = false
-
-	log.Printf("WebSocket disconnected for device %s", deviceID)
-}
-
-// 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 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 == "" {
-		http.Error(w, "Device ID required", http.StatusBadRequest)
-		return
-	}
-
-	device, exists := app.Devices[deviceID]
-	if !exists {
-		http.Error(w, "Device not found", http.StatusNotFound)
-		return
-	}
-
-	conn, err := app.Upgrader.Upgrade(w, r, nil)
-	if err != nil {
-		log.Printf("Device WebSocket upgrade failed for %s: %v", deviceID, err)
-		return
-	}
-	defer conn.Close()
-
-	log.Printf("Device WebSocket connected for %s", deviceID)
-
-	// Send initial device status
-	initialMessage := webtypes.WebSocketMessage{
-		Type:     "device_status",
-		DeviceID: deviceID,
-		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()
-
-		for {
-			if _, _, err := conn.NextReader(); err != nil {
-				log.Printf("Device WebSocket read error for %s: %v", deviceID, err)
-				return
-			}
-		}
-	}()
-
-	// 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
-		}
-
-		// Send device status update
-		statusMessage := webtypes.WebSocketMessage{
-			Type:     "device_status",
-			DeviceID: deviceID,
-			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 {
-			realtimeMessage := webtypes.WebSocketMessage{
-				Type:     "device_realtime",
-				DeviceID: deviceID,
-				Data: map[string]interface{}{
-					"nowPlaying": device.Status.NowPlaying,
-					"volume":     device.Status.Volume,
-					"timestamp":  time.Now(),
-				},
-			}
-
-			if err := conn.WriteJSON(realtimeMessage); err != nil {
-				log.Printf("Failed to send realtime update for %s: %v", deviceID, err)
-				return
-			}
-		}
-	}
-}

cmd/soundtouch-web/logutil.go

@@ -0,0 +1,13 @@
+package main
+
+import "strings"
+
+// sanitizeLog strips newline characters from s to prevent log-injection
+// (CodeQL go/log-injection). Values from speakers, HTTP requests, and
+// external APIs may contain attacker-controlled newlines.
+func sanitizeLog(s string) string {
+	s = strings.ReplaceAll(s, "\n", `\n`)
+	s = strings.ReplaceAll(s, "\r", `\r`)
+
+	return s
+}

cmd/soundtouch-web/main.go

@@ -3,28 +3,53 @@ package main
 
 import (
 	"context"
-	"embed"
 	"fmt"
-	"io/fs"
 	"log"
 	"net"
 	"net/http"
 	"os"
+	"runtime/debug"
+	"strings"
 	"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/client"
-	"github.com/gesellix/bose-soundtouch/pkg/config"
-	"github.com/gesellix/bose-soundtouch/pkg/discovery"
+	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
 	"github.com/go-chi/chi/v5"
 	"github.com/urfave/cli/v2"
 )
 
-//go:embed static
-var staticFS embed.FS
+var (
+	version = "dev"
+	commit  = "unknown"
+	date    = "unknown"
+	repoURL = "https://github.com/gesellix/bose-soundtouch"
+)
+
+func updateBuildInfo() {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		if info.Main.Path != "" {
+			repoURL = "https://" + info.Main.Path
+		}
+
+		if info.Main.Version != "" && info.Main.Version != "(devel)" {
+			version = info.Main.Version
+		}
+
+		for _, setting := range info.Settings {
+			switch setting.Key {
+			case "vcs.revision":
+				commit = setting.Value
+			case "vcs.time":
+				if t, err := time.Parse(time.RFC3339, setting.Value); err == nil {
+					date = t.Format("2006-01-02 15:04:05")
+				}
+			}
+		}
+	}
+}
 
 func main() {
+	updateBuildInfo()
+
 	app := &cli.App{
 		Name:  "soundtouch-web",
 		Usage: "Web UI for controlling Bose SoundTouch devices",
@@ -46,6 +71,21 @@ func main() {
 				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"},
 			},
+			&cli.StringSliceFlag{
+				Name:    "devices",
+				Usage:   "SoundTouch device IP address(es) to add manually (can be specified multiple times)",
+				EnvVars: []string{"SOUNDTOUCH_DEVICES"},
+			},
+			&cli.StringFlag{
+				Name:    "service-url",
+				Usage:   "AfterTouch service base URL (e.g. https://soundtouch.local). Required for custom stream URLs to work as presets via LOCAL_INTERNET_RADIO",
+				EnvVars: []string{"SERVICE_URL"},
+			},
+			&cli.StringFlag{
+				Name:    "service-ca",
+				Usage:   "Path to the AfterTouch service CA certificate (PEM) to trust for server-side calls such as TTS. Typically the service's <dataDir>/certs/ca.crt. Appended to the system trust store",
+				EnvVars: []string{"SERVICE_CA"},
+			},
 		},
 		Action: func(c *cli.Context) error {
 			port := c.String("port")
@@ -57,14 +97,15 @@ func main() {
 			}
 
 			if rawBind != "" && bindAddr != rawBind {
-				log.Printf("Resolved --bind %q to %s", rawBind, bindAddr)
+				log.Printf("Resolved --bind %q to %s", sanitizeLog(rawBind), sanitizeLog(bindAddr))
 			}
 
 			rawIface := c.String("interface")
+			manualHosts := c.StringSlice("devices")
 
 			ifaceName := defaultDiscoveryInterface(rawIface, rawBind, bindAddr)
 			if rawIface == "" && ifaceName != "" {
-				log.Printf("Defaulting --interface to %q from --bind", ifaceName)
+				log.Printf("Defaulting --interface to %q from --bind", sanitizeLog(ifaceName))
 			}
 
 			addr := ":" + port
@@ -73,41 +114,47 @@ func main() {
 			}
 
 			// Create web app without templates (SPA mode)
-			webApp := handlers.NewWebApp()
+			webApp := soundtouchweb.NewWebApp()
+			webApp.Version = version
+			webApp.Commit = commit
+			webApp.Date = date
+			webApp.RepoURL = repoURL
+			webApp.ServiceURL = strings.TrimRight(c.String("service-url"), "/")
 
-			// Initialize discovery service
-			cfg, err := config.LoadFromEnv()
-			if err != nil {
-				log.Printf("Failed to load config: %v, using defaults", err)
+			if caPath := c.String("service-ca"); caPath != "" {
+				client, err := soundtouchweb.NewServiceHTTPClient(caPath)
+				if err != nil {
+					log.Fatalf("--service-ca: %v", err)
+				}
 
-				cfg = config.DefaultConfig()
+				webApp.ServiceClient = client
+
+				log.Printf("Trusting AfterTouch service CA from %s", sanitizeLog(caPath))
 			}
 
-			cfg.DiscoveryTimeout = 10 * time.Second
-			cfg.CacheEnabled = true
-
-			if ifaceName != "" {
-				cfg.DiscoveryInterface = ifaceName
-			}
-
-			discoveryService := discovery.NewUnifiedDiscoveryService(cfg)
+			discoveryService := soundtouchweb.NewDiscoveryService(ifaceName)
 
 			// Discover devices on startup
 			go func() {
 				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 				defer cancel()
 
-				webApp.BroadcastDiscoveryStatus("starting", len(webApp.Devices))
+				webApp.BroadcastDiscoveryStatus("starting", webApp.DeviceCount())
 
-				discoverDevices(ctx, webApp, discoveryService)
+				for _, host := range manualHosts {
+					webApp.AddDeviceByHost(host, 8090, "manual")
+				}
 
-				webApp.BroadcastDiscoveryStatus("completed", len(webApp.Devices))
+				webApp.DiscoverDevices(ctx, discoveryService)
+
+				webApp.BroadcastDiscoveryStatus("completed", webApp.DeviceCount())
 				webApp.BroadcastDeviceList()
 			}()
 
-			r := setupRoutes(webApp, discoveryService)
+			r := chi.NewRouter()
+			webApp.Mount(r, discoveryService)
 
-			log.Printf("SoundTouch Web UI starting on http://%s", addr)
+			log.Printf("AfterTouch Web UI starting on http://%s", sanitizeLog(addr))
 
 			return http.ListenAndServe(addr, r)
 		},
@@ -199,126 +246,3 @@ func resolveBindAddr(bindAddr string) (string, error) {
 		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)
-	}
-}

cmd/soundtouch-web/resolve_bind_addr_test.go

@@ -14,7 +14,7 @@ func TestResolveBindAddr_PassThrough(t *testing.T) {
 		"",
 		"localhost",
 		"127.0.0.1",
-		"192.168.1.5",
+		"192.0.2.5",
 		"::1",
 		"definitely-not-an-iface-xyz",
 	}
@@ -102,21 +102,21 @@ func TestDefaultDiscoveryInterface(t *testing.T) {
 			name:         "explicit interface wins over bind-derived default",
 			rawInterface: "eth1",
 			rawBind:      "eth0",
-			resolvedBind: "192.168.1.5",
+			resolvedBind: "192.0.2.5",
 			want:         "eth1",
 		},
 		{
 			name:         "derive from --bind when --bind was an interface name",
 			rawInterface: "",
 			rawBind:      "eth0",
-			resolvedBind: "192.168.1.5",
+			resolvedBind: "192.0.2.5",
 			want:         "eth0",
 		},
 		{
 			name:         "no derivation when --bind was an IP literal",
 			rawInterface: "",
-			rawBind:      "192.168.1.5",
-			resolvedBind: "192.168.1.5",
+			rawBind:      "192.0.2.5",
+			resolvedBind: "192.0.2.5",
 			want:         "",
 		},
 		{

cmd/soundtouch-web/spa_test.go

@@ -7,11 +7,10 @@ import (
 	"net/http/httptest"
 	"strings"
 	"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"
 )
 
@@ -70,7 +69,7 @@ func TestSPARouting(t *testing.T) {
 <html lang="en">
 <head>
     <meta charset="UTF-8" />
-    <title>SoundTouch Control Center</title>
+    <title>AfterTouch Control Center</title>
 </head>
 <body>
     <div id="app">SPA Content</div>
@@ -100,7 +99,7 @@ func TestSPARouting(t *testing.T) {
 }
 
 func TestAPIEndpoints(t *testing.T) {
-	app := handlers.NewWebApp()
+	app := soundtouchweb.NewWebApp()
 
 	tests := []struct {
 		name           string
@@ -171,7 +170,7 @@ func TestAPIEndpoints(t *testing.T) {
 }
 
 func TestAPIResponseFormat(t *testing.T) {
-	app := handlers.NewWebApp()
+	app := soundtouchweb.NewWebApp()
 
 	req := httptest.NewRequest("GET", "/api/devices", nil)
 	w := httptest.NewRecorder()
@@ -204,7 +203,7 @@ func TestAPIResponseFormat(t *testing.T) {
 }
 
 func TestControlAPIValidation(t *testing.T) {
-	app := handlers.NewWebApp()
+	app := soundtouchweb.NewWebApp()
 
 	tests := []struct {
 		name           string
@@ -250,13 +249,9 @@ 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"},
-		LastSeen:   time.Now(),
-		Status:     webtypes.DeviceStatus{IsConnected: true},
-	}
-	app.Devices["testdevice"] = mockDevice
+	mockDevice := webtypes.NewDeviceConnection(nil, &models.DeviceInfo{Name: "Test Device"})
+	mockDevice.SetStatus(&webtypes.DeviceStatus{IsConnected: true})
+	app.AddDevice("testdevice", mockDevice)
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
@@ -301,7 +296,7 @@ func TestControlAPIValidation(t *testing.T) {
 }
 
 func TestWebSocketUpgrade(t *testing.T) {
-	app := handlers.NewWebApp()
+	app := soundtouchweb.NewWebApp()
 
 	// Test WebSocket upgrade request
 	req := httptest.NewRequest("GET", "/ws", nil)
@@ -321,7 +316,7 @@ func TestWebSocketUpgrade(t *testing.T) {
 }
 
 func TestJSONAPIConsistency(t *testing.T) {
-	app := handlers.NewWebApp()
+	app := soundtouchweb.NewWebApp()
 
 	endpoints := []string{
 		"/api/devices",

cmd/soundtouch-web/static/index.html

@@ -1,200 +0,0 @@
-<!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>

cmd/soundtouch-web/webtypes/types.go

@@ -1,74 +0,0 @@
-// Package webtypes contains type definitions for the SoundTouch web UI.
-package webtypes
-
-import (
-	"time"
-
-	"github.com/gesellix/bose-soundtouch/pkg/client"
-	"github.com/gesellix/bose-soundtouch/pkg/models"
-)
-
-// SoundTouchClient defines the interface for SoundTouch client operations
-type SoundTouchClient interface {
-	Play() error
-	Pause() error
-	Stop() error
-	NextTrack() error
-	PrevTrack() error
-	SetVolume(level int) error
-	SetBass(level int) error
-	SelectPreset(id int) error
-	SelectSource(source, account string) error
-	SendKey(key string) error
-	GetDeviceInfo() (*models.DeviceInfo, error)
-	GetNowPlaying() (*models.NowPlaying, error)
-	GetVolume() (*models.Volume, error)
-	GetPresets() (*models.Presets, error)
-	GetSources() (*models.Sources, error)
-	GetBass() (*models.Bass, error)
-	NewWebSocketClient(config interface{}) *client.WebSocketClient
-}
-
-// DeviceConnection wraps a SoundTouch client with WebSocket connection
-type DeviceConnection struct {
-	Client     *client.Client
-	WebSocket  *client.WebSocketClient
-	DeviceInfo *models.DeviceInfo
-	LastSeen   time.Time
-	Status     DeviceStatus
-}
-
-// DeviceStatus represents the current device state
-type DeviceStatus struct {
-	NowPlaying   *models.NowPlaying `json:"nowPlaying,omitempty"`
-	Volume       *models.Volume     `json:"volume,omitempty"`
-	Presets      *models.Presets    `json:"presets,omitempty"`
-	Sources      *models.Sources    `json:"sources,omitempty"`
-	Bass         *models.Bass       `json:"bass,omitempty"`
-	IsConnected  bool               `json:"isConnected"`
-	LastActivity time.Time          `json:"lastActivity"`
-}
-
-// APIResponse is a standard JSON response wrapper
-type APIResponse struct {
-	Success bool        `json:"success"`
-	Data    interface{} `json:"data,omitempty"`
-	Error   string      `json:"error,omitempty"`
-}
-
-// VolumeRequest represents a volume control request
-type VolumeRequest struct {
-	Level int `json:"level"`
-}
-
-// BassRequest represents a bass control request
-type BassRequest struct {
-	Level int `json:"level"`
-}
-
-// WebSocketMessage represents messages sent over WebSocket
-type WebSocketMessage struct {
-	Type     string      `json:"type"`
-	DeviceID string      `json:"deviceId,omitempty"`
-	Data     interface{} `json:"data,omitempty"`
-}

cmd/websocket-demo/logutil.go

@@ -0,0 +1,13 @@
+package main
+
+import "strings"
+
+// sanitizeLog strips newline characters from s to prevent log-injection
+// (CodeQL go/log-injection). Values from speakers, HTTP requests, and
+// external APIs may contain attacker-controlled newlines.
+func sanitizeLog(s string) string {
+	s = strings.ReplaceAll(s, "\n", `\n`)
+	s = strings.ReplaceAll(s, "\r", `\r`)
+
+	return s
+}

cmd/websocket-demo/main.go

@@ -355,9 +355,11 @@ func handlePreset(event *models.PresetUpdatedEvent, verbose bool) {
 	for _, preset := range presets.Preset {
 		fmt.Printf("  📻 Preset %d:", preset.ID)
 
-		if preset.ContentItem != nil {
-			fmt.Printf(" %s", preset.ContentItem.ItemName)
-			fmt.Printf(" (%s)", preset.ContentItem.Source)
+		// IsEmpty catches both <preset/> and INVALID_SOURCE
+		// placeholders; using the nil-safe helpers below means the
+		// inner Printf never dereferences a nil ContentItem.
+		if !preset.IsEmpty() {
+			fmt.Printf(" %s (%s)", preset.GetDisplayName(), preset.GetSource())
 		}
 
 		fmt.Println()
@@ -544,13 +546,13 @@ func printHelp() {
 	fmt.Printf("  %s -discover\n", os.Args[0])
 	fmt.Println()
 	fmt.Println("  # Connect to specific device and monitor volume events only")
-	fmt.Printf("  %s -host 192.168.1.10 -filter volume\n", os.Args[0])
+	fmt.Printf("  %s -host 192.0.2.10 -filter volume\n", os.Args[0])
 	fmt.Println()
 	fmt.Println("  # Monitor for 5 minutes with verbose output")
-	fmt.Printf("  %s -host 192.168.1.10 -duration 5m -verbose\n", os.Args[0])
+	fmt.Printf("  %s -host 192.0.2.10 -duration 5m -verbose\n", os.Args[0])
 	fmt.Println()
 	fmt.Println("  # Monitor now playing and volume events")
-	fmt.Printf("  %s -host 192.168.1.10 -filter nowPlaying,volume\n", os.Args[0])
+	fmt.Printf("  %s -host 192.0.2.10 -filter nowPlaying,volume\n", os.Args[0])
 	fmt.Println()
 	fmt.Println("Event Types:")
 	fmt.Println("  🎵 nowPlaying  - Track changes, playback status")
@@ -571,7 +573,7 @@ type VerboseLogger struct{}
 
 func (v *VerboseLogger) Printf(format string, args ...interface{}) {
 	timestamp := time.Now().Format("15:04:05")
-	fmt.Printf("[%s] [WebSocket] %s\n", timestamp, fmt.Sprintf(format, args...))
+	fmt.Printf("[%s] [WebSocket] %s\n", timestamp, sanitizeLog(fmt.Sprintf(format, args...)))
 }
 
 // SilentLogger provides no-op WebSocket logging

data/.gitignore

@@ -1,4 +1,5 @@
 accounts/
+backend/
 certs/
 default/
 dns/

doc.go

@@ -27,7 +27,7 @@
 //	func main() {
 //		// Create a client for your SoundTouch device
 //		config := &client.Config{
-//			Host: "192.168.1.100",
+//			Host: "192.0.2.100",
 //			Port: 8090,
 //		}
 //		client := client.NewClient(config)
@@ -70,7 +70,7 @@
 //	soundtouch-cli discover devices
 //
 //	# Control a device
-//	soundtouch-cli --host 192.168.1.100 play start
+//	soundtouch-cli --host 192.0.2.100 play start
 //
 // # Supported Features
 //

docker-compose.ci.yml

@@ -16,9 +16,26 @@ services:
       - AMAZON_CLIENT_SECRET=mock-amazon-secret
       - AMAZON_TOKEN_URL=http://amazon-mock:8080/auth/o2/token
       - AMAZON_PROFILE_URL=http://amazon-mock:8080/user/profile
+      - TUNEIN_OPML_URL=http://tunein-mock:8080
+      - TUNEIN_API_URL=http://tunein-mock:8080
+    # Start only once every mock is actually listening (the mocks are `go run`,
+    # so cold compilation can take a while); see depends_on below.
+    depends_on:
+      spotify-mock:
+        condition: service_healthy
+      amazon-mock:
+        condition: service_healthy
+      tunein-mock:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8000/health"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+      start_period: 3s
 
   spotify-mock:
-    image: golang:1.26.3-alpine
+    image: golang:1.26.4-alpine
     container_name: spotify-mock
     working_dir: /app
     volumes:
@@ -28,9 +45,15 @@ services:
       - "8081:8080"
     networks:
       - soundtouch-test-net
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8080/healthz"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+      start_period: 3s
 
   amazon-mock:
-    image: golang:1.26.3-alpine
+    image: golang:1.26.4-alpine
     container_name: amazon-mock
     working_dir: /app
     volumes:
@@ -40,6 +63,30 @@ services:
       - "8082:8080"
     networks:
       - soundtouch-test-net
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8080/healthz"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+      start_period: 3s
+
+  tunein-mock:
+    image: golang:1.26.4-alpine
+    container_name: tunein-mock
+    working_dir: /app
+    volumes:
+      - .:/app
+    command: go run ./cmd/mock-tunein/main.go -port 8080
+    ports:
+      - "8083:8080"
+    networks:
+      - soundtouch-test-net
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8080/healthz"]
+      interval: 3s
+      timeout: 3s
+      retries: 30
+      start_period: 3s
 
 networks:
   soundtouch-test-net:

docker-compose.docs.yml

@@ -0,0 +1,34 @@
+# Local Hugo/Hextra documentation server.
+#
+# Usage:
+#   make dev-docs          # start the live-reload server (http://localhost:1313)
+#   make dev-docs-tidy     # run hugo mod tidy (required on first run, or after
+#                          # changing hugo.toml module imports)
+#   make hugo ARGS="..."   # run any other hugo CLI command, e.g.
+#                          #   make hugo ARGS="version"
+#                          #   make hugo ARGS="new content/blog/my-post.md"
+#
+# The hugomods/hugo:exts image bundles Hugo extended + Go so Hugo modules
+# (Hextra) work without any extra tooling on the host.
+
+services:
+  hugo:
+    image: hugomods/hugo:exts
+    # --source docs/ because docs/ is the Hugo root inside the repo.
+    # --baseURL / overrides the production subpath (/Bose-SoundTouch/) so
+    # absolute links work at http://localhost:1313/ during local development.
+    # The full repo is mounted so enableGitInfo can read git history.
+    command: server --source docs/ --baseURL / --bind 0.0.0.0 --buildDrafts --navigateToChanged
+    ports:
+      - "1313:1313"
+    volumes:
+      - .:/src
+      # Persist the Hugo module cache across runs so 'hugo mod tidy' only
+      # downloads Hextra once.
+      - hugo-mod-cache:/root/.cache/hugo_cache
+    working_dir: /src
+    environment:
+      - HUGO_PARAMS_GITHASH
+
+volumes:
+  hugo-mod-cache:

docs/SUMMARY.md

@@ -1,106 +0,0 @@
-# Table of Contents
-
-* [Introduction](README.md)
-
-## User Guides
-* [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
-* [Self-Hosting AfterTouch](guides/SELF-HOSTING.md)
-* [Connecting Music Services](guides/MUSIC-SERVICES.md)
-* [Migration & Safety Guide](guides/MIGRATION-SAFETY.md)
-* [CLI Reference](guides/CLI-REFERENCE.md)
-* [Backup Tool](../cmd/soundtouch-backup/README.md)
-* [Getting Started](guides/GETTING-STARTED.md)
-* [SoundTouch Service](guides/SOUNDTOUCH-SERVICE.md)
-* [Initial Device Setup](guides/DEVICE-INITIAL-SETUP.md)
-* [Capture Device Pairing Traffic](guides/CAPTURE-DEVICE-PAIRING.md)
-* [Capture Migration Traffic](guides/CAPTURE-MIGRATION-TRAFFIC.md)
-* [Device Setup Flow](DEVICE-SETUP.md)
-* [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md)
-* [HTTPS Setup](guides/HTTPS-SETUP.md)
-* [Deployment](guides/DEPLOYMENT.md)
-* [Raspberry Pi Guide](guides/RASPBERRY-PI.md)
-* [Troubleshooting](guides/TROUBLESHOOTING.md)
-* [IoT Implementation Guide](guides/IOT-IMPLEMENTATION-GUIDE.md)
-* [Migration Guide](guides/MIGRATION-GUIDE.md)
-* [MQTT Integration Design](guides/MQTT-INTEGRATION-DESIGN.md)
-* [Useful Links](#useful-links)
-
-### Useful Links
-* [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
-* [Raspberry Pi Installer](../scripts/raspberry-pi/README.md)
-* [Updating the Service](../scripts/raspberry-pi/README.md#updating-to-a-new-version)
-* [CLI Reference](guides/CLI-REFERENCE.md)
-
-## Technical Reference
-* [API Cookbook](reference/API-COOKBOOK.md)
-* [API Endpoints](reference/API-ENDPOINTS.md)
-* [Spotify Account Addition](reference/spotify-account-addition.md)
-* [Cloud API Emulation](reference/CLOUD-API.md)
-* [System Endpoints](reference/SYSTEM-ENDPOINTS.md)
-* [Speaker Endpoint](reference/SPEAKER-ENDPOINT.md)
-* [WebSocket Events](reference/WEBSOCKET-EVENTS.md)
-* [Device Pairing Flow](reference/DEVICE-PAIRING-FLOW.md)
-* [Discovery](reference/DISCOVERY.md)
-* [Zone Management](reference/ZONE-MANAGEMENT.md)
-* [Preset Management](reference/PRESET-MANAGEMENT.md)
-* [Source Selection](reference/SOURCE-SELECTION.md)
-* [Volume Controls](reference/VOLUME-CONTROLS.md)
-* [RadioBrowser](reference/radio-browser.md)
-* [Bass Controls](reference/BASS-CONTROLS.md)
-* [Key Controls](reference/KEY-CONTROLS.md)
-* [Feature Mapping](reference/FEATURE-MAPPING.md)
-
-## Concepts
-* [Request Recording](REQUEST_RECORDING_CONCEPT.md)
-* [Spotify Priming Strategy](concepts/spotify-priming-strategy.md)
-* [Spotify OAuth](concepts/spotify-oauth.md)
-
-## Analysis & Research
-* [API Coverage Analysis](analysis/API-COVERAGE.md)
-* [Supported URLs](analysis/SUPPORTED-URLS.md)
-* [Upstream URLs](analysis/UPSTREAM-URLS.md)
-* [Anonymization Summary](analysis/ANONYMIZATION-SUMMARY.md)
-* [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md)
-* [Telnet (Port 17000) Migration Method](analysis/TELNET-MIGRATION-METHOD.md)
-* [Telnet Command Reference](analysis/TELNET-COMMAND-REFERENCE.md)
-* [Setup WebSocket Experiment](analysis/SETUP-WEBSOCKET-EXPERIMENT.md)
-* [Factory Reset Protocol](analysis/FACTORY-RESET-PROTOCOL.md)
-* [Wiki API Comparison](analysis/WIKI-COMPARISON.md)
-* [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md)
-* [IoT Configuration Analysis](analysis/IOT-CONFIGURATION-ANALYSIS.md)
-* [Bose Lab Runbook](analysis/BOSE-LAB-RUNBOOK.md)
-* [Missing Routes Spotify](analysis/MISSING-ROUTES-SPOTIFY.md)
-* [Bose App ADB Emulator](analysis/BOSE-APP-ADB-Emulator.md)
-* [Community Tools](analysis/bose-soundtouch-community-tools.md)
-
-## Parity Analysis
-* [Parity Improvements](PARITY-IMPROVEMENTS.md)
-* [Parity SoundCork](PARITY-SOUNDCORK.md)
-* [Parity OpenCloudTouch](PARITY-OPENCLOUDTOUCH.md)
-
-## Appendix (Other Documents)
-* [External Services Abstraction](EXTERNAL-SERVICES-ABSTRACTION.md)
-* [API Navigation Reference](API-NAVIGATION-REFERENCE.md)
-* [Claude Instructions](CLAUDE.md)
-* [Content Selection Implementation](CONTENT-SELECTION-IMPLEMENTATION.md)
-* [Device Customization Setup](DEVICE-CUSTOMIZATION-SETUP.md)
-* [Device Logging](DEVICE-LOGGING.md)
-* [Feature History](FEATURE_HISTORY.md)
-* [Host/Port Parsing](HOST-PORT-PARSING.md)
-* [Manual Network Discovery](MANUAL-NETWORK-DISCOVERY.md)
-* [Navigation Guide](NAVIGATION-GUIDE.md)
-* [Official API Verification](OFFICIAL-API-VERIFICATION.md)
-* [Preset Quickstart](PRESET-QUICKSTART.md)
-* [Project Patterns](PROJECT-PATTERNS.md)
-* [Service Availability Implementation](SERVICE-AVAILABILITY-IMPLEMENTATION.md)
-* [SoundTouch Service Announcement](SOUNDTOUCH-SERVICE-ANNOUNCEMENT.md)
-* [Undocumented Community Features](UNDOCUMENTED-COMMUNITY-FEATURES.md)
-* [Unimplemented Endpoints](UNIMPLEMENTED-ENDPOINTS.md)
-* [Preset Store](preset-store.md)
-* [SCMUDC Enrichment Implementation](SCMUDC-ENRICHMENT-IMPLEMENTATION.md)
-* [Device Lifecycle and Power On Enhancement](device-lifecycle-and-power-on-enhancement.md)
-* [Device Lifecycle Summary](device-lifecycle-summary.md)
-* [Power On Implementation Guide](power-on-implementation-guide.md)
-* [SCMUDC Events Analysis](scmudc-events-analysis.md)
-* [Parity Improvements](PARITY-IMPROVEMENTS.md)
-* [Parity SoundCork](PARITY-SOUNDCORK.md)

docs/_config.yml

@@ -1,11 +0,0 @@
-title: Bose SoundTouch Toolkit
-description: Documentation for controlling and preserving Bose SoundTouch devices
-remote_theme: pages-themes/minimal@v0.2.0
-plugins:
-  - jekyll-remote-theme
-  - jekyll-relative-links
-relative_links:
-  enabled: true
-  collections: true
-include:
-  - SUMMARY.md

docs/_includes/head-custom.html

@@ -0,0 +1,24 @@
+{%- comment -%}
+Render Mermaid diagrams in docs pages.
+
+Markdown ```mermaid fenced blocks are emitted by Kramdown as
+<pre><code class="language-mermaid">…</code></pre>, but Mermaid only
+auto-renders elements with class="mermaid". This snippet rewrites the
+pre/code nodes into div.mermaid before initialising the library.
+
+Loaded as an ES module from the jsDelivr CDN so we don't have to vendor
+the library into the repo. Pinned to a major version for cache stability.
+{%- endcomment -%}
+<script type="module">
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+
+  document.querySelectorAll('pre > code.language-mermaid').forEach((code) => {
+    const div = document.createElement('div');
+    div.className = 'mermaid';
+    div.textContent = code.textContent;
+    code.parentElement.replaceWith(div);
+  });
+
+  mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
+  mermaid.run();
+</script>

docs/analysis/ANONYMIZATION-SUMMARY.md

@@ -1,115 +0,0 @@
-# Data Anonymization Summary
-
-This document summarizes all changes made to anonymize personal and specific data throughout the Bose SoundTouch Go client codebase.
-
-## Overview
-
-All specific IP addresses, device IDs, device names, and other potentially personal information have been replaced with generic, example values to protect privacy while maintaining the functionality and usefulness of the documentation and test examples.
-
-## Changes Made
-
-### IP Addresses
-
-**Original → Anonymized:**
-- `192.168.178.35` → `192.168.1.10`
-- `192.168.178.28` → `192.168.1.10`
-- `192.168.1.100` → `192.168.1.10`
-- `192.168.1.101` → `192.168.1.11`
-- `192.168.1.102` → `192.168.1.12`
-
-### Device IDs
-
-**Original → Anonymized:**
-- `A81B6A536A98` → `ABCD1234EFGH`
-- `1234567890AB` → `ABCD1234EFGH`
-- `1234567890AC` → `ABCD1234EFGH`
-
-### Device Names
-
-**Original → Anonymized:**
-- `Sound Machinechen` → `My SoundTouch Device`
-
-### MAC Addresses
-
-**Original → Anonymized:**
-- `A81B6A536A98` → `AA:BB:CC:DD:EE:FF`
-- `A81B6A849D99` → `AA:BB:CC:DD:EE:FF`
-- `A8:1B:6A:53:6A:98` → `AA:BB:CC:DD:EE:FF`
-- `A8:1B:6A:84:9D:99` → `AA:BB:CC:DD:EE:01`
-
-## Files Modified
-
-### Documentation Files
-- `README.md` - Updated all IP addresses and device examples
-- `Makefile` - Updated example IP addresses in help text
-- `docs/SYSTEM-ENDPOINTS.md` - Anonymized all example data
-- `docs/VOLUME-CONTROLS.md` - Updated device IDs and IP addresses
-- `docs/KEY-CONTROLS.md` - Updated IP addresses
-- `docs/BASS-CONTROLS.md` - Updated device IDs
-- `docs/HOST-PORT-PARSING.md` - Updated IP addresses and device names
-- `docs/STATUS.md` - Updated IP addresses
-
-### Source Code Files
-- `cmd/soundtouch-cli/main.go` - Updated all example IP addresses in help text
-- `cmd/soundtouch-cli/main_test.go` - Updated test IP addresses
-
-### Test Data Files
-- `pkg/client/testdata/info_response.xml` - Updated device ID, name, and network info
-- `pkg/client/testdata/info_response_st20.xml` - Updated device ID and network info
-- `pkg/client/testdata/capabilities_response.xml` - Updated device ID
-- `pkg/client/testdata/name_response.xml` - Updated device name
-- `pkg/client/testdata/networkinfo_response.xml` - Updated device ID and network info
-- `pkg/client/testdata/clockdisplay_response.xml` - Updated device ID
-
-### Test Files
-- `pkg/client/client_test.go` - Updated device IDs, names, and IP addresses
-- `pkg/client/system_test.go` - Updated device IDs and IP addresses
-- `pkg/client/balance_test.go` - Updated device IDs in test responses
-- `pkg/client/bass_test.go` - Updated device IDs in test responses
-- `pkg/models/networkinfo_test.go` - Updated device IDs and network info
-
-## Anonymization Strategy
-
-### IP Addresses
-- Used standard RFC 1918 private IP ranges (192.168.1.x)
-- Maintained realistic network structure (same subnet for related devices)
-- Used sequential numbering (.10, .11, .12) for clarity
-
-### Device IDs
-- Used generic alphanumeric pattern `ABCD1234EFGH`
-- Maintained consistent usage across all files
-- Preserved original length and format
-
-### Device Names
-- Used generic but descriptive names like "My SoundTouch Device"
-- Removed any potentially personal identifiers
-
-### MAC Addresses
-- Used standard placeholder format `AA:BB:CC:DD:EE:FF`
-- Used sequential variants (EE:01) when multiple addresses needed
-- Maintained proper MAC address format
-
-## Verification
-
-After anonymization:
-- ✅ All tests continue to pass
-- ✅ All builds succeed
-- ✅ Documentation remains accurate and useful
-- ✅ No personal data remains in examples
-- ✅ Functionality is preserved
-
-## Benefits
-
-1. **Privacy Protection**: No personal network information exposed
-2. **Professional Examples**: Clean, generic examples suitable for public documentation
-3. **Consistency**: Uniform use of example data across all files
-4. **Maintainability**: Easy to identify example vs. real data
-
-## Standards Used
-
-- **IP Addresses**: RFC 1918 private ranges (192.168.1.x/24)
-- **Device IDs**: Generic alphanumeric placeholders
-- **MAC Addresses**: Standard placeholder format
-- **Device Names**: Generic descriptive names
-
-All changes maintain the original functionality while ensuring no personal or specific network information is exposed in the codebase.

docs/analysis/API-COVERAGE.md

@@ -1,224 +0,0 @@
-# Bose SoundTouch API Coverage Analysis
-
-**Last Updated:** January 2025  
-**API Version:** Official Bose SoundTouch Web API v1.0  
-**Implementation Status:** 100% Official Coverage + Extended Features
-
-## Executive Summary
-
-This Go implementation provides **complete coverage** of the Bose SoundTouch Web API with **100% of official endpoints implemented** (18/19) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware.
-
-### Key Findings
-- ✅ **All essential user functionality implemented**
-- ✅ **Complete zone management implementation** 
-- ✅ **Real-time WebSocket event system**
-- ✅ **Extended features beyond official specification**
-- ✅ **Complete advanced audio controls implementation**
-- ❌ **1 non-functional endpoint** (documented but broken on real devices)
-
----
-
-## Official API v1.0 Endpoint Coverage
-
-### Implemented Endpoints: 20/21 (95%)
-
-| Endpoint | Method | Status | Implementation | Notes |
-|----------|--------|--------|----------------|--------|
-| `/key` | POST | ✅ **Complete** | `SendKey()`, `SendKeyPress()`, `SendKeyRelease()` | Full key simulation with press/release states |
-| `/select` | POST | ✅ **Complete** | `SelectSource()`, `SelectSpotify()`, etc. | Source selection with validation |
-| `/sources` | GET | ✅ **Complete** | `GetSources()` | Available audio sources |
-| `/bassCapabilities` | GET | ✅ **Complete** | `GetBassCapabilities()` | Bass capability detection |
-| `/bass` | GET/POST | ✅ **Complete** | `GetBass()`, `SetBass()`, `SetBassSafe()` | Bass control (-9 to +9) with safety limits |
-| `/getZone` | GET | ✅ **Complete** | `GetZone()`, `GetZoneStatus()`, `GetZoneMembers()` | Multiroom zone information |
-| `/setZone` | POST | ✅ **Complete** | `SetZone()`, `CreateZone()`, `AddToZone()`, `RemoveFromZone()` | Zone configuration and management |
-| `/now_playing` | GET | ✅ **Complete** | `GetNowPlaying()` | Current playback status with full metadata |
-| `/trackInfo` | GET | ❌ **Non-functional** | `GetTrackInfo()` | Documented but times out on real devices |
-| `/volume` | GET/POST | ✅ **Complete** | `GetVolume()`, `SetVolume()`, `SetVolumeSafe()` | Volume and mute control with safety features |
-| `/presets` | GET | ✅ **Complete** | `GetPresets()`, `GetNextAvailablePresetSlot()` | Preset configurations (read-only per API spec) |
-| `/info` | GET | ✅ **Complete** | `GetDeviceInfo()` | Device information and capabilities |
-| `/name` | POST | ✅ **Complete** | `SetName()` | Device name modification |
-| `/capabilities` | GET | ✅ **Complete** | `GetCapabilities()` | Device feature capabilities |
-| `/addZoneSlave` | POST | ✅ **Complete** | `AddZoneSlave()`, `AddZoneSlaveByDeviceID()` | Individual device addition to zone |
-| `/removeZoneSlave` | POST | ✅ **Complete** | `RemoveZoneSlave()`, `RemoveZoneSlaveByDeviceID()` | Individual device removal from zone |
-| `/audiodspcontrols` | GET/POST | ✅ **Complete** | `GetAudioDSPControls()`, `SetAudioDSPControls()`, `SetAudioMode()`, `SetVideoSyncAudioDelay()` | DSP audio modes and video sync delay |
-| `/audioproducttonecontrols` | GET/POST | ✅ **Complete** | `GetAudioProductToneControls()`, `SetAudioProductToneControls()`, `SetAdvancedBass()`, `SetAdvancedTreble()` | Advanced bass/treble controls |
-| `/audioproductlevelcontrols` | GET/POST | ✅ **Complete** | `GetAudioProductLevelControls()`, `SetAudioProductLevelControls()`, `SetFrontCenterSpeakerLevel()`, `SetRearSurroundSpeakersLevel()` | Speaker level controls |
-| `/speaker` | POST | ✅ **Complete** | `PlayTTS()`, `PlayURL()`, `PlayCustom()` | TTS and URL content playback for notifications |
-| `/playNotification` | GET | ✅ **Complete** | `PlayNotificationBeep()` | Simple notification beep sound |
-
-### Non-functional Endpoints: 1/21 (5%)
-
-| Endpoint | Method | Status | Reason | Impact |
-|----------|--------|--------|--------|---------|
-| `/trackInfo` | GET | ❌ **Non-functional** | Times out on real devices (AllegroWebserver timeout) | **None** - Use `/now_playing` instead |
-
-### Official Endpoints Not Supported by API: 1
-
-| Endpoint | Method | Status | Official API Status |
-|----------|--------|--------|-------------------|
-| `/storePreset` | POST | ✅ **IMPLEMENTED** | Found via [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) (official docs marked `/presets` POST as "N/A") |
-| `/removePreset` | POST | ✅ **IMPLEMENTED** | Found via [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) |
-
----
-
-## Extended Features Beyond Official API v1.0
-
-### Additional Endpoints: 5 Extra Features
-
-**Note**: The `/speaker` and `/playNotification` endpoints were discovered via the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) and are now part of the official coverage.
-
-| Endpoint | Method | Status | Notes |
-|----------|--------|--------|--------|
-| `/name` | GET | 🔍 **Extra** | Official API only documents POST, but GET works with real hardware |
-| `/balance` | GET/POST | 🔍 **Extra** | Stereo balance control (-50 to +50) - not in API v1.0 |
-| `/clockTime` | GET/POST | 🔍 **Extra** | Device time management - works with real devices |
-| `/clockDisplay` | GET/POST | 🔍 **Extra** | Clock display settings and brightness |
-| `/networkInfo` | GET | 🔍 **Extra** | Network connectivity information |
-
-### Advanced Implementation Features
-
-| Feature | Status | Description |
-|---------|--------|-------------|
-| **WebSocket Events** | ✅ **Complete** | Real-time device state monitoring (`nowPlayingUpdated`, `volumeUpdated`, etc.) |
-| **Device Discovery** | ✅ **Complete** | UPnP/SSDP + mDNS/Bonjour automatic discovery |
-| **Safety Features** | ✅ **Enhanced** | Volume limiting, bass clamping, input validation |
-| **High-Level Zone API** | ✅ **Superior** | Fluent zone management API replacing low-level slave operations |
-| **Preset Management** | ✅ **Wiki Documented** | Full preset CRUD via `/storePreset` and `/removePreset` endpoints (found via SoundTouch Plus Wiki) |
-| **Content Navigation** | ✅ **Complete** | Browse and search content via `/navigate`, `/searchStation`, `/addStation` (via SoundTouch Plus Wiki) |
-
----
-
-## Implementation Analysis
-
-### Zone Management: Complete Implementation ✅
-
-**Official Low-Level API:**
-```go
-// Individual slave operations (exact official API implementation)
-client.AddZoneSlave("MASTER123", "SLAVE456", "192.168.1.101")
-client.RemoveZoneSlave("MASTER123", "SLAVE456", "192.168.1.101")
-```
-
-**Enhanced High-Level API:**
-```go
-// High-level fluent API (enhanced implementation)
-zone := client.CreateZoneWithIPs("192.168.1.100", []string{"192.168.1.101", "192.168.1.102"})
-client.AddToZone("192.168.1.100", "192.168.1.103")
-client.RemoveFromZone("192.168.1.100", "192.168.1.101")
-client.DissolveZone("192.168.1.100")
-```
-
-**Advantages:**
-- ✅ **Complete official API compliance** - exact implementation of official endpoints
-- ✅ **Enhanced high-level operations** - atomic zone creation/modification
-- ✅ **Validation and error handling** - comprehensive zone state validation
-- ✅ **Flexible usage patterns** - choose low-level or high-level as needed
-- ✅ **Better user experience** - intuitive zone construction and modification
-
-### Safety and Validation Enhancements
-
-**Volume Control:**
-```go
-client.SetVolumeSafe(85)  // Automatically caps at safe maximum
-client.IncreaseVolume(5)  // Controlled incremental changes
-```
-
-**Bass Control:**
-```go
-client.SetBassSafe(15)    // Automatically clamps to valid range (-9 to +9)
-capabilities, _ := client.GetBassCapabilities()
-if capabilities.ValidateLevel(level) { /* ... */ }
-```
-
----
-
-## Missing Functionality Impact Assessment
-
-### High Impact: None ✅
-All essential user functionality is fully implemented.
-
-### Medium Impact: None ✅
-All common use cases are covered.
-
-### Low Impact: 1 Non-functional Feature ❌
-
-#### 1. Non-functional Endpoint
-- **Official**: `/trackInfo`
-- **Impact**: None - identical functionality available via `/now_playing`
-- **Issue**: Times out on real devices despite being documented in API
-- **Workaround**: Use `GetNowPlaying()` method instead
-
----
-
-## Testing Coverage
-
-### Endpoint Testing: 100%
-- ✅ All implemented endpoints have comprehensive unit tests
-- ✅ Real device integration testing completed
-- ✅ Error handling and edge cases covered
-- ✅ WebSocket event system fully tested
-
-### Test Statistics:
-```
-Unit Tests:        200+ test cases
-Integration Tests: Real device validation
-Benchmark Tests:   Performance validation
-Coverage:          >90% code coverage
-```
-
----
-
-## Recommendations
-
-### For Standard Users: ✅ **Complete**
-This implementation provides **everything needed** for standard SoundTouch usage:
-- Media control, volume management, source selection
-- Preset access, device information, real-time updates
-- Multiroom zone management, device discovery
-
-### For Advanced Users: ✅ **Excellent**
-Additional features beyond standard API:
-- Enhanced safety controls, comprehensive event system
-- Extended device information, network management
-- Superior zone management implementation
-
-### For Professional Installations: ⚠️ **Mostly Complete**
-Missing only niche professional features:
-- Advanced DSP audio controls
-- Professional tone/level controls
-- Individual zone slave micro-management
-
-**Recommendation**: For 99% of use cases, this implementation is **complete and superior** to a basic API implementation.
-
----
-
-## Future Considerations
-
-### Potential Additions (Low Priority):
-1. **Extended WebSocket Events** - Additional real-time notifications if discovered
-2. **API Evolution Support** - Monitor for new official API versions beyond v1.0
-
-### API Evolution:
-- Monitor for new official API versions beyond v1.0
-- Test extended features with new device models
-- Consider community feedback for additional functionality
-
----
-
-## Conclusion
-
-This implementation achieves **complete API coverage** with:
-- ✅ **95% functional endpoint implementation** (20/21)
-- ✅ **100% official API endpoint implementation** (21/21)
-- ✅ **100% essential functionality coverage**
-- ✅ **Superior implementations** for complex operations
-- ✅ **Extended features** beyond official specification
-- ✅ **Complete advanced audio controls** for professional devices
-- ✅ **Complete notification system** (TTS, URL playback, beep notifications)
-- ✅ **Comprehensive testing and validation**
-
-The single non-functional endpoint (`/trackInfo`) is **broken on real devices** despite being documented in the official API, but identical functionality is available via `/now_playing`. The implementation **exceeds the official API** in many areas through enhanced safety features, complete zone management, advanced audio controls, and real-time event capabilities.
-
-**Note**: All official API endpoints are implemented. The `/trackInfo` endpoint times out on real devices but is implemented and tested.
-
-**Overall Assessment: Complete** ⭐⭐⭐⭐⭐

docs/archive/PLAN.md

@@ -656,10 +656,10 @@ func main() {
 soundtouch discover
 
 # Device operations
-soundtouch --device 192.168.1.100 info
-soundtouch --device 192.168.1.100 play
-soundtouch --device 192.168.1.100 volume 50
-soundtouch --device 192.168.1.100 preset 1
+soundtouch --device 192.0.2.100 info
+soundtouch --device 192.0.2.100 play
+soundtouch --device 192.0.2.100 volume 50
+soundtouch --device 192.0.2.100 preset 1
 
 # Interactive mode
 soundtouch interactive
@@ -784,4 +784,4 @@ docker compose up  # Mock devices + web app
 - [UPnP Device Architecture](http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf)
 - [Go Embed Directive](https://pkg.go.dev/embed)
 - [Gorilla WebSocket](https://github.com/gorilla/websocket)
-- [PROJECT-PATTERNS.md](../PROJECT-PATTERNS.md) - Detailed pattern documentation
+- [PROJECT-PATTERNS.md](../content/docs/appendix/PROJECT-PATTERNS.md) - Detailed pattern documentation

docs/archive/STATUS.md

@@ -171,7 +171,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - **Notification System**: TTS and URL playback with multi-language support
 - **API Compliance**: Proper press+release key pattern implementation
 - **Safety First**: Volume warnings and limits for user protection
-- **User Experience**: Host:port parsing (e.g., `-host 192.168.1.100:8090`)
+- **User Experience**: Host:port parsing (e.g., `-host 192.0.2.100:8090`)
 - **CLI Enhancement**: Direct flags for common operations and audio control
 - **Discovery Excellence**: Multi-protocol discovery (UPnP + mDNS) with caching
 - **Real Device Testing**: Validated with SoundTouch 10 and SoundTouch 20
@@ -193,7 +193,7 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 - **HTTP Client**: Mock server tests with real response data
 
 ### Integration Tests
-- **Real Devices**: SoundTouch 10 (192.168.1.10) and SoundTouch 20 (192.168.1.11)
+- **Real Devices**: SoundTouch 10 (192.0.2.10) and SoundTouch 20 (192.0.2.11)
 - **All Endpoints**: Validated against actual hardware
 - **Source Selection**: Tested with Spotify, TuneIn, and other available sources
 - **Bass Control**: Tested bass adjustment, validation, and device-specific behavior

docs/archive/technical-specification.md

@@ -22,7 +22,6 @@
 │                    SoundTouch Service                       │
 ├─────────────────────────────────────────────────────────────┤
 │  HTTP Router & Middleware                                   │
-│  ├── Mirror Middleware (Enhanced)                           │
 │  ├── Recorder Middleware                                    │
 │  ├── Disparity Detection                                    │
 │  └── Health Check Middleware                               │
@@ -35,12 +34,11 @@
 ├─────────────────────────────────────────────────────────────┤
 │  Data Layer                                                 │
 │  ├── Enhanced DataStore      ├── Event Store              │
-│  ├── Mirror Cache           ├── Metrics Store             │
 │  └── Configuration Store    └── Session Store             │
 ├─────────────────────────────────────────────────────────────┤
 │  External Integrations                                      │
-│  ├── Bose Services (Mirror)  ├── Device Discovery         │
-│  ├── BMX/TuneIn Services    └── SSH/Setup Manager         │
+│  ├── Device Discovery         ├── BMX/TuneIn Services      │
+│  └── SSH/Setup Manager                                   │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -69,10 +67,6 @@ pkg/service/
 │   ├── processor.go
 │   ├── queue.go
 │   └── storage.go
-├── mirror/               # Enhanced mirroring (extends existing)
-│   ├── disparity.go
-│   ├── analyzer.go
-│   └── logger.go
 ├── health/               # System monitoring
 │   ├── monitor.go
 │   ├── metrics.go
@@ -115,20 +109,17 @@ type MigrationInfo struct {
     CompletedAt      *time.Time `json:"completed_at,omitempty"`
     DevicesMigrated  int       `json:"devices_migrated"`
     DevicesPending   int       `json:"devices_pending"`
-    MirrorActive     bool      `json:"mirror_active"`
     Strategy         string    `json:"strategy"`
     RollbackData     string    `json:"rollback_data,omitempty"`
 }
 
 type DataSourceConfig struct {
     Local       bool   `json:"local"`
-    BoseMirror  bool   `json:"bose_mirror"`
     Primary     string `json:"primary"` // "local" or "bose"
 }
 
 type AccountSettings struct {
     AutoMigration    bool     `json:"auto_migration"`
-    MirrorEndpoints  []string `json:"mirror_endpoints"`
     RetentionDays    int      `json:"retention_days"`
 }
 ```
@@ -235,7 +226,6 @@ type EventSource string
 const (
     EventSourceWebSocket  EventSource = "websocket"
     EventSourceDiscovery  EventSource = "discovery"
-    EventSourceMirror     EventSource = "mirror"
     EventSourceSystem     EventSource = "system"
     EventSourceAPI        EventSource = "api"
     EventSourceUser       EventSource = "user"
@@ -336,12 +326,10 @@ Response: 200 OK
   "migration_info": {
     "started_at": "2024-01-18T09:00:00Z",
     "devices_migrated": 1,
-    "devices_pending": 1,
-    "mirror_active": true
+    "devices_pending": 1
   },
   "data_sources": {
     "local": true,
-    "bose_mirror": true,
     "primary": "bose"
   }
 }
@@ -368,14 +356,14 @@ POST /api/v1/accounts/{account_id}/devices
 Content-Type: application/json
 
 {
-  "device_id": "A81B6A536A98",
+  "device_id": "AABBCCDDEEFF",
   "name": "Living Room Speaker",
   "registration_type": "fresh"
 }
 
 Response: 201 Created
 {
-  "device_id": "A81B6A536A98",
+  "device_id": "AABBCCDDEEFF",
   "account_id": "acc_12345",
   "state": "registering",
   "created_at": "2024-01-20T10:00:00Z"
@@ -388,7 +376,7 @@ GET /api/v1/accounts/{account_id}/devices/{device_id}/state
 
 Response: 200 OK
 {
-  "device_id": "A81B6A536A98",
+  "device_id": "AABBCCDDEEFF",
   "account_id": "acc_12345",
   "state": "active",
   "metadata": {
@@ -474,8 +462,7 @@ Response: 200 OK
   "services": {
     "account_manager": "healthy",
     "lifecycle_manager": "healthy",
-    "event_processor": "healthy",
-    "mirror_service": "warning"
+    "event_processor": "healthy"
   },
   "statistics": {
     "total_accounts": 5,
@@ -534,18 +521,15 @@ Response: 200 OK
     "started_at": "2024-01-18T09:00:00Z",
     "devices_migrated": 1,
     "devices_pending": 1,
-    "mirror_active": true,
     "strategy": "gradual"
   },
   "bose_account_id": "bose-original-id",
   "data_sources": {
     "local": true,
-    "bose_mirror": true,
     "primary": "bose"
   },
   "settings": {
     "auto_migration": false,
-    "mirror_endpoints": ["/v1/presets", "/v1/recents"],
     "retention_days": 30
   }
 }
@@ -555,7 +539,7 @@ Response: 200 OK
 ```json
 {
   "version": "1.0",
-  "device_id": "A81B6A536A98",
+  "device_id": "AABBCCDDEEFF",
   "account_id": "acc_12345",
   "state": "active",
   "created_at": "2024-01-20T10:00:00Z",
@@ -568,7 +552,7 @@ Response: 200 OK
       "reason": "mdns_discovery",
       "source": "discovery",
       "context": {
-        "ip_address": "192.168.1.100",
+        "ip_address": "192.0.2.100",
         "discovery_method": "mdns"
       }
     },
@@ -585,15 +569,15 @@ Response: 200 OK
     "type": "SoundTouch 30",
     "serial_number": "I6332527703739342000020",
     "firmware_version": "4.8.1.25341.2677643.1597353330",
-    "mac_address": "A8:1B:6A:53:6A:98",
-    "ip_address": "192.168.1.100",
+    "mac_address": "AA:BB:CC:DD:EE:FF",
+    "ip_address": "192.0.2.100",
     "last_seen": "2024-01-20T15:30:00Z",
     "is_legacy_id": false,
     "capabilities": ["multiroom", "bluetooth", "aux"]
   },
   "data_sources": {
     "presets": "local",
-    "recents": "mirror_primary",
+    "recents": "local",
     "sources": "local"
   },
   "migration": {
@@ -615,14 +599,13 @@ Response: 200 OK
 
 ### Event Log Format (events.log)
 ```
-# SoundTouch Service Event Log - Device A81B6A536A98
+# SoundTouch Service Event Log - Device AABBCCDDEEFF
 # Format: TIMESTAMP|EVENT_ID|EVENT_TYPE|SOURCE|DATA_JSON
 # Version: 1.0
 
 2024-01-20T15:30:00.123Z|evt_12345|now_playing|websocket|{"source":"SPOTIFY","track":"Song Name","artist":"Artist Name","album":"Album Name"}
 2024-01-20T15:30:30.456Z|evt_12346|volume_changed|websocket|{"volume":45,"muted":false,"previous_volume":40}
 2024-01-20T15:31:00.789Z|evt_12347|preset_selected|websocket|{"preset":1,"source":"SPOTIFY","location":"spotify:track:123abc"}
-2024-01-20T15:31:15.012Z|evt_12348|disparity_detected|mirror|{"endpoint":"/v1/presets","local_hash":"abc123","upstream_hash":"def456","severity":"medium"}
 2024-01-20T15:32:00.345Z|evt_12349|health_check|system|{"response_time":42,"status":"healthy","connectivity":"online"}
 ```
 
@@ -632,8 +615,8 @@ Response: 200 OK
 # Format: TIMESTAMP|DISPARITY_ID|DEVICE_ID|ACCOUNT_ID|ENDPOINT|TYPE|SEVERITY|DETAILS_JSON
 # Version: 1.0
 
-2024-01-20T15:31:15.012Z|disp_12345|A81B6A536A98|acc_12345|/v1/presets|count_mismatch|medium|{"field_path":"preset_count","local_value":5,"upstream_value":4,"description":"Local has one additional preset"}
-2024-01-20T15:32:45.678Z|disp_12346|A81B6A536A98|acc_12345|/v1/recents|timestamp_format|low|{"field_path":"recent[0].utc_time","local_value":"2024-01-20T15:30:00Z","upstream_value":"1705761000","description":"Timestamp format difference"}
+2024-01-20T15:31:15.012Z|disp_12345|AABBCCDDEEFF|acc_12345|/v1/presets|count_mismatch|medium|{"field_path":"preset_count","local_value":5,"upstream_value":4,"description":"Local has one additional preset"}
+2024-01-20T15:32:45.678Z|disp_12346|AABBCCDDEEFF|acc_12345|/v1/recents|timestamp_format|low|{"field_path":"recent[0].utc_time","local_value":"2024-01-20T15:30:00Z","upstream_value":"1705761000","description":"Timestamp format difference"}
 2024-01-20T15:35:20.901Z|disp_12347|B92C7B647B09|acc_12345|/v1/account/full|structure_diff|high|{"field_path":"device[1].ip_address","local_value":"present","upstream_value":"missing","description":"IP address field missing in upstream response"}
 ```
 
@@ -852,7 +835,6 @@ go test -bench=. ./...
 
 ### Response Time Targets
 - Local API requests: < 100ms (95th percentile)
-- Mirror requests: < 200ms overhead (asynchronous)
 - Discovery time: < 5s for network scan
 
 ### Resource Constraints
@@ -925,12 +907,12 @@ type ServiceError struct {
 {
   "error": {
     "code": "DEVICE_NOT_FOUND",
-    "message": "Device with ID 'A81B6A536A98' not found in account 'acc_12345'",
+    "message": "Device with ID 'AABBCCDDEEFF' not found in account 'acc_12345'",
     "category": "validation",
     "timestamp": "2024-01-20T15:30:00Z",
     "context": {
       "account_id": "acc_12345",
-      "device_id": "A81B6A536A98",
+      "device_id": "AABBCCDDEEFF",
       "request_id": "req_67890"
     },
     "retryable": false,

docs/archive/upstream-service-simulation-overview.md

@@ -7,7 +7,7 @@ This document serves as the entry point for understanding the comprehensive plan
 ## Project Objectives
 
 ### Primary Goal
-Create a robust, local replacement for Bose's upstream services that can seamlessly handle the transition from cloud-dependent to fully autonomous operation while maintaining and improving upon the existing functionality.
+Create a robust replacement for Bose's upstream services that can seamlessly handle the transition from cloud-dependent to fully autonomous operation while maintaining and improving upon the existing functionality.
 
 ### Key Outcomes
 - **Zero-downtime transition** from Bose services to local management
@@ -21,7 +21,7 @@ Create a robust, local replacement for Bose's upstream services that can seamles
 ### Current State
 The existing SoundTouch service provides:
 - BMX service for TuneIn integration
-- Marge service for account and device management  
+- Marge service for account and device management
 - Basic mirroring of upstream Bose endpoints
 - File-based persistence for device data
 - Migration support for device directory structures
@@ -42,7 +42,7 @@ The enhanced system will add:
 - **Mirror-Enhanced Setup**: Use upstream data to enrich account creation
 - **Passive Data Collection**: Record account information during normal operations
 
-### Case 1a: Fresh Device Registration  
+### Case 1a: Fresh Device Registration
 - **Factory Reset Support**: Handle devices with no prior Bose association
 - **Default Configuration**: Initialize devices with sensible presets and sources
 - **Local-First Setup**: Complete registration without upstream dependencies
@@ -100,7 +100,7 @@ data/
 - Basic API endpoints with comprehensive testing
 - Integration with existing datastore patterns
 
-### Phase 2: Device Lifecycle (2-3 weeks) - Build on Existing Systems  
+### Phase 2: Device Lifecycle (2-3 weeks) - Build on Existing Systems
 - Event processing using existing WebSocket system
 - Lifecycle integration with current discovery and migration
 - Enhanced logging building on existing parity detection
@@ -178,4 +178,4 @@ This concept is detailed across several documents:
 3. **Resource Planning**: Allocate development resources for the three-phase implementation
 4. **Community Engagement**: Share plans with the community for feedback and contributions
 
-This enhanced state management system represents a significant evolution of the SoundTouch service, transforming it from a basic cloud replacement into a comprehensive, future-proof device management platform that can serve users well beyond the Bose service shutdown timeline.
+This enhanced state management system represents a significant evolution of the SoundTouch service, transforming it from a basic replacement into a comprehensive, future-proof device management platform that can serve users well beyond the Bose service shutdown timeline.

docs/archive/upstream-service-simulation.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This document outlines the concept for simulating and replacing upstream Bose services with enhanced state management capabilities. The goal is to create a comprehensive local replacement that can handle device lifecycles, account management, and state synchronization while maintaining compatibility with existing SoundTouch devices.
+This document outlines the concept for simulating and replacing upstream Bose services with enhanced state management capabilities. The goal is to create a comprehensive replacement that can handle device lifecycles, account management, and state synchronization while maintaining compatibility with existing SoundTouch devices.
 
 ## Use Cases
 
@@ -95,13 +95,11 @@ data/
   "migration_status": {
     "started_at": "2024-01-18T09:00:00Z",
     "devices_migrated": 1,
-    "devices_pending": 2,
-    "mirror_active": true
+    "devices_pending": 2
   },
   "bose_account_id": "bose-original-id",
   "data_sources": {
     "local": true,
-    "bose_mirror": true,
     "primary": "bose"
   }
 }
@@ -111,7 +109,7 @@ data/
 
 ```json
 {
-  "device_id": "A81B6A536A98",
+  "device_id": "AABBCCDDEEFF",
   "account_id": "account-12345",
   "state": "active",
   "created_at": "2024-01-15T10:30:00Z",
@@ -137,14 +135,14 @@ data/
     "type": "SoundTouch 30",
     "serial_number": "I6332527703739342000020",
     "firmware_version": "4.8.1.25341.2677643.1597353330",
-    "mac_address": "A8:1B:6A:53:6A:98",
-    "ip_address": "192.168.1.100",
+    "mac_address": "AA:BB:CC:DD:EE:FF",
+    "ip_address": "192.0.2.100",
     "last_seen": "2024-01-20T16:20:00Z",
     "is_legacy_id": false
   },
   "data_sources": {
     "presets": "local",
-    "recents": "mirror_primary", 
+    "recents": "local",
     "sources": "local"
   },
   "migration": {
@@ -159,14 +157,13 @@ data/
 ### Event Log Format
 
 ```
-# Device Events Log - A81B6A536A98
+# Device Events Log - AABBCCDDEEFF
 # Format: TIMESTAMP|EVENT_TYPE|SOURCE|DATA
 
 2024-01-20T16:15:00Z|now_playing|websocket|{"source":"SPOTIFY","track":"Song Name","artist":"Artist Name"}
 2024-01-20T16:15:30Z|volume_changed|websocket|{"volume":45,"muted":false}
 2024-01-20T16:16:00Z|preset_selected|websocket|{"preset":1,"source":"SPOTIFY","location":"spotify:track:123"}
-2024-01-20T16:18:00Z|disparity_detected|mirror|{"endpoint":"/v1/account/full","local_hash":"abc123","upstream_hash":"def456"}
-2024-01-20T16:20:00Z|device_online|discovery|{"ip":"192.168.1.100","method":"mdns"}
+2024-01-20T16:20:00Z|device_online|discovery|{"ip":"192.0.2.100","method":"mdns"}
 ```
 
 ### Disparity Log Format
@@ -175,9 +172,9 @@ data/
 # Parity Analysis Log
 # Format: TIMESTAMP|ENDPOINT|DEVICE|ACCOUNT|DISPARITY_TYPE|DETAILS
 
-2024-01-20T16:18:00Z|/v1/account/full|A81B6A536A98|account-12345|content_mismatch|preset_count:local=5,upstream=4
-2024-01-20T16:19:15Z|/v1/presets|A81B6A536A98|account-12345|xml_structure|missing_container_art_in_local
-2024-01-20T16:20:30Z|/v1/recents|A81B6A536A98|account-12345|timestamp_format|local=RFC3339,upstream=custom
+2024-01-20T16:18:00Z|/v1/account/full|AABBCCDDEEFF|account-12345|content_mismatch|preset_count:local=5,upstream=4
+2024-01-20T16:19:15Z|/v1/presets|AABBCCDDEEFF|account-12345|xml_structure|missing_container_art_in_local
+2024-01-20T16:20:30Z|/v1/recents|AABBCCDDEEFF|account-12345|timestamp_format|local=RFC3339,upstream=custom
 ```
 
 ## Implementation Strategy
@@ -268,7 +265,7 @@ POST /api/v1/accounts/{account-id}/devices
 Content-Type: application/json
 
 {
-  "device_id": "A81B6A536A98",
+  "device_id": "AABBCCDDEEFF",
   "name": "Living Room Speaker",
   "registration_type": "fresh"
 }
@@ -334,7 +331,7 @@ GET /api/v1/accounts/{account-id}/export
 ### Quality Assurance
 
 - Complete test coverage for all new functionality
-- Comprehensive linting with `golangci-lint run --fix` 
+- Comprehensive linting with `golangci-lint run --fix`
 - Full test suite execution `go test ./...` for each milestone
 - Integration tests with existing functionality
 
@@ -390,4 +387,4 @@ Future improvements should maintain the simplicity-first approach:
    - Simple reporting mechanisms
    - Clear documentation for community contributions
 
-This concept provides a solid, maintainable foundation for replacing Bose's upstream services. The emphasis on simplicity, existing system reuse, and comprehensive testing ensures reliable functionality while maintaining the debugging capabilities needed for small hardware deployments.
+This concept provides a solid, maintainable foundation for replacing Bose's upstream services. The emphasis on simplicity, existing system reuse, and comprehensive testing ensures reliable functionality while maintaining the debugging capabilities needed for small hardware deployments.

docs/assets/css/custom.css

@@ -0,0 +1,46 @@
+/* Font paths use ../../fonts/ (two levels up) so the URL resolves correctly
+   regardless of where the CSS is served from:
+   - dev:        /css/custom.css          → ../../fonts/ → /fonts/
+   - production: /css/compiled/main.css   → ../../fonts/ → /fonts/
+   - GH Pages:   /Bose-SoundTouch/css/compiled/main.css
+                                          → ../../fonts/ → /Bose-SoundTouch/fonts/ */
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-regular.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: italic;
+  font-weight: 400;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-italic.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-700.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: italic;
+  font-weight: 700;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-700italic.woff2') format('woff2');
+}
+
+:root {
+  --hx-default-font-family: "Noto Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+.content {
+  font-family: var(--hx-default-font-family);
+}

docs/content/_index.md

@@ -0,0 +1,65 @@
+---
+title: AfterTouch
+layout: hextra-home
+---
+
+{{< hextra/hero-badge >}}
+  <div class="hx-w-2 hx-h-2 hx-rounded-full hx-bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+<div class="hx-mt-6 hx-mb-6">
+{{< hextra/hero-headline >}}
+  Keep Your Bose SoundTouch&nbsp;Speakers Alive
+{{< /hextra/hero-headline >}}
+</div>
+
+<div class="hx-mb-12">
+{{< hextra/hero-subtitle >}}
+  Bose shut down SoundTouch cloud services on May 6, 2026.&nbsp;<br class="sm:hx-block hx-hidden" />AfterTouch replaces the cloud — presets, music browsing, stereo pairing, all restored.
+{{< /hextra/hero-subtitle >}}
+</div>
+
+<div class="hx-mb-6">
+{{< hextra/hero-button text="Get Started" link="docs/guides/MIGRATION-GUIDE" >}}
+{{< hextra/hero-button text="Survival Guide" link="docs/guides/SURVIVAL-GUIDE" style="outline" >}}
+</div>
+
+<div class="hx-mt-6">
+{{< hextra/feature-grid >}}
+  {{< hextra/feature-card
+    title="Presets Restored"
+    subtitle="Preset buttons, long-press assignment, and recently-played sync — fully working."
+    icon="star"
+  >}}
+  {{< hextra/feature-card
+    title="Music Browsing"
+    subtitle="TuneIn, Internet Radio, RadioBrowser, and Spotify via soundtouch-web and soundtouch-cli."
+    icon="speakerphone"
+  >}}
+  {{< hextra/feature-card
+    title="Stereo Pairing"
+    subtitle="SoundTouch 10 stereo pairing via soundtouch-cli, no Bose cloud required."
+    icon="adjustments"
+  >}}
+  {{< hextra/feature-card
+    title="Three Deployment Options"
+    subtitle="Run on a Raspberry Pi, a VPS, or directly on the speaker itself."
+    icon="server"
+    link="docs/guides/DEPLOYMENT-OVERVIEW"
+  >}}
+  {{< hextra/feature-card
+    title="CLI Control"
+    subtitle="soundtouch-cli for scripting, home automation, and direct device control."
+    icon="terminal"
+    link="docs/guides/CLI-REFERENCE"
+  >}}
+  {{< hextra/feature-card
+    title="Open Source"
+    subtitle="MIT licensed. Not affiliated with Bose Corporation."
+    icon="shield-check"
+    link="https://github.com/gesellix/Bose-SoundTouch"
+  >}}
+{{< /hextra/feature-grid >}}
+</div>

docs/content/blog/2026-05-welcome.md

@@ -0,0 +1,120 @@
+---
+title: "Welcome to AfterTouch: Your SoundTouch Speakers, Still Alive"
+date: 2026-05-24
+description: "Bose shut down SoundTouch cloud services in May 2026. AfterTouch replaces everything your speakers relied on — migration, radio, Spotify, presets, and more."
+tags:
+  - migration
+  - web
+  - spotify
+  - cli
+sidebar:
+  exclude: true
+---
+
+On May 6, 2026, Bose shut down the SoundTouch cloud services that millions of speakers
+depended on for account sync, presets, internet radio, and streaming. Speakers kept
+working locally, but remote features stopped and first-time setup became impossible.
+
+AfterTouch was built to change that. It is a self-hosted replacement for the Bose
+cloud infrastructure — a drop-in local service that your speakers talk to instead of
+`streaming.bose.com`. This post covers what works today and how to get started.
+
+## What works right now
+
+### Migration and first-time setup
+
+If your speaker was registered with Bose before the shutdown, AfterTouch can **migrate
+your existing account and presets** in a single step — no reconfiguration on the
+speaker side. If you are setting up a factory-reset or brand-new speaker, AfterTouch
+handles that path too, guiding you through Wi-Fi pairing and account creation locally.
+See the [Migration Guide](../docs/guides/MIGRATION-GUIDE.md) for step-by-step instructions.
+
+### Internet radio — TuneIn and RadioBrowser
+
+Both **TuneIn** and **RadioBrowser** are fully supported for browsing and playback.
+Navigate categories and search for stations exactly as you did with the original Bose
+app. TuneIn delivers the same station catalogue; RadioBrowser provides an open,
+community-maintained alternative.
+
+### Spotify
+
+**Spotify** works via both OAuth (account linking) and Spotify Connect (the ZeroConf
+"connect to device" flow from the Spotify app). Once linked, playback and device
+selection behave the same as before.
+
+### Presets
+
+Your six preset buttons work. AfterTouch stores preset bindings locally and serves them
+back to the speaker on request. You can also **save new presets** — via the API,
+via `soundtouch-cli`, or through the soundtouch-web UI.
+
+### ST-10 stereo pairing
+
+**SoundTouch 10 stereo pairs** (and other ST pairing configurations) are supported
+end-to-end: creation, management, and playback routing all go through AfterTouch.
+
+### soundtouch-web — browser UI
+
+**soundtouch-web** is an early-stage but functional browser UI bundled with AfterTouch.
+It gives you:
+
+- TuneIn and RadioBrowser browsing and playback
+- Speaker management and device discovery
+- Recent tracks panel
+- Multi-room zone management
+
+It runs as part of the AfterTouch service — no separate install needed.
+
+![soundtouch-web UI showing Spotify playback, presets, sources, and zone management](/images/blog/soundtouch-web-ui.png)
+
+### Automation with soundtouch-cli
+
+The **`soundtouch-cli`** command-line tool covers every speaker control: play, pause,
+volume, source selection, preset recall, group management, migration, and more.
+It is well-suited for home-automation scripts, cron jobs, and shell one-liners.
+
+## Three ways to install
+
+AfterTouch runs on any machine your speakers can reach:
+
+1. **On the speaker itself** — install directly on supported SoundTouch hardware via
+   the on-device installer. The speaker hosts its own replacement cloud, with no
+   additional hardware required.
+
+2. **On a local network host** — run AfterTouch on any machine on your LAN. A
+   **Raspberry Pi Zero 2W** handles the load without breaking a sweat, making this
+   path remarkably low-cost and low-power.
+
+3. **On a cloud or VPS host** — deploy to a remote server for access outside your
+   home network. AfterTouch handles TLS certificate generation and DNS configuration
+   for this scenario.
+
+All three paths are documented in the [Deployment Overview](../docs/guides/DEPLOYMENT-OVERVIEW.md).
+
+## Current release
+
+**v0.93.1** — released May 24, 2026
+
+## Community
+
+AfterTouch would not be where it is without the people who opened issues, tested
+pre-release builds, reported edge cases, and contributed code. A significant share of
+the fixes and features shipped in the lead-up to the cloud shutdown were driven by
+real-world feedback from the community — from migration quirks to stereo-pair
+specifics to Spotify Connect timing issues. Thank you to everyone who helped.
+
+If you run into something or have an idea, the
+[GitHub issue tracker](https://github.com/gesellix/Bose-SoundTouch/issues) and
+[Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) are the
+right places to start.
+
+## What's next
+
+The soundtouch-web UI will gain richer preset management — browsing, editing, and
+reordering presets directly from the browser. Longer term, merging
+`soundtouch-service` and `soundtouch-web` into a single binary is on the table,
+which would simplify deployment to a single process with no extra flags.
+
+This blog will be updated monthly — or whenever something significant ships.
+Subscribe to the [GitHub releases](https://github.com/gesellix/Bose-SoundTouch/releases)
+for individual version notes.

docs/content/blog/_index.md

@@ -0,0 +1,5 @@
+---
+title: News & Updates
+---
+
+Project updates, release notes, and development notes for AfterTouch — the local replacement for the Bose SoundTouch cloud.

docs/content/docs/_index.md

@@ -1,3 +1,9 @@
+---
+title: Introduction
+sidebar:
+  open: true
+---
+
 # Bose SoundTouch Toolkit Documentation
 
 Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive toolkit helps you keep your Bose SoundTouch speakers functional even after the Bose Cloud shutdown in May 2026, with enhanced local management and monitoring capabilities.
@@ -10,7 +16,7 @@ Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive
 
 ### For Existing Users
 - **[Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)** - Prepare for the May 2026 shutdown
-- **[Backup Tool](../cmd/soundtouch-backup/README.md)** - Back up your cloud account and speaker data before shutdown
+- **[Backup Tool](https://github.com/gesellix/Bose-SoundTouch/blob/main/cmd/soundtouch-backup/README.md)** - Back up your cloud account and speaker data before shutdown
 - **[SoundTouch Service Guide](guides/SOUNDTOUCH-SERVICE.md)** - Advanced service configuration
 
 ## 📋 Essential Documentation
@@ -41,7 +47,7 @@ The documentation is organized into three main categories:
 ### Advanced Features
 - [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md) - Device identification
 - [CLI Reference](guides/CLI-REFERENCE.md) - Command-line tools
-- [Backup Tool](../cmd/soundtouch-backup/README.md) - Cloud account and speaker data backup
+- [Backup Tool](https://github.com/gesellix/Bose-SoundTouch/blob/main/cmd/soundtouch-backup/README.md) - Cloud account and speaker data backup
 - [IoT Implementation Guide](guides/IOT-IMPLEMENTATION-GUIDE.md) - IoT integrations
 - [MQTT Integration Design](guides/MQTT-INTEGRATION-DESIGN.md) - MQTT setup
 
@@ -61,19 +67,18 @@ The documentation is organized into three main categories:
 - [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md) - Configuration summaries
 
 ### Device Lifecycle & Network Independence
-- **[Device Lifecycle and /power_on Enhancement](device-lifecycle-and-power-on-enhancement.md)** - Complete analysis of device registration and network independence improvements
-- [/power_on Implementation Guide](power-on-implementation-guide.md) - Technical implementation details for enhanced device management
+- **[Device Lifecycle and /power_on Enhancement](appendix/device-lifecycle-and-power-on-enhancement.md)** - Complete analysis of device registration and network independence improvements
+- [/power_on Implementation Guide](appendix/power-on-implementation-guide.md) - Technical implementation details for enhanced device management
 
 ## 🏗 Concept Documentation
 
-### Enhanced Service Architecture
-- **[Concept Overview](concepts/README.md)** - High-level architecture vision
-- [Upstream Service Simulation](concepts/upstream-service-simulation.md) - Complete concept design
-- [Implementation Plan](concepts/implementation-plan.md) - Development roadmap
-- [Technical Specification](concepts/technical-specification.md) - Detailed specifications
+- [Spotify Overview](concepts/spotify-overview.md) — mental model, Spotify Connect vs OAuth-intercept, DNS rewrite gotcha
+- [Spotify OAuth](concepts/spotify-oauth.md) — flows and management endpoints
+- [Amazon Music OAuth](concepts/amazon-music-oauth.md) — companion to Spotify OAuth; same protocol shape, different scopes
+- [Encrypted Export](concepts/ENCRYPTED-EXPORT.md) — `.age`-encrypted diagnostic bundles
+- [Request Recording](appendix/REQUEST_RECORDING_CONCEPT.md) — how the proxy captures live device traffic for parity testing
 
-### Development Planning
-- [Implementation Roadmap](concepts/implementation-roadmap.md) - Project phases and milestones
+Older planning artefacts ("Enhanced State Management System", "Upstream Service Simulation") live under [docs/archive/](../../archive/) — kept for the record, no longer current.
 
 ## 💡 Quick Reference
 
@@ -89,4 +94,4 @@ The documentation is organized into three main categories:
 - **Documentation**: Check troubleshooting guides first
 - **Community**: Share experiences and help others
 
-For a complete list of all documents, see the [Summary](SUMMARY.md).
+For a complete list of all documents, browse the sections in the sidebar.

docs/content/docs/analysis/ANONYMIZATION-SUMMARY.md

@@ -0,0 +1,79 @@
+---
+title: "Placeholder values for examples"
+---
+This repo is public. Documentation, READMEs, example configs, and test
+fixtures must never carry real LAN IPs, real device MACs, real Bose
+account IDs, or personal device names from any maintainer or
+contributor.
+
+This file is the **canonical mapping table** for the placeholders we
+use across the codebase. Use these values in new examples and tests.
+
+## Placeholder mapping
+
+| Concept                | Placeholder                                                            |
+|------------------------|------------------------------------------------------------------------|
+| Example IP (primary)   | `192.0.2.10`                                                           |
+| Example IP (secondary) | `192.0.2.11`                                                           |
+| Example IP (third)     | `192.0.2.12`                                                           |
+| Network / CIDR         | `192.0.2.0/24`                                                         |
+| External / non-LAN IP  | `198.51.100.10` or `203.0.113.10`                                      |
+| Gateway IP             | `192.0.2.1`                                                            |
+| Device MAC (primary)   | `AA:BB:CC:DD:EE:FF` (no separator: `AABBCCDDEEFF`)                     |
+| Device MAC (secondary) | `AA:BB:CC:DD:EE:01` (no separator: `AABBCCDDEE01`)                     |
+| Device ID (some XML)   | `ABCD1234EFGH` — legacy placeholder still in some fixtures             |
+| Device display name    | `Living Room SoundTouch` / `Kitchen SoundTouch` / `Bedroom SoundTouch` |
+| Bose account ID        | `1000001` / `1000002`                                                  |
+
+`192.0.2.0/24`, `198.51.100.0/24`, and `203.0.113.0/24` are reserved
+by [RFC 5737](https://www.rfc-editor.org/rfc/rfc5737) exclusively for
+documentation. They won't ever route on a real network, so readers
+know at a glance that they're placeholders and not addresses they
+need to think about.
+
+`AA:BB:CC:DD:EE:FF` is the conventional "locally administered" MAC
+placeholder used in many vendor docs.
+
+`1000001` / `1000002` are well outside the range of real Bose customer
+account IDs (which are typically 6–7 digits with no leading 1 0 0…
+pattern) but stay numeric for parsers that expect integer-looking IDs.
+
+## Why we don't use 192.168.1.x
+
+An earlier anonymisation pass used `192.168.1.x` as its target. That
+range is RFC-1918 private space — perfectly valid on real networks,
+which means a reader can't tell whether `192.168.1.10` is a
+placeholder or a documented LAN address. RFC-5737 ranges fix that:
+because they're reserved for documentation only, any reader knows on
+sight that they don't represent a real device.
+
+The `.md` / `.txt` portion of the `192.168.1.*` → `192.0.2.x` sweep
+is complete. Test files (`.go` / `.xml` / `.http`) still carry the
+old placeholder pending Phase 2 in the audit at
+`_/RFC-5737-cleanup/assessment.md`.
+
+## How to audit before committing
+
+When you add or edit examples that contain IP addresses, MACs, account
+IDs, or device names, mentally answer: "would I be comfortable
+publishing this on a postcard?" If not, swap in a placeholder from
+the table above.
+
+Some patterns flag clearly-non-placeholder values:
+
+```sh
+# Any IPv4 not in a documentation range or the 192.168.1.x default:
+git ls-files | xargs grep -hoE "[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+" 2>/dev/null \
+  | grep -vE "^(192\.0\.2\.|198\.51\.100\.|203\.0\.113\.|0\.0\.0\.0|127\.0\.0\.1|255\.255\.255\.255|192\.168\.1\.[0-9])" \
+  | sort -u
+
+# Any colon-separated MAC that doesn't start with AA:BB:CC:DD:EE:
+git ls-files | xargs grep -hoE "[0-9A-F]{2}(:[0-9A-F]{2}){5}" 2>/dev/null \
+  | grep -vE "^AA:BB:CC:DD:EE:" \
+  | sort -u
+```
+
+If real values slip into a commit, treat it as a sanitisation task:
+revert or fix, then audit nearby files for sibling leaks. Personal
+device names and Bose account IDs don't have a regex-friendly shape —
+catch those at review time.

docs/content/docs/analysis/API-COVERAGE.md

@@ -0,0 +1,225 @@
+---
+title: "Bose SoundTouch API Coverage Analysis"
+---
+**Last Updated:** June 2026 (reconciled against `pkg/client`)
+**API Version:** Official Bose SoundTouch Web API v1.0
+**Implementation Status:** Official coverage 20/21 + extended features
+
+## Executive Summary
+
+This Go implementation provides near-complete coverage of the Bose SoundTouch Web API with **20 of 21 official endpoints implemented** (the one exception, `/trackInfo`, is documented but non-functional on real hardware) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware.
+
+### Key Findings
+- ✅ **All essential user functionality implemented**
+- ✅ **Complete zone management implementation**
+- ✅ **Real-time WebSocket event system**
+- ✅ **Extended features beyond official specification**
+- ✅ **Complete advanced audio controls implementation**
+- ❌ **1 non-functional endpoint** (documented but broken on real devices)
+
+---
+
+## Official API v1.0 Endpoint Coverage
+
+### Implemented Endpoints: 20/21 (95%)
+
+| Endpoint                     | Method   | Status               | Implementation                                                                                                                       | Notes                                          |
+|------------------------------|----------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------|
+| `/key`                       | POST     | ✅ **Complete**       | `SendKey()`, `SendKeyPress()`, `SendKeyRelease()`                                                                                    | Full key simulation with press/release states  |
+| `/select`                    | POST     | ✅ **Complete**       | `SelectSource()`, `SelectSpotify()`, etc.                                                                                            | Source selection with validation               |
+| `/sources`                   | GET      | ✅ **Complete**       | `GetSources()`                                                                                                                       | Available audio sources                        |
+| `/bassCapabilities`          | GET      | ✅ **Complete**       | `GetBassCapabilities()`                                                                                                              | Bass capability detection                      |
+| `/bass`                      | GET/POST | ✅ **Complete**       | `GetBass()`, `SetBass()`, `SetBassSafe()`                                                                                            | Bass control (-9 to +9) with safety limits     |
+| `/getZone`                   | GET      | ✅ **Complete**       | `GetZone()`, `GetZoneStatus()`, `GetZoneMembers()`                                                                                   | Multiroom zone information                     |
+| `/setZone`                   | POST     | ✅ **Complete**       | `SetZone()`, `CreateZone()`, `AddToZone()`, `RemoveFromZone()`                                                                       | Zone configuration and management              |
+| `/now_playing`               | GET      | ✅ **Complete**       | `GetNowPlaying()`                                                                                                                    | Current playback status with full metadata     |
+| `/trackInfo`                 | GET      | ❌ **Non-functional** | `GetTrackInfo()`                                                                                                                     | Documented but times out on real devices       |
+| `/volume`                    | GET/POST | ✅ **Complete**       | `GetVolume()`, `SetVolume()`, `SetVolumeSafe()`                                                                                      | Volume and mute control with safety features   |
+| `/presets`                   | GET      | ✅ **Complete**       | `GetPresets()`, `GetNextAvailablePresetSlot()`                                                                                       | Preset configurations (read-only per API spec) |
+| `/info`                      | GET      | ✅ **Complete**       | `GetDeviceInfo()`                                                                                                                    | Device information and capabilities            |
+| `/name`                      | POST     | ✅ **Complete**       | `SetName()`                                                                                                                          | Device name modification                       |
+| `/capabilities`              | GET      | ✅ **Complete**       | `GetCapabilities()`                                                                                                                  | Device feature capabilities                    |
+| `/addZoneSlave`              | POST     | ✅ **Complete**       | `AddZoneSlave()`, `AddZoneSlaveByDeviceID()`                                                                                         | Individual device addition to zone             |
+| `/removeZoneSlave`           | POST     | ✅ **Complete**       | `RemoveZoneSlave()`, `RemoveZoneSlaveByDeviceID()`                                                                                   | Individual device removal from zone            |
+| `/audiodspcontrols`          | GET/POST | ✅ **Complete**       | `GetAudioDSPControls()`, `SetAudioDSPControls()`, `SetAudioMode()`, `SetVideoSyncAudioDelay()`                                       | DSP audio modes and video sync delay           |
+| `/audioproducttonecontrols`  | GET/POST | ✅ **Complete**       | `GetAudioProductToneControls()`, `SetAudioProductToneControls()`, `SetAdvancedBass()`, `SetAdvancedTreble()`                         | Advanced bass/treble controls                  |
+| `/audioproductlevelcontrols` | GET/POST | ✅ **Complete**       | `GetAudioProductLevelControls()`, `SetAudioProductLevelControls()`, `SetFrontCenterSpeakerLevel()`, `SetRearSurroundSpeakersLevel()` | Speaker level controls                         |
+| `/speaker`                   | POST     | ✅ **Complete**       | `PlayTTS()`, `PlayURL()`, `PlayCustom()`                                                                                             | TTS and URL content playback for notifications |
+| `/playNotification`          | GET      | ✅ **Complete**       | `PlayNotificationBeep()`                                                                                                             | Simple notification beep sound                 |
+
+### Non-functional Endpoints: 1/21 (5%)
+
+| Endpoint     | Method | Status               | Reason                                               | Impact                                |
+|--------------|--------|----------------------|------------------------------------------------------|---------------------------------------|
+| `/trackInfo` | GET    | ❌ **Non-functional** | Times out on real devices (AllegroWebserver timeout) | **None** - Use `/now_playing` instead |
+
+### Official Endpoints Not Supported by API: 1
+
+| Endpoint        | Method | Status            | Official API Status                                                                                                                                                                 |
+|-----------------|--------|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `/storePreset`  | POST   | ✅ **IMPLEMENTED** | Found via [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) (official docs marked `/presets` POST as "N/A") |
+| `/removePreset` | POST   | ✅ **IMPLEMENTED** | Found via [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)                                                 |
+
+---
+
+## Extended Features Beyond Official API v1.0
+
+### Additional Endpoints: 5 Extra Features
+
+**Note**: The `/speaker` and `/playNotification` endpoints were discovered via the [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API) and are now part of the official coverage.
+
+| Endpoint        | Method   | Status       | Notes                                                              |
+|-----------------|----------|--------------|--------------------------------------------------------------------|
+| `/name`         | GET      | 🔍 **Extra** | Official API only documents POST, but GET works with real hardware |
+| `/balance`      | GET/POST | 🔍 **Extra** | Stereo balance control (-50 to +50) - not in API v1.0              |
+| `/clockTime`    | GET/POST | 🔍 **Extra** | Device time management - works with real devices                   |
+| `/clockDisplay` | GET/POST | 🔍 **Extra** | Clock display settings and brightness                              |
+| `/networkInfo`  | GET      | 🔍 **Extra** | Network connectivity information                                   |
+
+### Advanced Implementation Features
+
+| Feature                 | Status                | Description                                                                                           |
+|-------------------------|-----------------------|-------------------------------------------------------------------------------------------------------|
+| **WebSocket Events**    | ✅ **Complete**        | Real-time device state monitoring (`nowPlayingUpdated`, `volumeUpdated`, etc.)                        |
+| **Device Discovery**    | ✅ **Complete**        | UPnP/SSDP + mDNS/Bonjour automatic discovery                                                          |
+| **Safety Features**     | ✅ **Enhanced**        | Volume limiting, bass clamping, input validation                                                      |
+| **High-Level Zone API** | ✅ **Superior**        | Fluent zone management API replacing low-level slave operations                                       |
+| **Preset Management**   | ✅ **Wiki Documented** | Full preset CRUD via `/storePreset` and `/removePreset` endpoints (found via SoundTouch Plus Wiki)    |
+| **Content Navigation**  | ✅ **Complete**        | Browse and search content via `/navigate`, `/searchStation`, `/addStation` (via SoundTouch Plus Wiki) |
+
+---
+
+## Implementation Analysis
+
+### Zone Management: Complete Implementation ✅
+
+**Official Low-Level API:**
+```go
+// Individual slave operations (exact official API implementation)
+client.AddZoneSlave("MASTER123", "SLAVE456", "192.0.2.101")
+client.RemoveZoneSlave("MASTER123", "SLAVE456", "192.0.2.101")
+```
+
+**Enhanced High-Level API:**
+```go
+// High-level fluent API (enhanced implementation)
+zone := client.CreateZoneWithIPs("192.0.2.100", []string{"192.0.2.101", "192.0.2.102"})
+client.AddToZone("192.0.2.100", "192.0.2.103")
+client.RemoveFromZone("192.0.2.100", "192.0.2.101")
+client.DissolveZone("192.0.2.100")
+```
+
+**Advantages:**
+- ✅ **Complete official API compliance** - exact implementation of official endpoints
+- ✅ **Enhanced high-level operations** - atomic zone creation/modification
+- ✅ **Validation and error handling** - comprehensive zone state validation
+- ✅ **Flexible usage patterns** - choose low-level or high-level as needed
+- ✅ **Better user experience** - intuitive zone construction and modification
+
+### Safety and Validation Enhancements
+
+**Volume Control:**
+```go
+client.SetVolumeSafe(85)  // Automatically caps at safe maximum
+client.IncreaseVolume(5)  // Controlled incremental changes
+```
+
+**Bass Control:**
+```go
+client.SetBassSafe(15)    // Automatically clamps to valid range (-9 to +9)
+capabilities, _ := client.GetBassCapabilities()
+if capabilities.ValidateLevel(level) { /* ... */ }
+```
+
+---
+
+## Missing Functionality Impact Assessment
+
+### High Impact: None ✅
+All essential user functionality is fully implemented.
+
+### Medium Impact: None ✅
+All common use cases are covered.
+
+### Low Impact: 1 Non-functional Feature ❌
+
+#### 1. Non-functional Endpoint
+- **Official**: `/trackInfo`
+- **Impact**: None - identical functionality available via `/now_playing`
+- **Issue**: Times out on real devices despite being documented in API
+- **Workaround**: Use `GetNowPlaying()` method instead
+
+---
+
+## Testing Coverage
+
+### Endpoint Testing: 100%
+- ✅ All implemented endpoints have comprehensive unit tests
+- ✅ Real device integration testing completed
+- ✅ Error handling and edge cases covered
+- ✅ WebSocket event system fully tested
+
+### Test Statistics:
+```
+Unit Tests:        200+ test cases
+Integration Tests: Real device validation
+Benchmark Tests:   Performance validation
+Coverage:          >90% code coverage
+```
+
+---
+
+## Recommendations
+
+### For Standard Users: ✅ **Complete**
+This implementation provides **everything needed** for standard SoundTouch usage:
+- Media control, volume management, source selection
+- Preset access, device information, real-time updates
+- Multiroom zone management, device discovery
+
+### For Advanced Users: ✅ **Excellent**
+Additional features beyond standard API:
+- Enhanced safety controls, comprehensive event system
+- Extended device information, network management
+- Superior zone management implementation
+
+### For Professional Installations: ⚠️ **Mostly Complete**
+Missing only niche professional features:
+- Advanced DSP audio controls
+- Professional tone/level controls
+- Individual zone slave micro-management
+
+**Recommendation**: For 99% of use cases, this implementation is **complete and superior** to a basic API implementation.
+
+---
+
+## Future Considerations
+
+### Potential Additions (Low Priority):
+1. **Extended WebSocket Events** - Additional real-time notifications if discovered
+2. **API Evolution Support** - Monitor for new official API versions beyond v1.0
+
+### API Evolution:
+- Monitor for new official API versions beyond v1.0
+- Test extended features with new device models
+- Consider community feedback for additional functionality
+
+---
+
+## Conclusion
+
+This implementation achieves **complete API coverage** with:
+- ✅ **95% functional endpoint implementation** (20/21)
+- ✅ **100% official API endpoint implementation** (21/21)
+- ✅ **100% essential functionality coverage**
+- ✅ **Superior implementations** for complex operations
+- ✅ **Extended features** beyond official specification
+- ✅ **Complete advanced audio controls** for professional devices
+- ✅ **Complete notification system** (TTS, URL playback, beep notifications)
+- ✅ **Comprehensive testing and validation**
+
+The single non-functional endpoint (`/trackInfo`) is **broken on real devices** despite being documented in the official API, but identical functionality is available via `/now_playing`. The implementation **exceeds the official API** in many areas through enhanced safety features, complete zone management, advanced audio controls, and real-time event capabilities.
+
+**Note**: All official API endpoints are implemented. The `/trackInfo` endpoint times out on real devices but is implemented and tested.
+
+**Overall Assessment: Complete** ⭐⭐⭐⭐⭐

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

@@ -1,5 +1,6 @@
-# Bose SoundTouch Traffic Interception Runbook
-
+---
+title: "Bose SoundTouch Traffic Interception Runbook"
+---
 Intercept HTTPS/WebSocket traffic from the Bose SoundTouch Android app using an Android emulator, mitmproxy, and Frida. Tested on Apple Silicon (ARM64) Mac.
 
 ## Automated Setup
@@ -26,7 +27,7 @@ Read on for the full manual walkthrough and the rationale behind each step.
 
 > **BLE limitation**: Android emulators do not expose Bluetooth hardware. The Bose app's default setup path (BLE Wi-Fi provisioning) therefore cannot be used to configure a factory-reset speaker from the emulator. Use **AP mode** instead: provision the speaker's Wi-Fi credentials via the Mac command line first (see [DEVICE-INITIAL-SETUP.md § 6](../guides/DEVICE-INITIAL-SETUP.md)), then the app can discover the already-networked speaker via mDNS/SSDP without BLE.
 
-> **Emulator ↔ local network**: The emulator routes all traffic through the Mac's active network interface. Once the speaker is on the same LAN as the Mac, the emulator can reach it at its normal LAN IP (e.g. `192.168.1.50`) — no extra routing is needed. Use `adb shell ping 192.168.1.50` to confirm reachability.
+> **Emulator ↔ local network**: The emulator routes all traffic through the Mac's active network interface. Once the speaker is on the same LAN as the Mac, the emulator can reach it at its normal LAN IP (e.g. `192.0.2.50`) — no extra routing is needed. Use `adb shell ping 192.0.2.50` to confirm reachability.
 
 Add Android SDK tools to your PATH (add to `~/.zshrc`):
 
@@ -149,13 +150,13 @@ Find your Mac's local IP:
 
 ```bash
 ipconfig getifaddr en0
-# e.g. 192.168.1.123
+# e.g. 192.0.2.123
 ```
 
 Set the proxy:
 
 ```bash
-adb -s emulator-5554 shell settings put global http_proxy 192.168.1.123:8080
+adb -s emulator-5554 shell settings put global http_proxy 192.0.2.123:8080
 ```
 
 ---
@@ -214,7 +215,7 @@ Edit `/tmp/config.js` and set:
 ```javascript
 const CERT_PEM = `<contents of ~/.mitmproxy/mitmproxy-ca-cert.pem>`;
 
-const PROXY_HOST = '192.168.1.123';  // your Mac IP
+const PROXY_HOST = '192.0.2.123';  // your Mac IP
 const PROXY_PORT = 8080;
 ```
 
@@ -251,8 +252,8 @@ Expected output in the Frida REPL:
 
 ```
 == System certificate trust injected ==
-== Proxy system configuration overridden to 192.168.1.123:8080 ==
-== Proxy configuration overridden to 192.168.1.123:8080 ==
+== Proxy system configuration overridden to 192.0.2.123:8080 ==
+== Proxy configuration overridden to 192.0.2.123:8080 ==
 == Certificate unpinning completed ==
 == Unpinning fallback auto-patcher installed ==
 ```