Livre blanc — RAG natif IA par fichiers Markdown

Une base de connaissance légère, performante et économe en tokens, sans MCP ni service externe

Version du document : 1.0
Date : juillet 2026
Auteur : Jean-Luc ANTOINE
Statut : publiable — production-ready
Spécification canonique de référence : rag.md (cahier des charges)
Licence d'usage : libre — adaptable à tout environnement d'IA en ligne de commande.

Sommaire

Partie I — Contexte et motivation

• Résumé exécutif
• - Le problème : le coût caché du RAG via MCP / Confluence
• - La proposition : un RAG « natif IA » par fichiers
• Partie II — Principes et architecture
• Cinq principes directeurs
• - Vue d'ensemble du système
• - Les cinq composants
• Partie III — Spécification technique
• Le marqueur d'activation .rag
• - Arborescence thématique et conventions de nommage
• - Format des documents .md (frontmatter)
• - Stratégie d'économie de tokens
• - Les index dérivés (OVERVIEW, INDEX, RELATIONS)
• Partie IV — Le protocole de requête
• Divulgation progressive : le cœur du système
• Partie V — Cycle de vie de la connaissance
• Initialisation depuis le code (/rag-init)
• - Synchronisation et détection de dérive (/rag-update)
• - Règles de maintenance
• - Validation et conformité (/rag-check)
• Partie VI — Propriétés non-fonctionnelles
• Scalabilité
• - Sécurité et confidentialité
• - Performance
• Partie VII — Comparatif
• RAG file-based vs MCP/Confluence : analyse comparative
• Partie VIII — Guide de mise en œuvre
• Démarrage en 10 minutes
• - Intégration native IA (skills, commandes, prompt système)
• - Déploiement et travail collaboratif
• Partie IX — Annexes techniques complètes
• Annexe A — Cahier des charges canonique (rag.md)
• - Annexe B — Skill rag (intégrale)
• - Annexe C — Skill rag-sync (intégrale)
• - Annexe D — Les quatre commandes (intégrales)
• - Annexe E — Pointeur AGENTS.md (intégrale)
• - Annexe F — Exemple complet commenté
• Partie X — Clôture
• FAQ
• - Cas d'usage typiques
• - Roadmap et extensions possibles
• - Glossaire
• - Checklist de mise en production
• ---

Partie I — Contexte et motivation

1. Résumé exécutif

Les assistants IA en ligne de commande (CLI) ont besoin d'accéder à la connaissance projet pour travailler efficacement : architecture, règles fonctionnelles, conventions, sécurité, ergonomie, etc. Aujourd'hui, ce besoin est le plus souvent satisfait par un MCP (Model Context Protocol) connecté à un outil externe comme Confluence, Notion ou un wiki d'entreprise.

Cette approche fonctionne, mais elle s'avère coûteuse à plusieurs titres : latence réseau à chaque requête, surconsommation de tokens due aux payloads JSON volumineux, dépendance à un service à déployer et maintenir, et surtout dérive permanente entre la documentation et le code réellement implémenté.

Ce livre blanc présente une approche radicale et simple : faire vivre la base de connaissance directement sous forme de fichiers Markdown, à côté du code source, sans aucun runtime, aucun service externe, aucun MCP. Conçue dès l'origine pour les assistants IA, cette architecture mise sur trois leviers :

• La divulgation progressive — l'IA ne lit jamais toute la base. Elle progresse par niveaux de coût croissant : un manifeste compact, puis les métadonnées seules, puis le corps ciblé, et enfin la navigation de proche en proche. Elle s'arrête dès qu'elle a sa réponse.
• - Le lien explicite documentation ↔ code — chaque document référence les fichiers de code qu'il décrit (impl_refs), ce qui permet de détecter la dérive et de garder la connaissance fidèle à la réalité.
• - L'intégration native par compétences (skills) — les IA CLI consomment la base via des skills chargés contextuellement, des commandes explicites et un prompt système minimal. Aucune glue applicative.
• Le résultat est un système léger, performant, scalable et économe en tokens, où la documentation est enfin traitée comme du code : versionnée, vérifiable, maintenue à chaque évolution.

2. Le problème : le coût caché du RAG via MCP / Confluence

2.1 Le scénario dominant

Pour qu'un assistant IA en CLI « connaisse » le projet sur lequel il travaille, on déploie typiquement l'architecture suivante :

IA CLI  ──MCP──►  Serveur MCP  ──API──►  Confluence / Notion / Wiki
                      (glue applicative)

Le serveur MCP joue le rôle d'adaptateur : il traduit les requêtes de l'IA en appels d'API vers l'outil de documentation, et sérialise les résultats en JSON. Cette pile apporte de la flexibilité, mais aussi quatre catégories de coûts.

2.2 Les quatre coûts cachés

Coût 1 — Latence

Chaque recherche entraîne un aller-retour réseau et une sérialisation/désérialisation MCP. Sur une session de travail où l'IA consulte la base plusieurs fois, ces latences s'accumulent et dégradent l'expérience (temps d'attente, sensation de lenteur).

Coût 2 — Consommation de tokens

Les réponses MCP sont des objets JSON contenant le contenu utile, mais aussi des métadonnées de transport (structure, identifiants, versions, ancres) souvent volumineuses. Une page Confluence complète, une fois sérialisée, consomme facilement plusieurs milliers de tokens — alors que l'IA n'avait peut-être besoin que d'un fragment. À l'échelle d'une session, c'est un gaspillage direct d'argent et de fenêtre de contexte.

Coût 3 — Dépendance opérationnelle

Un MCP doit être :

