# Consignes d'utilisation de VitiCore pour les agents

Toujours répondre en français.

Ce fichier décrit comment utiliser VitiCore depuis un projet hôte : personnaliser les vues, réutiliser les composants, placer les migrations, éviter de dupliquer la logique du coeur et conduire une migration de thème de manière fidèle.

Dans un projet hôte, il est généralement accessible par `vendor/cpcreation/viti-core/AGENTS.md`. En développement local, ce chemin peut être un symlink vers `libs/cpcreation/viti-core`.

## Périmètre

- Utiliser les APIs, composants et templates VitiCore avant de recréer une logique équivalente côté projet.
- Modifier le coeur VitiCore uniquement si la demande porte explicitement sur le coeur. Dans ce cas, lire aussi `vendor/cpcreation/viti-core/AGENTS.development.md`.
- Depuis un projet hôte qui contient `libs/cpcreation/viti-core`, travailler dans ce dossier pour une modification explicite du coeur ; `vendor/cpcreation/viti-core` peut être seulement un symlink.
- Pour une personnalisation projet, ne pas modifier les fichiers VitiCore : créer une personnalisation dans le projet hôte.
- Ne jamais modifier manuellement `vendor/` depuis un projet hôte, sauf comme résultat d'une commande Composer légitime.
- Ne pas copier/reprendre une vue, un composant Twig, un LiveComponent ou une classe PHP VitiCore depuis le vendor pour la modifier. Surcharger le template, utiliser une prop prévue comme `template`, ou créer une classe PHP projet seulement pour la logique métier propre au projet.
- Les templates fournis par VitiCore sont dans `src/Bridge/Symfony/Bundle/Resources/views`.
- Les composants Twig et LiveComponent sont dans `src/Bridge/Symfony/Bundle/Twig/Components`.

## Commandes

- Pour une personnalisation depuis un projet hôte, suivre les commandes indiquées dans le `AGENTS.md` du projet hôte.
- Pour une modification explicite du coeur VitiCore, lire `AGENTS.development.md` et utiliser ses commandes de vérification.
- Quand un projet hôte contient `docker-compose.yml`, lancer les commandes PHP, Composer, Symfony, Yarn, Node, Webpack/Encore et Tailwind depuis le conteneur applicatif du projet hôte, généralement `php`, sauf consigne contraire du projet hôte.

## Traductions

- Tout texte affiché par le code, les templates ou le JavaScript doit passer par le système de traduction Symfony et être défini dans `translations/`. Ne pas écrire de libellé visible en dur, sauf contenu explicitement administré en base.
- Lors de l'ajout ou de la modification d'un texte ou d'une clé de traduction, inspecter les locales présentes dans `translations/` et mettre à jour toutes les traductions correspondantes afin de ne laisser aucune locale existante avec un texte absent ou obsolète.

## Migrations Doctrine

- Les migrations du coeur doivent être placées dans `src/Bridge/Doctrine/Migrations`.
- Leur namespace doit être `CpCreation\VitiCore\Bridge\Doctrine\Migrations`.
- Ne pas créer de migration VitiCore dans le dossier `migrations/` du projet hôte.
- Les migrations liées au projet hôte, et non au coeur VitiCore, doivent être placées dans `src/Migrations`.
- Après une migration, vérifier son application via `doctrine:migrations:status` ou une requête ciblée sur `doctrine_migration_versions`.

## Surcharges VitiCore, Twig Components et Symfony UX

Si les skills Symfony UX ne sont pas disponibles dans l'environnement de l'agent, installer les skills depuis le dépôt suivant avant de travailler sur TwigComponent, LiveComponent, Stimulus, Turbo ou Symfony UX :

```bash
git clone https://github.com/smnandre/symfony-ux-skills.git
```

Les vues VitiCore de référence sont dans :

```text
vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Resources/views
```

Les personnalisations projet doivent être placées dans `templates/` avec le même chemin relatif.

Exemples :

