Implement dynamic Bose proxy with detailed origin logging and Soundcork fallback

This commit fixes a JS error in showSummary and migrate functions where they were still trying to access the UI element by its old ID 'proxy-domain' instead of the new 'soundcork-url'.

.env.example

@@ -1,6 +1,9 @@
 # Bose SoundTouch Configuration
 # Copy this file to .env and customize for your setup
 
+# Docker/Service Settings
+SOUNDTOUCH_HOSTNAME=soundtouch.local
+
 # Discovery Settings
 DISCOVERY_TIMEOUT=5s
 UPNP_ENABLED=true

.github/workflows/ci.yml

@@ -149,8 +149,8 @@ jobs:
           # Check that all documented endpoints exist in code
           echo "Validating API documentation consistency..."
 
-          # Extract endpoint patterns from cookbook
-          if [ -f "docs/API-COOKBOOK.md" ]; then
+          # Check API cookbook
+          if [ -f "docs/reference/API-COOKBOOK.md" ]; then
             echo "✓ API Cookbook exists"
           else
             echo "✗ API Cookbook missing"
@@ -158,7 +158,7 @@ jobs:
           fi
 
           # Check getting started guide
-          if [ -f "docs/GETTING-STARTED.md" ]; then
+          if [ -f "docs/guides/GETTING-STARTED.md" ]; then
             echo "✓ Getting Started guide exists"
           else
             echo "✗ Getting Started guide missing"

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Documentation
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: 'docs/'
+          destination: '_site'
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: '_site'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -133,10 +133,13 @@ jobs:
             local CMD_PATH=$2
             local OUTPUT_NAME
 
+            # Ensure build directory exists
+            mkdir -p build
+
             if [[ "${{ matrix.goos }}" == "windows" ]]; then
-              OUTPUT_NAME="${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}.exe"
+              OUTPUT_NAME="build/${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}.exe"
             else
-              OUTPUT_NAME="${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}"
+              OUTPUT_NAME="build/${BINARY_NAME}-v${{ needs.validate.outputs.version }}-${ARCH_SUFFIX}"
             fi
 
             echo "Building $BINARY_NAME: $OUTPUT_NAME"
@@ -159,7 +162,7 @@ jobs:
 
           # Build CLI
           build_binary "soundtouch-cli" "./cmd/soundtouch-cli"
-          
+
           # Build Service
           build_binary "soundtouch-service" "./cmd/soundtouch-service"
         id: build
@@ -193,8 +196,8 @@ jobs:
         with:
           name: binaries-${{ matrix.goos }}-${{ matrix.goarch }}${{ matrix.goarm }}
           path: |
-            soundtouch-cli-v*
-            soundtouch-service-v*
+            build/soundtouch-cli-v*
+            build/soundtouch-service-v*
           retention-days: 1
 
   checksums:
@@ -203,9 +206,10 @@ jobs:
     needs: [validate, build]
 
     steps:
-      - name: Download all artifacts
+      - name: Download binary artifacts
         uses: actions/download-artifact@v7
         with:
+          pattern: binaries-*
           path: ./binaries
 
       - name: Generate checksums

.gitignore

@@ -19,14 +19,17 @@ dist/
 /example-unified
 /mdns-scanner
 /websocket-demo
+/main
 
 # Environment configuration
 .env
 .env.local
 .env.*.local
+docker-compose.override.yml
 
 # Test coverage reports
 coverage.out
+coverage*.out
 coverage.html
 *.prof
 
@@ -60,6 +63,7 @@ Thumbs.db
 *.pid
 *.seed
 *.pid.lock
+.output.txt
 
 # Runtime data
 pids

CONTRIBUTING.md

@@ -76,7 +76,7 @@ When filing a bug report, include:
 Feature requests are welcome! Please:
 
 1. **Check if the feature already exists** in documentation
