test(player): adopt httptest.NewTestServer (Go 1.27) in the new discovery test

NewTestServer registers its own t.Cleanup(Close) instead of needing a
manual defer, and fails the test on a handler panic instead of just
logging it. It defaults to an in-memory transport reachable only via
Server.Client(), which wouldn't work here since our production
client.NewClient dials a real address rather than using that client --
calling Start() instead of Client() opts back into a real loopback
listener, identical to the old NewServer, confirmed by reading the
actual go1.27.0 source (server.go's Start implementation).

This is a proactive adoption of a new stdlib idiom, not one of the
review findings from the previous commit; it doesn't change the
goroutine-drain fix from that commit, which is a separate concern
Close()'s "wait for outstanding requests" guarantee doesn't fully
cover (a goroutine that hasn't started its request yet at Close() time
isn't "outstanding").

Verified: 10x -count re-run under -race, full suite + lint clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

.claude/commands/blog-update.md

@@ -0,0 +1,122 @@
+Draft a "News & Updates" blog post for AfterTouch covering recent git activity, commit it to a branch, and hand the maintainer the commands to push and open a draft PR (the maintainer pushes, not you).
+
+## Step 1 — Determine lookback window
+
+If the invocation arguments name an explicit starting point (a tag like `v0.93.1` or a
+date), use that as SINCE. For a tag, resolve its date:
+`git log -1 --format=%ad --date=short <tag>`. An explicit argument always overrides the
+auto-detection below.
+
+Otherwise, auto-detect from the last published post:
+```
+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. The body. Prefer a narrative that ties the changes into a story (what shifted, why it matters), not a bare aggregation of the release notes. Group related work under `##` sections (the commit categories are raw material, not the final headings). Write for an operator audience: no raw git subjects, no internal Go package paths. A short bullet list inside a section is fine, but the post should read like prose, not a changelog dump.
+3. Close with the standard footer convention used by the existing posts, so every post ends the same way:
+
+   ```markdown
+   ## Current release
+
+   **vX.Y.Z**, released MONTH D, YYYY
+
+   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.
+   ```
+
+   Get the release date with `git log -1 --format=%ad --date=format:'%B %-d, %Y' vX.Y.Z`.
+   When in doubt about any recurring element (footer, release line, tags), match the most
+   recent existing post under `docs/content/blog/` rather than inventing a new convention.
+   Never retrofit or restyle already-published posts to fit a new convention — they are
+   dated records; a new convention applies going forward only.
+
+Target length: 300–600 words (longer is fine when the story warrants it). Never include
+real IPs, MAC addresses, account IDs, or device names.
+
+**No em dashes.** Do not use the em dash character (`—`) anywhere in the post; use commas,
+parentheses, colons, or separate sentences. (En dashes in a period label like
+`April – May 2026` are fine.) Verify with `grep -c '—' <file>` before committing.
+
+## Step 6 — Create a branch and commit (do NOT push)
+
+```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"
+```
+
+**Do not push and do not open the PR yourself.** The maintainer always pushes over SSH
+(see the global and project instructions). Pushing on their behalf, including over HTTPS
+with a token or by switching the remote, is not allowed.
+
+## Step 7 — Done
+
+Hand the maintainer the ready-to-run commands to push and open the draft PR, then stop:
+
+```bash
+git push -u origin blog/YYYY-MM-update
+gh pr create --draft \
+  --title "Blog: PERIOD update post" \
+  --body "Update post covering recent changes. Review content before merging — deployment is automatic on merge to main."
+```
+
+If the `documentation` label exists on the repo, add `--label documentation`.
+
+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

@@ -1,77 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: 'bug'
-assignees: ''
-
----
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Environment (please complete the following information):**
-- OS: [e.g. macOS 14.0, Windows 11, Ubuntu 22.04]
-- Go version: [e.g. 1.25.5]
-- Library version: [e.g. v1.0.0, commit hash if using main branch]
-- SoundTouch device model: [e.g. SoundTouch 10, SoundTouch 20]
-- Device firmware version: [if known]
-
-**Command/Code that failed**
-```bash
-# If using CLI tool, provide the exact command
-soundtouch-cli --host 192.168.1.100 info get
-
-# If using Go library, provide minimal code example
-```
-
-**Error output**
-```
-Paste the complete error message here, including stack traces if available
-```
-
-**Device Information (if applicable)**
-```xml
-<!-- If the issue is device-specific, include output from: -->
-<!-- soundtouch-cli --host YOUR_DEVICE_IP info get -->
-```
-
-**Network Configuration**
-- Network setup: [e.g. home WiFi, corporate network, VPN]
-- Firewall/proxy: [any network restrictions]
-- Device connectivity: [how device connects to network - WiFi, Ethernet]
-
-**Additional context**
-Add any other context about the problem here. For example:
-- Does this happen consistently or intermittently?
-- Did this work in a previous version?
-- Are there any workarounds?
-- Any relevant log files or debug output
-
-**Logs (if applicable)**
-```
-# Enable verbose logging with --verbose flag or debug environment variable
-# and paste relevant log output here
-```
-
-**Screenshots**
-If applicable, add screenshots to help explain your problem.
-
----
-
-**Checklist**
-- [ ] I have searched existing issues to avoid duplicates
-- [ ] I have tested with the latest version
-- [ ] I have included all relevant environment information
-- [ ] I have provided a minimal reproduction case
-- [ ] I have included complete error messages

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,201 +1,118 @@
 name: Bug Report
-description: File a bug report to help us improve the library
+description: Something in AfterTouch isn't working the way it should
 title: "[Bug]: "
 labels: ["bug", "triage"]
-assignees: []
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for taking the time to fill out this bug report! Please provide as much detail as possible to help us diagnose and fix the issue.
+        Thanks for helping improve **AfterTouch**! 🙏
 
-  - type: input
-    id: version
-    attributes:
-      label: Library Version
-      description: What version of the library are you using?
-      placeholder: "v1.0.0"
-    validations:
-      required: true
+        AfterTouch is a community-built toolkit that keeps Bose SoundTouch speakers
+        working after the Bose cloud shutdown. We both give and ask for support here,
+        so don't worry about getting every field perfect.
 
-  - type: dropdown
-    id: go-version
-    attributes:
-      label: Go Version
-      description: What version of Go are you using?
-      options:
-        - "1.25.5+"
-        - "1.25"
-        - "1.24"
-        - "1.23"
-        - "Other (please specify in description)"
-    validations:
-      required: true
-
-  - type: dropdown
-    id: operating-system
-    attributes:
-      label: Operating System
-      description: What operating system are you running on?
-      options:
-        - "Linux"
-        - "macOS"
-        - "Windows"
-        - "FreeBSD"
-        - "Other (please specify in description)"
-    validations:
-      required: true
-
-  - type: input
-    id: device-model
-    attributes:
-      label: Bose Device Model
-      description: What Bose SoundTouch device are you trying to control?
-      placeholder: "SoundTouch 10, SoundTouch 20, etc."
-    validations:
-      required: true
-
-  - type: input
-    id: device-firmware
-    attributes:
-      label: Device Firmware Version
-      description: What firmware version is your device running? (Check in Bose app or via /info endpoint)
-      placeholder: "4.8.1.4567.891234567"
+        A quick look at the
+        [Troubleshooting Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/)
+        often saves time. For "how do I...?" questions, please use
+        [Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) instead.
 
   - type: textarea
     id: description
     attributes:
-      label: Bug Description
-      description: A clear and concise description of what the bug is.
-      placeholder: "Describe what happened and what you expected to happen..."
+      label: What happened?
+      description: What went wrong, and what did you expect to happen instead?
+      placeholder: "When I play a radio station from the player UI, the speaker shows an orange light and nothing plays. I expected it to start playing."
     validations:
       required: true
 
   - type: textarea
-    id: reproduction-steps
+    id: steps
     attributes:
-      label: Steps to Reproduce
-      description: Steps to reproduce the behavior
+      label: Steps to reproduce
+      description: How can we trigger it? Rough steps are fine.
       placeholder: |
-        1. Go to '...'
-        2. Click on '....'
-        3. Scroll down to '....'
-        4. See error
+        1. Open the player UI
+        2. Search for a station
+        3. Press play
+        4. ...
     validations:
-      required: true
+      required: false
 
   - type: textarea
-    id: expected-behavior
+    id: diagnostic
     attributes:
-      label: Expected Behavior
-      description: A clear and concise description of what you expected to happen.
-      placeholder: "What should have happened instead?"
+      label: Diagnostic report (the most helpful thing you can attach)
+      description: |
+        In the AfterTouch **admin UI**, open the **Health tab** and click
+        **Download diagnostic report**. It is by far the best way to help us
+        diagnose a bug. GitHub blocks `.age` uploads, so rename the file to
+        `.age.txt` (or zip it) before dragging it into this box. You can also email
+        it instead: aftertouch-support@gesellix.net.
+
+        The file is **encrypted** to the maintainer's key, so only the maintainer
+        can open it. The structured summary has credentials redacted, but the raw
+        datastore files (for example `Sources.xml`) are included as-is and can
+        contain the access tokens your speaker uses for linked services like
+        Spotify or Amazon. If that is a concern, unlink those services before
+        exporting, or email the report privately instead.
+      placeholder: "Attach the aftertouch-diagnostic-*.age.txt (or .zip) file here."
     validations:
-      required: true
+      required: false
 
-  - type: textarea
-    id: code-sample
+  - type: input
+    id: device
     attributes:
-      label: Code Sample
-      description: Please provide a minimal code sample that reproduces the issue
-      render: go
-      placeholder: |
-        package main
+      label: Speaker model & firmware
+      description: Which speaker, and (if you know it) the firmware version.
+      placeholder: "SoundTouch 10, firmware 27.0.6"
+    validations:
+      required: false
 
-        import (
-            "fmt"
-            "github.com/gesellix/bose-soundtouch/pkg/client"
-        )
+  - type: dropdown
+    id: how-run
+    attributes:
+      label: How are you running AfterTouch?
+      options:
+        - "Docker / docker compose"
+        - "Prebuilt binary"
+        - "Built from source"
+        - "Not sure"
+    validations:
+      required: false
 
-        func main() {
-            // Your code that demonstrates the issue
-        }
+  - type: input
+    id: version
+    attributes:
+      label: AfterTouch version
+      description: Shown in the admin UI footer, or via the binary's `--version`.
+      placeholder: "v0.123.0"
     validations:
       required: false
 
   - type: textarea
     id: logs
     attributes:
-      label: Error Messages / Logs
-      description: Please include any relevant error messages, stack traces, or log output
+      label: Logs / error messages
+      description: Any relevant output from the service, CLI, or browser console. Please mask real LAN IPs if you can.
       render: shell
-      placeholder: |
-        Error: connection refused
-        at github.com/gesellix/bose-soundtouch/pkg/client.(*Client).makeRequest
-        ...
-    validations:
-      required: false
-
-  - type: dropdown
-    id: component
-    attributes:
-      label: Component
-      description: Which component is affected?
-      multiple: true
-      options:
-        - "Client Library (pkg/client)"
-        - "WebSocket Events"
-        - "Device Discovery"
-        - "CLI Tool"
-        - "Models/XML Parsing"
-        - "Documentation"
-        - "Examples"
-        - "Build/Release"
-    validations:
-      required: false
-
-  - type: dropdown
-    id: severity
-    attributes:
-      label: Severity
-      description: How severe is this bug?
-      options:
-        - "Low - Minor inconvenience"
-        - "Medium - Affects functionality but workaround exists"
-        - "High - Blocks major functionality"
-        - "Critical - Application crashes or data loss"
-    validations:
-      required: true
-
-  - type: textarea
-    id: network-info
-    attributes:
-      label: Network Configuration
-      description: Details about your network setup (if relevant to the issue)
-      placeholder: |
-        - Device IP: 192.168.1.100
-        - Network type: WiFi/Ethernet
-        - Router model:
-        - Any firewalls or network restrictions:
-    validations:
-      required: false
-
-  - type: textarea
-    id: additional-context
-    attributes:
-      label: Additional Context
-      description: Add any other context about the problem here
-      placeholder: "Screenshots, network traces, related issues, etc."
     validations:
       required: false
 
   - type: checkboxes
-    id: troubleshooting
+    id: checklist
     attributes:
-      label: Troubleshooting Steps
-      description: Have you tried these troubleshooting steps?
+      label: Before you submit
       options:
-        - label: "I have checked the [Troubleshooting Guide](docs/TROUBLESHOOTING.md)"
-        - label: "I have verified my device is reachable (ping test)"
-        - label: "I have tested with the CLI tool"
-        - label: "I have checked for similar existing issues"
-        - label: "I am using the latest version of the library"
+        - label: "I checked the [Troubleshooting Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/)"
+        - label: "I searched [existing issues](https://github.com/gesellix/Bose-SoundTouch/issues) for a duplicate"
+        - label: "I'm on a recent AfterTouch version"
 
   - type: checkboxes
-    id: terms
+    id: coc
     attributes:
       label: Code of Conduct
-      description: By submitting this issue, you agree to follow our Code of Conduct
+      description: This project follows a [Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md).
       options:
         - label: "I agree to follow this project's Code of Conduct"
           required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,12 @@
+# Free-form blank issues stay enabled for anything that doesn't fit a template.
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Questions & Support (Discussions)
+    url: https://github.com/gesellix/Bose-SoundTouch/discussions
+    about: "\"How do I...?\", setup help, and general support. AfterTouch is a community effort: ask here, and help others when you can."
+  - name: 🚑 Survival Guide
+    url: https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/
+    about: "Getting your speakers working again after the Bose cloud shutdown. Start here."
+  - name: 🔧 Troubleshooting Guide
+    url: https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/
+    about: "Common problems and their fixes. Please check this before filing a bug."

.github/ISSUE_TEMPLATE/device_compatibility.md

@@ -1,113 +0,0 @@
----
-name: Device compatibility report
-about: Report compatibility with a new SoundTouch device model
-title: 'Device Compatibility: [Device Model]'
-labels: 'compatibility, documentation'
-assignees: ''
-
----
-
-**Device Information**
-- **Model**: [e.g. SoundTouch 30, Wave SoundTouch IV, SoundTouch Portable]
-- **Model Number**: [e.g. 738102-2100, found on device label]
-- **Firmware Version**: [if known, from device settings or API response]
-- **Purchase Date**: [approximate, helps identify firmware generation]
-
-**Testing Results**
-
-### Basic Functionality
-- [ ] Device discovery (UPnP/mDNS)
-- [ ] Basic device info (`GET /info`)
-- [ ] Now playing status (`GET /now_playing`)
-- [ ] Media controls (play/pause/stop)
-- [ ] Volume control
-- [ ] Source listing (`GET /sources`)
-
-### Advanced Features
-- [ ] Bass control (`GET/POST /bass`)
-- [ ] Balance control (`GET/POST /balance`) - if stereo device
-- [ ] Clock/time management (`GET/POST /clockTime`)
-- [ ] Network information (`GET /networkInfo`)
-- [ ] WebSocket events
-- [ ] Multiroom zones (master)
-- [ ] Multiroom zones (slave)
-
-### Advanced Audio Controls (Professional/High-end Models)
-- [ ] DSP controls (`GET/POST /audiodspcontrols`)
-- [ ] Tone controls (`GET/POST /audioproducttonecontrols`)
-- [ ] Level controls (`GET/POST /audioproductlevelcontrols`)
-
-### Known Issues
-List any features that don't work or behave unexpectedly:
-- Feature name: Description of issue
-- Command that fails: `soundtouch-cli command that doesn't work`
-
-**Device Info Output**
-```xml
-<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP info get -->
-<!-- This helps us understand device capabilities and variants -->
-```
-
-**Device Capabilities Output**
-```xml
-<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP capabilities -->
-<!-- This shows what features the device reports as available -->
-```
-
-**Bass Capabilities (if supported)**
-```xml
-<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP bass capabilities -->
-<!-- Only if the device supports bass control -->
-```
-
-**Available Sources**
-```xml
-<!-- Paste output from: soundtouch-cli --host YOUR_DEVICE_IP source list -->
-<!-- Shows what audio sources this device supports -->
-```
-
-**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
-# ... etc
-```
-
-**Environment**
-- **OS**: [e.g. macOS 14.0, Windows 11, Ubuntu 22.04]
-- **Go version**: [e.g. 1.25.5]
-- **Library version**: [e.g. v1.0.0, commit hash]
-- **Network setup**: [home WiFi, corporate, etc.]
-
-**Performance Notes**
-- Response times: [normal, slow, timeouts]
-- Specific timeouts: [any endpoints that timeout]
-- WebSocket stability: [connects reliably, frequent disconnects, etc.]
-
-**Comparison with Tested Models**
-If you have experience with other SoundTouch models:
-- **Similar to**: [e.g. works like SoundTouch 20]
-- **Differences from**: [e.g. missing balance control compared to SoundTouch 30]
-
-**Additional Notes**
-Any other observations about device behavior, quirks, or special considerations:
-- Does the device have unique features not seen in other models?
-- Are there any setup requirements or configuration notes?
-- Does it work differently in different network environments?
-
-**Documentation Impact**
-- [ ] Update supported devices list
-- [ ] Add device-specific notes to documentation
-- [ ] Update compatibility matrix
-- [ ] Add to integration test suite
-
----
-
-**Checklist**
-- [ ] I have tested basic functionality (info, play, volume)
-- [ ] I have tested advanced features available on this device
-- [ ] I have provided complete device information output
-- [ ] I have noted any issues or limitations
-- [ ] I have tested in a typical network environment
-- [ ] I understand this helps improve compatibility for all users

.github/ISSUE_TEMPLATE/device_compatibility.yml

@@ -0,0 +1,74 @@
+name: Device Compatibility Report
+description: Tell us how AfterTouch works (or doesn't) with your SoundTouch model
+title: "[Compatibility]: "
+labels: ["compatibility", "documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping map out which speakers AfterTouch supports! 📋
+
+        Reports like yours help everyone with the same model, and feed our
+        compatibility notes in the docs.
+
+  - type: input
+    id: model
+    attributes:
+      label: Speaker model
+      placeholder: "SoundTouch 20, Wave SoundTouch IV, SoundTouch Portable, ..."
+    validations:
+      required: true
+
+  - type: input
+    id: firmware
+    attributes:
+      label: Firmware version
+      description: From the admin UI, the Bose app, or the device's `/info`.
+      placeholder: "27.0.6"
+    validations:
+      required: false
+
+  - type: textarea
+    id: works
+    attributes:
+      label: What works?
+      placeholder: |
+        - Discovery
+        - Playback and presets
+        - Stereo pair / multiroom
+        - Migration off the Bose cloud
+    validations:
+      required: false
+
+  - type: textarea
+    id: broken
+    attributes:
+      label: What doesn't work?
+      placeholder: "Anything that failed or behaved unexpectedly on this model."
+    validations:
+      required: false
+
+  - type: textarea
+    id: diagnostic
+    attributes:
+      label: Diagnostic report
+      description: |
+        Optional, but very helpful. In the AfterTouch **admin UI**, open the
+        **Health tab** and click **Download diagnostic report**. GitHub blocks
+        `.age` uploads, so rename the file to `.age.txt` (or zip it) before
+        attaching, or email it to aftertouch-support@gesellix.net. It is encrypted
+        to the maintainer's key. The raw datastore files inside are included as-is,
+        so if you have linked services like Spotify or Amazon, unlink them first or
+        send the file privately.
+      placeholder: "Attach the aftertouch-diagnostic-*.age.txt (or .zip) file here."
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: coc
+    attributes:
+      label: Code of Conduct
+      description: This project follows a [Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md).
+      options:
+        - label: "I agree to follow this project's Code of Conduct"
+          required: true

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,77 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: ''
-labels: 'enhancement'
-assignees: ''
-
----
-
-**Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**Describe the solution you'd like**
-A clear and concise description of what you want to happen.
-
-**Describe alternatives you've considered**
-A clear and concise description of any alternative solutions or features you've considered.
-
-**Use case**
-Describe your specific use case and how this feature would benefit you and other users.
-
-**SoundTouch API Support**
-- [ ] This feature is supported by the official SoundTouch API
-- [ ] This feature is NOT supported by the SoundTouch API (custom enhancement)
-- [ ] I'm not sure if this is supported by the SoundTouch API
-
-**API Documentation Reference (if applicable)**
-If this feature is based on a SoundTouch API endpoint, please provide:
-- Endpoint URL: [e.g. GET /newendpoint]
-- Documentation reference: [page number or section in official API docs]
-- XML request/response examples: [if known]
-
-**Implementation Details (optional)**
-If you have ideas about how this could be implemented:
-- Suggested package/module: [e.g. pkg/client, cmd/soundtouch-cli]
-- Method signatures: [if you have suggestions]
-- CLI commands: [if this affects the CLI tool]
-
-**Device Compatibility**
-- SoundTouch models this applies to: [e.g. all models, SoundTouch 20+, specific models]
-- Have you tested this manually: [e.g. via curl, Postman, etc.]
-
-**Examples**
-Provide examples of how you would like to use this feature:
-
-```go
-// Go library example
-client.NewFeature(parameters)
-```
-
-```bash
-# CLI example
-soundtouch-cli --host 192.168.1.100 new-feature --param value
-```
-
-**Priority**
-- [ ] Critical - blocks important functionality
-- [ ] High - would significantly improve user experience
-- [ ] Medium - nice to have enhancement
-- [ ] Low - minor improvement
-
-**Additional context**
-Add any other context, screenshots, or examples about the feature request here.
-
-**Related Issues**
-- Related to #[issue number]
-- Depends on #[issue number]
-- Blocks #[issue number]
-
----
-
-**Checklist**
-- [ ] I have searched existing issues to avoid duplicates
-- [ ] I have checked the documentation to ensure this feature doesn't already exist
-- [ ] I have provided a clear use case and rationale
-- [ ] I have considered the impact on existing functionality
-- [ ] I understand this may require SoundTouch API support to implement

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,205 +1,74 @@
 name: Feature Request
-description: Suggest an idea or enhancement for this project
+description: Suggest an idea or improvement for AfterTouch
 title: "[Feature]: "
 labels: ["enhancement", "triage"]
-assignees: []
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for suggesting a new feature! Please provide as much detail as possible to help us understand your request and its potential impact.
+        Thanks for the idea! 💡
 
-  - type: input
-    id: version
-    attributes:
-      label: Library Version
-      description: What version of the library are you currently using?
-      placeholder: "v1.0.0"
-    validations:
-      required: true
+        AfterTouch is a community-built toolkit for keeping Bose SoundTouch speakers
+        alive. For open-ended "would it be possible...?" brainstorming,
+        [Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) is often
+        a better fit. Use this form when you have a concrete improvement in mind.
 
   - type: textarea
     id: problem
     attributes:
-      label: Problem Description
-      description: Is your feature request related to a problem? Please describe what you're trying to accomplish.
-      placeholder: "I'm always frustrated when... / I need to be able to... / Currently it's not possible to..."
+      label: What problem would this solve?
+      placeholder: "I can't ... / It's hard to ... / Currently there's no way to ..."
     validations:
       required: true
 
   - type: textarea
-    id: solution
+    id: idea
     attributes:
-      label: Proposed Solution
-      description: Describe the solution you'd like to see implemented.
-      placeholder: "I would like to see... / A new function that... / An option to..."
+      label: What would you like to see?
+      placeholder: "Describe the feature or improvement you have in mind."
     validations:
       required: true
 
+  - type: dropdown
+    id: area
+    attributes:
+      label: Which part of AfterTouch?
+      multiple: true
+      options:
+        - "soundtouch-service (local cloud)"
+        - "soundtouch-cli"
+        - "soundtouch-player (web UI)"
+        - "soundtouch-backup"
+        - "Go library (pkg/*)"
+        - "Documentation"
+        - "Not sure"
+    validations:
+      required: false
+
   - type: textarea
     id: alternatives
     attributes:
-      label: Alternatives Considered
-      description: Describe any alternative solutions or features you've considered.
-      placeholder: "I considered... / Another approach could be... / Workaround I'm currently using..."
-    validations:
-      required: false
-
-  - type: dropdown
-    id: component
-    attributes:
-      label: Component
-      description: Which component would this feature affect?
-      multiple: true
-      options:
-        - "Client Library (pkg/client)"
-        - "WebSocket Events"
-        - "Device Discovery"
-        - "CLI Tool"
-        - "Models/XML Parsing"
-        - "Documentation"
-        - "Examples"
-        - "New API Endpoint"
-        - "Performance Optimization"
-        - "Developer Experience"
-    validations:
-      required: true
-
-  - type: dropdown
-    id: device-compatibility
-    attributes:
-      label: Device Compatibility
-      description: Which Bose SoundTouch devices should this feature support?
-      multiple: true
-      options:
-        - "All SoundTouch devices"
-        - "SoundTouch 10"
-        - "SoundTouch 20"
-        - "SoundTouch 30"
-        - "SoundTouch Portable"
-        - "SoundTouch Wave"
-        - "Other (specify in description)"
-    validations:
-      required: false
-
-  - type: dropdown
-    id: priority
-    attributes:
-      label: Priority
-      description: How important is this feature to you?
-      options:
-        - "Low - Nice to have"
-        - "Medium - Would improve my workflow"
-        - "High - Important for my use case"
-        - "Critical - Blocking my project"
-    validations:
-      required: true
-
-  - type: dropdown
-    id: api-type
-    attributes:
-      label: API Type (if applicable)
-      description: What type of API enhancement is this?
-      options:
-        - "Not applicable"
-        - "New Bose SoundTouch endpoint"
-        - "Enhancement to existing endpoint"
-        - "Client library improvement"
-        - "WebSocket event enhancement"
-        - "Discovery enhancement"
-        - "CLI command addition"
-    validations:
-      required: false
-
-  - type: textarea
-    id: use-case
-    attributes:
-      label: Use Case / User Story
-      description: Describe your specific use case or user story
-      placeholder: |
-        As a [type of user], I want to [goal] so that [benefit].
-
-        Example: As a home automation developer, I want to create custom zones so that I can group speakers dynamically based on user preferences.
-    validations:
-      required: true
-
-  - type: textarea
-    id: example-api
-    attributes:
-      label: Desired API Example
-      description: Show how you'd like the API to work (if applicable)
-      render: go
-      placeholder: |
-        // Example of how you envision using this feature
-        client := soundtouch.New("192.168.1.100", 8090)
-
-        // Your desired API call
-        result, err := client.NewFeature(options)
-        if err != nil {
-            // handle error
-        }
-
-        // Use the result
-        fmt.Println(result)
-    validations:
-      required: false
-
-  - type: textarea
-    id: technical-details
-    attributes:
-      label: Technical Details
-      description: Any technical considerations, constraints, or implementation ideas?
-      placeholder: |
-        - Should this be backward compatible?
-        - Any performance considerations?
-        - Integration with existing features?
-        - External dependencies needed?
+      label: Alternatives or workarounds
+      description: Anything you've already tried or considered. Links and references are welcome.
+      placeholder: "See the API Cookbook (https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-COOKBOOK/) ..."
     validations:
       required: false
 
   - type: checkboxes
-    id: implementation
+    id: help
     attributes:
-      label: Implementation
-      description: Are you willing to help implement this feature?
+      label: Can you help?
+      description: Completely optional. Community contributions are very welcome.
       options:
-        - label: "I can help implement this feature"
-        - label: "I can provide testing/feedback"
+        - label: "I can help implement this"
+        - label: "I can help test it"
         - label: "I can help with documentation"
-        - label: "I need someone else to implement this"
-
-  - type: textarea
-    id: research
-    attributes:
-      label: Research & References
-      description: Have you found any relevant resources, similar implementations, or Bose documentation?
-      placeholder: |
-        - Links to relevant documentation
-        - Similar features in other libraries
-        - Bose SoundTouch API references
-        - Related GitHub issues or discussions
-    validations:
-      required: false
 
   - type: checkboxes
-    id: checklist
-    attributes:
-      label: Checklist
-      description: Please confirm the following
-      options:
-        - label: "I have searched for existing issues and feature requests"
-          required: true
-        - label: "I have checked the [API Cookbook](docs/API-COOKBOOK.md) for existing functionality"
-          required: true
-        - label: "This feature is related to Bose SoundTouch functionality"
-          required: true
-        - label: "I have considered backward compatibility"
-
-  - type: checkboxes
-    id: terms
+    id: coc
     attributes:
       label: Code of Conduct
-      description: By submitting this feature request, you agree to follow our Code of Conduct
+      description: This project follows a [Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md).
       options:
         - label: "I agree to follow this project's Code of Conduct"
           required: true

.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: "/"
@@ -62,6 +125,13 @@ updates:
     allow:
       - dependency-type: "all"
     groups:
+      # Group all codeql-action sub-actions (init/analyze/upload-sarif)
+      # so they bump together. They are separate dependencies to
+      # Dependabot but must stay on the same version, or CodeQL fails
+      # with "Loaded a configuration file for version X, but running Y".
+      codeql-action:
+        patterns:
+          - "github/codeql-action*"
       # Group actions from the same organization
       actions-core:
         patterns:
@@ -98,3 +168,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

@@ -1,171 +1,45 @@
-## Description
+## Summary
 
-Brief description of the changes in this PR.
+What does this PR do, and why?
 
-## Type of Change
+## Linked issue
 
-Please check the type of change your PR introduces:
+<!-- Use "Refs #123". Reserve "Fixes #123" for a change the maintainer has confirmed
+     actually resolves the issue (a merged PR is not confirmation on its own). -->
+Refs #
 
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
-- [ ] Performance improvement
-- [ ] Code refactoring (no functional changes)
-- [ ] Test improvements
-- [ ] Build/CI improvements
+## Type of change
 
-## Related Issues
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation
+- [ ] Refactor / tests / tooling
 
-- Fixes #[issue number]
-- Relates to #[issue number]
-- Part of #[issue number]
+## How was it tested?
 
-## Changes Made
+- [ ] `make check` passes (fmt, vet, lint, tests)
+- [ ] Tested against a real SoundTouch device (details below)
 
-### API Changes
-- [ ] Added new endpoints
-- [ ] Modified existing endpoints
-- [ ] Added new CLI commands
-- [ ] Modified existing CLI commands
-- [ ] Added new configuration options
+<!-- If you tested on hardware, note the model and what you observed. In any pasted
+     output, use RFC-5737 documentation IPs (192.0.2.x), never your real LAN IPs. -->
 
-### Implementation Details
-- Describe the main changes
-- List any new dependencies
-- Mention any architectural changes
+## Checklist
 
-## Testing
-
-### Automated Tests
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] All existing tests pass
-- [ ] Test coverage maintained or improved
-
-### Manual Testing
-- [ ] Tested with real SoundTouch device(s)
-- [ ] Tested CLI changes manually
-- [ ] Tested in different network environments
-
-**Device(s) tested with:**
-- Device model: [e.g. SoundTouch 10]
-- Device IP: [e.g. 192.168.1.100]
-- Test results: [brief description]
-
-### Test Commands
-```bash
-# Commands used to test this change
-make test
-go test ./pkg/client -v -run TestNewFeature
-soundtouch-cli --host 192.168.1.100 new-command
-```
-
-## Documentation
-
-- [ ] Updated relevant documentation
-- [ ] Added code comments for complex logic
-- [ ] Updated CLI help text
-- [ ] Added usage examples
-- [ ] Updated API documentation
-
-**Documentation files updated:**
-- [ ] README.md
-- [ ] docs/API-Endpoints-Overview.md
-- [ ] docs/CLI-REFERENCE.md
-- [ ] Code documentation (godoc)
-
-## Backward Compatibility
-
-- [ ] This change is backward compatible
-- [ ] This change includes breaking changes (requires major version bump)
-- [ ] This change requires configuration migration
-
-**Breaking changes (if any):**
-- Describe what breaks
-- Provide migration instructions
-
-## Security Considerations
-
-- [ ] No security implications
-- [ ] Security review required
-- [ ] Added input validation
-- [ ] Updated authentication/authorization
-
-## Performance Impact
-
-- [ ] No performance impact
-- [ ] Performance improvement
-- [ ] Potential performance regression (justify why)
-
-**Performance notes:**
-- Measured impact: [benchmarks, timing, memory usage]
-- Optimization opportunities: [if any]
-
-## Code Quality
-
-- [ ] Code follows project style guidelines
-- [ ] No linting errors
-- [ ] No security warnings
-- [ ] Memory leaks checked (if applicable)
-
-### Pre-submission Checklist
-
-- [ ] `make check` passes (format, lint, vet)
-- [ ] `make test` passes
-- [ ] No TODO comments left in production code
-- [ ] Error handling is comprehensive
-- [ ] Logging is appropriate (not too verbose, not too quiet)
-
-## Deployment Notes
-
-Any special considerations for deployment:
-- Configuration changes required
-- Database migrations needed
-- Service restart required
-- Rollback procedures
-
-## Screenshots (if applicable)
-
-If this PR includes UI changes or CLI output changes, include screenshots or terminal output examples.
-
-```bash
-# Before
-$ soundtouch-cli old-command
-Old output...
-
-# After  
-$ soundtouch-cli new-command
-New improved output...
-```
-
-## Additional Notes
-
-Any additional information that reviewers should know:
-- Design decisions and trade-offs
-- Future work planned
-- Alternative approaches considered
-- References to external documentation
-
-## Review Requests
-
-**Areas that need special attention:**
-- [ ] Error handling logic
-- [ ] Performance critical sections
-- [ ] Security implications
-- [ ] API design choices
-- [ ] Documentation clarity
-
-**Specific questions for reviewers:**
-1. Question about design choice X?
-2. Is error handling sufficient in section Y?
-3. Should we consider alternative approach Z?
+- [ ] My changes are focused, and I have read the diff myself
+- [ ] No personal data (real LAN IPs, MAC addresses, device IDs, account IDs) in code, tests, or fixtures
+- [ ] Docs or CLI help updated if behavior changed
 
 ---
 
-**Reviewer Guidelines:**
-- Check that all tests pass
-- Verify documentation is updated
-- Test manually if device access available  
-- Consider backward compatibility
-- Evaluate error handling and edge cases
+### A note on AI-assisted contributions
+
+AI and agent-assisted code is welcome, we use it here too. What we cannot accept is
+unreviewed "slop": large generated diffs the author has not read, run, or understood.
+Keep PRs small and focused, make sure `make check` passes, and be ready to explain your
+changes during review.
+
+By contributing, you agree that your work is licensed under the project's
+[MIT License](https://github.com/gesellix/Bose-SoundTouch/blob/main/LICENSE) and that you
+will follow the
+[Code of Conduct](https://github.com/gesellix/Bose-SoundTouch/blob/main/CODE_OF_CONDUCT.md).

.github/workflows/ci.yml

@@ -17,15 +17,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
       - name: Cache Go modules
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: |
             ~/.cache/go-build
@@ -53,7 +53,7 @@ jobs:
         run: make test-http-client
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:
           file: ./coverage.out
           flags: unittests
@@ -66,10 +66,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
@@ -77,7 +77,7 @@ jobs:
         run: sudo apt-get install -y libpcap-dev
 
       - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@v9
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
         with:
           version: latest
           args: --timeout=5m
@@ -86,39 +86,78 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        goos: [linux, darwin, windows]
-        goarch: [amd64, arm64]
-        exclude:
-          # Windows ARM64 builds are experimental
-          - goos: windows
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
             goarch: arm64
+          - goos: linux
+            goarch: arm
+            goarm: 7
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+          - goos: windows
+            goarch: amd64
+          - goos: freebsd
+            goarch: amd64
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
-      - name: Build CLI
+      - name: Cache Go modules
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.mod') }}-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: Build binaries
         env:
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
+          GOARM: ${{ matrix.goarm }}
+          CGO_ENABLED: 0
         run: |
-          output_name="soundtouch-cli-${{ matrix.goos }}-${{ matrix.goarch }}"
-          if [ "${{ matrix.goos }}" = "windows" ]; then
-            output_name="${output_name}.exe"
+          ARCH_SUFFIX="${{ matrix.goos }}-${{ matrix.goarch }}"
+          if [[ -n "${{ matrix.goarm }}" ]]; then
+            ARCH_SUFFIX="${ARCH_SUFFIX}v${{ matrix.goarm }}"
           fi
-          go build -trimpath -ldflags="-s -w" -o "$output_name" ./cmd/soundtouch-cli
+
+          EXT=""
+          if [[ "${{ matrix.goos }}" == "windows" ]]; then
+            EXT=".exe"
+          fi
+
+          mkdir -p build
+
+          # soundtouch-web is now a transitional alias of soundtouch-player
+          # (same source); building the player is enough to verify both.
+          for binary in soundtouch-cli soundtouch-service soundtouch-player soundtouch-backup; do
+            OUTPUT="build/${binary}-${ARCH_SUFFIX}${EXT}"
+            echo "Building $OUTPUT"
+            go build -trimpath -ldflags="-s -w" -o "$OUTPUT" "./cmd/$binary"
+          done
+
+          ls -la build/
 
       - name: Upload build artifacts
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: soundtouch-cli-${{ matrix.goos }}-${{ matrix.goarch }}
-          path: soundtouch-cli-*
+          name: binaries-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goarm }}
+          path: build/
 
   security:
     name: Basic Security Check
@@ -126,10 +165,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
@@ -153,12 +192,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Check documentation links
         run: |
           npm install -g markdown-link-check
-          find . -name "*.md" -not -path "./tests/*" -not -path "./node_modules/*" -print0 | xargs -0 -n1 markdown-link-check -q -v -c .github/markdown-link-check.json
+          ./scripts/check-doc-links.sh
 
       - name: Warn on pending images
         run: |
@@ -178,8 +217,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
 
@@ -189,7 +228,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"
@@ -197,7 +236,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"
@@ -211,10 +250,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
@@ -238,7 +277,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
@@ -266,14 +305,32 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.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
+        run: |
+          # Push on main, and on same-repo PRs (forks can't push to GHCR via GITHUB_TOKEN).
+          SHOULD_PUSH="false"
+          if [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
+            SHOULD_PUSH="true"
+          elif [[ "${{ github.event_name }}" == "pull_request" && \
+                  "${{ github.event.pull_request.head.repo.full_name }}" == "${{ github.repository }}" ]]; then
+            SHOULD_PUSH="true"
+          fi
+          echo "should-push=$SHOULD_PUSH" >> "$GITHUB_OUTPUT"
+          echo "Will push: $SHOULD_PUSH"
 
       - name: Log in to GitHub Container Registry
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v4
+        if: steps.push-check.outputs.should-push == 'true'
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -281,46 +338,93 @@ jobs:
 
       - name: Extract metadata (tags, labels) for soundtouch-service
         id: meta-service
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
             type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
-            type=ref,event=pr
+            type=ref,event=pr,prefix=preview-pr-
+            type=sha,prefix=preview-sha-,format=short,enable=${{ github.event_name == 'pull_request' }}
+            type=ref,event=branch,prefix=preview-branch-,enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
 
       - name: Build and push soundtouch-service Docker image
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           target: soundtouch-service
           platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+          push: ${{ steps.push-check.outputs.should-push == 'true' }}
           tags: ${{ steps.meta-service.outputs.tags }}
           labels: ${{ steps.meta-service.outputs.labels }}
+          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@v6
+      - name: Extract metadata (tags, labels) for soundtouch-player
+        id: meta-player
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
-          images: ghcr.io/${{ github.repository }}-web
+          images: ghcr.io/${{ github.repository }}-player
           tags: |
             type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
-            type=ref,event=pr
+            type=ref,event=pr,prefix=preview-pr-
+            type=sha,prefix=preview-sha-,format=short,enable=${{ github.event_name == 'pull_request' }}
+            type=ref,event=branch,prefix=preview-branch-,enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
 
-      - name: Build and push soundtouch-web Docker image
-        uses: docker/build-push-action@v7
+      - name: Build and push soundtouch-player Docker image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
-          target: soundtouch-web
+          target: soundtouch-player
           platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta-web.outputs.tags }}
-          labels: ${{ steps.meta-web.outputs.labels }}
+          push: ${{ steps.push-check.outputs.should-push == 'true' }}
+          tags: ${{ steps.meta-player.outputs.tags }}
+          labels: ${{ steps.meta-player.outputs.labels }}
+          build-args: |
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
+      - name: Summarize published images
+        if: steps.push-check.outputs.should-push == 'true'
+        env:
+          SERVICE_TAGS: ${{ steps.meta-service.outputs.tags }}
+          PLAYER_TAGS: ${{ steps.meta-player.outputs.tags }}
+          EVENT_NAME: ${{ github.event_name }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          {
+            echo "## 🐳 Published Docker Images"
+            echo ""
+            if [[ "$EVENT_NAME" == "pull_request" ]]; then
+              echo "**Preview** images for PR #${PR_NUMBER}. These are not release builds."
+            elif [[ "$REF_NAME" == "main" ]]; then
+              echo "**Edge** images from \`main\`."
+            else
+              echo "**Preview** images from branch \`${REF_NAME}\`. These are not release builds."
+            fi
+            echo ""
+            echo "### soundtouch-service"
+            echo ""
+            echo '```bash'
+            while IFS= read -r tag; do
+              [[ -n "$tag" ]] && echo "docker pull $tag"
+            done <<< "$SERVICE_TAGS"
+            echo '```'
+            echo ""
+            echo "### soundtouch-player"
+            echo ""
+            echo '```bash'
+            while IFS= read -r tag; do
+              [[ -n "$tag" ]] && echo "docker pull $tag"
+            done <<< "$PLAYER_TAGS"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
   notify:
     name: Notify Status
     runs-on: ubuntu-latest
@@ -355,7 +459,7 @@ jobs:
 
       - name: Update commit status
         if: always()
-        uses: actions/github-script@v9
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             try {

.github/workflows/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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - 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@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        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@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/docs.yml

@@ -20,18 +20,24 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Setup Pages
-        uses: actions/configure-pages@v6
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
+        id: pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+      - 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@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: '_site'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/release.yml

@@ -23,23 +23,27 @@ jobs:
     name: Validate Release
     runs-on: ubuntu-latest
     outputs:
+      tag: ${{ steps.version.outputs.tag }}
       version: ${{ steps.version.outputs.version }}
       is_prerelease: ${{ steps.version.outputs.is_prerelease }}
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
+          # Both triggers resolve to the same thing: the release tag. On a
+          # `release` event inputs.tag is empty, so this falls back to the
+          # published release's tag. Every other job checks out this same
+          # tag (via needs.validate.outputs.tag) so the build is always the
+          # tagged commit, never whatever branch the dispatch ran on (#525).
+          ref: ${{ github.event.inputs.tag || github.event.release.tag_name }}
           fetch-depth: 0
 
       - name: Validate tag format
         id: version
         run: |
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            TAG_NAME="${{ github.event.inputs.tag }}"
-          else
-            TAG_NAME="${GITHUB_REF#refs/tags/}"
-          fi
+          # Single source of truth for the tag, regardless of trigger.
+          TAG_NAME="${{ github.event.inputs.tag || github.event.release.tag_name }}"
 
           echo "Tag name: $TAG_NAME"
 
@@ -50,6 +54,15 @@ jobs:
             exit 1
           fi
 
+          # Confirm the tag actually exists in git. The dispatch path
+          # re-releases an existing tag; it never creates one from a branch.
+          if ! git rev-parse -q --verify "refs/tags/$TAG_NAME" >/dev/null; then
+            echo "❌ Tag $TAG_NAME does not exist in git. Push the tag first, then re-run."
+            exit 1
+          fi
+
+          echo "tag=$TAG_NAME" >> $GITHUB_OUTPUT
+
           # Extract version without 'v' prefix
           VERSION=${TAG_NAME#v}
           echo "version=$VERSION" >> $GITHUB_OUTPUT
@@ -64,7 +77,7 @@ jobs:
           fi
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: ${{ env.GO_VERSION_FILE }}
 
@@ -102,15 +115,17 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.tag }}
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: ${{ env.GO_VERSION_FILE }}
 
       - name: Cache Go modules
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
         with:
           path: |
             ~/.cache/go-build
@@ -125,6 +140,11 @@ jobs:
           CGO_ENABLED: 0
         run: |
           # Common variables
+          # Single build timestamp shared across every binary in this job.
+          BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+          # Commit of the checked-out tag (not GITHUB_SHA, which on a manual
+          # dispatch is the branch HEAD the run started from, not the tag).
+          COMMIT_SHA="$(git rev-parse HEAD)"
           ARCH_SUFFIX="${{ matrix.goos }}-${{ matrix.goarch }}"
           if [[ "${{ matrix.goarm }}" != "" ]]; then
             ARCH_SUFFIX="${ARCH_SUFFIX}v${{ matrix.goarm }}"
@@ -150,9 +170,13 @@ jobs:
             # Ensure clean build environment for this binary
             rm -f "$OUTPUT_NAME" "$OUTPUT_NAME.sha256" "$OUTPUT_NAME.sha512"
 
+            # Inject the validated version (plus commit/date) so the binary
+            # reports the right version regardless of git checkout state.
+            # Relying on Go's VCS stamping alone yields v0.0.0-… when built
+            # from a shallow checkout or a non-tagged commit (see #525).
             if ! go build \
               -trimpath \
-              -ldflags="-s -w" \
+              -ldflags="-s -w -X main.version=${{ needs.validate.outputs.tag }} -X main.commit=${COMMIT_SHA} -X main.date=${BUILD_DATE}" \
               -o "$OUTPUT_NAME" \
               "$CMD_PATH"; then
               echo "❌ Build failed for $BINARY_NAME"
@@ -170,8 +194,8 @@ jobs:
           # Build Service
           build_binary "soundtouch-service" "./cmd/soundtouch-service"
 
-          # Build Web
-          build_binary "soundtouch-web" "./cmd/soundtouch-web"
+          # Build Player (formerly soundtouch-web)
+          build_binary "soundtouch-player" "./cmd/soundtouch-player"
 
           # Build Backup
           build_binary "soundtouch-backup" "./cmd/soundtouch-backup"
@@ -181,7 +205,7 @@ jobs:
         run: |
           CLI_NAME="${{ steps.build.outputs.soundtouch-cli }}"
           SVC_NAME="${{ steps.build.outputs.soundtouch-service }}"
-          WEB_NAME="${{ steps.build.outputs.soundtouch-web }}"
+          PLAYER_NAME="${{ steps.build.outputs.soundtouch-player }}"
           BCK_NAME="${{ steps.build.outputs.soundtouch-backup }}"
 
           # Use atomic operations to avoid conflicts
@@ -198,7 +222,7 @@ jobs:
 
           generate_checksums "$CLI_NAME"
           generate_checksums "$SVC_NAME"
-          generate_checksums "$WEB_NAME"
+          generate_checksums "$PLAYER_NAME"
           generate_checksums "$BCK_NAME"
 
           # Cleanup
@@ -206,13 +230,13 @@ jobs:
           echo "✅ Checksums generated successfully"
 
       - name: Upload build artifact
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: binaries-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goarm }}
           path: |
             build/soundtouch-cli-v*
             build/soundtouch-service-v*
