Add starred cloud photos and opt-in seven-day random upload retention

docs/PHOTO_SOURCES.md

@@ -161,3 +161,25 @@ Random rendering tries at most five distinct candidates before any device write,
 skipping only invalid or unavailable images. Explicit selections never fall back.
 Operation `result.photo_attempts` records source-relative item IDs, names, status
 and stable error codes, including failures. This does not retry upload or switch.
+
+### Starred cloud photos and seven-day retention
+
+Automation `cleanup_unstarred` is opt-in and defaults to false. It is valid only
+for random photo-source jobs. New uploads retain their confirmed cloud image ID
+and an expiry seven days after upload. Existing images are never backfilled.
+The cloud gallery's star button stores a Frame Flow star in SQLite; it does not
+modify Synology Photos favorites or synchronize with KoKonna app favorites.
+Starred images stay; unstarred overdue images are eligible for deletion from the
+KoKonna cloud gallery. NAS originals and local Frame Flow assets remain.
+
+The scheduler checks hourly, queues at most 20 deletions per cycle, and rechecks
+stars and protection when executing. Current, previous/restore, override,
+playlist and explicit job image references are protected. Offline devices and
+write-disabled services skip cleanup. A failed or unknown deletion is retained
+for investigation and is not retried automatically. Unstarring an expired image
+makes it eligible at the next check. Removing a job does not cancel retention
+already assigned to its uploads; star these images to keep them.
+
+API: `PUT /api/v1/devices/{device_id}/images/{image_id}/star` with
+`{"starred": true}`; scope `images:write`. Gallery responses add `starred` and
+`expires_at`. All cleanup uses the existing operation queue, history and driver.