@olegkoval/agent-skills 1.35.2 → 1.36.0

package/adapters/claude/olko-creative/skills/music-to-plex/references/no-result-album-fallback.md

@@ -0,0 +1,28 @@
+# Album fallback when `mtp-bot` has no release result
+
+Use this only after the album handler returns an actual no-result outcome and the user has explicitly asked to continue the import. A bot/provider parsing or source-search failure is not a reason to end the job with a status report.
+
+## Fail-closed, track-by-track fallback
+
+1. Resolve an original official release in MusicBrainz. Record its release ID, release year, ordered tracks, and canonical durations.
+2. Prefer separate source audio per track over a single full-album upload. This produces real track boundaries and avoids cumulative timing drift when an upload has missing/extra intro or outro seconds.
+3. For each track, query using artist + track title + album. Accept a source only if:
+   - normalized source title contains the canonical track title;
+   - duration is plausibly close to the canonical duration;
+   - it is not visibly a video, remix, live take, or edit unless that is the canonical track.
+   Search normalization is only a first pass: canonical punctuation and wording often differ (`Parts` vs `Pts`, curly apostrophes, or ellipses). For a missed title, manually compare candidate title and MusicBrainz duration, record the chosen URL as an explicit override in the source manifest, then resume only the missing track — never relax the filter globally.
+4. Resolve the canonical genre from MusicBrainz (or another authoritative release source) before final tagging. Convert, then tag every output with artist, album artist, album, title, release year, **genre**, track number/total, and MusicBrainz release ID. Embed a verified front-cover image in every FLAC. Use that same genre value to build the final Plex library path, so the tag and `Genre/Artist/Album (Year)` folder agree.
+5. Verify the output file opens, has the required tags and embedded art, and is in the final artist/album folder structure before transfer.
+6. Transfer to the NAS Plex root only when the NAS is reachable. Then refresh Plex, inspect the album/track count in Plex/Plexamp, and only then report completion.
+
+## Full-album uploads
+
+Only use a continuous full-album upload if individual tracks are unavailable. Split against a canonical cue/timing sheet, inspect boundaries with silence detection and waveform/listening checks, and do not rely on proportional timestamps alone. A duration mismatch between the upload and the canonical release is a red flag for a different master, gap structure, or intro/outro.
+
+## Communication rule
+
+Do not stop at “the source returned zero results” when the user has asked for the music. State the fallback being launched, make real progress, and distinguish:
+
+- **staged locally** from
+- **transferred to NAS** from
+- **verified visible in Plex/Plexamp**.

package/adapters/claude/olko-creative/skills/music-to-plex/references/per-track-album-art-split.md

@@ -0,0 +1,12 @@
+# Per-track album-art split
+
+Use this when a DJ crate or batch import shows the same cover for every track, but each track actually belongs to a different release.
+
+## Pattern
+- If tracks are from different albums, do not try to force one shared album folder.
+- Split files into one folder per release before Plex refresh.
+- Keep embedded art on each file, but make the folder path match the release so Plex reads the right parent album.
+- Refresh the Plex audio section only after the files are in their final per-album locations.
+
+## Session note
+In the Deep Lineage Set case, the tracks were moved from one staging folder into release-specific folders like `Washing Machine/`, `Altered States/`, and `Tourist/`, then Plex was refreshed. That was the right fix for the "same art for every track" symptom.

package/adapters/claude/olko-creative/skills/music-to-plex/references/plex-playlist-append-and-verify.md

@@ -0,0 +1,18 @@
+# Plex playlist append and verification
+
+Use this when a playlist already exists and needs more items added.
+
+## What worked in this session
+
+- Read the playlist shell first: `GET /playlists/{playlist_id}`.
+- Read the current contents back with: `GET /playlists/{playlist_id}/items`.
+- Append library tracks with: `PUT /playlists/{playlist_id}/items?uri=server://{machineIdentifier}/com.plexapp.plugins.library/library/metadata/{ratingKey}`.
+- For multiple tracks, repeat the `uri` param once per item in the same request or loop one-by-one when order matters.
+- Verify by reading back `leafCount` and the returned `Metadata` item list.
+
+## Pitfalls
+
+- A successful PUT response is not enough. Always confirm the playlist item list changed.
+- If Plex returns a shell with `leafCount: 0`, do not assume creation failed. It may just need item appends.
+- Use the Plex server's `machineIdentifier` from `/identity` when building `server://...` URIs for library items.
+- If a requested track does not move the count, the add may have been a duplicate or the URI may be wrong. Re-read the item list before retrying.

