# Agent Instructions

Sokko G est une webapp React + Vite + Sass centrée sur des toolboxes locales et des pages de jeu.

## Références projet

Avant de modifier un outil toolbox, le stockage IndexedDB, l'import/export ou les formats de données, lire :

- `docs/STORAGE_SCHEMA.md`
- `docs/FEATURE_CHECKLIST.md`

Après ce type de modification, mettre à jour ces documents si le format ou le workflow change.

## Contenu éditable

Le contenu éditorial du site doit rester dans :

- `website/public/data/site.json`
- `website/public/data/<gameId>/...`

Ne pas réintroduire de fallback massif type `DEFAULT_SITE_CONTENT` dans le code React. `site.json` est la source de vérité et `npm run check` doit échouer si le contenu requis est invalide.

## En-têtes de fichiers

Chaque nouveau fichier source ou test doit commencer par un commentaire court `Rôle : ...` décrivant ce qu'il gère.

- mettre cet en-tête à jour si la responsabilité du fichier change ;
- garder l'intro concise, une ou deux lignes maximum ;
- utiliser `// Rôle : ...` dans les fichiers JS, JSX, MJS et SCSS.

## Outils toolbox

Chaque outil toolbox doit rester dans son propre fichier dans :

```text
website/src/features/toolboxes/modules/
```

Quand un outil est ajouté ou modifié :

- déclarer l'outil dans `website/src/features/toolboxes/modules/index.jsx` ;
- ajouter les textes dans `website/public/data/site.json` ;
- mettre à jour la validation dans `tests/helpers/data-validation.mjs` ;
- mettre à jour la structure IndexedDB dans `docs/STORAGE_SCHEMA.md` si nécessaire ;
- vérifier l'affichage page toolbox et panneau latéral.

## Style

Le style est en Sass dans `website/src/styles/`.

Privilégier :

- les tokens existants ;
- les classes de boutons existantes ;
- les patterns visuels déjà présents pour les cards, panels, badges, scrollbars et hovers.

Éviter les styles isolés qui ne réutilisent pas le thème.

## Validation

Avant de terminer une modification significative, lancer :

```bash
npm run check
```

Le check couvre la génération des index de listes, les tests et le build de production.

## Pré-push check

Quand l'utilisateur indique qu'il va push, faire une passe globale avant de conclure.

Vérifier et corriger si nécessaire :

- code mort, imports inutilisés, fonctions inutilisées, styles devenus obsolètes ;
- duplication de code ou de style pouvant être factorisée sans complexifier le projet ;
- composants qui utilisent des classes trop spécifiques alors qu'un pattern général existe déjà ;
- incohérences entre boutons, badges, cards, panels, hovers, focus states et scrollbars ;
- cohérence entre `website/public/data/site.json`, les validations et les textes utilisés ;
- cohérence entre `docs/STORAGE_SCHEMA.md` et les normalisations IndexedDB réelles ;
- import/export des toolboxes quand la structure de données a changé ;
- champs inutiles persistés dans IndexedDB ou dans les exports ;
- fichiers générés attendus, notamment les index de listes ;
- optimisations simples de performance : recalculs au render, listeners non nettoyés, observers, effets CSS lourds appliqués en masse.

Utiliser en priorité :

```bash
rg
git status --short
git diff --stat
npm run check
```

Ne pas faire de refactor large sans bénéfice clair. Garder les corrections pré-push ciblées, vérifiables et faciles à relire.