-            build/soundtouch-web-v*
+            build/soundtouch-player-v*
             build/soundtouch-backup-v*
           retention-days: 1
 
@@ -223,7 +247,7 @@ jobs:
 
     steps:
       - name: Download binary artifacts
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: binaries-*
           path: ./binaries
@@ -240,7 +264,7 @@ jobs:
           mkdir -p release-files
 
           # Move all files from subdirectories to the collection directory
-          find . -mindepth 2 -type f \( -name "soundtouch-cli-*" -o -name "soundtouch-service-*" -o -name "soundtouch-web-*" -o -name "soundtouch-backup-*" \) -exec mv {} release-files/ \;
+          find . -mindepth 2 -type f \( -name "soundtouch-cli-*" -o -name "soundtouch-service-*" -o -name "soundtouch-player-*" -o -name "soundtouch-backup-*" \) -exec mv {} release-files/ \;
 
           # Remove empty directories
           find . -type d -empty -delete
@@ -255,8 +279,8 @@ jobs:
           # Generate combined checksums (exclude individual .sha256/.sha512 files)
           if ls soundtouch-* 1> /dev/null 2>&1; then
             # Only checksum the actual binaries, not the .sha256/.sha512 files
-            ls soundtouch-cli-* soundtouch-service-* soundtouch-web-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha256sum > checksums.sha256
-            ls soundtouch-cli-* soundtouch-service-* soundtouch-web-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha512sum > checksums.sha512
+            ls soundtouch-cli-* soundtouch-service-* soundtouch-player-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha256sum > checksums.sha256
+            ls soundtouch-cli-* soundtouch-service-* soundtouch-player-* soundtouch-backup-* | grep -v '\.sha256$' | grep -v '\.sha512$' | xargs sha512sum > checksums.sha512
 
             echo "📋 Generated combined checksums:"
             cat checksums.sha256
@@ -280,7 +304,7 @@ jobs:
           fi
 
       - name: Upload checksums
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: checksums
           path: |
@@ -291,7 +315,7 @@ jobs:
           retention-days: 1
 
       - name: Upload all release assets
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: release-assets
           path: binaries/release-files/
@@ -305,12 +329,13 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
+          ref: ${{ needs.validate.outputs.tag }}
           fetch-depth: 0
 
       - name: Download release assets
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: release-assets
           path: ./release-assets
@@ -318,167 +343,73 @@ jobs:
       - name: Generate release notes
         id: release_notes
         run: |
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            TAG_NAME="${{ github.event.inputs.tag }}"
-          else
-            TAG_NAME="${{ github.event.release.tag_name }}"
-          fi
+          TAG_NAME="${{ needs.validate.outputs.tag }}"
           VERSION="${TAG_NAME#v}"
 
-          # Generate comprehensive release notes
+          # Real per-platform links for the two most-used tools, generated
+          # from the deterministic `<binary>-<tag>-<os>-<arch>[.exe]` asset
+          # naming convention (see scripts/release/quick-downloads.sh),
+          # instead of requiring a scroll through the flat, alphabetical
+          # Assets list. Inline checksum link per row (à la Helm's release
+          # notes) instead of sending people to the combined checksums file.
+          QUICK_DOWNLOADS="$(scripts/release/quick-downloads.sh "$TAG_NAME" "${{ github.repository }}")"
+
+          # Short, accurate header. GitHub's auto-generated "What's Changed"
+          # + "Full Changelog" are appended after this (generate_release_notes).
           cat > release_notes.md << EOF
-          # Bose SoundTouch Go Library $TAG_NAME
+          # AfterTouch $TAG_NAME
 
-          A comprehensive Go library for controlling Bose SoundTouch speakers with 100% API coverage, real-time WebSocket events, and production-ready features.
+          **Bose SoundTouch Toolkit.** Keep your Bose SoundTouch speakers alive after the Bose cloud shutdown. No Bose infrastructure required.
 
-          ## 🎯 Key Features
+          $QUICK_DOWNLOADS
 
-          - **100% API Coverage**: All 19 official endpoints + 6 useful extensions (25 total)
-          - **Real-time Events**: WebSocket support with auto-reconnect and comprehensive event handling
-          - **Multiroom Control**: Complete zone management and coordination
-          - **Production Ready**: Connection pooling, error handling, circuit breakers, monitoring
-          - **Excellent Documentation**: 4000+ lines including Getting Started, Cookbook, Troubleshooting, and Deployment guides
-          - **CLI Tool**: Full-featured command-line interface with all endpoints
+          ## What's included
 
