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>
fix(player): address code review findings on #644
2026-08-24 14:47:23 +00:00 · 2026-08-23 22:00:11 +02:00 · 2026-08-23 22:00:11 +02:00 · 2026-08-23 22:00:11 +02:00 · 2026-08-23 20:50:27 +02:00 · 2026-08-23 20:50:27 +02:00
524 changed files with 39752 additions and 5631 deletions
@@ -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.
@@ -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.0.2.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
@@ -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.0.2.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
@@ -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."
@@ -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.0.2.100 info get
-soundtouch-cli --host 192.0.2.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
@@ -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
@@ -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.0.2.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
@@ -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.0.2.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
@@ -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"
@@ -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:
@@ -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"
@@ -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.0.2.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.0.2.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).
@@ -17,15 +17,15 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: "go.mod"

      - name: Cache Go modules
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        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@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6.0.1
+        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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        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@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
+        uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
        with:
          version: latest
          args: --timeout=5m
@@ -107,15 +107,15 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: "go.mod"

      - name: Cache Go modules
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: |
            ~/.cache/go-build
@@ -143,7 +143,9 @@ jobs:

          mkdir -p build

-          for binary in soundtouch-cli soundtouch-service soundtouch-web soundtouch-backup; do
+          # 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"
@@ -163,10 +165,10 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: "go.mod"

@@ -190,12 +192,12 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        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: |
@@ -215,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

@@ -226,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"
@@ -234,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"
@@ -248,10 +250,10 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: "go.mod"

@@ -303,10 +305,14 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        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
@@ -324,7 +330,7 @@ jobs:

      - name: Log in to GitHub Container Registry
        if: steps.push-check.outputs.should-push == 'true'
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
@@ -332,7 +338,7 @@ jobs:

      - name: Extract metadata (tags, labels) for soundtouch-service
        id: meta-service
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
@@ -342,7 +348,7 @@ jobs:
            type=ref,event=branch,prefix=preview-branch-,enable=${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}

      - name: Build and push soundtouch-service Docker image
-        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
        with:
          context: .
          target: soundtouch-service
@@ -350,29 +356,35 @@ jobs:
          push: ${{ steps.push-check.outputs.should-push == 'true' }}
          tags: ${{ steps.meta-service.outputs.tags }}
          labels: ${{ steps.meta-service.outputs.labels }}
+          build-args: |
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

-      - name: Extract metadata (tags, labels) for soundtouch-web
-        id: meta-web
-        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+      - 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,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@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+      - 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: ${{ steps.push-check.outputs.should-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: |
+            COMMIT=${{ github.sha }}
+            DATE=${{ steps.build_date.outputs.date }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

@@ -380,7 +392,7 @@ jobs:
        if: steps.push-check.outputs.should-push == 'true'
        env:
          SERVICE_TAGS: ${{ steps.meta-service.outputs.tags }}
-          WEB_TAGS: ${{ steps.meta-web.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 }}
@@ -404,12 +416,12 @@ jobs:
            done <<< "$SERVICE_TAGS"
            echo '```'
            echo ""
-            echo "### soundtouch-web"
+            echo "### soundtouch-player"
            echo ""
            echo '```bash'
            while IFS= read -r tag; do
              [[ -n "$tag" ]] && echo "docker pull $tag"
-            done <<< "$WEB_TAGS"
+            done <<< "$PLAYER_TAGS"
            echo '```'
          } >> "$GITHUB_STEP_SUMMARY"

@@ -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 }}"
@@ -20,14 +20,20 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Setup Pages
+        id: pages
        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
-      - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@44a6e6beabd48582f863aeeb6cb2151cc1716697 # v1.0.13
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@2752ce1d29631191ea3f27c23495fa06139a5b78 # v3.2.1
        with:
-          source: 'docs/'
-          destination: '_site'
+          hugo-version: 'latest'
+          extended: true
+      - name: Build with Hugo
+        run: hugo --source docs/ --minify --destination ../_site --baseURL "${{ steps.pages.outputs.base_url }}"
+        env:
+          HUGO_ENVIRONMENT: production
+          HUGO_PARAMS_GITHASH: ${{ github.sha }}
      - name: Upload artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
@@ -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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        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@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.validate.outputs.tag }}

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: ${{ env.GO_VERSION_FILE }}

      - name: Cache Go modules
-        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        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
@@ -212,7 +236,7 @@ jobs:
          path: |
            build/soundtouch-cli-v*
            build/soundtouch-service-v*
-            build/soundtouch-web-v*
+            build/soundtouch-player-v*
            build/soundtouch-backup-v*
          retention-days: 1

@@ -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
@@ -305,8 +329,9 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
+          ref: ${{ needs.validate.outputs.tag }}
          fetch-depth: 0

      - name: Download 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.0.2.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@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        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@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@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
+        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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        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@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5 # v4.1.0
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0

      - name: Log in to GitHub Container Registry
-        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4.2.0
+        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@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+        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@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+        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@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
+      - 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@f9f3042f7e2789586610d6e8b85c8f03e5195baf # v7.2.0
+      - 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:"
@@ -19,20 +19,18 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        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@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: vulnerability-scan-results
-          path: |
-            vulnerability-report.json
-            nancy-report.json
-
  static-analysis:
    name: Static Security Analysis
    runs-on: ubuntu-latest
@@ -63,10 +46,10 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
+        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: "go.mod"

@@ -95,40 +78,11 @@ jobs:

      - name: Upload Semgrep SARIF results
        if: always()
-        uses: github/codeql-action/upload-sarif@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4.35.5
+        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@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Install libpcap
-        run: sudo apt-get install -y libpcap-dev
-
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4.35.5
-        with:
-          languages: go
-          config-file: ./.github/codeql-config.yml
-
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4.35.5
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@9e0d7b8d25671d64c341c19c0152d693099fb5ba # v4.35.5
-        with:
-          category: "/language:go"
-
  dependency-review:
    name: Dependency Review
    runs-on: ubuntu-latest
@@ -138,7 +92,7 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Dependency Review
        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
@@ -150,7 +104,7 @@ jobs:
  security-summary:
    name: Security Summary
    runs-on: ubuntu-latest
-    needs: [vulnerability-scan, static-analysis, codeql-analysis]
+    needs: [vulnerability-scan, static-analysis]
    if: always()
    permissions:
      contents: read
@@ -173,17 +127,11 @@ jobs:
            echo "❌ **Static Analysis**: FAILED" >> $GITHUB_STEP_SUMMARY
          fi

-          if [[ "${{ needs.codeql-analysis.result }}" == "success" ]]; then
-            echo "✅ **CodeQL Analysis**: PASSED" >> $GITHUB_STEP_SUMMARY
-          else
-            echo "❌ **CodeQL Analysis**: FAILED" >> $GITHUB_STEP_SUMMARY
-          fi
-
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "For detailed results, check the individual job logs above." >> $GITHUB_STEP_SUMMARY

      - name: Fail on security issues
-        if: needs.vulnerability-scan.result == 'failure' || needs.static-analysis.result == 'failure' || needs.codeql-analysis.result == 'failure'
+        if: needs.vulnerability-scan.result == 'failure' || needs.static-analysis.result == 'failure'
        run: |
          echo "Security scan detected issues. Please review the results above."
          exit 1
@@ -16,13 +16,13 @@ jobs:
    if: github.actor == 'dependabot[bot]' || github.event_name == 'workflow_dispatch'
    steps:
      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: ${{ github.head_ref }}
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '24'
          cache: 'npm'
@@ -15,11 +15,13 @@ 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
@@ -48,7 +50,8 @@ node_modules/
 # IDE and editor files
 .vscode/
 .idea/
-.claude/
+.claude/*
+!.claude/commands/
 .junie/
 *.swp
 *.swo
@@ -115,6 +118,10 @@ stockholm_zip/*.zip
 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.
@@ -122,3 +129,9 @@ 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/
@@ -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,7 +78,7 @@ linters:
        linters:
          - errcheck

-      # Carry-over from cmd/soundtouch-web/handlers relocation: same code,
+      # 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"
@@ -18,7 +18,7 @@ Key binaries:
  (status, play, presets, groups, migration, …).
 - `soundtouch-service` — replacement for `streaming.bose.com`
  and the `bmx` services, default port `8000`.
- `soundtouch-web` — Web UI for Radio browsing and device control.
+- `soundtouch-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):
@@ -43,7 +43,7 @@ Per-session pickup notes live in two local files at the repo root (they are `.gi
 make build          # All binaries
 make build-cli      # Just CLI
 make build-service  # Just service
-make build-web      # Just web UI
+make build-player   # Just web player
 make build-all      # Cross-platform builds (Linux, macOS, Windows)
 make install        # Install to $GOPATH/bin

@@ -99,13 +99,41 @@ 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-web/      # Web UI (TuneIn browser, device control)
+  soundtouch-player/      # Web UI (TuneIn browser, device control)
  soundtouch-backup/   # On-device backup helper
  example-*/           # Usage examples
 pkg/
@@ -182,6 +210,12 @@ 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:
@@ -221,6 +255,16 @@ When working with a human user in this repo:
  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
@@ -1,498 +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**!

-## Ways to Contribute
+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:

-All contributions are welcome — large or small:
+- **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, ...)

