fix(scan): fixed auto index and precache

app/main.py

@@ -331,10 +331,24 @@ def startup():
     app_logger.info(f"SQLite version: {sqlite_version}")
     app_logger.info(f"SQLite FTS5: {'ENABLED' if db.has_fts5() else 'DISABLED'}")
 
-    if AUTO_INDEX_ON_START:
+    # Check if database has any items
+    conn = db.connect()
+    try:
+        has_any = conn.execute("SELECT EXISTS(SELECT 1 FROM items LIMIT 1)").fetchone()[0] == 1
+    finally:
+        conn.close()
+
+    # Determine if we need to run a scan
+    should_scan = AUTO_INDEX_ON_START or not has_any
+
+    if should_scan:
         _start_scan(force=True)
-        return
-    # Run thumbnails pre-cache at startup even if no scan runs    
+        # Note: if PRECACHE_THUMBS=true, thumbnails will be generated during the scan
+    else:
+        _set_status(running=False, phase="idle", total=0, done=0, current="", ended_at=time.time())
+
+    # Run thumbnails pre-cache at startup if requested
+    # This runs independently of any scan that may have occurred
     if PRECACHE_ON_START and not _INDEX_STATUS["running"] and not _THUMB_STATUS["running"]:
         t = threading.Thread(target=_run_precache_thumbs, args=(THUMB_WORKERS,), daemon=True)
         t.start()
@@ -353,18 +367,6 @@ def startup():
         _LIBRARY_WATCHER.start()
         app_logger.warning(f"✓ Filesystem watcher started monitoring: {LIBRARY_DIR}")
 
-
-    conn = db.connect()
-    try:
-        has_any = conn.execute("SELECT EXISTS(SELECT 1 FROM items LIMIT 1)").fetchone()[0] == 1
-    finally:
-        conn.close()
-
-    if not has_any:
-        _start_scan(force=True)
-    else:
-        _set_status(running=False, phase="idle", total=0, done=0, current="", ended_at=time.time())
-
 @app.on_event("shutdown")
 def shutdown():
     """Clean up resources on shutdown."""

docs/configuration.md

@@ -42,4 +42,53 @@ For very large collections, some defaults should be adjusted to avoid long start
 - For private servers behind a VPN, you can disable auth: `DISABLE_AUTH=true`  
 - Otherwise, keep Basic Auth enabled (`OPDS_BASIC_USER` / `OPDS_BASIC_PASS`)
 
-These settings ensure the container starts faster, avoids unnecessary reprocessing, and lets you control when heavy tasks (indexing, thumbnailing) happen.
+These settings ensure the container starts faster, avoids unnecessary reprocessing, and lets you control when heavy tasks (indexing, thumbnailing) happen.
+
+### 💡 Common Configuration Scenarios
+
+Here are some typical use cases and their recommended settings:
+
+#### Scenario 1: Generate Thumbnails at Startup (Without Reindexing)
+**Use case:** You want to pre-cache thumbnails when the container starts, but don't need to reindex the library.
+
+```yaml
+AUTO_INDEX_ON_START: "false"    # Don't reindex on startup
+PRECACHE_ON_START: "true"       # Run thumbnail pre-cache at startup
+PRECACHE_THUMBS: "false"        # Not relevant (no reindex happening)
+```
+
+This is useful when you've already indexed your library and just want to ensure thumbnails are ready.
+
+#### Scenario 2: Reindex + Generate Thumbnails During Scan
+**Use case:** You want to reindex the library and generate thumbnails as part of the scan process.
+
+```yaml
+AUTO_INDEX_ON_START: "true"     # Reindex library on startup
+PRECACHE_THUMBS: "true"         # Generate thumbnails during reindex
+PRECACHE_ON_START: "false"      # Don't run separate thumbnail job
+```
+
+This is the most common setup for initial library setup or when you want everything fresh on each restart.
+
+#### Scenario 3: Reindex First, Then Generate Thumbnails Separately
+**Use case:** You want to reindex quickly without thumbnails, then run a separate thumbnail generation job.
+
+```yaml
+AUTO_INDEX_ON_START: "true"     # Reindex library on startup
+PRECACHE_THUMBS: "false"        # Skip thumbnails during reindex (faster)
+PRECACHE_ON_START: "true"       # Run separate thumbnail job after
+```
+
+This is useful for very large libraries where you want the index ready quickly, and can let thumbnails generate in the background afterward.
+
+#### Scenario 4: Manual Control (Recommended for Large Libraries)
+**Use case:** You have a large library and want to control indexing and thumbnails manually via the dashboard.
+
+```yaml
+AUTO_INDEX_ON_START: "false"    # Don't reindex on startup
+PRECACHE_ON_START: "false"      # Don't pre-cache on startup
+PRECACHE_THUMBS: "true"         # Generate thumbs when manual reindex is triggered
+ENABLE_WATCH: "true"            # Auto-update index on file changes
+```
+
+This gives you the fastest startup time and lets you trigger heavy operations only when needed via the dashboard buttons.