docs / bêta

Notes de margebêta

Commentez n'importe quel document Markdown local comme vous commenteriez une pull request — sauf que les commentaires vivent dans le fichier même, en simples commentaires HTML qui restent hors de la page rendue. Pensées pour une boucle en particulier : un agent vous écrit un document, vous le lisez dans PullMark en laissant des notes au fil de l'eau, puis vous rendez la main avec « traite les notes et supprime-les à mesure ». La page dédiée aux agents déroule toute la boucle, captures à l'appui.

Les utiliser dans PullMark

Vous lisez ceci sur le Mac où PullMark (0.28.1+) est installé ? Allez droit à l'interrupteur des notes de marge.

Activées par défaut — les notes de marge sont une fonctionnalité expérimentale en bêta livrée active (depuis 0.35). La première fois que vous tendez la main vers elles — la bulle au survol, ⌥⌘M, ou Modifier / Supprimer sur une note qu'on vous a laissée — PullMark présente la fonctionnalité : ce que sont les notes, un bouton Copier pour instruire votre agent, et un bouton Désactiver si ce n'est pas pour vous. L'interrupteur vit dans Réglages → Expérimental et ne gouverne que les outils de rédaction ; un document qui contient déjà des notes affiche ses bulles dans tous les cas (en lecture seule), pour qu'un fichier annoté par un collègue ou un agent ne s'affiche jamais silencieusement vide.
Ajouter une note — survolez n'importe quel bloc d'un document local et cliquez la bulle dans la marge (le geste même du commentaire sur une PR). Dans une liste, la bulle vise l'élément que vous pointez, et dans un tableau la ligne — une teinte discrète montre exactement ce à quoi la note va s'attacher. Sélectionnez du texte d'abord et la note s'ouvre avec la sélection citée — la façon de pointer une phrase plutôt qu'un paragraphe. ⌥⌘M note le bloc que vous lisez ; Édition → Note de marge sur le fichier… laisse une note sur le document entier, en tête de page.
Écrire en Markdown — gras, code en ligne, blocs de code délimités, liens, listes ; ⌘↩ enregistre. Chaque enregistrement compte pour une édition du fichier (annulez avec Fichier → Annuler la dernière modification).
Modifier / Supprimer — survolez une bulle de note pour ses actions. Supprimer une note, c'est ainsi qu'on la résout : pas d'état, pas d'archive — une note traitée est une note absente.
La pastille — les lignes de Fichiers ouverts portent une pastille de compte de commentaires tant que le document porte encore des notes. Elle est vivante : à mesure que l'agent traverse le fichier en supprimant les notes, le compteur descend et les bulles disparaissent sous vos yeux.
Partout ailleurs — les notes s'affichent en lecture seule dans les fichiers GitHub parcourus, n'apparaissent jamais à l'impression, ni dans les exports PDF/HTML, ni dans Quick Look (Coup d'œil), et Présentation → Masquer les notes de marge nettoie la page quand vous voulez lire au propre.
Votre signature — les notes sont signées @votre-login-github par défaut ; changez-la sous l'interrupteur de la fonctionnalité, dans Réglages → Expérimental.

Le format

Une note de marge est un commentaire HTML avec le mot-clé note et une étiquette d'auteur, posé sur sa propre ligne après le bloc dont il parle :

Requests retry three times with exponential backoff.

<!-- note @josh: Section 2 says five times. Which is it? -->

Une note sur un élément de liste vit à l'intérieur de l'élément — indentée au niveau de son contenu, serrée contre lui, pour que la liste reste entière :

- First point
  <!-- note @josh: too vague — name the metric -->
- Second point

Les notes plus longues mettent le marqueur de fermeture sur sa propre ligne ; le corps est du Markdown complet, lignes vides et code délimité compris :

<!-- note @josh:
This contradicts the design doc. Either reconcile them or
drop this section.

```suggestion
Requests retry five times with exponential backoff.
```
-->

La grammaire complète :

Règle	Détail
Marqueur	`<!-- note @` ouvre une note ; les commentaires HTML ordinaires (directives de lint, TODO) sont laissés tranquilles.
Auteur	Tout ce qui se trouve entre `@` et le premier deux-points. Les espaces sont permis ; les pseudos courts se lisent le mieux.
Corps	Du Markdown, du deux-points jusqu'à `-->` — sur la même ligne pour les notes courtes, sur les lignes suivantes pour les longues.
Échappement	Un `-->` littéral dans un corps s'écrit `--\>` (la seule séquence réservée ; PullMark l'échappe et la restitue pour vous).
Emplacement	Sur sa propre ligne, entourée de lignes vides, juste après le bloc qu'elle annote. Au-dessus du premier titre = une note sur le document entier.
Éléments de liste	Une note sur un élément de liste se place à l'intérieur de l'élément : juste après sa dernière ligne, indentée au niveau de son contenu (3 espaces au plus — au-delà, cela se lit comme du code), sans ligne vide autour. C'est l'indentation qui la rattache à l'élément.
Fils	Des notes voisines sous un même bloc se lisent comme une conversation — répondez en ajoutant une note en dessous.
Réservé	`@name (attrs):` — la case entre parenthèses est réservée pour l'avenir et préservée telle quelle ; rien ne l'écrit ni ne la lit aujourd'hui.
Blocs de code	Un commentaire qui a l'air d'une note, à l'intérieur d'un bloc de code délimité, est du code, pas une note.

Comme les moteurs de rendu Markdown sautent les commentaires HTML, un fichier qui contient des notes se rend proprement sur GitHub, dans les éditeurs et dans n'importe quel autre outil — les notes voyagent dans la source sans encombrer la page. PullMark est le client élégant d'un format qui fonctionne partout.

Pour les agents

La passation est à protocole zéro : les agents lisent des fichiers, et les notes sont dans le fichier, physiquement collées au texte dont elles parlent. Collez ceci dans votre CLAUDE.md / AGENTS.md — Réglages → Expérimental a un bouton Copier avec le même texte (ou dites-le simplement) :

## Margin notes

Markdown files may contain review notes as HTML comments:
`<!-- note @name: comment -->` (possibly multi-line, closing
with `-->` on its own line). Each note sits directly after the
passage it's about; a note above the first heading is about the
whole document. `--\>` inside a note means a literal `-->`.

When asked to address notes: work through each one, apply or
answer it, and DELETE the note (with its surrounding blank line)
once addressed. To reply or ask instead, leave your own note in
the same format below the original, signed with your own @name.
Don't add notes to code examples inside fenced blocks.

A note about one list item sits inside that item — directly after
the item's last line, indented to the item's content, with no
blank lines around it. Keep (or delete) the whole indented
comment; its indentation is what ties it to the item.

La boucle de convergence découle du format : les bulles qui restent sont le travail qui reste, et un fichier vide est une relecture terminée. Si les notes ne doivent jamais atteindre une pull request, un contrôle CI tient en une ligne — grep -rn '<!-- note @' docs/ && exit 1.

Pourquoi c'est en bêta

La mécanique a fait ses preuves — le format n'a pas eu besoin d'un changement incompatible depuis sa sortie, et c'est pour cela qu'il a quitté l'alpha. Selon le contrat bêta, nous faisons désormais un réel effort pour garder la grammaire et le comportement compatibles d'une version à l'autre, et la fonctionnalité a de bonnes chances de sortir tout à fait d'Expérimental. Ce qui n'est pas encore posé, c'est la surface autour : les noms, les gestes, et jusqu'où le procédé se généralise au-delà de la boucle de relecture d'agent où il est né. Les notes de version diront exactement ce qui a changé, s'il y a lieu. Vos retours sont bienvenus.