- `vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Resources/views/base.html.twig` se personnalise avec `templates/base.html.twig`.
- `vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Resources/views/components/shop/ProductCard.html.twig` se personnalise avec `templates/components/shop/ProductCard.html.twig`.

Pour personnaliser globalement un composant VitiCore, créer son template miroir dans le projet hôte :

```text
templates/components/...
```

Pour personnaliser ponctuellement une instance, utiliser la prop `template` quand elle existe :

```twig
<twig:shop:ProductCard
    :product="product"
    template="components/home/_product_card_featured.html.twig"
/>
```

Les LiveComponents VitiCore exposent `template` comme `LiveProp` quand cette personnalisation est prévue, ce qui conserve le template personnalisé pendant les rerenders AJAX.

Lorsqu'un composant VitiCore est surchargé par un template miroir dans le projet hôte, il est autorisé et attendu d'adapter ses classes au thème projet, notamment aux tokens issus de `assets/css/theme.scss`, d'un design system Stitch, d'une source HTML/CSS, d'un ancien thème ou du template déjà implémenté par le développeur, tant que les attributs fonctionnels sont conservés.

Conserver tous les attributs nécessaires au comportement :

- `{{ attributes }}` sur les templates de composants Twig/LiveComponent.
- Les attributs Alpine : `x-data`, `x-show`, `x-model`, `x-cloak`, `x-on:*`, `@click`, `@keydown`, `:class`.
- Les attributs Stimulus : `data-controller`, `data-action`, `data-*-target`, `data-*-value`, `data-*-class`, `data-*-outlet`.
- Les attributs LiveComponent : `data-model`, `data-loading`, `data-live-*`, `data-action` lié à `live#action`.
- Les éléments Turbo : `<turbo-frame>`, `<turbo-stream>`, `data-turbo-frame`, `data-turbo-action`, `data-turbo-cache`, `data-turbo-permanent`, `data-turbo-prefetch`.
- Les ids, `name`, `action`, `method`, champs CSRF et hooks utilisés par le JavaScript ou les formulaires Symfony.
- Les éléments SEO fonctionnels du template source : liens canoniques, métadonnées et scripts `<script type="application/ld+json">`, ainsi que les composants Twig qui les produisent.

Pour surcharger correctement un composant dans un thème :

1. Lire le template source VitiCore et la classe PHP du composant si elle existe.
2. Créer un template miroir dans `templates/` avec le même chemin relatif, ou utiliser la prop `template` quand le composant la supporte.
3. Copier la structure fonctionnelle du template source, puis adapter progressivement le HTML de présentation, les classes, les espacements, les icônes et le responsive.
4. Ne pas recréer la logique métier, les requêtes repository, les routes ou les formulaires côté projet si le composant VitiCore les fournit déjà.
5. Vérifier le rendu dans le navigateur, notamment les états interactifs et les re-rendus AJAX des LiveComponents.

## SEO et données structurées dans les thèmes

Les données structurées font partie du comportement fonctionnel VitiCore. Une création de thème, une migration ou une surcharge complète de page ne doit jamais les faire disparaître.

Avant de surcharger une page ou un composant :

1. Inspecter le template VitiCore effectivement rendu et inventorier les liens canoniques, métadonnées, composants SEO et scripts `<script type="application/ld+json">` qu'il contient.
2. Conserver ces éléments dans la surcharge ou les réintégrer explicitement avec les composants et données VitiCore cible.
3. Ne jamais reprendre une marque, un vendeur, un établissement ou un nom de site codé en dur depuis un thème source. Utiliser les données du Contact VitiCore, notamment `contact_business_name()` pour l'identité de l'entreprise.
4. Dans tout `partials/head.html.twig` fourni par un thème, conserver `seo:SiteStructuredData` afin de produire `WebSite`, `WebPage` et `BreadcrumbList` et de les relier au domaine viticole.
5. Pour le catalogue, conserver `shop:CatalogSeo` afin de produire `CollectionPage`, `ItemList`, `Product` et `Offer`.
6. Pour une fiche produit, conserver ou reconstruire le JSON-LD `Product`, ses `Offer`, leur disponibilité, leur prix, leur vendeur et la marque. Une surcharge de `shop/product.html.twig` devient responsable de ce balisage si elle remplace le template VitiCore qui le fournissait.
7. Ne pas dupliquer le JSON-LD `LocalBusiness`/`Winery` global déjà injecté par VitiCore et ne pas le supprimer lors d'un post-traitement HTML.

