Changelog

​

Bug Fixes

• ci: derive release PR SHA from GitHub (#133) (580ed98)

​

Features

• mcp: migrate to protocol 2026-07-28 (#130) (2a98863)

​

Documentation

• sync the generated changelog page to 0.18.2 (#86) (bd9ace9)

​

Bug Fixes

• web: mobile MCP card polish (hide derivable total, tighten wrapped subtext gap) (#85) (e592ba8)

​

Documentation

• sync the generated changelog page to 0.18.1 (#83) (19475c1)

​

Bug Fixes

• apex-worker: serve CW wordmark favicon instead of iPod mark (#79) (2d756e3)
• web: drop card radius + border on iOS so Claude doesn’t clip the corners (#82) (196f3e8)

​

Documentation

• sync the generated changelog page to 0.18.0 (#76) (fec60e5)

​

Features

• add clickwheel convert (FLAC→MP3 for iPod) (#75) (fae92d0)
• apex worker so Google caches the correct favicon (fixes black square) (#74) (b04bd6f)

​

Documentation

• add gear icon to configuration page (8c89cfa)
• convert Apple Music and Plex command lists to tables (e8572ee)
• mcp: mark apex redirect + favicon-app cleanup done in tracker (#72) (070ef15)
• mcp: mark connector re-auth on mcp.clickwheel.fm complete (#72) (8cc01ef)
• mcp: move remote-MCP deploy docs to mcp.clickwheel.fm + apex redirect (473fd79)
• split Reference into top-level CLI and MCP tabs (#68) (ba60739)
• sync the generated changelog page to 0.17.0 (#65) (f100bdd)

​

Features

• auto-remount a dropped library share instead of hanging (#61) (9ed6916)
• complete the mypy ratchet — full type coverage, zero exemptions (#60) (d5e8c86)
• playlist: track-level add/remove for saved playlists (31052be)
• playlist: track-level add/remove for saved playlists (f530e4a), closes #63

​

Documentation

• add sidebar icons, fix the logo flash, surface quickstart steps in the TOC (143b635)
• apple-music: collapse ‘From Claude’ to a one-line cross-link (ecb0a37)
• architecture: add autoscan.py to the module table (c63e3b8)
• deepen guides, add troubleshooting + requirements, automate changelog (94b7c1b)
• design: shorten section headings, merge read-only principles, short sidebar title (b9655ca)
• drop drift-prone perf figures and hardcoded tool counts (9e3b184)
• fix-metadata: surface the Last.fm key prereq, fix the target arg, trim jargon (b315435)
• genericize remaining clickwheel.fm examples to mcp.example.com (142ce06)
• integrations: point ‘From Claude’ at the per-domain MCP tool reference (bc3d856)
• keep the changelog icon in gen-changelog so regeneration matches (083088d)
• mcp-server: fold gating reassurance into the behavior bullet, drop the orphaned snippet (7fdf2bb)
• mcp: record the Managed-OAuth connector fix; mark remote access working (#56) (07bfcd7)
• og: light social card on a subtle light-gray background (8874034)
• playbook: capture the content/polish pass conventions, process, and Mintlify gotchas (ad60938)
• playlists: align commands, shorten the track path, rework two-concepts (61fc7e4)
• plex: inline the token env var, trim the token tip and push/pull prose (2942d0e)
• project: correct docs-site status — holding on Mintlify, not pivoted (#58) (6a63635)
• project: mark feedback, examples, snippets, mermaid adopted in playbook (246a292)
• pull the generic diagrams; park polished versions in DEFERRED (cb9bb3f)
• quickstart: drop the eject Warning box (command still in the step) (0cd0f38)
• quickstart: link the package name to PyPI on the install step (005d71c)
• quickstart: tighten the install path and trim chrome (b03ad6d)
• readme: point to the docs site, add docs badge, retire duplicated guides (417fb3b)
• reference: add curated Examples to CLI commands (703d8e8)
• reference: align overview cards; pointer once per overview (cbd9031)
• reference: group CLI by service, recurse sub-apps, add synopses (3d3e636)
• reference: MCP prompt examples, gating snippet, mermaid architecture (50412c4)
• reference: rebuild Configuration page (b78d85b)
• reference: render params as ParamField; strip em dashes from descriptions (2c163d6)
• reference: split CLI reference into per-group pages (1b2b430)
• reference: split MCP tools into per-domain pages (7e0979a)
• reference: trim verbose CLI/MCP descriptions; refresh sample data (fe94ef7)
• reframe the Welcome page around the iPod (4524221)
• regroup the Guides nav by topic (4c33fca)
• remote-mcp: genericize the example domain to mcp.example.com (6ace806)
• rename remote-mcp ‘Setup (summary)’ to ‘Setup’; clean up the deploy runbook (6490f2e)
• requirements: drop the Classic year, unbold Skipped, trim the Note and mount/capacity lines (87b749a)
• requirements: list supported iPods, trim, and shed non-requirements (1d3ac38)
• requirements: make Optional integrations a what-it-needs table (2b74de5)
• scrobbling: tighten the lead, demote the shared-key note, collapse ‘From Claude’ (dd45dd0)
• scrobbling: use a blue Note for the re-sync caution (Warning reserved for irreversible) (5e78949)
• site: enable contextual menu + feedback thumbs; track feature checklist (bbfb75c)
• site: maple theme, branded logo + favicon, iPod accent, copy polish (2f7a485)
• sync-to-ipod: rewrite the lead and retire the Notes section (b4a2dc9)
• title config and .env code blocks with their filenames (153cefb)
• troubleshooting: add an Integrations bucket pointing at the doctors (02b0f01)
• welcome: add an iPod hero image with rounded corners (06e02d6)

​

Features

• mcp: remote access — streamable-http transport + favicon + runbook (#48) (489cb4f)

​

Documentation

• add mintlify docs site with generated, drift-checked reference (#52) (ddc5981)
• bring trackers current after merging #48 + #52 (#54) (8ef174a)
• project: pause docs-site; record Mintlify→Starlight pivot (#55) (2ed4ef9)

​

Bug Fixes

• fix: escape LIKE wildcards in path prefix; tighten exception catches (29e66be)
• fix: skip writes for files that vanished between scan and write (1d4a54c)

​

Documentation

• reflect the native fix pipeline + metadata caches (5810c5e)

​

Features

• scan: summarise what each scan changed (#45) (274e037)

​

Bug Fixes

• artwork: retry transient MusicBrainz/Cover Art Archive failures (#46) (6168b71)
• beets: resolve beet next to the interpreter, not via PATH (#44) (f93baa2)

​

Documentation

• slim README commands table; trust the per-integration docs (#40) (0f816e3)
• stop enumerating tool names inline in README + MCP docs (#43) (6499161)
• tighten integration docs and even out the README commands table (#42) (07c8df8)

​

Bug Fixes

• applemusic: leave track_count unknown in apple list view (#38) (be61289)

​

Features

• applemusic: clickwheel apple delete via AppleScript (#36) (9114f78)

​

Features

• applemusic: pull + list playlists from Apple Music (#34) (27cf0ff)

​

Features

• applemusic: match + push playlists to Apple Music account (#32) (da34621)

​

Features

• applemusic: add auth + doctor for Apple Music API (#29) (2ef84d4)

​

Features

• plex: add playlist pull command for read-back recovery (#27) (e6fed7b)

​

Features

• fix: fetch album art and release years from musicbrainz (#25) (2fb694a)

​

Bug Fixes

• cli: keep beets metadata cleanup scoped to its target (#23) (597b4fe)

​

Features

• playlist: add playlist descriptions, synced to Plex (#20) (687c07b)

​

Features

• mcp: add tool titles, server icon, and resource display titles (#18) (d9d53bd)
• mcp: emit output schemas for all tools via typed return models (#19) (16898f4)
• plex: add optional plex playlist sync (#12) (d8afd75)
• plex: mcp tools, doctor command, and docs (#13) (b7a9094)

​

Documentation

• plex: drop design-rationale section (#16) (3d70d8d)
• trim readme integrations, extract docs/lastfm.md (#15) (1277ffb)

​

Documentation

• mcp: drop test plans, split bundles deep-dive into bundles.md (51a1174)

​

Features

• mcp: add_tracks_to_ipod / add_artist_to_ipod (no playlist required) (13c37c6)
• mcp: compute sync-result detail subtitle server-side (0413361)
• mcp: library_health bundle (status grid) (d2b24d5)
• mcp: library_stats bundle (overview dashboard) (5bb5548)
• mcp: live progress notifications for sync_playlist_to_ipod (a9c3b53)
• mcp: live progress polling in the sync-result iframe (bd0638f)
• mcp: mcp apps ui bundles with react + vite workbench (afb3506)
• mcp: primary-artist rollup, host theme tokens, click-to-message (770a08c)
• mcp: remove_tracks / remove_artist / remove_ipod_playlist (phase 4) (2a37a4c)
• mcp: sync creates the ipod playlist + new list_ipod_playlists tool (a3575c7)
• mcp: sync-result summary card iframe + preload experiment (85e3e10)
• web,mcp: rewind card chrome + route artist-browse away from search_tracks (abe69f2)
• web: align ipod-capacity to library-stats header + tooltip pattern (43bf893)
• web: balanced-5 categorical palette + workbench showcase (a4a5c55)
• web: finder-style library-stats + floating-ui tooltips (21e02a7)
• web: static detail subtitle, inline status text, drop library-health + stats-showcase (f8df644)
• web: unified header + done-state progress bar + capacity legend cap (6d42233)
• workbench: live-progress simulation for sync-result preview (faba9b3)
• workbench: viewport + theme toggles, transparent iframe bg, claude chat bg (1de4536)

​

Bug Fixes

• ci: exclude auto-generated _ui_bundles.py from ruff format check (ab6b831)
• mcp: handle classic-ipod auto-disconnect gracefully (b5effce)
• mcp: instruct the agent to check ipod state before curating a playlist for sync (8efaafa)
• mcp: primary_artist now trusts album_artist instead of parsing strings (cae3b23)
• mcp: teach the model to stop fuzzy-searching n times for known tracks (88cccd3)
• web: register ontoolresult before app.connect() so initial fixture renders (852130b)
• web: smooth out sync-result live progress + no end-of-sync flash (d84c02c)
• web: workbench drops first fixture on initial mount (d44bd82)

​

Documentation

• mcp: document inline ui bundles + web workspace workflow (6b658e7)
• mcp: manual test script for the playlist redesign (4cb48a5)
• mcp: refresh bundles + tool tables after recent feature work (aea99b3)
• web: note that fixtures must match post-tool output, not raw tags (4e3fefa)

​

Features

• add build-playlist mcp prompt (50c44e8)
• add eject_ipod tool and richer mcp tool descriptions (6b82b32)
• add mcp mutation tools (1bba30d)
• add read-only mcp server (74ba924)
• dual-content mcp responses with text summaries (6be17db)

​

Bug Fixes

• clearer copy on the elicitation confirm field (269433e)
• drop server-side elicitation; rely on client gating (99290de)
• elicit_confirm — accept = yes, no double-toggle required (8509362)
• filter missing tracks in library queries; preserve in playlist queries (ae41f17)
• mcp: dual-emit structured tool output for clients that hide it (2a160e1)
• paginate ipod and playlist tracks to fit the tool-result token cap (8dbe9d3)
• pre-flight checks on sync + heal_playlist for stale refs (14eb218)
• two-tier autoscan + mcp never autoscans (180afb3)
• write_ipod_db merges with existing itunesdb instead of clobbering (d38830c)

​

Documentation

• add autoscan-blocking-mcp-tool-calls to phase 5 findings (53057a1)
• add mcp integration project plan (7e7c796)
• capture phase 5 testing findings (397b4c1)
• claude desktop install path, stale readme defaults, round 6 findings (b269e15)
• discourage emoji in mcp client output (1a61e4c)
• document mcp server install and usage (40f2fe5)
• refresh mcp test plan for phases 4.5a–d (a0bac9c)
• restructure as a two-surface project — slim readme, dedicated client/config guides (8cf0339)
• restructure mcp test plan as a round-by-round walkthrough (a7d8d44)
• round out readme — heal command, heal_playlist tool, autoscan subsection (d2c2ae0)
• scrub internal jargon from user-facing mcp copy (586077e)

​

Features

• modernize CLI UX with interactive prompts, spinners, and live displays (5b12137)

​

Bug Fixes

• allow dashes and double blanks in markdownlint for release-please compat (8575db8)
• standardize table styling across cli output (52ef6f0)
• resolve table title truncation in tests (428a44e)

​

Features

• add last.fm web auth flow for scrobbling (0776e2e)
• auto-scan library before commands, incremental scan, fix improvements (bb56ab2)

​

Bug Fixes

• lint issues — line length, table alignment, changelog headings (3e8a9c7)

​

Documentation

• update architecture, readme, and claude.md for new features (b33eef0)
• update tracker with completed end-to-end testing (054d5eb)

​

v0.3.0 (2026-03-15)

​

Features

• Non-interactive playlist editing: clickwheel edit --add "Artist" / --remove "Artist"
• Live file counter during scan discovery phase (no more staring at a blank screen)
• Scan progress indicator using tqdm for file discovery

​

Fixes

• Always use ~/.clickwheel/ for data dir instead of varying by working directory
• Fix iPod sync: use shutil.copy instead of copy2 to avoid FAT32 xattr errors
• Fix sync error output: group failures by artist/album instead of per-file path noise
• Fix vendored iPod imports: bare from device_info → from clickwheel.ipod.device_info
• Fix iTunesDB reader to handle both flat and nested track list formats
• Normalize capitalized track keys (Title/Artist/Album) from iTunesDB writer format

​

Infrastructure

• Add release-please for automated changelog and version management
• 83 tests (6 new for non-interactive edit)

​

v0.2.1 (2026-03-15)

​

Fixes and Cleanup

• Remove unused acoustid_api_key from config
• Fix duplicate warn() in capacity bar
• Fix README capacity default to match code (64 GB)
• Rewrite README for end users (pipx install, clean config example)
• Update all dependencies to latest versions
• Add repo description, website, and topics on GitHub

​

v0.2.0 (2026-03-15)

​

Fixes

• Move macOS platform guard to individual commands so --help works on any OS
• Add test matrix job to CI (ubuntu + macos, Python 3.11-3.13)

​

v0.1.0 (2026-03-15)

​

Features

• Core CLI with Typer: scan, fix, select, playlist, diff, sync, ls, eject commands
• SQLite library index with metadata quality reporting
• Interactive artist/album/genre picker with capacity tracking
• iPod sync via vendored iOpenPodv2 (no libgpod dependency)
• Last.fm scrobbling via scrobble command with play count caching
• Playlist management: edit, delete commands
• Centralized Rich output helpers with consistent formatting
• macOS platform guard for clear error messaging
• Optional [artwork] extra for album art embedding (Pillow/numpy)
• Consumer-friendly CLI text throughout

​

Infrastructure

• Pre-commit hooks: ruff, shellcheck, shfmt, prettier, markdownlint, commitlint
• 78 tests across 7 test modules (db, config, library, output, CLI helpers, scrobble, smoke)
• CI workflow with lint, format, and test jobs (ubuntu + macos, Python 3.11-3.13)
• Dynamic versioning via hatchling reading from clickwheel/__init__.py
• PyPI-ready packaging with classifiers, URLs, and optional dependency extras