docs: add highlights subsystem reference

docs/architecture/subsystems/highlights.md

@@ -0,0 +1,35 @@
+# highlights
+
+## Purpose
+
+Generates derived video products from recorded footage: a daily highlight reel (events scored and assembled into a short FFmpeg-concatenated clip) and scheduled per-camera timelapses. These are offline/batch jobs that read the `events` and `recordings` tables and write new rows into `recordings` tagged with a synthetic trigger.
+
+## Key files
+
+- `vigilar/highlights/reel.py` — event scoring map (`PET_ESCAPE=10`, `WILDLIFE_PREDATOR=9`, ...), clip selection, FFmpeg concat assembly, inserts resulting file via `insert_recording`
+- `vigilar/highlights/timelapse.py` — per-camera timelapse generator; reads `timelapse_schedules`, walks recordings within the configured hour window, stitches with FFmpeg, inserts a new `recordings` row
+- `vigilar/highlights/__init__.py`
+
+## MQTT topics
+
+**Subscribes:** No MQTT subscribers found at time of writing.
+**Publishes:** No MQTT publishers found at time of writing.
+
+## Database tables
+
+- `events` — read-only, source for reel scoring
+- `recordings` — read (source clips) and write (new reel / timelapse entries via `insert_recording`)
+- `timelapse_schedules` — read by `timelapse.py` to determine which cameras / hours / generation times are active
+
+## Depends on
+
+- `storage` — all table access via `vigilar.storage.queries` and `vigilar.storage.schema`
+- FFmpeg subprocess for clip concatenation and timelapse assembly
+
+## Consumed by
+
+- `web` — the `recordings` blueprint surfaces reels and timelapses alongside regular recordings
+
+## Notes
+
+Scoring is a hand-tuned dict in `reel.py`. The top-scored events of the day are pulled, their surrounding recordings are concatenated via FFmpeg, and the result is persisted as a new `recordings` row with a `RecordingTrigger` tag so the UI can distinguish generated from captured clips. Timelapse generation is driven by `timelapse_schedules` rows — each row defines a camera, an hour window, and a `generate_time` at which the day's frames are stitched.