-          ## 🚀 Quick Start
+          Pre-built binaries for Linux (amd64, arm64, armv7), macOS (Intel & Apple Silicon), Windows (amd64), and FreeBSD (amd64):
+
+          - **soundtouch-service** (see above)
+          - **soundtouch-cli** (see above)
+          - **soundtouch-player**: standalone LAN web UI for device control: play/pause, volume, presets, live status. (Formerly \`soundtouch-web\`.)
+          - **soundtouch-backup**: back up your Bose cloud account and each speaker's local state. \`soundtouch-backup all\` captures everything in one step.
+
+          Not sure which file to grab? The [Downloads page](https://gesellix.github.io/Bose-SoundTouch/docs/downloads/) explains which tool you need and which \`<os>-<arch>\` build matches your computer.
+
+          ## Documentation
+
+          Full guides, setup walkthroughs, and troubleshooting: https://gesellix.github.io/Bose-SoundTouch/
+
+          ## Use as a Go library
+
+          The core client is also importable:
 
           \`\`\`bash
           go get github.com/gesellix/bose-soundtouch@$TAG_NAME
           \`\`\`
 
-          \`\`\`go
-          package main
+          ## Verifying downloads
 
-          import (
-              "fmt"
-              "log"
-
-              "github.com/gesellix/bose-soundtouch/pkg/client"
-          )
-
-          func main() {
-              // Create client
-              c := client.New("192.168.1.100", 8090)
-
-              // Get device info
-              info, err := c.GetInfo()
-              if err != nil {
-                  log.Fatal(err)
-              }
-
-              fmt.Printf("Device: %s\\n", info.Name)
-          }
-          \`\`\`
-
-          ## 📚 Documentation
-
-          - [Getting Started Guide](docs/GETTING-STARTED.md) - 10-minute tutorial from discovery to WebSocket monitoring
-          - [API Cookbook](docs/API-COOKBOOK.md) - 1000+ lines of real-world patterns and examples
-          - [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Systematic issue resolution
-          - [Deployment Guide](docs/DEPLOYMENT.md) - Production deployment examples (Docker, K8s, systemd)
-
-          ## 🔧 CLI & Service Tools
-
-          Download the tools for your platform from the assets below:
-
-          ### CLI Tool
-          \`\`\`bash
-          # Quick device discovery
-          ./soundtouch-cli -discover
-          \`\`\`
-
-          ### SoundTouch Service
-          \`\`\`bash
-          # Start the service
-          ./soundtouch-service
-          \`\`\`
-
-          ### SoundTouch Web
-          \`\`\`bash
-          # Start the web app
-          ./soundtouch-web
-          \`\`\`
-
-          ### SoundTouch Backup
-          \`\`\`bash
-          # Back up cloud account and all paired speakers in one go
-          ./soundtouch-backup all
-          \`\`\`
-
-          ## 🧪 Tested Hardware
-
-          - Bose SoundTouch 10
-          - Bose SoundTouch 20
-          - All core functionality validated on real devices
-
-          ## 📈 What's New in $TAG_NAME
-
-          $(git log --pretty=format:"- %s" $(git describe --tags --abbrev=0 HEAD^)..HEAD 2>/dev/null || echo "- Initial release with complete feature set")
-
-          ## 🏗️ Supported Platforms
-
-          This release includes pre-built binaries for:
-          - Linux (amd64, arm64, armv7)
-          - macOS (Intel & Apple Silicon)
-          - Windows (amd64)
-          - FreeBSD (amd64)
-
-          `soundtouch-cli`, `soundtouch-service`, `soundtouch-web`, and `soundtouch-backup` are included.
-
-          ## 🔐 Checksums
-
-          Multiple checksum options are provided for download verification:
-
-          ### Combined Checksums (Recommended)
-          - \`checksums.sha256\` - SHA256 checksums for all binaries
-          - \`checksums.sha512\` - SHA512 checksums for all binaries
+          Each binary has its own \`.sha256\`/\`.sha512\`, and combined \`checksums.sha256\` / \`checksums.sha512\` cover all of them:
 
           \`\`\`bash
-          # Download any binary + combined checksums
-          curl -L -O https://github.com/.../soundtouch-cli-v$TAG_NAME-linux-amd64
-          curl -L -O https://github.com/.../checksums.sha256
-
-          # Verify your specific download
           sha256sum -c checksums.sha256 --ignore-missing
           \`\`\`
-
-          ### Individual Checksums (Per Binary)
-          Each binary also has its own dedicated checksum files:
-          - \`soundtouch-cli-v$TAG_NAME-platform.sha256\`
-          - \`soundtouch-cli-v$TAG_NAME-platform.sha512\`
-
-          \`\`\`bash
-          # Download binary + its individual checksum
-          curl -L -O https://github.com/.../soundtouch-cli-v$TAG_NAME-linux-amd64
-          curl -L -O https://github.com/.../soundtouch-cli-v$TAG_NAME-linux-amd64.sha256
-
-          # Verify with individual checksum
-          sha256sum -c soundtouch-cli-v$TAG_NAME-linux-amd64.sha256
-          \`\`\`
-
-          ## 🤝 Contributing
-
-          Contributions welcome! See our documentation for examples and patterns.
-
-          ## 📄 License
-
-          MIT License - see [LICENSE](LICENSE) file.
           EOF
 
           echo "release_notes_file=release_notes.md" >> $GITHUB_OUTPUT
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
-          tag_name: ${{ github.event.inputs.tag }}
-          name: "Bose SoundTouch Go Library ${{ github.event.inputs.tag }}"
+          tag_name: ${{ needs.validate.outputs.tag }}
+          name: ${{ needs.validate.outputs.tag }}
           body_path: ${{ steps.release_notes.outputs.release_notes_file }}
+          generate_release_notes: true
           draft: false
           prerelease: ${{ needs.validate.outputs.is_prerelease == 'true' }}
           files: |
             release-assets/soundtouch-cli-v*
             release-assets/soundtouch-service-v*
-            release-assets/soundtouch-web-v*
+            release-assets/soundtouch-player-v*
             release-assets/soundtouch-backup-v*
             release-assets/checksums.sha256
             release-assets/checksums.sha512
@@ -493,20 +424,70 @@ jobs:
     if: github.event_name == 'release' && github.event.action == 'published'
 
     steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.tag }}
+
       - name: Download release assets
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: release-assets
           path: ./release-assets
 
+      - name: Upgrade the Downloads footer with direct per-platform links
+        # This is the path real releases take: a maintainer hand-writes
+        # "Noteworthy" notes and publishes via the GitHub web UI, which
+        # fires this job, not create_release (workflow_dispatch only).
+        # _/releases/_TEMPLATE.md's convention is a trailing footer line:
+        #   ---
+        #   📦 **Downloads / installation:** <downloads page URL>
+        # Drop that line (if present) and append the quick-downloads
+        # block in its place. Always goes through the same append path
+        # (strip block + strip footer + append), whether or not a
+        # footer line is still there, so re-runs stay byte-for-byte
+        # idempotent instead of drifting on the 2nd run.
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG_NAME="${{ needs.validate.outputs.tag }}"
+
+          scripts/release/quick-downloads.sh "$TAG_NAME" "${{ github.repository }}" > quick_downloads.md
+          gh release view "$TAG_NAME" --json body -q .body > existing_body.md
+
+          python3 - << 'PYEOF'
+          import re
+
+          with open("existing_body.md") as f:
+              body = f.read()
+          with open("quick_downloads.md") as f:
+              block = f.read().rstrip("\n")
+
+          # Drop a block this automation inserted on a previous run.
+          body = re.sub(r"\n*<!-- quick-downloads:start -->.*?<!-- quick-downloads:end -->\n*", "\n", body, flags=re.DOTALL)
+
+          # Drop the hand-authored footer line (first run only) so both
+          # cases converge on the same append below and re-runs stay
+          # byte-for-byte idempotent.
+          footer = re.compile(r"^📦 \*\*Downloads / installation:\*\*.*\n?", re.MULTILINE)
+          body = footer.sub("", body, count=1)
+
+          body = body.rstrip("\n") + "\n\n" + block + "\n"
+
+          with open("combined_notes.md", "w") as f:
+              f.write(body)
+          PYEOF
+
+          gh release edit "$TAG_NAME" --notes-file combined_notes.md
+
       - name: Upload additional assets to existing release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
-          tag_name: ${{ github.event.release.tag_name }}
+          tag_name: ${{ needs.validate.outputs.tag }}
           files: |
             release-assets/soundtouch-cli-v*
             release-assets/soundtouch-service-v*
-            release-assets/soundtouch-web-v*
+            release-assets/soundtouch-player-v*
             release-assets/soundtouch-backup-v*
             release-assets/checksums.sha256
             release-assets/checksums.sha512
@@ -521,13 +502,22 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.tag }}
+
+      - name: Set build metadata
+        id: build_date
+        run: |
+          echo "date=$(date -u +%Y-%m-%d)" >> $GITHUB_OUTPUT
+          # Commit of the checked-out tag, not github.sha (the dispatch HEAD).
+          echo "commit=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
@@ -535,7 +525,7 @@ jobs:
 
       - name: Extract metadata (tags, labels) for soundtouch-service
         id: meta-service
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
@@ -544,7 +534,7 @@ jobs:
             type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}
 
       - name: Build and push soundtouch-service Docker image
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           target: soundtouch-service
@@ -552,28 +542,36 @@ jobs:
           push: true
           tags: ${{ steps.meta-service.outputs.tags }}
           labels: ${{ steps.meta-service.outputs.labels }}
+          build-args: |
+            VERSION=${{ needs.validate.outputs.tag }}
+            COMMIT=${{ steps.build_date.outputs.commit }}
+            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@v6
+      - name: Extract metadata (tags, labels) for soundtouch-player
+        id: meta-player
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
         with:
-          images: ghcr.io/${{ github.repository }}-web
+          images: ghcr.io/${{ github.repository }}-player
           tags: |
             type=semver,pattern={{version}},value=v${{ needs.validate.outputs.version }}
             type=semver,pattern={{major}}.{{minor}},value=v${{ needs.validate.outputs.version }}
             type=raw,value=latest,enable=${{ needs.validate.outputs.is_prerelease == 'false' }}
 
-      - name: Build and push soundtouch-web Docker image
-        uses: docker/build-push-action@v7
+      - name: Build and push soundtouch-player Docker image
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
-          target: soundtouch-web
+          target: soundtouch-player
           platforms: linux/amd64,linux/arm64,linux/arm64/v8,linux/arm/v7
           push: true
-          tags: ${{ steps.meta-web.outputs.tags }}
-          labels: ${{ steps.meta-web.outputs.labels }}
+          tags: ${{ steps.meta-player.outputs.tags }}
+          labels: ${{ steps.meta-player.outputs.labels }}
+          build-args: |
+            VERSION=${{ needs.validate.outputs.tag }}
+            COMMIT=${{ steps.build_date.outputs.commit }}
+            DATE=${{ steps.build_date.outputs.date }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
 
@@ -587,12 +585,12 @@ jobs:
       - name: Notify success
         run: |
           echo "🎉 Release ${{ needs.validate.outputs.version }} completed successfully!"
-          echo "📦 Binaries built for 7 platforms (CLI, Service, Web, and Backup)"
+          echo "📦 Binaries built for 7 platforms (CLI, Service, Player, and Backup)"
           echo "🐳 Docker image published to ghcr.io"
           echo "🔐 Checksums generated and verified"
           echo "📋 Release notes automatically generated"
           echo ""
-          TAG_NAME="${{ github.event.inputs.tag || github.event.release.tag_name }}"
+          TAG_NAME="${{ needs.validate.outputs.tag }}"
           echo "🔗 Release URL: https://github.com/${{ github.repository }}/releases/tag/${TAG_NAME}"
           echo ""
           echo "Next steps:"

.github/workflows/security.yml

@@ -19,20 +19,18 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
       - 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@v7
-        with:
-          name: vulnerability-scan-results
-          path: |
-            vulnerability-report.json
-            nancy-report.json
-
   static-analysis:
     name: Static Security Analysis
     runs-on: ubuntu-latest
@@ -63,10 +46,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up Go
-        uses: actions/setup-go@v6
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
         with:
           go-version-file: "go.mod"
 
@@ -84,7 +67,7 @@ jobs:
           echo "::endgroup::"
 
       - name: Run Semgrep security analysis
-        uses: semgrep/semgrep-action@v1
+        uses: semgrep/semgrep-action@713efdd345f3035192eaa63f56867b88e63e4e5d # v1 (no v1.x.y semver tag exists)
         with:
           config: >-
             p/security-audit
@@ -95,40 +78,11 @@ jobs:
 
       - name: Upload Semgrep SARIF results
         if: always()
-        uses: github/codeql-action/upload-sarif@v4
+        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         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@v6
-
-      - name: Install libpcap
-        run: sudo apt-get install -y libpcap-dev
-
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4
-        with:
-          languages: go
-          config-file: ./.github/codeql-config.yml
-
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v4
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v4
-        with:
-          category: "/language:go"
-
   dependency-review:
     name: Dependency Review
     runs-on: ubuntu-latest
@@ -138,10 +92,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Dependency Review
-        uses: actions/dependency-review-action@v4
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
         with:
           fail-on-severity: moderate
           allow-ghsas: GHSA-xxxx-xxxx-xxxx  # Add specific allowlisted advisories if needed
@@ -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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.head_ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.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

@@ -15,13 +15,17 @@ dist/
 /soundtouch-backup
 /soundtouch-cli
 /soundtouch-service
+/soundtouch-player
 /soundtouch-web
+/dummy-speaker
 /example-mdns
 /example-upnp
 /example-unified
+/example-dlna-server
 /mdns-scanner
 /websocket-demo
 /main
+/screenshots
 
 # Environment configuration
 .env
@@ -41,10 +45,14 @@ go.work.sum
 
 # Dependency directories
 vendor/
+node_modules/
 
 # IDE and editor files
 .vscode/
 .idea/
+.claude/*
+!.claude/commands/
+.junie/
 *.swp
 *.swo
 *~
@@ -96,3 +104,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

@@ -1,5 +1,5 @@
 # golangci-lint configuration for Bose SoundTouch Go Library
-# Compatible with golangci-lint v2.8.0
+# Compatible with golangci-lint v2.13.1
 # See: https://golangci-lint.run/usage/configuration/
 
 version: "2"
@@ -78,6 +78,13 @@ linters:
         linters:
           - errcheck
 
+      # Carry-over from cmd/soundtouch-player/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,272 @@
+# 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-player` — 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-player   # Just web player
+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.
+
+## Decrypting diagnostic reports
+
+Reporters attach an encrypted diagnostic archive
+(`aftertouch-diagnostic-*.age`), usually saved under `_/i_<reporter>/`.
+Decrypt it with **this repo's own tool**, not the generic `age` CLI:
+
+```bash
+go run scripts/decrypt-diagnostic.go <file.age> | tar xz -C <dir containing the .age>
+```
+
+- The tool is `scripts/decrypt-diagnostic.go`; the private key lives at
+  `keys/private/diagnostic` (provisioned by `scripts/setup-diagnostic-key.sh`,
+  and never committed). It writes the decrypted `.tar.gz` to stdout.
+- Always decrypt/unpack next to the `.age` (not a scratch/tmp dir), into a
+  **per-file subfolder** so nothing collides: e.g.
+  `mkdir -p <dir>/extracted-<timestamp> && go run scripts/decrypt-diagnostic.go <dir>/<file>.age | tar xz -C <dir>/extracted-<timestamp>`.
+  This matters when a reporter folder holds multiple `.age` snapshots or
+  already has other files: every archive uses the same inner names
+  (`diagnostic.json`, `datastore/`, `http/`, ...), so extracting two into the
+  same dir overwrites and mixes them.
+- The archive contains `diagnostic.json` (health/device summary), `datastore/`
+  (raw speaker XML: DeviceInfo/Presets/Recents/Sources), `http/` (service
+  `full.xml`, `sourceproviders.xml`, captured speaker responses), `logs/`,
+  `settings.json`, `env.txt`, `system/`, `ssh/`. See
+  `docs/content/docs/appendix/DIAGNOSTIC-EXPORT.md`.
+- Reporter data stays under `_/` and is never committed (see "What never goes
+  into this repo").
+
+## Project structure
+
+```
+cmd/
+  soundtouch-cli/      # CLI tool for device control
+  soundtouch-service/  # Local cloud service emulator
+  soundtouch-player/      # 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

@@ -1,478 +1,185 @@
-# Contributing to Bose SoundTouch API Client
+# Contributing to AfterTouch
 
-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.
+Thank you for your interest in contributing to **AfterTouch**!
 
-## Table of Contents
+AfterTouch is a community-built toolkit that keeps Bose SoundTouch speakers
+usable after Bose shut down the SoundTouch cloud. It is a Go codebase that ships
+several tools plus a reusable library:
 
-- [Code of Conduct](#code-of-conduct)
-- [Getting Started](#getting-started)
-- [How Can I Contribute?](#how-can-i-contribute)
-- [Development Setup](#development-setup)
-- [Pull Request Process](#pull-request-process)
-- [Coding Guidelines](#coding-guidelines)
-- [Testing Guidelines](#testing-guidelines)
-- [Documentation Guidelines](#documentation-guidelines)
-- [Reporting Issues](#reporting-issues)
-- [Device Testing](#device-testing)
-- [Community](#community)
+- **soundtouch-service** the local cloud replacement (emulates `streaming.bose.com` and the `bmx` services)
+- **soundtouch-cli** command-line control of one or more speakers
+- **soundtouch-player** the web UI for radio browsing and device control
+- **soundtouch-backup** on-device backup and restore helper
+- **pkg/** the underlying Go library (HTTP + WebSocket client, models, discovery, ...)
+
+We are an open community: we both provide and ask for support. Contributions of
+every size are welcome, and you do not need to be a Go developer to help.
+
+## Ways to contribute
+
+- **Bug reports** even a clear reproducer is a real contribution. An attached
+  diagnostic report (see [Reporting issues](#reporting-issues)) helps enormously.
+- **Device compatibility reports** tell us how AfterTouch behaves with your speaker model.
+- **Code** bug fixes, features, refactoring, tests, tooling.
+- **Documentation** guides, examples, troubleshooting notes, inline doc comments.
+- **Helping others** answering questions in [Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions).
+- **Donations** if AfterTouch kept a speaker (or several) of yours alive and you
+  want to give back, [GitHub Sponsors](https://github.com/sponsors/gesellix) is
+  open. There is no expectation, and everything here stays MIT regardless.
+
+By submitting a code or documentation contribution you agree to license it under
+the project's [MIT License](LICENSE).
 
 ## Code of Conduct
 
-This project adheres to our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.
+This project follows a [Code of Conduct](CODE_OF_CONDUCT.md). By participating,
+you agree to uphold it. Please report unacceptable behavior to the maintainer.
 
-## Getting Started
+## Getting started
 
 ### Prerequisites
 
-- **Go 1.25.6 or later**: [Download Go](https://golang.org/dl/)
-- **Git**: For version control
-- **Make**: For build automation (optional but recommended)
-- **SoundTouch Device**: For testing (optional but valuable)
+- **Go** (version per [`go.mod`](go.mod), currently the 1.26.x series)
+- **Git**
+- **Make** (recommended; drives builds and the quality gate)
+- **Docker** (only needed for the HTTP-client integration tests)
+- A **SoundTouch device** is optional but valuable for testing
 
-### First Contribution
-
-1. **Fork the repository** on GitHub
-2. **Clone your fork** locally:
-   ```bash
-   git clone https://github.com/YOUR-USERNAME/Bose-SoundTouch.git
-   cd Bose-SoundTouch
-   ```
-3. **Install dependencies**:
-   ```bash
-   go mod download
-   ```
-4. **Run tests** to ensure everything works:
-   ```bash
-   make test
-   # or
-   go test ./...
-   ```
-5. **Build the CLI** to test functionality:
-   ```bash
-   make build
-   ./soundtouch-cli --help
-   ```
-
-## How Can I Contribute?
-
-### 🐛 Reporting Bugs
-
-Before creating a bug report, please:
-
-1. **Check existing issues** to avoid duplicates
-2. **Test with the latest version** from the main branch
-3. **Include device information** (model, firmware version if known)
-
-When filing a bug report, include:
-
-- **Clear title** describing the issue
-- **Steps to reproduce** the behavior
-- **Expected behavior** vs actual behavior
-- **Environment details**: OS, Go version, device model
-- **Log output** if applicable (use `--verbose` flag)
-
-### 💡 Suggesting Features
-
-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))
-3. **Explain the use case** and how it benefits users
-
-### 🔧 Contributing Code
-
-Areas where contributions are especially welcome:
-
-#### High Priority
-- **Bug fixes** for existing functionality
-- **Device compatibility** improvements
-- **Error handling** enhancements
-- **Performance optimizations**
-
-#### Medium Priority
-- **New endpoint implementations** (if officially documented)
-- **CLI improvements** (better UX, additional commands)
-- **Documentation improvements**
-- **Example applications**
-
-#### Future Enhancements
-- **Web interface** development
-- **Home Assistant integration**
-- **WASM/browser support**
-- **Mobile app development**
-
-## Development Setup
-
-### Project Structure
-
-```
-Bose-SoundTouch/
-├── cmd/                    # Command-line applications
-│   ├── soundtouch-cli/    # Main CLI tool
-│   └── examples/          # Example applications
-├── pkg/                   # Library packages
-│   ├── client/           # HTTP client implementation
-│   ├── discovery/        # Device discovery
-│   ├── models/           # Data structures
-│   └── config/           # Configuration management
-├── docs/                 # Documentation
-├── examples/             # Usage examples
-└── scripts/              # Build and utility scripts
-```
-
-### Development Commands
+### Build and run
 
 ```bash
-# Run tests
-make test
+# Clone your fork
+git clone https://github.com/YOUR-USERNAME/Bose-SoundTouch.git
+cd Bose-SoundTouch
 
-# Run tests with coverage
-make test-coverage
-
-# Build all binaries
+# Build all binaries into ./build/
 make build
 
-# Run linting and formatting
-make check
+# Try the CLI
+./build/soundtouch-cli --help
 
-# Run golangci-lint specifically
-golangci-lint run
-
-# Auto-fix linting issues where possible
-golangci-lint run --fix
-
-# Install CLI locally
-go install ./cmd/soundtouch-cli
-
-# Run integration tests (requires real device)
-make test-integration HOST=192.168.1.100
+# Run the local service on port 8000
+make dev-service
 ```
 
-### Environment Setup
+Other useful targets: `make build-cli`, `make build-service`, `make build-player`,
+`make dev-discover` (find devices on the LAN). See the `Makefile` for the full list.
 
-For development with real devices, create a `.env` file:
+## Development workflow
 
-```env
-# Optional: Pre-configured device for testing
-SOUNDTOUCH_HOST=192.168.1.100
-SOUNDTOUCH_PORT=8090
-
-# Optional: Enable debug logging
-SOUNDTOUCH_DEBUG=true
-```
-
-## Pull Request Process
-
-### Before Submitting
-
-1. **Create an issue** first for significant changes
-2. **Fork and create a feature branch**:
+1. For anything non-trivial, **open an issue first** so we can agree on the approach.
+2. Create a feature branch from `main`.
+3. Make small, focused changes with tests.
+4. Run the quality gate before pushing:
    ```bash
-   git checkout -b feature/your-feature-name
-   ```
-3. **Write tests** for your changes
-4. **Update documentation** if needed
-5. **Run the full test suite**:
-   ```bash
-   make check
-   make test
+   make check   # fmt + vet + tests (+ the Docker-based HTTP-client integration suite)
+   make lint    # golangci-lint, must be clean
    ```
+   If you do not have Docker handy, run `make test` and `make lint` and say so in
+   the PR; CI runs the full gate on every PR.
+5. Open a pull request. The PR template walks you through what to include.
 
-### Pull Request Guidelines
+New to the codebase? **[`CLAUDE.md`](CLAUDE.md)** is the entry point for any
+session (human or AI): it explains the layout, build/test commands, and the
+load-bearing gotchas. Please skim it before larger changes.
 
-1. **Clear title** describing the change
-2. **Detailed description** explaining:
-   - What the change does
-   - Why it's needed
-   - How it was tested
-   - Any breaking changes
-3. **Link to related issues**
-4. **Update CHANGELOG.md** if applicable
-5. **Ensure CI passes**
+### A note on AI-assisted contributions
 
-### Review Process
+AI and agent-assisted code is welcome, we use it here too. What we cannot accept
+is unreviewed "slop": large generated diffs the author has not read, run, or
+understood. Keep PRs small and focused, make sure `make check` passes, and be
+ready to explain your changes during review.
 
-- At least one maintainer will review your PR
-- Feedback will be constructive and specific
-- Address feedback in additional commits
-- Once approved, a maintainer will merge your PR
+### Never commit personal or device data
 
-## Coding Guidelines
+This repository is public. Do not commit real LAN IPs, MAC addresses, device IDs,
+Bose account IDs, tokens, firmware binaries, or Wi-Fi credentials, in code, tests,
+fixtures, commit messages, or PR text. Use the RFC-5737 documentation ranges
+(`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`) and placeholder identifiers
+in examples. See [`CLAUDE.md`](CLAUDE.md) for the full list.
 
-### Go Style
+## Coding and testing guidelines
 
-Follow standard Go conventions:
+- **Follow standard Go style:** `gofmt`, `go vet`, and `golangci-lint` all clean.
+  `golangci-lint run --fix` auto-fixes some issues.
+- **Tests are expected** with every change. Prefer unit tests with `httptest`
+  mocks; use integration tests where a unit test is impractical.
+- **Use real device data for fixtures where possible,** anonymized per the rule
+  above. Reproducer tests should graduate into permanent regression or
+  documentation tests rather than being deleted.
+- **Wrap errors with context** (`fmt.Errorf("...: %w", err)`) and validate inputs
+  with helpful messages.
+- **Keep it simple.** Favor readable, self-explanatory code over cleverness.
+- **The SoundTouch Web API is XML on the wire;** internal service-to-service
+  messages are JSON. (One sharp edge: the `ETag` response header must keep its
+  exact capitalization, see `CLAUDE.md`.)
 
-- **gofmt** for formatting
-- **golangci-lint** for comprehensive code quality checks
-- **go vet** for static analysis
-- **Effective Go** principles
-- **Standard library patterns** where applicable
+## Reporting issues
 
-### Code Organization
+Open a [new issue](https://github.com/gesellix/Bose-SoundTouch/issues) and pick
+one of the forms; they keep reports easy to triage:
 
-```go
-// Package-level documentation
-package client
+- **Bug report** something in AfterTouch is not working as it should
+- **Feature request** an idea or improvement
+- **Device compatibility report** how AfterTouch behaves with your speaker model
 
-import (
-    // Standard library first
-    "context"
-    "encoding/xml"
-    
-    // Third-party packages
-    "github.com/gorilla/websocket"
-    
-    // Local packages
-    "github.com/gesellix/bose-soundtouch/pkg/models"
-)
+For bugs, the most helpful thing you can attach is an **encrypted diagnostic
+report**. In the AfterTouch admin UI, open the **Health tab** and click
+**Download diagnostic report**. The file is encrypted to the maintainer's key, so
+only the maintainer can open it.
 
-// Public API should be well-documented
-// GetDeviceInfo retrieves comprehensive device information including
-// model, capabilities, network status, and current configuration.
-func (c *Client) GetDeviceInfo() (*models.DeviceInfo, error) {
-    // Implementation
-}
-```
+To share it, the Health tab recommends **email**: send it to
+<aftertouch-support@gesellix.net>. You can also attach it to a GitHub issue, but
+GitHub blocks `.age` uploads, so rename the file to `.age.txt` (or zip it) first.
 
-### Error Handling
+To be transparent about what it holds: the structured summary (`diagnostic.json`)
+and `settings.json` have credentials and OAuth secrets redacted, but the raw
+datastore files (for example `Sources.xml` and `full.xml`) are included **as-is**.
+For TuneIn, Radio Browser, and Local Internet Radio those carry only
+AfterTouch-generated placeholders, but for **linked accounts such as Spotify or
+Amazon they can contain the access tokens your speaker uses**. There is currently
+no setting that redacts the datastore files. If that is a concern, unlink those
+services before exporting, or email the report privately rather than attaching it
+to a public issue.
 
-- **Return errors** instead of panicking
-- **Wrap errors** with context using `fmt.Errorf`
-- **Create custom error types** for specific conditions
-- **Validate inputs** and return helpful error messages
+Before filing, the
+[Troubleshooting Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/TROUBLESHOOTING/)
+often has the answer. For "how do I...?" questions, please use
+[Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) rather than
+the issue tracker.
 
-```go
-// Good error handling example
-func (c *Client) SetVolume(level int) error {
-    if level < 0 || level > 100 {
-        return fmt.Errorf("volume level %d out of range [0-100]", level)
-    }
-    
-    if err := c.post("/volume", volumeXML); err != nil {
-        return fmt.Errorf("failed to set volume to %d: %w", level, err)
-    }
-    
-    return nil
-}
-```
+### Security issues
 
-### API Design
-
-- **Consistent method naming**: `Get*`, `Set*`, `Send*`, etc.
-- **Return pointers** for complex types, values for simple types
-- **Accept contexts** for potentially long-running operations
-- **Provide convenience methods** for common operations
-
-## Testing Guidelines
-
-### Test Structure
-
-```go
-func TestClient_SetVolume(t *testing.T) {
-    tests := []struct {
-        name          string
-        volume        int
-        expectedError string
-        setupMock     func(*httptest.Server)
-    }{
-        {
-            name:   "valid volume level",
-            volume: 50,
-            setupMock: func(server *httptest.Server) {
-                // Mock setup
-            },
-        },
-        {
-            name:          "volume too high",
-            volume:        150,
-            expectedError: "volume level 150 out of range",
-        },
-    }
-    
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            // Test implementation
-        })
-    }
-}
-```
-
-### Test Categories
-
-1. **Unit Tests**: Test individual functions with mocks
-2. **Integration Tests**: Test with real devices (when available)
-3. **Benchmark Tests**: Performance testing for critical paths
-
-### Mock Usage
-
-Use `httptest.Server` for HTTP client testing:
-
-```go
-func setupMockServer() *httptest.Server {
-    return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-        switch r.URL.Path {
-        case "/info":
-            w.Header().Set("Content-Type", "application/xml")
-            fmt.Fprint(w, mockDeviceInfoXML)
-        default:
-            w.WriteHeader(http.StatusNotFound)
-        }
-    }))
-}
-```
-
-### Real Device Testing
-
-When possible, test with real SoundTouch devices:
-
-```bash
-# Set device IP for integration tests
-export SOUNDTOUCH_HOST=192.168.1.100
-go test -tags integration ./pkg/client/
-```
-
-## Documentation Guidelines
-
-### Code Documentation
-
-- **Package documentation** for every package
-- **Function documentation** for all public functions
-- **Example documentation** for complex usage
-
-```go
-// Package client provides a comprehensive HTTP client for the Bose SoundTouch Web API.
-//
-// The client supports all documented SoundTouch endpoints including device information,
-// playback control, volume management, and real-time WebSocket events.
-//
-// Basic usage:
-//
-//     client := client.NewClient(&client.Config{
-//         Host: "192.168.1.100",
-//         Port: 8090,
-//     })
-//     
-//     info, err := client.GetDeviceInfo()
-//     if err != nil {
-//         log.Fatal(err)
-//     }
-//     
-//     fmt.Printf("Device: %s\n", info.Name)
-package client
-```
-
-### User Documentation
-
-- **README.md**: Overview and quick start
-- **API documentation**: Comprehensive endpoint reference
-- **Examples**: Real-world usage patterns
-- **Troubleshooting**: Common issues and solutions
-
-### Documentation Updates
-
-When making changes:
-
-1. **Update relevant docs** in the same PR
-2. **Include usage examples** for new features
-3. **Update CLI help text** if applicable
-4. **Test documentation** (ensure examples work)
-
-## Device Testing
-
-### Supported Devices
-
-The library has been tested with:
-
-- **SoundTouch 10** (firmware unknown)
-- **SoundTouch 20** (firmware unknown)
-
-### Testing New Devices
-
-If you have access to other SoundTouch models:
-
-1. **Run discovery** to find devices:
-   ```bash
-   ./soundtouch-cli discover devices
-   ```
-
-2. **Test basic functionality**:
-   ```bash
-   ./soundtouch-cli -h 192.168.1.100 info get
-   ./soundtouch-cli -h 192.168.1.100 now-playing get
-   ```
-
-3. **Report compatibility** in your PR or issue
-4. **Include device information** from the info endpoint
-
-### Testing Protocol
-
-For significant changes:
-
-1. **Test on multiple devices** if available
-2. **Test error scenarios** (device offline, network issues)
-3. **Test edge cases** (invalid inputs, boundary conditions)
-4. **Document any device-specific behavior**
-
-## Reporting Issues
-
-### Security Issues
-
-**Do not open public issues for security vulnerabilities.** Instead:
-
-1. **Email the maintainers** with details
-2. **Allow reasonable time** for response
-3. **Coordinate disclosure** timing
-
-### Bug Reports
-
-Use the bug report template and include:
-
-- **Device model and firmware** (if known)
-- **Complete error messages and logs**
-- **Minimal reproduction case**
-- **Environment information**
-
-### Feature Requests
-
-Use the feature request template and include:
-
-- **Clear description** of the desired functionality
-- **Use case explanation** 
-- **API documentation reference** (if applicable)
-- **Alternative solutions** you've considered
+Please do not open a public issue for a security vulnerability. Report it
+privately to the maintainer (GitHub's private vulnerability reporting on the
+repository's Security tab is the preferred channel) and allow reasonable time for
+a fix before any public disclosure.
 
 ## Community
 
-### Communication Channels
+- **Discussions:** questions, ideas, and general support
+- **Issues:** bugs, feature requests, compatibility reports
+- **Pull requests:** code and documentation
 
-- **GitHub Issues**: Bug reports, feature requests
-- **GitHub Discussions**: Questions, ideas, general discussion
-- **Pull Requests**: Code contributions and reviews
+Please be patient and respectful in all interactions. Significant contributions
+are credited in release notes.
 
-### Getting Help
+## Support the project
 
-1. **Check existing documentation** first
-2. **Search closed issues** for similar problems
-3. **Create a new issue** with detailed information
-4. **Be patient and respectful** in all interactions
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/gesellix?label=Sponsor%20on%20GitHub&logo=GitHub&color=ea4aaa)](https://github.com/sponsors/gesellix)
 
-### Recognition
+Sponsorship is entirely optional. Code, docs, bug reports, and helping others
+remain the most useful contributions.
 
-Contributors will be:
+## Resources
 
-- **Listed in CONTRIBUTORS.md**
-- **Mentioned in release notes** for significant contributions
-- **Credited in documentation** where appropriate
-
-## 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)
-- [Development Status](docs/archive/STATUS.md)
+- [AfterTouch documentation](https://gesellix.github.io/Bose-SoundTouch/)
+- [Survival Guide](https://gesellix.github.io/Bose-SoundTouch/docs/guides/SURVIVAL-GUIDE/)
+- [API Cookbook](https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-COOKBOOK/)
+- [API Endpoints](https://gesellix.github.io/Bose-SoundTouch/docs/reference/API-ENDPOINTS/)
+- [Go Documentation](https://golang.org/doc/) and [Effective Go](https://golang.org/doc/effective_go.html)
 
 ---
 
-**Thank you for contributing!** Every contribution helps make this library better for the entire SoundTouch community.
+**Thank you for contributing!** Every contribution helps keep the SoundTouch
+community's speakers playing.

Dockerfile

@@ -1,5 +1,5 @@
 # Build stage
-FROM --platform=$BUILDPLATFORM golang:1.26.3-alpine AS builder
+FROM --platform=$BUILDPLATFORM golang:1.27.0-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,23 +25,38 @@ 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
+# Build the soundtouch-player (formerly 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-player ./cmd/soundtouch-player; \
     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-player ./cmd/soundtouch-player; \
     fi
 
 # soundtouch-service image
-FROM alpine:3.23 AS soundtouch-service
+FROM alpine:3.24 AS soundtouch-service
 
 RUN apk add --no-cache ca-certificates tzdata
 
+# Non-root prep (dormant). Everything below is set up so the service CAN run
+# as a fixed non-root user, but the image still runs as root by default
+# (APP_USER below) so this is not a breaking change yet. The UID/GID is pinned
+# (65532) so a mounted data volume's ownership stays predictable.
+RUN addgroup -g 65532 -S aftertouch \
+    && adduser -u 65532 -S -G aftertouch -H -h /app aftertouch
+
 WORKDIR /app
 
 COPY --from=builder /soundtouch-service /app/soundtouch-service
@@ -43,28 +64,51 @@ COPY --from=builder /soundtouch-service /app/soundtouch-service
 # Verify the binary works on the target platform
 RUN /app/soundtouch-service version || echo "Binary verification complete"
 
-RUN mkdir -p /app/data
+# Create the data dir and hand /app to the non-root user.
+RUN mkdir -p /app/data && chown -R aftertouch:aftertouch /app
+
+# Allow the non-root process to bind the privileged DNS port (:53) when DNS
+# Discovery is enabled, without granting the whole container extra privileges
+# at runtime. NET_BIND_SERVICE is in Docker's default capability set, so this
+# file capability is effective out of the box (no --cap-add needed). Done
+# after chown, which would otherwise clear it; the setcap tool is removed after.
+RUN apk add --no-cache --virtual .setcap libcap \
+    && setcap 'cap_net_bind_service=+ep' /app/soundtouch-service \
+    && apk del .setcap
 
 ENV PORT=8000
 ENV DATA_DIR=/app/data
 ENV LOG_PROXY_BODY=false
 ENV REDACT_PROXY_LOGS=true
 
+# The toggle. Defaults to root, so this image behaves exactly as before and
+# the change is non-breaking today. Enabling non-root is planned for v1.0.0
+# (BREAKING: a bind-mounted DATA_DIR must then be writable by uid 65532 — the
+# service logs the exact chown command at startup if it can't write). To
+# enable, either change this default to "aftertouch" (a one-line commit) or
+# build with --build-arg APP_USER=aftertouch.
+ARG APP_USER=root
+USER ${APP_USER}
+
 EXPOSE 8000
 
 ENTRYPOINT ["/app/soundtouch-service"]
 
-# soundtouch-web image
-FROM alpine:3.23 AS soundtouch-web
+# soundtouch-player image
+FROM alpine:3.24 AS soundtouch-player
 
 RUN apk add --no-cache ca-certificates tzdata
 
 WORKDIR /app
 
-COPY --from=builder /soundtouch-web /app/soundtouch-web
+COPY --from=builder /soundtouch-player /app/soundtouch-player
 
 ENV PORT=8080
 
 EXPOSE 8080
 
-ENTRYPOINT ["/app/soundtouch-web"]
+# The player is stateless and binds an unprivileged port, so it has no reason
+# to run as root. mDNS/SSDP discovery uses unprivileged multicast.
+USER nobody
+
+ENTRYPOINT ["/app/soundtouch-player"]

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
+.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
@@ -14,8 +17,8 @@ BINARY_NAME=soundtouch-cli
 BINARY_PATH=./cmd/$(BINARY_NAME)
 SERVICE_NAME=soundtouch-service
 SERVICE_PATH=./cmd/$(SERVICE_NAME)
-WEB_NAME=soundtouch-web
-WEB_PATH=./cmd/$(WEB_NAME)
+PLAYER_NAME=soundtouch-player
+PLAYER_PATH=./cmd/$(PLAYER_NAME)
 EXAMPLE_MDNS_NAME=example-mdns
 EXAMPLE_MDNS_PATH=./cmd/$(EXAMPLE_MDNS_NAME)
 EXAMPLE_UPNP_NAME=example-upnp
@@ -31,9 +34,25 @@ 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
+build: build-cli build-service build-player build-examples build-favicon-gen build-backup
 
 build-cli:
 	@echo "Building $(BINARY_NAME)..."
@@ -45,10 +64,10 @@ build-service:
 	@mkdir -p $(BUILD_DIR)
 	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(SERVICE_NAME) $(SERVICE_PATH)
 
-build-web:
-	@echo "Building $(WEB_NAME)..."
+build-player:
+	@echo "Building $(PLAYER_NAME)..."
 	@mkdir -p $(BUILD_DIR)
-	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(WEB_NAME) $(WEB_PATH)
+	$(GOBUILD) $(BUILDFLAGS) -o $(BUILD_DIR)/$(PLAYER_NAME) $(PLAYER_PATH)
 
 build-examples:
 	@echo "Building $(EXAMPLE_MDNS_NAME)..."
@@ -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=$$?; \
@@ -189,7 +243,7 @@ vet:
 
 lint:
 	@echo "Running golangci-lint..."
-	@which golangci-lint > /dev/null || (echo "golangci-lint not found. Install with: go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest" && exit 1)
+	@which golangci-lint > /dev/null || (echo "golangci-lint not found. Install with: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest" && exit 1)
 	golangci-lint run
 
 tidy:
@@ -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
@@ -268,17 +334,17 @@ dev-scan-http: build-examples
 	@echo "Scanning for HTTP mDNS services..."
 	$(BUILD_DIR)/$(SCANNER_NAME) -service _http._tcp -v
 
-dev-web: build-web
-	@echo "Starting web UI (default port 8080)..."
-	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME)
+dev-player: build-player
+	@echo "Starting web player (default port 8080)..."
+	cd cmd/soundtouch-player && ../../$(BUILD_DIR)/$(PLAYER_NAME)
 
-dev-web-port: build-web
-	@echo "Starting web UI on custom port..."
+dev-player-port: build-player
+	@echo "Starting web player on custom port..."
 	@if [ -z "$(PORT)" ]; then \
-		echo "Usage: make dev-web-port PORT=8888"; \
+		echo "Usage: make dev-player-port PORT=8888"; \
 		exit 1; \
 	fi
-	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -port $(PORT)
+	cd cmd/soundtouch-player && ../../$(BUILD_DIR)/$(PLAYER_NAME) -port $(PORT)
 
 dev-backup: build-backup
 	@echo "Running backup tool..."
@@ -292,21 +358,25 @@ dev-backup-local: build-backup
 	@echo "Running local backup (auto-discover)..."
 	$(BUILD_DIR)/$(BACKUP_NAME) local --discover
 
-dev-web-host: build-web
-	@echo "Starting web UI with specific host..."
+dev-player-host: build-player
+	@echo "Starting web player with specific host..."
 	@if [ -z "$(HOST)" ]; then \
-		echo "Usage: make dev-web-host HOST=192.168.1.10"; \
+		echo "Usage: make dev-player-host HOST=192.0.2.10"; \
 		exit 1; \
 	fi
-	cd cmd/soundtouch-web && ../../$(BUILD_DIR)/$(WEB_NAME) -host $(HOST)
+	cd cmd/soundtouch-player && ../../$(BUILD_DIR)/$(PLAYER_NAME) -host $(HOST)
 
-install: build-cli build-service build-web build-backup
+install: build-cli build-service build-player build-backup
 	@echo "Installing binaries to $(GOPATH)/bin..."
 	cp $(BUILD_DIR)/$(BINARY_NAME) $(GOPATH)/bin/
 	cp $(BUILD_DIR)/$(SERVICE_NAME) $(GOPATH)/bin/
-	cp $(BUILD_DIR)/$(WEB_NAME) $(GOPATH)/bin/
+	cp $(BUILD_DIR)/$(PLAYER_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."
@@ -336,6 +469,26 @@ docker-run-ports:
 	@echo "Running Docker container with port mapping (discovery will be manual)..."
 	docker run --rm -it -p 8000:8000 -v $$(pwd)/data:/app/data soundtouch-service
 
+screenshots:
+	@echo "Capturing documentation screenshots..."
+	@bash scripts/screenshots/run.sh
+
+# 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"
@@ -348,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"
@@ -356,6 +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"
@@ -370,22 +530,25 @@ help:
 	@echo "  dev-backup       - Build and show backup tool help"
 	@echo "  dev-backup-cloud - Build and run cloud backup (prompts for credentials)"
 	@echo "  dev-backup-local - Build and run local backup (auto-discover speakers)"
-	@echo "  dev-web          - Build and run web UI (default port 8080)"
-	@echo "  dev-web-port     - Build and run web UI on custom port (PORT=8888)"
-	@echo "  dev-web-host     - Build and run web UI with specific device (HOST=ip)"
+	@echo "  dev-player       - Build and run web player (default port 8080)"
+	@echo "  dev-player-port  - Build and run web player on custom port (PORT=8888)"
+	@echo "  dev-player-host  - Build and run web player with specific device (HOST=ip)"
 	@echo "  install       - Install binaries to GOPATH/bin"
 	@echo "  clean         - Clean build artifacts"
 	@echo "  release       - Create release binaries"
 	@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"
@@ -394,8 +557,8 @@ help:
 	@echo "  make dev-upnp-timeout TIMEOUT=10s"
 	@echo "  make dev-scan-all"
 	@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-player"
+	@echo "  make dev-player-port PORT=8888"
+	@echo "  make dev-player-host HOST=192.0.2.10"
 	@echo "  make test"
 	@echo "  make build-all"

README.md

@@ -1,16 +1,20 @@
-# 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, or jump straight to [Downloads](https://gesellix.github.io/Bose-SoundTouch/docs/downloads/) to get the tools.
+
+[![AfterTouch docs homepage](media/docs-homepage.png)](https://gesellix.github.io/Bose-SoundTouch/)
 
 ---
 
@@ -20,13 +24,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.
 
-**Two scenarios:**
+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.
 
-**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.
+**Getting started:**
 
-**After shutdown or factory reset — start fresh**
-Create a local account, configure your speakers, and start using them immediately. No Bose infrastructure required.
+**Already migrated before May 6** — your presets and credentials are preserved. AfterTouch picks up where the Bose cloud left off.
+
+**Starting fresh (or after a factory reset)** — create a local account, configure your speakers, and start using them immediately.
 
 **Redirecting your speaker**
 
@@ -45,7 +49,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.
 
 ---
 
@@ -61,15 +65,17 @@ 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, and the [Downloads page](https://gesellix.github.io/Bose-SoundTouch/docs/downloads/) to get the `soundtouch-cli` build for your OS.
 
 ---
 
-### soundtouch-web
+### soundtouch-player
 
-A standalone web UI for device control — play, pause, volume, preset selection, real-time status — served from a local Go binary. Complements `soundtouch-service` when you want a dedicated device-control interface separate from the setup/admin UI.
+> Formerly `soundtouch-web`. The `soundtouch-web` binary, Docker image, and install script are no longer published; please use `soundtouch-player`. (If you still run the binary under its old name, it prints a rename notice and works as before.)
 
-See the [soundtouch-web README](cmd/soundtouch-web/README.md) for usage.
+A standalone, LAN-resident web UI for device control — play, pause, volume, preset selection, real-time status — served from a local Go binary. Because it reaches speakers directly on your network and can delegate cloud-only features (e.g. TTS) to a remote AfterTouch service via `--service-url`, it stays useful when `soundtouch-service` runs off-LAN (for example in the cloud), where the embedded `/app` player cannot reach your speakers.
+
+See the [soundtouch-player README](cmd/soundtouch-player/README.md) for usage.
 
 ---
 
@@ -81,21 +87,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/)
 
 ---
 
@@ -106,6 +112,7 @@ See the [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API
 - **[SoundTouch Plus](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus)** (Todd Lucas) — Home Assistant integration; extensive undocumented API documentation
 - **[ÜberBöse API](https://github.com/julius-d/ueberboese-api)** (Julius) — API research and advanced endpoint discovery
 - **[Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook)** (Adrian Böckenkamp) — `LD_PRELOAD` hooking for reverse engineering device internals
+- **[STR, SoundTouch Reborn](https://github.com/JRpersonal/streborn)** ([st-reborn.de](https://st-reborn.de)) — on-device agent plus desktop app; its published `iptables` REDIRECT technique is what makes AfterTouch's on-device install reachable over the LAN on co-processor chassis (see [Model Support Matrix](https://gesellix.github.io/Bose-SoundTouch/docs/reference/MODEL-SUPPORT-MATRIX/))
 
 ---
 
@@ -120,8 +127,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

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

cmd/example-dlna-server/main.go

@@ -0,0 +1,741 @@
+// Package main runs a LAN-visible DLNA / UPnP MediaServer backed by the
+// dlnatest in-memory content tree.
+//
+// Usage:
+//
+//	example-dlna-server [--port 8200] [--name "My Library"]
+//
+// The server:
+//   - Binds an HTTP server on 0.0.0.0:<port> (default 8200).
+//   - Detects the host's primary LAN IPv4 to build the SSDP LOCATION header
+//     and the absolute <res> URLs inside DIDL-Lite Browse responses.
+//   - Joins the SSDP multicast group 239.255.255.250:1900 and answers
+//     M-SEARCH requests whose ST matches upnp:rootdevice, ssdp:all, or
+//     urn:schemas-upnp-org:device:MediaServer:1.
+//   - Periodically sends ssdp:alive NOTIFY announcements.
+//   - Sends ssdp:byebye on graceful shutdown (SIGINT / SIGTERM).
+package main
+
+import (
+	"bytes"
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"io/fs"
+	"log/slog"
+	"net"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/dlna/dlnatest"
+)
+
+const (
+	ssdpMulticastAddr = "239.255.255.250:1900"
+	ssdpMulticastIP   = "239.255.255.250"
+	ssdpPort          = 1900
+
+	mediaServerURN = "urn:schemas-upnp-org:device:MediaServer:1"
+	contentDirURN  = "urn:schemas-upnp-org:service:ContentDirectory:1"
+	notifyInterval = 30 * time.Second
+	ssdpMaxAge     = 1800
+	serverVersion  = "AfterTouch/1.0 UPnP/1.0 AfterTouchDLNA/1.0"
+)
+
+func main() {
+	port := flag.Int("port", 8200, "HTTP port to bind")
+	name := flag.String("name", "AfterTouch Test Library", "UPnP friendlyName advertised over SSDP")
+	mediaDir := flag.String("media-dir", "", "serve real audio files + artwork from this directory "+
+		"(searched recursively, so an artist/album tree works) instead of the built-in silent test "+
+		"tracks. Audio: .mp3/.wav/.flac/.m4a/.ogg. Art per track: a sibling <name>.jpg/.png, else a "+
+		"cover.jpg/cover.png/folder.jpg in the same album folder. Files are loaded into memory, so "+
+		"point it at an album or a modest folder, not your whole library")
+
+	flag.Parse()
+
+	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelDebug}))
+
+	lanIP, err := primaryLANIP()
+	if err != nil {
+		logger.Warn("could not detect LAN IP, falling back to loopback", "err", err)
+
+		lanIP = "127.0.0.1"
+	}
+
+	addr := fmt.Sprintf("0.0.0.0:%d", *port)
+	location := fmt.Sprintf("http://%s:%d/rootDesc.xml", lanIP, *port)
+
+	// Join the SSDP multicast group on the interface that owns the LAN IP. On
+	// macOS net.Interfaces() lists lo0 (UP+MULTICAST) first, so picking the
+	// "first" multicast interface would join on loopback and never receive the
+	// LAN M-SEARCH from clients like AfterTouch.
+	lanIface := interfaceForIP(lanIP)
+	if lanIface != nil {
+		logger.Info("SSDP: will join multicast on LAN interface", "iface", lanIface.Name, "ip", lanIP)
+	}
+
+	opts := []dlnatest.Option{dlnatest.WithFriendlyName(*name)}
+
+	if *mediaDir != "" {
+		tree, n, err := loadTreeFromDir(*mediaDir, *name)
+		if err != nil {
+			logger.Error("failed to load --media-dir", "dir", *mediaDir, "err", err)
+			os.Exit(1)
+		}
+
+		opts = append(opts, dlnatest.WithTree(tree))
+
+		logger.Info("serving real media from directory", "dir", *mediaDir, "tracks", n)
+	}
+
+	srv := dlnatest.NewServer(opts...)
+
+	httpSrv := &http.Server{
+		Addr:    addr,
+		Handler: withAccessLog(logger, srv.HTTPHandler()),
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	// Start HTTP server.
+	go func() {
+		logger.Info("HTTP server starting", "addr", addr, "lanIP", lanIP, "location", location)
+
+		if err := httpSrv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			logger.Error("HTTP server error", "err", err)
+		}
+	}()
+
+	// Give the HTTP listener a moment to bind before we advertise it.
+	time.Sleep(50 * time.Millisecond)
+
+	udn := srv.UDN
+
+	// Start SSDP listener + responder.
+	go runSSDPListener(ctx, logger, udn, location, lanIface)
+
+	// Start periodic ssdp:alive announcements.
+	go runSSDPAlive(ctx, logger, udn, location)
+
+	logger.Info("DLNA MediaServer ready", "location", location, "name", *name)
+
+	// Wait for shutdown signal.
+	<-ctx.Done()
+
+	logger.Info("shutting down...")
+
+	// Send byebye before exiting.
+	sendByebye(logger, udn)
+
+	shutCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err := httpSrv.Shutdown(shutCtx); err != nil {
+		logger.Error("HTTP shutdown error", "err", err)
+	}
+
+	logger.Info("stopped")
+}
+
+// ----------------------------------------------------------------------------
+// SSDP listener: answers M-SEARCH requests
+// ----------------------------------------------------------------------------
+
+func runSSDPListener(ctx context.Context, logger *slog.Logger, udn, location string, ifi *net.Interface) {
+	group := &net.UDPAddr{IP: net.ParseIP(ssdpMulticastIP), Port: ssdpPort}
+
+	// Join the group on the LAN interface. If we could not resolve it, fall back
+	// to the first non-loopback multicast interface (never loopback, which would
+	// only ever receive same-host loopback traffic).
+	if ifi == nil {
+		if cands, err := multicastInterfaces(); err == nil {
+			for _, c := range cands {
+				if c != nil && c.Flags&net.FlagLoopback == 0 {
+					ifi = c
+
+					break
+				}
+			}
+		}
+	}
+
+	conn, err := net.ListenMulticastUDP("udp4", ifi, group)
+	if err != nil {
+		logger.Warn("SSDP: ListenMulticastUDP failed (try running as root or check firewall)", "err", err)
+
+		return
+	}
+
+	defer conn.Close()
+
+	logger.Info("SSDP: listening for M-SEARCH on multicast", "group", group.String())
+
+	buf := make([]byte, 2048)
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+		}
+
+		_ = conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond))
+
+		n, src, err := conn.ReadFromUDP(buf)
+		if err != nil {
+			// Deadline timeout is expected; just continue.
+			continue
+		}
+
+		msg := string(buf[:n])
+		if !strings.HasPrefix(msg, "M-SEARCH") {
+			continue
+		}
+
+		st := extractHeader(msg, "ST")
+		logger.Debug("SSDP: M-SEARCH received", "from", src, "ST", st)
+
+		if !stMatches(st) {
+			continue
+		}
+
+		logger.Info("SSDP: answering M-SEARCH", "from", src, "ST", st)
+
+		reply := buildMSearchReply(udn, location, st)
+		_, _ = conn.WriteToUDP([]byte(reply), src)
+	}
+}
+
+// multicastInterfaces returns all UP interfaces that support multicast.
+func multicastInterfaces() ([]*net.Interface, error) {
+	all, err := net.Interfaces()
+	if err != nil {
+		return nil, err
+	}
+
+	var result []*net.Interface
+
+	for i := range all {
+		iface := &all[i]
+		if iface.Flags&net.FlagUp == 0 || iface.Flags&net.FlagMulticast == 0 {
+			continue
+		}
+
+		result = append(result, iface)
+	}
+
+	return result, nil
+}
+
+// stMatches returns true when the ST header should receive an M-SEARCH reply.
+func stMatches(st string) bool {
+	switch st {
+	case "ssdp:all", "upnp:rootdevice", mediaServerURN:
+		return true
+	}
+
+	return false
+}
+
+// buildMSearchReply builds an HTTP/1.1 200 OK SSDP response.
+func buildMSearchReply(udn, location, st string) string {
+	usn := usnForST(udn, st)
+
+	return fmt.Sprintf(
+		"HTTP/1.1 200 OK\r\n"+
+			"CACHE-CONTROL: max-age=%d\r\n"+
+			"DATE: %s\r\n"+
+			"EXT:\r\n"+
+			"LOCATION: %s\r\n"+
+			"SERVER: %s\r\n"+
+			"ST: %s\r\n"+
+			"USN: %s\r\n"+
+			"\r\n",
+		ssdpMaxAge,
+		time.Now().UTC().Format(http.TimeFormat),
+		location,
+		serverVersion,
+		st,
+		usn,
+	)
+}
+
+// usnForST builds the USN header value for a given ST.
+func usnForST(udn, st string) string {
+	if st == "upnp:rootdevice" || st == "ssdp:all" {
+		return udn + "::upnp:rootdevice"
+	}
+
+	return udn + "::" + st
+}
+
+// ----------------------------------------------------------------------------
+// SSDP alive announcements
+// ----------------------------------------------------------------------------
+
+func runSSDPAlive(ctx context.Context, logger *slog.Logger, udn, location string) {
+	// Send an initial batch immediately, then repeat on the interval.
+	sendAlive(logger, udn, location)
+
+	ticker := time.NewTicker(notifyInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			sendAlive(logger, udn, location)
+		}
+	}
+}
+
+func sendAlive(logger *slog.Logger, udn, location string) {
+	nts := []struct{ nt, usn string }{
+		{"upnp:rootdevice", udn + "::upnp:rootdevice"},
+		{udn, udn},
+		{mediaServerURN, udn + "::" + mediaServerURN},
+		{contentDirURN, udn + "::" + contentDirURN},
+	}
+
+	conn, err := net.Dial("udp4", ssdpMulticastAddr)
+	if err != nil {
+		logger.Warn("SSDP: cannot send alive notification", "err", err)
+
+		return
+	}
+
+	defer conn.Close()
+
+	for _, n := range nts {
+		msg := fmt.Sprintf(
+			"NOTIFY * HTTP/1.1\r\n"+
+				"HOST: %s\r\n"+
+				"CACHE-CONTROL: max-age=%d\r\n"+
+				"LOCATION: %s\r\n"+
+				"NT: %s\r\n"+
+				"NTS: ssdp:alive\r\n"+
+				"SERVER: %s\r\n"+
+				"USN: %s\r\n"+
+				"\r\n",
+			ssdpMulticastAddr, ssdpMaxAge, location,
+			n.nt, serverVersion, n.usn,
+		)
+		_, _ = conn.Write([]byte(msg))
+	}
+
+	logger.Debug("SSDP: alive announcements sent")
+}
+
+// ----------------------------------------------------------------------------
+// SSDP byebye on shutdown
+// ----------------------------------------------------------------------------
+
+func sendByebye(logger *slog.Logger, udn string) {
+	conn, err := net.Dial("udp4", ssdpMulticastAddr)
+	if err != nil {
+		logger.Warn("SSDP: cannot send byebye", "err", err)
+
+		return
+	}
+
+	defer conn.Close()
+
+	nts := []struct{ nt, usn string }{
+		{"upnp:rootdevice", udn + "::upnp:rootdevice"},
+		{udn, udn},
+		{mediaServerURN, udn + "::" + mediaServerURN},
+		{contentDirURN, udn + "::" + contentDirURN},
+	}
+
+	for _, n := range nts {
+		msg := fmt.Sprintf(
+			"NOTIFY * HTTP/1.1\r\n"+
+				"HOST: %s\r\n"+
+				"NT: %s\r\n"+
+				"NTS: ssdp:byebye\r\n"+
+				"USN: %s\r\n"+
+				"\r\n",
+			ssdpMulticastAddr, n.nt, n.usn,
+		)
+		_, _ = conn.Write([]byte(msg))
+	}
+
+	logger.Info("SSDP: byebye announcements sent")
+}
+
+// ----------------------------------------------------------------------------
+// Network helpers
+// ----------------------------------------------------------------------------
+
+// primaryLANIP returns the first non-loopback, non-link-local IPv4 address
+// found on any UP interface.
+func primaryLANIP() (string, error) {
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		return "", err
+	}
+
+	for _, iface := range ifaces {
+		if iface.Flags&net.FlagUp == 0 || iface.Flags&net.FlagLoopback != 0 {
+			continue
+		}
+
+		addrs, err := iface.Addrs()
+		if err != nil {
+			continue
+		}
+
+		for _, addr := range addrs {
+			ipNet, ok := addr.(*net.IPNet)
+			if !ok {
+				continue
+			}
+
+			v4 := ipNet.IP.To4()
+			if v4 == nil {
+				continue
+			}
+
+			if v4.IsLoopback() || v4.IsLinkLocalUnicast() {
+				continue
+			}
+
+			return v4.String(), nil
+		}
+	}
+
+	return "", fmt.Errorf("no usable LAN IPv4 address found")
+}
+
+// ----------------------------------------------------------------------------
+// --media-dir loader
+// ----------------------------------------------------------------------------
+
+// loadTreeFromDir walks dir recursively and builds a single flat content folder
+// from every audio file found, so an artist/album tree works. Album art for a
+// track is, in order of preference: a sibling <basename>.<img>, then a
+// cover.jpg/cover.png/folder.jpg in the track's own directory. Returns the tree
+// and track count.
+func loadTreeFromDir(dir, fallbackName string) (*dlnatest.Tree, int, error) {
+	rootClean := filepath.Clean(dir)
+
+	// Cache the resolved cover per directory so we read each album's folder.jpg
+	// once rather than for every track in it.
+	type cover struct {
+		data []byte
+		mime string
+	}
+
+	coverCache := map[string]cover{}
+
+	dirCover := func(d string) ([]byte, string) {
+		if c, ok := coverCache[d]; ok {
+			return c.data, c.mime
+		}
+
+		var c cover
+
+		for _, n := range []string{"cover.jpg", "cover.jpeg", "cover.png", "folder.jpg", "folder.png", "albumart.jpg", "albumart.png"} {
+			if b, err := os.ReadFile(filepath.Join(d, n)); err == nil {
+				c = cover{data: b, mime: imageMimeForExt(filepath.Ext(n))}
+
+				break
+			}
+		}
+
+		coverCache[d] = c
+
+		return c.data, c.mime
+	}
+
+	// Group tracks by their containing directory (preserving first-seen order),
+	// so each real album folder becomes its own browsable + playable container
+	// named after the directory, rather than one flat list named after --name.
+	type group struct {
+		dir   string
+		items []*dlnatest.Item
+	}
+
+	groups := map[string]*group{}
+
+	var order []string
+
+	total := 0
+
+	walkErr := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil || d.IsDir() {
+			return nil //nolint:nilerr // skip unreadable entries and directories
+		}
+
+		mime := audioMimeForExt(filepath.Ext(path))
+		if mime == "" {
+			return nil // not an audio file we recognise
+		}
+
+		payload, rerr := os.ReadFile(path)
+		if rerr != nil {
+			return nil //nolint:nilerr // skip unreadable file, keep walking
+		}
+
+		trackDir := filepath.Dir(path)
+		base := strings.TrimSuffix(d.Name(), filepath.Ext(d.Name()))
+
+		// Prefer a per-track image sibling; fall back to the album-folder cover.
+		art, artMime := dirCover(trackDir)
+
+		for _, ae := range []string{".jpg", ".jpeg", ".png", ".webp"} {
+			if b, aerr := os.ReadFile(filepath.Join(trackDir, base+ae)); aerr == nil {
+				art = b
+				artMime = imageMimeForExt(ae)
+
+				break
+			}
+		}
+
+		g := groups[trackDir]
+		if g == nil {
+			g = &group{dir: trackDir}
+			groups[trackDir] = g
+			order = append(order, trackDir)
+		}
+
+		g.items = append(g.items, &dlnatest.Item{
+			Title:      base,
+			Class:      "object.item.audioItem.musicTrack",
+			Artist:     artistForDir(trackDir, rootClean),
+			Album:      albumTitle(trackDir, rootClean, fallbackName),
+			MimeType:   mime,
+			Payload:    payload,
+			ArtPayload: art,
+			ArtMime:    artMime,
+		})
+		total++
+
+		return nil
+	})
+	if walkErr != nil {
+		return nil, 0, walkErr
+	}
+
+	if total == 0 {
+		return nil, 0, fmt.Errorf("no audio files (.mp3/.wav/.flac/.m4a/.ogg) found under %s", dir)
+	}
+
+	containers := make([]*dlnatest.Container, 0, len(order))
+
+	for ci, d := range order {
+		cid := strconv.Itoa(ci + 1)
+		g := groups[d]
+
+		for ti, it := range g.items {
+			it.ID = fmt.Sprintf("%s$%d", cid, ti)
+			it.ParentID = cid
+		}
+
+		containers = append(containers, &dlnatest.Container{
+			ID:       cid,
+			ParentID: "0",
+			Title:    albumTitle(d, rootClean, fallbackName),
+			Class:    "object.container.storageFolder",
+			Children: g.items,
+		})
+	}
+
+	return &dlnatest.Tree{Containers: containers}, total, nil
+}
+
+// albumTitle returns the display name for a track directory: the directory's own
+// name, or the fallback (the --name) when the tracks sit directly in the root.
+func albumTitle(trackDir, root, fallback string) string {
+	if filepath.Clean(trackDir) == root {
+		return fallback
+	}
+
+	return filepath.Base(trackDir)
+}
+
+// artistForDir derives the artist from the directory above the album folder
+// (e.g. <root>/<artist>/<album>/track.mp3 → "<artist>"). Falls back to
+// "Unknown Artist" when there is no artist level (album directly under root, or
+// tracks directly in root).
+func artistForDir(trackDir, root string) string {
+	clean := filepath.Clean(trackDir)
+	if clean == root {
+		return "Unknown Artist"
+	}
+
+	parent := filepath.Dir(clean)
+	if parent == root {
+		return "Unknown Artist"
+	}
+
+	return filepath.Base(parent)
+}
+
+// audioMimeForExt maps an audio file extension to a MIME type, or "" if the
+// extension is not a recognised audio format.
+func audioMimeForExt(ext string) string {
+	switch strings.ToLower(ext) {
+	case ".mp3":
+		return "audio/mpeg"
+	case ".wav":
+		return "audio/x-wav"
+	case ".flac":
+		return "audio/flac"
+	case ".m4a", ".mp4":
+		return "audio/mp4"
+	case ".ogg":
+		return "audio/ogg"
+	}
+
+	return ""
+}
+
+// imageMimeForExt maps an image file extension to a MIME type.
+func imageMimeForExt(ext string) string {
+	switch strings.ToLower(ext) {
+	case ".jpg", ".jpeg":
+		return "image/jpeg"
+	case ".png":
+		return "image/png"
+	case ".webp":
+		return "image/webp"
+	case ".gif":
+		return "image/gif"
+	}
+
+	return "application/octet-stream"
+}
+
+// ----------------------------------------------------------------------------
+// HTTP access logging (debugging aid)
+// ----------------------------------------------------------------------------
+
+// statusRecorder captures the status code and byte count of a response.
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+	bytes  int
+}
+
+func (r *statusRecorder) WriteHeader(code int) {
+	r.status = code
+	r.ResponseWriter.WriteHeader(code)
+}
+
+func (r *statusRecorder) Write(b []byte) (int, error) {
+	n, err := r.ResponseWriter.Write(b)
+	r.bytes += n
+
+	return n, err
+}
+
+// withAccessLog logs every HTTP request the server handles. For ContentDirectory
+// Browse POSTs it also surfaces the ObjectID and BrowseFlag so the speaker's
+// browse sequence (and whether it ever resolves a track's metadata) is visible.
+func withAccessLog(logger *slog.Logger, next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+
+		var browseAttrs []any
+
+		if r.Method == http.MethodPost && strings.Contains(r.URL.Path, "ContentDir") {
+			body, _ := io.ReadAll(io.LimitReader(r.Body, 1<<16))
+			_ = r.Body.Close()
+			r.Body = io.NopCloser(bytes.NewReader(body))
+
+			browseAttrs = []any{
+				"objectID", between(string(body), "<ObjectID>", "</ObjectID>"),
+				"browseFlag", between(string(body), "<BrowseFlag>", "</BrowseFlag>"),
+			}
+		}
+
+		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
+		next.ServeHTTP(rec, r)
+
+		attrs := []any{
+			"method", r.Method,
+			"path", r.URL.Path,
+			"status", rec.status,
+			"bytes", rec.bytes,
+			"from", r.RemoteAddr,
+			"dur", time.Since(start).String(),
+		}
+		attrs = append(attrs, browseAttrs...)
+
+		logger.Info("HTTP", attrs...)
+	})
+}
+
+// between returns the text between the first occurrence of openTag and the next
+// closeTag, or "" if not found. Used for lightweight SOAP field extraction in logs.
+func between(s, openTag, closeTag string) string {
+	i := strings.Index(s, openTag)
+	if i < 0 {
+		return ""
+	}
+
+	i += len(openTag)
+
+	j := strings.Index(s[i:], closeTag)
+	if j < 0 {
+		return ""
+	}
+
+	return s[i : i+j]
+}
+
+// interfaceForIP returns the UP, multicast-capable interface that owns the given
+// IPv4 address, or nil if none is found.
+func interfaceForIP(ip string) *net.Interface {
+	ifaces, err := net.Interfaces()
+	if err != nil {
+		return nil
+	}
+
+	for i := range ifaces {
+		iface := &ifaces[i]
+		if iface.Flags&net.FlagUp == 0 || iface.Flags&net.FlagMulticast == 0 {
+			continue
+		}
+
+		addrs, aerr := iface.Addrs()
+		if aerr != nil {
+			continue
+		}
+
+		for _, addr := range addrs {
+			if ipNet, ok := addr.(*net.IPNet); ok {
+				if v4 := ipNet.IP.To4(); v4 != nil && v4.String() == ip {
+					return iface
+				}
+			}
+		}
+	}
+
+	return nil
+}
+
+// extractHeader extracts a header value from a raw HTTP-style SSDP message.
+// Key comparison is case-insensitive.
+func extractHeader(msg, key string) string {
+	lower := strings.ToLower(key) + ":"
+
+	for _, line := range strings.Split(msg, "\n") {
+		trimmed := strings.TrimRight(line, "\r")
+		if strings.HasPrefix(strings.ToLower(trimmed), lower) {
+			return strings.TrimSpace(trimmed[len(lower):])
+		}
+	}
+
+	return ""
+}

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-backup/cmd_updatecheck.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/updatecheck"
+	"github.com/urfave/cli/v2"
+)
+
+// updateCheckRepo is the GitHub repo checked for newer releases, matching
+// soundtouch-service's periodic background check (#591,
+// _/i591/design-update-check.md).
+const updateCheckRepo = "gesellix/Bose-SoundTouch"
+
+// updateCheckCommand assembles the on-demand `soundtouch-backup
+// update-check` command, the CLI-side answer to that design doc's open
+// question 2 (CLI-only users get no update notice from the service's
+// background checker). Unlike the service's opt-in periodic check, running
+// this command *is* the opt-in: no config flag, no persisted state, just
+// one GitHub API request each time it's invoked.
+func updateCheckCommand() *cli.Command {
+	return &cli.Command{
+		Name:   "update-check",
+		Usage:  "Check GitHub for a newer soundtouch-backup release",
+		Action: runUpdateCheck,
+	}
+}
+
+func runUpdateCheck(c *cli.Context) error {
+	checker := updatecheck.NewChecker(nil, updateCheckRepo, version)
+
+	result, err := checker.CheckNow(c.Context)
+	if err != nil {
+		return fmt.Errorf("update check failed: %w", err)
+	}
+
+	printUpdateCheckResult(result)
+
+	return nil
+}
+
+func printUpdateCheckResult(result updatecheck.Result) {
+	if result.LatestVersion == "" {
+		fmt.Printf("Running %s, not a released version, skipping comparison.\n", result.CurrentVersion)
+		return
+	}
+
+	if result.Available {
+		fmt.Printf("A newer version is available: %s (you're on %s)\n", result.LatestVersion, result.CurrentVersion)
+		fmt.Println(result.ReleaseURL)
+
+		return
+	}
+
+	fmt.Printf("You're on the latest version (%s).\n", result.CurrentVersion)
+}

