@olegkoval/agent-skills 1.35.3 → 1.37.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/adapters/claude/olko-github-pr/skills/lekker-review/SKILL.md

@@ -330,6 +330,50 @@ anchors. Apply your own judgment to every finding.
 - Pre-existing code not touched by this diff
 - Anything you are not confident about - omit rather than hedge
 
+**Approval standard.** The verdict answers "does this definitely improve the
+codebase's health", not "is this how I would have written it". Perfect code does
+not exist. `✅ LGTM - ship it` is the right call for a change that improves
+health and violates no hard rule, even with open Observations or Idiomatic
+findings. Reserve `🚫 Needs work` for an unfixed Critical, a hard-rule
+violation, or an Important finding that changes external behaviour or data
+shape. Never manufacture a Critical to justify a verdict, and never block on
+taste.
+
+**PR sizing.** Judge how much a reviewer must hold at once, not the raw diff
+count:
+- Under ~300 changed lines, or larger but one logical change: no finding.
+- Over ~800 changed lines spanning more than one logical change: `important`,
+  and name the split. Pick the strategy that fits - stack (sequential
+  dependencies), by file group (different reviewers), horizontal (shared code
+  and stubs first, then consumers), vertical (smaller full-stack slices).
+- A diff that both refactors existing code and adds new behaviour: `important`
+  at any size. Those are two PRs, and bundling them hides the real change.
+- A change that pushes a single file past ~1000 total lines with no
+  decomposition: `observation`. Ask for the extraction first, then the feature.
+Exempt: whole-file deletions and mechanical or automated refactors, where the
+reviewer verifies intent rather than every line.
+
+**Verify the verification.** Read the PR body for the author's verification
+story: which tests were run, whether the build passed, whether it was exercised
+manually, screenshots for a UI change, a before/after for a behaviour or
+performance change. A non-trivial PR whose body claims nothing about
+verification is an `observation` naming the evidence that is missing. `CI: ✅
+All passing` is not a verification story - it only says the suite that already
+existed still runs.
+
+**Rationalizations to reject.** If one of these is the reason a finding is about
+to be dropped or softened, keep the finding:
+
+| Rationalization | Reality |
+|---|---|
+| "The tests pass, so it's fine" | Tests do not catch architecture, security, or data-shape problems. |
+| "It works, that's good enough" | Working code that is unreadable or insecure is debt that compounds. |
+| "The refactor makes it cleaner" | Relocating complexity is not reducing it. Count the concepts a reader holds. |
+| "It's only a small addition to this file" | Judge the resulting structure, not the diff size. |
+| "It's just a version bump" | A bump is a behaviour change nobody in the PR wrote. |
+| "They'll clean it up later" | Later does not come. Require it now, or require a ticket. |
+| "An agent wrote it, so it's probably fine" | Generated code needs more scrutiny, not less: it is confident and plausible when wrong. |
+
 **Idiomatic & Consistency exception:** the conventions agent raises non-blocking
 suggestions ONLY when a concrete better pattern provably already exists in the
 codebase. Never on taste alone. These land in their own section, not in

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/quality.md

@@ -36,6 +36,24 @@ Axes to cover:
 - No JavaScript files (TS-2): if the diff adds any `.js` file to a non-Liquid
   theme repo, flag as Critical — must be `.ts`. Set `rule: "TS-2"` on the
   finding.
+- Dependency changes. Skip this axis entirely unless the diff touches
+  `package.json`, a lockfile, or a vendored dependency. Where it applies:
+  (a) A version bump is a behaviour change nobody in this PR wrote. If neither
+      the PR body nor a commit message cites the changelog or migration notes,
+      that is `important`: semver is a promise the maintainer may not have kept,
+      and a "patch" can carry a behavioural change.
+  (b) A bulk bump of several unrelated packages in one PR is `important`. When
+      it breaks the build you have lost which package did it. The `fix` is to
+      split it per package, or per genuinely related group.
+  (c) When the repository tracks a committed lockfile, a `package.json`
+      dependency change with no matching lockfile change in the same diff is
+      `critical`: the lockfile is what actually ships. A lockfile change with no
+      `package.json` change and no explanation is also `critical`. Do not require
+      a lockfile from a repository that intentionally does not commit one.
+  (d) A new direct dependency that duplicates something already in the stack is
+      `important`. Name the existing thing that already solves it.
+  Raise NO naming, comment, complexity, or hard-rule finding inside a lockfile
+  or a `node_modules` path.
 
 Setting rule tags the finding as a house hard rule: it keeps its Critical
 severity and skips adversarial verification. Only set it for a genuine

