handley-lab/handley-lab.github.io

Compétence Site Web

Utilisez cette compétence lorsque vous travaillez dans handley-lab.github.io. Elle encode les conventions du site à partir de CLAUDE.md et le workflow pour ajouter des recettes et d'autres contenus.

Quand l'utiliser

• L'utilisateur souhaite ajouter ou modifier du contenu sur le site.
• L'utilisateur souhaite prévisualiser ses modifications localement.
• L'utilisateur souhaite publier une recette (carte et éventuelle page compagnon longue).
• Une compétence recette (ou autre compétence de contenu) transmet un brouillon pour prévisualisation.

Bootstrap

Une fois par machine :

script/bootstrap            # gem install bundler && bundle install

Prévisualisation locale

script/server               # bundle exec jekyll serve, http://127.0.0.1:4000

Le rechargement en direct prend en compte les modifications des fichiers *.md, _data/*.yml, _layouts/*.html, _includes/*.html et des fichiers de collection dans _recipes/.

Vérification de la construction

Avant de valider :

script/build                # bundle exec jekyll build → _site/

Si vous avez touché à quoi que ce soit qui pourrait exposer skills/, exécutez également les vérifications de fuite. Le dépôt contient intentionnellement à la fois une page skills.md publique (publiée sur /skills/) et un répertoire source skills/ privé (exclu de la construction). La combinaison est subtile — ces vérifications rendent la distinction explicite :

# La page de la place de marché publique doit exister.
test -f _site/skills/index.html
# Les fichiers de compétences bruts ne doivent PAS fuiter.
test ! -e _site/skills/website
test ! -e _site/skills/recipe
test ! -e _site/skills/README.md
# Tout autre élément sous _site/skills/ sauf index.html et les ressources construites est une fuite.
find _site/skills -mindepth 1 ! -name index.html ! -name '*.css' ! -name '*.js' -print

La dernière commande find ne doit rien afficher.

script/cibuild              # construit, vérifie que _site/index.html existe, puis supprime _site

Si script/cibuild se termine avec le code 0 (affichant "It builds!"), le site se construit.

Le modèle de contenu du Cahier de recettes IA

Deux surfaces :

• _data/recipes.yml — la liste des cartes de recettes affichées sur /cookbook/. Chaque recette a une carte ici.
• _recipes/<id>.md — page compagnon optionnelle rendue sur /cookbook/<id>/. Ajoute un lien "Lire la recette complète" à la carte.

Les entrées avec uniquement une carte sont valides. La longueur est une propriété de la recette ; certaines recettes se lisent en 3 à 4 minutes sans page compagnon, d'autres ont un compte-rendu plus long qui mérite un lien.

Ajouter ou modifier une carte de recette

Les cartes de recettes vivent uniquement dans _data/recipes.yml. Elles ne nécessitent pas de fichier dans _recipes/.

- id: <id>
  title: "..."                           # descriptif simple — dites ce que c'est, pas à quel point c'est ingénieux
  category: "..."                        # ex. Ingénierie de contexte, Communication de recherche
  timebox: "..."                         # ex. 10 minutes, un après-midi, multi-session
  status: "Brouillon"                     # Ébauche | Brouillon | En cours | Terminé
  proposer: "..."                        # optionnel ; utile pour l'attribution dans un atelier
  summary: "..."                         # 1 à 2 phrases. Commencez par ce qui est devenu possible, pas par ce qui était efficace.
  outcome: "..."                         # requis, doit être non vide (Ébauche : ... est acceptable)
  evidence: "..."                        # requis, doit être non vide (Ébauche : ... est acceptable)
  demo_url:
  repo_url: "..."

Pendant l'atelier du 5 mai 2026 et tout atelier suivant, préférez poster le YAML de la carte de recette sur le ticket de coordination pour une fusion par lots par l'orchestrateur plutôt que d'ouvrir de nombreuses PR concurrentes sur _data/recipes.yml — ce fichier est un aimant à conflits de fusion en cas de modifications parallèles.

Ajouter une page compagnon longue pour une recette

Une recette longue comporte deux moitiés qui doivent rester synchronisées :

1. Carte — une entrée dans _data/recipes.yml. Rendu sur /cookbook/ et le bloc de prévisualisation de la page d'accueil.
2. Page compagnon — un fichier à _recipes/<id>.md. Rendu sur /cookbook/<id>/.

L'inclusion de carte (_includes/recipe_card.html) découvre une page compagnon correspondante par le slug de la collection — Jekyll dérive automatiquement le slug du nom de fichier. Donc <id> (le champ de la carte, l'id du frontmatter de la page compagnon et le nom de fichier) doivent tous correspondre. Sinon, le lien "Lire la recette complète" n'apparaîtra pas.

Étape 1 — Choisir <id> et vérifier qu'il n'est pas utilisé

• En kebab-case (ex. jaxwavelets, gw-emulator, cosmosis-cobaya-port).
• Unique dans les trois endroits où il doit correspondre (nom de fichier, id de la carte, id du frontmatter de la page compagnon).

Vérification scriptée (exécutez-la avec votre <id> choisi) :

id="<id>"
fail=0

# 1. L'id de la carte ne doit pas exister dans _data/recipes.yml
if grep -nE "^- id: ${id}$" _data/recipes.yml; then
  echo "ERREUR : _data/recipes.yml a déjà id: ${id}"; fail=1
fi

# 2. Le nom de fichier de la page compagnon ne doit pas exister
if test -e "_recipes/${id}.md"; then
  echo "ERREUR : _recipes/${id}.md existe déjà"; fail=1
fi

# 3. L'id du frontmatter de la page compagnon ne doit pas exister sous un autre nom de fichier
if grep -RsnE "^id: ${id}$" _recipes; then
  echo "ERREUR : un autre _recipes/*.md a déjà id: ${id}"; fail=1
fi

[ "$fail" = 0 ] && echo "OK : ${id} est libre"

Si l'une des vérifications échoue, choisissez un autre identifiant. N'écrasez pas.

Étape 2 — Créer la branche de fonctionnalité

git checkout -b recipe/<id>

Créez la branche d'abord, puis écrivez — les modifications non validées sont transférées, mais il est plus propre de délimiter vos modifications à la branche dès le début. Ne poussez jamais directement sur main.

Étape 3 — Écrire _recipes/<id>.md

Le frontmatter doit inclure le schéma complet de la carte (afin que la page soit auto-documentée et que la mise en page dispose des données nécessaires) :

---
id: <id>
title: "..."
category: "..."
timebox: "..."
status: "Brouillon"            # Ébauche | Brouillon | En cours | Terminé
summary: "..."
outcome: "..."
evidence: "..."
demo_url:                  # optionnel ; laissez le champ sans valeur ou omettez-le complètement
repo_url: "..."            # optionnel
author: "..."
date: AAAA-MM-JJ
---

status accepte "Ébauche", "Brouillon", "En cours" ou "Terminé". outcome et evidence doivent être non vides (pour les ébauches, commencez par Ébauche : ... plutôt que de laisser vide).

Ensuite, le corps long. N'écrivez pas de H1 en tête de corps — _layouts/recipe.html rend {{ page.title }} comme H1. Commencez le corps par ## Section.

Utilisez _recipes/jaxwavelets.md comme modèle de référence (avec l'avertissement que son exécution a été critiquée lors de l'atelier du 5 mai 2026 comme étant trop longue et trop dense — privilégiez des lectures de 3 à 4 minutes avec une note de méthodes pour les détails approfondis).

Étape 4 — Ajouter une carte correspondante à _data/recipes.yml

- id: <id>                              # DOIT correspondre à _recipes/<id>.md
  title: "..."
  category: "..."
  timebox: "..."
  status: "..."
  summary: "..."
  outcome: "..."                        # requis, doit être non vide
  evidence: "..."                       # requis, doit être non vide
  demo_url:
  repo_url: "..."

N'expédiez pas outcome ou evidence vides. Si vous ne pouvez pas les écrire, la recette n'est pas prête à être publiée.

Étape 5 — Prévisualisation

script/server (ou rafraîchissez le serveur en cours d'exécution). Visitez :

• /cookbook/<id>/ — la page compagnon s'affiche avec le titre du frontmatter en H1, MathJax chargé si nécessaire.
• /cookbook/ — la nouvelle carte apparaît avec un lien fonctionnel "Lire la recette complète".
• / — le bloc de prévisualisation de la page d'accueil reflète la modification si <id> fait partie des trois premières cartes.

Étape 6 — Vérification de la construction + validation

script/cibuild                          # se termine par 0 si tout va bien
git add _recipes/<id>.md _data/recipes.yml
git commit -m "Ajouter la recette <id>"
git push -u origin recipe/<id>
gh pr create                            # ou ouvrez la PR dans l'interface web GitHub si gh n'est pas authentifié

Fichiers que cette compétence NE DOIT PAS modifier sans l'accord explicite de l'utilisateur

• _posts/ — actuellement en cours d'audit ; les nouveaux articles passent par une revue de PR (voir Articles ci-dessous).
• assets/group/group.yaml — géré via script/calculate.
• _config.yml — configuration à l'échelle du site ; nécessite l'accord explicite de l'utilisateur.
• script/* — scripts de construction ; nécessite l'accord explicite de l'utilisateur.

Articles (_posts/)

Le répertoire _posts/ contenait historiquement des résumés arXiv générés automatiquement par script/posts/arxiv.py. Depuis le 5 mai 2026, ils sont en cours d'audit : rien dans _posts/ ne doit être présumé revu par un humain, et la page /papers/ est en cours de reconstruction pour n'afficher que les entrées revues par PR. En cas de doute, n'ajoutez pas directement dans _posts/ — ouvrez une PR et demandez une revue humaine.

Modes de défaillance courants

• Lien "Lire la recette complète" manquant : le slug du nom de fichier ne correspond pas à l'id de la carte. Vérifiez que _recipes/<id>.md existe et que la carte a id: <id>.
• H1 en double sur la page : le corps commence par # .... Supprimez-le ; la mise en page ajoute le H1 à partir de {{ page.title }}.
• Étiquettes "Résultat :" / "Preuve :" vides : les champs de la carte sont "". Remplissez-les ; la recette n'est pas prête à être publiée sans eux.
• Échec de la construction après modification de _config.yml : erreur de syntaxe dans la collection ou les portées par défaut. La collection actuelle est recipes (en minuscules) avec permalink: /cookbook/:path/.