npm - @hgdc/docs - Versions diffs - 0.4.1 → 0.4.3 - Mend

@hgdc/docs 0.4.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (184) hide show

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

@@ -1,2668 +1,852 @@
-# Host
+# Docs
-> Ton site en ligne, déployé à chaque modification.
+> Écrire une documentation en MDX, la publier avec Host et y brancher un assistant IA qui cite ses sources.
 ---
-Source : /docs/
+Source : /
-# Host
+# Bienvenue dans Docs
-Host déploie tes sites. Chaque modification donne une version en ligne, avec sa propre adresse, et la production reste sur ton domaine.
+Docs transforme un dossier de pages MDX en site de documentation. Tu écris dans ton dépôt Git, 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.
-Tu gardes tes outils : la CLI Vercel, `vercel.json` et le format Build Output API. Seule l’adresse de l’API change.
+[Ta première doc](/demarrer/premiere-doc/)
-## Par où commencer
+[Un dossier, un fichier `docs.json` et une page : ton site tourne en local en cinq minutes.](/demarrer/premiere-doc/)
-[Mettre un premier site en ligne](/docs/demarrer/premier-site/)
+[Publier avec Host](/guides/publier/)
-[Du compte à une preview, puis à la production, avec la CLI. Une quinzaine de minutes.](/docs/demarrer/premier-site/)
+[Relie le dépôt à Host : chaque push met le site à jour.](/guides/publier/)
-[Déployer depuis GitHub](/docs/demarrer/depuis-github/)
+[L'assistant IA](/guides/assistant/)
-[Importe un dépôt : chaque push construit le site et le publie.](/docs/demarrer/depuis-github/)
+[Il répond aux questions de tes visiteurs et cite les pages qu’il a utilisées.](/guides/assistant/)
-[Référence de la CLI](/docs/reference/cli/)
+[Pour les agents](/guides/agents/)
-[Les commandes `deploy`, `build`, `pull` et `link`, avec leurs options.](/docs/reference/cli/)
+[`llms.txt`, une version Markdown de chaque page et un serveur MCP en lecture.](/guides/agents/)
-[Référence de l'API](/docs/reference/api/introduction/)
+## Ce que tu obtiens
-[Les endpoints compatibles Vercel, leurs paramètres et leurs réponses.](/docs/reference/api/introduction/)
+- **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.
-## Ce que Host fait
+## Compatible avec Mintlify
-- **Des sites statiques et des frameworks** : un dossier de fichiers, ou le résultat de `vercel build` pour Astro, Vite, Next.js, SvelteKit, Nuxt, TanStack Start et React Router. Voir [Compatibilité](/docs/reference/compatibilite/).
-- **Une URL par version** : chaque déploiement a sa propre adresse, à faire valider avant de passer en production.
-- **Un domaine à toi** : tu ajoutes ton domaine, Host vérifie qu’il t’appartient et obtient le certificat HTTPS. Voir [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-- **Des variables par environnement** : production, preview et développement, avec des variables sensibles jamais relues. Voir [Variables d’environnement](/docs/guides/variables-d-environnement/).
-- **Une organisation et des rôles** : les membres se gèrent dans Account. Voir [Organisations et rôles](/docs/concepts/organisations-et-roles/).
+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.
-## Ce qui arrive en préversion
-Le rendu à la demande (SSR), les routes d’API, le proxy, le runtime edge, l’ISR et les crons s’exécutent en préversion, organisation par organisation. Les fichiers statiques et les pages pré-rendues sont servis dans tous les cas. Le détail est sur [Préversion](/docs/concepts/preversion/).
-## Les autres produits de la famille
-[Account](https://account.hgdc.ch/docs/)
-[![](/docs/images/famille/account.svg)](https://account.hgdc.ch/docs/)
-[Un seul compte pour toute la famille, avec « Se connecter avec HGDC ».](https://account.hgdc.ch/docs/)
-[Mail](https://mail.hgdc.ch/docs/)
-[![](/docs/images/famille/mail.svg)](https://mail.hgdc.ch/docs/)
-[Tes e-mails, newsletters et formulaires, envoyés depuis ton adresse.](https://mail.hgdc.ch/docs/)
-[Portal](https://portal.hgdc.ch/docs/)
-[![](/docs/images/famille/portal.svg)](https://portal.hgdc.ch/docs/)
-[Un espace partagé où ton client suit son projet, signe et paie.](https://portal.hgdc.ch/docs/)
-[Status](https://status.hgdc.ch/docs/)
-[![](/docs/images/famille/status.svg)](https://status.hgdc.ch/docs/)
-[Surveillance de tes services, heartbeats et page de statut.](https://status.hgdc.ch/docs/)
-[Analytics](https://analytics.hgdc.ch/docs/)
-[![](/docs/images/famille/analytics.svg)](https://analytics.hgdc.ch/docs/)
-[Tes visiteurs mesurés, sans cookies ni bannière.](https://analytics.hgdc.ch/docs/)
-[Docs](https://docs.hgdc.ch/docs/)
-[![](/docs/images/famille/docs.svg)](https://docs.hgdc.ch/docs/)
-[Ta documentation en MDX, avec un assistant IA qui cite ses sources.](https://docs.hgdc.ch/docs/)
----
-Source : /docs/demarrer/premier-site/
-# Mettre un premier site en ligne
-À la fin de ce parcours, ton site répond sur une adresse de preview, puis sur une adresse de production. Tu auras créé une clé d’API, installé la CLI et déployé un dossier de fichiers, sans étape de build.
-**Avant de commencer** : Node.js et npm, et un compte HGDC. Sans compte, la page [Demander un accès](https://host.hgdc.ch/acces) envoie ta demande à l’équipe, qui t’invite depuis Account.
-1. **Connecte-toi**
-   Ouvre [host.hgdc.ch](https://host.hgdc.ch) et clique **Se connecter avec HGDC**. Le même compte sert à Account, Mail et les autres produits de la famille.
-   Tu arrives sur le tableau de bord. Si tu n’as pas encore d’organisation, crée-la dans Account. Son slug apparaît dans l’adresse de l’app : `host.hgdc.ch/o/<slug>`.
-   **Vérification** : le tableau de bord affiche le nom de ton organisation.
-2. **Crée une clé d'API**
-   Dans ton organisation, ouvre l’onglet **Clés d’API** et crée une clé. Elle commence par `ah_` et ne s’affiche qu’une fois : copie-la tout de suite.
-   La clé remplace le mot de passe de la CLI. Le détail est dans [Clés d’API](/docs/guides/cle-d-api/).
-   **Vérification** : la clé apparaît dans la liste, avec le nom que tu lui as donné.
-3. **Installe la CLI Vercel**
-   ```bash
-   npm install --global vercel@63
-   ```
-   Host est testé avec la version 63 de la CLI. Une autre version peut fonctionner, mais ce n’est pas garanti.
-   **Vérification** : `vercel --version` affiche une version 63.x.
-4. **Donne la clé et l'adresse de l'API à la CLI**
-   Dans le terminal, exporte la clé, puis passe l’adresse de l’API à chaque commande avec `--api`. La CLI lit la clé dans `VERCEL_TOKEN`.
-   ```bash
-   export VERCEL_TOKEN=ah_…
-   vercel --api https://api.host.hgdc.ch whoami
-   ```
-   **Vérification** : la commande affiche ton identifiant, sans demander de connexion dans le navigateur. Pour ne pas retaper l’adresse, voir [Configurer la CLI](/docs/reference/cli/#configurer-la-cli).
-5. **Prépare un site**
-   Crée un dossier `mon-site` avec un fichier `index.html` à sa racine :
-   ```html
-   <!doctype html>
-   <html lang="fr">
-     <head>
-       <meta charset="utf-8" />
-       <title>Mon premier site</title>
-     </head>
-     <body>
-       <h1>Bonjour depuis Host</h1>
-     </body>
-   </html>
-   ```
-   **Vérification** : `index.html` se trouve directement dans `mon-site`, pas dans un sous-dossier.
-6. **Déploie une preview**
-   Depuis le dossier du site :
-   ```bash
-   cd mon-site
-   vercel --api https://api.host.hgdc.ch deploy
-   ```
-   Au premier envoi, la CLI crée le projet sous le nom du dossier et le relie au dossier dans `.vercel/project.json`. Elle affiche ensuite l’adresse du déploiement, de la forme `https://mon-site-abc123xyz.hgdc.cloud`.
-   **Vérification** : ouvre l’adresse affichée. La page « Bonjour depuis Host » s’affiche. Le déploiement apparaît aussi dans l’onglet **Déploiements** du projet, avec l’état **Prêt**.
-7. **Passe en production**
-   ```bash
-   vercel --api https://api.host.hgdc.ch deploy --prod
-   ```
-   Le déploiement devient la production du projet. La CLI affiche l’adresse de production du projet, `https://mon-site.hgdc.cloud`, qui suivra chaque mise en production. Les domaines de production du projet le servent aussi.
-   **Vérification** : l’onglet **Vue d’ensemble** du projet montre ce déploiement comme production.
-## Et après
-- Pour mettre le site sur ton propre domaine, suis [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-- Pour déployer à chaque `git push`, suis [Déployer depuis GitHub](/docs/demarrer/depuis-github/).
-## Si ça ne marche pas
-- La CLI répond `403` : la clé est mal copiée, ou elle ne commence pas par `ah_`. Voir [Dépannage](/docs/guides/depannage/#la-cli-renvoie-403).
-- La page affiche `404` : le dossier envoyé n’a pas d’`index.html` à sa racine.
----
-Source : /docs/demarrer/depuis-github/
-# Déployer un site depuis GitHub
-Dans ce parcours, tu importes un dépôt GitHub dans Host. À la fin, un `git push` sur la branche principale met ton site en production, et chaque autre branche reçoit sa propre preview.
-**Avant de commencer** :
-- un compte HGDC et une organisation dans Account ;
-- un dépôt GitHub avec un site qui se construit (Astro, Vite, Next.js ou un site statique) ;
-- le droit d’écriture (push) sur ce dépôt. Un dépôt où tu n’as que la lecture ne s’importe pas.
-1. **Ouvre un nouveau projet**
-   Dans ton organisation, clique **Nouveau projet**, puis **Importer depuis GitHub**.
-   **Vérification** : la liste des dépôts accessibles s’affiche, ou Host te propose d’installer l’app GitHub.
-2. **Installe l'app GitHub**
-   Installe l’app **Host** sur ton compte GitHub ou sur celui de ton organisation. Tu peux la limiter à quelques dépôts.
-   L’app ne demande que les droits dont le workflow a besoin. Le détail est dans [Déployer depuis GitHub](/docs/guides/deployer-depuis-github/).
-   **Vérification** : le dépôt choisi apparaît dans la liste de Host.
-3. **Choisis le dépôt et vérifie les réglages**
-   Sélectionne le dépôt. Host lit le projet et propose le framework, les commandes d’installation et de build, la version de Node.js et la branche de production.
-   Si le site est dans un sous-dossier ou dans un monorepo, choisis le dossier de l’app. Voir [Monorepo et sous-dossier](/docs/guides/monorepo/).
-   **Vérification** : le framework détecté correspond à ton site. Corrige les réglages qui ne correspondent pas.
-4. **Fusionne la PR d'installation**
-   L’import ouvre une pull request qui ajoute le fichier `.github/workflows/hgdc-host.yml` et pose le secret `HGDC_HOST_TOKEN` dans le dépôt. Relis-la, puis fusionne-la sur la branche principale.
-   Le secret est une clé limitée à ce projet. Elle ne peut ni créer de projet ni lire les autres.
-   **Vérification** : la PR est fusionnée, et le fichier `hgdc-host.yml` existe sur la branche principale.
-5. **Pousse une modification**
-   Modifie une page du site, puis pousse-la sur la branche principale :
-   ```bash
-   git add .
-   git commit -m "docs: ajoute une page de test"
-   git push
-   ```
-   **Vérification** : l’onglet **Déploiements** du projet affiche un déploiement en cours, puis **Prêt**. L’adresse de production affiche la modification.
-6. **Ouvre une preview**
-   Crée une branche, pousse-la, puis ouvre une pull request sur la branche principale. Host construit la branche et publie une preview.
-   **Vérification** : le commit affiche le statut du déploiement avec son lien. La preview répond sur son adresse `hgdc.cloud`.
-## Et après
-- Pour mettre le site sur ton domaine, suis [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-- Pour les variables de build, comme une clé publique ou l’adresse d’une API, suis [Variables d’environnement](/docs/guides/variables-d-environnement/).
-- Pour comprendre ce qui se passe à chaque push, lis [Déploiements](/docs/concepts/deploiements/).
-## Si ça ne marche pas
-- Le build n’apparaît pas après le push : vérifie que la PR d’installation est fusionnée. Voir [Dépannage](/docs/guides/depannage/#le-build-github-est-absent).
-- Le build échoue : ouvre le déploiement dans Host, la sortie du build y est affichée en direct.
----
-Source : /docs/guides/cle-d-api/
-# Créer et révoquer une clé d'API
-Une clé d’API authentifie la CLI et l’API. Ce guide crée une clé, la range au bon endroit, puis la révoque.
-**Résultat attendu** : une clé qui commence par `ah_`, visible dans la liste **Clés actives** de ton organisation, et révocable depuis la liste.
-**Avant de commencer** : être admin ou propriétaire de l’organisation. Les membres ne voient pas l’onglet **Clés d’API**.
-## Créer une clé
-1. **Ouvre l'onglet Clés d'API**
-   Dans ton organisation, ouvre **Clés d’API**, puis clique **Créer une clé**.
-2. **Donne-lui un nom parlant**
-   Choisis un nom qui dit où la clé sert, par exemple `Poste de Léa` ou `CI GitHub`. Il t’aidera à savoir quelle clé révoquer.
-3. **Copie la clé tout de suite**
-   La fenêtre **Nouvelle clé d’API** affiche la clé complète une seule fois. Clique **Copier la clé** et range-la dans un gestionnaire de mots de passe.
-   Host ne garde qu’une empreinte de la clé. Si tu la perds, aucune copie n’est possible : crée une nouvelle clé et révoque l’ancienne.
-   **Vérification** : la clé apparaît dans **Clés actives** avec son nom et la date de création.
-## Choisir la bonne portée
-| Sorte de clé       | Qui la crée                                  | Ce qu’elle peut faire                                            |
-| ------------------ | -------------------------------------------- | ---------------------------------------------------------------- |
-| Clé d’organisation | Un admin ou un propriétaire, dans la console | Tous les projets de l’organisation, et créer de nouveaux projets |
-| Clé de projet      | L’app GitHub, à l’import d’un dépôt          | Un seul projet. Tout autre projet répond `404`                   |
-Pour ton poste de développement, prends une clé d’organisation. Pour un dépôt, laisse l’app GitHub poser sa clé de projet.
-> **Attention**
->
-> Une clé d’organisation lit les variables non sensibles de tous les projets avec `vercel pull`. Ne la mets jamais dans un dépôt, ni dans du code envoyé au navigateur.
-## Utiliser la clé
-La CLI lit la clé dans la variable `VERCEL_TOKEN`, qui évite de l’écrire dans l’historique du shell :
-```bash
-export VERCEL_TOKEN=ah_…
-vercel --api https://api.host.hgdc.ch deploy
-```
-Pour une requête HTTP, envoie-la dans l’en-tête `Authorization` :
-```bash
-curl https://api.host.hgdc.ch/v2/user \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
-```
-## Révoquer une clé
-1. **Repère la clé**
-   Dans **Clés actives**, regarde la date de **Dernière utilisation**. Une clé inutilisée depuis longtemps peut être révoquée sans risque.
-2. **Révoque-la**
-   Clique **Révoquer la clé**, puis confirme.
-   **Vérification** : la clé disparaît de **Clés actives**. Une requête avec cette clé répond `403` avec le code `forbidden`.
-Une clé cesse aussi de fonctionner quand la personne qui l’a créée quitte l’organisation dans Account. Une clé n’expire pas d’elle-même.
-## Si ça ne marche pas
-- La CLI répond `403`, avec le message « Clé d’API absente ou invalide » : la clé est mal copiée, ou elle a été révoquée. Voir [Dépannage](/docs/guides/depannage/#la-cli-renvoie-403).
-- Le message « Cette clé est limitée à un autre projet » apparaît : tu utilises la clé d’un dépôt pour un autre projet. Crée une clé d’organisation.
-## Voir aussi
-- [Clés d’API et sécurité](/docs/concepts/secrets-et-coffre/) : ce que Host garde et ce qu’il ne garde pas.
-- [Référence de l’API](/docs/reference/api/introduction/#authentification) : l’en-tête, la portée et les limites.
----
-Source : /docs/guides/deployer-depuis-github/
-# Déployer depuis GitHub
-L’intégration GitHub construit ton site dans GitHub Actions, sur les minutes de ton compte, et publie le résultat. Chaque push sur la branche principale part en production. Chaque autre branche reçoit une preview.
-**Résultat attendu** : un push déclenche un build visible dans Host, avec sa sortie en direct, puis un déploiement **Prêt**.
-**Avant de commencer** : un dépôt où tu as le droit d’écriture, et un site qui se construit avec une commande de build.
-## Importer un dépôt
-1. **Installe l'app GitHub**
-   Dans **Nouveau projet**, choisis **Importer depuis GitHub** et installe l’app **Host** sur ton compte GitHub ou sur celui de ton organisation. Tu peux la restreindre à certains dépôts.
-   Host s’en sert pour lire la liste des dépôts, ouvrir la pull request d’installation et déclencher les builds.
-2. **Choisis le dépôt**
-   Seuls les dépôts où tu peux pousser apparaissent. Un dépôt où tu n’as que la lecture ne s’importe pas : l’import ouvre une pull request et pose un secret dans le dépôt.
-3. **Vérifie les réglages détectés**
-   Host propose le framework, les commandes d’installation et de build, la version de Node.js et la branche de production. Corrige ce qui ne correspond pas avant de continuer.
-   Pour un site dans un sous-dossier, voir [Monorepo et sous-dossier](/docs/guides/monorepo/).
-4. **Fusionne la pull request**
-   L’import ouvre une pull request qui ajoute `.github/workflows/hgdc-host.yml` et pose le secret `HGDC_HOST_TOKEN`.
-   **Vérification** : une fois la PR fusionnée, un push sur la branche principale déclenche un build.
-## Ce que fait le workflow
-1. Il annonce le build à Host. Le déploiement apparaît dans la console dès le début, avec sa sortie en direct.
-2. Il restaure le cache du run précédent : `node_modules` tant que ton fichier de verrouillage ne change pas, le cache de ton framework et la CLI Vercel.
-3. Il lance `vercel pull` pour récupérer les réglages et les variables, puis `vercel build`.
-4. Il envoie le résultat avec `vercel deploy --prebuilt`, avec `--prod` sur la branche de production.
-5. En cas d’échec ou d’annulation, il le signale. Le déploiement passe à **Erreur** ou **Annulé**.
-Deux pushes sur la même branche : le premier build est annulé au profit du second. Le premier build d’une branche remplit le cache, les suivants vont plus vite.
-Pour repartir d’un cache propre, supprime les caches `hgdc-host-*` dans l’onglet **Actions** du dépôt.
-## Déployer sans pousser
-Dans Host, deux actions relancent un build sans nouveau commit :
-- **Déployer en production** lance le workflow sur la branche de production.
-- **Redéployer**, sur un déploiement, reconstruit le même commit avec les variables d’aujourd’hui.
-Le build passe par GitHub Actions, comme pour un push.
-## Mettre le workflow à jour
-Quand Host fait évoluer son workflow, l’onglet **Git** du projet propose **Mettre à jour le workflow**. Host ouvre une pull request qui remplace le fichier. Fusionne-la, puis déploie.
-## Débrancher le dépôt
-Dans l’onglet **Git**, **Débrancher** révoque la clé posée dans le dépôt. Les pushes suivants n’arrivent plus à Host. Supprime ensuite le fichier `.github/workflows/hgdc-host.yml` du dépôt. Les dépôts branchés avant le changement de nom gardent `.github/workflows/smartflow-host.yml` et le secret `SMARTFLOW_HOST_TOKEN` : ils continuent de fonctionner, sans rien changer de ton côté.
-Les variables du projet restent en place, devenues manuelles. Aucun build ne les perd d’un coup.
-> **Astuce**
->
-> Tu préfères écrire ton propre workflow ? Voir [GitHub Actions sans l’application](/docs/guides/github-actions-sans-application/).
-## Si ça ne marche pas
-Voir [Dépannage](/docs/guides/depannage/#le-build-github-est-absent) pour le build qui n’apparaît pas, et la sortie du run dans l’onglet **Actions** du dépôt pour le build qui échoue.
----
-Source : /docs/guides/github-actions-sans-application/
-# Déployer avec GitHub Actions, sans l'application
-Tu préfères garder la main sur ton workflow, ou tu utilises une autre CI ? L’app GitHub n’est pas nécessaire : la CLI suffit. Ce guide met en place un workflow qui construit et déploie à chaque push.
-**Résultat attendu** : un push sur la branche principale publie en production, et un push sur une autre branche publie une preview.
-**Ce que tu perds par rapport à l’app** : le déploiement n’apparaît dans Host qu’à l’envoi, sans sortie de build en direct, et le statut du commit n’est pas mis à jour.
-## Relier le dossier au projet
-1. **Lance un premier déploiement en local**
-   Depuis le dossier du projet, avec ta clé d’organisation :
-   ```bash
-   export VERCEL_TOKEN=ah_…
-   vercel --api https://api.host.hgdc.ch deploy --yes
-   ```
-   La commande crée `.vercel/project.json`, qui contient `orgId` et `projectId`.
-   **Vérification** : le fichier `.vercel/project.json` existe, et le projet apparaît dans Host.
-2. **Ajoute les secrets au dépôt**
-   Dans le dépôt GitHub, ouvre **Settings → Secrets and variables → Actions** et crée trois secrets :
-   | Secret              | Valeur                                          |
-   | ------------------- | ----------------------------------------------- |
-   | `VERCEL_TOKEN`      | Une clé d’API `ah_…` d’organisation             |
-   | `VERCEL_ORG_ID`     | La valeur `orgId` de `.vercel/project.json`     |
-   | `VERCEL_PROJECT_ID` | La valeur `projectId` de `.vercel/project.json` |
-   Ne mets ni la clé ni les identifiants dans le fichier de workflow.
-3. **Ajoute le workflow**
-   Crée `.github/workflows/deploy.yml` :
-   ```yaml
-   name: Déploiement
-   on:
-     push:
-       branches: [main]
-     pull_request:
-   permissions:
-     contents: read
-   env:
-     VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
-     VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
-     VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
-     API: https://api.host.hgdc.ch
-   jobs:
-     deploy:
-       runs-on: ubuntu-latest
-       steps:
-         - uses: actions/checkout@v7
-         - uses: actions/setup-node@v7
-           with:
-             node-version: 24
-         - run: npm install --global vercel@63
-         - name: Production
-           if: github.ref == 'refs/heads/main'
-           run: |
-             vercel pull --yes --environment=production --api "$API"
-             vercel build --prod --api "$API"
-             vercel deploy --prebuilt --prod --api "$API"
-         - name: Preview
-           if: github.ref != 'refs/heads/main'
-           run: |
-             vercel pull --yes --environment=preview --api "$API"
-             vercel build --api "$API"
-             vercel deploy --prebuilt --api "$API"
-   ```
-   La CLI lit `VERCEL_TOKEN`, `VERCEL_ORG_ID` et `VERCEL_PROJECT_ID` dans l’environnement. Le projet n’a pas besoin d’un dossier `.vercel` dans le dépôt.
-   Adapte `node-version` à la version de Node.js de ton projet. Pour un site qui n’a pas de build, supprime les étapes `vercel build`.
-   **Vérification** : le run **Déploiement** apparaît dans l’onglet **Actions**, et son job se termine en vert. Le déploiement apparaît dans le projet Host.
-## Variables sensibles
-Une variable sensible n’est livrée qu’à une clé limitée au projet, celle que pose l’app GitHub. Avec une clé d’organisation, `vercel pull` ne la récupère pas.
-Si ton build a besoin d’un secret, passe-le par un secret du dépôt, puis expose-le au build avec `env:`. Ne le mets pas dans une variable publique du projet. Voir [Secrets et coffre](/docs/concepts/secrets-et-coffre/).
-## Si ça ne marche pas
-- Le job échoue sur `vercel pull` avec un `403` : la clé `VERCEL_TOKEN` est mal copiée ou révoquée. Voir [Dépannage](/docs/guides/depannage/#la-cli-renvoie-403).
-- Le job tourne, mais aucun déploiement n’apparaît : vérifie que `VERCEL_PROJECT_ID` et `VERCEL_ORG_ID` viennent bien de `.vercel/project.json`.
----
-Source : /docs/guides/deployer-un-framework/
-# Déployer un framework
-Host sert ce que `vercel build` produit : les fichiers statiques, les pages pré-rendues et, en préversion, les fonctions Node. Tu construis en local ou en CI, puis tu envoies le résultat. Les sources de ton projet ne sont jamais servies.
-**Résultat attendu** : un déploiement **Prêt** dont la page affiche ton site construit.
-**Avant de commencer** : une commande de build qui fonctionne sur ton poste, et une clé d’API dans `VERCEL_TOKEN`. Pour la liste des frameworks et de ce qui est servi pour chacun, voir [Compatibilité](/docs/reference/compatibilite/).
-## Construire puis envoyer
-1. **Construis le projet**
-   Depuis le dossier du projet :
-   ```bash
-   export VERCEL_TOKEN=ah_…
-   vercel --api https://api.host.hgdc.ch build
-   ```
-   La commande détecte le framework, installe les dépendances, lance le build, et écrit le résultat dans `.vercel/output`. Elle télécharge aussi les variables de l’environnement visé. Voir [vercel build](/docs/reference/cli/#vercel-build).
-   **Vérification** : le dossier `.vercel/output/static` contient les fichiers de ton site.
-2. **Envoie le résultat**
-   ```bash
-   vercel --api https://api.host.hgdc.ch deploy --prebuilt
-   ```
-   L’option `--prebuilt` envoie `.vercel/output` tel quel, sans reconstruire.
-   **Vérification** : l’adresse du déploiement répond avec ton site, et le déploiement passe à **Prêt**.
-3. **Passe en production**
-   Utilise la même cible des deux côtés. Pour la production :
-   ```bash
-   vercel --api https://api.host.hgdc.ch build --prod
-   vercel --api https://api.host.hgdc.ch deploy --prebuilt --prod
-   ```
-   > **Attention**
-   >
-   > La CLI refuse l’envoi si la cible du build et celle du déploiement ne correspondent pas. Une preview se construit sans `--prod`, et se déploie sans `--prod`.
-## Ce qui est servi, par framework
-| Framework                  | Servi tel quel                           | Préversion                                                                |
-| -------------------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
-| Astro                      | Les pages générées                       | Rendu à la demande, routes d’API, middleware, ISR                         |
-| Vite (React, Vue, Svelte…) | Le build de l’application                |                                                                           |
-| SvelteKit                  | Les pages pré-rendues                    | Rendu à la demande, routes d’API, actions de formulaire, ISR              |
-| Nuxt                       | Les pages générées                       | Rendu à la demande, routes d’API, middleware serveur, ISR                 |
-| TanStack Start             | Les pages pré-rendues                    |                                                                           |
-| React Router               | Les pages pré-rendues                    |                                                                           |
-| Next.js                    | Les pages pré-rendues et leur navigation | Rendu à la demande, routes d’API, Server Actions, proxy, ISR, routes edge |
-Le tableau complet, avec les fonctions de la plateforme, est dans [Compatibilité](/docs/reference/compatibilite/).
-## Next.js
-- `next/image` sert l’image d’origine, sans redimensionnement. Optimise tes images avant le build.
-- La page `not-found` sert de 404.
-- Une page rendue à la demande, une route d’API ou une Server Action tourne dans une fonction. Elle demande la préversion, voir [Préversion](/docs/concepts/preversion/).
-## Un site de documentation
-Un dossier avec un `docs.json` et le paquet `@hgdc/docs` dans son `package.json` est reconnu comme une documentation, sans `vercel.json`. Le build lance `hgdc-docs build` et publie le dossier `dist`. Les pages `.md` sont servies en `text/markdown`.
-## Si ça ne marche pas
-- Le déploiement répond `404` : la sortie de build ne contient pas de `index.html` à la racine, ou le dossier de sortie est faux. Voir [Dépannage](/docs/guides/depannage/#mon-site-affiche-404).
-- Une page répond `501` : le rendu à la demande n’est pas encore ouvert à ton organisation. Pré-rends la page, ou consulte [Préversion](/docs/concepts/preversion/).
----
-Source : /docs/guides/site-statique/
-# Déployer un site statique
-Un site statique est un dossier de fichiers déjà prêts : HTML, CSS, JavaScript et images. Aucun build n’est nécessaire. Une seule commande suffit.
-**Résultat attendu** : une adresse de production qui sert ton dossier, avec une page 404 personnalisée si tu en fournis une.
-**Avant de commencer** : une clé d’API dans `VERCEL_TOKEN`, et un dossier qui contient un `index.html` à sa racine.
-## Déployer le dossier
-```bash
-cd mon-site
-vercel --api https://api.host.hgdc.ch deploy --prod
-```
-Le premier déploiement crée le projet, sous le nom du dossier, et relie le dossier au projet. Les suivants republient ce qui a changé : un fichier déjà connu de l’organisation n’est jamais renvoyé.
-**Vérification** : l’adresse de production répond avec `index.html`.
-## Structure attendue
-```text
-mon-site/
-├── index.html
-├── a-propos.html
-├── 404.html
-├── styles.css
-└── images/
-    └── logo.svg
-```
-- Le dossier doit contenir un `index.html` à sa racine.
-- Un dossier qui ressemble à des sources, avec un `package.json` mais sans `index.html`, est refusé. Construis-le avec `vercel build` et envoie-le avec `--prebuilt`. Voir [Déployer un framework](/docs/guides/deployer-un-framework/).
-- Les fichiers et dossiers cachés, comme `.env` ou `.git`, ne sont jamais servis.
-- `404.html` sert de page d’erreur.
-## Servir un sous-dossier
-Si les fichiers à publier sont dans un sous-dossier, comme `public/` ou `dist/`, lance la commande depuis ce sous-dossier (`cd dist`, puis `deploy`). Avec un projet relié à GitHub, indique le dossier de sortie dans les réglages de build du projet.
-## URL propres et redirections
-Ajoute un `vercel.json` à la racine du dossier pour servir `/a-propos` sans `.html`, ou pour rediriger une ancienne adresse :
-```json
-{
-  "cleanUrls": true,
-  "redirects": [
-    { "source": "/ancienne-page", "destination": "/a-propos", "permanent": true }
-  ]
-}
-```
-Toutes les options sont dans [vercel.json](/docs/reference/vercel-json/).
-## Si ça ne marche pas
-- Le site répond `404` : le dossier envoyé n’a pas d’`index.html` à sa racine. Voir [Dépannage](/docs/guides/depannage/#mon-site-affiche-404).
-- `/a-propos` répond `404` alors que `a-propos.html` existe : active `cleanUrls` dans `vercel.json`.
----
-Source : /docs/guides/monorepo/
-# Déployer une app dans un monorepo
-Ton site peut vivre dans un sous-dossier, comme `apps/web` ou `site/`, dans un dépôt qui contient d’autres applications. Indique à Host le dossier racine du projet : c’est là que le build s’exécute.
-**Résultat attendu** : le build s’exécute depuis le dossier de ton app, et seule cette app est publiée.
-## Détection à l’import
-À l’import GitHub, Host lit tout le dépôt et cherche les dossiers qui contiennent un `package.json`, jusqu’à quatre niveaux de profondeur. Il préfère, dans l’ordre :
-1. un framework reconnu ;
-2. un dossier qui a un script `build` ;
-3. un nom usuel : `web`, `site`, `www`, `frontend`, `app`, `landing`, `marketing` ;
-4. le dossier le moins profond.
-La racine d’un monorepo, avec un champ `workspaces`, un `pnpm-workspace.yaml`, un `turbo.json` ou un `nx.json`, n’est jamais choisie seule. Si le dépôt contient plusieurs applications, choisis celle à déployer. Les dossiers `node_modules`, `dist`, `build` et les caches sont ignorés.
-Pour changer le dossier après l’import, modifie le **dossier racine** dans les réglages du projet.
-## Le fichier de verrouillage
-Dans un monorepo, le fichier de verrouillage, comme `pnpm-lock.yaml` ou `bun.lock`, est souvent à la racine. Il compte pour toutes les applications : la commande d’installation suit le gestionnaire qu’il désigne.
-## Plusieurs sites dans un dépôt
-Importe le dépôt une fois par site, en choisissant à chaque fois un dossier différent. Chaque projet a ses domaines, ses variables et son historique.
-## Avec la CLI
-Lance la CLI depuis le dossier de l’app :
-```bash
-cd apps/web
-vercel --api https://api.host.hgdc.ch deploy
-```
-Avec `vercel build` et `--prebuilt`, la même règle s’applique : construis depuis le dossier de l’app. Voir [Déployer un framework](/docs/guides/deployer-un-framework/).
-## Si ça ne marche pas
-- Le build ne trouve pas tes dépendances : ton dossier est sans doute le mauvais. Vérifie que le dossier racine contient le `package.json` de l’app, et que le fichier de verrouillage est bien à la racine du dépôt.
-- Host propose la racine du monorepo : choisis le dossier de l’application, pas la racine.
----
-Source : /docs/guides/brancher-un-domaine/
-# Brancher un domaine
-Ce guide sert ton site sur `www.exemple.ch` ou `exemple.ch`. Host vérifie que le domaine est à toi, attend que le trafic arrive, puis obtient le certificat HTTPS.
-**Résultat attendu** : le domaine affiche le statut **Vérifié** et le certificat HTTPS, et ton site répond sur ce domaine.
-**Avant de commencer** :
-- un projet déployé en production ;
-- l’accès à la zone DNS du domaine chez ton hébergeur. Le DNS d’Infomaniak, de Cloudflare ou d’un autre hébergeur fonctionne de la même façon.
-1. **Ajoute le domaine au projet**
-   Dans le projet, ouvre l’onglet **Domaines** et clique **Ajouter un domaine**. Saisis le nom, par exemple `www.exemple.ch` ou `exemple.ch`.
-   Choisis ce que le domaine sert, dans **Mise en ligne du domaine** :
-   - la production, pour le site principal ;
-   - une branche, par exemple `staging.exemple.ch` pour la branche `staging` ;
-   - une redirection vers un autre domaine du même projet.
-   Pour un domaine racine, la case **Ajouter aussi [www](http://www).** crée `www` en redirection permanente vers le domaine racine.
-   **Vérification** : le domaine apparaît dans la liste avec le statut **En attente des DNS**.
-2. **Prouve que le domaine est à toi**
-   Chez ton hébergeur DNS, crée un enregistrement **TXT** avec le nom et la valeur affichés sous **Prouver que le domaine est à toi (TXT)**.
-   Le nom commence toujours par `_agenthost.`, suivi du domaine. Certains hébergeurs ajoutent le domaine tout seul : saisis alors seulement la partie avant le domaine, par exemple `_agenthost.www`.
-3. **Dirige le trafic vers Host**
-   Sous **Diriger le trafic vers Host**, crée l’enregistrement indiqué :
-   | Domaine                                    | Type      | Nom   | Valeur                                  |
-   | ------------------------------------------ | --------- | ----- | --------------------------------------- |
-   | Sous-domaine, par exemple `www.exemple.ch` | **CNAME** | `www` | La cible affichée dans la console       |
-   | Domaine racine, `exemple.ch`               | **A**     | `@`   | L’adresse IPv4 affichée dans la console |
-   Un CNAME ne peut pas être posé sur la racine d’un domaine. Pour un domaine racine, utilise donc le A.
-   > **Attention**
-   >
-   > Supprime les anciens enregistrements A, AAAA ou CNAME qui pointent vers un autre hébergeur sur le même nom. Un enregistrement qui reste peut masquer le nouveau.
-4. **Attends la vérification**
-   Host revérifie le domaine toutes les 15 minutes tant qu’il n’est pas vérifié. Clique **Vérifier** pour lancer la vérification tout de suite.
-   Chaque étape s’affiche : la preuve TXT, le trafic, puis le certificat.
-   **Vérification** : le statut passe à **Vérifié**, puis le certificat HTTPS apparaît avec sa date d’échéance.
-Ouvre le domaine dans un navigateur : ton site répond en HTTPS.
-## Ce que tu n’as pas à faire
-- Téléverser un certificat. Host le demande dès que le domaine est vérifié, et le renouvelle seul.
-- Redéployer. Un domaine de production sert le dernier déploiement de production prêt.
-## Statuts d’un domaine
-| Statut                      | Signification                                                                       |
-| --------------------------- | ----------------------------------------------------------------------------------- |
-| **En attente des DNS**      | La preuve TXT ou le trafic manque encore. Le domaine n’est pas servi.               |
-| **Vérifié**                 | La preuve est là et le trafic arrive. Le domaine est servi.                         |
-| **Ne pointe pas vers nous** | La preuve TXT est là, mais le trafic n’arrive pas à Host. Corrige le CNAME ou le A. |
-Un domaine vérifié est revérifié chaque jour. Si la preuve TXT disparaît, une seconde vérification a lieu une heure plus tard. Si elle échoue aussi, le domaine repasse en attente et n’est plus servi. Garde donc le TXT en place.
-## Si ça ne marche pas
-- Le domaine reste **En attente des DNS** : vérifie le nom du TXT, qui doit commencer par `_agenthost.`. Un ancien enregistrement peut aussi retarder la propagation. Voir [Dépannage](/docs/guides/depannage/#mon-domaine-reste-en-attente).
-- Host refuse le nom avec « Ce domaine appartient à la plateforme » : les domaines de Host et ceux de la plateforme de déploiement ne peuvent pas être utilisés comme domaine client.
-- Le certificat n’est pas encore émis : attends que le statut soit **Vérifié**, puis patiente quelques minutes. Si l’erreur « Le certificat HTTPS n’a pas encore pu être émis » persiste, écris à <support@hgdc.ch>.
-## Voir aussi
-- [Domaines : référence](/docs/reference/domaines/) : les enregistrements, les codes de redirection et les limites.
-- [Migrer depuis Vercel](/docs/guides/migrer-depuis-vercel/) : changer le DNS sans coupure.
----
-Source : /docs/guides/variables-d-environnement/
-# Gérer les variables d'environnement
-Les variables d’environnement passent des réglages à ton build : l’adresse d’une API, un identifiant public, une clé de service. Ce guide les ajoute, les rend sensibles si besoin, et les applique à ton site.
-**Résultat attendu** : une variable visible dans l’onglet **Variables d’environnement** du projet, utilisée par le prochain build de l’environnement visé.
-**Avant de commencer** : être membre de l’organisation. Modifier une variable demande le rôle membre ou plus.
-## Ajouter une variable
-1. **Ouvre Ajouter**
-   Dans l’onglet **Variables d’environnement** du projet, clique **Ajouter**.
-2. **Remplis le nom et la valeur**
-   Le nom ne contient que des lettres, des chiffres et `_`, et ne commence pas par un chiffre. Il fait 256 caractères au plus. Les noms qui commencent par `VERCEL_` ou `AGENTHOST_` sont réservés à la plateforme.
-   La valeur fait 64 Ko au plus. Une note facultative rappelle à quoi sert la variable : 500 caractères au plus.
-3. **Choisis les environnements**
-   Chaque variable vise un ou plusieurs environnements :
-   | Environnement     | Utilisé par                                                              |
-   | ----------------- | ------------------------------------------------------------------------ |
-   | **Production**    | Les builds de production, avec `vercel build --prod`                     |
-   | **Preview**       | Les builds de preview, donc toutes les branches autres que la production |
-   | **Développement** | `vercel pull` depuis ton poste                                           |
-   Un même nom peut exister une fois par environnement, avec une valeur différente. Par exemple, `API_URL` pointe vers l’API de production en production, et vers l’API de test en preview.
-4. **Ou colle un fichier .env**
-   Colle le contenu d’un fichier `.env` dans le champ du nom : chaque ligne devient une variable.
-   ```text
-   PUBLIC_API_URL=https://api.exemple.ch
-   PUBLIC_ANALYTICS_ID=abc123
-   ```
-   **Vérification** : chaque variable apparaît dans la liste, avec ses environnements.
-## Marquer une variable comme sensible
-Une clé secrète ou un mot de passe se déclare **sensible**. Une variable sensible :
-- ne s’affiche plus jamais après l’enregistrement, ni dans la console ni dans la CLI. Tu peux seulement la remplacer ;
-- vise la production ou la preview, jamais le développement ;
-- n’est livrée qu’au build du dépôt GitHub, par la clé limitée au projet que pose l’app GitHub. Un `vercel pull` depuis ton poste ne la télécharge pas.
-Pour une valeur sensible utilisée par un build hors GitHub, voir [GitHub Actions sans l’application](/docs/guides/github-actions-sans-application/#variables-sensibles).
-> **Attention**
->
-> Tout ce que le build écrit dans les fichiers du site est public. Une variable lue dans le navigateur, comme celles qui commencent par `PUBLIC_`, `VITE_` ou `NEXT_PUBLIC_`, ne doit jamais contenir un secret, sensible ou non.
-## Appliquer un changement
-Une variable est lue au build. Les déploiements déjà en ligne gardent les valeurs de leur propre build, et une modification ne les touche pas.
-- Pour un projet relié à GitHub, clique **Redéployer la production** pour relancer le build avec les valeurs actuelles.
-- Pour un projet déployé avec la CLI, relance le déploiement de production depuis ton dossier ou ta CI :
-```bash
-vercel --api https://api.host.hgdc.ch pull --environment=production
-vercel --api https://api.host.hgdc.ch build --prod
-vercel --api https://api.host.hgdc.ch deploy --prebuilt --prod
-```
-L’onglet signale une variable modifiée depuis le dernier build de production.
-**Vérification** : le nouveau déploiement de production affiche la nouvelle valeur. Le déploiement précédent ne la montre pas.
-## Récupérer les variables sur ton poste
-```bash
-vercel --api https://api.host.hgdc.ch pull
-```
-Par défaut, la commande télécharge l’environnement **Développement** dans `.vercel/.env.development.local`. Ajoute `--environment=preview` ou `--environment=production` pour un autre environnement. Le dossier `.vercel` est ajouté au `.gitignore` : ne le commite pas.
-## Si ça ne marche pas
-- Une variable sensible n’apparaît pas dans `vercel pull` : c’est voulu. Utilise une valeur de développement, dans une variable non sensible visant l’environnement Développement.
-- Le site n’a pas changé après la modification : le déploiement n’a pas été relancé. Voir [Appliquer un changement](#appliquer-un-changement).
-- La variable ne peut pas être créée : son nom est réservé, ou sa valeur dépasse 64 Ko. Voir [Variables : référence](/docs/reference/variables/).
-## Voir aussi
-- [Secrets et coffre](/docs/concepts/secrets-et-coffre/) : comment les valeurs sont chiffrées et qui peut les lire.
-- [Synchroniser depuis Doppler](/docs/guides/synchroniser-doppler/) : garder les secrets dans Doppler.
----
-Source : /docs/guides/synchroniser-doppler/
-# Synchroniser les variables depuis Doppler
-Si tes secrets vivent déjà dans Doppler, relie une de tes configs à un environnement du projet. Doppler reste la source de vérité : chaque changement arrive dans Host sans copie à la main.
-**Résultat attendu** : les variables de la config apparaissent dans l’environnement choisi, avec le badge **Doppler**, et ne se modifient plus que dans Doppler.
-**Avant de commencer** : un projet Host, et un compte Doppler avec accès à la config à synchroniser.
-## Relier une config
-1. **Crée un jeton de service dans Doppler**
-   Dans Doppler, ouvre la config, par exemple `prd`, onglet **Access**, et génère un jeton de service en lecture seule. Il commence par `dp.st.`.
-2. **Relie la config au projet**
-   Dans l’onglet **Variables d’environnement** du projet, section **Synchroniser depuis Doppler**, clique **Relier une config Doppler**. Choisis l’environnement, nomme la config, puis colle le jeton.
-   Host essaie le jeton, le chiffre et ne l’affiche plus jamais. La première synchronisation part tout de suite.
-   **Vérification** : les variables de la config apparaissent avec le badge **Doppler**.
-3. **Ajoute le webhook dans Doppler**
-   Host affiche une adresse et un secret de signature, une seule fois. Dans Doppler, ouvre **Webhooks**, ajoute un webhook avec cette adresse, coche la config et colle le secret.
-   Chaque changement est alors signé, puis appliqué en quelques secondes.
-   **Vérification** : modifie une valeur de test dans Doppler. Elle apparaît dans Host en quelques secondes.
-## Ce qui est synchronisé
-- Toutes les variables de la config, sauf les métadonnées de Doppler, comme `DOPPLER_PROJECT` ou `DOPPLER_CONFIG`.
-- Les noms réservés, qui commencent par `VERCEL_` ou `AGENTHOST_`, ne sont pas synchronisés. Les valeurs de plus de 64 Ko non plus. La console les signale.
-- 300 variables au plus par config.
-- En production et en preview, les variables sont **sensibles** : elles ne descendent pas sur un poste par `vercel pull`. En développement, elles sont ordinaires. Voir [Variables](/docs/guides/variables-d-environnement/#marquer-une-variable-comme-sensible).
-## Ce qui se passe quand une valeur change
-- Une variable retirée de Doppler disparaît du projet au passage suivant.
-- Une config devenue vide d’un coup ne retire rien : la console signale l’erreur. C’est une protection contre un accident de configuration.
-- Une variable manuelle du même nom, sur le même environnement, l’emporte et n’est jamais écrasée. La console liste ces noms : supprime la variable manuelle pour que Doppler prenne le relais.
-- Sans webhook, ou si un appel se perd, la synchronisation repasse toute seule toutes les six heures. Clique **Synchroniser** pour la lancer tout de suite.
-## Redéployer à chaque changement
-Pour un projet relié à GitHub et la config de production, active **Redéployer la production à chaque changement**. Quand une valeur change dans Doppler, le workflow du dépôt reconstruit la production avec les nouvelles valeurs.
-Une synchronisation sans changement ne redéploie rien.
-## Débrancher
-**Débrancher** garde les variables dans le projet, redevenues manuelles. Aucun build ne les perd d’un coup. Retire ensuite le webhook et révoque le jeton dans Doppler.
-> **Astuce**
->
-> Le jeton de service et le secret du webhook sont chiffrés, liés au projet, et ne sont jamais renvoyés. Si tu perds le secret, clique **Générer un nouveau secret** sous l’adresse du webhook, puis remplace-le dans Doppler.
-## Si ça ne marche pas
-- La synchronisation affiche une erreur à la connexion : le jeton n’est pas un jeton de service de la config, ou il est révoqué. Crée-en un nouveau.
-- Une variable n’arrive pas : elle porte un nom réservé, ou sa valeur dépasse 64 Ko. Vérifie la liste signalée dans la console.
-- Le webhook ne déclenche rien : vérifie que l’adresse et le secret collés dans Doppler sont ceux affichés à la création du webhook. Sinon, génère un nouveau secret.
----
-Source : /docs/guides/revenir-en-arriere/
-# Revenir en arrière, redéployer ou annuler
-Une mise en production s’est mal passée ? Ce guide remet en ligne une version précédente, relance un build, ou annule un déploiement en cours. Aucune de ces actions ne demande de nouveau commit.
-**Résultat attendu** : ton domaine de production sert la version choisie, ou le déploiement en cours s’arrête.
-**Avant de commencer** : une version précédente **Prête**. Un déploiement en erreur ne peut pas redevenir la production.
-## Revenir à une version précédente
-1. **Ouvre la liste des déploiements**
-   Dans le projet, ouvre l’onglet **Déploiements**. Chaque ligne montre l’état, la cible et le commit, quand il est connu.
-2. **Choisis la version à remettre en ligne**
-   Ouvre un déploiement de production précédent, qui est **Prêt**, puis clique **Revenir en arrière**.
-   Le retour est immédiat : aucun build ne tourne.
-3. **Vérifie le site**
-   **Vérification** : tes domaines de production répondent avec la version choisie. L’onglet **Vue d’ensemble** l’affiche comme production.
-Le déploiement remis en ligne garde les variables qu’il a reçues à son build. Une variable modifiée depuis ne s’y applique pas. Pour appliquer une variable à la version remise en ligne, reconstruis-la : la section **Redéployer** plus bas explique comment.
-## Mettre une preview en production
-Depuis la page d’une preview prête, clique **Mettre en production**. Cette preview sert alors tes domaines de production, avec les variables de preview qu’elle a reçues. La console te le rappelle avant de confirmer.
-Utilise cette action pour valider une version sur son adresse de preview, puis la passer en production sans la reconstruire.
-## Redéployer
-Redéployer reconstruit une version avec les variables d’aujourd’hui :
-- **Projet relié à GitHub** : reconstruit le même commit dans GitHub Actions, avec les variables actuelles. Le bouton **Redéployer la production** le fait pour la production.
-- **Projet envoyé par la CLI** : republie les fichiers du déploiement choisi, sans rien reconstruire. Pour une nouvelle version, relance `vercel deploy`.
-## Annuler un déploiement
-Un déploiement **En file** ou **En cours de build** peut être annulé, avec **Annuler**. Un déploiement **Prêt** ne s’annule pas : reviens en arrière à la place.
-**Vérification** : le déploiement passe à **Annulé**, et la production n’a pas changé.
-## Si ça ne marche pas
-- **Revenir en arrière** est absent : le déploiement n’est pas **Prêt**, ou il n’est pas de production.
-- Le site répond encore avec l’ancienne version : le cache de ton navigateur ou de ton réseau peut retenir la page. Recharge la page sans cache, puis patiente quelques minutes.
-- Pour comprendre le cycle de vie d’un déploiement, lis [Déploiements](/docs/concepts/deploiements/).
----
-Source : /docs/guides/inviter-une-personne/
-# Inviter une personne dans une organisation
-Les membres d’une organisation se gèrent dans Account, pas dans Host. Ce guide invite une personne, puis vérifie qu’elle accède aux projets.
-**Résultat attendu** : la personne se connecte à Host, voit l’organisation et ses projets, avec le rôle que tu lui as donné.
-**Avant de commencer** : être propriétaire ou admin de l’organisation dans Account. Les rôles sont décrits dans [Organisations et rôles](/docs/concepts/organisations-et-roles/).
-1. **Invite depuis Account**
-   Ouvre la page de ton organisation dans [Account](https://account.hgdc.ch). Invite la personne par son adresse e-mail, et choisis son rôle : **membre**, **admin** ou **propriétaire**.
-   **Vérification** : l’invitation apparaît dans la liste des invitations en attente d’Account.
-2. **La personne se connecte**
-   La personne se connecte à Host avec **Se connecter avec HGDC**, avec la même adresse e-mail vérifiée. Son compte est lié à l’organisation, et ses projets restent en place.
-   Une personne qui n’a pas encore de compte demande d’abord un accès sur la page **Demander un accès** de Host. L’invitation suit.
-3. **Vérifie l'accès**
-   Demande à la personne d’ouvrir son tableau de bord.
-   **Vérification** : elle voit ton organisation dans le sélecteur de la barre latérale, et les projets qu’elle peut voir. Un membre n’a pas accès à l’onglet **Clés d’API**.
-## Changer un rôle ou retirer une personne
-Modifie le rôle ou retire la personne dans Account. Host ne garde pas sa propre liste de membres : la liste affichée dans Host est une copie en lecture seule, mise à jour à la prochaine connexion de la personne.
-Une session dure 7 jours au plus, sans prolongation. Un changement de rôle ou un retrait peut donc prendre effet jusqu’à la prochaine connexion, au plus tard à la fin de la session.
-Les clés d’API créées par une personne cessent de fonctionner quand elle quitte l’organisation. Révoque-les si tu veux agir tout de suite. Voir [Créer et révoquer une clé d’API](/docs/guides/cle-d-api/).
-## Si ça ne marche pas
-- L’organisation n’apparaît pas pour la personne : vérifie que l’adresse e-mail de l’invitation est la même que celle de son compte HGDC, et qu’elle est vérifiée.
-- La personne ne peut pas faire une action : son rôle ne le permet pas (voir le tableau des rôles). Vérifie son rôle dans Account.
----
-Source : /docs/guides/lire-les-logs/
-# Lire les logs
-Les logs répondent à deux questions : qu’est-ce que les visiteurs ont reçu, et qu’est-ce qui s’est passé pendant le build. Ce guide montre où les trouver et comment les filtrer.
-**Résultat attendu** : tu identifies la requête ou la ligne de build à l’origine d’un problème.
-## Les requêtes servies
-1. **Ouvre l'onglet Logs du projet**
-   Les requêtes apparaissent en direct. Pour chacune, tu vois l’heure, le statut HTTP, la méthode, le domaine, le chemin, la durée de traitement et la taille de la réponse.
-2. **Isole les erreurs**
-   Clique **Erreur** pour ne garder que les réponses `5xx`. Clique **Alerte** pour les réponses `4xx`. La recherche lit le chemin et le domaine.
-3. **Garde la vue à jour**
-   **Suivre** garde les dernières requêtes en vue. Sous la liste, un compteur donne le nombre de réponses par classe : 2xx, 3xx, 4xx et 5xx.
-4. **Copie ce qui t'intéresse**
-   **Tout copier** copie toutes les requêtes reçues, une par ligne. L’icône de copie ne copie que les lignes affichées.
-Les requêtes ne gardent ni adresse IP, ni en-têtes, ni paramètres d’URL (la partie après `?`). Elles disparaissent après trois jours. Voir [Confidentialité](/docs/concepts/confidentialite/).
-## La sortie d’un build
-La page de chaque déploiement affiche la sortie du build : installation, `vercel build`, puis publication.
-- Avec l’intégration GitHub, les lignes arrivent en direct pendant le build.
-- Cherche dans les lignes, ou filtre les erreurs et les alertes.
-- Ouvre le run GitHub Actions pour la sortie complète, si ton build passe par GitHub.
-- **Tout copier** copie la sortie entière. L’icône de copie ne copie que les lignes affichées.
-## Suivre un déploiement depuis le terminal
-`vercel deploy` suit la publication jusqu’à la fin, pendant 9 minutes au plus, puis rend la main :
-```bash
-vercel --api https://api.host.hgdc.ch deploy --prod
-```
-## Si ça ne marche pas
-- Un build n’a pas de sortie : il est peut-être en file, ou il a été annulé avant de démarrer. Vérifie l’état du déploiement.
-- Un problème de page n’apparaît pas dans les logs de requêtes : les requêtes sont gardées trois jours seulement. Reproduis le problème, puis regarde tout de suite.
-- Pour une erreur de build, commence par la première ligne d’erreur du filtre **Erreur**, puis remonte la sortie jusqu’à elle. Voir [Dépannage](/docs/guides/depannage/).
----
-Source : /docs/guides/migrer-depuis-vercel/
-# Migrer un projet depuis Vercel
-Host reprend les outils que tu utilises déjà : la CLI Vercel, `vercel.json` et le format Build Output API. Migrer revient à recréer le projet, reprendre ses variables, puis changer le DNS.
-**Résultat attendu** : ton domaine sert le site depuis Host, et le projet Vercel n’envoie plus de déploiement.
-**Avant de commencer** : vérifie que ton site n’utilise que des fonctions prises en charge. Les fonctions, le runtime edge, l’ISR et les crons sont en préversion, voir [Compatibilité](/docs/reference/compatibilite/).
-1. **Crée le projet sur Host**
-   Importe le dépôt depuis GitHub, voir [Déployer depuis GitHub](/docs/guides/deployer-depuis-github/). Ou lance `vercel deploy` depuis le dossier du projet avec une clé Host.
-   Supprime d’abord le dossier `.vercel` s’il existe : il pointe vers le projet Vercel.
-   ```bash
-   rm -rf .vercel
-   vercel --api https://api.host.hgdc.ch deploy
-   ```
-   **Vérification** : un déploiement de preview est **Prêt**.
-2. **Reprends les variables**
-   Sur Vercel, `vercel env pull .env.production --environment=production` écrit les variables lisibles dans un fichier.
-   Colle le contenu de ce fichier dans **Ajouter**, dans l’onglet **Variables d’environnement** de Host, en choisissant l’environnement Production. Les variables marquées « Sensitive » sur Vercel ne se relisent pas : saisis-les à nouveau.
-   **Vérification** : le nombre de variables correspond à celui de Vercel.
-3. **Vérifie la preview**
-   Ouvre l’adresse du déploiement et parcours le site : pages, redirections, page 404 et ressources.
-   **Vérification** : aucune page ne répond `404` ou `501` de façon inattendue.
-4. **Ajoute le domaine et change le DNS**
-   Ajoute le domaine au projet, pose le TXT de propriété, puis remplace les enregistrements qui pointaient vers Vercel par le CNAME ou le A indiqué. Le détail est dans [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-5. **Retire le projet de Vercel**
-   Une fois le trafic arrivé et le certificat émis, débranche le dépôt côté Vercel. Tu évites ainsi deux déploiements à chaque push.
-> **Astuce**
->
-> Pose d’abord le TXT : il ne change rien au trafic. Ne change le CNAME ou le A que quand le domaine est prêt côté Host. Baisse le TTL de l’enregistrement quelques heures avant la bascule, pour revenir vite en arrière si besoin.
-## Si ça ne marche pas
-- La preview affiche une page `501` : une fonction n’est pas encore ouverte à ton organisation. Voir [Préversion](/docs/concepts/preversion/).
-- Le site répond encore depuis Vercel : le DNS n’est pas propagé, ou un ancien enregistrement subsiste. Voir [Dépannage](/docs/guides/depannage/#mon-domaine-reste-en-attente).
----
-Source : /docs/guides/depannage/
-# Dépannage
-Ce guide liste les problèmes fréquents, classés par symptôme. Chaque section donne les causes probables, dans l’ordre où les vérifier.
-Si rien ne correspond, écris à <support@hgdc.ch> avec l’adresse du déploiement concerné.
-## La CLI renvoie 403
-La clé est absente, mal copiée, révoquée, ou elle appartient à une organisation qui n’existe plus.
-- Vérifie qu’elle commence par `ah_` et qu’elle est passée par `VERCEL_TOKEN` ou `--token`.
-- Vérifie qu’elle n’a pas été révoquée dans **Clés actives**. Une clé cesse aussi de fonctionner quand la personne qui l’a créée quitte l’organisation.
-- Vérifie que `--api https://api.host.hgdc.ch` est présent. Sans lui, la CLI parle à Vercel, pas à Host.
-Le message « Cette clé est limitée à un autre projet » signifie que tu utilises la clé posée dans un dépôt pour un autre projet. Crée une clé d’organisation, voir [Créer et révoquer une clé d’API](/docs/guides/cle-d-api/).
-## La CLI affiche missing_files
-C’est normal : Host demande les fichiers qu’il n’a pas encore, la CLI les envoie puis rappelle l’API. Si l’erreur persiste, un fichier n’a pas pu partir : il dépasse 20 Mo, ou le réseau a coupé. Relance le déploiement.
-## vercel login ne fonctionne pas
-C’est voulu : la connexion passe toujours par une clé d’API. Exporte la clé dans `VERCEL_TOKEN`, puis lance la commande avec `--api`, voir [Configurer la CLI](/docs/reference/cli/#configurer-la-cli).
-## Le build GitHub est absent
-Un push ne déclenche aucun build dans Host.
-- La pull request d’installation est-elle fusionnée sur la branche poussée ? Le fichier `.github/workflows/hgdc-host.yml` doit exister sur cette branche.
-- Ouvre l’onglet **Actions** du dépôt : le run y apparaît, avec son erreur.
-- Le secret `HGDC_HOST_TOKEN` manque ou a été supprimé. Débranche le dépôt, puis relie-le pour poser un nouveau secret.
-- Le projet a été importé avant une évolution du workflow. Utilise **Mettre à jour le workflow** dans l’onglet **Git**.
-## Mon site affiche 404
-- Le dossier envoyé n’a pas d’`index.html` à sa racine, ou le dossier de sortie configuré est faux. Voir [Déployer un site statique](/docs/guides/site-statique/).
-- La page est rendue à la demande, et l’exécution des fonctions n’est pas encore ouverte à ton organisation : la page répond alors `501`. Pré-rends-la, ou consulte [Préversion](/docs/concepts/preversion/).
-- Sans `cleanUrls`, `/a-propos` ne trouve pas `a-propos.html`. Ajoute `"cleanUrls": true` à `vercel.json`.
-- La page de déploiement liste les fichiers et les fonctions ignorés à la publication, avec un avertissement. Vérifie-la.
-## Mon domaine reste en attente
-- Vérifie le nom du TXT : `_agenthost.` suivi de ton domaine, pas `_agenthost` seul. Certains hébergeurs ajoutent le domaine tout seul : saisis alors seulement `_agenthost.www` pour `www.exemple.ch`.
-- Pour un domaine racine, il faut un enregistrement A, pas un CNAME.
-- Un ancien enregistrement A ou AAAA vers un autre hébergeur peut masquer le nouveau : supprime-le.
-- La propagation peut prendre quelques heures. Clique **Vérifier**, ou attends la vérification automatique, toutes les 15 minutes.
-Tu peux contrôler les enregistrements depuis un terminal :
-```bash
-dig +short TXT _agenthost.www.exemple.ch
-dig +short CNAME www.exemple.ch
-```
-Voir [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-## Ma variable sensible n’apparaît pas dans vercel pull
-C’est voulu : une variable sensible ne part que vers le build du dépôt, par la clé limitée au projet. Depuis ton poste, utilise une valeur de développement, dans une variable non sensible visant l’environnement Développement. Voir [Variables d’environnement](/docs/guides/variables-d-environnement/).
-## Une fonction répond 501
-Le rendu à la demande, les routes d’API et les Server Actions sont en préversion. L’exécution est ouverte organisation par organisation. Les pages statiques et pré-rendues de ton site restent en ligne. Voir [Préversion](/docs/concepts/preversion/).
-## Le build échoue
-- Ouvre le déploiement : la sortie du build est affichée, avec la première erreur. Voir [Lire les logs](/docs/guides/lire-les-logs/).
-- Reproduis le build sur ton poste avec `vercel build`, puis vérifie que la version de Node.js du projet correspond à celle de ton poste.
-- Une variable manque au build : ajoute-la à l’environnement visé, voir [Variables d’environnement](/docs/guides/variables-d-environnement/).
----
-Source : /docs/reference/cli/
-# CLI
-Host accepte la CLI Vercel officielle, version 63. Cette page décrit les commandes prises en charge, leurs options et ce qui n’est pas encore pris en charge.
-## Configurer la CLI
-Host n’utilise pas la connexion par navigateur de la CLI. Chaque commande reçoit l’adresse de l’API par `--api` et la clé par la variable `VERCEL_TOKEN`.
-```bash
-npm install --global vercel@63
-export VERCEL_TOKEN=ah_…
-vercel --api https://api.host.hgdc.ch deploy
-```
-Pour ne pas retaper l’adresse, crée un alias dans ton profil de shell :
-```bash
-# ~/.bashrc ou ~/.zshrc
-alias vh="vercel --api https://api.host.hgdc.ch"
-# Ensuite
-vh deploy --prod
-```
-En PowerShell, dans `$PROFILE` :
-```powershell
-function vh { vercel --api https://api.host.hgdc.ch @args }
-```
-> **Attention**
->
-> Sans `--api`, la CLI parle à Vercel. Si une commande te demande de te connecter dans le navigateur, vérifie que l’option est bien présente.
-### Options globales
-| Option    | Valeur | Rôle                                                                                         |
-| --------- | ------ | -------------------------------------------------------------------------------------------- |
-| `--api`   | URL    | Adresse de l’API : `https://api.host.hgdc.ch`                                                |
-| `--token` | `ah_…` | Clé d’API. Préfère la variable `VERCEL_TOKEN`, qui n’apparaît pas dans l’historique du shell |
-### Ce qui n’est pas pris en charge
-| Commande ou option  | État                                                                                         |
-| ------------------- | -------------------------------------------------------------------------------------------- |
-| `vercel login`      | Non : la connexion passe par la clé                                                          |
-| `vercel env`        | Pas encore : gère les variables dans la console                                              |
-| `vercel domains`    | Pas encore : gère les domaines dans la console                                               |
-| `vercel logs`       | Pas encore : les logs sont dans la console                                                   |
-| `vercel alias`      | Pas encore : utilise la console, voir [Revenir en arrière](/docs/guides/revenir-en-arriere/) |
-| `--scope`, `--team` | Ignorés : l’organisation vient de la clé                                                     |
-## vercel deploy
-Envoie un dossier, ou un build déjà construit, et crée un déploiement. Sans option, la commande crée une preview. Avec `--prod`, elle part en production.
-```bash
-# Preview du dossier courant
-vercel --api https://api.host.hgdc.ch deploy
-# Production
-vercel --api https://api.host.hgdc.ch deploy --prod
-```
-Dans un script, l’adresse du déploiement est écrite seule sur la sortie standard :
-```bash
-URL=$(vercel --api https://api.host.hgdc.ch deploy --yes)
-echo "Preview : $URL"
-```
-| Option                | Rôle                                                                                        |
-| --------------------- | ------------------------------------------------------------------------------------------- |
-| `--prod`              | Déploie en production                                                                       |
-| `--prebuilt`          | Envoie `.vercel/output`, produit par `vercel build`, sans reconstruire                      |
-| `--yes`               | Répond oui à toutes les questions : relie le dossier et crée le projet. Indispensable en CI |
-| `--cwd <chemin>`      | Dossier à déployer, s’il n’est pas le dossier courant                                       |
-| `--meta <clé=valeur>` | Métadonnée attachée au déploiement                                                          |
-La commande affiche l’adresse du déploiement, suit la publication, puis rend la main quand le déploiement est prêt ou en erreur. Le suivi dure 9 minutes au plus.
-Pour un framework, construis d’abord avec `vercel build`, puis envoie le résultat avec `--prebuilt`. Utilise la même cible des deux côtés : `build --prod` avec `deploy --prebuilt --prod`, ou aucune des deux pour une preview. Sinon, la CLI refuse l’envoi.
-## vercel build
-Construit le projet en local ou en CI, au format Build Output API. Le résultat va dans `.vercel/output`, prêt pour `vercel deploy --prebuilt`.
-```bash
-# Build de preview
-vercel --api https://api.host.hgdc.ch build
-# Build de production
-vercel --api https://api.host.hgdc.ch build --prod
-```
-Avant de construire, la commande télécharge les variables de l’environnement visé : preview par défaut, production avec `--prod`. Une variable sensible n’est pas téléchargée depuis un poste, seulement depuis le build du dépôt GitHub.
+> **Tout reste en Suisse quand c'est possible**
+>
+> Le site est servi par Host. Les questions des visiteurs sont gardées 90 jours au plus. Voir [Données et confidentialité](/explications/donnees/).
-| Option           | Rôle                                                                      |
-| ---------------- | ------------------------------------------------------------------------- |
-| `--prod`         | Construit pour la production, avec les variables de production            |
-| `--yes`          | Télécharge les réglages du projet sans rien demander. Indispensable en CI |
-| `--cwd <chemin>` | Dossier du projet, s’il n’est pas le dossier courant                      |
+---
-## vercel pull
+Source : /demarrer/premiere-doc/
-Télécharge les réglages du projet et les variables d’un environnement. `vercel build` s’en sert ensuite.
+# Ta première doc en cinq minutes
-```bash
-# Variables de développement, par défaut
-vercel --api https://api.host.hgdc.ch pull
+Il te faut Node.js 22 ou plus récent, ou Bun. Tout le reste s’installe avec le paquet `@hgdc/docs`.
-# Variables de preview ou de production
-vercel --api https://api.host.hgdc.ch pull --environment=preview
-vercel --api https://api.host.hgdc.ch pull --environment=production
-```
+1. **Créer le dossier**
-Les variables sont écrites dans `.vercel/.env.<environnement>.local`. La CLI ajoute ce dossier au `.gitignore` : ne le commite pas.
+   Un dépôt Git à part, ou un dossier `docs/` dans le dépôt de ton produit.
-| Option           | Valeur                                   | Rôle                                                 |
-| ---------------- | ---------------------------------------- | ---------------------------------------------------- |
-| `--environment`  | `development`, `preview` ou `production` | Environnement à lire. Par défaut : `development`     |
-| `--yes`          |                                          | Relie le dossier sans rien demander                  |
-| `--cwd <chemin>` |                                          | Dossier du projet, s’il n’est pas le dossier courant |
+   ```bash
+   mkdir docs && cd docs
+   npm init -y
+   npm install --save-dev @hgdc/docs
+   ```
-Ce que reçoit la commande dépend de la clé :
+2. **Écrire docs.json**
-| Clé                                   | Variables normales | Variables sensibles |
-| ------------------------------------- | ------------------ | ------------------- |
-| Clé d’organisation                    | Oui                | Non                 |
-| Clé de projet, posée par l’app GitHub | Oui                | Oui                 |
+   À la racine du dossier. Seuls `name` et `navigation` sont obligatoires.
-## vercel link
+   ```json
+   {
+     "name": "Documentation Acme",
+     "colors": { "primary": "#0f766e" },
+     "navigation": {
+       "groups": [{ "group": "Démarrer", "pages": ["index", "installation"] }]
+     }
+   }
+   ```
-Relie un dossier local à un projet. Les autres commandes savent ensuite à quel projet s’adresser.
+3. **Écrire les pages**
-```bash
-vercel --api https://api.host.hgdc.ch link
+   Une page par entrée de la navigation : `index.mdx` et `installation.mdx`. Chaque page commence par un titre.
-# Sans question, avec le nom du dossier
-vercel --api https://api.host.hgdc.ch link --yes
-```
+   ```mdx
+   ---
+   title: Installation
+   description: Installer Acme en deux minutes.
+   ---
-La liaison est écrite dans `.vercel/project.json`, qui contient `orgId` et `projectId`. Le premier `link` ou `deploy` sur un nom inconnu crée le projet, sous le nom du dossier.
+   Lance la commande suivante :
+   ```
-| Option            | Rôle                                                                     |
-| ----------------- | ------------------------------------------------------------------------ |
-| `--yes`           | Relie le dossier sans rien demander, et crée le projet s’il n’existe pas |
-| `--project <nom>` | Nom du projet à relier, s’il n’est pas celui du dossier                  |
-| `--cwd <chemin>`  | Dossier à relier, s’il n’est pas le dossier courant                      |
+4. **Voir le site**
-En CI, sans dossier `.vercel`, donne les deux identifiants par variables d’environnement, avec la clé :
+   Ajoute les scripts dans `package.json`, puis lance `npm run dev`.
-```bash
-export VERCEL_ORG_ID=…
-export VERCEL_PROJECT_ID=…
-export VERCEL_TOKEN=ah_…
-vercel --api https://api.host.hgdc.ch deploy --prod --yes
-```
+   ```json
+   {
+     "scripts": {
+       "dev": "hgdc-docs dev",
+       "build": "hgdc-docs build"
+     }
+   }
+   ```
-`VERCEL_ORG_ID` est la valeur renvoyée par [GET /v2/user](/docs/reference/api/utilisateur/). Le workflow posé par l’app GitHub contient déjà les bonnes valeurs.
+   Le site s’ouvre sur `http://localhost:4321` et se recharge à chaque modification.
-Pour délier un dossier, supprime son dossier `.vercel`. Le prochain déploiement te redemandera le projet.
+> **Note**
+>
+> `hgdc-docs build` écrit le site dans `dist/`. Ajoute `dist/` et `.hgdc-docs/` à ton `.gitignore`.
-## Voir aussi
+## Et ensuite
-- [Référence de l’API](/docs/reference/api/introduction/) : les mêmes opérations, sans la CLI.
-- [Compatibilité](/docs/reference/compatibilite/) : la liste des fonctions de la CLI et de la plateforme.
+- [Publier avec 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 : /docs/reference/variables/
-# Variables d'environnement
-Cette page donne les règles qui s’appliquent aux variables d’environnement. Pour les gérer pas à pas, voir [Gérer les variables](/docs/guides/variables-d-environnement/).
+Source : /guides/publier/
-## Nom
+# Publier avec Host
-| Règle                | Valeur                                            |
-| -------------------- | ------------------------------------------------- |
-| Caractères autorisés | Lettres, chiffres et `_`                          |
-| Premier caractère    | Une lettre ou `_`, pas un chiffre                 |
-| Longueur             | 256 caractères au plus                            |
-| Noms réservés        | Ceux qui commencent par `VERCEL_` ou `AGENTHOST_` |
+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.
-Un même nom peut exister une fois par environnement.
+## Mettre la doc en ligne
-## Valeur et note
+1. **Importer le dépôt**
-| Champ  | Limite                 |
-| ------ | ---------------------- |
-| Valeur | 64 Ko au plus          |
-| Note   | 500 caractères au plus |
+   Dans Host, crée un projet à partir de ton dépôt GitHub. Host reconnaît une doc 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.
-## Environnements
+2. **Fusionner la pull request de Host**
-| Environnement | Utilisé par                                                | Télécharge avec `vercel pull` |
-| ------------- | ---------------------------------------------------------- | ----------------------------- |
-| Production    | `vercel build --prod`, les déploiements de production      | `--environment=production`    |
-| Preview       | Les builds de toutes les branches autres que la production | `--environment=preview`       |
-| Développement | Ton poste de développement                                 | Par défaut, sans option       |
+   Host propose une pull request qui ajoute son workflow de déploiement. Fusionne-la : la doc part en production.
-## Variables fournies par la plateforme
+3. **Pousser**
-Host ajoute ces variables au build, sans que tu les crées :
+   Chaque push sur la branche principale publie le site en production. Les autres branches ont leur préversion.
-| Variable                        | Valeur                                                                                                                                             |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `VERCEL_PROJECT_PRODUCTION_URL` | Le domaine de production du projet, sans `https://`, à défaut son adresse de production `<projet>.hgdc.cloud`. Toujours présente, en preview aussi |
+## Activer Docs
-Les noms `VERCEL_` sont réservés : tu ne peux pas en créer, et une variable du projet du même nom n’écrase pas celle de la plateforme.
+1. **Cliquer sur « Activer Docs »**
-## Variables sensibles
+   Sur la vue d’ensemble du projet dans Host, la carte **Assistant et recherche avec 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.
-| Propriété      | Comportement                                                                                                                    |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| Affichage      | Jamais affichée après l’enregistrement, ni dans la console ni dans la CLI. Elle peut seulement être remplacée                   |
-| Environnements | Production ou preview uniquement. Jamais le développement                                                                       |
-| Téléchargement | Livrée uniquement au build du dépôt GitHub, par une clé limitée au projet. Absente de `vercel pull` avec une clé d’organisation |
+2. **Publier une fois de plus**
-## Synchronisation avec Doppler
+   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`.
-| Règle                       | Valeur                                                      |
-| --------------------------- | ----------------------------------------------------------- |
-| Variables par configuration | 300 au plus                                                 |
-| Métadonnées Doppler         | Exclues : `DOPPLER_PROJECT`, `DOPPLER_CONFIG` et similaires |
-| Noms réservés               | Ignorés                                                     |
-| Valeurs de plus de 64 Ko    | Ignorées et signalées                                       |
-| Synchronisation de secours  | Toutes les six heures, sans webhook                         |
+3. **Laisser faire**
-Voir [Synchroniser depuis Doppler](/docs/guides/synchroniser-doppler/).
+   À 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 **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.
-## Ce que le site publie
-Tout ce que le build écrit dans les fichiers du site est public. Une variable lue dans le navigateur, comme celles qui commencent par `PUBLIC_`, `VITE_` ou `NEXT_PUBLIC_`, ne doit jamais contenir un secret.
----
-Source : /docs/reference/domaines/
-# Domaines
-Cette page donne les valeurs exactes des enregistrements, les statuts et les règles de propriété. Pour brancher un domaine pas à pas, voir [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-## Enregistrements DNS
-Deux enregistrements, chez ton hébergeur DNS : un TXT de preuve, et un trafic qui arrive sur Host.
-| Enregistrement | Nom                    | Valeur                                  | Quand                                         |
-| -------------- | ---------------------- | --------------------------------------- | --------------------------------------------- |
-| **TXT**        | `_agenthost.<domaine>` | Le jeton affiché dans la console        | Toujours : prouve que le domaine t’appartient |
-| **CNAME**      | `<sous-domaine>`       | La cible affichée dans la console       | Pour un sous-domaine, comme `www`             |
-| **A**          | `<domaine racine>`     | L’adresse IPv4 affichée dans la console | Pour un domaine racine, comme `exemple.ch`    |
-Le CNAME ne peut pas être posé sur la racine d’un domaine : le DNS l’interdit. Pour un domaine racine, utilise le A.
-Les valeurs peuvent changer. La console affiche toujours les valeurs à utiliser : suis-les plutôt qu’une valeur copiée d’une ancienne page.
-## Statuts
+> **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.
-| Statut                      | Signification                                     | Servi ? |
-| --------------------------- | ------------------------------------------------- | ------- |
-| **En attente des DNS**      | Le TXT ou le trafic manque                        | Non     |
-| **Vérifié**                 | Le TXT est là et le trafic arrive                 | Oui     |
-| **Ne pointe pas vers nous** | Le TXT est là, mais le trafic n’arrive pas à Host | Non     |
+## Ton domaine
-Un domaine vérifié est revérifié chaque jour. Si le TXT disparaît, une seconde vérification a lieu une heure plus tard. Si elle échoue aussi, le domaine repasse en attente et n’est plus servi.
+Le domaine se branche dans 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.
-La vérification se relance toutes les 15 minutes tant que le domaine n’est pas vérifié. **Vérifier** la relance tout de suite.
+## Relier un projet existant
-## Certificat HTTPS
+Le dossier `dist/` est un site statique, il se dépose chez n’importe quel hébergeur. Hors de Host, ou pour un projet créé directement dans la console, relie la doc à la main.
-Dès qu’un domaine est **Vérifié**, Host demande un certificat HTTPS. Le certificat affiche sa date d’échéance dans la console, et se renouvelle seul. Un certificat n’est émis que pour un domaine vérifié.
+1. **Créer le projet dans la console**
-## Usages
+   Sur `docs.hgdc.ch`, ouvre ton organisation, puis **Nouveau projet**. Donne l’adresse de production du site, par exemple `https://docs.acme.ch`.
-| Usage       | Ce qui est servi                                                                  |
-| ----------- | --------------------------------------------------------------------------------- |
-| Production  | Le dernier déploiement de production prêt                                         |
-| Branche     | La dernière preview prête de la branche choisie, par exemple `staging.exemple.ch` |
-| Redirection | Un autre domaine du même projet, chemin conservé                                  |
+2. **Copier l'identifiant dans docs.json**
-Une redirection vise un domaine du même projet qui sert un site. Une redirection ne peut pas pointer vers une autre redirection.
+   La console affiche une ligne à copier. Ajoute-la dans `docs.json`, puis publie :
-Pour un domaine racine, la case **Ajouter aussi [www](http://www).** crée `www` en redirection permanente vers le domaine racine.
+   ```json
+   { "project": "k57a8m2x9q4n1b3c5d7e9f0g2h4j6k8m" }
+   ```
-## Codes de redirection
+   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.
-| Code  | Type                    | Méthode conservée |
-| ----- | ----------------------- | ----------------- |
-| `308` | Permanente (par défaut) | Oui               |
-| `301` | Permanente              | Non               |
-| `307` | Temporaire              | Oui               |
-| `302` | Temporaire              | Non               |
+3. **Synchroniser**
-Préfère `308` ou `307` : elles conservent la méthode et le corps de la requête.
+   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.
-## Propriété
+> **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.
-- La preuve TXT l’emporte. Une revendication non prouvée par une autre organisation ne bloque pas le propriétaire réel : l’organisation qui pose le TXT obtient le domaine.
-- Deux TXT prouvés en même temps : le premier prouvé garde le domaine.
-- Les noms de la plateforme ne peuvent pas être ajoutés comme domaine client : Host répond « Ce domaine appartient à la plateforme. »
+---
-## Limites
+Source : /guides/ecrire/
-| Limite                                    | Valeur                               |
-| ----------------------------------------- | ------------------------------------ |
-| Domaines par organisation                 | 50                                   |
-| Vérifications de domaine                  | 20 par minute, avec des rafales de 5 |
-| Revendications concurrentes d’un même nom | 10 au plus                           |
+# Écrire en MDX
-Voir [Limites](/docs/reference/limites/).
+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/`.
-## Propagation DNS
+## Métadonnées
-Un enregistrement neuf peut mettre de quelques minutes à quelques heures à apparaître. La vérification interroge des résolveurs DNS publics. Si aucun résolveur ne répond, le statut ne change pas.
+Le haut de la page, entre deux lignes `---`, décrit la page.
+```mdx
 ---
+title: Publier avec Host
+sidebarTitle: Publier
+description: Mettre la doc en ligne et brancher l'assistant.
+---
+```
-Source : /docs/reference/vercel-json/
-# vercel.json
+| 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. |
-Host applique le routage de ton site comme Vercel. Pour un site statique sans build, il lit `vercel.json` à la racine du dossier envoyé. Pour un site construit avec `vercel build`, il lit `.vercel/output/config.json`. Les options décrites ici sont converties par la bibliothèque de routage de Vercel, avec les mêmes règles.
+## Titres et sections
-## Options prises en charge
+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.
-| Option          | Effet                                                                      |
-| --------------- | -------------------------------------------------------------------------- |
-| `cleanUrls`     | Sert `/a-propos` pour `a-propos.html`, sans extension                      |
-| `trailingSlash` | Ajoute ou retire la barre oblique finale, par redirection                  |
-| `redirects`     | Redirige un chemin vers un autre, avec le code 301, 302, 307 ou 308        |
-| `rewrites`      | Sert un autre fichier, ou une URL externe, sans changer l’adresse affichée |
-| `headers`       | Ajoute des en-têtes de réponse à certains chemins                          |
-| `routes`        | Le format de routes historique de Vercel, pour les cas avancés             |
+> **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.
-Chaque liste (`redirects`, `rewrites`, `headers`, `routes`) accepte 1024 entrées au plus.
+## Liens
-## Exemple
+Les liens internes s’écrivent avec le chemin de la page : `[Publier](/guides/publier/)`. Pour une section : `[le domaine](/guides/publier/#ton-domaine)`.
-```json
-{
-  "cleanUrls": true,
-  "redirects": [
-    { "source": "/blog/:slug", "destination": "/articles/:slug", "permanent": true }
-  ],
-  "headers": [
-    {
-      "source": "/assets/(.*)",
-      "headers": [
-        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
-      ]
-    }
-  ]
-}
-```
+## Images
-## Build Output API
+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.
-Pour un site envoyé avec `vercel deploy --prebuilt`, Host lit `.vercel/output/config.json` (version 3) et sert le dossier `.vercel/output/static`. Les routes passent par les mêmes phases que chez Vercel : routes principales, système de fichiers, `miss`, `rewrite`, puis `error`.
+```mdx
+![Le tableau de bord](/images/tableau-de-bord.png)
+```
-Les conditions `has` et `missing` sont prises en compte. Elles portent sur l’hôte, un en-tête, un cookie ou un paramètre.
+Pour une légende, entoure l’image d’un cadre :
-## Ce qui est filtré
+```mdx
+<Frame caption="Le tableau de bord après la première publication">
+  ![Le tableau de bord](/images/tableau-de-bord.png)
+</Frame>
+```
-- Les en-têtes `set-cookie` d’une route ne sont pas servis.
-- Les fichiers et dossiers qui commencent par un point (`.env`, `.git`) ne sont jamais servis. Seul `.well-known` fait exception.
-- Une expression régulière jugée dangereuse ou trop longue fait échouer la publication. Le message désigne la route en cause. Un exemple de motif dangereux : des quantificateurs imbriqués, comme `(a+)+`.
+## Code
-## Pages introuvables
+Les blocs de code sont colorés et ont un bouton Copier. Indique le langage après les trois accents graves :
-Un fichier `404.html` à la racine du site sert de page d’erreur. Sans lui, Host affiche sa propre page 404.
+````mdx
+```bash
+npm run build
+```
+````
----
+## Ce qui n’est pas publié
-Source : /docs/reference/compatibilite/
-# Compatibilité avec Vercel
-Host implémente la partie de l’API Vercel qu’utilise la CLI pour relier un projet, récupérer ses variables, construire et déployer. La CLI officielle, version 63, est la référence de test.
-Cette page dit ce qui marche aujourd’hui. Elle distingue trois états :
-- **Pris en charge** : utilisable en production.
-- **En préversion** : utilisable, mais ouvert organisation par organisation. Une organisation qui n’en profite pas encore reçoit une réponse `501`.
-- **Pas encore** : absent de Host pour le moment.
-## Commandes de la CLI
-| Commande                                       | État                                                                  |
-| ---------------------------------------------- | --------------------------------------------------------------------- |
-| `vercel deploy`, avec `--prod` et `--prebuilt` | Pris en charge                                                        |
-| `vercel build`                                 | Pris en charge : télécharge les variables de l’environnement visé     |
-| `vercel pull`                                  | Pris en charge : réglages et variables                                |
-| `vercel link`                                  | Pris en charge                                                        |
-| `vercel login`                                 | Non : la connexion passe par la clé, dans `VERCEL_TOKEN` ou `--token` |
-| `vercel env`                                   | Pas encore : gère les variables dans la console                       |
-| `vercel domains`                               | Pas encore : gère les domaines dans la console                        |
-| `vercel logs`                                  | Pas encore : les logs sont dans la console                            |
-| `vercel env add`                               | Pas encore : ajoute les variables dans la console                     |
-## Fonctions de la plateforme
-| Fonction                                               | État                                                                   |
-| ------------------------------------------------------ | ---------------------------------------------------------------------- |
-| Fichiers statiques, Build Output API v3                | Pris en charge                                                         |
-| Routage de `vercel.json` et de `config.json`           | Pris en charge, voir [vercel.json](/docs/reference/vercel-json/)       |
-| Pages pré-rendues de Next.js                           | Prises en charge                                                       |
-| Draft mode                                             | Pris en charge                                                         |
-| Domaines, redirections, certificats                    | Pris en charge                                                         |
-| Réécritures vers une URL externe                       | Prises en charge                                                       |
-| Variables d’environnement, variables sensibles         | Prises en charge                                                       |
-| Rendu à la demande (SSR), routes d’API, Server Actions | En préversion : fonctions Node, ouvertes organisation par organisation |
-| Proxy (ex-middleware) et middleware Node.js            | En préversion                                                          |
-| Fonctions et middleware en runtime edge                | En préversion                                                          |
-| ISR (régénération incrémentale)                        | En préversion : cache par serveur, vidé à son redémarrage              |
-| Optimisation d’images                                  | Pas encore : l’image d’origine est servie, sans redimensionnement      |
-| Crons                                                  | En préversion : production seulement, avec `CRON_SECRET`               |
-Le détail du fonctionnement de la préversion est dans [Préversion et rendu à la demande](/docs/concepts/preversion/).
-## Frameworks
-| Framework                     | Ce qui est servi                                                                                                                                  | Commande de build        |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| Site statique (HTML, CSS, JS) | Le dossier tel quel                                                                                                                               | Aucune : `vercel deploy` |
-| Astro                         | Les pages générées, et en préversion le rendu à la demande, les routes d’API, le middleware et l’ISR                                              | `vercel build`           |
-| Vite (React, Vue, Svelte…)    | Le build de l’application                                                                                                                         | `vercel build`           |
-| SvelteKit                     | Les pages pré-rendues, et en préversion le rendu à la demande, les routes d’API, les actions de formulaire et l’ISR                               | `vercel build`           |
-| Nuxt                          | Les pages générées, et en préversion le rendu à la demande, les routes d’API, le middleware serveur et l’ISR                                      | `vercel build`           |
-| TanStack Start                | Les pages pré-rendues                                                                                                                             | `vercel build`           |
-| React Router                  | Les pages pré-rendues                                                                                                                             | `vercel build`           |
-| Next.js                       | Les pages pré-rendues et leur navigation, et en préversion le rendu à la demande, les routes d’API, le proxy, l’ISR et les routes en runtime edge | `vercel build`           |
-| Documentation `@hgdc/docs`    | Le site de documentation, chaque page en Markdown (`.md`), `llms.txt` et le corpus de l’assistant                                                 | `hgdc-docs build`        |
-Pour tout framework, la séquence est la même : construis, puis envoie le résultat avec `--prebuilt`. Voir [Déployer un framework](/docs/guides/deployer-un-framework/).
-## Ce que cette page ne couvre pas
-- Ce qui n’est pas listé ici n’est pas garanti. Ne suppose pas qu’une fonctionnalité de Vercel marche sur Host sans l’avoir testée.
-- Les limites chiffrées, comme la taille des fichiers ou les débits, sont sur [Limites](/docs/reference/limites/).
+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 : /docs/reference/limites/
-# Limites
+Source : /guides/composants/
-Ces limites protègent la plateforme et les autres organisations. Une requête qui dépasse une limite de débit reçoit `429` avec le code `rate_limited`. Attends quelques secondes, puis réessaie.
+# Composants
-Besoin d’une limite plus haute ? Écris à <support@hgdc.ch>.
+Ces composants s’utilisent directement dans une page `.mdx`, sans `import`. Ils portent les mêmes noms que chez Mintlify.
-## Déploiements et fichiers
+## Encadrés
-| Limite                                                     | Valeur                                                       |
-| ---------------------------------------------------------- | ------------------------------------------------------------ |
-| Taille d’un fichier                                        | 20 Mo                                                        |
-| Fichiers inclus directement dans la requête de déploiement | 20 Mo au total. Au-delà, envoie les fichiers par `/v2/files` |
-| Fichiers par déploiement                                   | 15 000                                                       |
-| Déploiements par organisation                              | 60 par heure, avec des rafales de 10                         |
-| Suivi de la publication par la CLI                         | 9 minutes au plus par connexion                              |
-## Fonctions (préversion)
+> **Note**
+>
+> Une information utile à côté du texte.
-| Limite                                   | Valeur                                                  |
-| ---------------------------------------- | ------------------------------------------------------- |
-| Mémoire par fonction                     | 512 Mo par défaut, 1 Go au plus                         |
-| Durée par requête                        | 30 secondes par défaut, 60 secondes au plus             |
-| Première requête après une période calme | Quelques secondes, le temps de démarrer l’environnement |
+> **Astuce**
+>
+> Un conseil qui fait gagner du temps.
-La durée peut être réglée par fonction avec `maxDuration`, dans la limite de 60 secondes. Voir [Préversion](/docs/concepts/preversion/).
+> **Attention**
+>
+> Un piège à éviter.
-## API
+> **Danger**
+>
+> Une action qui détruit des données.
-| Limite                          | Valeur                                      | Compté par   |
-| ------------------------------- | ------------------------------------------- | ------------ |
-| Requêtes à l’API                | 600 par minute, avec des rafales de 120     | Clé d’API    |
-| Envoi de fichiers (`/v2/files`) | 6 000 par minute, avec des rafales de 3 000 | Clé d’API    |
-| Vérifications de domaine        | 20 par minute, avec des rafales de 5        | Organisation |
+```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>
+```
-Les rafales sont le nombre de requêtes acceptées d’un coup, avant que la limite par minute ne s’applique.
+`<Info>` et `<Check>` existent aussi. Chacun accepte un `title`.
-## Projets, domaines et variables
+## Étapes
-| Limite                                                                            | Valeur         |
-| --------------------------------------------------------------------------------- | -------------- |
-| Domaines par organisation                                                         | 50             |
-| Nom d’une variable                                                                | 256 caractères |
-| Valeur d’une variable                                                             | 64 Ko          |
-| Note d’une variable                                                               | 500 caractères |
-| Variables synchronisées par configuration Doppler                                 | 300            |
-| Entrées par liste de `vercel.json` (`redirects`, `rewrites`, `headers`, `routes`) | 1024           |
+1. **Installer**
-## Journaux
+   Ajoute le paquet.
-| Limite                               | Valeur                    |
-| ------------------------------------ | ------------------------- |
-| Conservation des logs des requêtes   | 3 jours                   |
-| Lignes de logs de requêtes affichées | 1000 au plus              |
-| Conservation des logs de build       | Tant que le projet existe |
+2. **Configurer**
-Les minutes de GitHub Actions dépendent de ton compte GitHub, pas de Host.
+   Écris `docs.json`.
----
+```mdx
+<Steps>
+  <Step title="Installer">Ajoute le paquet.</Step>
+  <Step title="Configurer">Écris `docs.json`.</Step>
+</Steps>
+```
-Source : /docs/reference/api/introduction/
+## Cartes
-# Introduction à l'API
+[Avec un lien](/guides/publier/)
-L’API de Host reprend le sous-ensemble de l’API Vercel qu’utilise la CLI pour relier un dossier, construire et déployer. Elle accepte du JSON, renvoie du JSON, et s’authentifie par une clé d’API.
+[Toute la carte est cliquable.](/guides/publier/)
-Utilise l’API si tu écris ton propre outil. Pour déployer depuis un poste ou une CI, la [CLI](/docs/reference/cli/) suffit.
+Sans lien
-## Adresse de base
+Pour présenter une idée.
-```text
-https://api.host.hgdc.ch
+```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>
 ```
-Toutes les requêtes passent en HTTPS.
+`cols` va de 1 à 4. Sur téléphone, les cartes passent l’une sous l’autre.
-## Authentification
+## Onglets
-Envoie ta clé dans l’en-tête `Authorization`. Les clés commencent par `ah_` et se créent dans l’onglet **Clés d’API** de l’organisation. Voir [Créer et révoquer une clé d’API](/docs/guides/cle-d-api/).
-```http
-Authorization: Bearer ah_…
+```bash
+npm install --save-dev @hgdc/docs
 ```
 ```bash
-curl https://api.host.hgdc.ch/v2/user \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
+bun add --dev @hgdc/docs
 ```
-Il existe deux sortes de clés :
-| Clé                                                       | Portée                                                           | Variables sensibles      |
-| --------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------ |
-| Clé d’organisation, créée par un admin ou un propriétaire | Tous les projets de l’organisation, création de projets comprise | Jamais renvoyées         |
-| Clé de projet, posée par l’app GitHub dans le dépôt       | Ce seul projet. Tout autre projet répond `404`                   | Renvoyées, pour le build |
-> **Attention**
->
-> Une clé donne accès aux variables d’environnement de tes projets. Garde-la dans un gestionnaire de secrets, jamais dans le code ni dans le navigateur.
-## L’organisation vient de la clé
-Chaque clé appartient à une organisation, et chaque requête s’exécute dans cette organisation. Un identifiant d’organisation dans l’URL, ou un paramètre `teamId` ou `slug`, que la CLI ajoute parfois, est ignoré.
-## Versions dans le chemin
-Les chemins gardent les numéros de version de l’API Vercel, comme `/v2`, `/v9` ou `/v13`, pour que la CLI fonctionne sans modification. Plusieurs versions d’un même endpoint renvoient la même réponse : `/v9/projects` et `/v10/projects` par exemple.
+```mdx
+<Tabs>
+  <Tab title="npm">…</Tab>
+  <Tab title="Bun">…</Tab>
+</Tabs>
+```
-## Pagination
+## Accordéons
-Les listes ne sont pas paginées. Elles renvoient un objet `pagination` pour la compatibilité, avec `next` toujours à `null`.
+Faut-il un compte HGDC pour écrire ?
-## Limites de débit
+Non. Le site se construit sans compte. Le compte sert à la console : publication suivie et assistant.
-Chaque clé dispose de 600 requêtes par minute, avec des rafales de 120. L’envoi de fichiers a son propre budget : 6 000 par minute, avec des rafales de 3 000.
+Puis-je garder mes composants Mintlify ?
-Au-delà, l’API répond `429` avec le code `rate_limited` :
+Ceux de cette page, oui. Les autres s’affichent comme du texte : remplace-les ou écris-nous.
-```json
-{
-  "error": {
-    "code": "rate_limited",
-    "message": "Trop de requêtes, réessaie dans un instant."
-  }
-}
+```mdx
+<AccordionGroup>
+  <Accordion title="Question">Réponse.</Accordion>
+</AccordionGroup>
 ```
-La réponse porte un en-tête `retry-after` quand l’attente est connue. La création de déploiements est aussi limitée par organisation : voir [Limites](/docs/reference/limites/).
+## Dans le Markdown publié
-## Endpoints
+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.
-| Méthode | Chemin                                                            | Rôle                                  |
-| ------- | ----------------------------------------------------------------- | ------------------------------------- |
-| `GET`   | [`/v2/user`](/docs/reference/api/utilisateur/)                    | Personne qui a créé la clé            |
-| `GET`   | [`/v2/teams`](/docs/reference/api/utilisateur/)                   | Organisation de la clé                |
-| `GET`   | [`/v2/teams/:idOrSlug`](/docs/reference/api/utilisateur/)         | Lire l’organisation                   |
-| `GET`   | [`/v9/projects`](/docs/reference/api/projets/)                    | Lister les projets                    |
-| `GET`   | [`/v9/projects/:idOrName`](/docs/reference/api/projets/)          | Lire un projet                        |
-| `POST`  | [`/v11/projects`](/docs/reference/api/projets/)                   | Créer un projet                       |
-| `POST`  | [`/v2/files`](/docs/reference/api/fichiers/)                      | Envoyer un fichier                    |
-| `POST`  | [`/v13/deployments`](/docs/reference/api/deploiements/)           | Créer un déploiement                  |
-| `GET`   | [`/v13/deployments/:id`](/docs/reference/api/deploiements/)       | Lire un déploiement                   |
-| `GET`   | [`/v3/deployments/:id/events`](/docs/reference/api/deploiements/) | Suivre les logs                       |
-| `GET`   | [`/v3/env/pull/:project/:target`](/docs/reference/api/variables/) | Lire les variables d’un environnement |
+---
-Les erreurs et leurs codes sont sur [Erreurs](/docs/reference/api/erreurs/).
+Source : /guides/navigation/
----
+# Navigation, onglets et versions
-Source : /docs/reference/api/erreurs/
+La navigation se décrit dans `docs.json`, sous `navigation`. Choisis **une** forme : `pages`, `groups`, `tabs` ou `versions`.
-# Erreurs de l'API
+## Pages et groupes
-Une erreur répond avec un statut HTTP `4xx` ou `5xx`, et un objet `error`. Le champ `code` est stable : teste-le dans ton code. Le champ `message` est en français et s’affiche à une personne.
+Pour une petite doc, une liste de groupes suffit. Un groupe peut contenir d’autres groupes.
 ```json
 {
-  "error": {
-    "code": "not_found",
-    "message": "Projet introuvable."
+  "navigation": {
+    "groups": [
+      { "group": "Démarrer", "pages": ["index", "installation"] },
+      {
+        "group": "Guides",
+        "pages": ["guides/facturer", { "group": "Avancé", "expanded": false, "pages": ["guides/webhooks"] }]
+      }
+    ]
   }
 }
 ```
-## Codes
-| Statut | Code                    | Cause                                                                                                    | Que faire                                                                               |
-| ------ | ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `400`  | `bad_request`           | Corps ou paramètre invalide. Le message nomme le champ en cause                                          | Corrige la requête                                                                      |
-| `400`  | `missing_files`         | Des fichiers du déploiement ne sont pas encore envoyés. La réponse liste leurs empreintes dans `missing` | Envoie-les par [`/v2/files`](/docs/reference/api/fichiers/), puis recrée le déploiement |
-| `400`  | `invalid_digest`        | Le contenu envoyé ne correspond pas à l’empreinte annoncée                                               | Recalcule le SHA1 du fichier                                                            |
-| `403`  | `forbidden`             | Clé absente, inconnue ou révoquée. Ou clé de projet utilisée pour un autre projet                        | Vérifie la clé et sa portée                                                             |
-| `404`  | `not_found`             | Ressource introuvable, ou hors de la portée de la clé                                                    | Vérifie l’identifiant ou le nom                                                         |
-| `409`  | `conflict`              | Un projet porte déjà ce nom                                                                              | Choisis un autre nom, ou utilise le projet existant                                     |
-| `409`  | `deployment_closed`     | Le déploiement a été annulé ou a échoué : rien n’est publié                                              | Crée un nouveau déploiement                                                             |
-| `413`  | `file_too_large`        | Un fichier dépasse 20 Mo                                                                                 | Allège le fichier, ou sers-le autrement                                                 |
-| `413`  | `payload_too_large`     | Les fichiers inclus dans le corps dépassent 20 Mo au total                                               | Envoie-les par [`/v2/files`](/docs/reference/api/fichiers/)                             |
-| `429`  | `rate_limited`          | Trop de requêtes pour cette clé                                                                          | Attends un instant, puis réessaie                                                       |
-| `500`  | `internal_server_error` | Erreur de la plateforme. Elle est signalée automatiquement                                               | Réessaie. Si elle persiste, écris à <support@hgdc.ch>                                   |
-Toutes les routes peuvent répondre `403 forbidden`, `429 rate_limited` et `500 internal_server_error`.
-Le message d’une erreur `500` ne donne jamais de détail technique. Ne compte pas sur son texte, seulement sur son code.
+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.
-## Le cas de missing_files
+## Onglets
-`missing_files` n’est pas une panne : c’est l’étape normale d’un déploiement. La CLI la traite toute seule. Si tu écris ton propre client, voici la réponse :
+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
 {
-  "error": {
-    "code": "missing_files",
-    "message": "Fichiers à envoyer avant de créer le déploiement.",
-    "missing": [
-      "2ef7bde608ce5404e97d5f042f95f89f1c232871"
+  "navigation": {
+    "tabs": [
+      { "tab": "Guides", "groups": [{ "group": "Démarrer", "pages": ["index"] }] },
+      { "tab": "Référence", "groups": [{ "group": "API", "pages": ["reference/api"] }] }
     ]
   }
 }
 ```
-Envoie chaque fichier listé, puis renvoie exactement la même requête de [création de déploiement](/docs/reference/api/deploiements/).
----
-Source : /docs/reference/api/utilisateur/
-# Lire le propriétaire de la clé et l'organisation
-Ces trois endpoints disent qui utilise la clé, et dans quelle organisation elle travaille. La CLI les appelle au premier contact.
-## GET `/v2/user`
-Renvoie la personne qui a créé la clé.
+> **Astuce**
+>
+> Cette doc suit le découpage Diataxis : des guides pour faire, une référence pour vérifier, des explications pour comprendre.
-```bash
-curl https://api.host.hgdc.ch/v2/user \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
-```
+## Versions
-Réponse `200` :
+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
 {
-  "user": {
-    "id": "u1a2b3c4d5",
-    "uid": "u1a2b3c4d5",
-    "email": "camille@atelier.ch",
-    "name": "Camille Rochat",
-    "username": "atelier",
-    "defaultTeamId": "k57a1b2c3d4e5f6g7h8j9k0m1n",
-    "version": "northstar"
+  "navigation": {
+    "versions": [
+      { "version": "v2", "default": true, "groups": [{ "group": "Démarrer", "pages": ["index"] }] },
+      { "version": "v1", "groups": [{ "group": "Démarrer", "pages": ["v1/index"] }] }
+    ]
   }
 }
 ```
-| Champ                | Type     | Description                                                                 |
-| -------------------- | -------- | --------------------------------------------------------------------------- |
-| `user.id`            | `string` | Identifiant de la personne. `uid` porte la même valeur                      |
-| `user.email`         | `string` | Adresse e-mail de la personne, tant qu’elle est membre de l’organisation    |
-| `user.name`          | `string` | Nom affiché de la personne. À défaut, l’adresse e-mail                      |
-| `user.username`      | `string` | Slug de l’organisation de la clé                                            |
-| `user.defaultTeamId` | `string` | Identifiant de l’organisation de la clé. C’est la valeur de `VERCEL_ORG_ID` |
-| `user.version`       | `string` | Valeur fixe : `northstar`                                                   |
+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 ».
-Erreurs : `403 forbidden` si l’organisation de la clé n’existe plus.
+## Précédent et suivant
-## GET `/v2/teams`
+En bas de chaque page, les liens Précédent et Suivant suivent l’ordre de la navigation, sans sortir de l’onglet ouvert.
-Renvoie l’organisation de la clé. La liste ne contient jamais qu’une seule organisation : une clé n’ouvre qu’une organisation.
+---
-```bash
-curl https://api.host.hgdc.ch/v2/teams \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
-```
+Source : /guides/theme/
+# Thème et logo
-Réponse `200` :
+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
-{
-  "teams": [
-    {
-      "id": "k57a1b2c3d4e5f6g7h8j9k0m1n",
-      "slug": "atelier",
-      "name": "Atelier Rochat",
-      "avatar": null,
-      "membership": { "role": "OWNER" }
-    }
-  ],
-  "pagination": { "count": 1, "next": null, "prev": null }
-}
+{ "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**
 >
-> `membership.role` vaut toujours `OWNER` pour la CLI, quel que soit le rôle réel de la personne. Les vrais rôles se gèrent dans Account, voir [Organisations et rôles](/docs/concepts/organisations-et-roles/).
-## GET `/v2/teams/:idOrSlug`
+> Dans la console, **Réglages › Thème** montre l’effet d’une couleur en clair et en sombre, son contraste sur un fond blanc, et prépare la ligne à copier dans `docs.json`.
-Renvoie l’organisation seule, sans liste. Le paramètre est l’identifiant ou le slug de l’organisation de la clé.
+## Logo
-```bash
-curl https://api.host.hgdc.ch/v2/teams/atelier \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
+```json
+{ "logo": { "light": "/images/logo-clair.svg", "dark": "/images/logo-sombre.svg" } }
 ```
-Toute autre organisation répond `404 not_found`. Les deux routes répondent aussi sous `/v1`.
+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"`.
-## Erreurs
+## Favicon
-| Statut | Code        | Cause                                                                          |
-| ------ | ----------- | ------------------------------------------------------------------------------ |
-| `403`  | `forbidden` | Pour `/v2/user` : l’organisation de la clé n’existe plus                       |
-| `404`  | `not_found` | Pour `/v2/teams/:idOrSlug` : l’organisation demandée n’est pas celle de la clé |
+```json
+{ "favicon": "/images/favicon.svg" }
+```
-Voir la liste complète sur [Erreurs](/docs/reference/api/erreurs/).
+Sans favicon, le site n’en annonce pas d’autre que `/favicon.svg` s’il existe.
 ---
-Source : /docs/reference/api/projets/
-# Projets
+Source : /guides/assistant/
-Un projet correspond à un site. Il a ses variables, ses domaines et son historique de déploiements.
+# L'assistant IA
-## GET `/v9/projects`
+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.
-Liste les projets de l’organisation. Avec une clé de projet, la liste ne contient que ce projet. La liste compte 100 projets au plus.
+## D’où viennent les réponses
-```bash
-curl https://api.host.hgdc.ch/v9/projects \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
-```
-Réponse `200` :
-```json
-{
-  "projects": [
-    {
-      "id": "j97d3k2m8x1q4p6s7t9v0w2y5z",
-      "name": "site-atelier",
-      "accountId": "k57a1b2c3d4e5f6g7h8j9k0m1n",
-      "framework": "astro",
-      "rootDirectory": null,
-      "buildCommand": null,
-      "installCommand": null,
-      "outputDirectory": null,
-      "nodeVersion": "24.x",
-      "createdAt": 1760259600000,
-      "updatedAt": 1760259600000
-    }
-  ],
-  "pagination": { "count": 1, "next": null, "prev": null }
-}
-```
+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.
-Le même endpoint répond aussi sous `/v10/projects`.
+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.
-## GET `/v9/projects/:idOrName`
-Lit un projet, par son identifiant ou son nom, sans tenir compte de la casse.
-```bash
-curl https://api.host.hgdc.ch/v9/projects/site-atelier \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
-```
+> **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.
-Réponse `200` : l’objet projet, décrit ci-dessous. Les routes `/v9` et `/v10` renvoient la même réponse.
+## Activer et désactiver
-| Erreur | Code        | Cause                                                                             |
-| ------ | ----------- | --------------------------------------------------------------------------------- |
-| `404`  | `not_found` | Aucun projet de ce nom dans l’organisation, ou projet hors de la portée de la clé |
+L’assistant est actif dès que `docs.json` porte l’identifiant `project` et que la console a indexé le site. Pour le couper :
-## POST `/v11/projects`
+- dans la console, **Assistant › Assistant sur le site** (effet immédiat) ;
+- ou dans `docs.json`, `"assistant": { "enabled": false }` (au prochain build).
-Crée un projet. Tu peux aussi t’en passer : le premier déploiement sur un nom inconnu crée le projet.
+## Quota
-```bash
-curl -X POST https://api.host.hgdc.ch/v11/projects \
-  -H "Authorization: Bearer $VERCEL_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name":"site-atelier","framework":"astro"}'
-```
+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.
-| Champ       | Type               | Requis | Description                                                                                                                                        |
-| ----------- | ------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`      | `string`           | Oui    | Nom du projet, 100 caractères au plus. Il devient le nom dans l’URL, en minuscules                                                                 |
-| `framework` | `string` ou `null` | Non    | `nextjs`, `astro`, `vite`, `sveltekit`, `nuxt`, `tanstack-start` ou `react-router`. Une autre valeur, ou `null`, enregistre un site sans framework |
-Réponse `200` : l’objet projet créé.
-| Erreur | Code          | Cause                                              |
-| ------ | ------------- | -------------------------------------------------- |
-| `400`  | `bad_request` | Nom absent ou trop long                            |
-| `403`  | `forbidden`   | La clé est limitée à un projet : elle ne crée rien |
-| `409`  | `conflict`    | Un projet porte déjà ce nom                        |
-## L’objet projet
-| Champ                | Type                 | Description                                                                                                                                                                                                                                                            |
-| -------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                 | `string`             | Identifiant du projet. C’est la valeur de `VERCEL_PROJECT_ID`                                                                                                                                                                                                          |
-| `name`               | `string`             | Nom du projet, dans l’URL de la console                                                                                                                                                                                                                                |
-| `accountId`          | `string`             | Identifiant de l’organisation propriétaire                                                                                                                                                                                                                             |
-| `framework`          | `string` ou `null`   | Framework enregistré, ou `null` pour un site sans framework                                                                                                                                                                                                            |
-| `rootDirectory`      | `string` ou `null`   | Dossier de l’app dans le dépôt, pour un monorepo                                                                                                                                                                                                                       |
-| `buildCommand`       | `string` ou `null`   | Commande de build imposée. `null` : celle détectée par `vercel build`                                                                                                                                                                                                  |
-| `installCommand`     | `string` ou `null`   | Commande d’installation imposée                                                                                                                                                                                                                                        |
-| `outputDirectory`    | `string` ou `null`   | Dossier de sortie imposé                                                                                                                                                                                                                                               |
-| `nodeVersion`        | `"22.x"` ou `"24.x"` | Version de Node.js du build                                                                                                                                                                                                                                            |
-| `createdAt`          | `number`             | Date de création, en millisecondes depuis l’époque Unix                                                                                                                                                                                                                |
-| `updatedAt`          | `number`             | Même valeur que `createdAt`                                                                                                                                                                                                                                            |
-| `link`               | `object`             | Présent seulement pour un projet relié à GitHub : `type` (`github`), `repo` (`propriétaire/dépôt`) et `productionBranch`                                                                                                                                               |
-| `alias`              | `object[]`           | Adresse de production du projet : `domain` (`<projet>.hgdc.cloud`), `target` (`PRODUCTION`), `environment` (`production`), `createdAt`, `deployment` (`null`). Les domaines personnalisés n’y figurent pas                                                             |
-| `targets.production` | `object`             | Présent une fois une production en ligne : le déploiement servi, avec `id`, `url`, `alias` (`["<projet>.hgdc.cloud"]`), `aliasAssigned` (moment de la mise en ligne), `readyState`, `createdAt`, `readyAt` et `meta`. `targets` vaut `{}` avant la première production |
-Pour un projet dont le framework n’est pas reconnu, `framework` vaut `null`.
-## Voir aussi
-- [Déploiements](/docs/reference/api/deploiements/) : créer un déploiement pour ce projet.
-- [Erreurs](/docs/reference/api/erreurs/) : la liste des codes.
+Pour éviter qu’un seul visiteur ou un script épuise le quota, chaque visiteur a droit à 6 questions par minute et 40 par jour, et chaque doc à 30 par minute et 200 par jour. HGDC relève le plafond journalier d’une doc sur demande.
----
+## Tester et lire le journal
-Source : /docs/reference/api/deploiements/
+En haut de la page **Assistant**, les 30 derniers jours : nombre de questions, part de réponses sourcées, et les **questions sans réponse**, regroupées et classées de la plus posée à la moins posée. Chacune ouvre le journal filtré : c’est la liste des pages à écrire.
-# Déploiements
+**Assistant › Tester l’assistant** pose une question comme un visiteur. Le **journal** garde les questions des 90 derniers jours avec leur état :
-Un déploiement est une version figée de ton site, avec sa propre adresse. Créer un déploiement est l’appel central de `vercel deploy`.
+| É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. |
-## Déroulement d’une création
+Au-dessus du journal, cherche une question par ses mots, ou filtre par état : **État › Hors doc** ne garde que les questions sans réponse. Les filtres restent dans l’adresse de la page : tu peux la garder en favori ou l’envoyer à un collègue.
-1. Envoie la liste des fichiers avec leur empreinte SHA1.
-2. Si des fichiers manquent, l’API répond `400 missing_files`, avec leurs empreintes dans `missing`. Envoie-les par [`/v2/files`](/docs/reference/api/fichiers/).
-3. Renvoie exactement la même requête. Elle crée le déploiement.
+> **Astuce**
+>
+> Lis les questions « hors doc » une fois par semaine : c’est la liste des pages qui manquent, écrite par tes visiteurs.
-Les petits fichiers peuvent aussi être inclus directement dans le corps, dans le champ `data`, sans passer par `/v2/files`. La limite de 20 Mo vaut alors pour l’ensemble des fichiers inclus.
+---
-## POST `/v13/deployments`
+Source : /guides/agents/
-```bash
-curl -X POST https://api.host.hgdc.ch/v13/deployments \
-  -H "Authorization: Bearer $VERCEL_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "site-atelier",
-    "target": "production",
-    "files": [
-      { "file": "index.html", "data": "<h1>Bonjour</h1>" }
-    ]
-  }'
-```
+# llms.txt et MCP
-### Corps
+Les assistants de code et les agents lisent la documentation pour écrire du code juste. Docs leur donne trois portes d’entrée, sans rien à configurer.
-| Champ                       | Type                     | Requis                  | Description                                                                                                                |
-| --------------------------- | ------------------------ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `name`                      | `string`                 | Si `project` est absent | Nom du projet. Le projet est créé s’il n’existe pas                                                                        |
-| `project`                   | `string`                 | Non                     | Identifiant ou nom du projet. Prioritaire sur `name`                                                                       |
-| `target`                    | `"production"` ou `null` | Non                     | `production` pour la production. Toute autre valeur crée une preview                                                       |
-| `files`                     | `object[]`               | Oui                     | Fichiers du déploiement, 15 000 au plus. Voir ci-dessous                                                                   |
-| `projectSettings.framework` | `string` ou `null`       | Non                     | Framework, enregistré si le déploiement crée le projet                                                                     |
-| `gitMetadata`               | `object`                 | Non                     | `commitRef` (branche), `commitSha` et `commitMessage`, affichés dans la console                                            |
-| `meta`                      | `Record<string, string>` | Non                     | Métadonnées libres. `githubCommitRef`, `githubCommitSha` et `githubCommitMessage` remplacent `gitMetadata` quand il manque |
+## llms.txt
-Chaque élément de `files` prend l’une de ces formes :
+Chaque site publie à sa racine :
-- `{ "file", "sha", "size" }` : chemin relatif, empreinte SHA1 et taille en octets, pour un fichier déjà envoyé par `/v2/files` ;
-- `{ "file", "data", "encoding" }` : contenu inclus. `encoding` vaut `utf-8` (par défaut) ou `base64`.
+- `/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.
-`mode` (permissions Unix) est accepté et conservé. Un dossier vide, `{ "file", "mode" }`, est ignoré.
+## Une page en Markdown
-### Réponse
+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"`.
-Réponse `200` : l’objet déploiement. Le déploiement naît le plus souvent à l’état `QUEUED`. Suis-le avec `GET /v13/deployments/:id`, plus bas sur cette page, ou avec le flux de logs `GET /v3/deployments/:id/events`.
+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.
-### Erreurs
+## Serveur MCP
-| Statut | Code                | Cause                                                              |
-| ------ | ------------------- | ------------------------------------------------------------------ |
-| `400`  | `bad_request`       | Corps invalide, ou nom de projet absent. Le message nomme le champ |
-| `400`  | `missing_files`     | Des fichiers sont à envoyer avant de créer le déploiement          |
-| `403`  | `forbidden`         | La clé est limitée à un autre projet                               |
-| `409`  | `deployment_closed` | Le déploiement a été annulé ou a échoué : rien n’est publié        |
-| `413`  | `payload_too_large` | Les fichiers inclus dépassent 20 Mo au total                       |
+Chaque projet a un serveur MCP en lecture seule. L’adresse est dans l’aperçu du projet, dans la console :
-## GET `/v13/deployments/:id`
+```text
+https://docs.hgdc.ch/mcp/<identifiant du projet>
+```
-Lit un déploiement.
+Dans Claude Code :
 ```bash
-curl https://api.host.hgdc.ch/v13/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
+claude mcp add --transport http acme-docs https://docs.hgdc.ch/mcp/<identifiant du projet>
 ```
-Réponse `200` :
+Dans Cursor (`.cursor/mcp.json`) :
 ```json
-{
-  "id": "jd7f2k9m3x8q1p5s6t4v0w7y2z",
-  "uid": "jd7f2k9m3x8q1p5s6t4v0w7y2z",
-  "url": "site-atelier-h3k9x2.hgdc.cloud",
-  "name": "site-atelier",
-  "projectId": "j97d3k2m8x1q4p6s7t9v0w2y5z",
-  "ownerId": "k57a1b2c3d4e5f6g7h8j9k0m1n",
-  "readyState": "READY",
-  "status": "READY",
-  "target": "production",
-  "type": "LAMBDAS",
-  "createdAt": 1760259600000,
-  "buildingAt": 1760259601000,
-  "ready": 1760259604000,
-  "alias": ["site-atelier.hgdc.cloud"],
-  "aliasAssigned": true,
-  "aliasAssignedAt": 1760259604000,
-  "aliasError": null,
-  "errorMessage": null,
-  "inspectorUrl": "https://host.hgdc.ch/atelier/site-atelier/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z",
-  "meta": {
-    "branch": "main",
-    "commitSha": "4c3e2f1a9b8d7c6e5f4a3b2c1d0e9f8a7b6c5d4e",
-    "commitMessage": "Nouvelle page Tarifs"
-  },
-  "creator": { "uid": "u1a2b3c4d5" }
-}
-```
-| Champ             | Type                     | Description                                                                                                                                                           |
-| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`              | `string`                 | Identifiant du déploiement. `uid` porte la même valeur                                                                                                                |
-| `url`             | `string`                 | Adresse du déploiement, sans `https://`. Elle reste valable tant que le déploiement existe                                                                            |
-| `name`            | `string`                 | Nom du projet                                                                                                                                                         |
-| `projectId`       | `string`                 | Identifiant du projet                                                                                                                                                 |
-| `ownerId`         | `string`                 | Identifiant de l’organisation                                                                                                                                         |
-| `readyState`      | `string`                 | État : `QUEUED`, `BUILDING`, `READY`, `ERROR` ou `CANCELED`. `status` porte la même valeur                                                                            |
-| `target`          | `"production"` ou `null` | `production`, ou `null` pour une preview                                                                                                                              |
-| `createdAt`       | `number`                 | Date de création, en millisecondes                                                                                                                                    |
-| `buildingAt`      | `number`                 | Début du traitement, en millisecondes                                                                                                                                 |
-| `ready`           | `number` ou `null`       | Fin du traitement. `null` tant que le déploiement n’est pas prêt                                                                                                      |
-| `alias`           | `string[]`               | Adresse de production du projet (`<projet>.hgdc.cloud`), une fois un déploiement de production prêt. Vide pour une preview. La CLI l’affiche sur la ligne « Aliased » |
-| `aliasAssigned`   | `boolean`                | `true` quand le déploiement est prêt                                                                                                                                  |
-| `aliasAssignedAt` | `number` ou `null`       | Moment où l’adresse de production lui a été attribuée. `null` pour une preview                                                                                        |
-| `aliasError`      | `null`                   | Toujours `null`                                                                                                                                                       |
-| `errorMessage`    | `string` ou `null`       | Cause de l’échec, quand `readyState` vaut `ERROR`                                                                                                                     |
-| `inspectorUrl`    | `string`                 | Page du déploiement dans la console                                                                                                                                   |
-| `type`            | `"LAMBDAS"`              | Valeur fixe, pour la CLI                                                                                                                                              |
-| `meta`            | `object`                 | Informations Git connues : `branch`, `commitSha`, `commitMessage`                                                                                                     |
-| `creator.uid`     | `string`                 | Personne qui a créé la clé utilisée                                                                                                                                   |
-### Attendre la fin
-Pour attendre qu’un déploiement soit prêt, interroge cet endpoint toutes les secondes jusqu’à `READY`, `ERROR` ou `CANCELED`. Tu peux aussi ouvrir le flux `GET /v3/deployments/:id/events` décrit plus bas, qui se ferme tout seul à la fin.
-| Erreur | Code        | Cause                                                                         |
-| ------ | ----------- | ----------------------------------------------------------------------------- |
-| `404`  | `not_found` | Déploiement inconnu, d’une autre organisation, ou hors de la portée de la clé |
-## GET `/v3/deployments/:id/events`
-Renvoie les logs de build d’un déploiement, un événement JSON par ligne (NDJSON). Avec `follow=1`, la connexion reste ouverte et reçoit les nouvelles lignes au fil de l’eau.
-```bash
-curl -N "https://api.host.hgdc.ch/v3/deployments/jd7f2k9m3x8q1p5s6t4v0w7y2z/events?follow=1" \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
+{ "mcpServers": { "acme-docs": { "url": "https://docs.hgdc.ch/mcp/<identifiant du projet>" } } }
 ```
-| Paramètre | Valeur | Rôle                                                                        |
-| --------- | ------ | --------------------------------------------------------------------------- |
-| `follow`  | `1`    | Garde la connexion ouverte jusqu’à la fin du déploiement, 9 minutes au plus |
-Le type de réponse est `application/x-ndjson`. Chaque ligne de log ressemble à ceci :
+Dans VS Code (`.vscode/mcp.json`) :
 ```json
-{"type":"stdout","created":1760259601000,"date":1760259601000,"deploymentId":"jd7f2k9m3x8q1p5s6t4v0w7y2z","id":"l3k…","text":"Publication de 42 fichiers","payload":{"id":"l3k…","text":"Publication de 42 fichiers","date":1760259601000,"deploymentId":"jd7f2k9m3x8q1p5s6t4v0w7y2z"}}
+{ "servers": { "acme-docs": { "type": "http", "url": "https://docs.hgdc.ch/mcp/<identifiant du projet>" } } }
 ```
-| Champ     | Type                     | Description                                                        |
-| --------- | ------------------------ | ------------------------------------------------------------------ |
-| `type`    | `"stdout"` ou `"stderr"` | `stderr` pour une ligne d’erreur                                   |
-| `text`    | `string`                 | Texte de la ligne                                                  |
-| `date`    | `number`                 | Date de la ligne, en millisecondes. `created` porte la même valeur |
-| `payload` | `object`                 | Les mêmes champs, au format historique de la CLI                   |
+L’aperçu du projet donne ces lignes déjà remplies. Le serveur reste ouvert quand l’assistant du site est coupé : il ne fait que chercher, sans modèle.
-Une fois le déploiement terminé, une dernière ligne donne son état, puis le flux se ferme :
+Le serveur propose trois outils :
-```json
-{"type":"state","event":"state","date":1760259604000,"payload":{"value":"READY"}}
-```
+| 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.                                              |
-Les lignes du build GitHub Actions ne sont pas renvoyées ici : elles sont dans le run GitHub, et la console les affiche sur la page du déploiement.
+Le détail du protocole est dans la [référence MCP](/reference/mcp/).
-Le même endpoint répond aussi sous `/v3/now/deployments/:id/events`.
+---
-| Erreur | Code        | Cause                                               |
-| ------ | ----------- | --------------------------------------------------- |
-| `404`  | `not_found` | Déploiement inconnu, ou hors de la portée de la clé |
+Source : /reference/docs-json/
----
+# docs.json
-Source : /docs/reference/api/fichiers/
+`docs.json` vit à la racine du dossier de la doc. Il reprend le format de Mintlify : les champs que 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"`.
-# Envoyer un fichier
+## Champs
-Un fichier s’envoie par son empreinte SHA1. Host ne stocke jamais deux fois le même contenu pour une organisation : tu n’envoies que les fichiers que [Créer un déploiement](/docs/reference/api/deploiements/) signale comme manquants.
+| 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.                                                                                                                                                                                                                                                                                                   |
+| `base`               | texte                                         | non         | Sous-chemin où la doc est servie, par exemple `/docs` quand ton application la publie derrière un proxy (`https://app.acme.ch/docs`). Liens, images, recherche, `llms.txt` et pages `.md` le portent ; le site est écrit dans `dist/docs/`. Écris tes liens depuis la racine de la doc (`/guides/publier/`) : le sous-chemin est ajouté au build. |
+| `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.                                                                                                                                                                                                                                                                                                                  |
+| `navbar.links`       | liste de `{ label, href }`                    | non         | Jusqu’à 5 liens dans la barre du haut (adresses complètes).                                                                                                                                                                                                                                                                                       |
+| `navbar.primary`     | `{ label, href }`                             | non         | Bouton mis en avant à droite de la barre du haut.                                                                                                                                                                                                                                                                                                 |
+| `footer.socials`     | objet                                         | non         | Liens vers tes réseaux : `linkedin`, `github`, `gitlab`, `x`, `youtube`, `instagram`, `facebook`, `discord`, `mastodon`, `bluesky`, `website`.                                                                                                                                                                                                    |
+| `redirects`          | liste de `{ source, destination, permanent }` | non         | Anciennes adresses qui mènent aux nouvelles. `source` est un chemin du site (`/guides/ancien`), `destination` un chemin ou une adresse `https://`. `permanent: false` pour une redirection temporaire. 500 au plus.                                                                                                                               |
+| `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.                                                                                                                                                                                                                                                                               |
-## POST `/v2/files`
+## Navigation
-```bash
-SHA=$(sha1sum index.html | cut -d' ' -f1)
-curl -X POST https://api.host.hgdc.ch/v2/files \
-  -H "Authorization: Bearer $VERCEL_TOKEN" \
-  -H "x-vercel-digest: $SHA" \
-  -H "Content-Type: application/octet-stream" \
-  --data-binary @index.html
-```
+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": [...] }]` |
-En Node.js, calcule l’empreinte avant l’envoi :
+Un groupe accepte `expanded: false` pour être replié par défaut, et peut contenir des groupes.
-```javascript
-import { createHash } from "node:crypto"
-import { readFile } from "node:fs/promises"
+## Erreurs
-const bytes = await readFile("index.html")
-const sha = createHash("sha1").update(bytes).digest("hex")
+Un `docs.json` invalide fait échouer le build avec la liste des problèmes, par exemple :
-await fetch("https://api.host.hgdc.ch/v2/files", {
-  method: "POST",
-  headers: {
-    Authorization: `Bearer ${process.env.VERCEL_TOKEN}`,
-    "x-vercel-digest": sha,
-    "Content-Type": "application/octet-stream",
-  },
-  body: bytes,
-})
+```text
+docs.json invalide :
+- colors.primary : couleur attendue au format #rrggbb
+- navigation : utiliser une seule forme parmi versions, tabs, groups ou pages
 ```
-### En-têtes
+---
-| En-tête           | Valeur                                                   | Requis                                |
-| ----------------- | -------------------------------------------------------- | ------------------------------------- |
-| `Authorization`   | `Bearer ah_…`                                            | Oui                                   |
-| `x-vercel-digest` | Empreinte SHA1 du contenu, en hexadécimal, 40 caractères | Oui. `x-now-digest` est aussi accepté |
-| `Content-Type`    | `application/octet-stream`                               | Recommandé                            |
+Source : /reference/cli/
-### Corps
+# La commande hgdc-docs
-Le contenu brut du fichier, 20 Mo au plus.
+`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.
-### Réponse
+## Commandes
-Réponse `200` avec un objet vide, `{}`.
+| 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.                                                     |
-### Erreurs
+Options : `--port 4000` change le port de `dev` et `preview`, `--help` affiche l’aide.
-| Statut | Code             | Cause                                                                  |
-| ------ | ---------------- | ---------------------------------------------------------------------- |
-| `400`  | `bad_request`    | En-tête `x-vercel-digest` absent ou mal formé                          |
-| `400`  | `invalid_digest` | Le contenu ne correspond pas à l’empreinte annoncée. Recalcule le SHA1 |
-| `413`  | `file_too_large` | Le fichier dépasse 20 Mo                                               |
+## Variables d’environnement
-## Limites
+| 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 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.                                                                                                              |
-L’envoi de fichiers a son propre débit : 6 000 par minute, avec des rafales de 3 000 par clé. Un site Next.js compte souvent des milliers de fichiers : envoie-les en parallèle, mais sans dépasser ce débit. Voir [Limites](/docs/reference/limites/).
+## 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 : /docs/reference/api/variables/
+Source : /reference/api-assistant/
-# Lire les variables d'un environnement
+# API de l'assistant
-Cet endpoint renvoie les variables d’un environnement, au format attendu par `vercel pull` et `vercel build`. Les valeurs sont renvoyées déchiffrées : elles ne doivent jamais partir vers le navigateur.
+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.
-## GET `/v3/env/pull/:project/:target`
+## Requête
-```bash
-curl https://api.host.hgdc.ch/v3/env/pull/site-atelier/production \
-  -H "Authorization: Bearer $VERCEL_TOKEN"
+```http
+POST https://docs.hgdc.ch/api/v1/ask
+Content-Type: application/json
+Origin: https://docs.acme.ch
 ```
-```bash
-# Équivalent avec la CLI
-vercel --api https://api.host.hgdc.ch pull --environment=production
+```json
+{
+  "project": "k57a8m2x9q4n1b3c5d7e9f0g2h4j6k8m",
+  "question": "Comment publier ma doc ?",
+  "page": "/guides/publier/",
+  "previous": ["j97f2k8m1q4n6b3c5d7e9f0g2h4j6k8m"]
+}
 ```
-### Paramètres de chemin
-| Paramètre | Type                                           | Requis | Description                               |
-| --------- | ---------------------------------------------- | ------ | ----------------------------------------- |
-| `project` | `string`                                       | Oui    | Identifiant ou nom du projet              |
-| `target`  | `"production"`, `"preview"` ou `"development"` | Non    | Environnement. Par défaut : `development` |
+| 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. |
-### Réponse
+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 40 par jour.
-Réponse `200` :
+## Réponse
 ```json
 {
-  "env": {
-    "PUBLIC_API_URL": "https://api.atelier.ch",
-    "CONTACT_EMAIL": "bonjour@atelier.ch"
-  },
-  "buildEnv": {
-    "PUBLIC_API_URL": "https://api.atelier.ch",
-    "CONTACT_EMAIL": "bonjour@atelier.ch"
-  }
+  "id": "j97f…",
+  "status": "answered",
+  "answer": "Importe le dépôt dans Host[^1], puis synchronise le projet dans la console[^2].",
+  "sources": [
+    { "n": 1, "title": "Publier avec Host", "section": "Avec Host", "url": "https://docs.acme.ch/guides/publier/#avec-host" },
+    { "n": 2, "title": "Publier avec Host", "section": "Relier la console", "url": "https://docs.acme.ch/guides/publier/#relier-la-console" }
+  ]
 }
 ```
-`env` et `buildEnv` contiennent les mêmes variables. Si le projet a un domaine de production, `VERCEL_PROJECT_PRODUCTION_URL` figure aussi dans la réponse. Voir [Variables : référence](/docs/reference/variables/#variables-fournies-par-la-plateforme).
-La réponse n’est jamais mise en cache : elle porte `cache-control: no-store`.
-## Variables sensibles
-Une variable sensible n’est renvoyée qu’à une clé limitée au projet, celle que l’app GitHub pose dans le dépôt. Avec une clé d’organisation, elle est absente de la réponse.
-Chaque lecture d’une variable par une clé est consignée dans le journal du coffre, sans la valeur. Voir [Secrets et coffre](/docs/concepts/secrets-et-coffre/).
+`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
-| Statut | Code          | Cause                                          |
-| ------ | ------------- | ---------------------------------------------- |
-| `400`  | `bad_request` | Environnement inconnu                          |
-| `404`  | `not_found`   | Projet inconnu, ou hors de la portée de la clé |
-Voir la liste complète sur [Erreurs](/docs/reference/api/erreurs/).
----
-Source : /docs/concepts/deploiements/
-# Déploiements
-Un déploiement est une version figée de ton site. Il ne change plus après sa publication : une nouvelle version crée un nouveau déploiement, avec sa propre adresse.
-Cette page explique ce modèle. Pour les actions pas à pas, voir [Revenir en arrière, redéployer ou annuler](/docs/guides/revenir-en-arriere/).
-## Preview et production
+| 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 déploiement est soit une **preview**, soit une **production**.
-| Cible      | Créée par                                               | Servie sur                                                                                  |
-| ---------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| Preview    | `vercel deploy`, ou une branche autre que la production | Son adresse de déploiement, et les domaines de branche qui la suivent                       |
-| Production | `vercel deploy --prod`, ou la branche de production     | Son adresse de déploiement, l’adresse de production du projet et ses domaines de production |
-Avec l’intégration GitHub, la branche de production part en production, et toutes les autres en preview. Le dernier déploiement de production prêt est celui que servent tes domaines de production.
-## Adresse de production
-Chaque projet reçoit à sa création une adresse qui suit toujours sa production, de la forme `https://<projet>.hgdc.cloud`. C’est l’équivalent de `<projet>.vercel.app`.
-- Elle ne change jamais : ni à une nouvelle mise en production, ni si tu renommes le projet.
-- Elle sert le déploiement de production du moment. Une nouvelle production ou un retour arrière la déplace tout de suite, sans nouveau certificat ni réglage DNS.
-- Si `<projet>` est déjà pris par une autre organisation, l’adresse devient `<projet>-<organisation>.hgdc.cloud`. La console affiche celle de ton projet dans la carte de production, sous **Domaines**.
-- Elle n’est pas indexée par les moteurs de recherche. Pour un site public, branche ton propre domaine : voir [Brancher un domaine](/docs/guides/brancher-un-domaine/).
-Donne cette adresse à un outil qui doit toujours viser ta production : un proxy, une sonde de disponibilité, une console Docs. Elle est aussi la valeur de `VERCEL_PROJECT_PRODUCTION_URL` tant que le projet n’a pas de domaine.
-## Adresse de déploiement
-Chaque déploiement reçoit une adresse unique, de la forme `https://<projet>-<suffixe>.hgdc.cloud`. Elle reste valable tant que le déploiement existe.
-Partage cette adresse pour faire valider une version avant de la passer en production. Une preview se valide ainsi, sans toucher au site en ligne.
-## Statuts
-| Statut     | Libellé dans la console | Signification                                                                |
-| ---------- | ----------------------- | ---------------------------------------------------------------------------- |
-| `QUEUED`   | En file                 | Le déploiement attend son tour de publication                                |
-| `BUILDING` | Build en cours          | Le build tourne dans la CI, ou les fichiers sont en cours de publication     |
-| `READY`    | Prêt                    | Le site est en ligne sur son adresse                                         |
-| `ERROR`    | Erreur                  | Le build ou la publication a échoué. La cause est sur la page du déploiement |
-| `CANCELED` | Annulé                  | Annulé dans la console, ou dans GitHub Actions                               |
-Pour corriger une version en ligne, déploie une nouvelle version : elle reçoit son propre déploiement et sa propre adresse.
-## Vue d’ensemble du projet
-La vue d’ensemble montre le déploiement de production : un aperçu du site, son adresse, l’adresse de production du projet et ses domaines, le commit et son auteur. Le projet reprend le favicon de son site.
-Les previews actives listent la dernière adresse de chaque branche.
-## Revenir en arrière
-Revenir en arrière remet en ligne un déploiement de production précédent, tout de suite et sans nouveau build. L’adresse de production et les domaines le servent aussitôt. Seul un déploiement **prêt** peut passer en production.
-Le déploiement remis en ligne garde les variables qu’il a reçues à son build. Une variable modifiée depuis ne s’y applique pas.
-## Redéployer
-- Projet relié à GitHub : reconstruit le même commit, avec les variables d’aujourd’hui.
-- Projet envoyé par la CLI : republie les fichiers du déploiement choisi, sans rien reconstruire. Pour une nouvelle version, relance `vercel deploy`.
-## Annuler
-Un déploiement **en file** ou **en cours de build** peut être annulé. Un déploiement prêt ne s’annule pas : reviens en arrière à la place.
-## Logs de build
-La page de chaque déploiement affiche la sortie du build, en direct pendant le build avec l’intégration GitHub. Voir [Lire les logs](/docs/guides/lire-les-logs/).
----
-Source : /docs/concepts/organisations-et-roles/
-# Organisations et rôles
-Une organisation regroupe des personnes, des projets et des clés d’API. Tu peux appartenir à plusieurs organisations, et passer de l’une à l’autre depuis la barre latérale, ou avec `Ctrl+K`.
-L’organisation se crée et se gère dans Account. Son slug apparaît dans l’adresse de l’app : `host.hgdc.ch/o/<slug>/…`.
-## Rôles
-| Action                                                             | Propriétaire | Admin | Membre |
-| ------------------------------------------------------------------ | ------------ | ----- | ------ |
-| Voir les projets, déploiements et logs                             | Oui          | Oui   | Oui    |
-| Voir les noms des variables                                        | Oui          | Oui   | Oui    |
-| Voir les valeurs des variables non sensibles                       | Oui          | Oui   | Oui    |
-| Créer et déployer des projets, gérer les variables et les domaines | Oui          | Oui   | Oui    |
-| Créer et révoquer des clés d’API                                   | Oui          | Oui   | Non    |
-| Supprimer un projet                                                | Oui          | Oui   | Non    |
-| Gérer l’organisation elle-même, dans Account                       | Oui          | Non   | Non    |
-Une valeur sensible ne s’affiche jamais, quel que soit le rôle. Voir [Secrets et coffre](/docs/concepts/secrets-et-coffre/).
-Le rôle lecture seule n’existe plus : les anciens membres en lecture seule sont passés membres.
-## Inviter et retirer
-Les invitations, les membres et les rôles se gèrent dans Account, pas dans Host. Le guide pas à pas est sur [Inviter une personne](/docs/guides/inviter-une-personne/).
-Quand une personne rejoint l’organisation, elle se connecte avec son compte HGDC, avec la même adresse e-mail vérifiée. Son compte est lié, et ses projets restent en place.
-## Membres dans Host
-Host affiche la liste des membres en lecture seule, avec un bouton vers Account. Un changement fait dans Account arrive dans Host à la prochaine connexion de la personne. Une session dure 7 jours au plus, sans prolongation.
-## Quitter ou être retiré
-Quand une personne quitte l’organisation, les clés d’API qu’elle a créées cessent de fonctionner. Les projets, les déploiements et les variables restent dans l’organisation.
-## Les clés d’API et l’organisation
-Une clé d’API appartient à une organisation. L’organisation vient toujours de la clé : une option `--scope` ou `--team` de la CLI est ignorée. Voir [Clés d’API](/docs/guides/cle-d-api/).
+Chaque erreur porte aussi `error.message`, une phrase en français à montrer telle quelle.
 ---
-Source : /docs/concepts/secrets-et-coffre/
-# Secrets et coffre
+Source : /reference/mcp/
-Les valeurs de tes variables sont des secrets : mots de passe, clés de service, jetons. Host les garde dans un coffre, les chiffre, et ne les renvoie jamais en clair à quiconque n’en a pas besoin.
+# Serveur MCP
-Cette page explique le modèle. Pour les règles chiffrées, voir [Variables : référence](/docs/reference/variables/).
+Le serveur suit le [Model Context Protocol](https://modelcontextprotocol.io), transport Streamable HTTP, sans session : chaque requête est indépendante.
-## Le coffre
-- Chaque organisation a sa propre clé de chiffrement, AES-GCM 256 bits.
-- Cette clé est elle-même chiffrée par une clé maîtresse, gardée hors de la base de données.
-- Chaque valeur est liée à son projet. Une valeur recopiée dans un autre projet ne se déchiffre pas.
-## Qui lit quoi
-| Donnée                             | Qui la voit                                                          |
-| ---------------------------------- | -------------------------------------------------------------------- |
-| Nom d’une variable                 | Tous les membres de l’organisation                                   |
-| Valeur d’une variable non sensible | Tous les membres de l’organisation                                   |
-| Valeur d’une variable sensible     | Personne, après l’enregistrement. Elle peut seulement être remplacée |
+```text
+POST https://docs.hgdc.ch/mcp/<identifiant du projet>
+Content-Type: application/json
+Accept: application/json, text/event-stream
+```
-Une variable sensible ne part que vers le build du dépôt GitHub, par une clé limitée au projet. Un `vercel pull` depuis un poste de développement ne la télécharge pas.
+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`.
-## Le journal du coffre
+## Méthodes
-Le journal, en bas de l’onglet **Variables d’environnement**, garde les 50 derniers gestes sur le coffre :
+| 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.                         |
-- qui a créé, modifié ou supprimé une variable ;
-- qui a affiché une valeur non sensible ;
-- quelle clé d’API a téléchargé les variables, avec `vercel pull` ou un build ;
-- quand Doppler a synchronisé une valeur.
+Une notification (message sans `id`) reçoit un 202 sans corps.
-Le journal ne garde jamais une valeur.
+## Outils
-## Les clés d’API
+### search_docs
-Host ne garde qu’une empreinte SHA-256 de chaque clé d’API. La clé complète ne s’affiche qu’une fois, à sa création. Si tu la perds, aucune copie n’est possible : crée une nouvelle clé, puis révoque l’ancienne.
+| Paramètre | Type           | Rôle                              |
+| --------- | -------------- | --------------------------------- |
+| `query`   | texte          | Question ou mots-clés.            |
+| `limit`   | entier, 1 à 10 | Nombre de passages, 5 par défaut. |
-Une clé posée dans un dépôt GitHub ne donne accès qu’à son projet. Une clé d’organisation donne accès à tous les projets de l’organisation, avec les variables non sensibles.
+Rend les passages trouvés, chacun avec son titre, sa section, son adresse et son texte.
-## Les secrets des intégrations
+### get_page
-Les jetons Doppler et les secrets des webhooks sont chiffrés de la même façon, et ne sont jamais renvoyés par la console ni par l’API. Chaque webhook Doppler est vérifié par sa signature HMAC.
+| Paramètre | Type  | Rôle                                                             |
+| --------- | ----- | ---------------------------------------------------------------- |
+| `path`    | texte | Chemin de la page (`/guides/publier/`), ou son adresse complète. |
-## Ce que le site publie
+Rend la page en Markdown, précédée de son adresse.
-Le coffre protège les valeurs dans Host. Il ne protège pas un secret qui finit dans le site. Tout ce que le build écrit dans les fichiers du site est public, même si la variable d’origine était sensible.
+### list_pages
-Une variable lue dans le navigateur, comme celles qui commencent par `PUBLIC_`, `VITE_` ou `NEXT_PUBLIC_`, ne doit jamais contenir un secret.
+Sans paramètre. Rend la liste des pages publiées.
-## Voir aussi
+## Limites
-- [Gérer les variables d’environnement](/docs/guides/variables-d-environnement/)
-- [Synchroniser depuis Doppler](/docs/guides/synchroniser-doppler/)
-- [Confidentialité](/docs/concepts/confidentialite/)
+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 : /docs/concepts/preversion/
-# Préversion et rendu à la demande
-Host sert toujours les fichiers statiques et les pages pré-rendues. Les fonctions, c’est-à-dire le rendu à la demande, les routes d’API, les Server Actions, le proxy, le runtime edge, l’ISR et les crons, sont en préversion. Cette page explique comment elles se comportent, et ce que tu observes.
-## Ce qui est en ligne dans tous les cas
-Un site construit avec `vercel build` produit deux sortes de contenu :
-- les fichiers statiques et les pages pré-rendues au build. Ils sont servis dès le déploiement, sans fonction ;
-- les pages et les routes qui ont besoin d’une fonction. Elles passent par l’exécution en préversion.
-Une organisation qui n’a pas encore accès à l’exécution des fonctions voit ses pages statiques en ligne normalement. Seule une adresse qui demande une fonction répond `501`, avec le message « Rendu à la demande pas encore servi ».
+Source : /explications/fonctionnement/
-## Ouvert organisation par organisation
+# Comment ça marche
-L’exécution des fonctions est ouverte organisation par organisation. Si une de tes adresses répond `501`, demande l’activation à <support@hgdc.ch>, avec le nom de ton organisation.
+Docs tient en trois pièces : un modèle de site, Host qui le publie, et la console qui l’indexe pour l’assistant.
-## Comportement des fonctions
+## 1. Le modèle de site
-- Chaque déploiement a son environnement d’exécution, isolé des autres, avec les variables de son environnement.
-- Une fonction dispose de 512 Mo de mémoire par défaut, et de 1 Go au plus.
-- Une requête dure 30 secondes au plus par défaut. Tu peux allonger jusqu’à 60 secondes avec `maxDuration`.
-- Après une période sans trafic, l’environnement s’arrête. La première requête suivante prend quelques secondes ; les suivantes sont immédiates.
+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.
-## Runtime edge
+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.
-Une fonction marquée `runtime: "edge"` tourne dans un contexte isolé, avec les API Web, comme chez Vercel.
+## 2. La publication par Host
-## ISR
+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.
-Une page avec une durée de revalidation est rendue une fois, puis gardée. Une fois la durée écoulée, elle est régénérée en arrière-plan. Le visiteur reçoit toujours une réponse immédiate.
+## 3. L’indexation par la console
-Le cache de l’ISR est tenu en mémoire par serveur. Il repart à vide quand le serveur redémarre : la page suivante est rendue à nouveau.
+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 :
-## Crons
+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.
-Les `crons` de `vercel.json` appellent leur chemin en GET, à l’heure indiquée en UTC, sur le déploiement de production uniquement. Un déploiement de preview n’a jamais de cron.
+Un build identique au précédent ne change rien à l’index.
-Si tu définis la variable `CRON_SECRET` pour la production, chaque appel porte `Authorization: Bearer <CRON_SECRET>`. Vérifie cet en-tête dans ta route avant d’agir.
+## 4. La réponse
-## Proxy et middleware
+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.
-Le proxy, anciennement middleware, et le middleware Node.js s’exécutent en préversion, comme les fonctions.
-## Pour une page qui ne peut pas attendre
-Si une page a besoin d’une fonction alors que l’exécution n’est pas encore ouverte à ton organisation, tu peux la pré-rendre au build. Elle est alors servie comme une page statique.
-## Voir aussi
-- [Compatibilité](/docs/reference/compatibilite/) : la liste complète, fonction par fonction.
-- [Limites](/docs/reference/limites/) : mémoire, durée et débits.
+> **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 : /docs/concepts/confidentialite/
-# Sécurité et confidentialité
-Cette page décrit ce que Host fait pour protéger tes projets, tes secrets, les sites qu’il sert et les visiteurs de ces sites. Elle ne remplace pas ton analyse de risque. Pour une question précise sur le traitement de tes données personnelles, écris à <support@hgdc.ch>.
+Source : /explications/donnees/
-## Accès
+# Données et confidentialité
-- La connexion passe uniquement par HGDC. Host ne garde aucun mot de passe.
-- Chaque action vérifie ton rôle dans l’organisation : propriétaire, admin ou membre. Voir [Organisations et rôles](/docs/concepts/organisations-et-roles/).
-- Une clé d’API ne donne accès qu’à une organisation. Une clé posée dans un dépôt ne donne accès qu’à son projet.
-- Les dépôts GitHub ne s’importent que si tu as le droit d’écriture. L’app GitHub ne demande que les droits dont le workflow a besoin.
+## Ce qui est stocké
-## Secrets
+| 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 |
-- Les valeurs des variables sont chiffrées dans un coffre. Chaque organisation a sa propre clé. Voir [Secrets et coffre](/docs/concepts/secrets-et-coffre/).
-- Les clés d’API ne sont stockées que sous forme d’empreinte SHA-256. La clé complète ne s’affiche qu’une fois.
-- Une variable sensible ne se relit jamais après l’enregistrement, et ne part que vers le build du dépôt.
-- Le journal du coffre garde qui a créé, modifié, lu ou téléchargé une variable. Il ne garde jamais la valeur.
+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 et par jour.
-## Sites servis
+## Qui traite quoi
-- HTTPS partout, avec un certificat automatique pour chaque domaine vérifié. Un certificat n’est émis que pour un domaine vérifié.
-- Chaque réponse porte l’en-tête `X-Content-Type-Options: nosniff`.
-- Les fichiers cachés, comme `.env` ou `.git`, ne sont jamais servis, sauf `.well-known`.
-- Les configurations et les sources d’un framework ne sont jamais servies. Seul le résultat du build l’est.
+- **Le site** est servi par 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.
-## Données et journaux
+Sans clé d’embeddings, la recherche de l’assistant reste en plein texte : rien ne part chez Mistral.
-- Les logs des requêtes ne gardent ni adresse IP, ni en-têtes, ni paramètres d’URL. Ils disparaissent après trois jours.
-- Les logs de build restent tant que le projet existe.
-- Les valeurs des variables ne figurent dans aucun journal.
+## Ce que voit l’assistant
-## Signaler une faille
+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.
-Tu penses avoir trouvé une faille ? Écris à <support@hgdc.ch>, avec les étapes pour la reproduire. Pour rester dans le cadre de la divulgation responsable :
+## Supprimer
-- n’accède pas aux données d’une autre organisation, même pour démontrer la faille ;
-- ne teste pas la charge de la plateforme ;
-- ne publie pas la faille avant qu’elle soit corrigée.
+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.