Add project roadmap and architecture docs

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+## Branching
+
+- `main` is stable.
+- `develop` is the integration branch.
+- Feature branches use: `feature/<name>`.
+
+## Safety Rules
+
+Never commit personal music library files, Serato databases, or crates.
+
+Never write repair code without dry-run mode, backup plan, and rollback log.

ROADMAP.md

@@ -0,0 +1,48 @@
+# Serato Doctor Roadmap
+
+## v0.1 — Library Inspector
+
+- [x] Project repository
+- [x] Filesystem scanner
+- [x] Serato crate parser
+- [x] Missing reference CSV report
+- [x] Grouped missing reference report
+- [ ] HTML health dashboard
+- [ ] Test suite
+- [ ] Sample library fixtures
+- [ ] Database V2 read-only parser
+
+## v0.2 — Diagnostics
+
+- [ ] Duplicate filename detection
+- [ ] Duplicate audio hash detection
+- [ ] Broken symlink detection
+- [ ] Orphaned audio detection
+- [ ] OneDrive rename detection
+- [ ] Crate classification: static vs smart/dynamic
+- [ ] Library health score
+
+## v0.3 — Safe Repair
+
+- [ ] Dry-run repair plan
+- [ ] Backup before repair
+- [ ] Compatibility symlink creation
+- [ ] Compatibility copy creation
+- [ ] Rename repair
+- [ ] Rollback log
+
+## v0.4 — Migration Wizard
+
+- [ ] Move library root
+- [ ] Cloud provider migration
+- [ ] External drive migration
+- [ ] Verify moved library
+- [ ] Update application references
+
+## v1.0 — DJ Library Doctor
+
+- [ ] Desktop UI
+- [ ] Serato support
+- [ ] Rekordbox support
+- [ ] VirtualDJ support
+- [ ] Engine DJ support

docs/ARCHITECTURE.md

@@ -0,0 +1,11 @@
+# Architecture
+
+Serato Doctor is designed as a DJ library inspection, repair, and migration platform.
+
+## Design Principles
+
+1. Read-only by default.
+2. Every repair must support preview/dry-run.
+3. Every repair must create a backup or rollback path.
+4. Application-specific logic lives in engines.
+5. Core matching and scanning logic should be application-agnostic.

docs/case-studies/onedrive-mac-migration.md

@@ -0,0 +1,26 @@
+# Case Study: OneDrive Mac Migration
+
+## Scenario
+
+A large Serato DJ library was migrated from an older Mac to a newer Mac using OneDrive.
+
+## Symptoms
+
+- OneDrive client stuck syncing
+- Duplicate OneDrive folders
+- Thousands of files renamed with trailing ` 2`
+- Serato reported many tracks as missing
+- Some files existed on disk but still appeared orange in Serato
+
+## Findings
+
+- OneDrive sync state was rebuilt successfully
+- Thousands of orphaned filename conflicts were repaired
+- Some Serato references were stale database objects, not missing files
+- Smart/dynamic crates should be classified separately from static user crates
+
+## Lessons
+
+- Filesystem health and Serato database health are separate problems
+- Smart crates should not be treated the same as static crates
+- Repair tools must be read-only by default and generate a plan before changing anything

pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "serato-doctor"
+version = "0.1.0"
+description = "Inspect, diagnose, repair, and migrate DJ libraries."
+requires-python = ">=3.9"
+dependencies = []
+
+[project.scripts]
+serato-doctor = "serato_doctor.cli:main"