yellowjacket/.planning/phases/12-library-crud-data-integrity/12-CONTEXT.md

Phase 12: Library CRUD & Data Integrity - Context

Gathered: 2026-03-12 Status: Ready for planning

## Phase Boundary

Users can add, rename, and remove libraries through the UI with correct data lifecycle management. Tracks are created/deleted, shared entities (artists, albums, genres) are cleaned up only when orphaned, FTS5 search index stays consistent, queue tracks cascade-delete, and playlist tracks convert to phantoms. The library manager UI lives in settings alongside scan controls.

## Implementation Decisions

Library management UI

• Integrated library + scan section in the settings page — combine library management and scanning into one unified section
• Remove the libraries tab from the sidebar list entirely
• Each library row displays: name, directory path, track count in the main row; actions (rename, remove, rescan) hidden behind a ... overflow menu
• Replace the old single-directory config UI (directory path field + rescan button) completely — the migrated library appears in the new list

Add-library flow

• Click "Add Library" button in the library management section
• OS folder picker dialog opens
• Library auto-named from the folder name (editable later via rename)
• Scan starts automatically after adding
• Uses the existing per-library scan pipeline from Phase 11

Removal confirmation & feedback

• Warning dialog with impact summary before removal: "Remove 'Jazz Collection'? This will delete 1,234 tracks, affect 2 playlists, and remove 15 queue items."
• If a track from the library being removed is currently playing, stop playback first, then proceed with removal; queue advances to next valid track if one exists
• Blocking operation with spinner on the dialog while cleanup runs (expected < 1 second for most libraries)
• Toast notification on completion: "Removed 'Jazz Collection' (1,234 tracks deleted)"

Orphan cleanup behavior

• Immediate cleanup in the same database transaction — delete tracks, identify orphaned entities, delete orphans, convert playlist phantoms, all atomic
• Reference-counting bottom-up: only delete artists/albums/genres that have zero remaining track references after the library's tracks are removed
• Rebuild the entire FTS5 index from remaining tracks after library removal (handles contentless table limitation cleanly)
• Playlist phantom track conversion in the same transaction: copy track metadata to phantom columns on playlist_tracks, then SET NULL the audio_file_id
• Queue tracks cascade-delete (queue is ephemeral, not user-curated)
• Removal API endpoint returns cleanup summary: {tracks_deleted, artists_removed, albums_removed, genres_removed, playlists_affected, queue_items_removed} — feeds the toast notification

Rename & display behavior

• Library names must be unique — validation error if user tries to use an existing name
• Inline edit on the list row: click name (or rename action from menu) turns it into an editable text field, Enter to save, Escape to cancel
• Name validation: 1-50 characters, non-empty
• Rename changes display name only — changing a library's directory path requires remove + add (no path editing)

Claude's Discretion

• Exact layout/styling of the library management section within settings
• Loading skeleton design while library list loads
• Error state handling for failed operations
• Exact spinner implementation during removal
• Toast notification library/component choice
• API endpoint URL structure and HTTP methods
• SQL query optimization for orphan detection

## Specific Ideas

• Library management section should feel like a natural extension of the existing settings page — not a separate app within settings
• The impact summary in the removal dialog should use real counts from the database, not estimates
• The ... overflow menu pattern keeps the list clean — same pattern used elsewhere in the app for action menus

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 12-library-crud-data-integrity Context gathered: 2026-03-12