Add AGENTS.md with instructions for AI coding agents

Author: lyrixx

AGENTS.md

@@ -0,0 +1,82 @@
+# AGENT.md
+
+Instructions pour les agents IA travaillant sur ce projet.
+
+## Règle fondamentale : jamais de PHP/Node/Composer sur la machine hôte
+
+Tout passe par le container `builder`, via Castor :
+
+```bash
+castor builder -- bin/console cache:clear   # commande ponctuelle
+castor builder                              # shell interactif
+```
+
+Prérequis hôte uniquement : Docker, Bash, Castor.
+
+## Commandes essentielles
+
+```bash
+castor start                     # build + install + up + migrate
+castor stop                      # arrêter la stack
+castor logs [--service=service]  # logs (frontend, postgres, ...)
+castor app:install               # composer install + yarn/npm ci + importmap + qa:install
+castor app:db:migrate            # migrations Doctrine (alias: castor migrate)
+castor app:db:fixtures           # fixtures (alias: castor fixtures)
+castor postgres                  # psql interactif (user/db = app/app)
+```
+
+Docker / workers :
+
+```bash
+castor docker:build [--service=service]
+castor docker:up [--service=service]
+castor start-workers             # démarre les workers (profil worker)
+castor stop-workers
+```
+
+## Contextes Castor
+
+Le contexte modifie l'environnement d'exécution des tâches (`APP_ENV`,
+fichiers compose, etc.) :
+
+```bash
+castor --context=test qa:phpunit      # APP_ENV=test, pour les tests
+castor --context=ci ...               # comme test, adapté CI
+```
+
+Lancer toujours les tests et tout ce qui touche à la base de données avec
+`--context=test`. Sans option, c'est le contexte `default` qui s'applique.
+
+## Stack
+
+- Symfony dans `application/` (docroot = `application/public`)
+- PostgreSQL 16 : user/pass/db = `app`/`app`, DATABASE_URL déjà configurée
+- nginx + php-fpm (service `frontend`), router Traefik, HTTPS sur `<root_domain>` (voir `castor.php`)
+- Node/yarn uniquement dans le container `builder`
+
+## Qualité — avant de considérer une tâche terminée
+
+Les outils tournent dans le builder.
+
+```bash
+castor qa                 # tout : cs + phpstan + twig-cs + phpunit
+castor qa:cs [--dry-run]  # PHP-CS-Fixer (.php-cs-fixer.php)
+castor qa:phpstan [-b]    # PHPStan niveau 8 (phpstan.neon)
+castor qa:twig-cs         # Twig-CS-Fixer
+castor qa:phpunit         # PHPUnit (si présent dans application/)
+```
+
+Après toute modification de code PHP/Twig : `castor qa:cs --dry-run`,
+`castor qa:phpstan`, puis `castor qa:phpunit`.
+
+## Conventions
+
+1. **Ne pas invoquer `docker compose` à la main** : utiliser les fonctions
+   `docker_compose()` / `docker_compose_run()` de `.castor/docker.php`
+   pour écrire de nouvelles tâches.
+2. **Ne pas hardcoder de ports ni de noms de projet** : le support git worktree
+   isole automatiquement projet/volumes/ports. Utiliser `variable('project_name')` etc.
+3. Nouvelle tâche récurrente ? Tâche Castor (`castor.php` ou `.castor/*.php`),
+   pas script shell.
+4. Les dépendances des outils QA vivent dans `tools/<outil>/composer.json`
+   (pas dans `application/composer.json`).