ci: update homebrew tap on release

Replace the static one-page index.html with a Node-based docs site
generator. Sidebar nav, per-page TOC, dark mode toggle (system-pref
default, persisted), and a Spotify-green theme with animated equalizer
brand mark and ambient hero gradient.

Adds 11 hand-written doc pages (index, install, quickstart, auth,
playback, library, queue, devices, engines, output, agents,
troubleshooting, commands) alongside existing spec.md and RELEASING.md.

Pages workflow deploys dist/docs-site to GitHub Pages on push to main;
repo Pages source is now "GitHub Actions" instead of legacy /docs.

.github/workflows/pages.yml

@@ -0,0 +1,54 @@
+name: pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "scripts/build-docs-site.mjs"
+      - "scripts/docs-site-assets.mjs"
+      - "Makefile"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Check out
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
+
+      - name: Build docs site
+        run: make docs-site
+
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: dist/docs-site
+
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

.github/workflows/release.yml

@@ -44,3 +44,62 @@ jobs:
           args: release --clean --config /tmp/.goreleaser.yaml
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  update-homebrew-tap:
+    runs-on: ubuntu-latest
+    needs: goreleaser
+    steps:
+      - name: Resolve release tag
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "RELEASE_TAG=${{ inputs.tag }}" >> "$GITHUB_ENV"
+          else
+            echo "RELEASE_TAG=${{ github.ref_name }}" >> "$GITHUB_ENV"
+          fi
+
+      - name: Dispatch tap formula update
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          if [ -z "$GH_TOKEN" ]; then
+            echo "::error::Set HOMEBREW_TAP_TOKEN with workflow access to steipete/homebrew-tap"
+            exit 1
+          fi
+
+          request_id="spogo-${RELEASE_TAG}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          expected_title="Update spogo for ${RELEASE_TAG} (${request_id})"
+
+          gh workflow run update-formula.yml \
+            --repo steipete/homebrew-tap \
+            --ref main \
+            -f formula=spogo \
+            -f tag="$RELEASE_TAG" \
+            -f repository=steipete/spogo \
+            -f artifact_template="{formula}_{version}_{target}.tar.gz" \
+            -f request_id="$request_id"
+
+          run_id=""
+          for _ in {1..30}; do
+            run_id=$(gh run list \
+              --repo steipete/homebrew-tap \
+              --workflow update-formula.yml \
+              --branch main \
+              --event workflow_dispatch \
+              --limit 20 \
+              --json databaseId,displayTitle \
+              --jq ".[] | select(.displayTitle == \"$expected_title\") | .databaseId" | head -n1)
+            if [ -n "$run_id" ]; then
+              break
+            fi
+            sleep 5
+          done
+
+          if [ -z "$run_id" ]; then
+            echo "::error::Could not find tap workflow run with title: $expected_title"
+            exit 1
+          fi
+
+          gh run watch "$run_id" \
+            --repo steipete/homebrew-tap \
+            --exit-status \
+            --interval 10

Makefile

@@ -1,4 +1,7 @@
-.PHONY: spogo
+.PHONY: spogo docs-site
 
 spogo:
 	go build -o spogo ./cmd/spogo
+
+docs-site:
+	@node scripts/build-docs-site.mjs

docs/CNAME

@@ -0,0 +1 @@
+spogo.sh

docs/agents.md

