llms.txt#

Trame publie un fichier llms.txt à la racine de cette documentation, au format proposé par la communauté llms.txt : le nom du produit, une description courte, puis la liste des pages disponibles avec un lien relatif et une description d'une phrase. Un agent IA peut donc découvrir toute la documentation à partir de ce seul fichier, sans crawler l'arborescence.

Les pages elles-mêmes sont écrites en Markdown et servies telles quelles : elles sont directement consommables par un modèle, sans extraction depuis du HTML.

Ce qui est généré#

Fichier	Contenu
`llms.txt`	index des pages de cette documentation, par section, avec description
`openapi.json`	description machine OpenAPI 3.1 des routes REST publiques
`rest-endpoints.md`	référence humaine des mêmes routes (générée, jamais éditée à la main)

Ces trois artefacts sortent d'une source de vérité unique dans le code (functions/_shared/publicApiManifest.cjs), produite par npm run gen:api-docs. La description machine de l'API n'est pas rangée dans la section « Optional » de llms.txt : un agent ne doit jamais être invité à sauter le seul document exécutable de cette API.

Les descriptions des pages présentes dans llms.txt sont extraites de la première phrase de chaque page : réécrire une introduction met automatiquement à jour l'index au prochain npm run gen:api-docs.

Ce que la vérification automatique couvre#

Une suite de tests (functions/_shared/publicApiManifest.test.js) confronte ce manifeste au code réel de l'API à chaque exécution. Elle appelle réellement chaque route documentée à travers le dispatch de l'API et compare le résultat observé à ce que cette documentation annonce. Sont vérifiés :

Vérifié	Comment
le scope exigé par chaque route	comparé au routage de scopes réel
le préfixe de montage de l'URL de base	lu dans la configuration d'hébergement, puis comparé à l'URL publiée ici et dans le SDK
le statut HTTP de succès de chaque route	mesuré en appelant la route (les routes contacts, agenda et tâches passent par leurs handlers réels)
l'existence des paramètres documentés	le corps d'exemple est rejoué, ses valeurs sont relues dans la ressource créée
le caractère obligatoire annoncé d'un paramètre	l'appel est rejoué sans lui et doit échouer
la fusion silencieuse annoncée (`existed: true`)	la création est rejouée à l'identique
la réponse à une clé de type `agent` à approbation requise	mesurée route par route (`202`, `403` ou `404`)
les plafonds (fréquence, pièces jointes, adresses)	comparés aux constantes du code ; le refus `413` est mesuré à travers le pipeline d'envoi
les codes d’erreur machine des routes contacts, agenda et tâches	chacun doit exister dans le module qui le lève
la fraîcheur des artefacts générés	régénération comparée au contenu publié

Une route ajoutée, un scope modifié, un statut de réponse changé ou un paramètre renommé sans mise à jour de cette documentation fait donc échouer la suite de tests.

Ce que la vérification automatique ne couvre pas#

Il faut le dire aussi clairement : cette suite ne rend pas une garantie générale d'exactitude de la documentation. Elle ne vérifie pas :

la prose — résumés, notes et descriptions de champs ne sont confrontés à rien ;
la forme complète des corps de réponse au-delà des champs explicitement contrôlés ;
les paramètres optionnels qui ne participent pas à un contrôle de valeur : leur existence n'est pas prouvée ;
le comportement du fournisseur de messagerie : l'envoi est joué contre un transport factice, seules les gardes locales (interrupteur global, idempotence, plafonds) sont mesurées ;
les surfaces non décrites ici (helpdesk omnicanal, réglages de l'espace, lien de consultation invité) ;
l'écart entre les magasins de test et la base de données de production.

Sur ces points, la documentation reste une affirmation humaine : signalez toute divergence plutôt que de la supposer impossible.

Statut : llms.txt et openapi.json sont générés dans le dépôt. Leur publication sur le domaine canonique du produit suit celle du reste de la documentation.