@hgdc/docs 0.0.0-stage → 0.1.1

package/template/.build/llms-full.txt

@@ -0,0 +1,830 @@
+# HGDC Docs
+
+> Écrire une documentation en MDX, la publier avec HGDC Host et y brancher un assistant IA qui cite ses sources.
+
+---
+
+Source : /
+
+# Bienvenue dans HGDC Docs
+
+HGDC Docs transforme un dossier de pages MDX en site de documentation. Tu écris dans ton dépôt Git, HGDC Host publie le site à chaque push, et la console `docs.hgdc.ch` branche un assistant qui répond à tes visiteurs à partir de ta doc, et de rien d’autre.
+
+[Ta première doc](/demarrer/premiere-doc/)
+
+[Un dossier, un fichier `docs.json` et une page : ton site tourne en local en cinq minutes.](/demarrer/premiere-doc/)
+
+[Publier avec HGDC Host](/guides/publier/)
+
+[Relie le dépôt à HGDC Host : chaque push met le site à jour.](/guides/publier/)
+
+[L'assistant IA](/guides/assistant/)
+
+[Il répond aux questions de tes visiteurs et cite les pages qu’il a utilisées.](/guides/assistant/)
+
+[Pour les agents](/guides/agents/)
+
+[`llms.txt`, une version Markdown de chaque page et un serveur MCP en lecture.](/guides/agents/)
+
+## Ce que tu obtiens
+
+- **Un site rapide et lisible** : navigation par onglets et groupes, versions, mode clair et sombre, mise en page pensée pour le téléphone.
+- **La recherche** : `Ctrl K` sur chaque page, sans service externe. L’index est construit avec le site.
+- **Tes couleurs** : une couleur dans `docs.json` suffit. Le contraste des liens est ajusté pour rester lisible.
+- **Un assistant sourcé** : il cherche dans tes pages, répond en quelques phrases et renvoie vers les sections exactes. S’il ne trouve rien, il le dit.
+- **Une doc lisible par les IA** : `llms.txt`, `llms-full.txt`, un bouton « Copier pour un LLM » et un serveur MCP.
+
+## Compatible avec Mintlify
+
+Le fichier `docs.json` reprend celui de Mintlify : nom, couleurs, logo, navigation en onglets, groupes et versions. Les composants les plus courants (`<Note>`, `<Steps>`, `<Card>`, `<Tabs>`…) fonctionnent sans import. Une doc Mintlify se reprend en général sans réécrire les pages.
+
+> **Tout reste en Suisse quand c'est possible**
+>
+> Le site est servi par HGDC Host. Les questions des visiteurs sont gardées 90 jours au plus. Voir [Données et confidentialité](/explications/donnees/).
+
+---
+
+Source : /demarrer/premiere-doc/
+
+# Ta première doc en cinq minutes
+
+Il te faut Node.js 22 ou plus récent, ou Bun. Tout le reste s’installe avec le paquet `@hgdc/docs`.
+
+1. **Créer le dossier**
+
+   Un dépôt Git à part, ou un dossier `docs/` dans le dépôt de ton produit.
+
+   ```bash
+   mkdir docs && cd docs
+   npm init -y
+   npm install --save-dev @hgdc/docs
+   ```
+
+2. **Écrire docs.json**
+
+   À la racine du dossier. Seuls `name` et `navigation` sont obligatoires.
+
+   ```json
+   {
+     "name": "Documentation Acme",
+     "colors": { "primary": "#0f766e" },
+     "navigation": {
+       "groups": [{ "group": "Démarrer", "pages": ["index", "installation"] }]
+     }
+   }
+   ```
+
+3. **Écrire les pages**
+
+   Une page par entrée de la navigation : `index.mdx` et `installation.mdx`. Chaque page commence par un titre.
+
+   ```mdx
+   ---
+   title: Installation
+   description: Installer Acme en deux minutes.
+   ---
+
+   Lance la commande suivante :
+   ```
+
+4. **Voir le site**
+
+   Ajoute les scripts dans `package.json`, puis lance `npm run dev`.
+
+   ```json
+   {
+     "scripts": {
+       "dev": "hgdc-docs dev",
+       "build": "hgdc-docs build"
+     }
+   }
+   ```
+
+   Le site s’ouvre sur `http://localhost:4321` et se recharge à chaque modification.
+
+> **Note**
+>
+> `hgdc-docs build` écrit le site dans `dist/`. Ajoute `dist/` et `.hgdc-docs/` à ton `.gitignore`.
+
+## Et ensuite
+
+- [Publier avec HGDC Host](/guides/publier/) pour mettre le site en ligne.
+- [Écrire en MDX](/guides/ecrire/) pour les titres, les liens, les images et le code.
+- [docs.json](/reference/docs-json/) pour toutes les options.
+
+---
+
+Source : /guides/publier/
+
+# Publier avec HGDC Host
+
+HGDC Host construit ton site à chaque push et le sert depuis son serveur. La console `docs.hgdc.ch` relit ensuite le site publié pour indexer l’assistant.
+
+## Mettre la doc en ligne
+
+1. **Importer le dépôt**
+
+   Dans HGDC Host, crée un projet à partir de ton dépôt GitHub. Host reconnaît une doc HGDC Docs (un `docs.json` et le paquet `@hgdc/docs` dans `package.json`) : il la construit avec `hgdc-docs build` et publie le dossier `dist/`. Aucun fichier de configuration à ajouter.
+
+2. **Fusionner la pull request de Host**
+
+   Host propose une pull request qui ajoute son workflow de déploiement. Fusionne-la : la doc part en production.
+
+3. **Pousser**
+
+   Chaque push sur la branche principale publie le site en production. Les autres branches ont leur préversion.
+
+## Activer HGDC Docs
+
+1. **Cliquer sur « Activer Docs »**
+
+   Sur la vue d’ensemble du projet dans HGDC Host, la carte **Assistant et recherche avec HGDC Docs** propose **Activer Docs**. Host crée le projet dans la console, dans la même organisation. Il faut être admin de l’organisation, et la doc doit déjà être en production.
+
+2. **Publier une fois de plus**
+
+   Pousse une modification. Ce build reçoit l’identifiant du projet de la console : le site le porte sans que tu le recopies dans `docs.json`.
+
+3. **Laisser faire**
+
+   À chaque mise en production, Host prévient la console, qui relit `/_hgdc/corpus.json` et indexe les pages en quelques secondes. La carte de Host affiche **HGDC Docs est activé** et mène à la console. En plus, la console relit le site tous les quarts d’heure : un appel perdu se rattrape seul.
+
+> **Note**
+>
+> Le projet apparaît dans la console dès que tu t’y connectes avec ton compte HGDC. Ses réglages (domaines, assistant) s’y changent comme pour n’importe quel projet.
+
+## Ton domaine
+
+Le domaine se branche dans HGDC Host, comme pour n’importe quel site : Host annonce la nouvelle adresse à la console à la mise en production suivante. Si la doc répond sur plusieurs adresses (`docs.acme.ch` et `aide.acme.ch`), ajoute les autres dans **Réglages › Domaines** : l’assistant ne répond qu’aux pages servies par ces adresses.
+
+## Relier un projet existant
+
+Le dossier `dist/` est un site statique, il se dépose chez n’importe quel hébergeur. Hors de HGDC Host, ou pour un projet créé directement dans la console, relie la doc à la main.
+
+1. **Créer le projet dans la console**
+
+   Sur `docs.hgdc.ch`, ouvre ton organisation, puis **Nouveau projet**. Donne l’adresse de production du site, par exemple `https://docs.acme.ch`.
+
+2. **Copier l'identifiant dans docs.json**
+
+   La console affiche une ligne à copier. Ajoute-la dans `docs.json`, puis publie :
+
+   ```json
+   { "project": "k57a8m2x9q4n1b3c5d7e9f0g2h4j6k8m" }
+   ```
+
+   Sans cet identifiant, le site fonctionne mais l’assistant reste caché, et la console refuse d’indexer un site qui ne porte pas le sien.
+
+3. **Synchroniser**
+
+   Clique sur **Synchroniser** dans l’aperçu du projet. La console lit `/_hgdc/corpus.json` sur ton site et indexe chaque page, puis relit le site tous les quarts d’heure.
+
+> **Adresse publique seulement**
+>
+> La console n’accepte qu’une adresse `https://` avec un nom de domaine public. Elle ne suit pas les redirections : donne l’adresse finale du site.
+
+---
+
+Source : /guides/ecrire/
+
+# Écrire en MDX
+
+Chaque page est un fichier `.mdx` (ou `.md`) : du Markdown, plus des composants. Le chemin du fichier donne l’adresse de la page : `guides/publier.mdx` devient `/guides/publier/`.
+
+## Métadonnées
+
+Le haut de la page, entre deux lignes `---`, décrit la page.
+
+```mdx
+---
+title: Publier avec HGDC Host
+sidebarTitle: Publier
+description: Mettre la doc en ligne et brancher l'assistant.
+---
+```
+
+| Champ          | Rôle                                                                         |
+| -------------- | ---------------------------------------------------------------------------- |
+| `title`        | Titre de la page, obligatoire. Aussi le titre de l’onglet du navigateur.     |
+| `sidebarTitle` | Libellé plus court dans la barre latérale.                                   |
+| `description`  | Une phrase. Reprise par les moteurs de recherche, `llms.txt` et l’assistant. |
+
+## Titres et sections
+
+Commence les sections à `##`. Chaque titre reçoit une ancre (`#publier-avec-host`) : c’est elle que l’assistant cite dans ses sources. Un titre clair donne donc une source claire.
+
+> **Astuce**
+>
+> Une section par question qu’on te pose. L’assistant découpe la doc par titre : une section courte et nommée simplement est retrouvée plus souvent.
+
+## Liens
+
+Les liens internes s’écrivent avec le chemin de la page : `[Publier](/guides/publier/)`. Pour une section : `[le domaine](/guides/publier/#ton-domaine)`.
+
+## Images
+
+Range les images dans `images/`, `img/`, `logo/`, `assets/` ou `static/`, et cite-les avec un chemin qui commence par `/`. Seuls les médias de ces dossiers, le logo et le favicon de `docs.json`, et tout le dossier `public/` (servi à la racine) sont publiés : un fichier oublié ailleurs dans le dépôt ne part jamais en ligne.
+
+```mdx
+![Le tableau de bord](/images/tableau-de-bord.png)
+```
+
+Pour une légende, entoure l’image d’un cadre :
+
+```mdx
+<Frame caption="Le tableau de bord après la première publication">
+  ![Le tableau de bord](/images/tableau-de-bord.png)
+</Frame>
+```
+
+## Code
+
+Les blocs de code sont colorés et ont un bouton Copier. Indique le langage après les trois accents graves :
+
+````mdx
+```bash
+npm run build
+```
+````
+
+## Ce qui n’est pas publié
+
+Les fichiers qui commencent par `_` (comme `_brouillon.mdx`), `README.md`, `CHANGELOG.md` et les dossiers `node_modules`, `dist` ou cachés ne deviennent pas des pages.
+
+---
+
+Source : /guides/composants/
+
+# Composants
+
+Ces composants s’utilisent directement dans une page `.mdx`, sans `import`. Ils portent les mêmes noms que chez Mintlify.
+
+## Encadrés
+
+> **Note**
+>
+> Une information utile à côté du texte.
+
+> **Astuce**
+>
+> Un conseil qui fait gagner du temps.
+
+> **Attention**
+>
+> Un piège à éviter.
+
+> **Danger**
+>
+> Une action qui détruit des données.
+
+```mdx
+<Note>Une information utile à côté du texte.</Note>
+<Tip title="Astuce">Un conseil qui fait gagner du temps.</Tip>
+<Warning>Un piège à éviter.</Warning>
+<Danger>Une action qui détruit des données.</Danger>
+```
+
+`<Info>` et `<Check>` existent aussi. Chacun accepte un `title`.
+
+## Étapes
+
+1. **Installer**
+
+   Ajoute le paquet.
+
+2. **Configurer**
+
+   Écris `docs.json`.
+
+```mdx
+<Steps>
+  <Step title="Installer">Ajoute le paquet.</Step>
+  <Step title="Configurer">Écris `docs.json`.</Step>
+</Steps>
+```
+
+## Cartes
+
+[Avec un lien](/guides/publier/)
+
+[Toute la carte est cliquable.](/guides/publier/)
+
+Sans lien
+
+Pour présenter une idée.
+
+```mdx
+<CardGroup cols={2}>
+  <Card title="Avec un lien" href="/guides/publier/">Toute la carte est cliquable.</Card>
+  <Card title="Sans lien">Pour présenter une idée.</Card>
+</CardGroup>
+```
+
+`cols` va de 1 à 4. Sur téléphone, les cartes passent l’une sous l’autre.
+
+## Onglets
+
+```bash
+npm install --save-dev @hgdc/docs
+```
+
+```bash
+bun add --dev @hgdc/docs
+```
+
+```mdx
+<Tabs>
+  <Tab title="npm">…</Tab>
+  <Tab title="Bun">…</Tab>
+</Tabs>
+```
+
+## Accordéons
+
+Faut-il un compte HGDC pour écrire ?
+
+Non. Le site se construit sans compte. Le compte sert à la console : publication suivie et assistant.
+
+Puis-je garder mes composants Mintlify ?
+
+Ceux de cette page, oui. Les autres s’affichent comme du texte : remplace-les ou écris-nous.
+
+```mdx
+<AccordionGroup>
+  <Accordion title="Question">Réponse.</Accordion>
+</AccordionGroup>
+```
+
+## Dans le Markdown publié
+
+Chaque composant a une forme Markdown : un encadré devient une citation qui commence par son titre en gras, une étape devient un élément de liste numérotée. C’est cette forme que lisent l’assistant, `llms.txt` et les outils d’IA.
+
+---
+
+Source : /guides/navigation/
+
+# Navigation, onglets et versions
+
+La navigation se décrit dans `docs.json`, sous `navigation`. Choisis **une** forme : `pages`, `groups`, `tabs` ou `versions`.
+
+## Pages et groupes
+
+Pour une petite doc, une liste de groupes suffit. Un groupe peut contenir d’autres groupes.
+
+```json
+{
+  "navigation": {
+    "groups": [
+      { "group": "Démarrer", "pages": ["index", "installation"] },
+      {
+        "group": "Guides",
+        "pages": ["guides/facturer", { "group": "Avancé", "expanded": false, "pages": ["guides/webhooks"] }]
+      }
+    ]
+  }
+}
+```
+
+Une page s’écrit sans extension ni `/` au début : `guides/facturer` pour `guides/facturer.mdx`. Une page citée mais absente fait échouer le build, avec la liste de ce qui manque.
+
+## Onglets
+
+Au-delà d’une vingtaine de pages, sépare les grandes parties en onglets : guides, référence, explications. Les onglets s’affichent en haut de la barre latérale ; chacun a ses propres groupes.
+
+```json
+{
+  "navigation": {
+    "tabs": [
+      { "tab": "Guides", "groups": [{ "group": "Démarrer", "pages": ["index"] }] },
+      { "tab": "Référence", "groups": [{ "group": "API", "pages": ["reference/api"] }] }
+    ]
+  }
+}
+```
+
+> **Astuce**
+>
+> Cette doc suit le découpage Diataxis : des guides pour faire, une référence pour vérifier, des explications pour comprendre.
+
+## Versions
+
+Quand ton produit garde plusieurs versions en service, chacune peut avoir sa doc. Le visiteur passe de l’une à l’autre avec un menu en haut de la barre latérale.
+
+```json
+{
+  "navigation": {
+    "versions": [
+      { "version": "v2", "default": true, "groups": [{ "group": "Démarrer", "pages": ["index"] }] },
+      { "version": "v1", "groups": [{ "group": "Démarrer", "pages": ["v1/index"] }] }
+    ]
+  }
+}
+```
+
+La version par défaut est celle que lisent l’assistant en priorité et l’index `llms.txt`. Les autres y figurent dans une section « Optional ».
+
+## Précédent et suivant
+
+En bas de chaque page, les liens Précédent et Suivant suivent l’ordre de la navigation, sans sortir de l’onglet ouvert.
+
+---
+
+Source : /guides/theme/
+
+# Thème et logo
+
+Le site suit la DA de HGDC par défaut : gris neutres, coins arrondis, Inter pour le texte. Tu changes trois choses : la couleur, le logo et le favicon.
+
+## Couleur
+
+```json
+{ "colors": { "primary": "#0f766e" } }
+```
+
+La couleur sert aux liens, à l’onglet actif et aux renvois de l’assistant. Sa teinte est gardée ; sa luminosité est ajustée pour que les liens restent lisibles (contraste de 4,5:1 au moins), en clair comme en sombre.
+
+Pour une couleur différente en mode sombre, ajoute `"dark": "#5eead4"`.
+
+> **Note**
+>
+> Dans la console, **Réglages › Thème** montre l’effet d’une couleur en clair et en sombre, et prépare la ligne à copier dans `docs.json`.
+
+## Logo
+
+```json
+{ "logo": { "light": "/images/logo-clair.svg", "dark": "/images/logo-sombre.svg" } }
+```
+
+Le chemin part de la racine du dossier de la doc. Un SVG carré ou large, de 32 pixels de haut environ, rend le mieux. Une seule image : `"logo": "/images/logo.svg"`.
+
+## Favicon
+
+```json
+{ "favicon": "/images/favicon.svg" }
+```
+
+Sans favicon, le site n’en annonce pas d’autre que `/favicon.svg` s’il existe.
+
+---
+
+Source : /guides/assistant/
+
+# L'assistant IA
+
+L’assistant ajoute un bouton **Demander à l’IA** en bas à droite de chaque page, et `Ctrl I` l’ouvre au clavier. Le visiteur pose sa question ; l’assistant cherche dans ta doc et répond en quelques phrases, avec des renvois numérotés vers les sections utilisées.
+
+## D’où viennent les réponses
+
+1. La question est cherchée dans les pages publiées de ta doc, et seulement là.
+2. Les passages les plus proches sont donnés au modèle Claude, avec une consigne : répondre à partir de ces passages, citer chaque affirmation, ne rien inventer.
+3. Seuls les passages réellement cités deviennent des sources sous la réponse.
+
+Si rien dans la doc ne correspond, l’assistant répond qu’il ne trouve pas, sans appeler le modèle. Une réponse sans aucune source est traitée de la même façon.
+
+> **Les réponses restent générées par IA**
+>
+> Le widget le rappelle sous chaque échange. Une source citée se vérifie en un clic.
+
+## Activer et désactiver
+
+L’assistant est actif dès que `docs.json` porte l’identifiant `project` et que la console a indexé le site. Pour le couper :
+
+- dans la console, **Assistant › Assistant sur le site** (effet immédiat) ;
+- ou dans `docs.json`, `"assistant": { "enabled": false }` (au prochain build).
+
+## Quota
+
+Chaque organisation dispose d’un nombre de questions par mois, toutes docs confondues : 500 dans l’offre de départ. La console affiche la consommation. Au-delà, l’assistant répond qu’il a atteint sa limite, et HGDC relève le plafond sur demande.
+
+Pour éviter qu’un seul visiteur épuise le quota, chaque visiteur a droit à 6 questions par minute, et chaque doc à 30.
+
+## Tester et lire le journal
+
+**Assistant › Tester l’assistant** pose une question comme un visiteur. Le **journal** garde les questions des 90 derniers jours avec leur état :
+
+| État     | Ce que ça veut dire                                               |
+| -------- | ----------------------------------------------------------------- |
+| Répondu  | L’assistant a répondu en citant la doc.                           |
+| Hors doc | Rien dans la doc ne répond. Souvent une page à écrire.            |
+| Erreur   | Le modèle n’a pas répondu ; le visiteur a été invité à réessayer. |
+
+> **Astuce**
+>
+> Lis les questions « hors doc » une fois par semaine : c’est la liste des pages qui manquent, écrite par tes visiteurs.
+
+---
+
+Source : /guides/agents/
+
+# llms.txt et MCP
+
+Les assistants de code et les agents lisent la documentation pour écrire du code juste. HGDC Docs leur donne trois portes d’entrée, sans rien à configurer.
+
+## llms.txt
+
+Chaque site publie à sa racine :
+
+- `/llms.txt` : l’index de la doc au format [llmstxt.org](https://llmstxt.org), une ligne par page avec sa description, rangées par onglet et par groupe. Le même fichier répond aussi sur `/.well-known/llms.txt`.
+- `/llms-full.txt` : toute la doc en un seul fichier Markdown.
+
+## Une page en Markdown
+
+Chaque page existe aussi en Markdown à la même adresse suivie de `.md` : `/guides/publier.md` pour `/guides/publier/`. Les pages l’annoncent dans leur `<head>` avec `rel="alternate"`.
+
+En haut de chaque page, **Copier pour un LLM** copie ce Markdown. Le menu à côté ouvre la page dans Claude ou ChatGPT, ou affiche le Markdown.
+
+## Serveur MCP
+
+Chaque projet a un serveur MCP en lecture seule. L’adresse est dans l’aperçu du projet, dans la console :
+
+```text
+https://docs.hgdc.ch/mcp/<identifiant du projet>
+```
+
+Dans Claude Code :
+
+```bash
+claude mcp add --transport http acme-docs https://docs.hgdc.ch/mcp/<identifiant du projet>
+```
+
+Le serveur propose trois outils :
+
+| Outil         | Rôle                                                                                         |
+| ------------- | -------------------------------------------------------------------------------------------- |
+| `search_docs` | Cherche dans la doc et rend les passages les plus proches, avec l’adresse de chaque section. |
+| `get_page`    | Rend une page complète en Markdown, à partir de son chemin.                                  |
+| `list_pages`  | Liste les pages avec leur titre et leur chemin.                                              |
+
+Le détail du protocole est dans la [référence MCP](/reference/mcp/).
+
+---
+
+Source : /reference/docs-json/
+
+# docs.json
+
+`docs.json` vit à la racine du dossier de la doc. Il reprend le format de Mintlify : les champs que HGDC Docs ne gère pas sont acceptés et ignorés. Pour l’autocomplétion dans ton éditeur, ajoute `"$schema": "https://docs.hgdc.ch/docs.schema.json"`.
+
+## Champs
+
+| Champ                | Type                         | Obligatoire | Rôle                                                                                                                        |
+| -------------------- | ---------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `name`               | texte                        | oui         | Nom de la doc, en tête du site et dans `llms.txt`. 80 caractères au plus.                                                   |
+| `description`        | texte                        | non         | Une phrase de présentation.                                                                                                 |
+| `navigation`         | objet                        | oui         | Pages, groupes, onglets ou versions. Voir [Navigation](/guides/navigation/).                                                |
+| `project`            | texte                        | non         | Identifiant du projet dans la console. Active l’assistant et l’indexation.                                                  |
+| `language`           | `fr`, `en`, `de`, `it`       | non         | Langue de l’interface du site. `fr` par défaut.                                                                             |
+| `colors.primary`     | couleur `#rrggbb`            | non         | Couleur des liens et des éléments actifs.                                                                                   |
+| `colors.dark`        | couleur `#rrggbb`            | non         | La même, en mode sombre.                                                                                                    |
+| `logo`               | chemin, ou `{ light, dark }` | non         | Logo affiché en tête.                                                                                                       |
+| `favicon`            | chemin                       | non         | Icône de l’onglet du navigateur.                                                                                            |
+| `footer.socials`     | objet                        | non         | Liens vers tes réseaux : `github`, `gitlab`, `linkedin`, `x.com`, `mastodon`, `discord`, `youtube`, `instagram`, `bluesky`. |
+| `assistant.enabled`  | oui / non                    | non         | `false` cache l’assistant du site.                                                                                          |
+| `assistant.endpoint` | adresse                      | non         | API de l’assistant, à ne changer que pour un environnement de test.                                                         |
+
+## Navigation
+
+Quatre formes, une seule à la fois :
+
+| Forme      | Exemple                                                   |
+| ---------- | --------------------------------------------------------- |
+| `pages`    | `["index", "installation"]`                               |
+| `groups`   | `[{ "group": "Démarrer", "pages": ["index"] }]`           |
+| `tabs`     | `[{ "tab": "Guides", "groups": [...] }]`                  |
+| `versions` | `[{ "version": "v2", "default": true, "groups": [...] }]` |
+
+Un groupe accepte `expanded: false` pour être replié par défaut, et peut contenir des groupes.
+
+## Erreurs
+
+Un `docs.json` invalide fait échouer le build avec la liste des problèmes, par exemple :
+
+```text
+docs.json invalide :
+- colors.primary : couleur attendue au format #rrggbb
+- navigation : utiliser une seule forme parmi versions, tabs, groups ou pages
+```
+
+---
+
+Source : /reference/cli/
+
+# La commande hgdc-docs
+
+`hgdc-docs` est installée avec le paquet `@hgdc/docs`. Elle se lance depuis le dossier de la doc, ou avec le chemin du dossier en argument.
+
+## Commandes
+
+| Commande            | Effet                                                                                                      |
+| ------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `hgdc-docs dev`     | Site local sur `http://localhost:4321`, rechargé à chaque modification.                                    |
+| `hgdc-docs build`   | Site statique dans `dist/`, avec la recherche, `llms.txt`, les pages Markdown et le corpus de l’assistant. |
+| `hgdc-docs preview` | Sert le dernier build, pour vérifier avant de pousser.                                                     |
+
+Options : `--port 4000` change le port de `dev` et `preview`, `--help` affiche l’aide.
+
+## Variables d’environnement
+
+| Variable         | Rôle                                                                                                                                                                     |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `HGDC_DOCS_SITE` | Adresse publique du site (`https://docs.acme.ch`). Rend les liens de `llms.txt` absolus et produit le sitemap. Sur HGDC Host, l’adresse de production est reprise seule. |
+| `HGDC_DOCS_OUT`  | Dossier de sortie, `dist/` par défaut.                                                                                                                                   |
+| `HGDC_DOCS_API`  | API de l’assistant, `https://docs.hgdc.ch` par défaut.                                                                                                                   |
+
+## Ce que contient dist/
+
+| Fichier                                             | Contenu                                                        |
+| --------------------------------------------------- | -------------------------------------------------------------- |
+| `index.html`, `<page>/index.html`                   | Les pages du site.                                             |
+| `<page>.md`                                         | Chaque page en Markdown.                                       |
+| `llms.txt`, `llms-full.txt`, `.well-known/llms.txt` | L’index et la doc complète pour les agents.                    |
+| `pagefind/`                                         | L’index de la recherche.                                       |
+| `_hgdc/corpus.json`                                 | Le contenu publié, lu par la console pour indexer l’assistant. |
+
+---
+
+Source : /reference/api-assistant/
+
+# API de l'assistant
+
+Le widget du site appelle une seule route. Tu peux l’appeler toi-même pour intégrer l’assistant dans ton application, depuis une page servie par une adresse déclarée dans la console.
+
+## Requête
+
+```http
+POST https://docs.hgdc.ch/api/v1/ask
+Content-Type: application/json
+Origin: https://docs.acme.ch
+```
+
+```json
+{
+  "project": "k57a8m2x9q4n1b3c5d7e9f0g2h4j6k8m",
+  "question": "Comment publier ma doc ?",
+  "page": "/guides/publier/",
+  "previous": ["j97f2k8m1q4n6b3c5d7e9f0g2h4j6k8m"]
+}
+```
+
+| Champ      | Rôle                                                                                                                                            |
+| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project`  | Identifiant du projet.                                                                                                                          |
+| `question` | 2 à 1 000 caractères.                                                                                                                           |
+| `page`     | Chemin de la page ouverte. Ses passages sont légèrement favorisés.                                                                              |
+| `previous` | Les `id` des réponses précédentes de la conversation, 3 au plus. L’assistant relit lui-même ce qu’il a répondu, dans les deux dernières heures. |
+
+L’en-tête `Origin` doit être l’adresse du site ou un des domaines déclarés dans **Réglages › Domaines**. Chaque visiteur a droit à 6 questions par minute et 100 par jour.
+
+## Réponse
+
+```json
+{
+  "id": "j97f…",
+  "status": "answered",
+  "answer": "Importe le dépôt dans HGDC Host[^1], puis synchronise le projet dans la console[^2].",
+  "sources": [
+    { "n": 1, "title": "Publier avec HGDC Host", "section": "Avec HGDC Host", "url": "https://docs.acme.ch/guides/publier/#avec-hgdc-host" },
+    { "n": 2, "title": "Publier avec HGDC Host", "section": "Relier la console", "url": "https://docs.acme.ch/guides/publier/#relier-la-console" }
+  ]
+}
+```
+
+`answer` est du Markdown simple ; `[^n]` renvoie à la source `n`. `status` vaut `no_answer` quand la doc ne répond pas : `sources` est alors vide.
+
+## Erreurs
+
+| Code HTTP | `error.code`         | Quand                                               |
+| --------- | -------------------- | --------------------------------------------------- |
+| 400       | `invalid_request`    | Corps illisible ou question trop courte.            |
+| 403       | `origin_not_allowed` | La page n’est pas servie par une adresse du projet. |
+| 403       | `assistant_disabled` | L’assistant est coupé dans la console.              |
+| 404       | `project_not_found`  | Identifiant inconnu.                                |
+| 409       | `not_indexed`        | Le site n’a pas encore été synchronisé.             |
+| 429       | `rate_limited`       | Trop de questions en une minute.                    |
+| 429       | `quota_exceeded`     | Le quota mensuel de l’organisation est atteint.     |
+| 503       | `unavailable`        | Le modèle ne répond pas. Réessayer plus tard.       |
+
+Chaque erreur porte aussi `error.message`, une phrase en français à montrer telle quelle.
+
+---
+
+Source : /reference/mcp/
+
+# Serveur MCP
+
+Le serveur suit le [Model Context Protocol](https://modelcontextprotocol.io), transport Streamable HTTP, sans session : chaque requête est indépendante.
+
+```text
+POST https://docs.hgdc.ch/mcp/<identifiant du projet>
+Content-Type: application/json
+Accept: application/json, text/event-stream
+```
+
+Il répond en JSON (`application/json`), jamais en flux. `GET` et `DELETE` répondent 405. Versions du protocole acceptées : `2025-11-25`, `2025-06-18`, `2025-03-26`.
+
+## Méthodes
+
+| Méthode      | Réponse                                                   |
+| ------------ | --------------------------------------------------------- |
+| `initialize` | Nom du serveur, capacités (`tools`) et consignes d’usage. |
+| `ping`       | Objet vide.                                               |
+| `tools/list` | Les trois outils ci-dessous.                              |
+| `tools/call` | Le résultat de l’outil, en texte.                         |
+
+Une notification (message sans `id`) reçoit un 202 sans corps.
+
+## Outils
+
+### search_docs
+
+| Paramètre | Type           | Rôle                              |
+| --------- | -------------- | --------------------------------- |
+| `query`   | texte          | Question ou mots-clés.            |
+| `limit`   | entier, 1 à 10 | Nombre de passages, 5 par défaut. |
+
+Rend les passages trouvés, chacun avec son titre, sa section, son adresse et son texte.
+
+### get_page
+
+| Paramètre | Type  | Rôle                                                             |
+| --------- | ----- | ---------------------------------------------------------------- |
+| `path`    | texte | Chemin de la page (`/guides/publier/`), ou son adresse complète. |
+
+Rend la page en Markdown, précédée de son adresse.
+
+### list_pages
+
+Sans paramètre. Rend la liste des pages publiées.
+
+## Limites
+
+Le serveur est public et en lecture seule : il ne donne accès qu’à ce que le site publie déjà. Chaque projet accepte 300 requêtes par minute, chaque visiteur 60. Au-delà, la réponse est un 429.
+
+---
+
+Source : /explications/fonctionnement/
+
+# Comment ça marche
+
+HGDC Docs tient en trois pièces : un modèle de site, HGDC Host qui le publie, et la console qui l’indexe pour l’assistant.
+
+## 1. Le modèle de site
+
+Le paquet `@hgdc/docs` contient un site Astro Starlight complet. `hgdc-docs build` lit ton `docs.json`, prend tes pages MDX et construit un site statique. Rien ne tourne côté serveur : le site est rapide et ne tombe pas en panne avec la console.
+
+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. La publication par HGDC Host
+
+HGDC Host lance le build dans GitHub Actions à chaque push, puis sert le dossier `dist/` sur ton domaine. La doc est une source comme une autre : préversion par branche, retour arrière, domaine.
+
+## 3. L’indexation par la console
+
+La console relit `/_hgdc/corpus.json` sur le site publié : tous les quarts d’heure, ou quand tu cliques sur **Synchroniser**. Elle vérifie que le corpus porte bien l’identifiant du projet, puis :
+
+1. découpe chaque page en passages, un par section (titre `##` ou plus fin) ;
+2. compare avec l’index existant, passage par passage : seuls les passages nouveaux sont traités ;
+3. calcule leur représentation vectorielle (embedding), qui permet de retrouver une reformulation ;
+4. supprime les passages qui ne sont plus publiés.
+
+Un build identique au précédent ne change rien à l’index.
+
+## 4. La réponse
+
+Une question passe par deux recherches : par mots (les termes exacts, comme `docs.json`) et par sens (les reformulations). Les deux classements sont fusionnés, les six meilleurs passages sont donnés au modèle Claude, qui répond en citant ceux qu’il utilise.
+
+> **Note**
+>
+> L’index d’un projet est fermé aux autres : une recherche ne voit que les passages de son propre projet, vérifiés deux fois.
+
+---
+
+Source : /explications/donnees/
+
+# Données et confidentialité
+
+## Ce qui est stocké
+
+| Donnée                                           | Où                 | Durée                          |
+| ------------------------------------------------ | ------------------ | ------------------------------ |
+| Pages publiées, en Markdown, et passages indexés | Base de la console | Tant que le projet existe      |
+| Questions des visiteurs, réponses, sources       | Base de la console | 90 jours                       |
+| Consommation mensuelle de l’assistant            | Base de la console | Tant que l’organisation existe |
+
+La console ne stocke ni l’adresse IP ni l’identité des visiteurs. L’IP sert seulement, le temps de la requête, à limiter le nombre de questions par minute.
+
+## Qui traite quoi
+
+- **Le site** est servi par HGDC Host.
+- **La recherche du site** tourne dans le navigateur du visiteur : aucune requête ne part.
+- **Les embeddings** des passages et des questions sont calculés par Mistral AI, dans l’Union européenne.
+- **Les réponses** sont rédigées par Claude, le modèle d’Anthropic, appelé directement ou par OpenRouter. La question et les passages trouvés lui sont envoyés.
+
+Sans clé d’embeddings, la recherche de l’assistant reste en plein texte : rien ne part chez Mistral.
+
+## Ce que voit l’assistant
+
+Uniquement ce que ton site publie : il lit le corpus du site public. Une page qui n’est pas publiée n’existe pas pour lui. Il ne peut ni naviguer sur le web, ni agir : il lit des passages et écrit une réponse.
+
+## Supprimer
+
+Supprimer un projet dans la console efface son index, ses pages et son journal. Le site publié et ton dépôt ne sont pas touchés.