cmd/soundtouch-backup/cmd_updatecheck_test.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/updatecheck"
+)
+
+// TestUpdateCheckCommand_Registered checks the command is wired up with the
+// expected name and an Action, without making any real GitHub API calls.
+func TestUpdateCheckCommand_Registered(t *testing.T) {
+	cmd := updateCheckCommand()
+
+	if cmd.Name != "update-check" {
+		t.Errorf("command name = %q; want %q", cmd.Name, "update-check")
+	}
+
+	if cmd.Action == nil {
+		t.Error("expected an Action to be set")
+	}
+}
+
+// TestPrintUpdateCheckResult_DoesNotPanic exercises all three result shapes
+// (unparseable current version, update available, up to date) purely for
+// the "does not panic" guarantee; updatecheck.Checker's own tests already
+// cover the comparison logic itself.
+func TestPrintUpdateCheckResult_DoesNotPanic(t *testing.T) {
+	cases := []struct {
+		name   string
+		result updatecheck.Result
+	}{
+		{"unparseable current version", updatecheck.Result{CurrentVersion: "dev"}},
+		{"update available", updatecheck.Result{CurrentVersion: "v1.0.0", LatestVersion: "v1.1.0", Available: true, ReleaseURL: "https://example.invalid"}},
+		{"up to date", updatecheck.Result{CurrentVersion: "v1.1.0", LatestVersion: "v1.1.0", Available: false}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			printUpdateCheckResult(tc.result)
+		})
+	}
+}

