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

open tools/visual_asset_manager.html

ALI preko serverja:

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

# 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:

// 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:

# 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?

# 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?

# Debug mode:
python3 -v scripts/deep_code_scanner.py

Delete ne dela?

• Manager je trenutno frontend-only
• Za actual deletion uporabi terminal:

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:

# 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:

# 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