docs(spotify): document 6-month re-auth cycle and add client-level invalid_grant test

- Remove the 'you only log in once per machine' claim from spotify.md
  and document the ~6-month refresh token expiry with re-auth instructions
- Add test_client_wraps_invalid_grant_as_spotify_auth_required_error to
  confirm SpotifyClient wraps AuthError(code=spotify_refresh_invalid_grant)
  into SpotifyAuthRequiredError with a user-facing message

Refs: #28155

tests/tools/test_spotify_client.py

@@ -4,6 +4,7 @@ import json
 
 import pytest
 
+from hermes_cli.auth import AuthError
 from plugins.spotify import client as spotify_mod
 from plugins.spotify import tools as spotify_tool
 
@@ -297,3 +298,25 @@ def test_spotify_playback_recently_played_action(monkeypatch: pytest.MonkeyPatch
     payload = json.loads(spotify_tool._handle_spotify_playback({"action": "recently_played", "limit": 5}))
     assert seen and seen[0]["limit"] == 5
     assert isinstance(payload, dict)
+
+
+def test_client_wraps_invalid_grant_as_spotify_auth_required_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """SpotifyClient._resolve_runtime wraps AuthError(code=spotify_refresh_invalid_grant) into SpotifyAuthRequiredError."""
+
+    def _raise_invalid_grant(**kwargs):
+        raise AuthError(
+            "Spotify refresh token has expired or was revoked. Run `hermes auth spotify` again.",
+            provider="spotify",
+            code="spotify_refresh_invalid_grant",
+            relogin_required=True,
+        )
+
+    monkeypatch.setattr(
+        spotify_mod,
+        "resolve_spotify_runtime_credentials",
+        _raise_invalid_grant,
+    )
+    with pytest.raises(spotify_mod.SpotifyAuthRequiredError, match="expired or was revoked"):
+        spotify_mod.SpotifyClient()

website/docs/user-guide/features/spotify.md

@@ -1,6 +1,6 @@
 # Spotify
 
-Hermes can control Spotify directly — playback, queue, search, playlists, saved tracks/albums, and listening history — using Spotify's official Web API with PKCE OAuth. Tokens are stored in `~/.hermes/auth.json` and refreshed automatically on 401; you only log in once per machine.
+Hermes can control Spotify directly — playback, queue, search, playlists, saved tracks/albums, and listening history — using Spotify's official Web API with PKCE OAuth. Tokens are stored in `~/.hermes/auth.json` and refreshed automatically on 401; you only log in once per machine (refresh tokens expire after ~6 months; re-run `hermes auth spotify` when they do).
 
 Unlike Hermes' built-in OAuth integrations (Google, GitHub Copilot, Codex), Spotify requires every user to register their own lightweight developer app. Spotify does not let third parties ship a public OAuth app that anyone can use. It takes about two minutes and `hermes auth spotify` walks you through it.