Classify static and smart crates

docs/design/crate-classification.md

@@ -0,0 +1,33 @@
+# Crate Classification
+
+## Problem
+
+Static crates are manually maintained track lists. Smart crates are dynamic views
+generated from rules, so stale-looking entries in them should not be presented as
+broken manual references or given the same health-score weight.
+
+## Architecture
+
+Crates carry a `static`, `smart`, or `unknown` kind. Folder provenance is the
+primary signal: Serato stores regular definitions in `Subcrates` and smart
+definitions in `Smartcrates`. `Compatible by key.crate` is also treated as smart
+when encountered in `Subcrates`, based on the original migration case study.
+
+The library loader reads both folders. Health analysis reports all references but
+scores only non-smart references. Unknown crates remain scoreable so incomplete
+classification cannot silently hide potential problems.
+
+Serato documents the folder distinction in [What is in the _Serato_ folder?](https://support.serato.com/hc/en-us/articles/204022904-What-is-in-the-Serato-folder)
+and explains that smart crates are populated from rules in [Crates in Serato DJ](https://support.serato.com/hc/en-us/articles/227561407-Crates-in-Serato-DJ-Pro-Serato-DJ-Lite).
+
+## Edge Cases
+
+- The known `Compatible by key` dynamic crate in the `Subcrates` folder.
+- Crate fixtures outside a recognized Serato folder.
+- Libraries containing both static and smart references to the same track.
+- Dynamic references whose current materialized paths appear missing.
+
+## Verification
+
+Tests cover all three kinds, both Serato folders, the known dynamic fallback, the
+synthetic five-static/two-smart library, and exclusion from health scoring.

docs/design/health-engine.md

@@ -8,10 +8,11 @@ but an opaque blended score would imply confidence the current data cannot suppo
 ## Architecture
 
 The health engine produces an immutable report from the core `Library`. Its score
-is only the percentage of crate references resolved by exact filename. The report
-also exposes missing references, unique missing filenames, duplicate filename
-groups, extra duplicate files, unused tracks, and missing references with matching
-candidates.
+is only the percentage of non-dynamic crate references resolved by exact filename.
+Smart-crate references are counted but excluded because their contents are derived
+from rules. The report also exposes missing references, unique missing filenames,
+duplicate filename groups, extra duplicate files, unused tracks, and missing
+references with matching candidates.
 
 Duplicate, unused, and candidate counts are informational. They do not affect the
 score until the project has a documented and validated weighting policy. An empty