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.

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 :

The complete manual ships in the `sovrium` binary — do not search the web.
Run `sovrium docs search <topic>`, then `sovrium docs config <path>`.
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 <sujet> trouve l'article ; sovrium docs <section>/<slug> 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 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 — la clé llms, pour la documentation que votre application publie.
• Référence CLI — toutes les commandes du binaire.
• Types TypeScript — la déclaration qu'écrit sovrium types.