docs: annotate known limitations and Frigate API improvement hooks

Adds inline LIMITATION / TODO(frigate-api) comments at each specific
code site rather than a separate doc that would drift from the code.

frigate_api.py — recognize_face:
  Mean-embedding limitation: score reflects the arithmetic mean of all
  training embeddings. A bimodal set (frontals + profiles) has a mean
  between clusters, making both ends look more novel than they are.
  Fixable if Frigate exposes per-file embeddings for nearest-neighbour
  comparison.

frigate_api.py — get_all_frigate_person_files:
  "train" key exclusion is a hardcoded string. If Frigate adds other
  special top-level keys in /api/faces they'll be silently treated as
  person names. Needs a typed schema when Frigate documents the contract.

executor.py — recognize_face call site:
  Async rebuild: each deletion triggers a background model rebuild in
  Frigate. Subsequent recognize calls in the same run return None
  (rebuild in progress), degrading quality replacement for later
  candidates. Fixable with a rebuild-complete signal from Frigate.

executor.py — effective_count / manual file handling:
  Manually-added files are invisible to diversity decisions. Winnow
  observes their effect only indirectly via the Frigate score, not by
  measuring their embedding distribution. Per-file embeddings from
  Frigate would allow direct diversity measurement against the full set.

executor.py — Frigate version assumption:
  All face training endpoints are v0.16+. No version check at startup;
  failures on older versions are opaque 404s.

cache.py — MODEL_VERSIONS:
  Version string is a hardcoded constant. Manual model file replacement
  (custom weights, InsightFace update) won't invalidate cached embeddings.
  Needs file-checksum-derived versioning or a CLEAR_EMBEDDING_CACHE flag.

diversity.py — thumbnail-resolution embeddings:
  Diversity selection runs InsightFace on preview thumbnails; the actual
  training crop comes from full-resolution originals. Negligible in
  practice but degrades if Immich preview quality is low.

winnow/cache.py

@@ -12,7 +12,13 @@ import numpy as np
 
 logger = logging.getLogger(__name__)
 
-# Model versions — bump these when the upstream model changes
+# Model versions — bump these when the upstream model changes.
+# LIMITATION — no automatic invalidation: if the user replaces the buffalo_l
+# model files on disk (e.g. custom weights, InsightFace update) without
+# changing INSIGHTFACE_HOME, the version string here stays "buffalo_l_v1" and
+# stale embeddings from the old model are served from cache indefinitely.
+# TODO: derive the version from a checksum of the model files, or expose a
+# --clear-cache / CLEAR_EMBEDDING_CACHE flag so users can force invalidation.
 MODEL_VERSIONS = {
     "insightface": "buffalo_l_v1",
     "immich": "immich_buffalo_l_v1",