docs: add detection subsystem reference

docs/architecture/subsystems/detection.md

@@ -0,0 +1,44 @@
+# detection
+
+## Purpose
+
+Library of computer-vision models and classifiers that the camera worker loads in-process. Provides YOLO/SSD object detection, pet identification, face recognition, wildlife threat scoring, package-delivery state machine, vehicle fingerprinting, activity heatmaps, and sunset-aware scheduling. It is not itself a supervised subsystem; there is no `detection` process and no direct MQTT involvement — the camera worker invokes these modules and publishes on their behalf.
+
+## Key files
+
+- `vigilar/detection/yolo.py` — YOLO object detector and category classifier (person/vehicle/pet/wildlife)
+- `vigilar/detection/person.py` — MobileNet-SSD v2 detector for person/car/truck
+- `vigilar/detection/pet_id.py` — MobileNetV3-Small pet identification classifier
+- `vigilar/detection/trainer.py` — transfer-learning trainer for pet-ID model
+- `vigilar/detection/face.py` — dlib/`face_recognition`-based face matcher against `face_profiles`/`face_embeddings`
+- `vigilar/detection/wildlife.py` — wildlife species + threat-level classifier
+- `vigilar/detection/package.py` — package-delivery state machine (`IDLE → PRESENT → REMINDED → COLLECTED`)
+- `vigilar/detection/vehicle.py` — dominant-color and size fingerprinting for vehicles
+- `vigilar/detection/zones.py` — polygon zones and intersection tests
+- `vigilar/detection/heatmap.py` — accumulates detection bboxes into a grid for activity heatmaps
+- `vigilar/detection/crop_manager.py` — saves detection crops into staging and training directories
+- `vigilar/detection/solar.py` — stdlib NOAA sunset calculator for twilight-aware logic
+
+## MQTT topics
+
+**Subscribes:** none. Detection modules are library calls inside the camera worker.
+**Publishes:** none directly. The camera worker publishes detection results on `vigilar/camera/{id}/motion/start` (person/vehicle, with an extra `detection` field), `vigilar/camera/{id}/pet/detected`, `vigilar/camera/{id}/wildlife/detected`, and `vigilar/pets/{pet_name}/location`.
+
+## Database tables
+
+No direct writes. `face.py` reads `face_profiles` and `face_embeddings` via `vigilar.storage.queries`.
+
+## Depends on
+
+- `storage` — `face.py` loads face profiles and embeddings
+- `camera` — invoked as a library inside the camera worker process
+
+## Consumed by
+
+- `camera` — worker imports and calls these modules per frame
+- `pets` — downstream consumer of pet-ID results (via MQTT topics published by camera)
+- `events` — consumes the resulting detection topics off the bus
+
+## Notes
+
+Person and vehicle detections are piggybacked on `motion/start` rather than published on their own topics; the events processor currently collapses both back to `MOTION_START`. The package state machine in `package.py` is driven by the camera worker and uses `solar.get_sunset` to decide when a package has been "abandoned" after dusk.