@olegkoval/agent-skills 1.35.2 → 1.36.0

package/plugins/olko-creative/skills/music-to-plex/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: music-to-plex
+description: "Acquire music and make it playable in Plex/Plexamp — single albums (via mtp-bot), DJ tracklists/crates, and YouTube playlists. Use ONLY when the user explicitly wants to ADD or DOWNLOAD music to Plex (e.g. 'add to Plex', 'get me this album', 'download this playlist', a timestamped DJ tracklist, or a plain 'Artist - Title' list). NOT for podcasts or non-music; for albums already on disk that won't show up, bulk library repair, or Plex scanner/DB problems, hand off to plex-music-ingest."
+version: 3.0.0
+platforms: [macos, linux]
+metadata:
+  hermes:
+    tags: [music, plex, flac, nas, synology, album, playlist, plexamp]
+    related_skills: [plex-music-ingest, music-library-publishing, music-note-curation, podcast-monitoring]
+---
+
+# Music to Plex
+
+Acquire music and surface it in Plex/Plexamp. Three flows: **album** (one-shot
+via `mtp-bot`), **DJ tracklist/crate**, and **YouTube playlist**. Pick the flow,
+run it, verify, post notes.
+
+## Operating rules (non-negotiable)
+
+- **One command per album.** For a single album/release, call `mtp-bot handle`
+  once and post its output. Do **not** run `mtp search`/`add`/`status` yourself,
+  do **not** pick a version (auto-pick is automatic), do **not** poll for
+  download status (the notifier streams it).
+- **Serialize multi-album imports.** `mtp-bot` keeps a state machine per chat;
+  never dispatch album handler calls in parallel. Send one request, inspect its
+  reply, and proceed only after it has accepted the release or returned to idle.
+  If it opens a numbered picker, stop the batch and preserve that picker until
+  its owner chooses or explicitly authorizes cancellation. Do not send a bare
+  number, `cancel`, or a new request into an existing picker on behalf of a
+  different request. **Exception:** when the user explicitly says to ignore or
+  override an active download and names the replacement, treat that as direct
+  cancellation authority: dispatch the resolved replacement once, without a
+  redundant confirmation loop, and state that the earlier job may be abandoned.
+- **Route by shape.** Album → `mtp-bot handle`. DJ tracklist/crate → the crate
+  ingest reference. YouTube playlist or plain track list → the YouTube flow.
+  Never pass a crate or multi-track prose to `mtp-bot handle` (album-shaped
+  parser; it will reply `⏭️ Not a music album request — skipped.`).
+- **Cover-art requests need resolution before dispatch.** A bare `mtp` with an
+  album image is an explicit album request, but `mtp` alone is not handler-ready.
+  Transcribe/identify the cover, verify the canonical release and track count,
+  then proceed through the resolved-image continuation. Never expect the album
+  parser to infer a title from an image caption. When invoking `mtp-bot`, use the
+  **originating Telegram chat ID** from the inbound route; a group ID, user ID,
+  and configured home-chat ID are different things.
+- **Never claim done without verification.** A "Downloading…" or a successful Plex refresh is a *start* signal, not proof. The album is done only when the files exist under the configured Plex library path **and** are visible in Plexamp. Read back playlist items before saying a playlist is updated.
+- **Show the user the checklist.** For every album ingest, post/update this exact evidence-led checklist in order. Mark `✅` only after tool evidence; use `⏳` while active, `⚠️` for a verified blocker, and never silently omit a step:
+  ```text
+  ⏳ Canonical release metadata / tracklist verified
+  ⏳ Audio acquired and locally staged
+  ⏳ Track count, tags, embedded art, and file integrity verified
+  ⏳ NAS artist-path and write-permission preflight verified
+  ⏳ Files copied to the final Plex-scanned NAS folder
+  ⏳ NAS count/art/folder traversal verified; transfer sidecars cleaned
+  ⏳ Plex refresh triggered and album + full track count read back from Plex
+  ⏳ Obsidian note written: Artist note → Album note → DJ summary
+  ```
+  The final response must retain this checklist with concrete proof values (final path, counts, Plex result, and note path). If a fallback bypasses the normal handler, say so explicitly and still keep the checklist.
+- **Never fabricate facts.** In DJ notes, if unsure of a musician/label/year, say less. Do not invent files, APIs, env vars, or NAS paths.
+- **Obsidian note voice and substance.** Notes must use the full enrichment standard in `references/music-note-blurb-order.md`: original WFMU / LDBK / Radio Brussels / classic-underground-radio energy, vivid sensory language, and juicy source-backed facts that make listeners curious and emotionally engaged. Include verified recording/release context, label/year, collaborators/producers, samples or scene links, unusual backstory, cultural impact, and concrete listening cues when available. Never imitate a named presenter, write generic promo copy, or pad the note with unsourced trivia. Run the replaceability test before saving: if the note would mostly work after swapping the album name, rewrite it.
+- **Obsidian vault path.** Write music notes to `/Users/olegkoval/Documents/opus/Music/`, the visible Music folder used by the existing notes (not `Documents/opus/Obsidian/Hermes/Music/`). Verify the exact note path by reading it back after writing.
+- **Secrets live in `~/.config/music-to-plex/.env`** (loaded automatically by
+  `Config.load`), never in `config.toml`. If a check says "PLEX_TOKEN not set",
+  fix the `.env`. See `references/plex-token-source.md`.
+- **Hand off repair.** Album on disk but not visible, wrong folder/tags after
+  the fact, bulk library cleanup, permission problems, or Plex scanner/DB
+  crashes → this is **plex-music-ingest**'s job, not this skill's.
+
+## One-shot album flow
+
+The user posts once ("add <album>") and gets a status stream back. The mechanics
+(auto-pick best version, download, organize, Plex refresh, staged status
+messages) are handled by the tool chain. **Your only creative job is the DJ
+blurb.**
+
+### Step 1 — Run the handler once
+
+```bash
+mtp-bot handle "<exact user message>" --chat <chat_id>
+```
+
+`<exact user message>` = what the user said; `<chat_id>` = the Telegram chat ID.
+This auto-picks the highest-seed release, starts the download, and spawns a
+background notifier. It returns:
+
+```
+✅ Accepted: <Artist> — <Album>
+⏳ Downloading [FORMAT] SIZE, N seeds — status updates to follow.
+```
+
+Post that result as-is.
+
+### Step 2 — Write the notes in strict order
+
+Immediately after posting "Accepted", while the download runs in the background,
+write one enrichment package, in this order:
+
+1. **Artist note** — a specific, substantial paragraph in the original WFMU / LDBK / Radio Brussels / classic-underground-radio lane: the artist's broader sound, history, scene, collaborators, and lane. Include at least one verified fact that gives the listener a reason to care.
+2. **Album note** — a separate, juicy paragraph: year, label, recording/release context, key players, unusual backstory, samples or scene connections, cultural impact, and two or three concrete things to listen for. Use only facts verified from authoritative sources; turn them into a human invitation rather than a database dump.
+3. Optional one-line DJ summary or recommendation — tactile, specific, curious, and emotionally inviting.
+
+Keep artist note first and album note second — never merge them into one generic promo paragraph. Sound like a great late-night radio host with a crate-digger’s memory, not a press release or a Wikipedia entry. See
+`references/music-note-blurb-order.md`. Optional extras: 🎵 YouTube link,
+`🎶 You might also like:` + 2 short recommendations.
+
+### Step 3 — Let the notifier stream the rest
+
+The background notifier posts these on its own — **do not poll or re-run**:
+
+```
+📥 Downloaded → 📂 Moving to library folder → 🔄 Rescanning Plex → ✅ Ready in Plexamp
+```
+
+After "Ready", mirror the notes into the canonical visible Music vault at
+`/Users/olegkoval/Documents/opus/Music/` as a music note for that release
+(append if it exists), artist note above album note, followed by DJ summary and
+source links. Read the exact file back before reporting the note complete. If
+the user asked for album art, save the release image as `cover.jpg` in the
+artist/release folder and verify it exists. See
+`references/cover-art-sourcing-session.md`.
+
+### Step 4 — Follow-up replies (stuck downloads)
+
+If a download stalls, the notifier posts a "stuck" message with 4 numbered
+options (wait 1h / wait N hours / next release / YouTube). When the user replies
+— a bare number `1`–`4`, a count of hours, or "next" / "youtube" — **pass the
+reply verbatim to `mtp-bot handle`**, exactly like an add request. Post whatever
+it returns.
+
+**YouTube handoff:** if `mtp-bot handle` returns a line starting with
+`__YOUTUBE_FALLBACK__`, strip it and run the YouTube flow yourself (download
+highest-quality audio with `yt-dlp`, fix tags, move into the library, refresh
+Plex), then post the blurb. If `rsync` or `scp` is unsuitable for a release transfer, use the verified tar-over-SSH fallback, remove any macOS AppleDouble sidecars, and compare NAS/Plex track counts with canonical metadata. See `references/manual-fallback-transfer-and-plex-verification.md`, `references/youtube-403-fallbacks.md`, and `references/youtube-full-album-fallback.md`.
+
+**No-result continuation:** if the bot returns an actual no-results outcome and
+the user asks to continue, do not stop at a blocker report. Resolve canonical
+MusicBrainz metadata, then run the fail-closed track-by-track YouTube fallback:
+match each track by normalized title and duration, reject videos/remixes/live
+versions unless canonical, tag and cover-embed every file, stage it, transfer,
+and verify in Plex. A file's existence is not evidence it completed: fully decode
+all staged files and compare each actual duration to canonical metadata before
+NAS transfer; re-tag the full set after any interrupted run. Prefer separately
+sourced tracks over slicing a continuous full-album upload; only split a full
+upload using validated cues and boundary checks. Clearly distinguish local
+staging, NAS transfer, and Plex visibility. See
+`references/no-result-album-fallback.md` and
+`references/fallback-audio-validation-and-nas-preflight.md`.
+
+### Manual-fallback NAS preflight
+
+Resolve the canonical release first, then preflight the exact NAS destination
+**in parallel with source selection and before substantial fallback downloading**.
+Inspect the NAS layout and an existing album by the same artist. `nas_music` is a
+storage root, not proof that a new artist directory is inside the Plex-scanned
+library. Confirm the originating transfer account can write and traverse the
+exact final parent; if a new artist directory is required, confirm it can create
+that directory too. If the parent is root-owned or read-only, do not spend the
+whole fallback download hoping the copy will work and do not invent an alternate
+writable folder. Keep any already-staged release local and request an
+album-scoped permission repair from the NAS owner.
+
+**Durable access repair:** when the user explicitly wants future managed imports
+to work, repair the *Plex library root* (for this setup,
+`/volume1/music/library`) rather than recursively changing ownership of the
+whole `/volume1/music` share. A safe target is managed-account ownership and
+library-root group write (for example `beheerder:users`, `775`), then verify by
+creating and removing a uniquely named probe directory over SSH. New artist and
+album parents must still be Plex-traversable (`755`); an artist directory left
+at `770` can block scanner traversal even when the release directory and FLACs
+are readable. Never widen ownership/permissions above the Plex library root
+without explicit user approval. See
+`references/nas-library-layout-and-write-preflight.md`,
+`references/fallback-audio-validation-and-nas-preflight.md`, and
+`references/nas-permissions-and-plex-traversal.md`.
+
+## DJ tracklist / crate flow
+
+A timestamped DJ set or a themed crate brief is **not** an album request. Parse
+the list, find lawful sources, acquire audio when allowed, fix metadata/artwork,
+store a separate DJ-friendly folder on NAS, and create/refresh a Plex playlist.
+Creation is incomplete until Plex shows a visible playlist **and** the crate has
+proper cover art. If the user says the set is for DJ practice, treat it as a
+**practice crate**: rebuild/trim for mixability, don't just append tracks. Full
+procedure: `references/dj-tracklist-crate-ingest.md`.
+
+## YouTube playlist flow
+
+Use when the user wants a YouTube playlist (not a timestamped DJ set, not a
+single album) turned into a normal Plex listening playlist. Two inputs: a
+ready-made playlist URL, or a plain list of `Artist - Title` lines. Do not route
+through `mtp-bot handle` or the crate flow. Full download/tagging/placement/
+verification steps: `references/youtube-playlist-import.md`.
+
+## Verification pitfalls (hard-won)
+
+- **File exists ≠ visible.** After refresh, if Plexamp shows nothing, re-verify
+  the album landed under the configured Plex-rooted library path (not a staging/
+  download dir or a bucket Plex doesn't scan). See `references/plex-visibility-check.md`.
+- **Permissions.** Root-owned `700` directories are invisible to Plex traversal
+  even if the audio is readable. Verify the final folder is traversable and fix
+  to `755` before every refresh.
+- **Refresh verb.** On this Plex install, `/library/sections/{id}/refresh` must
+  be **GET**; PUT returns 404, and a targeted `path=` refresh may also 404 - fall
+  back to a plain section refresh. Refresh only after files are in their final
+  NAS path; refresh again after any later tag/rename change.
+- **Targeted refresh exists in the CLI.** `mtp refresh --path <final NAS path>`
+  is the preferred completion check when the release lands cleanly. Treat
+  `{"refreshed": true, "section_id": ...}` as a real success signal.
+
+- **Target layout beats generic configuration.** Before creating a genre bucket, inspect where Plex stores an existing album from the same artist and confirm the transfer account can write that parent. Do not redirect a release to an unrelated writable folder or `unsorted` solely to make the copy succeed; repair access to the canonical target instead. See `references/nas-library-layout-and-write-preflight.md`.
+- **Corrupt source ≠ Plex problem.** If a chapter-based rip yields a zero-byte or
+  corrupt final track, switch source first, then tag and move — don't just
+  re-refresh. See `references/malformed-flac-fallbacks.md`.
+- **NAS codec tools may be unavailable.** Some NAS images ship neither `ffprobe`
+  nor an AAC decoder in `ffmpeg`. In that case, fully decode each staged source
+  locally before transfer, then use NAS file count/art/sidecar/traversal checks
+  plus Plex’s album-and-track read-back as the remote verification receipt. Do
+  not describe a remote decode as passed when the NAS tool cannot decode it.
+- **Duplicate torrent.** On Synology `Duplicate torrent file`, do not retry
+  blindly — `list_tasks` first; repeated attempts stack failed tasks. Clean stale
+  tasks, then re-search with plain artist/album text (no magnet URLs in replies).
+  See `references/duplicate-torrent-handling.md`.
+- **Image/typo identification.** If the user sends cover art or a misspelled/clip
+  title (`Single`, `Official clip`, `teaser`), use it as a *clue* — confirm the
+  real release name and track count on the store/release page before importing.
+  See `references/image-driven-identification-and-verification.md` and
+  `references/bandcamp-album-identification.md`.
+- **Lesson (scanner health):** when an album repeatedly "won't ingest" after the
+  files are correctly placed, stop re-moving files. The cause is usually scanner/
+  DB state, not placement — a direct scanner probe can crash with `DB::Exception`
+  while a plain refresh succeeds. At that point the album is a **plex-music-ingest**
+  case: check scanner health, DB state, and crash cause before touching tags again.
+  (Real example: an album sat correctly at `/volume1/music/Various Artists/…`
+  yet stayed invisible; extra nested `library/pop` layers never helped.)
+
+## References
+
+- Notes & enrichment: `music-note-blurb-order.md`, `cover-art-sourcing-session.md`
+- Album ID & verification: `image-driven-identification-and-verification.md`,
+  `gear-change-image-identification.md`, `bandcamp-album-identification.md`,
+  `plex-visibility-check.md`, `verification-and-pitfalls.md`
+- DJ crates: `dj-tracklist-crate-ingest.md`, `cover-art-repair-session.md`,
+  `per-track-album-art-split.md`, `youtube-lineage-playlist-fallback.md`
+- YouTube: `youtube-playlist-import.md`, `youtube-403-fallbacks.md`,
+  `youtube-full-album-fallback.md`, `fallback-audio-validation-and-nas-preflight.md`
+- Playlists: `plex-playlist-creation.md`, `plex-playlist-append-and-verify.md`,
+  `zero-track-playlist-recovery.md`
+- Plex/NAS plumbing: `plex-token-source.md`, `nas-routing-and-refresh.md`,
+  `batch-import-staging.md`, `mtp-subprocess-wrapper.md`,
+  `mtp-bot-bulk-state-safety.md`, `session-2026-06-17-synology-probe.md`
+- Repair/forensics (mostly owned by **plex-music-ingest**):
+  `library-repair-folders.md`, `canonical-artist-normalization.md`,
+  `cover-art-and-plexamp.md`
+
+That is the skill. Pick the flow, run it, verify, post notes. Silence if no output.

package/plugins/olko-creative/skills/music-to-plex/references/bandcamp-album-identification.md

@@ -0,0 +1,29 @@
+# Bandcamp album identification when OCR/YouTube points at a single
+
+Use this when cover art or a clip title points to a song, but the user actually wants the full release.
+
+## Pattern from this session
+
+- Cover art text said `74 Miles Away - Gear Change`.
+- A YouTube clip title looked like a single: `74 Miles Away - Gear Change // Single`.
+- The Bandcamp release page was the source of truth:
+  - `https://74milesaway.bandcamp.com/album/gear-change`
+  - page title: `Gear Change | 74 Miles Away`
+  - tracklist: 8 tracks
+  - release date: `2013-05-16`
+- `yt-dlp -J` on the Bandcamp album URL exposed the album metadata directly:
+  - `playlist_title = Gear Change`
+  - `playlist_count = 8`
+  - `album = Gear Change`
+  - `album_artist = 74 Miles Away`
+
+## Practical rule
+
+If the clip title includes `Single`, `Official clip`, or another video-oriented label, do not treat it as the final release name. Check the Bandcamp album page (or equivalent store page) for the actual album title and track count before importing.
+
+## Verification
+
+- Prefer the album page over a clip title.
+- Use `yt-dlp -J <album-url>` to confirm the release title and track list.
+- Import the full album folder, not the clip single, before refreshing Plex.
+- Verify the album in Plex by searching the music section for the album title after refresh.

package/plugins/olko-creative/skills/music-to-plex/references/batch-import-staging.md

@@ -0,0 +1,23 @@
+# Batch import staging and source validation
+
+Use this pattern when importing multiple albums from downloaded source material into Plex.
+
+## Stage-first workflow
+
+1. Stage each album in a temp tree before touching the NAS library path.
+2. After staging, push the staged tree into the final NAS location in one shot.
+3. Normalize final permissions before refresh:
+   - album directories: `755`
+   - audio files and art: `644`
+4. Refresh Plex only after the final path and permissions are correct.
+5. Verify Plex search for album and at least one track after refresh.
+
+## Source validation for YouTube rips
+
+- Prefer a source with reliable chapter metadata when the album is chapter-based.
+- If the first candidate download produces a bad last track or an invalid MP3, do not keep tagging it. Treat that as a source problem and try an alternate full-album upload instead.
+- Sanity-check extracted audio before tagging or moving it into the library. A quick `ffprobe` or `file` pass on each MP3 is enough to catch a corrupt final track.
+
+## Practical fallback
+
+If the local machine cannot write to the NAS library path directly, keep the staging tree local and stream it to the NAS over SSH, then run the permission normalization and Plex refresh remotely.

package/plugins/olko-creative/skills/music-to-plex/references/canonical-artist-normalization.md

@@ -0,0 +1,24 @@
+# Canonical artist normalization
+
+Session note for bulk metadata repair and folder convergence.
+
+## Rule
+When multiple artist spellings refer to one real artist, normalize them to a single canonical display name before writing tags or deciding folder placement.
+
+Example from this session:
+- Canonical display name: `Godspeed You! Black Emperor`
+- Collapsed variants included punctuation/no-punctuation spellings such as `godspeedyoublackemperor`, `Godspeed You Black Emperor!`, and `Godspeed You! Black Emperor`
+
+## Practical pattern
+- Normalize artist strings by stripping non-alphanumerics for lookup.
+- Apply the canonical mapping in two places:
+  - when choosing the dominant artist for a directory or album batch
+  - when comparing existing tags before deciding whether to rewrite them
+- If the normalized value differs from the current tag, treat it as drift and rewrite the tag so the library converges.
+
+## Why this matters
+- Plex can surface the same artist multiple times when tags disagree on punctuation or spacing.
+- Folder names and tags need to converge on the same canonical form or future refreshes keep re-splitting the library.
+
+## Implementation note
+If the normalizer is generated inside an outer f-string, escape literal braces in embedded dicts with `{{ ... }}` so the generator does not try to interpret the mapping as formatting syntax.

package/plugins/olko-creative/skills/music-to-plex/references/cover-art-and-plexamp.md

@@ -0,0 +1,22 @@
+# Cover art and PlexAmp visibility
+
+Session note: when a music release is imported from a chapter-split source or a plain audio rip, the album may index in Plex with no artwork because there is no local cover image and Plex cannot reliably match the release online.
+
+## Practical rule
+
+If PlexAmp shows the album but the tile is blank or generic:
+1. Check the final album folder for a local image first (`cover.jpg`, `folder.jpg`, `front.jpg`, or `*.png`).
+2. If none exists, fetch the real release art from Discogs or another authoritative release listing and place it in the album folder as `cover.jpg`.
+3. Prefer the exact release art over YouTube thumbnails, generic web images, or a random match.
+4. Refresh the Plex music section again after the art file is in place.
+5. Prefer folder art for compilation releases and niche albums that Plex metadata matching may not recognize.
+
+## Useful note
+
+A clean import can still be missing art. That is not the same failure as library ingest. Treat artwork as a separate visibility layer from track indexing.
+
+## Discogs workflow
+
+- Search Discogs by the exact album title and year.
+- Open the release page or API record, then use the release image for the final folder art.
+- Verify the art file on disk after copy, then refresh Plex and re-check PlexAmp.

package/plugins/olko-creative/skills/music-to-plex/references/cover-art-repair-session.md

@@ -0,0 +1,34 @@
+# Embedded cover-art repair session notes
+
+Use this when a DJ crate or playlist already exists on the NAS and Plexamp shows the gray "no album art" thumbnail on every track.
+
+## What worked
+
+- The set was `Deep Lineage Set` and the source folder was:
+  `/volume1/video/plex-imports/deep-lineage-set`
+- The tracklist came from a screenshot, so the first pass was image-assisted identification of the set name and sequence.
+- The fixed files were FLACs, so `mutagen.flac.FLAC` was enough to rewrite embedded artwork in place.
+- Each file ended up with exactly one embedded picture after the rewrite.
+- Plex was refreshed with `GET /library/sections/{id}/refresh` on the NAS, not a UI click.
+
+## Practical pattern
+
+1. Identify the exact release for each track before writing tags.
+2. Pull the release art from Cover Art Archive or another authoritative source.
+3. Rewrite embedded art in the track files themselves.
+4. Verify the resulting files have `1` picture each.
+5. Refresh Plex only after the files are in final NAS path.
+
+## Pitfalls
+
+- Folder-level artwork is not enough if the tracks themselves have missing embedded art and Plexamp is reading track thumbnails.
+- Do not assume the Spotify-looking playlist title is the actual release title. Screenshot tracklists often mix track names, artists, and playlist labels.
+- When a release has similarly named variants, resolve by artist + release group, not title alone.
+
+## Verification
+
+Check both:
+- file-level art count in each FLAC/MP3
+- Plex refresh on the target section
+
+If both are true, the playlist should render with original cover art in Plexamp.

package/plugins/olko-creative/skills/music-to-plex/references/cover-art-sourcing-session.md

@@ -0,0 +1,23 @@
+# Cover art sourcing session note
+
+Use this when the user wants music notes plus actual album art, not just text notes.
+
+## Pattern that worked
+- Create the release note as usual, but do not stop there.
+- Find a reliable source image for the release cover.
+- Prefer an image URL already exposed by the page's image inventory over scraping HTML manually.
+- If Bandcamp page image is available, use that for direct art.
+- If Bandcamp does not expose the needed cover clearly, fall back to a verified artwork image from Wikipedia or another canonical release page.
+- Save the image locally as `cover.jpg` in the artist or release folder.
+- Verify with a filesystem search, not by assuming the download worked.
+
+## Session outcome
+- Fred Everything - Mercyless: cover saved as `cover.jpg` in the artist folder.
+- Ron Trent - Altered States: cover saved as `cover.jpg`.
+- Chez Damier & Ron Trent, M.D. - Hip To Be Disillusioned Vol. 1: cover saved as `cover.jpg`.
+- St Germain - Tourist: cover saved as `cover.jpg`.
+- Larry Heard - Can You Feel It: cover saved as `cover.jpg`.
+
+## Pitfall
+- Do not answer with notes-only completion if the user asked for album art. That is partial work.
+- Treat art placement as part of the deliverable for music-library curation.

package/plugins/olko-creative/skills/music-to-plex/references/dj-tracklist-crate-ingest.md

@@ -0,0 +1,184 @@
+# DJ tracklist crate ingest to NAS + Plex
+
+Use when the user posts a timestamped DJ set tracklist and wants it turned into a DJ-usable folder and Plex/Plexamp listening playlist.
+
+## Scope and legality
+
+- Prefer legal/owned sources: Bandcamp, Qobuz, Beatport, Juno Download, artist/label stores, existing NAS library, or user-provided files.
+- YouTube is allowed only for lawful sources: official uploads, artist/label uploads, Creative Commons, public-domain material, or user-confirmed personal-use fallback where local law/account terms permit it.
+- Do not present piracy as the default path. If a track is commercially available, prefer purchase/store source over a random YouTube rip.
+- If source rights are unclear, stage it as `needs_source_confirmation` and ask before download.
+
+## Input format
+
+Accept lines like:
+
+```text
+00:00 Intro - Marc Bianco
+02:30 Ghetto Opera (Loft Mix) - Nicholas featuring Nikki-O
+1:19:17 Under The Sun - Fred Everything
+```
+
+Parse into:
+
+- original timestamp
+- title
+- mix/version
+- artist(s)
+- original line
+- confidence
+- source URL(s)
+- final file path
+- metadata status
+- Plex ratingKey if indexed
+
+## Target folder structure
+
+Create a dedicated crate separate from normal album folders so it is DJ-friendly and easy to copy to Rekordbox/USB later:
+
+```text
+<NAS_MUSIC_ROOT>/DJ Crates/<YYYY-MM-DD> - <Set Name>/
+  00_PLAYLIST.m3u8
+  00_TRACKLIST.md
+  00_MANIFEST.json
+  artwork/
+    folder.jpg
+    01 - Artist - Title.jpg
+  audio/
+    01 - Artist - Title (Version).flac
+    02 - Artist - Title.mp3
+```
+
+Naming rules:
+
+- Prefix files with set order: `01`, `02`, `03`.
+- Use `Artist - Title (Mix)` after the prefix.
+- Sanitize `/`, `:`, shell metacharacters, and weird whitespace.
+- Preserve original timestamp in tags/comments and manifest, not in filename.
+- Keep source quality in manifest. Do not put `[YouTube]` in the DJ filename unless quality/source ambiguity matters.
+
+## Acquisition order
+
+For each track:
+
+1. Search existing NAS/Plex library first. Reuse existing clean file if present.
+2. Search official stores/catalog pages for metadata confirmation.
+3. Search YouTube only after metadata is clear or when no store source exists.
+4. Prefer official artist/label uploads over user rips.
+5. Download best audio only when lawful/approved.
+6. If the track cannot be sourced confidently, create a manifest row with `status=missing` and continue.
+
+## Tool routing pitfall
+
+`mtp-bot handle` is for one album/release at a time. Do not feed it a DJ playlist, crate brief, or natural-language list of artists. It can correctly classify that as not an album request and skip it.
+
+For crates, parse the tracklist yourself into a manifest, then run per-track acquisition and verification. If you use the plain `mtp` album search path for a release, inspect ranking before adding: the one-shot album auto-pick historically ranked by seeds, not by archival quality. When the user asks for "biggest quality" or "FLAC as possible", prefer this order explicitly: true lossless format (`FLAC`, `WAV`, `ALAC`, `APE`, `WavPack`, `TTA`), then larger release size when it matches the release, then seeds/availability. Never present a lossy YouTube-to-FLAC conversion as real lossless.
+
+## YouTube search and download pattern
+
+Use exact queries first:
+
+```bash
+yt-dlp "ytsearch5:<artist> <title> <mix/version>" --dump-json --flat-playlist
+```
+
+Pick using this priority:
+
+1. exact artist + exact title + exact mix/version
+2. official channel / label channel
+3. duration close to expected release duration, not the DJ-set timestamp segment
+4. audio quality / stable upload
+5. avoid live rips, radio rips, sped-up/slowed/reverb, AI covers, compilations, and low-effort reposts
+
+Download pattern:
+
+```bash
+yt-dlp -x --audio-format flac --audio-quality 0 \
+  --embed-thumbnail --convert-thumbnails jpg \
+  --add-metadata \
+  -o "staging/%(title).200B.%(ext)s" "<url>"
+```
+
+If FLAC conversion is wasteful because source is lossy, keep high-quality MP3/M4A and record `source_lossy=true` in manifest. Do not pretend a YouTube FLAC is lossless.
+
+## Metadata repair
+
+After every download, rewrite tags from the parsed/canonical metadata, not from uploader title:
+
+Required tags:
+
+- title
+- artist
+- albumartist = `Various Artists`
+- album = `<Set Name>`
+- tracknumber / tracktotal
+- date/year if known
+- genre = best broad crate genre, e.g. `Deep House`, `Disco House`, `Balearic`
+- comment = `Crate: <Set Name>; Original timestamp: <timestamp>; Source: <url>`
+- compilation = 1 where supported
+
+Recommended DJ tags if tools are available:
+
+- BPM
+- initial key / Camelot key
+- replaygain / loudness normalization metadata
+
+Use `mutagen` for tag writes. Use `ffmpeg` only for conversion/extraction. Validate tags with `ffprobe` or `mutagen` before moving to NAS.
+
+## Cover art
+
+Cover hierarchy:
+
+1. official release cover from MusicBrainz/Discogs/Bandcamp/store page
+2. label/artist upload thumbnail if official
+3. YouTube thumbnail only as fallback
+4. crate-level generated or neutral cover if no per-track cover exists
+
+Save:
+
+- embedded art in each audio file when format supports it
+- `artwork/<track>.jpg`
+- `folder.jpg` for the crate
+
+## Plex integration
+
+After final files are copied to the NAS path:
+
+1. Fix permissions so Plex can traverse directories.
+2. Refresh the relevant Plex music section.
+3. Search Plex for every imported track and capture ratingKeys.
+4. Create a Plex audio playlist named `<Set Name> - DJ crate` using ratingKeys in set order.
+5. Verify playlist item count and order by reading back `/playlists/<id>/items`.
+6. Report missing/unmatched tracks separately. Do not call the crate done if Plex indexed only part of it.
+
+Use `references/plex-playlist-creation.md` for the exact Plex API sequence.
+
+## Outputs to user
+
+Return concise status:
+
+- crate folder path
+- Plex playlist name / ID
+- total tracks requested
+- imported count
+- Plex-visible count
+- missing/problem tracks
+- source quality warning if any tracks came from lossy YouTube audio
+
+Example:
+
+```text
+Crate built: /volume1/music/DJ Crates/2026-07-04 - Deep House Set/audio
+Plex playlist: Deep House Set - DJ crate, 27 tracks
+Imported: 25/27
+Plex visible: 25/25
+Missing: 2 - exact source not found
+Warning: 8 tracks came from YouTube lossy sources; fine for listening/practice, not archival.
+```
+
+## Verification rules
+
+- A downloaded file is not enough. Verify tags, path, Plex visibility, and playlist order.
+- A Plex refresh response is not enough. Read back playlist items.
+- Do not overwrite existing clean library files. Copy/link them into the crate or reference them in M3U.
+- Keep the manifest. It is the audit trail for where each track came from and why a track is missing.

package/plugins/olko-creative/skills/music-to-plex/references/duplicate-torrent-handling.md

@@ -0,0 +1,19 @@
+# Duplicate torrent handling
+
+Session note:
+- The same magnet (`41bfeae4e4edb72b0e4acc1f816cf4c4914965f2`) was submitted repeatedly for The Chemical Brothers - *Push the Button*.
+- Synology Download Station replied with `Duplicate torrent file`.
+- Three task IDs showed the same failed magnet in `list_tasks`: `dbid_807`, `dbid_808`, `dbid_809`.
+
+Retry-safe sequence:
+1. Call `list_tasks` first.
+2. Search by magnet hash / title.
+3. If the task already exists, do not add another copy.
+4. If the task is failed and duplicated, clean the stale entries before trying a fresh add.
+5. Re-run search with plain artist/album text only. Do not expose magnet URLs back to the user.
+
+Session outcome:
+- After cleanup, the only RuTracker hit for this album was topic `3296838`.
+- There was no alternate source in the current index, so the retry used the same text-only release rather than inventing a fallback.
+
+This is a Download Station state issue, not a Plex ingest issue.