Après chaque création ou surcharge de thème :

- vérifier le HTML réellement rendu sur les URL concernées, et pas seulement le code Twig ;
- confirmer que les JSON-LD attendus sont présents une seule fois et qu'ils sont décodables ;
- vérifier que `brand`, `seller`, `name`, les URL et les offres proviennent des données et routes du projet cible ;
- tester au minimum le catalogue et une fiche produit réelle avant mise en production ;
- utiliser le test de résultats enrichis Google lorsque la page doit être éligible à un résultat enrichi.

Pour les LiveComponents basés sur des formulaires Symfony dynamiques, ne jamais supposer qu'un champ est toujours présent après un re-render. Tester son existence avant de lire ses variables ou de le rendre :

```twig
{% if form.quantity is defined %}
    {{ form_widget(form.quantity) }}
{% endif %}
```

Cette règle vaut notamment pour `form.quantity`, `form.option` ou tout champ ajouté par `DynamicFormBuilder`.

Pour du contenu provenant de la BDD ou dépendant d'une logique dynamique, privilégier la création ou la réutilisation d'un composant Twig/UX plutôt qu'un controller dédié ou une logique lourde dans un template. Utiliser un TwigComponent quand le rendu est serveur et statique après chargement ; utiliser un LiveComponent quand l'interface doit réagir à une action utilisateur ou se rerendre en AJAX.

Tout composant Twig ou UX qui affiche une collection VitiCore doit être piloté par une prop explicite `collection`, contenant le code administrable de la collection. Ne pas sélectionner une collection par ID codé en dur, par position, par première ligne trouvée ou par nom affiché.

Le `code` d'une collection VitiCore est saisi à la main dans l'admin. Ne pas le générer automatiquement : le front peut être écrit avec `<twig:collection:ProductCollection collection="homepage-cuvees" />`, puis la collection correspondante est rattachée plus tard dans l'admin avec ce même code.

Pour afficher des cuvées ou produits déjà gérés par VitiCore, réutiliser le composant VitiCore prévu, en priorité `<twig:collection:ProductCollection collection="homepage-cuvees" />`, puis surcharger uniquement son template si le rendu doit changer. Ne pas créer un composant projet comme `CuveeShowcase` qui injecte `ProductRepository`, appelle `findOnlyCuvee()` et limite les résultats en PHP uniquement pour produire une grille front : cela contourne les collections administrables et duplique la logique VitiCore.

## Front Tailwind

Ne pas dépendre implicitement de `vendor/cpcreation/viti-core/assets/css/theme.css` pour les tokens Tailwind du projet. Pour un front projet, créer un thème propre dans `assets/css/theme.scss`, y déclarer les tokens Tailwind du projet avec `@theme`, puis l'importer explicitement depuis `assets/css/app.scss`.

`assets/css/app.scss` doit rendre la chaîne Tailwind explicite :

- charger Tailwind ;
- charger le thème projet ;
- ajouter des directives `@source` seulement si nécessaire, par exemple pour scanner un chemin ignoré par défaut, une librairie externe, un dossier hors racine de détection ou une configuration avec `source(none)`.

Avec Tailwind CSS 4, les fichiers du projet sont détectés automatiquement dans le cas standard. Ne pas ajouter systématiquement `@source "../templates"` si la compilation part déjà de la racine du projet et que `templates/` est bien détecté.

