docs: add repository architecture and agent guidelines

AGENTS.md

@@ -0,0 +1,80 @@
+# Guide des agents Lardon3D
+
+## Validation obligatoire
+
+Avant livraison, exécuter réellement :
+
+```sh
+CC=clang meson setup build --wipe
+meson compile -C build -j8
+meson test -C build --print-errorlogs
+git diff --check
+```
+
+Pour les changements sensibles à la mémoire ou aux durées de vie, ajouter un
+build ASan/UBSan séparé. Pour toute concurrence, exécuter aussi TSan lorsque
+disponible. Ne jamais annoncer une vérification non exécutée.
+
+## Git et périmètre
+
+- Ne jamais utiliser `git add -A`.
+- Ne jamais ajouter ou modifier `scan3d/`, notamment
+  `scan3d/tri_photos.py`.
+- Ne faire ni commit ni push depuis le sandbox.
+- Préserver les changements existants hors ticket.
+- Fournir à la fin la liste exacte des fichiers appartenant au ticket.
+
+## Architecture à préserver
+
+- La TUI orchestre les entrées et ncurses ; le métier et le layout restent
+  séparés. Le layout dessine uniquement et ne modifie aucun état.
+- ncurses appartient exclusivement au thread principal.
+- Toute tâche possède une estimation immuable et une réservation valide avant
+  son exécution. Aucun callback ne démarre sans réservation active.
+- Le Resource Governor décide des budgets, slots et lots. Le scheduler applique
+  le FIFO et exécute le contrat ; il ne réinterprète jamais les ressources.
+- Les API à durée de vie complexe restent opaques, avec propriété et nettoyage
+  explicites.
+
+## Principes non négociables
+
+- La stabilité du système hôte et la réactivité de la TUI passent avant le
+  débit.
+- Aucun traitement lourd monolithique : utiliser des séquences adaptatives.
+- Budgets, files et buffers doivent être bornés.
+- La RAM d'un iGPU partagé appartient au budget RAM système.
+- La zram est un filet de sécurité, jamais un budget de travail.
+- Publier uniquement des sorties atomiques validées ; effectuer un rollback
+  ciblé sans toucher aux données antérieures.
+- Préserver des frontières permettant la reprise après interruption.
+- Le viewer reste séparé, lecteur de snapshots validés et non bloquant.
+
+## Contraintes de code
+
+- C17, Clang, Meson et ncursesw.
+- Aucune variable globale d'état.
+- Nettoyer explicitement chaque allocation, descripteur, mutex, condition et
+  thread.
+- Ne pas utiliser `system()` ni `popen()` dans le code de production.
+- Ne laisser aucun `TODO`, code mort ou dépendance inutile dans un ticket fini.
+- Préférer l'évolution minimale aux réécritures de modules validés.
+
+## État actuel
+
+- Moteur de tâches FIFO, un worker, pause et annulation coopératives.
+- Gouverneur thread-safe avec estimations, budgets et réservations opaques.
+- Scheduler relié au gouverneur ; réservation obligatoire avant callback.
+- Aucun DAG, aucune priorité, aucun pool de workers.
+- L'import asynchrone utilise encore son worker dédié et n'est pas migré vers
+  le scheduler générique.
+- Le viewer Vulkan n'est pas commencé.
+
+## Prochains tickets recommandés
+
+1. Sélectionner une tâche admissible sans blocage par la tête de file.
+2. Introduire le DAG et les dépendances.
+3. Persister les tâches et checkpoints de reprise.
+4. Orchestrer et mesurer les séquences adaptatives.
+5. Ajouter les pools bornés CPU, IO et GPU.
+6. Migrer l'import vers le scheduler générique.
+7. Ajouter la publication live validée, puis le viewer Vulkan séparé.