@olegkoval/agent-skills 1.35.2 → 1.36.0

package/adapters/claude/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/adapters/claude/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/adapters/claude/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/adapters/claude/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.

package/adapters/claude/olko-creative/skills/music-to-plex/references/fallback-audio-validation-and-nas-preflight.md

@@ -0,0 +1,42 @@
+# Manual album fallback: validation and NAS preflight
+
+Use this only after the normal `mtp-bot` path has returned a real no-result/fallback outcome, or the user explicitly authorizes a manual recovery path.
+
+## 1. Derive the request and route correctly
+
+- A bare `mtp` accompanying cover art is an album request. Read the cover, then confirm the canonical artist, release title, year, official track count, and expected track durations before acquiring anything.
+- `mtp-bot handle` must receive the **originating Telegram chat ID**. For a group, that is the negative group ID from the inbound route, not the user ID and not the configured home-DM ID.
+- Do not call `mtp-bot` with a naked image caption such as `mtp`; it has no album text to parse. After identification, use a clear album-shaped add request only if the workflow permits a resolved-image continuation.
+
+## 2. Preflight NAS while metadata is being confirmed
+
+Read-only inspect the exact final parent path first. Verify:
+
+```bash
+ssh <user>@<nas> "test -d '<final-parent>' && test -w '<final-parent>' && test -x '<final-parent>'"
+```
+
+If the artist directory does not exist, verify the transfer account can create it **before** downloading the whole album. A read-only library is a blocker, not a signal to choose an arbitrary alternate directory. Ask the NAS owner for an album-scoped directory plus write/traverse access.
+
+## 3. Track-by-track YouTube staging
+
+For every canonical track:
+
+1. Search separately; prefer an official audio upload.
+2. Reject live, remix, edit, video, and compilation variants unless the canonical release requires one.
+3. Check normalized title and source duration against the canonical duration before download.
+4. Tag *every* FLAC and embed the same verified cover art. Never skip tagging merely because a filename already exists—the process may have timed out between conversion and tagging.
+
+## 4. Decode and duration validation are mandatory
+
+A successfully created `.flac` may still be truncated after a timeout/interruption. Before NAS transfer:
+
+- decode every FLAC to null with FFmpeg (or use another installed lossless decoder);
+- check exact file count, canonical tags, track numbering, and an embedded front-cover picture;
+- compare each decoded duration with MusicBrainz/canonical duration using a tolerance appropriate to the source (normally ±12%; use a tighter bound when directly matching an official upload).
+
+If any duration is implausibly short, replace that track from a verified source, re-tag it, and repeat the full per-track check. Do **not** transfer or refresh Plex until all tracks pass.
+
+## 5. Resume safely after interruption
+
+Treat a process timeout as an incomplete transaction. Enumerate staged FLACs and validate their tags/art/durations, rather than treating `EXISTS` as success. Re-run idempotent tagging over the complete track set, then validate again.

package/adapters/claude/olko-creative/skills/music-to-plex/references/gear-change-image-identification.md

@@ -0,0 +1,35 @@
+# Cover-art driven identification and verification
+
+Use this pattern when the user sends an image instead of a clean text release name.
+
+## What worked in this session
+
+- The image was a viewer screenshot, not just artwork.
+- Vision identified the release from cover text: `74 Miles Away - Gear Change`.
+- The tracker exact search did not return a hit for the release title.
+- `yt-dlp` search found the exact YouTube upload:
+  - `https://www.youtube.com/watch?v=KDwMTXynA4w`
+  - title: `74 Miles Away - Gear Change // Single`
+- The shorter official clip also existed, but the longer `// Single` upload was the better audio source.
+
+## Verification sequence
+
+1. Use the image as primary evidence for the release name.
+2. Try tracker search on artist and title.
+3. If tracker search returns nothing, search YouTube exact title.
+4. Prefer the cleanest full upload over a short clip when both exist.
+5. Download audio, tag it, write cover art, copy to NAS, then refresh Plex.
+6. Verify in Plex with the music section search endpoint, not the generic search endpoint.
+
+## Plex check that succeeded
+
+- Section search endpoint:
+  - `GET /library/sections/2/search?type=10&query=Gear%20Change`
+- The returned track proved the import landed in Plex:
+  - track title: `Gear Change`
+  - artist: `74 Miles Away`
+  - file path: `/volume1/music/library/74 Miles Away/2013 - Gear Change - Single/01 Gear Change.flac`
+
+## Why this matters
+
+Image-driven requests are easy to misread if you trust OCR or the user's prose too early. The right flow is image first, tracker second, YouTube fallback third, Plex verification last.

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

