# Helper-First per SVG

Usa questa reference quando il task richiede calcoli geometrici, parametrici o
trasformazioni deterministiche per cui esiste un helper in `skills/svg/tools/`.

## Discovery

Ordine consigliato:

1. leggi `skills/svg/tools/catalog.json`;
2. scegli il tool in base a `use_when` e `keywords`;
3. apri `skills/svg/tools/README.md` solo se servono parametri o limiti;
4. esegui il comando reale;
5. conserva comando, output rilevante e path di eventuali artifact.

Per sviluppo o modifica del catalogo/helper, seguire anche
`docs/svg/svg-skill-maintenance-guide.md`.

Comandi utili:

```bash
Get-ChildItem skills/svg/tools -Filter *.js
node skills/svg/tools/superellipse.js --help
```

## Regola anti-bypass

Se un helper copre il caso, non partire da calcolo manuale o implementazione ad
hoc. Il valore della skill e' rendere ripetibili le parti numeriche fragili.

Fallback manuale ammesso solo quando:

- nessun helper copre il task;
- l'helper fallisce con errore esplicito;
- l'input richiede una scelta progettuale fuori dal contratto del tool.

In caso di fallback, riporta sempre:

- helper valutato;
- motivo del mancato uso;
- alternativa usata;
- rischio residuo.

## Contratto minimo helper

Ogni helper deve avere:

- CLI esplicita con parametri validati;
- output JSON o SVG consumabile;
- errori espliciti con exit code non zero;
- smoke happy-path + input invalido;
- check di determinismo quando il calcolo produce path o coordinate critiche;
- fallback documentale se non disponibile.

## Mappa tool

| Intento | Tool | Output principale |
| --- | --- | --- |
| superellipse/supercerchio | `superellipse.js` | `path_d` o SVG |
| punti su arco | `arc-points.js` | `points[]`, `path_d` |
| distribuzione su cerchio/arco | `polar-distribute.js` | `points[]` |
| handle cubic Bezier | `bezier-handles.js` | `c1`, `c2`, `cubic_command` |
| calcolo viewBox | `fit-viewbox.js` | `viewBox_string` |
| rettangolo arrotondato | `rounded-corners.js` | `path_d` |

## Smoke consigliati

Per regressione rapida:

```bash
node scripts/smoke-svg-superellipse.js
node scripts/smoke-svg-phase3-helpers.js
```

Se l'ambiente sandbox blocca `spawnSync(process.execPath)` con `EPERM`, riesegui
fuori sandbox prima di classificare il fallimento come bug del tool.