# Lire le manuel hors ligne Le manuel du binaire est livré **dans** le binaire. C'est la promesse que `sovrium types` tient déjà pour la surface TypeScript, étendue des types à la prose : la déclaration qu'émet `sovrium types` décrit le schéma que **ce** binaire accepte, et le manuel qu'imprime `sovrium docs` décrit le comportement de **ce** binaire. Un décalage de version entre le moteur qui tourne et la documentation qu'il vous remet n'est pas représentable. ```bash sovrium docs # la table des matières sovrium docs app-schema # une section entière sovrium docs app-schema/llms-txt # un article sovrium docs search llms # trouver l'article qui traite d'un sujet sovrium docs config llms.full # consulter une option sovrium docs env DATABASE_URL # une variable d'environnement sovrium docs cli migrate # une commande sovrium docs --full # tout le manuel, pour une fenêtre de contexte sovrium docs --full --format llms --output llms-full.txt ``` Le Markdown est le format par défaut, pour la raison que `sovrium design-system` donne déjà : le lecteur visé est un modèle qui lit une fenêtre de contexte, et injecter le manuel dans un prompt ne devrait demander aucune option. `--format json` est là pour l'outillage. ## Deux moitiés, assemblées à la lecture Le récit est rédigé sous forme de fragments Markdown posés à côté du code qu'ils décrivent — l'article sur la clé `llms` est voisin du fichier de schéma et de ses tests. Les tableaux d'options, eux, ne sont **pas rédigés du tout** : un fragment porte une directive nommant un schéma, et la commande la développe à partir des annotations de ce schéma au moment d'imprimer. Un tableau ne peut donc jamais prendre de retard sur l'option qu'il documente, puisqu'il n'existe pas avant l'instant où il est lu. Une directive nommant un schéma disparu est une erreur de construction ; un tableau écrit à la main décrivant un schéma disparu est un mensonge que personne ne remarque. ## Les blocs de comportement viennent des critères d'acceptation Chaque article nomme les user stories qu'il documente, et la commande restitue leurs critères d'acceptation sous forme de bloc `Behaviour`, groupés par story. Une ligne n'y est donc pas une affirmation que quelqu'un a écrite à côté d'une fonctionnalité : c'est le critère d'un test qui est rédigé et non désactivé. Les critères dont le test est encore un simple emplacement sont omis, pour que le manuel ne décrive jamais un comportement que personne n'a spécifié. Ce que cela ne prouve **pas** mérite d'être dit franchement plutôt que sous-entendu : « rédigé et non désactivé » est un signal de construction. Que le test passe, c'est ce qu'établit l'exécution de bout en bout — et un critère faux est livré faux. ## Trois refus, et chacun est un refus plutôt qu'un repli - **Un `--format` inconnu.** Se rabattre silencieusement sur le Markdown est la pire défaillance : une étape de build qui demande `yaml` reçoit du Markdown, sort en `0`, écrit le mauvais fichier, et personne ne regarde à nouveau. La commande sort en erreur en nommant les valeurs acceptées. - **Un `--lang` autre que `en`.** Le manuel embarqué est en anglais. L'option existe pour qu'ajouter une langue plus tard ne soit pas une rupture, et elle refuse toute autre valeur **en la nommant** plutôt que de servir discrètement de l'anglais à quelqu'un qui a demandé du français et ne vérifiera pas. - **Une section, un article ou un chemin d'option inconnu.** Un lecteur qui a tapé un chemin inexistant a besoin d'apprendre lesquels existent, pas de recevoir la table des matières et d'en déduire que son chemin était vide. ## Déterminisme `sovrium docs --full` est une fonction pure du binaire : deux exécutions d'un même binaire produisent des octets identiques. C'est ce qui permet à un consommateur d'épingler une version, de régénérer, et de traiter toute différence comme un vrai changement plutôt que comme du bruit. ## Y pointer un agent Tout l'intérêt est qu'un agent qui configure votre application lise les règles depuis l'artefact qu'il configure, plutôt que depuis des connaissances pré-entraînées qui décrivent peut-être une autre version. Mettez ceci dans le `CLAUDE.md` du projet — `sovrium init` vous l'écrit : ```markdown The complete manual ships in the `sovrium` binary — do not search the web. Run `sovrium docs search `, then `sovrium docs config `. The docs describe THIS binary: check `sovrium --version`. ``` Une boucle qui fonctionne pour rédiger une configuration avec un agent : 1. **Donnez-lui le contexte nécessaire, et rien de plus.** `sovrium docs search ` trouve l'article ; `sovrium docs
/` l'imprime. Ne recourez à `--full` que si un outil a réellement besoin de tout le corpus en un seul appel — il est assez volumineux pour évincer tout le reste d'une fenêtre de contexte. 2. **Rédigez en TypeScript.** Lancez `sovrium types` une fois, puis faites générer à l'agent un `app.ts` vérifié par `satisfies AppConfig`. Votre éditeur valide sa production à mesure qu'il écrit, et signale les types de champs invalides et les sections mal formées directement dans le fichier. 3. **Validez avant d'exécuter.** `sovrium validate app.ts` confirme que la configuration se décode, en faisant remonter les types de champs inconnus et les erreurs de structure avec le code de sortie `1`. 4. **Itérez face à l'application qui tourne.** `sovrium start app.ts --watch` recharge à l'enregistrement, pour que l'agent affine la configuration et en voie le résultat. Associer le manuel (le contexte), la déclaration qu'écrit `sovrium types` (la validation à la compilation) et `sovrium validate` (le décodage à l'exécution) donne à l'agent une boucle de retour serrée : les configurations générées sont vérifiées au moment de l'écriture et au moment de la validation, avant même de démarrer. **Quand ce manuel et `sovrium schema` divergent, c'est le schéma qui fait foi** — il est dérivé des définitions mêmes qu'exécute le décodeur. ## Les équivalents publiés sur un site Une application Sovrium peut publier sa propre documentation lisible par les machines en HTTP — un index `llms.txt`, un corpus `llms-full.txt`, et un jumeau en Markdown brut de chaque page — via la clé [`llms`](/fr/docs/llms-txt) de la configuration. C'est une autre surface, pour un autre public : ces fichiers décrivent **votre** application à un robot d'indexation, là où `sovrium docs` décrit **le moteur** à qui le configure. ## Pages connexes - [Publier llms.txt](/fr/docs/llms-txt) — la clé `llms`, pour la documentation que votre application publie. - [Référence CLI](/fr/docs/cli) — toutes les commandes du binaire. - [Types TypeScript](/fr/docs/configuration-typescript) — la déclaration qu'écrit `sovrium types`.