novafarma/docs/VISUAL_MANAGER_QUICKSTART.md

# 🎨 Visual Asset Manager - Quick Start Guide

**Status**: ✅ LIVE  
**URL**: `tools/visual_asset_manager.html`  
**Assets**: 1,166 slik

---

## 🚀 HITRI START

### 1. Odpri Visual Asset Manager
```bash
open tools/visual_asset_manager.html
```

**ALI** preko serverja:
```bash
cd tools
python3 -m http.server 8080
# Odpri: http://localhost:8080/visual_asset_manager.html
```

---

## 🎯 KAJ LAHKO NARDI

### 📁 Sidebar (Leva Stran)

**Statistika:**
- Skupaj assetov: 1,166
- Prikazanih: Live count
- Velikost: 576 MB

**Kategorije z Filtri:**
- 👤 Liki (31)
- 🏠 Zgradbe (54)
- ⚔️ Oprema (48)
- 🌿 Narava (289)
- 🛋️ Notranjost (57)
- 🗺️ Teren (30)
- 🎨 UI (34)

**Akcijski Gumbi:**
- 🔍 **Code Deep Scan** - preveri kodo za napake
- ✅ **Validate Paths** - preveri če vse poti obstajajo
- 📂 **Organize Assets** - organiziraj v folderje
- 🗑️ **Delete Selected** - izbriši označene

---

### 🖼️ Asset Cards (Vsaka Slika)

**3 Gumbi pri vsaki sliki:**

1. **🗑️ Delete** (rdeč)
   - Izbriše asset (z potrditev)
   - Uporabno za cleanup Duplicates

2. **🔄 Re-roll** (zelen)
   - Regenerira asset z novim promptom
   - Če ti verzija ni všeč

3. **👁️ View Full** (moder)
   - Odpre modal s celotnim pregledom
   - Pokaže full resolution sliko
   - Prikaže path in velikost

---

### 🔍 Toolbar (Zgoraj)

**Search Box:**
- Išči po imenu datoteke
- Live filtering
- Primer: "kai", "zombie", "terrain"

**View Toggle:**
- ⊞ **Grid View** - card layout (default)
- ☰ **List View** - seznam format

---

## 🛠️ FUNKCIJE

### 1️⃣ Delete Asset

```
1. Klikni 🗑️ Delete na asset cardu
2. Confirm dialog
3. Asset se remove iz galleryja in filesystem
```

**Uporaba:**
- Cleanup duplicates
- Remove bad generations
- Cleanup old test assets

---

### 2️⃣ Re-roll Asset

```
1. Klikni 🔄 Re-roll
2. Confirm dialog
3. System regenerira asset z novim random seed
4. Stara verzija se nadomesti
```

**Kdaj uporabiti:**
- Asset ni v pravem stilu
- Zahteva drugačne detajle
- Potrebuješ varianti

---

### 3️⃣ Code Deep Scan

```bash
# ALI direktno iz terminala:
python3 scripts/deep_code_scanner.py
```

**Kaj scan naredi:**
- ✅ Preveri vse asset reference v kodi
- ✅ Najde broken paths
- ✅ Preveri naming conventions
- ✅ Otkrije duplicate file sizes
- ✅ Najde large files (>1MB)
- ✅ Generira JSON report

**Report lokacija:**
`docs/CODE_SCAN_REPORT.json`

**Primer Output:**
```
📊 SCAN SUMMARY
Total Assets: 1,166
Code References: 210
Errors: 1 (200 broken references)
Warnings: 1 (2,322 naming issues)
Suggestions: 1 (168 possible duplicates)
Status: ❌ FAIL
```

---

### 4️⃣ Validate Paths

**Funkcija:**
- Preveri če vsi referenced assets obstajajo
- Cross-reference koda ↔ filesystem
- Poročilo manjkajočih datotek

**Upoabra:**
```
Klikni "✅ Validate Paths" v sidebaru
```

---

### 5️⃣ Organize Assets

**Izvede:**
- Runs `smart_asset_organizer.py`
- Premakne files v kategorije
- Rename z smart naming
- Ustvari manifest

**Uporaba:**
```
Klikni "📂 Organize Assets" v sidebaru
```

---

## 📊 DEEP CODE SCAN - Razlaga Rezultatov

### ❌ ERRORS

**BROKEN_REFERENCES**
```
Found: 200 broken references
```

**Kaj to pomeni:**
- Koda reference asset, ki NE obstaja
- Napačna pot
- Datoteka izbrisana

**Kako popraviti:**
1. Poglej `CODE_SCAN_REPORT.json`
2. Poišči section "errors"
3. Vsaka broken ref je listed
4. Update kodo ALI re-generate asset

