docs: add health subsystem reference

docs/architecture/subsystems/health.md

@@ -0,0 +1,39 @@
+# health
+
+## Purpose
+
+Self-monitoring and housekeeping. Periodically checks disk usage and MQTT reachability, publishes an aggregated system-health snapshot, auto-prunes old recordings when the disk gets full, builds a daily "what happened today" digest, and drives the scheduled firing of highlight-reel and timelapse jobs.
+
+## Key files
+
+- `vigilar/health/monitor.py` — `HealthMonitor` subsystem loop: disk check every 5 min, MQTT port check every 30 s, status publish every 10 s, daily reel trigger, per-minute timelapse schedule check
+- `vigilar/health/pruner.py` — `auto_prune` / `find_prunable_recordings`; deletes oldest unstarred recordings (and their thumbnails) until usage is back under target
+- `vigilar/health/digest.py` — `build_digest`: counts person/vehicle events, pet and wildlife sightings, and recording totals over a time window for notification digests
+- `vigilar/health/__init__.py`
+
+## MQTT topics
+
+**Subscribes:** none
+**Publishes:**
+- `vigilar/system/health` — rolled-up health status with per-check breakdown
+
+## Database tables
+
+- `recordings` — read in pruner (`starred = 0`, oldest first) and deleted row-by-row once the file is unlinked
+- `events`, `pet_sightings`, `wildlife_sightings`, `recordings` — read in `digest.py`
+- `timelapse_schedules` — read indirectly via `vigilar.highlights.timelapse.check_schedules`
+
+## Depends on
+
+- `storage` — all DB access
+- `highlights` — calls `generate_daily_reel` and `check_schedules` on schedule
+- Filesystem — `shutil.disk_usage` on `system.data_dir`
+
+## Consumed by
+
+- `web` — surfaces `vigilar/system/health` and the digest output in the system blueprint
+- `events` — ingests `vigilar/system/health` off the bus (subscribes to everything)
+
+## Notes
+
+The pruner is keyed on percentages, not gigabytes: it checks `config.health.disk_warn_pct` / `disk_critical_pct` for alerting and prunes toward `config.health.auto_prune_target_pct`. It never deletes a recording whose `starred` flag is set, and it unlinks the thumbnail alongside the video. The monitor owns the scheduling clock for both `generate_daily_reel` (fires when wall-clock matches `highlights.generate_time`) and timelapse generation (polls `check_schedules` every 60 s), so neither `highlights/` nor its cron is wired directly into the supervisor.