Comment ça marche

Docs tient en trois morceaux : un modèle de site qui construit la doc, un hébergeur qui la publie, et la console qui indexe le site pour l’assistant. Chacun peut tomber en panne sans entraîner les autres.

1. Le site se construit

Le paquet @hgdc/docs contient un site complet, bâti sur Astro et Starlight. hgdc-docs build lit ton docs.json, prend tes pages MDX et écrit un site statique. Rien ne tourne côté serveur : le site reste rapide, et il reste en ligne même si la console est indisponible.

Pendant le build, chaque page est aussi convertie en Markdown à partir du HTML final. Les composants sont donc déjà rendus : ce que lit un agent est exactement ce que voit un visiteur.

2. Le site est publié

L’hébergeur sert le dossier dist/ sur l’adresse de ton projet. Chaque mise en production publie une nouvelle version. Tant que le site n’est pas publié, la console n’a rien à lire.

3. La console indexe le site

La console lit /_hgdc/corpus.json sur ton site, à intervalle régulier ou quand tu cliques sur Synchroniser. Elle vérifie que le corpus porte l’identifiant de son projet, puis :

1. Elle découpe chaque page en passages, un par section.
2. Elle compare les passages avec l’index existant. Seuls les nouveaux, ou les modifiés, sont traités.
3. Elle calcule la représentation vectorielle de chaque nouveau passage. C’est elle qui permet de retrouver une question reformulée.
4. Elle supprime les passages qui ne sont plus publiés.

Un build identique au précédent n’écrit rien dans l’index.

4. L’assistant répond

Une question passe par deux recherches : une recherche par mots, pour les termes exacts comme un nom de champ, et une recherche par sens, pour les reformulations. Les deux classements sont fusionnés. Les six meilleurs passages sont donnés au modèle, qui rédige la réponse en citant ceux qu’il utilise.

Seules les sources effectivement citées apparaissent sous la réponse. Si rien ne répond, l’assistant le dit au lieu d’inventer. Le détail est dans L’assistant et ses sources.

Chaque projet a son propre index. Une recherche ne voit que les passages du projet qui la pose.

Ce qui tourne où

Étape	Où
Construction du site	Chez l’hébergeur, à chaque mise en production
Site publié et recherche du site	Chez l’hébergeur, et dans le navigateur du visiteur
Lecture, index et journal	Console Docs
Réponse rédigée	Un modèle d’IA, appelé par la console

Voir aussi

• Mettre ta doc en ligne et activer l’assistant.
• Données et confidentialité.