Si un MCP Stitch ou un design system Stitch est disponible pour le projet, l'utiliser pour compléter les directives Tailwind propres au projet : couleurs, typographies, espacements, rayons, ombres et autres tokens utiles. Ces valeurs doivent être reportées dans `assets/css/theme.scss` via `@theme`, sans créer de dépendance implicite au thème VitiCore.

Les vues Twig VitiCore existantes servent de référence HTML et fonctionnelle. Pour personnaliser le front, créer des surcharges dans `templates/` avec les mêmes chemins relatifs, puis appliquer les classes Tailwind propres au projet.

L'agent peut ajouter du comportement Alpine, Stimulus ou une librairie front comme Splide selon le besoin du prompteur, en gardant les fichiers projet dans `assets/` et sans modifier VitiCore. Tout JavaScript nécessaire au fonctionnement du site doit être importé explicitement depuis les entrées projet, sinon il ne sera pas chargé.

Si un package externe semble nécessaire, l'agent peut le proposer, mais son ajout doit être validé par le développeur avant toute installation ou modification de dépendance.

Après l'ajout d'un controller Stimulus, d'une initialisation Alpine ou d'une librairie JS, vérifier que l'import correspondant est présent dans `assets/js/app.js`. Vérifier aussi que `assets/js/app.js` importe `../css/app.scss`, afin que les règles et thèmes Tailwind du projet soient pris en compte.

## Protocole de migration fidèle de thème

Pour toute migration fidèle de thème, utiliser le skill `theme-migration-pixelmatch` s'il est disponible.

Une migration fidèle de thème n'est pas une réinterprétation graphique. La source est une spécification visuelle vivante. Le rendu cible doit pouvoir être superposé au rendu source sans différence visible significative, hors contenus dynamiques explicitement remplacés par VitiCore.

L'agent doit préparer un plan de migration avant toute modification. Ce plan doit être basé sur :

- la source lancée ;
- les captures desktop/mobile ;
- les états interactifs capturés ;
- les templates, CSS, JS, fonts et assets inspectés ;
- une table de correspondance source -> cible ;
- une stratégie de comparaison visuelle ;
- les composants VitiCore cible à conserver ou intégrer.

Le rendu source est la référence visuelle et contenu. L'installation VitiCore cible est la référence fonctionnelle.

Si la source utilise aussi VitiCore, son ancienne version n'est pas la référence fonctionnelle. Elle sert uniquement à comprendre le rendu visuel et le contenu affiché. Ne pas supposer que ses controllers, routes, composants, formulaires, panier, boutique ou paiement sont compatibles avec la version cible.

Interdictions :

- inventer un nouveau thème ;
- migrer seulement "l'esprit" du thème ;
- remplacer les polices, espacements, couleurs, compositions ou interactions sans justification ;
- utiliser le design par défaut VitiCore si la source définit déjà un rendu ;
- reprendre la logique métier de la source ;
- modifier `vendor/` depuis un projet hôte ;
- remplacer une fonctionnalité VitiCore par une logique projet équivalente.

Si la source ne peut pas être lancée ou capturée, l'agent doit s'arrêter et demander les accès, fichiers, dumps, assets, variables ou captures manquants. Il ne doit pas produire une migration approximative.

Critère de réussite :

Le développeur doit pouvoir comparer les captures source et cible sans voir d'écart notable.

## Cas source : ancien projet complet

Cette section complète le protocole général lorsque la source est un ancien projet complet, notamment un backend avec dépendances, base de données, assets et configuration de lancement.

Lorsqu'un ancien projet complet est fourni comme source, l'agent doit privilégier une version déjà disponible localement et déjà lancée. Cette source locale lancée devient la référence visuelle obligatoire.

Étapes obligatoires :

