Merge remote-tracking branch 'upstream/main'

Author: tomballgithub

README.md

@@ -25,7 +25,7 @@ Powerful real-time tracker for Spotify friend music activity: monitor listening
 pip install spotify_monitor
 ```
 
-Run setup by itself:
+Run setup wizard:
 
 ```sh
 spotify_monitor --setup
@@ -41,30 +41,16 @@ Use a macOS shell or Windows PowerShell with a Docker-compatible runtime that pr
 docker run --rm --pull=always -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
 ```
 
-After setup finishes, start monitoring with the files created by the wizard:
-
-```sh
-docker run --rm -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
-```
-
-The setup command pulls the current image. Both commands keep configuration, private values and output in the current directory.
-
-In Windows Command Prompt replace `${PWD}` with `%cd%`. Windows hosts must use Linux containers.
+In Windows Command Prompt replace `${PWD}` with `%cd%` above.
 
 ##### Linux
 
-`--user "$(id -u):$(id -g)"` runs the container with your numeric user and group IDs. This lets the container write files that your host account can edit.
+Run the container with your numeric user and group IDs (`--user "$(id -u):$(id -g)"` below). This lets the container write files that your host account can edit.
 
 ```sh
 docker run --rm --pull=always -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --setup
 ```
 
-After setup finishes, start monitoring:
-
-```sh
-docker run --rm -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
-```
-
 #### Docker Compose - shorter recurring commands
 
 Download the Compose file:
@@ -82,18 +68,12 @@ export SPOTIFY_MONITOR_GID="$(id -g)"
 
 Docker-compatible runtimes on macOS and Windows normally do not need these values.
 
-Run setup by itself:
+Run setup wizard:
 
 ```sh
 docker compose run --rm --pull=always spotify_monitor --setup
 ```
 
-After setup finishes, start monitoring with the shorter recurring command:
-
-```sh
-docker compose up --no-log-prefix
-```
-
 For the manual single-file method, optional extras and upgrade commands for every method, see [Installation](https://misiektoja.github.io/spotify_monitor/installation/).
 
 <a id="features"></a>
@@ -147,12 +127,10 @@ Spotify only shows a person's listening activity when both of these conditions a
 
 The setup wizard checks whether the monitoring account follows the target. It can send the follow request after you confirm. To follow manually, open the target's profile in the Spotify desktop or mobile app. You can use **Share** > **Copy link to profile** and paste the complete link into the wizard. You do not need to extract the user ID. See [Following the Monitored User](https://misiektoja.github.io/spotify_monitor/configuration/#following-the-monitored-user).
 
-Firefox import is the recommended login path for local and container installs. See [Container Operation](https://misiektoja.github.io/spotify_monitor/usage/#import-firefox-into-container-authentication) for the host-specific import commands.
-
 <a id="common-commands"></a>
 ## Common Commands
 
-Use [Quick Install & Run](#-quick-install-run) above for first-time setup. The table uses PyPI commands. For manual script, direct Docker and Docker Compose equivalents, see [Run Individual Commands](https://misiektoja.github.io/spotify_monitor/quick-start/#run-individual-commands).
+Use [Quick Install & Run](#-quick-install-run) above for first-time setup. The table uses PyPI commands. For manual script, direct Docker and Docker Compose equivalents, see [Run Individual Commands](https://misiektoja.github.io/spotify_monitor/setup-and-first-run/#run-individual-commands).
 
 | I want to... | Run this |
 | --- | --- |
@@ -166,7 +144,7 @@ Use [Quick Install & Run](#-quick-install-run) above for first-time setup. The t
 
 Running the tool with no arguments offers the wizard if you have not saved a target. If a target is already saved, it starts monitoring that target.
 
-For authentication, saved targets, configuration backups and setup recovery, see the [full Quick Start guide](https://misiektoja.github.io/spotify_monitor/quick-start/).
+For authentication, saved targets, configuration backups and setup recovery, see the [full Setup & First Run guide](https://misiektoja.github.io/spotify_monitor/setup-and-first-run/).
 
 For browser profiles, manual cookie extraction, Docker authentication, email and webhook setup, see [Configuration](https://misiektoja.github.io/spotify_monitor/configuration/). For notification choices, playback controls and output files, see [Usage](https://misiektoja.github.io/spotify_monitor/usage/).
 
@@ -176,7 +154,7 @@ For browser profiles, manual cookie extraction, Docker authentication, email and
 Full documentation is available at **[misiektoja.github.io/spotify_monitor](https://misiektoja.github.io/spotify_monitor/)**:
 
 - [Installation](https://misiektoja.github.io/spotify_monitor/installation/) - PyPI, manual script, Docker installation and upgrades
-- [Quick Start](https://misiektoja.github.io/spotify_monitor/quick-start/) - setup wizard, authentication and first run
+- [Setup & First Run](https://misiektoja.github.io/spotify_monitor/setup-and-first-run/) - setup wizard, authentication and first run
 - [Configuration](https://misiektoja.github.io/spotify_monitor/configuration/) - Spotify login, targets, SMTP, webhooks and secrets
 - [Usage](https://misiektoja.github.io/spotify_monitor/usage/) - command formats, monitoring, container operation, notifications, playback and output
 - [Troubleshooting](https://misiektoja.github.io/spotify_monitor/troubleshooting/) - the `--doctor` self-check and logging levels

RELEASE_NOTES.md

@@ -2,6 +2,12 @@
 
 This is a high-level summary of the most important changes.
 
+# Changes in 3.1.1 (24 Jul 2026)
+
+**Bug fixes**:
+
+- **BUGFIX:** Updated the built-in guide link to the renamed **Setup & First Run** page so CLI help and recovery guidance no longer point to the retired Quick Start URL
+
 # Changes in 3.1 (23 Jul 2026)
 
 Version **3.1** makes **Docker onboarding portable across macOS, Linux and Windows**. Setup now centers on **host-aware Firefox authentication**, keeps configuration and secrets on the persistent **`/data` bind mount** and carries exact **Doctor and monitoring commands** through recovery.

docs/configuration.md

@@ -140,7 +140,7 @@ Follow these steps:
 
 As an alternative, [Cookie-Editor by cgagnier](https://cookie-editor.com/) can display the `sp_dc` value. Only use a browser extension that you trust because browser extensions can access sensitive login cookies.
 
-The recommended `--set-sp-dc` command validates the cookie with Spotify before changing `.env`. Existing cookie replacement requires confirmation. See the [copy-paste commands](quick-start.md#run-individual-commands) for PyPI, downloaded-script, Docker Compose and Docker installations.
+The recommended `--set-sp-dc` command validates the cookie with Spotify before changing `.env`. Existing cookie replacement requires confirmation. See the [copy-paste commands](setup-and-first-run.md#run-individual-commands) for PyPI, downloaded-script, Docker Compose and Docker installations.
 
 You can also provide `SP_DC_COOKIE` in these ways:
 

docs/debugging.md

@@ -35,6 +35,9 @@ The command prints the access token response. Example output:
 
 ```sh
 python3 spotify_monitor_totp_test.py --sp-dc "your_sp_dc_cookie_value" --fetch-secrets
