### SwingMusic Production Readiness Plan: Multi-User, Download-First Artist Experience

**Summary**
- Deliver a production workflow from first launch to daily usage: owner bootstrap, invite-based users, root directory setup, recommendation-driven home, and fully actionable artist pages.
- Make all library behavior user-isolated at the profile level while deduplicating physical files on disk, with explicit opt-in import prompts when another user already has matching songs.
- Replace placeholder downloader behavior with a real server-side job pipeline, fix current downloader API/service mismatches, and unify status/quality reporting in UI.
- Make lyrics auto-download fully enabled by default, remove experimental gating, and add robust synced/unsynced retrieval + storage.
- Add personalized radio and “This Is Artist” generation that starts heuristic and becomes user-adaptive via listening data; include optional Last.fm sync.

**Implementation Changes**
- Authentication and tenancy:
  - Add first-run owner bootstrap flow (only when no users exist), then invite/admin user creation only.
  - Introduce strict user scoping on all user-facing resources (library views, recommendations, stats, queues, settings).
  - Migrate existing single-user installs by assigning current library/root-dir ownership to the owner account automatically.
- Library model and cross-user import:
  - Split data into physical file registry (global dedup) and per-user library ownership/projection tables.
  - Mark track availability per user (`available`, `missing`, `queued`, `failed`) and expose this state everywhere tracks are rendered.
  - Implement “another user already has this song” detection; always show consent popup with choices to import existing file or continue with new download.
- Download system hardening:
  - Replace simulated universal queue with real async download workers and durable job states.
  - Standardize a single downloader service interface and align Spotify API handlers to it (fix current contract mismatch).
  - Enforce source strategy: Spotify-first metadata + fallback provider adapters for media acquisition.
  - Persist source, codec/quality, destination path, and failure reasons for UI badges and retry flows.
- Home, navigation, and artist UX:
  - Home/Dashboard default content: random recommended artists from available catalog APIs for newly initialized users.
  - Ensure click-throughs resolve correctly to artist/song/album/playlist/radio pages; repair current route-name inconsistencies and wire missing global views.
  - Artist page behavior:
    - Show top 15 popular songs.
    - Show full discography sections.
    - Render available tracks as normal and missing tracks grayed with active download action.
    - Keep quality badges visible using existing badge language/colors.
    - Add “Artist Radio” (similar artists/tracks) and “This Is {Artist}” (artist-only set).
- Personalization and listening analytics:
  - Keep per-user local scrobbling as primary and add optional Last.fm sync per user account.
  - Ensure all counters/rankers are user-scoped; remove any cross-user aggregation leakage.
  - Ranking engine: deterministic heuristic at cold start, then blend with user listening signals over time.
- Lyrics by default:
  - Remove experimental toggle and force auto-lyrics retrieval on by default.
  - Implement SpotiFLAC-style LRCLIB-first retrieval with fallback query strategy.
  - Save lyrics as embedded tags when format supports it and also write sidecar `.lrc` files.
  - Backfill missing lyrics after downloads and during scan/import cycles.

**Public API / Interface Changes**
- Add bootstrap/invite endpoints for owner-first provisioning and user onboarding.
- Extend artist/home/catalog responses to include per-user availability, download action metadata, and recommendation blocks.
- Add import-candidate and import-confirm endpoints for cross-user local reuse flow.
- Unify download job endpoints around one job schema (`state`, `source`, `quality`, `target_path`, `error`, `progress`).
- Add user-scoped external scrobble integration endpoints (connect/disconnect/sync status for Last.fm).

**Test Plan**
- First-run scenarios:
  - Empty install -> owner creation -> root directory setup -> home recommendations visible.
  - Existing install upgrade -> auto migration to owner with no lost library visibility.
- Multi-user isolation:
  - Two users with separate dashboards, stats, queues, and library projections.
  - No accidental cross-user data in recommendations, playcounts, or settings.
- Cross-user import behavior:
  - Candidate detected -> popup shown -> accept imports without copy.
  - Candidate detected -> decline keeps item missing and allows independent download.
- Artist page acceptance:
  - Top 15 tracks displayed, full discography visible, correct available/missing styling, download actions functional, quality badges accurate.
  - “Artist Radio” and “This Is Artist” render on cold start and improve after listening history accumulates.
- Downloader reliability:
  - Queue, retry, failure states, progress updates, and destination writes validated under concurrent jobs.
- Lyrics:
  - Auto-fetch runs by default; embed + `.lrc` both generated when possible; fallback paths validated.
- Responsive UI:
  - Mobile/tablet/desktop checks for onboarding, home, artist, downloader, and import-popup flows.

**Assumptions and Defaults**
- Signup model: owner bootstrap + invite/admin management.
- Storage model: user-isolated libraries with shared deduplicated physical files.
- Import policy: always ask user before importing songs from another user’s local files.
- Download strategy: Spotify-first with fallback providers.
- Mix generation: heuristic first, then personalization.
- Lyrics strategy: embed + sidecar `.lrc`, auto-enabled globally.
- Listen tracking: local tracking plus optional Last.fm sync.