docs(spotify): implement milestone M5 install docs

docs/spotify.md

@@ -1,8 +1,8 @@
 # Spotify
 
-The Spotify skill adds a local helper for Spotify Web API work from OpenClaw.
+The Spotify skill adds a local helper for Spotify Web API playlist work from OpenClaw.
 
-Current scope:
+## Scope
 
 - search Spotify tracks
 - list the current user's playlists
@@ -13,6 +13,91 @@ Current scope:
 
 The skill uses OAuth2 Authorization Code with PKCE. It does not need a Spotify client secret and does not use browser automation for Spotify operations.
 
-Implementation is in `skills/spotify/`.
+## Setup
 
-Setup and live-smoke details will be completed with the auth and command implementation.
+Create the local credential directory:
+
+```bash
+mkdir -p ~/.openclaw/workspace/.clawdbot/credentials/spotify
+chmod 700 ~/.openclaw/workspace/.clawdbot/credentials/spotify
+$EDITOR ~/.openclaw/workspace/.clawdbot/credentials/spotify/config.json
+```
+
+Example `config.json`:
+
+```json
+{
+  "clientId": "your-spotify-client-id",
+  "redirectUri": "http://127.0.0.1:8888/callback"
+}
+```
+
+Run auth from the active OpenClaw skill copy:
+
+```bash
+cd ~/.openclaw/workspace/skills/spotify
+scripts/setup.sh
+```
+
+Or run only the OAuth login after dependencies are installed:
+
+```bash
+scripts/spotify auth
+scripts/spotify status --json
+```
+
+Tokens are written to the local credentials directory as `token.json` with owner-only file mode when the filesystem supports it. Do not print token files.
+
+## Commands
+
+```bash
+scripts/spotify status --json
+scripts/spotify search "Radiohead Karma Police" --limit 3 --json
+scripts/spotify list-playlists --limit 10 --json
+scripts/spotify create-playlist "OpenClaw Mix" --description "Created by OpenClaw" --json
+scripts/spotify add-to-playlist "<playlistId>" "spotify:track:..." --json
+scripts/spotify remove-from-playlist "<playlistId>" "spotify:track:..." --json
+scripts/spotify search-and-add "<playlistId>" "Radiohead Karma Police" --json
+scripts/spotify import "/path/to/tracks.txt" --playlist "Imported Mix" --json
+scripts/spotify import "/path/to/playlist.m3u8" --playlist-id "<playlistId>" --json
+scripts/spotify import "/path/to/music-folder" --playlist "Folder Import" --json
+```
+
+`--playlist NAME` always creates a new playlist, private by default unless `--public` is provided. Spotify allows duplicate playlist names, so use `--playlist-id ID` when updating an existing playlist.
+
+## Import Behavior
+
+Text imports ignore blank lines and comment lines starting with `#` or `//`.
+
+M3U/M3U8 imports use `#EXTINF` metadata when present and fall back to the filename otherwise.
+
+Folder imports recursively scan supported audio filenames and ignore non-audio files.
+
+The importer searches Spotify once per parsed candidate, adds the first match, reports misses, and skips duplicate Spotify URI matches.
+
+## Endpoint Notes
+
+This skill uses the current Spotify playlist endpoints:
+
+```text
+GET  /v1/me
+GET  /v1/search?type=track&q=<query>&limit=<1-10>
+GET  /v1/me/playlists?limit=<n>&offset=<n>
+POST /v1/me/playlists
+POST /v1/playlists/{id}/items
+DELETE /v1/playlists/{id}/items
+POST https://accounts.spotify.com/api/token
+```
+
+Do not use the removed 2026 endpoints:
+
+```text
+POST /v1/users/{user_id}/playlists
+GET  /v1/users/{id}/playlists
+POST /v1/playlists/{id}/tracks
+DELETE /v1/playlists/{id}/tracks
+```
+
+## Live Smoke Caution
+
+Spotify does not offer a normal delete-playlist Web API operation. Any live smoke that creates a playlist must be explicitly approved because the playlist can only be manually cleaned up later.

skills/spotify/SKILL.md

@@ -18,3 +18,41 @@ scripts/spotify --help
 This skill uses the Spotify Web API with OAuth2 Authorization Code + PKCE. It does not use browser automation for Spotify operations and does not need a Spotify client secret.
 
 Do not print token files or OAuth callback data. Use `--json` for machine-readable command output.
+
+## Setup
+
+```bash
+mkdir -p ~/.openclaw/workspace/.clawdbot/credentials/spotify
+chmod 700 ~/.openclaw/workspace/.clawdbot/credentials/spotify
+$EDITOR ~/.openclaw/workspace/.clawdbot/credentials/spotify/config.json
+cd ~/.openclaw/workspace/skills/spotify
+scripts/setup.sh
+```
+
+`config.json`:
+
+```json
+{
+  "clientId": "your-spotify-client-id",
+  "redirectUri": "http://127.0.0.1:8888/callback"
+}
+```
+
+## Commands
+
+```bash
+scripts/spotify status --json
+scripts/spotify search "Radiohead Karma Police" --limit 3 --json
+scripts/spotify list-playlists --limit 10 --json
+scripts/spotify create-playlist "OpenClaw Mix" --description "Created by OpenClaw" --public --json
+scripts/spotify add-to-playlist "<playlistId>" "spotify:track:..." --json
+scripts/spotify remove-from-playlist "<playlistId>" "spotify:track:..." --json
+scripts/spotify search-and-add "<playlistId>" "Radiohead Karma Police" --json
+scripts/spotify import "/path/to/tracks.txt" --playlist "Imported Mix" --json
+```
+
+`--playlist NAME` creates a new private playlist by default. Use `--playlist-id ID` to update an exact existing playlist.
+
+Current Spotify endpoints used by this skill include `/v1/me/playlists` and `/v1/playlists/{id}/items`; do not use the removed `/tracks` playlist mutation endpoints.
+
+Spotify has no normal delete-playlist Web API operation. Ask before running live smoke tests that create playlists.