@@ -0,0 +1,19 @@
+# Image-driven album identification and verification
+
+Use this when the user gives an attached cover image, a misspelled album title, or only partial artist/release text.
+
+## Pattern
+1. Treat the image as primary evidence for identifying the release.
+2. Use text search only to confirm the likely album, not to override the cover art.
+3. After download/import, verify both:
+   - the final NAS folder exists and contains audio files
+   - Plex can see the album/track(s) after refresh
+4. If the album title is uncertain, report the exact release name you actually matched, not the user's misspelling.
+
+## Session example
+- User wrote: "Paul McCrtney (newsest one)" and attached album art.
+- The matched release was `Paul McCartney - The Boys of Dungeon Lane`.
+- Verification succeeded only after checking the final folder and confirming Plex search results returned the album and tracks.
+
+## Why this matters
+Text-only guesses are fragile on new releases and misspellings. Cover art plus post-import verification avoids adding the wrong release or reporting success before Plex has indexed it.

package/adapters/claude/olko-creative/skills/music-to-plex/references/library-repair-folders.md

@@ -0,0 +1,22 @@
+# Library repair: folder consolidation and malformed FLAC handling
+
+Use this when repairing an existing music library, not just ingesting one album.
+
+## Pattern
+- Normalize artist variants to a canonical display name before deciding folder placement.
+- Apply the same canonical mapping while aggregating batch dominance and while comparing per-file tags.
+- Treat punctuation-only splits as real drift if they create duplicate artist folders in Plex.
+- Sanitize destination folder names before joining paths. `AC/DC` is display text, not a path separator.
+- If a FLAC is malformed (`invalid FLAC header`, `sample rate not set`), skip it, record it, and keep the batch moving.
+- Refresh Plex after files reach their final NAS paths, then refresh again after any later tag or folder rename.
+
+## Session-specific pitfalls observed
+- Safe folder naming must convert `/` to `-` before moving trees.
+- Canonical artist normalization fixed GYBE variants by collapsing them to `Godspeed You! Black Emperor`.
+- The repair pass surfaced two bad Twin Peaks FLACs that should be quarantined or skipped rather than retried as metadata issues.
+- Raw error logs are noisy. Default to concise status unless the user explicitly asks for debug output.
+
+## Verification
+- Spot-check canonical artists that previously split: GYBE, AC/DC, i/dex.
+- Verify one folder per canonical artist on disk.
+- Refresh Plex and confirm the duplicate artist entries disappear after the next scan.

package/adapters/claude/olko-creative/skills/music-to-plex/references/malformed-flac-fallbacks.md

@@ -0,0 +1,11 @@
+# Malformed FLAC fallback notes
+
+Session takeaways for bulk music library tag repair:
+
+- `ffmpeg` can fail on some legacy FLACs with `sample rate not set` or `invalid FLAC header`.
+- Treat these as file-level salvage failures, not library-wide failures.
+- Prefer `mutagen` for tag writes first. Only fall back to `ffmpeg` when a file is structurally writable.
+- If a FLAC header is invalid, record the path, skip it, and continue the batch. Do not retry indefinitely.
+- After successful writes, refresh Plex only once the files are in their final NAS path.
+
+This is a session note, not a general claim about all FLAC files.

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