cmd/soundtouch-backup/main.go

@@ -14,7 +14,11 @@ var version = "dev"
 
 func init() {
 	if info, ok := debug.ReadBuildInfo(); ok {
-		if info.Main.Version != "" && info.Main.Version != "(devel)" {
+		// Only fall back to build info when the version was not injected via
+		// -ldflags (i.e. still the "dev" default, e.g. `go install …@vX.Y.Z`).
+		// This keeps an explicitly stamped release version from being clobbered
+		// by a VCS pseudo-version (e.g. v0.0.0-… from a shallow checkout).
+		if version == "dev" && info.Main.Version != "" && info.Main.Version != "(devel)" {
 			version = info.Main.Version
 		}
 	}
@@ -29,6 +33,7 @@ func main() {
 			allCommand(),
 			cloudCommand(),
 			localCommand(),
+			updateCheckCommand(),
 		},
 	}
 	if err := app.Run(os.Args); err != nil {

cmd/soundtouch-cli/cmd_account.go

@@ -318,7 +318,7 @@ func removePandoraAccount(c *cli.Context) error {
 func addStoredMusicAccount(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)
 
-	client, err := CreateSoundTouchClient(clientConfig)
+	stClient, err := CreateSoundTouchClient(clientConfig)
 	if err != nil {
 		return err
 	}
@@ -340,13 +340,26 @@ func addStoredMusicAccount(c *cli.Context) error {
 	fmt.Printf("  Display Name: %s\n", displayName)
 	fmt.Printf("  Type: UPnP/DLNA Media Server\n")
 
-	err = client.AddStoredMusicAccount(user, displayName)
+	err = stClient.AddStoredMusicAccount(user, displayName)
 	if err != nil {
 		return fmt.Errorf("failed to add network music library: %w", err)
 	}
 
 	PrintSuccess("Network music library added successfully")
 
+	// Send a sourcesUpdated nudge so the speaker re-fetches its account list and
+	// registers the new source without requiring a power-cycle. This is
+	// best-effort: a failure here does not abort the command.
+	if info, infoErr := stClient.GetDeviceInfo(); infoErr == nil && info != nil && info.DeviceID != "" {
+		if nudgeErr := stClient.NotifySourcesUpdated(info.DeviceID); nudgeErr == nil {
+			fmt.Println("  Sent a sources refresh to the speaker (no reboot needed).")
+		} else {
+			fmt.Println("  Warning: could not send sources refresh; you may need to power-cycle the speaker for the new source to register.")
+		}
+	} else {
+		fmt.Println("  Warning: could not retrieve device ID; you may need to power-cycle the speaker for the new source to register.")
+	}
+
 	// Show next steps
 	fmt.Printf("\n💡 Next Steps:\n")
 	fmt.Printf("   • Check available sources: soundtouch-cli --host %s source list\n", clientConfig.Host)

cmd/soundtouch-cli/cmd_clock.go

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

cmd/soundtouch-cli/cmd_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

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

@@ -0,0 +1,383 @@
+package main
+
+import (
+	"fmt"
+	"net"
+	"sync"
+
+	"github.com/gesellix/bose-soundtouch/pkg/client"
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/speaker"
+	"github.com/urfave/cli/v2"
+)
+
+// getGroupStatus retrieves and prints the device's current stereo-pair state.
+func getGroupStatus(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	PrintDeviceHeader("Getting group information", clientConfig.Host, clientConfig.Port)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	group, err := client.GetGroup()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to get group: %v", err))
+		return err
+	}
+
+	if group.IsEmpty() {
+		fmt.Println("Device is not in a stereo pair")
+		return nil
+	}
+
+	printGroup(group)
+
+	return nil
+}
+
+// createGroup forms a stereo pair by POSTing /addGroup to both speakers in
+// parallel. LEFT is the master. Addressing each speaker directly (instead of
+// only the master and letting it propagate via marge) sidesteps the
+// inter-device round-trip that surfaced as client timeouts in #252.
+func createGroup(c *cli.Context) error {
+	leftIP := c.String("left")
+	rightIP := c.String("right")
+	name := c.String("name")
+
+	if net.ParseIP(leftIP) == nil {
+		PrintError(fmt.Sprintf("Invalid left IP address: %s", leftIP))
+		return fmt.Errorf("invalid left IP: %s", leftIP)
+	}
+
+	if net.ParseIP(rightIP) == nil {
+		PrintError(fmt.Sprintf("Invalid right IP address: %s", rightIP))
+		return fmt.Errorf("invalid right IP: %s", rightIP)
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Creating stereo pair: LEFT=%s RIGHT=%s", leftIP, rightIP), leftIP, speaker.HTTPPort)
+
+	leftInfo, err := fetchDeviceInfo(c, leftIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read LEFT device info: %v", err))
+		return err
+	}
+
+	rightInfo, err := fetchDeviceInfo(c, rightIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read RIGHT device info: %v", err))
+		return err
+	}
+
+	if name == "" {
+		name = fmt.Sprintf("%s + %s", leftInfo.Name, rightInfo.Name)
+	}
+
+	req := &models.Group{
+		Name:           name,
+		MasterDeviceID: leftInfo.DeviceID,
+		Roles: models.GroupRoles{
+			Roles: []models.GroupRole{
+				{DeviceID: leftInfo.DeviceID, Role: "LEFT", IPAddress: leftIP},
+				{DeviceID: rightInfo.DeviceID, Role: "RIGHT", IPAddress: rightIP},
+			},
+		},
+		// SenderIPAddress is intentionally omitted on the base request.
+		// propagateAddGroup adds it to the slave's copy only — see comment there.
+	}
+
+	leftClient, err := clientForHost(c, leftIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client for LEFT: %v", err))
+		return err
+	}
+
+	rightClient, err := clientForHost(c, rightIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client for RIGHT: %v", err))
+		return err
+	}
+
+	leftOut, rightOut := propagateAddGroup(leftClient, rightClient, leftIP, rightIP, req)
+
+	if leftOut.err != nil {
+		PrintError(fmt.Sprintf("LEFT (%s) /addGroup failed: %v", leftIP, leftOut.err))
+	}
+
+	if rightOut.err != nil {
+		PrintError(fmt.Sprintf("RIGHT (%s) /addGroup failed: %v", rightIP, rightOut.err))
+	}
+
+	if leftOut.err != nil || rightOut.err != nil {
+		if (leftOut.err == nil) != (rightOut.err == nil) {
+			succeeded := leftIP
+			if leftOut.err != nil {
+				succeeded = rightIP
+			}
+
+			PrintError(fmt.Sprintf("Partial group state on %s — clean up with `soundtouch-cli --host %s group remove`", succeeded, succeeded))
+		}
+
+		return fmt.Errorf("/addGroup propagation failed")
+	}
+
+	// The LEFT (master) response carries the assigned group ID; use it for display.
+	PrintSuccess(fmt.Sprintf("Stereo pair created (id=%s)", leftOut.group.ID))
+	printGroup(leftOut.group)
+
+	return nil
+}
+
+// addGroupOutcome is the per-speaker result of a parallel /addGroup call.
+type addGroupOutcome struct {
+	host  string
+	group *models.Group
+	err   error
+}
+
+// propagateAddGroup POSTs /addGroup to both speakers concurrently and returns
+// the (LEFT, RIGHT) outcomes. A non-GROUP_OK Status in the response is
+// reported as an error so callers don't have to re-inspect the body.
+//
+// The two POSTs carry different payloads: the master (LEFT) receives the base
+// request with no senderIPAddress so its state machine forms the group as the
+// master, while the slave (RIGHT) receives a copy with senderIPAddress set to
+// the master's IP so its state machine joins as the slave. Sending the same
+// payload to both makes both speakers think they're the slave — they enter
+// AddingSlave, wait for a master that never confirms, time out after 5 s, and
+// revert (issue #252).
+func propagateAddGroup(left, right *client.Client, leftIP, rightIP string, req *models.Group) (addGroupOutcome, addGroupOutcome) {
+	masterReq := *req
+	masterReq.SenderIPAddress = ""
+
+	slaveReq := *req
+	slaveReq.SenderIPAddress = leftIP
+
+	var (
+		wg                sync.WaitGroup
+		leftOut, rightOut addGroupOutcome
+	)
+
+	wg.Add(2)
+
+	go func() {
+		defer wg.Done()
+
+		leftOut = postAddGroup(left, leftIP, &masterReq)
+	}()
+
+	go func() {
+		defer wg.Done()
+
+		rightOut = postAddGroup(right, rightIP, &slaveReq)
+	}()
+
+	wg.Wait()
+
+	return leftOut, rightOut
+}
+
+func postAddGroup(cli *client.Client, host string, req *models.Group) addGroupOutcome {
+	out := addGroupOutcome{host: host}
+
+	g, err := cli.AddGroup(req)
+	if err != nil {
+		out.err = err
+		return out
+	}
+
+	out.group = g
+
+	if g != nil && g.Status != "" && g.Status != "GROUP_OK" {
+		out.err = fmt.Errorf("device returned status %q (want GROUP_OK)", g.Status)
+	}
+
+	return out
+}
+
+// renameGroup updates the name of the existing stereo pair. The device
+// requires the full structure on every update, so we fetch the current
+// state first.
+func renameGroup(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	newName := c.String("name")
+
+	if newName == "" {
+		PrintError("--name is required")
+		return fmt.Errorf("name is required")
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Renaming stereo pair to %q", newName), clientConfig.Host, clientConfig.Port)
+
+	stClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	current, err := stClient.GetGroup()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read current group: %v", err))
+		return err
+	}
+
+	if current.IsEmpty() {
+		PrintError("Device is not in a stereo pair — nothing to rename")
+		return fmt.Errorf("no group configured")
+	}
+
+	// Status is read-only on the device side; don't echo it back.
+	current.Status = ""
+	current.Name = newName
+
+	result, err := stClient.UpdateGroup(current)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to rename group: %v", err))
+		return err
+	}
+
+	PrintSuccess(fmt.Sprintf("Stereo pair renamed to %q", result.Name))
+	printGroup(result)
+
+	return nil
+}
+
+// removeGroup tears down the device's stereo pair 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)
+
+	stClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return 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
+}
+
+// fetchDeviceInfo builds a one-off client for the given IP and reads /info.
+// Reused for both halves of a `create` invocation so the caller doesn't have
+// to babysit two host/port pairs.
+func fetchDeviceInfo(c *cli.Context, host string) (*models.DeviceInfo, error) {
+	stClient, err := clientForHost(c, host)
+	if err != nil {
+		return nil, err
+	}
+
+	return stClient.GetDeviceInfo()
+}
+
+// clientForHost mirrors CreateSoundTouchClient but overrides the host so we
+// can talk to a speaker other than the one named in --host.
+func clientForHost(c *cli.Context, host string) (*client.Client, error) {
+	cfg, err := loadConfig(c.Duration("timeout"))
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	return client.NewClient(&client.Config{
+		Host:      host,
+		Port:      speaker.HTTPPort,
+		Timeout:   cfg.HTTPTimeout,
+		UserAgent: cfg.UserAgent,
+	}), nil
+}
+
+func printGroup(g *models.Group) {
+	fmt.Println("Stereo Pair Configuration:")
+	fmt.Printf("  ID:        %s\n", g.ID)
+	fmt.Printf("  Name:      %s\n", g.Name)
+	fmt.Printf("  Master:    %s\n", g.MasterDeviceID)
+
+	if g.Status != "" {
+		fmt.Printf("  Status:    %s\n", g.Status)
+	}
+
+	for _, r := range g.Roles.Roles {
+		fmt.Printf("  %-5s     %s", r.Role, r.DeviceID)
+
+		if r.IPAddress != "" {
+			fmt.Printf(" (IP: %s)", r.IPAddress)
+		}
+
+		fmt.Println()
+	}
+}

cmd/soundtouch-cli/cmd_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_library.go

@@ -0,0 +1,443 @@
+// Package main — `soundtouch-cli library` command group.
+//
+// Three subcommands:
+//
+//   - library servers: discover DLNA media servers on the LAN, either via an
+//     app-side SSDP sweep (default) or via the speaker's own list (--via-speaker).
+//   - library browse: walk a DLNA ContentDirectory tree by UDN.
+//   - library play: play a DLNA track on a speaker via native STORED_MUSIC playback.
+package main
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/discovery"
+	"github.com/gesellix/bose-soundtouch/pkg/dlna"
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/urfave/cli/v2"
+)
+
+// libraryCommand returns the top-level `library` command group.
+func libraryCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "library",
+		Usage: "DLNA music library commands (server discovery, browse, play)",
+		Subcommands: []*cli.Command{
+			{
+				Name:   "browse",
+				Usage:  "Browse a DLNA ContentDirectory tree",
+				Action: libraryBrowse,
+				Flags: []cli.Flag{
+					&cli.IntFlag{
+						Name:  "count",
+						Usage: "Page size (number of entries to request)",
+						Value: 50,
+					},
+					&cli.StringFlag{
+						Name:  "object",
+						Usage: `ContentDirectory object ID to browse ("0" = root)`,
+						Value: "0",
+					},
+					&cli.IntFlag{
+						Name:  "start",
+						Usage: "Page offset (starting index)",
+						Value: 0,
+					},
+					&cli.DurationFlag{
+						Name:  "timeout",
+						Usage: "SSDP discovery + SOAP timeout",
+						Value: 5 * time.Second,
+					},
+					&cli.StringFlag{
+						Name:     "udn",
+						Usage:    "UDN (uuid:...) of the DLNA media server to browse",
+						Required: true,
+					},
+				},
+			},
+			{
+				Name:   "play",
+				Usage:  "Play a DLNA track on a speaker via native STORED_MUSIC playback",
+				Action: libraryPlay,
+				Before: RequireHost,
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:  "art",
+						Usage: "Container art URL (optional)",
+					},
+					&cli.StringFlag{
+						Name:  "name",
+						Usage: "Display name shown on the speaker (optional)",
+					},
+					&cli.StringFlag{
+						Name:     "source-account",
+						Usage:    "STORED_MUSIC source account (media-server UDN with /0 suffix, e.g. fa095ecc-e13e-40e7-8e6c-e0286d5bc000/0)",
+						Required: true,
+					},
+					&cli.StringFlag{
+						Name:  "type",
+						Usage: `ContentItem type: "track" or "dir"`,
+						Value: "track",
+					},
+					&cli.StringFlag{
+						Name:     "location",
+						Usage:    "Object ID from a browse result (e.g. 5:audio5:part13:3171:5 TRACK)",
+						Required: true,
+					},
+				},
+			},
+			{
+				Name:   "servers",
+				Usage:  "List DLNA media servers visible on the LAN",
+				Action: libraryServers,
+				Flags: []cli.Flag{
+					&cli.DurationFlag{
+						Name:  "timeout",
+						Usage: "SSDP sweep timeout",
+						Value: 5 * time.Second,
+					},
+					&cli.BoolFlag{
+						Name:  "via-speaker",
+						Usage: "Ask the speaker (--host required) instead of doing an app-side SSDP sweep",
+					},
+				},
+			},
+		},
+	}
+}
+
+// libraryServers implements `library servers`.
+func libraryServers(c *cli.Context) error {
+	if c.Bool("via-speaker") {
+		return libraryServersViaSpeaker(c)
+	}
+
+	return libraryServersAppSide(c)
+}
+
+// libraryServersAppSide runs an SSDP sweep from the CLI process itself.
+func libraryServersAppSide(c *cli.Context) error {
+	timeout := c.Duration("timeout")
+
+	ctx, cancel := context.WithTimeout(context.Background(), timeout+5*time.Second)
+	defer cancel()
+
+	servers, err := discovery.DiscoverMediaServers(ctx, timeout)
+	if err != nil {
+		PrintError(fmt.Sprintf("SSDP discovery failed: %v", err))
+
+		return err
+	}
+
+	if len(servers) == 0 {
+		fmt.Println("No DLNA media servers found on the LAN.")
+
+		return nil
+	}
+
+	fmt.Printf("Found %d DLNA media server(s):\n\n", len(servers))
+
+	for _, srv := range servers {
+		printAppSideServer(srv)
+	}
+
+	return nil
+}
+
+// libraryServersViaSpeaker asks the speaker for its own DLNA server list.
+func libraryServersViaSpeaker(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+
+	speakerClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create speaker client: %v", err))
+
+		return err
+	}
+
+	resp, err := speakerClient.ListMediaServers()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to list media servers via speaker: %v", err))
+
+		return err
+	}
+
+	if len(resp.MediaServers) == 0 {
+		fmt.Println("Speaker reports no DLNA media servers.")
+
+		return nil
+	}
+
+	fmt.Printf("Speaker reports %d DLNA media server(s):\n\n", len(resp.MediaServers))
+
+	for i := range resp.MediaServers {
+		printSpeakerServer(resp.MediaServers[i])
+	}
+
+	return nil
+}
+
+// printAppSideServer prints a single server discovered by the app-side sweep.
+func printAppSideServer(srv discovery.MediaServer) {
+	fmt.Printf("  Name:   %s\n", srv.FriendlyName)
+	fmt.Printf("  Vendor: %s / %s\n", srv.Manufacturer, srv.ModelName)
+	fmt.Printf("  UDN:    %s\n", srv.UDN)
+	fmt.Printf("  CDS:    %s\n", srv.CDSControlURL)
+
+	if srv.IconURL != "" {
+		fmt.Printf("  Icon:   %s\n", srv.IconURL)
+	}
+
+	fmt.Println()
+}
+
+// printSpeakerServer prints a single server as reported by the speaker.
+func printSpeakerServer(srv models.MediaServerInfo) {
+	name := srv.FriendlyName
+	if name == "" {
+		name = "(unnamed)"
+	}
+
+	vendor := srv.Manufacturer
+
+	if srv.ModelName != "" {
+		if vendor != "" {
+			vendor += " / " + srv.ModelName
+		} else {
+			vendor = srv.ModelName
+		}
+	}
+
+	fmt.Printf("  Name:     %s\n", name)
+
+	if vendor != "" {
+		fmt.Printf("  Vendor:   %s\n", vendor)
+	}
+
+	fmt.Printf("  UDN:      %s\n", srv.ID)
+
+	if srv.IP != "" {
+		fmt.Printf("  IP:       %s\n", srv.IP)
+	}
+
+	if srv.Location != "" {
+		fmt.Printf("  Location: %s\n", srv.Location)
+	}
+
+	fmt.Println()
+}
+
+// libraryBrowse implements `library browse`.
+func libraryBrowse(c *cli.Context) error {
+	udn := strings.TrimSpace(c.String("udn"))
+	objectID := c.String("object")
+	start := c.Int("start")
+	count := c.Int("count")
+	timeout := c.Duration("timeout")
+
+	ctx, cancel := context.WithTimeout(context.Background(), timeout+5*time.Second)
+	defer cancel()
+
+	servers, err := discovery.DiscoverMediaServers(ctx, timeout)
+	if err != nil {
+		PrintError(fmt.Sprintf("SSDP discovery failed: %v", err))
+
+		return err
+	}
+
+	var target *discovery.MediaServer
+
+	for i := range servers {
+		if servers[i].UDN == udn {
+			target = &servers[i]
+
+			break
+		}
+	}
+
+	if target == nil {
+		var udns []string
+
+		for _, srv := range servers {
+			udns = append(udns, fmt.Sprintf("  %s  (%s)", srv.UDN, srv.FriendlyName))
+		}
+
+		if len(udns) == 0 {
+			PrintError(fmt.Sprintf("No server with UDN %q found; no servers discovered.", udn))
+		} else {
+			PrintError(fmt.Sprintf(
+				"No server with UDN %q found.\nKnown servers:\n%s",
+				udn, strings.Join(udns, "\n"),
+			))
+		}
+
+		return fmt.Errorf("server %q not found", udn)
+	}
+
+	fmt.Printf("Browsing %q (object %q, offset %d, page %d)\n\n", target.FriendlyName, objectID, start, count)
+
+	browseCtx, browseCancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer browseCancel()
+
+	result, err := dlna.Browse(browseCtx, *target, objectID, start, count)
+	if err != nil {
+		PrintError(fmt.Sprintf("Browse failed: %v", err))
+
+		return err
+	}
+
+	fmt.Printf("TotalMatches: %d  Returned: %d\n\n", result.TotalMatches, result.Returned)
+
+	for _, con := range result.Containers {
+		fmt.Printf("  [dir]  %s  (id=%s, children=%d)\n", con.Title, con.ID, con.ChildCount)
+	}
+
+	for i := range result.Items {
+		it := &result.Items[i]
+
+		audio := ""
+		if it.IsAudioItem() {
+			audio = " [audio]"
+		}
+
+		meta := ""
+
+		if it.Artist != "" || it.Album != "" {
+			parts := []string{}
+			if it.Artist != "" {
+				parts = append(parts, it.Artist)
+			}
+
+			if it.Album != "" {
+				parts = append(parts, it.Album)
+			}
+
+			meta = "  — " + strings.Join(parts, " / ")
+		}
+
+		dur := ""
+
+		if it.DurationSec > 0 {
+			m := it.DurationSec / 60
+			s := it.DurationSec % 60
+			dur = fmt.Sprintf("  [%d:%02d]", m, s)
+		}
+
+		fmt.Printf("  [item]%s  %s%s%s\n", audio, it.Title, meta, dur)
+
+		if it.StreamURL != "" {
+			fmt.Printf("         url: %s\n", it.StreamURL)
+		}
+	}
+
+	return nil
+}
+
+// libraryPlay implements `library play` using native STORED_MUSIC playback.
+func libraryPlay(c *cli.Context) error {
+	sourceAccount := strings.TrimSpace(c.String("source-account"))
+	location := strings.TrimSpace(c.String("location"))
+	name := c.String("name")
+	itemType := c.String("type")
+	art := c.String("art")
+
+	if sourceAccount == "" {
+		PrintError("--source-account is required")
+
+		return fmt.Errorf("--source-account is required")
+	}
+
+	if location == "" {
+		PrintError("--location is required")
+
+		return fmt.Errorf("--location is required")
+	}
+
+	clientConfig := GetClientConfig(c)
+
+	speakerClient, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create speaker client: %v", err))
+
+		return err
+	}
+
+	// Check that the STORED_MUSIC source for this account is READY before
+	// attempting playback. Re-registering an already-READY account can flip
+	// it to UNAVAILABLE, so we intentionally do NOT auto-register here.
+	sources, err := speakerClient.GetSources()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to retrieve sources: %v", err))
+
+		return err
+	}
+
+	ready := false
+
+	for _, si := range sources.SourceItem {
+		if si.Source == "STORED_MUSIC" && si.SourceAccount == sourceAccount {
+			if si.Status.IsReady() {
+				ready = true
+			}
+
+			break
+		}
+	}
+
+	if !ready {
+		host := clientConfig.Host
+		PrintError(fmt.Sprintf(
+			"STORED_MUSIC source account %q is not READY on the speaker.\n"+
+				"Register it first:\n"+
+				"  soundtouch-cli --host %s account add-nas --user %s --name <server-display-name>",
+			sourceAccount, host, sourceAccount,
+		))
+
+		return fmt.Errorf("STORED_MUSIC source account %q not ready", sourceAccount)
+	}
+
+	PrintDeviceHeader("STORED_MUSIC play", clientConfig.Host, clientConfig.Port)
+	fmt.Printf("  Source account: %s\n", sourceAccount)
+	fmt.Printf("  Location:       %s\n", location)
+	fmt.Printf("  Type:           %s\n", itemType)
+
+	if name != "" {
+		fmt.Printf("  Name:           %s\n", name)
+	}
+
+	if art != "" {
+		fmt.Printf("  Art:            %s\n", art)
+	}
+
+	fmt.Println()
+
+	// SelectStoredMusic does not set Type, so we build the ContentItem directly
+	// so we can pass the correct type ("track" or "dir") to the speaker.
+	ci := &models.ContentItem{
+		Source:        "STORED_MUSIC",
+		SourceAccount: sourceAccount,
+		Location:      location,
+		Type:          itemType,
+		ItemName:      name,
+		ContainerArt:  art,
+		IsPresetable:  true,
+	}
+
+	if err = speakerClient.SelectContentItem(ci); err != nil {
+		PrintError(fmt.Sprintf("Playback command failed: %v", err))
+
+		return err
+	}
+
+	label := name
+	if label == "" {
+		label = location
+	}
+
+	PrintSuccess(fmt.Sprintf("Playing %q (STORED_MUSIC, location=%s)", label, location))
+
+	return nil
+}