1. Vérifier que le projet source local est accessible.
2. Vérifier que l'URL source lancée répond correctement.
3. Lire les consignes du projet source si elles existent : `README`, `AGENTS.md`, `docker-compose.yml`, `.env.dist`, scripts d'installation.
4. Ne relancer, installer ou cloner la source que si elle n'est pas exploitable en l'état, et seulement après l'avoir signalé.
5. Capturer les pages et états importants en desktop et mobile.
6. Analyser le HTML/CSS rendu, les templates, assets, fonts, espacements, couleurs et interactions.
7. Migrer le rendu vers le projet cible avec Tailwind CSS 4 ou la stack front cible.
8. Intégrer les fonctionnalités VitiCore cible dans le rendu source.
9. Vérifier par comparaison visuelle ancien/nouveau.

## Cas source : Stitch ou HTML/CSS statique

Cette section complète le protocole général lorsque la source est une source visuelle sans backend complet exploitable.

Sources possibles :

- projet Stitch accessible via MCP ;
- export Stitch HTML/CSS ;
- dossier HTML/CSS/JS statique ;
- template frontend acheté ;
- maquette intégrée sans backend ;
- archive contenant HTML, CSS, images, fonts et JavaScript d'interaction.

Méthode obligatoire :

1. Copier ou récupérer la source visuelle dans `/tmp/visual-source-{project}`.
2. Identifier les pages et états à migrer.
3. Lancer la source si possible :
    - serveur statique local pour HTML/CSS ;
    - navigation via Stitch MCP pour Stitch ;
    - ouverture navigateur avec les assets réels.
4. Capturer les écrans de référence desktop et mobile.
5. Analyser la structure HTML, CSS, breakpoints, couleurs, typographies, espacements, ombres, images, icônes et interactions frontend.
6. Créer ou compléter une source de vérité visuelle, par exemple `.stitch/DESIGN.md` ou `docs/DESIGN.md`, si utile au projet.
7. Convertir le rendu vers Tailwind CSS 4 dans `assets/css/theme.scss`.
8. Créer les surcharges Twig dans `templates/`.
9. Intégrer les composants VitiCore cible dans ce rendu.
10. Vérifier par comparaison visuelle entre la source et le projet VitiCore.

Cas Stitch :

- utiliser Stitch MCP pour récupérer écrans, screenshots, HTML généré et `.stitch/DESIGN.md` si disponible ;
- si `.stitch/DESIGN.md` n'existe pas, le créer à partir des écrans Stitch avant de coder ;
- si un état important n'existe pas dans Stitch, par exemple panier ouvert, modal produit, information block, panier vide ou mobile, demander un écran Stitch complémentaire ou proposer une extension explicitement marquée comme dérivée du thème source.

Cas HTML/CSS statique :

- lancer un serveur statique local pour inspecter le rendu réel ;
- ne pas se limiter à lire les fichiers ;
- si les assets, fonts ou scripts manquent, demander l'archive complète ;
- si le template contient du JavaScript d'interaction purement visuel, le migrer ou le remplacer par Stimulus/Alpine dans `assets/` sans reprendre de logique métier.

Si un état important n'existe pas dans la source, l'agent doit demander une maquette complémentaire ou proposer un écran dérivé explicitement marqué comme extension du thème source.

## Contenus, textes et visuels source

Lors d'une migration fidèle de thème, les textes, images, pictogrammes, logos, vidéos, fonds, illustrations et contenus visibles du projet source font partie du rendu à migrer.

L'agent doit conserver les contenus source autant que possible :

- titres ;
- sous-titres ;
- paragraphes ;
- libellés de boutons ;
- textes de navigation ;
- textes de boutique ;
- mentions visibles ;
- images ;
- logos ;
- pictogrammes ;
- vidéos ;
- arrière-plans ;
- compositions visuelles.

Ces contenus ne doivent pas être remplacés par des textes génériques, du marketing inventé, des placeholders ou des images alternatives, sauf demande explicite du développeur.

Dans un projet Symfony/VitiCore, les textes affichés par le code ou les templates doivent être déplacés dans `translations/` conformément aux règles du projet hôte. Les contenus administrables en base ne doivent pas être dupliqués en dur dans les templates.

