diff --git a/docs/VELODY_ROADMAP.md b/docs/VELODY_ROADMAP.md
index e69de29..2ce1568 100644
--- a/docs/VELODY_ROADMAP.md
+++ b/docs/VELODY_ROADMAP.md
@@ -0,0 +1,397 @@
+# Velody Roadmap
+
+This document is the permanent roadmap and milestone status source of truth for Velody.
+When milestone scope, sequencing, or status changes, update this file first.
+
+## Status Summary
+
+| Milestone | Name | Status |
+| --- | --- | --- |
+| 1 | Foundation | Completed |
+| 2 | Device Registration | Completed |
+| 3 | Local Library Discovery | Completed |
+| 4 | Local Catalog Ownership | Completed |
+| 5 | Playback Engine | Completed |
+| 6 | Upload Pipeline | Completed |
+| 7 | iPhone Sync Foundation | Completed |
+| 8 | iPhone User Experience | Completed |
+| 9 | Ownership & Security | Completed |
+| 10 | Offline Resilience Program | In Progress |
+| 10.1 | Multi-device Identity Foundation | Completed |
+| 10.2 | Incremental Sync Cursors | Completed |
+| 10.3 | Offline Recovery | Completed |
+| 10.4 | iPhone Playback Controls | Completed |
+| 10.5 | Offline Sync Polish Audit | Completed |
+| 10.6 | Offline Resilience E2E | Planned |
+| 11 | Accounts | Planned |
+| 12 | Monetization | Planned |
+| 13 | Pro Features | Planned |
+
+## Milestone 1 Foundation
+
+**Goal**  
+Establish the project structure, backend foundation, Apple workspace, and core architectural decisions for a private personal music system.
+
+**Major features**
+
+- Monorepo structure for Apple apps, shared Swift packages, backend services, infrastructure, and docs.
+- NestJS backend scaffold with Prisma, configuration, health checks, and local Docker support.
+- Apple workspace setup for `macOS` and `iPhone` targets plus shared package wiring.
+- Initial project architecture documented in `docs/PROJECT_ENVIRONMENT_ARCHITECTURE.md`.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The repository now has a stable implementation base, local development environment, and shared architectural direction. Later milestones build on this structure rather than replacing it.
+
+## Milestone 2 Device Registration
+
+**Goal**  
+Give each client a recognized device identity so the backend can authenticate and track trusted app installs.
+
+**Major features**
+
+- Device registration endpoint with generated device access tokens and bootstrap tokens.
+- Stored device metadata including platform, device name, app version, and last seen timestamps.
+- Heartbeat flow for refreshing device activity.
+- Keychain-backed device credential persistence in the Apple clients.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Velody can now register trusted devices, persist credentials locally, and use those identities for authenticated backend requests.
+
+## Milestone 3 Local Library Discovery
+
+**Goal**  
+Discover music on `macOS` from a user-selected folder and extract enough metadata to build a usable local library.
+
+**Major features**
+
+- Folder selection and restoration for the local music source.
+- Recursive `MP3` scanning on `macOS`.
+- Metadata extraction for title, artist, album, duration, and embedded artwork.
+- File hashing and file modification capture for later deduplication and upload work.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The Mac app can scan a local folder, recognize supported music files, and produce structured local track data ready for cataloging and upload.
+
+## Milestone 4 Local Catalog Ownership
+
+**Goal**  
+Turn local discovery into a durable app-owned catalog instead of a transient scan result.
+
+**Major features**
+
+- Persistent local track repository and library store.
+- Catalog reconciliation that inserts, updates, reactivates, merges, and soft-deletes scanned tracks.
+- Deduplication based on stable keys rather than raw file paths alone.
+- Local track state that keeps upload status, artwork, remote linkage, and scan timestamps.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Repeated scans now update a single durable local catalog. Missing files are marked deleted, returning files can be reactivated, and duplicate scan results are merged into canonical records.
+
+## Milestone 5 Playback Engine
+
+**Goal**  
+Provide a shared playback core for Apple clients so library items can be played locally with standard transport behavior.
+
+**Major features**
+
+- Shared `VelodyPlayback` package backed by `AVFoundation`.
+- Play, pause, stop, seek, next, and previous controls.
+- Queue management with shuffle and repeat support.
+- Playback session persistence and restore across launches.
+- Playback error handling for empty queues, missing files, and engine failures.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Velody now has a reusable playback engine shared across clients, which reduces duplicated platform logic and enables richer playback experiences in later milestones.
+
+## Milestone 6 Upload Pipeline
+
+**Goal**  
+Move trusted local music from the Mac catalog into the backend library with validation, storage, and change tracking.
+
+**Major features**
+
+- Upload prepare, transfer, status, and finalize backend endpoints.
+- File validation for size, type, and `SHA-256` integrity.
+- Audio asset deduplication by owner and hash.
+- Track, audio asset, and artwork asset persistence during finalize.
+- Library event generation so downstream sync clients can observe changes.
+- Mac upload actions for selected tracks and bulk upload flow with progress states.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Uploads now complete the full ingest loop: prepare, validate, store, finalize, attach metadata, and emit sync-visible library events.
+
+## Milestone 7 iPhone Sync Foundation
+
+**Goal**  
+Give the `iPhone` app a working path to consume the remote Velody library and cache it locally.
+
+**Major features**
+
+- `iPhone` networking client for Velody API access.
+- Remote library bootstrap sync flow.
+- Local persistence for cached remote tracks, download states, audio files, and artwork.
+- Sync service and repository abstractions for remote library updates and asset downloads.
+- Device self-registration flow on `iPhone` using persisted credentials.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The phone can now identify itself, fetch the remote library, cache it locally, and download assets needed for offline listening.
+
+## Milestone 8 iPhone User Experience
+
+**Goal**  
+Turn sync and download capabilities into a usable browsing experience on `iPhone`.
+
+**Major features**
+
+- Remote library and available offline sections.
+- Search and filtering across cached library data.
+- Download actions and per-track download state display.
+- Empty, loading, and connection-failure states with user-facing copy.
+- Favorites persistence and now playing presentation groundwork.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The `iPhone` experience now supports real library browsing instead of raw data plumbing, including search, download workflows, and clearer feedback when the app is empty or offline.
+
+## Milestone 9 Ownership & Security
+
+**Goal**  
+Enforce library ownership boundaries and require authenticated device access for protected backend operations.
+
+**Major features**
+
+- Owner context resolution for the single-owner bootstrap model.
+- Bearer device access tokens with hashing, validation, and last-used tracking.
+- Owner-scoped queries for devices, library records, uploads, audio assets, and artwork assets.
+- Middleware and guards for protected device-authenticated routes.
+- Tests that reject cross-owner access and foreign-device access patterns.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Velody now consistently treats the library as owner-scoped data. Backend operations no longer rely on trust alone and instead enforce device and owner boundaries at the service layer.
+
+## Milestone 10 Offline Resilience Program
+
+**Goal**  
+Harden the multi-device sync and offline playback experience so it survives real-world interruptions, stale state, and repeated client restarts.
+
+**Major features**
+
+- Stable per-device identity across Apple clients.
+- Incremental sync with persisted cursors and bootstrap fallback.
+- Offline recovery for interrupted downloads and missing local files.
+- Richer `iPhone` playback controls and session continuity.
+- UX and behavior polish across sync, playback, favorites, and download states.
+- Final end-to-end resilience coverage.
+
+**Current status**  
+In Progress
+
+**Completion notes**  
+Milestones `10.1` through `10.5` are complete. Milestone `10.6` is still planned, so the umbrella milestone remains open.
+
+## Milestone 10.1 Multi-device Identity Foundation
+
+**Goal**  
+Make device identity stable enough to support repeated sync and download activity across more than one trusted client.
+
+**Major features**
+
+- Durable storage of device identifiers and access tokens in Apple clients.
+- Backend device records tied to a specific owner, platform, and app version.
+- Restore flows that reuse device identity instead of creating duplicate devices on every launch.
+- Shared identity assumptions across `macOS`, `iPhone`, and backend services.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Velody devices can now come back as the same logical device across app launches, which is a prerequisite for reliable sync cursors, download ownership, and activity tracking.
+
+## Milestone 10.2 Incremental Sync Cursors
+
+**Goal**  
+Avoid reloading the entire library for every sync by moving to cursor-driven incremental updates.
+
+**Major features**
+
+- Append-only `library_events` change log.
+- `sync/changes` endpoint with paging and `hasMore` handling.
+- Persisted client-side sync cursor storage.
+- Server-side per-device sync cursor tracking.
+- Bootstrap fallback when a client cursor is too old to recover incrementally.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The `iPhone` sync path now applies deltas when possible and automatically falls back to bootstrap when retained events are no longer sufficient.
+
+## Milestone 10.3 Offline Recovery
+
+**Goal**  
+Recover cleanly from interrupted downloads, stale file paths, and missing offline assets.
+
+**Major features**
+
+- Download state reconciliation on restore.
+- Recovery from interrupted download states after relaunch.
+- Asset-based local file path resolution when persisted paths go stale.
+- Explicit missing-file detection and user-facing error states.
+- Offline library snapshot rebuild based on cached remote tracks plus available local files.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The offline library can now restore itself more safely after app restarts and partial failures, and it surfaces missing or broken downloads as recoverable states instead of silent corruption.
+
+## Milestone 10.4 iPhone Playback Controls
+
+**Goal**  
+Bring the `iPhone` player up to expected music-app behavior for offline listening.
+
+**Major features**
+
+- Previous, next, stop, and seek controls.
+- Shuffle and repeat controls.
+- Persisted playback queue and session restore.
+- Richer now playing model with progress, duration, badges, and error messaging.
+- Shared playback behavior with the underlying `VelodyPlayback` package.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+Offline playback on `iPhone` now behaves like a real player rather than a minimal preview flow, with standard transport controls and state restoration.
+
+## Milestone 10.5 Offline Sync Polish Audit
+
+**Goal**  
+Audit the end-user sync and offline experience and tighten rough edges before final end-to-end validation.
+
+**Major features**
+
+- Better cached-library restore behavior and status messaging.
+- Connection-failure handling that preserves usable cached data.
+- Artwork cache usage across remote and offline library views.
+- Favorites restore and persistence flow cleanup.
+- Additional targeted tests around playback, favorites, and sync behavior.
+
+**Current status**  
+Completed
+
+**Completion notes**  
+The product flow has been polished substantially, but Milestone `10` still requires a full resilience-oriented end-to-end pass before it can be marked complete.
+
+## Milestone 10.6 Offline Resilience E2E
+
+**Goal**  
+Prove that the full Mac-to-backend-to-`iPhone` pipeline remains reliable across interruptions and recovery scenarios.
+
+**Major features**
+
+- End-to-end coverage for ingest, sync, download, relaunch, and offline playback.
+- Regression scenarios for interrupted downloads and missing local files.
+- Validation of stale-cursor bootstrap fallback behavior.
+- Multi-device consistency checks for library state and cursor advancement.
+- Final resilience sign-off criteria for closing Milestone `10`.
+
+**Current status**  
+Planned
+
+**Completion notes**  
+Not started yet. This milestone is the remaining gate for closing the broader offline resilience program.
+
+## Milestone 11 Accounts
+
+**Goal**  
+Move beyond the current single-owner bootstrap model and introduce formal user accounts.
+
+**Major features**
+
+- Account creation, sign-in, and session management.
+- Migration from bootstrap ownership to account-linked ownership.
+- Device enrollment and recovery flows tied to a real account.
+- Backend identity model changes needed to support account lifecycle operations.
+
+**Current status**  
+Planned
+
+**Completion notes**  
+Not started yet. The current codebase intentionally assumes a private single-owner system, so this milestone begins the transition to explicit account identity.
+
+## Milestone 12 Monetization
+
+**Goal**  
+Introduce billing and entitlements once account identity exists and the core product flow is stable.
+
+**Major features**
+
+- Subscription plan and entitlement model.
+- Billing provider integration and event handling.
+- Upgrade, downgrade, renewal, and cancellation support.
+- Plan-aware gating for server and client features.
+- Basic internal reporting for billing state and entitlement debugging.
+
+**Current status**  
+Planned
+
+**Completion notes**  
+Not started yet. Monetization is intentionally deferred until core sync reliability and account identity are in place.
+
+## Milestone 13 Pro Features
+
+**Goal**  
+Ship high-value premium capabilities on top of a stable paid Velody foundation.
+
+**Major features**
+
+- Advanced offline automation and smart download rules.
+- Power-user library management and metadata tools.
+- Premium playback and cross-device continuity improvements.
+- Advanced diagnostics, backup, or admin-oriented controls.
+- Feature rollout tied to entitlement checks.
+
+**Current status**  
+Planned
+
+**Completion notes**  
+Not started yet. The exact scope should be finalized only after Milestones `11` and `12` define the account and entitlement model.
+
+## Future Ideas
+
+The items below are intentionally outside the committed milestone plan above. They are good candidates for later evaluation after the current roadmap stabilizes.
+
+- Background folder watching on `macOS` so manual rescans become optional.
+- Background downloads and periodic refresh on `iPhone`.
+- Support for formats beyond `MP3` once the current ingest path is fully hardened.
+- Smart playlists, richer sorting, and advanced search filters.
+- Lock screen, external control, and car-focused playback integrations.
+- Library health tooling such as orphaned asset cleanup, re-hash verification, and storage audits.
+- Backup and restore workflows for local offline state.