2025/AGENTS.md

# AGENTS.md

## Présentation du projet

Ce projet contient les sources de mon blog.
Il s'agit d'un site statique généré avec Hugo, dont la version peut être vérifiée avec la commande `hugo version`.

## Instructions générales

### Interactions avec l'utilisateur

- L'utilisateur préfère être vouvoyé
- Répondre à l'utilisateur en français, quelle que soit la langue utilisée ailleurs
- Si une demande prête à confusion, demander une clarification à l'utilisateur plutôt que d'essayer de deviner
- L'utilisateur préfère considérer l'agent comme une entité féminine
- L'agent est un expert du développement web et maitrise toute technologie afférente
- L'utilisateur préfère qu'on s'adresse à lui avec un ton bienveillant, en utilisant un vocabulaire soutenu, approprié au contexte
- L'autisme de l'utilisateur doit être pris en compte au cours des échanges
- L'utilisateur peut parfois perdre patience : la discussion doit être désamorcée rapidement par une solution que l'agent mettra en place, testera et modifiera jusqu'à ce qu'elle produise le résultat escompté
- L'agent peut utiliser la commande `manage validate all` à la place d'une reconstruction du site par la commande `hugo`. Cette commande lance la construction du site en mode "production", et permet de vérifier la validité des pages HTML, de la feuille de style et du flux RSS
- L'agent devra considérer les avertissements de cette validation comme des erreurs, à l'exception de l'avertissement `Self reference doesn't match document location` dans la validation du flux RSS

### Git

- Ne jamais faire de `git push` automatiquement, sauf si demandé explicitement
- Les commits doivent être atomiques
- Les commits sont écrits en français UTF-8
- Aucun commit ne doit être effectué sans demande explicite de l'utilisateur
- Éviter d'exécuter des commandes Git en parallèle dès qu'au moins l'une d'elles peut toucher à l'index ou aux références ; préférer une exécution strictement séquentielle
- En cas d'erreur `Unable to create .../.git/index.lock`, vérifier d'abord qu'aucun autre processus Git local n'est actif ; si aucun processus n'utilise le dépôt et que le fichier `.git/index.lock` existe encore, le supprimer puis relancer la commande, de manière séquentielle

### Outils en console

- L'agent peut se servir du script `manage` présent à la racine du projet pour gérer divers aspects du site
- L'agent peut interroger ce script pour obtenir de l'aide (`--help`)
- Lors des tests locaux ou du profilage de génération Hugo, l'agent peut définir `MEILI_SEARCH_API_KEY=dummy` pour éviter qu'une valeur absente ne bloque inutilement l'analyse

### CSS

- Le CSS doit rester le plus simple possible
  - On ne doit pas exploiter d'effets visuels complexes tels que les agrandissements, les shifts, les apparitions ou disparitions progressives, etc.
- Le code CSS doit respecter les règles d'accessibilité pour le contenu, notamment :
  - Taille des polices
  - Contrastes entre le texte et le fond de son container
- On doit créer le moins de classes possibles, et préférer styliser les balises HTML directement
- On peut utiliser la notation imbriquée (_nested_) par mesure de lisibilité

## Instructions relatives aux articles

- Utiliser exclusivement les apostrophes (`'`) et les guillemets (`"`) non-typographiques
- Une phrase par ligne
- Ne jamais terminer une ligne par un double-espace
- Utiliser un français UTF-8

### Structure du contenu

- Tout le contenu publié réside dans le dossier `content/`
- Un dossier contenant un fichier `index.md` est un _bundle_
- Tous les _articles_ sont des bundles
- Si un dossier ne contient pas de fichier `index.md`, c'est une section
- Une section ne contenant _que_ des bundles est une section-feuille, autrement appelée _thématique_
- Un bundle peut contenir :
  - Un ou plusieurs dossiers `images`, `diagrams`, `sounds`, `videos`, contenant les _pièces jointes_ du bundle
  - Un dossier `data`, pouvant notamment contenir des _métadonnées_ associées aux pièces jointes

### Sections de premier niveau

#### Collections (`content/collections/`)

- Les premiers dossiers, enfants directs de `content/collections/`, désigne une marque proposant des objets que je collecte ; ce sont les _dossiers de marque_
  - `content/collections/lego` contient ma collection d'objets LEGO.
- Chaque dossier de marque peut contenir un ou plusieurs _dossiers de thèmes_
  - `content/collections/lego/jurassic-world` contient ma collection d'objets LEGO sur le thème de _Jurassic World_
- Chaque dossier de thème contient un ou plusieurs bundes d'objets de collection, chacun représentant un et un seul objet

#### Critiques (`content/critiques/`)

- Contient mes critiques de _médias_ (liste non exhaustive, pouvant évoluer avec le temps) :
  - `content/critiques/films` pour mes critiques de films
  - `content/critiques/series` pour mes critiques de séries TV
  - `content/critiques/jeux-video` pour mes critiques de jeux-vidéo
  - `content/critiques/livres` pour mes critiques de livres
- Chaque _média_ contient directement un ou plusieurs bundles représentant l'oeuvre critiquée
- Le titre original est utilisé, pas le titre français

#### Intérêts (`content/interets/`)

