chore(release): v1.1.2 bump, notes/template + README updates, Docker Hub description updater, headless/docs tweaks

code/main.py

@@ -35,11 +35,41 @@ def _ensure_data_ready() -> None:
 
     # Ensure required CSVs exist and are tagged before proceeding
     try:
+        import time
+        import json as _json
+        from datetime import datetime as _dt
         cards_path = os.path.join(CSV_DIRECTORY, 'cards.csv')
+        flag_path = os.path.join(CSV_DIRECTORY, '.tagging_complete.json')
+        refresh_needed = False
+        # Missing CSV forces refresh
         if not os.path.exists(cards_path):
             logger.info("cards.csv not found. Running initial setup and tagging...")
+            refresh_needed = True
+        else:
+            # Stale CSV (>7 days) forces refresh
+            try:
+                age_seconds = time.time() - os.path.getmtime(cards_path)
+                if age_seconds > 7 * 24 * 60 * 60:
+                    logger.info("cards.csv is older than 7 days. Refreshing data (setup + tagging)...")
+                    refresh_needed = True
+            except Exception:
+                pass
+        # Missing tagging flag forces refresh
+        if not os.path.exists(flag_path):
+            logger.info("Tagging completion flag not found. Performing full tagging...")
+            refresh_needed = True
+        if refresh_needed:
             initial_setup()
             tagger.run_tagging()
+            # Write tagging completion flag
+            try:
+                os.makedirs(CSV_DIRECTORY, exist_ok=True)
+                with open(flag_path, 'w', encoding='utf-8') as _fh:
+                    _json.dump({
+                        'tagged_at': _dt.now().isoformat(timespec='seconds')
+                    }, _fh)
+            except Exception:
+                logger.warning("Failed to write tagging completion flag (non-fatal).")
             logger.info("Initial setup and tagging completed.")
     except Exception as e:
         logger.error(f"Failed ensuring CSVs are ready: {e}")