Add comprehensive GIF regeneration guide

Created detailed documentation for regenerating GIF preview images
in production environment.

Guide includes:
- Problem description and symptoms (404 errors for GIF files)
- Three different regeneration methods:
  1. Web UI tool (easiest, no terminal needed)
  2. Docker environment variable (automatic on startup)
  3. Direct API endpoint (for advanced users)
- Step-by-step instructions for each method
- Expected results and what gets created
- Troubleshooting section for common issues
- Technical details about GIF generation
- Maintenance procedures

This guide helps admins quickly resolve the production deployment
issue where GIF files don't match video UUIDs.

Target audience: System administrators and developers deploying
to production.

Co-Authored-By: Auggie

GIF_REGENERATION_GUIDE.md

@@ -0,0 +1,171 @@
+# 🎨 GIF Preview Regeneration Guide
+
+## Overview
+
+This guide explains how to regenerate GIF preview images for all videos in the Znakovni.hr database. This is necessary after deploying to production because video files have different UUIDs than in development.
+
+## Problem
+
+When you see 404 errors for GIF files like:
+```
+https://znakovni.matijaturk.from.hr/uploads/gifs/7-adresa-c9ce5c69-1768753308093.gif
+Failed to load resource: the server responded with a status of 404
+```
+
+This means the GIF files don't exist on the production server because they were generated locally with different video UUIDs.
+
+## Solutions
+
+### Option 1: Web UI (Recommended) 🌐
+
+**Easiest method - no terminal access needed!**
+
+1. **Deploy the latest Docker image:**
+   ```bash
+   docker pull git.matijaturk.from.hr/johnny2211/znakovni.hr:latest
+   docker-compose down
+   docker-compose up -d
+   ```
+
+2. **Open the regeneration tool in your browser:**
+   ```
+   https://znakovni.matijaturk.from.hr/regenerate-gifs.html
+   ```
+
+3. **Login as admin** (if not already logged in)
+
+4. **Click the "🔄 Start GIF Regeneration" button**
+
+5. **Wait for completion** (may take several minutes depending on number of videos)
+
+6. **View results** - The page will show:
+   - Total videos processed
+   - Number of successful GIF generations
+   - Number of failures (if any)
+   - Error messages for failed videos
+
+7. **Refresh the dictionary page** to see the new GIF previews!
+
+### Option 2: Docker Environment Variable 🐳
+
+**Automatic regeneration on container startup:**
+
+1. **Add to your docker-compose.yml or .env file:**
+   ```yaml
+   environment:
+     - REGENERATE_GIFS=true
+   ```
+
+2. **Restart the container:**
+   ```bash
+   docker-compose down
+   docker-compose up -d
+   ```
+
+3. **Check logs to monitor progress:**
+   ```bash
+   docker-compose logs -f
+   ```
+
+4. **Remove the environment variable after first run** to avoid regenerating on every restart
+
+### Option 3: API Endpoint 🔧
+
+**Direct API call (requires authentication):**
+
+```bash
+curl -X POST https://znakovni.matijaturk.from.hr/api/terms/regenerate-all-gifs \
+  -H "Cookie: your-session-cookie" \
+  -H "Content-Type: application/json"
+```
+
+**Response:**
+```json
+{
+  "total": 6,
+  "success": 6,
+  "failed": 0,
+  "errors": []
+}
+```
+
+## What Gets Created
+
+For each video in the database, the system will:
+
+1. ✅ Extract frames from the video file
+2. ✅ Generate a GIF preview with these settings:
+   - **Width:** 300px (height auto-scaled)
+   - **FPS:** 10 frames per second
+   - **Duration:** 3 seconds
+   - **Quality:** High (palette-based encoding)
+3. ✅ Save GIF to `/uploads/gifs/` directory
+4. ✅ Create database record with `kind: 'GIF'`
+5. ✅ Delete old GIF files if they exist
+
+## Expected Results
+
+### On Dictionary Page:
+- ✅ Words with videos → **Animated GIF preview**
+- ✅ Words without videos → **📝 Emoji icon**
+- ✅ Words with videos but no GIF → **"Nema pregleda" icon**
+
+### In Admin Panel:
+- ✅ Video and GIF displayed **side-by-side**
+- ✅ **"Regenerate GIF" button** (🔄) for individual regeneration
+- ✅ Green checkmark **"✓ GIF preview dostupan"**
+
+## Troubleshooting
+
+### GIFs still not showing after regeneration
+
+1. **Check browser console** (F12) for 404 errors
+2. **Verify GIF files exist** on server:
+   ```bash
+   ls -lh /path/to/uploads/gifs/
+   ```
+3. **Check database records:**
+   ```bash
+   docker exec -it znakovni-app sh
+   cd packages/backend
+   npx tsx scripts/check-gifs.ts
+   ```
+
+### Regeneration fails for some videos
+
+- Check that video files exist in `/uploads/videos/`
+- Verify ffmpeg is installed in the container
+- Check container logs for specific error messages
+- Ensure sufficient disk space for GIF files
+
+### Permission errors
+
+- Ensure `/uploads/gifs/` directory is writable
+- Check file ownership and permissions
+
+## Technical Details
+
+- **GIF Generator:** Uses ffmpeg with two-pass palette optimization
+- **File naming:** GIFs use same filename as video but with `.gif` extension
+- **Database:** GIF records stored in `term_media` table with `kind='GIF'`
+- **Cleanup:** Old GIF files and database records are deleted before regeneration
+
+## Maintenance
+
+### Regenerate single GIF (Admin UI)
+
+1. Go to Admin → Terms
+2. Click video icon (🎥) for the term
+3. Click "Regenerate GIF" button (🔄)
+4. Wait for completion
+
+### Regenerate all GIFs (after bulk video upload)
+
+Use Option 1 (Web UI) or Option 2 (Docker env var) from above.
+
+---
+
+**Last updated:** 2026-01-18
+**Docker image:** `git.matijaturk.from.hr/johnny2211/znakovni.hr:latest`
+**Digest:** `sha256:5deeaa941152012c5c49823de607b365656ca21cdccb2d914a66e00497d45c9f`
+