Les images et assets du thème source doivent être copiés ou référencés dans le projet cible selon l'organisation du projet, sans perdre leur rôle visuel. Si un asset est manquant, l'agent doit le signaler et demander l'archive complète ou le fichier manquant.

Si un contenu source doit être remplacé par une donnée VitiCore administrable, l'agent doit conserver le rendu et l'emplacement du contenu, puis brancher la donnée VitiCore équivalente.

Exemples :

- un titre statique source devient une clé de traduction si le projet l'exige ;
- une image produit source devient l'image produit VitiCore si elle est administrée ;
- une card produit source garde sa structure visuelle mais utilise `cart:ItemForm` ;
- un bloc éditorial source devient un `shop:InformationBlocks` ou un composant VitiCore équivalent s'il doit être administrable.

Interdictions :

- inventer des textes ;
- remplacer les visuels par des images d'ambiance non demandées ;
- supprimer un contenu source visible sans justification ;
- traduire ou réécrire le ton éditorial sans demande explicite ;
- mettre en dur un texte dans Twig/PHP/JS si le projet impose les traductions.

Critère de réussite :

Le visiteur doit retrouver les mêmes contenus visibles que dans la source, avec les fonctionnalités VitiCore branchées quand elles remplacent une donnée statique.

## Boutique VitiCore dans une migration de thème

Pour la boutique, le thème source est la référence visuelle obligatoire. L'installation VitiCore cible est la référence fonctionnelle.

L'agent doit migrer la boutique en conservant le rendu source :

- menu boutique ;
- grille produits ;
- cards produits ;
- boutons ;
- quantités ;
- panier ;
- responsive mobile ;
- couleurs, typographies, espacements et assets.

Les fonctionnalités VitiCore cible doivent être intégrées dans ce rendu, sans utiliser le design par défaut VitiCore si celui-ci rompt le style source :

- `shop:Tabs` ;
- `cart:ItemForm` ;
- `cart:CartForm` ;
- `shop:InformationBlocks` ;
- `shop:LegalNotice` ;
- `shop:PartnerCode` ;
- `marketing:ProductReviews` pour les avis publics sous les fiches produits ;
- `marketing:ProductReviewForm` et `marketing:ReviewSolicitationOptOut` pour les pages d’avis, avec leur prop `template` et leurs vues surchargeables sous `templates/components/marketing/` ;
- modals produit, récompense et dégressivité ;
- checkout et paiement VitiCore.

Interdictions :

- inventer un nouveau rendu ;
- reprendre la logique métier de la boutique source ;
- modifier `vendor/` ;
- remplacer les composants VitiCore par une logique projet équivalente.

Méthode obligatoire :

1. Capturer la boutique source en desktop et mobile.
2. Capturer les états interactifs : menu, panier ouvert, panier vide, quantité, ajout panier, modals, messages et responsive.
3. Faire une table de correspondance ancien rendu -> composant VitiCore cible.
4. Surcharger les templates dans `templates/`.
5. Convertir Foundation, Theme3 ou le CSS source vers Tailwind CSS 4 dans `assets/css/theme.scss`.
6. Vérifier par comparaison visuelle source/cible.

Les nouvelles fonctionnalités VitiCore qui n'existaient pas dans la source doivent être ajoutées comme une extension naturelle du rendu source. Elles ne doivent pas ressembler au design par défaut VitiCore si celui-ci rompt le style du thème source.

Critère de réussite :

La boutique doit ressembler à la boutique source, avec les fonctionnalités VitiCore cible en plus.

## Vérification visuelle des migrations

Pour une migration de thème, le lint, le cache clear et le build ne suffisent pas. Le rendu est le contrat principal.

L'agent doit vérifier au minimum :

- accueil desktop ;
- accueil mobile ;
- header/menu desktop ;
- header/menu mobile ouvert ;
- boutique desktop ;
- boutique mobile ;
- fiche/card produit ;
- ajout panier ;
- panier vide ;
- panier rempli si des fixtures le permettent ;
- modals VitiCore visibles ;
- page contact ;
- captcha AltCha si le formulaire contact est présent ;
- footer.