@@ -0,0 +1,150 @@
+---
+title: Agents & Automation
+description: "Use spogo from shell scripts, CI, cron, and AI coding agents — patterns, exit codes, and safety."
+---
+
+# Agents & Automation
+
+spogo is built to be driven by something other than a human at a terminal — shell scripts, cron jobs, CI pipelines, AI coding agents. The same properties that make it pleasant interactively (stable JSON, plain mode, predictable exit codes, stderr-only logs) also make it safe to script.
+
+## The contract
+
+A script-friendly CLI must guarantee:
+
+- **Stable output.** spogo's `--json` and `--plain` modes don't change keys/columns between releases without a major bump.
+- **Stable exit codes.** `0` success, `1` generic, `2` usage, `3` auth, `4` network. Branch on these.
+- **stdout is data.** stderr carries everything else. Pipes always work.
+- **No interactive surprises.** When stdin is not a TTY, spogo refuses to prompt. Pass `--no-input` to be explicit.
+- **No tight rate limits.** Cookie auth via Connect avoids the public Web API throttle.
+
+See [Output](output.md) for the full contract.
+
+## Wiring spogo into a shell script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Make sure auth still works
+if ! spogo auth status >/dev/null 2>&1; then
+  echo "spogo: cookies missing or stale; re-run 'spogo auth import'" >&2
+  exit 3
+fi
+
+# Capture the currently playing track ID
+track_id=$(spogo status --json | jq -r '.item.id // empty')
+if [[ -z "$track_id" ]]; then
+  echo "Nothing playing" >&2
+  exit 0
+fi
+
+# Save it
+spogo library tracks add "$track_id"
+```
+
+Pin to a specific spogo version in CI to avoid silent JSON drift across releases.
+
+## Common patterns
+
+### Save the currently playing track
+
+```bash
+id=$(spogo status --json | jq -r '.item.id')
+spogo library tracks add "$id"
+```
+
+### Build a playlist from a search
+
+```bash
+spogo playlist create "Weekly Lo-Fi"
+spogo search track "lo-fi 2026" --limit 30 --plain |
+  awk '{print $1}' |
+  xargs spogo playlist add "Weekly Lo-Fi"
+```
+
+### Snapshot library to JSON
+
+```bash
+spogo library tracks list --limit 1000 --json > snapshots/tracks.$(date +%F).json
+```
+
+### Move playback to a specific room when leaving home
+
+```bash
+spogo device set "Phone"
+```
+
+### "Sleep timer" — pause after N minutes
+
+```bash
+sleep "${1:-1800}" && spogo pause
+```
+
+## Cron / launchd / systemd
+
+spogo writes nothing to stdout that isn't useful and nothing to stderr unless something happened — perfect for cron tail logs.
+
+```cron
+# Snapshot liked tracks daily at 04:00
+0 4 * * * /usr/local/bin/spogo library tracks list --limit 1000 --json > "$HOME/snapshots/tracks-$(date +\%F).json" 2>&1
+```
+
+For headless servers / CI runners, copy a working cookie jar (from a machine where you ran `auth import`) into the runner's spogo config directory rather than trying to import from a browser that doesn't exist.
+
+## CI
+
+GitHub Actions example:
+
+```yaml
+- name: Install spogo
+  run: brew install steipete/tap/spogo
+
+- name: Restore cookies
+  run: |
+    mkdir -p "$HOME/.config/spogo/default"
+    echo "$SPOGO_COOKIES" > "$HOME/.config/spogo/default/cookies.json"
+  env:
+    SPOGO_COOKIES: ${{ secrets.SPOGO_COOKIES }}
+
+- name: Snapshot library
+  run: spogo library tracks list --json --limit 1000 > tracks.json
+```
+
+Treat the cookie jar like a credential — it's tied to your Spotify session.
+
+## Coding agents
+
+spogo is a good fit for AI coding agents (Claude Code, Codex, Cursor) because:
+
+- **Self-documenting.** `spogo --help` and `spogo <subcommand> --help` describe the entire surface. The [Spec](spec.md) is short and stable.
+- **Deterministic.** Stable JSON keys mean the agent's parsing doesn't drift across releases.
+- **Safe-ish.** The destructive surface is small (`library tracks remove`, `playlist remove`, `auth clear`). Wrap those behind explicit confirmation in your agent prompt.
+
+Recommended agent rules:
+
+- Always pass `--json` or `--plain` for output the agent will parse.
+- Always pass `--no-input` so spogo cannot block on a prompt.
+- Branch on exit code, not stderr text.
+- Pin spogo version in the agent's environment.
+
+A starter system prompt fragment for an agent:
+
+> You can use the `spogo` CLI to control Spotify. Always pass `--json` and `--no-input`. Read `spogo --help` and `spogo <cmd> --help` before invoking unfamiliar commands. Treat exit code `3` as "needs auth" — surface that to the user, don't try to recover automatically.
+
+## Safety
+
+spogo has no built-in command allowlist or read-only mode. If you're handing it to an unattended process or untrusted agent and want to restrict it:
+
+- Run inside a separate spogo profile (`SPOGO_PROFILE=automation`) with cookies for an account that has limited permissions.
+- Wrap spogo in a thin shell script that whitelists subcommands.
+- Use the `applescript` engine on macOS — no cookies, no remote mutations possible (only local app control).
+
+## Debugging an automation
+
+Always re-run with `-v` (or `-d` for full HTTP traces) when something misbehaves — diagnostic output goes to stderr and won't pollute pipelines:
+
+```bash
+spogo -d status 2>spogo.log | jq .
+```
+
+See [Troubleshooting](troubleshooting.md).

docs/auth.md

@@ -0,0 +1,132 @@
+---
+title: Auth
+description: "How spogo authenticates with Spotify using your browser cookies — import, paste, status, troubleshooting."
+---
+
+# Auth
+
+spogo does not use the Spotify Developer API. It reads the cookies your browser already has for `open.spotify.com` and uses them to fetch a web access token. That means **no app registration, no client ID, no redirect URI** — just log in to Spotify in your browser, then import.
+
+The cookie machinery comes from [steipete/sweetcookie](https://github.com/steipete/sweetcookie).
+
+## What spogo needs
+
+The minimum cookies for authentication:
+
+- `sp_dc` — required. Long-lived web session cookie.
+- `sp_key` — optional, helps with rotation.
+- `sp_t` — recommended for `connect` engine playback control.
+
+These cookies live in your browser's cookie store and rotate on their own; spogo refreshes its cached access token using them as needed.
+
+## Importing from a browser
+
+```bash
+spogo auth import --browser chrome
+```
+
+Defaults: Chrome + `Default` profile + `spotify.com` domain. Cookies are stored under your config directory keyed by profile.
+
+### Pick a different browser
+
+```bash
+spogo auth import --browser brave
+spogo auth import --browser edge
+spogo auth import --browser firefox
+spogo auth import --browser safari
+```
+
+### Pick a non-default profile
+
+Chrome / Brave / Edge keep profiles in directories like `Default`, `Profile 1`, `Profile 2`. Pass the directory name:
+
+```bash
+spogo auth import --browser chrome --browser-profile "Profile 1"
+```
+
+### Use a specific cookie store file
+
+If you have an exported cookie jar already:
+
+```bash
+spogo auth import --cookie-path /path/to/cookies.sqlite
+```
+
+### Limit the cookie scope
+
+```bash
+spogo auth import --domain spotify.com
+```
+
+When the browser-store read returns nothing, spogo now surfaces the underlying warning (locked keychain, missing profile, decryption failure) instead of just printing `no cookies found`.
+
+## Manual paste (WSL fallback)
+
+If WSL cookie decryption is broken, or you need to copy cookies from a Chromium DevTools session, paste the values straight in:
+
+1. In Chrome, open DevTools → Application → Cookies → `https://open.spotify.com`.
+2. Copy the values for `sp_dc` (required), `sp_key` (optional), `sp_t` (recommended).
+3. Run:
+
+```bash
+spogo auth paste
+```
+
+spogo prompts for each cookie. To skip the prompts (CI, scripts):
+
+```bash
+printf '%s\n%s\n' "sp_dc=..." "sp_t=..." | spogo auth paste --no-input
+```
+
+Other paste flags:
+
+- `--cookie-path <file>` — write the resulting cookie jar to a custom path.
+- `--domain <suffix>` — override the cookie domain (default `spotify.com`).
+- `--path <path>` — override the cookie path (default `/`).
+
+## Status & clearing
+
+```bash
+spogo auth status        # which profile, when imported, what cookies exist
+spogo auth clear         # delete the stored cookies for the current profile
+```
+
+`auth status` does not call Spotify; it only inspects the local store. To verify cookies actually work, run any read command:
+
+```bash
+spogo status
+spogo search track "test" --limit 1
+```
+
+A `401`/`403` from those means the cookies are stale — re-import.
+
+## Where cookies are stored
+
+- macOS: `~/Library/Application Support/spogo/<profile>/cookies.json`
+- Linux: `~/.config/spogo/<profile>/cookies.json`
+- Windows: `%APPDATA%\spogo\<profile>\cookies.json`
+
+`<profile>` defaults to `default` — override with `--profile <name>` or `SPOGO_PROFILE`.
+
+## Multiple accounts
+
+Use profiles to keep multiple Spotify logins side by side:
+
+```bash
+spogo --profile work auth import --browser chrome --browser-profile "Profile 1"
+spogo --profile personal auth import --browser chrome --browser-profile "Default"
+
+spogo --profile work status
+spogo --profile personal play spotify:track:...
+```
+
+Set the default for a shell with `export SPOGO_PROFILE=work`.
+
+## Troubleshooting
+
+- **"no cookies found"** — pass `--browser-profile`, double-check you're logged in to `open.spotify.com` in that browser, and check the warning spogo prints (it now surfaces the real reason).
+- **Locked keychain (macOS Chrome)** — unlock the login keychain, then re-run `auth import`.
+- **WSL Chrome** — cookie decryption is unreliable; use [paste](#manual-paste-wsl-fallback).
+- **Auth works locally but not in CI** — copy the cookie jar file (the path printed by `auth status`) into the CI runner before running spogo.
+
+See [Troubleshooting](troubleshooting.md) for more.

docs/commands.md

@@ -0,0 +1,154 @@
+---
+title: Command Reference
+description: "Every spogo subcommand and flag, organized by topic. The machine-readable spec is at spec.md."
+---
+
+# Command Reference
+
+Hand-written index of every `spogo` subcommand. The fully normative spec lives in [spec.md](spec.md); this page is the readable browse.
+
+For deeper guides, see [Auth](auth.md), [Playback](playback.md), [Library](library.md), [Queue](queue.md), [Devices](devices.md), [Engines](engines.md), and [Output](output.md).
+
+## Global flags
+
+Apply to every command.
+
+| Flag | Default | Purpose |
+| --- | --- | --- |
+| `-h`, `--help` | — | Show contextual help. |
+| `--version` | — | Print the spogo version. |
+| `--config <path>` | platform default | Path to a config file. |
+| `--profile <name>` | `default` | Named profile (separate cookies + config). |
+| `--timeout <dur>` | `10s` | HTTP timeout for any single request. |
+| `--market <cc>` | account market or `US` | Two-letter market code. |
+| `--language <tag>` | `en` | Language/locale. |
+| `--device <name|id>` | active | Target a specific Connect device. |
+| `--engine <name>` | `connect` | `auto` / `connect` / `web` / `applescript`. |
+| `--json` | off | JSON output. |
+| `--plain` | off | Plain (TSV) output. |
+| `--no-color` | auto | Disable color in human output. |
+| `-q`, `--quiet` | off | Suppress non-essential stderr. |
+| `-v`, `--verbose` | off | Verbose stderr. |
+| `-d`, `--debug` | off | Debug stderr (HTTP traces). |
+| `--no-input` | auto when not a TTY | Refuse interactive prompts. |
+
+Env overrides: every global flag has a `SPOGO_<NAME>` env equivalent. Two extras:
+
+| Env | Purpose |
+| --- | --- |
+| `SPOGO_TOTP_SECRET_URL` | Override TOTP secret source (`http(s)` or `file://`). |
+| `SPOGO_CONNECT_VERSION` | Override Connect client version sent to playback endpoints. |
+
+## auth
+
+Cookie management. See [Auth](auth.md).
+
+| Command | Purpose |
+| --- | --- |
+| `spogo auth status` | Show stored cookie state for the current profile. |
+| `spogo auth import [--browser <name>] [--browser-profile <name>] [--cookie-path <file>] [--domain <host>]` | Pull cookies from a browser store. |
+| `spogo auth paste [--cookie-path <file>] [--domain <suffix>] [--path <path>]` | Read cookies from stdin (interactive prompts unless `--no-input`). |
+| `spogo auth clear` | Delete stored cookies for the current profile. |
+
+## search
+
+Browse the catalog. Each subcommand takes a query plus `--limit N` and `--offset N`.
+
+| Command | Returns |
+| --- | --- |
+| `spogo search track <query>` | Tracks. |
+| `spogo search album <query>` | Albums. |
+| `spogo search artist <query>` | Artists. |
+| `spogo search playlist <query>` | Playlists. |
+| `spogo search show <query>` | Podcast shows. |
+| `spogo search episode <query>` | Podcast episodes. |
+
+## info
+
+Fetch a single item by ID, URI, or URL.
+
+| Command | Returns |
+| --- | --- |
+| `spogo track info <id|url>` | One track. |
+| `spogo album info <id|url>` | One album with track listing. |
+| `spogo artist info <id|url>` | One artist + top tracks. |
+| `spogo playlist info <id|url>` | One playlist's metadata. |
+| `spogo show info <id|url>` | One show with episodes. |
+| `spogo episode info <id|url>` | One episode. |
+
+## playback
+
+Drive what's playing. See [Playback](playback.md).
+
+| Command | Purpose |
+| --- | --- |
+| `spogo play [<id|url>] [--type <kind>] [--shuffle]` | Resume, or start a track / album / playlist / show / artist. |
+| `spogo pause` | Pause current playback. |
+| `spogo next` | Skip to the next item. |
+| `spogo prev` | Previous (restart current if past ~3s). |
+| `spogo seek <ms|mm:ss>` | Seek within the current item. |
+| `spogo volume <0-100>` | Set device volume. |
+| `spogo shuffle <on|off>` | Toggle shuffle. |
+| `spogo repeat <off|track|context>` | Set repeat mode. |
+| `spogo status` | Print currently playing item + device. |
+
+## queue
+
+Up-next list. See [Queue](queue.md).
+
+| Command | Purpose |
+| --- | --- |
+| `spogo queue add <id|url>` | Append one item to the queue. |
+| `spogo queue show` | Print currently playing + queued items. |
+| `spogo queue clear` | Not supported by Spotify's API; use `spogo play <something>` to replace the context. |
+
+## library
+
+Saved tracks, albums, followed artists, owned/followed playlists. See [Library](library.md).
+
+| Command | Purpose |
+| --- | --- |
+| `spogo library tracks list [--limit N]` | List saved tracks. |
+| `spogo library tracks add <id|url...>` | Save tracks. |
+| `spogo library tracks remove <id|url...>` | Unsave tracks. |
+| `spogo library albums list [--limit N]` | List saved albums. |
+| `spogo library albums add <id|url...>` | Save albums. |
+| `spogo library albums remove <id|url...>` | Unsave albums. |
+| `spogo library artists list [--limit N] [--after <artist-id>]` | List followed artists. |
+| `spogo library artists follow <id|url...>` | Follow artists. |
+| `spogo library artists unfollow <id|url...>` | Unfollow artists. |
+| `spogo library playlists list [--limit N]` | List owned/followed playlists. |
+
+## playlist
+
+Mutate playlists. See [Library](library.md).
+
+| Command | Purpose |
+| --- | --- |
+| `spogo playlist create <name> [--public] [--collab]` | Create a new playlist. |
+| `spogo playlist add <playlist> <track...>` | Append tracks. |
+| `spogo playlist remove <playlist> <track...>` | Remove tracks. |
+| `spogo playlist tracks <playlist> [--limit N]` | List a playlist's items. |
+
+`<playlist>` accepts a playlist ID, URI, URL, or owned-playlist name.
+
+## device
+
+Connect devices. See [Devices](devices.md).
+
+| Command | Purpose |
+| --- | --- |
+| `spogo device list` | List Connect-visible devices. |
+| `spogo device set <name|id>` | Transfer playback to a device. |
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Generic failure |
+| `2` | Invalid usage / validation |
+| `3` | Auth / cookies missing or invalid |
+| `4` | Network / timeouts |
+
+See [Output](output.md) for the full output contract.

docs/devices.md

@@ -0,0 +1,62 @@
+---
+title: Devices
+description: "List Spotify Connect devices, switch active playback, target a specific device per command."
+---
+
+# Devices
+
+Every Spotify-capable thing you've signed in on — phone, desktop app, web player, smart speaker, console — is a Spotify Connect device. spogo can list them and route playback to whichever you want.
+
+## device list
+
+```bash
+spogo device list
+spogo device list --plain
+spogo device list --json
+```
+
+Prints every device Spotify Connect currently knows about, with the active one marked. Plain mode is one device per line: `id`, `name`, `type`, `is_active`, `volume_percent`.
+
+## device set
+
+```bash
+spogo device set "Kitchen"
+spogo device set 0d1841b0976bae2a3a310dd74c0f3df354899bc8
+```
+
+Transfers playback to the named device (case-insensitive substring match) or device ID. If the current Connect state has no origin device, spogo falls back to the Web API transfer endpoint instead of failing.
+
+## --device flag (per-command)
+
+Every playback / queue / status command accepts `--device <name|id>`:
+
+```bash
+spogo play spotify:track:... --device "Kitchen"
+spogo volume 30 --device "MacBook Pro"
+spogo status --device "Living Room"
+```
+
+This temporarily targets a specific device for one command without changing the active device.
+
+## Default device
+
+Set a per-shell default with the env var:
+
+```bash
+export SPOGO_DEVICE="Kitchen"
+spogo play spotify:track:...           # goes to Kitchen
+spogo play spotify:track:... --device "Phone"   # overrides
+```
+
+## Discovery tips
+
+- A device only shows up after it has been opened/played to recently. If your speaker isn't listed, open Spotify on it once.
+- The Spotify desktop app shows up as the device name from the OS (`MacBook Pro`, `peter-laptop`).
+- Web players appear as `Web Player (Chrome)` and similar; they don't persist after the tab closes.
+- Sonos / Google Cast / AirPlay endpoints appear when they're being used by a Spotify session — not always at idle.
+
+## Errors
+
+- **`device not found`** — open the device's Spotify session once, then re-run.
+- **`PREMIUM_REQUIRED`** — Connect transfer needs Premium.
+- **`Connect state has no origin device`** — happens when no device is currently active; spogo retries via the Web API transfer.

docs/engines.md

@@ -0,0 +1,114 @@
+---
+title: Engines
+description: "Choose between connect, web, auto, and applescript — what each engine talks to and when to use it."
+---
+
+# Engines
+
+spogo can talk to Spotify through one of four engines. Pick whichever matches what you need, or let `auto` decide.
+
+## Quick pick
+
+| Need | Engine |
+| --- | --- |
+| Default; works for almost everything | `connect` |
+| Account where Connect is unavailable | `web` |
+| "I just want it to work" | `auto` |
+| Drive Spotify.app on macOS, no network needed | `applescript` |
+
+Set with `--engine <name>` per call, or globally with `SPOGO_ENGINE`.
+
+## connect (default)
+
+Talks to Spotify's internal Connect endpoints — the same ones the official desktop and mobile apps use to coordinate playback across devices. spogo's first choice for everything.
+
+**Best for**
+
+- Playback control (play, pause, next, prev, seek, volume, shuffle, repeat).
+- Device discovery and transfer.
+- Playlist mutations under heavy use (Connect doesn't hit the Web API rate limits).
+- Search and item info via the internal GraphQL surface.
+
+**Tradeoffs**
+
+- A handful of features fall back to the Web API automatically (e.g. transfers when Connect has no origin device, volume on certain hardware that needs `PUT`).
+- Search/info uses GraphQL hashes; if a hash can't be resolved, falls back to web search.
+
+## web
+
+The public Spotify Web API. Slower, lower throughput, and rate-limited (~180 req/min/account before backoff), but it works on accounts where Connect is unavailable.
+
+**Best for**
+
+- Accounts that can't use Connect (rare — usually corporate or family-restricted).
+- Forcing the documented public API for a reproducible test.
+- Anything that requires Web API specific endpoints not yet in Connect.
+
+**Tradeoffs**
+
+- Rate limits will bite under bulk operations. If you see `429`, switch to `connect` or `auto`.
+- Search/info/playback auto-fall-back to Connect when rate limited, so practical behavior is closer to `auto`.
+
+## auto
+
+Try `connect` first; fall back to `web` for unsupported features or when Connect signals the call won't work. The friendliest default if you're not sure.
+
+```bash
+spogo --engine auto play spotify:playlist:...
+```
+
+Most users don't need this — `connect` already falls back to web for the specific paths where it has to. `auto` is useful when you want **explicit** fallback behavior across all calls.
+
+## applescript (macOS only)
+
+Drives the local Spotify desktop app via AppleScript. No network, no cookies, no rate limits — but only the Mac you're on can be controlled, and you only see the local app's view (no Connect device list).
+
+```bash
+spogo --engine applescript play
+spogo --engine applescript pause
+spogo --engine applescript next
+spogo --engine applescript status
+```
+
+**Best for**
+
+- Quick local hotkeys / shortcuts (Raycast, Alfred, sketchybar, etc.) where network round trips are wasted.
+- Sandboxed environments where cookie auth is awkward.
+- Scripts that just need "pause my Mac's Spotify" without touching cloud state.
+
+**Tradeoffs**
+
+- macOS only.
+- No Connect device list (`device list` shows just the Mac), no transfers.
+- Search uses the Mac app's local search; results may differ from web search.
+- Library/playlist mutations are not supported via AppleScript — fall back to `connect` or `web` for those.
+
+## Setting an engine
+
+Per command:
+
+```bash
+spogo --engine connect play
+spogo --engine web search track "weezer"
+spogo --engine applescript pause
+```
+
+Per shell:
+
+```bash
+export SPOGO_ENGINE=connect
+```
+
+In a config profile (`~/.config/spogo/<profile>/config.toml` or platform equivalent):
+
+```toml
+engine = "connect"
+```
+
+## Diagnosing engine issues
+
+```bash
+spogo --debug status
+```
+
+Debug logging on stderr shows which engine handled each call and any fallbacks that fired. See [Output](output.md) and [Troubleshooting](troubleshooting.md).

docs/index.md

@@ -0,0 +1,37 @@
+---
+title: Overview
+permalink: /
+description: "spogo is a Spotify power CLI for search, playback, library, playlists, devices, and scripting — auth via browser cookies, output as human, plain, or JSON."
+---
+
+# spogo
+
+A single Go binary for Spotify on the command line. Search the catalog, drive playback, manage your library and playlists, pick devices, and pipe stable JSON or plain output into anything.
+
+## Why spogo
+
+- **No app registration.** spogo authenticates with the cookies your browser already has — `spogo auth import --browser chrome` and you're authenticated. No client ID, no redirect URI, no developer dashboard.
+- **No tight rate limits.** Talks to Spotify's internal web endpoints (the same ones `open.spotify.com` uses), so search, info, and playback are usable for automation that the public Web API would throttle.
+- **Predictable output.** `--json` for tools, `--plain` for `awk`/`cut`, color human output by default. `NO_COLOR`, `TERM=dumb`, and `--no-color` all respected.
+- **Multiple engines.** `connect` (internal), `web` (public Web API), `auto` (connect first, fall back to web), and `applescript` (drive Spotify.app on macOS) — pick what works.
+- **Built for agents.** Stable exit codes, structured errors, machine output — drop spogo into a shell script or hand it to a coding agent and it'll behave.
+
+## Pick your path
+
+- **Trying it.** Read [Install](install.md) then [Quickstart](quickstart.md). About five minutes from `brew install` to playing a track from the terminal.
+- **Cookies are confusing.** Read [Auth](auth.md) for browser import, manual paste, the WSL fallback, and the `auth status` checks.
+- **Picking an engine.** Read [Engines](engines.md) for the tradeoffs between `connect`, `web`, `auto`, and `applescript`.
+- **Wiring up a script or agent.** Read [Output](output.md) for the JSON/plain contract, then [Agents](agents.md) for end-to-end automation patterns.
+- **Looking up a flag.** Open the [Command Reference](commands.md) — every subcommand is listed with its flags. The full machine-readable spec lives in [Spec](spec.md).
+
+## Status
+
+Actively developed. The [CHANGELOG](https://github.com/steipete/spogo/blob/main/CHANGELOG.md) tracks every shipping release. Current line is `v0.3.x`.
+
+## Out of scope
+
+- MCP server — this is a CLI.
+- Hosted runtime, web UI, or GUI.
+- A library — spogo is a tool, not a Go SDK; internal packages are not stable.
+
+Released under the [MIT license](https://github.com/steipete/spogo/blob/main/LICENSE). Not affiliated with Spotify. Spotify is a trademark of Spotify AB.

docs/install.md

@@ -0,0 +1,58 @@
+---
+title: Install
+description: "Install spogo via Homebrew, go install, or a release binary. macOS, Linux, and Windows are all supported."
+---
+
+# Install
+
+spogo ships as a single static Go binary. Pick whichever path matches how you usually install CLIs.
+
+## Homebrew (macOS, Linux)
+
+```bash
+brew install steipete/tap/spogo
+```
+
+That's it — the formula pulls a signed binary from the latest GitHub release.
+
+## go install (any platform)
+
+```bash
+go install github.com/steipete/spogo/cmd/spogo@latest
+```
+
+Builds from source against your local Go toolchain. Requires Go 1.22+.
+
+## Pre-built release binaries
+
+Grab a tarball or zip for your OS/arch from the [releases page](https://github.com/steipete/spogo/releases) and drop the `spogo` binary somewhere on `PATH`:
+
+```bash
+curl -L https://github.com/steipete/spogo/releases/latest/download/spogo_$(uname -s)_$(uname -m).tar.gz | tar xz
+sudo mv spogo /usr/local/bin/
+spogo --version
+```
+
+## Build from source
+
+```bash
+git clone https://github.com/steipete/spogo.git
+cd spogo
+make spogo
+./spogo --version
+```
+
+## Verify
+
+```bash
+spogo --version
+spogo --help
+```
+
+If `--help` lists `auth`, `search`, `play`, `library`, `playlist`, `device`, and friends, you're done. Next stop: [Quickstart](quickstart.md).
+
+## Uninstall
+
+- Homebrew: `brew uninstall spogo`
+- go install: `rm $(which spogo)`
+- Manual: delete the binary; remove `~/Library/Application Support/spogo` (macOS), `~/.config/spogo` (Linux), or `%APPDATA%\spogo` (Windows) to clear cached cookies and config.

docs/library.md

@@ -0,0 +1,133 @@
+---
+title: Library & Playlists
+description: "List, save, remove tracks/albums/artists, and create or mutate playlists from the terminal."
+---
+
+# Library & Playlists
+
+Your saved tracks, albums, followed artists, and playlists — all listable, mutable, and pipeable.
+
+## library tracks
+
+```bash
+spogo library tracks list [--limit N]
+spogo library tracks add <id|url...>
+spogo library tracks remove <id|url...>
+```
+
+`add`/`remove` accept multiple IDs or URLs in one call:
+
+```bash
+spogo library tracks add \
+  spotify:track:7hQJA50XrCWABAu5v6QZ4i \
+  https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8
+```
+
+## library albums
+
+```bash
+spogo library albums list [--limit N]
+spogo library albums add <id|url...>
+spogo library albums remove <id|url...>
+```
+
+## library artists
+
+```bash
+spogo library artists list [--limit N] [--after <artist-id>]
+spogo library artists follow <id|url...>
+spogo library artists unfollow <id|url...>
+```
+
+`--after` paginates by artist ID — pass the last ID from the previous page to fetch the next.
+
+## library playlists
+
+```bash
+spogo library playlists list [--limit N]
+```
+
+Lists every playlist you own or follow. To list **tracks** in a playlist, use `playlist tracks` below.
+
+## playlist create
+
+```bash
+spogo playlist create "Road Trip"
+spogo playlist create "Team Mix" --public
+spogo playlist create "Shared Notes" --collab
+```
+
+`--public` marks the playlist as discoverable; `--collab` makes it editable by collaborators (collaborative playlists must be private).
+
+## playlist add / remove
+
+```bash
+spogo playlist add <playlist> <track...>
+spogo playlist remove <playlist> <track...>
+```
+
+`<playlist>` is a playlist ID, `spotify:playlist:...` URI, `https://open.spotify.com/playlist/...` URL, or **the playlist name** if you own it. Tracks accept the same flexible forms as `library tracks add`.
+
+```bash
+spogo playlist add "Road Trip" \
+  spotify:track:7hQJA50XrCWABAu5v6QZ4i \
+  spotify:track:0sf12qNH5qcw8qpgymFOqD
+
+spogo playlist remove 37i9dQZF1DXcBWIGoYBM5M spotify:track:7hQJA50XrCWABAu5v6QZ4i
+```
+
+Playlist mutations route through Connect by default — Connect avoids the Web API rate limits that bite when you script bulk add/remove. spogo automatically detects writable playlists and falls back to Web API where Connect can't help.
+
+## playlist tracks
+
+```bash
+spogo playlist tracks <playlist> [--limit N]
+```
+
+Lists the items inside a playlist:
+
+```bash
+spogo playlist tracks "Road Trip" --plain | head
+spogo playlist tracks 37i9dQZF1DXcBWIGoYBM5M --json | jq '.tracks[].name'
+```
+
+## Common patterns
+
+### Save the currently playing track
+
+```bash
+id=$(spogo status --json | jq -r '.item.id')
+spogo library tracks add "$id"
+```
+
+### Build a playlist from a search
+
+```bash
+spogo playlist create "Lo-Fi Coding"
+spogo search track "lo-fi" --limit 20 --plain |
+  awk '{print $1}' |
+  xargs spogo playlist add "Lo-Fi Coding"
+```
+
+### Snapshot all liked tracks to a file
+
+```bash
+spogo library tracks list --limit 1000 --json > liked-tracks.json
+```
+
+### Remove duplicates from a playlist
+
+```bash
+spogo playlist tracks "Road Trip" --plain |
+  awk '{print $1}' |
+  sort | uniq -d |
+  xargs -I {} spogo playlist remove "Road Trip" {}
+```
+
+## Errors
+
+- **`playlist not found`** — confirm spelling, or pass the URI/URL instead of the name.
+- **`not collaborative`** — only owners and explicitly added collaborators can mutate a playlist.
+- **`429 too many requests`** — should not happen with Connect; if you see it on `web`, switch engines or insert a sleep.
+
+See [Engines](engines.md) and [Output](output.md) for output and engine details.

docs/output.md

@@ -0,0 +1,120 @@
+---
+title: Output
+description: "spogo's output contract — human, plain, and JSON modes; stdout vs stderr; color and verbosity controls."
+---
+
+# Output
+
+spogo follows a strict separation: **stdout** carries data, **stderr** carries logs and errors. Pipes always work — `spogo X | tool Y` never gets contaminated with progress bars or color codes when the destination isn't a TTY.
+
+## Three output modes
+
+### Human (default)
+
+Coloured, formatted, friendly. Tables, headings, dimmed metadata. What you want when you're at a terminal.
+
+```bash
+spogo status
+```
+
+Color is automatic when stdout is a TTY. It is disabled when:
+
+- `--no-color` is passed.
+- `NO_COLOR` is set (any value).
+- `TERM=dumb`.
+- stdout is not a TTY (piped, redirected).
+
+### `--plain`
+
+Line-oriented, tab-separated, **stable**. Designed for `awk`, `cut`, `xargs`, and shell pipelines:
+
+```bash
+spogo search track "weezer" --limit 3 --plain
+# spotify:track:7hQJA50XrCWABAu5v6QZ4i  Say It Ain't So     Weezer
+# spotify:track:0sf12qNH5qcw8qpgymFOqD  Buddy Holly         Weezer
+# spotify:track:4PTG3Z6ehGkBFwjybzWkR8  Undone — The Sweater Song   Weezer
+```
+
+Field order per command is documented in the [Spec](spec.md). Tabs are the only delimiter; values containing tabs are escaped.
+
+### `--json`
+
+Structured, **stable** keys. Use `jq` (or any JSON tool) downstream:
+
+```bash
+spogo status --json | jq -r '.item.name + " — " + (.item.artists|map(.name)|join(", "))'
+```
+
+JSON shapes match the [Spec](spec.md). Fields may be added; existing keys are not renamed or removed without a major version bump.
+
+## Verbosity
+
+| Flag | Effect |
+| --- | --- |
+| (default) | Normal: prints results to stdout, errors to stderr. |
+| `-q`, `--quiet` | Suppress non-essential stderr output. |
+| `-v`, `--verbose` | Extra context on stderr (engine choices, fallbacks, timings). |
+| `-d`, `--debug` | Everything `-v` plus HTTP request/response details. |
+
+Debug mode is the right escalation when something is misbehaving — see [Troubleshooting](troubleshooting.md).
+
+## Stdout vs stderr
+
+- **stdout**: command results only.
+- **stderr**: warnings, errors, debug logs, prompts.
+
+This is invariant — every spogo command in every mode follows it. That means `2>/dev/null` mutes diagnostic noise without losing data, and `>file.json` always captures clean output.
+
+```bash
+spogo library tracks list --json --limit 100 > tracks.json 2>/dev/null
+```
+
+## No prompts in pipelines
+
+When stdin is not a TTY, spogo never prompts — commands that would normally ask for input return an error instead. Force prompts off explicitly with `--no-input`.
+
+```bash
+spogo auth paste --no-input < cookies.txt
+```
+
+## Color in CI
+
+CI logs usually want color stripped. spogo respects `NO_COLOR` and detects non-TTY stdout, so the default behavior is correct in GitHub Actions, GitLab CI, etc. — no flag needed.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success |
+| `1` | Generic failure |
+| `2` | Invalid usage / validation error |
+| `3` | Auth / cookies missing or invalid |
+| `4` | Network / timeout |
+
+Use these in scripts:
+
+```bash
+if ! spogo auth status >/dev/null 2>&1; then
+  case $? in
+    3) echo "Need to re-import cookies" >&2 ;;
+    *) echo "Auth check failed" >&2 ;;
+  esac
+  exit 1
+fi
+```
+
+## Examples
+
+```bash
+# Pipe-friendly: just the URI
+spogo search track "weezer" --limit 1 --plain | awk '{print $1}'
+
+# Capture full JSON, pluck a field
+spogo status --json | jq -r '.item.id'
+
+# Mute stderr noise but keep stdout
+spogo library tracks list --json 2>/dev/null > tracks.json
+
+# Force color even in a pipe (rare; for fancy renderers)
+spogo --no-color=false status | bat -l ansi
+```

docs/playback.md

@@ -0,0 +1,122 @@
+---
+title: Playback
+description: "Play, pause, seek, volume, shuffle, repeat — drive Spotify playback from the terminal."
+---
+
+# Playback
+
+All playback commands act on the currently active Spotify Connect device unless you pass `--device`. Use [`spogo device list`](devices.md) to see what's available and `spogo device set <name|id>` to switch.
+
+## play
+
+```bash
+spogo play [<id|url>] [--type <track|album|playlist|show|episode>] [--shuffle]
+```
+
+Accepts:
+
+- A Spotify URI: `spotify:track:7hQJA50XrCWABAu5v6QZ4i`, `spotify:album:...`, `spotify:playlist:...`, `spotify:show:...`, `spotify:episode:...`, `spotify:artist:...`.
+- A web URL: `https://open.spotify.com/track/7hQJA50XrCWABAu5v6QZ4i`.
+- A bare ID — combine with `--type` to disambiguate.
+- No argument — resumes the current item.
+
+Behavior:
+
+- **Tracks** start immediately.
+- **Albums / playlists / shows** start a context — `spogo next` walks through items.
+- **Artists** start with the artist's top tracks (first track first).
+- `--shuffle` enables shuffle on the device before play, randomizing the first track for context URIs.
+
+Examples:
+
+```bash
+spogo play                                                      # resume
+spogo play spotify:track:7hQJA50XrCWABAu5v6QZ4i                 # one track
+spogo play https://open.spotify.com/album/4aawyAB9vmqN3uQ7FjRGTy
+spogo play 37i9dQZF1DXcBWIGoYBM5M --type playlist               # bare ID
+spogo play spotify:playlist:37i9dQZF1DXcBWIGoYBM5M --shuffle    # shuffle on
+spogo play spotify:artist:6sFIWsNpZYqfjUpaCgueju                # top tracks
+```
+
+## pause / resume
+
+```bash
+spogo pause
+spogo play              # no argument resumes
+```
+
+## next / prev
+
+```bash
+spogo next
+spogo prev              # restart current track if past ~3s, else previous
+```
+
+## seek
+
+```bash
+spogo seek 90000        # milliseconds
+spogo seek 1:30         # mm:ss
+spogo seek 0            # back to start
+```
+
+## volume
+
+```bash
+spogo volume 60         # 0-100
+spogo volume 0          # mute
+```
+
+Some devices ignore volume changes (e.g. Spotify Connect on hardware that exposes its own volume).
+
+## shuffle / repeat
+
+```bash
+spogo shuffle on
+spogo shuffle off
+
+spogo repeat off
+spogo repeat track       # loop current track
+spogo repeat context     # loop current album/playlist
+```
+
+## status
+
+```bash
+spogo status             # human, color
+spogo status --plain     # tab-separated key value
+spogo status --json      # full payload
+```
+
+JSON shape includes `is_playing`, `progress_ms`, `device`, `item` (track or episode), `context`, `repeat_state`, `shuffle_state`. Use `jq` to pluck what you need:
+
+```bash
+spogo status --json | jq -r '.item.name + " — " + (.item.artists|map(.name)|join(", "))'
+```
+
+## Targeting a specific device
+
+Every playback command accepts `--device <name|id>`:
+
+```bash
+spogo play spotify:track:... --device "Kitchen"
+spogo volume 30 --device "MacBook Pro"
+spogo pause --device 0d1841b0976bae2a3a310dd74c0f3df354899bc8
+```
+
+When Connect state has no origin device, `spogo` falls back to the Web API transfer endpoint instead of failing.
+
+## Engine notes
+
+- **`connect`** (default) — playback control via Spotify's internal Connect endpoints. Best fidelity for transitions, queueing, and device transfer; auto-falls-back to Web API for transfers when no origin device exists.
+- **`web`** — the public Web API. Slower, rate-limited, but the only option for accounts with restrictive Connect availability.
+- **`auto`** — Connect first, fall back to Web on Connect-unsupported features.
+- **`applescript`** (macOS only) — drive Spotify.app directly via AppleScript. No network, but only sees the local Mac app.
+
+See [Engines](engines.md) for the full breakdown.
+
+## Errors
+
+- `no active device` — open Spotify on a phone/desktop/Connect speaker first, or pass `--device`.
+- `403 PREMIUM_REQUIRED` — playback requires a Spotify Premium account.
+- `429 too many requests` — Connect engine handles rate limits internally; if you see this on `web`, switch to `auto` or `connect`.

docs/queue.md

@@ -0,0 +1,71 @@
+---
+title: Queue
+description: "Add tracks to and inspect the playback queue."
+---
+
+# Queue
+
+The queue is the up-next list managed by Spotify Connect. It survives device transfers and persists across pause/resume.
+
+## queue add
+
+```bash
+spogo queue add <id|url>
+```
+
+Appends one item to the queue. Accepts a track URI, URL, or bare ID (combine with `--type` for non-tracks):
+
+```bash
+spogo queue add spotify:track:7hQJA50XrCWABAu5v6QZ4i
+spogo queue add https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8
+spogo queue add 0sf12qNH5qcw8qpgymFOqD --type track
+```
+
+`queue add` requires an active device. Open Spotify on a phone/desktop or pass `--device <name|id>`.
+
+## queue show
+
+```bash
+spogo queue show
+spogo queue show --plain
+spogo queue show --json
+```
+
+Prints the currently-playing item plus the upcoming queue. Plain mode emits one item per line:
+
+```
+spotify:track:...   Track Name              Artist Name
+spotify:track:...   Another Track           Another Artist
+```
+
+JSON mode includes `currently_playing` and a `queue` array with full track objects.
+
+## queue clear
+
+Spotify's API does not currently expose a way to clear the queue programmatically. The cleanest workaround is to start a new context, which replaces the queue:
+
+```bash
+spogo play spotify:track:7hQJA50XrCWABAu5v6QZ4i      # any single track
+```
+
+## Patterns
+
+### Queue up the top results of a search
+
+```bash
+spogo search track "miles davis" --limit 5 --plain |
+  awk '{print $1}' |
+  while read uri; do spogo queue add "$uri"; done
+```
+
+### Queue an entire playlist's worth of next-up
+
+`queue add` only takes one item — to queue every track from a playlist:
+
+```bash
+spogo playlist tracks "Road Trip" --plain |
+  awk '{print $1}' |
+  while read uri; do spogo queue add "$uri"; done
+```
+
+For long playlists this is N HTTP calls — usually faster to just `play` the playlist as a context.

docs/quickstart.md

@@ -0,0 +1,87 @@
+---
+title: Quickstart
+description: "From install to playing your first track in five minutes — cookie import, search, play, status."
+---
+
+# Quickstart
+
+Five minutes from `brew install` to controlling Spotify from the terminal.
+
+## 1. Install
+
+```bash
+brew install steipete/tap/spogo
+```
+
+Other options live in [Install](install.md).
+
+## 2. Import your browser cookies
+
+spogo authenticates by reading the cookies your browser already has for `open.spotify.com`. Make sure you're logged in there in Chrome (or Brave, Edge, Firefox, Safari), then:
+
+```bash
+spogo auth import --browser chrome
+```
+
+Defaults: Chrome, the `Default` profile. To pick a non-default profile:
+
+```bash
+spogo auth import --browser chrome --browser-profile "Profile 1"
+```
+
+If something goes wrong (locked keychain, weird WSL setup), see [Auth](auth.md) for `auth paste` and other fallbacks.
+
+Verify:
+
+```bash
+spogo auth status
+```
+
+## 3. Find something to play
+
+```bash
+spogo search track "weezer say it ain't so" --limit 3
+```
+
+Add `--json` if you want structured output, or `--plain` for tab-separated lines.
+
+## 4. Play it
+
+```bash
+spogo play spotify:track:7hQJA50XrCWABAu5v6QZ4i
+```
+
+You can also pass an `https://open.spotify.com/...` URL, or a playlist/album/show URI. spogo figures out the type from the URI; for raw IDs use `--type`.
+
+## 5. Drive the rest
+
+```bash
+spogo status                 # what's playing
+spogo pause
+spogo next
+spogo volume 60
+spogo shuffle on
+spogo queue add spotify:track:6rqhFgbbKwnb9MLmUQDhG6
+spogo device list            # available speakers/players
+spogo device set "Kitchen"   # switch playback there
+```
+
+## 6. Pipe it into something
+
+```bash
+# What track is playing right now, machine-readable?
+spogo status --json | jq -r '.item.name'
+
+# Save the top-5 search results into a playlist
+spogo search track "lo-fi" --limit 5 --plain |
+  awk '{print $1}' |
+  xargs spogo playlist add "Lo-Fi Coding"
+```
+
+## Where to next
+
+- [Auth](auth.md) — cookie details, manual paste, troubleshooting.
+- [Engines](engines.md) — when to choose `connect`, `web`, `auto`, or `applescript`.
+- [Output](output.md) — the JSON / plain contract.
+- [Agents](agents.md) — end-to-end automation patterns.
+- [Command Reference](commands.md) — every subcommand and flag.

docs/social-card.svg

@@ -0,0 +1,132 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-labelledby="title desc">
+  <title id="title">spogo social card</title>
+  <desc id="desc">spogo: Spotify, but make it terminal. A Go CLI for Spotify search, playback, library, playlists, queue, and devices.</desc>
+  <defs>
+    <radialGradient id="bg" cx="100%" cy="0%" r="120%">
+      <stop offset="0" stop-color="#143a26"/>
+      <stop offset="0.45" stop-color="#0c1816"/>
+      <stop offset="1" stop-color="#06090c"/>
+    </radialGradient>
+    <radialGradient id="bgWarm" cx="0%" cy="100%" r="60%">
+      <stop offset="0" stop-color="#5a2410" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#06090c" stop-opacity="0"/>
+    </radialGradient>
+    <linearGradient id="panel" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#0f172a"/>
+      <stop offset="1" stop-color="#070b15"/>
+    </linearGradient>
+    <linearGradient id="panelBar" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#1b2438"/>
+      <stop offset="1" stop-color="#141c2e"/>
+    </linearGradient>
+    <linearGradient id="brandSweep" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#1ed760"/>
+      <stop offset="0.4" stop-color="#ffd95e"/>
+      <stop offset="0.7" stop-color="#ff7a3d"/>
+      <stop offset="1" stop-color="#ff6ea1"/>
+    </linearGradient>
+    <linearGradient id="titleSweep" x1="0" y1="0" x2="1" y2="0.2">
+      <stop offset="0" stop-color="#1ed760"/>
+      <stop offset="0.55" stop-color="#ff7a3d"/>
+      <stop offset="1" stop-color="#ff6ea1"/>
+    </linearGradient>
+    <filter id="shadow" x="-10%" y="-10%" width="120%" height="130%">
+      <feDropShadow dx="0" dy="24" stdDeviation="28" flood-color="#000000" flood-opacity="0.45"/>
+    </filter>
+    <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="10" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <rect width="1200" height="630" fill="url(#bg)"/>
+  <rect width="1200" height="630" fill="url(#bgWarm)"/>
+
+  <!-- Brand mark: equalizer bars in tile -->
+  <g transform="translate(76 76)">
+    <rect x="0" y="0" width="118" height="118" rx="26" fill="#0a0e12" stroke="#1d2a30"/>
+    <rect x="30" y="62" width="14" height="36" rx="3" fill="#0f7c34"/>
+    <rect x="52" y="32" width="14" height="66" rx="3" fill="#1ed760"/>
+    <rect x="74" y="44" width="14" height="54" rx="3" fill="#ff7a3d"/>
+  </g>
+
+  <!-- Title -->
+  <text x="76" y="290" fill="#f5f8f6" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="116" font-weight="800" letter-spacing="-2">spogo</text>
+
+  <!-- Tagline with gradient terminal accent -->
+  <text x="76" y="350" fill="#e8efeb" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="36" font-weight="700" letter-spacing="-0.5">
+    Spotify, but make it <tspan fill="url(#titleSweep)" font-weight="800">terminal</tspan>.
+  </text>
+
+  <!-- Description (two lines) -->
+  <text x="76" y="402" fill="#9aa9a3" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="500">One Go binary. Search, playback, library,</text>
+  <text x="76" y="430" fill="#9aa9a3" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="22" font-weight="500">playlists, queue, devices. JSON or plain.</text>
+
+  <!-- Multi-color accent bar -->
+  <rect x="76" y="454" width="280" height="4" rx="2" fill="url(#brandSweep)"/>
+
+  <!-- Bottom row: install pill + URL pill -->
+  <g transform="translate(76 490)">
+    <rect x="0" y="0" width="372" height="52" rx="12" fill="#0a0e12" stroke="#1d2a30"/>
+    <text x="22" y="34" fill="#1ed760" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="700">$</text>
+    <text x="44" y="34" fill="#e6f7ec" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="18" font-weight="600">brew install steipete/tap/spogo</text>
+
+    <rect x="392" y="0" width="148" height="52" rx="12" fill="#1ed760"/>
+    <text x="466" y="34" fill="#06281a" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="20" font-weight="800" text-anchor="middle">spogo.sh</text>
+  </g>
+
+  <!-- Right-side terminal mockup -->
+  <g transform="translate(672 142)" filter="url(#shadow)">
+    <rect x="0" y="0" width="464" height="346" rx="18" fill="url(#panel)" stroke="#1d2a30"/>
+    <rect x="0" y="0" width="464" height="42" rx="18" fill="url(#panelBar)"/>
+    <rect x="0" y="22" width="464" height="20" fill="url(#panelBar)"/>
+    <circle cx="24" cy="21" r="6" fill="#ff7a3d"/>
+    <circle cx="46" cy="21" r="6" fill="#ffd95e"/>
+    <circle cx="68" cy="21" r="6" fill="#1ed760"/>
+    <text x="232" y="27" fill="#94a3b8" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13" font-weight="500" text-anchor="middle">spogo — open.spotify.com</text>
+
+    <!-- Terminal content -->
+    <text x="22" y="80" fill="#1ed760" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="15" font-weight="600">$ spogo status</text>
+    <text x="22" y="106" fill="#cbd5e1" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">▶ Buddy Holly — Weezer</text>
+    <text x="22" y="128" fill="#94a3b8" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">  Pinkerton · 1:48 / 2:39</text>
+    <text x="22" y="150" fill="#94a3b8" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">  Kitchen · vol 60</text>
+
+    <text x="22" y="186" fill="#1ed760" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="15" font-weight="600">$ spogo status --json | jq .item.id</text>
+
+    <rect x="22" y="204" width="420" height="118" rx="10" fill="#06090c" stroke="#1d2a30"/>
+    <text x="38" y="232" fill="#fbbf24" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">{</text>
+    <text x="54" y="252" fill="#a5b4fc" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">"is_playing": true,</text>
+    <text x="54" y="272" fill="#a5b4fc" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">"item": {</text>
+    <text x="74" y="292" fill="#a7f3d0" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">"name": "Buddy Holly",</text>
+    <text x="74" y="312" fill="#a7f3d0" font-family="JetBrains Mono, SFMono-Regular, Menlo, monospace" font-size="13">"id":   "0sf12qNH5qcw8qpgymFOqD"</text>
+  </g>
+
+  <!-- Service pills below terminal -->
+  <g transform="translate(672 514)" font-family="Inter, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="14" font-weight="600">
+    <g>
+      <rect x="0" y="0" width="86" height="32" rx="16" fill="#0a0e12" stroke="#1d2a30"/>
+      <circle cx="16" cy="16" r="4" fill="#1ed760"/>
+      <text x="52" y="21" fill="#e8efeb" text-anchor="middle">Search</text>
+    </g>
+    <g transform="translate(98 0)">
+      <rect x="0" y="0" width="98" height="32" rx="16" fill="#0a0e12" stroke="#1d2a30"/>
+      <circle cx="16" cy="16" r="4" fill="#ff7a3d"/>
+      <text x="58" y="21" fill="#e8efeb" text-anchor="middle">Playback</text>
+    </g>
+    <g transform="translate(208 0)">
+      <rect x="0" y="0" width="86" height="32" rx="16" fill="#0a0e12" stroke="#1d2a30"/>
+      <circle cx="16" cy="16" r="4" fill="#ff6ea1"/>
+      <text x="52" y="21" fill="#e8efeb" text-anchor="middle">Library</text>
+    </g>
+    <g transform="translate(306 0)">
+      <rect x="0" y="0" width="78" height="32" rx="16" fill="#0a0e12" stroke="#1d2a30"/>
+      <circle cx="16" cy="16" r="4" fill="#8a6dff"/>
+      <text x="48" y="21" fill="#e8efeb" text-anchor="middle">Queue</text>
+    </g>
+    <g transform="translate(396 0)">
+      <rect x="0" y="0" width="68" height="32" rx="16" fill="#0a0e12" stroke="#1d2a30"/>
+      <circle cx="16" cy="16" r="4" fill="#4ea0ff"/>
+      <text x="42" y="21" fill="#e8efeb" text-anchor="middle">JSON</text>
+    </g>
+  </g>
+</svg>

docs/troubleshooting.md

@@ -0,0 +1,151 @@
+---
+title: Troubleshooting
+description: "Common spogo failures — auth, devices, rate limits, WSL — and how to fix them."
+---
+
+# Troubleshooting
+
+The first move when anything misbehaves is to re-run with `-d`:
+
+```bash
+spogo -d <command>
+```
+
+Debug logs go to stderr and include engine choices, fallbacks, HTTP status codes, and request IDs. They will not pollute a `--json` or `--plain` pipeline.
+
+## Auth
+
+### `no cookies found`
+
+spogo couldn't read cookies from the browser store. Check:
+
+1. You're actually logged in to `https://open.spotify.com` in that browser.
+2. You picked the right `--browser-profile` (Chrome's default is `Default`, but most users have `Profile 1`, `Profile 2`).
+3. spogo printed an underlying warning — recent versions surface the real reason (locked keychain, decryption failure, missing profile dir).
+
+If browser-store reads keep failing, fall back to `auth paste` (see [Auth](auth.md#manual-paste-wsl-fallback)).
+
+### `401 Unauthorized` / `403 Forbidden` from any read command
+
+Cookies are stale. Re-import:
+
+```bash
+spogo auth import --browser chrome
+spogo auth status
+```
+
+If that doesn't help, your browser's session may have expired. Visit `https://open.spotify.com`, log back in, then re-import.
+
+### macOS Chrome keychain prompt
+
+The first cookie import will trigger a "Chrome wants to use your confidential information from your keychain" dialog. Click **Always Allow**. If you mis-click **Deny**, fix it via:
+
+`Keychain Access → login → Passwords → search "Chrome Safe Storage" → right-click → Get Info → Access Control → +` add `spogo`.
+
+### WSL: cookie decryption fails
+
+Chrome on WSL has a fragile DPAPI/Linux-keyring combo. Use `auth paste` instead:
+
+1. DevTools → Application → Cookies → `https://open.spotify.com` → copy `sp_dc`, `sp_t`.
+2. `spogo auth paste`.
+
+## Playback
+
+### `no active device`
+
+Open Spotify on a phone, desktop, or Connect speaker once so it registers, or pass `--device <name|id>`:
+
+```bash
+spogo device list
+spogo play spotify:track:... --device "Kitchen"
+```
+
+### `403 PREMIUM_REQUIRED`
+
+Playback control (play, pause, seek, transfer, queue) requires a Spotify Premium account. spogo's read-only commands (`status`, `search`, `library tracks list`, etc.) work on free accounts.
+
+### Volume command does nothing
+
+Some Connect endpoints expose their own hardware volume and ignore Spotify's volume command. Try `--device` to a different target, or set the volume on the device itself.
+
+### `device set` fails with "Connect state has no origin device"
+
+Recent spogo versions auto-fall-back to the Web API transfer endpoint here. If you're on an older version, upgrade:
+
+```bash
+brew upgrade spogo
+```
+
+## Search & info
+
+### Empty results for a search that should match
+
+The internal GraphQL search uses query hashes that occasionally roll. spogo falls back to web search when a hash can't be resolved; if both fail, try:
+
+```bash
+spogo --engine web search track "your query"
+```
+
+### `track info` returns sparse data
+
+Older spogo versions had Connect responses missing artist/album for some track shapes. Upgrade to the latest release.
+
+## Rate limits
+
+### `429 too many requests`
+
+Should not happen on the `connect` engine for normal usage. If you see it:
+
+- You're on `--engine web` — switch to `connect` or `auto`.
+- You're hammering the API in a tight loop — add `sleep 0.2` between calls, or batch via `--limit`.
+- Multiple spogo profiles are sharing the same Spotify account at the same time — the throttle is per-account, not per-process.
+
+## Output
+
+### Color codes leaking into a file
+
+You're capturing stdout but spogo thinks stdout is a TTY. This shouldn't happen — spogo detects TTY correctly — but if it does, force off:
+
+```bash
+spogo --no-color status > out.txt
+NO_COLOR=1 spogo status > out.txt
+```
+
+### `jq` complains the JSON is malformed
+
+You're capturing stderr too. Redirect it:
+
+```bash
+spogo status --json 2>/dev/null | jq .
+```
+
+### Pipe is empty / silent
+
+The command may be writing to stderr only (errors, prompts). Re-run without redirecting stderr to see what happened:
+
+```bash
+spogo <command>
+```
+
+## Engines
+
+### "Connect engine returned X" — what does that mean?
+
+Run with `-d` and look for the `engine=` line in the debug output. spogo logs which engine handled each call and any fallback that fired.
+
+### AppleScript engine: "spotify not running"
+
+Open Spotify.app first. AppleScript can't launch the app reliably; spogo expects it to already be open.
+
+### AppleScript engine: search results differ from web
+
+The Mac app uses local search. Switch to `connect` or `web` for canonical results.
+
+## Diagnostics to share when filing an issue
+
+```bash
+spogo --version
+spogo -d <failing command> 2> spogo.log
+```
+
+Attach `spogo.log` (redact any cookie values it contains) to a [GitHub issue](https://github.com/steipete/spogo/issues).

scripts/build-docs-site.mjs

@@ -0,0 +1,583 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+
+import { css, faviconSvg, js, themeBootstrap, themeToggleSvg } from "./docs-site-assets.mjs";
+
+const root = process.cwd();
+const docsDir = path.join(root, "docs");
+const outDir = path.join(root, "dist", "docs-site");
+const repoBase = "https://github.com/steipete/spogo";
+const repoEditBase = `${repoBase}/edit/main/docs`;
+const cname = readCname();
+const siteBase = cname ? `https://${cname}` : "";
+
+const productName = "spogo";
+const productTagline = "Spotify, but make it terminal";
+const productDescription =
+  "spogo is a Spotify power CLI: search, control playback, manage library and playlists, pick devices, and script with stable JSON or plain output.";
+const brewInstall = "brew install steipete/tap/spogo";
+
+const sections = [
+  ["Start", ["index.md", "install.md", "quickstart.md", "auth.md"]],
+  ["Use", ["playback.md", "library.md", "queue.md", "devices.md"]],
+  ["Engine & Output", ["engines.md", "output.md"]],
+  ["Automation", ["agents.md", "troubleshooting.md"]],
+  ["Reference", ["commands.md", "spec.md", "RELEASING.md"]],
+];
+
+const buildExcludes = [/^refactor\//];
+
+fs.rmSync(outDir, { recursive: true, force: true });
+fs.mkdirSync(outDir, { recursive: true });
+
+const allPages = allMarkdown(docsDir).map((file) => {
+  const rel = path.relative(docsDir, file).replaceAll(path.sep, "/");
+  const raw = fs.readFileSync(file, "utf8");
+  const { frontmatter, body } = parseFrontmatter(raw);
+  const cleaned = stripStrayDirectives(body);
+  const title = frontmatter.title || firstHeading(cleaned) || titleize(path.basename(rel, ".md"));
+  return { file, rel, title, outRel: outPath(rel, frontmatter), markdown: cleaned, frontmatter };
+});
+
+const pages = allPages.filter((page) => !buildExcludes.some((re) => re.test(page.rel)));
+const pageMap = new Map(pages.map((page) => [page.rel, page]));
+const permalinkMap = new Map();
+for (const page of pages) {
+  if (page.frontmatter.permalink) {
+    permalinkMap.set(normalizePermalink(page.frontmatter.permalink), page);
+  }
+}
+
+const nav = sections
+  .map(([name, rels]) => ({
+    name,
+    pages: rels.map((rel) => pageMap.get(rel)).filter(Boolean),
+  }))
+  .filter((section) => section.pages.length);
+
+const sectionByRel = new Map();
+for (const section of nav) for (const page of section.pages) sectionByRel.set(page.rel, section.name);
+const orderedPages = nav.flatMap((s) => s.pages);
+
+for (const page of pages) {
+  const html = markdownToHtml(page.markdown, page.rel);
+  const toc = tocFromHtml(html);
+  const idx = orderedPages.findIndex((p) => p.rel === page.rel);
+  const prev = idx > 0 ? orderedPages[idx - 1] : null;
+  const next = idx >= 0 && idx < orderedPages.length - 1 ? orderedPages[idx + 1] : null;
+  const sectionName = sectionByRel.get(page.rel) || "Reference";
+  const pageOut = path.join(outDir, page.outRel);
+  fs.mkdirSync(path.dirname(pageOut), { recursive: true });
+  fs.writeFileSync(pageOut, layout({ page, html, toc, prev, next, sectionName }), "utf8");
+}
+
+fs.writeFileSync(path.join(outDir, "favicon.svg"), faviconSvg(), "utf8");
+copyStaticAsset("social-card.svg");
+copyStaticAsset("social-card.png");
+fs.writeFileSync(path.join(outDir, ".nojekyll"), "", "utf8");
+if (cname) fs.writeFileSync(path.join(outDir, "CNAME"), cname, "utf8");
+validateLinks(outDir);
+console.log(`built docs site: ${path.relative(root, outDir)}`);
+
+function readCname() {
+  for (const candidate of [path.join(docsDir, "CNAME"), path.join(root, "CNAME")]) {
+    if (fs.existsSync(candidate)) return fs.readFileSync(candidate, "utf8").trim();
+  }
+  return "";
+}
+
+function copyStaticAsset(name) {
+  const source = path.join(docsDir, name);
+  if (fs.existsSync(source)) fs.copyFileSync(source, path.join(outDir, name));
+}
+
+function parseFrontmatter(raw) {
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return { frontmatter: {}, body: raw };
+  const fm = {};
+  for (const line of match[1].split("\n")) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*?)\s*$/);
+    if (!m) continue;
+    let value = m[2];
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    fm[m[1]] = value;
+  }
+  return { frontmatter: fm, body: raw.slice(match[0].length) };
+}
+
+function stripStrayDirectives(body) {
+  return body
+    .replace(/\r\n/g, "\n")
+    .split("\n")
+    .filter((line) => !/^\s*\{:\s*[^}]*\}\s*$/.test(line))
+    .map((line) => line.replace(/\s*\{:\s*[^}]*\}\s*$/, ""))
+    .join("\n");
+}
+
+function normalizePermalink(value) {
+  let v = value.trim();
+  if (!v) return "/";
+  if (!v.startsWith("/")) v = `/${v}`;
+  if (v.length > 1 && v.endsWith("/")) v = v.slice(0, -1);
+  return v;
+}
+
+function allMarkdown(dir) {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .flatMap((entry) => {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) return allMarkdown(full);
+      return entry.name.endsWith(".md") ? [full] : [];
+    })
+    .sort();
+}
+
+function outPath(rel, frontmatter = {}) {
+  if (frontmatter.permalink) {
+    const permalink = normalizePermalink(frontmatter.permalink);
+    if (permalink === "/") return "index.html";
+    return `${permalink.slice(1)}/index.html`;
+  }
+  if (rel === "index.md") return "index.html";
+  if (rel === "README.md") return "index.html";
+  if (rel.endsWith("/README.md")) return rel.replace(/README\.md$/, "index.html");
+  return rel.replace(/\.md$/, ".html");
+}
+
+function firstHeading(markdown) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim();
+}
+
+function titleize(input) {
+  return input.replaceAll("-", " ").replace(/\b\w/g, (m) => m.toUpperCase());
+}
+
+function markdownToHtml(markdown, currentRel) {
+  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+  const html = [];
+  let paragraph = [];
+  let list = null;
+  let fence = null;
+  let blockquote = [];
+
+  const flushParagraph = () => {
+    if (!paragraph.length) return;
+    html.push(`<p>${inline(paragraph.join(" "), currentRel)}</p>`);
+    paragraph = [];
+  };
+  const closeList = () => {
+    if (!list) return;
+    html.push(`</${list}>`);
+    list = null;
+  };
+  const flushBlockquote = () => {
+    if (!blockquote.length) return;
+    const inner = markdownToHtml(blockquote.join("\n"), currentRel);
+    html.push(`<blockquote>${inner}</blockquote>`);
+    blockquote = [];
+  };
+  const splitRow = (line) => {
+    let trimmed = line.trim();
+    if (trimmed.startsWith("|")) trimmed = trimmed.slice(1);
+    if (trimmed.endsWith("|") && !trimmed.endsWith("\\|")) trimmed = trimmed.slice(0, -1);
+    const cells = [];
+    let current = "";
+    for (let idx = 0; idx < trimmed.length; idx++) {
+      const char = trimmed[idx];
+      if (char === "\\" && trimmed[idx + 1] === "|") {
+        current += "\\|";
+        idx += 1;
+        continue;
+      }
+      if (char === "|") {
+        cells.push(current.trim().replace(/\\\|/g, "|"));
+        current = "";
+        continue;
+      }
+      current += char;
+    }
+    cells.push(current.trim().replace(/\\\|/g, "|"));
+    return cells;
+  };
+  const isDivider = (line) => /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)+\|?\s*$/.test(line);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(/^```([\w+-]+)?\s*$/);
+    if (fenceMatch) {
+      flushParagraph();
+      closeList();
+      flushBlockquote();
+      if (fence) {
+        html.push(`<pre><code class="language-${escapeAttr(fence.lang)}">${escapeHtml(fence.lines.join("\n"))}</code></pre>`);
+        fence = null;
+      } else {
+        fence = { lang: fenceMatch[1] || "text", lines: [] };
+      }
+      continue;
+    }
+    if (fence) {
+      fence.lines.push(line);
+      continue;
+    }
+    if (/^>\s?/.test(line)) {
+      flushParagraph();
+      closeList();
+      blockquote.push(line.replace(/^>\s?/, ""));
+      continue;
+    }
+    flushBlockquote();
+    if (!line.trim()) {
+      flushParagraph();
+      closeList();
+      continue;
+    }
+    if (/^\s*---+\s*$/.test(line)) {
+      flushParagraph();
+      closeList();
+      html.push("<hr>");
+      continue;
+    }
+    const heading = line.match(/^(#{1,4})\s+(.+)$/);
+    if (heading) {
+      flushParagraph();
+      closeList();
+      const level = heading[1].length;
+      const text = heading[2].trim();
+      const id = slug(text);
+      const inner = inline(text, currentRel);
+      if (level === 1) {
+        html.push(`<h1 id="${id}">${inner}</h1>`);
+      } else {
+        html.push(`<h${level} id="${id}"><a class="anchor" href="#${id}" aria-label="Anchor link">#</a>${inner}</h${level}>`);
+      }
+      continue;
+    }
+    if (line.trimStart().startsWith("|") && line.includes("|", line.indexOf("|") + 1) && isDivider(lines[i + 1] || "")) {
+      flushParagraph();
+      closeList();
+      const header = splitRow(line);
+      const aligns = splitRow(lines[i + 1]).map((cell) => {
+        const left = cell.startsWith(":");
+        const right = cell.endsWith(":");
+        return right && left ? "center" : right ? "right" : left ? "left" : "";
+      });
+      i += 1;
+      const rows = [];
+      while (i + 1 < lines.length && lines[i + 1].trimStart().startsWith("|")) {
+        i += 1;
+        rows.push(splitRow(lines[i]));
+      }
+      const th = header.map((c, idx) => `<th${aligns[idx] ? ` style="text-align:${aligns[idx]}"` : ""}>${inline(c, currentRel)}</th>`).join("");
+      const tb = rows.map((r) => `<tr>${r.map((c, idx) => `<td${aligns[idx] ? ` style="text-align:${aligns[idx]}"` : ""}>${inline(c, currentRel)}</td>`).join("")}</tr>`).join("");
+      html.push(`<table><thead><tr>${th}</tr></thead><tbody>${tb}</tbody></table>`);
+      continue;
+    }
+    const bullet = line.match(/^\s*-\s+(.+)$/);
+    const numbered = line.match(/^\s*\d+\.\s+(.+)$/);
+    if (bullet || numbered) {
+      flushParagraph();
+      const tag = bullet ? "ul" : "ol";
+      if (list && list !== tag) closeList();
+      if (!list) {
+        list = tag;
+        html.push(`<${tag}>`);
+      }
+      html.push(`<li>${inline((bullet || numbered)[1], currentRel)}</li>`);
+      continue;
+    }
+    paragraph.push(line.trim());
+  }
+  flushParagraph();
+  closeList();
+  flushBlockquote();
+  return html.join("\n");
+}
+
+function inline(text, currentRel) {
+  const stash = [];
+  let out = text.replace(/`([^`]+)`/g, (_, code) => {
+    stash.push(`<code>${escapeHtml(code)}</code>`);
+    return `\u0000${stash.length - 1}\u0000`;
+  });
+  out = escapeHtml(out)
+    .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+    .replace(/(^|[^*])\*([^*\s][^*]*?)\*(?!\*)/g, "$1<em>$2</em>")
+    .replace(/(^|[^_])_([^_\s][^_]*?)_(?!_)/g, "$1<em>$2</em>")
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, label, href) => `<a href="${escapeAttr(rewriteHref(href, currentRel))}">${label}</a>`)
+    .replace(/&lt;(https?:\/\/[^\s<>]+)&gt;/g, '<a href="$1">$1</a>');
+  out = out.replace(/\\\|/g, "|");
+  out = out.replace(/&lt;br&gt;/g, "<br>");
+  return out.replace(/\u0000(\d+)\u0000/g, (_, i) => stash[Number(i)]);
+}
+
+function rewriteHref(href, currentRel) {
+  if (/^(https?:|mailto:|tel:|#)/.test(href)) return href;
+  const [raw, hash = ""] = href.split("#");
+  if (!raw) return hash ? `#${hash}` : "";
+  if (raw.startsWith("/")) {
+    const target = permalinkMap.get(normalizePermalink(raw));
+    if (target) {
+      const currentOut = pageMap.get(currentRel)?.outRel || outPath(currentRel);
+      const out = hrefToOutRel(target.outRel, currentOut);
+      return hash ? `${out}#${hash}` : out;
+    }
+    return href;
+  }
+  if (!raw.endsWith(".md")) return href;
+  const from = path.posix.dirname(currentRel);
+  const target = path.posix.normalize(path.posix.join(from, raw));
+  let rewritten = pageMap.get(target)?.outRel || outPath(target);
+  const currentOut = pageMap.get(currentRel)?.outRel || outPath(currentRel);
+  rewritten = hrefToOutRel(rewritten, currentOut);
+  return `${rewritten}${hash ? `#${hash}` : ""}`;
+}
+
+function tocFromHtml(html) {
+  const items = [];
+  const re = /<h([23]) id="([^"]+)">([\s\S]*?)<\/h[23]>/g;
+  let m;
+  while ((m = re.exec(html))) {
+    const text = m[3]
+      .replace(/<a class="anchor"[^>]*>.*?<\/a>/, "")
+      .replace(/<[^>]+>/g, "")
+      .trim();
+    items.push({ level: Number(m[1]), id: m[2], text });
+  }
+  if (items.length < 2) return "";
+  return `<nav class="toc" aria-label="On this page"><h2>On this page</h2>${items
+    .map((i) => `<a class="toc-l${i.level}" href="#${i.id}">${escapeHtml(i.text)}</a>`)
+    .join("")}</nav>`;
+}
+
+function isHomePage(page) {
+  if (page.frontmatter.permalink && normalizePermalink(page.frontmatter.permalink) === "/") return true;
+  return page.rel === "index.md" || page.rel === "README.md";
+}
+
+function homeHero(page) {
+  const description = page.frontmatter.description || productDescription;
+  const installRel = pageMap.get("install.md")?.outRel
+    ? hrefToOutRel(pageMap.get("install.md").outRel, page.outRel)
+    : "install.html";
+  const quickstartRel = pageMap.get("quickstart.md")?.outRel
+    ? hrefToOutRel(pageMap.get("quickstart.md").outRel, page.outRel)
+    : "quickstart.html";
+  const capabilities = ["Search", "Playback", "Library", "Playlists", "Queue", "Devices", "Connect", "Web", "AppleScript"];
+  const tagline = escapeHtml(productTagline);
+  // Highlight "terminal" with a gradient accent span.
+  const highlighted = tagline.replace(
+    /(terminal)/i,
+    '<span class="accent">$1</span>',
+  );
+  return `<header class="home-hero">
+        <p class="eyebrow">Spotify · Single binary · Cookies, no app</p>
+        <h1>${highlighted}</h1>
+        <p class="lede">${escapeHtml(description)}</p>
+        <div class="home-cta">
+          <a class="btn btn-primary" href="${quickstartRel}">Quickstart</a>
+          <a class="btn btn-ghost" href="${repoBase}" rel="noopener">GitHub</a>
+          <div class="home-install" aria-label="Install with Homebrew">
+            <span class="prompt" aria-hidden="true">$</span>
+            <code>${escapeHtml(brewInstall)}</code>
+          </div>
+        </div>
+        <div class="home-services" aria-label="What spogo covers">
+          ${capabilities.map((s) => `<span>${escapeHtml(s)}</span>`).join("")}
+        </div>
+        <p class="muted"><a href="${installRel}">Other install options →</a></p>
+      </header>`;
+}
+
+function standardHero(page, sectionName, editUrl) {
+  return `<header class="hero">
+        <div class="hero-text">
+          <p class="eyebrow">${escapeHtml(sectionName)}</p>
+          <h1>${escapeHtml(page.title)}</h1>
+        </div>
+        <div class="hero-meta">
+          <a class="repo" href="${repoBase}" rel="noopener">GitHub</a>
+          <a class="edit" href="${escapeAttr(editUrl)}" rel="noopener">Edit page</a>
+        </div>
+      </header>`;
+}
+
+function layout({ page, html, toc, prev, next, sectionName }) {
+  const depth = page.outRel.split("/").length - 1;
+  const rootPrefix = depth ? "../".repeat(depth) : "";
+  const editUrl = `${repoEditBase}/${page.rel}`;
+  const home = isHomePage(page);
+  const prevNext = !home && (prev || next) ? pageNavHtml(prev, next, page.outRel) : "";
+  const heroBlock = home ? homeHero(page) : standardHero(page, sectionName, editUrl);
+  const articleClass = home ? "doc doc-home" : "doc";
+  const tocBlock = home ? "" : toc;
+  const titleSuffix = home ? `${productName} — ${productTagline}` : `${page.title} — ${productName}`;
+  const description = page.frontmatter.description || (home ? productDescription : `${page.title} — ${productName} CLI documentation.`);
+  const canonicalUrl = pageCanonicalUrl(page);
+  const socialImage = siteBase ? `${siteBase}/social-card.png` : `${rootPrefix}social-card.png`;
+  const socialMeta = [
+    ["link", "rel", "canonical", "href", canonicalUrl],
+    ["meta", "property", "og:type", "content", "website"],
+    ["meta", "property", "og:site_name", "content", productName],
+    ["meta", "property", "og:title", "content", titleSuffix],
+    ["meta", "property", "og:description", "content", description],
+    ["meta", "property", "og:url", "content", canonicalUrl],
+    ["meta", "property", "og:image", "content", socialImage],
+    ["meta", "property", "og:image:width", "content", "1200"],
+    ["meta", "property", "og:image:height", "content", "630"],
+    ["meta", "name", "twitter:card", "content", "summary_large_image"],
+    ["meta", "name", "twitter:title", "content", titleSuffix],
+    ["meta", "name", "twitter:description", "content", description],
+    ["meta", "name", "twitter:image", "content", socialImage],
+  ].map(tagHtml).join("\n  ");
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <script>${themeBootstrap()}</script>
+  <title>${escapeHtml(titleSuffix)}</title>
+  <meta name="description" content="${escapeAttr(description)}">
+  ${socialMeta}
+  <link rel="icon" href="${rootPrefix}favicon.svg" type="image/svg+xml">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+  <style>${css()}</style>
+</head>
+<body${home ? ' class="home"' : ""}>
+  <button class="nav-toggle" type="button" aria-label="Toggle navigation" aria-expanded="false">
+    <span aria-hidden="true"></span><span aria-hidden="true"></span><span aria-hidden="true"></span>
+  </button>
+  <div class="shell">
+    <aside class="sidebar">
+      <div class="sidebar-top">
+        <a class="brand" href="${hrefToOutRel("index.html", page.outRel)}" aria-label="${productName} docs home">
+          <span class="mark" aria-hidden="true"><i></i><i></i><i></i></span>
+          <span><strong>${escapeHtml(productName)}</strong><small>Spotify CLI docs</small></span>
+        </a>
+        <button class="theme-toggle" type="button" aria-label="Switch to dark mode">${themeToggleSvg()}</button>
+      </div>
+      <label class="search"><span>Search</span><input id="doc-search" type="search" placeholder="auth, play, queue"></label>
+      <nav>${navHtml(page)}</nav>
+    </aside>
+    <main>
+      ${heroBlock}
+      <div class="doc-grid${home ? " doc-grid-home" : ""}">
+        <article class="${articleClass}">${html}${prevNext}</article>
+        ${tocBlock}
+      </div>
+    </main>
+  </div>
+  <script>${js()}</script>
+</body>
+</html>`;
+}
+
+function pageCanonicalUrl(page) {
+  if (!siteBase) return page.outRel;
+  if (page.outRel === "index.html") return `${siteBase}/`;
+  const rel = page.outRel.endsWith("/index.html") ? page.outRel.slice(0, -"index.html".length) : page.outRel;
+  return `${siteBase}/${rel}`;
+}
+
+function tagHtml([tag, k1, v1, k2, v2]) {
+  return tag === "link" ? `<link ${k1}="${v1}" ${k2}="${escapeAttr(v2)}">` : `<meta ${k1}="${v1}" ${k2}="${escapeAttr(v2)}">`;
+}
+
+function pageNavHtml(prev, next, currentOutRel) {
+  const cell = (page, dir) => {
+    if (!page) return "";
+    return `<a class="page-nav-${dir}" href="${hrefToOutRel(page.outRel, currentOutRel)}"><small>${dir === "prev" ? "Previous" : "Next"}</small><span>${escapeHtml(page.title)}</span></a>`;
+  };
+  return `<nav class="page-nav" aria-label="Pager">${cell(prev, "prev")}${cell(next, "next")}</nav>`;
+}
+
+function navHtml(currentPage) {
+  return nav
+    .map((section) => `<section><h2>${escapeHtml(section.name)}</h2>${section.pages.map((page) => {
+      const href = hrefToOutRel(page.outRel, currentPage.outRel);
+      const active = page.rel === currentPage.rel ? " active" : "";
+      return `<a class="nav-link${active}" href="${href}">${escapeHtml(navTitle(page))}</a>`;
+    }).join("")}</section>`)
+    .join("");
+}
+
+function navTitle(page) {
+  if (page.rel === "index.md") return "Overview";
+  return page.title.replace(/^`spogo\s*/, "").replace(/`$/, "");
+}
+
+function hrefToOutRel(targetOutRel, currentOutRel) {
+  const currentDir = path.posix.dirname(currentOutRel);
+  if (targetOutRel.endsWith("/index.html")) {
+    const targetDir = targetOutRel.slice(0, -"index.html".length);
+    const rel = path.posix.relative(currentDir, targetDir || ".") || ".";
+    return rel.endsWith("/") ? rel : `${rel}/`;
+  }
+  if (targetOutRel === "index.html") {
+    const rel = path.posix.relative(currentDir, ".") || ".";
+    return rel.endsWith("/") ? rel : `${rel}/`;
+  }
+  return path.posix.relative(currentDir, targetOutRel) || path.posix.basename(targetOutRel);
+}
+
+function slug(text) {
+  return text.toLowerCase().replace(/`/g, "").replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+
+function escapeHtml(value) {
+  return String(value ?? "").replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+}
+
+function escapeAttr(value) {
+  return escapeHtml(value);
+}
+
+function validateLinks(outputDir) {
+  const failures = [];
+  const placeholderHrefs = /^(url|path|file|dir|name|id)$/i;
+  for (const file of allHtml(outputDir)) {
+    const html = fs.readFileSync(file, "utf8");
+    for (const match of html.matchAll(/href="([^"]+)"/g)) {
+      const href = match[1];
+      if (/^(#|https?:|mailto:|tel:|javascript:)/.test(href)) continue;
+      if (placeholderHrefs.test(href)) continue;
+      const [rawPath, anchor = ""] = href.split("#");
+      const targetPath = rawPath
+        ? path.resolve(path.dirname(file), rawPath)
+        : file;
+      const target = fs.existsSync(targetPath) && fs.statSync(targetPath).isDirectory()
+        ? path.join(targetPath, "index.html")
+        : targetPath;
+      if (!fs.existsSync(target)) {
+        failures.push(`${path.relative(outputDir, file)}: ${href} -> missing ${path.relative(outputDir, target)}`);
+        continue;
+      }
+      if (anchor) {
+        const targetHtml = fs.readFileSync(target, "utf8");
+        if (!targetHtml.includes(`id="${anchor}"`) && !targetHtml.includes(`name="${anchor}"`)) {
+          failures.push(`${path.relative(outputDir, file)}: ${href} -> missing anchor`);
+        }
+      }
+    }
+  }
+  if (failures.length) {
+    throw new Error(`broken docs links:\n${failures.join("\n")}`);
+  }
+}
+
+function allHtml(dir) {
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .flatMap((entry) => {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) return allHtml(full);
+      return entry.name.endsWith(".html") ? [full] : [];
+    })
+    .sort();
+}

