better-dsh 0.2.5 → 0.3.0-a

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

@@ -1,271 +0,0 @@
----
-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

@@ -1,279 +0,0 @@
-# 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 |