cmd/soundtouch-cli/cmd_library_test.go

@@ -0,0 +1,130 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/urfave/cli/v2"
+)
+
+// TestLibraryCommand_Registered checks that the library command and its three
+// subcommands are wired up with the expected names and flags. No live multicast
+// or real speaker calls are made.
+func TestLibraryCommand_Registered(t *testing.T) {
+	cmd := libraryCommand()
+
+	if cmd.Name != "library" {
+		t.Errorf("top-level command name = %q; want %q", cmd.Name, "library")
+	}
+
+	// Index subcommands by name for easy lookup.
+	sub := make(map[string]interface{})
+
+	for _, sc := range cmd.Subcommands {
+		sub[sc.Name] = sc
+	}
+
+	for _, name := range []string{"servers", "browse", "play"} {
+		if _, ok := sub[name]; !ok {
+			t.Errorf("expected subcommand %q to be registered", name)
+		}
+	}
+}
+
+// TestLibraryServersFlags checks the flags on `library servers`.
+func TestLibraryServersFlags(t *testing.T) {
+	cmd := libraryCommand()
+
+	for _, s := range cmd.Subcommands {
+		if s.Name != "servers" {
+			continue
+		}
+
+		flags := flagNames(s.Flags)
+
+		for _, want := range []string{"timeout", "via-speaker"} {
+			if !contains(flags, want) {
+				t.Errorf("servers subcommand missing flag %q; got %v", want, flags)
+			}
+		}
+
+		return
+	}
+
+	t.Fatal("servers subcommand not found")
+}
+
+// TestLibraryBrowseFlags checks the flags on `library browse`.
+func TestLibraryBrowseFlags(t *testing.T) {
+	cmd := libraryCommand()
+
+	for _, s := range cmd.Subcommands {
+		if s.Name != "browse" {
+			continue
+		}
+
+		flags := flagNames(s.Flags)
+
+		for _, want := range []string{"udn", "object", "start", "count", "timeout"} {
+			if !contains(flags, want) {
+				t.Errorf("browse subcommand missing flag %q; got %v", want, flags)
+			}
+		}
+
+		return
+	}
+
+	t.Fatal("browse subcommand not found")
+}
+
+// TestLibraryPlayFlags checks the flags on `library play`.
+func TestLibraryPlayFlags(t *testing.T) {
+	cmd := libraryCommand()
+
+	for _, s := range cmd.Subcommands {
+		if s.Name != "play" {
+			continue
+		}
+
+		flags := flagNames(s.Flags)
+
+		// source-account and location are required; name, type, art are optional.
+		for _, want := range []string{"source-account", "location", "name", "type", "art"} {
+			if !contains(flags, want) {
+				t.Errorf("play subcommand missing flag %q; got %v", want, flags)
+			}
+		}
+
+		// Old URL-mode flags must no longer be present.
+		for _, gone := range []string{"url", "mode"} {
+			if contains(flags, gone) {
+				t.Errorf("play subcommand should not have flag %q", gone)
+			}
+		}
+
+		return
+	}
+
+	t.Fatal("play subcommand not found")
+}
+
+// flagNames extracts the primary Name from each flag in a slice.
+func flagNames(flags []cli.Flag) []string {
+	names := make([]string, 0, len(flags))
+
+	for _, f := range flags {
+		names = append(names, getFlagName(f))
+	}
+
+	return names
+}
+
+// contains reports whether needle is in haystack.
+func contains(haystack []string, needle string) bool {
+	for _, s := range haystack {
+		if s == needle {
+			return true
+		}
+	}
+
+	return false
+}

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_test.go

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

cmd/soundtouch-cli/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_speaker.go

@@ -136,6 +136,40 @@ func playURL(c *cli.Context) error {
 	return nil
 }
 
+// playURLUPnP plays audio from a URL via the speaker's UPnP AVTransport service.
+// Unlike `speaker url` (the /speaker play_info path), it needs no app-key and no
+// DNS interception, so it works on a plain LAN. It switches the speaker to the
+// UPNP source and replaces the current playback (no duck-and-resume), and the
+// speaker itself must be able to reach the URL.
+func playURLUPnP(c *cli.Context) error {
+	clientConfig := GetClientConfig(c)
+	urlStr := c.String("url")
+
+	if urlStr == "" {
+		PrintError("URL is required")
+		return fmt.Errorf("URL cannot be empty")
+	}
+
+	PrintDeviceHeader(fmt.Sprintf("Playing URL via UPnP: %s", urlStr), clientConfig.Host, clientConfig.Port)
+
+	client, err := CreateSoundTouchClient(clientConfig)
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to create client: %v", err))
+		return err
+	}
+
+	if err := client.PlayURLViaUPnP(urlStr); err != nil {
+		PrintError(fmt.Sprintf("Failed to play URL via UPnP: %v", err))
+		return err
+	}
+
+	fmt.Printf("✅ URL playback started via UPnP\n")
+	fmt.Printf("   URL: %s\n", urlStr)
+	fmt.Printf("   Note: replaces the current source (UPNP); no app-key or DNS needed\n")
+
+	return nil
+}
+
 // playNotification plays a notification sound or a local file on the speaker
 func playNotification(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)