**Primer broken ref:**
```javascript
// Koda:
sprite: 'assets/npc_child.png'  // ❌ Ta file ne obstaja

// Fix:
sprite: 'assets/slike 🟢/liki/npcs/npc_child_style32.png'  // ✅
```

---

### ⚠️ WARNINGS

**NAMING_ISSUES**
```
Found: 2,322 naming issues
```

**Kaj to pomeni:**
- Assets ne sledijo naming convention
- Timestamps v imenih
- Manjka category prefix
- Manjka `_style32` suffix

**Kako popraviti:**
```bash
# Avtomatska popravka:
python3 scripts/smart_asset_organizer.py --execute
```

---

### 💡 SUGGESTIONS

**POSSIBLE DUPLICATES**
```
Found: 168 groups of same-size files
```

**Kaj to pomeni:**
- Datoteke z exactly isto velikostjo
- Mogoče duplicates (lahko so legit različne)

**Kako preveriti:**
1. Poglej `CODE_SCAN_REPORT.json`
2. Section "suggestions"
3. Manually preglej suspected duplicates
4. Uporabi Visual Asset Manager za delete

---

## 🔧 TROUBLESHOOTING

### Manager se ne odpre?
```bash
# Uporabi local server:
cd tools
python3 -m http.server 8080
open http://localhost:8080/visual_asset_manager.html
```

### Slike se ne prikazujejo?
- Preveri da so paths relativni od project root
- Browser console (F12) za napake
- Preveri CORS permissions (use local server)

### Deep Scan crashne?
```bash
# Debug mode:
python3 -v scripts/deep_code_scanner.py
```

### Delete ne dela?
- Manager je trenutno frontend-only
- Za actual deletion uporabi terminal:
```bash
rm "path/to/asset.png"
```

---

## 📝 WORKFLOW PRIMER

### Scenario: Cleanup Duplicates

```
1. Odpri Visual Asset Manager
2. Klikni "🔍 Code Deep Scan"
3. Počakaj scan complete (3s toast notification)
4. Odpri docs/CODE_SCAN_REPORT.json
5. Poglej "suggestions" → duplicates
6. Nazaj v Manager, search za duplicate names
7. Uporabi 🗑️ Delete za removes
8. Run "✅ Validate Paths" da confirm
```

---

### Scenario: Fix Broken References

```
1. Run Deep Code Scan
2. Odpri CODE_SCAN_REPORT.json
3. Poglej "errors" → "BROKEN_REFERENCES"
4. Za vsako broken ref:
   a. Najdi kodo kjer je referenced
   b. Update path
   c. ALI re-generate missing asset
5. Re-run scan da confirm fixed
```

---

### Scenario: Standardize Names

```
1. Run: python3 scripts/smart_asset_organizer.py
2. Review what would change (dry run)
3. Run: python3 scripts/smart_asset_organizer.py --execute
4. Run Deep Code Scan ponovno
5. Naming issues bi morale bit 0
```

---

## 🎯 BEST PRACTICES

### Pred Veliko Asset Generation:
```bash
# 1. Backup
cp -r assets/ assets_backup_$(date +%Y%m%d)/

# 2. Run scan
python3 scripts/deep_code_scanner.py

# 3. Fix existing issues
# 4. Commit clean state
git add . && git commit -m "cleanup: before asset generation"
```

### Po Asset Generation:
```bash
# 1. Organize
python3 scripts/smart_asset_organizer.py --execute

# 2. Scan
python3 scripts/deep_code_scanner.py

# 3. Review in Visual Manager
open tools/visual_asset_manager.html

# 4. Commit
git add . && git commit -m "assets: new batch organized"
```

---

## 📈 TRENUTNO STANJE

**Scan Results (2026-01-04):**
- ✅ Assets: 1,166 datotek
- ❌ Broken refs: 200
- ⚠️ Naming issues: 2,322
- 💡 Duplicates: 168 groups

**Priority Actions:**
1. Fix broken references (200)
2. Run smart organizer (fix 2,322 names)
3. Review duplicates manually
4. Re-scan to verify

---

## 🔗 RELATED FILES

- `tools/visual_asset_manager.html` - Main UI
- `tools/asset_gallery.html` - Simple gallery (read-only)
- `scripts/deep_code_scanner.py` - Code analysis
- `scripts/smart_asset_organizer.py` - Auto organization
- `docs/CODE_SCAN_REPORT.json` - Latest scan results
- `docs/VISUAL_ASSET_SYSTEM.md` - Full documentation

---

**Version**: 1.0  
**Last Updated**: 2026-01-04  
**Maintainer**: Antigravity Agent