libsync

Use when changing libsync backend services, routers, event wiring, or SDK integration; when adding a new source, WebSocket event, config key, or a new writer of album download_status; when a WS event never reaches the UI, albums stay stuck in queued/downloading after a restart, dedup skips downloads unexpectedly, or pagination total reads 0; or when reviewing a diff that touches mark-downloaded, client hot-reload, dedup DB placement, or the static SPA route.

Use when setting up libsync from a fresh clone; when make deps, poetry install, or npm install fails; when ModuleNotFoundError: No module named 'qobuz' or 'tidal' appears; when docker build fails or bakes unexpected SDK code; when make dev serves a 404 UI or make dev-frontend requests hit the wrong port; when the sdks/qobuz_api_client submodule is empty, dirty, or needs a pin bump; or when local Python/Node/Poetry versions differ from CI and behavior diverges.

Use when merging, opening a PR, or classifying a change in the libsync repo — deciding if a change needs a spec, plan, or CHANGELOG entry; when a required check (backend-tests, frontend-build, docker-publish, ruff) blocks a merge; when someone proposes renaming "streamrip" identifiers, overwriting qobuz_app_id, rewriting the SPA path guard for CodeQL, vendoring/bypassing the SDK submodule, editing design tokens, or basing work on origin/dev.

Use when a libsync setting or credential change does not take effect, STREAMRIP_DB_PATH or STREAMRIP_DOWNLOADS_PATH seems ignored, a Settings toggle silently inverts, downloads land in an unexpected folder layout, auto-sync never fires or fires late, GET or PATCH /api/config returns 500 or unexpected defaults, .streamrip.json sentinels stop being written, or when adding, renaming, or auditing any config key or environment variable.

Use when libsync misbehaves at runtime: downloads 401 while the library loads, a settings toggle acts inverted or ignored, logger.info never prints, ModuleNotFoundError: No module named qobuz/tidal, make lint fails on untouched main, UI 404s while /api answers, a downloaded FLAC is not real FLAC, Tidal capped at AAC 320, scan stuck at 0/? or 409 'Another scan is already running', 'database is locked', albums stuck queued after restart, PKCE 400 'Unknown handle', or grep finds deleted code.

Use when a libsync symptom needs measurement instead of eyeballing - this skill ships runnable read-only scripts to dump the config table with secrets redacted, probe what actually arrives on the live WebSocket, report album download_status states, reconcile .streamrip.json sentinels against the library DB, inspect the per-source dedup DBs behind silently skipped re-downloads, or health-check a fresh checkout; also use when you need visible backend INFO logs via the shipped uvicorn --log-config (the backend configures no logging of its own).

Use when writing or updating any libsync doc — CHANGELOG entries, README, CLAUDE.md, docs/WEB_UI.md, specs/plans under docs/superpowers/, or a new skill; when two docs disagree (e.g. about Tidal auth or endpoints); when a doc references a file that does not exist; when deciding which doc to trust or which doc to update after adding an endpoint or config key; or when asked about the house changelog format, commit-message style, or spec/plan naming convention.

Use when writing anything public about libsync — README or website copy, release notes, feature claims, screenshots, demo videos, blog or social posts; when handling .har captures, tokens, or /api/config output that could leave the machine; when asked about the GPL license, the nathom/streamrip fork lineage, the 2026-04-14 history reroot, or the FUNDING.yml sponsor button; when an external user wants to file an issue or contribute; or when deciding whether a capability may be claimed.

Use when a libsync symptom looks familiar — 'library loads but downloads 401', wrong quality/folder labels, boolean settings behaving inverted, scan progress stuck at '0 / ?', 'Album <id>' placeholder names — or when git history confuses: a bisect stops at root f5058e4, a submodule pin does not exist upstream, PRs #7–#10 show MERGED but their content is absent from main, CodeQL flags path-injection on serve_frontend, or a 22-bug review file cites nonexistent streamrip/ paths.

Use when about to accept a root cause or "just try a fix" on libsync and want to PROVE it first — a Qobuz 401 that could be expired token vs app-id mismatch vs bad signing secret, a "library loads but downloads 401" split-brain, deciding if an SDK secret is valid without live guessing, a frontend event that never arrives, git history that looks wrong after the 2026-04-14 reroot, or SQLite state disagreeing with the UI.

Use when building in-app Qobuz token-expiry recovery, wiring the dead `token_expired` WebSocket event to a real publisher and Settings banner, making Qobuz download-secret resolution observable, or hardening the play.qobuz.com spoofer chain. Symptoms — every Qobuz call 401s after a period of working; Qobuz 401 shows only a generic "Download failed" toast with no re-auth prompt; users must restart or re-login to recover an expired Qobuz token; secret-tier winner is invisible in logs.

Use when asked what libsync could do beyond existing tools, when brainstorming roadmap or research directions, or when someone proposes: making the scan matcher learn from user confirmations, formalizing the Qobuz/Tidal SDK facade into a contract or adding a third source, detecting upstream secret/app-id rotation before it breaks downloads, or running libsync offline/air-gapped (fonts, cover art). Also use to check whether an ambitious idea already has a vetted framing before starting work.

Use when a libsync hunch, bug theory, or improvement idea needs to become an accepted change; when a proposed fix explains only some of the symptoms (e.g., library loads but downloads 401); when tempted to ship without a spec, plan, or CHANGELOG entry; when designing any experiment that touches Qobuz/Tidal behavior; when a CodeQL alert or Codex review finding suggests a rewrite; or when deciding whether to remove a feature outright.

Use when running libsync locally or in Docker, choosing a compose file, deciding whether streamrip.db, downloads.db, .streamrip.json, or other data files are safe to delete, cutting a release or pushing a version tag, or diagnosing symptoms like logger.info output never appearing, auto-sync not running after being enabled, the download queue vanishing after a restart, albums stuck in queued/downloading, "Unknown or expired PKCE handle", or no versioned GHCR image after tagging.

Use when preparing to push or open a PR in libsync, deciding which checks to run before merge, adding or locating tests, or judging whether a fix has enough evidence. Also use on these symptoms — make lint fails with RUF100 errors on a clean main checkout, local ruff results differ from CI, node --test reports a single failing "tests" entry, a required check (backend-tests, frontend-build, docker-publish, ruff) blocks a merge, or a change is claimed to "work on my machine" without a test.

Use when you lack background on how Qobuz/Tidal streaming APIs, audio formats, or reverse-engineered auth work as they apply to libsync — e.g. confused by format IDs 5/6/7/27, MQA vs HI_RES_LOSSLESS, why a download needs an app_secret not just a token, why Tidal HiRes yields MP4-in-.flac without ffmpeg, why X-App-Id 304027809 vs 798273057 matters, what device-code vs PKCE unlocks, TrackResult.path vs .file_path, or why live-API testing is risky.