@@ -193,6 +227,11 @@ func showSpeakerHelp(_ *cli.Context) error {
 	fmt.Println("  Play audio files from HTTP/HTTPS URLs")
 	fmt.Println("  Example: soundtouch-cli speaker url --url \"https://example.com/audio.mp3\" --app-key YOUR_KEY")
 	fmt.Println()
+	fmt.Println("• URL via UPnP/AVTransport (no app key, no DNS):")
+	fmt.Println("  Play an http:// audio URL directly via the speaker's UPnP renderer.")
+	fmt.Println("  Replaces the current source; http:// only (https is rejected).")
+	fmt.Println("  Example: soundtouch-cli speaker url-upnp --url \"http://192.0.2.10/audio.mp3\"")
+	fmt.Println()
 	fmt.Println("• Notification Beep:")
 	fmt.Println("  Play a simple notification sound")
 	fmt.Println("  Example: soundtouch-cli speaker beep")

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/cmd_updatecheck.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"fmt"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/updatecheck"
+	"github.com/urfave/cli/v2"
+)
+
+// updateCheckRepo is the GitHub repo checked for newer releases, matching
+// soundtouch-service's periodic background check (#591,
+// _/i591/design-update-check.md).
+const updateCheckRepo = "gesellix/Bose-SoundTouch"
+
+// updateCheckCommand assembles the on-demand `soundtouch-cli update-check`
+// command, the CLI-side answer to that design doc's open question 2
+// (CLI-only users get no update notice from the service's background
+// checker). Unlike the service's opt-in periodic check, running this
+// command *is* the opt-in: no config flag, no persisted state, just one
+// GitHub API request each time it's invoked.
+func updateCheckCommand() *cli.Command {
+	return &cli.Command{
+		Name:   "update-check",
+		Usage:  "Check GitHub for a newer soundtouch-cli release",
+		Action: runUpdateCheck,
+	}
+}
+
+func runUpdateCheck(c *cli.Context) error {
+	checker := updatecheck.NewChecker(nil, updateCheckRepo, version)
+
+	result, err := checker.CheckNow(c.Context)
+	if err != nil {
+		return fmt.Errorf("update check failed: %w", err)
+	}
+
+	printUpdateCheckResult(result)
+
+	return nil
+}
+
+func printUpdateCheckResult(result updatecheck.Result) {
+	if result.LatestVersion == "" {
+		fmt.Printf("Running %s, not a released version, skipping comparison.\n", result.CurrentVersion)
+		return
+	}
+
+	if result.Available {
+		fmt.Printf("A newer version is available: %s (you're on %s)\n", result.LatestVersion, result.CurrentVersion)
+		fmt.Println(result.ReleaseURL)
+
+		return
+	}
+
+	fmt.Printf("You're on the latest version (%s).\n", result.CurrentVersion)
+}

cmd/soundtouch-cli/cmd_updatecheck_test.go

@@ -0,0 +1,42 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/updatecheck"
+)
+
+// TestUpdateCheckCommand_Registered checks the command is wired up with the
+// expected name and an Action, without making any real GitHub API calls.
+func TestUpdateCheckCommand_Registered(t *testing.T) {
+	cmd := updateCheckCommand()
+
+	if cmd.Name != "update-check" {
+		t.Errorf("command name = %q; want %q", cmd.Name, "update-check")
+	}
+
+	if cmd.Action == nil {
+		t.Error("expected an Action to be set")
+	}
+}
+
+// TestPrintUpdateCheckResult_DoesNotPanic exercises all three result shapes
+// (unparseable current version, update available, up to date) purely for
+// the "does not panic" guarantee; updatecheck.Checker's own tests already
+// cover the comparison logic itself.
+func TestPrintUpdateCheckResult_DoesNotPanic(t *testing.T) {
+	cases := []struct {
+		name   string
+		result updatecheck.Result
+	}{
+		{"unparseable current version", updatecheck.Result{CurrentVersion: "dev"}},
+		{"update available", updatecheck.Result{CurrentVersion: "v1.0.0", LatestVersion: "v1.1.0", Available: true, ReleaseURL: "https://example.invalid"}},
+		{"up to date", updatecheck.Result{CurrentVersion: "v1.1.0", LatestVersion: "v1.1.0", Available: false}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			printUpdateCheckResult(tc.result)
+		})
+	}
+}

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

@@ -73,8 +73,12 @@ func getFlagName(flag cli.Flag) string {
 // updateBuildInfo extracts version information from debug.BuildInfo and updates package variables
 func updateBuildInfo() {
 	if info, ok := debug.ReadBuildInfo(); ok {
-		// Get version from module info
-		if info.Main.Version != "" && info.Main.Version != "(devel)" {
+		// Get version from module info. Only fall back to build info when the
+		// version was not injected via -ldflags (i.e. still the "dev" default,
+		// e.g. `go install …@vX.Y.Z`). This keeps an explicitly stamped release
+		// version from being clobbered by a VCS pseudo-version (e.g. v0.0.0-…
+		// from a shallow checkout).
+		if version == "dev" && info.Main.Version != "" && info.Main.Version != "(devel)" {
 			version = info.Main.Version
 		}
 
@@ -132,6 +136,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 +389,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 +593,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 +681,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 +695,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 +714,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 +1131,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 +1218,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
@@ -1312,6 +1432,19 @@ func main() {
 								},
 								Before: RequireHost,
 							},
+							{
+								Name:   "timezone",
+								Usage:  "Set display timezone (IANA zone, e.g. Europe/Berlin)",
+								Action: setClockDisplayTimezone,
+								Flags: []cli.Flag{
+									&cli.StringFlag{
+										Name:     "tz",
+										Usage:    "IANA timezone identifier (e.g. Europe/Berlin, America/New_York)",
+										Required: true,
+									},
+								},
+								Before: RequireHost,
+							},
 						},
 					},
 				},
@@ -1478,6 +1611,64 @@ func main() {
 					},
 				},
 			},
+			// Stereo-pair (group) commands — ST-10 only
+			{
+				Name:    "group",
+				Aliases: []string{"g"},
+				Usage:   "ST-10 stereo-pair management (left/right channel pairing)",
+				Subcommands: []*cli.Command{
+					{
+						Name:   "status",
+						Usage:  "Show the device's current stereo-pair configuration",
+						Action: getGroupStatus,
+						Before: RequireHost,
+					},
+					{
+						Name:   "create",
+						Usage:  "Form a stereo pair (LEFT speaker becomes master)",
+						Action: createGroup,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "left",
+								Aliases:  []string{"l"},
+								Usage:    "IP address of the LEFT speaker (will be master)",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:     "right",
+								Aliases:  []string{"r"},
+								Usage:    "IP address of the RIGHT speaker",
+								Required: true,
+							},
+							&cli.StringFlag{
+								Name:    "name",
+								Aliases: []string{"n"},
+								Usage:   "Pair name (defaults to \"<left> + <right>\")",
+							},
+						},
+					},
+					{
+						Name:   "rename",
+						Usage:  "Rename the existing stereo pair on the device",
+						Action: renameGroup,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "name",
+								Aliases:  []string{"n"},
+								Usage:    "New pair name",
+								Required: true,
+							},
+						},
+						Before: RequireHost,
+					},
+					{
+						Name:   "remove",
+						Usage:  "Dissolve the device's stereo pair",
+						Action: removeGroup,
+						Before: RequireHost,
+					},
+				},
+			},
 			// Advanced Audio commands
 			{
 				Name:    "audio",
@@ -1735,6 +1926,20 @@ func main() {
 							},
 						},
 					},