package/adapters/claude/olko-creative/skills/music-to-plex/references/plex-playlist-creation.md

@@ -0,0 +1,21 @@
+# Plex playlist creation from existing library tracks
+
+Session finding:
+- The Plex server accepted playlist creation through the standard library API, not through the app UI.
+- Tracks can be resolved by section search using `type=10`, `title`, and `artist`, then referenced by `ratingKey`.
+- Playlist creation used a `server://<machineIdentifier>/com.plexapp.plugins.library/library/metadata/<comma-separated ratingKeys>` URI.
+
+Working sequence:
+1. Read `/identity` with the Plex token to get `machineIdentifier`.
+2. Search the music section for each track and capture the track `ratingKey`.
+3. POST to `/playlists` with:
+   - `title=<playlist name>`
+   - `type=audio`
+   - `smart=0`
+   - `uri=server://<machineIdentifier>/com.plexapp.plugins.library/library/metadata/<ratingKey1>,<ratingKey2>,...`
+4. Verify by GETting `/playlists/<id>/items` and checking leaf count / order.
+
+Pitfalls:
+- Track search can 400 if you use the wrong query shape. `type=10&title=...&artist=...` worked here.
+- Do not assume `search?query=` works for music tracks.
+- Verify the playlist contents after create, not just the create response.

package/adapters/claude/olko-creative/skills/music-to-plex/references/plex-token-source.md

@@ -0,0 +1,20 @@
+# Plex token source
+
+Session note:
+- Secrets (`PLEX_TOKEN`, `SYNO_USER/PASS`, `RUTRACKER_USER/PASS`, `TELEGRAM_BOT_TOKEN`)
+  live in `~/.config/music-to-plex/.env`, NOT in `config.toml`. `config.toml` holds
+  only non-secret structure (URLs, `music_section_id`, paths).
+- `Config.load()` sources that `.env` automatically (via `load_env()`), so every
+  entrypoint — `mtp`, `mtp-bot`, `mtp doctor` — sees the token without the shell
+  having to `export` anything. If a check says "PLEX_TOKEN not set", the fix is the
+  `.env` file, not the shell env and not `config.toml`.
+- Verify quickly with: `mtp doctor` (look for "PLEX_TOKEN set" and
+  "Plex reachable + token valid").
+- Do not echo the token in chat or logs; use it only for local verification.
+
+If the token is missing from `.env`, fetch it from the NAS Preferences.xml:
+
+    ssh beheerder@192.168.178.245 'grep -oE "PlexOnlineToken=\"[^\"]+" \
+      "/volume1/PlexMediaServer/AppData/Plex Media Server/Preferences.xml"'
+
+then add `PLEX_TOKEN=<value>` to `~/.config/music-to-plex/.env`.

package/adapters/claude/olko-creative/skills/music-to-plex/references/plex-visibility-check.md

@@ -0,0 +1,28 @@
+# Plex visibility check when PlexAmp shows nothing
+
+Use this when the album was supposedly imported, a refresh was triggered, but PlexAmp still returns no results.
+
+## Check order
+
+1. Verify the album is on the NAS in the final Plex-rooted music path, not a staging/download directory.
+2. Verify the final folder name matches the canonical album/artist/year structure that Plex scans.
+3. Refresh Plex *after* the files are in the final path.
+4. Query Plex by track or album title and artist. If search size is 0, Plex has not indexed the content yet.
+5. If the content exists on disk but Plex still sees 0 results, treat it as a path/layout problem first, not a rescan problem.
+
+## Practical rule
+
+A successful refresh is not proof of visibility. The only reliable proof is:
+- audio files exist in the final library path, and
+- Plex search returns matching tracks/albums.
+
+Use Plex's own search endpoint with the album title and at least one track title. If the album appears but tracks do not, the folder landed but indexing is incomplete.
+
+## Failure mode now covered
+
+If Plex search stays at `size=0` after refresh and the scanner later crashes, treat the scanner crash as the root signal. Do not keep retagging or re-refreshing the album until the log or crash report explains why Plex never indexed it.
+
+## Pitfalls from this session
+
+- A root-owned `700` album folder blocked Plex traversal even though the files were present. Fix the directory to `755` before refresh so Plex can traverse it on first scan.
+- An album folder existed on disk under the expected `Various Artists/...` tree, but Plex search still returned `size=0` for title and track queries until the final path was re-verified and refresh was repeated.

