npm - living-ai-documentation - Versions diffs - 3.36.0 → 3.38.0 - Mend

living-ai-documentation 3.36.0 → 3.38.0

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 (80) hide show

package/README.fr.md CHANGED Viewed

@@ -6,365 +6,316 @@
 [🇬🇧 Read in English](./README.md)
-> **Hub local de documentation Markdown avec serveur MCP intégré , vos agents de code créent les ADR, dessinent les diagrammes et détectent la dérive pendant que vous codez.**
+> **Un atelier local pour générer, maintenir, versionner et automatiser votre documentation.**
-Du Markdown sur disque, pas de cloud, pas de base de données, pas d'étape de build. Pointez l'outil vers un dossier, ouvrez `http://localhost:4321`. Branchez n'importe quel agent IA compatible MCP (Claude Code, Claude Desktop, Cursor…) et votre documentation se maintient à mesure que le code évolue.
+**Living Documentation** n'est pas un générateur de code. C'est un outil de production documentaire : Markdown local, notes, process, ADR, diagrammes, Git, agents IA, providers LLM, images générées, MCP et automatisations.
+Tout reste dans vos fichiers. Vous lancez l'outil, vous ouvrez le navigateur, vous documentez. Puis vous pouvez brancher Git, vos agents, vos LLMs et vos workflows.
 ![npm](https://img.shields.io/npm/v/living-ai-documentation) ![Node.js](https://img.shields.io/badge/Node.js-20.19%2B-green) ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue) ![License](https://img.shields.io/badge/License-AGPL--3.0-blue) ![MCP](https://img.shields.io/badge/MCP-Streamable_HTTP-purple)
 ```bash
-npx living-ai-documentation@latest                # assistant interactif (EN/FR)
-npx living-ai-documentation@latest ./docs         # servir un dossier existant
+npx living-ai-documentation@latest
 ```
-![Viewer Living Documentation](/images/living_documentation.jpg)
+![Atelier Living Documentation](./images/DOCUMENTATION/concept-01-hero-produit.png)
+---
+## Pourquoi l'utiliser ?
+La documentation finit souvent dispersée : README, notes, tickets, captures, ADR, prompts, exports, diagrammes, conversations IA, fichiers joints. **Living Documentation** sert à remettre tout cela dans un espace local unique, lisible, versionnable et exploitable par des agents.
+| Besoin             | Ce que Living Documentation apporte                                                  |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| Écrire vite        | Éditeur Markdown, snippets, tableaux, images, fichiers joints, annotations.          |
+| Structurer         | Dossiers, catégories, conventions de nommage, recherche plein texte.                 |
+| Versionner         | Intégration Git, commits automatiques, comparaison visuelle, restauration par blocs. |
+| Visualiser         | Éditeur de diagrammes, images, exports, liens cliquables dans les documents.         |
+| Automatiser        | Workspace, providers LLM, agents réutilisables, tools MCP internes.                  |
+| Garder la maîtrise | Fichiers locaux, pas de cloud imposé, pas de base de données propriétaire.           |
 ---
-## Deux façons de l'utiliser
+## Les fonctionnalités qui changent tout
+### Documentation local-first
+Vos documents sont de simples fichiers Markdown dans un dossier.
+- lisibles dans n'importe quel éditeur
+- versionnables avec Git
+- utilisables par vos LLMs
+- portables d'un projet à l'autre
+- faciles à sauvegarder
+![Modèle local-first](./images/DOCUMENTATION/concept-03-local-first.png)
+### Git intégré, versions et restauration
-### 1. Avec un agent de code IA , la fonctionnalité phare
+Quand l'intégration Git est activée, Living Documentation peut créer un commit à chaque sauvegarde documentaire. Vous pouvez ensuite ouvrir l'historique d'un document, comparer le HEAD avec un ancien commit et restaurer des blocs précis dans le document courant.
-Living Documentation embarque un **serveur MCP** sur `POST /mcp`. N'importe quel agent compatible MCP peut lire, créer et auditer la documentation de votre projet de façon autonome.
+![Git, versions et restauration](./images/DOCUMENTATION/concept-08-git-versions-restore.png)
-| Vous dites…                                                  | L'agent déclenche…            | Ce qui se passe                                                                                                                                             |
-| ------------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| _« feature done »_ / _« feature terminée »_                  | `create-adr`                  | Cherche les ADR existants, supplante l'ADR obsolète s'il y en a un, écrit un nouvel ADR en `To be validated`, attache les fichiers source via les métadonnées. |
-| _« audit the ADRs »_ / _« vérifie la fiabilité des ADR »_    | `audit-adrs-drift`            | Liste chaque ADR sous 80 % de fiabilité et remet chacun en cohérence , re-baseline ou supersession après votre confirmation.                                |
-| _« review this ADR »_ / _« vérifie la pertinence de cet ADR »_ | `review-adr-relevance`        | Examine un seul ADR à la lumière des fichiers source liés ; rafraîchit les hashes ou propose la supersession.                                               |
-| _« backfill ADRs from git »_ / _« retrodocumente depuis git »_ | `retrodocument-adrs-from-git` | Parcourt l'historique git du plus ancien au plus récent et crée des ADR pour les décisions durables qui n'ont jamais été documentées.                       |
-| _« give me the big picture »_                                | `generate-context-diagram`    | Crée un diagramme C4 de contexte **dérivé des documents**, jamais inventé.                                                                                  |
+### Workspace, LLMs et agents
-**Tous les nouveaux ADR atterrissent en `To be validated`.** _Vous_ les promouvez. L'agent ne promeut jamais à votre place.
+Le <kbd>Workspace</kbd> permet de configurer des providers LLM et de créer des agents documentaires : traduction, correction, résumé, génération d'image, amélioration Markdown, production de brouillons, audit de documents.
-### 2. En solo, sans IA
+Les agents peuvent travailler en mode **Chat only** ou avec les **tools MCP** de Living Documentation quand le provider les accepte.
-Un hub de documentation personnel : ADR, notes de réunion, journaux de développement, plans de fonctionnalités, esquisses d'architecture , tout reste en Markdown sur disque, git-friendly, zéro vendor lock-in. Édition inline, snippets, collage d'image, pièces jointes, éditeur de diagrammes, recherche plein-texte, export PDF/HTML/Notion/Confluence.
+![Workspace providers agents](./images/DOCUMENTATION/concept-07-workspace-providers-agents.png)
-Les deux modes se mélangent librement : prenez des notes en solo toute la semaine, puis laissez votre agent enregistrer l'ADR quand la fonctionnalité est effectivement livrée.
+### Agents lancés depuis toute l'application
+Une fois créés, les agents sont disponibles depuis le menu <kbd>Agents</kbd>, quelle que soit la page ouverte. Chaque exécution produit un document de run avec statut, input, réponse, et debug optionnel.
+![Menu Agents](./images/DOCUMENTATION/execution_d_agents.png)
+### Diagrammes et schémas
+Living Documentation contient un éditeur de diagrammes intégré. Vous pouvez dessiner à la main, relier des diagrammes à des documents Markdown, exporter, ou laisser un agent proposer une première version à partir d'un document.
+![Exemple de diagramme](./images/DOCUMENTATION/exemple_diagramme_documentation.png)
+### Laboratoire d'automatisation agentique
+Avec Workspace, MCP, les providers LLM et les tools internes, Living Documentation devient un laboratoire d'automatisation appliquée à la documentation. Vous pouvez créer des agents qui lisent un document, le transforment, génèrent une image, écrivent un compte rendu ou enrichissent votre base documentaire.
+![Laboratoire agentique](./images/DOCUMENTATION/concept-12-laboratoire-agentique.png)
 ---
 ## Démarrage rapide
+Nécessite **Node.js 20.19 ou plus récent**.
 ```bash
-# Assistant interactif , crée un dossier de doc de démarrage (EN ou FR), scaffold
-# AGENTS.md / CLAUDE.md / memory/MEMORY.md à la racine du projet et crée des symlinks
-# dans <docs>/AI/ pour que les agents IA les trouvent.
+# Assistant interactif : crée un starter EN ou FR
 npx living-ai-documentation@latest
 # Ou servir un dossier existant
 npx living-ai-documentation@latest ./docs
+# Port explicite
 npx living-ai-documentation@latest ./docs --port 4000 --open
 ```
-Ensuite ouvrez [http://localhost:4321](http://localhost:4321) (viewer) et [http://localhost:4321/admin](http://localhost:4321/admin) (config).
-> L'argument du dossier doit être un **chemin relatif** (`./docs`, `../shared/docs`…). Les chemins absolus et `~` sont rejetés pour que le fichier `.living-doc.json` généré reste portable et puisse être commité.
+Puis ouvrez :
-### Installation
+- application : [http://localhost:4321](http://localhost:4321)
+- admin : [http://localhost:4321/admin](http://localhost:4321/admin)
+- MCP : [http://localhost:4321/mcp](http://localhost:4321/mcp)
-Nécessite **Node.js 20.19 ou plus récent** (Vite 8 et Commander 14 ne prennent plus en charge Node.js 18).
+Le premier lancement peut créer un starter documentaire complet, en français ou en anglais, avec des guides intégrés pour comprendre Home, Markdown, Workspace, Agents et Diagram.
-```bash
-npx living-ai-documentation@latest                 # zéro installation
-npm install -g living-ai-documentation      # global
-```
+> Le dossier passé au CLI doit être un chemin relatif (`./docs`, `../documentation`). Les chemins absolus et `~` sont rejetés pour garder `.living-doc.json` portable.
 ---
-## Connectez votre agent IA
+## Ce que contient l'application
-### Claude Code
+| Surface               | Usage                                                                     |
+| --------------------- | ------------------------------------------------------------------------- |
+| <kbd>Home</kbd>       | Lire, créer, éditer, rechercher et organiser les documents Markdown.      |
+| <kbd>Workspace</kbd>  | Configurer les providers LLM, MCP, agents et providers image.             |
+| <kbd>Agents</kbd>     | Lancer les agents depuis n'importe quelle page.                           |
+| <kbd>Diagram</kbd>    | Créer et modifier des diagrammes liés aux documents.                      |
+| <kbd>Files</kbd>      | Parcourir les fichiers joints et assets documentaires.                    |
+| <kbd>AI Context</kbd> | Inspecter le contexte IA, les règles, la mémoire et l'explorateur MCP.    |
+| <kbd>Admin</kbd>      | Configurer thème, langue, Git, patterns, sécurité fichiers, debug agents. |
-```bash
-claude mcp add --transport http living-ai-documentation http://localhost:4321/mcp
-```
+---
-Ou manuellement dans `.claude/settings.json` :
+## Écrire dans Living Documentation
-```json
-{
-  "mcpServers": {
-    "living-ai-documentation": {
-      "type": "http",
-      "url": "http://localhost:4321/mcp"
-    }
-  }
-}
-```
+Le viewer Home est aussi un éditeur Markdown.
-### Claude Desktop
+Fonctions utiles :
-Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), puis redémarrez :
+- édition inline avec sauvegarde disque
+- snippets Markdown
+- tableaux assistés
+- arbres ASCII
+- blocs repliables
+- callouts
+- images collées depuis le presse-papier
+- fichiers joints
+- annotations
+- table des matières automatique
+- recherche plein texte
-```json
-{
-  "mcpServers": {
-    "living-ai-documentation": {
-      "type": "http",
-      "url": "http://localhost:4321/mcp"
-    }
-  }
-}
-```
+Les fichiers sont classés par dossiers réels et par catégories extraites du nom :
-### Cursor, Continue, tout client MCP
+```text
+PROCESSUS/2026_06_30_10_00_[GUIDE]_preparer_une_reunion.md
+```
-Utilisez le même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sans état).
+Ici :
-> Le serveur Living Documentation doit être lancé en premier (`npx living-ai-documentation@latest ./docs`) avant que l'agent ne se connecte.
+- `PROCESSUS` est le dossier
+- `GUIDE` est la catégorie
+- `preparer_une_reunion` est le titre
 ---
-## Concepts clés
+## Git et versions
-- **Markdown sur disque** , chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
-- **Pattern de nom de fichier** , par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`. Le pattern est configurable ; la date, la catégorie et le titre sont extraits. Les fichiers qui ne correspondent pas apparaissent sous **General**.
-- **Dossiers → catégories → docs** dans la barre latérale. Les noms de dossiers deviennent les libellés ; les préfixes numériques (`1_TUTORIAL`, `2_REFERENCE`) contrôlent l'ordre sans s'afficher dans l'UI.
-- **Les ADR** sont l'enregistrement canonique des décisions. Le serveur MCP impose un frontmatter normalisé (`**date:**`, `**status:**`, `**description:**`, `**tags:**`) et un statut initial `To be validated` que seul un humain peut promouvoir.
-- **`sourceRoot`** pointe vers le code du projet. Les tools MCP source (`list_source_files`, `read_source_file`, `search_source`) et l'attache de métadonnées en dépendent. Valeur par défaut : le parent du dossier de documentation.
-- **Métadonnées de fichiers source + jauge de fiabilité** , liez un document aux fichiers source qu'il décrit. Chaque liaison stocke un SHA-256. La jauge dans l'en-tête du document (`🔴 → 🟡 → 🟢`) reflète le ratio `unchanged / total`. Dès qu'un fichier lié est modifié ou supprimé, la dérive est visible. Les **god files** (`package.json`, lock files, manifests, barrels) sont exclus par convention.
-- **Les diagrammes sont des vues dérivées** , ils citent les documents sur lesquels ils s'appuient (`evidence`). Ils ne peuvent pas introduire des concepts absents de la documentation.
+L'intégration Git est optionnelle, mais fortement recommandée.
----
+Elle permet :
-## Référence MCP
-### Tools (19)
-| Groupe                 | Tool                          | Description                                                                                                                                   |
-| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| Onboarding             | `get_server_guide`            | Retourne le guide du serveur : workflow, conventions, règles de diagrammes.                                                                   |
-| Documents              | `list_documents`              | Inventaire : `id`, `title`, `category`, `folder`, `linkHref`.                                                                                 |
-|                        | `read_document`               | Contenu Markdown brut d'un document.                                                                                                          |
-|                        | `create_document`             | Crée un nouveau fichier `.md` (nom de fichier dérivé du pattern configuré, paramètre `date` optionnel pour la rétrodocumentation).            |
-|                        | `update_document`             | Écrase un document existant (correction de dérive, supersession).                                                                             |
-| Diagrammes             | `list_diagrams`               | Liste les diagrammes sauvegardés.                                                                                                             |
-|                        | `read_diagram`                | Lit les nœuds + arêtes d'un diagramme.                                                                                                        |
-|                        | `create_diagram`              | Crée / écrase un diagramme (garde-fous côté serveur appliquent la progression C4 et les labels d'arêtes).                                     |
-| Code source (fallback) | `list_source_files`           | Liste les fichiers sous `sourceRoot` (ignore : `node_modules`, `dist`, `.git`…).                                                              |
-|                        | `read_source_file`            | Lit un fichier sous `sourceRoot`.                                                                                                             |
-|                        | `search_source`               | Recherche texte de type grep sous `sourceRoot`.                                                                                               |
-| Métadonnées            | `list_metadata`               | Liaisons de fichiers source d'un document.                                                                                                    |
-|                        | `get_accuracy`                | Statut par entrée (`unchanged` / `modified` / `missing`) + accuracy pondérée ∈ [0, 1].                                                        |
-|                        | `add_metadata`                | Lie un fichier source (chemin sous `sourceRoot`), enregistre le SHA-256. **Ignore les god files.**                                            |
-|                        | `remove_metadata`             | Détache une liaison (idempotent , pour les renommages/suppressions).                                                                          |
-|                        | `refresh_metadata`            | Re-hashe chaque liaison (re-baseline après une mise à jour).                                                                                  |
-| Audit ADR              | `list_adrs_below_accuracy`    | Jusqu'à 10 ADR dont l'accuracy < 80 %, triés du plus dégradé au moins dégradé. Exclut `SuperSeeded` et les non-ADR.                           |
-|                        | `review_adr_relevance`        | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state` qui pilote l'arbre de décision du LLM.                          |
-| Rétrodocumentation     | `retrodocument_adrs_from_git` | Jusqu'à 200 commits git (du plus ancien) classés `candidate` / `trivial` / `merge`, avec flags god-file. Pour backfiller les ADR manquants.   |
-### Prompts (10)
-| Groupe           | Prompt                        | Quand                                                                                                                  |
-| ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Cycle de vie ADR | `create-adr`                  | Une fonctionnalité vient d'être implémentée ou modifiée. Enregistre la décision, supplante un ADR antérieur le cas échéant. |
-|                  | `audit-adrs-drift`            | Audit par lot : ramener chaque ADR en dérive à un état clair (re-baseline ou supersession confirmée par l'utilisateur). |
-|                  | `review-adr-relevance`        | Examen d'un seul ADR à la lumière des fichiers source liés.                                                             |
-|                  | `retrodocument-adrs-from-git` | Backfill d'ADR depuis l'historique git quand le projet en manque.                                                       |
-| Diagrammes       | `generate-context-diagram`    | DÉFAUT. Diagramme C4 de contexte, gardé côté serveur.                                                                   |
-|                  | `generate-container-diagram`  | Sur demande explicite uniquement. Diagramme C4 de conteneur d'un système.                                                |
-|                  | `generate-uml-diagram`        | Sur demande explicite uniquement. UML classe/séquence/état/activité/cas d'utilisation.                                   |
-|                  | `generate-screen-guide`       | Sur demande explicite uniquement. Capture d'écran annotée avec callouts post-it.                                         |
-|                  | `update-diagram-from-docs`    | Relit les documents source pour mettre à jour les diagrammes existants.                                                  |
-|                  | `flow`, `erd`                 | Diagrammes de flux linéaire / entité-relation.                                                                            |
-Un `GET http://localhost:4321/mcp` retourne les schémas live des tools + prompts pour inspection.
+- commits automatiques après les sauvegardes
+- push désactivé ou push tous les N commits
+- avertissement si Git n'est pas configuré
+- détection des changements hors dossier documentaire
+- bouton <kbd>Versions</kbd> sur les documents
+- diff visuel entre HEAD et un commit sélectionné
+- restauration de blocs depuis une ancienne version
----
+Living Documentation ne commit que le dossier documentaire configuré. Les changements hors de ce dossier sont ignorés et signalés.
-## Fonctionnalités d'édition
+---
-- **Éditeur inline** , éditez n'importe quel document dans le navigateur, sauvegarde instantanée sur disque.
-- **Panneau Snippets** (`🧩 Snippets`) , constructions Markdown préfabriquées au curseur : blocs repliables, liens (intra-doc, inter-doc, ancre), listes, blocs de code, blockquotes, séparateurs, images. Plus un **éditeur de tableaux** (grille dynamique → tableau Markdown aligné) et un **éditeur d'arborescence** (indentation → arbre ASCII avec `├──` / `└──`). Sélectionner un snippet existant **détecte son type** et pré-remplit le formulaire pour édition.
-- **Collage d'image** , collez depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, inséré en Markdown.
-- **Pièces jointes** , glissez, déposez, collez ou choisissez tout fichier non-image (PDF, archive, document bureautique). Uploadé sous `<docs>/files/`, inséré comme un pill trombone. Extensions bloquées et limites de taille configurables dans l'Admin.
-- **Recherche plein-texte** , filtre instantané par nom de fichier + recherche serveur dans le contenu ; pour chaque fichier, liste chaque occurrence, les surligne et permet de naviguer vers elles.
-- **Préfixe de recherche `metadata://<nomdefichier>`** , recherche inversée : quels documents référencent cette pièce jointe ?
-- **Annotations** , marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
-- **Navigation par ancre** , `[label](#heading-slug)` scrolle correctement après rendu asynchrone ; IDs auto-générés.
-- **Mode sombre** , suit la préférence système, basculable manuellement. Coloration syntaxique toujours en mode sombre.
+## Agents et MCP
-![Sidebar groupé par dossier → catégorie](/images/readme-sidebar.png)
+Living Documentation expose un serveur MCP local sur :
-![Recherche plein-texte](/images/readme-intelligent-search-demo.jpg)
+```text
+http://localhost:4321/mcp
+```
----
+Les agents compatibles MCP peuvent utiliser les tools internes pour :
-## Éditeur de diagrammes
+- lister et lire les documents
+- créer ou mettre à jour un document
+- gérer les métadonnées
+- générer des diagrammes
+- générer des images via un provider image configuré
+- lire le sourceRoot quand c'est nécessaire
+- sauvegarder un contexte d'exécution
-Éditeur de diagrammes canvas intégré (vis-network), accessible via `/diagram?id=...`.
+L'endpoint `GET /mcp` retourne les schémas live des tools et prompts disponibles. Le README ne duplique volontairement pas cette liste : elle évolue avec le produit.
-- **Progression C4 imposée** , contexte d'abord (défaut), conteneur/composant uniquement sur demande explicite. UML sur demande explicite.
-- **`kind` architectural vs `renderAs` visuel** , sépare le concept (`software_system`, `database`, `queue`, `api`, `cloud_service`…) de la forme (`box`, `ellipse`, `database`, `actor`, `post-it`…). Le MCP choisit des valeurs par défaut pertinentes pour chaque `kind`.
-- **Provenance documentaire (`evidence`)** , chaque nœud/arête architectural peut citer le document et la section qui le justifient. L'éditeur signale les warnings d'evidence manquante.
-- **Bibliothèques de formes personnalisées** sur `/shape-editor` , définissez vos propres formes (icônes SVG, ports, couleurs par défaut) et réutilisez-les dans tous les diagrammes.
-- **Ports** pour arêtes ancrées, **guides d'alignement**, **undo/redo**, **snap-to-grid**, **collage d'images**, **export PNG**, **deep-link** vers un diagramme par id.
+### Exemple Claude Code
----
+```bash
+claude mcp add --transport http living-ai-documentation http://localhost:4321/mcp
+```
-## Organisation des fichiers
+### Exemple Claude Desktop
-```
-docs/
-├── 2024_01_15_09_30_[DevOps]_deploy.md          → catégorie : DevOps
-├── 1_tutorial/                                   → dossier : Tutorial (préfixe caché dans l'UI)
-│   └── 2024_03_01_10_00_[Onboarding]_setup.md   → dossier : Tutorial / catégorie : Onboarding
-├── adrs/
-│   └── 2024_04_01_10_15_[Architecture]_event_sourcing.md
-└── 2_reference/
-    └── api.md                                    → dossier : Reference / catégorie : General
+```json
+{
+  "mcpServers": {
+    "living-ai-documentation": {
+      "type": "http",
+      "url": "http://localhost:4321/mcp"
+    }
+  }
+}
 ```
-- Le tag `[Category]` est extrait du nom de fichier quel que soit le dossier.
-- Les fichiers sans `[Category]` tombent sous **General**. **General** est toujours rendu en premier.
-- Les dossiers sont triés alphabétiquement , préfixez par `1_`, `2_`… pour forcer un ordre ; le préfixe est caché dans l'UI mais visible au survol.
-- L'imbrication de sous-dossiers est supportée récursivement.
-![Pattern de nom de fichier](/images/readme-filename-pattern.png)
+Même endpoint pour Cursor, Continue ou tout client MCP compatible Streamable HTTP.
 ---
-## Configuration (`.living-doc.json`)
+## Configuration
+La configuration est stockée dans `.living-doc.json`, dans le dossier documentaire.
-Créé automatiquement dans votre dossier de documentation au premier lancement. Modifiable depuis l'Admin ou à la main.
+Exemple :
 ```json
 {
   "filenamePattern": "YYYY_MM_DD_HH_mm_[Category]_title",
   "title": "Living Documentation",
   "theme": "system",
+  "language": "fr",
   "port": 4321,
-  "extraFiles": ["../README.md", "../CLAUDE.md"],
-  "sourceRoot": "../src",
-  "blockedFileExtensions": [".exe", ".bin"]
+  "sourceRoot": "..",
+  "extraFiles": [],
+  "gitIntegration": {
+    "mode": "enabled",
+    "pushMode": "never",
+    "pushEveryCommits": 1,
+    "commitMessage": "docs: update living documentation"
+  }
 }
 ```
-| Champ                   | Rôle                                                                                                                                             |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `filenamePattern`       | Convention de nom de fichier utilisée pour extraire date / catégorie / titre. Le token `[Category]` est obligatoire, exactement une fois.        |
-| `extraFiles`            | Fichiers Markdown ordonnés **hors** du dossier docs (ex. `README.md`, `CLAUDE.md`). Affichés en premier dans General.                            |
-| `sourceRoot`            | Où vit votre code (relatif au dossier docs). Défaut : `..`. Utilisé par les tools MCP source + métadonnées.                                      |
-| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable depuis l'Admin.                                                                     |
+Points importants :
-**Tous les chemins sont relatifs POSIX** pour que `.living-doc.json` reste portable. Les chemins absolus legacy sont migrés silencieusement à la première lecture.
-![Extra files](/images/readme-extra-files.png)
+- les chemins sont stockés en relatif quand c'est possible
+- `sourceRoot` sert aux tools source et aux agents
+- `[Category]` est utilisé pour classer les documents
+- Git peut rester non configuré, désactivé, ou activé explicitement
+- les extensions de fichiers jointes peuvent être bloquées dans Admin
 ---
-## Export
-| Format                  | Endpoint                    | Notes                                                              |
-| ----------------------- | --------------------------- | ------------------------------------------------------------------ |
-| PDF (par document)      | `POST /api/export/html`     | Boîte de dialogue d'impression du navigateur depuis le HTML rendu. |
-| HTML , mode Notion      | `POST /api/export/html`     | Bundle HTML unique adapté à l'import Notion.                       |
-| HTML , mode Confluence  | `POST /api/export/html`     | Bundle HTML zippé adapté à l'import Confluence.                    |
-| Bundle Markdown         | `POST /api/export/markdown` | Zip de tous les documents avec liens normalisés.                   |
+## Exports
----
+Living Documentation sait exporter :
-## Surfaces de l'UI
-| URL             | Page                                                                                                      |
-| --------------- | --------------------------------------------------------------------------------------------------------- |
-| `/`             | Viewer , sidebar, rendu de document, édition inline, snippets, recherche, pièces jointes.                  |
-| `/admin`        | Config , titre, thème, pattern de nom de fichier, extra files, source root, liste de sécurité des fichiers. |
-| `/diagram?id=`  | Éditeur de diagrammes (vis-network) avec conventions C4, ports, guides d'alignement, undo/redo.             |
-| `/shape-editor` | Éditeur de bibliothèques de formes personnalisées , icônes SVG, couleurs par défaut, ports.                 |
-| `/context`      | Page de contexte IA , instructions, règles, mémoire, **explorateur MCP** (testez les tools en live dans le navigateur). |
+- un document en HTML imprimable / PDF navigateur
+- un bundle HTML pour Notion ou Confluence
+- un bundle Markdown complet
+- des diagrammes en image ou `.drawio` selon le cas
 ---
-## API REST
-<details>
-<summary>API HTTP complète (cliquer pour déplier)</summary>
-| Méthode  | Endpoint                       | Description                                                                                                               |
-| -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
-| `GET`    | `/api/documents`               | Liste les documents avec métadonnées (inclut les extra files).                                                            |
-| `GET`    | `/api/documents/:id`           | Contenu du document + HTML rendu.                                                                                         |
-| `POST`   | `/api/documents`               | Crée à partir de `{ title, category, folder?, content?, date? }`.                                                         |
-| `PUT`    | `/api/documents/:id`           | Sauvegarde le contenu sur disque.                                                                                         |
-| `DELETE` | `/api/documents/:id`           | Supprime un document.                                                                                                     |
-| `GET`    | `/api/documents/search?q=`     | Recherche plein-texte.                                                                                                    |
-| `GET`    | `/api/config`                  | Lit la configuration.                                                                                                     |
-| `PUT`    | `/api/config`                  | Met à jour la configuration (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`…). |
-| `GET`    | `/api/browse?path=`            | Liste les dossiers et fichiers `.md` à un chemin donné.                                                                   |
-| `POST`   | `/api/browse/mkdir`            | Crée un dossier sous la racine docs.                                                                                      |
-| `POST`   | `/api/images/upload`           | Upload d'une image base64 → `<docs>/images/`.                                                                             |
-| `POST`   | `/api/files/upload`            | Upload d'une pièce jointe base64 → `<docs>/files/`.                                                                       |
-| `GET`    | `/api/files`                   | Liste toutes les pièces jointes (ordre chronologique).                                                                    |
-| `PUT`    | `/api/files/:filename`         | Remplace une pièce jointe.                                                                                                |
-| `DELETE` | `/api/files/:filename`         | Supprime une pièce jointe.                                                                                                |
-| `GET`    | `/api/metadata/:docId`         | Rapport de fiabilité pour un document.                                                                                    |
-| `POST`   | `/api/metadata/:docId`         | Ajoute ou remplace une liaison.                                                                                           |
-| `DELETE` | `/api/metadata/:docId`         | Retire une liaison.                                                                                                       |
-| `POST`   | `/api/metadata/:docId/refresh` | Re-baseline les hashes.                                                                                                   |
-| `GET`    | `/api/browse-source?path=`     | Navigue dans l'arbre source ancré sur `sourceRoot`.                                                                       |
-| `GET`    | `/api/diagrams`                | Liste les diagrammes sauvegardés.                                                                                         |
-| `GET`    | `/api/diagrams/:id`            | Lit un diagramme (nœuds + arêtes).                                                                                        |
-| `PUT`    | `/api/diagrams/:id`            | Crée ou met à jour un diagramme.                                                                                          |
-| `DELETE` | `/api/diagrams/:id`            | Supprime un diagramme.                                                                                                    |
-| `GET`    | `/api/shape-libraries`         | Liste les bibliothèques de formes personnalisées.                                                                         |
-| `PUT`    | `/api/shape-libraries/:id`     | Sauvegarde une bibliothèque de formes.                                                                                    |
-| `GET`    | `/api/annotations[/:docId]`    | Liste les annotations (tous les docs / un doc).                                                                           |
-| `POST`   | `/api/annotations/:docId`      | Ajoute une annotation.                                                                                                    |
-| `DELETE` | `/api/annotations/:docId/:id`  | Supprime une annotation.                                                                                                  |
-| `POST`   | `/api/export/html`             | Export HTML , modes Notion / Confluence.                                                                                  |
-| `POST`   | `/api/export/markdown`         | Export bundle Markdown.                                                                                                   |
-| `GET`    | `/api/wordcloud?path=&ext=`    | Concatène récursivement les fichiers source correspondants en texte brut.                                                 |
-| `POST`   | `/mcp`                         | Endpoint Model Context Protocol (Streamable HTTP).                                                                        |
-| `GET`    | `/mcp`                         | Résumé live des schémas tools + prompts.                                                                                  |
-</details>
----
-## Build et test
+## Développement local
 ```bash
 git clone https://github.com/craftskillz/living-documentation.git
 cd living-documentation
 npm install
-npm run setup-hooks                      # une fois : active .githooks/ comme core.hooksPath
-npm run dev -- ./documentation          # Vite (UI sur :5174, HMR) + backend Express (:4321)
-npm run build                            # tsc (serveur) + vite build (UI → dist/frontend-svelte)
-npm run test:e2e                         # Playwright end-to-end (~3 s, ~30 specs MCP)
-npm run test:coverage                    # couverture c8 V8-natif
+npm run dev -- ./documentation
 ```
-En **dev**, ouvrez l'UI sur **http://localhost:5174** (Vite sert l'app Svelte avec HMR et proxifie `/api`, `/mcp`, `/images`, `/files` vers le backend Express sur `:4321`).
+En développement :
+- UI Vite : [http://localhost:5174](http://localhost:5174)
+- backend Express : [http://localhost:4321](http://localhost:4321)
+- proxy Vite : `/api`, `/mcp`, `/images`, `/files`
-Les tests end-to-end utilisent **Playwright**. Chaque test lance un vrai processus CLI enfant sur un fixture frais sur un port aléatoire , pas de fuite d'état, exécution en parallèle. Couverture côté serveur via **c8** (V8 natif, ~72 % de référence globale, 83 % sur `src/routes` et `src/lib`).
+Commandes utiles :
-### Tester le package publié en local
+```bash
+npm run build
+npm run test:e2e
+npm run test:coverage
+npm run setup-hooks
+```
-Pas besoin de publier une version. Le CLI démarre un **serveur Express unique** qui sert l'UI Svelte pré-buildée **et** l'API/MCP sur un seul port , Vite (`:5174`) est uniquement pour le développement et n'existe pas pour les utilisateurs finaux.
+Pour tester le package comme il sera publié :
 ```bash
-# Lancer l'artefact de production exact, puis ouvrir http://localhost:4321
 npm run build
 node dist/bin/cli.js ./documentation
-# Le plus fidèle : construire le tarball que npm publierait (respecte "files"), puis le lancer
-npm pack                                 # → living-ai-documentation-<version>.tgz
+npm pack
 npx ./living-ai-documentation-*.tgz ./documentation
-npm pack --dry-run                       # inspecter exactement quels fichiers seraient publiés
 ```
-> En production, il n'y a pas de `:5174`. L'endpoint MCP auquel les clients se connectent est **`http://localhost:4321/mcp`** (Express, port par défaut).
+> En production, il n'y a pas de serveur Vite sur `:5174`. Le CLI sert l'UI, l'API et MCP depuis Express, sur le port configuré.
+---
-### Contribuer
+## Contribution
+Le dépôt applique un contrat de README bilingue : si vous modifiez `README.fr.md`, vous devez aussi mettre à jour `README.md`, et inversement.
+Activez les hooks locaux après le clone :
+```bash
+npm run setup-hooks
+```
-Ce dépôt embarque un hook `pre-commit` (dans `.githooks/`) qui impose le contrat de README bilingue : si vous touchez `README.md`, vous devez aussi toucher `README.fr.md`, et inversement. Lancez `npm run setup-hooks` une fois après le clone pour l'activer. La même vérification s'exécute en CI sur chaque PR (voir `.github/workflows/readme-sync.yml`), donc la règle est appliquée même si un contributeur oublie la configuration locale.
+La même vérification tourne en CI via `.github/workflows/readme-sync.yml`.
 ---
 ## Licence
-[AGPL-3.0](./LICENSE) , © Youssef MEDAGHRI-ALAOUI.
+[AGPL-3.0](./LICENSE), © Youssef MEDAGHRI-ALAOUI.