-2. **Verify it's supported by the SoundTouch API** (see [official API docs](docs/API-Endpoints-Overview.md))
+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
@@ -469,10 +469,10 @@ Contributors will be:
 
 - [Go Documentation](https://golang.org/doc/)
 - [Effective Go](https://golang.org/doc/effective_go.html)
-- [Bose SoundTouch API Documentation](docs/API-Endpoints-Overview.md)
+- [Bose SoundTouch API Documentation](docs/reference/API-ENDPOINTS.md)
 - [Project Architecture](docs/PROJECT-PATTERNS.md)
-- [Development Status](docs/STATUS.md)
+- [Development Status](docs/archive/STATUS.md)
 
 ---
 
-**Thank you for contributing!** Every contribution helps make this library better for the entire SoundTouch community.
+**Thank you for contributing!** Every contribution helps make this library better for the entire SoundTouch community.

Dockerfile

@@ -1,5 +1,5 @@
 # Build stage
-FROM golang:1.25.7-alpine AS builder
+FROM golang:1.26.0-alpine AS builder
 
 WORKDIR /app
 

README.md

@@ -1,6 +1,6 @@
-# Bose SoundTouch API Client
+# Bose SoundTouch Toolkit
 
-A comprehensive Go library and CLI tool for controlling Bose SoundTouch devices via their Web API.
+A comprehensive solution for controlling and preserving Bose SoundTouch devices, including a Go library, CLI tool, and a local service for cloud emulation.
 
 [![Go Reference](https://pkg.go.dev/badge/github.com/gesellix/bose-soundtouch.svg)](https://pkg.go.dev/github.com/gesellix/bose-soundtouch)
 [![Go Report Card](https://goreportcard.com/badge/github.com/gesellix/bose-soundtouch)](https://goreportcard.com/report/github.com/gesellix/bose-soundtouch)
@@ -21,7 +21,9 @@ A comprehensive Go library and CLI tool for controlling Bose SoundTouch devices
 - 🖥️ **CLI Tool**: Comprehensive command-line interface
 - 🌐 **SoundTouch Service**: Emulate Bose cloud services for offline device operation
 - 🔧 **Service Migration**: Migrate devices to use local services instead of Bose cloud
-- 📊 **Traffic Analysis**: Proxy and log device communications for debugging
+- 📊 **Traffic Analysis**: Proxy and log device communications
+- 📝 **HTTP Recording**: Persist interactions as re-playable `.http` files
+- 🧹 **Session Management**: Manage and cleanup recorded interaction sessions
 - 🔒 **Production Ready**: Extensive testing with real SoundTouch hardware
 - 🌐 **Cross-Platform**: Windows, macOS, Linux support
 
@@ -42,148 +44,51 @@ go get github.com/gesellix/bose-soundtouch
 
 ### CLI Usage
 
-#### Discover Devices
+Find SoundTouch devices on your network:
 ```bash
-# Find SoundTouch devices on your network
 soundtouch-cli discover devices
 ```
 
-# Control a Device
+Control a device (replace `192.168.1.100` with your speaker's IP):
 ```bash
-# Basic device information
-soundtouch-cli --host 192.168.1.100 info get
+# Basic information
+soundtouch-cli --host 192.168.1.100 info
 
 # Media controls
 soundtouch-cli --host 192.168.1.100 play start
 soundtouch-cli --host 192.168.1.100 volume set --level 50
-soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY
 
 # Preset management
 soundtouch-cli --host 192.168.1.100 preset list
-soundtouch-cli --host 192.168.1.100 preset store-current --slot 1
-soundtouch-cli --host 192.168.1.100 preset select --slot 1
-
-# Browse and discover content
-soundtouch-cli --host 192.168.1.100 browse tunein
-soundtouch-cli --host 192.168.1.100 station search-tunein --query "jazz"
-soundtouch-cli --host 192.168.1.100 station add --source TUNEIN --token <token> --name "Jazz Radio"
-
-# Speaker notifications (ST-10 only)
-soundtouch-cli --host 192.168.1.100 speaker tts --text "Welcome home" --app-key YOUR_KEY
-soundtouch-cli --host 192.168.1.100 speaker url --url "https://example.com/doorbell.mp3" --app-key YOUR_KEY
-soundtouch-cli --host 192.168.1.100 speaker beep
-
-# Real-time monitoring
-soundtouch-cli --host 192.168.1.100 events subscribe
 ```
 
-### SoundTouch Service
+For full CLI documentation, see the [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html).
 
-The `soundtouch-service` is a local server that emulates Bose's cloud services, enabling offline operation and custom integrations. This is particularly valuable as Bose has announced the discontinuation of cloud support in May 2026.
+### SoundTouch Service (Cloud Shutdown Protection)
 
-#### Key Features
+The `soundtouch-service` is a local server that emulates Bose's cloud services. This is critical for keeping your speakers functional after the **Bose Cloud Shutdown in May 2026**.
 
-- **🏠 Local Service Emulation**: Complete BMX (Bose Media eXchange) and Marge service implementation
-- **🔧 Device Migration**: Seamlessly migrate devices from Bose cloud to local services  
-- **📊 Traffic Proxying**: Inspect and log all device communications for debugging
-- **🌐 Web Management UI**: Browser-based interface for device management
-- **💾 Persistent Data**: Store device configurations, presets, and usage statistics
-- **🔍 Auto-Discovery**: Automatically detect and configure SoundTouch devices
-- **🔒 Offline Operation**: Continue using full device functionality without internet
-
-#### Quick Start
+#### Key Features:
+- **🏠 Local Emulation**: BMX and Marge service implementation
+- **🔌 Easy Setup**: Activate SSH via USB stick (`remote_services` file)
+- **🔧 Device Migration**: Seamlessly transition devices to local control
+- **🌐 Web Management UI**: Easy browser-based setup and management
+- **💾 Persistent Data**: Store presets, recents, and sources locally
+- **📝 HTTP Recording**: Persist all interactions as re-playable `.http` files
+- **🧹 Session Management**: Manage and cleanup recorded interaction sessions
 
+#### Quick Start:
 ```bash
-# Install the service
-go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
-
-# Start with default settings (http://localhost:8000, proxying to http://localhost:8001)
+# Start the service
 soundtouch-service
-
-# Or configure with environment variables
-PORT=9000 PYTHON_BACKEND_URL=http://your-python-backend:8001 DATA_DIR=/my/data soundtouch-service
 ```
+Open `http://localhost:8000` in your browser to manage your devices. Documentation is also available directly through the web interface.
 
-#### Running with Docker
+For a comprehensive guide on transitioning your system, see the [Bose Cloud Shutdown: Survival Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SURVIVAL-GUIDE.html).
 
-You can also run the SoundTouch service using Docker or Docker Compose.
+Detailed service configuration and Docker instructions can be found in [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html).
 
-> **Note for macOS and Windows users**: The `--net host` option is only supported on Linux. On macOS and Windows, service discovery (mDNS, UPnP) will not work automatically within the container. You will need to manually enter your device's IP address in the management UI, and the service will communicate with it directly.
-
-##### Using Docker
-
-**Linux (with host networking for discovery):**
-```bash
-docker run -d \
-  --name soundtouch-service \
-  --network host \
-  -v $(pwd)/data:/app/data \
-  ghcr.io/gesellix/bose-soundtouch:latest
-```
-
-**macOS / Windows (with port mapping):**
-```bash
-docker run -d \
-  --name soundtouch-service \
-  -p 8000:8000 \
-  -v $(pwd)/data:/app/data \
-  ghcr.io/gesellix/bose-soundtouch:latest
-```
-
-##### Using Docker Compose
-
-Create a `docker-compose.yml` file:
-
-```yaml
-services:
-  soundtouch-service:
-    image: ghcr.io/gesellix/bose-soundtouch:latest
-    container_name: soundtouch-service
-    # Linux users: use host networking for device discovery
-    # network_mode: host
-    # macOS/Windows users: use port mapping (discovery will be manual)
-    ports:
-      - "8000:8000"
-    environment:
-      - PORT=8000
-      - DATA_DIR=/app/data
-    volumes:
-      - ./data:/app/data
-    restart: unless-stopped
-```
-
-And run:
-
-```bash
-docker-compose up -d
-```
-
-> **Note**: `--network host` is required for device discovery via UPnP and mDNS to work correctly within the container.
-
-#### Device Migration Example
-
-```bash
-# 1. Start the service
-soundtouch-service
-
-# 2. Open web UI at http://localhost:8000
-# 3. Discover your devices
-# 4. Click "Migrate" to configure devices to use local services
-
-# Or use the API directly:
-curl -X POST http://localhost:8000/setup/migrate/192.168.1.100
-```
-
-#### Service Endpoints
-
-- **Web UI**: `http://localhost:8000/` - Device management interface
-- **Discovery**: `GET /setup/devices` - List discovered devices
-- **Migration**: `POST /setup/migrate/{deviceIP}` - Switch device to local services
-- **BMX Services**: `/bmx/*` - Music service emulation (TuneIn, etc.)
-- **Marge Services**: `/marge/*` - Account and device management
-- **Proxy**: `/proxy/*` - Traffic inspection and debugging
-
-See [docs/SOUNDTOUCH-SERVICE.md](docs/SOUNDTOUCH-SERVICE.md) for detailed configuration and API reference.
+For professional migration tips and safety measures, see the [Migration & Safety Guide](https://gesellix.github.io/Bose-SoundTouch/guides/MIGRATION-SAFETY.html).
 
 ### Library Usage
 
@@ -476,19 +381,19 @@ This library supports all Bose SoundTouch-compatible devices, including:
 ## Documentation
 
 - 📖 [Contributing Guide](CONTRIBUTING.md) - How to contribute to the project
-- 📚 [API Reference](docs/API-Endpoints-Overview.md) - Complete endpoint documentation
-- 🔧 [CLI Reference](docs/CLI-REFERENCE.md) - Command-line tool guide
-- 🌐 [SoundTouch Service Guide](docs/SOUNDTOUCH-SERVICE.md) - Local service setup and migration
-- 🎯 [Getting Started](docs/GETTING-STARTED.md) - Detailed setup and usage
-- 📻 [Preset Quick Start](docs/PRESET-QUICKSTART.md) - Favorite content management
-- 🧭 [Navigation Guide](docs/NAVIGATION-GUIDE.md) - Content browsing and station management
-- 📋 [Navigation API Reference](docs/API-NAVIGATION-REFERENCE.md) - Navigation API documentation
-- ⚙️ [Advanced Features](docs/SYSTEM-ENDPOINTS.md) - Advanced functionality
-- 🏠 [Multiroom Setup](docs/zone-management.md) - Zone configuration guide
-- ⚡ [WebSocket Events](docs/websocket-events.md) - Real-time event handling
-- 🔔 [Speaker Notifications](docs/SPEAKER_ENDPOINT.md) - TTS and audio notifications guide
-- 🔍 [Device Discovery](docs/DISCOVERY.md) - Discovery configuration
-- 🛠️ [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
+ - 📚 [API Reference](https://gesellix.github.io/Bose-SoundTouch/reference/API-ENDPOINTS.html) - Complete endpoint documentation
+- 🔧 [CLI Reference](https://gesellix.github.io/Bose-SoundTouch/guides/CLI-REFERENCE.html) - Command-line tool guide
+- 🌐 [SoundTouch Service Guide](https://gesellix.github.io/Bose-SoundTouch/guides/SOUNDTOUCH-SERVICE.html) - Local service setup and migration
+- 🎯 [Getting Started](https://gesellix.github.io/Bose-SoundTouch/guides/GETTING-STARTED.html) - Detailed setup and usage
+- 📻 [Preset Quick Start](https://gesellix.github.io/Bose-SoundTouch/PRESET-QUICKSTART.md) - Favorite content management
+- 🧭 [Navigation Guide](https://gesellix.github.io/Bose-SoundTouch/NAVIGATION-GUIDE.md) - Content browsing and station management
+- 📋 [Navigation API Reference](https://gesellix.github.io/Bose-SoundTouch/API-NAVIGATION-REFERENCE.md) - Navigation API documentation
+- ⚙️ [Advanced Features](https://gesellix.github.io/Bose-SoundTouch/reference/SYSTEM-ENDPOINTS.html) - Advanced functionality
+- 🏠 [Multiroom Setup](https://gesellix.github.io/Bose-SoundTouch/reference/ZONE-MANAGEMENT.html) - Zone configuration guide
+- ⚡ [WebSocket Events](https://gesellix.github.io/Bose-SoundTouch/reference/WEBSOCKET-EVENTS.html) - Real-time event handling
+- 🔔 [Speaker Notifications](https://gesellix.github.io/Bose-SoundTouch/reference/SPEAKER-ENDPOINT.html) - TTS and audio notifications guide
+- 🔍 [Device Discovery](https://gesellix.github.io/Bose-SoundTouch/reference/DISCOVERY.html) - Discovery configuration
+- 🛠️ [Troubleshooting](https://gesellix.github.io/Bose-SoundTouch/guides/TROUBLESHOOTING.html) - Common issues and solutions
 
 ## Development
 
@@ -575,14 +480,14 @@ This project builds upon the excellent work of several community projects:
 
 ### SoundCork 🍾
 - **Project**: [SoundCork - SoundTouch API Intercept](https://github.com/deborahgu/soundcork)
-- **Authors**: Deborah Gu and contributors
-- **Our Implementation**: The `soundtouch-service` in this project is heavily inspired by and based on SoundCork's Python implementation. SoundCork pioneered the approach of intercepting and emulating Bose's cloud services, providing the foundation for offline SoundTouch operation.
+- **Authors**: Deborah Kaplan and contributors
+- **Our Implementation**: The `soundtouch-service` in this project is heavily inspired by SoundCork's Python implementation. SoundCork pioneered the approach of intercepting and emulating Bose's cloud services, providing the foundation for offline SoundTouch operation.
 - **Key Contributions**: Service emulation architecture, BMX/Marge endpoint discovery, device migration strategies
 - **License**: MIT License
 
 ### ÜberBöse API 🎵
 - **Project**: [ÜberBöse API](https://github.com/julius-d/ueberboese-api)
-- **Author**: Julius D.
+- **Author**: Julius
 - **Our Implementation**: This project provided valuable insights into advanced SoundTouch API endpoints and helped make our implementation more complete, particularly for content navigation and advanced device features.
 - **Key Contributions**: Extended API endpoint documentation, advanced feature discovery
 - **License**: MIT License
@@ -595,6 +500,13 @@ This project builds upon the excellent work of several community projects:
 - **Key Contributions**: Extensive API endpoint documentation, real-world usage patterns
 - **License**: MIT License
 
+### SoundTouch Hook 🪝
+- **Project**: [Bose SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook)
+- **Author**: Adrian Böckenkamp
+- **Our Implementation**: This project provides a powerful framework for intercepting and hooking into internal device processes using `LD_PRELOAD`. It was instrumental in verifying internal function calls and understanding how the device validates cloud domains.
+- **Key Contributions**: Reverse engineering framework, process hooking, cross-compilation toolchain
+- **License**: GPL-3.0 License
+
 ### Community Ecosystem
 
 These projects together form a comprehensive ecosystem for SoundTouch device management:
@@ -603,6 +515,7 @@ These projects together form a comprehensive ecosystem for SoundTouch device man
 - **SoundCork**: Python-based service interception and cloud replacement  
 - **SoundTouch Plus**: Home Assistant integration with extensive device support
 - **ÜberBöse**: API research and advanced endpoint discovery
+- **SoundTouch Hook**: Advanced reverse engineering and process instrumentation
 
 We are grateful to these projects and their maintainers for paving the way and providing the foundation that made this comprehensive Go implementation possible. The SoundTouch community's collaborative approach to reverse engineering and documentation has been invaluable.
 
@@ -615,7 +528,13 @@ If you discover new endpoints, features, or improvements through this library, p
 - 🐛 **Bug Reports**: [Create an issue](https://github.com/gesellix/bose-soundtouch/issues/new)
 - 💡 **Feature Requests**: [Start a discussion](https://github.com/gesellix/bose-soundtouch/discussions)
 - ❓ **Questions**: Check [existing discussions](https://github.com/gesellix/bose-soundtouch/discussions)
-- 📖 **Documentation**: Browse the [docs/](docs/) directory
+- 📖 **Documentation**: [Online Documentation](https://gesellix.github.io/Bose-SoundTouch/)
+- 🔍 **New Discoveries**: [Undocumented Community Features](https://gesellix.github.io/Bose-SoundTouch/UNDOCUMENTED-COMMUNITY-FEATURES.md)
+- 🌐 **Upstream Analysis**: [Upstream URLs & Domains](https://gesellix.github.io/Bose-SoundTouch/analysis/UPSTREAM-URLS.html)
+- 🔧 **Redirection Guide**: [Device Redirect Methods](https://gesellix.github.io/Bose-SoundTouch/analysis/DEVICE-REDIRECT-METHODS.html)
+- 🐣 **Initial Setup**: [Device Initial Setup Variants](https://gesellix.github.io/Bose-SoundTouch/guides/DEVICE-INITIAL-SETUP.html)
+- 📜 **Logging & Debugging**: [Device Logging Guide](https://gesellix.github.io/Bose-SoundTouch/DEVICE-LOGGING.md)
+- 🔒 **HTTPS & CA Setup**: [HTTPS & Custom CA Guide](https://gesellix.github.io/Bose-SoundTouch/guides/HTTPS-SETUP.html)
 
 ---
 

cmd/soundtouch-cli/cmd_speaker.go

@@ -147,10 +147,16 @@ func playURL(c *cli.Context) error {
 	return nil
 }
 
-// playNotificationBeep plays a notification beep on the speaker (uses existing endpoint)
-func playNotificationBeep(c *cli.Context) error {
+// playNotification plays a notification sound or a local file on the speaker
+func playNotification(c *cli.Context) error {
 	clientConfig := GetClientConfig(c)
-	PrintDeviceHeader("Playing notification beep", clientConfig.Host, clientConfig.Port)
+	path := c.String("path")
+
+	if path != "" {
+		PrintDeviceHeader(fmt.Sprintf("Playing notification file: %s", path), clientConfig.Host, clientConfig.Port)
+	} else {
+		PrintDeviceHeader("Playing notification beep", clientConfig.Host, clientConfig.Port)
+	}
 
 	client, err := CreateSoundTouchClient(clientConfig)
 	if err != nil {
@@ -158,18 +164,31 @@ func playNotificationBeep(c *cli.Context) error {
 		return err
 	}
 
-	// Use the existing playNotification endpoint
-	err = client.PlayNotificationBeep()
+	err = client.PlayNotification(path)
 	if err != nil {
-		PrintError(fmt.Sprintf("Failed to play notification beep: %v", err))
+		if path != "" {
+			PrintError(fmt.Sprintf("Failed to play notification file: %v", err))
+		} else {
+			PrintError(fmt.Sprintf("Failed to play notification beep: %v", err))
+		}
+
 		return err
 	}
 
-	fmt.Printf("✅ Notification beep played successfully\n")
+	if path != "" {
+		fmt.Printf("✅ Notification file sent successfully: %s\n", path)
+	} else {
+		fmt.Printf("✅ Notification beep played successfully\n")
+	}
 
 	return nil
 }
 
+// playNotificationBeep plays a notification beep on the speaker (uses existing endpoint)
+func playNotificationBeep(c *cli.Context) error {
+	return playNotification(c)
+}
+
 // showSpeakerHelp displays help information about speaker functionality
 func showSpeakerHelp(_ *cli.Context) error {
 	fmt.Println("SoundTouch Speaker Playback Commands")
@@ -189,6 +208,10 @@ func showSpeakerHelp(_ *cli.Context) error {
 	fmt.Println("  Play a simple notification sound")
 	fmt.Println("  Example: soundtouch-cli speaker beep")
 	fmt.Println()
+	fmt.Println("• Custom Notification:")
+	fmt.Println("  Play a device-local PCM file as notification")
+	fmt.Println("  Example: soundtouch-cli speaker notify --path \"/opt/Bose/chimes/grouped.pcm\"")
+	fmt.Println()
 	fmt.Println("Notes:")
 	fmt.Println("• Only ST-10 (Series III) speakers support the /speaker endpoint")
 	fmt.Println("• ST-300 and other models may not support this functionality")

cmd/soundtouch-cli/common.go

@@ -7,6 +7,7 @@ import (
 	"io"
 	"net"
 	"net/http"
+	"os"
 	"regexp"
 	"runtime"
 	"strconv"
@@ -331,7 +332,7 @@ func PrintWarning(message string) {
 
 // showVersionInfo displays detailed version information including build details
 func showVersionInfo(_ *cli.Context) error {
-	fmt.Printf("soundtouch-cli version %s\n", version)
+	fmt.Printf("%s version %s\n", os.Args[0], version)
 	fmt.Printf("Build commit: %s\n", commit)
 	fmt.Printf("Build date: %s\n", date)
 	fmt.Printf("Go version: %s\n", runtime.Version())

cmd/soundtouch-cli/main.go

@@ -104,7 +104,7 @@ func main() {
 		Version: version,
 		Authors: []*cli.Author{
 			{
-				Name: "Tobias Gesellchen, and the SoundTouch CLI Contributors",
+				Name: "Tobias Gesellchen, and the Bose-SoundTouch Contributors",
 			},
 		},
 		Flags: CommonFlags,
@@ -1707,6 +1707,19 @@ func main() {
 							},
 						},
 					},
+					{
+						Name:   "notify",
+						Usage:  "Play a notification sound or local file",
+						Action: playNotification,
+						Before: RequireHost,
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:    "path",
+								Aliases: []string{"p"},
+								Usage:   "Device-local path to a PCM file (e.g. /opt/Bose/chimes/grouped.pcm)",
+							},
+						},
+					},
 					{
 						Name:   "beep",
 						Usage:  "Play a notification beep sound",

cmd/soundtouch-service/main.go

@@ -4,113 +4,449 @@ package main
 
 import (
 	"context"
+	"crypto/tls"
+	"encoding/json"
+	"fmt"
 	"log"
 	"net/http"
-	"net/http/httputil"
 	"net/url"
 	"os"
+	"path/filepath"
+	"runtime"
+	"runtime/debug"
 	"strings"
 	"time"
 
+	"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/proxy"
 	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
 	"github.com/go-chi/chi/v5"
 	"github.com/go-chi/chi/v5/middleware"
+	"github.com/urfave/cli/v2"
 )
 
+var (
+	version = "dev"
+	commit  = "unknown"
+	date    = "unknown"
+)
+
+func updateBuildInfo() {
+	if info, ok := debug.ReadBuildInfo(); ok {
+		if info.Main.Version != "" && info.Main.Version != "(devel)" {
+			version = info.Main.Version
+		}
+
+		for _, setting := range info.Settings {
+			switch setting.Key {
+			case "vcs.revision":
+				commit = setting.Value
+			case "vcs.time":
+				if t, err := time.Parse(time.RFC3339, setting.Value); err == nil {
+					date = t.Format("2006-01-02_15:04:05")
+				}
+			}
+		}
+	}
+}
+
 func main() {
-	port := os.Getenv("PORT")
-	if port == "" {
-		port = "8000"
+	updateBuildInfo()
+
+	app := &cli.App{
+		Name:  "soundtouch-service",
+		Usage: "Local service for Bose SoundTouch cloud emulation and management",
+		Description: `⠎⠕⠥⠝⠙⠤⠞⠕⠥⠉⠓ A local server that emulates Bose cloud services (BMX, Marge).
+   It enables offline operation, device migration, and HTTP interaction recording.`,
+		Version: version,
+		Authors: []*cli.Author{
+			{
+				Name: "Tobias Gesellchen, and the Bose-SoundTouch Contributors",
+			},
+		},
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "port",
+				Aliases: []string{"p"},
+				Usage:   "HTTP port to bind the service to",
+				Value:   "8000",
+				EnvVars: []string{"PORT"},
+			},
+			&cli.StringFlag{
+				Name:    "bind",
+				Usage:   "Network interface to bind to",
+				EnvVars: []string{"BIND_ADDR"},
+			},
+			&cli.StringFlag{
+				Name:    "soundcork-url",
+				Usage:   "URL for Soundcork-based service components (legacy)",
+				Value:   "http://localhost:8001",
+				EnvVars: []string{"SOUNDCORK_BACKEND_URL", "TARGET_URL"},
+			},
+			&cli.BoolFlag{
+				Name:    "enable-soundcork-proxy",
+				Usage:   "Enable proxying unknown requests to the Soundcork backend",
+				EnvVars: []string{"ENABLE_SOUNDCORK_PROXY"},
+			},
+			&cli.StringFlag{
+				Name:    "data-dir",
+				Usage:   "Directory for persistent data",
+				Value:   "data",
+				EnvVars: []string{"DATA_DIR"},
+			},
+			&cli.StringFlag{
+				Name:    "server-url",
+				Aliases: []string{"s"},
+				Usage:   "External URL of this service",
+				EnvVars: []string{"SERVER_URL"},
+			},
+			&cli.StringFlag{
+				Name:    "https-port",
+				Usage:   "HTTPS port to bind the service to",
+				Value:   "8443",
+				EnvVars: []string{"HTTPS_PORT"},
+			},
+			&cli.StringFlag{
+				Name:    "https-server-url",
+				Aliases: []string{"S"},
+				Usage:   "External HTTPS URL",
+				EnvVars: []string{"HTTPS_SERVER_URL"},
+			},
+			&cli.BoolFlag{
+				Name:    "redact-logs",
+				Usage:   "Redact sensitive data in proxy logs",
+				Value:   true,
+				EnvVars: []string{"REDACT_PROXY_LOGS"},
+			},
+			&cli.BoolFlag{
+				Name:    "log-bodies",
+				Usage:   "Log full request/response bodies",
+				EnvVars: []string{"LOG_PROXY_BODY"},
+			},
+			&cli.BoolFlag{
+				Name:    "record-interactions",
+				Usage:   "Record HTTP interactions to disk",
+				Value:   true,
+				EnvVars: []string{"RECORD_INTERACTIONS"},
+			},
+			&cli.StringFlag{
+				Name:    "discovery-interval",
+				Usage:   "Device discovery interval",
+				Value:   "5m",
+				EnvVars: []string{"DISCOVERY_INTERVAL"},
+			},
+		},
+		Action: func(c *cli.Context) error {
+			config := loadConfig(c)
+			ds := initDataStore(config.dataDir)
+
+			persisted := applyPersistedSettings(ds, &config)
+
+			if persisted.ServerURL == "" {
+				log.Printf("Creating default settings.json in %s", config.dataDir)
+				persisted = createDefaultSettings(ds, config)
+			}
+
+			// Recalculate domains if settings changed
+			hostname, _ := os.Hostname()
+			if hostname == "" {
+				hostname = "localhost"
+			}
+
+			config.domains = getDomains(config.serverURL, config.httpsServerURL, hostname)
+
+			cm := initCertificateManager(config.dataDir)
+			sm := setup.NewManager(config.serverURL, ds, cm)
+			server := handlers.NewServer(ds, sm, config.serverURL, config.redact, config.logBody, config.record, config.enableSoundcorkProxy)
+			server.SetSoundcorkURL(config.soundcorkURL)
+			server.SetHTTPServerURL(config.httpsServerURL)
+			server.SetVersionInfo(version, commit, date)
+			server.SetDiscoverySettings(config.discoveryInterval, persisted.DiscoveryEnabled)
+			server.SetShortcuts(persisted.Shortcuts)
+
+			for path, status := range persisted.Shortcuts {
+				log.Printf("Warning: configured shortcut: %s -> %d", path, status)
+			}
+
+			recorder := proxy.NewRecorder(config.dataDir)
+			recorder.Redact = config.redact
+			patternsPath := filepath.Join(config.dataDir, "patterns.json")
+
+			patterns, err := proxy.LoadPatterns(patternsPath)
+			if err != nil {
+				log.Printf("Warning: Failed to load patterns from %s: %v", patternsPath, err)
+			}
+
+			if len(patterns) == 0 {
+				log.Printf("Creating default patterns at %s", patternsPath)
+
+				patterns = proxy.DefaultPatterns()
+
+				patternsData, jsonErr := json.MarshalIndent(patterns, "", "  ")
+				if jsonErr != nil {
+					log.Printf("Warning: Failed to marshal default patterns: %v", jsonErr)
+				} else {
+					_ = os.WriteFile(patternsPath, patternsData, 0644)
+				}
+			}
+
+			if len(patterns) > 0 {
+				recorder.Patterns = patterns
+			}
+
+			server.SetRecorder(recorder)
+
+			tlsConfig, err := cm.GetServerTLSConfig(config.domains)
+			if err != nil {
+				log.Printf("Warning: Failed to setup TLS: %v", err)
+			}
+
+			startDeviceDiscovery(server)
+
+			r := setupRouter(server)
+
+			log.Printf("Go service starting on %s, proxying to %s", config.serverURL, config.soundcorkURL)
+
+			if tlsConfig != nil {
+				startHTTPSServer(config.httpsAddr, r, tlsConfig, config.httpsServerURL)
+			}
+
+			return http.ListenAndServe(config.addr, r)
+		},
+		Commands: []*cli.Command{
+			{
+				Name:    "version",
+				Aliases: []string{"v"},
+				Usage:   "Show detailed version information",
+				Action:  showVersionInfo,
+			},
+		},
 	}
 
-	bindAddr := os.Getenv("BIND_ADDR")
-	// If BIND_ADDR is explicitly set, use it. Otherwise, bind to all interfaces (IPv4 and IPv6).
+	if err := app.Run(os.Args); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func showVersionInfo(_ *cli.Context) error {
+	fmt.Printf("%s version %s\n", os.Args[0], version)
+	fmt.Printf("Build commit: %s\n", commit)
+	fmt.Printf("Build date: %s\n", date)
+	fmt.Printf("Go version: %s\n", runtime.Version())
+	fmt.Printf("Platform: %s/%s\n", runtime.GOOS, runtime.GOARCH)
+
+	return nil
+}
+
+type serviceConfig struct {
+	port                 string
+	bindAddr             string
+	addr                 string
+	soundcorkURL         string
+	dataDir              string
+	serverURL            string
+	httpsServerURL       string
+	httpsAddr            string
+	redact               bool
+	logBody              bool
+	record               bool
+	enableSoundcorkProxy bool
+	discoveryInterval    time.Duration
+	domains              []string
+}
+
+func loadConfig(c *cli.Context) serviceConfig {
+	port := c.String("port")
+	bindAddr := c.String("bind")
+
 	addr := bindAddr + ":" + port
 	if bindAddr == "" {
 		addr = ":" + port
 	}
 
-	targetURL := os.Getenv("PYTHON_BACKEND_URL")
-	if targetURL == "" {
-		targetURL = "http://localhost:8001"
+	soundcorkURL := c.String("soundcork-url")
+	dataDir := c.String("data-dir")
+
+	hostname, _ := os.Hostname()
+	if hostname == "" {
+		hostname = "localhost"
 	}
 
-	target, err := url.Parse(targetURL)
+	hostname = strings.ToLower(hostname)
+
+	serverURL := c.String("server-url")
+	if serverURL == "" {
+		serverURL = "http://" + hostname + ":" + port
+	}
+
+	httpsPort := c.String("https-port")
+
+	httpsAddr := bindAddr + ":" + httpsPort
+	if bindAddr == "" {
+		httpsAddr = ":" + httpsPort
+	}
+
+	httpsServerURL := c.String("https-server-url")
+	if httpsServerURL == "" {
+		httpsServerURL = "https://" + hostname + ":" + httpsPort
+	}
+
+	domains := getDomains(serverURL, httpsServerURL, hostname)
+
+	redact := c.Bool("redact-logs")
+	logBody := c.Bool("log-bodies")
+	record := c.Bool("record-interactions")
+	enableSoundcorkProxy := c.Bool("enable-soundcork-proxy")
+
+	discoveryIntervalStr := c.String("discovery-interval")
+
+	discoveryInterval, err := time.ParseDuration(discoveryIntervalStr)
 	if err != nil {
-		log.Fatalf("Failed to parse target URL: %v", err)
+		log.Printf("Warning: Failed to parse discovery interval %s, using default 5m: %v", discoveryIntervalStr, err)
+
+		discoveryInterval = 5 * time.Minute
 	}
 
-	dataDir := os.Getenv("DATA_DIR")
-	if dataDir == "" {
-		dataDir = "data"
+	return serviceConfig{
+		port:                 port,
+		bindAddr:             bindAddr,
+		addr:                 addr,
+		soundcorkURL:         soundcorkURL,
+		dataDir:              dataDir,
+		serverURL:            serverURL,
+		httpsServerURL:       httpsServerURL,
+		httpsAddr:            httpsAddr,
+		redact:               redact,
+		logBody:              logBody,
+		record:               record,
+		enableSoundcorkProxy: enableSoundcorkProxy,
+		discoveryInterval:    discoveryInterval,
+		domains:              domains,
+	}
+}
+
+func getDomains(serverURL, httpsServerURL, hostname string) []string {
+	domainsMap := map[string]bool{
+		"streaming.bose.com":  true,
+		"updates.bose.com":    true,
+		"stats.bose.com":      true,
+		"bmx.bose.com":        true,
+		"content.api.bose.io": true,
+		setup.TestDomain:      true,
+		hostname:              true,
+		"localhost":           true,
+		"127.0.0.1":           true,
 	}
 
+	if u, err := url.Parse(serverURL); err == nil && u.Hostname() != "" {
+		domainsMap[strings.ToLower(u.Hostname())] = true
+	}
+
+	if u, err := url.Parse(httpsServerURL); err == nil && u.Hostname() != "" {
+		domainsMap[strings.ToLower(u.Hostname())] = true
+	}
+
+	domains := make([]string, 0, len(domainsMap))
+	for d := range domainsMap {
+		domains = append(domains, d)
+	}
+
+	return domains
+}
+
+func applyPersistedSettings(ds *datastore.DataStore, config *serviceConfig) datastore.Settings {
+	persisted, err := ds.GetSettings()
+	if err != nil {
+		return datastore.Settings{}
+	}
+
+	if persisted.ServerURL != "" {
+		config.serverURL = persisted.ServerURL
+	}
+
+	if persisted.SoundcorkURL != "" {
+		config.soundcorkURL = persisted.SoundcorkURL
+	}
+
+	if persisted.HTTPServerURL != "" {
+		config.httpsServerURL = persisted.HTTPServerURL
+	}
+
+	if persisted.DiscoveryInterval != "" {
+		if d, durErr := time.ParseDuration(persisted.DiscoveryInterval); durErr == nil {
+			config.discoveryInterval = d
+		}
+	}
+
+	config.redact = persisted.RedactLogs || config.redact
+	config.logBody = persisted.LogBodies || config.logBody
+	config.record = persisted.RecordInteractions || config.record
+	config.enableSoundcorkProxy = persisted.EnableSoundcorkProxy || config.enableSoundcorkProxy
+
+	return persisted
+}
+
+func createDefaultSettings(ds *datastore.DataStore, config serviceConfig) datastore.Settings {
+	settings := datastore.Settings{
+		ServerURL:            config.serverURL,
+		SoundcorkURL:         config.soundcorkURL,
+		HTTPServerURL:        config.httpsServerURL,
+		RedactLogs:           config.redact,
+		LogBodies:            config.logBody,
+		RecordInteractions:   config.record,
+		DiscoveryInterval:    config.discoveryInterval.String(),
+		DiscoveryEnabled:     true,
+		EnableSoundcorkProxy: config.enableSoundcorkProxy,
+		Shortcuts: map[string]int{
+			"/.well-known/appspecific/com.chrome.devtools.json": http.StatusNotFound,
+			"/sw.js": http.StatusNotFound,
+		},
+	}
+	_ = ds.SaveSettings(settings)
+
+	return settings
+}
+
+func initDataStore(dataDir string) *datastore.DataStore {
 	ds := datastore.NewDataStore(dataDir)
 	if err := ds.Initialize(); err != nil {
 		log.Printf("Warning: Failed to initialize datastore: %v", err)
 	}
 
-	serverURL := os.Getenv("SERVER_URL")
-	if serverURL == "" {
-		// Try to guess the server URL
-		hostname, _ := os.Hostname()
-		if hostname == "" {
-			hostname = "localhost"
-		}
+	return ds
+}
 
-		serverURL = "http://" + strings.ToLower(hostname) + ":" + port
+func initCertificateManager(dataDir string) *certmanager.CertificateManager {
+	cm := certmanager.NewCertificateManager(filepath.Join(dataDir, "certs"))
+	if err := cm.EnsureCA(); err != nil {
+		log.Printf("Warning: Failed to ensure CA: %v", err)
 	}
 
-	sm := setup.NewManager(serverURL, ds)
+	return cm
+}
 
-	redact := os.Getenv("REDACT_PROXY_LOGS") != "false"
-	logBody := os.Getenv("LOG_PROXY_BODY") == "true"
-
-	server := handlers.NewServer(ds, sm, serverURL, redact, logBody)
-
-	pyProxy := httputil.NewSingleHostReverseProxy(target)
-	pyProxy.ModifyResponse = func(res *http.Response) error {
-		// Generic Header Preservation:
-		// Go's net/http canonicalizes headers (e.g., ETag becomes Etag).
-		// We ensure ETag specifically uses uppercase 'T' as some Bose devices are case-sensitive.
-		if etags, ok := res.Header["Etag"]; ok {
-			delete(res.Header, "Etag")
-			res.Header["ETag"] = etags
-		}
-		// Also restore other potentially sensitive headers if needed, but for now we focus on ETag
-		// as it's the most common culprit.
-
-		currentLp := proxy.NewLoggingProxy(target.String(), redact)
-		currentLp.LogBody = logBody
-		currentLp.LogResponse(res)
-
-		return nil
-	}
-	originalPyDirector := pyProxy.Director
-	pyProxy.Director = func(req *http.Request) {
-		originalPyDirector(req)
-
-		currentLp := proxy.NewLoggingProxy(target.String(), redact)
-		currentLp.LogBody = logBody
-		currentLp.LogRequest(req)
-	}
-
-	// Phase 5: Device Discovery
+func startDeviceDiscovery(server *handlers.Server) {
 	go func() {
 		for {
-			server.DiscoverDevices(context.Background())
-			time.Sleep(5 * time.Minute)
+			currentInterval, enabled := server.GetDiscoverySettings()
+			if enabled {
+				server.DiscoverDevices(context.Background())
+			}
+
+			time.Sleep(currentInterval)
 		}
 	}()
+}
 
+func setupRouter(server *handlers.Server) *chi.Mux {
 	r := chi.NewRouter()
-	r.Use(middleware.Logger)
+	r.Use(server.OriginMiddleware)
 	r.Use(middleware.Recoverer)
+	r.Use(server.ShortcutMiddleware)
+	r.Use(server.RecordMiddleware)
 
-	// Phase 2: Root endpoint implemented in Go
 	r.Get("/", server.HandleRoot)
 	r.Get("/health", server.HandleHealth)
 	r.Get("/favicon.ico", func(w http.ResponseWriter, r *http.Request) {
@@ -118,10 +454,10 @@ func main() {
 		server.HandleMedia()(w, r)
 	})
 
-	// Phase 2: Static file serving for /media
 	r.Get("/media/*", server.HandleMedia())
+	r.Get("/web/*", server.HandleWeb())
+	r.Get("/docs/*", server.HandleDocs)
 
-	// Phase 3: BMX endpoints
 	r.Route("/bmx", func(r chi.Router) {
 		r.Get("/registry/v1/services", server.HandleBMXRegistry)
 		r.Get("/tunein/v1/playback/station/{stationID}", server.HandleTuneInPlayback)
@@ -130,7 +466,13 @@ func main() {
 		r.Post("/orion/v1/playback/station/{data}", server.HandleOrionPlayback)
 	})
 
-	// Phase 4: Marge endpoints
+	// Legacy or direct domain calls without /bmx prefix
+	r.Get("/registry/v1/services", server.HandleBMXRegistry)
+	r.Get("/tunein/v1/playback/station/{stationID}", server.HandleTuneInPlayback)
+	r.Get("/tunein/v1/playback/episodes/{podcastID}", server.HandleTuneInPodcastInfo)
+	r.Get("/tunein/v1/playback/episode/{podcastID}", server.HandleTuneInPlaybackPodcast)
+	r.Post("/orion/v1/playback/station/{data}", server.HandleOrionPlayback)
+
 	r.Route("/marge", func(r chi.Router) {
 		r.Get("/streaming/sourceproviders", server.HandleMargeSourceProviders)
 		r.Get("/accounts/{account}/full", server.HandleMargeAccountFull)
@@ -144,39 +486,96 @@ func main() {
 		r.Get("/streaming/account/{account}/provider_settings", server.HandleMargeProviderSettings)
 		r.Get("/streaming/device/{device}/streaming_token", server.HandleMargeStreamingToken)
 		r.Post("/streaming/support/customersupport", server.HandleMargeCustomerSupport)
+		r.Get("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeGetDeviceSettings)
+		r.Post("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeUpdateDeviceSettings)
+		r.Get("/streaming/account/{account}/emailaddress", server.HandleMargeGetEmailAddress)
+	})
+
+	// Legacy or direct domain calls without /marge prefix
+	r.Get("/streaming/sourceproviders", server.HandleMargeSourceProviders)
+	r.Get("/accounts/{account}/full", server.HandleMargeAccountFull)
+	r.Post("/streaming/support/power_on", server.HandleMargePowerOn)
+	r.Get("/updates/soundtouch", server.HandleMargeSoftwareUpdate)
+	r.Get("/accounts/{account}/devices/{device}/presets", server.HandleMargePresets)
+	r.Post("/accounts/{account}/devices/{device}/presets/{presetNumber}", server.HandleMargeUpdatePreset)
+	r.Post("/accounts/{account}/devices/{device}/recents", server.HandleMargeAddRecent)
+	r.Post("/accounts/{account}/devices", server.HandleMargeAddDevice)
+	r.Delete("/accounts/{account}/devices/{device}", server.HandleMargeRemoveDevice)
+	r.Get("/streaming/account/{account}/provider_settings", server.HandleMargeProviderSettings)
+	r.Get("/streaming/device/{device}/streaming_token", server.HandleMargeStreamingToken)
+	r.Post("/streaming/support/customersupport", server.HandleMargeCustomerSupport)
+	r.Get("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeGetDeviceSettings)
+	r.Post("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeUpdateDeviceSettings)
+	r.Get("/streaming/account/{account}/emailaddress", server.HandleMargeGetEmailAddress)
+
+	r.Route("/customer", func(r chi.Router) {
+		r.Get("/account/{account}", server.HandleMargeAccountProfile)
+		r.Post("/account/{account}", server.HandleMargeUpdateAccountProfile)
+		r.Post("/account/{account}/password", server.HandleMargeChangePassword)
+	})
+
+	r.Route("/v1", func(r chi.Router) {
+		r.Post("/stapp/{deviceId}", server.HandleAppEvents)
+		r.Post("/scmudc/{deviceId}", server.HandleAppEvents)
 	})
 
-	// Phase 10: Stats endpoints
 	r.Route("/streaming/stats", func(r chi.Router) {
 		r.Post("/usage", server.HandleUsageStats)
 		r.Post("/error", server.HandleErrorStats)
 	})
 
-	// Proxy route integrated into main router
 	r.Get("/proxy/*", server.HandleProxyRequest)
 
-	// Phase 7: Setup and Discovery endpoints
 	r.Route("/setup", func(r chi.Router) {
 		r.Get("/devices", server.HandleListDiscoveredDevices)
+		r.Post("/devices", server.HandleAddManualDevice)
+		r.Delete("/devices/{deviceId}", server.HandleRemoveDevice)
 		r.Post("/discover", server.HandleTriggerDiscovery)
 		r.Get("/discovery-status", server.HandleGetDiscoveryStatus)
 		r.Get("/settings", server.HandleGetSettings)
+		r.Post("/settings", server.HandleUpdateSettings)
 		r.Get("/info/{deviceIP}", server.HandleGetDeviceInfo)
 		r.Get("/summary/{deviceIP}", server.HandleGetMigrationSummary)
 		r.Post("/migrate/{deviceIP}", server.HandleMigrateDevice)
+		r.Post("/revert/{deviceIP}", server.HandleRevertMigration)
+		r.Post("/reboot/{deviceIP}", server.HandleRebootDevice)
+		r.Post("/trust-ca/{deviceIP}", server.HandleTrustCACert)
 		r.Post("/ensure-remote-services/{deviceIP}", server.HandleEnsureRemoteServices)
 		r.Post("/remove-remote-services/{deviceIP}", server.HandleRemoveRemoteServices)
 		r.Post("/backup/{deviceIP}", server.HandleBackupConfig)
+		r.Post("/sync/{deviceIP}", server.HandleInitialSync)
+		r.Post("/test-connection/{deviceIP}", server.HandleTestConnection)
+		r.Post("/test-hosts/{deviceIP}", server.HandleTestHostsRedirection)
+		r.Get("/ca.crt", server.HandleGetCACert)
 		r.Get("/proxy-settings", server.HandleGetProxySettings)
 		r.Post("/proxy-settings", server.HandleUpdateProxySettings)
+		r.Get("/version", server.HandleGetVersionInfo)
+		r.Get("/interaction-stats", server.HandleGetInteractionStats)
+		r.Get("/interactions", server.HandleListInteractions)
+		r.Get("/interaction-content", server.HandleGetInteractionContent)
+		r.Get("/interactions/sessions/{session}/download", server.HandleDownloadSession)
+		r.Delete("/interactions/sessions/{session}", server.HandleDeleteSession)
+		r.Delete("/interactions/sessions", server.HandleCleanupSessions)
 		r.Get("/devices/{deviceId}/events", server.HandleGetDeviceEvents)
 	})
 
-	// Delegation Logic: Proxy everything else to Python
-	r.NotFound(func(w http.ResponseWriter, r *http.Request) {
-		pyProxy.ServeHTTP(w, r)
-	})
+	r.NotFound(server.HandleNotFound)
 
-	log.Printf("Go service starting on %s, proxying to %s", addr, targetURL)
-	log.Fatal(http.ListenAndServe(addr, r))
+	return r
+}
+
+func startHTTPSServer(httpsAddr string, r http.Handler, tlsConfig *tls.Config, httpsServerURL string) {
+	httpsServer := &http.Server{
+		Addr:      httpsAddr,
+		Handler:   r,
+		TLSConfig: tlsConfig,
+	}
+
+	log.Printf("Go service starting HTTPS on %s", httpsServerURL)
+
+	go func() {
+		if err := httpsServer.ListenAndServeTLS("", ""); err != nil && err != http.ErrServerClosed {
+			log.Printf("HTTPS server error: %v", err)
+		}
+	}()
 }

data/.gitignore

@@ -1 +1,6 @@
+accounts/
+certs/
 default/
+interactions/
+patterns.json
+settings.json

doc.go

@@ -1,8 +1,11 @@
-// Package soundtouch provides a comprehensive Go library and CLI tool for controlling Bose SoundTouch devices.
+// Package soundtouch provides a comprehensive Go library, CLI tool, and local service for controlling and emulating Bose SoundTouch devices.
 //
-// This library implements the complete Bose SoundTouch Web API, enabling programmatic control
+// This project implements the complete Bose SoundTouch Web API, enabling programmatic control
 // of SoundTouch speakers including playback control, volume management, source selection,
-// multiroom zone management, and real-time event monitoring via WebSocket connections.
+// multiroom zone management, and real-time event monitoring.
+//
+// It also provides a local service (`soundtouch-service`) that can emulate the Bose Cloud,
+// allowing for offline control and enhanced debugging through HTTP interaction recording.
 //
 // # Quick Start
 //
@@ -41,63 +44,20 @@
 //		if err != nil {
 //			log.Fatal(err)
 //		}
-//
-//		// Set volume
-//		err = client.SetVolume(50)
-//		if err != nil {
-//			log.Fatal(err)
-//		}
 //	}
 //
-// # Device Discovery
+// # SoundTouch Service
 //
-// Automatically discover SoundTouch devices on your network:
+// The `soundtouch-service` provides several advanced features:
 //
-//	import "github.com/gesellix/bose-soundtouch/pkg/discovery"
+//   - Bose Cloud Emulation: Allows speakers to work without an internet connection.
+//   - HTTP Interaction Recording: Captures all traffic as IntelliJ-compatible .http files.
+//   - Speaker Migration: Automated tools to redirect speakers to the local service.
+//   - Web Interface: A management dashboard for proxy settings and speaker setup.
 //
-//	// Discover devices using UPnP/SSDP
-//	service := discovery.NewService(5*time.Second)
-//	devices, err := service.DiscoverDevices(ctx)
-//	if err != nil {
-//		log.Fatal(err)
-//	}
+// Install the service:
 //
-//	for _, device := range devices {
-//		fmt.Printf("Found device: %s at %s\n", device.Name, device.Host)
-//	}
-//
-// # Real-time Events
-//
-// Monitor device state changes in real-time using WebSocket connections:
-//
-//	// Subscribe to device events
-//	events, err := client.SubscribeToEvents(ctx)
-//	if err != nil {
-//		log.Fatal(err)
-//	}
-//
-//	for event := range events {
-//		switch e := event.(type) {
-//		case *models.NowPlayingUpdated:
-//			fmt.Printf("Now playing: %s by %s\n", e.Track, e.Artist)
-//		case *models.VolumeUpdated:
-//			fmt.Printf("Volume changed to: %d\n", e.ActualVolume)
-//		}
-//	}
-//
-// # Multiroom Zone Management
-//
-// Create and manage multiroom zones:
-//
-//	// Create a zone with multiple speakers
-//	zone := &models.Zone{
-//		Master: "192.168.1.100",
-//		Members: []models.ZoneMember{
-//			{IPAddress: "192.168.1.101"},
-//			{IPAddress: "192.168.1.102"},
-//		},
-//	}
-//	err = client.SetZone(zone)
+//	go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
 //
 // # CLI Tool
 //
@@ -111,45 +71,33 @@
 //
 //	# Control a device
 //	soundtouch-cli --host 192.168.1.100 play start
-//	soundtouch-cli --host 192.168.1.100 volume set --level 50
-//	soundtouch-cli --host 192.168.1.100 source select --source SPOTIFY
 //
 // # Supported Features
 //
 //   - ✅ Device Information & Capabilities
-//   - ✅ Playback Control (Play/Pause/Stop/Next/Previous)
-//   - ✅ Volume, Bass, and Balance Control
-//   - ✅ Source Selection (Spotify, Bluetooth, AUX, etc.)
-//   - ✅ Preset Management
-//   - ✅ Clock/Time Management
-//   - ✅ Network Information
+//   - ✅ Playback, Volume, Bass, and Balance Control
+//   - ✅ Source Selection & Preset Management
 //   - ✅ Real-time WebSocket Events
 //   - ✅ Multiroom Zone Management
 //   - ✅ Device Discovery (UPnP/SSDP and mDNS)
-//   - ✅ Cross-platform Support (Windows, macOS, Linux)
+//   - ✅ Local Cloud Emulation (soundtouch-service)
+//   - ✅ HTTP Traffic Recording & Sanitization
+//   - ✅ Automated Speaker Migration & Revert
 //
 // # Package Structure
 //
 //   - client: HTTP client for SoundTouch Web API
 //   - discovery: Device discovery using UPnP/SSDP and mDNS
 //   - models: Data structures for API requests/responses
-//   - config: Configuration management
+//   - service: Core logic for the soundtouch-service (proxy, recording, setup)
 //   - cmd/soundtouch-cli: Command-line interface tool
-//
-// # Hardware Compatibility
-//
-// This library has been tested with real Bose SoundTouch hardware and supports
-// all SoundTouch-compatible devices including:
-//   - SoundTouch 10, 20, 30 series
-//   - SoundTouch Portable
-//   - Wave SoundTouch music system
-//   - And other SoundTouch-enabled Bose speakers
+//   - cmd/soundtouch-service: Local cloud emulation service
 //
 // # Implementation Notes
 //
-// This implementation is based on the official Bose SoundTouch Web API documentation
-// and provides 90% coverage of all available endpoints. It is an independent project
-// and is not affiliated with or endorsed by Bose Corporation.
+// This project is an independent effort to preserve the functionality of Bose SoundTouch
+// devices and provide enhanced debugging and control capabilities. It is not
+// affiliated with or endorsed by Bose Corporation.
 //
 // For detailed API documentation, examples, and advanced usage patterns, visit:
 // https://pkg.go.dev/github.com/gesellix/bose-soundtouch

docker-compose.yml

@@ -1,15 +1,41 @@
 services:
   soundtouch-service:
-    build: .
+    image: ghcr.io/gesellix/bose-soundtouch:latest
+    # build: .
     container_name: soundtouch-service
-    # network_mode: host # Linux only, required for discovery
+    # Linux only, required for discovery. Swarm requires host network at the task level.
+    # network_mode: host
     ports:
       - "8000:8000"
+      - "8443:8443"
     environment:
       - PORT=8000
+      - HTTPS_PORT=8443
       - DATA_DIR=/app/data
       - LOG_PROXY_BODY=false
       - REDACT_PROXY_LOGS=true
+      - RECORD_INTERACTIONS=true
+      - DISCOVERY_INTERVAL=5m
+      - SERVER_URL=http://${SOUNDTOUCH_HOSTNAME:-soundtouch.local}:8000
+      - HTTPS_SERVER_URL=https://${SOUNDTOUCH_HOSTNAME:-soundtouch.local}:8443
     volumes:
-      - ./data:/app/data
+      - soundtouch-data:/app/data
+      # Use host volume for local development if preferred:
+      # - ./data:/app/data
     restart: unless-stopped
+    deploy:
+      replicas: 1
+      restart_policy:
+        condition: on-failure
+      resources:
+        limits:
+          cpus: '0.50'
+          memory: 512M
+        reservations:
+          cpus: '0.25'
+          memory: 128M
+
+volumes:
+  soundtouch-data:
+    # Named volumes are preferred in Swarm. For multi-node persistence,
+    # consider using a volume driver like NFS or GlusterFS.

docs/CLAUDE.md

@@ -4,9 +4,9 @@
 
 This document contains important development guidelines for working on the Bose SoundTouch project. Please also read the following documentation:
 
-- **[PLAN.md](PLAN.md)** - Project planning and roadmap
+- **[PLAN.md](archive/PLAN.md)** - Project planning and roadmap
 - **[PROJECT-PATTERNS.md](PROJECT-PATTERNS.md)** - Project structure and design patterns
-- **[API-Endpoints-Overview.md](API-Endpoints-Overview.md)** - API endpoints overview
+- **[API-ENDPOINTS.md](reference/API-ENDPOINTS.md)** - API endpoints overview
 - **[SoundTouch Web API.pdf](2025.12.18%20SoundTouch%20Web%20API.pdf)** - Official API documentation
 
 ## Development Guidelines
@@ -95,4 +95,3 @@ When creating test data for API endpoints, prefer real device responses over hyp
 - **Documentation**: Completely in English for international accessibility
 - Conduct regular code reviews
 - Consider performance from the beginning
-

docs/CONTENT-SELECTION-IMPLEMENTATION.md

@@ -195,8 +195,9 @@ soundtouch-cli --host 192.168.1.100 source internet-radio \
 - [SoundTouch WebServices API Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
 - [LOCAL_INTERNET_RADIO - streamUrl format](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API#select-local_internet_radio---streamurl-format)
 - [LOCAL_MUSIC](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API#select-local_music)
-- [Content Selection Example](/examples/content-selection/)
-- [CLI Reference](/docs/CLI-REFERENCE.md)
+- [Content Selection Example](../examples/content-selection/README.md)
+- [CLI Reference](guides/CLI-REFERENCE.md)
+- [Content Selection Example (Direct)](../examples/content-selection/)
 
 ## ✅ Verification
 
@@ -208,4 +209,4 @@ This implementation has been verified to:
 5. ✅ Include complete documentation and examples
 6. ✅ Maintain backward compatibility
 
-**Status**: 🎉 **COMPLETE** - All requested content selection features are fully implemented and ready for use!
+**Status**: 🎉 **COMPLETE** - All requested content selection features are fully implemented and ready for use!

docs/DEVICE-LOGGING.md

@@ -0,0 +1,107 @@
+# Device Logging & Troubleshooting
+
+Accessing logs from SoundTouch devices is critical for debugging custom service integrations and understanding internal device behavior. This document outlines the methods for collecting logs, as discovered by the **SoundCork** and **ÜberBöse API** communities.
+
+## Log Types
+
+1.  **System Logs**: Internal OS logs (Linux-based) including `dmesg`, `syslog`, and process-specific logs.
+2.  **Traffic Logs**: Real-time HTTP/HTTPS requests sent by the device to cloud or local services.
+3.  **Proxy Logs**: Logs generated by the `soundtouch-service` when it acts as a man-in-the-middle.
+
+---
+
+## 1. Accessing System Logs (Requires Root)
+
+Most SoundTouch devices run a modified Linux distribution. Accessing these logs requires root SSH or Telnet access.
+
+### Enabling Root Access (Remote Services)
+
+Community research (SoundCork Issue #112) has identified a "backdoor" to enable developer services:
+
+1.  **USB Method**:
+    -   Format a USB stick to **FAT32**.
+    -   Create an empty file named `remote_services` (no extension) in the root of the USB stick.
+    -   Insert the stick into the SoundTouch device.
+    -   Reboot the device (power cycle).
+    -   On some models, you may need to hold **4** and **Volume -** on the device while powering on to force a USB check.
+2.  **TAP Command (Legacy)**:
+    -   On older firmware versions, you can connect to port 17000 via Telnet and issue the command: `remote_services on`.
+
+### Making Root Access Persistent
+Once you have logged in as `root` (usually no password or a well-known community password), you can make the access survive reboots without the USB stick:
+```bash
+touch /mnt/nv/remote_services
+/etc/init.d/sshd start
+```
+
+### Viewing Logs
+Once inside via SSH:
+-   **Kernel Logs**: `dmesg`
+-   **System Logs**: `cat /var/log/messages` or `tail -f /tmp/soundtouch.log` (paths vary by firmware).
+-   **Real-time Monitoring**: `logread -f`
+-   **Process List**: `ps w`
+
+#### Pro-Tip: Filtered Real-time Monitoring
+To focus on cloud service and preset interactions (Marge), use the following command on the device:
+```bash
+logread -f | grep -Ei '(marge|preset)'
+```
+This is particularly useful for debugging preset synchronization and service redirection issues.
+
+---
+
+## 2. Traffic Logging & Interception
+
+If you cannot or do not want to root the device, you can monitor its outbound traffic by redirecting it to a proxy.
+
+### Via `soundtouch-service`
+The `soundtouch-service` included in this repository includes a built-in proxy. When a device is migrated to use this service, all of its cloud-bound traffic is logged to the service console.
+
+**Key Traffic to Monitor**:
+-   `POST /v1/scmudc/{deviceId}`: Real-time telemetry events.
+-   `GET /marge/...`: Account and streaming configuration requests.
+-   `POST /streaming/support/power_on`: Boot-time diagnostics.
+
+### Via Packet Sniffing (Advanced)
+If you have a managed switch or a router capable of port mirroring, you can use **Wireshark** or `tcpdump` to capture traffic.
+-   **Filter**: `tcp port 80 or tcp port 443`
+-   **Target**: The IP address of your SoundTouch device.
+
+---
+
+## 3. Troubleshooting Common Issues
+
+### "IsItBose" Validation Failures
+If the device fails to connect to your custom service despite correct configuration, it may be failing the internal `IsItBose` regex check.
+-   **Evidence**: Look for SSL handshake failures or "Unauthorized" errors in your service logs.
+-   **Solution**: See the [Binary Patching section in DEVICE-REDIRECT-METHODS.md](analysis/DEVICE-REDIRECT-METHODS.md#method-3-binary-patching).
+
+### Disappearing Sources (TuneIn/Local Radio)
+If `TUNEIN` or `LOCAL_INTERNET_RADIO` sources disappear after a reboot in an offline environment.
+-   **Cause**: These sources are validated against the cloud only during the initial boot sequence.
+-   **Solution**: Ensure your emulated service is reachable and responding correctly to `/streaming/support/power_on` and `/streaming/sourceproviders` during the device's boot-up.
+
+---
+
+## 4. HTTP Protocol Quirks
+
+### ETag Case-Sensitivity
+Research in **SoundCork Issue #129** revealed a significant bug in the SoundTouch device firmware regarding HTTP `ETag` headers.
+
+- **The Issue**: The device firmware expects the `ETag` header to be exactly title-cased (`ETag`). Many modern web servers or frameworks (like FastAPI/Uvicorn) return headers in all lowercase (`etag`) per HTTP/2 or standard case-insensitive conventions.
+- **The Symptom**: If the server returns a lowercase `etag`, the device fails to recognize it. Consequently, the device will never send an `If-None-Match` header in subsequent requests, breaking preset synchronization and efficient caching.
+- **The Workaround**: If you are using a custom service, you may need to use a reverse proxy (like **Nginx**) or a middleware to force the header casing to `ETag`.
+
+**Example Nginx Fix**:
+```nginx
+proxy_hide_header etag;
+add_header ETag $upstream_http_etag;
+```
+
+---
+
+## References
+- [SoundCork Issue #112: Enabling Remote Services](https://github.com/deborahgu/soundcork/issues/112)
+- [SoundCork Issue #149: Debugging with Systemd/Gunicorn](https://github.com/deborahgu/soundcork/issues/149)
+- [ÜberBöse API: Telemetry Documentation](https://github.com/julius-d/ueberboese-api)
+- [SoundCork Issue #129: ETag Case-Sensitivity & Preset Sync](https://github.com/deborahgu/soundcork/issues/129)

docs/NAVIGATION-GUIDE.md

@@ -895,4 +895,4 @@ For additional help:
 
 ---
 
-*This guide covers the complete navigation and station management functionality. For preset management, see [PRESET-MANAGEMENT.md](PRESET-MANAGEMENT.md).*
+*This guide covers the complete navigation and station management functionality. For preset management, see [PRESET-MANAGEMENT.md](reference/PRESET-MANAGEMENT.md).*

docs/PRESET-QUICKSTART.md

@@ -332,14 +332,14 @@ soundtouch-cli --host 192.168.1.100 info
 
 ## Next Steps
 
-- 📖 [Complete CLI Reference](CLI-REFERENCE.md)
-- 🔧 [Full Implementation Guide](preset-store.md)
-- 📡 [WebSocket Events Documentation](websocket-events.md)
+- 📖 [Complete CLI Reference](guides/CLI-REFERENCE.md)
+- 🔧 [Full Implementation Guide](reference/PRESET-MANAGEMENT.md)
+- 📡 [WebSocket Events Documentation](reference/WEBSOCKET-EVENTS.md)
 - 💻 [Preset Management Example](../examples/preset-management/)
-- 📚 [API Endpoints Overview](API-Endpoints-Overview.md)
+- 📚 [API Endpoints Overview](reference/API-ENDPOINTS.md)
 
 ## Need Help?
 
 - 🐛 **Bug Reports**: [Create an issue](https://github.com/gesellix/bose-soundtouch/issues)
 - 💡 **Feature Requests**: [Start a discussion](https://github.com/gesellix/bose-soundtouch/discussions)
-- ❓ **Questions**: [Browse discussions](https://github.com/gesellix/bose-soundtouch/discussions)
+- ❓ **Questions**: [Browse discussions](https://github.com/gesellix/bose-soundtouch/discussions)

docs/README.md

@@ -0,0 +1,32 @@
+# Bose SoundTouch Toolkit Documentation
+
+Welcome to the documentation for the Bose SoundTouch Toolkit. This toolkit helps you keep your Bose SoundTouch speakers functional even after the Bose Cloud shutdown in May 2026.
+
+## 📖 Quick Links
+
+- [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
+- [Migration & Safety Guide](guides/MIGRATION-SAFETY.md)
+- [CLI Reference](guides/CLI-REFERENCE.md)
+- [Getting Started](guides/GETTING-STARTED.md)
+- [SoundTouch Service Guide](guides/SOUNDTOUCH-SERVICE.md)
+
+## 🗂 Documentation Structure
+
+### User Guides
+- [Initial Device Setup](guides/DEVICE-INITIAL-SETUP.md)
+- [HTTPS Setup](guides/HTTPS-SETUP.md)
+- [Deployment Guide](guides/DEPLOYMENT.md)
+- [Raspberry Pi Setup](guides/RASPBERRY-PI.md)
+- [Troubleshooting](guides/TROUBLESHOOTING.md)
+
+### Technical Reference
+- [API Endpoints](reference/API-ENDPOINTS.md)
+- [WebSocket Events](reference/WEBSOCKET-EVENTS.md)
+- [Zone Management](reference/ZONE-MANAGEMENT.md)
+- [Preset Management](reference/PRESET-MANAGEMENT.md)
+
+### Analysis & Research
+- [Upstream URLs](analysis/UPSTREAM-URLS.md)
+- [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md)
+
+For a complete list of all documents, see the [Summary](SUMMARY.md).

docs/SERVICE-AVAILABILITY-IMPLEMENTATION.md

@@ -23,7 +23,7 @@ This document summarizes the implementation of the `/serviceAvailability` endpoi
 ### Modified Files
 
 1. **`pkg/client/client.go`** - Added `GetServiceAvailability()` method
-2. **`docs/API-Endpoints-Overview.md`** - Updated implementation status
+2. **`docs/reference/API-ENDPOINTS.md`** - Updated implementation status
 3. **`docs/UNIMPLEMENTED-ENDPOINTS.md`** - Marked as implemented
 
 ## API Interface
@@ -263,4 +263,4 @@ BenchmarkGetServiceAvailability-8                         1000    1.2ms/op
 ✅ **Performance benchmarks established**  
 ✅ **Error handling verified**  
 
-The ServiceAvailability implementation is production-ready and provides a solid foundation for building user-friendly SoundTouch applications with better service discovery and user feedback capabilities.
+The ServiceAvailability implementation is production-ready and provides a solid foundation for building user-friendly SoundTouch applications with better service discovery and user feedback capabilities.

docs/SOUNDTOUCH-SERVICE-ANNOUNCEMENT.md

@@ -144,10 +144,10 @@ LOG_PROXY_BODY=true soundtouch-service
 
 ## 📚 Documentation
 
-- **[Complete Service Guide](SOUNDTOUCH-SERVICE.md)**: Comprehensive setup and configuration
-- **[API Reference](SOUNDTOUCH-SERVICE.md#api-reference)**: Full endpoint documentation
-- **[Migration Guide](SOUNDTOUCH-SERVICE.md#device-migration)**: Step-by-step device migration
-- **[Troubleshooting](SOUNDTOUCH-SERVICE.md#troubleshooting)**: Common issues and solutions
+- **[Complete Service Guide](guides/SOUNDTOUCH-SERVICE.md)**: Comprehensive setup and configuration
+- **[API Reference](guides/SOUNDTOUCH-SERVICE.md#api-reference)**: Full endpoint documentation
+- **[Migration Guide](guides/SOUNDTOUCH-SERVICE.md#device-migration)**: Step-by-step device migration
+- **[Troubleshooting](guides/SOUNDTOUCH-SERVICE.md#troubleshooting)**: Common issues and solutions
 
 ## 🤝 Contributing
 
@@ -172,9 +172,9 @@ The collaborative spirit of reverse engineering and documentation in the SoundTo
 ## 🔗 Links
 
 - **[Main Repository](https://github.com/gesellix/bose-soundtouch)**
-- **[Service Documentation](SOUNDTOUCH-SERVICE.md)**
-- **[CLI Documentation](CLI-REFERENCE.md)**
-- **[Getting Started Guide](GETTING-STARTED.md)**
+- **[Service Documentation](guides/SOUNDTOUCH-SERVICE.md)**
+- **[CLI Documentation](guides/CLI-REFERENCE.md)**
+- **[Getting Started Guide](guides/GETTING-STARTED.md)**
 - **[SoundCork Project](https://github.com/deborahgu/soundcork)**
 - **[ÜberBöse API](https://github.com/julius-d/ueberboese-api)**
 
@@ -187,4 +187,4 @@ go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
 soundtouch-service
 ```
 
-Open `http://localhost:8000` and start your journey to local SoundTouch control! 🎵
+Open `http://localhost:8000` and start your journey to local SoundTouch control! 🎵

docs/SUMMARY.md

@@ -0,0 +1,65 @@
+# Table of Contents
+
+* [Introduction](README.md)
+
+## User Guides
+* [Cloud Shutdown Survival Guide](guides/SURVIVAL-GUIDE.md)
+* [Migration & Safety Guide](guides/MIGRATION-SAFETY.md)
+* [CLI Reference](guides/CLI-REFERENCE.md)
+* [Getting Started](guides/GETTING-STARTED.md)
+* [SoundTouch Service](guides/SOUNDTOUCH-SERVICE.md)
+* [Initial Device Setup](guides/DEVICE-INITIAL-SETUP.md)
+* [HTTPS Setup](guides/HTTPS-SETUP.md)
+* [Deployment](guides/DEPLOYMENT.md)
+* [Raspberry Pi Guide](guides/RASPBERRY-PI.md)
+* [Troubleshooting](guides/TROUBLESHOOTING.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)
+* [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)
+* [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)
+* [Bass Controls](reference/BASS-CONTROLS.md)
+* [Key Controls](reference/KEY-CONTROLS.md)
+* [Feature Mapping](reference/FEATURE-MAPPING.md)
+
+## Analysis & Research
+* [API Coverage Analysis](analysis/API-COVERAGE.md)
+* [Supported URLs](analysis/SUPPORTED-URLS.md)
+* [Upstream URLs](analysis/UPSTREAM-URLS.md)
+* [Anonymization Summary](analysis/ANONYMIZATION-SUMMARY.md)
+* [Device Redirect Methods](analysis/DEVICE-REDIRECT-METHODS.md)
+* [Wiki API Comparison](analysis/WIKI-COMPARISON.md)
+
+## Appendix (Other Documents)
+* [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)

docs/UNDOCUMENTED-COMMUNITY-FEATURES.md

@@ -0,0 +1,46 @@
+# Undocumented Community Features & API Discoveries
+This document captures advanced API endpoints and device behaviors discovered by the SoundTouch community through reverse engineering projects like **SoundCork** and **ÜberBöse API**. These features are not documented in the official Bose SoundTouch Web API v1.0 but are crucial for full device emulation and offline operation.
+## Cloud Emulation (Marge/BMX) Discoveries
+While the local `/8090` API is well-documented, the cloud-side service emulation reveals deeper device integration points.
+### 1. Stereo Pairing & Cloud-Side Grouping
+SoundCork has pioneered the emulation of "Marge" group endpoints, which differ from the local `/getGroup` API. These are primarily used for persistent configurations like **Stereo Pairs** (e.g., two ST-10s).
+- **GET** `/marge/streaming/account/{account}/device/{device}/group`
+  Returns `<group/>` if ungrouped, or full group configuration for stereo pairs.
+- **POST** `/marge/streaming/account/{account}/group`
+  Creates a new group (returns a 7-digit group ID). Used for initial pairing.
+- **DELETE** `/marge/streaming/account/{account}/group/{group}`
+  Dissolves a group configuration.
+### 2. Device Analytics & Event Reporting
+Devices report real-time telemetry to the cloud. Intercepting these provides a window into device usage without polling.
+- **Endpoint**: `POST /v1/scmudc/{deviceId}`
+- **Function**: Submits event data including `play-state-changed`, `preset-pressed`, `power-pressed`, `source-state-changed`, and `art-changed` (Metadata updates). This endpoint was first extensively documented in the **ÜberBöse API** specification.
+### 3. Power-On Lifecycle
+When a SoundTouch device boots or "powers on" (distinct from waking from standby), it contacts specific support endpoints.
+- **Endpoint**: `POST /streaming/support/power_on`
+- **Behavior**: Reports device serial number, IP address, and diagnostic data.
+- **Critical Finding**: SoundTouch devices fetch `TUNEIN` and `LOCAL_INTERNET_RADIO` source availability from the cloud **ONLY at boot time**. If the cloud is unreachable during a hard reboot (power cycle), these sources will disappear from the device's `/sources` list and become unavailable, even if the local API is working. This behavior was analyzed and reported by the **ÜberBöse API** project (Issue #3).
+### 4. OAuth & Service Tokens
+Integration with music services (Spotify, Pandora, etc.) involves specific token management endpoints.
+- **Endpoint**: `POST /oauth/device/{deviceId}/music/musicprovider/{providerId}/token/{tokenType}`
+- **Usage**: Used to refresh or validate session tokens for cloud-based music providers.
+## Community-Driven Extensions
+The community is working on extending SoundTouch functionality beyond its original design.
+### 1. Radio-Browser.info Integration
+There is an active effort to add `radio-browser.info` as a native `sourceprovider`. This would allow devices to browse a massive directory of thousands of stations without relying on the TuneIn cloud service.
+- **Status**: Research phase in SoundCork (Issue #150).
+- **Implementation**: Requires adding a new source provider entry in the emulated `/streaming/sourceproviders` response.
+### 2. Stockholm Internal App Analysis
+Deep analysis of the Stockholm (device firmware) internal web application reveals a set of internal AJAX/XML calls used by the device's own control interface.
+- **Internal Domains**: `Marge` (XML-based) and `Gabbo` (App-send based).
+- **Reference**: See SoundCork Issue #128 for a comprehensive list of internal JS controllers and their functions.
+### 3. ETag Case-Sensitivity Bug
+The SoundTouch device firmware has a case-sensitivity bug regarding HTTP `ETag` headers.
+- **Discovery**: SoundCork Issue #129.
+- **Detail**: The device expects the `ETag` header to be exactly title-cased. If a server returns `etag` (lowercase), the device fails to use it for `If-None-Match` requests, breaking efficient preset synchronization.
+- **Solution**: Force title-casing of the header via a reverse proxy like Nginx or mitmproxy.
+## References
+- [SoundCork GitHub Repo](https://github.com/deborahgu/soundcork)
+- [ÜberBöse API Spec](https://github.com/julius-d/ueberboese-api)
+- [SoundTouch Plus Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
+- [IsItBose Regex Research](https://github.com/deborahgu/soundcork/issues/62#issuecomment-3610563908)
+- [SoundTouch Hook Repo](https://github.com/CodeFinder2/bose-soundtouch-hook)

docs/_config.yml

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

docs/analysis/DEVICE-REDIRECT-METHODS.md

@@ -0,0 +1,198 @@
+# 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.
+
+## Overview of Redirection Targets
+
+SoundTouch devices primarily communicate with the following domains:
+- `streaming.bose.com`: Marge (Account and streaming services)
+- `updates.bose.com`: Software updates
+- `stats.bose.com`: Telemetry and analytics
+- `bmx.bose.com`: Bose Media eXchange registry
+- `events.api.bosecm.com`: Stockholm app analytics
+- `bose-prod.apigee.net`: Apigee gateway (used by some services)
+- `worldwide.bose.com`: Software update metadata and secondary services
+
+---
+
+## Method 1: XML Configuration Modification (Recommended)
+
+The most robust and granular method involves modifying the device's private configuration file. This is the primary method used by **SoundCork**'s migration logic to redirect devices to a local service instance.
+
+### Technical Details
+- **File Path**: `/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml`
+- **Mechanism**: The device firmware reads this XML file at boot to determine service URLs.
+- **Fields to Modify**:
+  - `<margeServerUrl>`: Redirects account/streaming calls.
+  - `<statsServerUrl>`: Redirects telemetry.
+  - `<swUpdateUrl>`: Redirects update checks.
+  - `<bmxRegistryUrl>`: Redirects service discovery.
+
+### Implementation
+Requires SSH access to the device.
+```xml
+<SoundTouchSdkPrivateCfg>
+  <margeServerUrl>http://192.168.1.10:8000/marge</margeServerUrl>
+  <statsServerUrl>http://192.168.1.10:8000</statsServerUrl>
+  <swUpdateUrl>http://192.168.1.10:8000/updates/soundtouch</swUpdateUrl>
+  <bmxRegistryUrl>http://192.168.1.10:8000/bmx/registry/v1/services</bmxRegistryUrl>
+</SoundTouchSdkPrivateCfg>
+```
+
+### Pros & Cons
+| Pros | Cons |
+| :--- | :--- |
+| **Granular Control**: Redirect specific services while leaving others (e.g., updates) intact. | **Requires SSH**: Must have root/SSH access to the device. |
+| **Persistent**: Survives software updates (usually). | **Syntax Sensitive**: Errors in XML can cause boot issues or service failures. |
+| **Native**: Uses the device's built-in configuration mechanism. | |
+
+---
+
+## Method 2: `/etc/hosts` DNS Override
+
+This method uses the standard Linux hosts file to redirect traffic at the network level within the device. It is often used as a quick alternative in the **ÜberBöse API** community for global redirection.
+
+### Technical Details
+- **File Path**: `/etc/hosts`
+- **Mechanism**: Overrides DNS resolution for Bose domains to point to a local IP.
+- **Resolution Order**: SoundTouch devices use the standard Linux Name Service Switch (`/etc/nsswitch.conf`). The default configuration (`hosts: files dns`) ensures that `/etc/hosts` is consulted *before* any external DNS lookups. This makes the redirection highly reliable for all system processes, including `curl`, `BoseApp`, and `IoT`.
+
+### Implementation
+Requires SSH access. Add entries for the target domains:
+```text
+192.168.1.10  streaming.bose.com
+192.168.1.10  updates.bose.com
+192.168.1.10  stats.bose.com
+```
+
+### Pros & Cons
+| Pros | Cons |
+| :--- | :--- |
+| **Simple**: Easy to understand and implement. | **Requires SSH**: Must have root access. |
+| **Universal**: Affects all processes on the device attempting to reach those domains. | **HTTPS Issues**: Redirecting HTTPS domains to a local IP will cause SSL certificate errors unless the device is patched to skip verification or trust a custom CA. |
+| | **Brittle**: Some firmware versions may overwrite `/etc/hosts` on reboot. |
+
+---
+
+## Method 3: Binary Patching
+
+A low-level approach where the actual compiled binaries (e.g., `BoseApp`, `IoT`) are modified to change hardcoded URL patterns. Research into these patterns has been documented in both **SoundCork** (Issue #128) and **ÜberBöse API** research.
+
+### Technical Details
+- **Target Binaries**: `/opt/Bose/BoseApp`, `/opt/Bose/IoT`, `/opt/Bose/lib/libBmxAccountHsm.so`
+- **Mechanism**:
+    - **URL Replacement**: Using a hex editor to search for string patterns like `https://streaming.bose.com` and replacing them with a custom URL of the **exact same length**.
+    - **Regex Neutralization**: Some libraries (like `libBmxAccountHsm.so`) perform a validation check called `IsItBose` using a hardcoded regex. This regex prevents the device from connecting to non-Bose domains even if the URL is changed in the configuration.
+
+#### The `IsItBose` Regex Patch
+Research in the **SoundCork** community (Issue #62) identified a specific regex in `libBmxAccountHsm.so` that enforces Bose/Apigee domain usage:
+`^https:\/\/bose-[a-zA-Z0-9\.\_\-\$\%]\+\.apigee\.net\/`
+
+By patching this regex to be more "lax", the device can be made to accept any custom domain.
+
+**Example Patch**:
+Using `sed` to replace the strict regex with a broad match while preserving the original string length:
+```bash
+sed "s#\^https:....bose.\+apigee..net..#http[aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]*#g" \
+< libBmxAccountHsm.so.orig > libBmxAccountHsm.so.patched
+```
+
+### Implementation
+1. Copy the target binary or library from the device to a PC.
+2. Use a hex editor or `sed` to locate and patch the URL strings or regex patterns.
+3. Copy the patched file back to the device.
+4. Restore execution permissions and reboot.
+
+### Pros & Cons
+| Pros | Cons |
+| :--- | :--- |
+| **Bypass Config**: Works even if the firmware ignores XML settings. | **High Risk**: Modifying binaries can lead to permanent bricks or boot loops. |
+| **Hardcoded Redirects**: Can catch URLs that aren't exposed in configuration files. | **Length Constraint**: Custom URLs must fit within the space of the original strings. |
+| | **Firmware Specific**: Patches must be reapplied after every software update. |
+| | **Complexity**: Requires understanding of binary structures and potential checksums. |
+
+---
+
+## Comparison & Usage Strategy
+
+### Summary Table
+
+| Method | Primary Use Case | Ease | Safety | Persistence | Granularity |
+| :--- | :--- | :---: | :---: | :---: | :---: |
+| **XML Config** | Logical service redirection | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **`/etc/hosts`** | Quick global DNS override | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐ | ⭐⭐ |
+| **Binary Patch** | Bypassing hardcoded checks | ⭐ | ⭐ | ⭐ | ⭐⭐⭐ |
+
+---
+
+## Combining Methods: When is one not enough?
+
+A common question is whether these methods can be used in isolation or if they must be combined. The answer depends on your specific firmware version and the target service.
+
+### Scenario A: XML Config Only (The Ideal Case)
+If your firmware does not strictly enforce the `IsItBose` check for the specific URLs you are changing, **Method 1 (XML)** is sufficient. This is the cleanest approach and is used by the `soundtouch-service` migration tool.
+
+### Scenario B: XML Config + Binary Patching (The "Locked" Case)
+On some newer firmware versions, even if you change the `<margeServerUrl>` in the XML to `http://192.168.1.10`, the internal library (`libBmxAccountHsm.so`) will validate the string against the hardcoded Bose regex.
+*   **Symptom**: The device ignores the XML setting or fails to connect despite the correct URL being present.
+*   **Solution**: You **must** apply the **Binary Patch (Method 3)** to neutralize the `IsItBose` check *in addition* to the XML change.
+
+### Scenario C: `/etc/hosts` + Custom CA (The "Clean Deep Redirect")
+If you use `/etc/hosts` to point `streaming.bose.com` to a local IP and want to avoid binary patching.
+*   **Requirement 1**: Your local server must handle HTTPS (port 443).
+*   **Requirement 2**: You must inject your Root CA into the device's trust store.
+*   **Automated Tool**: The `soundtouch-service` now supports this via the `/setup/migrate/{deviceIP}?method=hosts` endpoint.
+*   **CA Download**: You can download the auto-generated Root CA from `http://<your-server>:8000/setup/ca.crt`.
+*   **Benefit**: Maintains system integrity (no binary changes) and full end-to-end encryption.
+
+### Scenario D: `/etc/hosts` + Binary Patching (The "Legacy Deep Redirect")
+If you cannot or do not want to manage certificates, but still use `/etc/hosts` for DNS redirection.
+*   **Requirement 1**: Your local server must handle HTTPS (port 443).
+*   **Requirement 2**: Since the certificate will be invalid (mismatched domain/CA), you must patch the binary to **skip SSL verification** (see [Option 2](#option-2-ssl-verification-bypass) below).
+*   **Risk**: Less secure and higher risk of bricking due to binary modification.
+
+### Scenario E: The Triple-Threat (Total Control)
+For developers creating a completely isolated "dark" environment (no internet at all):
+1.  **XML**: Point all URLs to local services.
+2.  **Binary Patch**: Neutralize `IsItBose` to allow non-Bose domains/IPs.
+3.  **`/etc/hosts`**: Redirect hardcoded domains that aren't exposed in the XML (like analytics or NTP) to prevent leakage to the real Bose cloud.
+4.  **Process Instrumentation**: Use [SoundTouch Hook](https://github.com/CodeFinder2/bose-soundtouch-hook) to monitor and override internal behavior in real-time. This is particularly useful for handling unknown hostnames or deep-hooking into service discovery logic that might bypass standard DNS lookups.
+
+---
+
+## Handling HTTPS & SSL Certificates
+
+When redirecting HTTPS traffic to a custom service, SoundTouch devices will fail the SSL handshake because they do not trust your local server's certificate.
+
+### Option 1: Custom CA Certificate (Recommended)
+
+As suggested by community members, you can configure the device to trust your own Root CA. This allows for secure HTTPS communication without patching binaries.
+
+**Technical Steps**:
+1.  **Generate a Root CA** and issue a certificate for the target domain (e.g., `streaming.bose.com`).
+2.  **SSH into the device** and copy your `rootCA.crt` to `/usr/share/ca-certificates/custom/`.
+3.  **Update the Trust Store**:
+    - **Method A (Append to Bundle)**: `cat /usr/share/ca-certificates/custom/rootCA.crt >> /etc/pki/tls/certs/ca-bundle.crt`
+    - **Method B (Symlinks)**: Add the certificate to `/etc/ssl/certs/` and create a hash symlink using `c_rehash` (if available) or manual mapping.
+
+**Pros & Cons**:
+| Pros | Cons |
+| :--- | :--- |
+| **Secure**: Maintains end-to-end encryption. | **Requires SSH**: Must have root access to modify the trust store. |
+| **Clean**: No binary patching required for SSL bypass. | **Update Risk**: Firmware updates might overwrite the `ca-bundle.crt`. |
+
+### Option 2: SSL Verification Bypass
+
+If you cannot or do not want to manage certificates, you can patch the binary to skip certificate verification.
+
+**Target**: `libBmxAccountHsm.so` or `BoseApp`
+**Mechanism**: Locating the SSL verification function (often in the internal curl-based or openssl-based logic) and forcing it to return "Success" regardless of the certificate status.
+
+---
+
+## Recommendation
+
+1.  **Start with Method 1 (XML Modification)**. It is the least invasive and most likely to work across different models.
+2.  **Verify connectivity**. If the device refuses to connect to your custom endpoint, check logs for "IsItBose" or validation failures.
+3.  **Apply Method 3 (Binary Patching)** only if Method 1 is being actively blocked by the firmware's validation logic.
+4.  **Avoid Method 2 (`/etc/hosts`)** unless you are prepared to handle SSL certificate complexities or are performing quick temporary tests.

docs/analysis/UPSTREAM-URLS.md

@@ -0,0 +1,84 @@
+# Upstream URLs & Domains Analysis
+
+This document provides a comprehensive overview of the upstream Bose cloud services and domains that SoundTouch devices communicate with. These details were gathered from firmware analysis of ST10/ST20 devices, binary string extraction, and community research from the **SoundCork** project (Issue #128).
+
+## Core Service Domains
+
+SoundTouch devices use a set of primary domains for their operation. These are often configurable via the `SoundTouchSdkPrivateCfg.xml` file.
+
+| Service | Primary Domain | Purpose |
+| :--- | :--- | :--- |
+| **Marge** | `streaming.bose.com` | Account management, streaming source providers, and preset sync. |
+| **BMX Registry** | `content.api.bose.io` | Bose Media eXchange service discovery and registry. |
+| **Stats/Analytics** | `events.api.bosecm.com` | Telemetry, device events, and usage statistics. |
+| **Software Update** | `worldwide.bose.com` | Firmware update checks and downloads (path: `/updates/soundtouch`). |
+| **Voice/Alexa** | `voice.api.bose.io` | Token management for Amazon Alexa integration. |
+
+## Internal & Development Domains
+
+Analysis of device binaries (`BoseApp`, `IoT`) and community findings revealed several internal, integration, and development domains used by Bose.
+
+### Marge & Auth Proxies
+- `bose-test.apigee.net/margeproxy` (Integration/Test proxy)
+- `bose-test.apigee.net/margeproxyefe`
+- `streamingstg.bose.com` (Staging)
+- `streamingintoauth.bose.com` (Internal Auth)
+- `streamingefeintoauth.bose.com` (Internal EFE Auth)
+- `streamingefeint.bose.com`
+
+### BMX & Content Registry
+- `test.content.api.bose.io`
+- `content.api.bose.io/bmx/registry/v1/services`
+- `test.content.api.bose.io/bmx/int-registry/v1/services`
+- `test.content.api.bose.io/bmx/efe-registry/v1/services`
+
+### Stats & Analytics
+- `eventsdev.api.bosecm.com`
+- `eventsefe.api.bosecm.com`
+- `eventsdev.bosecm.com`
+
+### Software Updates
+- `worldwide.bose.com/updates/soundtouch-int`
+- `worldwide.bose.com/updates/soundtouch-efe`
+
+## Third-Party Services
+
+Devices also communicate directly with third-party providers for specific features.
+
+- **Pandora**: 
+    - `device-tuner.pandora.com`
+    - `device-tuner-beta.savagebeast.com`
+- **Amazon AVS**:
+    - `avs.na.amazonalexa.com`
+
+## Hardcoded Validation (IsItBose)
+
+As documented in [DEVICE-REDIRECT-METHODS.md](DEVICE-REDIRECT-METHODS.md#method-3-binary-patching), the `libBmxAccountHsm.so` library contains a hardcoded regex to validate these URLs:
+
+`^https:\/\/bose-[a-zA-Z0-9\.\_\-\$\%]\+\.apigee\.net\/`
+
+This regex ensures that certain critical services must reside on the `apigee.net` domain under a `bose-` prefix, unless patched.
+
+## Configuration File References
+
+On-device, these URLs are primarily managed in the following files:
+
+1.  **`/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml`**:
+    *   `<margeServerUrl>`
+    *   `<statsServerUrl>`
+    *   `<swUpdateUrl>`
+    *   `<bmxRegistryUrl>`
+2.  **`/opt/Bose/etc/Voice.xml`**:
+    *   `<TPDATokenUrl>` (Points to `voice.api.bose.io`)
+3.  **`/opt/Bose/etc/HandCraftedWebServer-SoundTouch.xml`**:
+    *   Contains internal local API mapping.
+
+## Conclusion for Offline Operation
+
+To achieve full offline operation or redirection to a custom service (like `soundtouch-service`), all of the above domains must either be redirected via DNS (`/etc/hosts`) or updated in the device's XML configuration files. For domains not exposed in XML, binary patching or DNS-level redirection is the only option.
+
+---
+
+## References
+- [SoundCork Issue #128: Endpoint and URL Listing](https://github.com/deborahgu/soundcork/issues/128#issuecomment-3892933337)
+- [Bose SoundTouch Web API v1.0 Specification](https://assets.bosecreative.com/m/496577402d128874/original/SoundTouch-Web-API.pdf)

docs/archive/PLAN.md

@@ -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](../PROJECT-PATTERNS.md) - Detailed pattern documentation

docs/archive/STATUS.md

@@ -206,14 +206,14 @@ This project implements a comprehensive Go client library and CLI tool for Bose
 
 ### ✅ Complete Documentation
 - `README.md` - Project overview and usage examples ✅
-- `docs/API-Endpoints-Overview.md` - API reference with status ✅
-- `docs/KEY-CONTROLS.md` - Media control implementation ✅
-- `docs/VOLUME-CONTROLS.md` - Volume management guide ✅
-- `docs/PRESET-MANAGEMENT.md` - Preset analysis and limitations ✅
+- `docs/reference/API-ENDPOINTS.md` - API reference with status ✅
+- `docs/reference/KEY-CONTROLS.md` - Media control implementation ✅
+- `docs/guides/VOLUME-CONTROLS.md` - Volume management guide ✅
+- `docs/reference/PRESET-MANAGEMENT.md` - Preset analysis and limitations ✅
 - `docs/HOST-PORT-PARSING.md` - Enhanced CLI feature ✅
-- `docs/PLAN.md` - Development roadmap (updated) ✅
+- `docs/archive/PLAN.md` - Development roadmap (updated) ✅
 - `docs/PROJECT-PATTERNS.md` - Development guidelines ✅
-- `SPEAKER_ENDPOINT.md` - Complete speaker notification documentation ✅
+- `docs/reference/SPEAKER-ENDPOINT.md` - Complete speaker notification documentation ✅
 
 ### 📝 Documentation Notes
 - All docs are synchronized with current implementation

docs/guides/CLI-REFERENCE.md

@@ -1248,6 +1248,6 @@ SOUNDTOUCH_DISCOVERY_TIMEOUT=10s
 ## See Also
 
 - [Getting Started Guide](GETTING-STARTED.md) - Basic setup and usage
-- [WebSocket Events](websocket-events.md) - Real-time monitoring
-- [Zone Management](zone-management.md) - Multi-room setup
-- [API Endpoints](API-Endpoints-Overview.md) - Complete API reference
+- [WebSocket Events](../reference/WEBSOCKET-EVENTS.md) - Real-time monitoring
+- [Zone Management](../reference/ZONE-MANAGEMENT.md) - Multi-room setup
+- [API Endpoints](../reference/API-ENDPOINTS.md) - Complete API reference

docs/guides/DEPLOYMENT.md

@@ -13,6 +13,10 @@ This guide covers everything you need to know to deploy robust, scalable SoundTo
 - [Performance Optimization](#performance-optimization)
 - [Error Handling Recovery](#error-handling-recovery)
 - [Deployment Strategies](#deployment-strategies)
+    - [Docker Deployment](#docker-deployment)
+    - [Kubernetes Deployment](#kubernetes-deployment)
+    - [Systemd Service](#systemd-service)
+    - [Raspberry Pi Installer](#raspberry-pi-installer)
 - [Maintenance Operations](#maintenance-operations)
 
 ---
@@ -926,39 +930,49 @@ data:
   device_hosts: "192.168.1.100,192.168.1.101,192.168.1.102"
 ```
 
-### Systemd Service
+#### Systemd Service
+
+A standard systemd unit for manual installation. This example assumes the binary is at `/usr/local/bin/soundtouch-service` and data is stored in `/var/lib/soundtouch-service`.
 
 ```ini
-# /etc/systemd/system/soundtouch.service
+# /etc/systemd/system/soundtouch-service.service
 [Unit]
-Description=SoundTouch Control Service
-After=network.target
-Wants=network.target
+Description=Bose SoundTouch Service
+Wants=network-online.target
+After=network-online.target
 
 [Service]
 Type=simple
 User=soundtouch
 Group=soundtouch
-WorkingDirectory=/opt/soundtouch
-ExecStart=/opt/soundtouch/bin/soundtouch-app
-ExecReload=/bin/kill -HUP $MAINPID
-Restart=always
-RestartSec=5
-Environment=DEVICE_HOSTS=192.168.1.100,192.168.1.101
-Environment=LOG_LEVEL=info
-Environment=CONFIG_FILE=/opt/soundtouch/config/production.yaml
+WorkingDirectory=/var/lib/soundtouch-service
+ExecStart=/usr/local/bin/soundtouch-service
+Environment=PORT=80
+Environment=SERVER_URL=http://soundtouch.local
 
-# Security settings
-NoNewPrivileges=true
-ProtectSystem=strict
-ProtectHome=true
-ReadWritePaths=/opt/soundtouch/logs
+# Allow binding to privileged ports (80/443) without running as root
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE
+
+Restart=on-failure
+RestartSec=5
+
+# Security hardening
 PrivateTmp=true
+ProtectSystem=full
+ProtectHome=true
+ReadWritePaths=/var/lib/soundtouch-service
 
 [Install]
 WantedBy=multi-user.target
 ```
 
+#### Raspberry Pi Installer
+
+For users deploying on a Raspberry Pi, we provide a specialized automated installer that handles everything from architecture detection to security hardening.
+
+See the [Raspberry Pi Installation Guide](RASPBERRY-PI.md) for step-by-step instructions.
+
 ---
 
 ## Maintenance Operations
@@ -1071,4 +1085,4 @@ func init() {
     
     // Set GC target percentage
     if os.Getenv("GOGC") == "" {
-        debug.SetGCPerc
+        debug.SetGCPerc

docs/guides/DEVICE-INITIAL-SETUP.md

@@ -0,0 +1,80 @@
+# SoundTouch Device Initial Setup Variants
+
+Based on community research from the **SoundCork** and **ÜberBöse API** projects, as well as analysis of the Stockholm firmware (`firmware/Stockholm/.../setup/`), this document outlines the methods used for the "out-of-the-box" setup of SoundTouch devices.
+
+## Setup Overview
+
+Initial setup is the process of connecting a new or factory-reset device to a local Wi-Fi network and a Bose (or custom) account. This is distinct from the "Migration" process (handled by `soundtouch-service`), which redirects an already-configured device to a new server.
+
+---
+
+## 1. Bluetooth Low Energy (BLE) Setup
+Used by most modern SoundTouch devices (ST-10, ST-20/30 Series III, SoundTouch 300).
+
+- **Mechanism**: The SoundTouch app communicates with the device over BLE to exchange Wi-Fi credentials.
+- **Protocol**: Internal research refers to this as the **Gabbo** protocol (see `gabbo_setup_bco.js` in firmware).
+- **Process**:
+  1. Put the device in setup mode (usually by holding the '2' and '-' buttons).
+  2. The app discovers the device via BLE.
+  3. The app sends the Wi-Fi SSID and Password to the device.
+  4. The device connects to Wi-Fi and disables BLE setup.
+
+---
+
+## 2. Access Point (AP) Mode / Web Setup
+The classic "failover" or "alternate" setup method.
+
+- **Mechanism**: The device creates its own Wi-Fi network (SSID: `Bose SoundTouch ...` or `Bose Home Speaker ...`).
+- **IP Address**: Typically `192.168.1.1` or `10.0.0.1` (device-side).
+- **Web Interface**: The device hosts a web server on port 80.
+- **Process**:
+  1. Connect a PC/Phone to the device's Wi-Fi.
+  2. Open a browser to `http://192.168.1.1`.
+  3. The device serves `setup.html`, which redirects to a setup wizard (`setup/index.html`).
+  4. Use the `gabbo_wifi` form to select a network and enter credentials.
+
+---
+
+## 3. Wireless Accessory Configuration (WAC)
+Specific to Apple iOS devices.
+
+- **Mechanism**: Uses Apple's MFi/WAC protocol to pass Wi-Fi settings from an iPhone/iPad directly to the device without manual password entry.
+- **Status**: Detected automatically by iOS when a new SoundTouch device is in setup mode.
+
+---
+
+## 4. USB Setup (Legacy)
+Primarily used for older SoundTouch Series I and II devices or as a last resort.
+
+- **Mechanism**: Physical connection via Micro-USB to a computer running the SoundTouch Setup application.
+- **Process**:
+  1. Connect USB cable.
+  2. The desktop app communicates via a proprietary HID or Serial-over-USB protocol.
+  3. The app pushes Wi-Fi credentials.
+  4. References to this exist in the firmware as `lost_USB_connection` and `connect_device` (see `setup_wizard.xml`).
+
+---
+
+## Technical Details: The "Gabbo" Protocol
+The Stockholm firmware contains references to a communication layer called **Gabbo**.
+- **File**: `setup/js/gabbo_setup_bco.js`
+- **Function**: Handles the state machine for Wi-Fi connection, account pairing, and error handling during setup.
+- **Relationship**: It appears to be an internal wrapper for the messages sent between the setup client (App or Browser) and the device firmware.
+
+## Redirection during Setup
+While the `soundtouch-service` focuses on migrating existing devices, a truly "clean" setup to a custom service would require:
+1. Intercepting the initial account pairing request.
+2. Providing a mock "Marge" service that accepts any credentials.
+3. Patching the `SoundTouchSdkPrivateCfg.xml` during or immediately after the Wi-Fi connection phase.
+
+---
+
+## Comparison: Initial Setup vs. Migration
+
+| Feature | Initial Setup | Migration (soundtouch-service) |
+| :--- | :--- | :--- |
+| **Connectivity** | BLE, AP Mode, USB, WAC | Ethernet/Wi-Fi (existing) |
+| **Credentials** | Required (SSID/Pass) | Not required (uses existing) |
+| **Access** | Web UI / App protocol | SSH (root) |
+| **Primary File** | `setup/index.html` | `SoundTouchSdkPrivateCfg.xml` |
+| **Use Case** | Out-of-the-box / Reset | Redirecting active devices |

docs/guides/HTTPS-SETUP.md

@@ -0,0 +1,102 @@
+# HTTPS Setup & Custom CA Certificate
+
+To use the `/etc/hosts` redirection method safely, SoundTouch devices must communicate over HTTPS. This requires the device to trust the AfterTouch Root CA certificate used by the local service.
+
+## 1. Automated Migration (Hosts Method)
+
+The `soundtouch-service` can automatically configure a device to use the `/etc/hosts` method:
+
+```bash
+curl -X POST "http://localhost:8000/setup/migrate/{deviceIP}?method=hosts"
+```
+
+This command will:
+1.  Connect to the device via SSH.
+2.  Update `/etc/hosts` to point Bose domains to the service IP.
+3.  Inject the auto-generated AfterTouch Root CA into the device's trust store (`/etc/pki/tls/certs/ca-bundle.crt`).
+4.  Reboot the device.
+
+## 2. Managing the Root CA
+
+The AfterTouch service automatically generates a Root CA when it first starts.
+
+- **CA Certificate**: `data/certs/ca.crt`
+- **CA Private Key**: `data/certs/ca.key`
+
+### Downloading the CA Certificate
+You can download the CA certificate for manual installation on other devices (like your phone or PC) from:
+`http://<server-ip>:8000/setup/ca.crt`
+
+### 3. Built-in HTTPS Support
+
+The `soundtouch-service` now includes a built-in HTTPS listener. This simplifies the `/etc/hosts` redirection method by automatically presenting the correct certificates for Bose domains.
+
+- **HTTPS Port**: Configurable via `HTTPS_PORT` environment variable (defaults to `8443`).
+- **HTTPS Server URL**: Configurable via `HTTPS_SERVER_URL` (e.g., `https://mysoundtouch.local:8443`). If not set, the service attempts to guess it using the system hostname.
+- **Domain Coverage**: Automatically presents a certificate for `streaming.bose.com`, `updates.bose.com`, `stats.bose.com`, `bmx.bose.com`, and `content.api.bose.io`.
+- **Automatic Setup**: On first start, it generates a server certificate signed by your AfterTouch local Root CA.
+
+#### TLS Security
+
+The built-in HTTPS listener is configured to use modern and secure TLS settings while maintaining compatibility with SoundTouch devices (which support up to TLS 1.2 with OpenSSL 1.0.2).
+
+- **Minimum TLS Version**: TLS 1.2
+- **Preferred Cipher Suites**:
+  - `ECDHE-RSA-AES128-GCM-SHA256`
+  - `ECDHE-RSA-AES256-GCM-SHA384`
+  - `ECDHE-RSA-CHACHA20-POLY1305`
+  - `RSA-AES128-GCM-SHA256` (Legacy support)
+  - `RSA-AES256-GCM-SHA384` (Legacy support)
+
+#### Binding to Port 443
+SoundTouch devices expect HTTPS on the default port 443. Since binding to port 443 usually requires root privileges, you have two options:
+
+1.  **Port Forwarding (Recommended)**: Run the service on a high port (e.g., 8443) and use `iptables` or your firewall to forward traffic from 443 to 8443.
+2.  **Capabilities**: Grant the binary permission to bind to low ports: `sudo setcap 'cap_net_bind_service=+ep' ./soundtouch-service`.
+3.  **Reverse Proxy**: Use Nginx or Caddy as described below.
+
+### 4. Reverse Proxy (Optional)
+
+1.  **Generate a certificate** for the Bose domains signed by your Root CA.
+2.  **Configure Nginx** to use this certificate and proxy requests to `soundtouch-service`.
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name streaming.bose.com bmx.bose.com stats.bose.com updates.bose.com;
+
+    ssl_certificate /path/to/generated-cert.crt;
+    ssl_certificate_key /path/to/generated-cert.key;
+
+    # Secure TLS configuration (matches soundtouch-service defaults)
+    ssl_protocols TLSv1.2;
+    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:AES128-GCM-SHA256:AES256-GCM-SHA384';
+
+    location / {
+        proxy_pass http://localhost:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+## 5. Manual CA Injection (Legacy/Manual)
+
+If you prefer to inject the CA certificate manually:
+
+1.  Copy `ca.crt` to the device:
+    ```bash
+    scp data/certs/ca.crt root@{deviceIP}:/tmp/
+    ```
+2.  Append it to the trust store on the device:
+    ```bash
+    ssh root@{deviceIP} "(rw || mount -o remount,rw /) && cat /tmp/ca.crt >> /etc/pki/tls/certs/ca-bundle.crt"
+    ```
+
+    ## 6. Verifying Connectivity
+
+    You can verify that your device can correctly reach the `soundtouch-service` over HTTPS using the management web UI.
+
+    In the **Migration Summary** for a device, you will find an **HTTPS Connection Test** section:
+    - **Test with Explicit CA.crt**: Uploads a temporary copy of the Root CA to the device and uses `curl --cacert` to verify the connection. Use this to verify your HTTPS setup *before* modifying the device's shared trust store.
+    - **Test with Shared Trust Store**: Uses the device's default trust store. Use this to verify that your CA injection was successful and the device now natively trusts your local server.

docs/guides/MIGRATION-SAFETY.md

@@ -0,0 +1,41 @@
+### Professional Migration & Safety Guide
+
+Starting a migration on real hardware requires a "Safety First" approach. This guide outlines the safety features implemented in the `soundtouch-service` and provides a checklist for a successful migration.
+
+#### 🛠 Technical Safety Enhancements
+
+The following features are built into the `soundtouch-service` to ensure stability and easy rollbacks:
+
+1.  **Off-Device Backups**: Before any migration starts, the service automatically fetches the original `SoundTouchSdkPrivateCfg.xml` and `/etc/hosts` from your speaker and saves them locally in your `data/default/devices/<SERIAL>/` directory. This ensures you have a recovery path even if the speaker's filesystem becomes inaccessible.
+2.  **Pre-flight Write Verification**: The migration process includes a mandatory check for SSH write access (`rw`) before attempting any modifications. This prevents "half-baked" migrations where a script might fail halfway through due to a read-only filesystem.
+3.  **Automatic Safety on Sync**: Running a "Sync" in the Web UI or CLI automatically triggers an off-device backup, making it the perfect first step for any new device discovery.
+
+#### 📋 Professional Migration Checklist
+
+Before you proceed with the actual migration, follow these steps:
+
+1.  **Enable SSH Access (Prerequisite)**: This toolkit requires SSH access to your speakers, which is not enabled by default. 
+    - Create an empty file named `remote_services` on a USB stick.
+    - Insert the USB stick into the SoundTouch speaker's **SERVICE** port.
+    - Reboot the speaker (unplug and replug).
+    - The speaker will now allow SSH connections as `root` with no password.
+    - **Verify**: Run `ssh -oHostKeyAlgorithms=+ssh-rsa root@<SPEAKER-IP>` to confirm access. (Note: older devices may require enabling `ssh-rsa` support).
+2.  **Network Isolation (Optional but Recommended)**: Ensure the device is on a stable wired connection if possible, or a dedicated 2.4GHz SSID to avoid drops during SSH operations.
+3.  **Initial Discovery & Sync**: 
+    - Run `soundtouch-cli discover devices` to ensure connectivity.
+    - Use the Web UI or CLI to "Sync" the device. This will automatically backup your presets and system configuration files to your local server.
+4.  **Validate SSH Access**: Confirm the device responds to SSH without a password. 
+    - In the Web UI **Migration** tab, select your speaker and verify that the "SSH Connection" status shows ✅ Success.
+    - This toolkit automatically handles the necessary SSH parameters (ciphers and key exchanges) required by older Bose firmware.
+5.  **Use XML Migration First**: The `XML` migration method is less invasive than the `Hosts` method. It only changes the application config and doesn't require modifying the system's DNS/CA trust store if you don't need full HTTPS interception initially.
+6.  **Monitor Logs**: Run the `soundtouch-service` with `DEBUG` or `INFO` logging to see the step-by-step progress of the migration.
+
+#### 🔄 Rollback Strategy
+
+If something goes wrong or you want to return to the original Bose cloud services:
+
+*   **Standard Revert**: Use the "Revert Migration" button in the Web UI or the corresponding CLI command. This restores the `.original` files created on the device.
+*   **Emergency Recovery**: If the device is unreachable via the UI but SSH still works, you can manually restore the files from your local `data/` directory using `scp` or the backups created on-device (`.original`).
+*   **Factory Reset**: As a last resort, Bose SoundTouch devices can be factory reset (usually by holding '1' and 'Volume Down' while plugging in). This will wipe all settings and return the device to the stock firmware configuration (the firmware itself remains at the current version, but configurations are reset).
+
+By using the built-in off-device backups and pre-flight checks, the risk of "bricking" or losing configuration during the transition is significantly reduced.

docs/guides/RASPBERRY-PI.md

@@ -0,0 +1,69 @@
+# Raspberry Pi Installation Guide
+
+This guide explains how to install the `soundtouch-service` as a persistent systemd service on a Raspberry Pi (tested on Raspberry Pi Zero 2W, 3, and 4).
+
+## Automated Installer
+
+We provide a specialized installer script located in the `scripts/raspberry-pi/` directory of the repository.
+
+### Features
+*   **Automatic start on boot**: Installs a systemd unit.
+*   **Non-root operation**: Uses `AmbientCapabilities` to bind to ports 80/443 without root privileges.
+*   **Arch Detection**: Automatically selects the correct binary for `armv7`, `arm64`, or `amd64`.
+*   **Easy Updates**: Re-running the script updates the binary to the latest version.
+
+### Installation Steps
+
+1.  **Download the installer**:
+    ```bash
+    curl -fsSL -o install.sh https://raw.githubusercontent.com/gesellix/bose-soundtouch/main/scripts/raspberry-pi/install.sh
+    ```
+
+2.  **Run with sudo**:
+    ```bash
+    sudo bash install.sh
+    ```
+
+### Overriding Defaults
+
+You can customize the installation using environment variables:
+
+```bash
+sudo \
+  VERSION=v0.17.0 \
+  HOSTNAME_FQDN=soundtouch.local \
+  HTTP_PORT=80 \
+  HTTPS_PORT=443 \
+  bash install.sh
+```
+
+### Updating the Service
+
+To update the service to a specific version, run the installer with the version as an argument:
+
+```bash
+sudo bash install.sh v0.18.1
+```
+
+The installer will automatically fetch the latest version of itself for that release and then update the service binary and restart it.
+
+## Management
+
+Once installed, use standard `systemctl` commands to manage the service:
+
+```bash
+# Check status
+systemctl status soundtouch-service
+
+# Follow logs
+journalctl -u soundtouch-service -f
+
+# Restart
+sudo systemctl restart soundtouch-service
+```
+
+## Configuration
+
+Configuration is stored in `/etc/soundtouch-service/soundtouch-service.env`. Note that settings saved via the Web UI (in `settings.json`) will take precedence over these environment variables once the service is running.
+
+For more details, see the [scripts/raspberry-pi/README.md](../../scripts/raspberry-pi/README.md) in the repository.

docs/guides/SOUNDTOUCH-SERVICE.md

@@ -11,6 +11,7 @@ The service provides:
 - **📊 Traffic Proxying**: Inspect and log all device communications for debugging
 - **🌐 Web Management UI**: Browser-based interface for device management
 - **💾 Persistent Data**: Store device configurations, presets, and usage statistics
+- **📝 HTTP Recording**: Persist all interactions as re-playable `.http` files
 - **🔍 Auto-Discovery**: Automatically detect and configure SoundTouch devices
 - **🔒 Offline Operation**: Continue using full device functionality without internet
 
@@ -49,10 +50,67 @@ cd Bose-SoundTouch
 go build -o soundtouch-service ./cmd/soundtouch-service
 ```
 
-### Docker (coming soon)
+### Docker Support
+
+You can run the SoundTouch service using Docker or Docker Compose. 
+
+> **Note for macOS and Windows users**: The `--net host` option is only supported on Linux. On macOS and Windows, service discovery (mDNS, UPnP) will not work automatically within the container. You will need to manually enter your device's IP address in the management UI, and the service will communicate with it directly.
+
+#### Using Docker
+
+**Linux (with host networking for discovery):**
 ```bash
-# Docker support planned for future release
-docker run -p 8000:8000 gesellix/soundtouch-service
+docker run -d \
+  --name soundtouch-service \
+  --network host \
+  -v $(pwd)/data:/app/data \
+  ghcr.io/gesellix/bose-soundtouch:latest
+```
+
+**macOS / Windows (with port mapping):**
+```bash
+docker run --rm -it \
+  -p 8000:8000 -p 8443:8443 \
+  -v $(pwd)/data:/app/data \
+  --env SERVER_URL=http://soundtouch.local:8000 \
+  --env HTTPS_SERVER_URL=https://soundtouch.local:8443 \
+  ghcr.io/gesellix/bose-soundtouch:latest
+```
+
+> **Note**: The hostnames configured via `SERVER_URL` and `HTTPS_SERVER_URL` are automatically added as Subject Alternative Names (SAN) to the generated TLS certificate, ensuring valid SSL connections.
+
+#### Using Docker Compose
+
+Create a `docker-compose.yml` file:
+
+```yaml
+services:
+  soundtouch-service:
+    image: ghcr.io/gesellix/bose-soundtouch:latest
+    container_name: soundtouch-service
+    # Linux users: use host networking for device discovery
+    # network_mode: host
+    # macOS/Windows users: use port mapping (discovery will be manual)
+    ports:
+      - "8000:8000"
+      - "8443:8443"
+    environment:
+      - PORT=8000
+      - SERVER_URL=http://soundtouch.local:8000
+      - HTTPS_SERVER_URL=https://soundtouch.local:8443
+      - DATA_DIR=/app/data
+    volumes:
+      - soundtouch-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  soundtouch-data:
+```
+
+And run:
+
+```bash
+docker-compose up -d
 ```
 
 ## Quick Start
@@ -78,17 +136,32 @@ Use the web interface or API to migrate devices from Bose cloud services to your
 
 ## Configuration
 
-The service can be configured via environment variables or command-line flags:
+### Configuration Precedence
 
-| Variable | Flag | Description | Default |
-|----------|------|-------------|---------|
-| `PORT` | `--port` | Port to bind the service to | `8000` |
-| `BIND_ADDR` | `--bind` | Network interface to bind to | all (ipv4 and ipv6) |
-| `DATA_DIR` | `--data-dir` | Directory for persistent data | `./data` |
-| `SERVER_URL` | `--server-url` | External URL of this service | `http://<hostname>:8000` |
-| `REDACT_PROXY_LOGS` | `--redact-logs` | Redact sensitive data in proxy logs | `true` |
-| `LOG_PROXY_BODY` | `--log-bodies` | Log full request/response bodies | `false` |
-| `DISCOVERY_INTERVAL` | `--discovery-interval` | Device discovery interval | `5m` |
+The service supports multiple ways to configure its behavior. When multiple sources provide the same setting, the following precedence rules apply (highest to lowest):
+
+1.  **`settings.json`**: Settings saved via the Web UI (stored in the data directory) take the highest precedence. This ensures that changes made in the browser persist across service restarts even if environment variables or flags change.
+2.  **Environment Variables / CLI Flags**: If a setting is not present in `settings.json`, environment variables and flags are used.
+3.  **Default Values**: If no configuration is provided, the service uses its built-in defaults.
+
+> **Tip**: If you find that changes to environment variables are not taking effect, check the **Settings** tab in the Web UI or inspect the `settings.json` file in your data directory, as it might be overriding your manual configuration.
+
+### Configuration Options
+
+| Variable                           | Flag                       | Description                                      | Default                   |
+|------------------------------------|----------------------------|--------------------------------------------------|---------------------------|
+| `PORT`                             | `--port`, `-p`             | HTTP port to bind the service to                 | `8000`                    |
+| `BIND_ADDR`                        | `--bind`                   | Network interface to bind to                     | all (ipv4 and ipv6)       |
+| `DATA_DIR`                         | `--data-dir`               | Directory for persistent data                    | `./data`                  |
+| `SERVER_URL`                       | `--server-url`, `-s`       | External URL of this service                     | `http://<hostname>:8000`  |
+| `HTTPS_PORT`                       | `--https-port`             | HTTPS port to bind the service to                | `8443`                    |
+| `HTTPS_SERVER_URL`                 | `--https-server-url`, `-S` | External HTTPS URL                               | `https://<hostname>:8443` |
+| `PYTHON_BACKEND_URL`, `TARGET_URL` | `--target-url`             | URL for Python-based service components (legacy) | `http://localhost:8001`   |
+| `REDACT_PROXY_LOGS`                | `--redact-logs`            | Redact sensitive data in proxy logs              | `true`                    |
+| `LOG_PROXY_BODY`                   | `--log-bodies`             | Log full request/response bodies                 | `false`                   |
+| `RECORD_INTERACTIONS`              | `--record-interactions`    | Record HTTP interactions to disk                 | `true`                    |
+| `DISCOVERY_INTERVAL`               | `--discovery-interval`     | Device discovery interval                        | `5m`                      |
+| `DISCOVERY_DISABLED`               |                            | Disable automated device discovery               | `false`                   |
 
 ### Configuration Examples
 
@@ -302,6 +375,13 @@ The web management interface provides a comprehensive dashboard for managing you
 - **Statistics Dashboard**: Usage and error analytics
 - **Debug Tools**: Device communication testing utilities
 
+#### Interactions & Traffic Analysis
+- **Traffic Overview**: View aggregate request counts for self-handled and proxied traffic.
+- **Session Browsing**: Browse recorded interactions grouped by session.
+- **Advanced Filtering**: Filter interactions by session, category (Self/Upstream), and timestamp.
+- **Interaction Viewer**: View raw `.http` recording content directly in the browser.
+- **Session Management**: Delete individual sessions or perform bulk cleanup to keep only recent sessions.
+
 ### Usage Tips
 
 1. **First Time Setup**: The interface will guide you through initial device discovery
@@ -309,6 +389,49 @@ The web management interface provides a comprehensive dashboard for managing you
 3. **Troubleshooting**: Use the debug tools to diagnose device connectivity issues
 4. **Log Analysis**: Enable detailed logging for development and troubleshooting
 
+## HTTP Interaction Recording
+
+The service automatically records all HTTP interactions (both those handled locally and those proxied upstream) as `.http` files. These files are compatible with the [IntelliJ IDEA HTTP Client](https://www.jetbrains.com/help/idea/exploring-http-syntax.html).
+
+### Key Features
+
+- **Session Grouping**: All interactions from a single server session are stored in a dedicated directory named `{timestamp}-{pid}`.
+- **Chronological Order**: Files are prefixed with a sequential number (e.g., `0001-`, `0002-`) to preserve the exact order of requests across the entire session.
+- **Path-Based Structure**: Recordings are organized into subdirectories based on their URL path for better discoverability.
+- **Automatic Sanitization**: Variable path segments like IP addresses, Device IDs, and Account IDs are automatically identified and replaced with placeholders (e.g., `{{ip}}`, `{{deviceId}}`). The original values are preserved as comments at the top of the recorded `.http` files for easy identification.
+- **Re-playability**: An `http-client.env.json` file is generated for each session, allowing you to re-play the recorded requests immediately in IntelliJ IDEA.
+- **Management UI**: The **5. Interactions** tab provides a built-in viewer and management tools for all recorded data.
+
+### Configuration
+
+#### Redaction
+
+By default, the service redacts sensitive information from the recorded `.http` files, including:
+- `Authorization` headers
+- `Cookie` headers
+- `X-Bose-Token` headers
+
+This behavior is controlled by the `--redact-logs` flag or the `REDACT_PROXY_LOGS` environment variable.
+
+#### Custom Patterns
+
+The service uses regex patterns to identify variable segments in URL paths. These patterns are loaded from `data/patterns.json`. You can add custom patterns to this file to support additional variable segments:
+
+```json
+[
+  {
+    "name": "MyVariable",
+    "regexp": "^[0-9]{5}$",
+    "replacement": "{myVar}"
+  }
+]
+```
+
+Variables found via these patterns will be:
+1. Used as directory names in the `interactions/` folder.
+2. Parameterized as `{{myVar}}` within the `.http` files.
+3. Added to the `http-client.env.json` file with their actual values.
+
 ## Persistent Data
 
 ### Data Directory Structure
@@ -327,6 +450,15 @@ data/
 │       ├── Sources.xml
 │       ├── Presets.xml
 │       └── Recents.xml
+├── interactions/
+│   └── {SESSION_ID}/
+│       ├── self/
+│       │   └── {PATH}/
+│       │       └── {SEQ}-{TIME}-{METHOD}.http
+│       ├── upstream/
+│       │   └── {PATH}/
+│       │       └── {SEQ}-{TIME}-{METHOD}.http
+│       └── http-client.env.json
 ├── stats/
 │   ├── usage/
 │   │   └── *.json
@@ -355,6 +487,14 @@ data/
 #### Events (`events/`)
 - **device_events_*.log**: Device event history and debugging logs
 
+#### HTTP Interactions (`interactions/`)
+- **{SESSION_ID}/**: A unique directory per server run (format: `YYYYMMDD-HHMMSS-PID`).
+- **self/**: Requests handled directly by the service.
+- **upstream/**: Requests proxied to external Bose services.
+- **{PATH}/**: Nested subdirectories reflecting the URL path (sanitized).
+- **http-client.env.json**: IntelliJ IDEA HTTP Client environment file with session variables.
+- **{SEQ}-{TIME}-{METHOD}.http**: Individual interaction recordings in standard HTTP Client format.
+
 ### Data Management
 
 #### Backup Strategy
@@ -383,6 +523,49 @@ find data/events/ -name "*.log" -mtime +30 -delete
 find data/stats/ -name "*.json" -mtime +90 -delete
 ```
 
+## API Endpoints
+
+### Management UI
+- **URL**: `http://localhost:8000/` or `http://localhost:8000/web/`
+- **Description**: Browser-based guided flow for discovery, data sync, and migration.
+
+### Setup API
+- `GET /setup/devices`: List all known (auto-discovered and manual) devices.
+- `POST /setup/devices`: Manually add a device by IP.
+- `POST /setup/discover`: Trigger a new network discovery scan.
+- `GET /setup/discovery-status`: Check if a scan is currently in progress.
+- `POST /setup/sync/{deviceIP}`: Fetch presets, recents, and sources from a device.
+- `GET /setup/summary/{deviceIP}`: Get a detailed migration readiness summary.
+- `POST /setup/migrate/{deviceIP}`: Migrate a device using the specified method (XML/Hosts).
+- `GET /setup/ca.crt`: Download the Root CA certificate for manual installation.
+
+#### `GET /setup/interactions`
+Lists recorded interactions with optional filtering.
+
+**Query Parameters:**
+- `session`: Filter by session ID (optional)
+- `category`: Filter by category (`self` or `upstream`) (optional)
+- `since`: Filter by timestamp (e.g., `2026-02-15 15:00:00`) (optional)
+
+#### `GET /setup/interaction-stats`
+Returns aggregate statistics about recorded interactions across all sessions.
+
+#### `GET /setup/interaction-content?file={path}`
+Returns the raw content of a specific recorded `.http` file.
+
+#### `DELETE /setup/interactions/sessions/{sessionID}`
+Deletes all recordings associated with a specific session.
+
+#### `DELETE /setup/interactions/sessions?keep={N}`
+Bulk cleanup: deletes all but the most recent `N` sessions.
+
+### Emulated Services
+- `/bmx/registry/v1/services`: BMX service registry.
+- `/bmx/tunein/v1/*`: TuneIn radio emulation.
+- `/marge/accounts/*`: Account and device management.
+- `/marge/updates/soundtouch`: Software update emulation.
+- `/proxy/*`: Logging proxy for original Bose services.
+
 ## Troubleshooting
 
 ### Common Issues

docs/guides/SURVIVAL-GUIDE.md

@@ -0,0 +1,85 @@
+### Bose Cloud Shutdown: Survival Guide for SoundTouch
+
+With Bose's announcement of discontinuing cloud support for SoundTouch devices in May 2026, this project provides the necessary tools to keep your speakers fully functional using a local emulation service.
+
+This guide explains how to set up the `soundtouch-service` to run your devices independently of Bose's servers.
+
+---
+
+### Supported Use Cases
+
+1.  **Local Service Emulation**: The service emulates Bose's BMX (Bose Media eXchange) and Marge services, which handle content registries, presets, recents, and software update checks.
+2.  **Traffic Redirection**: Tools are provided to redirect your speakers to this local service instead of `*.bose.com`.
+3.  **Offline Operation**: Once redirected, the speakers function without needing to reach Bose's servers.
+4.  **Preset & Recent Management**: Captures and stores presets and "recently played" items locally.
+
+---
+
+### Setup Steps
+
+To set up your SoundTouch system for local-only operation, follow these steps:
+
+#### 1. Install and Start the Service
+Run the `soundtouch-service` on a machine that is always on (like a Raspberry Pi or a NAS) within your local network.
+
+```bash
+# Install the service
+go install github.com/gesellix/bose-soundtouch/cmd/soundtouch-service@latest
+
+# Start the service (defaults to http://localhost:8000)
+soundtouch-service
+```
+
+#### 2. Access the Management UI
+Open your web browser and navigate to the service's web interface:
+`http://<your-server-ip>:8000/`, e.g. `http://localhost:8000/`
+
+*Note: The service also supports a `/web/` path for management.*
+
+#### 3. Enable SSH on Your Speakers
+To migrate your speakers, the service needs SSH access. You can enable it by:
+1. Creating an empty file named `remote_services` on a USB stick.
+2. Inserting the USB stick into the SoundTouch speaker's service port.
+3. Rebooting the speaker (unplug/replug).
+
+**Verify SSH Access:**
+- Confirm the device responds to SSH without a password: `ssh -oHostKeyAlgorithms=+ssh-rsa root@<IP>`
+- Or use the **Migration** tab in the Web UI to see if the device shows a "✅ Success" status for SSH.
+Once enabled, you can log in as `root` (no password).
+
+#### 4. Setup Through the Web UI
+The web interface handles the entire process in a guided flow. Before proceeding, we strongly recommend reviewing the [Migration & Safety Guide](MIGRATION-SAFETY.md).
+
+*   **Step 1: Settings**: Configure your server's IP or domain. This ensures the speakers know where to find the local services.
+*   **Step 2: Devices**: The service automatically scans for SoundTouch devices on your network. If a device is not found, you can manually add its IP address.
+*   **Step 3: Data Sync**: Select your device and click "Start Sync". This will automatically fetch your presets, recents, and configured sources from the speaker and store them in the local `data/` directory.
+*   **Step 4: Migration**: Choose your redirection method (XML Recommended) and click "Confirm Migration". After the migration, reboot your speaker to apply the changes.
+
+#### 5. Verify Your Local Data
+Once migrated, your speaker will use the data captured during the Sync step.
+*   The service stores data in the `data/` directory, organized by device serial number (e.g., `data/default/devices/<SERIAL>/`).
+*   **Automatic Capture**: As you use the device (changing presets, playing new music), the service continues to "learn" and update your local files.
+
+---
+
+### Comparison with other implementations (soundcork)
+Our implementation (`soundtouch-service`) is largely compatible with the Python-based `soundcork` project but offers several advantages:
+- **Web UI**: Integrated management interface for discovery and migration.
+- **Surgical Migration**: Uses XML-based redirection by default, which is less invasive than `/etc/hosts`.
+- **Automated SSL**: Handles Root CA injection automatically for secure communication.
+- **Proxy Support**: Can proxy requests to original Bose servers while "learning" your configuration.
+
+---
+
+### Alternative: DNS Redirection (No SSH)
+If you prefer not to modify your speakers via SSH, you can use a local DNS server (like Pi-hole, AdGuard Home, or Unbound) to point the following domains to your local server's IP:
+
+*   `bmx.bose.com`
+*   `streaming.bose.com`
+*   `updates.bose.com`
+*   `stats.bose.com`
+*   `content.api.bose.io`
+
+*Note: DNS redirection for HTTPS services requires the speakers to trust your local service's SSL certificate. The SSH-based migration handles this automatically by injecting the CA.*
+
+---

docs/reference/BASS-CONTROLS.md

@@ -418,10 +418,10 @@ soundtouch-cli -host <discovered-ip> -bass  # Verify final state
 
 ## Related Documentation
 
-- **[API Endpoints Overview](API-Endpoints-Overview.md)** - Complete API reference
+- **[API Endpoints Overview](API-ENDPOINTS.md)** - Complete API reference
 - **[Volume Controls](VOLUME-CONTROLS.md)** - Related audio control documentation
-- **[Client Usage Examples](../cmd/soundtouch-cli/main.go)** - CLI implementation reference
-- **[Models](../pkg/models/bass.go)** - Bass model implementation
+- **[Client Usage Examples](../../cmd/soundtouch-cli/main.go)** - CLI implementation reference
+- **[Models](../../pkg/models/bass.go)** - Bass model implementation
 
 ## API Compliance
 
@@ -443,4 +443,4 @@ The implementation follows the official SoundTouch API:
 **Implementation Date**: 2026-01-09  
 **Status**: ✅ Complete and tested  
 **Real Device Validation**: SoundTouch 10, SoundTouch 20  
-**API Compliance**: Full compliance with SoundTouch Web API specification
+**API Compliance**: Full compliance with SoundTouch Web API specification

docs/reference/CLOUD-API.md

@@ -0,0 +1,73 @@
+# Bose SoundTouch Cloud API Emulation (Marge/BMX/Stats)
+
+This document describes the cloud-emulation APIs provided by the SoundTouch service. These APIs mimic the Bose cloud services (Marge, BMX, Stats) that SoundTouch devices and the SoundTouch controller application (Stockholm) interact with.
+
+## Marge API (Account & Configuration)
+
+Base path: `/marge`
+
+### GET /streaming/sourceproviders
+Retrieves a list of available streaming source providers.
+
+### GET /accounts/{accountId}/full
+Retrieves the full account configuration including sources, presets, and devices.
+
+### GET /streaming/account/{accountId}/emailaddress
+Retrieves the email address associated with the account.
+
+### GET /streaming/device_setting/account/{accountId}/device/{deviceId}/device_settings
+Retrieves settings for a specific device (e.g., clock format).
+
+### POST /streaming/device_setting/account/{accountId}/device/{deviceId}/device_settings
+Updates settings for a specific device.
+
+### POST /accounts/{accountId}/devices/{deviceId}/presets/{presetNumber}
+Updates a preset for a device.
+
+### POST /accounts/{accountId}/devices/{deviceId}/recents
+Adds an item to the device's recently played history.
+
+### POST /accounts/{accountId}/devices
+Adds a device to the account.
+
+### DELETE /accounts/{accountId}/devices/{deviceId}
+Removes a device from the account.
+
+## Customer API (Profile & Password)
+
+Base path: `/customer`
+
+### GET /account/{accountId}
+Retrieves the customer account profile.
+
+### POST /account/{accountId}
+Updates the customer account profile.
+
+### POST /account/{accountId}/password
+Changes the account password.
+
+## Analytics & Stats API
+
+Base path: `/v1` (App Events) or `/streaming/stats` (Device Stats)
+
+### POST /v1/stapp/{deviceId}
+Endpoint called by Bose SoundTouch mobile and web applications (Stockholm) to submit event data.
+
+### POST /v1/scmudc/{deviceId}
+Endpoint equivalent to `/v1/stapp/{deviceId}` sometimes used by apps or devices.
+
+### POST /streaming/stats/usage
+Endpoint used by physical devices to report usage statistics.
+
+### POST /streaming/stats/error
+Endpoint used by physical devices to report error statistics.
+
+## BMX API (Streaming & Registry)
+
+Base path: `/bmx`
+
+### GET /registry/v1/services
+Retrieves the registry of available streaming services.
+
+### GET /tunein/v1/playback/station/{stationID}
+Retrieves playback information for a TuneIn station.

docs/reference/PRESET-MANAGEMENT.md

@@ -366,7 +366,7 @@ This implementation now provides the full preset management lifecycle:
 
 ## Related Documentation
 
-- [API Endpoints Overview](API-Endpoints-Overview.md) - Complete API reference
+- [API Endpoints Overview](API-ENDPOINTS.md) - Complete API reference
 - [Volume Controls](VOLUME-CONTROLS.md) - Volume management
 - [Key Controls](KEY-CONTROLS.md) - Media control commands
 - [Source Selection](SOURCE-SELECTION.md) - Audio source management
@@ -375,4 +375,4 @@ This implementation now provides the full preset management lifecycle:
 
 Preset management in the Bose SoundTouch API is **intentionally read-only** by design. The API provides excellent capabilities for analyzing and understanding preset configurations, but preset creation must be done through official channels (app or device). This is a deliberate design decision that respects user control over their personal preset configurations.
 
-For most use cases, reading preset information is sufficient for building applications that work with existing user configurations. For preset creation, guide users to use the official app or device controls, which provide the proper user experience and validation.
+For most use cases, reading preset information is sufficient for building applications that work with existing user configurations. For preset creation, guide users to use the official app or device controls, which provide the proper user experience and validation.

docs/reference/SOURCE-SELECTION.md

@@ -345,13 +345,13 @@ The implementation follows the official SoundTouch API:
 
 ## Related Documentation
 
-- **[API Endpoints Overview](API-Endpoints-Overview.md)** - Complete API reference
-- **[Sources](../pkg/models/sources.go)** - Source model implementation  
-- **[Now Playing](../pkg/models/nowplaying.go)** - ContentItem model
-- **[Client Usage Examples](../cmd/soundtouch-cli/main.go)** - CLI implementation reference
+- **[API Endpoints Overview](API-ENDPOINTS.md)** - Complete API reference
+- **[Sources](../../pkg/models/sources.go)** - Source model implementation  
+- **[Now Playing](../../pkg/models/nowplaying.go)** - ContentItem model
+- **[Client Usage Examples](../../cmd/soundtouch-cli/main.go)** - CLI implementation reference
 
 ---
 
 **Implementation Date**: 2026-01-09  
 **Status**: ✅ Complete and tested  
-**Real Device Validation**: SoundTouch 10, SoundTouch 20
+**Real Device Validation**: SoundTouch 10, SoundTouch 20

examples/account-management/README.md

@@ -149,4 +149,4 @@ After configuring accounts:
 3. Use `browse` commands to explore content
 4. Use `play` commands to start playback
 
-See the [CLI Reference](../../docs/CLI-REFERENCE.md) for complete documentation.
+See the [CLI Reference](../../docs/guides/CLI-REFERENCE.md) for complete documentation.

examples/content-selection/README.md

@@ -176,5 +176,5 @@ The example gracefully handles missing services:
 ## Related Documentation
 
 - [SoundTouch WebServices API Wiki](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki/SoundTouch-WebServices-API)
-- [CLI Reference](../../docs/CLI-REFERENCE.md)
-- [Navigation Guide](../../docs/NAVIGATION-GUIDE.md)
+- [CLI Reference](../../docs/guides/CLI-REFERENCE.md)
+- [Navigation Guide](../../docs/guides/SURVIVAL-GUIDE.md)

examples/introspect/README.md

@@ -177,11 +177,11 @@ if err != nil {
 
 This introspect data is useful before:
 - [Preset Management](../preset-management/) - Verify service state before storing presets
-- [Content Selection](../../docs/SOURCE-SELECTION.md) - Check capabilities before switching sources
-- [Zone Management](../../docs/zone-management.md) - Ensure all devices support the service
+- [Content Selection](../../docs/reference/SOURCE-SELECTION.md) - Check capabilities before switching sources
+- [Zone Management](../../docs/reference/ZONE-MANAGEMENT.md) - Ensure all devices support the service
 
 ## API Documentation
 
 For complete API documentation, see:
-- [API Reference](../../docs/API-Endpoints-Overview.md)
-- [Service Availability Implementation](../../docs/SERVICE-AVAILABILITY-IMPLEMENTATION.md)
+- [API Reference](../../docs/reference/API-ENDPOINTS.md)
+- [Service Availability Implementation](../../docs/SERVICE-AVAILABILITY-IMPLEMENTATION.md)

examples/navigation-station-demo/README.md

@@ -275,10 +275,10 @@ go run ./cmd/soundtouch-cli --host 192.168.1.100 info
 
 ## Related Documentation
 
-- [CLI Reference](../../docs/CLI-REFERENCE.md) - Browse and station commands
-- [Navigation Guide](../../docs/NAVIGATION-GUIDE.md) - Comprehensive navigation documentation
+- [CLI Reference](../../docs/guides/CLI-REFERENCE.md) - Browse and station commands
+- [Navigation Guide](../../docs/guides/SURVIVAL-GUIDE.md) - Comprehensive navigation documentation
 - [Navigation API Reference](../../docs/API-NAVIGATION-REFERENCE.md) - Technical API details
-- [WebSocket Events](../../docs/websocket-events.md) - Real-time event handling
+- [WebSocket Events](../../docs/reference/WEBSOCKET-EVENTS.md) - Real-time event handling
 
 ## Use Cases
 
@@ -288,4 +288,4 @@ This example demonstrates patterns for:
 - **Direct Playback**: Play content without storing as presets first
 - **Content Exploration**: Browse large music libraries efficiently
 - **Smart Home Integration**: Programmatically start specific content
-- **Personalized Experiences**: Access account-specific content from streaming services
+- **Personalized Experiences**: Access account-specific content from streaming services

examples/preset-management/README.md

@@ -256,10 +256,10 @@ Error: All preset slots are occupied
 
 ## Related Documentation
 
-- [CLI Reference](../../docs/CLI-REFERENCE.md) - Command-line usage
+- [CLI Reference](../../docs/guides/CLI-REFERENCE.md) - Command-line usage
 - [Preset Implementation Guide](../../docs/preset-store.md) - Technical details
-- [WebSocket Events](../../docs/websocket-events.md) - Real-time event handling
-- [API Reference](../../docs/API-Endpoints-Overview.md) - Complete API documentation
+- [WebSocket Events](../../docs/reference/WEBSOCKET-EVENTS.md) - Real-time event handling
+- [API Reference](../../docs/reference/API-ENDPOINTS.md) - Complete API documentation
 
 ## Use Cases
 
@@ -269,4 +269,4 @@ This example demonstrates patterns for:
 - **Music Management**: Organize favorite content into quick-access presets
 - **Family Scenarios**: Each person gets their own preset slots
 - **Party Mode**: Pre-configure playlists for different moods
-- **Radio Favorites**: Save frequently listened radio stations
+- **Radio Favorites**: Save frequently listened radio stations

examples/recents/README.md

@@ -252,8 +252,8 @@ go run main.go -host 192.168.1.100 -type unknown
 
 This recents data is useful for:
 - [Preset Management](../preset-management/) - Finding presetable content to save
-- [Content Selection](../../docs/SOURCE-SELECTION.md) - Understanding usage patterns
-- [Navigation](../../docs/NAVIGATION-GUIDE.md) - Quickly accessing recently played content
+- [Content Selection](../../docs/reference/SOURCE-SELECTION.md) - Understanding usage patterns
+- [Navigation](../../docs/guides/SURVIVAL-GUIDE.md) - Quickly accessing recently played content
 
 ## Related CLI Commands
 
@@ -274,6 +274,6 @@ soundtouch-cli --host 192.168.1.100 recents latest
 ## API Documentation
 
 For complete API documentation, see:
-- [API Reference](../../docs/API-Endpoints-Overview.md)
-- [CLI Reference](../../docs/CLI-REFERENCE.md)
-- [Recents Models](../../pkg/models/recents.go)
+- [API Reference](../../docs/reference/API-ENDPOINTS.md)
+- [CLI Reference](../../docs/guides/CLI-REFERENCE.md)
+- [Recents Models](../../pkg/models/recents.go)

go.mod

@@ -6,18 +6,18 @@ require (
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/gorilla/websocket v1.5.3
 	github.com/hashicorp/mdns v1.0.6
+	github.com/russross/blackfriday/v2 v2.1.0
 	github.com/urfave/cli/v2 v2.27.7
-	golang.org/x/crypto v0.47.0
+	golang.org/x/crypto v0.48.0
 )
 
 require (
 	github.com/cpuguy83/go-md2man/v2 v2.0.7 // indirect
 	github.com/miekg/dns v1.1.72 // indirect
-	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/xrash/smetrics v0.0.0-20240521201337-686a1a2994c1 // indirect
-	golang.org/x/mod v0.32.0 // indirect
-	golang.org/x/net v0.49.0 // indirect
+	golang.org/x/mod v0.33.0 // indirect
+	golang.org/x/net v0.50.0 // indirect
 	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
-	golang.org/x/tools v0.41.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/tools v0.42.0 // indirect
 )

go.sum

@@ -24,16 +24,16 @@ golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliY
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
-golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
-golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.7.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/mod v0.32.0 h1:9F4d3PHLljb6x//jOyokMv3eX+YDeepZSEo3mFJy93c=
-golang.org/x/mod v0.32.0/go.mod h1:SgipZ/3h2Ci89DlEtEXWUk/HteuRin+HHhN+WbNhguU=
+golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
+golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
@@ -44,8 +44,8 @@ golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
 golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
 golang.org/x/net v0.34.0/go.mod h1:di0qlW3YNM5oh6GqDGQr92MyTozJPmybPK4Ev/Gm31k=
-golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
-golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
@@ -67,8 +67,8 @@ golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
@@ -79,8 +79,8 @@ golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
 golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
 golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek=
-golang.org/x/term v0.39.0 h1:RclSuaJf32jOqZz74CkPA9qFuVTX7vhLlpfj/IGWlqY=
-golang.org/x/term v0.39.0/go.mod h1:yxzUCTP/U+FzoxfdKmLaA0RV1WgE0VY7hXBwKtY/4ww=
+golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
+golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
@@ -98,6 +98,6 @@ golang.org/x/tools v0.3.0/go.mod h1:/rWhSS2+zyEVwoJf8YAX6L2f0ntZ7Kn/mGgAWcipA5k=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
-golang.org/x/tools v0.41.0 h1:a9b8iMweWG+S0OBnlU36rzLp20z1Rp10w+IY2czHTQc=
-golang.org/x/tools v0.41.0/go.mod h1:XSY6eDqxVNiYgezAVqqCeihT4j1U2CCsqvH3WhQpnlg=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

pkg/client/client.go

@@ -1801,8 +1801,29 @@ func (c *Client) PlayCustom(playInfo *models.PlayInfo) error {
 
 // PlayNotificationBeep plays a notification beep on the device
 func (c *Client) PlayNotificationBeep() error {
-	var status models.StationResponse
-	return c.get("/playNotification", &status)
+	return c.PlayNotification("")
+}
+
+// PlayNotification plays a notification. If a non-empty local path is provided,
+// it will be sent as XML body to play that specific device-local PCM file.
+// When path is empty, the device's default beep is triggered.
+func (c *Client) PlayNotification(path string) error {
+	// Empty path -> trigger default beep via GET
+	if strings.TrimSpace(path) == "" {
+		var status models.StationResponse
+		return c.get("/playNotification", &status)
+	}
+
+	// Non-empty path -> POST minimal XML payload as required by the device
+	payload := struct {
+		XMLName    xml.Name `xml:"audioSource"`
+		PathToFile string   `xml:"pathToFile,attr"`
+	}{
+		XMLName:    xml.Name{Local: "audioSource"},
+		PathToFile: path,
+	}
+
+	return c.post("/playNotification", payload)
 }
 
 // Introspect retrieves introspect data for a specified music service

pkg/client/client_test.go

@@ -1,6 +1,7 @@
 package client
 
 import (
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
@@ -1160,3 +1161,71 @@ func TestClient_RequestToken_Error(t *testing.T) {
 		t.Errorf("Error should mention 'failed to request token', got: %v", err)
 	}
 }
+
+func TestClient_PlayNotificationBeep(t *testing.T) {
+	// Create mock server
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/playNotification" {
+			t.Errorf("Expected path '/playNotification', got '%s'", r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+
+		if r.Method != http.MethodGet {
+			t.Errorf("Expected GET method, got %s", r.Method)
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/xml")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`<?xml version="1.0" encoding="UTF-8" ?><status>success</status>`))
+	}))
+	defer server.Close()
+
+	// Create test client
+	client := createTestClient(server.URL)
+
+	// Test PlayNotificationBeep
+	err := client.PlayNotificationBeep()
+	if err != nil {
+		t.Fatalf("PlayNotificationBeep() failed: %v", err)
+	}
+}
+
+func TestClient_PlayNotification_Path(t *testing.T) {
+	testPath := "/opt/Bose/chimes/grouped.pcm"
+
+	// Create mock server
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/playNotification" {
+			t.Errorf("Expected path '/playNotification', got '%s'", r.URL.Path)
+			w.WriteHeader(http.StatusNotFound)
+			return
+		}
+
+		if r.Method != http.MethodPost {
+			t.Errorf("Expected POST method, got %s", r.Method)
+			w.WriteHeader(http.StatusMethodNotAllowed)
+			return
+		}
+
+		body, _ := io.ReadAll(r.Body)
+		expectedXML := `<audioSource pathToFile="` + testPath + `"></audioSource>`
+		if string(body) != expectedXML {
+			t.Errorf("Expected body '%s', got '%s'", expectedXML, string(body))
+		}
+
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer server.Close()
+
+	// Create test client
+	client := createTestClient(server.URL)
+
+	// Test PlayNotification with path
+	err := client.PlayNotification(testPath)
+	if err != nil {
+		t.Fatalf("PlayNotification() failed: %v", err)
+	}
+}

pkg/models/models.go

@@ -160,12 +160,19 @@ type ServiceRecent struct {
 
 // ConfiguredSource represents a configured media source with authentication details.
 type ConfiguredSource struct {
-	DisplayName      string `json:"display_name" xml:"sourcename"`
-	ID               string `json:"id" xml:"id,attr"`
-	Secret           string `json:"secret" xml:"credential"`
-	SecretType       string `json:"secret_type" xml:"credential_type,attr"`
-	SourceKeyType    string `json:"source_key_type" xml:"sourceproviderid"`
-	SourceKeyAccount string `json:"source_key_account" xml:"username"`
+	DisplayName string `json:"display_name" xml:"displayName,attr"`
+	ID          string `json:"id" xml:"id,attr"`
+	Secret      string `json:"secret" xml:"secret,attr"`
+	SecretType  string `json:"secret_type" xml:"secretType,attr"`
+	SourceKey   struct {
+		Type    string `xml:"type,attr"`
+		Account string `xml:"account,attr"`
+	} `json:"source_key" xml:"sourceKey"`
+
+	// Legacy fields for backward compatibility in code if needed,
+	// though it's better to update the code to use SourceKey.
+	SourceKeyType    string `json:"source_key_type" xml:"-"`
+	SourceKeyAccount string `json:"source_key_account" xml:"-"`
 }
 
 // ServiceDeviceInfo represents information about a SoundTouch device.
@@ -177,6 +184,8 @@ type ServiceDeviceInfo struct {
 	FirmwareVersion     string `json:"firmware_version" xml:"softwareVersion"`
 	IPAddress           string `json:"ip_address" xml:"ipAddress"`
 	Name                string `json:"name" xml:"name"`
+	DiscoveryMethod     string `json:"discovery_method,omitempty"`
+	AccountID           string `json:"account_id,omitempty"`
 }
 
 // CustomerSupportDevice represents device information for customer support purposes.
@@ -231,3 +240,70 @@ type DeviceEvent struct {
 	MonoTime int64                  `json:"monoTime"`
 	Data     map[string]interface{} `json:"data"`
 }
+
+// DeviceEventsRequest represents a request containing multiple device events (stapp/scmudc).
+type DeviceEventsRequest struct {
+	Envelope struct {
+		MonoTime               int64  `json:"monoTime"`
+		PayloadProtocolVersion string `json:"payloadProtocolVersion"`
+		PayloadType            string `json:"payloadType"`
+		ProtocolVersion        string `json:"protocolVersion"`
+		Time                   string `json:"time"`
+		UniqueID               string `json:"uniqueId"`
+	} `json:"envelope"`
+	Payload struct {
+		DeviceInfo struct {
+			BoseID          string `json:"boseID"`
+			DeviceID        string `json:"deviceID"`
+			DeviceType      string `json:"deviceType"`
+			SoftwareVersion string `json:"softwareVersion"`
+		} `json:"deviceInfo"`
+		Events []struct {
+			Data map[string]interface{} `json:"data"`
+			Time string                 `json:"time"`
+			Type string                 `json:"type"`
+		} `json:"events"`
+	} `json:"payload"`
+}
+
+// DeviceSettingsResponse represents device settings.
+type DeviceSettingsResponse struct {
+	XMLName  xml.Name        `xml:"deviceSettings"`
+	Settings []DeviceSetting `xml:"deviceSetting"`
+}
+
+// DeviceSetting represents a single device setting.
+type DeviceSetting struct {
+	Name  string `xml:"name"`
+	Value string `xml:"value"`
+}
+
+// AccountProfileResponse represents a customer account profile.
+type AccountProfileResponse struct {
+	XMLName        xml.Name `xml:"customer"`
+	AccountID      string   `xml:"accountID"`
+	Email          string   `xml:"email"`
+	FirstName      string   `xml:"firstName"`
+	LastName       string   `xml:"lastName"`
+	CountryCode    string   `xml:"countryCode"`
+	LanguageCode   string   `xml:"languageCode"`
+	Street         string   `xml:"street"`
+	City           string   `xml:"city"`
+	PostalCode     string   `xml:"postalCode"`
+	State          string   `xml:"state"`
+	Phone          string   `xml:"phone"`
+	MarketingOptIn bool     `xml:"marketingOptIn"`
+}
+
+// ChangePasswordRequest represents a request to change the account password.
+type ChangePasswordRequest struct {
+	XMLName     xml.Name `xml:"passwordChange"`
+	OldPassword string   `xml:"oldPassword"`
+	NewPassword string   `xml:"newPassword"`
+}
+
+// EmailAddressResponse represents the account email address.
+type EmailAddressResponse struct {
+	XMLName xml.Name `xml:"emailAddress"`
+	Email   string   `xml:",chardata"`
+}

pkg/service/certmanager/certmanager.go

@@ -0,0 +1,262 @@
+// Package certmanager provides tools for managing Root CAs and generating SSL certificates.
+package certmanager
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/tls"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/pem"
+	"math/big"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// CertificateManager handles CA and certificate generation.
+type CertificateManager struct {
+	CertsDir string
+}
+
+// NewCertificateManager creates a new CertificateManager.
+func NewCertificateManager(certsDir string) *CertificateManager {
+	return &CertificateManager{CertsDir: certsDir}
+}
+
+// GetCACertPath returns the path to the CA certificate.
+func (cm *CertificateManager) GetCACertPath() string {
+	return filepath.Join(cm.CertsDir, "ca.crt")
+}
+
+// GetCAKeyPath returns the path to the CA private key.
+func (cm *CertificateManager) GetCAKeyPath() string {
+	return filepath.Join(cm.CertsDir, "ca.key")
+}
+
+// EnsureCA ensures that a CA certificate and key exist.
+func (cm *CertificateManager) EnsureCA() error {
+	certPath := cm.GetCACertPath()
+	keyPath := cm.GetCAKeyPath()
+
+	if _, err := os.Stat(certPath); err == nil {
+		if _, err := os.Stat(keyPath); err == nil {
+			return nil
+		}
+	}
+
+	return cm.GenerateCA()
+}
+
+// GetServerCertPEMPath returns the path to the server certificate PEM.
+func (cm *CertificateManager) GetServerCertPEMPath() string {
+	return filepath.Join(cm.CertsDir, "server.crt")
+}
+
+// GetServerKeyPEMPath returns the path to the server private key PEM.
+func (cm *CertificateManager) GetServerKeyPEMPath() string {
+	return filepath.Join(cm.CertsDir, "server.key")
+}
+
+// GetServerTLSConfig returns a TLS config with the server certificate.
+// If the certificate doesn't exist, it generates one for the given domains.
+func (cm *CertificateManager) GetServerTLSConfig(domains []string) (*tls.Config, error) {
+	certPath := cm.GetServerCertPEMPath()
+	keyPath := cm.GetServerKeyPEMPath()
+
+	generate := false
+	if _, err := os.Stat(certPath); os.IsNotExist(err) {
+		generate = true
+	} else {
+		// Check if the current certificate covers all requested domains
+		certBytes, err := os.ReadFile(certPath)
+		if err == nil {
+			block, _ := pem.Decode(certBytes)
+			if block != nil {
+				cert, err := x509.ParseCertificate(block.Bytes)
+				if err == nil {
+					domainMap := make(map[string]bool)
+					for _, d := range cert.DNSNames {
+						domainMap[d] = true
+					}
+
+					for _, d := range domains {
+						if !domainMap[d] {
+							generate = true
+							break
+						}
+					}
+				} else {
+					generate = true
+				}
+			} else {
+				generate = true
+			}
+		} else {
+			generate = true
+		}
+	}
+
+	if generate {
+		certPEM, keyPEM, err := cm.GenerateCertificate(domains)
+		if err != nil {
+			return nil, err
+		}
+
+		if err := os.WriteFile(certPath, certPEM, 0644); err != nil {
+			return nil, err
+		}
+
+		if err := os.WriteFile(keyPath, keyPEM, 0600); err != nil {
+			return nil, err
+		}
+	}
+
+	cert, err := tls.LoadX509KeyPair(certPath, keyPath)
+	if err != nil {
+		return nil, err
+	}
+
+	return &tls.Config{
+		Certificates: []tls.Certificate{cert},
+		MinVersion:   tls.VersionTLS12,
+		CipherSuites: []uint16{
+			tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
+			tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
+			tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
+			tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
+			tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
+		},
+	}, nil
+}
+
+// GenerateCA generates a new CA certificate and key.
+func (cm *CertificateManager) GenerateCA() error {
+	priv, err := rsa.GenerateKey(rand.Reader, 4096)
+	if err != nil {
+		return err
+	}
+
+	notBefore := time.Now()
+	notAfter := notBefore.Add(10 * 365 * 24 * time.Hour) // 10 years
+
+	serialNumber, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
+	if err != nil {
+		return err
+	}
+
+	template := x509.Certificate{
+		SerialNumber: serialNumber,
+		Subject: pkix.Name{
+			Organization: []string{"AfterTouch"},
+			CommonName:   "AfterTouch Local Root CA",
+		},
+		NotBefore:             notBefore,
+		NotAfter:              notAfter,
+		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageDigitalSignature,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		BasicConstraintsValid: true,
+		IsCA:                  true,
+	}
+
+	derBytes, err := x509.CreateCertificate(rand.Reader, &template, &template, &priv.PublicKey, priv)
+	if err != nil {
+		return err
+	}
+
+	certPath := cm.GetCACertPath()
+	if mkdirErr := os.MkdirAll(cm.CertsDir, 0755); mkdirErr != nil {
+		return mkdirErr
+	}
+
+	certOut, err := os.Create(certPath)
+	if err != nil {
+		return err
+	}
+
+	if encodeErr := pem.Encode(certOut, &pem.Block{Type: "CERTIFICATE", Bytes: derBytes}); encodeErr != nil {
+		return encodeErr
+	}
+
+	certOut.Close()
+
+	keyOut, err := os.OpenFile(cm.GetCAKeyPath(), os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0600)
+	if err != nil {
+		return err
+	}
+
+	if err := pem.Encode(keyOut, &pem.Block{Type: "RSA PRIVATE KEY", Bytes: x509.MarshalPKCS1PrivateKey(priv)}); err != nil {
+		return err
+	}
+
+	keyOut.Close()
+
+	return nil
+}
+
+// GenerateCertificate generates a certificate for the given domains signed by the CA.
+func (cm *CertificateManager) GenerateCertificate(domains []string) ([]byte, []byte, error) {
+	if err := cm.EnsureCA(); err != nil {
+		return nil, nil, err
+	}
+
+	caCertPEM, err := os.ReadFile(cm.GetCACertPath())
+	if err != nil {
+		return nil, nil, err
+	}
+
+	caKeyPEM, err := os.ReadFile(cm.GetCAKeyPath())
+	if err != nil {
+		return nil, nil, err
+	}
+
+	caBlock, _ := pem.Decode(caCertPEM)
+
+	caCert, err := x509.ParseCertificate(caBlock.Bytes)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	keyBlock, _ := pem.Decode(caKeyPEM)
+
+	caKey, err := x509.ParsePKCS1PrivateKey(keyBlock.Bytes)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	priv, err := rsa.GenerateKey(rand.Reader, 2048)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	notBefore := time.Now()
+	notAfter := notBefore.Add(365 * 24 * time.Hour) // 1 year
+
+	serialNumber, err := rand.Int(rand.Reader, new(big.Int).Lsh(big.NewInt(1), 128))
+	if err != nil {
+		return nil, nil, err
+	}
+
+	template := x509.Certificate{
+		SerialNumber: serialNumber,
+		Subject: pkix.Name{
+			Organization: []string{"AfterTouch"},
+			CommonName:   domains[0],
+		},
+		NotBefore:   notBefore,
+		NotAfter:    notAfter,
+		KeyUsage:    x509.KeyUsageDigitalSignature | x509.KeyUsageKeyEncipherment,
+		ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+		DNSNames:    domains,
+	}
+
+	derBytes, err := x509.CreateCertificate(rand.Reader, &template, caCert, &priv.PublicKey, caKey)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	certPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: derBytes})
+	keyPEM := pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: x509.MarshalPKCS1PrivateKey(priv)})
+
+	return certPEM, keyPEM, nil
+}

pkg/service/certmanager/certmanager_test.go

@@ -0,0 +1,128 @@
+package certmanager
+
+import (
+	"crypto/x509"
+	"encoding/pem"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestCertificateManager(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "crypto-test")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	cm := NewCertificateManager(filepath.Join(tempDir, "certs"))
+
+	// Test CA generation
+	if err := cm.EnsureCA(); err != nil {
+		t.Fatalf("Failed to ensure CA: %v", err)
+	}
+
+	if _, err := os.Stat(cm.GetCACertPath()); os.IsNotExist(err) {
+		t.Errorf("CA certificate not created")
+	}
+	if _, err := os.Stat(cm.GetCAKeyPath()); os.IsNotExist(err) {
+		t.Errorf("CA key not created")
+	}
+
+	// Test loading CA
+	caCertPEM, err := os.ReadFile(cm.GetCACertPath())
+	if err != nil {
+		t.Fatalf("Failed to read CA cert: %v", err)
+	}
+	block, _ := pem.Decode(caCertPEM)
+	if block == nil || block.Type != "CERTIFICATE" {
+		t.Errorf("Invalid CA certificate PEM")
+	}
+	caCert, err := x509.ParseCertificate(block.Bytes)
+	if err != nil {
+		t.Fatalf("Failed to parse CA cert: %v", err)
+	}
+	if !caCert.IsCA {
+		t.Errorf("Generated certificate is not a CA")
+	}
+
+	// Test certificate generation
+	domains := []string{"streaming.bose.com", "updates.bose.com"}
+	certPEM, keyPEM, err := cm.GenerateCertificate(domains)
+	if err != nil {
+		t.Fatalf("Failed to generate certificate: %v", err)
+	}
+
+	if len(certPEM) == 0 || len(keyPEM) == 0 {
+		t.Errorf("Generated certificate or key is empty")
+	}
+
+	// Verify generated certificate
+	block, _ = pem.Decode(certPEM)
+	if block == nil || block.Type != "CERTIFICATE" {
+		t.Errorf("Invalid certificate PEM")
+	}
+	cert, err := x509.ParseCertificate(block.Bytes)
+	if err != nil {
+		t.Fatalf("Failed to parse certificate: %v", err)
+	}
+
+	if cert.Subject.CommonName != domains[0] {
+		t.Errorf("Expected CommonName %s, got %s", domains[0], cert.Subject.CommonName)
+	}
+
+	// Check DNS names
+	if len(cert.DNSNames) != len(domains) {
+		t.Errorf("Expected %d DNS names, got %d", len(domains), len(cert.DNSNames))
+	}
+
+	// Verify against CA
+	roots := x509.NewCertPool()
+	roots.AddCert(caCert)
+	opts := x509.VerifyOptions{
+		DNSName: domains[0],
+		Roots:   roots,
+	}
+
+	if _, err := cert.Verify(opts); err != nil {
+		t.Errorf("Failed to verify certificate against CA: %v", err)
+	}
+
+	// Test GetServerTLSConfig
+	tlsConfig, err := cm.GetServerTLSConfig(domains)
+	if err != nil {
+		t.Fatalf("Failed to get TLS config: %v", err)
+	}
+
+	if tlsConfig == nil {
+		t.Fatal("TLS config is nil")
+	}
+
+	if len(tlsConfig.Certificates) == 0 {
+		t.Fatal("TLS config has no certificates")
+	}
+
+	// Test certificate regeneration if domains change
+	newDomains := append(domains, "mac.fritz.box")
+	tlsConfig2, err := cm.GetServerTLSConfig(newDomains)
+	if err != nil {
+		t.Fatalf("Failed to get updated TLS config: %v", err)
+	}
+	if len(tlsConfig2.Certificates[0].Leaf.DNSNames) < 3 {
+		// Note: tls.LoadX509KeyPair doesn't populate Leaf by default.
+		// We should parse it manually or rely on the file existence/content.
+		certBytes, _ := os.ReadFile(cm.GetServerCertPEMPath())
+		block, _ := pem.Decode(certBytes)
+		cert, _ := x509.ParseCertificate(block.Bytes)
+		found := false
+		for _, d := range cert.DNSNames {
+			if d == "mac.fritz.box" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Regenerated certificate does not contain new domain")
+		}
+	}
+}

pkg/service/datastore/datastore.go

@@ -42,12 +42,12 @@ func NewDataStore(dataDir string) *DataStore {
 
 // AccountDir returns the directory path for a specific account.
 func (ds *DataStore) AccountDir(account string) string {
-	return filepath.Join(ds.DataDir, account)
+	return filepath.Join(ds.DataDir, "accounts", account)
 }
 
 // AccountDevicesDir returns the devices directory path for a specific account.
 func (ds *DataStore) AccountDevicesDir(account string) string {
-	return filepath.Join(ds.DataDir, account, constants.DevicesDir)
+	return filepath.Join(ds.AccountDir(account), constants.DevicesDir)
 }
 
 // AccountDeviceDir returns the directory path for a specific device within an account.
@@ -132,7 +132,10 @@ func (ds *DataStore) ListAllDevices() ([]models.ServiceDeviceInfo, error) {
 			}
 
 			accDevices := ds.listDevicesInAccount(dir, acc.Name())
-			for _, info := range accDevices {
+			for i := range accDevices {
+				info := accDevices[i]
+				info.AccountID = acc.Name()
+
 				key := info.DeviceID
 				if key == "" {
 					key = info.IPAddress
@@ -151,13 +154,13 @@ func (ds *DataStore) ListAllDevices() ([]models.ServiceDeviceInfo, error) {
 
 func (ds *DataStore) getPossibleDataDirs() []string {
 	dirs := []string{}
-	if exists(ds.DataDir) {
-		dirs = append(dirs, ds.DataDir)
+	if exists(filepath.Join(ds.DataDir, "accounts")) {
+		dirs = append(dirs, filepath.Join(ds.DataDir, "accounts"))
 	}
 
-	// Also check soundcork-go/data if it's different and exists
-	altDir := "soundcork-go/data"
-	if ds.DataDir != altDir && exists(altDir) {
+	// Also check st-go/data/accounts if it's different and exists
+	altDir := "st-go/data/accounts"
+	if filepath.Join(ds.DataDir, "accounts") != altDir && exists(altDir) {
 		dirs = append(dirs, altDir)
 	}
 
@@ -219,6 +222,7 @@ func (ds *DataStore) parseDeviceInfoFile(path string) (*models.ServiceDeviceInfo
 			Type      string `xml:"type,attr"`
 			IPAddress string `xml:"ipAddress"`
 		} `xml:"networkInfo"`
+		DiscoveryMethod string `xml:"discoveryMethod"`
 	}
 
 	if err := xml.Unmarshal(data, &info); err != nil {
@@ -226,9 +230,10 @@ func (ds *DataStore) parseDeviceInfoFile(path string) (*models.ServiceDeviceInfo
 	}
 
 	deviceInfo := &models.ServiceDeviceInfo{
-		DeviceID:    info.DeviceID,
-		ProductCode: fmt.Sprintf("%s %s", info.Type, info.ModuleType),
-		Name:        info.Name,
+		DeviceID:        info.DeviceID,
+		ProductCode:     fmt.Sprintf("%s %s", info.Type, info.ModuleType),
+		Name:            info.Name,
+		DiscoveryMethod: info.DiscoveryMethod,
 	}
 
 	for _, comp := range info.Components {
@@ -250,9 +255,9 @@ func (ds *DataStore) parseDeviceInfoFile(path string) (*models.ServiceDeviceInfo
 	return deviceInfo, nil
 }
 
-// GetPresets retrieves all presets for the specified account.
-func (ds *DataStore) GetPresets(account string) ([]models.ServicePreset, error) {
-	path := filepath.Join(ds.AccountDir(account), constants.PresetsFile)
+// GetPresets retrieves all presets for the specified account and device.
+func (ds *DataStore) GetPresets(account, device string) ([]models.ServicePreset, error) {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.PresetsFile)
 
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -303,9 +308,9 @@ func (ds *DataStore) GetPresets(account string) ([]models.ServicePreset, error)
 	return presets, nil
 }
 
-// SavePresets saves the preset list for the specified account.
-func (ds *DataStore) SavePresets(account string, presets []models.ServicePreset) error {
-	path := filepath.Join(ds.AccountDir(account), constants.PresetsFile)
+// SavePresets saves the preset list for the specified account and device.
+func (ds *DataStore) SavePresets(account, device string, presets []models.ServicePreset) error {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.PresetsFile)
 
 	type PresetXML struct {
 		ID          string `xml:"id,attr"`
@@ -357,9 +362,9 @@ func (ds *DataStore) SavePresets(account string, presets []models.ServicePreset)
 	return os.WriteFile(path, append(header, data...), 0644)
 }
 
-// GetRecents retrieves all recent items for the specified account.
-func (ds *DataStore) GetRecents(account string) ([]models.ServiceRecent, error) {
-	path := filepath.Join(ds.AccountDir(account), constants.RecentsFile)
+// GetRecents retrieves all recent items for the specified account and device.
+func (ds *DataStore) GetRecents(account, device string) ([]models.ServiceRecent, error) {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.RecentsFile)
 
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -410,9 +415,9 @@ func (ds *DataStore) GetRecents(account string) ([]models.ServiceRecent, error)
 	return recents, nil
 }
 
-// SaveRecents saves the recent items list for the specified account.
-func (ds *DataStore) SaveRecents(account string, recents []models.ServiceRecent) error {
-	path := filepath.Join(ds.AccountDir(account), constants.RecentsFile)
+// SaveRecents saves the recent items list for the specified account and device.
+func (ds *DataStore) SaveRecents(account, device string, recents []models.ServiceRecent) error {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.RecentsFile)
 
 	type RecentXML struct {
 		ID          string `xml:"id,attr"`
@@ -494,13 +499,14 @@ func (ds *DataStore) SaveDeviceInfo(account, device string, info *models.Service
 	}
 
 	type InfoXML struct {
-		XMLName     xml.Name         `xml:"info"`
-		DeviceID    string           `xml:"deviceID,attr"`
-		Name        string           `xml:"name"`
-		Type        string           `xml:"type"`
-		ModuleType  string           `xml:"moduleType"`
-		Components  []ComponentXML   `xml:"components>component"`
-		NetworkInfo []NetworkInfoXML `xml:"networkInfo"`
+		XMLName         xml.Name         `xml:"info"`
+		DeviceID        string           `xml:"deviceID,attr"`
+		Name            string           `xml:"name"`
+		Type            string           `xml:"type"`
+		ModuleType      string           `xml:"moduleType"`
+		Components      []ComponentXML   `xml:"components>component"`
+		NetworkInfo     []NetworkInfoXML `xml:"networkInfo"`
+		DiscoveryMethod string           `xml:"discoveryMethod,omitempty"`
 	}
 
 	// Parsing product code back to type and moduleType (best effort)
@@ -539,6 +545,7 @@ func (ds *DataStore) SaveDeviceInfo(account, device string, info *models.Service
 				IPAddress: info.IPAddress,
 			},
 		},
+		DiscoveryMethod: info.DiscoveryMethod,
 	}
 
 	data, err := xml.MarshalIndent(ix, "", "    ")
@@ -557,9 +564,9 @@ func (ds *DataStore) RemoveDevice(account, device string) error {
 	return os.RemoveAll(dir)
 }
 
-// GetConfiguredSources retrieves all configured sources for the specified account.
-func (ds *DataStore) GetConfiguredSources(account string) ([]models.ConfiguredSource, error) {
-	path := filepath.Join(ds.AccountDir(account), constants.SourcesFile)
+// GetConfiguredSources retrieves all configured sources for the specified account and device.
+func (ds *DataStore) GetConfiguredSources(account, device string) ([]models.ConfiguredSource, error) {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
 
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -567,81 +574,52 @@ func (ds *DataStore) GetConfiguredSources(account string) ([]models.ConfiguredSo
 	}
 
 	var sourcesWrap struct {
-		Sources []struct {
-			DisplayName string `xml:"displayName,attr"`
-			ID          string `xml:"id,attr"`
-			Secret      string `xml:"secret,attr"`
-			SecretType  string `xml:"secretType,attr"`
-			SourceKey   struct {
-				Account string `xml:"account,attr"`
-				Type    string `xml:"type,attr"`
-			} `xml:"sourceKey"`
-		} `xml:"source"`
+		Sources []models.ConfiguredSource `xml:"source"`
 	}
 
 	if err := xml.Unmarshal(data, &sourcesWrap); err != nil {
 		return nil, fmt.Errorf("malformed sources XML at %s: %w", path, err)
 	}
 
-	var sources []models.ConfiguredSource
-
-	lastID := 100001
-
-	for _, s := range sourcesWrap.Sources {
-		id := s.ID
-		if id == "" {
-			id = strconv.Itoa(lastID)
-			lastID++
+	for i := range sourcesWrap.Sources {
+		s := &sourcesWrap.Sources[i]
+		if s.ID == "" {
+			s.ID = strconv.Itoa(100001 + i)
 		}
-
-		sources = append(sources, models.ConfiguredSource{
-			DisplayName:      s.DisplayName,
-			ID:               id,
-			Secret:           s.Secret,
-			SecretType:       s.SecretType,
-			SourceKeyType:    s.SourceKey.Type,
-			SourceKeyAccount: s.SourceKey.Account,
-		})
+		// Sync legacy fields
+		s.SourceKeyType = s.SourceKey.Type
+		s.SourceKeyAccount = s.SourceKey.Account
 	}
 
-	return sources, nil
+	return sourcesWrap.Sources, nil
 }
 
-// SaveConfiguredSources saves the configured sources list for the specified account.
-func (ds *DataStore) SaveConfiguredSources(account string, sources []models.ConfiguredSource) error {
-	path := filepath.Join(ds.AccountDir(account), constants.SourcesFile)
+// SaveConfiguredSources saves the configured sources list for the specified account and device.
+func (ds *DataStore) SaveConfiguredSources(account, device string, sources []models.ConfiguredSource) error {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
 	if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
 		return err
 	}
 
-	type sourceXML struct {
-		DisplayName string `xml:"displayName,attr"`
-		ID          string `xml:"id,attr"`
-		Secret      string `xml:"secret,attr"`
-		SecretType  string `xml:"secretType,attr"`
-		SourceKey   struct {
-			Account string `xml:"account,attr"`
-			Type    string `xml:"type,attr"`
-		} `xml:"sourceKey"`
-	}
-
 	type sourcesWrap struct {
-		XMLName xml.Name    `xml:"sources"`
-		Sources []sourceXML `xml:"source"`
+		XMLName xml.Name                  `xml:"sources"`
+		Sources []models.ConfiguredSource `xml:"source"`
 	}
 
-	wrap := sourcesWrap{}
-
-	for _, s := range sources {
-		sx := sourceXML{
-			DisplayName: s.DisplayName,
-			ID:          s.ID,
-			Secret:      s.Secret,
-			SecretType:  s.SecretType,
+	// Ensure SourceKey is populated from legacy fields if necessary before saving
+	for i := range sources {
+		s := &sources[i]
+		if s.SourceKey.Type == "" && s.SourceKeyType != "" {
+			s.SourceKey.Type = s.SourceKeyType
 		}
-		sx.SourceKey.Account = s.SourceKeyAccount
-		sx.SourceKey.Type = s.SourceKeyType
-		wrap.Sources = append(wrap.Sources, sx)
+
+		if s.SourceKey.Account == "" && s.SourceKeyAccount != "" {
+			s.SourceKey.Account = s.SourceKeyAccount
+		}
+	}
+
+	wrap := sourcesWrap{
+		Sources: sources,
 	}
 
 	data, err := xml.MarshalIndent(wrap, "", "    ")
@@ -661,23 +639,12 @@ func (ds *DataStore) Initialize() error {
 		return fmt.Errorf("failed to create data directory: %w", err)
 	}
 
-	// Ensure default account exists
-	defaultDir := ds.AccountDir("default")
-	if err := os.MkdirAll(defaultDir, 0755); err != nil {
-		return fmt.Errorf("failed to create default account directory: %w", err)
-	}
-
-	// Ensure devices subdirectory for default account
-	if err := os.MkdirAll(ds.AccountDevicesDir("default"), 0755); err != nil {
-		return fmt.Errorf("failed to create default devices directory: %w", err)
-	}
-
 	return nil
 }
 
-// GetETagForPresets returns the ETag (modification time) for the presets file.
-func (ds *DataStore) GetETagForPresets(account string) int64 {
-	path := filepath.Join(ds.AccountDir(account), constants.PresetsFile)
+// GetETagForPresets returns the ETag (modification time) for the presets file for a specific device.
+func (ds *DataStore) GetETagForPresets(account, device string) int64 {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.PresetsFile)
 
 	info, err := os.Stat(path)
 	if err != nil {
@@ -687,9 +654,9 @@ func (ds *DataStore) GetETagForPresets(account string) int64 {
 	return info.ModTime().UnixNano() / int64(time.Millisecond)
 }
 
-// GetETagForSources returns the ETag (modification time) for the sources file.
-func (ds *DataStore) GetETagForSources(account string) int64 {
-	path := filepath.Join(ds.AccountDir(account), constants.SourcesFile)
+// GetETagForSources returns the ETag (modification time) for the sources file for a specific device.
+func (ds *DataStore) GetETagForSources(account, device string) int64 {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.SourcesFile)
 
 	info, err := os.Stat(path)
 	if err != nil {
@@ -699,9 +666,9 @@ func (ds *DataStore) GetETagForSources(account string) int64 {
 	return info.ModTime().UnixNano() / int64(time.Millisecond)
 }
 
-// GetETagForRecents returns the ETag (modification time) for the recents file.
-func (ds *DataStore) GetETagForRecents(account string) int64 {
-	path := filepath.Join(ds.AccountDir(account), constants.RecentsFile)
+// GetETagForRecents returns the ETag (modification time) for the recents file for a specific device.
+func (ds *DataStore) GetETagForRecents(account, device string) int64 {
+	path := filepath.Join(ds.AccountDeviceDir(account, device), constants.RecentsFile)
 
 	info, err := os.Stat(path)
 	if err != nil {
@@ -711,11 +678,11 @@ func (ds *DataStore) GetETagForRecents(account string) int64 {
 	return info.ModTime().UnixNano() / int64(time.Millisecond)
 }
 
-// GetETagForAccount returns the highest ETag among presets, sources, and recents for the account.
-func (ds *DataStore) GetETagForAccount(account string) int64 {
-	e1 := ds.GetETagForPresets(account)
-	e2 := ds.GetETagForSources(account)
-	e3 := ds.GetETagForRecents(account)
+// GetETagForAccount returns the highest ETag among presets, sources, and recents for the account and device.
+func (ds *DataStore) GetETagForAccount(account, device string) int64 {
+	e1 := ds.GetETagForPresets(account, device)
+	e2 := ds.GetETagForSources(account, device)
+	e3 := ds.GetETagForRecents(account, device)
 
 	maxETag := e1
 	if e2 > maxETag {
@@ -729,6 +696,64 @@ func (ds *DataStore) GetETagForAccount(account string) int64 {
 	return maxETag
 }
 
+// Settings represents the global service settings.
+type Settings struct {
+	ServerURL            string         `json:"server_url"`
+	SoundcorkURL         string         `json:"soundcork_url"`
+	HTTPServerURL        string         `json:"https_server_url,omitempty"`
+	RedactLogs           bool           `json:"redact_logs"`
+	LogBodies            bool           `json:"log_bodies"`
+	RecordInteractions   bool           `json:"record_interactions"`
+	DiscoveryInterval    string         `json:"discovery_interval,omitempty"`
+	DiscoveryEnabled     bool           `json:"discovery_enabled"`
+	EnableSoundcorkProxy bool           `json:"enable_soundcork_proxy"`
+	Shortcuts            map[string]int `json:"shortcuts,omitempty"`
+}
+
+// GetSettings retrieves the global service settings.
+func (ds *DataStore) GetSettings() (Settings, error) {
+	if ds == nil || ds.DataDir == "" {
+		return Settings{}, nil
+	}
+
+	path := filepath.Join(ds.DataDir, "settings.json")
+	if !exists(path) {
+		return Settings{}, nil
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return Settings{}, err
+	}
+
+	var settings Settings
+	if err := json.Unmarshal(data, &settings); err != nil {
+		return Settings{}, err
+	}
+
+	return settings, nil
+}
+
+// SaveSettings saves the global service settings.
+func (ds *DataStore) SaveSettings(settings Settings) error {
+	if ds == nil || ds.DataDir == "" {
+		return nil
+	}
+
+	if err := os.MkdirAll(ds.DataDir, 0755); err != nil {
+		return fmt.Errorf("failed to create data directory: %w", err)
+	}
+
+	path := filepath.Join(ds.DataDir, "settings.json")
+
+	data, err := json.MarshalIndent(settings, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	return os.WriteFile(path, data, 0644)
+}
+
 // SaveUsageStats saves usage statistics to the datastore.
 func (ds *DataStore) SaveUsageStats(stats models.UsageStats) error {
 	dir := filepath.Join(ds.DataDir, "stats", "usage")

pkg/service/datastore/datastore_test.go

@@ -9,7 +9,7 @@ import (
 )
 
 func TestDataStore(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -22,8 +22,9 @@ func TestDataStore(t *testing.T) {
 
 	// Test Save/Get DeviceInfo
 	info := &models.ServiceDeviceInfo{
-		DeviceID: device,
-		Name:     "Test Speaker",
+		DeviceID:  device,
+		Name:      "Test Speaker",
+		AccountID: account,
 	}
 
 	err = ds.SaveDeviceInfo(account, device, info)
@@ -49,12 +50,12 @@ func TestDataStore(t *testing.T) {
 		},
 	}
 
-	err = ds.SavePresets(account, presets)
+	err = ds.SavePresets(account, device, presets)
 	if err != nil {
 		t.Errorf("SavePresets failed: %v", err)
 	}
 
-	loadedPresets, err := ds.GetPresets(account)
+	loadedPresets, err := ds.GetPresets(account, device)
 	if err != nil {
 		t.Errorf("GetPresets failed: %v", err)
 	}
@@ -72,12 +73,12 @@ func TestDataStore(t *testing.T) {
 		},
 	}
 
-	err = ds.SaveRecents(account, recents)
+	err = ds.SaveRecents(account, device, recents)
 	if err != nil {
 		t.Errorf("SaveRecents failed: %v", err)
 	}
 
-	loadedRecents, err := ds.GetRecents(account)
+	loadedRecents, err := ds.GetRecents(account, device)
 	if err != nil {
 		t.Errorf("GetRecents failed: %v", err)
 	}
@@ -87,14 +88,14 @@ func TestDataStore(t *testing.T) {
 	}
 
 	// Test path helpers
-	expectedAccountDir := filepath.Join(tempDir, account)
+	expectedAccountDir := filepath.Join(tempDir, "accounts", account)
 	if ds.AccountDir(account) != expectedAccountDir {
 		t.Errorf("Expected account dir %s, got %s", expectedAccountDir, ds.AccountDir(account))
 	}
 }
 
 func TestListAllDevices_Empty(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-empty-test-*")
+	tempDir, err := os.MkdirTemp("", "st-empty-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -133,7 +134,7 @@ func TestListAllDevices_Empty(t *testing.T) {
 }
 
 func TestListAllDevices(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-list-test-*")
+	tempDir, err := os.MkdirTemp("", "st-list-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -151,6 +152,7 @@ func TestListAllDevices(t *testing.T) {
 		DeviceSerialNumber: deviceID,
 		ProductCode:        "SoundTouch 10",
 		FirmwareVersion:    "1.2.3",
+		AccountID:          account,
 	}
 
 	err = ds.SaveDeviceInfo(account, deviceID, info)
@@ -173,7 +175,7 @@ func TestListAllDevices(t *testing.T) {
 }
 
 func TestListAllDevices_EmptyDeviceID(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-empty-id-test-*")
+	tempDir, err := os.MkdirTemp("", "st-empty-id-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -185,8 +187,9 @@ func TestListAllDevices_EmptyDeviceID(t *testing.T) {
 	deviceID := ""
 
 	info := &models.ServiceDeviceInfo{
-		DeviceID: deviceID,
-		Name:     "Empty ID Speaker",
+		DeviceID:  deviceID,
+		Name:      "Empty ID Speaker",
+		AccountID: account,
 	}
 
 	// Use IP as fallback for device ID if it is empty
@@ -215,7 +218,7 @@ func TestListAllDevices_EmptyDeviceID(t *testing.T) {
 }
 
 func TestListAllDevices_MultipleEmptyIDs(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-multi-empty-test-*")
+	tempDir, err := os.MkdirTemp("", "st-multi-empty-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -230,11 +233,13 @@ func TestListAllDevices_MultipleEmptyIDs(t *testing.T) {
 		DeviceID:  "",
 		Name:      "Speaker 1",
 		IPAddress: "192.168.1.1",
+		AccountID: account,
 	}
 	info2 := &models.ServiceDeviceInfo{
 		DeviceID:  "",
 		Name:      "Speaker 2",
 		IPAddress: "192.168.1.2",
+		AccountID: account,
 	}
 
 	// We use the same logic as in main.go: use IP as fallback for directory name
@@ -259,7 +264,7 @@ func TestListAllDevices_MultipleEmptyIDs(t *testing.T) {
 }
 
 func TestListAllDevices_MalformedXML(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-malformed-test-*")
+	tempDir, err := os.MkdirTemp("", "st-malformed-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -294,29 +299,37 @@ func TestConfiguredSources(t *testing.T) {
 
 	sources := []models.ConfiguredSource{
 		{
-			DisplayName:      "Source 1",
-			ID:               "101",
-			Secret:           "secret1",
-			SecretType:       "type1",
+			DisplayName: "Source 1",
+			ID:          "101",
+			Secret:      "secret1",
+			SecretType:  "type1",
+			SourceKey: struct {
+				Type    string `xml:"type,attr"`
+				Account string `xml:"account,attr"`
+			}{Type: "TUNEIN", Account: "user1"},
 			SourceKeyType:    "TUNEIN",
 			SourceKeyAccount: "user1",
 		},
 		{
-			DisplayName:      "Source 2",
-			ID:               "102",
-			Secret:           "secret2",
-			SecretType:       "type2",
+			DisplayName: "Source 2",
+			ID:          "102",
+			Secret:      "secret2",
+			SecretType:  "type2",
+			SourceKey: struct {
+				Type    string `xml:"type,attr"`
+				Account string `xml:"account,attr"`
+			}{Type: "PANDORA", Account: "user2"},
 			SourceKeyType:    "PANDORA",
 			SourceKeyAccount: "user2",
 		},
 	}
 
-	err := ds.SaveConfiguredSources(account, sources)
+	err := ds.SaveConfiguredSources(account, "any", sources)
 	if err != nil {
 		t.Fatalf("SaveConfiguredSources failed: %v", err)
 	}
 
-	loadedSources, err := ds.GetConfiguredSources(account)
+	loadedSources, err := ds.GetConfiguredSources(account, "any")
 	if err != nil {
 		t.Fatalf("GetConfiguredSources failed: %v", err)
 	}
@@ -343,12 +356,12 @@ func TestConfiguredSources(t *testing.T) {
 		},
 	}
 
-	err = ds.SaveConfiguredSources(account, sources2)
+	err = ds.SaveConfiguredSources(account, "any", sources2)
 	if err != nil {
 		t.Fatal(err)
 	}
 
-	loadedSources2, err := ds.GetConfiguredSources(account)
+	loadedSources2, err := ds.GetConfiguredSources(account, "any")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -357,3 +370,44 @@ func TestConfiguredSources(t *testing.T) {
 		t.Error("Expected auto-assigned ID for source with empty ID")
 	}
 }
+
+func TestSettingsPersistence(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "settings-test-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ds := NewDataStore(tempDir)
+
+	settings := Settings{
+		ServerURL:         "http://myserver:8000",
+		SoundcorkURL:      "http://myproxy:8001",
+		LogBodies:         true,
+		DiscoveryInterval: "10m",
+		DiscoveryEnabled:  true,
+	}
+
+	err = ds.SaveSettings(settings)
+	if err != nil {
+		t.Fatalf("SaveSettings failed: %v", err)
+	}
+
+	loaded, err := ds.GetSettings()
+	if err != nil {
+		t.Fatalf("GetSettings failed: %v", err)
+	}
+
+	if loaded.ServerURL != settings.ServerURL {
+		t.Errorf("Expected ServerURL %s, got %s", settings.ServerURL, loaded.ServerURL)
+	}
+	if loaded.LogBodies != settings.LogBodies {
+		t.Errorf("Expected LogBodies %v, got %v", settings.LogBodies, loaded.LogBodies)
+	}
+	if loaded.DiscoveryInterval != settings.DiscoveryInterval {
+		t.Errorf("Expected DiscoveryInterval %s, got %s", settings.DiscoveryInterval, loaded.DiscoveryInterval)
+	}
+	if loaded.DiscoveryEnabled != settings.DiscoveryEnabled {
+		t.Errorf("Expected DiscoveryEnabled %v, got %v", settings.DiscoveryEnabled, loaded.DiscoveryEnabled)
+	}
+}

pkg/service/handlers/docs_consistency_test.go

@@ -0,0 +1,71 @@
+package handlers
+
+import (
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestDocsConsistency(t *testing.T) {
+	// Root of the project relative to this test file
+	// The test runs in the directory of the package
+	projectRoot := "../../.."
+	docsDir := filepath.Join(projectRoot, "docs")
+	summaryPath := filepath.Join(docsDir, "SUMMARY.md")
+
+	summaryContent, err := os.ReadFile(summaryPath)
+	if err != nil {
+		t.Fatalf("Failed to read SUMMARY.md: %v", err)
+	}
+
+	summaryText := string(summaryContent)
+
+	// List of directories to check
+	dirsToCheck := []string{".", "guides", "reference", "analysis"}
+
+	for _, dir := range dirsToCheck {
+		dirPath := filepath.Join(docsDir, dir)
+		err := filepath.WalkDir(dirPath, func(path string, d fs.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			if d.IsDir() {
+				// Don't recurse into subdirectories if we are checking the root,
+				// as they are handled separately or ignored (like archive)
+				if dir == "." && path != dirPath {
+					return filepath.SkipDir
+				}
+				return nil
+			}
+			if !strings.HasSuffix(d.Name(), ".md") {
+				return nil
+			}
+
+			// Skip SUMMARY.md itself
+			if d.Name() == "SUMMARY.md" {
+				return nil
+			}
+
+			// Get relative path from docs/
+			relPath, err := filepath.Rel(docsDir, path)
+			if err != nil {
+				return err
+			}
+
+			// Check if this file is linked in SUMMARY.md
+			// We look for [Label](relPath)
+			linkPattern := "(" + relPath + ")"
+			if !strings.Contains(summaryText, linkPattern) {
+				t.Errorf("Documentation file %s is not linked in docs/SUMMARY.md", relPath)
+			}
+
+			return nil
+		})
+
+		if err != nil {
+			t.Errorf("Error walking directory %s: %v", dir, err)
+		}
+	}
+}

pkg/service/handlers/handlers_docs.go

@@ -0,0 +1,127 @@
+package handlers
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/russross/blackfriday/v2"
+)
+
+// HandleDocs returns a handler for serving documentation files as HTML.
+func (s *Server) HandleDocs(w http.ResponseWriter, r *http.Request) {
+	path := strings.TrimPrefix(r.URL.Path, "/docs")
+
+	path = strings.TrimPrefix(path, "/")
+	if path == "" {
+		path = "guides/SURVIVAL-GUIDE.md"
+	}
+
+	// Ensure we only serve files from the docs directory
+	filePath := filepath.Join("docs", path)
+	if !strings.HasPrefix(filepath.Clean(filePath), "docs") {
+		http.Error(w, "Forbidden", http.StatusForbidden)
+		return
+	}
+
+	content, err := os.ReadFile(filePath)
+	if err != nil {
+		http.Error(w, "File not found", http.StatusNotFound)
+		return
+	}
+
+	// Load sidebar (SUMMARY.md)
+	summaryContent, _ := os.ReadFile(filepath.Join("docs", "SUMMARY.md"))
+
+	sidebar := ""
+	if len(summaryContent) > 0 {
+		// Render summary to HTML
+		sidebar = string(blackfriday.Run(summaryContent))
+		// Adjust links in sidebar to be relative to /docs/
+		sidebar = strings.ReplaceAll(sidebar, "href=\"guides/", "href=\"/docs/guides/")
+		sidebar = strings.ReplaceAll(sidebar, "href=\"reference/", "href=\"/docs/reference/")
+		sidebar = strings.ReplaceAll(sidebar, "href=\"analysis/", "href=\"/docs/analysis/")
+		// Fix relative links that don't have a directory prefix (root docs)
+		// We look for href="filename.md" and replace with href="/docs/filename.md"
+		// This avoids manual listing of every file.
+		sidebar = s.fixSidebarLinks(sidebar)
+	}
+
+	// Render markdown to HTML
+	output := blackfriday.Run(content)
+
+	// Wrap in a documentation template with sidebar
+	w.Header().Set("Content-Type", "text/html")
+	_, _ = fmt.Fprintf(w, `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>%s - Bose SoundTouch Toolkit Docs</title>
+    <link rel="icon" href="/media/favicon-braille.svg" type="image/svg+xml">
+    <link rel="stylesheet" href="/web/css/style.css">
+    <style>
+        body { margin: 0; padding: 0; display: flex; font-family: sans-serif; height: 100vh; overflow: hidden; }
+        .sidebar { width: 300px; background: #f8f9fa; border-right: 1px solid #dee2e6; padding: 20px; overflow-y: auto; flex-shrink: 0; }
+        .content-area { flex-grow: 1; overflow-y: auto; padding: 40px; }
+        .markdown-body { max-width: 800px; margin: 0 auto; line-height: 1.6; color: #333; }
+        h1, h2, h3 { color: #2196F3; }
+        pre { background: #f4f4f4; padding: 15px; border-radius: 5px; overflow-x: auto; }
+        code { font-family: monospace; background: #eee; padding: 2px 4px; border-radius: 3px; }
+        pre code { background: none; padding: 0; }
+        a { color: #2196F3; text-decoration: none; }
+        a:hover { text-decoration: underline; }
+        .back-link { margin-bottom: 20px; display: block; font-weight: bold; }
+        .sidebar h2 { font-size: 1.1em; margin-top: 20px; color: #666; text-transform: uppercase; letter-spacing: 1px; }
+        .sidebar ul { list-style: none; padding: 0; }
+        .sidebar li { margin-bottom: 8px; }
+        .sidebar a { color: #444; font-size: 0.95em; }
+        .sidebar a:hover { color: #2196F3; }
+    </style>
+</head>
+<body>
+    <div class="sidebar">
+        <a href="/" class="back-link">&larr; Back to Toolkit</a>
+        %s
+    </div>
+    <div class="content-area">
+        <div class="markdown-body">
+            %s
+        </div>
+   	</div>
+</body>
+</html>`, path, sidebar, output)
+}
+
+// fixSidebarLinks ensures that relative links in the SUMMARY.md (sidebar)
+// are correctly prefixed with /docs/ for the web UI.
+func (s *Server) fixSidebarLinks(sidebar string) string {
+	// Root links like [Label](file.md) become href="file.md"
+	// We want href="/docs/file.md", but only if it doesn't already start with /docs/
+	// and isn't an external link.
+	// Since blackfriday renders [Label](file.md) as <a href="file.md">
+
+	// A simple but effective way is to use a regex or just check for common patterns.
+	// We already handled subdirectories. Now we handle files in the root of docs/
+
+	// We'll look for href="filename.md" where filename doesn't contain a slash
+	// and isn't already prefixed.
+
+	// Since we know our doc files always end in .md, we can look for that.
+	lines := strings.Split(sidebar, "\n")
+	for i, line := range lines {
+		if strings.Contains(line, "href=\"") && !strings.Contains(line, "href=\"/docs/") && !strings.Contains(line, "://") {
+			// Extract filename
+			start := strings.Index(line, "href=\"") + 6
+			end := strings.Index(line[start:], "\"") + start
+			filename := line[start:end]
+
+			if strings.HasSuffix(filename, ".md") && !strings.Contains(filename, "/") {
+				lines[i] = strings.ReplaceAll(line, "href=\""+filename+"\"", "href=\"/docs/"+filename+"\"")
+			}
+		}
+	}
+
+	return strings.Join(lines, "\n")
+}

pkg/service/handlers/handlers_etag_test.go

@@ -16,24 +16,26 @@ const normalizedEtag = "Etag"
 const caseSensitiveETag = "ETag"
 
 func TestMargeETags(t *testing.T) {
-	tempDir, _ := os.MkdirTemp("", "soundcork-etag-test-*")
+	tempDir, _ := os.MkdirTemp("", "st-etag-test-*")
 
 	defer func() { _ = os.RemoveAll(tempDir) }()
 
 	ds := datastore.NewDataStore(tempDir)
 
 	account := "12345"
-	accountDir := filepath.Join(tempDir, account)
-	_ = os.MkdirAll(accountDir, 0755)
+	deviceID := "DEV1"
+	accountDir := filepath.Join(tempDir, "accounts", account)
+	deviceDir := filepath.Join(accountDir, "devices", deviceID)
+	_ = os.MkdirAll(deviceDir, 0755)
 
 	// Create some initial data
-	presetsFile := filepath.Join(accountDir, "Presets.xml")
+	presetsFile := filepath.Join(deviceDir, "Presets.xml")
 	_ = os.WriteFile(presetsFile, []byte("<presets/>"), 0644)
 
-	sourcesFile := filepath.Join(accountDir, "Sources.xml")
+	sourcesFile := filepath.Join(deviceDir, "Sources.xml")
 	_ = os.WriteFile(sourcesFile, []byte("<sources/>"), 0644)
 
-	recentsFile := filepath.Join(accountDir, "Recents.xml")
+	recentsFile := filepath.Join(deviceDir, "Recents.xml")
 	_ = os.WriteFile(recentsFile, []byte("<recents/>"), 0644)
 
 	// Ensure devices directory exists for AccountFull

pkg/service/handlers/handlers_marge.go

@@ -36,7 +36,9 @@ func (s *Server) HandleMargeSourceProviders(w http.ResponseWriter, r *http.Reque
 func (s *Server) HandleMargeAccountFull(w http.ResponseWriter, r *http.Request) {
 	account := chi.URLParam(r, "account")
 
-	etag := strconv.FormatInt(s.ds.GetETagForAccount(account), 10)
+	device := r.URL.Query().Get("device")
+
+	etag := strconv.FormatInt(s.ds.GetETagForAccount(account, device), 10)
 	if r.Header.Get("If-None-Match") == etag {
 		w.WriteHeader(http.StatusNotModified)
 		return
@@ -58,6 +60,85 @@ func (s *Server) HandleMargePowerOn(w http.ResponseWriter, _ *http.Request) {
 	w.WriteHeader(http.StatusOK)
 }
 
+// HandleMargeAccountProfile returns the account profile.
+func (s *Server) HandleMargeAccountProfile(w http.ResponseWriter, r *http.Request) {
+	accountID := chi.URLParam(r, "account")
+
+	// Mock profile data
+	profile := models.AccountProfileResponse{
+		AccountID:    accountID,
+		Email:        "user@example.com",
+		FirstName:    "SoundTouch",
+		LastName:     "User",
+		CountryCode:  "US",
+		LanguageCode: "en",
+	}
+
+	data, err := xml.MarshalIndent(profile, "", "  ")
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/xml")
+	_, _ = w.Write([]byte(xml.Header))
+	_, _ = w.Write(data)
+}
+
+// HandleMargeUpdateAccountProfile updates the account profile.
+func (s *Server) HandleMargeUpdateAccountProfile(w http.ResponseWriter, _ *http.Request) {
+	// Stub implementation
+	w.WriteHeader(http.StatusOK)
+}
+
+// HandleMargeChangePassword changes the account password.
+func (s *Server) HandleMargeChangePassword(w http.ResponseWriter, _ *http.Request) {
+	// Stub implementation
+	w.WriteHeader(http.StatusOK)
+}
+
+// HandleMargeGetEmailAddress returns the account email address.
+func (s *Server) HandleMargeGetEmailAddress(w http.ResponseWriter, _ *http.Request) {
+	resp := models.EmailAddressResponse{
+		Email: "user@example.com",
+	}
+
+	data, err := xml.MarshalIndent(resp, "", "  ")
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/xml")
+	_, _ = w.Write([]byte(xml.Header))
+	_, _ = w.Write(data)
+}
+
+// HandleMargeGetDeviceSettings returns device settings.
+func (s *Server) HandleMargeGetDeviceSettings(w http.ResponseWriter, _ *http.Request) {
+	resp := models.DeviceSettingsResponse{
+		Settings: []models.DeviceSetting{
+			{Name: "CLOCK_FORMAT", Value: "24HR"},
+		},
+	}
+
+	data, err := xml.MarshalIndent(resp, "", "  ")
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/xml")
+	_, _ = w.Write([]byte(xml.Header))
+	_, _ = w.Write(data)
+}
+
+// HandleMargeUpdateDeviceSettings updates device settings.
+func (s *Server) HandleMargeUpdateDeviceSettings(w http.ResponseWriter, _ *http.Request) {
+	// Stub implementation
+	w.WriteHeader(http.StatusOK)
+}
+
 // HandleMargeSoftwareUpdate returns the Marge software update information.
 func (s *Server) HandleMargeSoftwareUpdate(w http.ResponseWriter, r *http.Request) {
 	etag := "default-embedded"
@@ -79,14 +160,15 @@ func (s *Server) HandleMargeSoftwareUpdate(w http.ResponseWriter, r *http.Reques
 // HandleMargePresets returns the Marge presets for a device.
 func (s *Server) HandleMargePresets(w http.ResponseWriter, r *http.Request) {
 	account := chi.URLParam(r, "account")
+	device := chi.URLParam(r, "device")
 
-	etag := strconv.FormatInt(s.ds.GetETagForPresets(account), 10)
+	etag := strconv.FormatInt(s.ds.GetETagForPresets(account, device), 10)
 	if r.Header.Get("If-None-Match") == etag {
 		w.WriteHeader(http.StatusNotModified)
 		return
 	}
 
-	data, err := marge.PresetsToXML(s.ds, account)
+	data, err := marge.PresetsToXML(s.ds, account, device)
 	if err != nil {
 		http.Error(w, err.Error(), http.StatusInternalServerError)
 		return
@@ -102,7 +184,7 @@ func (s *Server) HandleMargeUpdatePreset(w http.ResponseWriter, r *http.Request)
 	account := chi.URLParam(r, "account")
 	device := chi.URLParam(r, "device")
 
-	etag := strconv.FormatInt(s.ds.GetETagForPresets(account), 10)
+	etag := strconv.FormatInt(s.ds.GetETagForPresets(account, device), 10)
 	w.Header()["ETag"] = []string{etag}
 
 	presetNumberStr := chi.URLParam(r, "presetNumber")
@@ -134,7 +216,7 @@ func (s *Server) HandleMargeAddRecent(w http.ResponseWriter, r *http.Request) {
 	account := chi.URLParam(r, "account")
 	device := chi.URLParam(r, "device")
 
-	etag := strconv.FormatInt(s.ds.GetETagForRecents(account), 10)
+	etag := strconv.FormatInt(s.ds.GetETagForRecents(account, device), 10)
 	w.Header()["ETag"] = []string{etag}
 
 	body, err := io.ReadAll(r.Body)
@@ -199,11 +281,22 @@ func (s *Server) HandleMargeProviderSettings(w http.ResponseWriter, r *http.Requ
 func (s *Server) HandleMargeStreamingToken(w http.ResponseWriter, _ *http.Request) {
 	// Simple mock token for offline use.
 	// In a real production environment, this would be a JWT or similar signed token.
-	// Some speakers might expect a specific format; soundcork uses a distinctive prefix
+	// Some speakers might expect a specific format; we use a distinctive prefix
 	// to indicate it's a locally generated token.
-	token := "soundcork-local-token-" + strconv.FormatInt(time.Now().Unix(), 10)
-	w.Header().Set("Authorization", "Bearer "+token)
+	tokenValue := "st-local-token-" + strconv.FormatInt(time.Now().Unix(), 10)
+	bearerToken := models.NewBearerToken(tokenValue)
+
+	data, err := xml.Marshal(bearerToken)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/vnd.bose.streaming-v1.2+xml")
+	w.Header().Set("Authorization", bearerToken.GetAuthHeader())
 	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte(xml.Header))
+	_, _ = w.Write(data)
 }
 
 // HandleMargeCustomerSupport handles Marge customer support uploads.

pkg/service/handlers/handlers_marge_stockholm_test.go

@@ -0,0 +1,102 @@
+package handlers
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestMargeStockholmHandlers(t *testing.T) {
+	r, _ := setupRouter("http://localhost:8001", nil)
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	t.Run("HandleMargeAccountProfile GET", func(t *testing.T) {
+		res, err := http.Get(ts.URL + "/customer/account/12345")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+
+		if res.StatusCode != http.StatusOK {
+			t.Errorf("Expected status OK, got %v", res.Status)
+		}
+
+		body, _ := io.ReadAll(res.Body)
+		if !strings.Contains(string(body), "<accountID>12345</accountID>") {
+			t.Errorf("Response missing account ID: %s", string(body))
+		}
+	})
+
+	t.Run("HandleMargeUpdateAccountProfile POST", func(t *testing.T) {
+		res, err := http.Post(ts.URL+"/customer/account/12345", "application/xml", strings.NewReader("<profile/>"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+
+		if res.StatusCode != http.StatusOK {
+			t.Errorf("Expected status OK, got %v", res.Status)
+		}
+	})
+
+	t.Run("HandleMargeChangePassword POST", func(t *testing.T) {
+		res, err := http.Post(ts.URL+"/customer/account/12345/password", "application/xml", strings.NewReader("<password/>"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+
+		if res.StatusCode != http.StatusOK {
+			t.Errorf("Expected status OK, got %v", res.Status)
+		}
+	})
+
+	t.Run("HandleMargeGetEmailAddress GET", func(t *testing.T) {
+		res, err := http.Get(ts.URL + "/marge/streaming/account/12345/emailaddress")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+
+		if res.StatusCode != http.StatusOK {
+			t.Errorf("Expected status OK, got %v", res.Status)
+		}
+
+		body, _ := io.ReadAll(res.Body)
+		if !strings.Contains(string(body), "user@example.com") {
+			t.Errorf("Response missing email: %s", string(body))
+		}
+	})
+
+	t.Run("HandleMargeGetDeviceSettings GET", func(t *testing.T) {
+		res, err := http.Get(ts.URL + "/marge/streaming/device_setting/account/123/device/DEV1/device_settings")
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+
+		if res.StatusCode != http.StatusOK {
+			t.Errorf("Expected status OK, got %v", res.Status)
+		}
+
+		body, _ := io.ReadAll(res.Body)
+		if !strings.Contains(string(body), "CLOCK_FORMAT") {
+			t.Errorf("Response missing settings: %s", string(body))
+		}
+	})
+
+	t.Run("HandleMargeUpdateDeviceSettings POST", func(t *testing.T) {
+		res, err := http.Post(ts.URL+"/marge/streaming/device_setting/account/123/device/DEV1/device_settings", "application/xml", strings.NewReader("<settings/>"))
+		if err != nil {
+			t.Fatal(err)
+		}
+		defer res.Body.Close()
+
+		if res.StatusCode != http.StatusOK {
+			t.Errorf("Expected status OK, got %v", res.Status)
+		}
+	})
+}

pkg/service/handlers/handlers_marge_test.go

@@ -61,7 +61,7 @@ func TestMargeSoftwareUpdate(t *testing.T) {
 }
 
 func TestMargeAccountFull(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
@@ -72,7 +72,7 @@ func TestMargeAccountFull(t *testing.T) {
 
 	account := "12345"
 	deviceID := "ABCDE"
-	accountDir := filepath.Join(tempDir, account)
+	accountDir := filepath.Join(tempDir, "accounts", account)
 
 	deviceDir := filepath.Join(accountDir, "devices", deviceID)
 	err = os.MkdirAll(deviceDir, 0755)
@@ -125,7 +125,7 @@ func TestMargeAccountFull(t *testing.T) {
 }
 
 func TestMargePresets(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
@@ -135,12 +135,14 @@ func TestMargePresets(t *testing.T) {
 	ds := datastore.NewDataStore(tempDir)
 
 	account := "12345"
+	deviceID := "any"
 
-	accountDir := filepath.Join(tempDir, account)
-	err = os.MkdirAll(accountDir, 0755)
+	accountDir := filepath.Join(tempDir, "accounts", account)
+	deviceDir := filepath.Join(accountDir, "devices", deviceID)
+	err = os.MkdirAll(deviceDir, 0755)
 
 	if err != nil {
-		t.Fatalf("Failed to create account dir: %v", err)
+		t.Fatalf("Failed to create device dir: %v", err)
 	}
 
 	r, _ := setupRouter("http://localhost:8001", ds)
@@ -149,24 +151,17 @@ func TestMargePresets(t *testing.T) {
 	defer ts.Close()
 
 	// Mock Sources.xml and Presets.xml
-	if err := os.WriteFile(filepath.Join(accountDir, "Sources.xml"), []byte(`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Sources.xml"), []byte(`
 		<sources>
-			<source id="123" type="Audio">
-				<createdOn>2012-09-19T12:43:00.000+00:00</createdOn>
-				<credential type="token"></credential>
-				<name>TUNEIN</name>
-				<sourceproviderid>1</sourceproviderid>
-				<sourcename>TUNEIN</sourcename>
-				<sourcesettings></sourcesettings>
-				<updatedOn>2012-09-19T12:43:00.000+00:00</updatedOn>
-				<username></username>
+			<source id="123" displayName="TUNEIN" secret="" secretType="Audio">
+				<sourceKey type="TUNEIN" account=""/>
 			</source>
 		</sources>
 	`), 0644); err != nil {
 		t.Fatalf("Failed to write Sources.xml: %v", err)
 	}
 
-	if err := os.WriteFile(filepath.Join(accountDir, "Presets.xml"), []byte(`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Presets.xml"), []byte(`
 		<presets>
 			<preset id="1">
 				<ContentItem source="TUNEIN" type="station" location="/station/s123" sourceAccount="" isPresetable="true">
@@ -201,7 +196,7 @@ func TestMargePresets(t *testing.T) {
 }
 
 func TestMargeUpdatePreset(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
@@ -211,26 +206,28 @@ func TestMargeUpdatePreset(t *testing.T) {
 	ds := datastore.NewDataStore(tempDir)
 
 	account := "12345"
+	deviceID := "DEV1"
 
-	accountDir := filepath.Join(tempDir, account)
-	err = os.MkdirAll(accountDir, 0755)
+	accountDir := filepath.Join(tempDir, "accounts", account)
+	deviceDir := filepath.Join(accountDir, "devices", deviceID)
+	err = os.MkdirAll(deviceDir, 0755)
 
 	if err != nil {
-		t.Fatalf("Failed to create account dir: %v", err)
+		t.Fatalf("Failed to create device dir: %v", err)
 	}
 
 	// Mock Sources.xml
-	if err := os.WriteFile(filepath.Join(accountDir, "Sources.xml"), []byte(`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Sources.xml"), []byte(`
 		<sources>
-			<source id="SRC1" type="Audio">
-				<sourcename>TUNEIN</sourcename>
+			<source id="SRC1" displayName="TUNEIN" secret="" secretType="Audio">
+				<sourceKey type="TUNEIN" account=""/>
 			</source>
 		</sources>
 	`), 0644); err != nil {
 		t.Fatalf("Failed to write Sources.xml: %v", err)
 	}
 
-	if err := os.WriteFile(filepath.Join(accountDir, "Presets.xml"), []byte(`<presets></presets>`), 0644); err != nil {
+	if err := os.WriteFile(filepath.Join(deviceDir, "Presets.xml"), []byte(`<presets></presets>`), 0644); err != nil {
 		t.Fatalf("Failed to write Presets.xml: %v", err)
 	}
 
@@ -248,7 +245,7 @@ func TestMargeUpdatePreset(t *testing.T) {
 			<containerArt>http://example.com/new.jpg</containerArt>
 		</preset>`
 
-	res, err := http.Post(ts.URL+"/marge/accounts/"+account+"/devices/DEV1/presets/1", "application/xml", strings.NewReader(payload))
+	res, err := http.Post(ts.URL+"/marge/accounts/"+account+"/devices/"+deviceID+"/presets/1", "application/xml", strings.NewReader(payload))
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -261,14 +258,14 @@ func TestMargeUpdatePreset(t *testing.T) {
 	}
 
 	// Verify file was saved
-	presetData, _ := os.ReadFile(filepath.Join(accountDir, "Presets.xml"))
+	presetData, _ := os.ReadFile(filepath.Join(deviceDir, "Presets.xml"))
 	if !strings.Contains(string(presetData), "New Preset") {
 		t.Error("Preset was not saved to datastore")
 	}
 }
 
 func TestMargeDeviceInfo(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
@@ -278,26 +275,28 @@ func TestMargeDeviceInfo(t *testing.T) {
 	ds := datastore.NewDataStore(tempDir)
 
 	account := "12345"
+	deviceID := "DEV1"
 
-	accountDir := filepath.Join(tempDir, account)
-	err = os.MkdirAll(accountDir, 0755)
+	accountDir := filepath.Join(tempDir, "accounts", account)
+	deviceDir := filepath.Join(accountDir, "devices", deviceID)
+	err = os.MkdirAll(deviceDir, 0755)
 
 	if err != nil {
-		t.Fatalf("Failed to create account dir: %v", err)
+		t.Fatalf("Failed to create device dir: %v", err)
 	}
 
 	// Mock Sources.xml
-	if err := os.WriteFile(filepath.Join(accountDir, "Sources.xml"), []byte(`
+	if err := os.WriteFile(filepath.Join(deviceDir, "Sources.xml"), []byte(`
 		<sources>
-			<source id="SRC1" type="Audio">
-				<sourcename>TUNEIN</sourcename>
+			<source id="SRC1" displayName="TUNEIN" secret="" secretType="Audio">
+				<sourceKey type="TUNEIN" account=""/>
 			</source>
 		</sources>
 	`), 0644); err != nil {
 		t.Fatalf("Failed to write Sources.xml: %v", err)
 	}
 
-	if err := os.WriteFile(filepath.Join(accountDir, "Recents.xml"), []byte(`<recents></recents>`), 0644); err != nil {
+	if err := os.WriteFile(filepath.Join(deviceDir, "Recents.xml"), []byte(`<recents></recents>`), 0644); err != nil {
 		t.Fatalf("Failed to write Recents.xml: %v", err)
 	}
 
@@ -314,7 +313,7 @@ func TestMargeDeviceInfo(t *testing.T) {
 			<contentItemType>station</contentItemType>
 		</recent>`
 
-	res, err := http.Post(ts.URL+"/marge/accounts/"+account+"/devices/DEV1/recents", "application/xml", strings.NewReader(payload))
+	res, err := http.Post(ts.URL+"/marge/accounts/"+account+"/devices/"+deviceID+"/recents", "application/xml", strings.NewReader(payload))
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -326,14 +325,14 @@ func TestMargeDeviceInfo(t *testing.T) {
 	}
 
 	// Verify file was saved
-	recentData, _ := os.ReadFile(filepath.Join(accountDir, "Recents.xml"))
+	recentData, _ := os.ReadFile(filepath.Join(deviceDir, "Recents.xml"))
 	if !strings.Contains(string(recentData), "Recent Station") {
 		t.Error("Recent was not saved to datastore")
 	}
 }
 
 func TestMargeAddRemoveDevice(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
@@ -344,7 +343,7 @@ func TestMargeAddRemoveDevice(t *testing.T) {
 
 	account := "12345"
 
-	accountDir := filepath.Join(tempDir, account)
+	accountDir := filepath.Join(tempDir, "accounts", account)
 	err = os.MkdirAll(accountDir, 0755)
 
 	if err != nil {
@@ -428,7 +427,7 @@ func TestMargePowerOn(t *testing.T) {
 }
 
 func TestMargeAdvancedFeatures(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
@@ -472,10 +471,23 @@ func TestMargeAdvancedFeatures(t *testing.T) {
 			t.Errorf("Expected status OK, got %v", res.Status)
 		}
 
+		contentType := res.Header.Get("Content-Type")
+		if contentType != "application/vnd.bose.streaming-v1.2+xml" {
+			t.Errorf("Invalid content type: %s", contentType)
+		}
+
 		token := res.Header.Get("Authorization")
-		if !strings.HasPrefix(token, "Bearer soundcork-local-token-") {
+		if !strings.HasPrefix(token, "Bearer st-local-token-") {
 			t.Errorf("Invalid token header: %s", token)
 		}
+
+		body, _ := io.ReadAll(res.Body)
+		if !strings.Contains(string(body), "<bearertoken") {
+			t.Errorf("Response body missing <bearertoken: %s", body)
+		}
+		if !strings.Contains(string(body), token) {
+			t.Errorf("Response body missing token value: %s", body)
+		}
 	})
 
 	t.Run("CustomerSupport", func(t *testing.T) {

pkg/service/handlers/handlers_media.go

@@ -8,16 +8,19 @@ import (
 	"strings"
 )
 
-//go:embed index.html
+//go:embed web/index.html
 var indexHTML []byte
 
-//go:embed soundcork/media/*
+//go:embed web/css/* web/js/*
+var webFS embed.FS
+
+//go:embed static/media/*
 var mediaFS embed.FS
 
-//go:embed soundcork/bmx_services.json
+//go:embed static/bmx_services.json
 var bmxServicesJSON []byte
 
-//go:embed soundcork/swupdate.xml
+//go:embed static/swupdate.xml
 var swUpdateXML []byte
 
 // HandleRoot returns the root endpoint response.
@@ -34,9 +37,17 @@ func (s *Server) HandleRoot(w http.ResponseWriter, r *http.Request) {
 	_, _ = w.Write(indexHTML)
 }
 
+// HandleWeb returns a handler for serving web resources.
+func (s *Server) HandleWeb() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		fs := http.FileServer(http.FS(webFS))
+		fs.ServeHTTP(w, r)
+	}
+}
+
 // HandleMedia returns a handler for serving media files.
 func (s *Server) HandleMedia() http.HandlerFunc {
-	subFS, _ := fs.Sub(mediaFS, "soundcork/media")
+	subFS, _ := fs.Sub(mediaFS, "static/media")
 
 	return func(w http.ResponseWriter, r *http.Request) {
 		fs := http.StripPrefix("/media/", http.FileServer(http.FS(subFS)))

pkg/service/handlers/handlers_media_test.go

@@ -35,8 +35,8 @@ func TestRootEndpoint(t *testing.T) {
 	}
 
 	body, _ := io.ReadAll(res.Body)
-	if !strings.Contains(string(body), "Soundcork Management") {
-		t.Errorf("Expected body to contain 'Soundcork Management', got %s", string(body))
+	if !strings.Contains(string(body), "AfterTouch") {
+		t.Errorf("Expected body to contain 'AfterTouch', got %s", string(body))
 	}
 }
 
@@ -80,7 +80,7 @@ func TestStaticMedia(t *testing.T) {
 	ts := httptest.NewServer(r)
 	defer ts.Close()
 
-	// Use a known file from soundcork/media
+	// Use a known file from static/media
 	res, err := http.Get(ts.URL + "/media/SiriusXM_Logo_Color.svg")
 	if err != nil {
 		t.Fatal(err)
@@ -97,3 +97,39 @@ func TestStaticMedia(t *testing.T) {
 		t.Errorf("Expected image/svg+xml content type, got %s", contentType)
 	}
 }
+
+func TestStaticWeb(t *testing.T) {
+	r, _ := setupRouter("http://localhost:8001", nil)
+
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	// 1. Test CSS
+	res, err := http.Get(ts.URL + "/web/css/style.css")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("CSS: Expected status OK, got %v", res.Status)
+	}
+	if !strings.Contains(res.Header.Get("Content-Type"), "text/css") {
+		t.Errorf("CSS: Expected text/css content type, got %s", res.Header.Get("Content-Type"))
+	}
+
+	// 2. Test JS
+	res, err = http.Get(ts.URL + "/web/js/script.js")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("JS: Expected status OK, got %v", res.Status)
+	}
+	if !strings.Contains(res.Header.Get("Content-Type"), "application/javascript") &&
+		!strings.Contains(res.Header.Get("Content-Type"), "text/javascript") {
+		t.Errorf("JS: Expected javascript content type, got %s", res.Header.Get("Content-Type"))
+	}
+}

pkg/service/handlers/handlers_proxy.go

@@ -1,6 +1,10 @@
 package handlers
 
 import (
+	"bytes"
+	"crypto/tls"
+	"io"
+	"log"
 	"net/http"
 	"net/http/httputil"
 	"net/url"
@@ -33,31 +37,155 @@ func (s *Server) HandleProxyRequest(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	lp := proxy.NewLoggingProxy(target.String(), s.proxyRedact)
-	lp.LogBody = s.proxyLogBody
+	s.ServeProxy(target)(w, r)
+}
 
-	proxy := httputil.NewSingleHostReverseProxy(target)
-	// Update director to set the correct host and path
-	originalDirector := proxy.Director
-	proxy.Director = func(req *http.Request) {
-		originalDirector(req)
-		req.Host = target.Host
-		req.URL.Path = target.Path
-		req.URL.RawQuery = r.URL.RawQuery
-		lp.LogRequest(req)
-	}
+// ServeProxy returns a handler that proxies to the given target.
+func (s *Server) ServeProxy(target *url.URL) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		lp := proxy.NewLoggingProxy(target.String(), s.proxyRedact)
+		lp.LogBody = s.proxyLogBody
+		lp.RecordEnabled = s.recordEnabled
+		lp.SetRecorder(s.recorder)
 
-	proxy.ModifyResponse = func(res *http.Response) error {
-		// Generic Header Preservation
-		if etags, ok := res.Header["Etag"]; ok {
-			delete(res.Header, "Etag")
-			res.Header["ETag"] = etags
+		rp := httputil.NewSingleHostReverseProxy(target)
+		rp.Transport = &http.Transport{
+			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
 		}
 
-		lp.LogResponse(res)
+		// Update director to set the correct host and path
+		originalDirector := rp.Director
+		rp.Director = func(req *http.Request) {
+			originalDirector(req)
+			req.Host = target.Host
+			// If target has a path, we should probably append or replace.
+			// For Bose upstream, it's usually just the domain.
+			if target.Path != "" && target.Path != "/" {
+				req.URL.Path = target.Path
+			}
 
-		return nil
+			lp.LogRequest(req)
+		}
+
+		rp.ModifyResponse = func(res *http.Response) error {
+			res.Header.Set("X-Proxy-Origin", "upstream")
+			// Generic Header Preservation
+			if etags, ok := res.Header["Etag"]; ok {
+				delete(res.Header, "Etag")
+				res.Header["ETag"] = etags
+			}
+
+			lp.LogResponse(res)
+
+			return nil
+		}
+
+		rp.ServeHTTP(w, r)
+	}
+}
+
+// HandleNotFound handles requests that don't match any route.
+func (s *Server) HandleNotFound(w http.ResponseWriter, r *http.Request) {
+	if s.enableSoundcorkProxy {
+		s.HandleSoundcorkWithFallback(w, r)
+		return
 	}
 
-	proxy.ServeHTTP(w, r)
+	s.HandleBoseProxy(w, r)
+}
+
+// HandleSoundcorkWithFallback tries Soundcork first, then Bose if Soundcork returns 404 or fails.
+func (s *Server) HandleSoundcorkWithFallback(w http.ResponseWriter, r *http.Request) {
+	target, _ := url.Parse(s.soundcorkURL)
+
+	// Buffer request body if any, to allow multiple proxy attempts
+	var bodyBytes []byte
+	if r.Body != nil {
+		bodyBytes, _ = io.ReadAll(r.Body)
+		_ = r.Body.Close()
+	}
+
+	// We use a custom response writer to catch 404s
+	rw := &fallbackResponseWriter{
+		ResponseWriter: w,
+		statusCode:     http.StatusOK,
+		buffer:         &bytes.Buffer{},
+	}
+
+	// Create a shallow copy of the request to avoid side effects between attempts
+	r2 := r.Clone(r.Context())
+	if bodyBytes != nil {
+		r2.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))
+	} else {
+		r2.Body = nil
+	}
+
+	// Remove RequestURI as it's not allowed in client requests
+	r2.RequestURI = ""
+
+	s.ServeProxy(target)(rw, r2)
+
+	if rw.statusCode == http.StatusNotFound || rw.statusCode == http.StatusBadGateway || rw.statusCode == http.StatusServiceUnavailable {
+		log.Printf("[PROXY] Soundcork returned %d for %s, falling back to Bose", rw.statusCode, r.URL.Path)
+
+		if !rw.wroteHeader {
+			// Restore original body if any
+			if bodyBytes != nil {
+				r.Body = io.NopCloser(bytes.NewBuffer(bodyBytes))
+			}
+
+			s.HandleBoseProxy(w, r)
+		}
+	}
+}
+
+type fallbackResponseWriter struct {
+	http.ResponseWriter
+	statusCode  int
+	wroteHeader bool
+	buffer      *bytes.Buffer
+}
+
+func (rw *fallbackResponseWriter) WriteHeader(code int) {
+	rw.statusCode = code
+	if code != http.StatusNotFound && code != http.StatusBadGateway && code != http.StatusServiceUnavailable {
+		rw.wroteHeader = true
+		rw.ResponseWriter.WriteHeader(code)
+	}
+}
+
+func (rw *fallbackResponseWriter) Write(b []byte) (int, error) {
+	if rw.statusCode == http.StatusNotFound || rw.statusCode == http.StatusBadGateway || rw.statusCode == http.StatusServiceUnavailable {
+		return len(b), nil // Drop the body
+	}
+
+	rw.wroteHeader = true
+
+	return rw.ResponseWriter.Write(b)
+}
+
+// HandleBoseProxy proxies the request to the Bose upstream.
+func (s *Server) HandleBoseProxy(w http.ResponseWriter, r *http.Request) {
+	host := r.Host
+	if host == "" {
+		host = "streaming.bose.com"
+	}
+
+	// Default to HTTPS for Bose services
+	scheme := "https"
+	if strings.HasPrefix(host, "localhost") || strings.HasPrefix(host, "127.0.0.1") || strings.HasPrefix(host, "::1") {
+		scheme = "http"
+	}
+
+	targetURL := scheme + "://" + host
+
+	target, err := url.Parse(targetURL)
+	if err != nil {
+		log.Printf("[PROXY_ERR] Failed to parse target URL %s: %v", targetURL, err)
+		http.Error(w, "Invalid upstream host", http.StatusBadGateway)
+
+		return
+	}
+
+	s.ServeProxy(target)(w, r)
 }

pkg/service/handlers/handlers_setup.go

@@ -1,9 +1,19 @@
 package handlers
 
 import (
+	"context"
 	"encoding/json"
+	"log"
 	"net/http"
+	"os"
+	"strconv"
+	"time"
 
+	"fmt"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
 	"github.com/go-chi/chi/v5"
 )
 
@@ -23,9 +33,54 @@ func (s *Server) HandleListDiscoveredDevices(w http.ResponseWriter, _ *http.Requ
 	}
 }
 
+// HandleAddManualDevice adds a device manually by IP.
+func (s *Server) HandleAddManualDevice(w http.ResponseWriter, r *http.Request) {
+	var body struct {
+		IP string `json:"ip"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+		http.Error(w, "Invalid request body", http.StatusBadRequest)
+		return
+	}
+
+	if body.IP == "" {
+		http.Error(w, "IP address is required", http.StatusBadRequest)
+		return
+	}
+
+	// Try to get live info
+	liveInfo, err := s.sm.GetLiveDeviceInfo(body.IP)
+	if err != nil {
+		// Even if we can't get live info, we might want to add it?
+		// But usually we need at least the serial for proper account management.
+		http.Error(w, "Failed to reach device at "+body.IP+": "+err.Error(), http.StatusBadGateway)
+		return
+	}
+
+	// Reuse handleDiscoveredDevice logic via a fake models.DiscoveredDevice
+	d := models.DiscoveredDevice{
+		Name:            liveInfo.Name,
+		Host:            body.IP,
+		ModelID:         liveInfo.Type,
+		SerialNo:        liveInfo.SerialNumber,
+		DiscoveryMethod: "manual",
+	}
+
+	s.handleDiscoveredDevice(d)
+	s.mergeOverlappingDevices()
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]bool{"ok": true}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
 // HandleTriggerDiscovery triggers a new device discovery scan.
-func (s *Server) HandleTriggerDiscovery(w http.ResponseWriter, r *http.Request) {
-	go s.DiscoverDevices(r.Context())
+func (s *Server) HandleTriggerDiscovery(w http.ResponseWriter, _ *http.Request) {
+	//nolint:contextcheck
+	go s.DiscoverDevices(context.Background())
 
 	w.WriteHeader(http.StatusAccepted)
 	_, _ = w.Write([]byte(`{"status": "Discovery started"}`))
@@ -41,19 +96,155 @@ func (s *Server) HandleGetDiscoveryStatus(w http.ResponseWriter, _ *http.Request
 	}
 }
 
+// HandleRemoveDevice removes a device from the datastore.
+func (s *Server) HandleRemoveDevice(w http.ResponseWriter, r *http.Request) {
+	deviceId := chi.URLParam(r, "deviceId")
+	if deviceId == "" {
+		http.Error(w, "Device ID is required", http.StatusBadRequest)
+		return
+	}
+
+	// Find which account this device belongs to.
+	devices, err := s.ds.ListAllDevices()
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	var found bool
+
+	for i := range devices {
+		if devices[i].DeviceID == deviceId {
+			err = s.ds.RemoveDevice(devices[i].AccountID, devices[i].DeviceID)
+			if err != nil {
+				http.Error(w, err.Error(), http.StatusInternalServerError)
+				return
+			}
+
+			found = true
+
+			break
+		}
+	}
+
+	if !found {
+		http.Error(w, "Device not found", http.StatusNotFound)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]bool{"ok": true}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
 // HandleGetSettings returns the current service settings.
 func (s *Server) HandleGetSettings(w http.ResponseWriter, _ *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
-	if err := json.NewEncoder(w).Encode(map[string]string{
-		"server_url": s.serverURL,
-		"proxy_url":  s.proxyURL,
+	s.mu.RLock()
+	serverURL, soundcorkURL, httpsServerURL := s.serverURL, s.soundcorkURL, s.httpsServerURL
+	discoveryInterval := s.discoveryInterval.String()
+	discoveryEnabled := s.discoveryEnabled
+	enableSoundcorkProxy := s.enableSoundcorkProxy
+	redact, logBody, record := s.proxyRedact, s.proxyLogBody, s.recordEnabled
+	shortcuts := s.shortcuts
+	s.mu.RUnlock()
+
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{
+		"server_url":             serverURL,
+		"soundcork_url":          soundcorkURL,
+		"https_server_url":       httpsServerURL,
+		"discovery_interval":     discoveryInterval,
+		"discovery_enabled":      discoveryEnabled,
+		"enable_soundcork_proxy": enableSoundcorkProxy,
+		"redact_logs":            redact,
+		"log_bodies":             logBody,
+		"record_interactions":    record,
+		"shortcuts":              shortcuts,
 	}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
 	}
 }
 
+// HandleUpdateSettings updates the service settings.
+func (s *Server) HandleUpdateSettings(w http.ResponseWriter, r *http.Request) {
+	var settings struct {
+		ServerURL            string         `json:"server_url"`
+		SoundcorkURL         string         `json:"soundcork_url"`
+		DiscoveryInterval    string         `json:"discovery_interval"`
+		DiscoveryEnabled     bool           `json:"discovery_enabled"`
+		EnableSoundcorkProxy bool           `json:"enable_soundcork_proxy"`
+		Shortcuts            map[string]int `json:"shortcuts"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&settings); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	interval, err := time.ParseDuration(settings.DiscoveryInterval)
+	if err != nil && settings.DiscoveryInterval != "" {
+		http.Error(w, "Invalid discovery interval: "+err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	s.mu.Lock()
+	s.serverURL = settings.ServerURL
+
+	s.soundcorkURL = settings.SoundcorkURL
+	if settings.DiscoveryInterval != "" {
+		s.discoveryInterval = interval
+	}
+
+	s.discoveryEnabled = settings.DiscoveryEnabled
+
+	s.enableSoundcorkProxy = settings.EnableSoundcorkProxy
+	if settings.Shortcuts != nil {
+		s.shortcuts = settings.Shortcuts
+	}
+
+	if s.sm != nil {
+		s.sm.ServerURL = settings.ServerURL
+	}
+
+	// Persist to datastore
+	// Access fields directly since we already hold the lock
+	currentRedact := s.proxyRedact
+	currentLogBody := s.proxyLogBody
+	currentRecord := s.recordEnabled
+	currentHTTPS := s.httpsServerURL
+
+	log.Printf("Saving updated settings to %s/settings.json", s.ds.DataDir)
+	err = s.ds.SaveSettings(datastore.Settings{
+		ServerURL:            s.serverURL,
+		SoundcorkURL:         s.soundcorkURL,
+		HTTPServerURL:        currentHTTPS,
+		RedactLogs:           currentRedact,
+		LogBodies:            currentLogBody,
+		RecordInteractions:   currentRecord,
+		DiscoveryInterval:    s.discoveryInterval.String(),
+		DiscoveryEnabled:     s.discoveryEnabled,
+		EnableSoundcorkProxy: s.enableSoundcorkProxy,
+		Shortcuts:            s.shortcuts,
+	})
+	s.mu.Unlock()
+
+	if err != nil {
+		http.Error(w, "Failed to save settings: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Settings updated"}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
 // HandleGetDeviceInfo returns live information for a device.
 func (s *Server) HandleGetDeviceInfo(w http.ResponseWriter, r *http.Request) {
 	deviceIP := chi.URLParam(r, "deviceIP")
@@ -126,6 +317,7 @@ func (s *Server) HandleMigrateDevice(w http.ResponseWriter, r *http.Request) {
 
 	targetURL := r.URL.Query().Get("target_url")
 	proxyURL := r.URL.Query().Get("proxy_url")
+	method := setup.MigrationMethod(r.URL.Query().Get("method"))
 
 	options := make(map[string]string)
 
@@ -135,11 +327,12 @@ func (s *Server) HandleMigrateDevice(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	if err := s.sm.MigrateSpeaker(deviceIP, targetURL, proxyURL, options); err != nil {
+	output, err := s.sm.MigrateSpeaker(deviceIP, targetURL, proxyURL, options, method)
+	if err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusInternalServerError)
 
-		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error()}); encodeErr != nil {
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
 			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 			return
 		}
@@ -149,7 +342,79 @@ func (s *Server) HandleMigrateDevice(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
 
-	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Migration started"}); err != nil {
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Migration started", "output": output}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
+// HandleRevertMigration reverts the migration for a device.
+func (s *Server) HandleRevertMigration(w http.ResponseWriter, r *http.Request) {
+	deviceIP := chi.URLParam(r, "deviceIP")
+	if deviceIP == "" {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+
+		if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": "Device IP is required"}); err != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+
+		return
+	}
+
+	output, err := s.sm.RevertMigration(deviceIP)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Revert started", "output": output}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
+// HandleTrustCACert injects the local Root CA into the device's shared trust store.
+func (s *Server) HandleTrustCACert(w http.ResponseWriter, r *http.Request) {
+	deviceIP := chi.URLParam(r, "deviceIP")
+	if deviceIP == "" {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+
+		if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": "Device IP is required"}); err != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+
+		return
+	}
+
+	output, err := s.sm.TrustCACert(deviceIP)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Root CA trusted", "output": output}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
 	}
@@ -170,11 +435,12 @@ func (s *Server) HandleEnsureRemoteServices(w http.ResponseWriter, r *http.Reque
 		return
 	}
 
-	if err := s.sm.EnsureRemoteServices(deviceIP); err != nil {
+	output, err := s.sm.EnsureRemoteServices(deviceIP)
+	if err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusInternalServerError)
 
-		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error()}); encodeErr != nil {
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
 			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 			return
 		}
@@ -184,7 +450,7 @@ func (s *Server) HandleEnsureRemoteServices(w http.ResponseWriter, r *http.Reque
 
 	w.Header().Set("Content-Type", "application/json")
 
-	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Remote services ensured"}); err != nil {
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Remote services enabled", "output": output}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
 	}
@@ -205,11 +471,12 @@ func (s *Server) HandleRemoveRemoteServices(w http.ResponseWriter, r *http.Reque
 		return
 	}
 
-	if err := s.sm.RemoveRemoteServices(deviceIP); err != nil {
+	output, err := s.sm.RemoveRemoteServices(deviceIP)
+	if err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusInternalServerError)
 
-		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error()}); encodeErr != nil {
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
 			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 			return
 		}
@@ -219,7 +486,7 @@ func (s *Server) HandleRemoveRemoteServices(w http.ResponseWriter, r *http.Reque
 
 	w.Header().Set("Content-Type", "application/json")
 
-	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Remote services removed"}); err != nil {
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Remote services removed", "output": output}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
 	}
@@ -240,11 +507,12 @@ func (s *Server) HandleBackupConfig(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	if err := s.sm.BackupConfig(deviceIP); err != nil {
+	output, err := s.sm.BackupConfig(deviceIP)
+	if err != nil {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusInternalServerError)
 
-		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error()}); encodeErr != nil {
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
 			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 			return
 		}
@@ -254,7 +522,7 @@ func (s *Server) HandleBackupConfig(w http.ResponseWriter, r *http.Request) {
 
 	w.Header().Set("Content-Type", "application/json")
 
-	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Backup created"}); err != nil {
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Config backed up", "output": output}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
 	}
@@ -264,28 +532,78 @@ func (s *Server) HandleBackupConfig(w http.ResponseWriter, r *http.Request) {
 func (s *Server) HandleGetProxySettings(w http.ResponseWriter, _ *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 
-	if err := json.NewEncoder(w).Encode(map[string]bool{
-		"redact":   s.proxyRedact,
-		"log_body": s.proxyLogBody,
+	redact, logBody, record, enableSoundcorkProxy := s.GetProxySettings()
+
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{
+		"redact":                 redact,
+		"log_body":               logBody,
+		"record":                 record,
+		"enable_soundcork_proxy": enableSoundcorkProxy,
 	}); err != nil {
 		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
 		return
 	}
 }
 
+// HandleGetCACert returns the Root CA certificate.
+func (s *Server) HandleGetCACert(w http.ResponseWriter, _ *http.Request) {
+	caCertPath := s.sm.Crypto.GetCACertPath()
+
+	content, err := os.ReadFile(caCertPath)
+	if err != nil {
+		http.Error(w, "Failed to read CA certificate", http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/x-x509-ca-cert")
+	w.Header().Set("Content-Disposition", "attachment; filename=soundtouch-ca.crt")
+	_, _ = w.Write(content)
+}
+
 // HandleUpdateProxySettings updates the proxy settings.
 func (s *Server) HandleUpdateProxySettings(w http.ResponseWriter, r *http.Request) {
 	var settings struct {
-		Redact  bool `json:"redact"`
-		LogBody bool `json:"log_body"`
+		Redact               bool `json:"redact"`
+		LogBody              bool `json:"log_body"`
+		Record               bool `json:"record"`
+		EnableSoundcorkProxy bool `json:"enable_soundcork_proxy"`
 	}
 	if err := json.NewDecoder(r.Body).Decode(&settings); err != nil {
 		http.Error(w, err.Error(), http.StatusBadRequest)
 		return
 	}
 
+	s.mu.Lock()
 	s.proxyRedact = settings.Redact
 	s.proxyLogBody = settings.LogBody
+	s.recordEnabled = settings.Record
+	s.enableSoundcorkProxy = settings.EnableSoundcorkProxy
+
+	// Persist to datastore
+	// Access fields directly since we already hold the lock
+	serverURL, soundcorkURL, httpsServerURL := s.serverURL, s.soundcorkURL, s.httpsServerURL
+	discoveryInterval := s.discoveryInterval.String()
+	discoveryEnabled := s.discoveryEnabled
+
+	log.Printf("Saving updated proxy settings to %s/settings.json", s.ds.DataDir)
+	err := s.ds.SaveSettings(datastore.Settings{
+		ServerURL:            serverURL,
+		SoundcorkURL:         soundcorkURL,
+		HTTPServerURL:        httpsServerURL,
+		RedactLogs:           s.proxyRedact,
+		LogBodies:            s.proxyLogBody,
+		RecordInteractions:   s.recordEnabled,
+		DiscoveryInterval:    discoveryInterval,
+		DiscoveryEnabled:     discoveryEnabled,
+		EnableSoundcorkProxy: s.enableSoundcorkProxy,
+		Shortcuts:            s.shortcuts,
+	})
+	s.mu.Unlock()
+
+	if err != nil {
+		http.Error(w, "Failed to save settings: "+err.Error(), http.StatusInternalServerError)
+		return
+	}
 
 	w.Header().Set("Content-Type", "application/json")
 
@@ -294,3 +612,296 @@ func (s *Server) HandleUpdateProxySettings(w http.ResponseWriter, r *http.Reques
 		return
 	}
 }
+
+// HandleTestHostsRedirection performs a preliminary check for /etc/hosts redirection.
+func (s *Server) HandleTestHostsRedirection(w http.ResponseWriter, r *http.Request) {
+	deviceIP := chi.URLParam(r, "deviceIP")
+	if deviceIP == "" {
+		http.Error(w, "Device IP is required", http.StatusBadRequest)
+		return
+	}
+
+	targetURL := r.URL.Query().Get("target_url")
+	if targetURL == "" {
+		targetURL = s.serverURL
+	}
+
+	output, err := s.sm.TestHostsRedirection(deviceIP, targetURL)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK) // Return 200 but ok: false so UI can show the output
+
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{
+			"ok":      false,
+			"message": err.Error(),
+			"output":  output,
+		}); encodeErr != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		}
+
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{
+		"ok":      true,
+		"message": "Hosts redirection test successful",
+		"output":  output,
+	}); encodeErr != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// HandleInitialSync fetches presets, recents and sources from the device and saves them to the datastore.
+func (s *Server) HandleInitialSync(w http.ResponseWriter, r *http.Request) {
+	deviceIP := chi.URLParam(r, "deviceIP")
+	if deviceIP == "" {
+		http.Error(w, "Missing deviceIP", http.StatusBadRequest)
+		return
+	}
+
+	if err := s.sm.SyncDeviceData(deviceIP); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write([]byte(`{"ok": true}`))
+}
+
+// HandleRebootDevice reboots a device.
+func (s *Server) HandleRebootDevice(w http.ResponseWriter, r *http.Request) {
+	deviceIP := chi.URLParam(r, "deviceIP")
+	if deviceIP == "" {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+
+		if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": "Device IP is required"}); err != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+
+		return
+	}
+
+	output, err := s.sm.Reboot(deviceIP)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{"ok": false, "message": err.Error(), "output": output}); encodeErr != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+			return
+		}
+
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]interface{}{"ok": true, "message": "Reboot started", "output": output}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
+// HandleTestConnection performs a connection check from the device to the server.
+func (s *Server) HandleTestConnection(w http.ResponseWriter, r *http.Request) {
+	deviceIP := chi.URLParam(r, "deviceIP")
+	if deviceIP == "" {
+		http.Error(w, "Device IP is required", http.StatusBadRequest)
+		return
+	}
+
+	targetURL := r.URL.Query().Get("target_url")
+	if targetURL == "" {
+		http.Error(w, "Target URL is required", http.StatusBadRequest)
+		return
+	}
+
+	useExplicitCA := r.URL.Query().Get("use_explicit_ca") == "true"
+
+	output, err := s.sm.TestConnection(deviceIP, targetURL, useExplicitCA)
+	if err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK) // Return 200 but ok: false so UI can show the output
+
+		if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{
+			"ok":      false,
+			"message": err.Error(),
+			"output":  output,
+		}); encodeErr != nil {
+			http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		}
+
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if encodeErr := json.NewEncoder(w).Encode(map[string]interface{}{
+		"ok":      true,
+		"message": "Connection test successful",
+		"output":  output,
+	}); encodeErr != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// HandleGetVersionInfo returns version information for the service.
+func (s *Server) HandleGetVersionInfo(w http.ResponseWriter, _ *http.Request) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(map[string]string{
+		"version": s.Version,
+		"commit":  s.Commit,
+		"date":    s.Date,
+	}); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
+// HandleGetInteractionStats returns statistics about recorded interactions.
+func (s *Server) HandleGetInteractionStats(w http.ResponseWriter, _ *http.Request) {
+	if s.recorder == nil {
+		http.Error(w, "Recorder not initialized", http.StatusServiceUnavailable)
+		return
+	}
+
+	stats, err := s.recorder.GetInteractionStats()
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(stats); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
+// HandleListInteractions returns a list of recorded interactions.
+func (s *Server) HandleListInteractions(w http.ResponseWriter, r *http.Request) {
+	if s.recorder == nil {
+		http.Error(w, "Recorder not initialized", http.StatusServiceUnavailable)
+		return
+	}
+
+	session := r.URL.Query().Get("session")
+	category := r.URL.Query().Get("category")
+	since := r.URL.Query().Get("since")
+
+	interactions, err := s.recorder.ListInteractions(session, category, since)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if err := json.NewEncoder(w).Encode(interactions); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+		return
+	}
+}
+
+// HandleGetInteractionContent returns the raw content of a recorded interaction.
+func (s *Server) HandleGetInteractionContent(w http.ResponseWriter, r *http.Request) {
+	if s.recorder == nil {
+		http.Error(w, "Recorder not initialized", http.StatusServiceUnavailable)
+		return
+	}
+
+	file := r.URL.Query().Get("file")
+	if file == "" {
+		http.Error(w, "File parameter is required", http.StatusBadRequest)
+		return
+	}
+
+	content, err := s.recorder.GetInteractionContent(file)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/plain")
+	_, _ = w.Write(content)
+}
+
+// HandleDeleteSession deletes a recorded interaction session.
+func (s *Server) HandleDeleteSession(w http.ResponseWriter, r *http.Request) {
+	if s.recorder == nil {
+		http.Error(w, "Recorder not initialized", http.StatusServiceUnavailable)
+		return
+	}
+
+	session := chi.URLParam(r, "session")
+	if session == "" {
+		http.Error(w, "Session ID is required", http.StatusBadRequest)
+		return
+	}
+
+	if err := s.recorder.DeleteSession(session); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_, _ = w.Write([]byte(`{"ok": true}`))
+}
+
+// HandleCleanupSessions deletes all but the most recent N sessions.
+func (s *Server) HandleCleanupSessions(w http.ResponseWriter, r *http.Request) {
+	if s.recorder == nil {
+		http.Error(w, "Recorder not initialized", http.StatusServiceUnavailable)
+		return
+	}
+
+	keep := 10
+
+	keepStr := r.URL.Query().Get("keep")
+	if keepStr != "" {
+		if k, err := strconv.Atoi(keepStr); err == nil {
+			keep = k
+		}
+	}
+
+	if err := s.recorder.CleanupSessions(keep); err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_, _ = w.Write([]byte(`{"ok": true}`))
+}
+
+// HandleDownloadSession returns a .tar.gz archive of a recorded interaction session.
+func (s *Server) HandleDownloadSession(w http.ResponseWriter, r *http.Request) {
+	if s.recorder == nil {
+		http.Error(w, "Recorder not initialized", http.StatusServiceUnavailable)
+		return
+	}
+
+	session := chi.URLParam(r, "session")
+	if session == "" {
+		http.Error(w, "Session ID is required", http.StatusBadRequest)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/gzip")
+	w.Header().Set("Content-Disposition", fmt.Sprintf("attachment; filename=\"%s.tar.gz\"", session))
+
+	if err := s.recorder.ArchiveSession(session, w); err != nil {
+		log.Printf("Error archiving session %s: %v", session, err)
+		// Since we already set headers, if we have an error here it might be partially written.
+		// But for now, simple error handling.
+		return
+	}
+}

pkg/service/handlers/handlers_setup_test.go

@@ -5,11 +5,26 @@ import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
+	"os"
+	"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/setup"
 )
 
 func TestProxySettingsAPI(t *testing.T) {
-	r, server := setupRouter("http://localhost:8001", nil)
+	tempDir, err := os.MkdirTemp("", "proxy-settings-test")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ds := datastore.NewDataStore(tempDir)
+	_ = ds.Initialize()
+
+	r, server := setupRouter("http://localhost:8001", ds)
 
 	ts := httptest.NewServer(r)
 	defer ts.Close()
@@ -80,4 +95,255 @@ func TestProxySettingsAPI(t *testing.T) {
 	if settings["redact"] != false || settings["log_body"] != true {
 		t.Errorf("GET (after update): Unexpected settings: %+v", settings)
 	}
+
+	// 3. Test System Settings POST
+	sysUpdate := map[string]string{
+		"server_url":    "http://new-server:8000",
+		"soundcork_url": "http://new-proxy:8001",
+	}
+
+	sysBody, err := json.Marshal(sysUpdate)
+	if err != nil {
+		t.Fatalf("Failed to marshal system settings data: %v", err)
+	}
+
+	res, err = http.Post(ts.URL+"/setup/settings", "application/json", bytes.NewBuffer(sysBody))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	defer func() { _ = res.Body.Close() }()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("POST /setup/settings: Expected status OK, got %v", res.Status)
+	}
+
+	// Verify server state
+	sURL, pURL, _ := server.GetSettings()
+	if sURL != "http://new-server:8000" || pURL != "http://new-proxy:8001" {
+		t.Errorf("POST /setup/settings: Server state did not update: serverURL=%s, soundcorkURL=%s", sURL, pURL)
+	}
 }
+
+func TestMigrationAndCA(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "handlers-test")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ds := datastore.NewDataStore(tempDir)
+	_ = ds.Initialize()
+	cm := certmanager.NewCertificateManager(filepath.Join(tempDir, "certs"))
+	_ = cm.EnsureCA()
+
+	sm := setup.NewManager("http://localhost:8000", ds, cm)
+	// Mock SSH to avoid real connections
+	sm.NewSSH = func(host string) setup.SSHClient {
+		return &mockSSH{}
+	}
+
+	r, server := setupRouter("http://localhost:8001", ds)
+	server.sm = sm // Inject our manager with mock SSH
+
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	// 1. Test GET /setup/ca.crt
+	res, err := http.Get(ts.URL + "/setup/ca.crt")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("CA: Expected status OK, got %v", res.Status)
+	}
+	if res.Header.Get("Content-Type") != "application/x-x509-ca-cert" {
+		t.Errorf("CA: Unexpected content type: %s", res.Header.Get("Content-Type"))
+	}
+
+	// 2. Test POST /setup/migrate/{deviceIP}?method=hosts
+	res, err = http.Post(ts.URL+"/setup/migrate/192.168.1.10?method=hosts&target_url=http://192.168.1.100:8000", "application/json", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("Migrate: Expected status OK, got %v", res.Status)
+	}
+
+	var result map[string]interface{}
+	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
+		t.Fatalf("Migrate: Failed to decode response: %v", err)
+	}
+	if result["ok"] != true {
+		t.Errorf("Migrate: Expected ok=true, got %v", result["ok"])
+	}
+	if _, ok := result["output"]; !ok {
+		t.Errorf("Migrate: Expected output field in response")
+	}
+
+	// 3. Test POST /setup/trust-ca/{deviceIP}
+	res, err = http.Post(ts.URL+"/setup/trust-ca/192.168.1.10", "application/json", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("TrustCA: Expected status OK, got %v", res.Status)
+	}
+
+	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
+		t.Fatalf("TrustCA: Failed to decode response: %v", err)
+	}
+	if result["ok"] != true {
+		t.Errorf("TrustCA: Expected ok=true, got %v", result["ok"])
+	}
+	if _, ok := result["output"]; !ok {
+		t.Errorf("TrustCA: Expected output field in response")
+	}
+
+	// 4. Test POST /setup/reboot/{deviceIP}
+	res, err = http.Post(ts.URL+"/setup/reboot/192.168.1.10", "application/json", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("Reboot: Expected status OK, got %v", res.Status)
+	}
+
+	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
+		t.Fatalf("Reboot: Failed to decode response: %v", err)
+	}
+	if result["ok"] != true {
+		t.Errorf("Reboot: Expected ok=true, got %v", result["ok"])
+	}
+	if _, ok := result["output"]; !ok {
+		t.Errorf("Reboot: Expected output field in response")
+	}
+
+	// 5. Test POST /setup/remove-remote-services/{deviceIP}
+	res, err = http.Post(ts.URL+"/setup/remove-remote-services/192.168.1.10", "application/json", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("RemoveRemote: Expected status OK, got %v", res.Status)
+	}
+
+	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
+		t.Fatalf("RemoveRemote: Failed to decode response: %v", err)
+	}
+	if result["ok"] != true {
+		t.Errorf("RemoveRemote: Expected ok=true, got %v", result["ok"])
+	}
+	if _, ok := result["output"]; !ok {
+		t.Errorf("RemoveRemote: Expected output field in response")
+	}
+}
+
+func TestRemoveDevice(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "remove-device-test")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ds := datastore.NewDataStore(tempDir)
+	_ = ds.Initialize()
+
+	// Setup a dummy device in the datastore
+	account := "test-account"
+	deviceID := "TEST-DEVICE-ID"
+	deviceDir := filepath.Join(tempDir, "accounts", account, "devices", deviceID)
+	if err := os.MkdirAll(deviceDir, 0755); err != nil {
+		t.Fatalf("Failed to create device dir: %v", err)
+	}
+
+	infoFile := filepath.Join(deviceDir, "DeviceInfo.xml")
+	infoXML := `<?xml version="1.0" encoding="UTF-8" ?><info deviceID="TEST-DEVICE-ID"><name>Test Device</name><type>SoundTouch 10</type></info>`
+	if err := os.WriteFile(infoFile, []byte(infoXML), 0644); err != nil {
+		t.Fatalf("Failed to create device info file: %v", err)
+	}
+
+	r, _ := setupRouter("http://localhost:8001", ds)
+	ts := httptest.NewServer(r)
+	defer ts.Close()
+
+	// 1. Verify device exists
+	res, err := http.Get(ts.URL + "/setup/devices")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	var devices []map[string]interface{}
+	if err := json.NewDecoder(res.Body).Decode(&devices); err != nil {
+		t.Fatalf("Failed to decode devices: %v", err)
+	}
+
+	found := false
+	for _, d := range devices {
+		if d["device_id"] == deviceID {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("Device not found in list before removal")
+	}
+
+	// 2. Remove device
+	req, err := http.NewRequest(http.MethodDelete, ts.URL+"/setup/devices/"+deviceID, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err = http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if res.StatusCode != http.StatusOK {
+		t.Errorf("Expected status OK, got %v", res.Status)
+	}
+
+	// 3. Verify device is gone
+	res, err = http.Get(ts.URL + "/setup/devices")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer res.Body.Close()
+
+	if err := json.NewDecoder(res.Body).Decode(&devices); err != nil {
+		t.Fatalf("Failed to decode devices after removal: %v", err)
+	}
+
+	for _, d := range devices {
+		if d["device_id"] == deviceID {
+			t.Errorf("Device still exists in list after removal")
+		}
+	}
+
+	// 4. Verify directory is gone
+	if _, err := os.Stat(deviceDir); !os.IsNotExist(err) {
+		t.Errorf("Device directory still exists after removal")
+	}
+}
+
+type mockSSH struct{}
+
+func (m *mockSSH) Run(command string) (string, error) {
+	if command == "cat /etc/hosts" {
+		return "127.0.0.1 localhost", nil
+	}
+	return "", nil
+}
+func (m *mockSSH) UploadContent(content []byte, remotePath string) error { return nil }

pkg/service/handlers/handlers_stats.go

@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/go-chi/chi/v5"
 )
 
 // HandleUsageStats handles Marge usage stats uploads.
@@ -49,6 +50,42 @@ func (s *Server) HandleUsageStats(w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(http.StatusOK)
 }
 
+// HandleAppEvents handles events from the Bose SoundTouch app (stapp/scmudc).
+func (s *Server) HandleAppEvents(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		http.Error(w, "Failed to read body", http.StatusBadRequest)
+		return
+	}
+
+	var req models.DeviceEventsRequest
+	if err := json.Unmarshal(body, &req); err != nil {
+		http.Error(w, "Invalid app events format", http.StatusBadRequest)
+		return
+	}
+
+	deviceID := req.Envelope.UniqueID
+	if deviceID == "" {
+		deviceID = chi.URLParam(r, "deviceId")
+	}
+
+	for _, e := range req.Payload.Events {
+		event := models.DeviceEvent{
+			Type:     e.Type,
+			Time:     e.Time,
+			MonoTime: req.Envelope.MonoTime,
+			Data:     e.Data,
+		}
+		if event.Time == "" {
+			event.Time = time.Now().Format(time.RFC3339)
+		}
+
+		s.ds.AddDeviceEvent(deviceID, event)
+	}
+
+	w.WriteHeader(http.StatusOK)
+}
+
 // HandleErrorStats handles Marge error stats uploads.
 func (s *Server) HandleErrorStats(w http.ResponseWriter, r *http.Request) {
 	body, err := io.ReadAll(r.Body)

pkg/service/handlers/handlers_stats_test.go

@@ -12,7 +12,7 @@ import (
 )
 
 func TestStatsHandlers(t *testing.T) {
-	tempDir, err := os.MkdirTemp("", "soundcork-test-*")
+	tempDir, err := os.MkdirTemp("", "st-test-*")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -63,4 +63,44 @@ func TestStatsHandlers(t *testing.T) {
 			t.Error("Error stats file was not created")
 		}
 	})
+
+	t.Run("HandleAppEvents", func(t *testing.T) {
+		jsonData := `{
+			"envelope": {
+				"monoTime": 12345,
+				"payloadProtocolVersion": "3.1",
+				"payloadType": "stapp",
+				"protocolVersion": "1.0",
+				"time": "2023-10-27T10:00:00Z",
+				"uniqueId": "device789"
+			},
+			"payload": {
+				"deviceInfo": {
+					"deviceID": "device789"
+				},
+				"events": [
+					{
+						"type": "APP_OPEN",
+						"time": "2023-10-27T10:00:01Z",
+						"data": {"foo": "bar"}
+					}
+				]
+			}
+		}`
+		req := httptest.NewRequest("POST", "/v1/stapp/device789", bytes.NewBufferString(jsonData))
+		w := httptest.NewRecorder()
+
+		s.HandleAppEvents(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("Expected status OK, got %d", w.Code)
+		}
+
+		events := ds.GetDeviceEvents("device789")
+		if len(events) == 0 {
+			t.Error("App events were not recorded")
+		} else if events[0].Type != "APP_OPEN" {
+			t.Errorf("Expected event type APP_OPEN, got %s", events[0].Type)
+		}
+	})
 }

pkg/service/handlers/index.html

@@ -1,515 +0,0 @@
-<!DOCTYPE html>
-<html>
-<head>
-    <meta charset="UTF-8">
-    <title>Soundcork Management</title>
-    <link rel="icon" href="/media/favicon-braille.svg" type="image/svg+xml">
-    <style>
-        body { font-family: sans-serif; margin: 20px; }
-        table { border-collapse: collapse; width: 100%; }
-        th, td { border: 1px solid #ddd; padding: 8px; text-align: left; }
-        th { background-color: #f2f2f2; }
-        button { padding: 5px 10px; cursor: pointer; }
-        .status { margin-top: 10px; padding: 10px; border: 1px solid #ccc; display: none; }
-        .summary-box { margin-top: 20px; padding: 15px; border: 1px solid #aaa; background-color: #f9f9f9; display: none; }
-        pre { background-color: #eee; padding: 10px; overflow-x: auto; font-size: 12px; }
-        .diff-container { display: flex; gap: 10px; }
-        .diff-pane { flex: 1; min-width: 0; }
-        .config-header { font-weight: bold; margin-bottom: 5px; display: block; }
-    </style>
-</head>
-<body>
-    <h1>Soundcork Management</h1>
-    <h2>Discovered Devices <span id="discovery-indicator" style="font-size: 0.5em; vertical-align: middle; display: none;">🔍 Scanning...</span></h2>
-    <div id="device-list">Loading devices...</div>
-
-    <div id="manual-entry" style="margin-top: 20px; border-top: 1px solid #eee; padding-top: 10px;">
-        <h3>Manual Entry</h3>
-        <input type="text" id="manual-ip" placeholder="Device IP (e.g. 192.168.1.100)">
-        <button onclick="showSummary(document.getElementById('manual-ip').value)">Check Migration</button>
-
-        <h3 style="margin-top: 20px;">Settings</h3>
-        <div style="margin-bottom: 10px;">
-            <label for="target-domain">Target Domain:</label>
-            <input type="text" id="target-domain" placeholder="http://localhost:8000" style="width: 300px;">
-            <span style="font-size: 0.8em; color: #666;">(This URL will be used for standard services)</span>
-        </div>
-        <div style="margin-bottom: 10px;">
-            <label for="proxy-domain">Proxy Domain:</label>
-            <input type="text" id="proxy-domain" placeholder="http://localhost:8000" style="width: 300px;">
-            <span style="font-size: 0.8em; color: #666;">(This URL will be used to proxy upstream Bose services)</span>
-        </div>
-        <div style="margin-bottom: 10px;">
-            Proxy Logging:
-            <label><input type="checkbox" id="proxy-redact" onchange="updateProxySettings()"> Redact Sensitive Headers</label>
-            <label style="margin-left: 15px;"><input type="checkbox" id="proxy-log-body" onchange="updateProxySettings()"> Log Bodies</label>
-        </div>
-    </div>
-
-    <div id="status" class="status"></div>
-
-    <div id="migration-summary" class="summary-box">
-        <h3>Migration Summary for <span id="summary-ip"></span></h3>
-        <p>SSH Connection: <span id="ssh-status"></span></p>
-        <p id="original-config-status" style="display: none;">Backup: ✅ Found .original config at <code>/opt/Bose/etc/SoundTouchSdkPrivateCfg.xml.original</code> <button onclick="toggleOriginalConfig()">Show Original Config</button></p>
-        <p id="no-original-config-status" style="display: none;">Backup: ❌ Not found <button id="backup-config-btn">Backup Config Now</button></p>
-        <p>Remote Services Enabled: <span id="remote-services-status"></span> <span id="remote-services-found" style="font-size: 0.8em; color: #666;"></span></p>
-
-        <div id="original-config-pane" style="display: none; margin-bottom: 20px;">
-            <span class="config-header">Original Config (Backup)</span>
-            <pre id="original-config-content"></pre>
-        </div>
-
-        <div id="service-options" style="margin-bottom: 20px; display: none;">
-            <h4>Service Implementations</h4>
-            <table>
-                <tr><th>Service</th><th>Original URL</th><th>Implementation</th></tr>
-                <tr>
-                    <td>Marge (Streaming)</td>
-                    <td id="orig-marge">loading...</td>
-                    <td>
-                        <select id="opt-marge" onchange="refreshSummary()">
-                            <option value="soundcork">Soundcork (Go/Python)</option>
-                            <option value="original">Original (Proxy via soundcork-go)</option>
-                        </select>
-                    </td>
-                </tr>
-                <tr>
-                    <td>Stats</td>
-                    <td id="orig-stats">loading...</td>
-                    <td>
-                        <select id="opt-stats" onchange="refreshSummary()">
-                            <option value="soundcork">Soundcork (Go/Python)</option>
-                            <option value="original">Original (Proxy via soundcork-go)</option>
-                        </select>
-                    </td>
-                </tr>
-                <tr>
-                    <td>Software Update</td>
-                    <td id="orig-sw_update">loading...</td>
-                    <td>
-                        <select id="opt-sw_update" onchange="refreshSummary()">
-                            <option value="soundcork">Soundcork (Go/Python)</option>
-                            <option value="original">Original (Proxy via soundcork-go)</option>
-                        </select>
-                    </td>
-                </tr>
-                <tr>
-                    <td>BMX (Registry)</td>
-                    <td id="orig-bmx">loading...</td>
-                    <td>
-                        <select id="opt-bmx" onchange="refreshSummary()">
-                            <option value="soundcork">Soundcork (Go/Python)</option>
-                            <option value="original">Original (Proxy via soundcork-go)</option>
-                        </select>
-                    </td>
-                </tr>
-            </table>
-        </div>
-
-        <div class="diff-container">
-            <div class="diff-pane">
-                <span class="config-header">Current Config (on Speaker)</span>
-                <pre id="current-config"></pre>
-            </div>
-            <div class="diff-pane">
-                <span class="config-header">Planned Config (Soundcork)</span>
-                <pre id="planned-config"></pre>
-            </div>
-        </div>
-        <div style="margin-top: 15px;">
-            <button id="confirm-migrate-btn" style="background-color: #4CAF50; color: white; border: none; padding: 10px 20px;">Confirm Migration & Reboot</button>
-            <button id="ensure-remote-btn" style="background-color: #2196F3; color: white; border: none; padding: 10px 20px;">Enable Persistent Remote Services</button>
-            <button id="remove-remote-btn" style="background-color: #f44336; color: white; border: none; padding: 10px 20px;">Remove Persistent Remote Services</button>
-            <button onclick="document.getElementById('migration-summary').style.display='none'" style="padding: 10px 20px;">Cancel</button>
-        </div>
-    </div>
-
-    <script>
-        async function fetchSettings() {
-            try {
-                const response = await fetch('/setup/settings');
-                const settings = await response.json();
-                if (settings.server_url) {
-                    document.getElementById('target-domain').value = settings.server_url;
-                }
-                if (settings.proxy_url) {
-                    document.getElementById('proxy-domain').value = settings.proxy_url;
-                }
-                fetchProxySettings();
-            } catch (error) {
-                console.error('Failed to fetch settings', error);
-            }
-        }
-
-        async function fetchProxySettings() {
-            try {
-                const response = await fetch('/setup/proxy-settings');
-                const settings = await response.json();
-                document.getElementById('proxy-redact').checked = settings.redact;
-                document.getElementById('proxy-log-body').checked = settings.log_body;
-            } catch (error) {
-                console.error('Failed to fetch proxy settings', error);
-            }
-        }
-
-        async function updateProxySettings() {
-            const settings = {
-                redact: document.getElementById('proxy-redact').checked,
-                log_body: document.getElementById('proxy-log-body').checked
-            };
-            try {
-                await fetch('/setup/proxy-settings', {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify(settings)
-                });
-            } catch (error) {
-                console.error('Failed to update proxy settings', error);
-            }
-        }
-
-        async function fetchDevices() {
-            try {
-                const response = await fetch('/setup/devices');
-                const devices = await response.json();
-                const container = document.getElementById('device-list');
-
-                if (devices.length === 0) {
-                    container.innerHTML = 'No devices found.';
-                } else {
-                    let html = '<table><tr><th>Name</th><th>IP Address</th><th>Model</th><th>Serial Number</th><th>Firmware</th><th>Action</th></tr>';
-                    devices.forEach(d => {
-                        html += `
-                            <tr id="device-row-${d.ip_address.replace(/\./g, '-')}">
-                                <td class="col-name">${d.name}</td>
-                                <td class="col-ip">${d.ip_address}</td>
-                                <td class="col-model">${d.product_code}</td>
-                                <td class="col-serial">${d.device_serial_number}</td>
-                                <td class="col-firmware">${d.firmware_version || '0.0.0'}</td>
-                                <td><button onclick="showSummary('${d.ip_address}')">Prepare Migration</button></td>
-                            </tr>
-                        `;
-                    });
-                    html += '</table>';
-                    container.innerHTML = html;
-
-                    // Asynchronously fetch live info for each device
-                    devices.forEach(d => updateDeviceInfo(d.ip_address));
-                }
-            } catch (error) {
-                document.getElementById('device-list').innerHTML = 'Error loading devices: ' + error;
-            }
-        }
-
-        async function triggerDiscovery() {
-            const indicator = document.getElementById('discovery-indicator');
-            indicator.style.display = 'inline';
-            try {
-                await fetch('/setup/discover', { method: 'POST' });
-                pollDiscoveryStatus();
-            } catch (error) {
-                console.error('Failed to trigger discovery', error);
-                indicator.style.display = 'none';
-            }
-        }
-
-        async function pollDiscoveryStatus() {
-            const indicator = document.getElementById('discovery-indicator');
-            try {
-                const response = await fetch('/setup/discovery-status');
-                const data = await response.json();
-                if (data.discovering) {
-                    setTimeout(pollDiscoveryStatus, 2000);
-                } else {
-                    indicator.style.display = 'none';
-                    fetchDevices();
-                }
-            } catch (error) {
-                console.error('Failed to check discovery status', error);
-                indicator.style.display = 'none';
-            }
-        }
-
-        async function updateDeviceInfo(ip) {
-            try {
-                const response = await fetch('/setup/info/' + ip);
-                if (!response.ok) return;
-                const info = await response.json();
-
-                const rowId = 'device-row-' + ip.replace(/\./g, '-');
-                const row = document.getElementById(rowId);
-                if (row) {
-                    if (info.name) row.querySelector('.col-name').innerText = info.name;
-                    if (info.type) row.querySelector('.col-model').innerText = info.type;
-                    if (info.serialNumber) row.querySelector('.col-serial').innerText = info.serialNumber;
-                    if (info.softwareVersion) row.querySelector('.col-firmware').innerText = info.softwareVersion;
-                }
-            } catch (error) {
-                console.warn('Failed to fetch live info for ' + ip, error);
-            }
-        }
-
-        async function showSummary(ip) {
-            if (!ip) {
-                alert('Please enter a valid IP address.');
-                return;
-            }
-            const targetUrl = document.getElementById('target-domain').value;
-            const proxyUrl = document.getElementById('proxy-domain').value;
-
-            const opts = {
-                marge: document.getElementById('opt-marge').value,
-                stats: document.getElementById('opt-stats').value,
-                sw_update: document.getElementById('opt-sw_update').value,
-                bmx: document.getElementById('opt-bmx').value
-            };
-
-            const statusDiv = document.getElementById('status');
-            statusDiv.style.display = 'block';
-            statusDiv.style.backgroundColor = '#ffffcc';
-            statusDiv.innerHTML = 'Fetching summary for ' + ip + '...';
-
-            let query = '?target_url=' + encodeURIComponent(targetUrl) + '&proxy_url=' + encodeURIComponent(proxyUrl);
-            for (let k in opts) {
-                query += '&' + k + '=' + encodeURIComponent(opts[k]);
-            }
-
-            try {
-                const response = await fetch('/setup/summary/' + ip + query);
-                if (!response.ok) {
-                    const errorText = await response.text();
-                    throw new Error(errorText);
-                }
-                const summary = await response.json();
-
-                statusDiv.style.display = 'none';
-                document.getElementById('summary-ip').innerText = ip;
-
-                // Update table row if it exists
-                const rowId = 'device-row-' + ip.replace(/\./g, '-');
-                const row = document.getElementById(rowId);
-                if (row) {
-                    if (summary.device_name) row.querySelector('.col-name').innerText = summary.device_name;
-                    if (summary.device_model) row.querySelector('.col-model').innerText = summary.device_model;
-                    if (summary.device_serial) row.querySelector('.col-serial').innerText = summary.device_serial;
-                    if (summary.firmware_version) row.querySelector('.col-firmware').innerText = summary.firmware_version;
-                }
-
-                document.getElementById('ssh-status').innerText = summary.ssh_success ? '✅ Success' : '❌ Failed';
-                document.getElementById('ssh-status').style.color = summary.ssh_success ? 'green' : 'red';
-
-                document.getElementById('original-config-status').style.display = summary.original_config ? 'block' : 'none';
-                document.getElementById('no-original-config-status').style.display = summary.original_config ? 'none' : 'block';
-                document.getElementById('original-config-content').innerText = summary.original_config || '';
-                document.getElementById('original-config-pane').style.display = 'none';
-
-                if (summary.parsed_current_config) {
-                    document.getElementById('service-options').style.display = 'block';
-                    document.getElementById('orig-marge').innerText = summary.parsed_current_config.margeServerUrl;
-                    document.getElementById('orig-stats').innerText = summary.parsed_current_config.statsServerUrl;
-                    document.getElementById('orig-sw_update').innerText = summary.parsed_current_config.swUpdateUrl;
-                    document.getElementById('orig-bmx').innerText = summary.parsed_current_config.bmxRegistryUrl;
-                } else {
-                    document.getElementById('service-options').style.display = 'none';
-                }
-
-                const remoteStatus = document.getElementById('remote-services-status');
-                const remoteFound = document.getElementById('remote-services-found');
-                if (summary.ssh_success) {
-                    if (summary.remote_services_enabled) {
-                        remoteStatus.innerText = summary.remote_services_persistent ? '✅ Yes' : '⚠️ Yes (non-persistent)';
-                        remoteStatus.style.color = summary.remote_services_persistent ? 'green' : 'orange';
-                    } else {
-                        remoteStatus.innerText = '❌ No';
-                        remoteStatus.style.color = 'red';
-                    }
-                    remoteFound.innerText = summary.remote_services_found && summary.remote_services_found.length > 0
-                        ? '(' + summary.remote_services_found.join(', ') + ')'
-                        : '';
-                } else {
-                    remoteStatus.innerText = '❓ Unknown';
-                    remoteStatus.style.color = 'gray';
-                    remoteFound.innerText = '';
-                }
-
-                const currentConfigElem = document.getElementById('current-config');
-                currentConfigElem.innerText = summary.current_config;
-                currentConfigElem.style.color = summary.ssh_success ? 'black' : 'red';
-
-                document.getElementById('planned-config').innerText = summary.planned_config;
-
-                const migrateBtn = document.getElementById('confirm-migrate-btn');
-                migrateBtn.onclick = () => migrate(ip);
-                migrateBtn.disabled = !summary.ssh_success;
-
-                const remoteBtn = document.getElementById('ensure-remote-btn');
-                remoteBtn.onclick = () => ensureRemoteServices(ip);
-                remoteBtn.disabled = !summary.ssh_success;
-
-                const removeRemoteBtn = document.getElementById('remove-remote-btn');
-                removeRemoteBtn.onclick = () => removeRemoteServices(ip);
-                removeRemoteBtn.disabled = !summary.ssh_success || !summary.remote_services_enabled;
-
-                const backupBtn = document.getElementById('backup-config-btn');
-                backupBtn.onclick = () => backupConfig(ip);
-                backupBtn.disabled = !summary.ssh_success || !!summary.original_config;
-
-                document.getElementById('migration-summary').style.display = 'block';
-                document.getElementById('migration-summary').scrollIntoView();
-            } catch (error) {
-                statusDiv.style.backgroundColor = '#ffcccc';
-                statusDiv.innerHTML = 'Error fetching summary for ' + ip + ': ' + error;
-            }
-        }
-
-        function refreshSummary() {
-            const ip = document.getElementById('summary-ip').innerText;
-            if (ip) {
-                showSummary(ip);
-            }
-        }
-
-        async function migrate(ip) {
-            if (!ip) {
-                alert('Please enter a valid IP address.');
-                return;
-            }
-            const targetUrl = document.getElementById('target-domain').value;
-            const proxyUrl = document.getElementById('proxy-domain').value;
-
-            const opts = {
-                marge: document.getElementById('opt-marge').value,
-                stats: document.getElementById('opt-stats').value,
-                sw_update: document.getElementById('opt-sw_update').value,
-                bmx: document.getElementById('opt-bmx').value
-            };
-
-            const summaryDiv = document.getElementById('migration-summary');
-            summaryDiv.style.display = 'none';
-
-            const statusDiv = document.getElementById('status');
-            statusDiv.style.display = 'block';
-            statusDiv.style.backgroundColor = '#ffffcc';
-            statusDiv.innerHTML = 'Migrating ' + ip + '...';
-
-            let query = '?target_url=' + encodeURIComponent(targetUrl) + '&proxy_url=' + encodeURIComponent(proxyUrl);
-            for (let k in opts) {
-                query += '&' + k + '=' + encodeURIComponent(opts[k]);
-            }
-
-            try {
-                const response = await fetch('/setup/migrate/' + ip + query, { method: 'POST' });
-                const result = await response.json();
-                if (result.ok) {
-                    statusDiv.style.backgroundColor = '#ccffcc';
-                    statusDiv.innerHTML = 'Successfully started migration for ' + ip + '. The speaker will reboot.';
-                } else {
-                    statusDiv.style.backgroundColor = '#ffcccc';
-                    statusDiv.innerHTML = 'Migration failed for ' + ip + ': ' + (result.message || 'Unknown error');
-                }
-            } catch (error) {
-                statusDiv.style.backgroundColor = '#ffcccc';
-                statusDiv.innerHTML = 'Error migrating ' + ip + ': ' + error;
-            }
-        }
-
-        async function ensureRemoteServices(ip) {
-            if (!ip) {
-                alert('Please enter a valid IP address.');
-                return;
-            }
-            const summaryDiv = document.getElementById('migration-summary');
-            summaryDiv.style.display = 'none';
-
-            const statusDiv = document.getElementById('status');
-            statusDiv.style.display = 'block';
-            statusDiv.style.backgroundColor = '#ffffcc';
-            statusDiv.innerHTML = 'Ensuring remote services for ' + ip + '...';
-
-            try {
-                const response = await fetch('/setup/ensure-remote-services/' + ip, { method: 'POST' });
-                const result = await response.json();
-                if (result.ok) {
-                    statusDiv.style.backgroundColor = '#ccffcc';
-                    statusDiv.innerHTML = 'Successfully ensured remote services for ' + ip + '.';
-                } else {
-                    statusDiv.style.backgroundColor = '#ffcccc';
-                    statusDiv.innerHTML = 'Failed to ensure remote services for ' + ip + ': ' + (result.message || 'Unknown error');
-                }
-            } catch (error) {
-                statusDiv.style.backgroundColor = '#ffcccc';
-                statusDiv.innerHTML = 'Error ensuring remote services for ' + ip + ': ' + error;
-            }
-        }
-
-        async function removeRemoteServices(ip) {
-            if (!ip) {
-                alert('Please enter a valid IP address.');
-                return;
-            }
-            if (!confirm('Are you sure you want to remove remote services from ' + ip + '?')) {
-                return;
-            }
-            const summaryDiv = document.getElementById('migration-summary');
-            summaryDiv.style.display = 'none';
-
-            const statusDiv = document.getElementById('status');
-            statusDiv.style.display = 'block';
-            statusDiv.style.backgroundColor = '#ffffcc';
-            statusDiv.innerHTML = 'Removing remote services for ' + ip + '...';
-
-            try {
-                const response = await fetch('/setup/remove-remote-services/' + ip, { method: 'POST' });
-                const result = await response.json();
-                if (result.ok) {
-                    statusDiv.style.backgroundColor = '#ccffcc';
-                    statusDiv.innerHTML = 'Successfully removed remote services from ' + ip + '.';
-                } else {
-                    statusDiv.style.backgroundColor = '#ffcccc';
-                    statusDiv.innerHTML = 'Failed to remove remote services for ' + ip + ': ' + (result.message || 'Unknown error');
-                }
-            } catch (error) {
-                statusDiv.style.backgroundColor = '#ffcccc';
-                statusDiv.innerHTML = 'Error removing remote services for ' + ip + ': ' + error;
-            }
-        }
-
-        async function backupConfig(ip) {
-            if (!ip) {
-                alert('Please enter a valid IP address.');
-                return;
-            }
-            const statusDiv = document.getElementById('status');
-            statusDiv.style.display = 'block';
-            statusDiv.style.backgroundColor = '#ffffcc';
-            statusDiv.innerHTML = 'Creating backup for ' + ip + '...';
-
-            try {
-                const response = await fetch('/setup/backup/' + ip, { method: 'POST' });
-                const result = await response.json();
-                if (result.ok) {
-                    statusDiv.style.backgroundColor = '#ccffcc';
-                    statusDiv.innerHTML = 'Successfully created backup for ' + ip + '.';
-                    showSummary(ip); // Refresh
-                } else {
-                    statusDiv.style.backgroundColor = '#ffcccc';
-                    statusDiv.innerHTML = 'Backup failed for ' + ip + ': ' + (result.message || 'Unknown error');
-                }
-            } catch (error) {
-                statusDiv.style.backgroundColor = '#ffcccc';
-                statusDiv.innerHTML = 'Error creating backup for ' + ip + ': ' + error;
-            }
-        }
-
-        function toggleOriginalConfig() {
-            const pane = document.getElementById('original-config-pane');
-            pane.style.display = pane.style.display === 'none' ? 'block' : 'none';
-        }
-
-        fetchDevices();
-        fetchSettings();
-        triggerDiscovery();
-    </script>
-</body>
-</html>

pkg/service/handlers/interactions_test.go

@@ -0,0 +1,161 @@
+package handlers
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/gesellix/bose-soundtouch/pkg/service/proxy"
+	"github.com/go-chi/chi/v5"
+)
+
+func TestInteractionHandlers(t *testing.T) {
+	t.Setenv("RECORDER_ASYNC", "false")
+	tmpDir, err := os.MkdirTemp("", "interaction-handlers-test")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	ds := datastore.NewDataStore(filepath.Join(tmpDir, "test.db"))
+	server := &Server{ds: ds}
+
+	t.Run("HandleGetInteractionStats_NoRecorder", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/setup/interaction-stats", nil)
+		w := httptest.NewRecorder()
+		server.HandleGetInteractionStats(w, req)
+		if w.Code != http.StatusServiceUnavailable {
+			t.Errorf("Expected status 503, got %d", w.Code)
+		}
+	})
+
+	recorder := proxy.NewRecorder(tmpDir)
+	server.SetRecorder(recorder)
+
+	// Create a dummy interaction file
+	sessionID := recorder.SessionID
+	relPath := filepath.Join(sessionID, "self", "test", "0001-12-00-00.000-GET.http")
+	fullPath := filepath.Join(tmpDir, "interactions", relPath)
+	os.MkdirAll(filepath.Dir(fullPath), 0755)
+	os.WriteFile(fullPath, []byte("### GET /test\n\n> {% \n    // Response: 200 OK\n%}\n"), 0644)
+
+	r := chi.NewRouter()
+	r.Route("/setup", func(r chi.Router) {
+		r.Get("/interaction-stats", server.HandleGetInteractionStats)
+		r.Get("/interactions", server.HandleListInteractions)
+		r.Get("/interaction-content", server.HandleGetInteractionContent)
+	})
+
+	t.Run("HandleGetInteractionStats", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/setup/interaction-stats", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("Expected status 200, got %d", w.Code)
+		}
+
+		var stats proxy.InteractionStats
+		if err := json.NewDecoder(w.Body).Decode(&stats); err != nil {
+			t.Fatalf("Failed to decode stats: %v", err)
+		}
+
+		if stats.TotalRequests != 1 {
+			t.Errorf("Expected 1 total request, got %d", stats.TotalRequests)
+		}
+	})
+
+	t.Run("HandleListInteractions", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/setup/interactions?category=self", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("Expected status 200, got %d", w.Code)
+		}
+
+		var interactions []proxy.Interaction
+		if err := json.NewDecoder(w.Body).Decode(&interactions); err != nil {
+			t.Fatalf("Failed to decode interactions: %v", err)
+		}
+
+		if len(interactions) != 1 {
+			t.Errorf("Expected 1 interaction, got %d", len(interactions))
+		}
+	})
+
+	t.Run("HandleGetInteractionContent", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/setup/interaction-content?file="+relPath, nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusOK {
+			t.Errorf("Expected status 200, got %d", w.Code)
+		}
+
+		if !strings.Contains(w.Body.String(), "### GET /test") {
+			t.Errorf("Unexpected content: %s", w.Body.String())
+		}
+	})
+
+	t.Run("HandleGetInteractionContent_MissingFile", func(t *testing.T) {
+		req := httptest.NewRequest("GET", "/setup/interaction-content", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+		if w.Code != http.StatusBadRequest {
+			t.Errorf("Expected status 400, got %d", w.Code)
+		}
+	})
+}
+
+func TestRecordMiddleware(t *testing.T) {
+	t.Setenv("RECORDER_ASYNC", "false")
+	tmpDir, err := os.MkdirTemp("", "record-middleware-test")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	ds := datastore.NewDataStore(filepath.Join(tmpDir, "test.db"))
+	server := &Server{
+		ds:            ds,
+		recordEnabled: true,
+	}
+	recorder := proxy.NewRecorder(tmpDir)
+	server.SetRecorder(recorder)
+
+	r := chi.NewRouter()
+	r.Use(server.RecordMiddleware)
+	r.Get("/test-middleware", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("X-Test", "Value")
+		w.WriteHeader(http.StatusCreated)
+		w.Write([]byte("created"))
+
+		if f, ok := w.(http.Flusher); ok {
+			f.Flush()
+		}
+	})
+
+	req := httptest.NewRequest("GET", "/test-middleware", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusCreated {
+		t.Errorf("Expected status 201, got %d", w.Code)
+	}
+
+	t.Run("HandleRecordMiddleware_Disabled", func(t *testing.T) {
+		server.recordEnabled = false
+		req := httptest.NewRequest("GET", "/test-middleware", nil)
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+		if w.Code != http.StatusCreated {
+			t.Errorf("Expected status 201, got %d", w.Code)
+		}
+	})
+}

pkg/service/handlers/main_test.go

@@ -1,23 +1,24 @@
 package handlers
 
 import (
-	"net/http"
-	"net/url"
-
 	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
 	"github.com/go-chi/chi/v5"
 )
 
 func setupRouter(targetURL string, ds *datastore.DataStore) (*chi.Mux, *Server) {
-	target, _ := url.Parse(targetURL)
-	proxy := &reverseProxy{target: target}
-	server := &Server{ds: ds}
+	server := NewServer(ds, nil, "http://localhost:8000", false, false, false, false)
+	server.SetSoundcorkURL(targetURL)
 
 	r := chi.NewRouter()
+	r.Use(server.OriginMiddleware)
+	r.Use(server.ShortcutMiddleware)
+	r.Use(server.RecordMiddleware)
+
 	r.Get("/", server.HandleRoot)
 
-	// Setup media directory for tests
+	// Setup media and web directories for tests
 	r.Get("/media/*", server.HandleMedia())
+	r.Get("/web/*", server.HandleWeb())
 
 	// Setup BMX for tests
 	r.Route("/bmx", func(r chi.Router) {
@@ -28,6 +29,13 @@ func setupRouter(targetURL string, ds *datastore.DataStore) (*chi.Mux, *Server)
 		r.Post("/orion/v1/playback/station/{data}", server.HandleOrionPlayback)
 	})
 
+	// Legacy or direct domain calls without /bmx prefix
+	r.Get("/registry/v1/services", server.HandleBMXRegistry)
+	r.Get("/tunein/v1/playback/station/{stationID}", server.HandleTuneInPlayback)
+	r.Get("/tunein/v1/playback/episodes/{podcastID}", server.HandleTuneInPodcastInfo)
+	r.Get("/tunein/v1/playback/episode/{podcastID}", server.HandleTuneInPlaybackPodcast)
+	r.Post("/orion/v1/playback/station/{data}", server.HandleOrionPlayback)
+
 	// Setup Marge for tests
 	r.Route("/marge", func(r chi.Router) {
 		r.Get("/streaming/sourceproviders", server.HandleMargeSourceProviders)
@@ -42,29 +50,60 @@ func setupRouter(targetURL string, ds *datastore.DataStore) (*chi.Mux, *Server)
 		r.Get("/streaming/account/{account}/provider_settings", server.HandleMargeProviderSettings)
 		r.Get("/streaming/device/{device}/streaming_token", server.HandleMargeStreamingToken)
 		r.Post("/streaming/support/customersupport", server.HandleMargeCustomerSupport)
+		r.Get("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeGetDeviceSettings)
+		r.Post("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeUpdateDeviceSettings)
+		r.Get("/streaming/account/{account}/emailaddress", server.HandleMargeGetEmailAddress)
+	})
+
+	// Legacy or direct domain calls without /marge prefix
+	r.Get("/streaming/sourceproviders", server.HandleMargeSourceProviders)
+	r.Get("/accounts/{account}/full", server.HandleMargeAccountFull)
+	r.Post("/streaming/support/power_on", server.HandleMargePowerOn)
+	r.Get("/updates/soundtouch", server.HandleMargeSoftwareUpdate)
+	r.Get("/accounts/{account}/devices/{device}/presets", server.HandleMargePresets)
+	r.Post("/accounts/{account}/devices/{device}/presets/{presetNumber}", server.HandleMargeUpdatePreset)
+	r.Post("/accounts/{account}/devices/{device}/recents", server.HandleMargeAddRecent)
+	r.Post("/accounts/{account}/devices", server.HandleMargeAddDevice)
+	r.Delete("/accounts/{account}/devices/{device}", server.HandleMargeRemoveDevice)
+	r.Get("/streaming/account/{account}/provider_settings", server.HandleMargeProviderSettings)
+	r.Get("/streaming/device/{device}/streaming_token", server.HandleMargeStreamingToken)
+	r.Post("/streaming/support/customersupport", server.HandleMargeCustomerSupport)
+	r.Get("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeGetDeviceSettings)
+	r.Post("/streaming/device_setting/account/{account}/device/{device}/device_settings", server.HandleMargeUpdateDeviceSettings)
+	r.Get("/streaming/account/{account}/emailaddress", server.HandleMargeGetEmailAddress)
+
+	// Setup Customer for tests
+	r.Route("/customer", func(r chi.Router) {
+		r.Get("/account/{account}", server.HandleMargeAccountProfile)
+		r.Post("/account/{account}", server.HandleMargeUpdateAccountProfile)
+		r.Post("/account/{account}/password", server.HandleMargeChangePassword)
 	})
 
 	// Setup Setup for tests
 	r.Route("/setup", func(r chi.Router) {
+		r.Get("/devices", server.HandleListDiscoveredDevices)
+		r.Delete("/devices/{deviceId}", server.HandleRemoveDevice)
+		r.Get("/settings", server.HandleGetSettings)
+		r.Post("/settings", server.HandleUpdateSettings)
 		r.Get("/proxy-settings", server.HandleGetProxySettings)
 		r.Post("/proxy-settings", server.HandleUpdateProxySettings)
 		r.Post("/ensure-remote-services/{deviceIP}", server.HandleEnsureRemoteServices)
 		r.Post("/remove-remote-services/{deviceIP}", server.HandleRemoveRemoteServices)
+		r.Post("/migrate/{deviceIP}", server.HandleMigrateDevice)
+		r.Post("/revert/{deviceIP}", server.HandleRevertMigration)
+		r.Post("/reboot/{deviceIP}", server.HandleRebootDevice)
+		r.Post("/trust-ca/{deviceIP}", server.HandleTrustCACert)
+		r.Post("/test-connection/{deviceIP}", server.HandleTestConnection)
+		r.Post("/test-hosts/{deviceIP}", server.HandleTestHostsRedirection)
+		r.Get("/ca.crt", server.HandleGetCACert)
 	})
 
-	r.NotFound(func(w http.ResponseWriter, r *http.Request) {
-		proxy.ServeHTTP(w, r)
-	})
+	r.NotFound(server.HandleNotFound)
 
 	return r, server
 }
 
-type reverseProxy struct {
-	target *url.URL
-}
-
-func (p *reverseProxy) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	// Simplified proxy for testing
-	w.WriteHeader(http.StatusAccepted) // Custom status to identify proxy hit in tests
-	_, _ = w.Write([]byte("Proxied to " + p.target.String()))
+func init() {
+	// Silence logger for tests
+	// log.SetOutput(io.Discard)
 }

pkg/service/handlers/origin_middleware.go

@@ -0,0 +1,27 @@
+package handlers
+
+import (
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/go-chi/chi/v5/middleware"
+)
+
+// OriginMiddleware returns a middleware that logs whether the request was handled "self" or "upstream".
+func (s *Server) OriginMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+
+		ww := middleware.NewWrapResponseWriter(w, r.ProtoMajor)
+
+		next.ServeHTTP(ww, r)
+
+		origin := "self"
+		if ww.Header().Get("X-Proxy-Origin") != "" {
+			origin = "upstream"
+		}
+
+		log.Printf("[LOG] %s %s | %d | %s | %v", r.Method, r.URL.Path, ww.Status(), origin, time.Since(start))
+	})
+}

pkg/service/handlers/recorder_middleware.go

@@ -0,0 +1,99 @@
+package handlers
+
+import (
+	"bufio"
+	"bytes"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+)
+
+// RecordMiddleware returns a middleware that records "self" requests and responses.
+func (s *Server) RecordMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if s.recorder == nil || !s.recordEnabled {
+			next.ServeHTTP(w, r)
+			return
+		}
+
+		// Buffer the request body if it exists
+		var reqBody []byte
+
+		if r.Body != nil {
+			var err error
+
+			reqBody, err = io.ReadAll(r.Body)
+			if err == nil {
+				r.Body = io.NopCloser(bytes.NewBuffer(reqBody))
+			}
+		}
+
+		// wrap ResponseWriter to capture the response
+		rw := &responseWriter{
+			ResponseWriter: w,
+			body:           &bytes.Buffer{},
+		}
+
+		next.ServeHTTP(rw, r)
+
+		// Create a response object for the recorder
+		res := rw.getRecordedResponse(r)
+		if res.Body != nil {
+			defer func() { _ = res.Body.Close() }()
+		}
+
+		// Put back the original request body for recording
+		r.Body = io.NopCloser(bytes.NewBuffer(reqBody))
+
+		_ = s.recorder.Record("self", r, res)
+	})
+}
+
+type responseWriter struct {
+	http.ResponseWriter
+	statusCode int
+	body       *bytes.Buffer
+}
+
+func (rw *responseWriter) Header() http.Header {
+	return rw.ResponseWriter.Header()
+}
+
+func (rw *responseWriter) WriteHeader(code int) {
+	rw.statusCode = code
+	rw.ResponseWriter.WriteHeader(code)
+}
+
+func (rw *responseWriter) Write(b []byte) (int, error) {
+	rw.body.Write(b)
+	return rw.ResponseWriter.Write(b)
+}
+
+func (rw *responseWriter) getRecordedResponse(r *http.Request) *http.Response {
+	statusCode := rw.statusCode
+	if statusCode == 0 {
+		statusCode = http.StatusOK
+	}
+
+	return &http.Response{
+		StatusCode: statusCode,
+		Header:     rw.ResponseWriter.Header(),
+		Body:       io.NopCloser(bytes.NewBuffer(rw.body.Bytes())),
+		Request:    r,
+	}
+}
+
+func (rw *responseWriter) Flush() {
+	if f, ok := rw.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+func (rw *responseWriter) Hijack() (net.Conn, *bufio.ReadWriter, error) {
+	if h, ok := rw.ResponseWriter.(http.Hijacker); ok {
+		return h.Hijack()
+	}
+
+	return nil, nil, fmt.Errorf("ResponseWriter does not support Hijacker")
+}

pkg/service/handlers/server.go

@@ -3,37 +3,143 @@ package handlers
 import (
 	"context"
 	"log"
+	"net/http"
+	"sync"
 	"time"
 
 	"github.com/gesellix/bose-soundtouch/pkg/discovery"
 	"github.com/gesellix/bose-soundtouch/pkg/models"
 	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+	"github.com/gesellix/bose-soundtouch/pkg/service/proxy"
 	"github.com/gesellix/bose-soundtouch/pkg/service/setup"
 )
 
 // Server handles HTTP requests for the SoundTouch service.
 type Server struct {
-	ds           *datastore.DataStore
-	sm           *setup.Manager
-	serverURL    string
-	proxyURL     string
-	discovering  bool
-	proxyRedact  bool
-	proxyLogBody bool
+	ds                   *datastore.DataStore
+	sm                   *setup.Manager
+	mu                   sync.RWMutex
+	serverURL            string
+	soundcorkURL         string
+	httpsServerURL       string
+	discovering          bool
+	proxyRedact          bool
+	proxyLogBody         bool
+	recordEnabled        bool
+	discoveryInterval    time.Duration
+	discoveryEnabled     bool
+	enableSoundcorkProxy bool
+	shortcuts            map[string]int
+	recorder             *proxy.Recorder
+	UpstreamProxy        http.Handler
+	Version              string
+	Commit               string
+	Date                 string
 }
 
 // NewServer creates a new SoundTouch service server.
-func NewServer(ds *datastore.DataStore, sm *setup.Manager, serverURL string, proxyRedact, proxyLogBody bool) *Server {
+func NewServer(ds *datastore.DataStore, sm *setup.Manager, serverURL string, proxyRedact, proxyLogBody, recordEnabled, enableSoundcorkProxy bool) *Server {
 	return &Server{
-		ds:           ds,
-		sm:           sm,
-		serverURL:    serverURL,
-		proxyURL:     serverURL,
-		proxyRedact:  proxyRedact,
-		proxyLogBody: proxyLogBody,
+		ds:                   ds,
+		sm:                   sm,
+		serverURL:            serverURL,
+		soundcorkURL:         "http://localhost:8001",
+		proxyRedact:          proxyRedact,
+		proxyLogBody:         proxyLogBody,
+		recordEnabled:        recordEnabled,
+		enableSoundcorkProxy: enableSoundcorkProxy,
+		discoveryInterval:    5 * time.Minute,
 	}
 }
 
+// SetVersionInfo sets the version information for the server.
+func (s *Server) SetVersionInfo(version, commit, date string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.Version = version
+	s.Commit = commit
+	s.Date = date
+}
+
+// SetDiscoverySettings sets the discovery settings for the server.
+func (s *Server) SetDiscoverySettings(interval time.Duration, enabled bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.discoveryInterval = interval
+	s.discoveryEnabled = enabled
+}
+
+// SetShortcuts sets the request shortcuts for the server.
+func (s *Server) SetShortcuts(shortcuts map[string]int) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.shortcuts = shortcuts
+}
+
+// GetShortcuts returns the current request shortcuts.
+func (s *Server) GetShortcuts() map[string]int {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return s.shortcuts
+}
+
+// GetDiscoverySettings returns the current discovery settings.
+func (s *Server) GetDiscoverySettings() (time.Duration, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return s.discoveryInterval, s.discoveryEnabled
+}
+
+// SetHTTPServerURL sets the external HTTPS URL of the service.
+func (s *Server) SetHTTPServerURL(url string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.httpsServerURL = url
+}
+
+// SetSoundcorkURL sets the URL for the Soundcork backend.
+func (s *Server) SetSoundcorkURL(url string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	s.soundcorkURL = url
+}
+
+// SetRecorder sets the recorder for the server.
+func (s *Server) SetRecorder(r *proxy.Recorder) {
+	s.recorder = r
+}
+
+// GetRecordEnabled returns whether recording is enabled.
+func (s *Server) GetRecordEnabled() bool {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return s.recordEnabled
+}
+
+// GetSettings returns the current server settings.
+func (s *Server) GetSettings() (string, string, string) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return s.serverURL, s.soundcorkURL, s.httpsServerURL
+}
+
+// GetProxySettings returns the current proxy settings.
+func (s *Server) GetProxySettings() (bool, bool, bool, bool) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return s.proxyRedact, s.proxyLogBody, s.recordEnabled, s.enableSoundcorkProxy
+}
+
 // DiscoverDevices starts a background device discovery process.
 //
 //nolint:contextcheck
@@ -44,16 +150,18 @@ func (s *Server) DiscoverDevices(ctx context.Context) {
 
 	log.Println("Scanning for Bose devices...")
 
+	// Use background context if none provided or if it's likely a request context
 	if ctx == nil {
-		var cancel context.CancelFunc
-
-		ctx, cancel = context.WithTimeout(context.Background(), 10*time.Second)
-		defer cancel()
+		ctx = context.Background()
 	}
 
+	// Always wrap in a timeout to prevent hanging forever
+	discoveryCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+
 	svc := discovery.NewService(10 * time.Second)
 
-	devices, err := svc.DiscoverDevices(ctx)
+	devices, err := svc.DiscoverDevices(discoveryCtx)
 	if err != nil {
 		log.Printf("Discovery error: %v", err)
 		return
@@ -62,12 +170,15 @@ func (s *Server) DiscoverDevices(ctx context.Context) {
 	for _, d := range devices {
 		s.handleDiscoveredDevice(*d)
 	}
+
+	// Post-discovery cleanup: merge overlapping IP/Serial entries
+	s.mergeOverlappingDevices()
 }
 
 func (s *Server) handleDiscoveredDevice(d models.DiscoveredDevice) {
 	log.Printf("Discovered Bose device: %s at %s (Serial: %s)", d.Name, d.Host, d.SerialNo)
 
-	// 1. Check if we already have this device by serial number (best identifier)
+	// 1. Check if we already have this device
 	existingID := s.findExistingDeviceID(d)
 
 	// Use SerialNo if available, otherwise fallback to IP for the datastore directory name
@@ -87,37 +198,142 @@ func (s *Server) handleDiscoveredDevice(d models.DiscoveredDevice) {
 		deviceID = d.Host
 	}
 
+	accountID := ""
+
+	if liveInfo, err := s.sm.GetLiveDeviceInfo(d.Host); err == nil {
+		if liveInfo.MargeAccountUUID != "" {
+			accountID = liveInfo.MargeAccountUUID
+		}
+
+		if liveInfo.SerialNumber != "" {
+			d.SerialNo = liveInfo.SerialNumber
+			deviceID = d.SerialNo
+		}
+	}
+
+	if accountID == "" {
+		// Try to find account ID from existing device entries if live info failed
+		if existing := s.findExistingDeviceInfo(d); existing != nil {
+			accountID = existing.AccountID
+		}
+	}
+
+	if accountID == "" {
+		accountID = "default"
+	}
+
 	info := &models.ServiceDeviceInfo{
-		DeviceID:           d.SerialNo,
+		DeviceID:           deviceID,
+		AccountID:          accountID,
 		Name:               d.Name,
 		IPAddress:          d.Host,
 		DeviceSerialNumber: d.SerialNo,
 		ProductCode:        d.ModelID,
 		FirmwareVersion:    "0.0.0", // Unknown from discovery
+		DiscoveryMethod:    d.DiscoveryMethod,
 	}
 
 	// If we had an IP-based entry and now have a Serial, clean up the IP-based entry
 	if d.SerialNo != "" && existingID != "" && existingID != d.SerialNo {
 		log.Printf("Device %s previously known as %s, migrating to serial-based ID %s", d.Name, existingID, d.SerialNo)
-		_ = s.ds.RemoveDevice("default", existingID)
+		_ = s.ds.RemoveDevice(accountID, existingID)
 	}
 
-	if err := s.ds.SaveDeviceInfo("default", deviceID, info); err != nil {
+	if err := s.ds.SaveDeviceInfo(accountID, deviceID, info); err != nil {
 		log.Printf("Failed to save device info: %v", err)
 	}
 }
 
-func (s *Server) findExistingDeviceID(d models.DiscoveredDevice) string {
-	allDevices, _ := s.ds.ListAllDevices()
-	for _, known := range allDevices {
-		if d.SerialNo != "" && (known.DeviceID == d.SerialNo || known.DeviceSerialNumber == d.SerialNo) {
-			if known.DeviceID != "" {
-				return known.DeviceID
+func (s *Server) mergeOverlappingDevices() {
+	allDevices, err := s.ds.ListAllDevices()
+	if err != nil {
+		return
+	}
+
+	// Group devices by IP
+	byIP := make(map[string][]models.ServiceDeviceInfo)
+
+	for i := range allDevices {
+		dev := allDevices[i]
+		if dev.IPAddress != "" {
+			byIP[dev.IPAddress] = append(byIP[dev.IPAddress], dev)
+		}
+	}
+
+	for ip, devices := range byIP {
+		if len(devices) <= 1 {
+			continue
+		}
+
+		// We have multiple entries for the same IP.
+		// Try to find one with a Serial Number to be the master.
+		var master *models.ServiceDeviceInfo
+
+		for i := range devices {
+			if devices[i].DeviceSerialNumber != "" {
+				master = &devices[i]
+				break
+			}
+		}
+
+		if master == nil {
+			// Fallback: look for one with DeviceID that isn't the IP
+			for i := range devices {
+				if devices[i].DeviceID != "" && devices[i].DeviceID != devices[i].IPAddress {
+					master = &devices[i]
+					break
+				}
+			}
+		}
+
+		if master == nil {
+			// None have serials, just keep the first one
+			continue
+		}
+
+		masterID := master.DeviceID
+		if masterID == "" {
+			masterID = master.DeviceSerialNumber
+		}
+
+		for i := range devices {
+			dev := devices[i]
+			devID := dev.DeviceID
+
+			if devID == "" {
+				devID = dev.IPAddress
 			}
 
-			return known.IPAddress
+			if devID != masterID && dev.IPAddress == ip {
+				log.Printf("Merging overlapping device entry %s into %s (IP: %s)", devID, masterID, ip)
+				_ = s.ds.RemoveDevice(dev.AccountID, devID)
+			}
 		}
 	}
+}
+
+func (s *Server) findExistingDeviceID(d models.DiscoveredDevice) string {
+	info := s.findExistingDeviceInfo(d)
+	if info != nil {
+		return info.DeviceID
+	}
 
 	return ""
 }
+
+func (s *Server) findExistingDeviceInfo(d models.DiscoveredDevice) *models.ServiceDeviceInfo {
+	allDevices, _ := s.ds.ListAllDevices()
+	for i := range allDevices {
+		known := allDevices[i]
+		// Match by Serial
+		if d.SerialNo != "" && (known.DeviceID == d.SerialNo || known.DeviceSerialNumber == d.SerialNo) {
+			return &known
+		}
+		// Match by IP
+		if d.Host != "" && known.IPAddress == d.Host {
+			return &known
+		}
+	}
+
+	return nil
+}

pkg/service/handlers/server_merge_test.go

@@ -0,0 +1,130 @@
+package handlers
+
+import (
+	"os"
+	"testing"
+
+	"github.com/gesellix/bose-soundtouch/pkg/models"
+	"github.com/gesellix/bose-soundtouch/pkg/service/datastore"
+)
+
+func TestMergeOverlappingDevices(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "merge-test-*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	ds := datastore.NewDataStore(tempDir)
+	s := &Server{ds: ds}
+
+	// Case 1: IP-only entry and Serial-based entry for the same IP
+	ip := "192.168.1.100"
+	serial := "SERIAL123"
+
+	// 1. Save IP-based entry
+	infoIP := &models.ServiceDeviceInfo{
+		DeviceID:    ip,
+		Name:        "Speaker IP",
+		IPAddress:   ip,
+		AccountID:   "default",
+		ProductCode: "ST10",
+	}
+	err = ds.SaveDeviceInfo("default", ip, infoIP)
+	if err != nil {
+		t.Fatalf("Failed to save IP info: %v", err)
+	}
+
+	// 2. Save Serial-based entry
+	infoSerial := &models.ServiceDeviceInfo{
+		DeviceID:           serial,
+		DeviceSerialNumber: serial,
+		Name:               "Speaker Serial",
+		IPAddress:          ip,
+		AccountID:          "default",
+		ProductCode:        "ST10",
+	}
+	err = ds.SaveDeviceInfo("default", serial, infoSerial)
+	if err != nil {
+		t.Fatalf("Failed to save Serial info: %v", err)
+	}
+
+	// Verify both exist
+	devices, _ := ds.ListAllDevices()
+	if len(devices) != 2 {
+		t.Fatalf("Expected 2 devices before merge, got %d", len(devices))
+	}
+
+	// Run merge
+	s.mergeOverlappingDevices()
+
+	// Verify merge
+	devices, _ = ds.ListAllDevices()
+	if len(devices) != 1 {
+		t.Fatalf("Expected 1 device after merge, got %d", len(devices))
+	}
+
+	if devices[0].DeviceID != serial {
+		t.Errorf("Expected remaining device to be Serial-based (%s), got %s", serial, devices[0].DeviceID)
+	}
+}
+
+func TestFindExistingDeviceID(t *testing.T) {
+	tempDir, _ := os.MkdirTemp("", "find-test-*")
+	defer os.RemoveAll(tempDir)
+
+	ds := datastore.NewDataStore(tempDir)
+	s := &Server{ds: ds}
+
+	ip := "192.168.1.101"
+	serial := "SERIAL456"
+
+	// Save IP-based
+	ds.SaveDeviceInfo("default", ip, &models.ServiceDeviceInfo{
+		DeviceID:    ip,
+		IPAddress:   ip,
+		Name:        "IP Speaker",
+		AccountID:   "default",
+		ProductCode: "ST10",
+	})
+
+	// Test finding by IP
+	foundID := s.findExistingDeviceID(models.DiscoveredDevice{
+		Host: ip,
+	})
+	if foundID != ip {
+		t.Errorf("Expected to find by IP, got %s", foundID)
+	}
+
+	// Save Serial-based for SAME IP
+	ds.SaveDeviceInfo("default", serial, &models.ServiceDeviceInfo{
+		DeviceID:           serial,
+		DeviceSerialNumber: serial,
+		IPAddress:          ip,
+		Name:               "Serial Speaker",
+		AccountID:          "default",
+		ProductCode:        "ST10",
+	})
+
+	// Test finding by IP should now return Serial (if Serial is known)
+	// Actually findExistingDeviceID returns the first match it finds in allDevices.
+	// Since we haven't merged yet, it could be either.
+
+	// Test finding by Serial
+	foundID = s.findExistingDeviceID(models.DiscoveredDevice{
+		Host:     ip,
+		SerialNo: serial,
+	})
+	if foundID != serial && foundID != ip {
+		t.Errorf("Expected to find by Serial or IP, got %s", foundID)
+	}
+
+	// Merge and check again
+	s.mergeOverlappingDevices()
+	foundID = s.findExistingDeviceID(models.DiscoveredDevice{
+		Host: ip,
+	})
+	if foundID != serial {
+		t.Errorf("After merge, expected to find Serial ID for IP, got %s", foundID)
+	}
+}

pkg/service/handlers/shortcut_middleware.go

@@ -0,0 +1,23 @@
+package handlers
+
+import (
+	"net/http"
+)
+
+// ShortcutMiddleware returns a middleware that shortcuts requests to specific paths.
+func (s *Server) ShortcutMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		s.mu.RLock()
+		shortcuts := s.shortcuts
+		s.mu.RUnlock()
+
+		if shortcuts != nil {
+			if status, ok := shortcuts[r.URL.Path]; ok {
+				w.WriteHeader(status)
+				return
+			}
+		}
+
+		next.ServeHTTP(w, r)
+	})
+}