sokko-g/AGENTS.md

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

Avant de modifier le style, les composants UI, les layouts, les boutons, cards, panels, hovers, scrollbars ou notifications, lire :

- `DESIGN_SYSTEM.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 à trois lignes maximum selon la complexité du fichier ;
- quand un fichier existant est modifié, vérifier si son en-tête mérite d'être précisé au-delà de la ligne générique initiale ;
- enrichir l'en-tête quand le fichier porte une logique transverse, un hook partagé, un format de données ou un comportement réutilisable ;
- ne pas allonger mécaniquement les en-têtes des fichiers simples : la précision doit aider à comprendre la responsabilité réelle du fichier ;
- utiliser `// Rôle : ...` dans les fichiers JS, JSX, MJS et SCSS.

## Hooks et comportements partagés

Quand un comportement est déjà couvert par un hook ou un helper partagé, privilégier son utilisation plutôt qu'une réimplémentation locale afin de garder une expérience homogène.

- pour la réorganisation par drag & drop, utiliser `useGroupedReorder` dès qu'il s'agit d'items, groupes, catégories, boundaries, parent/enfant ou listes horizontales/verticales ;
- réserver `usePointerReorder` au moteur bas niveau ou aux cas DOM très spécifiques qui ne correspondent pas au modèle applicatif de `useGroupedReorder` ;
- si une variation est nécessaire, vérifier d'abord si elle doit devenir une option du hook partagé ;
- demander ou expliciter le choix uniquement quand la variation est réellement métier et pourrait alourdir le hook ;
- éviter de dupliquer dans un outil une règle de reorder générique déjà prise en charge par le hook.

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

Quand la structure de données d'un outil change, ne pas prévoir de compatibilité legacy, de migration ou de tolérance d'anciens formats, sauf demande explicite. Le format documenté dans `docs/STORAGE_SCHEMA.md` doit rester le format cible strict.

## Style

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

`DESIGN_SYSTEM.md` est la référence visuelle du projet et doit rester synchronisé avec les patterns réellement utilisés.

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.

## Serveur de développement

Si le port `5173` est déjà occupé, considérer qu'un `npm run dev` est probablement déjà en cours. Ne pas lancer automatiquement un nouveau serveur sur `5174` dans ce cas.

Quand une vérification navigateur est nécessaire après des modifications, utiliser l'instance déjà ouverte sur `http://localhost:5173` si elle répond.

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

Après lecture du diff pré-push, proposer un exemple de message de commit en anglais, concis et représentatif des changements réellement présents.

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

<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:970c3bf2 -->
## Beads Issue Tracker

This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.

### Quick Reference

```bash
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work
```

### Rules

- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files

**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

## Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

## Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

1. **File issues for remaining work** - Create beads for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **Handle git/sync by active profile**:
   ```bash
   # Conservative/minimal/default: report status and proposed commands; wait for approval.
   git status

   # Team-maintainer opt-in only, unless current instructions forbid it:
   git pull --rebase
   bd dolt push
   git push
   git status
   ```
5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step

**Critical rules:**
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION -->

<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
## Beads Issue Tracker

Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations.

### Quick Reference

```bash
bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context
```

### Rules

- Use `bd` for all task tracking; do not create markdown TODO lists.
- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.

**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.
<!-- END BEADS CODEX SETUP -->