• déployé (un processus ou un service à faire tourner) ;
• - authentifié (credentials, jetons, rotation) ;
• - maintenu (mises à jour de l'outil source, breaking changes d'API) ;
• - disponible (s'il tombe, l'IA perd l'accès à la connaissance).
• C'est une pièce d'infrastructure supplémentaire à faire vivre.

Coût 4 — La dérive (le plus insidieux)

C'est le coût le plus dangereux, car invisible. La documentation vit dans Confluence ; le code vit dans git. Rien ne les lie structurellement. Au fil des évolutions :

• on modifie le code sans toucher au wiki ;
• - on documente un comportement qui n'existe plus ;
• - l'IA s'appuie sur une connaissance périmée et produit des résultats faux.
• Cette dérive ne se détecte pas facilement, et son impact — des recommandations IA incorrectes — est difficile à attribuer.

2.3 Ce que cela signifie en pratique

Une équipe déploie un MCP Confluence pour son IA. Au bout de six mois : la base est partiellement obsolète, les requêtes sont lentes, les coûts d'inférence ont augmenté, et personne n'est sûr que la doc reflète le code. Le RAG « existe » mais ne « sert » plus vraiment.

3. La proposition : un RAG « natif IA » par fichiers

L'idée est d'abandonner l'architecture « IA → MCP → service externe » au profit d'une architecture plate :

IA CLI  ──lectures de fichiers──►  base de connaissance Markdown (.md)
                                        (à côté du code source)

La base de connaissance vit dans le dépôt (ou sur une unité réseau), se lit comme n'importe quel fichier, et est conçue dès l'origine pour minimiser la latence et la consommation de tokens.

3.1 Trois piliers

3.2 Ce que le système N'EST PAS

Pour fixer les attentes, il est important de préciser ce qui est hors périmètre :

• Pas un moteur de recherche vectoriel. Il n'y a pas d'embeddings ni de similarité sémantique. La recherche est déterministe (manifeste + graphe de relations), ce qui la rend contrôlable en tokens et prévisible.
• Pas un service déployé. Rien à installer, rien à faire tourner, rien à authentifier côté RAG.
• Pas une solution de synchronisation réseau. Le partage/réplication est délégué aux outils existants (git, Syncthing, kdrive, lecteurs réseau). Le système est agnostique au stockage.
• Pas un contrôle d'accès. La sécurité du contenu est portée par le système de fichiers ou l'outil de sync.

3.3 Pourquoi cela fonctionne mieux pour les IA CLI

Les assistants IA en CLI disposent déjà d'outils de lecture de fichiers, de recherche (grep) et de glob. Le RAG file-based exploite exactement ces outils natifs au lieu d'en ajouter de nouveaux. La connaissance n'est pas « derrière une API », elle est dans l'espace de travail, au même titre que le code — ce qui est aussi l'endroit le plus naturel pour qu'elle soit maintenue à jour.

Partie II — Principes et architecture

4. Cinq principes directeurs

Ces principes guident chaque décision de conception. Ils doivent être compris avant d'aborder la spécification technique.

Principe 1 — La source de vérité, ce sont les fichiers .md

Les fichiers Markdown sont la source. Les index (INDEX.md, RELATIONS.yaml, OVERVIEW.md) sont des artéfacts dérivés : toujours régénérables, jamais source d'autorité.
Conséquence majeure : un humain peut éditer n'importe quel .md librement, n'importe quand. Une régénération réconcilie les index. La base « s'auto-guérit ».

Principe 2 — Divulgation progressive (progressive disclosure)

L'IA ne lit jamais tout. Hiérarchie de coût croissant :
manifeste → frontmatter → corps ciblé → corps complet → navigation de proche en proche.
Chaque niveau permet de décider si le suivant est nécessaire. C'est le cœur de l'économie de tokens.

Principe 3 — Convention plutôt que configuration

Les noms, l'arborescence et le frontmatter encodent la structure et la navigation. Il y a très peu de configuration à faire. On devine la structure en lisant les fichiers.

Principe 4 — Outil-agnostique

La norme ne dépend d'aucun outil d'IA. Les IA CLI adoptent le protocole de requête via un skill ou un prompt ; les bindings spécifiques (ex. Kilo) sont un exemple d'intégration parmi d'autres.

Principe 5 — Connaissances vivantes

Toute évolution du code entraîne la mise à jour des .md concernés. La documentation n'est pas un livrable ponctuel : c'est un artéfact vivant, maintenu au fil de l'eau comme le code.

5. Vue d'ensemble du système

        ┌─────────────────────────────────────────────────────────────┐
        │  Dépôt / Unité réseau (stockage, hors scope)                │
        │                                                             │
        │  .rag ────────────────► pointe vers la racine RAG           │ ◀ marqueur
        │  code source (les impl_refs pointent ici)                     │   (présence = actif)
        │                                                             │
        │  docs-rag/                          ◀ racine de la base      │
        │   ├─ OVERVIEW.md    (arbre des thèmes — dérivé)             │
        │   ├─ INDEX.md       (manifeste compact — dérivé)            │
        │   ├─ RELATIONS.yaml (graphe bidirectionnel — dérivé)        │
        │   ├─ perimetre-fonctionnel/                                 │
        │   │   └─ authentification/                                  │
        │   │       ├─ login.md     ┐                                 │
        │   │       └─ session.md   │ contenus source                 │
        │   └─ securite/            │ (frontmatter + corps + liens)   │
        │       └─ mfa.md           ┘                                 │
        └─────────────────────────────────────────────────────────────┘

Lecture du schéma :

• À la racine du dépôt, un fichier .rag (marqueur) indique que le système est actif et pointe vers la racine de la base.
• - Le code source coexiste avec la base ; les documents y font référence via impl_refs.
• - La racine de la base (docs-rag/) contient trois fichiers dérivés en surface, puis une arborescence de thèmes (répertoires) contenant les documents (.md).
• ---

6. Les cinq composants

Partie III — Spécification technique

7. Le marqueur d'activation .rag

7.1 Rôle

Un fichier nommé .rag placé à la racine du dépôt (ou du workspace) indique qu'un RAG est actif et donne la racine de la base de connaissance.

Règle absolue : si .rag est absent, aucune logique RAG ne s'applique. Les IA ignorent totalement le système. Cela permet d'activer/désactiver le RAG simplement en ajoutant ou supprimant un fichier.

7.2 Format (YAML)

# .rag — activateur et configuration du RAG file-based
version: "1"                 # version de la norme utilisée
root: ./docs-rag             # chemin de la racine RAG (relatif au fichier .rag, ou absolu)
lang: fr                     # langue par défaut des documents (surchargeable par document)
index:                       # noms des fichiers d'index dérivés (valeurs par défaut montrées)
  manifest: INDEX.md
  relations: RELATIONS.yaml
  overview: OVERVIEW.md
summary_max: 240             # longueur max conseillée du champ summary (caractères)
check_on_update: true        # exécuter la validation (§16) après chaque update

Tous les champs sauf version et root sont optionnels (valeurs par défaut ci-dessus).

7.3 Résolution de la racine

• root relatif : résolu par rapport au répertoire contenant .rag.
• root absolu : utilisé tel quel (utile pour une unité réseau montée).
• La racine doit exister ; sinon le RAG est considéré « non initialisé » → exécuter l'initialisation (§13).

8. Arborescence thématique et conventions de nommage

8.1 Thèmes > sous-thèmes > documents

L'arborescence reflète une classification hiérarchique par thèmes :

• Les répertoires de premier niveau = thèmes généraux (ex. perimetre-fonctionnel, ergonomie, securite, performance, architecture, exploitation…).
• > Ces thèmes ne sont pas prédéfinis : ils dépendent du contexte du projet. La procédure d'initialisation les déduit du code et des conventions du dépôt.
• Les sous-répertoires = sous-thèmes du thème parent (récursif, profondeur libre mais ≤ 3 recommandée).
• - Chaque répertoire contient des fichiers .md traitant de la thématique.

• 8.2 Conventions de nommage (strictes)

Slugification (à la création) :

"Authentification 2FA" → "authentification-2fa"
"Gestion des accès"    → "gestion-des-acces"
"API_Utilisateur"      → "api-utilisateur"

Pourquoi cette rigueur ? Des noms normalisés garantissent des chemins stables, prévisibles et sans surprise (pas d'échappement d'espaces, pas de sensibilité à la casse selon l'OS, pas de problèmes d'encodage). C'est la base d'un système multiplateforme et durable.

8.3 Fichiers système réservés (à la racine RAG)

Noms réservés, auto-générés (ne pas créer de document thématique avec ces noms) :

• OVERVIEW.md — arbre des thèmes + statistiques (§11.1).
• - INDEX.md — manifeste compact (§11.2).
• - RELATIONS.yaml — graphe de relations (§11.3).
• Tout fichier/dossier préfixé _ (ex. _drafts/) est ignoré par l'indexation (zone de brouillon).

9. Format des documents .md

9.1 Anatomie

Un document = un frontmatter YAML délimité par ---, suivi d'un corps Markdown.

---
title: "Authentification par login"
summary: "Flux de connexion utilisateur par identifiant/mot de passe, avec MFA optionnel et verrouillage après N échecs."
type: feature
status: stable
tags: [auth, login, mot-de-passe, mfa]
audience: [dev, po]
impl_refs: [src/auth/login.ts, src/auth/login.service.ts]
related: [securite/mfa.md]
created: 2026-07-01
updated: 2026-07-01
owners: [equipe-auth]
version: "1.2"
priority: p1
---

# Authentification par login

## Périmètre
Le module couvre la connexion... Voir aussi [MFA](../securite/mfa.md).

## Parcours
1. Saisie identifiant/mot de passe ...

9.2 Schéma du frontmatter

L'identifiant canonique d'un document est son chemin relatif depuis la racine RAG (ex. securite/mfa.md). Il n'y a pas de champ id séparé : le chemin est non-ambigu et stable.

9.3 Corps du document

• Titres hiérarchiques (#, ##, ###) : structurent le document et permettent à l'IA de cibler une section (lecture par offset/recherche) plutôt que le corps entier — un autre levier d'économie de tokens.
• Hyperliens inter-documents en chemins relatifs : [texte](../securite/mfa.md). Les relations sont extraites de ces liens (§11.3).
• Longueur cible : un document = un sujet. Si > ~300 lignes, envisager un sous-dossier ou scinder le document (cela améliore la granularité de la divulgation progressive).

10. Stratégie d'économie de tokens

Cette section mérite d'être isolée car elle est la raison d'être du système.

10.1 Le principe directeur

Les métadonnées doivent suffire à décider de lire ou non le corps.

10.2 Comment chaque champ contribue

• summary : la « publicité » du document. Doit contenir le quoi et le périmètre. Contrainte stricte de longueur pour garantir la compacité du manifeste.
• type + tags + audience : permettent un filtrage déterministe côté IA (pas de lecture sémantique coûteuse). L'IA peut écarter une dizaine de documents en lisant une seule table.
• status : needs-review/deprecated signalent une connaissance potentiellement caduque → l'IA l'évite ou prévient l'utilisateur.
• impl_refs : permettent à l'IA de vérifier directement le code plutôt que de se fier à un doc potentiellement dérivé.

10.3 Le budget

Budget indicatif par document lu en phase 2 (frontmatter seul) : ~150–400 tokens, vs plusieurs milliers pour un corps complet.
Sur une requête typique :

• Phase 1 (manifeste) : ~1 ligne par document, soit quelques centaines de tokens pour toute la base.
• - Phase 2 (frontmatters filtrés) : ~150–400 tokens par candidat retenu.
• - Phase 3 (corps) : uniquement pour 1–2 documents pertinents.
• Comparé à un MCP qui renverrait des pages complètes en JSON, le gain est d'un ordre de grandeur.

11. Les index dérivés

Tous trois sont régénérés automatiquement. Ils portent l'en-tête > Auto-généré — NE PAS ÉDITER.

11.1 OVERVIEW.md — arbre des thèmes

Vue d'ensemble de l'arborescence + compteurs. Sert de carte en tête de requête.

# OVERVIEW — Carte de la base de connaissance
> Auto-généré — NE PAS ÉDITER. Généré le 2026-07-01. Documents : 12.

perimetre-fonctionnel (5)
  authentification (2)
    login.md
    session.md
  ...
securite (4)
  mfa.md
  ...

11.2 INDEX.md — manifeste compact

Une ligne par document, format tabulaire. C'est le fichier lu en phase 1 de toute requête. Tri déterministe (par chemin) pour des diffs propres.

# INDEX — Manifeste
> Auto-généré — NE PAS ÉDITER. Généré le 2026-07-01. Documents : 12.

| chemin | type | statut | prio | tags | résumé |
|---|---|---|---|---|---|
| perimetre-fonctionnel/authentification/login.md | feature | stable | p1 | auth,login,mfa | Flux de connexion par identifiant/mot de passe, MFA optionnel, verrouillage après N échecs. |
| perimetre-fonctionnel/authentification/session.md | feature | stable | p1 | auth,session | Gestion de session : création, durée, révocation, rotation. |
| securite/mfa.md | concept | stable | p0 | securite,mfa,2fa | Second facteur TOTP/matériel ; enrollment et vérification. |

Scalabilité : au-delà de ~500 documents, le manifeste est shardé par thème de premier niveau (perimetre-fonctionnel/INDEX.md, etc.) et INDEX.md racine devient un sommaire pointant vers les shards. Le protocole de requête reste identique (phase 1 → manifeste racine → shard pertinent). Voir §17.

11.3 RELATIONS.yaml — graphe bidirectionnel

Adjacence dans les deux sens (navigation de proche en proche sans relire les corps).

# Auto-généré — NE PAS ÉDITER.
version: "1"
generated: "2026-07-01T19:46:00+02:00"
nodes:
  perimetre-fonctionnel/authentification/login.md:
    links: [securite/mfa.md, perimetre-fonctionnel/authentification/session.md]
    related: [securite/mfa.md]
    linked_by: [securite/mfa.md]
  securite/mfa.md:
    links: [perimetre-fonctionnel/authentification/login.md]
    linked_by: [perimetre-fonctionnel/authentification/login.md]

• links = hyperliens extraits du corps.
• related = champ frontmatter related.
• linked_by = pré-calcul inverse (quels documents pointent vers celui-ci).

11.4 Auto-guérison

Les index sont recalculés à partir des .md réels à chaque initialisation ou mise à jour. Toute édition humaine (ajout/retrait de lien, renommage, suppression) est réconciliée.
Règle de cohérence des relations : si un document ne contient plus d'hyperlien (ni related) vers une cible, l'arête correspondante disparaît du graphe à la régénération. Cela répond directement au besoin exprimé : « si on supprime un hyperlien et qu'il n'y a plus d'autres hyperliens vers cette cible, on supprime l'entrée de l'index ».

Partie IV — Le protocole de requête

12. Divulgation progressive : le cœur du système

C'est le cœur de l'économie de tokens. L'IA doit suivre ces phases, en s'arrêtant dès qu'elle dispose de la réponse.

Règles d'application

• Ne jamais lire l'intégralité de la base.
• Préférer une recherche/grep bornée au chargement complet de fichiers longs.
• Si le status est needs-review ou deprecated, vérifier impl_refs contre le code avant de s'y fier.
• En cas d'absence de résultat en phase 1/2, élargir via OVERVIEW.md puis RELATIONS.yaml.

Exemple mental de requête

Question : « Comment fonctionne le verrouillage de compte après échecs de login ? »

• - - Phase 0 : .rag présent → racine docs-rag/.
• - - Phase 1 : INDEX.md → la ligne login.md (tags auth,login,mfa, résumé mentionnant « verrouillage après N échecs ») est un candidat évident.
• - - Phase 2 : frontmatter de login.md → confirme type: feature, status: stable. Pertinent.
• - - Phase 3 : on lit la section ## Sécurité uniquement → réponse trouvée (« Verrouillage après 5 échecs consécutifs »).
• - - Stop. On a lu le manifeste + un frontmatter + une section. Coût minimal.

Partie V — Cycle de vie de la connaissance

13. Initialisation depuis le code (/rag-init)

Objectif : produire une base de connaissance reflétant ce qui est réellement implémenté.

Procédure

• Cadrage : déterminer/valider la racine RAG (créer .rag si besoin, avec root).
• Scan du code : arborescence des sources, points d'entrée, modules, endpoints, schémas, tests, configs, README/AGENTS.md.
• Déduction des thèmes de premier niveau puis sous-thèmes (à partir du découpage fonctionnel, des dossiers, des responsabilités).
• Génération d'un squelette de .md par unité de connaissance, avec frontmatter pré-rempli (type, tags, impl_refs pointant vers les fichiers réels, status: draft).
• Démoulage d'un premier contenu (résumé, périmètre, parcours) à partir du code + commentaires + README.
• Régénération de OVERVIEW.md, INDEX.md, RELATIONS.yaml.
• status: draft tant qu'un humain n'a pas validé.

Le principe clé : on ne fabrique pas de comportements non présents dans le code. L'initialisation reflète la réalité, elle n'invente pas.

14. Synchronisation et détection de dérive (/rag-update)

14.1 Mise à jour (après une évolution)

• Détecter les changements depuis la dernière sync (via git, mtimes, ou périmètre fourni en argument).
• Pour chaque .md impacté (via impl_refs chevauchant les fichiers modifiés) :

• mettre à jour le contenu + impl_refs + updated ;

• passer status: needs-review si le code a divergé et qu'une vérification humaine est requise.
• Créer les .md manquants pour de nouvelles fonctionnalités (status: draft).
• Marquer status: deprecated/archived ce qui a été supprimé (ne pas effacer l'historique sémantique sans confirmation).
• Régénérer les index dérivés.
• Si check_on_update: true, exécuter la validation (§16).

14.2 Détection de dérive (drift)

C'est la réponse directe au coût n°4 identifié en §2.2.

• impl_refs + git log/git diff/hash de fichier permettent de savoir si un doc est en retard sur le code.
• - Un doc dont un impl_ref a été supprimé/renommé → status: needs-review + avertissement.
• - La validation signale les docs potentiellement stalé.

• Bénéfice : la dérive, invisible dans une architecture MCP/Confluence, devient détectable et signalée ici. L'IA ne s'appuie jamais à l'aveugle sur une connaissance périmée.

15. Règles de maintenance

• Obligation : à chaque évolution ou développement, mettre à jour les .md concernés avant de clôturer la tâche. Les index sont régénérés en conséquence.
• Édition humaine tolérée et encouragée : les .md sont la source de vérité ; une régénération réconcilie toujours les index.
• Cohérence des relations : l'ajout d'un hyperlien crée une arête à la prochaine régénération ; la suppression du dernier hyperlien (et related) vers une cible supprime l'arête.
• Renommage/déplacement : créer le nouveau .md, mettre à jour les liens pointant vers l'ancien, puis supprimer l'ancien ; la validation détecte les liens cassés.
• Suppression : archived préférée à l'effacement (préserve la navigation et l'historique).

16. Validation et conformité (/rag-check)

Vérifie que la base respecte la norme. Sortie : rapport d'erreurs/alertes.

Partie VI — Propriétés non-fonctionnelles

17. Scalabilité

• Sharding du manifeste par thème au-delà de ~500 docs : le manifeste racine devient un sommaire pointant vers des shards par thème. Le protocole de requête reste identique.
• Graphe global compact : un nœud = quelques lignes ; reste lisible jusqu'à plusieurs milliers de documents.
• Lectures ciblées : frontmatter puis section, jamais corpus complet. Le coût d'une requête ne croît pas proportionnellement à la taille de la base.
• Déterminisme : tris et formats stables → diffs minimes en git, fusion facile.

Ordre de grandeur : une base de 2 000 documents produit un manifeste de ~2 000 lignes. La phase 1 reste abordable ; et comme l'IA filtre puis ne lit que quelques frontmatters, le coût réel d'une requête reste maîtrisé.

18. Sécurité et confidentialité

• Pas de secret dans les .md ni dans impl_refs (ne jamais référencer un .env).
• Le contenu est stocké en clair : ne pas y mettre de données sensibles personnelles ou d'authentification.
• L'accès est délégué au système de fichiers / à l'outil de sync (hors scope).
• audience peut servir de signal de sensibilité (ex. security) mais ne remplace pas un contrôle d'accès réel.

19. Performance

• Zéro round-trip applicatif : la « recherche » est une lecture de fichier (disque local ou unité réseau montée). Pas de sérialisation MCP, pas de réseau vers un service externe.
• Lectures minimales : grâce à la divulgation progressive, on ne charge que ce qui est nécessaire.
• Pas de runtime : aucun processus à démarrer, aucun cache à invalider. La fraîcheur est garantie par construction (on lit les fichiers à l'instant T).

Partie VII — Comparatif

20. RAG file-based vs MCP/Confluence : analyse comparative

Quand choisir quoi ?

Le RAG file-based est pertinent quand :

• la priorité est la performance et le coût en tokens ;
• - on veut une documentation fidèle au code (anti-dérive) ;
• - on souhaite zéro infrastructure supplémentaire ;
• - la base de connaissance est technique et évolue avec le code ;
• - l'équipe maîtrise Markdown (ou un éditeur wysiwyg de Markdown) et git.
• Un MCP/Confluence reste pertinent quand :
• on a besoin d'une recherche sémantique vectorielle avancée ;
• - la documentation est business/métier et éditée par des non-techniques ;
• - on requiert un contrôle d'accès fin par page ;
• - on s'appuie sur un existant Confluence riche qu'on ne veut pas migrer.
• > Les deux approches ne s'excluent pas : on peut tout à fait maintenir la documentation métier dans Confluence et la connaissance technique « code » dans un RAG file-based. Ce dernier vient combler le fossé entre le code et sa description.

Partie VIII — Guide de mise en œuvre

21. Démarrage en 10 minutes

Étape 1 — Créer le marqueur

À la racine de votre dépôt, créez un fichier .rag :

version: "1"
root: ./docs-rag
lang: fr
summary_max: 240
check_on_update: true

Étape 2 — Créer le répertoire racine

mkdir docs-rag

Étape 3 — Lancer l'initialisation

Si vous utilisez Kilo (ou un CLI compatible) avec le toolkit installé :

/rag-init

L'IA scanne votre code, déduit les thèmes, génère les .md et les index, puis produit un rapport. Tous les documents sont en status: draft (à valider par un humain).

Étape 4 — Valider

/rag-check

Corrigez les éventuelles erreurs (E001–E003).

Étape 5 — Revoir et passer en stable

Pour chaque .md pertinent, vérifiez le contenu puis changez status: stable.

Étape 6 — Utiliser au quotidien

Pour poser une question à la base :

/rag-query Comment fonctionne le verrouillage de compte ?

L'IA applique la divulgation progressive et ne lit que le strict nécessaire.

Étape 7 — Maintenir

Après chaque évolution du code :

/rag-update

Les documents impactés sont mis à jour, les index régénérés, les dérives signalées.

22. Intégration native IA (skills, commandes, prompt système)

L'approche recommandée repose sur trois mécanismes complémentaires, sans MCP ni runtime.

22.1 Le triplet d'intégration

22.2 Pourquoi cette répartition ?

• Le prompt système est minimal : il ne contient que la détection et l'aiguillage. Il est lu à chaque session, son coût doit donc être négligeable.
• Les skills contiennent tout le savoir procédural mais ne sont chargées que lorsqu'une tâche les nécessite. C'est l'équivalent de la divulgation progressive, appliquée au prompt lui-même.
• Les commandes sont des déclencheurs minces : elles chargent et exécutent la skill pertinente (principe DRY — une seule source de vérité procédurale).

22.3 Installation du toolkit

Pour rendre les skills et commandes disponibles :

Option A — Installation globale (recommandée pour usage multi-projets)
Copiez les répertoires skills/ et command/ dans le répertoire de configuration globale de votre CLI (ex. ~/.config/kilo/ pour Kilo, ou l'équivalent de votre outil). Le toolkit est alors disponible dans tous vos dépôts. Les skills se désactivent d'elles-mêmes tant qu'il n'y a pas de .rag.

Option B — Référence via configuration
Pointez la configuration vers le répertoire contenant le toolkit (ex. champ skills.paths dans kilo.json). Pas de copie, une seule source — mais dépendance au chemin.

Option C — Copie projet par projet
Copiez le dossier .kilo/ (ou équivalent) dans chaque dépôt cible. Isolation totale, mais à répéter sur chaque projet.

Note importante : le fichier .rag seul n'installe pas les skills. .rag est un marqueur de données. Les skills/commands vivent dans la configuration du CLI et sont découverts au démarrage. Relancez la session après installation pour qu'ils apparaissent.

22.4 Adapter à un autre CLI que Kilo

La norme (rag.md) est outil-agnostique. Pour un autre CLI :

• Traduisez les skills en prompts ou system prompts conditionnels de votre outil.
• - Traduisez les commandes en macros/raccourcis équivalents.
• - Ajoutez le prompt système minimal (AGENTS.md) aux instructions chargées par défaut.
• - Le reste (format .rag, arborescence, frontmatter, index) est inchangé : ce sont des fichiers.

• ---

23. Déploiement et travail collaboratif

23.1 Stockage

La base vit dans le dépôt (recommandé : versionnée avec le code) ou sur une unité réseau. Le système est agnostique au support.

23.2 Synchronisation / réplication

Hors scope. Utilisez les outils existants :

• git pour la versioning (idéal : la base est committée avec le code).
• - Syncthing / kdrive / lecteur réseau pour le partage multi-postes.
• - L'unité réseau montée pour un accès direct (utiliser un root absolu dans .rag).

• 23.3 Contribution humaine

23.4 Intégration dans le workflow de développement

La règle d'or : une tâche de code n'est pas terminée tant que les .md concernés ne sont pas mis à jour. Intégrez /rag-update dans votre checklist de fin de tâche / de pull request.

Partie IX — Annexes techniques complètes

Cette partie contient l'intégralité des artefacts prêts à l'emploi. Chacun peut être copié tel quel dans votre environnement.

24. Annexe A — Cahier des charges canonique (rag.md)

Ce fichier est la spécification canonique du système. Placez-le à la racine de votre dépôt pour servir de référence normative.

# Cahier des charges — RAG par fichiers Markdown (file-based RAG)

> Version de la norme : 1.0 — Statut : stable
> Portée : spécification canonique et outil-agnostique du système.

## 1. Objectifs et périmètre

### 1.1 Contexte et motivation
Les assistants IA en CLI accèdent aujourd'hui fréquemment à la connaissance projet via un MCP couplé à un outil externe (ex. Confluence, Notion, wiki). Ce modèle présente plusieurs coûts :
- latence : un aller-retour réseau + sérialisation MCP à chaque recherche ;
- coût en tokens : payloads JSON volumineux, métadonnées de transport ;
- dépendance : service externe à déployer, authentifier, maintenir ;
- dérive : la connaissance documentaire se désynchronise du code.

Ce cahier des charges décrit un RAG par fichiers Markdown, purement filesystem, sans MCP ni service externe.

### 1.2 Objectifs mesurables
- Latence de « recherche » : ~ lecture disque ; zéro round-trip applicatif.
- Coût en tokens : lecture du manifeste en phase 1, puis frontmatter seul en phase 2.
- Scalabilité : de quelques dizaines à plusieurs milliers de documents.
- Empreinte : aucun runtime, aucune dépendance ; uniquement des fichiers.
- Robustesse : index dérivés et auto-régénérables.
- Fiabilité : lien explicite doc ↔ code (impl_refs) + détection de dérive.

### 1.3 Hors périmètre
- Synchronisation / réplication / partage réseau (outils tiers).
- Moteur de recherche plein-texte vectoriel.
- Authentification / contrôle d'accès au stockage.

## 2. Principes directeurs
1. La source de vérité, ce sont les fichiers .md (index = dérivés).
2. Divulgation progressive : l'IA ne lit jamais tout.
3. Convention plutôt que configuration.
4. Outil-agnostique.
5. Connaissances vivantes (mises à jour à chaque évolution du code).

## 3. Composants
- Marqueur .rag (§4) : active/désactive et localise la racine.
- Arborescence thématique (§5).
- Documents .md (§6).
- Index dérivés (§8) : OVERVIEW.md, INDEX.md, RELATIONS.yaml.
- Bindings IA (§15) : skills, commandes, prompt système.

## 4. Le marqueur .rag
Fichier .rag à la racine du dépôt. Présent = RAG actif. Absent = aucune logique.
Format YAML : version, root, lang, index.{manifest,relations,overview}, summary_max, check_on_update.
Résolution : root relatif (au dossier du .rag) ou absolu.

## 5. Arborescence
Thèmes de premier niveau (non prédéfinis, déduits du projet) > sous-thèmes > documents .md.
Nommage strict : a-z0-9- uniquement, minuscules, tirets, sans accents ni espaces.
Fichiers système réservés : OVERVIEW.md, INDEX.md, RELATIONS.yaml. Préfixe _ = ignoré.

## 6. Format des documents
Frontmatter YAML (---) + corps Markdown.
Champs requis : title, summary (≤ summary_max), type, status, tags (≥1), updated.
Énumérations : type (concept|feature|api|guide|process|decision|reference|overview),
status (draft|stable|needs-review|deprecated|archived), priority (p0|p1|p2).
Identifiant canonique = chemin relatif depuis la racine RAG.
Corps : titres ##/###, hyperliens relatifs.

## 7. Économie de tokens
Les métadonnées suffisent à décider de lire ou non le corps.
Budget frontmatter seul : ~150–400 tokens vs plusieurs milliers pour un corps complet.

## 8. Index dérivés
OVERVIEW.md : arbre des thèmes + compteurs.
INDEX.md : manifeste 1 ligne/doc (tri par chemin). Sharding au-delà de ~500 docs.
RELATIONS.yaml : graphe bidirectionnel (links, related, linked_by).
Auto-guérison : recalcules depuis les .md réels.

## 9. Protocole de requête (divulgation progressive)
Phase 0 (.rag) → Phase 1 (INDEX.md) → Phase 2 (frontmatters) → Phase 3 (corps ciblé) → Phase 4 (RELATIONS.yaml).
Stoppe dès que la réponse est obtenue. Ne jamais lire toute la base.

## 10. Init / sync depuis le code
/rag-init : scan du code, déduction des thèmes, génération des .md (draft), régénération des index.
/rag-update : détection des changements (git), MAJ des .md impactés via impl_refs, needs-review sur dérive.
Drift : impl_refs + git pour détecter les docs en retard sur le code.

## 11. Maintenance
Mise à jour obligatoire des .md à chaque évolution du code.
Édition humaine réconciliée à la régénération.
Cohérence des relations : dernier lien vers une cible supprimé → arête supprimée.

## 12. Validation (/rag-check)
E001 (nom), E002 (frontmatter), E003 (enum), E004 (summary long),
W001 (lien cassé), W002 (orphelin), W003 (impl_refs absent), W004 (staleness 90j), W005 (index désync).
Auto-réparation déterministe (W005).

## 13. Scalabilité
Sharding du manifeste, graphe compact, lectures ciblées, déterminisme.

## 14. Sécurité
Pas de secret dans les .md ni impl_refs. Contenu en clair. Accès délégué au système de fichiers.

## 15. Bindings Kilo
AGENTS.md (prompt système minimal) + skills (rag, rag-sync) + commandes (/rag-init, /rag-update, /rag-query, /rag-check).
Les skills = source de vérité procédurale ; les commandes = déclencheurs minces (DRY).

Le fichier rag.md complet et détaillé (17 sections, ~440 lignes) est fourni dans le dépôt de référence. L'extrait ci-dessus en est la synthèse normative.

25. Annexe B — Skill rag (intégrale)

Placez ce fichier dans <config>/skills/rag/SKILL.md. C'est la compétence de consultation, écriture et maintenance.

---
name: rag
description: Base de connaissance RAG par fichiers Markdown. Utiliser ce skill dès qu'il faut consulter, écrire ou maintenir la documentation projet stockée en .md (repérée par le fichier .rag à la racine). Décrit le protocole de requête économe en tokens (divulgation progressive), le schéma de frontmatter YAML, les conventions de nommage, l'arborescence par thèmes et les index dérivés (INDEX.md, RELATIONS.yaml, OVERVIEW.md).
---

# Skill — RAG file-based (consultation, écriture, maintenance)

Tu opères une base de connaissance RAG par fichiers Markdown. Référence canonique : rag.md (cahier des charges). Ce skill en est le mode d'emploi opérationnel.

## 0. Activation / détection
1. Cherche un fichier .rag à la racine du dépôt/workspace.
   - Absent → le RAG n'est pas actif. Ne fais rien de RAG-spécifique.
   - Présent → lis-le (YAML). Il fournit root (racine de la base) et la config (index.manifest, index.relations, index.overview, lang, summary_max).
2. Résous root (relatif au dossier contenant .rag, ou absolu). Si la racine n'existe pas ou est vide → propose /rag-init (skill rag-sync).

Noms par défaut des index : INDEX.md, RELATIONS.yaml, OVERVIEW.md (à la racine RAG), sauf surcharge dans .rag.

## 1. Protocole de requête — DIVULGATION PROGRESSIVE (obligatoire)
Objectif : minimiser les tokens. Tu ne lis JAMAIS toute la base. Suis les phases et stoppe dès que tu as ta réponse.

- Phase 0 : lire .rag → obtenir root.
- Phase 1 : lire INDEX.md (manifeste, 1 ligne/doc). Sélectionner des candidats par tags / type / audience / résumé. Si manifeste sharded (>500 docs), lire d'abord le sommaire racine puis le shard du thème pertinent.
- Phase 2 : pour chaque candidat, lire uniquement le frontmatter (recherche bornée sur le bloc entre les ---, ou lecture limitée aux ~30 premières lignes). Éliminer les non-pertinents.
- Phase 3 : pour les survivants, lire le corps, en ciblant d'abord la section (titre ##/###) pertinente plutôt que le fichier entier (utilise recherche/offset).
- Phase 4 : navigation de proche en proche via RELATIONS.yaml ou les hyperliens du corps, uniquement si nécessaire.

Règles :
- Préfère une recherche/grep bornée au chargement complet d'un long fichier.
- Si status ∈ {needs-review, deprecated} → vérifie impl_refs contre le code avant de t'y fier ; signale le risque à l'utilisateur.
- Si rien en phases 1–2 → élargir via OVERVIEW.md puis RELATIONS.yaml.

## 2. Conventions de nommage (strictes)
Pour tous fichiers et dossiers de contenu : a-z0-9- uniquement, minuscules, tirets comme séparateurs, pas d'accents, pas d'espaces, pas de _ pour les contenus. Extension .md (ou .markdown).
Slugification à la création : "Authentification 2FA" → authentification-2fa.
Fichiers système réservés à la racine RAG : OVERVIEW.md, INDEX.md, RELATIONS.yaml. Préfixe _ = ignoré par l'indexation (brouillons).

## 3. Schéma frontmatter (YAML, entre ---)
Champs requis : title, summary (≤ summary_max, défaut 240), type, status, tags (≥1), updated (date ISO).
Optionnels : audience, theme, impl_refs (chemins code source), related (chemins .md), created, owners, version, priority, lang.

Énumérations :
- type : concept | feature | api | guide | process | decision | reference | overview
- status : draft | stable | needs-review | deprecated | archived
- priority : p0 | p1 | p2
- audience : dev | po | qa | ops | design | security | all

L'identifiant canonique d'un doc = son chemin relatif depuis la racine RAG (ex. securite/mfa.md). Pas de champ id.

## 4. Index dérivés (AUTO-GÉNÉRÉS — ne pas éditer manuellement)
- OVERVIEW.md : arbre des thèmes + compteurs (la « carte »).
- INDEX.md : manifeste compact tabulaire (1 ligne/doc, tri par chemin). Lu en phase 1.
- RELATIONS.yaml : graphe bidirectionnel (links, related, linked_by par nœud).
Ces fichiers portent l'en-tête > Auto-généré — NE PAS ÉDITER. Ils sont régénérés par la skill rag-sync (commandes /rag-init, /rag-update). Source de vérité = les .md, pas les index.

## 5. Écrire / mettre à jour un document .md
1. Choisis l'emplacement selon le thème/sous-thème ; nom conforme (§2).
2. Rédige un frontmatter complet (§3). summary doit permettre de juger la pertinence sans lire le corps.
3. Corps structuré par titres (##, ###) pour permettre la lecture ciblée.
4. Hyperliens inter-docs en chemins relatifs : [texte](../securite/mfa.md).
5. Renseigne impl_refs vers le code réellement concerné (fraîcheur/dérive).
6. Met updated à la date du jour ; status cohérent (draft si non validé, needs-review si incertain).
7. Après toute modification de contenu ou de liens : régénère les index (skill rag-sync / /rag-update) pour répercuter les relations.

## 6. Règles de maintenance (rappel obligatoire)
- À chaque évolution du code, mets à jour les .md concernés avant de clôturer la tâche.
- L'édition humaine est toujours réconciliée à la prochaine régénération.
- Renommage : nouveau doc + mise à jour des liens entrants + suppression de l'ancien ; vérifier les liens cassés.
- Préférer status: archived à l'effacement (préserve la navigation).

## 7. Quand init/sync est nécessaire
Si la base est vide/inexistante, ou après des changements de code, ou si /rag-check signale une désynchronisation → passe à la skill rag-sync (ou lance /rag-init, /rag-update). Ce skill (rag) reste sur la consultation/écriture ponctuelle.

## 8. Référence
Spécification complète et normative : rag.md à la racine du dépôt (en cas de doute sur un cas limite, rag.md fait foi).

26. Annexe C — Skill rag-sync (intégrale)

Placez ce fichier dans <config>/skills/rag-sync/SKILL.md. C'est la compétence d'initialisation, synchronisation et détection de dérive.

---
name: rag-sync
description: Initialiser ou synchroniser la base de connaissance RAG (.md) depuis le contenu réel d'un dépôt de code, pour refléter ce qui est réellement implémenté. Utiliser ce skill pour /rag-init (création de la base), /rag-update (mise à jour après évolution, détection de dérive via impl_refs/git) et la régénération des index dérivés (INDEX.md, RELATIONS.yaml, OVERVIEW.md).
---

# Skill — RAG sync (init / update / drift depuis le code)

Ce skill matérialise les opérations lourdes du RAG : constitution puis synchronisation de la base depuis le code, et régénération des index dérivés. Il complète la skill rag (consultation/écriture ponctuelle). Référence normative : rag.md (§10, §8, §11).

Prérequis : le système RAG et ses conventions sont décrits par la skill rag ; charge-la si besoin pour les conventions de nommage et le schéma frontmatter.

## Principes communs
- La base doit refléter le code réellement implémenté (impl_refs pointent vers les vrais fichiers).
- Les .md sont la source de vérité ; OVERVIEW.md, INDEX.md, RELATIONS.yaml sont dérivés et régénérés à la fin de chaque opération.
- Déterminisme : trie par chemin, formats stables → diffs propres.
- Préserve l'historique sémantique : archived/deprecated plutôt qu'effacement (sauf confirmation explicite).
- Sécurité : ne référence jamais de secret (.env, credentials) dans impl_refs ou le contenu.

## A. /rag-init — créer la base depuis le dépôt

### A.0 Paramètres
- Argument $1 / $ARGUMENTS : racine RAG souhaitée (défaut ./docs-rag). Si .rag existe déjà et pointe vers une base non vide, ne pas écraser : propose /rag-update à la place.

### A.1 Cadrage
1. Confirme/choisis la racine RAG (création du dossier si besoin).
2. Crée/écrit le fichier .rag à la racine du dépôt :
   version: "1", root: ./docs-rag, lang: fr, summary_max: 240, check_on_update: true
3. Identifie la langue dominante du dépôt pour lang et la langue de rédaction.

### A.2 Scan du code
Explore le dépôt pour en extraire la structure fonctionnelle :
- Arborescence des sources, points d'entrée, modules/packages, routing/endpoints, schémas/models, services, tests, configs, migrations.
- Documents existants (README, AGENTS.md, CONTRIBUTING, ADR, OpenAPI/specs).
- Déduis les responsabilités et le découpage fonctionnel.
Outils recommandés : glob (fichiers), grep (points d'entrée, routes, définitions), lecture ciblée des fichiers clés. Évite de tout lire : échantillonne représentativement.

### A.3 Déduction des thèmes
- Définis 3 à 8 thèmes de premier niveau adaptés au projet (perimetre-fonctionnel, architecture, securite, performance, ergonomie, exploitation…) — non prédéfinis, déduits du contexte.
- Sous-thèmes = sous-responsabilités (profondeur ≤ 3 recommandée).
- Justifie brièvement le choix des thèmes à l'utilisateur si le contexte est ambigu.

### A.4 Génération des documents
Pour chaque unité de connaissance cohérente, crée un .md :
- Emplacement + nom conformes (a-z0-9-, sans accents/espaces).
- Frontmatter complet : title, summary (≤ summary_max, auto-suffisant), type, tags, audience, impl_refs (chemins réels), related, created, updated (aujourd'hui), status: draft, priority.
- Corps : titre # + sections ## (Périmètre, Parcours/Comportement, Points clés, Liens). Démoule le contenu depuis le code réel (ne fabrique pas de comportements non présents).
- Hyperliens relatifs vers les docs connexes.

### A.5 Régénération des index (procédure C)
Exécute la procédure C ci-dessous.

### A.6 Validation + rapport
- Lance la vérification (skill rag §2/§3 + règles /rag-check) : noms, frontmatter, liens.
- Laisse status: draft partout (validation humaine requise).
- Restitue un rapport : thèmes créés, nb de documents, éventuels impl_refs non résolus, prochaines étapes.

---

## B. /rag-update — synchroniser après une évolution

### B.0 Paramètres
- Argument : périmètre (chemins/fichiers modifiés, branche, ou « depuis dernier sync »). Si absent, déduis les changements via git (status/diff/log) ou mtimes.

### B.1 Détection du périmètre impacté
- Identifie les fichiers de code modifiés/ajoutés/supprimés.
- Croise avec les impl_refs existants pour trouver les .md impactés.

### B.2 Mises à jour
Pour chaque .md impacté :
- Contenu modifié (comportement du code changé) → rédige/mets à jour le corps + summary + updated + impl_refs. Si divergence notable non vérifiable → status: needs-review.
- Nouvelle fonctionnalité sans doc → crée un .md (status: draft).
- Code supprimé/renommé :
  - impl_ref supprimé/renommé → corrige la référence ; si le doc n'a plus de raison d'être → status: archived (ne pas effacer sans confirmation).
  - doc dont tous les impl_refs ont disparu → status: needs-review + alerte.

### B.3 Cohérence des relations
- Ajout d'hyperlien → nouvelle arête à la régénération.
- Suppression du dernier lien (corps + related) vers une cible → l'arête disparaît.
- Liens cassés (cible renommée/supprimée) → corriger ou archived.

### B.4 Régénération des index (procédure C)

### B.5 Validation + rapport
- Si .rag.check_on_update: true → exécute /rag-check (auto-réparation déterministe : W005).
- Rapport : documents créés/mis à jour/archivés, dérives détectées (needs-review), liens réparés.

---

## C. Procédure de régénération des index (déterministe)

À exécuter à la fin de A et B (et via /rag-check pour W005).

### C.1 Collecte
- Lister récursivement tous les .md/.markdown sous la racine RAG, sauf ceux préfixés _ et les fichiers système (INDEX.md, OVERVIEW.md).
- Pour chaque doc : lire le frontmatter (bloc ---), extraire title, summary, type, status, tags, audience, priority, related, impl_refs, et les hyperliens .md du corps (résoudre les chemins relatifs → chemin canonique depuis la racine).

### C.2 OVERVIEW.md
- Arbre des thèmes (dossiers) avec compteurs de documents par nœud.
- En-tête > Auto-généré — NE PAS ÉDITER. Généré le <date ISO>. Documents : <n>.

### C.3 INDEX.md
- Tableau 1 ligne par doc, colonnes : chemin | type | statut | prio | tags | résumé.
- Tri par chemin (déterministe). Résumé tronqué proprement à ~summary_max.
- Même en-tête auto-généré.

### C.4 RELATIONS.yaml
version: "1"
generated: "<date ISO>"
nodes:
  <chemin-canonique>:
    links: [...]      # hyperliens du corps (dédupliqués, triés)
    related: [...]    # champ frontmatter related (trié)
    linked_by: [...]  # calcul inverse (trié)
- Un nœud par doc (même sans relations). Tri des listes pour stabilité.
- N'émet une arête links que si le lien existe réellement dans le corps ; linked_by = miroir de tous les links+related entrants.

### C.5 Cohérence
- Tout impl_ref ou lien .md introuvable → signaler (W001/W003), ne pas faire échouer la régénération.
- Vérifier que les noms respectent la convention (E001) et le frontmatter (E002/E003) → rapporter.

---

## D. Détection de dérive (drift) — synthèse
- Source de vérité du « code courant » : git (fichiers modifiés depuis la date updated du doc) ou hash/mtime des impl_refs.
- Un doc est stalé si un impl_ref a changé/après sa date updated, ou a disparu.
- Action : status: needs-review + mention dans le rapport. Ne jamais marquer stable un doc non vérifié après dérive.

## E. Production-ready — garde-fous
- Idempotence : relancer init/update sans changement ne modifie rien (diffs vides grâce au déterminisme).
- Non-destruction : ne supprime jamais un .md sans confirmation explicite de l'utilisateur.
- Pas de secret dans impl_refs/contenu.
- Tri et formats stables à chaque régénération.
- Toujours restituer un rapport des actions et des alertes.

27. Annexe D — Les quatre commandes (intégrales)

Placez ces fichiers dans <config>/command/. Ce sont les déclencheurs explicites. Chacun charge la skill pertinente et exécute la procédure correspondante.

27.1 rag-init.md

---
description: Initialise la base de connaissance RAG (.md) depuis le dépôt de code
agent: code
---
 Initialise la base de connaissance RAG à partir du contenu réel de ce dépôt, afin qu'elle reflète ce qui est réellement implémenté.

Utilise l'outil skill pour charger la skill rag-sync, puis exécute sa procédure A (/rag-init) dans son intégralité.

Paramètre : $ARGUMENTS = racine RAG souhaitée (défaut ./docs-rag). Si .rag existe déjà et pointe vers une base non vide, n'écrase rien : propose plutôt /rag-update.

Étapes obligatoires :
1. Cadrage + écriture du fichier .rag (racine + config).
2. Scan du code (échantillonnage représentatif, sans tout lire).
3. Déduction des thèmes de premier niveau et sous-thèmes (adaptés au projet).
4. Génération des .md (frontmatter complet, impl_refs vers les vrais fichiers, status: draft).
5. Régénération des index via la procédure C (OVERVIEW.md, INDEX.md, RELATIONS.yaml).
6. Validation + rapport final (thèmes, nb de documents, impl_refs non résolus, prochaine étape = revue humaine).

Respecte les conventions de la skill rag (noms a-z0-9-, schéma frontmatter). Ne mets aucun secret dans impl_refs ou le contenu. Référence normative : rag.md.

27.2 rag-update.md

---
description: Synchronise la base RAG avec les évolutions du code (dérive via impl_refs/git)
agent: code
---
 Synchronise la base de connaissance RAG avec les évolutions récentes du code.

Utilise l'outil skill pour charger la skill rag-sync, puis exécute sa procédure B (/rag-update).

Paramètre : $ARGUMENTS = périmètre (fichiers/chemins modifiés, branche, ou « depuis dernier sync »). Si absent, déduis les changements via git (status/diff/log) ou les mtimes.

Étapes obligatoires :
1. Détection du périmètre impacté (croisement code modifié ↔ impl_refs des .md).
2. Mise à jour des .md concernés : contenu + summary + updated + impl_refs. Divergence non vérifiable → status: needs-review. Nouveautés → nouveau .md (draft). Code supprimé → archived (jamais d'effacement sans confirmation).
3. Cohérence des relations (ajout d'hyperlien → arête ; dernier lien vers une cible supprimé → arête retirée).
4. Régénération des index via la procédure C.
5. Si .rag.check_on_update: true → exécute /rag-check (auto-réparation W005).
6. Rapport final : documents créés/mis à jour/archivés, dérives détectées, liens réparés.

Respecte les conventions de la skill rag. Référence normative : rag.md.

27.3 rag-query.md

---
description: Interroge la base RAG en suivant le protocole économe en tokens
agent: code
---
 Réponds à la question suivante en exploitant la base de connaissance RAG, en suivant strictement le protocole de divulgation progressive (coût minimal en tokens).

Utilise l'outil skill pour charger la skill rag, puis applique son protocole de requête (§1) :
phase 0 (.rag) → phase 1 (INDEX.md) → phase 2 (frontmatters seuls) → phase 3 (corps/section ciblés) → phase 4 (navigation via RELATIONS.yaml si utile). Stoppe dès que tu as la réponse ; ne charge jamais toute la base.

Question : $ARGUMENTS

Restitue la réponse, puis cite les chemins canoniques des documents effectivement lus (avec file_path:line quand pertinent). Si un document utilisé est needs-review/deprecated, signale-le et vérifie ses impl_refs contre le code. Si la base est absente/vide, indique-le et propose /rag-init.

27.4 rag-check.md

---
description: Valide la conformité de la base RAG et auto-répare les index dérivés
agent: code
---
 Vérifie la conformité de la base de connaissance RAG vis-à-vis de la norme, et auto-répare ce qui est déterministe.

Utilise l'outil skill pour charger la skill rag (conventions + schéma frontmatter), puis applique les règles de validation de rag.md §12 :

- E001 noms de fichiers/dossiers (a-z0-9-, sans accents/espaces).
- E002/E003 frontmatter valide (champs requis : title, summary, type, status, tags, updated) et énumérations correctes.
- E004/W001/W002/W003/W004 summary trop long, lien cassé, doc orphelin, impl_refs absent, doc stable non MAJ > 90 j.
- W005 index désynchronisé → auto-répare en régénérant OVERVIEW.md, INDEX.md, RELATIONS.yaml (procédure C de la skill rag-sync).

Restitue un rapport structuré par code (error / warning / info), avec le chemin concerné pour chacun. Liste les auto-réparations effectuées. À la fin, exécute /rag-update uniquement si des needs-review/liens cassés le justifient, après confirmation.

Paramètre optionnel $ARGUMENTS : chemin ou thème à restreindre. Référence normative : rag.md.

28. Annexe E — Pointeur AGENTS.md (intégrale)

Placez ce fichier à la racine de chaque dépôt où vous activez le RAG. C'est le prompt système always-on minimal.

# AGENTS.md — Instructions de projet

## RAG file-based (base de connaissance Markdown)
Ce dépôt définit et utilise un système RAG par fichiers Markdown (aucun MCP, aucun service externe).

- Spécification canonique : rag.md (cahier des charges complet).
- Détection : si un fichier .rag est présent à la racine d'un dépôt/workspace, le RAG est actif (il localise la racine de la base). Absent → aucune logique RAG.

### Réflexes obligatoires
- Avant de consulter/écrire la connaissance projet : charge la skill rag (protocole de requête « divulgation progressive », schéma frontmatter, conventions de nommage). Ne lis jamais toute la base.
- Pour initialiser ou synchroniser la base depuis le code : charge la skill rag-sync, ou utilise les commandes /rag-init (création), /rag-update (synchronisation + dérive), /rag-check (conformité), /rag-query (requête guidée).
- Après toute évolution du code : mets à jour les .md concernés et régénère les index (OVERVIEW.md, INDEX.md, RELATIONS.yaml) avant de clôturer la tâche.
- Sécurité : ne référence jamais de secret (.env, credentials) dans impl_refs ou le contenu.

En cas de doute sur un cas limite, rag.md fait foi.

29. Annexe F — Exemple complet commenté

Cette annexe présente une base de connaissance complète et fonctionnelle, prête à copier. Elle illustre toutes les conventions sur un cas réaliste (authentification/MFA).

29.1 Structure de l'exemple

.rag                          ◀ marqueur à la racine du dépôt
docs-rag/                     ◀ racine de la base
  OVERVIEW.md                 ◀ dérivé
  INDEX.md                    ◀ dérivé
  RELATIONS.yaml              ◀ dérivé
  perimetre-fonctionnel/      ◀ thème
    authentification/         ◀ sous-thème
      login.md                ◀ document
      session.md              ◀ document
  securite/                   ◀ thème
    mfa.md                    ◀ document

29.2 Le fichier .rag

version: "1"
root: ./docs-rag
lang: fr
summary_max: 240
check_on_update: true

29.3 OVERVIEW.md (dérivé)

# OVERVIEW — Carte de la base de connaissance

> Auto-généré — NE PAS ÉDITER. Généré le 2026-07-01. Documents : 3.

perimetre-fonctionnel (2)
  authentification (2)
    login.md
    session.md
securite (1)
  mfa.md

29.4 INDEX.md (dérivé)

# INDEX — Manifeste

> Auto-généré — NE PAS ÉDITER. Généré le 2026-07-01. Documents : 3.

| chemin | type | statut | prio | tags | résumé |
|---|---|---|---|---|---|
| perimetre-fonctionnel/authentification/login.md | feature | stable | p1 | auth,login,mot-de-passe,mfa | Flux de connexion par identifiant/mot de passe, MFA optionnel, verrouillage après N échecs. |
| perimetre-fonctionnel/authentification/session.md | feature | stable | p1 | auth,session,cookie | Gestion de session : création, durée de vie, rotation, révocation. |
| securite/mfa.md | concept | stable | p0 | securite,mfa,2fa,totp | Second facteur TOTP/matériel : enrollment, vérification et repli. |

29.5 RELATIONS.yaml (dérivé)

# Auto-généré — NE PAS ÉDITER.
version: "1"
generated: "2026-07-01T19:46:00+02:00"
nodes:
  perimetre-fonctionnel/authentification/login.md:
    links:
      - perimetre-fonctionnel/authentification/session.md
      - securite/mfa.md
    related:
      - securite/mfa.md
    linked_by:
      - perimetre-fonctionnel/authentification/session.md
      - securite/mfa.md
  perimetre-fonctionnel/authentification/session.md:
    links:
      - perimetre-fonctionnel/authentification/login.md
    related: []
    linked_by:
      - perimetre-fonctionnel/authentification/login.md
  securite/mfa.md:
    links:
      - perimetre-fonctionnel/authentification/login.md
    related: []
    linked_by:
      - perimetre-fonctionnel/authentification/login.md

29.6 Document login.md (source)

---
title: "Authentification par login"
summary: "Flux de connexion par identifiant/mot de passe, MFA optionnel et verrouillage après N échecs."
type: feature
status: stable
tags: [auth, login, mot-de-passe, mfa]
audience: [dev, po]
impl_refs: [src/auth/login.controller.ts, src/auth/login.service.ts]
related: [securite/mfa.md]
created: 2026-07-01
updated: 2026-07-01
owners: [equipe-auth]
version: "1.2"
priority: p1
---

# Authentification par login

## Périmètre
Connexion d'un utilisateur par identifiant + mot de passe, avec second facteur optionnel et protection anti-force-brute. Le cycle de vie de la session est géré séparément dans [Session](session.md).

## Parcours nominal
1. Réception POST /auth/login ({ identifier, password }).
2. Vérification du couple via login.service.ts (hash + comparaison à temps constant).
3. Si compte éligible au MFA → délégation à [MFA](../../securite/mfa.md).
4. Émission d'une session (cf. [Session](session.md)).

## Sécurité
- Verrouillage du compte après 5 échecs consécutifs (LOGIN_MAX_ATTEMPTS).
- Rate-limiting par IP et par identifiant.
- Aucune fuite d'information (messages d'erreur génériques).

## Points clés
- LOGIN_MAX_ATTEMPTS, LOCK_DURATION_MS : configuration.
- status: stable — vérifié contre impl_refs le 2026-07-01.

29.7 Document session.md (source)

---
title: "Gestion de session"
summary: "Gestion de session : création, durée de vie, rotation et révocation (cookie httpOnly)."
type: feature
status: stable
tags: [auth, session, cookie]
audience: [dev, ops]
impl_refs: [src/auth/session.service.ts, src/auth/session.store.ts]
related: []
created: 2026-07-01
updated: 2026-07-01
owners: [equipe-auth]
version: "1.0"
priority: p1
---

# Gestion de session

## Périmètre
Cycle de vie du jeton de session après authentification (cf. [Login](login.md)).

## Comportement
- Création : à la réussite du login, un identifiant de session est émis, stocké côté serveur (session.store.ts), et posé dans un cookie httpOnly; Secure; SameSite=Lax.
- Durée de vie : SESSION_TTL (sliding : prolongée à chaque requête).
- Rotation : nouvel identifiant à l'élévation de privilège.
- Révocation : POST /auth/logout et liste noire server-side.

## Points clés
- SESSION_TTL, SESSION_COOKIE_NAME : configuration.
- Stockage configurable (mémoire en dev, Redis en prod).

29.8 Document mfa.md (source)

---
title: "Authentification multi-facteurs (MFA)"
summary: "Second facteur TOTP/matériel : enrollment, vérification et repli vers le login."
type: concept
status: stable
tags: [securite, mfa, 2fa, totp]
audience: [dev, security]
impl_refs: [src/security/mfa.service.ts, src/security/mfa.controller.ts]
related: [perimetre-fonctionnel/authentification/login.md]
created: 2026-07-01
updated: 2026-07-01
owners: [equipe-security]
version: "1.1"
priority: p0
---

# Authentification multi-facteurs (MFA)

## Périmètre
Second facteur d'authentification (TOTP ou clé matérielle) activable par l'utilisateur ; intégré au flux de [login](../perimetre-fonctionnel/authentification/login.md).

## Enrollment
1. L'utilisateur génère un secret TOTP (mfa.service.ts).
2. Affichage d'un QR code ; saisie d'un code de validation pour confirmer.
3. Codes de récupération fournis (usage unique).

## Vérification
- Lors du login, si le compte a un MFA actif, un code à 6 chiffres est exigé.
- Fenêtre de tolérance ±1 période (30 s).

## Repli
- En cas d'indisponibilité : codes de récupération, puis procédure de réinitialisation assistée.

## Points clés
- MFA_ISSUER, MFA_TOTP_STEP : configuration.
- status: stable — vérifié contre impl_refs le 2026-07-01.

29.9 Lecture commentée de l'exemple

Observons comment l'exemple illustre chaque mécanisme :

• Le marqueur .rag active le système et pointe vers ./docs-rag.
• - L'arborescence reflète deux thèmes : perimetre-fonctionnel (avec sous-thème authentification) et securite. Les noms respectent strictement la convention (a-z0-9-).
• - Chaque document a un frontmatter complet avec summary auto-suffisant (on comprend le périmètre sans lire le corps), des impl_refs pointant vers le code réel, et des tags filtrables.
• - Les hyperliens sont en chemins relatifs ([Session](session.md), [MFA](../../securite/mfa.md)). Ils sont la source du graphe RELATIONS.yaml.
• - Le graphe est bidirectionnel : login.md pointe vers mfa.md (lien explicite + related), et mfa.md est linked_by login.md. La navigation de proche en proche est possible sans relire les corps.
• - Les index dérivés portent l'en-tête > Auto-généré — NE PAS ÉDITER.
• - Le status: stable est justifié par une vérification contre impl_refs à une date précise — traçabilité.
• > Si un humain supprimait le lien [MFA](https://icantext.com/securite/mfa.md) du corps de login.md : à la prochaine régénération, l'arête links de login.md vers mfa.md disparaîtrait — mais le champ related: [securite/mfa.md] maintiendrait encore la relation (car ce n'est pas le dernier lien). Si l'on supprimait aussi le related, alors l'arête serait entièrement retirée, illustrant la règle de cohérence des relations (§11.4).

Partie X — Clôture

30. FAQ

Q1 — Le fichier .rag installe-t-il automatiquement les skills ?
Non. .rag est un marqueur de données qui active/désactive le système et localise la base. Les skills/commands vivent dans la configuration du CLI et sont installés séparément (voir §22.3). Relancez la session après installation.

Q2 — Que se passe-t-il si je supprime le fichier .rag ?
Tout le système est désactivé. Les IA ignorent la base. C'est un moyen simple et radical d'activer/désactiver le RAG sans toucher au contenu.

Q3 — Puis-je éditer les fichiers .md à la main ?
Oui, c'est même encouragé. Les .md sont la source de vérité. Une régénération réconcilie toujours les index. Évitez seulement d'éditer manuellement OVERVIEW.md, INDEX.md et RELATIONS.yaml (ils sont écrasés à la régénération).

Q4 — Que deviennent les relations si je supprime un hyperlien ?
Si vous supprimez un hyperlien vers une cible et qu'il ne reste aucun autre hyperlien (ni champ related) vers cette cible, l'arête disparaît du graphe à la prochaine régénération. Tant qu'un lien subsiste, la relation est conservée.

Q5 — Combien de documents le système peut-il gérer ?
De quelques dizaines à plusieurs milliers. Au-delà de ~500, le manifeste est shardé par thème. Le coût d'une requête ne croît pas proportionnellement à la taille grâce à la divulgation progressive.

Q6 — Faut-il un moteur de recherche vectoriel ?
Non. La recherche est déterministe (manifeste + graphe de relations). C'est un choix délibéré pour la prévisibilité et l'économie de tokens. Rien n'empêche d'ajouter une couche vectorielle en complément, mais ce n'est pas dans le périmètre.

Q7 — Comment ça se comporte avec git ?
Excellent. La base étant des fichiers texte, elle se versionne parfaitement (on peut naviguer comme sur un site html avec l'outil MD Studio). Le déterminisme (tris, formats stables) produit des diffs minimes et des fusions faciles. Recommandation : commitez la base avec le code.

Q8 — Et sur une unité réseau (kdrive, NAS) ?
Le système est agnostique au stockage. Utilisez un root absolu dans .rag. La synchronisation/réplication est gérée par l'outil de votre choix (hors scope).

Q9 — Est-ce que ça marche avec un autre outil IA que Kilo ?
Oui. La norme (rag.md) est outil-agnostique. Traduisez les skills en prompts/conditions et les commandes en macros de votre outil. Le format des fichiers est inchangé.

Q10 — Comment éviter que la doc dérive ?
Deux garde-fous : (1) la discipline d'équipe — une tâche n'est pas finie tant que les .md ne sont pas mis à jour ; (2) la détection automatique — impl_refs + git signalent les docs en retard, marqués needs-review. La validation les met en évidence.

Q11 — Puis-je mettre des secrets dans les .md ?
Non. Règle absolue de sécurité : jamais de secret (.env, credentials) dans impl_refs ou le contenu. Le contenu est stocké en clair.

Q12 — Que faire d'un document obsolète ?
Préférez status: archived à l'effacement. Cela préserve la navigation et l'historique. L'effacement n'intervient qu'après confirmation explicite.

31. Cas d'usage typiques

Cas 1 — Onboarding d'un nouvel arrivant

Le nouvel arrivant lance une session IA dans le dépôt. Grâce au RAG, l'IA peut répondre à « explique-moi l'architecture » en lisant le manifeste puis les documents pertinents, sans qu'on ait à lui réexpliquer tout le contexte. L'onboarding est accéléré.

Cas 2 — Refactoring sécurisé

Avant de refactorer un module, l'IA interroge la base, identifie les documents qui décrivent ce module (impl_refs), et propose de les mettre à jour en même temps que le code. Le RAG garantit que la refactoration ne laisse pas la doc en suspens.

Cas 3 — Revue de conformité

Un audit exige de vérifier que la documentation de sécurité est à jour. On lance /rag-check : les documents needs-review ou dont les impl_refs ont disparu sont signalés. On traite les alertes, on régénère, on a une base saine et certifiable.

Cas 4 — Multi-projets avec base partagée

Une organisation gère 5 dépôts. Elle installe le toolkit une fois en configuration globale. Chaque dépôt a son .rag et sa base. L'IA active automatiquement le RAG là où .rag est présent, et l'ignore ailleurs.

Cas 5 — Documentation « docs-as-code »

Une équipe veut traiter sa documentation comme du code. Le RAG file-based est l'incarnation de cette philosophie : versionnée, vérifiable, reviewable en PR, maintenue au fil de l'eau.

32. Roadmap et extensions possibles

Le système est conçu pour rester simple. Voici des extensions envisageables sans casser la norme (elles restent optionnelles et hors périmètre du cœur) :

Le principe directeur reste : le cœur doit rester léger. Toute extension se greffe sur les fichiers, sans introduire de runtime obligatoire.

33. Glossaire

34. Checklist de mise en production

Avant de considérer le RAG « en production », vérifiez :

• .rag présent à la racine, pointant vers une racine RAG existante.
• Noms 100% conformes (a-z0-9-, minuscules, tirets, sans accents/espaces).
• Chaque .md a un frontmatter valide avec les champs requis (title, summary, type, status, tags, updated).
• INDEX.md, RELATIONS.yaml, OVERVIEW.md régénérés et à jour.
• Aucun lien cassé (W001), aucun impl_refs absent (W003).
• status reflète la réalité (needs-review sur dérive détectée, stable après vérification).
• Les skills et commandes sont installés dans la configuration du CLI (et visibles après redémarrage).
• AGENTS.md présent à la racine du dépôt pour l'aiguillage automatique.
• La base est versionnée (git) avec le code.
• Aucun secret dans les .md ni impl_refs.
• L'équipe a adopté la règle : une tâche n'est pas finie tant que les .md ne sont pas mis à jour.

Conclusion. Le RAG natif IA par fichiers Markdown n'est pas une technologie de plus à déployer : c'est un changement de posture. La documentation cesse d'être un artefact externe, périphérique et perpétuellement en retard, pour devenir un citoyen de premier rang du dépôt — versionné, vérifiable, fidèle au code, et consommable par l'IA au moindre coût. Léger par conception, scalable par sharding, et auto-guérissant par ses index dérivés, il s'installe en minutes et s'adapte à n'importe quel environnement d'IA en ligne de commande. Tout ce qu'il faut pour commencer tient dans un fichier .rag, un répertoire, et la volonté de traiter la connaissance comme du code.