@olegkoval/agent-skills 1.35.2 → 1.36.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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