scripts/docs-site-assets.mjs

@@ -0,0 +1,348 @@
+export function css() {
+  return `
+:root{
+  --ink:#0f1115;
+  --text:#1f2328;
+  --muted:#6b7280;
+  --subtle:#9aa1ab;
+  --bg:#fafafa;
+  --paper:#ffffff;
+  --paper-2:#f3f4f6;
+  --accent:#169c46;
+  --accent-soft:rgba(30,215,96,.12);
+  --accent-strong:#0f7c34;
+  --brand:#1ed760;
+  --brand-deep:#0f7c34;
+  --brand-glow:rgba(30,215,96,.22);
+  --accent-warm:#ff7a3d;
+  --accent-pink:#ff6ea1;
+  --accent-violet:#8a6dff;
+  --accent-blue:#4ea0ff;
+  --accent-yellow:#ffd95e;
+  --line:#e5e7eb;
+  --line-soft:#eef0f3;
+  --code-bg:#0c1014;
+  --code-fg:#e6f7ec;
+  --shadow-card:0 1px 2px rgba(15,17,21,.04),0 8px 24px rgba(15,17,21,.05);
+  --shadow-glow:0 0 0 1px rgba(30,215,96,.18),0 18px 60px rgba(30,215,96,.12);
+}
+[data-theme="dark"]{
+  --ink:#f5f8f6;
+  --text:#d6dedc;
+  --muted:#8c9994;
+  --subtle:#5e6c68;
+  --bg:#0a0e12;
+  --paper:#11171c;
+  --paper-2:#161e23;
+  --accent:#1ed760;
+  --accent-soft:rgba(30,215,96,.18);
+  --accent-strong:#4ee07c;
+  --brand:#1ed760;
+  --brand-deep:#13a248;
+  --brand-glow:rgba(30,215,96,.32);
+  --line:#1f2a30;
+  --line-soft:#161e23;
+  --code-bg:#06090c;
+  --code-fg:#dfeee6;
+  --shadow-card:0 1px 2px rgba(0,0,0,.4),0 12px 36px rgba(0,0,0,.45);
+  --shadow-glow:0 0 0 1px rgba(30,215,96,.28),0 22px 80px rgba(30,215,96,.22);
+}
+*{box-sizing:border-box}
+html{scroll-behavior:smooth;scroll-padding-top:24px}
+html,body{background:var(--bg);color:var(--text)}
+body{margin:0;font-family:"Inter",ui-sans-serif,system-ui,-apple-system,Segoe UI,sans-serif;line-height:1.65;overflow-x:hidden;-webkit-font-smoothing:antialiased;font-feature-settings:"cv02","cv03","cv04","cv11";transition:background .25s ease,color .25s ease}
+::selection{background:var(--brand);color:#07120b}
+a{color:var(--accent);text-decoration:none;transition:color .12s}
+a:hover{text-decoration:underline;text-underline-offset:.2em}
+[data-theme="dark"] a{color:var(--accent-strong)}
+.shell{display:grid;grid-template-columns:268px minmax(0,1fr);min-height:100vh}
+.sidebar{position:sticky;top:0;height:100vh;overflow:auto;padding:22px 22px 22px;background:var(--paper);border-right:1px solid var(--line);scrollbar-width:thin;scrollbar-color:var(--line) transparent;transition:background .25s ease,border-color .25s ease}
+.sidebar::-webkit-scrollbar{width:6px}
+.sidebar::-webkit-scrollbar-thumb{background:var(--line);border-radius:6px}
+.sidebar-top{display:flex;align-items:center;justify-content:space-between;gap:10px;margin-bottom:22px}
+.brand{display:flex;align-items:center;gap:11px;color:var(--ink);text-decoration:none;flex:1;min-width:0}
+.brand:hover{text-decoration:none}
+.brand .mark{display:flex;align-items:flex-end;justify-content:center;gap:3px;flex:0 0 28px;height:28px;padding:0}
+.brand .mark i{display:block;width:5px;border-radius:2px;background:var(--brand);transform-origin:bottom;animation:eq 1.4s ease-in-out infinite}
+.brand .mark i:nth-child(1){height:55%;background:var(--brand-deep);animation-delay:-.2s}
+.brand .mark i:nth-child(2){height:100%;animation-delay:-.5s}
+.brand .mark i:nth-child(3){height:75%;background:var(--accent-warm);animation-delay:-.9s}
+@keyframes eq{
+  0%,100%{transform:scaleY(.55)}
+  20%{transform:scaleY(1)}
+  40%{transform:scaleY(.4)}
+  60%{transform:scaleY(.85)}
+  80%{transform:scaleY(.5)}
+}
+@media(prefers-reduced-motion:reduce){
+  .brand .mark i{animation:none}
+}
+.brand strong{display:block;font-size:1.05rem;line-height:1.1;font-weight:700;letter-spacing:0;color:var(--ink)}
+.brand small{display:block;color:var(--muted);font-size:.74rem;margin-top:3px;font-weight:400}
+.theme-toggle{display:inline-flex;align-items:center;justify-content:center;width:34px;height:34px;border-radius:9px;background:var(--paper-2);border:1px solid var(--line);color:var(--ink);cursor:pointer;padding:0;transition:background .15s,border-color .15s,color .15s,transform .15s}
+.theme-toggle:hover{border-color:var(--brand);color:var(--accent-strong);transform:translateY(-1px)}
+.theme-toggle svg{width:16px;height:16px;display:block}
+.theme-toggle .icon-sun{display:none}
+.theme-toggle .icon-moon{display:block}
+[data-theme="dark"] .theme-toggle .icon-sun{display:block}
+[data-theme="dark"] .theme-toggle .icon-moon{display:none}
+.search{display:block;margin:0 0 22px}
+.search span{display:block;color:var(--muted);font-size:.7rem;font-weight:600;text-transform:uppercase;letter-spacing:0;margin-bottom:7px}
+.search input{width:100%;border:1px solid var(--line);background:var(--paper);color:var(--text);border-radius:8px;padding:9px 12px;font:inherit;font-size:.9rem;outline:none;transition:border-color .15s,box-shadow .15s,background .25s ease}
+.search input:focus{border-color:var(--accent);box-shadow:0 0 0 3px var(--accent-soft)}
+nav section{margin:0 0 18px}
+nav h2{font-size:.68rem;color:var(--muted);text-transform:uppercase;letter-spacing:0;margin:0 0 6px;font-weight:600}
+.nav-link{display:block;color:var(--text);text-decoration:none;border-radius:6px;padding:5px 10px;margin:1px 0;font-size:.9rem;line-height:1.4;transition:background .12s,color .12s}
+.nav-link:hover{background:var(--line-soft);color:var(--ink);text-decoration:none}
+.nav-link.active{background:var(--accent-soft);color:var(--accent-strong);font-weight:600}
+main{min-width:0;padding:32px clamp(20px,4.5vw,56px) 80px;max-width:1180px;margin:0 auto;width:100%}
+.hero{display:flex;align-items:flex-end;justify-content:space-between;gap:22px;border-bottom:1px solid var(--line);padding:8px 0 22px;margin-bottom:8px;flex-wrap:wrap}
+.hero-text{min-width:0;flex:1 1 320px}
+.eyebrow{margin:0 0 8px;color:var(--accent-strong);font-weight:700;text-transform:uppercase;letter-spacing:.06em;font-size:.7rem}
+.hero h1{font-size:2.25rem;line-height:1.1;letter-spacing:-.01em;margin:0;font-weight:700;color:var(--ink)}
+.hero-meta{display:flex;gap:8px;flex:0 0 auto;flex-wrap:wrap}
+.repo,.edit,.btn-ghost{border:1px solid var(--line);color:var(--text);text-decoration:none;border-radius:7px;padding:6px 11px;font-weight:500;font-size:.83rem;background:var(--paper);transition:border-color .15s,color .15s,background .15s}
+.repo:hover,.edit:hover,.btn-ghost:hover{border-color:var(--brand);color:var(--ink);text-decoration:none}
+.edit{color:var(--muted)}
+.home-hero{
+  position:relative;
+  padding:44px 32px 40px;
+  margin:0 -8px 32px;
+  border-radius:20px;
+  border:1px solid var(--line);
+  background-color:var(--paper);
+  background-image:
+    radial-gradient(ellipse 70% 110% at 100% -10%, var(--brand-glow) 0%, transparent 60%),
+    radial-gradient(ellipse 60% 90% at -5% 110%, rgba(255,122,61,.18) 0%, transparent 60%),
+    linear-gradient(160deg, var(--paper) 0%, var(--paper-2) 100%);
+  box-shadow:var(--shadow-card);
+  overflow:hidden;
+  isolation:isolate;
+}
+[data-theme="dark"] .home-hero{
+  background-image:
+    radial-gradient(ellipse 75% 110% at 100% -10%, rgba(30,215,96,.28) 0%, transparent 65%),
+    radial-gradient(ellipse 60% 90% at -5% 110%, rgba(255,122,61,.16) 0%, transparent 65%),
+    linear-gradient(160deg, #0e151a 0%, #0a1014 100%);
+  border-color:#1a262d;
+}
+.home-hero>*{position:relative;z-index:1}
+.home-hero h1{font-size:3.4rem;line-height:1.04;letter-spacing:-.02em;margin:0 0 .35em;font-weight:800;color:var(--ink)}
+.home-hero h1 .accent{background:linear-gradient(120deg,var(--brand) 0%,var(--accent-warm) 65%,var(--accent-pink) 100%);-webkit-background-clip:text;background-clip:text;-webkit-text-fill-color:transparent;color:transparent}
+.home-hero .lede{font-size:1.18rem;line-height:1.55;color:var(--text);opacity:.85;margin:0 0 1.2em;max-width:60ch}
+.home-cta{display:flex;flex-wrap:wrap;gap:10px;align-items:center;margin:0 0 18px}
+.home-cta .btn{display:inline-flex;align-items:center;gap:7px;border-radius:999px;padding:11px 22px;font-weight:700;font-size:.92rem;text-decoration:none;transition:background .15s,border-color .15s,color .15s,transform .15s,box-shadow .15s}
+.home-cta .btn-primary{background:var(--brand);color:#07120b;border:1px solid var(--brand);box-shadow:0 8px 22px var(--brand-glow)}
+.home-cta .btn-primary:hover{background:#19c557;border-color:#19c557;text-decoration:none;transform:translateY(-1px);box-shadow:0 12px 28px var(--brand-glow)}
+.home-cta .btn-ghost{padding:11px 22px;border-radius:999px;background:var(--paper);border:1px solid var(--line);color:var(--text)}
+.home-cta .btn-ghost:hover{border-color:var(--brand);color:var(--ink);transform:translateY(-1px)}
+.home-install{display:flex;align-items:center;gap:14px;background:var(--code-bg);color:var(--code-fg);border-radius:10px;padding:11px 14px;font:500 .9rem/1.2 "JetBrains Mono","SF Mono",ui-monospace,monospace;max-width:38em;border:1px solid #1f2937;box-shadow:0 6px 18px rgba(15,17,21,.08)}
+.home-install .prompt{color:var(--brand);user-select:none;font-weight:700;flex:0 0 auto}
+.home-install code{flex:1;min-width:0;background:transparent;border:0;color:var(--code-fg);font:inherit;padding:0;white-space:pre;overflow:hidden;text-overflow:ellipsis}
+.home-install .copy{flex:0 0 auto;margin-left:auto;background:rgba(255,255,255,.08);color:var(--code-fg);border:1px solid rgba(255,255,255,.18);border-radius:7px;padding:6px 12px;font:600 .72rem/1 "Inter",sans-serif;letter-spacing:.02em;cursor:pointer;transition:background .15s,border-color .15s,transform .12s}
+.home-install .copy:hover{background:rgba(255,255,255,.16);border-color:rgba(255,255,255,.28);transform:translateY(-1px)}
+.home-install .copy.copied{background:var(--brand);border-color:var(--brand);color:#07120b}
+.home-services{display:flex;flex-wrap:wrap;gap:7px;margin:18px 0 14px}
+.home-services span{display:inline-flex;align-items:center;gap:6px;padding:5px 12px;border:1px solid var(--line);border-radius:999px;font-size:.78rem;color:var(--text);background:var(--paper);font-weight:500;transition:transform .15s,border-color .15s,color .15s}
+.home-services span::before{content:"";width:7px;height:7px;border-radius:50%;background:var(--brand)}
+.home-services span:nth-child(7n+1)::before{background:var(--brand)}
+.home-services span:nth-child(7n+2)::before{background:var(--accent-warm)}
+.home-services span:nth-child(7n+3)::before{background:var(--accent-pink)}
+.home-services span:nth-child(7n+4)::before{background:var(--accent-violet)}
+.home-services span:nth-child(7n+5)::before{background:var(--accent-blue)}
+.home-services span:nth-child(7n+6)::before{background:var(--accent-yellow)}
+.home-services span:nth-child(7n+7)::before{background:var(--brand-deep)}
+.home-services span:hover{transform:translateY(-1px);border-color:var(--brand)}
+.home-hero .muted{color:var(--muted);font-size:.92rem;margin:6px 0 0}
+.home-hero .muted a{color:var(--accent-strong);font-weight:600}
+.doc-grid{display:grid;grid-template-columns:minmax(0,1fr);gap:48px;margin-top:24px}
+.doc-grid-home{margin-top:8px}
+@media(min-width:1180px){.doc-grid{grid-template-columns:minmax(0,72ch) 200px;justify-content:start}.doc-grid-home{grid-template-columns:minmax(0,76ch);justify-content:start}}
+.doc{min-width:0;max-width:72ch;overflow-wrap:break-word}
+.doc-home{max-width:78ch}
+.doc h1{font-size:2.6rem;line-height:1.08;letter-spacing:-.01em;margin:0 0 .4em;font-weight:700;color:var(--ink)}
+body:not(.home) .doc>h1:first-child{display:none}
+.doc h2{font-size:1.45rem;line-height:1.2;margin:2em 0 .5em;font-weight:700;letter-spacing:-.01em;color:var(--ink);position:relative;padding-left:14px}
+.doc h2::before{content:"";position:absolute;left:0;top:.35em;bottom:.3em;width:4px;border-radius:3px;background:linear-gradient(180deg,var(--brand) 0%,var(--brand-deep) 100%)}
+.doc h3{font-size:1.1rem;margin:1.7em 0 .35em;position:relative;font-weight:600;color:var(--ink);letter-spacing:0}
+.doc h4{font-size:.98rem;margin:1.4em 0 .25em;color:var(--ink);position:relative;font-weight:600}
+.doc h2:first-child,.doc h3:first-child,.doc h4:first-child{margin-top:.2em}
+.doc :is(h2,h3,h4) .anchor{position:absolute;left:-1.05em;top:0;color:var(--subtle);opacity:0;text-decoration:none;font-weight:400;padding-right:.3em;transition:opacity .12s,color .12s}
+.doc h2 .anchor{left:-.7em}
+.doc :is(h2,h3,h4):hover .anchor{opacity:.7}
+.doc :is(h2,h3,h4) .anchor:hover{opacity:1;color:var(--accent-strong);text-decoration:none}
+.doc p{margin:0 0 1.05em}
+.doc ul,.doc ol{padding-left:1.3rem;margin:0 0 1.15em}
+.doc li{margin:.25em 0}
+.doc li>p{margin:0 0 .4em}
+.doc strong{font-weight:600;color:var(--ink)}
+.doc em{font-style:italic}
+.doc code{font-family:"JetBrains Mono","SF Mono",ui-monospace,monospace;font-size:.84em;background:var(--accent-soft);border:1px solid var(--line);border-radius:5px;padding:.08em .4em;color:var(--accent-strong)}
+[data-theme="dark"] .doc code{color:var(--brand);background:rgba(30,215,96,.12)}
+.doc pre{position:relative;overflow:auto;background:var(--code-bg);color:var(--code-fg);border-radius:10px;padding:16px 18px 14px;margin:1.3em 0;font-size:.85em;line-height:1.6;scrollbar-width:thin;scrollbar-color:#334155 transparent;border:1px solid #1f2937;box-shadow:0 6px 18px rgba(15,17,21,.06)}
+.doc pre::before{content:"";position:absolute;top:10px;left:14px;width:9px;height:9px;border-radius:50%;background:var(--brand);box-shadow:14px 0 0 #ffd95e,28px 0 0 #ff6ea1;opacity:.85}
+.doc pre>code{padding-top:14px}
+.doc pre::-webkit-scrollbar{height:8px;width:8px}
+.doc pre::-webkit-scrollbar-thumb{background:#334155;border-radius:8px}
+.doc pre code{display:block;background:transparent;border:0;color:inherit;padding:0;font-size:1em;white-space:pre}
+.doc pre .copy{position:absolute;top:10px;right:10px;background:rgba(255,255,255,.08);color:var(--code-fg);border:1px solid rgba(255,255,255,.18);border-radius:7px;padding:5px 12px;font:600 .7rem/1 "Inter",sans-serif;letter-spacing:.02em;cursor:pointer;opacity:0;transition:opacity .15s,background .15s,border-color .15s}
+.doc pre:hover .copy,.doc pre .copy:focus{opacity:1}
+.doc pre .copy:hover{background:rgba(255,255,255,.12)}
+.doc pre .copy.copied{background:var(--brand);border-color:var(--brand);color:#07120b;opacity:1}
+.doc blockquote{margin:1.4em 0;padding:12px 18px;border-left:4px solid var(--brand);background:var(--accent-soft);border-radius:0 10px 10px 0;color:var(--text)}
+.doc blockquote p:last-child{margin-bottom:0}
+.doc table{width:100%;border-collapse:collapse;margin:1.2em 0;font-size:.92em;background:var(--paper);border-radius:8px;overflow:hidden;border:1px solid var(--line)}
+.doc th,.doc td{border-bottom:1px solid var(--line);padding:9px 12px;text-align:left;vertical-align:top}
+.doc tr:last-child td{border-bottom:0}
+.doc th{font-weight:700;color:var(--ink);background:var(--paper-2);border-bottom:1px solid var(--line);font-size:.86em;text-transform:uppercase;letter-spacing:.04em}
+.doc hr{border:0;border-top:1px solid var(--line);margin:2.2em 0}
+.toc{position:sticky;top:24px;align-self:start;font-size:.84rem;padding-left:14px;border-left:1px solid var(--line);max-height:calc(100vh - 48px);overflow:auto;scrollbar-width:thin;scrollbar-color:var(--line) transparent}
+.toc::-webkit-scrollbar{width:5px}
+.toc::-webkit-scrollbar-thumb{background:var(--line);border-radius:5px}
+.toc h2{font-size:.66rem;color:var(--muted);text-transform:uppercase;letter-spacing:.06em;margin:0 0 10px;font-weight:700}
+.toc a{display:block;color:var(--muted);text-decoration:none;padding:4px 0 4px 10px;line-height:1.35;border-left:2px solid transparent;margin-left:-12px;transition:color .12s,border-color .12s}
+.toc a:hover{color:var(--ink);text-decoration:none}
+.toc a.active{color:var(--accent-strong);border-left-color:var(--brand);font-weight:600}
+.toc-l3{padding-left:22px!important;font-size:.94em}
+@media(max-width:1179px){.toc{display:none}}
+.page-nav{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:48px;border-top:1px solid var(--line);padding-top:20px}
+.page-nav>a{display:block;border:1px solid var(--line);background:var(--paper);border-radius:10px;padding:14px 16px;text-decoration:none;color:var(--text);transition:border-color .15s,transform .15s,box-shadow .15s}
+.page-nav>a:hover{border-color:var(--brand);text-decoration:none;color:var(--ink);transform:translateY(-1px);box-shadow:var(--shadow-card)}
+.page-nav small{display:block;color:var(--muted);font-size:.7rem;text-transform:uppercase;letter-spacing:.05em;margin-bottom:5px;font-weight:700}
+.page-nav span{display:block;font-weight:600;line-height:1.3;color:var(--ink)}
+.page-nav-prev{text-align:left}
+.page-nav-next{text-align:right;grid-column:2}
+.page-nav-prev:only-child{grid-column:1}
+.nav-toggle{display:none;position:fixed;top:14px;right:14px;top:calc(14px + env(safe-area-inset-top, 0px));right:calc(14px + env(safe-area-inset-right, 0px));z-index:20;width:40px;height:40px;border-radius:10px;background:var(--paper);border:1px solid var(--line);color:var(--ink);cursor:pointer;padding:10px 9px;flex-direction:column;align-items:stretch;justify-content:space-between;box-shadow:0 4px 14px rgba(15,17,21,.12)}
+.nav-toggle span{display:block;width:100%;height:2px;flex:0 0 2px;background:currentColor;border-radius:2px;transition:transform .2s,opacity .2s}
+.nav-toggle[aria-expanded="true"] span:nth-child(1){transform:translateY(8px) rotate(45deg)}
+.nav-toggle[aria-expanded="true"] span:nth-child(2){opacity:0}
+.nav-toggle[aria-expanded="true"] span:nth-child(3){transform:translateY(-8px) rotate(-45deg)}
+@media(max-width:900px){
+  .shell{display:block}
+  .sidebar{position:fixed;inset:0 30% 0 0;max-width:320px;height:100vh;z-index:15;transform:translateX(-100%);transition:transform .25s ease,background .25s ease,border-color .25s ease;box-shadow:0 18px 40px rgba(15,17,21,.18);background:var(--paper);pointer-events:none}
+  .sidebar.open{transform:translateX(0);pointer-events:auto}
+  .nav-toggle{display:flex}
+  main{padding:64px 18px 56px}
+  .hero{padding-top:6px}
+  .hero h1{font-size:1.8rem}
+  .home-hero{padding:28px 18px 26px;margin:0 0 24px;border-radius:16px}
+  .home-hero h1{font-size:2.5rem}
+  .doc h1{font-size:2.1rem}
+  .hero-meta{width:100%;justify-content:flex-start}
+  .doc{padding:0}
+  .doc-grid{margin-top:18px;gap:24px}
+  .doc :is(h2,h3,h4) .anchor{display:none}
+  .doc h2{padding-left:12px}
+}
+@media(max-width:520px){
+  main{padding:60px 14px 48px}
+  .doc pre{margin-left:-14px;margin-right:-14px;border-radius:0;border-left:0;border-right:0}
+  .home-install{flex-wrap:wrap}
+}
+`;
+}
+
+export function js() {
+  return `
+const root=document.documentElement;
+const themeBtn=document.querySelector('.theme-toggle');
+const storedThemeKey='spogo-theme';
+function applyTheme(t,persist){
+  if(t!=='light'&&t!=='dark')t='light';
+  root.dataset.theme=t;
+  if(themeBtn){
+    const next=t==='dark'?'light':'dark';
+    themeBtn.setAttribute('aria-label','Switch to '+next+' mode');
+    themeBtn.setAttribute('title','Switch to '+next+' mode');
+  }
+  if(persist){try{localStorage.setItem(storedThemeKey,t)}catch{}}
+}
+function currentTheme(){
+  if(root.dataset.theme==='dark'||root.dataset.theme==='light')return root.dataset.theme;
+  return 'light';
+}
+themeBtn?.addEventListener('click',()=>{applyTheme(currentTheme()==='dark'?'light':'dark',true)});
+applyTheme(currentTheme(),false);
+const systemDark=window.matchMedia('(prefers-color-scheme: dark)');
+const onSystemChange=(e)=>{let stored=null;try{stored=localStorage.getItem(storedThemeKey)}catch{}if(stored)return;applyTheme(e.matches?'dark':'light',false)};
+systemDark.addEventListener?.('change',onSystemChange);
+
+const sidebar=document.querySelector('.sidebar');
+const toggle=document.querySelector('.nav-toggle');
+const mobileNav=window.matchMedia('(max-width: 900px)');
+const sidebarFocusable='a[href],button,input,select,textarea,[tabindex]';
+function setSidebarFocusable(enabled){
+  sidebar?.querySelectorAll(sidebarFocusable).forEach((el)=>{
+    if(enabled){
+      if(el.dataset.sidebarTabindex!==undefined){
+        if(el.dataset.sidebarTabindex)el.setAttribute('tabindex',el.dataset.sidebarTabindex);
+        else el.removeAttribute('tabindex');
+        delete el.dataset.sidebarTabindex;
+      }
+    }else if(el.dataset.sidebarTabindex===undefined){
+      el.dataset.sidebarTabindex=el.getAttribute('tabindex')??'';
+      el.setAttribute('tabindex','-1');
+    }
+  });
+}
+function setSidebarOpen(open){
+  if(!sidebar||!toggle)return;
+  sidebar.classList.toggle('open',open);
+  toggle.setAttribute('aria-expanded',open?'true':'false');
+  if(mobileNav.matches){
+    sidebar.inert=!open;
+    if(open)sidebar.removeAttribute('aria-hidden');
+    else sidebar.setAttribute('aria-hidden','true');
+    setSidebarFocusable(open);
+  }else{
+    sidebar.inert=false;
+    sidebar.removeAttribute('aria-hidden');
+    setSidebarFocusable(true);
+  }
+}
+setSidebarOpen(false);
+toggle?.addEventListener('click',()=>setSidebarOpen(!sidebar?.classList.contains('open')));
+document.addEventListener('click',(e)=>{if(!sidebar?.classList.contains('open'))return;if(sidebar.contains(e.target)||toggle?.contains(e.target))return;setSidebarOpen(false)});
+document.addEventListener('keydown',(e)=>{if(e.key==='Escape')setSidebarOpen(false)});
+const syncSidebarForViewport=()=>setSidebarOpen(sidebar?.classList.contains('open')??false);
+if(mobileNav.addEventListener)mobileNav.addEventListener('change',syncSidebarForViewport);
+else mobileNav.addListener?.(syncSidebarForViewport);
+
+const input=document.getElementById('doc-search');
+input?.addEventListener('input',()=>{const q=input.value.trim().toLowerCase();document.querySelectorAll('nav section').forEach(sec=>{let any=false;sec.querySelectorAll('.nav-link').forEach(a=>{const m=!q||a.textContent.toLowerCase().includes(q);a.style.display=m?'block':'none';if(m)any=true});sec.style.display=any?'block':'none'})});
+function attachCopy(target,getText){const btn=document.createElement('button');btn.type='button';btn.className='copy';btn.textContent='Copy';btn.addEventListener('click',async()=>{try{await navigator.clipboard.writeText(getText());btn.textContent='Copied';btn.classList.add('copied');setTimeout(()=>{btn.textContent='Copy';btn.classList.remove('copied')},1400)}catch{btn.textContent='Failed';setTimeout(()=>{btn.textContent='Copy'},1400)}});target.appendChild(btn)}
+document.querySelectorAll('.doc pre').forEach(pre=>attachCopy(pre,()=>pre.querySelector('code')?.textContent??''));
+document.querySelectorAll('.home-install').forEach(el=>attachCopy(el,()=>el.querySelector('code')?.textContent??''));
+const tocLinks=document.querySelectorAll('.toc a');
+if(tocLinks.length){const map=new Map();tocLinks.forEach(a=>{const id=a.getAttribute('href').slice(1);const el=document.getElementById(id);if(el)map.set(el,a)});const setActive=l=>{tocLinks.forEach(x=>x.classList.remove('active'));l.classList.add('active')};const obs=new IntersectionObserver(entries=>{const visible=entries.filter(e=>e.isIntersecting).sort((a,b)=>a.boundingClientRect.top-b.boundingClientRect.top);if(visible.length){const link=map.get(visible[0].target);if(link)setActive(link)}},{rootMargin:'-15% 0px -65% 0px',threshold:0});map.forEach((_,el)=>obs.observe(el))}
+`;
+}
+
+export function themeBootstrap() {
+  // Inline-able tiny script that runs before render, no FOUC.
+  return `(function(){try{var k='spogo-theme';var s=localStorage.getItem(k);var d=window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches;var t=s==='dark'||s==='light'?s:(d?'dark':'light');document.documentElement.dataset.theme=t}catch(e){}})();`;
+}
+
+export function faviconSvg() {
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="spogo">
+<defs>
+  <radialGradient id="g" cx="50%" cy="50%" r="50%">
+    <stop offset="0%" stop-color="#1ed760"/>
+    <stop offset="65%" stop-color="#0f7c34"/>
+    <stop offset="100%" stop-color="#06281a"/>
+  </radialGradient>
+</defs>
+<rect width="64" height="64" rx="14" fill="#0c1014"/>
+<circle cx="32" cy="32" r="22" fill="url(#g)"/>
+<circle cx="32" cy="32" r="22" fill="none" stroke="rgba(255,255,255,.08)" stroke-width="1"/>
+<circle cx="32" cy="32" r="14" fill="none" stroke="rgba(0,0,0,.35)" stroke-width="1"/>
+<circle cx="32" cy="32" r="9" fill="none" stroke="rgba(0,0,0,.45)" stroke-width="1"/>
+<circle cx="32" cy="32" r="4" fill="#ff7a3d"/>
+<circle cx="32" cy="32" r="1.4" fill="#0c1014"/>
+</svg>`;
+}
+
+export function themeToggleSvg() {
+  return `<svg class="icon-moon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg><svg class="icon-sun" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/></svg>`;
+}