better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/skins.md

@@ -0,0 +1,271 @@
+---
+sidebar_position: 10
+title: "Skins & Themes"
+description: "Customize the Hermes CLI with built-in and user-defined skins"
+---
+
+# Skins & Themes
+
+Skins control the **visual presentation** of the Hermes CLI: banner colors, spinner faces and verbs, response-box labels, branding text, and the tool activity prefix.
+
+Conversational style and visual style are separate concepts:
+
+- **Personality** changes the agent's tone and wording.
+- **Skin** changes the CLI's appearance.
+
+## Change skins
+
+```bash
+/skin                # show the current skin and list available skins
+/skin ares           # switch to a built-in skin
+/skin mytheme        # switch to a custom skin from ~/.hermes/skins/mytheme.yaml
+```
+
+Or set the default skin in `~/.hermes/config.yaml`:
+
+```yaml
+display:
+  skin: default
+```
+
+## Built-in skins
+
+| Skin | Description | Agent branding | Visual character |
+|------|-------------|----------------|------------------|
+| `default` | Classic Hermes — gold and kawaii | `Hermes Agent` | Warm gold borders, cornsilk text, kawaii faces in spinners. The familiar caduceus banner. Clean and inviting. |
+| `ares` | War-god theme — crimson and bronze | `Ares Agent` | Deep crimson borders with bronze accents. Aggressive spinner verbs ("forging", "marching", "tempering steel"). Custom sword-and-shield ASCII art banner. |
+| `mono` | Monochrome — clean grayscale | `Hermes Agent` | All grays — no color. Borders are `#555555`, text is `#c9d1d9`. Ideal for minimal terminal setups or screen recordings. |
+| `slate` | Cool blue — developer-focused | `Hermes Agent` | Royal blue borders (`#4169e1`), soft blue text. Calm and professional. No custom spinner — uses default faces. |
+| `daylight` | Light theme for bright terminals with dark text and cool blue accents | `Hermes Agent` | Designed for white or bright terminals. Dark slate text with blue borders, pale status surfaces, and a light completion menu that stays readable in light terminal profiles. |
+| `warm-lightmode` | Warm brown/gold text for light terminal backgrounds | `Hermes Agent` | Warm parchment tones for light terminals. Dark brown text with saddle-brown accents, cream-colored status surfaces. An earthy alternative to the cooler daylight theme. |
+| `poseidon` | Ocean-god theme — deep blue and seafoam | `Poseidon Agent` | Deep blue to seafoam gradient. Ocean-themed spinners ("charting currents", "sounding the depth"). Trident ASCII art banner. |
+| `sisyphus` | Sisyphean theme — austere grayscale with persistence | `Sisyphus Agent` | Light grays with stark contrast. Boulder-themed spinners ("pushing uphill", "resetting the boulder", "enduring the loop"). Boulder-and-hill ASCII art banner. |
+| `charizard` | Volcanic theme — burnt orange and ember | `Charizard Agent` | Warm burnt orange to ember gradient. Fire-themed spinners ("banking into the draft", "measuring burn"). Dragon-silhouette ASCII art banner. |
+
+## Complete list of configurable keys
+
+### Colors (`colors:`)
+
+Controls all color values throughout the CLI. Values are hex color strings.
+
+| Key | Description | Default (`default` skin) |
+|-----|-------------|--------------------------|
+| `banner_border` | Panel border around the startup banner | `#CD7F32` (bronze) |
+| `banner_title` | Title text color in the banner | `#FFD700` (gold) |
+| `banner_accent` | Section headers in the banner (Available Tools, etc.) | `#FFBF00` (amber) |
+| `banner_dim` | Muted text in the banner (separators, secondary labels) | `#B8860B` (dark goldenrod) |
+| `banner_text` | Body text in the banner (tool names, skill names) | `#FFF8DC` (cornsilk) |
+| `ui_accent` | General UI accent color (highlights, active elements) | `#FFBF00` |
+| `ui_label` | UI labels and tags | `#DAA520` (goldenrod) |
+| `ui_ok` | Success indicators (checkmarks, completion) | `#4caf50` (green) |
+| `ui_error` | Error indicators (failures, blocked) | `#ef5350` (red) |
+| `ui_warn` | Warning indicators (caution, approval prompts) | `#ffa726` (orange) |
+| `prompt` | Interactive prompt text color | `#FFF8DC` |
+| `input_rule` | Horizontal rule above the input area | `#CD7F32` |
+| `response_border` | Border around the agent's response box (ANSI escape) | `#FFD700` |
+| `session_label` | Session label color | `#DAA520` |
+| `session_border` | Session ID dim border color | `#8B8682` |
+| `status_bar_bg` | Background color for the TUI status / usage bar | `#1a1a2e` |
+| `voice_status_bg` | Background color for the voice-mode status badge | `#1a1a2e` |
+| `selection_bg` | Background color for the TUI mouse-selection highlighter. Falls back to `completion_menu_current_bg` when unset. | `#3a3a55` |
+| `completion_menu_bg` | Background color for the completion menu list | `#1a1a2e` |
+| `completion_menu_current_bg` | Background color for the active completion row | `#333355` |
+| `completion_menu_meta_bg` | Background color for the completion meta column | `#1a1a2e` |
+| `completion_menu_meta_current_bg` | Background color for the active completion meta column | `#333355` |
+
+### Spinner (`spinner:`)
+
+Controls the animated spinner shown while waiting for API responses.
+
+| Key | Type | Description | Example |
+|-----|------|-------------|---------|
+| `waiting_faces` | list of strings | Faces cycled while waiting for API response | `["(⚔)", "(⛨)", "(▲)"]` |
+| `thinking_faces` | list of strings | Faces cycled during model reasoning | `["(⚔)", "(⌁)", "(<>)"]` |
+| `thinking_verbs` | list of strings | Verbs shown in spinner messages | `["forging", "plotting", "hammering plans"]` |
+| `wings` | list of [left, right] pairs | Decorative brackets around the spinner | `[["⟪⚔", "⚔⟫"], ["⟪▲", "▲⟫"]]` |
+
+When spinner values are empty (like in `default` and `mono`), hardcoded defaults from `display.py` are used.
+
+### Branding (`branding:`)
+
+Text strings used throughout the CLI interface.
+
+| Key | Description | Default |
+|-----|-------------|---------|
+| `agent_name` | Name shown in banner title and status display | `Hermes Agent` |
+| `welcome` | Welcome message shown at CLI startup | `Welcome to Hermes Agent! Type your message or /help for commands.` |
+| `goodbye` | Message shown on exit | `Goodbye! ☤` |
+| `response_label` | Label on the response box header | ` ☤ Hermes ` |
+| `prompt_symbol` | Symbol before the user input prompt (bare token, renderers add a trailing space) | `❯` |
+| `help_header` | Header text for the `/help` command output | `(^_^)? Available Commands` |
+
+### Other top-level keys
+
+| Key | Type | Description | Default |
+|-----|------|-------------|---------|
+| `tool_prefix` | string | Character prefixed to tool output lines in the CLI | `┊` |
+| `tool_emojis` | dict | Per-tool emoji overrides for spinners and progress (`{tool_name: emoji}`) | `{}` |
+| `banner_logo` | string | Rich-markup ASCII art logo (replaces the default HERMES_AGENT banner) | `""` |
+| `banner_hero` | string | Rich-markup hero art (replaces the default caduceus art) | `""` |
+
+## Custom skins
+
+Create YAML files under `~/.hermes/skins/`. User skins inherit missing values from the built-in `default` skin, so you only need to specify the keys you want to change.
+
+### Full custom skin YAML template
+
+```yaml
+# ~/.hermes/skins/mytheme.yaml
+# Complete skin template — all keys shown. Delete any you don't need;
+# missing values automatically inherit from the 'default' skin.
+
+name: mytheme
+description: My custom theme
+
+colors:
+  banner_border: "#CD7F32"
+  banner_title: "#FFD700"
+  banner_accent: "#FFBF00"
+  banner_dim: "#B8860B"
+  banner_text: "#FFF8DC"
+  ui_accent: "#FFBF00"
+  ui_label: "#4dd0e1"
+  ui_ok: "#4caf50"
+  ui_error: "#ef5350"
+  ui_warn: "#ffa726"
+  prompt: "#FFF8DC"
+  input_rule: "#CD7F32"
+  response_border: "#FFD700"
+  session_label: "#DAA520"
+  session_border: "#8B8682"
+  status_bar_bg: "#1a1a2e"
+  voice_status_bg: "#1a1a2e"
+  selection_bg: "#333355"
+  completion_menu_bg: "#1a1a2e"
+  completion_menu_current_bg: "#333355"
+  completion_menu_meta_bg: "#1a1a2e"
+  completion_menu_meta_current_bg: "#333355"
+
+spinner:
+  waiting_faces:
+    - "(⚔)"
+    - "(⛨)"
+    - "(▲)"
+  thinking_faces:
+    - "(⚔)"
+    - "(⌁)"
+    - "(<>)"
+  thinking_verbs:
+    - "processing"
+    - "analyzing"
+    - "computing"
+    - "evaluating"
+  wings:
+    - ["⟪⚡", "⚡⟫"]
+    - ["⟪●", "●⟫"]
+
+branding:
+  agent_name: "My Agent"
+  welcome: "Welcome to My Agent! Type your message or /help for commands."
+  goodbye: "See you later! ⚡"
+  response_label: " ⚡ My Agent "
+  prompt_symbol: "⚡"
+  help_header: "(⚡) Available Commands"
+
+tool_prefix: "┊"
+
+# Per-tool emoji overrides (optional)
+tool_emojis:
+  terminal: "⚔"
+  web_search: "🔮"
+  read_file: "📄"
+
+# Custom ASCII art banners (optional, Rich markup supported)
+# banner_logo: |
+#   [bold #FFD700] MY AGENT [/]
+# banner_hero: |
+#   [#FFD700]  Custom art here  [/]
+```
+
+### Minimal custom skin example
+
+Since everything inherits from `default`, a minimal skin only needs to change what's different:
+
+```yaml
+name: cyberpunk
+description: Neon terminal theme
+
+colors:
+  banner_border: "#FF00FF"
+  banner_title: "#00FFFF"
+  banner_accent: "#FF1493"
+
+spinner:
+  thinking_verbs: ["jacking in", "decrypting", "uploading"]
+  wings:
+    - ["⟨⚡", "⚡⟩"]
+
+branding:
+  agent_name: "Cyber Agent"
+  response_label: " ⚡ Cyber "
+
+tool_prefix: "▏"
+```
+
+## Hermes Mod — Visual Skin Editor
+
+[Hermes Mod](https://github.com/cocktailpeanut/hermes-mod) is a community-built web UI for creating and managing skins visually. Instead of writing YAML by hand, you get a point-and-click editor with live preview.
+
+![Hermes Mod skin editor](https://raw.githubusercontent.com/cocktailpeanut/hermes-mod/master/nous.png)
+
+**What it does:**
+
+- Lists all built-in and custom skins
+- Opens any skin into a visual editor with all Hermes skin fields (colors, spinner, branding, tool prefix, tool emojis)
+- Generates `banner_logo` text art from a text prompt
+- Converts uploaded images (PNG, JPG, GIF, WEBP) into `banner_hero` ASCII art with multiple render styles (braille, ASCII ramp, blocks, dots)
+- Saves directly to `~/.hermes/skins/`
+- Activates a skin by updating `~/.hermes/config.yaml`
+- Shows the generated YAML and a live preview
+
+### Install
+
+**Option 1 — Pinokio (1-click):**
+
+Find it on [pinokio.computer](https://pinokio.computer) and install with one click.
+
+**Option 2 — npx (quickest from terminal):**
+
+```bash
+npx -y hermes-mod
+```
+
+**Option 3 — Manual:**
+
+```bash
+git clone https://github.com/cocktailpeanut/hermes-mod.git
+cd hermes-mod/app
+npm install
+npm start
+```
+
+### Usage
+
+1. Start the app (via Pinokio or terminal).
+2. Open **Skin Studio**.
+3. Choose a built-in or custom skin to edit.
+4. Generate a logo from text and/or upload an image for hero art. Pick a render style and width.
+5. Edit colors, spinner, branding, and other fields.
+6. Click **Save** to write the skin YAML to `~/.hermes/skins/`.
+7. Click **Activate** to set it as the current skin (updates `display.skin` in `config.yaml`).
+
+Hermes Mod respects the `HERMES_HOME` environment variable, so it works with [profiles](/user-guide/profiles) too.
+
+## Operational notes
+
+- Built-in skins load from `hermes_cli/skin_engine.py`.
+- Unknown skins automatically fall back to `default`.
+- `/skin` updates the active CLI theme immediately for the current session.
+- User skins in `~/.hermes/skins/` take precedence over built-in skins with the same name.
+- Skin changes via `/skin` are session-only. To make a skin your permanent default, set it in `config.yaml`.
+- The `banner_logo` and `banner_hero` fields support Rich console markup (e.g., `[bold #FF0000]text[/]`) for colored ASCII art.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/spotify.md

@@ -0,0 +1,279 @@
+# 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 (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.
+
+## Prerequisites
+
+- A Spotify account. **Free** works for search, playlist, library, and activity tools. **Premium** is required for playback control (play, pause, skip, seek, volume, queue add, transfer).
+- Hermes Agent installed and running.
+- For playback tools: an **active Spotify Connect device** — the Spotify app must be open on at least one device (phone, desktop, web player, speaker) so the Web API has something to control. If nothing is active you'll get a `403 Forbidden` with a "no active device" message; open Spotify on any device and retry.
+
+## Setup
+
+### One-shot: `hermes tools` or first-run setup
+
+The fastest path. Run:
+
+```bash
+hermes tools
+```
+
+Scroll to `🎵 Spotify`, press space to toggle it on, then `s` to save. The same toggle is also available during the first-run `hermes setup` / `hermes setup tools` flow. Spotify stays opt-in, so enabling it there runs the same provider-aware configuration as `hermes tools`.
+
+Hermes drops you straight into the OAuth flow — if you don't have a Spotify app yet, it walks you through creating one inline. Once you finish, the toolset is enabled AND authenticated in one pass.
+
+If you prefer to do the steps separately (or you're re-authing later), use the two-step flow below.
+
+### Two-step flow
+
+#### 1. Enable the toolset
+
+```bash
+hermes tools
+```
+
+Toggle `🎵 Spotify` on, save, and when the inline wizard opens, dismiss it (Ctrl+C). The toolset stays on; only the auth step is deferred.
+
+#### 2. Run the login wizard
+
+```bash
+hermes auth spotify
+```
+
+The 7 Spotify tools only appear in the agent's toolset after step 1 — they're off by default so users who don't want them don't ship extra tool schemas on every API call.
+
+If no `HERMES_SPOTIFY_CLIENT_ID` is set, Hermes walks you through the app registration inline:
+
+1. Opens `https://developer.spotify.com/dashboard` in your browser
+2. Prints the exact values to paste into Spotify's "Create app" form
+3. Prompts you for the Client ID you get back
+4. Saves it to `~/.hermes/.env` so future runs skip this step
+5. Continues straight into the OAuth consent flow
+
+After you approve, tokens are written under `providers.spotify` in `~/.hermes/auth.json`. The active inference provider is NOT changed — Spotify auth is independent of your LLM provider.
+
+### Creating the Spotify app (what the wizard asks for)
+
+When the dashboard opens, click **Create app** and fill in:
+
+| Field | Value |
+|-------|-------|
+| App name | anything (e.g. `hermes-agent`) |
+| App description | anything (e.g. `personal Hermes integration`) |
+| Website | leave blank |
+| Redirect URI | `http://127.0.0.1:43827/spotify/callback` |
+| Which API/SDKs? | check **Web API** |
+
+Agree to the terms and click **Save**. On the next page click **Settings** → copy the **Client ID** and paste it into the Hermes prompt. That's the only value Hermes needs — PKCE doesn't use a client secret.
+
+### Running over SSH / in a headless environment
+
+If `SSH_CLIENT` or `SSH_TTY` is set, Hermes skips the automatic browser open during both the wizard and the OAuth step. Copy the dashboard URL and the authorization URL Hermes prints, open them in a browser on your local machine, and proceed normally — the local HTTP listener still runs on the remote host on port `43827`. Your laptop's browser can't reach the remote loopback without an SSH local-forward:
+
+```bash
+ssh -N -L 43827:127.0.0.1:43827 user@remote-host
+```
+
+For jump-box / bastion setups and other gotchas (mosh, tmux, port conflicts), see [OAuth over SSH / Remote Hosts](../../guides/oauth-over-ssh.md).
+
+## Verify
+
+```bash
+hermes auth status spotify
+```
+
+Shows whether tokens are present and when the access token expires. Refresh is automatic: when any Spotify API call returns 401, the client exchanges the refresh token and retries once. Refresh tokens persist across Hermes restarts, so you only re-auth if you revoke the app in your Spotify account settings or run `hermes auth logout spotify`.
+
+## Using it
+
+Once logged in, the agent has access to 7 Spotify tools. You talk to the agent naturally — it picks the right tool and action. For the best behavior, the agent loads a companion skill that teaches canonical usage patterns (single-search-then-play, when not to preflight `get_state`, etc.).
+
+```
+> play some miles davis
+> what am I listening to
+> add this track to my Late Night Jazz playlist
+> skip to the next song
+> make a new playlist called "Focus 2026" and add the last three songs I played
+> which of my saved albums are by Radiohead
+> search for acoustic covers of Blackbird
+> transfer playback to my kitchen speaker
+```
+
+### Tool reference
+
+All playback-mutating actions accept an optional `device_id` to target a specific device. If omitted, Spotify uses the currently active device.
+
+#### `spotify_playback`
+Control and inspect playback, plus fetch recently played history.
+
+| Action | Purpose | Premium? |
+|--------|---------|----------|
+| `get_state` | Full playback state (track, device, progress, shuffle/repeat) | No |
+| `get_currently_playing` | Just the current track (returns empty on 204 — see below) | No |
+| `play` | Start/resume playback. Optional: `context_uri`, `uris`, `offset`, `position_ms` | Yes |
+| `pause` | Pause playback | Yes |
+| `next` / `previous` | Skip track | Yes |
+| `seek` | Jump to `position_ms` | Yes |
+| `set_repeat` | `state` = `track` / `context` / `off` | Yes |
+| `set_shuffle` | `state` = `true` / `false` | Yes |
+| `set_volume` | `volume_percent` = 0-100 | Yes |
+| `recently_played` | Last played tracks. Optional `limit`, `before`, `after` (Unix ms) | No |
+
+#### `spotify_devices`
+| Action | Purpose |
+|--------|---------|
+| `list` | Every Spotify Connect device visible to your account |
+| `transfer` | Move playback to `device_id`. Optional `play: true` starts playback on transfer |
+
+### Home Assistant-managed speakers
+
+If Home Assistant manages speakers that already support Spotify Connect (for example Sonos, Echo, Nest, or other Connect-capable speakers), they appear in `spotify_devices list` automatically whenever Spotify can see them. Hermes does not need a Home Assistant ↔ Spotify bridge for this path — Spotify handles the device routing natively.
+
+Ask Hermes to transfer playback by the speaker's display name (for example, “transfer Spotify to the kitchen speaker”), or call `spotify_devices list` and pass the exact `device_id` to `spotify_devices transfer` when scripting. If the speaker is missing, open the Spotify app or the speaker's Spotify integration once so Spotify registers it as an active Connect target.
+
+#### `spotify_queue`
+| Action | Purpose | Premium? |
+|--------|---------|----------|
+| `get` | Currently queued tracks | No |
+| `add` | Append `uri` to the queue | Yes |
+
+#### `spotify_search`
+Search the catalog. `query` is required. Optional: `types` (array of `track` / `album` / `artist` / `playlist` / `show` / `episode`), `limit`, `offset`, `market`.
+
+#### `spotify_playlists`
+| Action | Purpose | Required args |
+|--------|---------|---------------|
+| `list` | User's playlists | — |
+| `get` | One playlist + tracks | `playlist_id` |
+| `create` | New playlist | `name` (+ optional `description`, `public`, `collaborative`) |
+| `add_items` | Add tracks | `playlist_id`, `uris` (optional `position`) |
+| `remove_items` | Remove tracks | `playlist_id`, `uris` (+ optional `snapshot_id`) |
+| `update_details` | Rename / edit | `playlist_id` + any of `name`, `description`, `public`, `collaborative` |
+
+#### `spotify_albums`
+| Action | Purpose | Required args |
+|--------|---------|---------------|
+| `get` | Album metadata | `album_id` |
+| `tracks` | Album track list | `album_id` |
+
+#### `spotify_library`
+Unified access to saved tracks and saved albums. Pick the collection with the `kind` arg.
+
+| Action | Purpose |
+|--------|---------|
+| `list` | Paginated library listing |
+| `save` | Add `ids` / `uris` to library |
+| `remove` | Remove `ids` / `uris` from library |
+
+Required: `kind` = `tracks` or `albums`, plus `action`.
+
+### Feature matrix: Free vs Premium
+
+Read-only tools work on Free accounts. Anything that mutates playback or the queue requires Premium.
+
+| Works on Free | Premium required |
+|---------------|------------------|
+| `spotify_search` (all) | `spotify_playback` — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume |
+| `spotify_playback` — get_state, get_currently_playing, recently_played | `spotify_queue` — add |
+| `spotify_devices` — list | `spotify_devices` — transfer |
+| `spotify_queue` — get | |
+| `spotify_playlists` (all) | |
+| `spotify_albums` (all) | |
+| `spotify_library` (all) | |
+
+## Scheduling: Spotify + cron
+
+Because Spotify tools are regular Hermes tools, a cron job running in a Hermes session can trigger playback on any schedule. No new code needed.
+
+### Morning wake-up playlist
+
+```bash
+hermes cron add \
+  --name "morning-commute" \
+  "0 7 * * 1-5" \
+  "Transfer playback to my kitchen speaker and start my 'Morning Commute' playlist. Volume to 40. Shuffle on."
+```
+
+What happens at 7am every weekday:
+1. Cron spins up a headless Hermes session.
+2. Agent reads the prompt, calls `spotify_devices list` to find "kitchen speaker" by name, then `spotify_devices transfer` → `spotify_playback set_volume` → `spotify_playback set_shuffle` → `spotify_search` + `spotify_playback play`.
+3. Music starts on the target speaker. Total cost: one session, a few tool calls, no human input.
+
+### Wind-down at night
+
+```bash
+hermes cron add \
+  --name "wind-down" \
+  "30 22 * * *" \
+  "Pause Spotify. Then set volume to 20 so it's quiet when I start it again tomorrow."
+```
+
+### Gotchas
+
+- **An active device must exist when the cron fires.** If no Spotify client is running (phone/desktop/Connect speaker), playback actions return `403 no active device`. For morning playlists, the trick is to target a device that's always on (Sonos, Echo, a smart speaker) rather than your phone.
+- **Premium required for anything that mutates playback** — play, pause, skip, volume, transfer. Read-only cron jobs (scheduled "email me my recently played tracks") work fine on Free.
+- **The cron agent inherits your active toolsets.** Spotify must be enabled in `hermes tools` for the cron session to see the Spotify tools.
+- **Cron jobs run with `skip_memory=True`** so they don't write to your memory store.
+
+Full cron reference: [Cron Jobs](./cron).
+
+## Sign out
+
+```bash
+hermes auth logout spotify
+```
+
+Removes tokens from `~/.hermes/auth.json`. To also clear the app config, delete `HERMES_SPOTIFY_CLIENT_ID` (and `HERMES_SPOTIFY_REDIRECT_URI` if you set it) from `~/.hermes/.env`, or run the wizard again.
+
+To revoke the app on Spotify's side, visit [Apps connected to your account](https://www.spotify.com/account/apps/) and click **REMOVE ACCESS**.
+
+## Troubleshooting
+
+**`403 Forbidden — Player command failed: No active device found`** — You need Spotify running on at least one device. Open the Spotify app on your phone, desktop, or web player, start any track for a second to register it, and retry. `spotify_devices list` shows what's currently visible.
+
+**`403 Forbidden — Premium required`** — You're on a Free account trying to use a playback-mutating action. See the feature matrix above.
+
+**`204 No Content` on `get_currently_playing`** — nothing is currently playing on any device. This is Spotify's normal response, not an error; Hermes surfaces it as an explanatory empty result (`is_playing: false`).
+
+**`INVALID_CLIENT: Invalid redirect URI`** — the redirect URI in your Spotify app settings doesn't match what Hermes is using. The default is `http://127.0.0.1:43827/spotify/callback`. Either add that to your app's allowed redirect URIs, or set `HERMES_SPOTIFY_REDIRECT_URI` in `~/.hermes/.env` to whatever you registered.
+
+**`429 Too Many Requests`** — Spotify's rate limit. Hermes returns a friendly error; wait a minute and retry. If this persists, you're probably running a tight loop in a script — Spotify's quota resets roughly every 30 seconds.
+
+**`401 Unauthorized` keeps coming back** — Your refresh token was revoked (usually because you removed the app from your account, or the app was deleted). Run `hermes auth spotify` again.
+
+**Wizard doesn't open the browser** — If you're over SSH or in a container without a display, Hermes detects it and skips the auto-open. Copy the dashboard URL it prints and open it manually.
+
+## Advanced: custom scopes
+
+By default Hermes requests the scopes needed for every shipped tool. Override if you want to restrict access:
+
+```bash
+hermes auth spotify --scope "user-read-playback-state user-modify-playback-state playlist-read-private"
+```
+
+Scope reference: [Spotify Web API scopes](https://developer.spotify.com/documentation/web-api/concepts/scopes). If you request fewer scopes than a tool needs, that tool's calls will fail with 403.
+
+## Advanced: custom client ID / redirect URI
+
+```bash
+hermes auth spotify --client-id <id> --redirect-uri http://localhost:3000/callback
+```
+
+Or set them permanently in `~/.hermes/.env`:
+
+```
+HERMES_SPOTIFY_CLIENT_ID=<your_id>
+HERMES_SPOTIFY_REDIRECT_URI=http://localhost:3000/callback
+```
+
+The redirect URI must be allow-listed in your Spotify app's settings. The default works for almost everyone — only change it if port 43827 is taken.
+
+## Where things live
+
+| File | Contents |
+|------|----------|
+| `~/.hermes/auth.json` → `providers.spotify` | access token, refresh token, expiry, scope, redirect URI |
+| `~/.hermes/.env` | `HERMES_SPOTIFY_CLIENT_ID`, optional `HERMES_SPOTIFY_REDIRECT_URI` |
+| Spotify app | owned by you at [developer.spotify.com/dashboard](https://developer.spotify.com/dashboard); contains the Client ID and the redirect URI allow-list |