- **Code suggestions** — bug fixes, new features, refactoring, performance improvements.
- **Documentation updates** — README, guides, examples, troubleshooting notes, inline doc comments.
- **Bug fixes** — even just a clear reproducer in an issue is a real contribution.
- **Donations** — if the project kept a speaker (or several) of yours alive past the Bose cloud shutdown and you want to give back, [GitHub Sponsors](https://github.com/sponsors/gesellix) is open. No expectation; everything in this repo stays MIT regardless.
+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.

-By submitting a code or documentation contribution you agree to license it under MIT. The detailed guides below cover the mechanics.
+## Ways to contribute

-## Table of Contents
+- **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.

- [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)
- [Support the Project](#support-the-project)
+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.0.2.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.0.2.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.0.2.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.0.2.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.0.2.100 info get
-   ./soundtouch-cli -h 192.0.2.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
-
-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
-
-### Recognition
-
-Contributors will be:
-
- **Listed in CONTRIBUTORS.md**
- **Mentioned in release notes** for significant contributions
- **Credited in documentation** where appropriate
-
-## Support the Project
-
-If you want to support the maintenance effort beyond code:
+## Support the project

 [![GitHub Sponsors](https://img.shields.io/github/sponsors/gesellix?label=Sponsor%20on%20GitHub&logo=GitHub&color=ea4aaa)](https://github.com/sponsors/gesellix)

-Sponsorship is entirely optional. Code, docs, and bug reports remain the most useful contributions for the project itself.
+Sponsorship is entirely optional. Code, docs, bug reports, and helping others
+remain the most useful contributions.

-## Additional Resources
+## 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.
@@ -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"]
@@ -1,4 +1,4 @@
-.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
+.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
@@ -17,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
@@ -52,7 +52,7 @@ 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)..."
@@ -64,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)..."
@@ -164,10 +164,8 @@ test-http-client-rotate:
 	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" \
@@ -177,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 \
@@ -190,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 \
@@ -199,11 +215,14 @@ 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; \
@@ -224,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:
@@ -315,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..."
@@ -339,19 +358,19 @@ 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.0.2.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:
@@ -454,6 +473,22 @@ screenshots:
 	@echo "Capturing documentation screenshots..."
 	@bash scripts/screenshots/run.sh

+# Documentation site (Hugo + Hextra via Docker)
+# First run: make dev-docs-tidy  (downloads Hextra, writes docs/go.sum)
+# Then:      make dev-docs        (http://localhost:1313, live reload)
+dev-docs:
+	HUGO_PARAMS_GITHASH=$(shell git rev-parse HEAD) docker compose -f docker-compose.docs.yml up
+
+dev-docs-tidy:
+	docker compose -f docker-compose.docs.yml run --rm hugo mod tidy --source docs/
+
+# Run any hugo CLI command inside the docs container:
+#   make hugo ARGS="version"
+#   make hugo ARGS="new content/docs/guides/my-guide.md"
+ARGS ?=
+hugo:
+	docker compose -f docker-compose.docs.yml run --rm hugo --source docs/ $(ARGS)
+
 help:
 	@echo "Available targets:"
 	@echo "  build         - Build the CLI tool, service, and examples"
@@ -478,6 +513,9 @@ help:
 	@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"
@@ -492,9 +530,9 @@ 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"
@@ -519,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.0.2.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"
@@ -2,18 +2,19 @@
 <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, 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/)

 ---

@@ -23,15 +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.

-If you don't want to run a server for this - no problem. The service is small enough to run on the SoundTouch itself. See the [On-Device Installer](./scripts/on-device-install/README.md) for instructions.
+Not sure which approach fits your situation? See the [Deployment Overview](./docs/content/docs/guides/DEPLOYMENT-OVERVIEW.md) — it compares running AfterTouch on a Raspberry Pi or other always-on host against running it directly on the SoundTouch speaker, with links to step-by-step walkthroughs for each path.

-**Two scenarios:**
+**Getting started:**

-**Before shutdown — migrate your existing setup**
-While the Bose cloud is still running, use `soundtouch-backup` to save your account data. The local service web UI then helps with the migration so your speaker keeps its presets and credentials.
+**Already migrated before May 6** — your presets and credentials are preserved. AfterTouch picks up where the Bose cloud left off.

-**After shutdown or factory reset — start fresh**
-Create a local account, configure your speakers, and start using them immediately. No Bose infrastructure required.
+**Starting fresh (or after a factory reset)** — create a local account, configure your speakers, and start using them immediately.

 **Redirecting your speaker**

@@ -50,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.

 ---

@@ -66,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.

 ---

@@ -86,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/)

 ---

@@ -111,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/))

 ---

@@ -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
+}
@@ -43,10 +43,10 @@ func main() {
 		log.Fatalf("start fake speaker: %v", err)
 	}

-	log.Printf("fake speaker HTTP listening on http://%s", s.HTTPAddr())
+	log.Printf("fake speaker HTTP listening on http://%s", sanitizeLog(s.HTTPAddr()))

 	if addr := s.TelnetAddr(); addr != "" {
-		log.Printf("fake speaker telnet listening on tcp://%s", addr)
+		log.Printf("fake speaker telnet listening on tcp://%s", sanitizeLog(addr))
 	}

 	if *register != "" {
@@ -58,7 +58,7 @@ func main() {
 		if err := registerWithService(*register, target); err != nil {
 			log.Printf("self-register failed: %v (continuing anyway)", err)
 		} else {
-			log.Printf("registered %s with service at %s", target, *register)
+			log.Printf("registered %s with service at %s", sanitizeLog(target), sanitizeLog(*register))
 		}
 	}

@@ -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 ""
+}
@@ -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
+}
@@ -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{
@@ -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)
 	}
@@ -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)
 	}
@@ -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)
+	}
+}
@@ -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
@@ -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)
+}
@@ -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)
+		})
+	}
+}
@@ -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 {
@@ -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)
@@ -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)))
+}
@@ -568,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{}
@@ -244,7 +244,10 @@ func renameGroup(c *cli.Context) error {
 	return nil
 }

-// removeGroup tears down the device's stereo pair.
+// removeGroup tears down the device's stereo pair by sending /removeGroup to
+// every member in parallel. Sending it only to the master (as the old code
+// did) leaves the slave stuck in GroupSlave state indefinitely — mirrors the
+// same symmetry as createGroup (see issue #252 comment there).
 func removeGroup(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)
 	PrintDeviceHeader("Removing stereo pair", clientConfig.Host, clientConfig.Port)
@@ -255,11 +258,76 @@ func removeGroup(c *cli.Context) error {
 		return err
 	}

-	if err := stClient.RemoveGroup(); err != nil {
-		PrintError(fmt.Sprintf("Failed to remove group: %v", err))
+	// Fetch current group to learn every member's IP before tearing down.
+	group, err := stClient.GetGroup()
+	if err != nil {
+		PrintError(fmt.Sprintf("Failed to read current group: %v", err))
 		return err
 	}

+	if group.IsEmpty() {
+		fmt.Println("Device is not in a stereo pair — nothing to remove")
+		return nil
+	}
+
+	// Collect the unique set of member IPs. The master is always reachable
+	// via clientConfig.Host; the roles carry all members including slaves.
+	type memberResult struct {
+		ip  string
+		err error
+	}
+
+	members := make([]string, 0, len(group.Roles.Roles))
+	seen := map[string]bool{}
+
+	for _, role := range group.Roles.Roles {
+		if role.IPAddress != "" && !seen[role.IPAddress] {
+			seen[role.IPAddress] = true
+			members = append(members, role.IPAddress)
+		}
+	}
+
+	// Always include the addressed host even if the group response omitted IPs.
+	if !seen[clientConfig.Host] {
+		members = append(members, clientConfig.Host)
+	}
+
+	results := make([]memberResult, len(members))
+
+	var wg sync.WaitGroup
+
+	for i, ip := range members {
+		wg.Add(1)
+
+		go func(idx int, host string) {
+			defer wg.Done()
+
+			mc, mcErr := clientForHost(c, host)
+			if mcErr != nil {
+				results[idx] = memberResult{ip: host, err: mcErr}
+				return
+			}
+
+			results[idx] = memberResult{ip: host, err: mc.RemoveGroup()}
+		}(i, ip)
+	}
+
+	wg.Wait()
+
+	anyErr := false
+
+	for _, r := range results {
+		if r.err != nil {
+			PrintError(fmt.Sprintf("%s /removeGroup failed: %v", r.ip, r.err))
+
+			anyErr = true
+		}
+	}
+
+	if anyErr {
+		return fmt.Errorf("/removeGroup propagation failed")
+	}
+
 	PrintSuccess("Stereo pair removed")

 	return nil
@@ -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
+}
@@ -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
+}
@@ -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 (
@@ -15,6 +15,7 @@ import (

 	"github.com/gesellix/bose-soundtouch/pkg/models"
 	"github.com/gesellix/bose-soundtouch/pkg/service/constants"
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
 	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
 	"github.com/urfave/cli/v2"
 	"golang.org/x/term"
@@ -48,13 +49,16 @@ func setupCommand() *cli.Command {
 			setupWaitAPCmd(),
 			setupWaitOnlineCmd(),
 			setupSSHCheckCmd(),
+			setupEnableSSHCmd(),
 			setupRemoteServicesCmd(),
 			setupInstallCACmd(),
 			setupMigrateCmd(),
+			setupRevertCmd(),
 			setupRebootCmd(),
 			setupVerifyCmd(),
 			setupPlanCmd(),
 			setupPairCmd(),
+			setupSyncCmd(),
 		},
 	}
 }