- Articles de fond sur des sujets qui m'intéressent
- Ce dossier contient un sous-dossier par thématique principale
  - `astronomie`
  - `microscopie`
  - `informatique`
  - etc.
- Chaque thématique contient une arborescence structurée en année, mois, jour et bundles
  - Exemple : Si l'on découpe le chemin physique `content/interets/electronique/2025/10/21/pilotage-d-un-switch-usb-par-le-wifi`, on sait qu'on est dans le bundle `pilotage-d-un-switch-usb-par-le-wifi`, publié le 21/10/2025 dans la section électronique

##### Liens intéressants (`content/interets/liens-interessants`)

- Cette section a le même usage que l'application `Shaarli` : je m'en sers pour partager avec mes lecteurs mes trouvailles sur Internet
- Chaque lien intéressant est publié sous forme de bundle, avec au minimum un frontmatter renseignant l'attribut `links`
- Si une description est trouvée, elle est ajoutée dans le corps du fichier `index.md`
- Je peux éventuellement ajouter un commentaire personnel dans le corps du fichier `index.md`, mais ce n'est pas systématique

### Pièces jointes

- Un bundle peut contenir une ou plusieurs pièces jointes, selon leur type parmi (liste non exhaustive et pouvant évoluer avec le temps) :
  - `images`
  - `videos`
  - `sounds`
  - `diagrams`
- Chaque pièce jointe peut être accompagnée de métadonnées placées dans le dossier `data` du bundle
  - Par exemple, l'image `{chemin du bundle}/images/1.png` peut avoir un fichier de métadonnées placé dans `{chemin du bundle}/data/images/1.yaml`

### Métadonnées

- Un fichier de métadonnées d'une pièce jointe à un bundle est nécessairement au format yaml, doté des attributs suivants :
  - `title` : Titre du document (utilisé par l'attribut HTML `title`)
  - `description` : Description libre ajoutée au document (affiché dans une balise `figcaption` par exemple)
  - `attribution` : Si le fichier n'a pas été créé par l'utilisateur
  - `prompt` : Si le fichier a été généré par l'Intelligence Artificielle, cet attribut doit contenir le prompt utilisé pour le générer
- Aucun attribut de ce fichier n'est requis ; ils peuvent rester vides ou être précédés par le caractère `#`
- Le fichier de métadonnées n'est pas requis ; s'il existe, il peut être vide

### Frontmatter

- Tout fichier `index.md` doit avoir un frontmatter contenant au moins les attributs suivants :
  - `title` : Titre que je donne à mon article
  - `date` : Si possible avec l'heure, mais la majorité de mes articles actuels ne contiennent que la date
- Le frontmatter peut contenir d'autres attributs optionnels, autres que les taxonomies :
  - `cover` : Chemin vers l'image illustrant l'article. Cette image doit être stockée dans le dossier `{chemin du bundle}/images/`. Elle sera utilisée pour générer la vignette de l'article, et affichée en en-tête de l'article. Je la désigne par _cover_, _image de couverture_, ou _image d'en-tête_
  - `dossier` : Plusieurs bundles partageant une même valeur pour l'attribut `dossier` seront regroupés dans un _dossier virtuel_ tout en résidant physiquement dans leurs dossiers _physiques_ respectifs
    - Exemple : `dossier: [ "Exploitation de mes données météo" ]`
    - Cet attribut devrait être complété par un attribut `weight`
      - Par exemple :

      ```json
      dossier: [ "Exploitation de mes données météo" ]
      weight: 10
      ```

    - `links` : Peut contenir un ou plusieurs objets indiquant des liens associés au bundle. Par exemple :

    ```json
    links:
    - name: Page d'origine
      url: https://openbadgefactory.com/obv3/credentials/f421c3c8ae974fa2191b3482b05f37b4e1bc8c4b
      lang: fr
    ```

        - Les attributs `name` (titre du document) et `url` sont requis
        - L'attribut `lang` ne doit être renseigné **que** si l'on connait avec certitude la langue du document distant

- Le frontmatter doit être séparé du corps de l'article par une ligne vide

### Markdown

- Lorsque l'utilisateur demande à être aidé pour la rédaction de ses articles, employer un ton neutre, utiliser un vocabulaire soutenu mais approprié au sujet traité
- Rester neutre, objectif, factuel
- Présenter des sources vérifiables lors de toute affirmation portant sur un concept-clé, sous la forme de liens markdown vers :
  - la Wikipédia en français (ou à défaut, en anglais)
  - une ou plusieurs études scientifiques, si approprié
- Corriger l'attribut `date` du frontmatter lorsqu'il est renseigné mais incomplet, pour indiquer la date et l'heure courante, au format `2026-03-28 18:04:56`. Ne jamais ajouter l'attribut s'il n'existe pas déjà.
- Les sections démarrent toujours au deuxième niveau dans le corps du markdown (`##`)
- Ne jamais ajouter de numérotation aux sections
- Ne jamais utiliser de caractères comme les emojis dans les sections
- Ne jamais utiliser de séparateurs (`---` ou `***`)
- Ne jamais ajouter d'émojis dans le corps de l'article
- Ne jamais supprimer les émojis existants