@@ -0,0 +1,39 @@
+# Manual fallback: NAS transfer and Plex verification
+
+Use after a fully tagged/cover-embedded album is staged locally and the standard bot workflow cannot complete the import.
+
+## 1. Write preflight
+
+Inspect the canonical location first: use an existing album by the same artist as the layout guide. Test the **exact final album directory** with a create/remove probe using the same SSH account that will transfer. If its parent is root-owned, ask for an **album-scoped** directory/ACL repair; never change ownership recursively across the library.
+
+## 2. Transfer without fragile rsync assumptions
+
+Some bundled macOS `rsync` builds lack newer flags such as `--info=progress2`, and a remote-shell rsync session can behave differently from a standalone SSH probe. If rsync is unsuitable, send the staged directory through a tar stream over SSH:
+
+```bash
+/usr/bin/tar -C "$LOCAL_ALBUM" -cf - . | \
+  ssh -i "$SSH_KEY" -o BatchMode=yes "$SSH_USER@$SSH_HOST" \
+  "tar -C '$NAS_ALBUM' -xf -"
+```
+
+On macOS, this can create `._*` AppleDouble sidecars on the NAS. Remove only those sidecars from the newly created target folder, then verify that the count of normal `*.flac` files equals the expected track count and that `cover.jpg` exists.
+
+```bash
+ssh -i "$SSH_KEY" -o BatchMode=yes "$SSH_USER@$SSH_HOST" \
+  "find '$NAS_ALBUM' -maxdepth 1 -type f -name '._*' -delete; \
+   find '$NAS_ALBUM' -maxdepth 1 -type f -name '*.flac' ! -name '._*' | wc -l; \
+   test -f '$NAS_ALBUM/cover.jpg'"
+```
+
+## 3. Refresh and prove Plex visibility
+
+Run a targeted refresh first, then a plain section refresh if needed:
+
+```bash
+mtp refresh --path "$NAS_ALBUM"
+mtp refresh
+```
+
+The refresh response only proves Plex accepted the request. Poll the Plex API for the album and verify **album title, artist, year, and track count**. Plex album (`type=9`) metadata uses `parentTitle` for the artist; `grandparentTitle` may be empty. To prove track visibility, request `GET /library/metadata/<ratingKey>/children` and count its metadata entries.
+
+Treat an album as complete only after the NAS file count and Plex track count agree with canonical metadata.

package/adapters/claude/olko-creative/skills/music-to-plex/references/mtp-bot-bulk-state-safety.md

@@ -0,0 +1,21 @@
+# mtp-bot bulk import state safety
+
+## Why bulk album requests must be serialized
+
+`mtp-bot` is a chat-scoped state machine. A search that needs a numbered choice leaves the chat in `AWAITING_PICK`; a later request is not an independent request. Concurrent handler calls can therefore collide with or overwrite the intended conversational flow.
+
+## Safe procedure
+
+1. Identify the exact artist and release scope before starting (for example, core studio albums vs. live, compilation, collaboration, or solo records).
+2. Check for an existing picker/state in the destination chat before sending any batch item.
+3. If a picker exists, preserve it. Only send `cancel` after the user has explicitly authorized cancelling that specific stale request.
+4. Send exactly one `mtp-bot handle` request.
+5. Read its reply before the next request:
+   - **Accepted/downloading:** record it and proceed to the next album only if the handler has returned to idle.
+   - **Numbered picker:** stop and ask the requester to choose; never guess a number.
+   - **No results / skipped / malformed parse:** stop the batch. Diagnose the request parser or source integration; do not substitute direct `mtp` search/add commands or claim that an import started.
+6. Verify the final album only when it is in the library path and visible in Plex/Plexamp.
+
+## Parsing degradation signal
+
+If an otherwise clear message is parsed with artist/album words incorrectly divided, the LLM parser may have fallen back to its simplistic token-splitting heuristic. Treat this as a bot integration issue, not a reason to send malformed variants repeatedly. Preserve the chat state and repair or route the parser before continuing.

package/adapters/claude/olko-creative/skills/music-to-plex/references/mtp-subprocess-wrapper.md

@@ -0,0 +1,13 @@
+# mtp subprocess wrapper pitfall
+
+Session finding:
+- The bot path can accidentally execute the globally installed `mtp` wrapper instead of the checked-out project code.
+- That hid a valid NAS connection behind an old launcher that was not exercising the current tree.
+
+Preferred invocation during development:
+- Use `uv run python -m mtp.bot.cli handle "<message>" --chat <chat_id>` to exercise the repo checkout.
+- In `mtp/bot/mtp_client.py`, subprocesses should call `sys.executable -m mtp ...` so child calls stay on the same environment as the parent process.
+
+Verification:
+- Confirm the target NAS endpoint with `curl` or a direct Python request before blaming the network.
+- If `mtp-bot` selection still looks wrong, inspect which launcher is being used before assuming the DS API is down.

package/adapters/claude/olko-creative/skills/music-to-plex/references/music-note-blurb-order.md