+```
+
+```sh
 python3 spotify_monitor_totp_test.py --sp-dc "your_sp_dc_cookie_value" --download-secrets
 ```
 

docs/index.md

@@ -25,7 +25,7 @@ Powerful real-time tracker for Spotify friend music activity: monitor listening
 pip install spotify_monitor
 ```
 
-Run setup by itself:
+Run setup wizard:
 
 ```sh
 spotify_monitor --setup
@@ -41,32 +41,16 @@ Use a macOS shell or Windows PowerShell with a Docker-compatible runtime that pr
 docker run --rm --pull=always -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
 ```
 
-After setup finishes, start monitoring with the files created by the wizard:
-
-```sh
-docker run --rm -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
-```
-
-The setup command pulls the current image. Both commands keep configuration, private values and output in the current directory.
-
-In Windows Command Prompt replace `${PWD}` with `%cd%`. Windows hosts must use Linux containers.
-
-When setup asks how to import Firefox on Windows, choose PowerShell or Command Prompt. The wizard prints the matching direct Docker command with the current directory mounted at `/data` and the Firefox profile under `%APPDATA%\Mozilla\Firefox` mounted read-only. The same host choice also prints the matching Docker Compose import command.
+In Windows Command Prompt replace `${PWD}` with `%cd%` above.
 
 ##### Linux
 
