Add configurable library reference roots

docs/design/configuration.md

@@ -0,0 +1,25 @@
+# Scan Configuration
+
+## Problem
+
+The prototype recognized crate paths by matching one developer's historical
+OneDrive path. That made otherwise valid libraries invisible to the parser.
+
+## Architecture
+
+`ScanConfig` owns the paths for a read-only scan. The CLI accepts repeatable
+`--reference-root` options for roots embedded in crates before a migration. The
+parser uses those roots as record boundaries. Without explicit roots, it recognizes
+generic macOS home and mounted-volume paths without embedding a username.
+
+## Edge Cases
+
+- A library may have references from more than one historical root.
+- Root paths may contain spaces or have leading/trailing separators.
+- Existing `/Users/...` and `/Volumes/...` crates must work without new flags.
+- A record without a recognized terminator remains ignored.
+
+## Verification
+
+Tests cover default root discovery, a custom migrated root, the CLI option, and
+the existing synthetic sample library. The scanner remains read-only.