# SVG Asset Discovery

Usa questa reference quando il task richiede di trovare o riusare asset SVG
locali, come icone Lucide o illustrazioni Open Peeps.

## Scenari adatti

Apri questa reference quando il prompt chiede:

- icone UI, toolbar, menu, stati, azioni o indicatori;
- pittogrammi semplici da adattare a palette/stroke;
- avatar, figure umane leggere o stati vuoti;
- placeholder grafici, illustrazioni minime o decorazioni riusabili;
- una base SVG locale da convertire in componente, ottimizzare o esportare.

Evita asset discovery quando il task richiede una scena originale complessa,
un'illustrazione con composizione narrativa o un asset che deve essere disegnato
da zero con geometria specifica. In quei casi usa il workflow di creazione SVG
semplice solo se il perimetro resta tecnico e verificabile.

## Sorgenti dichiarate

La lista delle librerie supportate e' in
`skills/svg/assets/libraries-catalog.json`.

Ogni libreria dichiara:

- `id`: nome stabile della libreria;
- `kind`: tipo di asset (`icons`, `illustrations`, ...);
- `bundled_root_path`: path locale primario dentro la skill;
- `workspace_fallback_paths`: path opzionali da provare nel progetto corrente;
- `license_*` e `attribution`: metadati da riportare quando rilevanti.

`lucide` e' gestita come submodule Git popolato nel checkout della skill.
`open-peeps` e' vendorizzata nel repository.

## Risoluzione path

1. Leggi `skills/svg/assets/libraries-catalog.json`.
2. Per ogni libreria richiesta, risolvi `bundled_root_path` rispetto a
   `skills/svg/`.
3. Considera il path usabile solo se esiste ed e' popolato con file SVG.
4. Se il path locale primario non e' usabile, prova l'indice workspace
   `skills/svg/assets/index.json`.
5. Se l'indice workspace manca o non e' valido, prova i
   `workspace_fallback_paths`.

Non trattare un path vuoto come successo. Riporta sempre lo stato usato:
`bundled`, `index`, `filesystem-fallback` oppure `missing-assets-root`.

## Uso dell'indice

`skills/svg/assets/index.json` contiene:

- metadati libreria;
- conteggio asset;
- path relativi degli SVG;
- keyword derivate da nome file e cartelle.

Usalo per cercare candidati senza scandire tutto il filesystem. Dopo aver
selezionato un asset, verifica comunque che il file esista prima di usarlo.

Per ricerca rapida usa il tool bundled nella skill:

```bash
node skills/svg/tools/search-assets.js --query "save icon" --kind icons --limit 5
```

Filtri utili:

- `--query`: termini liberi confrontati con nome, path e keyword;
- `--library`: limita a una libreria (`lucide`, `open-peeps`);
- `--kind`: limita per tipo (`icons`, `illustrations`);
- `--limit`: numero massimo risultati.

Il tool restituisce JSON con `matches[]`, `skill_relative_path`,
`absolute_path`, `exists`, `license`, `attribution` e `score`. In una skill
installata, `absolute_path` punta alla copia locale dell'asset dentro la skill,
non al workspace del progetto utente. Usa solo risultati con `exists: true`.

## Output

Quando riusi asset locali, includi nel report:

- libreria e asset selezionati;
- stato di risoluzione (`bundled`, `index`, `filesystem-fallback`,
  `missing-assets-root`);
- path effettivo usato;
- attribution/licenza quando l'output viene consegnato come asset riusabile.