package/adapters/claude/olko-creative/skills/music-to-plex/references/practice-crate-playlist.md

@@ -0,0 +1,18 @@
+# DJ practice crate playlist notes
+
+Session lesson:
+- When the user says the playlist is for DJ practice, treat it as a **practice crate**, not a general listening set.
+- Tighten the set by favoring steady, mix-friendly tracks over vibes alone.
+
+Selection heuristics:
+- Keep tracks with stable tempo and phrasing.
+- Prefer long intros/outros, clean drum passages, and predictable transitions.
+- Favor instrumental or sparse-vocal tracks for controller drills.
+- Remove tracks that are too short, too busy, or better as listening-only picks.
+
+Playlist update pattern:
+- If an existing playlist has drifted, **replace/trim** it instead of only appending more tracks.
+- After edits, verify final contents by reading back the Plex playlist items.
+- For bulk adds/removals in Plex, use the playlist items endpoint and confirm the resulting leaf count.
+
+This file is intentionally narrow and session-derived. The umbrella skill should stay class-level; use this reference for the exact practice-crate curation pattern.

package/adapters/claude/olko-creative/skills/music-to-plex/references/session-2026-06-17-synology-probe.md

@@ -0,0 +1,13 @@
+# Session note: Synology probe and mtp-bot mismatch
+
+When `mtp-bot handle "add <album>"` reported `No route to host` against `192.168.178.245:5000`, direct network probes showed the NAS was reachable and the Synology API responded.
+
+Observed checks:
+- `curl http://192.168.178.245:5000/webapi/query.cgi?...` returned `{"success":true}` for `SYNO.API.Auth`.
+- `/usr/bin/python3` socket connect to `192.168.178.245:5000` and `:5001` succeeded.
+- `curl --cookie ~/.config/music-to-plex/cookies.txt https://rutracker.org/forum/dl.php?t=3296838` downloaded the torrent.
+- Direct Synology API calls with `curl` succeeded and `task.cgi?method=create` returned `{"success":true}`.
+- The created task showed up in Download Station as `dbid_806` with status `downloading`.
+
+Takeaway:
+- If the bot path fails but direct curl/API probes succeed, treat it as a bot runtime/context issue and verify the Synology call sequence with curl before changing album selection or torrent handling.

package/adapters/claude/olko-creative/skills/music-to-plex/references/torrent-stall-fallback.md

