> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snakysec.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS

# Documentation project instructions — SnakySec

Ces instructions sont lues par les AI tools (Claude Code, Cursor, Windsurf) qui
contribuent à cette documentation. Pour la connaissance Mintlify (composants,
syntaxe, configuration), installer le skill officiel :

```bash theme={null}
npx skills add https://mintlify.com/docs
```

## À propos de ce projet

* Site Mintlify v4 (`docs.json`, pas `mint.json`).
* Pages MDX avec frontmatter YAML (`title`, `description`, `icon`).
* 83 fichiers `.md` existants couvrent : architecture, ADR, conventions, DR
  policy + runbooks restore + incident response + compliance, runbooks ops,
  catalogs, project state.
* Lancer `mint dev` dans `docs/` pour preview locale.
* Lancer `mint broken-links` avant de push.

## Audiences (à garder en tête en écrivant)

| Audience               | Profil                     | Format préféré                              |
| ---------------------- | -------------------------- | ------------------------------------------- |
| **Admins MSSP**        | Opérateurs/devops SnakySec | Runbooks step-by-step, procédures concrètes |
| **Analystes**          | Reviewers manuels d'audits | Catalogs + procédures de review             |
| **Auditeurs externes** | ISO 27001 / NIS2 / ANSSI   | Policies formelles, mappings, preuves       |
| **Clients PME (DSI)**  | Non-experts cyber          | Onboarding clair, pas de jargon             |
| **Devs**               | Contributeurs code         | Architecture, ADR, conventions              |

Ne pas optimiser pour un développeur pro quand l'audience est un DSI PME.

## Glossaire canonique (NON-NÉGOCIABLE)

Source de vérité : [`docs/conventions/glossary.md`](conventions/glossary.md). Linter CI
(`platform/scripts/check-i18n-vocabulary.mjs`) bloque les variantes dépréciées.

| FR canonique                              | EN canonique              | À éviter                                          |
| ----------------------------------------- | ------------------------- | ------------------------------------------------- |
| **Écart**                                 | **Finding**               | « non-conformité » (FR), « issue » (FR/EN ambigu) |
| **Lancer** un audit                       | **Run** an audit          | « Trigger » (FR), « Démarrer » (FR pour audits)   |
| **Conforme** / Non-conforme               | Compliant / Non-compliant | « Pass/Fail », « OK/KO »                          |
| **Audit**                                 | Audit                     | « Scan », « Assessment »                          |
| **Contrôle**                              | Control                   | « Check », « Test »                               |
| **Rapport de suivi** vs **certification** | Tracking vs Certification | « Live report » seul                              |

Voir le glossaire complet pour les \~30 termes (sévérité, statuts, rôles, etc.).

## Style preferences

* **Voix active**, deuxième personne (« tu » en FR, « you » en EN).
* **Phrases courtes**, une idée par phrase.
* **Headings** en sentence case (`## Mise en route`, pas `## Mise En Route`).
* **Bold** pour les éléments UI : Cliquer **Settings**.
* **Code formatting** pour fichiers, commandes, paths : `mint dev`, `docs.json`.
* **Pas de jargon non-explicité** : si tu utilises « WAL », précise « Write-Ahead Log »
  la première fois.
* **No em dashes** (`—`) en abusant : préfère virgules ou points pour le rythme.
* **Pas d'AI-vocab** : « delve », « crucial », « robust », « comprehensive » à éviter.
* Ton : **consultant senior**, pas commercial. On respecte le temps du lecteur.

## Composants Mintlify préférés

<table>
  <tr><th>Pour</th><th>Composant</th></tr>
  <tr><td>Page d'accueil</td><td>`<Card>`, `<CardGroup>`, `<Columns cols={2}>`</td></tr>
  <tr><td>Procédure step-by-step</td><td>`<Steps>` + `<Step title="...">`</td></tr>
  <tr><td>Avertissement important</td><td>`<Warning>`</td></tr>
  <tr><td>Astuce optionnelle</td><td>`<Tip>`</td></tr>
  <tr><td>Note explicative</td><td>`<Note>`</td></tr>
  <tr><td>Schéma ASCII</td><td>`<Frame>` autour d'un code block</td></tr>
  <tr><td>Choix langage</td><td>`<Tabs>` + `<Tab title="...">`</td></tr>
</table>

**Ne pas surcharger** : 2-3 callouts par page max. Trop de Note/Tip/Warning =
bruit visuel et perte d'attention.

## Frontmatter standard

```yaml theme={null}
---
title: "Titre court explicite"
description: "Une phrase qui résume le contenu — visible dans Google + sidebar."
icon: "shield-halved"  # FontAwesome solid ou Lucide
---
```

Icônes : préférer `shield-halved` (DR), `book` (runbook), `wrench` (ops),
`scale-balanced` (compliance), `rocket` (quickstart), `gear` (settings).

## Content boundaries

* **Pas de secrets** dans la doc : pas de tokens, certificats, clés Vault.
  Renvoie vers le path Vault ou le runbook bootstrap-secrets.
* **Pas d'instructions internes confidentielles** : on est en doc publique
  (HTTPS, indexée Google). Si c'est sensible, mets-le dans
  [docs/\_archive/](_archive/) (excluded by default).
* **Pas de noms de clients réels** dans les exemples : utilise « Acme PME »,
  « Tenant de référence SnakySec » (le seul publié), ou des placeholders.
* **Liens externes** : préfère `https://snakysec.com/...` quand c'est notre
  contenu, pas une release GitLab privée.

## Workflow de contribution

1. **Branche feature** : `docs/<scope-court>` (ex : `docs/dr-runbook-ransomware`)
2. **Éditer + preview** : `mint dev` en parallèle de l'IDE
3. **Vérifier** : `mint broken-links` → 0 broken
4. **Linter glossaire** : `cd platform && npm run i18n:vocab` (couvre aussi les
   `.md` de la doc dans certains scénarios — à vérifier au cas par cas)
5. **Commit** : `docs(<scope>): <résumé court>` (conventional-commits)
6. **MR sur `main`** : Mintlify déclenche un build automatique au merge

## Référence

* Glossaire produit : [`docs/conventions/glossary.md`](conventions/glossary.md)
* Conventions i18n : [`docs/conventions/i18n.md`](conventions/i18n.md)
* Patterns UI plateforme : [`docs/conventions/ui-patterns.md`](conventions/ui-patterns.md)
* Mintlify components : [https://mintlify.com/docs/components](https://mintlify.com/docs/components)
* Mintlify writing standards : [https://mintlify.com/docs/writing](https://mintlify.com/docs/writing)