fix(v2-import): namespace source identity for snapshot upserts

README.md

@@ -185,6 +185,15 @@ Command behavior:
 - moves valid files to archive
 - moves invalid files to failed
 
+### Source Identity Namespacing
+
+Raw external IDs are **not globally unique** across basketball data sources. HoopScout v2 uses a namespaced identity for imported entities:
+- `Competition`: unique key is `(source_name, source_uid)`
+- `Team`: unique key is `(source_name, source_uid)`
+- `Player`: unique key is `(source_name, source_uid)`
+
+`source_uid` values from different sources (for example `lba` and `bcl`) can safely overlap without overwriting each other.
+
 Import history is visible in Django admin:
 - `ImportRun`
 - `ImportFile`