@@ -0,0 +1,62 @@
+# Torrent Stall & YouTube Fallback Pattern
+
+**Context:** May 2026 session adding "Dexter Gordon — Go" to Plex revealed a reliability pattern in RuTracker sourcing.
+
+## The Pattern
+
+RuTracker torrent searches often succeed (find 5–10 versions), but the selected torrent may:
+- Have low/stalled seeders
+- Stall at 0% or low % for 5+ minutes
+- Eventually timeout or fail silently
+
+Rather than wait indefinitely, the workflow should detect stall within 5 minutes and pivot to YouTube + MP3.
+
+## Dexter Gordon — Go (Case Study)
+
+Search returned multiple FLAC versions:
+- `[SACD-R][OF] Dexter Gordon – Go - 2010` (9 seeds, 1 GB)
+- `[TR24][OF] Dexter Gordon - Go - 1962/2013` (8 seeds, 1 GB)
+- `(Bop, Hard Bop) [CD] Dexter Gordon - Go! - 1962 (1989 Japan Edition), FLAC` (7 seeds, 254 MB) ← often a safe choice: smaller, older, established peers
+- `[CD] Dexter Gordon - GO-RVG Edition - 1962 {1998 Blue Note RVG}` (5 seeds, 307 MB) ← audiophile remaster
+
+**Watch for:** even 7–9 seeds may not mean fast peers. Seed count ≠ reachability.
+
+## 5-Minute Timeout Rationale
+
+- 30 seconds: too aggressive, may give up on legitimate slow starts
+- 5 minutes: Oleg's preference — balances hope vs. pragmatism
+- 10+ minutes: frustrating UX; YouTube is known-good
+
+## YouTube Fallback Quality
+
+When switching to YouTube, the skill currently:
+1. Fetches full album via `yt-dlp`
+2. Extracts audio to `.opus` or `.mp3`
+3. Rewrites ID3 tags (artist, album, genre)
+4. Moves to NAS via SSH
+5. Refreshes Plex
+
+Result: playable album in Plexamp. Quality is typically 128–320 kbps MP3 (YT limits). Not lossless, but reliable and fast.
+
+## Detection & Automation (current behavior — June 2026)
+
+This is now **automated and interactive**. The background notifier
+(`mtp-notify`) polls `mtp status <task_id>` every 30s. If percent-done stays
+flat for the stuck window (default 10 min; `stuck_timeout` in the chat-state
+blob), it flips the chat to the `STUCK` state and posts a message with **four
+numbered options** — it does NOT auto-pivot to YouTube:
+
+```
+1️⃣ Wait 1 more hour
+2️⃣ Wait N hours (asks how many)
+3️⃣ Try the next release in the list   ← deletes stuck task, auto-picks next by seeds
+4️⃣ Grab it from YouTube in highest quality
+```
+
+The user's reply (`1`–`4`, a count of hours, or "next"/"youtube") is passed
+verbatim to `mtp-bot handle`, which routes it through the `STUCK` /
+`STUCK_WAIT_INPUT` handlers in `mtp/bot/machine.py`. Option 4 returns the
+`__YOUTUBE_FALLBACK__` signal that hands the YouTube acquisition to Hermes.
+
+Operator choice is preserved by design — the user decides per-stall, rather than
+the tool silently switching sources.

package/adapters/claude/olko-creative/skills/music-to-plex/references/verification-and-pitfalls.md

@@ -0,0 +1,17 @@
+# Verification and pitfalls
+
+Session takeaway:
+- The bot can print a successful download-start message even if the follow-up notification step fails.
+- In this case, the started download later showed a local album folder at `/Volumes/home/downloads/Fear Of The Dark` containing the FLAC tracks.
+- `mtp-notify` originally failed with `album required` because the bot passed `task_id` + `chat_id` and the notifier expected full metadata. The durable fix was to resolve `artist` and `album` from `~/.config/music-to-plex/bot-state.db` when they are omitted.
+- The downloaded FLAC also had a bad `genre` tag (`Pop`), which can misroute the album during organize. Verify tags before moving anything into the Plex library.
+
+Verification pattern:
+1. Treat the bot's "Downloading ..." output as a start signal, not proof of completion.
+2. Check the configured mount download directory for the album folder.
+3. Confirm actual audio files exist inside the folder before telling the user the album is ready.
+4. If the notification helper errors, report that separately from download state.
+5. If tags look wrong, fix or override them before organize, otherwise Plex refresh will not correct the folder placement.
+
+Known local path from this session:
+- `/Volumes/home/downloads/Fear Of The Dark`

package/adapters/claude/olko-creative/skills/music-to-plex/references/youtube-403-fallbacks.md

@@ -0,0 +1,17 @@
+# YouTube download fallback for music-to-plex
+
+When a track rip fails with `HTTP Error 403: Forbidden` or `unable to download video data`, retry `yt-dlp` with a different YouTube client before abandoning the source.
+
+## Proven retry order
+
+1. Standard extraction.
+2. Retry the same verified URL with `--extractor-args 'youtube:player_client=android'`.
+3. If it still fails, use the next **already verified** candidate from the album source manifest (same canonical title and duration). Do not restart or discard the successfully staged tracks.
+4. If no verified alternative remains, leave only that track unresolved and report the exact gap; do not fill it with an unverified remix, live take, or unrelated upload.
+
+## Practical notes
+
+- The Android client can surface working media URLs when the default client gets blocked.
+- This is a retry pattern, not a guarantee. If it still 403s, stop burning time on the same URL.
+- Keep the exact album folder and cover placement workflow separate from track acquisition. Cover art can usually be finalized even when the rip path is blocked.
+- When the final import succeeds, remember to verify the NAS folder permissions too. A `700` directory owned by root can make Plex ignore the album even though the files download cleanly.

