From f846cb3d50bd8f445ec253c60dd709ea482ad7cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= <lyrixx@lyrixx.info>
Date: Sun, 30 Aug 2026 10:32:09 +0200
Subject: [PATCH] Add AGENTS.md and symlink CLAUDE.md to it

Adapted from jolicode/docker-starter's AGENTS.md to this project's
layout (no application/ subdir, cron service, no Node/yarn build step).
---
 AGENTS.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 84 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ab430e2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,83 @@
+# AGENTS.md
+
+Instructions for AI agents working on this project.
+
+## Fundamental rule: never run PHP/Composer on the host machine
+
+Everything goes through the `builder` container, via Castor:
+
+```bash
+castor builder -- bin/console cache:clear    # one-off command
+castor builder -- bin/console make:migration # one-off command
+```
+
+Host prerequisites only: Docker, Bash, Castor.
+
+## Essential commands
+
+```bash
+castor start                                 # build + install + up + migrate
+castor stop                                  # stop the stack
+castor logs [--service=service]              # logs (frontend, postgres, ...)
+castor app:install                           # composer install + importmap:install + qa:install
+castor app:db:migrate                        # Doctrine migrations (alias: castor migrate)
+castor app:db:fixtures                       # fixtures (alias: castor fixtures)
+castor app:cache-clear                       # clears var/cache (alias: castor cache-clear)
+castor postgres                              # opens a psql shell (alias: castor pg)
+```
+
+Docker / workers:
+
+```bash
+castor docker:build [--service=service]
+castor docker:up [--service=service]
+castor start-workers                         # start workers (worker profile, currently unused — see Stack)
+castor stop-workers
+```
+
+## Castor contexts
+
+The context changes how tasks are executed (`APP_ENV`, compose files, etc.):
+
+```bash
+castor --context=test qa:phpunit             # APP_ENV=test, for tests
+castor --context=ci ...                      # like test, tuned for CI
+```
+
+Always run tests and anything touching the database with `--context=test`.
+Without option, the `default` context applies.
+
+## Stack
+
+- Symfony at the repo root (docroot = `public/`)
+- PostgreSQL 16: user/pass/db = `qotd`/`qotd`/`qotd`
+- nginx + php-fpm (service `frontend`), Traefik router, HTTPS on `<root_domain>` (see `castor.php`)
+- `cron` service for scheduled tasks (e.g. posting the daily quote)
+- Symfony AssetMapper for JS/CSS (`importmap.php`) — no Node/yarn build step
+- A Messenger `worker` service is defined in `infrastructure/docker/docker-compose.yml` but
+  currently commented out (no async transport in use yet)
+
+## QA — before considering a task done
+
+Tools run inside the builder.
+
+```bash
+castor qa                                    # everything: cs + phpstan + twig-cs + phpunit
+castor qa:cs [--dry-run]                     # PHP-CS-Fixer (.php-cs-fixer.php)
+castor qa:phpstan [-b]                       # PHPStan level 8 (phpstan.neon)
+castor qa:twig-cs                            # Twig-CS-Fixer
+castor qa:phpunit                            # PHPUnit
+```
+
+After any PHP/Twig code change: `castor qa:cs --dry-run`,
+`castor qa:phpstan`, then `castor qa:phpunit`.
+
+## Conventions
+
+1. **Never invoke `docker compose` by hand**: use the `docker_compose()` /
+   `docker_compose_run()` functions from `.castor/docker.php` to write new tasks.
+2. **Never hardcode ports or project names**: use `variable('project_name')` etc.
+3. New recurring task? Make it a Castor task (`castor.php` or `.castor/*.php`),
+   not a shell script.
+4. QA tool dependencies live in `tools/<tool>/composer.json`
+   (not in the root `composer.json`).
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file