From 4f6967258f1b8f8cb153641c72a90165bcbd06a0 Mon Sep 17 00:00:00 2001
From: Holden <holden@arch.fyi>
Date: Fri, 12 Jun 2026 15:50:51 +0000
Subject: [PATCH] docs: update .env.example and README to reflect VERBOSE and
 current defaults

- .env.example: add VERBOSE, remove active AUTO_MODE=true (now TTY-detected),
  comment out FORCE_CPU/ENABLE_CACHE default values, update CRON_SCHEDULE
  section to document all three modes
- README: clarify that log file is always DEBUG regardless of VERBOSE

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .env.example | 18 +++++++++++++-----
 README.md    |  2 +-
 2 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/.env.example b/.env.example
index 5ee4794..86702f7 100644
--- a/.env.example
+++ b/.env.example
@@ -4,7 +4,10 @@ API_KEY=your-immich-api-key
 FRIGATE_URL=http://192.168.1.10:5000
 
 # ── Mode & Strategy ───────────────────────────────────────────────────────────
-AUTO_MODE=true
+# Auto mode is active by default when no TTY is present (Docker/cron).
+# Set AUTO_MODE=true to force auto mode even in an interactive terminal.
+# AUTO_MODE=true
+# VERBOSE=true                # Enable DEBUG-level console output (log file is always DEBUG)
 # TRAINING_MODE: face = upload to Frigate face recognition API
 #                object = save crops to output dir for manual Frigate placement
 TRAINING_MODE=face
@@ -29,8 +32,8 @@ STRATEGY=auto
 # MAX_AUTO_IMAGES=80          # Hard cap on auto-diversity selection (default: 80)
 
 # ── Caching & Models ──────────────────────────────────────────────────────────
-FORCE_CPU=false
-ENABLE_CACHE=true
+# FORCE_CPU=true              # Disable GPU, fall back to CPU
+# ENABLE_CACHE=false          # Disable embedding cache (default: true)
 CACHE_DIR=/app/.if_cache
 HF_HOME=/models/huggingface
 INSIGHTFACE_HOME=/models/.insightface
@@ -41,5 +44,10 @@ INSIGHTFACE_HOME=/models/.insightface
 # RESET_PERSON=John           # Clear uploaded+rejected history for one person
 
 # ── Scheduling ────────────────────────────────────────────────────────────────
-# Cron expression (unset = run once and exit)
-CRON_SCHEDULE=0 3 * * 0     # Every Sunday at 3 AM
+# CRON_SCHEDULE controls container lifetime:
+#   unset          — run once on startup, then exit
+#   empty string   — stay alive, run nothing (trigger manually: docker exec -it winnow winnow)
+#   cron expression — run on startup, then on schedule
+# CRON_SCHEDULE=              # Manual mode (keep alive, no auto-run)
+# CRON_SCHEDULE=0 3 * * 0    # Every Sunday at 3 AM
+# CRON_SCHEDULE=0 3 1 * *    # First of every month
diff --git a/README.md b/README.md
index fa1386a..a7ee3b6 100644
--- a/README.md
+++ b/README.md
@@ -169,7 +169,7 @@ The first run after a fresh install downloads the embedding models (~1-2 GB). Su
 | Variable | Default | Description |
 | :--- | :--- | :--- |
 | `AUTO_MODE` | *(auto)* | Force non-interactive mode even in a terminal; auto-detected otherwise (no TTY = auto) |
-| `VERBOSE` | `false` | Set to `true` to enable DEBUG-level console output |
+| `VERBOSE` | `false` | Set to `true` to enable DEBUG-level console output (the log file is always DEBUG) |
 | `TRAINING_MODE` | `face` | `face` — upload crops to Frigate API; `object` — save crops to disk |
 | `STRATEGY` | `auto` | `auto` (adaptive), `standard` (30 images), `broad` (100 images) |
 | `LIMIT` | *(unset)* | Exact image count — overrides `STRATEGY` |