package/adapters/claude/olko-creative/skills/music-to-plex/references/youtube-full-album-fallback.md

@@ -0,0 +1,34 @@
+# YouTube full-album fallback salvage
+
+Use this when RuTracker / Download Station fails and the only practical source is a YouTube full-album upload.
+
+## Pattern observed
+
+- `yt-dlp` can pull a clean album source, but uploader metadata is often garbage.
+- Treat the first download as a source artifact, not Plex-ready media.
+- Validate tags with `ffprobe` or `mutagen` before any organize step.
+
+## Repair flow
+
+1. Download the upload at highest audio quality.
+2. Inspect embedded metadata immediately.
+3. If the output is one long FLAC, split it into tracks using album track timings.
+4. Retag each track with canonical artist, album, year, tracknumber, and tracktotal.
+5. Embed official cover art, not the YouTube thumbnail.
+6. Move the repaired album into the final NAS music path.
+7. Refresh Plex only after the final path exists.
+8. Verify the album appears in Plex search.
+
+## NAS transfer workaround
+
+When `rsync` or `scp` fights remote path quoting, use a tar pipe instead:
+
+```bash
+cd /local/staging && tar -cf - *.flac | ssh user@nas 'cd "/volume1/music/.../Release" && tar -xf -'
+```
+
+If macOS leaves AppleDouble sidecar files on the NAS, remove `._*` before refresh.
+
+## Session note
+
+For `Ozzy Osbourne - Diary Of A Madman (1981)`, the fallback source was a YouTube full-album upload. The tracks were downloaded to FLAC, retagged, cover art embedded, copied into `/volume1/music/metal/Ozzy Osbourne/Diary Of A Madman (1981)`, AppleDouble files removed, and Plex refreshed with `mtp refresh --path`.

package/adapters/claude/olko-creative/skills/music-to-plex/references/youtube-lineage-playlist-fallback.md

@@ -0,0 +1,33 @@
+# YouTube-only lineage playlist fallback
+
+Use when the user wants a new DJ crate or playlist based on mood/lineage rather than a formal release request, and the intended path is YouTube track finding/downloading only.
+
+## Trigger
+
+- The user says things like "check this message and create new playlist" and provides lane/feeling language instead of a single album.
+- The brief is built from references, influences, or lineage tags such as "classic deep house DNA", "modern disco/deep house revival", "jazzy/warm cuts", or a left-field closer.
+- The task is explicitly on the YouTube branch, not a tracker or store purchase flow.
+
+## Pattern
+
+1. Convert the message into a small set of lanes first.
+2. Pick 1-3 anchor artists or canonical tracks per lane.
+3. Search exact titles with `yt-dlp`/YouTube query strings before broadening the search.
+4. Prefer official or Topic uploads, then the cleanest stable upload with the closest duration and metadata match.
+5. Assemble a local crate manifest, tracklist, and playlist file.
+6. Verify the files exist and the playlist content matches the intended lane order.
+
+## Curation notes
+
+- Keep the middle of the set mix-friendly.
+- Use the final lane for the emotional curveball or taste-flex closer.
+- If the user explicitly says the branch is YouTube-only, do not route through tracker/search paths for acquisition.
+- If Spotify or another catalog route is unavailable, skip it and continue with the YouTube branch instead of stalling.
+
+## File outputs
+
+- `00_MANIFEST.json`
+- `00_TRACKLIST.md`
+- `00_PLAYLIST.m3u8`
+
+This reference is session-derived but the pattern is reusable for future YouTube-only crate builds.

package/adapters/claude/olko-creative/skills/music-to-plex/references/youtube-playlist-import.md