@@ -516,8 +520,13 @@ func setupSSHCheckCmd() *cli.Command {
 			if err != nil {
 				PrintError(fmt.Sprintf("port 22 not reachable: %v", err))
 				fmt.Println()
-				fmt.Println("Modern SoundTouch firmware (27.x) does not let us enable SSH from")
-				fmt.Println("telnet — those commands were removed. To enable SSH on the speaker:")
+				fmt.Println("Try enabling it over telnet first — this works on many (not all) FW 27.x")
+				fmt.Println("speakers via the port-17000 envswitch trick (#471):")
+				fmt.Println("  soundtouch-cli setup enable-ssh")
+				fmt.Println("For stubborn devices (ST Portable, CineMate 520) where the default")
+				fmt.Println("injection is accepted but sshd never starts, add --full-config.")
+				fmt.Println()
+				fmt.Println("If enable-ssh doesn't work on this device, fall back to the USB-stick method:")
 				fmt.Println("  1. Format a FAT32 USB stick.")
 				fmt.Println("  2. Create an empty file named `remote_services` at its root.")
 				fmt.Println("  3. Plug the stick into the speaker (rear USB port) while it is on.")
@@ -537,6 +546,280 @@ func setupSSHCheckCmd() *cli.Command {
 	}
 }

+// runEnableSSHInjection runs the port-17000 SSH-enable injection over telnet,
+// printing the device transcript as it goes. With fullConfig it sends the
+// #515 sequence (all four config URLs with the injection on margeServerUrl, not
+// just envswitch), pausing commandDelay between each of the 6 steps (5
+// commands + reboot) — see setup.DefaultTelnetCommandDelay for why the pause
+// exists — then reboots; otherwise it sends the single-envswitch default that
+// fires on the speaker's next boseurls check (no pause needed, it's one
+// command).
+func runEnableSSHInjection(m *setup.Manager, host, serviceURL string, fullConfig bool, commandDelay time.Duration) error {
+	var (
+		logs string
+		err  error
+	)
+
+	if fullConfig {
+		// 6 steps total (5 commands + reboot), so 6 gaps between/around them.
+		fmt.Printf("Enabling SSH on %s via telnet :17000 (full #515 sequence: all four config URLs with "+
+			"the injection on margeServerUrl, %s between each of 6 steps — about %s before the reboot fires "+
+			"— then reboot)...\n", host, commandDelay, 6*commandDelay)
+		logs, err = m.EnableSSHViaTelnetFullConfig(host, serviceURL, commandDelay)
+	} else {
+		fmt.Printf("Enabling SSH on %s via telnet :17000 (runs on the speaker's next boseurls check, up to ~60s)...\n", host)
+		logs, err = m.EnableSSHViaTelnet(host, serviceURL)
+	}
+
+	if logs != "" {
+		fmt.Print(logs)
+	}
+
+	if err != nil {
+		PrintError(err.Error())
+		return err
+	}
+
+	if !fullConfig {
+		return nil
+	}
+
+	if commandDelay > 0 {
+		time.Sleep(commandDelay)
+	}
+
+	fmt.Println("Rebooting the speaker to apply the new configuration...")
+
+	rlogs, rerr := m.Reboot(host, setup.RebootMethodTelnet)
+	if rlogs != "" {
+		fmt.Print(rlogs)
+	}
+
+	if rerr != nil {
+		PrintError(rerr.Error())
+		return rerr
+	}
+
+	return nil
+}
+
+// ensureMargeAccountPaired checks /info and pairs an unpaired device before
+// the SSH-enable injection runs — see setup.EnsureMargeAccountPaired for why.
+// Pairing failure is logged as a warning, not fatal: the claim that an
+// unpaired device never polls margeServerUrl is not yet confirmed on every
+// device this command targets, so the injection is still worth attempting
+// even if the pairing step itself couldn't be verified.
+func ensureMargeAccountPaired(m *setup.Manager, deviceIP, wantAccountID string) {
+	var t setup.TelnetClient
+
+	if m.NewTelnet != nil {
+		t = m.NewTelnet(deviceIP)
+
+		if dialErr := t.Dial(); dialErr != nil {
+			t = nil
+		} else {
+			defer func() { _ = t.Close() }()
+		}
+	}
+
+	accountID, alreadyPaired, logs, err := m.EnsureMargeAccountPaired(deviceIP, wantAccountID, t)
+	if logs != "" {
+		fmt.Print(logs)
+	}
+
+	switch {
+	case err != nil:
+		PrintWarning(fmt.Sprintf("Pairing check failed (%v) — continuing anyway; the SSH-enable injection may not "+
+			"fire on an unpaired device (#515).", err))
+	case alreadyPaired:
+		fmt.Printf("Device already paired (margeAccountUUID=%s).\n", accountID)
+	default:
+		fmt.Printf("Device was unpaired — paired it with generated account %s so margeServerUrl gets polled (#515).\n", accountID)
+	}
+}
+
+func setupEnableSSHCmd() *cli.Command {
+	return &cli.Command{
+		Name: "enable-ssh",
+		Usage: "Bootstrap SSH on a speaker with no prior access via the port-17000 envswitch trick (#471), " +
+			"then restore clean URLs and persist it",
+		Before: RequireHost,
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name: "service-url",
+				Usage: "AfterTouch service base URL to point the speaker at (e.g. https://192.0.2.10:8443). " +
+					"Optional: enabling SSH does not need a live server (the injection fires when the speaker " +
+					"parses its boseurls), so you can omit this now and set the real URLs later via migration",
+			},
+			&cli.DurationFlag{
+				Name:  "wait",
+				Value: 90 * time.Second,
+				Usage: "How long to wait for sshd (:22) after the envswitch injection (it runs on the speaker's next boseurls check, ~60s)",
+			},
+			&cli.BoolFlag{
+				Name: "full-config",
+				Usage: "For stubborn devices (ST Portable, CineMate 520) where the default single-envswitch injection is accepted but sshd never starts: " +
+					"replicate the #515 manual sequence — write all four sys configuration URL keys with the SSH-enable injection on margeServerUrl (not just envswitch), then reboot",
+			},
+			&cli.DurationFlag{
+				Name:  "command-delay",
+				Value: setup.DefaultTelnetCommandDelay,
+				Usage: "Only affects --full-config: pause between each of its 6 steps (5 commands + reboot). " +
+					"Raise this if the default doesn't work on your device; 0 sends everything back-to-back",
+			},
+			&cli.BoolFlag{
+				Name: "no-auto-pair",
+				Usage: "Skip the automatic pairing check: by default, enable-ssh reads /info first and pairs an unpaired " +
+					"(factory-reset) device with an account ID, since an unpaired device reportedly never " +
+					"polls margeServerUrl at all (#515) — the injection would have nothing to fire on otherwise",
+			},
+			&cli.StringFlag{
+				Name: "account",
+				Usage: "Only used when the device is unpaired and --no-auto-pair is not set: account ID to pair with " +
+					"(empty = generate a fresh 7-digit one). Use this if you already know which account this device " +
+					"should end up on (e.g. to match one already in the datastore) rather than getting a random one now",
+			},
+			&cli.BoolFlag{
+				Name:  "no-reset-urls",
+				Usage: "Skip restoring clean boseurls after SSH is up (leaves the injected marge URL in place)",
+			},
+			&cli.BoolFlag{
+				Name:  "no-persist",
+				Usage: "Skip persisting the remote_services marker (SSH would not survive a reboot)",
+			},
+			&cli.StringFlag{
+				Name:  "authorized-key",
+				Usage: "Opt-in hardening: install this SSH public key for root (key auth instead of the empty-password login). Pass the key text, e.g. --authorized-key \"$(cat id_ed25519.pub)\"",
+			},
+			&cli.BoolFlag{
+				Name:  "close-17000",
+				Usage: "Opt-in hardening: block port 17000 from the LAN (firewall rule applied now + persisted); loopback access is kept",
+			},
+		},
+		Action: func(c *cli.Context) error {
+			cfg := GetClientConfig(c)
+			m := setup.NewManager("", nil, nil)
+
+			// The URL is only the vehicle for the command injection; the
+			// SSH-enable fires when the speaker parses its boseurls, whether
+			// or not anything answers there. When the user has no service URL
+			// yet, use a clearly-placeholder value and tell them to set the
+			// real URLs during migration.
+			serviceURL := c.String("service-url")
+			placeholder := serviceURL == ""
+
+			if placeholder {
+				serviceURL = "https://aftertouch.invalid"
+			}
+
+			if !c.Bool("no-auto-pair") {
+				ensureMargeAccountPaired(m, cfg.Host, c.String("account"))
+			}
+
+			if err := runEnableSSHInjection(m, cfg.Host, serviceURL, c.Bool("full-config"), c.Duration("command-delay")); err != nil {
+				return err
+			}
+
+			fmt.Printf("Waiting up to %s for sshd (:22) to come up...\n", c.Duration("wait"))
+
+			if err := setup.WaitForSSHPort(cfg.Host, c.Duration("wait")); err != nil {
+				// Not a hard failure: on some devices (e.g. the Wireless Link
+				// Adapter, see #471) the envswitch injection is accepted but
+				// sshd only actually starts after the speaker restarts. We
+				// deliberately leave the injected boseurls in place (no reset)
+				// so a power-cycle re-triggers the unlock, and guide the user
+				// to reboot and retry rather than exiting with an error.
+				fmt.Println()
+				PrintWarning(fmt.Sprintf("sshd (:22) did not come up within %s, but the speaker accepted the SSH-enable command.", c.Duration("wait")))
+				fmt.Println("On some devices sshd only starts after a restart. Next steps:")
+				fmt.Println("  1. Power-cycle the speaker (unplug it, wait a few seconds, plug it back in).")
+				fmt.Println("  2. Once it is back online, run this same command again, or just connect with:")
+				fmt.Printf("       ssh -o HostKeyAlgorithms=+ssh-rsa,ssh-dss root@%s\n", cfg.Host)
+				fmt.Println("The temporary boseurls were left in place on purpose, so the restart re-triggers the unlock.")
+
+				if placeholder {
+					fmt.Println("(No --service-url was given; you'll set the real service URLs later during migration.)")
+				}
+
+				return nil
+			}
+
+			PrintSuccess("SSH is up on " + cfg.Host)
+
+			if !c.Bool("no-reset-urls") {
+				fmt.Println("Restoring clean boseurls (so the marge URL is usable again)...")
+
+				rlogs, rerr := m.ResetBoseURLs(cfg.Host, serviceURL)
+				if rlogs != "" {
+					fmt.Print(rlogs)
+				}
+
+				if rerr != nil {
+					PrintError(rerr.Error())
+					return rerr
+				}
+			}
+
+			if !c.Bool("no-persist") {
+				fmt.Println("Persisting the remote_services marker (SSH survives reboot)...")
+
+				plogs, perr := m.EnsureRemoteServices(cfg.Host)
+				if plogs != "" {
+					fmt.Print(plogs)
+				}
+
+				if perr != nil {
+					PrintError(perr.Error())
+					return perr
+				}
+			}
+
+			if key := c.String("authorized-key"); key != "" {
+				fmt.Println("Installing authorized_keys for root (key auth)...")
+
+				klogs, kerr := m.InstallAuthorizedKey(cfg.Host, key)
+				if klogs != "" {
+					fmt.Print(klogs)
+				}
+
+				if kerr != nil {
+					PrintError(kerr.Error())
+					return kerr
+				}
+			}
+
+			closed17000 := c.Bool("close-17000")
+			if closed17000 {
+				fmt.Println("Closing port 17000 to the LAN (loopback kept)...")
+
+				clogs, cerr := m.Close17000(cfg.Host)
+				if clogs != "" {
+					fmt.Print(clogs)
+				}
+
+				if cerr != nil {
+					PrintError(cerr.Error())
+					return cerr
+				}
+			}
+
+			PrintSuccess("Done — SSH enabled on " + cfg.Host + ". From here, the usual migration / CA-install / inspect commands work.")
+
+			if placeholder {
+				fmt.Println("No --service-url was given, so the speaker's boseurls now point at a placeholder; run your migration next to set the real service URLs.")
+			}
+
+			if closed17000 {
+				fmt.Println("Port 17000 is now blocked from the LAN (loopback kept).")
+			} else {
+				fmt.Println("Note: port 17000 is left open (opt-in --close-17000 to block it from the LAN).")
+			}
+
+			return nil
+		},
+	}
+}
+
 func setupRemoteServicesCmd() *cli.Command {
 	return &cli.Command{
 		Name:   "remote-services",
@@ -606,7 +889,7 @@ func setupInstallCACmd() *cli.Command {
 				return err
 			}

-			fmt.Printf("Fetched %d bytes of CA PEM from %s/setup/ca.crt\n", len(certPEM), serviceURL)
+			fmt.Printf("Fetched %d bytes of CA PEM from %s/api/setup/ca.crt\n", len(certPEM), serviceURL)

 			m := setup.NewManager(serviceURL, nil, nil)

@@ -627,11 +910,11 @@ func setupInstallCACmd() *cli.Command {
 	}
 }

-// fetchCACert pulls AfterTouch's CA bundle from /setup/ca.crt. On HTTP 401
+// fetchCACert pulls AfterTouch's CA bundle from /api/setup/ca.crt. On HTTP 401
 // it prompts interactively for basic-auth credentials (or accepts --auth)
 // and retries once.
 func fetchCACert(serviceURL, authFlag string) ([]byte, error) {
-	url := serviceURL + "/setup/ca.crt"
+	url := serviceURL + "/api/setup/ca.crt"

 	doRequest := func(user, pass string) (*http.Response, error) {
 		req, err := http.NewRequest(http.MethodGet, url, nil)
@@ -733,6 +1016,116 @@ func promptBasicAuth() (string, string, error) {
 	return user, string(pass), nil
 }

+// setupSyncCmd wraps POST /api/setup/sync/{deviceId} — the same operation
+// as the web UI's Devices → Sync Data button. It only reads from the
+// speaker (presets, recents, sources) into AfterTouch's datastore; it never
+// writes anything back to the speaker. Useful for scripting or reproducing
+// what Sync does in isolation (see issue #614: Sync's own code cannot wipe
+// the speaker's preset table, since it never sends anything back).
+func setupSyncCmd() *cli.Command {
+	return &cli.Command{
+		Name:   "sync",
+		Usage:  "Pull presets/recents/sources from the speaker into AfterTouch's datastore (same as the web UI's \"Sync Data\" button)",
+		Before: RequireHost,
+		Flags: []cli.Flag{
+			&cli.StringFlag{Name: "service-url", Required: true, Usage: "AfterTouch base URL"},
+			&cli.StringFlag{Name: "auth", Usage: "Basic-auth credentials for AfterTouch as user:pass (omit to be prompted on 401)"},
+		},
+		Action: func(c *cli.Context) error {
+			cfg := GetClientConfig(c)
+			serviceURL := strings.TrimRight(c.String("service-url"), "/")
+
+			if err := validateServiceURL(serviceURL); err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
+			client, err := CreateSoundTouchClient(cfg)
+			if err != nil {
+				PrintError(fmt.Sprintf("Failed to create client: %v", err))
+				return err
+			}
+
+			deviceInfo, err := client.GetDeviceInfo()
+			if err != nil {
+				PrintError(fmt.Sprintf("Failed to get device info from speaker: %v", err))
+				return err
+			}
+
+			if deviceInfo.DeviceID == "" {
+				err := fmt.Errorf("speaker at %s did not report a DeviceID", cfg.Host)
+				PrintError(err.Error())
+
+				return err
+			}
+
+			PrintDeviceHeader(fmt.Sprintf("Syncing %s into AfterTouch", deviceInfo.DeviceID), cfg.Host, cfg.Port)
+
+			if err := postSetupSync(serviceURL, deviceInfo.DeviceID, c.String("auth")); err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
+			PrintSuccess(fmt.Sprintf("Synced presets, recents, and sources for %s.", deviceInfo.DeviceID))
+
+			return nil
+		},
+	}
+}
+
+// postSetupSync POSTs to AfterTouch's /api/setup/sync/{deviceId}, prompting
+// for basic-auth credentials on 401 (matches fetchCACert's pattern).
+func postSetupSync(serviceURL, deviceID, authFlag string) error {
+	endpoint := fmt.Sprintf("%s/api/setup/sync/%s", serviceURL, deviceID)
+
+	doRequest := func(user, pass string) (*http.Response, error) {
+		req, err := http.NewRequest(http.MethodPost, endpoint, nil)
+		if err != nil {
+			return nil, err
+		}
+
+		if user != "" {
+			req.SetBasicAuth(user, pass)
+		}
+
+		client := &http.Client{Timeout: 30 * time.Second}
+
+		return client.Do(req)
+	}
+
+	user, pass := splitAuth(authFlag)
+
+	resp, err := doRequest(user, pass)
+	if err != nil {
+		return fmt.Errorf("POST %s: %w", endpoint, err)
+	}
+
+	if resp.StatusCode == http.StatusUnauthorized {
+		_ = resp.Body.Close()
+
+		fmt.Printf("%s requires basic auth.\n", endpoint)
+
+		user, pass, err = promptBasicAuth()
+		if err != nil {
+			return err
+		}
+
+		resp, err = doRequest(user, pass)
+		if err != nil {
+			return fmt.Errorf("POST %s (with auth): %w", endpoint, err)
+		}
+	}
+
+	defer func() { _ = resp.Body.Close() }()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("POST %s returned %d: %s", endpoint, resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	return nil
+}
+
 func setupMigrateCmd() *cli.Command {
 	return &cli.Command{
 		Name:   "migrate",
@@ -743,6 +1136,10 @@ func setupMigrateCmd() *cli.Command {
 			&cli.StringFlag{Name: "method", Value: string(setup.MigrationMethodTelnet), Usage: "telnet | hosts | resolv | xml"},
 			&cli.StringFlag{Name: "proxy-url", Usage: "Optional upstream proxy URL (for --method=xml)"},
 			&cli.BoolFlag{Name: "skip-preflight", Usage: "Skip the AfterTouch settings preflight (use when AfterTouch's settings endpoint is unreachable)"},
+			&cli.StringFlag{Name: "marge-url", Usage: "Override margeServerUrl instead of deriving it from --service-url (e.g. to restore the original Bose cloud URL). Applies to --method=telnet and --method=xml"},
+			&cli.StringFlag{Name: "stats-url", Usage: "Override statsServerUrl (telnet/xml)"},
+			&cli.StringFlag{Name: "sw-update-url", Usage: "Override swUpdateUrl (telnet/xml)"},
+			&cli.StringFlag{Name: "bmx-url", Usage: "Override bmxRegistryUrl (telnet/xml)"},
 		},
 		Action: func(c *cli.Context) error {
 			cfg := GetClientConfig(c)
@@ -754,6 +1151,13 @@ func setupMigrateCmd() *cli.Command {
 				return err
 			}

+			options := map[string]string{
+				"marge_url":     c.String("marge-url"),
+				"stats_url":     c.String("stats-url"),
+				"sw_update_url": c.String("sw-update-url"),
+				"bmx_url":       c.String("bmx-url"),
+			}
+
 			m := setup.NewManager(serviceURL, nil, nil)

 			// For DNS-redirect methods check that AfterTouch's DNS listener
@@ -777,7 +1181,7 @@ func setupMigrateCmd() *cli.Command {

 			fmt.Printf("Migrating %s → %s using method=%s\n", cfg.Host, serviceURL, method)

-			logs, err := m.MigrateSpeaker(cfg.Host, serviceURL, c.String("proxy-url"), nil, method)
+			logs, err := m.MigrateSpeaker(cfg.Host, serviceURL, c.String("proxy-url"), options, method)
 			if logs != "" {
 				fmt.Print(logs)
 			}
@@ -1106,6 +1510,45 @@ func renderMigrationSummary(deviceIP, serviceURL string, s *setup.MigrationSumma
 	}
 }

+// setupRevertCmd wraps setup.Manager.RevertMigration — the same operation
+// as the web UI's "Revert to Defaults" button (Migrate tab). Restores
+// SoundTouchSdkPrivateCfg.xml, /etc/hosts, and /etc/resolv.conf from their
+// .original backups, removes the AfterTouch DNS-hook artifacts, and strips
+// just the AfterTouch-labeled cert out of the trust bundle. No --service-url
+// needed: everything it touches already lives on the speaker.
+//
+// Deliberately out of scope (matches the web UI button): SSH/remote_services
+// persistence (use `setup remote-services --remove`) and account pairing
+// (use `account unpair`) — see #614 self-test notes for the full checklist.
+func setupRevertCmd() *cli.Command {
+	return &cli.Command{
+		Name:   "revert",
+		Usage:  "Undo a migration: restore SoundTouchSdkPrivateCfg.xml/hosts/resolv.conf from backups and remove the AfterTouch CA cert",
+		Before: RequireHost,
+		Action: func(c *cli.Context) error {
+			cfg := GetClientConfig(c)
+			m := setup.NewManager("", nil, nil)
+
+			fmt.Printf("Reverting migration on %s...\n", cfg.Host)
+
+			logs, err := m.RevertMigration(cfg.Host)
+			if logs != "" {
+				fmt.Print(logs)
+			}
+
+			if err != nil {
+				PrintError(err.Error())
+				return err
+			}
+
+			PrintSuccess("Migration reverted. SSH access and account pairing are untouched by this — " +
+				"see `setup remote-services --remove` and `account unpair` if you want those cleared too.")
+
+			return nil
+		},
+	}
+}
+
 func setupRebootCmd() *cli.Command {
 	return &cli.Command{
 		Name:   "reboot",
@@ -1532,7 +1975,7 @@ func setupPairCmd() *cli.Command {
 		Usage:  "Pair the speaker with an account via WebSocket SETUP state machine",
 		Before: RequireHost,
 		Flags: []cli.Flag{
-			&cli.StringFlag{Name: "account", Usage: "7-digit account ID (empty = generate)"},
+			&cli.StringFlag{Name: "account", Usage: "Account ID to pair with (empty = generate a fresh 7-digit one)"},
 			&cli.StringFlag{Name: "mode", Value: "full", Usage: "full (state machine) or bare (setMargeAccount only — experimental)"},
 			&cli.StringFlag{Name: "service-url", Value: "http://aftertouch.local:8000", Usage: "AfterTouch base URL (also populates <boseServer>/<updateServer> in setMargeAccount)"},
 			&cli.StringFlag{Name: "name", Usage: "Speaker name to set during pairing (empty = keep current)"},
@@ -1556,8 +1999,8 @@ func setupPairCmd() *cli.Command {
 				fmt.Printf("Generated account id: %s\n", accountID)
 			}

-			if !setup.IsValidAccountID(accountID) {
-				return fmt.Errorf("invalid account id %q: must be 7 digits", accountID)
+			if !datastore.IsSafeIdentifier(accountID) {
+				return fmt.Errorf("invalid account id %q: must be a non-empty, path-safe identifier", accountID)
 			}

 			switch mode {
@@ -1639,6 +2082,17 @@ func runPairBare(c *cli.Context, deviceIP, accountID string) error {
 func runPairFull(c *cli.Context, deviceIP, accountID string) error {
 	m := setup.NewManager(c.String("service-url"), nil, nil)

+	needed, status, err := m.PreflightInitPlan(deviceIP)
+	if err != nil {
+		PrintError(fmt.Sprintf("preflight: %v", err))
+		return err
+	}
+
+	if !needed {
+		PrintSuccess(fmt.Sprintf("Device already configured (status=%s) — nothing to do.", status))
+		return nil
+	}
+
 	plan := setup.InitPlan{
 		DeviceIP:       deviceIP,
 		ServiceURL:     c.String("service-url"),
@@ -1652,7 +2106,7 @@ func runPairFull(c *cli.Context, deviceIP, accountID string) error {
 	ctx, cancel := context.WithTimeout(c.Context, 60*time.Second)
 	defer cancel()

-	_, err := m.ExecuteInitPlan(ctx, plan, func(e setup.StepEvent) {
+	_, err = m.ExecuteInitPlan(ctx, plan, func(e setup.StepEvent) {
 		switch e.Status {
 		case setup.StatusOK:
 			fmt.Printf("[%d] %s — ok\n", e.Kind, e.Name)
@@ -3,6 +3,8 @@ package main
 import (
 	"bytes"
 	"io"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"strings"
 	"testing"
@@ -43,6 +45,46 @@ func captureStdout(t *testing.T, fn func()) string {
 	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)"
@@ -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
+}
@@ -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")
@@ -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"))
+}
@@ -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
+}
@@ -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)
+}
@@ -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)
+		})
+	}
+}
@@ -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)
@@ -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
+}
@@ -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
 		}

@@ -385,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,
 					},
@@ -584,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{
@@ -609,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{
@@ -623,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{
@@ -642,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{
@@ -1146,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
@@ -1848,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",
@@ -1867,6 +1959,7 @@ func main() {
 						Action: playNotificationBeep,
 						Before: RequireHost,
 					},
+					ttsCloudCmd(),
 					{
 						Name:   "help",
 						Usage:  "Show detailed help about speaker functionality",
@@ -2238,6 +2331,17 @@ func main() {
 	// Defined in cmd_setup.go to keep the top-level command list readable.
 	app.Commands = append(app.Commands, setupCommand())

+	// AfterTouch service management (sources, accounts, devices).
+	// Defined in cmd_cloud.go.
+	app.Commands = append(app.Commands, cloudCommand())
+
+	// 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)

@@ -0,0 +1,4 @@
+soundtouch-player
+soundtouch-player-test
+soundtouch-web
+soundtouch-web-test
@@ -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
@@ -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.0.2.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
@@ -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
+}
@@ -1,4 +1,12 @@
-// Package main provides a web UI for controlling Bose SoundTouch devices.
+// 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 (
@@ -8,7 +16,9 @@ import (
 	"net"
 	"net/http"
 	"os"
+	"path/filepath"
 	"runtime/debug"
+	"strings"
 	"time"

 	"github.com/gesellix/bose-soundtouch/pkg/service/soundtouchweb"
@@ -29,7 +39,11 @@ func updateBuildInfo() {
 			repoURL = "https://" + info.Main.Path
 		}

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

@@ -46,12 +60,28 @@ func updateBuildInfo() {
 	}
 }

+// 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-web",
-		Usage: "Web UI for controlling Bose SoundTouch devices",
+		Name:  "soundtouch-player",
+		Usage: "LAN web player for controlling Bose SoundTouch devices",
 		Flags: []cli.Flag{
 			&cli.StringFlag{
 				Name:    "port",
@@ -75,6 +105,16 @@ func main() {
 				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")
@@ -86,7 +126,7 @@ func main() {
 			}

 			if rawBind != "" && bindAddr != rawBind {
-				log.Printf("Resolved --bind %q to %s", rawBind, bindAddr)
+				log.Printf("Resolved --bind %q to %s", sanitizeLog(rawBind), sanitizeLog(bindAddr))
 			}

 			rawIface := c.String("interface")
@@ -94,7 +134,7 @@ func main() {

 			ifaceName := defaultDiscoveryInterface(rawIface, rawBind, bindAddr)
 			if rawIface == "" && ifaceName != "" {
-				log.Printf("Defaulting --interface to %q from --bind", ifaceName)
+				log.Printf("Defaulting --interface to %q from --bind", sanitizeLog(ifaceName))
 			}

 			addr := ":" + port
@@ -108,8 +148,20 @@ func main() {
 			webApp.Commit = commit
 			webApp.Date = date
 			webApp.RepoURL = repoURL
+			webApp.ServiceURL = strings.TrimRight(c.String("service-url"), "/")

-			discoveryService := soundtouchweb.NewDiscoveryService(ifaceName)
+			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() {
@@ -118,6 +170,11 @@ func main() {

 				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")
 				}
@@ -131,7 +188,7 @@ func main() {
 			r := chi.NewRouter()
 			webApp.Mount(r, discoveryService)

-			log.Printf("AfterTouch Web UI starting on http://%s", addr)
+			log.Printf("AfterTouch Web UI starting on http://%s", sanitizeLog(addr))

 			return http.ListenAndServe(addr, r)
 		},
@@ -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
+}
@@ -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)
+	}
+}
@@ -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)
+	}
+}
@@ -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
+}
@@ -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
+}
@@ -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 {
@@ -151,3 +286,119 @@ func TestMergeTLSExtraHosts(t *testing.T) {
 		})
 	}
 }
+
+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)
+	}
+}
@@ -13,13 +13,16 @@ import (

 	"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, nil)
+	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 {
@@ -36,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 {
@@ -128,7 +128,7 @@ func TestPUTRenameRoutesToLocalHandler(t *testing.T) {
 	_ = ds.Initialize()

 	server := handlers.NewServer(ds, nil, "http://localhost:8000", false, false, false)
-	r := setupRouter(server, nil)
+	r := setupRouter(server, nil, nil)
 	ts := httptest.NewServer(r)
 	defer ts.Close()

@@ -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/*
@@ -1,7 +1,16 @@
 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).HandleMargeRemoveDevice-fm
-DELETE   /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeDeleteGroup-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   /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
@@ -9,29 +18,93 @@ DELETE   /setup/devices/{deviceId}                                    handlers.(
 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/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
@@ -42,6 +115,7 @@ GET      /favicon.ico                                                 setupRoute
 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
@@ -71,6 +145,7 @@ GET      /setup/logging-settings                                      handlers.(
 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
@@ -92,21 +167,68 @@ 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
+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).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/                                   handlers.(*Server).HandleMargeAddGroup-fm
-POST     /accounts/{account}/group/{groupId}                          handlers.(*Server).HandleMargeModifyGroup-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     /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
@@ -132,6 +254,7 @@ 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
@@ -146,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
@@ -169,5 +293,7 @@ PUT      /core02/svc-bmx-adapter-siriusxm-everest-eco1/prod/live-adapter handler
 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
+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
@@ -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)
+	}
+}
@@ -1,2 +0,0 @@
-soundtouch-web
-soundtouch-web-test
@@ -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
+}
@@ -573,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
@@ -5,5 +5,7 @@ default/
 dns/
 interactions/
 parity_mismatches/
+stats/
 patterns.json
 settings.json
+update-check.json
@@ -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:
@@ -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:
@@ -1,111 +0,0 @@
-# Table of Contents
-
-* [Introduction](README.md)
-
-## User Guides
-* [Device-Local Install Journeys](DEVICE-LOCAL-INSTALL.md)
-* [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)
-* [Encrypted Export](concepts/ENCRYPTED-EXPORT.md)
-* [Diagnostic Export (Maintainer Setup)](DIAGNOSTIC-EXPORT.md)
-* [soundtouch-web Roadmap](soundtouch-web-roadmap.md)
-
-## Analysis & Research
-* [API Coverage Analysis](analysis/API-COVERAGE.md)
-* [Supported URLs](analysis/SUPPORTED-URLS.md)
-* [Upstream URLs](analysis/UPSTREAM-URLS.md)
-* [Anonymization Summary](analysis/ANONYMIZATION-SUMMARY.md)
-* [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md)
-* [Telnet (Port 17000) Migration Method](analysis/TELNET-MIGRATION-METHOD.md)
-* [Telnet Command Reference](analysis/TELNET-COMMAND-REFERENCE.md)
-* [Setup WebSocket Experiment](analysis/SETUP-WEBSOCKET-EXPERIMENT.md)
-* [Factory Reset Protocol](analysis/FACTORY-RESET-PROTOCOL.md)
-* [Wiki API Comparison](analysis/WIKI-COMPARISON.md)
-* [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md)
-* [IoT Configuration Analysis](analysis/IOT-CONFIGURATION-ANALYSIS.md)
-* [Bose Lab Runbook](analysis/BOSE-LAB-RUNBOOK.md)
-* [Missing Routes Spotify](analysis/MISSING-ROUTES-SPOTIFY.md)
-* [Bose App ADB Emulator](analysis/BOSE-APP-ADB-Emulator.md)
-* [Community Tools](analysis/bose-soundtouch-community-tools.md)
-
-## Parity Analysis
-* [Parity Improvements](PARITY-IMPROVEMENTS.md)
-* [Parity SoundCork](PARITY-SOUNDCORK.md)
-* [Parity OpenCloudTouch](PARITY-OPENCLOUDTOUCH.md)
-
-## Appendix (Other Documents)
-* [External Services Abstraction](EXTERNAL-SERVICES-ABSTRACTION.md)
-* [API Navigation Reference](API-NAVIGATION-REFERENCE.md)
-* [Claude Instructions](CLAUDE.md)
-* [Content Selection Implementation](CONTENT-SELECTION-IMPLEMENTATION.md)
-* [Device Customization Setup](DEVICE-CUSTOMIZATION-SETUP.md)
-* [Device Logging](DEVICE-LOGGING.md)
-* [Feature History](FEATURE_HISTORY.md)
-* [Host/Port Parsing](HOST-PORT-PARSING.md)
-* [Manual Network Discovery](MANUAL-NETWORK-DISCOVERY.md)
-* [Navigation Guide](NAVIGATION-GUIDE.md)
-* [Official API Verification](OFFICIAL-API-VERIFICATION.md)
-* [Preset Quickstart](PRESET-QUICKSTART.md)
-* [Project Patterns](PROJECT-PATTERNS.md)
-* [Service Availability Implementation](SERVICE-AVAILABILITY-IMPLEMENTATION.md)
-* [SoundTouch Service Announcement](SOUNDTOUCH-SERVICE-ANNOUNCEMENT.md)
-* [Undocumented Community Features](UNDOCUMENTED-COMMUNITY-FEATURES.md)
-* [Unimplemented Endpoints](UNIMPLEMENTED-ENDPOINTS.md)
-* [Preset Store](preset-store.md)
-* [SCMUDC Enrichment Implementation](SCMUDC-ENRICHMENT-IMPLEMENTATION.md)
-* [Device Lifecycle and Power On Enhancement](device-lifecycle-and-power-on-enhancement.md)
-* [Device Lifecycle Summary](device-lifecycle-summary.md)
-* [Power On Implementation Guide](power-on-implementation-guide.md)
-* [SCMUDC Events Analysis](scmudc-events-analysis.md)
-* [Parity Improvements](PARITY-IMPROVEMENTS.md)
-* [Parity SoundCork](PARITY-SOUNDCORK.md)
-* [Stockholm Port Guide](stockholm-port-guide.md)
@@ -1,11 +0,0 @@
-title: Bose SoundTouch Toolkit
-description: Documentation for controlling and preserving Bose SoundTouch devices
-remote_theme: pages-themes/minimal@v0.2.0
-plugins:
-  - jekyll-remote-theme
-  - jekyll-relative-links
-relative_links:
-  enabled: true
-  collections: true
-include:
-  - SUMMARY.md
@@ -665,7 +665,7 @@ soundtouch --device 192.0.2.100 preset 1
 soundtouch interactive

 # Web interface
-soundtouch-webapp --port 8080
+soundtouch-playerapp --port 8080
 ```

 ### JavaScript/WASM Usage
@@ -727,10 +727,10 @@ client.startEventStream((event) => {
 ./soundtouch-linux-amd64 --device IP play

 # Web Application (embedded assets)
-./soundtouch-webapp-linux-amd64 --port 8080
+./soundtouch-playerapp-linux-amd64 --port 8080

 # Docker
-docker run -p 8080:8080 soundtouch-webapp
+docker run -p 8080:8080 soundtouch-playerapp
 ```

 ### Development Environment
@@ -784,4 +784,4 @@ docker compose up  # Mock devices + web app
 - [UPnP Device Architecture](http://upnp.org/specs/arch/UPnP-arch-DeviceArchitecture-v1.0.pdf)
 - [Go Embed Directive](https://pkg.go.dev/embed)
 - [Gorilla WebSocket](https://github.com/gorilla/websocket)
- [PROJECT-PATTERNS.md](../PROJECT-PATTERNS.md) - Detailed pattern documentation
+- [PROJECT-PATTERNS.md](../content/docs/appendix/PROJECT-PATTERNS.md) - Detailed pattern documentation
@@ -0,0 +1,46 @@
+/* Font paths use ../../fonts/ (two levels up) so the URL resolves correctly
+   regardless of where the CSS is served from:
+   - dev:        /css/custom.css          → ../../fonts/ → /fonts/
+   - production: /css/compiled/main.css   → ../../fonts/ → /fonts/
+   - GH Pages:   /Bose-SoundTouch/css/compiled/main.css
+                                          → ../../fonts/ → /Bose-SoundTouch/fonts/ */
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-regular.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: italic;
+  font-weight: 400;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-italic.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: normal;
+  font-weight: 700;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-700.woff2') format('woff2');
+}
+
+@font-face {
+  font-family: 'Noto Sans';
+  font-style: italic;
+  font-weight: 700;
+  font-display: swap;
+  src: url('../../fonts/noto-sans-v42-latin-700italic.woff2') format('woff2');
+}
+
+:root {
+  --hx-default-font-family: "Noto Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+.content {
+  font-family: var(--hx-default-font-family);
+}
@@ -0,0 +1,65 @@
+---
+title: AfterTouch
+layout: hextra-home
+---
+
+{{< hextra/hero-badge >}}
+  <div class="hx-w-2 hx-h-2 hx-rounded-full hx-bg-primary-400"></div>
+  <span>Free, open source</span>
+  {{< icon name="arrow-circle-right" attributes="height=14" >}}
+{{< /hextra/hero-badge >}}
+
+<div class="hx-mt-6 hx-mb-6">
+{{< hextra/hero-headline >}}
+  Keep Your Bose SoundTouch&nbsp;Speakers Alive
+{{< /hextra/hero-headline >}}
+</div>
+
+<div class="hx-mb-12">
+{{< hextra/hero-subtitle >}}
+  Bose shut down SoundTouch cloud services on May 6, 2026.&nbsp;<br class="sm:hx-block hx-hidden" />AfterTouch replaces the cloud — presets, music browsing, stereo pairing, all restored.
+{{< /hextra/hero-subtitle >}}
+</div>
+
+<div class="hx-mb-6">
+{{< hextra/hero-button text="Get Started" link="docs/guides/MIGRATION-GUIDE" >}}
+{{< hextra/hero-button text="Survival Guide" link="docs/guides/SURVIVAL-GUIDE" style="outline" >}}
+</div>
+
+<div class="hx-mt-6">
+{{< hextra/feature-grid >}}
+  {{< hextra/feature-card
+    title="Presets Restored"
+    subtitle="Preset buttons, long-press assignment, and recently-played sync — fully working."
+    icon="star"
+  >}}
+  {{< hextra/feature-card
+    title="Music Browsing"
+    subtitle="TuneIn, Internet Radio, RadioBrowser, and Spotify via soundtouch-player and soundtouch-cli."
+    icon="speakerphone"
+  >}}
+  {{< hextra/feature-card
+    title="Stereo Pairing"
+    subtitle="SoundTouch 10 stereo pairing via soundtouch-cli, no Bose cloud required."
+    icon="adjustments"
+  >}}
+  {{< hextra/feature-card
+    title="Three Deployment Options"
+    subtitle="Run on a Raspberry Pi, a VPS, or directly on the speaker itself."
+    icon="server"
+    link="docs/guides/DEPLOYMENT-OVERVIEW"
+  >}}
+  {{< hextra/feature-card
+    title="CLI Control"
+    subtitle="soundtouch-cli for scripting, home automation, and direct device control."
+    icon="terminal"
+    link="docs/guides/CLI-REFERENCE"
+  >}}
+  {{< hextra/feature-card
+    title="Open Source"
+    subtitle="MIT licensed. Not affiliated with Bose Corporation."
+    icon="shield-check"
+    link="https://github.com/gesellix/Bose-SoundTouch"
+  >}}
+{{< /hextra/feature-grid >}}
+</div>
@@ -0,0 +1,120 @@
+---
+title: "Welcome to AfterTouch: Your SoundTouch Speakers, Still Alive"
+date: 2026-05-24
+description: "Bose shut down SoundTouch cloud services in May 2026. AfterTouch replaces everything your speakers relied on — migration, radio, Spotify, presets, and more."
+tags:
+  - migration
+  - web
+  - spotify
+  - cli
+sidebar:
+  exclude: true
+---
+
+On May 6, 2026, Bose shut down the SoundTouch cloud services that millions of speakers
+depended on for account sync, presets, internet radio, and streaming. Speakers kept
+working locally, but remote features stopped and first-time setup became impossible.
+
+AfterTouch was built to change that. It is a self-hosted replacement for the Bose
+cloud infrastructure — a drop-in local service that your speakers talk to instead of
+`streaming.bose.com`. This post covers what works today and how to get started.
+
+## What works right now
+
+### Migration and first-time setup
+
+If your speaker was registered with Bose before the shutdown, AfterTouch can **migrate
+your existing account and presets** in a single step — no reconfiguration on the
+speaker side. If you are setting up a factory-reset or brand-new speaker, AfterTouch
+handles that path too, guiding you through Wi-Fi pairing and account creation locally.
+See the [Migration Guide](../docs/guides/MIGRATION-GUIDE.md) for step-by-step instructions.
+
+### Internet radio — TuneIn and RadioBrowser
+
+Both **TuneIn** and **RadioBrowser** are fully supported for browsing and playback.
+Navigate categories and search for stations exactly as you did with the original Bose
+app. TuneIn delivers the same station catalogue; RadioBrowser provides an open,
+community-maintained alternative.
+
+### Spotify
+
+**Spotify** works via both OAuth (account linking) and Spotify Connect (the ZeroConf
+"connect to device" flow from the Spotify app). Once linked, playback and device
+selection behave the same as before.
+
+### Presets
+
+Your six preset buttons work. AfterTouch stores preset bindings locally and serves them
+back to the speaker on request. You can also **save new presets** — via the API,
+via `soundtouch-cli`, or through the soundtouch-player UI.
+
+### ST-10 stereo pairing
+
+**SoundTouch 10 stereo pairs** (and other ST pairing configurations) are supported
+end-to-end: creation, management, and playback routing all go through AfterTouch.
+
+### soundtouch-player — browser UI
+
+**soundtouch-player** is an early-stage but functional browser UI bundled with AfterTouch.
+It gives you:
+
+- TuneIn and RadioBrowser browsing and playback
+- Speaker management and device discovery
+- Recent tracks panel
+- Multi-room zone management
+
+It runs as part of the AfterTouch service — no separate install needed.
+
+![soundtouch-player UI showing Spotify playback, presets, sources, and zone management](/images/blog/soundtouch-player-ui.png)
+
+### Automation with soundtouch-cli
+
+The **`soundtouch-cli`** command-line tool covers every speaker control: play, pause,
+volume, source selection, preset recall, group management, migration, and more.
+It is well-suited for home-automation scripts, cron jobs, and shell one-liners.
+
+## Three ways to install
+
+AfterTouch runs on any machine your speakers can reach:
+
+1. **On the speaker itself** — install directly on supported SoundTouch hardware via
+   the on-device installer. The speaker hosts its own replacement cloud, with no
+   additional hardware required.
+
+2. **On a local network host** — run AfterTouch on any machine on your LAN. A
+   **Raspberry Pi Zero 2W** handles the load without breaking a sweat, making this
+   path remarkably low-cost and low-power.
+
+3. **On a cloud or VPS host** — deploy to a remote server for access outside your
+   home network. AfterTouch handles TLS certificate generation and DNS configuration
+   for this scenario.
+
+All three paths are documented in the [Deployment Overview](../docs/guides/DEPLOYMENT-OVERVIEW.md).
+
+## Current release
+
+**v0.93.1** — released May 24, 2026
+
+## Community
+
+AfterTouch would not be where it is without the people who opened issues, tested
+pre-release builds, reported edge cases, and contributed code. A significant share of
+the fixes and features shipped in the lead-up to the cloud shutdown were driven by
+real-world feedback from the community — from migration quirks to stereo-pair
+specifics to Spotify Connect timing issues. Thank you to everyone who helped.
+
+If you run into something or have an idea, the
+[GitHub issue tracker](https://github.com/gesellix/Bose-SoundTouch/issues) and
+[Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) are the
+right places to start.
+
+## What's next
+
+The soundtouch-player UI will gain richer preset management — browsing, editing, and
+reordering presets directly from the browser. Longer term, merging
+`soundtouch-service` and `soundtouch-player` into a single binary is on the table,
+which would simplify deployment to a single process with no extra flags.
+
+This blog will be updated monthly — or whenever something significant ships.
+Subscribe to the [GitHub releases](https://github.com/gesellix/Bose-SoundTouch/releases)
+for individual version notes.
@@ -0,0 +1,131 @@
+---
+title: "AfterTouch: From Rescue to Something Better, and the Road to 1.0"
+date: 2026-06-28
+description: "Since v0.93.1, AfterTouch grew from a cloud-shutdown rescue into a platform of its own: local music, voice prompts, sturdier internals, a growing community, and a 1.0 on the horizon."
+tags:
+  - discovery
+  - health
+  - migration
+  - fixes
+sidebar:
+  exclude: true
+---
+
+The launch post went out under the wire. Bose pulled the plug on the SoundTouch cloud on
+May 6, and **v0.93.1** was very much a rescue: get accounts migrated, keep radio and
+presets alive, stop perfectly good speakers from turning into bricks. The weeks since,
+up through **v0.117.0**, have been about a quieter shift: turning that rescue into
+something that stands on its own, and in a few places, something better than what Bose
+offered. And almost none of that direction came from me. I use my own speakers with a
+pretty narrow set of features; nearly everything below exists because someone in the
+community described a use case I'd never have thought to build.
+
+## Local music, back under your control, and a speaker that talks
+
+The clearest sign of that shift is local music. Your speakers always had a native
+local-music source for playing your own library off the network, but browsing it used to
+run through the Bose app. AfterTouch brings that back on its own terms: it discovers
+DLNA / UPnP media servers on your network and drives the speaker's native source
+directly. Browse folders in the **Library** tab or from the command line, queue a whole
+folder, and next/previous and auto-advance behave like a real playlist.
+
+Then there's something genuinely new: speakers can now *talk*. A text-to-speech feature
+announces arbitrary text out loud, with Google Cloud TTS as a pluggable provider you
+configure from the settings UI. It's built on the speaker's notification capability, but
+turning that into spoken prompts is the kind of thing that happens when the platform is
+open and nobody has to wait for a vendor to approve it.
+
+There is more in the same spirit, smaller but useful: service-side search across TuneIn
+and Radio Browser, a "Play URL" view for arbitrary streams, save-as-preset straight from
+Now Playing, and a step toward needing no extra hardware at all, an on-device SSH unlock
+flow that opens the door to running AfterTouch directly on the speaker.
+
+## The unglamorous half: earning trust
+
+Features are the easy part to write about. The work that actually mattered most was
+making AfterTouch dependable enough that you stop thinking about it. Speaker data is now
+written to disk durably, so a power cut mid-write no longer wipes your presets and
+accounts, and corrupt or empty files fall back to sane defaults instead of failing.
+Recent tracks stopped vanishing and duplicating. Internet radio got steadier: Radio
+Browser plays through its proper native source, TuneIn fails over across stream
+candidates, and a stray trailing slash in a server URL no longer breaks playback.
+Multi-room grouping handles member removal correctly.
+
+Under the surface, a sustained pass closed several request-forgery paths, swept the code
+for log-injection, validated identifiers on management endpoints, and removed a
+credential-logging shortcut. And the health checks grew teeth: server-URL reachability,
+CA-bundle integrity, a speaker-clock check with a one-click fix, and a DNS-path probe for
+the internet-radio escape problem, all now labelled with the device name and IP so you
+know exactly which speaker a warning is about.
+
+## A community, not a product
+
+The best thing to happen since launch isn't in the changelog. It's the people.
+
+It's worth saying plainly: this project is driven by its users. I personally use
+SoundTouch in a fairly simple way, and most of what shipped over these weeks (features
+and bug fixes alike) is the result of friendly, constructive feedback from people who use
+their speakers very differently than I do. The DLNA library, the voice prompts, the radio
+and grouping fixes, the migration edge cases: each one started as someone taking the time
+to explain a real-world setup and point at what was missing. That feedback is the
+roadmap. Keep it coming.
+
+A standout is **[Sander ten Brinke](https://x.com/sandertenbrinke)**, who is building
+**[soundtouch-maui](https://github.com/sander1095/soundtouch-maui)**, a cross-platform
+SoundTouch app designed to work hand in hand with AfterTouch. That's exactly the shape
+this project should take: not one tool trying to do everything, but independent pieces
+that fit together because they share an open, community-owned foundation. Go build a
+player, a remote, a home-automation bridge, whatever you need, and have it talk to a
+service you control.
+
+An honest admission: there has been more activity in issues and discussions than one
+maintainer can keep up with, and not every thread got the reply it deserved. But the
+encouraging part is that it increasingly doesn't have to. People are answering each
+other, sharing setups (the FRITZ!Box and AdGuard DNS notes came straight from a user's
+own working configuration), and debugging together. That's the project moving in the
+right direction. AfterTouch works best as a community, not a support desk.
+
+And a heartfelt thank you to everyone who sponsors AfterTouch. The project is free and
+maintained in spare time, so every contribution, recurring or one-off, directly funds the
+hosting, the test hardware, and the hours that keep these speakers alive. It genuinely
+makes a difference, and it's deeply appreciated. If you'd like to chip in, the
+[sponsor page](../sponsor.md) has the details.
+
+## The road to 1.0
+
+So what does **v1.0.0** mean? Mostly: stability. A version number that signals a proper,
+dependable base you can build on, with a management API that won't shift under you and a
+service that runs unprivileged and installs cleanly by default.
+
+A few things are on the list to get there. The admin and account-management UI works,
+but it feels rough at the edges, and that's the part you actually touch, so it deserves
+some polish. I also want to keep a publicly deployed, cloud-hosted service in mind:
+the moment AfterTouch is reachable from the open internet, it needs proper authentication
+and authorization, so a passing script kiddie can't read your recently played songs (or
+worse). And the docs need some love and a clearer structure. One feature is likely to land
+in this stretch too: making
+[presets propagate cleanly across the speakers in one account](https://github.com/gesellix/Bose-SoundTouch/issues/495),
+without the manual "refresh sources" dance. There's probably more before it's truly
+"1.0", but none of it is blocking: there's nothing preventing us from getting there *now*.
+
+It's also a natural moment for a clean slate. If your migration has accumulated quirks,
+1.0 is a good excuse to reset and re-migrate your speakers onto a known-good footing.
+
+And then the interesting part begins. With the rescue done and a stable base in place, the
+focus shifts to delivering value the old Bose cloud never could. Some of that is already
+taking shape in the issue tracker: an
+[audiobook mode](https://github.com/gesellix/Bose-SoundTouch/issues/508), and deeper
+integration with external music providers such as
+[Amazon Music](https://github.com/gesellix/Bose-SoundTouch/issues/188). A service under
+community control is a rare chance to actually solve the things people ask for, instead of
+waiting on a roadmap that was discontinued. If there's something you wish your speakers
+did, the [issue tracker](https://github.com/gesellix/Bose-SoundTouch/issues) and
+[Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions) are where it starts.
+
+## Current release
+
+**v0.117.0**, released June 28, 2026
+
+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.
@@ -0,0 +1,5 @@
+---
+title: News & Updates
+---
+
+Project updates, release notes, and development notes for AfterTouch — the local replacement for the Bose SoundTouch cloud.
@@ -1,3 +1,9 @@
+---
+title: Introduction
+sidebar:
+  open: true
+---
+
 # Bose SoundTouch Toolkit Documentation

 Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive toolkit helps you keep your Bose SoundTouch speakers functional even after the Bose Cloud shutdown in May 2026, with enhanced local management and monitoring capabilities.
@@ -10,7 +16,7 @@ Welcome to the documentation for the Bose SoundTouch Toolkit. This comprehensive

 ### For Existing Users
 - **[Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)** - Prepare for the May 2026 shutdown
- **[Backup Tool](../cmd/soundtouch-backup/README.md)** - Back up your cloud account and speaker data before shutdown
+- **[Backup Tool](https://github.com/gesellix/Bose-SoundTouch/blob/main/cmd/soundtouch-backup/README.md)** - Back up your cloud account and speaker data before shutdown
 - **[SoundTouch Service Guide](guides/SOUNDTOUCH-SERVICE.md)** - Advanced service configuration

 ## 📋 Essential Documentation
@@ -41,7 +47,7 @@ The documentation is organized into three main categories:
 ### Advanced Features
 - [MAC Address Mapping](guides/MAC-ADDRESS-MAPPING.md) - Device identification
 - [CLI Reference](guides/CLI-REFERENCE.md) - Command-line tools
- [Backup Tool](../cmd/soundtouch-backup/README.md) - Cloud account and speaker data backup
+- [Backup Tool](https://github.com/gesellix/Bose-SoundTouch/blob/main/cmd/soundtouch-backup/README.md) - Cloud account and speaker data backup
 - [IoT Implementation Guide](guides/IOT-IMPLEMENTATION-GUIDE.md) - IoT integrations
 - [MQTT Integration Design](guides/MQTT-INTEGRATION-DESIGN.md) - MQTT setup

@@ -61,19 +67,18 @@ The documentation is organized into three main categories:
 - [IoT Config Summary](analysis/IOT-CONFIG-SUMMARY.md) - Configuration summaries

 ### Device Lifecycle & Network Independence
- **[Device Lifecycle and /power_on Enhancement](device-lifecycle-and-power-on-enhancement.md)** - Complete analysis of device registration and network independence improvements
- [/power_on Implementation Guide](power-on-implementation-guide.md) - Technical implementation details for enhanced device management
+- **[Device Lifecycle and /power_on Enhancement](appendix/device-lifecycle-and-power-on-enhancement.md)** - Complete analysis of device registration and network independence improvements
+- [/power_on Implementation Guide](appendix/power-on-implementation-guide.md) - Technical implementation details for enhanced device management

 ## 🏗 Concept Documentation

-### Enhanced Service Architecture
- **[Concept Overview](concepts/README.md)** - High-level architecture vision
- [Upstream Service Simulation](concepts/upstream-service-simulation.md) - Complete concept design
- [Implementation Plan](concepts/implementation-plan.md) - Development roadmap
- [Technical Specification](concepts/technical-specification.md) - Detailed specifications
+- [Spotify Overview](concepts/spotify-overview.md) — mental model, Spotify Connect vs OAuth-intercept, DNS rewrite gotcha
+- [Spotify OAuth](concepts/spotify-oauth.md) — flows and management endpoints
+- [Amazon Music OAuth](concepts/amazon-music-oauth.md) — companion to Spotify OAuth; same protocol shape, different scopes
+- [Encrypted Export](concepts/ENCRYPTED-EXPORT.md) — `.age`-encrypted diagnostic bundles
+- [Request Recording](appendix/REQUEST_RECORDING_CONCEPT.md) — how the proxy captures live device traffic for parity testing

-### Development Planning
- [Implementation Roadmap](concepts/implementation-roadmap.md) - Project phases and milestones
+Older planning artefacts ("Enhanced State Management System", "Upstream Service Simulation") live under [docs/archive/](../../archive/) — kept for the record, no longer current.

 ## 💡 Quick Reference

@@ -88,5 +93,6 @@ The documentation is organized into three main categories:
 - **Questions & Discussion**: [GitHub Discussions](https://github.com/gesellix/Bose-SoundTouch/discussions)
 - **Documentation**: Check troubleshooting guides first
 - **Community**: Share experiences and help others
+- **Direct chat (last resort)**: There's a small Discord for the rare case where an email exchange or an issue/discussion thread needs real-time back-and-forth. It's not a primary support channel: please start with Issues or Discussions. If a conversation genuinely needs it, ask in your thread and I'll share an invite.

-For a complete list of all documents, see the [Summary](SUMMARY.md).
+For a complete list of all documents, browse the sections in the sidebar.
@@ -1,5 +1,6 @@
-# Placeholder values for examples
-
+---
+title: "Placeholder values for examples"
+---
 This repo is public. Documentation, READMEs, example configs, and test
 fixtures must never carry real LAN IPs, real device MACs, real Bose
 account IDs, or personal device names from any maintainer or
@@ -1,12 +1,13 @@
-# Bose SoundTouch API Coverage Analysis
-
-**Last Updated:** February 2026
+---
+title: "Bose SoundTouch API Coverage Analysis"
+---
+**Last Updated:** June 2026 (reconciled against `pkg/client`)
 **API Version:** Official Bose SoundTouch Web API v1.0
-**Implementation Status:** 100% Official Coverage + Extended Features
+**Implementation Status:** Official coverage 20/21 + extended features

 ## Executive Summary

-This Go implementation provides **complete coverage** of the Bose SoundTouch Web API with **100% of official endpoints implemented** (18/19) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware.
+This Go implementation provides near-complete coverage of the Bose SoundTouch Web API with **20 of 21 official endpoints implemented** (the one exception, `/trackInfo`, is documented but non-functional on real hardware) plus **5 additional extended features** not documented in the official API v1.0 but working with real hardware.

 ### Key Findings
 - ✅ **All essential user functionality implemented**
@@ -1,5 +1,6 @@
-# Bose SoundTouch Traffic Interception Runbook
-
+---
+title: "Bose SoundTouch Traffic Interception Runbook"
+---
 Intercept HTTPS/WebSocket traffic from the Bose SoundTouch Android app using an Android emulator, mitmproxy, and Frida. Tested on Apple Silicon (ARM64) Mac.

 ## Automated Setup
@@ -1,5 +1,6 @@
-# Bose SoundTouch – Traffic Analysis Runbook
-
+---
+title: "Bose SoundTouch – Traffic Analysis Runbook"
+---
 > **Goal:** Set up a Raspberry Pi as a transparent access point to fully observe the traffic of the Bose SoundTouch app – specifically the pairing flow with the Bose Cloud. This serves as a basis for later reverse engineering / simulation of the cloud endpoints.

 ---
@@ -83,7 +84,7 @@ sudo tee /etc/systemd/network/08-wlan0.network << 'EOF'
 Name=wlan0

 [Network]
-Address=192.168.10.1/24
+Address=198.51.100.1/24
 IPForward=yes
 ConfigureWithoutCarrier=yes
 DHCP=no
@@ -103,7 +104,7 @@ sudo systemctl mask wpa_supplicant@wlan0
 **Verify:**
 ```bash
 ip addr show wlan0
-# Expected: ONLY inet 192.168.10.1/24 (NO second DHCP IP)
+# Expected: ONLY inet 198.51.100.1/24 (NO second DHCP IP)
 ```

 ---
@@ -150,9 +151,9 @@ sudo mv /etc/dnsmasq.conf /etc/dnsmasq.conf.bak

 sudo tee /etc/dnsmasq.conf << 'EOF'
 interface=wlan0
-dhcp-range=192.168.10.100,192.168.10.200,24h
-dhcp-option=3,192.168.10.1
-dhcp-option=6,192.168.10.1
+dhcp-range=198.51.100.100,198.51.100.200,24h
+dhcp-option=3,198.51.100.1
+dhcp-option=6,198.51.100.1

 # DNS Upstream: custom server on localhost (adjust port if necessary)
 server=127.0.0.1#5353    # Example: custom server on port 5353
@@ -236,7 +237,7 @@ If you cannot see the `Bose-Lab` SSID on your phone:
    ```bash
    sudo nmcli device set wlan0 managed no
    ```
-7.  **Ghost IP Conflict:** If `ip addr show wlan0` shows both `192.168.10.1` and another IP (like `192.0.2.x`), `hostapd` will fail. This is usually caused by NetworkManager managing the interface. Ensure you've run:
+7.  **Ghost IP Conflict:** If `ip addr show wlan0` shows both `198.51.100.1` and another IP (like `192.0.2.x`), `hostapd` will fail. This is usually caused by NetworkManager managing the interface. Ensure you've run:
    ```bash
    sudo nmcli device set wlan0 managed no
    # If the ghost IP is still there, remove it manually:
@@ -258,13 +259,13 @@ If you haven't created a CA yet, follow **Appendix A** first.
 # Temporarily make reachable via HTTP for easy download:
 cd /etc/my-dns-ca/
 python3 -m http.server 8080
-# → Reachable at http://192.168.10.1:8080/ca.crt
+# → Reachable at http://198.51.100.1:8080/ca.crt
 ```

 ### Install on Android

 1. Connect phone to `Bose-Lab`
-2. Open browser → `http://192.168.10.1:8080/ca.crt`
+2. Open browser → `http://198.51.100.1:8080/ca.crt`
 3. Download certificate
 4. **Settings → Security → Credentials → Install CA Certificate**
 5. Select certificate and confirm
@@ -321,7 +322,7 @@ sudo tcpdump -i wlan0 -n 'not port 53' -w /tmp/bose-nodns.pcap

 # Traffic of a specific host only (filter by phone IP)
 # Read phone IP from dnsmasq.leases beforehand (see below)
-sudo tcpdump -i wlan0 -n host 192.168.10.101
+sudo tcpdump -i wlan0 -n host 198.51.100.101
 ```

 ### Read SNI from TLS Traffic (without decryption)
@@ -350,7 +351,7 @@ Transfer `.pcap` files from the Pi to the PC:

 ```bash
 # From the PC (scp)
-scp pi@192.168.10.1:/tmp/bose-*.pcap ~/Desktop/
+scp pi@198.51.100.1:/tmp/bose-*.pcap ~/Desktop/
 ```

 **Important Wireshark Filters:**
@@ -606,7 +607,7 @@ You can either configure the macOS system proxy manually or use `mitmproxy`'s au
 **Method 1: System Proxy (Manual)**
 1.  Go to **System Settings → Network → Wi-Fi → Details... → Proxies**.
 2.  Enable **HTTP Proxy** and **HTTPS Proxy**.
-3.  Set Server to your Pi's IP (`192.168.10.1`) and Port to `8080`.
+3.  Set Server to your Pi's IP (`198.51.100.1`) and Port to `8080`.
 4.  Click **OK** and **Apply**.

 **Method 2: mitmproxy Local Redirect (Automatic)**
@@ -666,7 +667,7 @@ If the app uses **Certificate Pinning** (hardcoded hashes), even moving the CA t
 If the **Transparent AP** setup (Steps 1–6) is too complex or you are experiencing routing issues, you can use `mitmproxy` as a **Regular HTTP Proxy**.

 ### 1. How it works
-In this mode, the Pi acts as a simple server on port 8080. You tell your phone's Wi-Fi settings to send all traffic to `192.168.10.1:8080`.
+In this mode, the Pi acts as a simple server on port 8080. You tell your phone's Wi-Fi settings to send all traffic to `198.51.100.1:8080`.

 *   **Pros:** No complex `nftables` or NAT rules required.
 *   **Cons:** Many Android apps (and background processes) ignore system-wide proxy settings. **HTTPS still requires a trusted CA for decryption.**
@@ -682,7 +683,7 @@ mitmproxy --listen-port 8080
 1.  Go to **Settings → Wi-Fi → Bose-Lab**.
 2.  Select **Modify Network** (or the "i" icon).
 3.  Set **Proxy** to **Manual**.
-4.  **Proxy hostname:** `192.168.10.1`
+4.  **Proxy hostname:** `198.51.100.1`
 5.  **Proxy port:** `8080`
 6.  Save and try to browse a site.

@@ -705,7 +706,7 @@ go get github.com/google/gopacket
 go run scripts/extract-ws.go your_capture.pcap [filter_ip]

 # Example: Filter for a specific speaker's IP in WebSocket messages
-go run scripts/extract-ws.go capture.pcap 192.168.100.1
+go run scripts/extract-ws.go capture.pcap 203.0.113.1
 ```

 ### 2. Manual Extraction with tshark
@@ -888,5 +889,5 @@ pgrep -a tcpdump
 dig @127.0.0.1 -p 5353 global.api.bose.io

 # Check network connectivity from the phone (from the Pi)
-ping 192.168.10.101   # Phone IP from dnsmasq.leases
+ping 198.51.100.101   # Phone IP from dnsmasq.leases
 ```
@@ -1,5 +1,6 @@
-# Device Redirect Methods & Custom Service Setup
-
+---
+title: "Device Redirect Methods & Custom Service Setup"
+---
 To enable offline operation or use custom services like **SoundCork** or **ÜberBöse API**, SoundTouch devices must be redirected from Bose's official cloud endpoints to a local or custom server. This document outlines the three known methods to achieve this, gathered from community reverse-engineering efforts in the **SoundCork** and **ÜberBöse API** projects.

 > A fourth, **SSH-free** path — driving the device's diagnostic shell on TCP port 17000 — is being added as a peer to the XML and DNS methods. See **[TELNET-MIGRATION-METHOD.md](TELNET-MIGRATION-METHOD.md)** for the use cases, community findings, and feasibility analysis. The `/etc/hosts` method documented below is now deprecated and will not be exposed in the web UI.
@@ -1,5 +1,6 @@
-# What a SoundTouch speaker does during factory reset
-
+---
+title: "What a SoundTouch speaker does during factory reset"
+---
 Observed live on ST10 firmware `27.0.6.46330.5043500` (build `epdbuild.trunk.hepdswbld04.2022-08-04`) on 2026-05-12, by running `soundtouch-cli setup factory-reset` and tailing the speaker's `logread` over SSH. The trace is preserved at `_/logs/factory-reset.txt` for reference.

 ## Sequence
@@ -1,5 +1,6 @@
-# IoT Configuration Quick Reference
-
+---
+title: "IoT Configuration Quick Reference"
+---
 ## Key Files and Locations

 | File/Location                           | Purpose                | Notes                                   |
--- a/Show More
+++ b/Show More