La comparaison doit utiliser des captures ou une navigation directe dans le navigateur. Toute divergence visuelle importante doit être corrigée avant de considérer la migration terminée.

Lorsque c'est possible, fournir :

- captures source ;
- captures cible ;
- captures diff ;
- liste courte des écarts restants ;
- commandes de vérification lancées.

## Routes et pages simples

Avant de créer une page, vérifier que la route respecte ces consignes.

Les routes propres au projet doivent être déclarées dans `config/routes.yaml`.

Ne jamais importer `vendor/cpcreation/viti-core/src/Bridge/Symfony/Bundle/Routing/routes.yaml` : ce fichier de routes VitiCore est obsolète. Si une page projet est nécessaire, créer sa route dans `config/routes.yaml` en respectant les règles de cette section.

Avant d'ajouter une nouvelle route, vérifier si une route VitiCore utile existe déjà dans `config/routes/viti_core.yaml`.

Bien séparer les routes chargées automatiquement par le loader `type: viti-core`, les pages publiques optionnelles et les endpoints techniques :

- le loader `type: viti-core` charge les routes internes indispensables du coeur, dont `site_media`, `presta_sitemap`, API Platform, FOS JS Routing, LiipImagine et UX LiveComponent ; ne pas les réimporter comme des pages projet ;
- les pages publiques optionnelles doivent être activées selon le site : `site_shop` pour boutique/checkout, `site_security` pour connexion/compte utilisateur, `site_depot` pour la page dépôts, `site_legal` pour mentions légales/CGV/politique de confidentialité, `site_news` pour actualités, `site_locale` pour les changements de langue et `site_social` si la fonctionnalité est utilisée ;
- `site_payment` ne sert qu'à exposer la page autonome `/paiement-en-ligne` avec le composant `payment:Form` ; ne pas l'importer si le site n'a pas besoin de cette page ;
- `site_payment_methods` expose les routes techniques `payment_*` et les callbacks `/request/*/responseAt` des moyens de paiement ; l'importer quand le checkout ou `payment:Form` doit utiliser un paiement en ligne.

Les routes publiques localisées du coeur doivent déclarer les clés `fr`, `en`, `de`, `nl`, `it` et `es` quand elles exposent une page utilisateur. Ne pas localiser les endpoints techniques stables comme `/cdn`, `/api`, `/request/*/responseAt` ou les callbacks bancaires. La disponibilité réelle d'une langue est contrôlée en base via `locale_locale` : une locale routée mais inactive doit répondre en 404.

Décommenter et adapter les blocs nécessaires plutôt que recréer une route équivalente.

Eviter de créer des controllers pour les pages simples. Utiliser une route YAML avec `Symfony\Bundle\FrameworkBundle\Controller\TemplateController`.

Exemple :

```yaml
homepage:
    path:
        fr: /
        en: /en
    controller: Symfony\Bundle\FrameworkBundle\Controller\TemplateController
    defaults:
        template: 'home/index.html.twig'
        context: []
    options:
        sitemap: true
```

Créer ensuite le template correspondant, par exemple `templates/home/index.html.twig`.

Ne créer un controller que si la page a besoin de logique serveur spécifique impossible à obtenir proprement via Twig, composants, LiveComponents, services existants ou configuration.

## Administration

- Garder les libellés admin en français.
- Eviter les validations qui remontent une erreur SQL brute ; préférer des contraintes Symfony explicites.
- Pour les formulaires à collections imbriquées, vérifier l'affichage des erreurs pour éviter les doublons.
- Pour les champs ordonnés, garder une donnée persistée claire, généralement `position`, et une UI qui permet de modifier cette valeur directement.
- Pour les personnalisations projet, ne pas modifier les controllers ou formulaires d'administration du coeur sauf demande explicite portant sur le coeur VitiCore.