@@ -0,0 +1,50 @@
+# YouTube-first playlist import for MTP
+
+Use this flow when the user gives a YouTube playlist URL or a plain track list and wants it landed in Plex.
+
+## Input shapes
+- Playlist URL
+- Plain list of `Artist - Title` lines
+
+If only a track list is provided, resolve each track on YouTube first, then download in album/sequence order.
+
+## Download + staging
+Use max-quality audio extraction and preserve ordering with explicit numbering:
+
+```bash
+yt-dlp -x --audio-format flac --audio-quality 0 \
+  --write-thumbnail --convert-thumbnails jpg --embed-thumbnail \
+  --add-metadata \
+  -o "/tmp/mtp_youtube_crates/<crate>/work/raw/%(playlist_index)02d - %(title)s.%(ext)s" \
+  "<youtube-url>"
+```
+
+Notes:
+- Keep a manifest with index, source URL, resolved artist/title, and final filename.
+- For VA / DJ-style sets, keep track order stable even if metadata is messy.
+- If a title needs cleanup, fix it in tags, not by renaming out of sequence.
+
+## Import into Plex
+- Copy the finalized files into the NAS import path that Plex scans for the music section.
+- Trigger a library scan after the copy.
+- Create a normal Plex playlist from the imported track rating keys in the exact source order.
+
+## Verification
+Prefer proof over assumptions:
+- Check Plex scanner logs for `Added new metadata item` / `Loaded metadata for ...` on each track.
+- Confirm the imported track by querying Plex search directly and inspecting the returned `ratingKey`, `title`, `originalTitle`, and `parentTitle`.
+- For playlist verification, read the playlist back and enumerate items in order.
+
+## Plex metadata quirks
+- For compilation-style sets, Plex often shows `grandparentTitle=Various Artists`.
+- The displayed `title` may be the track title, while `originalTitle` carries the artist.
+- Search by both artist and title when matching imported tracks.
+- If a search query misses a track, try the cleaned title and artist separately.
+
+## Session-proven pattern
+The Deep Lineage Set import worked by:
+1. staging 8 FLAC tracks from YouTube,
+2. copying the final files into a Plex-scanned NAS import directory,
+3. refreshing Plex,
+4. creating a playlist in the source order,
+5. verifying all 8 items and their order.

package/adapters/claude/olko-creative/skills/music-to-plex/references/youtube-track-resolution-heuristics.md

@@ -0,0 +1,23 @@
+# YouTube track resolution heuristics
+
+Use this when a user gives a plain `Artist - Title` list and wants it turned into a Plex playlist.
+
+## Search pattern
+- Run `yt-dlp --flat-playlist --dump-json "ytsearch5:<artist> <title>"` for each line.
+- Keep the source order from the user list. Never reorder by search result rank.
+
+## Scoring
+Prefer results with:
+1. exact title match,
+2. artist match in the channel/uploader name,
+3. `Topic` channel or official upload,
+4. clean metadata over remix/edit clutter.
+
+## Pitfalls
+- The first search hit is often wrong for house/disco catalog cuts.
+- If the user only gives a vibe list and not a playlist name, derive a short title from the theme, then ask once before creating the Plex playlist.
+- For compilation-style uploads, check both title and channel before deciding.
+
+## Verification
+- After download, confirm each track title still maps to the intended line.
+- When building the Plex playlist, read it back and verify item order matches the source list.

package/adapters/claude/olko-creative/skills/music-to-plex/references/zero-track-playlist-recovery.md

@@ -0,0 +1,21 @@
+# Zero-track playlist recovery
+
+Use this when Plex shows a playlist shell but the track list is empty or `0 tracks`.
+
+## What it means
+
+- The playlist object exists.
+- The import likely failed to attach playable items, or the items have not been indexed yet.
+- Do not treat the playlist as done until Plex returns leaf items.
+
+## Recovery order
+
+1. Read back the playlist with `GET /playlists/<id>/items`.
+2. Confirm the returned leaf count matches the source track count.
+3. Compare the returned order with the intended playlist order.
+4. If the playlist is still empty, re-check the source track `ratingKey` list before trying another create.
+5. If the UI says `0 tracks` but the API returns items, trust the API and let PlexAmp refresh.
+
+## Rule
+
+A playlist is only imported when the API read-back shows the expected number of items and order. The UI tile alone is not proof.

package/adapters/codex/olko-creative/README.md

@@ -6,5 +6,6 @@ Use the canonical skills directly:
 
 - `plugins/olko-creative/skills/gallery/SKILL.md`
 - `plugins/olko-creative/skills/fill-music-player/SKILL.md`
+- `plugins/olko-creative/skills/music-to-plex/SKILL.md`
 - `plugins/olko-creative/skills/vinted-listing/SKILL.md`
 - `plugins/olko-creative/skills/wikipedia-uk-editor/SKILL.md`