@olegkoval/agent-skills 1.35.2 → 1.36.0

package/.windsurf/rules/music-to-plex.md

@@ -0,0 +1,249 @@
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+---
+description: "Acquire music and make it playable in Plex/Plexamp: single albums, DJ crates, and YouTube playlists, with verified NAS/Plex delivery and source-backed Obsidian radio notes."
+---
+
+# 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/README.md

@@ -259,14 +259,15 @@ Build, test and publish Garmin Connect IQ watch faces.
 |-------|-------------|----------|
 | [garmin-watchface](plugins/olko-garmin-kit/skills/garmin-watchface/SKILL.md) | Designs, builds, tests, screenshots, and publishes Garmin Connect IQ watch faces in Monkey C | Working on a Connect IQ watch face, SVG design proposals, inspiration gathering, layout that clips or overlaps, simulator screenshots, app settings, device support, or store submission |
 
-### olko-creative (4)
+### olko-creative (5)
 
-Creative and personal projects: photo galleries, music players, listings, wiki editing.
+Creative and personal projects: photo galleries, music players, Plex ingest, listings, wiki editing.
 
 | Skill | What it does | Use when |
 |-------|-------------|----------|
 | [gallery](plugins/olko-creative/skills/gallery/SKILL.md) | Creates photo galleries with AI-assisted layout curation and sequencing | Building a gallery from photos or planning photo layout, sequencing, and curation |
 | [fill-music-player](plugins/olko-creative/skills/fill-music-player/SKILL.md) | Fills a portable music player with a curated random selection while balancing formats, artists, albums, and capacity | Copying music from a NAS or local library to a Walkman, iPod, USB drive, or similar device |
+| [music-to-plex](plugins/olko-creative/skills/music-to-plex/SKILL.md) | Acquires albums, DJ crates, and YouTube playlists for Plex/Plexamp with verified NAS delivery, Plex visibility, and source-backed Obsidian radio notes | Adding or downloading music to Plex/Plexamp, including an album request, DJ crate, or YouTube playlist |
 | [vinted-listing](plugins/olko-creative/skills/vinted-listing/SKILL.md) | Creates and safely publishes Vinted listings from verified item details and the seller’s original photos, with automatic suggestions, duplicate checks, draft verification, and publish confirmation | Creating, editing, or publishing a Vinted listing |
 | [wikipedia-uk-editor](plugins/olko-creative/skills/wikipedia-uk-editor/SKILL.md) | Drafts policy-compliant Ukrainian Wikipedia edits, en→uk translation, stub expansion, sourcing, backlog cleanup, returning ready-to-paste wikitext, an edit summary, and a verified source list | Editing, translating, or sourcing a uk.wikipedia.org article, or planning what to contribute next |
 

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

@@ -0,0 +1,255 @@
+---
+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]
+---
+<!-- Generated by scripts/build-adapters.sh. Do not edit directly. -->
+
+# 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/adapters/claude/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/adapters/claude/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/adapters/claude/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/adapters/claude/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.