@@ -0,0 +1,38 @@
+# Music note blurb order
+
+Use this exact order for artist/album notes:
+
+1. Artist note
+2. Album note
+3. Optional one-line DJ-style summary
+
+Style:
+- Write in the lane of WFMU, LDBK / Radio Brussels, and serious classic underground radio: crate-digger intelligence, warm human enthusiasm, sly humour, and a little beautiful weirdness.
+- This is an original radio-DJ voice, not an imitation of any one station or presenter. Never name-drop the style in the note itself.
+- Make listeners feel an invitation to listen: sensory, curious, vivid, and slightly dangerous when the record demands it. Prefer concrete musical images over generic praise.
+- Include juicy, source-backed facts: recording/release context, label and year, collaborators/producers, samples or scene connections when verified, unusual backstory, chart/cultural impact, and one or two specific listening details. Facts should create intrigue, not become a Wikipedia dump.
+- Separate fact from interpretation. If a fact is uncertain or unsourced, omit it or say it is a claim; never invent samples, personnel, labels, dates, or anecdotes.
+- Artist note: establish the artist's lane, history, sound, collaborators, and why this artist matters before discussing the particular album.
+- Album note: give the release year/label, key players and context, then explain what to listen for and why the record still matters.
+- End with an optional one-line DJ cue or listening invitation that is tactile and specific, not promotional copy.
+- Avoid reusable AI-blurb phrases and generic metaphors such as “summer breeze,” “bright telescope,” “one sneaker on the pavement,” “the room needs colour,” “key document,” or “still sounds fresh.” If a sentence could describe twenty unrelated albums, rewrite it.
+- Do not use a fixed artist-note → atmospheric-album-note → generic-DJ-cue template mechanically. Vary the opening: a scene, an odd fact, a collaborator, a production decision, a historical collision, a lyric-level observation, or a listener challenge.
+- Every album note should contain at least two genuinely specific hooks: an unusual verified fact, a named musical relationship explained in context, a concrete production/sample detail, a scene or label connection, or a precise moment to listen for. Names alone are not facts.
+- **Editorial attitude:** WFMU is not merely poetic wording. Make the note feel like a live, adventurous radio segment: playful, eccentric, conversational, anti-commercial, and happy to take a funny detour. Let the host sound delighted by the discovery. Use odd connections, affectionate mischief, sharp asides, mini cliffhangers, and unexpected turns when the facts support them.
+- The prose may be lopsided, funny, slangy, or slightly unruly. It should sound like a person with a crate, a microphone, and genuine excitement—not a critic delivering a verdict or a label polishing a campaign.
+- Facts should enter through personality: “Here’s the strange bit…”, “Listen for what happens after…”, “This is where the record gets gloriously sideways…” Use that energy without forcing these exact phrases every time.
+- Ban commercial-review language and prestige fog: “sonic journey,” “immersive experience,” “genre-defining,” “landmark,” “timeless masterpiece,” “a testament to,” and similar claims unless directly quoted and necessary.
+- Fun does not mean shallow. Keep the juicy verified facts, but let them trigger curiosity, jokes, and listener invitations rather than sit as a dry credits list.
+- Before saving, perform a replaceability test: delete the album and artist names. If most of the note still works for another record, it is too generic and must be rewritten.
+
+Recommended note structure in Obsidian:
+
+```md
+# Artist - Album
+
+## Artist note
+...
+
+## Album note
+...
+```

package/adapters/claude/olko-creative/skills/music-to-plex/references/nas-import-and-refresh.md

@@ -0,0 +1,16 @@
+# NAS import and Plex refresh note
+
+Use this workflow when importing an album into the NAS music library and refreshing Plex afterwards.
+
+## What worked in this session
+- Source can be a chaptered YouTube/vinyl rip when it contains a clean track breakdown.
+- Inspect chapters first to confirm track count and titles before tagging.
+- Stage files locally, tag them, then transfer to the NAS over SSH if direct writes to the library path are blocked by permissions.
+- If the final library path is root-owned, use an interactive SSH `sudo` move on the NAS rather than trying to bypass permissions from the local machine.
+- Expected destination pattern:
+  - `/volume1/music/library/<genre>/<Artist>/<Album (Year)>`
+- After the move, refresh the Plex music section so the new album is indexed.
+- Verify the remote album folder contains the expected track count before closing out.
+
+## Output preference
+- Keep user-facing confirmation short. Do not dump command output unless the user asks for it.

package/adapters/claude/olko-creative/skills/music-to-plex/references/nas-library-layout-and-write-preflight.md