Si une donnée doit devenir administrable :

- vérifier si VitiCore possède déjà une entité, une collection, un bloc d'information, une page légale, une configuration ou un composant prévu ;
- utiliser les mécanismes existants avant de créer une logique projet ;
- documenter clairement le code administrable attendu quand le front dépend d'une collection ou d'un bloc.

## Exemples de prompts

### Ancien projet complet déjà lancé

```text
Utilise le skill theme-migration-pixelmatch s'il est disponible.

Migre le rendu de l'ancien projet déjà disponible en local vers ce projet VitiCore 2.

Source :
- chemin : /Users/julien/Sites/champagne-banette
- URL lancée : https://localhost:8448/

Cible :
- chemin : /Users/julien/Sites/champagne-banette-v2
- URL lancée : https://localhost/

Respecte strictement les consignes de migration fidèle du AGENTS.md VitiCore :
- la source lancée est la référence visuelle et contenu ;
- l'installation VitiCore cible est la référence fonctionnelle ;
- prépare un plan de migration avant toute modification ;
- capture la source et la cible en desktop/mobile ;
- capture les états interactifs : menu, panier, boutique, modals, contact, responsive ;
- inspecte les templates, CSS, JS, fonts et assets source ;
- établis une table source -> cible ;
- migre Foundation/Theme3/CSS source vers Tailwind CSS 4 ;
- intègre les composants VitiCore cible sans reprendre l'ancienne logique métier ;
- vérifie par comparaison visuelle jusqu'à ce que les rendus se superposent.

Conserve les textes et visuels du projet source. Ne remplace pas les contenus par des textes ou images inventés. Si un contenu doit devenir administrable VitiCore ou passer par les traductions Symfony, garde le même rendu et branche-le proprement.

Si la source locale n'est pas accessible ou ne rend pas correctement, arrête-toi et demande les accès, dumps, variables ou assets nécessaires.
```

### Stitch

```text
Migre le thème Stitch du projet [NOM/ID STITCH] vers ce projet VitiCore 2.

Utilise Stitch MCP comme référence visuelle obligatoire. Récupère les écrans, screenshots, HTML généré et .stitch/DESIGN.md si disponible. Si .stitch/DESIGN.md n'existe pas, crée-le à partir des écrans Stitch avant de coder.

Prépare un plan de migration avant toute modification.

Pour la boutique, conserve le rendu Stitch mais intègre les composants VitiCore cible : shop:Tabs, cart:ItemForm, cart:CartForm, shop:InformationBlocks, shop:LegalNotice, shop:PartnerCode, modals et checkout.

Ne reprends aucune logique métier externe. Surcharge uniquement les templates nécessaires dans templates/.
```

### HTML/CSS statique

```text
Migre le thème HTML/CSS situé dans /chemin/vers/theme-source vers ce projet VitiCore 2.

Traite ce thème comme la référence visuelle obligatoire. Copie-le dans /tmp/visual-source-{project}, lance-le avec un serveur statique local, capture les pages desktop/mobile, puis convertis le rendu vers Tailwind CSS 4.

Ne crée pas un nouveau thème. Le header, menu, boutique, cards produits, boutons, panier, footer, couleurs, typos, espacements, assets et responsive doivent correspondre au thème source.

Intègre les fonctionnalités VitiCore cible dans ce rendu : shop:Tabs, cart:ItemForm, cart:CartForm, shop:InformationBlocks, shop:LegalNotice, shop:PartnerCode, modals, checkout et paiement.

Conserve les textes et visuels du thème source. Ne remplace pas les contenus par des textes ou images inventés. Si un contenu doit devenir administrable VitiCore ou passer par les traductions Symfony, garde le même rendu et branche-le proprement.

Ne reprends aucune logique métier du thème source. Utilise les composants VitiCore et surcharge seulement les templates nécessaires dans templates/.

Si un état manque dans le thème source, demande une validation avant de l'inventer.
```