package/adapters/claude/olko-github-pr/skills/lekker-review/references/agents/simplification.md

@@ -20,10 +20,39 @@ Look for:
   anti-pattern (handler → service → repo with no logic in any layer).
 - Feature flags always on/off, fallback that can never trigger, dual
   implementations where old has no callers.
+- Relocated complexity: a refactor that moves code without reducing the number
+  of concepts a reader must hold to follow it. Count them before and after, but
+  an unchanged count alone is not a finding. Flag only when the move leaves a
+  concrete residual coupling, duplication, branch, or bug-surface maintenance
+  risk, and name both that risk and the cheaper move available (deleting a
+  branch, a mode, or a layer outright, rather than re-centralising the same
+  logic). `important` when the PR is sold as a cleanup or refactor,
+  `observation` otherwise.
+- Feature logic in a shared module: feature-specific behaviour added to a
+  general-purpose util, a shared client, or a base class. The branch belongs in
+  the package that owns the concept. Name the owning layer in the `fix`.
+- Dead code this diff orphans: when the diff replaces or reroutes something,
+  grep the worktree for remaining callers of what it superseded (the old helper,
+  the old component, a now-unreferenced constant, a flag that can no longer be
+  false). Enumerate what is now unreachable. NEVER propose a silent deletion:
+  the `fix` lists the orphans and asks the author to confirm removal.
+  `observation`, or `important` when the dead path is still reachable from
+  production code. When WORKTREE_PATH is null in scan mode, do not infer absent
+  callers from the diff: mark orphan analysis unverified and request
+  worktree-backed verification instead.
 
 Only flag where duplication or complexity creates a real maintenance risk or
 bug surface — not aesthetic preference.
 
+When you flag a structural problem, name the move, not just the smell: replace a
+chain of conditionals with a typed model or an explicit dispatcher, collapse
+duplicate branches into one flow, separate orchestration from business logic,
+move feature logic into the package that owns it, reuse the canonical helper
+instead of a near-duplicate, delete a pass-through wrapper. Prefer the remedy
+that removes moving pieces over one that spreads the same complexity around. A
+finding that says "this is complex" without naming the restructuring is not
+actionable: name the move or drop the finding.
+
 EXISTING_REVIEWS: read key "existingReviews" from CONTEXT_FILE (awareness only — skip findings already raised)
 
 PROJECT_RULES to verify: read key "projectRules" from CONTEXT_FILE.

package/adapters/claude/olko-github-pr/skills/lekker-review/references/output-format.md

@@ -140,6 +140,36 @@ proof inline.>
 
 ---
 
+## 📋 PR-level findings
+
+PR-level findings have no single file:line. Render them with this dedicated
+contract instead of demoting them to Observations because a location is absent:
+
+For an `important` sizing finding:
+
+### #N — Sizing
+
+**Scope:** PR-level · **Severity:** Important
+
+**Risk:** <why the PR cannot be reviewed safely as presented>
+
+**Action:** <the recommended split and strategy>
+
+For a missing verification story:
+
+### Verification story — action required
+
+**Missing evidence:** <tests run, manual exercise, screenshots for UI, or
+before/after for behaviour or performance>
+
+**Action:** <exactly what the author must add to the PR description>
+
+An `important` sizing finding counts toward the Important total and continues
+the finding-number sequence. Missing verification evidence is an explicit
+action, not a no-action Observation.
+
+*(Omit section entirely if empty.)*
+
 ## 📝 Observations
 
 - <note — tradeoff, risk to watch, or design question worth raising>

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

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