+					{
+						Name:   "url-upnp",
+						Usage:  "Play a URL via UPnP/AVTransport (no app-key, no DNS; replaces current source)",
+						Action: playURLUPnP,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:     "url",
+								Aliases:  []string{"u"},
+								Usage:    "URL of the audio content to play (must be reachable by the speaker)",
+								Required: true,
+							},
+						},
+					},
 					{
 						Name:   "notify",
 						Usage:  "Play a notification sound or local file",
@@ -1754,6 +1959,7 @@ func main() {
 						Action: playNotificationBeep,
 						Before: RequireHost,
 					},
+					ttsCloudCmd(),
 					{
 						Name:   "help",
 						Usage:  "Show detailed help about speaker functionality",
@@ -2093,7 +2299,7 @@ func main() {
 							&cli.StringFlag{
 								Name:    "filter",
 								Aliases: []string{"f"},
-								Usage:   "Filter events by type (comma-separated): nowPlaying,volume,connection,preset,zone,bass,sdkInfo,userActivity",
+								Usage:   "Filter events by type (comma-separated): nowPlaying,volume,connection,preset,zone,group,bass,sdkInfo,userActivity",
 							},
 							&cli.DurationFlag{
 								Name:    "duration",
@@ -2105,6 +2311,10 @@ func main() {
 								Name:  "no-reconnect",
 								Usage: "Disable automatic reconnection on connection loss",
 							},
+							&cli.StringFlag{
+								Name:  "debug",
+								Usage: "Print raw WebSocket frames to stderr — one of: all, unknown, errors",
+							},
 							&cli.BoolFlag{
 								Name:    "verbose",
 								Aliases: []string{"v"},
@@ -2117,6 +2327,21 @@ func main() {
 		},
 	}
 
+	// Speaker provisioning (factory-reset, Wi-Fi, URL rewrite, pairing).
+	// Defined in cmd_setup.go to keep the top-level command list readable.
+	app.Commands = append(app.Commands, setupCommand())
+
+	// AfterTouch service management (sources, accounts, devices).
+	// Defined in cmd_cloud.go.
+	app.Commands = append(app.Commands, cloudCommand())
+
+	// DLNA music library (server discovery, browse, play).
+	// Defined in cmd_library.go.
+	app.Commands = append(app.Commands, libraryCommand())
+
+	// On-demand GitHub release check (#591). Defined in cmd_updatecheck.go.
+	app.Commands = append(app.Commands, updateCheckCommand())
+
 	// 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-player/.gitignore

@@ -0,0 +1,4 @@
+soundtouch-player
+soundtouch-player-test
+soundtouch-web
+soundtouch-web-test

cmd/soundtouch-player/IMPLEMENTATION.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The `soundtouch-web` tool provides a modern single-page application (SPA) for controlling Bose SoundTouch devices. Built with a JSON API backend and client-side JavaScript rendering, it offers superior performance and eliminates template rendering issues.
+The `soundtouch-player` tool provides a modern single-page application (SPA) for controlling Bose SoundTouch devices. Built with a JSON API backend and client-side JavaScript rendering, it offers superior performance and eliminates template rendering issues.
 
 ## Architecture
 
@@ -141,10 +141,10 @@ GET  /api/control/{id}/source?name=X # Select source
 ### Build Commands
 ```bash
 # Build the web application
-cd cmd/soundtouch-web
-go build -o soundtouch-web
+cd cmd/soundtouch-player
+go build -o soundtouch-player
 
-# Build all project components (includes soundtouch-web)
+# Build all project components (includes soundtouch-player)
 make build
 
 # Cross-platform builds
@@ -154,19 +154,19 @@ make build-all
 ### Testing
 ```bash
 # Run unit tests
-go test ./cmd/soundtouch-web/...
+go test ./cmd/soundtouch-player/...
 
 # Run with coverage
-go test -cover ./cmd/soundtouch-web/...
+go test -cover ./cmd/soundtouch-player/...
 
 # Lint checking
-golangci-lint run cmd/soundtouch-web/...
+golangci-lint run cmd/soundtouch-player/...
 ```
 
 ### Development Server
 ```bash
 # Run development server
-cd cmd/soundtouch-web
+cd cmd/soundtouch-player
 go run main.go -port 8080
 
 # Access the web interface
@@ -177,7 +177,7 @@ open http://localhost:8080
 
 ### Command Line Options
 ```bash
-soundtouch-web [options]
+soundtouch-player [options]
 
 Options:
   -port string    Web server port (default "8080")
@@ -186,9 +186,9 @@ Options:
 
 ### File Structure
 ```
-cmd/soundtouch-web/
+cmd/soundtouch-player/
 ├── main.go                    # Application entry point
-├── soundtouch-web            # Built binary
+├── soundtouch-player            # Built binary
 ├── handlers/
 │   ├── handlers.go           # HTTP request handlers
 │   ├── handlers_test.go      # Handler tests

cmd/soundtouch-player/README.md

@@ -75,29 +75,56 @@ Individual device pages provide full control over:
 make build
 
 # Or manually
-cd cmd/soundtouch-web
-go build -o soundtouch-web
+cd cmd/soundtouch-player
+go build -o soundtouch-player
 ```
 
 ### Running
 ```bash
 # Run with default settings (port 8080)
-./soundtouch-web
+./soundtouch-player
 
 # Specify custom port
-./soundtouch-web -port 8888
+./soundtouch-player -port 8888
 
 # Connect to specific device
-./soundtouch-web -host 192.168.1.100
+./soundtouch-player --devices 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-player, so the "Speak" feature proxies to the service's
+`/setup/tts/speak` endpoint. To use it, point soundtouch-player at the service
+with `--service-url`.
+
+When the service is served over HTTPS with its own self-signed certificate
+(the default), soundtouch-player 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-player \
+  --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
@@ -110,7 +137,7 @@ go build -o soundtouch-web
 The application automatically discovers SoundTouch devices using:
 - **mDNS discovery** for local network devices
 - **UPnP/SSDP discovery** as fallback
-- **Manual device addition** via IP address
+- **Configured devices** via `--devices`, retried whenever discovery runs
 
 ### Real-time Updates
 The interface maintains WebSocket connections to each device for instant updates of:
@@ -191,7 +218,7 @@ ws.onmessage = function(event) {
 
 ### Project Structure
 ```
-cmd/soundtouch-web/
+cmd/soundtouch-player/
 ├── main.go              # Application entry point and SPA routing
 ├── handlers/            # HTTP and WebSocket handlers
 │   ├── handlers.go     # JSON API endpoints
@@ -217,7 +244,7 @@ cmd/soundtouch-web/
 go test ./...
 
 # Manual testing with multiple devices
-./soundtouch-web -port 8080
+./soundtouch-player -port 8080
 
 # API testing
 curl http://localhost:8080/api/devices
@@ -296,7 +323,7 @@ This UI is based on extensive analysis of captured SoundTouch WebSocket interact
 Add verbose logging by setting environment variable:
 ```bash
 export DEBUG=true
-./soundtouch-web
+./soundtouch-player
 ```
 
 ## Contributing

cmd/soundtouch-player/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-player/main.go

@@ -0,0 +1,282 @@
+// Package main provides soundtouch-player, the LAN-resident web player for
+// controlling Bose SoundTouch devices. It reaches speakers directly on the
+// local network and optionally delegates cloud-only features (e.g. TTS) to a
+// remote AfterTouch service via --service-url, which is why it stays useful
+// when soundtouch-service runs off-LAN (e.g. in the cloud).
+//
+// It was previously named soundtouch-web; that name is no longer published.
+// If you still run the binary under the old name, it prints a rename notice
+// and otherwise behaves identically.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime/debug"
+	"strings"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
+	"github.com/go-chi/chi/v5"
+	"github.com/urfave/cli/v2"
+)
+
+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
+		}
+
+		// Only fall back to build info when the version was not injected via
+		// -ldflags (i.e. still the "dev" default, e.g. `go install …@vX.Y.Z`).
+		// This keeps an explicitly stamped release version from being clobbered
+		// by a VCS pseudo-version (e.g. v0.0.0-… from a shallow checkout).
+		if version == "dev" && 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")
+				}
+			}
+		}
+	}
+}
+
+// warnIfInvokedAsWeb prints a one-line deprecation notice when the binary is
+// run under its old name (soundtouch-web). That name is no longer published,
+// but anyone who renamed the binary still gets nudged to soundtouch-player.
+func warnIfInvokedAsWeb() {
+	if len(os.Args) == 0 {
+		return
+	}
+
+	name := filepath.Base(os.Args[0])
+	if name == "soundtouch-web" || name == "soundtouch-web.exe" {
+		log.Println("notice: 'soundtouch-web' has been renamed to 'soundtouch-player'. " +
+			"The 'soundtouch-web' name is no longer published; please switch to 'soundtouch-player'.")
+	}
+}
+
+func main() {
+	updateBuildInfo()
+	warnIfInvokedAsWeb()
+
+	app := &cli.App{
+		Name:  "soundtouch-player",
+		Usage: "LAN web player for controlling Bose SoundTouch devices",
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "port",
+				Aliases: []string{"p"},
+				Usage:   "HTTP port to listen on",
+				Value:   "8080",
+				EnvVars: []string{"PORT"},
+			},
+			&cli.StringFlag{
+				Name:    "bind",
+				Usage:   "Address for the HTTP listener: host, IP, or local interface name (e.g. eth0). Leave empty to listen on all interfaces",
+				EnvVars: []string{"BIND_ADDR"},
+			},
+			&cli.StringFlag{
+				Name:    "interface",
+				Usage:   "Network interface name (e.g. eth0) for mDNS and UPnP device discovery. Defaults to the --bind interface name when one was given; leave empty otherwise to auto-pick",
+				EnvVars: []string{"DISCOVERY_INTERFACE"},
+			},
+			&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")
+			rawBind := c.String("bind")
+
+			bindAddr, err := resolveBindAddr(rawBind)
+			if err != nil {
+				log.Fatal(err)
+			}
+
+			if rawBind != "" && bindAddr != rawBind {
+				log.Printf("Resolved --bind %q to %s", 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", sanitizeLog(ifaceName))
+			}
+
+			addr := ":" + port
+			if bindAddr != "" {
+				addr = bindAddr + ":" + port
+			}
+
+			// Create web app without templates (SPA mode)
+			webApp := soundtouchweb.NewWebApp()
+			webApp.Version = version
+			webApp.Commit = commit
+			webApp.Date = date
+			webApp.RepoURL = repoURL
+			webApp.ServiceURL = strings.TrimRight(c.String("service-url"), "/")
+
+			if caPath := c.String("service-ca"); caPath != "" {
+				client, err := soundtouchweb.NewServiceHTTPClient(caPath)
+				if err != nil {
+					log.Fatalf("--service-ca: %v", err)
+				}
+
+				webApp.ServiceClient = client
+
+				log.Printf("Trusting AfterTouch service CA from %s", sanitizeLog(caPath))
+			}
+
+			discoveryService := soundtouchweb.NewDiscoveryService(ifaceName, manualHosts...)
+
+			// Discover devices on startup
+			go func() {
+				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+				defer cancel()
+
+				webApp.BroadcastDiscoveryStatus("starting", webApp.DeviceCount())
+
+				// Register configured devices immediately rather than waiting for
+				// the full mDNS/UPnP sweep below (bounded by cfg.DiscoveryTimeout,
+				// currently 10s) to complete. manualHosts are also folded into
+				// discoveryService's PreferredDevices so a host that's offline
+				// right now still gets retried on every subsequent discovery pass.
+				for _, host := range manualHosts {
+					webApp.AddDeviceByHost(host, 8090, "manual")
+				}
+
+				webApp.DiscoverDevices(ctx, discoveryService)
+
+				webApp.BroadcastDiscoveryStatus("completed", webApp.DeviceCount())
+				webApp.BroadcastDeviceList()
+			}()
+
+			r := chi.NewRouter()
+			webApp.Mount(r, discoveryService)
+
+			log.Printf("AfterTouch Web UI starting on http://%s", sanitizeLog(addr))
+
+			return http.ListenAndServe(addr, r)
+		},
+	}
+
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}
+
+// defaultDiscoveryInterface picks the interface name to use for mDNS/UPnP
+// discovery. An explicit --interface always wins; otherwise, when --bind was
+// given an interface name (i.e. resolveBindAddr substituted an IP for it),
+// that name is reused so the common single-interface case "just works".
+// Returns the empty string when there is nothing to propagate, leaving the
+// discovery service to auto-pick.
+func defaultDiscoveryInterface(rawInterface, rawBind, resolvedBind string) string {
+	if rawInterface != "" {
+		return rawInterface
+	}
+
+	if rawBind != "" && rawBind != resolvedBind {
+		return rawBind
+	}
+
+	return ""
+}
+
+// resolveBindAddr returns the address to bind the HTTP listener to.
+//
+// If bindAddr names a local network interface, the interface's single IPv4
+// address is returned. When no IPv4 is present, the function falls back to the
+// interface's single non-link-local IPv6 address (wrapped in brackets so it
+// composes correctly with ":port"). Ambiguous interfaces (multiple addresses
+// in the chosen family) or interfaces with no usable address produce an error,
+// so misconfiguration surfaces immediately instead of becoming an obscure DNS
+// lookup failure at listen time.
+//
+// If bindAddr is not an interface name — including the empty string, a host
+// name, or a literal IP — it is returned unchanged.
+func resolveBindAddr(bindAddr string) (string, error) {
+	// A lookup failure here just means bindAddr isn't an interface name
+	// (it's a host, IP, or empty); fall through to pass-through.
+	iface, _ := net.InterfaceByName(bindAddr)
+	if iface == nil {
+		return bindAddr, nil
+	}
+
+	addrs, err := iface.Addrs()
+	if err != nil {
+		return "", fmt.Errorf("--bind %q: failed to list addresses for interface: %w", bindAddr, err)
+	}
+
+	var ipv4, ipv6 []net.IP
+
+	for _, addr := range addrs {
+		var ip net.IP
+
+		switch v := addr.(type) {
+		case *net.IPNet:
+			ip = v.IP
+		case *net.IPAddr:
+			ip = v.IP
+		}
+
+		if ip == nil {
+			continue
+		}
+
+		if v4 := ip.To4(); v4 != nil {
+			ipv4 = append(ipv4, v4)
+		} else if !ip.IsLinkLocalUnicast() {
+			// Skip IPv6 link-local (fe80::); it requires a zone ID and
+			// can't be used as a plain "[ip]:port" listen address.
+			ipv6 = append(ipv6, ip)
+		}
+	}
+
+	switch {
+	case len(ipv4) == 1:
+		return ipv4[0].String(), nil
+	case len(ipv4) > 1:
+		return "", fmt.Errorf("--bind %q: interface has multiple IPv4 addresses (%v); specify one directly", bindAddr, ipv4)
+	case len(ipv6) == 1:
+		return "[" + ipv6[0].String() + "]", nil
+	case len(ipv6) > 1:
+		return "", fmt.Errorf("--bind %q: interface has multiple IPv6 addresses (%v); specify one directly", bindAddr, ipv6)
+	default:
+		return "", fmt.Errorf("--bind %q: interface has no usable IPv4 or IPv6 address", bindAddr)
+	}
+}

cmd/soundtouch-player/resolve_bind_addr_test.go

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

cmd/soundtouch-player/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-service/admin_area_auth_gate_test.go

@@ -0,0 +1,117 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/certmanager"
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
+	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
+)
+
+// TestAdminAreaAuthGate is the wiring-level regression test for #419: it
+// exercises the real production router (setupRouter), not just the
+// BasicAuthAdmin middleware in isolation, to pin two things at once:
+//  1. /admin and /api/setup/* (and their /setup/* legacy aliases) are open
+//     by default and become gated once AdminAreaAuth is "enabled".
+//  2. A handful of routes deliberately stay reachable WITHOUT credentials
+//     regardless of the gate: ca.crt/tts/speak/tts/config because
+//     soundtouch-cli/soundtouch-player call them directly (the whole reason
+//     mountSetupAPI was split into mountSetupAPIShared/mountSetupAPIAdmin),
+//     and /api/announcements because it specifically needs to reach
+//     operators who haven't set up credentials yet.
+func TestAdminAreaAuthGate(t *testing.T) {
+	tempDir := t.TempDir()
+
+	ds := datastore.NewDataStore(tempDir)
+	_ = ds.Initialize()
+
+	// A real setup.Manager (with an actual CA) so /setup/ca.crt genuinely
+	// succeeds instead of failing on a nil dependency for an unrelated
+	// reason, which would make the "stays reachable" assertion meaningless.
+	cm := certmanager.NewCertificateManager(filepath.Join(tempDir, "certs"))
+	_ = cm.EnsureCA()
+	sm := setup.NewManager("http://localhost:8000", ds, cm)
+
+	server := handlers.NewServer(ds, sm, "http://localhost:8000", true, false, false)
+	server.SetMgmtConfig("custom-admin", "custom-password")
+
+	r := setupRouter(server, nil, nil)
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	adminGatedPaths := []string{
+		"/admin",
+		"/setup/settings",
+		"/api/setup/settings",
+	}
+	alwaysUngatedPaths := []string{
+		"/setup/ca.crt",
+		"/api/setup/ca.crt",
+		"/setup/tts/config",
+		"/api/setup/tts/config",
+		"/api/announcements?target=admin",
+	}
+
+	t.Run("open by default (AdminAreaAuth unset)", func(t *testing.T) {
+		for _, path := range adminGatedPaths {
+			status := getStatus(t, ts.URL, path, "", "")
+			if status == http.StatusUnauthorized {
+				t.Errorf("%s: expected open access by default, got 401", path)
+			}
+		}
+	})
+
+	server.SetAdminAreaAuth("enabled")
+	defer server.SetAdminAreaAuth("")
+
+	t.Run("gated paths reject without credentials once enabled", func(t *testing.T) {
+		for _, path := range adminGatedPaths {
+			status := getStatus(t, ts.URL, path, "", "")
+			if status != http.StatusUnauthorized {
+				t.Errorf("%s: expected 401 without credentials once enabled, got %d", path, status)
+			}
+		}
+	})
+
+	t.Run("gated paths accept correct credentials once enabled", func(t *testing.T) {
+		for _, path := range adminGatedPaths {
+			status := getStatus(t, ts.URL, path, "custom-admin", "custom-password")
+			if status == http.StatusUnauthorized {
+				t.Errorf("%s: expected access with correct credentials, got 401", path)
+			}
+		}
+	})
+
+	t.Run("routes intentionally left outside the gate stay reachable without credentials", func(t *testing.T) {
+		for _, path := range alwaysUngatedPaths {
+			status := getStatus(t, ts.URL, path, "", "")
+			if status != http.StatusOK {
+				t.Errorf("%s: expected 200 without credentials even with the gate enabled, got %d", path, status)
+			}
+		}
+	})
+}
+
+func getStatus(t *testing.T, base, path, user, pass string) int {
+	t.Helper()
+
+	req, err := http.NewRequest(http.MethodGet, base+path, nil)
+	if err != nil {
+		t.Fatalf("Failed to build request for %s: %v", path, err)
+	}
+	if user != "" || pass != "" {
+		req.SetBasicAuth(user, pass)
+	}
+
+	res, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatalf("Request to %s failed: %v", path, err)
+	}
+	defer res.Body.Close()
+
+	return res.StatusCode
+}

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, 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, 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, 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

@@ -1,12 +1,147 @@
 package main
 
 import (
+	"flag"
 	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/urfave/cli/v2"
 )
 
+// newTestServiceContext builds a real *cli.Context against serviceFlags (the
+// exact flags soundtouch-service registers), so loadConfig tests exercise the
+// same parsing/env-var wiring production code does, instead of a hand-rolled
+// stand-in that could silently drift from it.
+func newTestServiceContext(t *testing.T, args ...string) *cli.Context {
+	t.Helper()
+
+	app := &cli.App{Flags: serviceFlags}
+	set := flag.NewFlagSet("test", flag.ContinueOnError)
+
+	for _, f := range serviceFlags {
+		if err := f.Apply(set); err != nil {
+			t.Fatalf("apply flag %v: %v", f.Names(), err)
+		}
+	}
+
+	if err := set.Parse(args); err != nil {
+		t.Fatalf("parse args %v: %v", args, err)
+	}
+
+	return cli.NewContext(app, set, nil)
+}
+
+func TestResolveFallbackHost(t *testing.T) {
+	hostname, _ := os.Hostname()
+	if hostname == "" {
+		hostname = "localhost"
+	}
+
+	hostname = strings.ToLower(hostname)
+
+	cases := []struct {
+		name           string
+		deploymentMode string
+		wantHost       string
+		wantWarn       bool
+	}{
+		{"on-device uses localhost, no warning", "on-device", "localhost", false},
+		{"public-network returns no fallback, no warning (caller must fail fast)", "public-network", "", false},
+		{"private-network uses this host's own hostname, with warning", "private-network", hostname, true},
+		{"unset/legacy behaves like private-network", "", hostname, true},
+		{"unrecognized mode behaves like private-network", "some-typo", hostname, true},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			gotHost, gotWarn := resolveFallbackHost(tc.deploymentMode)
+			if gotHost != tc.wantHost {
+				t.Errorf("host: got %q, want %q", gotHost, tc.wantHost)
+			}
+
+			if gotWarn != tc.wantWarn {
+				t.Errorf("warnOnUse: got %v, want %v", gotWarn, tc.wantWarn)
+			}
+		})
+	}
+}
+
+func TestLoadConfig_DeploymentMode(t *testing.T) {
+	t.Run("on-device with no --server-url defaults to localhost", func(t *testing.T) {
+		config, err := loadConfig(newTestServiceContext(t, "--deployment-mode=on-device", "--port=8000"))
+		if err != nil {
+			t.Fatalf("loadConfig: unexpected error: %v", err)
+		}
+
+		if config.serverURL != "http://localhost:8000" {
+			t.Errorf("serverURL: got %q, want %q", config.serverURL, "http://localhost:8000")
+		}
+
+		if config.httpsDefaultURL != "https://localhost:8443" {
+			t.Errorf("httpsDefaultURL: got %q, want %q", config.httpsDefaultURL, "https://localhost:8443")
+		}
+	})
+
+	t.Run("public-network with no --server-url fails fast instead of guessing", func(t *testing.T) {
+		_, err := loadConfig(newTestServiceContext(t, "--deployment-mode=public-network"))
+		if err == nil {
+			t.Fatal("expected an error, got nil")
+		}
+
+		if !strings.Contains(err.Error(), "public-network") {
+			t.Errorf("expected error to mention public-network, got: %v", err)
+		}
+	})
+
+	t.Run("public-network with an explicit --server-url succeeds", func(t *testing.T) {
+		config, err := loadConfig(newTestServiceContext(t,
+			"--deployment-mode=public-network", "--server-url=https://soundtouch.example.com"))
+		if err != nil {
+			t.Fatalf("loadConfig: unexpected error: %v", err)
+		}
+
+		if config.serverURL != "https://soundtouch.example.com" {
+			t.Errorf("serverURL: got %q, want %q", config.serverURL, "https://soundtouch.example.com")
+		}
+	})
+
+	t.Run("unset deployment-mode with no --server-url keeps today's hostname fallback", func(t *testing.T) {
+		hostname, _ := os.Hostname()
+		if hostname == "" {
+			hostname = "localhost"
+		}
+
+		hostname = strings.ToLower(hostname)
+
+		config, err := loadConfig(newTestServiceContext(t, "--port=8000"))
+		if err != nil {
+			t.Fatalf("loadConfig: unexpected error: %v", err)
+		}
+
+		want := "http://" + hostname + ":8000"
+		if config.serverURL != want {
+			t.Errorf("serverURL: got %q, want %q (legacy installs must keep working without --deployment-mode)", config.serverURL, want)
+		}
+	})
+
+	t.Run("explicit --server-url always wins regardless of deployment-mode", func(t *testing.T) {
+		for _, mode := range []string{"", "on-device", "private-network", "public-network"} {
+			config, err := loadConfig(newTestServiceContext(t,
+				"--deployment-mode="+mode, "--server-url=http://198.51.100.7:8000"))
+			if err != nil {
+				t.Fatalf("mode %q: loadConfig: unexpected error: %v", mode, err)
+			}
+
+			if config.serverURL != "http://198.51.100.7:8000" {
+				t.Errorf("mode %q: serverURL: got %q, want explicit override unchanged", mode, config.serverURL)
+			}
+		}
+	})
+}
+
 func TestApplyPersistedSettings(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "main-test")
 	if err != nil {
@@ -90,3 +225,180 @@ 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
+}
+
+func TestSettingsFileExists(t *testing.T) {
+	dir := t.TempDir()
+
+	if settingsFileExists(dir) {
+		t.Fatal("expected false for a dir without settings.json")
+	}
+
+	if err := os.WriteFile(filepath.Join(dir, "settings.json"), []byte("{}"), 0o644); err != nil {
+		t.Fatalf("write settings.json: %v", err)
+	}
+
+	if !settingsFileExists(dir) {
+		t.Fatal("expected true once settings.json is present")
+	}
+
+	if settingsFileExists("") {
+		t.Fatal("expected false for an empty data dir")
+	}
+}
+
+// applyFirstRunSeed mirrors the startup gate in the CLI Action: a default
+// settings.json is written only when none exists yet, so a hand-authored file
+// is never clobbered.
+func applyFirstRunSeed(ds *datastore.DataStore, config *serviceConfig) {
+	existed := settingsFileExists(config.dataDir)
+
+	applyPersistedSettings(ds, config)
+
+	if !existed {
+		createDefaultSettings(ds, *config)
+	}
+}
+
+func TestFirstRunSeed_PreservesHandAuthoredSettings(t *testing.T) {
+	dir := t.TempDir()
+
+	// Operator pre-seeds proxy trust but leaves server_url to the --server-url
+	// flag. Before the fix this was treated as "first run" and overwritten.
+	if err := os.WriteFile(filepath.Join(dir, "settings.json"),
+		[]byte(`{"trust_forwarded_headers":true,"trusted_proxy_cidrs":["10.0.0.0/8"]}`), 0o644); err != nil {
+		t.Fatalf("write settings.json: %v", err)
+	}
+
+	ds := datastore.NewDataStore(dir)
+	config := &serviceConfig{dataDir: dir, serverURL: "http://192.0.2.1:8000"}
+
+	applyFirstRunSeed(ds, config)
+
+	got, err := ds.GetSettings()
+	if err != nil {
+		t.Fatalf("GetSettings: %v", err)
+	}
+
+	if !got.TrustForwardedHeaders {
+		t.Error("trust_forwarded_headers was clobbered on startup")
+	}
+
+	if len(got.TrustedProxyCIDRs) != 1 || got.TrustedProxyCIDRs[0] != "10.0.0.0/8" {
+		t.Errorf("trusted_proxy_cidrs was clobbered, got %v", got.TrustedProxyCIDRs)
+	}
+}
+
+func TestFirstRunSeed_WritesDefaultsWhenAbsent(t *testing.T) {
+	dir := t.TempDir()
+
+	ds := datastore.NewDataStore(dir)
+	config := &serviceConfig{dataDir: dir, serverURL: "http://192.0.2.1:8000"}
+
+	applyFirstRunSeed(ds, config)
+
+	got, err := ds.GetSettings()
+	if err != nil {
+		t.Fatalf("GetSettings: %v", err)
+	}
+
+	if got.ServerURL != "http://192.0.2.1:8000" {
+		t.Errorf("expected defaults to be written with server_url, got %q", got.ServerURL)
+	}
+}

cmd/soundtouch-service/router_test.go

@@ -3,6 +3,7 @@ package main
 import (
 	"fmt"
 	"net/http"
+	"net/http/httptest"
 	"os"
 	"reflect"
 	"runtime"
@@ -10,14 +11,18 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
 	"github.com/gesellix/bose-soundtouch/pkg/service/handlers"
+	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
 	"github.com/go-chi/chi/v5"
 )
 
 func TestPrintRoutes(t *testing.T) {
-	// Initialize a minimal server to get the router
+	// Initialize a minimal server to get the router. Pass a web app so the
+	// snapshot also captures the embedded soundtouch-player surface
+	// (/api/control + /app); discovery is nil since we only register routes.
 	server := handlers.NewServer(nil, nil, "http://localhost:8000", true, true, true)
-	r := setupRouter(server)
+	r := setupRouter(server, nil, soundtouchweb.NewWebApp())
 
 	var routes []string
 	walkFunc := func(method string, route string, handler http.Handler, middlewares ...func(http.Handler) http.Handler) error {
@@ -34,11 +39,8 @@ func TestPrintRoutes(t *testing.T) {
 		// Now we might have "soundtouch-service.setupRouter.func1"
 		// or "command-line-arguments.setupRouter.func1"
 		// or "main.setupRouter.func1"
-		// Let's remove the first part if it's a known varying package name
-		if idx := strings.Index(handlerName, "setupRouter"); idx != -1 {
-			handlerName = handlerName[idx:]
-		}
-		// In case it's not setupRouter but still has a package prefix
+		// Remove the leading package/binary-name segment(s), whatever form
+		// they take.
 		for {
 			dotIdx := strings.Index(handlerName, ".")
 			if dotIdx == -1 {
@@ -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, 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,121 @@
-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/control/devices/{id}/                                   soundtouchweb.(*WebApp).HandleDeleteDevice-fm
+DELETE   /api/control/devices/{id}/library/servers/{account}          soundtouchweb.(*WebApp).HandleRemoveLibraryServer-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      /admin                                                       handlers.(*Server).HandleAdmin-fm
+GET      /api/announcements                                           handlers.(*Server).HandleListAnnouncements-fm
+GET      /api/control/devices/                                        soundtouchweb.(*WebApp).HandleAPIDevices-fm
+GET      /api/control/devices/{id}/                                   soundtouchweb.(*WebApp).HandleAPIDevice-fm
+GET      /api/control/devices/{id}/action/{action}                    soundtouchweb.(*WebApp).HandleAPIControl-fm
+GET      /api/control/devices/{id}/library/browse                     soundtouchweb.(*WebApp).HandleLibraryBrowse-fm
+GET      /api/control/devices/{id}/library/servers                    soundtouchweb.(*WebApp).HandleDeviceLibraryServers-fm
+GET      /api/control/devices/{id}/power-status                       soundtouchweb.(*WebApp).HandleDevicePowerStatus-fm
+GET      /api/control/devices/{id}/recents                            soundtouchweb.(*WebApp).HandleDeviceRecents-fm
+GET      /api/control/devices/{id}/ws                                 soundtouchweb.(*WebApp).HandleDeviceWebSocket-fm
+GET      /api/control/devices/{id}/zone/                              soundtouchweb.(*WebApp).HandleGetZone-fm
+GET      /api/control/providers/library/servers                       soundtouchweb.(*WebApp).HandleDiscoverLibraryServers-fm
+GET      /api/control/providers/radiobrowser/search                   soundtouchweb.(*WebApp).HandleRadioBrowserSearch-fm
+GET      /api/control/providers/tunein/navigate                       soundtouchweb.(*WebApp).HandleTuneInNavigate-fm
+GET      /api/control/providers/tunein/navigate/*                     soundtouchweb.(*WebApp).HandleTuneInNavigate-fm
+GET      /api/control/providers/tunein/search                         soundtouchweb.(*WebApp).HandleTuneInSearch-fm
+GET      /api/control/providers/tunein/search/next                    soundtouchweb.(*WebApp).HandleTuneInSearchNext-fm
+GET      /api/control/version                                         soundtouchweb.(*WebApp).HandleAPIVersion-fm
+GET      /api/control/ws                                              soundtouchweb.(*WebApp).HandleWebSocket-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      /app                                                         soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/device/*                                                soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/devices                                                 soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/library                                                 soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/playurl                                                 soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/radiobrowser                                            soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/static/*                                                http.Handler.ServeHTTP-fm
+GET      /app/tts                                                     soundtouchweb.(*WebApp).serveIndex-fm
+GET      /app/tunein                                                  soundtouchweb.(*WebApp).serveIndex-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,23 +126,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
@@ -84,22 +167,74 @@ 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
+GET      /web/*                                                       handlers.(*Server).HandleWeb
+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/announcements/{id}/dismiss                              handlers.(*Server).HandleDismissAnnouncement-fm
+POST     /api/control/devices/{id}/action/{action}                    soundtouchweb.(*WebApp).HandleAPIControl-fm
+POST     /api/control/devices/{id}/key/{key}                          soundtouchweb.(*WebApp).HandleDeviceKey-fm
+POST     /api/control/devices/{id}/library/play                       soundtouchweb.(*WebApp).HandlePlayLibrary-fm
+POST     /api/control/devices/{id}/library/servers                    soundtouchweb.(*WebApp).HandleAddLibraryServer-fm
+POST     /api/control/devices/{id}/play                               soundtouchweb.(*WebApp).HandleDevicePlay-fm
+POST     /api/control/devices/{id}/power                              soundtouchweb.(*WebApp).HandleDevicePower-fm
+POST     /api/control/devices/{id}/providers/radiobrowser/play        soundtouchweb.(*WebApp).HandlePlayRadioBrowser-fm
+POST     /api/control/devices/{id}/providers/tts/play                 soundtouchweb.(*WebApp).HandleAPISpeakText-fm
+POST     /api/control/devices/{id}/providers/tunein/play              soundtouchweb.(*WebApp).HandlePlayTuneIn-fm
+POST     /api/control/devices/{id}/providers/url/play                 soundtouchweb.(*WebApp).HandlePlayURL-fm
+POST     /api/control/devices/{id}/volume/{volume}                    soundtouchweb.(*WebApp).HandleDirectVolumeControl-fm
+POST     /api/control/devices/{id}/zone/add/{slaveId}                 soundtouchweb.(*WebApp).HandleZoneAdd-fm
+POST     /api/control/devices/{id}/zone/dissolve                      soundtouchweb.(*WebApp).HandleZoneDissolve-fm
+POST     /api/control/devices/{id}/zone/leave                         soundtouchweb.(*WebApp).HandleZoneLeave-fm
+POST     /api/control/devices/{id}/zone/remove/{slaveId}              soundtouchweb.(*WebApp).HandleZoneRemove-fm
+POST     /api/control/discover                                        soundtouchweb.(*WebApp).MountWeb
+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
@@ -111,7 +246,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
@@ -120,8 +254,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/proxy-settings                                        handlers.(*Server).HandleUpdateProxySettings-fm
+POST     /setup/pair-account/{deviceId}                               handlers.(*Server).HandlePairAccount-fm
+POST     /setup/peer-probe/{deviceId}                                 handlers.(*Server).HandlePeerProbe-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
@@ -131,6 +269,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
@@ -138,6 +277,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
@@ -149,6 +289,11 @@ 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
+QUERY    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handlers.(*Server).HandleSiriusXMLiveAdapter-fm
+QUERY    /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter/* handlers.(*Server).HandleSiriusXMLiveAdapterSubpath-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-service/update_check_test.go

@@ -0,0 +1,156 @@
+package main
+
+import (
+	"testing"
+	"time"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/updatecheck"
+)
+
+func TestShouldCheckImmediately(t *testing.T) {
+	now := time.Date(2026, 8, 9, 12, 0, 0, 0, time.UTC)
+	interval := 24 * time.Hour
+
+	cases := []struct {
+		name          string
+		lastCheckedAt time.Time
+		want          bool
+	}{
+		{"never checked", time.Time{}, true},
+		{"stale (older than interval)", now.Add(-25 * time.Hour), true},
+		{"exactly one interval ago", now.Add(-interval), true},
+		{"recent (within interval)", now.Add(-1 * time.Hour), false},
+	}
+
+	for _, tc := range cases {
+		if got := shouldCheckImmediately(tc.lastCheckedAt, interval, now); got != tc.want {
+			t.Errorf("%s: shouldCheckImmediately() = %v, want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestShouldSkipDueToBackoff(t *testing.T) {
+	now := time.Date(2026, 8, 9, 12, 0, 0, 0, time.UTC)
+
+	cases := []struct {
+		name        string
+		lastErrorAt time.Time
+		want        bool
+	}{
+		{"no recent failure", time.Time{}, false},
+		{"failed 30 minutes ago", now.Add(-30 * time.Minute), true},
+		{"failed exactly 1 hour ago", now.Add(-time.Hour), false},
+		{"failed 2 hours ago", now.Add(-2 * time.Hour), false},
+	}
+
+	for _, tc := range cases {
+		if got := shouldSkipDueToBackoff(tc.lastErrorAt, now); got != tc.want {
+			t.Errorf("%s: shouldSkipDueToBackoff() = %v, want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestLogUpdateIfNewlyAvailable(t *testing.T) {
+	cases := []struct {
+		name              string
+		result            updatecheck.Result
+		lastLoggedVersion string
+		want              string
+	}{
+		{
+			name:              "nothing available",
+			result:            updatecheck.Result{Available: false},
+			lastLoggedVersion: "",
+			want:              "",
+		},
+		{
+			name:              "newly available",
+			result:            updatecheck.Result{Available: true, LatestVersion: "v1.1.0"},
+			lastLoggedVersion: "",
+			want:              "v1.1.0",
+		},
+		{
+			name:              "already logged this version",
+			result:            updatecheck.Result{Available: true, LatestVersion: "v1.1.0"},
+			lastLoggedVersion: "v1.1.0",
+			want:              "v1.1.0",
+		},
+		{
+			name:              "a newer version than what was logged",
+			result:            updatecheck.Result{Available: true, LatestVersion: "v1.2.0"},
+			lastLoggedVersion: "v1.1.0",
+			want:              "v1.2.0",
+		},
+	}
+
+	for _, tc := range cases {
+		if got := logUpdateIfNewlyAvailable(tc.result, tc.lastLoggedVersion); got != tc.want {
+			t.Errorf("%s: logUpdateIfNewlyAvailable() = %q, want %q", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestRandomJitter(t *testing.T) {
+	if got := randomJitter(0); got != 0 {
+		t.Errorf("randomJitter(0) = %v, want 0", got)
+	}
+
+	upperBound := 5 * time.Minute
+	for i := 0; i < 20; i++ {
+		got := randomJitter(upperBound)
+		if got < 0 || got >= upperBound {
+			t.Fatalf("randomJitter(%v) = %v, want in [0, %v)", upperBound, got, upperBound)
+		}
+	}
+}
+
+// There is deliberately no test for startUpdateCheck itself, matching
+// startDeviceDiscovery (its equally untested sibling): both are thin,
+// forever-looping goroutine wrappers whose only decisions live in pure
+// helpers, which is what the tests above and below cover. The former
+// TestStartUpdateCheck_DisabledIsANoOp asserted a contract that no longer
+// exists — the goroutine now always starts, precisely so that enabling the
+// check from the Settings page takes effect without a restart, and an
+// early return for "disabled" would defeat that.
+func TestShouldRunUpdateCheckNow(t *testing.T) {
+	now := time.Date(2026, 8, 10, 12, 0, 0, 0, time.UTC)
+	interval := 24 * time.Hour
+	stale := now.Add(-25 * time.Hour)
+	fresh := now.Add(-1 * time.Hour)
+
+	cases := []struct {
+		name          string
+		enabled       bool
+		lastCheckedAt time.Time
+		interval      time.Duration
+		lastErrorAt   time.Time
+		want          bool
+	}{
+		{"disabled, never checked", false, time.Time{}, interval, time.Time{}, false},
+		{"disabled, due", false, stale, interval, time.Time{}, false},
+		{"enabled, never checked", true, time.Time{}, interval, time.Time{}, true},
+		{"enabled, due", true, stale, interval, time.Time{}, true},
+		{"enabled, not due yet", true, fresh, interval, time.Time{}, false},
+		{"enabled and due, but in error backoff", true, stale, interval, now.Add(-30 * time.Minute), false},
+		{"enabled and due, backoff expired", true, stale, interval, now.Add(-2 * time.Hour), true},
+		// A zero interval must not turn every poll tick into a GitHub request.
+		{"enabled with a zero interval", true, stale, 0, time.Time{}, false},
+	}
+
+	for _, tc := range cases {
+		got := shouldRunUpdateCheckNow(tc.enabled, tc.lastCheckedAt, tc.interval, tc.lastErrorAt, now)
+		if got != tc.want {
+			t.Errorf("%s: shouldRunUpdateCheckNow() = %v, want %v", tc.name, got, tc.want)
+		}
+	}
+}
+
+// TestUpdateCheckPollTickIsShorterThanTheDefaultInterval guards the property
+// that makes the Settings-page toggle feel live: the goroutine must re-read
+// the settings far more often than the check interval itself, otherwise
+// switching the check on would appear to do nothing for up to a day.
+func TestUpdateCheckPollTickIsShorterThanTheDefaultInterval(t *testing.T) {
+	if updateCheckPollTick >= 24*time.Hour {
+		t.Errorf("updateCheckPollTick = %v, want well below the 24h default interval", updateCheckPollTick)
+	}
+}

cmd/soundtouch-web/.gitignore

@@ -1,2 +0,0 @@
-soundtouch-web
-soundtouch-web-test

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/main.go

@@ -1,215 +0,0 @@
-// Package main provides a web UI for controlling Bose SoundTouch devices.
-package main
-
-import (
-	"context"
-	"embed"
-	"io/fs"
-	"log"
-	"net/http"
-	"os"
-	"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/go-chi/chi/v5"
-	"github.com/urfave/cli/v2"
-)
-
-//go:embed static
-var staticFS embed.FS
-
-func main() {
-	app := &cli.App{
-		Name:  "soundtouch-web",
-		Usage: "Web UI for controlling Bose SoundTouch devices",
-		Flags: []cli.Flag{
-			&cli.StringFlag{
-				Name:    "port",
-				Aliases: []string{"p"},
-				Usage:   "HTTP port to listen on",
-				Value:   "8080",
-				EnvVars: []string{"PORT"},
-			},
-			&cli.StringFlag{
-				Name:    "bind",
-				Usage:   "Network interface to bind to",
-				EnvVars: []string{"BIND_ADDR"},
-			},
-		},
-		Action: func(c *cli.Context) error {
-			port := c.String("port")
-			bindAddr := c.String("bind")
-
-			addr := ":" + port
-			if bindAddr != "" {
-				addr = bindAddr + ":" + port
-			}
-
-			// Create web app without templates (SPA mode)
-			webApp := handlers.NewWebApp()
-
-			// Initialize discovery service
-			cfg, err := config.LoadFromEnv()
-			if err != nil {
-				log.Printf("Failed to load config: %v, using defaults", err)
-
-				cfg = config.DefaultConfig()
-			}
-
-			cfg.DiscoveryTimeout = 10 * time.Second
-			cfg.CacheEnabled = true
-
-			discoveryService := discovery.NewUnifiedDiscoveryService(cfg)
-
-			// Discover devices on startup
-			go func() {
-				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-				defer cancel()
-
-				webApp.BroadcastDiscoveryStatus("starting", len(webApp.Devices))
-
-				discoverDevices(ctx, webApp, discoveryService)
-
-				webApp.BroadcastDiscoveryStatus("completed", len(webApp.Devices))
-				webApp.BroadcastDeviceList()
-			}()
-
-			r := setupRoutes(webApp, discoveryService)
-
-			log.Printf("SoundTouch Web UI starting on http://%s", addr)
-
-			return http.ListenAndServe(addr, r)
-		},
-	}
-
-	if err := app.Run(os.Args); err != nil {
-		log.Fatal(err)
-	}
-}
-
-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/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,8 +1,11 @@
 accounts/
+backend/
 certs/
 default/
 dns/
 interactions/
 parity_mismatches/
+stats/
 patterns.json
 settings.json
+update-check.json

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.27.0-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.27.0-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.27.0-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,102 +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)
-* [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)