-`--user "$(id -u):$(id -g)"` runs the container with your numeric user and group IDs. This lets the container write files that your host account can edit.
+Run the container with your numeric user and group IDs (`--user "$(id -u):$(id -g)"` below). This lets the container write files that your host account can edit.
 
 ```sh
 docker run --rm --pull=always -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --setup
 ```
 
-After setup finishes, start monitoring:
-
-```sh
-docker run --rm -it --init --user "$(id -u):$(id -g)" -v "$PWD:/data:z" misiektoja/spotify-monitor:latest --config-file /data/spotify_monitor.conf
-```
-
 #### Docker Compose - shorter recurring commands
 
 Download the Compose file:
@@ -75,26 +59,22 @@ Download the Compose file:
 curl -fsSLO https://raw.githubusercontent.com/misiektoja/spotify_monitor/refs/heads/main/docker-compose.yml
 ```
 
-On a native Linux container engine, export your numeric user ID and group ID so files created in the current directory belong to you instead of `root`. Docker-compatible runtimes on macOS and Windows normally do not need these values.
+Linux container engine requires to export your numeric user ID and group ID so files created in the current directory belong to you instead of `root`.
 
 ```sh
 export SPOTIFY_MONITOR_UID="$(id -u)"
 export SPOTIFY_MONITOR_GID="$(id -g)"
 ```
 
-Run setup by itself:
+Docker-compatible runtimes on macOS and Windows normally do not need these values.
 
-```sh
-docker compose run --rm --pull=always spotify_monitor --setup
-```
-
-After setup finishes, start monitoring with the shorter recurring command:
+Run setup wizard:
 
 ```sh
-docker compose up --no-log-prefix
+docker compose run --rm --pull=always spotify_monitor --setup
 ```
 
-For the manual single-file method, optional extras and upgrade commands for every method, see [Installation](installation.md).
+For the manual single-file method, optional extras and upgrade commands for every method, see [Installation](https://misiektoja.github.io/spotify_monitor/installation/).
 
 <a id="features"></a>
 ## Features

docs/installation.md

@@ -11,8 +11,8 @@ Choose either the Python path or the container path.
 
 - [Python](https://www.python.org/downloads/) 3.9 or higher
 - Core libraries: `requests`, `python-dateutil`, `urllib3`, `pyotp`, `python-dotenv`, `wcwidth`, `Pillow`
-- `spotipy` is optional and is needed only for legacy OAuth metadata access
-- `pycookiecheat` is optional and is needed only to import cookies from Chrome, Brave or Chromium
+- [spotipy](https://github.com/spotipy-dev/spotipy) is optional and is needed only for legacy OAuth metadata access
+- [pycookiecheat](https://github.com/n8henrie/pycookiecheat) is optional and is needed only to import cookies from Chrome, Brave or Chromium
 
 **Container path** (Python is included in the image):
 
@@ -30,9 +30,9 @@ The examples use the `docker` command. Check that it works with `docker --versio
 
 Tested on:
 