@@ -0,0 +1,31 @@
+# NAS library layout and write preflight
+
+Use this before transferring a manually staged fallback album. Treat `nas_music` in app configuration as a storage root, **not proof of Plex's scanned folder layout**.
+
+## Preflight
+
+1. Inspect an existing album by the same artist when possible. This reveals the real Plex tree (for example, an artist-first `library/<Artist>/` layout rather than a proposed genre bucket).
+2. Check that the configured SSH account can create the target directory before staging a large fallback:
+
+```bash
+ssh -i ~/.ssh/id_ed25519 -o BatchMode=yes <user>@<host> \
+  "test -d '<parent>' && test -w '<parent>' && printf WRITABLE"
+```
+
+3. If the artist folder exists but is not writable, do not silently place the album in an arbitrary writable genre folder. Keep the release staged and report the permission blocker.
+
+## Least-privilege repair
+
+Have the NAS owner create **only the target album directory**, then grant the transfer account ownership. Avoid recursively changing ownership of the whole music library.
+
+```bash
+sudo mkdir -p "/volume1/music/library/<Artist>/<Album> (<Year>)"
+sudo chown -R <transfer-user>:users "/volume1/music/library/<Artist>/<Album> (<Year>)"
+sudo chmod 755 "/volume1/music/library/<Artist>/<Album> (<Year>)"
+```
+
+The `sudo` password must be entered by the NAS owner in an interactive shell; never ask them to paste it into chat. Afterward, transfer into that album-only directory, verify file count/cover/permissions, then run the Plex refresh.
+
+## Why it matters
+
+A successful download and correct tags do not establish Plex readiness. A wrong scanned root or non-writable parent folder can make a genre-based transfer both inaccessible to Plex and inconsistent with the existing library.

package/adapters/claude/olko-creative/skills/music-to-plex/references/nas-permissions-and-plex-traversal.md

@@ -0,0 +1,26 @@
+# NAS permission repair and Plex traversal
+
+Use when a staged album cannot be copied into the canonical Plex music library, or Plex is not indexing files after a successful copy.
+
+## Scope the repair narrowly
+
+- Do **not** recursively `chown` the broad `/volume1/music` share just to enable one import.
+- If the owner explicitly wants durable managed imports, grant ownership/write access at the configured Plex **library root** (for this environment, `/volume1/music/library`) only.
+- Verify it with a real SSH probe: create a unique temporary directory, write a file inside it, remove both, then inspect ownership/mode.
+
+## Permissions to verify
+
+1. Managed import account can create an artist directory below the library root.
+2. Every parent from the Plex section root through `Artist/Album` is traversable by the Plex process. Use `755` for artist and album directories unless the Plex service group has been deliberately granted equivalent execute access.
+3. Do not infer traversal from file readability. A `770` artist directory can prevent scanning even though the account that transferred the FLACs can read the album.
+
+## Transfer fallback
+
+If the NAS rsync implementation cannot support the desired safe flags or preservation semantics, stream the already-validated album using `tar` over SSH into the final directory. On macOS-originated sources, remove `._*` AppleDouble sidecars afterward and verify the exact FLAC count on NAS before triggering Plex refresh.
+
+## Plex evidence order
+
+1. Refresh the music section after permissions and copy are final.
+2. Query the Plex DB for `media_parts` at the final path.
+3. Read album metadata and track children through Plex API/DB; do not rely only on a fuzzy library-search query.
+4. Compare the returned track count and sequence with the canonical release tracklist.

package/adapters/claude/olko-creative/skills/music-to-plex/references/nas-routing-and-refresh.md

@@ -0,0 +1,22 @@
+# NAS routing and Plex refresh
+
+Session takeaway:
+- For albums that must land in a genre bucket, the final Plex path matters more than the download origin.
+- If the intended genre bucket does not exist or cannot be written by the organizer, create a writable bucket first and move the album there instead of leaving it in `unsorted`.
+- After moving files into the final NAS music folder, trigger a Plex music library refresh for the correct section.
+- If tags are corrected after the move, refresh again. Plex refresh does not retroactively fix a wrong folder placement; it only re-indexes what is already on disk.
+
+Case study from this session:
+- Iron Maiden albums ended up in `/volume1/music/metal/Iron Maiden/...` after the metal bucket was made writable.
+- A later metadata correction from `Pop` to `Heavy Metal` required another Plex refresh.
+
+Reusable order of operations:
+1. Confirm the album's real tags.
+2. Ensure the target NAS bucket exists and is writable.
+3. Move the album into the final Plex-rooted path.
+4. Refresh Plex section 2.
+5. Verify PlexAmp can actually see the album after the refresh. If it cannot, re-check the on-disk path before assuming the scan succeeded.
+6. If tags changed, refresh Plex again.
+
+Session note:
+- In one follow-up, Plex was refreshed successfully but PlexAmp still showed nothing. The fix path was to re-verify the album's final library location instead of trusting the refresh alone.