-* **macOS**: Ventura, Sonoma, Sequoia, Tahoe
-* **Linux**: Raspberry Pi OS (Bullseye, Bookworm, Trixie), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2024/2025
-* **Windows**: 10, 11
+* **macOS**: Tahoe, Sequoia, Sonoma, Ventura
+* **Linux**: Raspberry Pi OS (Trixie, Bookworm, Bullseye), Ubuntu 24/25, Rocky Linux 8.x/9.x, Kali Linux 2026/2025/2024
+* **Windows**: 11, 10
 
 It should work on other versions of macOS, Linux, Unix and Windows as well.
 
@@ -127,13 +127,19 @@ Use `python spotify_monitor.py --version` on Windows.
 <a id="docker-image"></a>
 ### Install from Docker Hub
 
-The published [`misiektoja/spotify-monitor`](https://hub.docker.com/r/misiektoja/spotify-monitor) image supports `linux/amd64` and `linux/arm64`:
+The published [`misiektoja/spotify-monitor`](https://hub.docker.com/r/misiektoja/spotify-monitor) image supports `linux/amd64` and `linux/arm64`.
 
-No separate image download is required. Continue to [Quick Start](quick-start.md#new-here-run-the-setup-wizard). Its first-run command uses `docker run --pull=always` to pull the current image and start the setup wizard in one step.
+No separate image download is required. Its first-run command uses `docker run --pull=always` to pull the current image and start the setup wizard in one step, so for Docker installing and setting up are a single command:
+
+```sh
+docker run --rm --pull=always -it --init -v "${PWD}:/data:z" misiektoja/spotify-monitor:latest --setup
+```
+
+On a native Linux container engine, add `--user "$(id -u):$(id -g)"` immediately after `--init`. [Setup & First Run](setup-and-first-run.md#new-here-run-the-setup-wizard) shows the exact command for macOS shells, Windows PowerShell and native Linux engines then explains what the wizard asks.
 
 Normal monitoring commands reuse the installed image and do not check for a newer release. The [upgrade instructions](#upgrade-a-direct-docker-installation) pull explicitly when you choose to upgrade.
 
-Normal runs make the current directory available as `/data` in the container. Configuration and output written there remain on the host after the temporary container stops. On a native Linux container engine, the command also passes your numeric user and group IDs so new files belong to you. [Quick Start](quick-start.md#new-here-run-the-setup-wizard) shows the complete commands for macOS shells, Windows PowerShell and native Linux engines.
+Normal runs make the current directory available as `/data` in the container. Configuration and output written there remain on the host after the temporary container stops. On a native Linux container engine, the command also passes your numeric user and group IDs so new files belong to you.
 
 The macOS shell and Windows PowerShell examples use `${PWD}`. In Windows Command Prompt use `%cd%` for the current directory. Native Linux examples use `$PWD` and pass your numeric user and group IDs.
 
@@ -170,7 +176,13 @@ SPOTIFY_MONITOR_GID=1000
 
 The values above are only examples. Use the numbers returned on your system. The setup wizard keeps unrelated entries in this file. Docker-compatible runtimes on macOS and Windows normally handle bind-mount ownership, so users on those systems can usually skip this step. If `/data` is not writable, set the host user and group IDs as shown above.
 
-Compose makes the current host directory available as `/data` inside the container. This is called a bind mount. The setup wizard creates `spotify_monitor.conf` and `.env` there, so the files remain on your computer when the container is replaced. Keep this directory and continue with [Quick Start](quick-start.md#new-here-run-the-setup-wizard). Its Compose setup command pulls the current image with `--pull=always`, so no separate `docker compose pull` is needed during onboarding.
+Compose makes the current host directory available as `/data` inside the container. This is called a bind mount. The setup wizard creates `spotify_monitor.conf` and `.env` there, so the files remain on your computer when the container is replaced. From this directory your first command is the setup wizard:
+
+```sh
+docker compose run --rm --pull=always spotify_monitor --setup
+```
+
+The `--pull=always` flag pulls the current image first, so no separate `docker compose pull` is needed during onboarding. On a native Linux container engine, export the UID and GID shown above in the same terminal before you run setup. See [Setup & First Run](setup-and-first-run.md#new-here-run-the-setup-wizard) for the wizard walkthrough.
 
 <a id="build-docker-locally"></a>
 ### Build the Docker Image Locally
@@ -187,7 +199,7 @@ To use this image through Compose, comment out `image:` in `docker-compose.yml`
 <a id="next-step"></a>
 ## Next Step
 
-Continue to [Quick Start](quick-start.md). It shows the setup wizard command for every installation method then explains authentication and the first monitoring run.
+Continue to [Setup & First Run](setup-and-first-run.md). It shows the setup wizard command for every installation method then explains authentication and the first monitoring run.
 
 <a id="upgrading"></a>
 ## Upgrading

docs/quick-start.md docs/setup-and-first-run.mddocs/quick-start.md renamed to docs/setup-and-first-run.md

@@ -1,9 +1,9 @@
-# Quick Start
+# Setup & First Run
 
 <a id="new-here-run-the-setup-wizard"></a>
-## New here? Run the setup wizard
+## Run the setup wizard
 
-Quick Start configures an existing installation. If you opened this page first, choose [PyPI](installation.md#install-from-pypi), the [manual Python script](installation.md#manual-installation), the [Docker image](installation.md#docker-image) or [Docker Compose](installation.md#docker-compose). Complete that method's prerequisites and return here.
+This page assumes Spotify Monitor is already installed (see [Installation](installation.md)). It walks through the interactive setup wizard then your first monitoring run. If you opened this page first, choose [PyPI](installation.md#install-from-pypi), the [manual Python script](installation.md#manual-installation), the [Docker image](installation.md#docker-image) or [Docker Compose](installation.md#docker-compose), finish that method's steps then return here.
 
 Then use the interactive setup wizard. It asks who to monitor, how to connect to Spotify and which alerts to enable. You can review and change your answers before saving. Regular settings go in `spotify_monitor.conf`. Private values such as login cookies and webhook URLs go in `.env`.
 
@@ -74,7 +74,7 @@ After saving authentication, the wizard checks whether the monitoring account fo
 
 For Docker or Docker Compose, choose **Import from Firefox after setup**. The wizard asks whether Docker runs on macOS, standard Linux, Linux with Snap, Linux with Flatpak, Windows PowerShell or Windows Command Prompt. It then prints the matching command to mount the signed-in host profile read-only once and save `SP_DC_COOKIE` in the host `.env` file. Windows commands use the Firefox profile under `%APPDATA%\Mozilla\Firefox`. Use [manual extraction](configuration.md#manual-cookie-extraction) only when that mount is unavailable.
 
-If the selected configuration contains `TARGET_USER_URI_ID`, running Spotify Monitor without a target starts that saved user. If no target is saved, an interactive no-argument run shows quick-start guidance and offers the setup wizard.
+If the selected configuration contains `TARGET_USER_URI_ID`, running Spotify Monitor without a target starts that saved user. If no target is saved, an interactive no-argument run shows setup guidance and offers the setup wizard.
 
 If the selected `.env` file already contains a saved `SP_DC_COOKIE`, container setup offers to keep it. Otherwise Firefox import remains the default. Setup does not run Doctor while that import is pending. It finishes with the host-specific import command followed by the Doctor and monitoring commands.
 
@@ -198,3 +198,8 @@ To see all supported command-line arguments and flags:
 ```sh
 spotify_monitor --help
 ```
+
+<a id="next-step"></a>
+## Next Step
+
+With authentication saved and a first run working, continue to [Configuration](configuration.md) for targets, Spotify login, SMTP and secrets. See [Usage](usage.md) for command formats, monitoring, container operation, notifications, playback and output.

mkdocs.yml

@@ -70,7 +70,7 @@ validation:
 nav:
   - Home: index.md
   - Installation: installation.md
-  - Quick Start: quick-start.md
+  - Setup & First Run: setup-and-first-run.md
   - Configuration: configuration.md
   - Usage: usage.md
   - Troubleshooting: troubleshooting.md