living-documentation 8.10.0 → 8.12.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.
- package/README.fr.md +344 -0
- package/README.md +112 -101
- package/images/living_documentation.jpg +0 -0
- package/images/readme-intelligent-search-demo.jpg +0 -0
- package/package.json +3 -1
- package/images/living_documentation.png +0 -0
- package/images/readme-code-blocks.png +0 -0
- package/images/readme-intelligent-search-demo.png +0 -0
package/README.fr.md
ADDED
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
# Living Documentation
|
|
2
|
+
|
|
3
|
+
[🇬🇧 Read in English](./README.md)
|
|
4
|
+
|
|
5
|
+
> **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.**
|
|
6
|
+
|
|
7
|
+
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.
|
|
8
|
+
|
|
9
|
+
    
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx living-documentation # assistant interactif (EN/FR)
|
|
13
|
+
npx living-documentation ./docs # servir un dossier existant
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Deux usages
|
|
21
|
+
|
|
22
|
+
### 1. Avec un agent IA — la fonctionnalité phare
|
|
23
|
+
|
|
24
|
+
Living Documentation embarque un **serveur MCP** sur `POST /mcp`. N'importe quel agent compatible MCP peut lire, créer et auditer la documentation projet de façon autonome.
|
|
25
|
+
|
|
26
|
+
| Ce que vous dites… | Ce que l'agent déclenche… | Ce qui se passe |
|
|
27
|
+
| ------------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| _« feature terminée »_ / _"feature done"_ | `create-adr` | Cherche les ADR existants, supplante l'ADR obsolète s'il y en a, écrit un nouvel ADR en `To be validated`, relie les fichiers source via les métadonnées. |
|
|
29
|
+
| _« audite les ADR »_ / _"audit the ADRs"_ | `audit-adrs-drift` | Liste chaque ADR sous 80 % de fiabilité et remet chacun en cohérence — soit re-baseliner les hashes, soit supplanter après confirmation. |
|
|
30
|
+
| _« vérifie la pertinence de cet ADR »_ / _"review this ADR"_ | `review-adr-relevance` | Revue d'un ADR précis contre les fichiers source liés ; rafraîchit les hashes ou propose la supersession. |
|
|
31
|
+
| _« retrodocumente depuis git »_ / _"backfill ADRs from 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 jamais documentées. |
|
|
32
|
+
| _« donne-moi la big picture »_ | `generate-context-diagram` | Crée un diagramme C4 de contexte **dérivé des documents**, jamais inventé. |
|
|
33
|
+
|
|
34
|
+
**Tous les nouveaux ADR atterrissent en `To be validated`.** _Vous_ les promouvez. L'agent ne promeut jamais à votre place.
|
|
35
|
+
|
|
36
|
+
### 2. Sans IA, en solo
|
|
37
|
+
|
|
38
|
+
Un hub doc personnel : ADR, notes de réunion, journal de dev, plans de features, esquisses d'architecture — tout reste en Markdown sur disque, git-friendly, zéro lock-in. Édition inline, snippets, paste d'image, pièces jointes, éditeur de diagrammes, recherche plein-texte, export PDF/HTML/Notion/Confluence.
|
|
39
|
+
|
|
40
|
+
Les deux modes se mélangent : prendre des notes en solo toute la semaine, puis laisser l'agent enregistrer l'ADR quand la feature est livrée.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Démarrage rapide
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# Assistant interactif — crée un dossier de doc de démarrage (EN ou FR), scaffold
|
|
48
|
+
# AGENTS.md / CLAUDE.md / memory/MEMORY.md à la racine du projet et fait des symlinks
|
|
49
|
+
# dans <docs>/AI/ pour que les agents IA les trouvent.
|
|
50
|
+
npx living-documentation
|
|
51
|
+
|
|
52
|
+
# Ou servir un dossier existant
|
|
53
|
+
npx living-documentation ./docs
|
|
54
|
+
npx living-documentation ./docs --port 4000 --open
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Puis ouvrez [http://localhost:4321](http://localhost:4321) (viewer) et [http://localhost:4321/admin](http://localhost:4321/admin) (config).
|
|
58
|
+
|
|
59
|
+
> Le chemin du dossier doit être **relatif** (`./docs`, `../shared/docs`…). Les chemins absolus et `~` sont rejetés pour que `.living-doc.json` reste portable et soit committable.
|
|
60
|
+
|
|
61
|
+
### Installation
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npx living-documentation # sans installation
|
|
65
|
+
npm install -g living-documentation # global
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Connecter votre agent IA
|
|
71
|
+
|
|
72
|
+
### Claude Code
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
claude mcp add --transport http living-documentation http://localhost:4321/mcp
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Ou manuellement dans `.claude/settings.json` :
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"living-documentation": {
|
|
84
|
+
"type": "http",
|
|
85
|
+
"url": "http://localhost:4321/mcp"
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Claude Desktop
|
|
92
|
+
|
|
93
|
+
Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), puis redémarrer :
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"mcpServers": {
|
|
98
|
+
"living-documentation": {
|
|
99
|
+
"type": "http",
|
|
100
|
+
"url": "http://localhost:4321/mcp"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Cursor, Continue, tout client MCP
|
|
107
|
+
|
|
108
|
+
Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sans état).
|
|
109
|
+
|
|
110
|
+
> Le serveur Living Documentation doit tourner (`npx living-documentation ./docs`) avant que l'agent ne s'y connecte.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Concepts centraux
|
|
115
|
+
|
|
116
|
+
- **Markdown sur disque** — chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
|
|
117
|
+
- **Pattern de nom de fichier** — par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`. Configurable ; date, catégorie et titre sont extraits. Les fichiers hors pattern apparaissent sous **General**.
|
|
118
|
+
- **Dossiers → catégories → docs** dans le sidebar. Les noms de dossiers deviennent les libellés ; un préfixe numérique (`1_TUTORIAL`, `2_REFERENCE`) contrôle l'ordre sans s'afficher dans l'UI.
|
|
119
|
+
- **Les ADR** sont le journal 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 promeut.
|
|
120
|
+
- **`sourceRoot`** désigne 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. Défaut : parent du dossier de doc.
|
|
121
|
+
- **Métadonnées source + jauge de fiabilité** — lier un document à ses fichiers source. Chaque lien stocke un SHA-256. La jauge dans le header (`🔴 → 🟡 → 🟢`) reflète `unchanged / total`. Dès qu'un fichier change ou disparaît, la dérive est visible. Les **god files** (`package.json`, lock files, manifests, barrels) sont exclus par convention.
|
|
122
|
+
- **Les diagrammes sont des vues dérivées** — ils citent les documents qui les justifient (`evidence`). Ils ne peuvent pas introduire un concept absent de la documentation.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## Référence MCP
|
|
127
|
+
|
|
128
|
+
### Tools (19)
|
|
129
|
+
|
|
130
|
+
| Groupe | Tool | Description |
|
|
131
|
+
| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| Onboarding | `get_server_guide` | Retourne le guide du serveur : workflow, conventions, règles des diagrammes. |
|
|
133
|
+
| Documents | `list_documents` | Inventaire : `id`, `title`, `category`, `folder`, `linkHref`. |
|
|
134
|
+
| | `read_document` | Contenu Markdown brut d'un document. |
|
|
135
|
+
| | `create_document` | Crée un nouveau `.md` (nom de fichier dérivé du pattern, paramètre `date` optionnel pour la rétro-doc). |
|
|
136
|
+
| | `update_document` | Écrase un document existant (correction de dérive, supersession). |
|
|
137
|
+
| Diagrammes | `list_diagrams` | Liste les diagrammes sauvegardés. |
|
|
138
|
+
| | `read_diagram` | Lit les nœuds + arêtes d'un diagramme. |
|
|
139
|
+
| | `create_diagram` | Crée / écrase un diagramme (garde-fous serveur : progression C4 et labels d'arêtes). |
|
|
140
|
+
| Code source (fallback) | `list_source_files` | Liste les fichiers sous `sourceRoot` (ignore : `node_modules`, `dist`, `.git`…). |
|
|
141
|
+
| | `read_source_file` | Lit un fichier sous `sourceRoot`. |
|
|
142
|
+
| | `search_source` | Recherche grep-like sous `sourceRoot`. |
|
|
143
|
+
| Métadonnées | `list_metadata` | Fichiers source liés à un document. |
|
|
144
|
+
| | `get_accuracy` | Statut par entrée (`unchanged` / `modified` / `missing`) + accuracy pondérée ∈ [0, 1]. |
|
|
145
|
+
| | `add_metadata` | Attache un fichier source (chemin sous `sourceRoot`), enregistre SHA-256. **Saute les god files.** |
|
|
146
|
+
| | `remove_metadata` | Détache un lien (idempotent — pour renames/deletes). |
|
|
147
|
+
| | `refresh_metadata` | Re-hashe chaque lien (re-baseline après une mise à jour). |
|
|
148
|
+
| Audit ADR | `list_adrs_below_accuracy` | Jusqu'à 10 ADR dont l'accuracy < 80 %, triés du plus dégradé. Exclut `SuperSeeded` et non-ADR. |
|
|
149
|
+
| | `review_adr_relevance` | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state` pour piloter le LLM. |
|
|
150
|
+
| Rétrodocumentation | `retrodocument_adrs_from_git` | Jusqu'à 200 commits git (du plus ancien), classés `candidate` / `trivial` / `merge`, avec flags god-files. Pour backfiller les ADR manquants. |
|
|
151
|
+
|
|
152
|
+
### Prompts (10)
|
|
153
|
+
|
|
154
|
+
| Groupe | Prompt | Quand l'invoquer |
|
|
155
|
+
| ---------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
156
|
+
| Cycle de vie ADR | `create-adr` | Une feature vient d'être implémentée ou modifiée. Enregistre la décision, supersede l'ADR antérieur si pertinent. |
|
|
157
|
+
| | `audit-adrs-drift` | Audit batch : ramener chaque ADR en dérive à un état clair (re-baseline ou supersession confirmée). |
|
|
158
|
+
| | `review-adr-relevance` | Revue d'un ADR précis contre ses fichiers source liés. |
|
|
159
|
+
| | `retrodocument-adrs-from-git` | Backfill d'ADR depuis l'historique git quand le projet en manque. |
|
|
160
|
+
| Diagrammes | `generate-context-diagram` | DÉFAUT. Diagramme C4 de contexte, gardé serveur. |
|
|
161
|
+
| | `generate-container-diagram` | Sur demande explicite. Diagramme C4 conteneur d'un système. |
|
|
162
|
+
| | `generate-uml-diagram` | Sur demande explicite. UML classe/séquence/état/activité/cas d'usage. |
|
|
163
|
+
| | `generate-screen-guide` | Sur demande explicite. Capture annotée avec post-it callouts. |
|
|
164
|
+
| | `update-diagram-from-docs` | Relit les documents source pour mettre à jour les diagrammes existants. |
|
|
165
|
+
| | `flow`, `erd` | Diagrammes flow linéaires / entité-relation. |
|
|
166
|
+
|
|
167
|
+
Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et prompts pour inspection.
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Fonctionnalités d'édition
|
|
172
|
+
|
|
173
|
+
- **Éditeur inline** — édition de n'importe quel document dans le navigateur, sauvegarde disque instantanée.
|
|
174
|
+
- **Panneau Snippets** (`🧩 Snippets`) — constructions Markdown pré-fabriquées au curseur : blocs repliables, liens (in-doc, cross-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 → ASCII tree avec `├──` / `└──`). Sélectionner un snippet existant **détecte son type** et pré-remplit le formulaire pour édition.
|
|
175
|
+
- **Paste d'image** — colle depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, insertion en Markdown.
|
|
176
|
+
- **Pièces jointes** — glisser, déposer, coller ou choisir n'importe quel fichier non-image (PDF, archive, doc bureautique). Upload sous `<docs>/files/`, insertion en pill trombone. Extensions bloquées et limites configurables en Admin.
|
|
177
|
+
- **Recherche plein-texte** — filtre filename instantané + recherche serveur de contenu ; pour chaque fichier liste chaque occurrence, surlignée, navigable.
|
|
178
|
+
- **Préfixe de recherche `metadata://<nomdefichier>`** — recherche inverse : quels documents référencent cette pièce jointe ?
|
|
179
|
+
- **Annotations** — marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
|
|
180
|
+
- **Navigation par ancre** — `[label](#heading-slug)` scrolle correctement après le rendu async ; IDs auto-générés.
|
|
181
|
+
- **Mode sombre** — suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Éditeur de diagrammes
|
|
190
|
+
|
|
191
|
+
Éditeur de diagrammes canvas intégré (vis-network), accessible via `/diagram?id=...`.
|
|
192
|
+
|
|
193
|
+
- **Progression C4 imposée** — contexte d'abord (défaut), conteneur/composant seulement sur demande explicite. UML sur demande explicite.
|
|
194
|
+
- **`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 défauts sensés pour chaque `kind`.
|
|
195
|
+
- **Provenance documentaire (`evidence`)** — chaque nœud / arête architectural peut citer le document et la section qui le justifient. L'éditeur lève des warnings si l'evidence manque.
|
|
196
|
+
- **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.
|
|
197
|
+
- **Ports** pour arêtes ancrées, **guides d'alignement**, **undo/redo**, **snap-to-grid**, **paste d'image**, **export PNG**, **deep-link** vers un diagramme par id.
|
|
198
|
+
|
|
199
|
+
---
|
|
200
|
+
|
|
201
|
+
## Organisation des fichiers
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
docs/
|
|
205
|
+
├── 2024_01_15_09_30_[DevOps]_deploy.md → catégorie : DevOps
|
|
206
|
+
├── 1_tutorial/ → dossier : Tutorial (préfixe caché dans l'UI)
|
|
207
|
+
│ └── 2024_03_01_10_00_[Onboarding]_setup.md → dossier : Tutorial / catégorie : Onboarding
|
|
208
|
+
├── adrs/
|
|
209
|
+
│ └── 2024_04_01_10_15_[Architecture]_event_sourcing.md
|
|
210
|
+
└── 2_reference/
|
|
211
|
+
└── api.md → dossier : Reference / catégorie : General
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- Le tag `[Category]` est extrait du filename quel que soit le dossier.
|
|
215
|
+
- Les fichiers sans `[Category]` tombent sous **General**. **General** est toujours rendu en premier.
|
|
216
|
+
- Les dossiers sont triés alphabétiquement — préfixer par `1_`, `2_`… pour forcer un ordre ; le préfixe est caché dans l'UI mais visible au survol.
|
|
217
|
+
- L'imbrication de sous-dossiers est récursive.
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## Configuration (`.living-doc.json`)
|
|
224
|
+
|
|
225
|
+
Créé automatiquement dans votre dossier de doc au premier lancement. Modifiable depuis l'Admin ou à la main.
|
|
226
|
+
|
|
227
|
+
```json
|
|
228
|
+
{
|
|
229
|
+
"filenamePattern": "YYYY_MM_DD_HH_mm_[Category]_title",
|
|
230
|
+
"title": "Living Documentation",
|
|
231
|
+
"theme": "system",
|
|
232
|
+
"port": 4321,
|
|
233
|
+
"extraFiles": ["../README.md", "../CLAUDE.md"],
|
|
234
|
+
"sourceRoot": "../src",
|
|
235
|
+
"blockedFileExtensions": [".exe", ".bin"]
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
| Champ | Rôle |
|
|
240
|
+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `filenamePattern` | Convention de nom de fichier utilisée pour extraire date / catégorie / titre. Le token `[Category]` est obligatoire, exactement une fois. |
|
|
242
|
+
| `extraFiles` | Fichiers Markdown ordonnés **hors** du dossier docs (ex. `README.md`, `CLAUDE.md`). Affichés en premier dans General. |
|
|
243
|
+
| `sourceRoot` | Où vit votre code (relatif au dossier docs). Défaut : `..`. Utilisé par les tools MCP source + métadonnées. |
|
|
244
|
+
| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable en Admin. |
|
|
245
|
+
|
|
246
|
+
**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.
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Export
|
|
253
|
+
|
|
254
|
+
| Format | Endpoint | Notes |
|
|
255
|
+
| ---------------------- | --------------------------- | ------------------------------------------------------------------ |
|
|
256
|
+
| PDF (par doc) | `POST /api/export/html` | Boîte de dialogue d'impression du navigateur depuis le HTML rendu. |
|
|
257
|
+
| HTML — mode Notion | `POST /api/export/html` | Bundle HTML unique adapté à l'import Notion. |
|
|
258
|
+
| HTML — mode Confluence | `POST /api/export/html` | Bundle HTML zippé adapté à l'import Confluence. |
|
|
259
|
+
| Bundle Markdown | `POST /api/export/markdown` | Zip de tous les documents avec liens normalisés. |
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Surfaces UI
|
|
264
|
+
|
|
265
|
+
| URL | Page |
|
|
266
|
+
| --------------- | ---------------------------------------------------------------------------------------------------- |
|
|
267
|
+
| `/` | Viewer — sidebar, rendu document, édition inline, snippets, recherche, pièces jointes. |
|
|
268
|
+
| `/admin` | Config — titre, thème, pattern de filename, extra files, source root, liste de sécurité fichiers. |
|
|
269
|
+
| `/diagram?id=` | Éditeur de diagrammes (vis-network) avec conventions C4, ports, guides d'alignement, undo/redo. |
|
|
270
|
+
| `/shape-editor` | Éditeur de bibliothèques de formes personnalisées — icônes SVG, couleurs par défaut, ports. |
|
|
271
|
+
| `/context` | Page de contexte IA — instructions, règles, mémoire, **explorateur MCP** (tester les tools en live). |
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## API REST
|
|
276
|
+
|
|
277
|
+
<details>
|
|
278
|
+
<summary>API HTTP complète (cliquer pour déplier)</summary>
|
|
279
|
+
|
|
280
|
+
| Méthode | Endpoint | Description |
|
|
281
|
+
| -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
|
|
282
|
+
| `GET` | `/api/documents` | Liste les documents avec métadonnées (inclut extra files). |
|
|
283
|
+
| `GET` | `/api/documents/:id` | Contenu du document + HTML rendu. |
|
|
284
|
+
| `POST` | `/api/documents` | Crée depuis `{ title, category, folder?, content?, date? }`. |
|
|
285
|
+
| `PUT` | `/api/documents/:id` | Sauvegarde du contenu sur disque. |
|
|
286
|
+
| `DELETE` | `/api/documents/:id` | Supprime un document. |
|
|
287
|
+
| `GET` | `/api/documents/search?q=` | Recherche plein-texte. |
|
|
288
|
+
| `GET` | `/api/config` | Lit la config. |
|
|
289
|
+
| `PUT` | `/api/config` | Met à jour la config (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`, …). |
|
|
290
|
+
| `GET` | `/api/browse?path=` | Liste les dossiers et `.md` à un chemin. |
|
|
291
|
+
| `POST` | `/api/browse/mkdir` | Crée un dossier sous la racine docs. |
|
|
292
|
+
| `POST` | `/api/images/upload` | Upload d'image base64 → `<docs>/images/`. |
|
|
293
|
+
| `POST` | `/api/files/upload` | Upload de pièce jointe base64 → `<docs>/files/`. |
|
|
294
|
+
| `GET` | `/api/files` | Liste toutes les pièces jointes (chronologique). |
|
|
295
|
+
| `PUT` | `/api/files/:filename` | Remplace une pièce jointe. |
|
|
296
|
+
| `DELETE` | `/api/files/:filename` | Supprime une pièce jointe. |
|
|
297
|
+
| `GET` | `/api/metadata/:docId` | Rapport de fiabilité d'un doc. |
|
|
298
|
+
| `POST` | `/api/metadata/:docId` | Ajoute ou remplace un lien. |
|
|
299
|
+
| `DELETE` | `/api/metadata/:docId` | Retire un lien. |
|
|
300
|
+
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline les hashes. |
|
|
301
|
+
| `GET` | `/api/browse-source?path=` | Navigue l'arbre source ancré sur `sourceRoot`. |
|
|
302
|
+
| `GET` | `/api/diagrams` | Liste les diagrammes sauvegardés. |
|
|
303
|
+
| `GET` | `/api/diagrams/:id` | Lit un diagramme (nœuds + arêtes). |
|
|
304
|
+
| `PUT` | `/api/diagrams/:id` | Crée ou met à jour un diagramme. |
|
|
305
|
+
| `DELETE` | `/api/diagrams/:id` | Supprime un diagramme. |
|
|
306
|
+
| `GET` | `/api/shape-libraries` | Liste les bibliothèques de formes personnalisées. |
|
|
307
|
+
| `PUT` | `/api/shape-libraries/:id` | Sauvegarde une bibliothèque de formes. |
|
|
308
|
+
| `GET` | `/api/annotations[/:docId]` | Liste les annotations (tous docs / un doc). |
|
|
309
|
+
| `POST` | `/api/annotations/:docId` | Ajoute une annotation. |
|
|
310
|
+
| `DELETE` | `/api/annotations/:docId/:id` | Supprime une annotation. |
|
|
311
|
+
| `POST` | `/api/export/html` | Export HTML — modes Notion / Confluence. |
|
|
312
|
+
| `POST` | `/api/export/markdown` | Export bundle Markdown. |
|
|
313
|
+
| `GET` | `/api/wordcloud?path=&ext=` | Concatène récursivement les fichiers source filtrés en texte brut. |
|
|
314
|
+
| `POST` | `/mcp` | Endpoint Model Context Protocol (Streamable HTTP). |
|
|
315
|
+
| `GET` | `/mcp` | Résumé live des schémas tools + prompts. |
|
|
316
|
+
|
|
317
|
+
</details>
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## Build et test
|
|
322
|
+
|
|
323
|
+
```bash
|
|
324
|
+
git clone https://github.com/craftskillz/living-documentation.git
|
|
325
|
+
cd living-documentation
|
|
326
|
+
npm install
|
|
327
|
+
npm run setup-hooks # une fois : active .githooks/ comme core.hooksPath
|
|
328
|
+
npm run dev -- ./documentation # nodemon + ts-node, watch src + bin
|
|
329
|
+
npm run build # tsc → dist/ + copie des assets frontend
|
|
330
|
+
npm run test:e2e # Playwright end-to-end (~3 s, ~30 specs MCP)
|
|
331
|
+
npm run test:coverage # couverture c8 V8-natif
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
Les tests end-to-end utilisent **Playwright**. Chaque test lance un vrai process CLI enfant sur un fixture frais sur un port aléatoire — pas de fuite d'état, parallélisable. Couverture serveur via **c8** (V8 natif, ~72 % global, 83 % sur `src/routes` et `src/lib`).
|
|
335
|
+
|
|
336
|
+
### Contribuer
|
|
337
|
+
|
|
338
|
+
Ce dépôt embarque un hook `pre-commit` (dans `.githooks/`) qui impose le contrat bilingue des README : 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. Le même check tourne en CI sur chaque PR (`.github/workflows/readme-sync.yml`), donc la règle est imposée même si un contributeur oublie le setup local.
|
|
339
|
+
|
|
340
|
+
---
|
|
341
|
+
|
|
342
|
+
## Licence
|
|
343
|
+
|
|
344
|
+
[AGPL-3.0](./LICENSE) — © Youssef MEDAGHRI-ALAOUI.
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Living Documentation
|
|
2
2
|
|
|
3
|
+
[🇫🇷 Lire en français](./README.fr.md)
|
|
4
|
+
|
|
3
5
|
> **Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams, and detect drift while you code.**
|
|
4
6
|
|
|
5
7
|
Markdown on disk, no cloud, no database, no build step. Point it at a folder, open `http://localhost:4321`. Plug any MCP-aware AI agent into it (Claude Code, Claude Desktop, Cursor…) and your documentation maintains itself as your code evolves.
|
|
@@ -11,7 +13,7 @@ npx living-documentation # interactive wizard (EN/FR)
|
|
|
11
13
|
npx living-documentation ./docs # serve an existing folder
|
|
12
14
|
```
|
|
13
15
|
|
|
14
|
-
|
|
15
17
|
|
|
16
18
|
---
|
|
17
19
|
|
|
@@ -21,15 +23,15 @@ npx living-documentation ./docs # serve an existing folder
|
|
|
21
23
|
|
|
22
24
|
Living Documentation ships an **MCP server** on `POST /mcp`. Any MCP-aware agent can read, create and audit your project's documentation autonomously.
|
|
23
25
|
|
|
24
|
-
| You say…
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
26
|
+
| You say… | The agent triggers… | What happens |
|
|
27
|
+
| ---------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| _"feature done"_ / _"feature terminée"_ | `create-adr` | Searches existing ADRs, supersedes the obsolete one if any, writes a new ADR at `To be validated`, binds the source files via metadata. |
|
|
29
|
+
| _"audit the ADRs"_ / _"vérifie la fiabilité des ADR"_ | `audit-adrs-drift` | Lists every ADR below 80% reliability and brings each back in sync — re-baseline or supersede after your confirmation. |
|
|
30
|
+
| _"review this ADR"_ / _"vérifie la pertinence de cet ADR"_ | `review-adr-relevance` | Reviews a single ADR against the bound source files; refreshes hashes or proposes supersession. |
|
|
31
|
+
| _"backfill ADRs from git"_ / _"retrodocumente depuis git"_ | `retrodocument-adrs-from-git` | Walks git history oldest-first and creates ADRs for the durable decisions that were never documented. |
|
|
32
|
+
| _"give me the big picture"_ | `generate-context-diagram` | Creates a C4 context diagram **derived from the docs**, never invented. |
|
|
31
33
|
|
|
32
|
-
**All new ADRs land at `To be validated`.**
|
|
34
|
+
**All new ADRs land at `To be validated`.** _You_ promote them. The agent never promotes on your behalf.
|
|
33
35
|
|
|
34
36
|
### 2. Solo, no AI
|
|
35
37
|
|
|
@@ -78,7 +80,10 @@ Or manually in `.claude/settings.json`:
|
|
|
78
80
|
```json
|
|
79
81
|
{
|
|
80
82
|
"mcpServers": {
|
|
81
|
-
"living-documentation": {
|
|
83
|
+
"living-documentation": {
|
|
84
|
+
"type": "http",
|
|
85
|
+
"url": "http://localhost:4321/mcp"
|
|
86
|
+
}
|
|
82
87
|
}
|
|
83
88
|
}
|
|
84
89
|
```
|
|
@@ -90,7 +95,10 @@ In `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), th
|
|
|
90
95
|
```json
|
|
91
96
|
{
|
|
92
97
|
"mcpServers": {
|
|
93
|
-
"living-documentation": {
|
|
98
|
+
"living-documentation": {
|
|
99
|
+
"type": "http",
|
|
100
|
+
"url": "http://localhost:4321/mcp"
|
|
101
|
+
}
|
|
94
102
|
}
|
|
95
103
|
}
|
|
96
104
|
```
|
|
@@ -119,42 +127,42 @@ Use the same HTTP endpoint: `http://localhost:4321/mcp` (Streamable HTTP transpo
|
|
|
119
127
|
|
|
120
128
|
### Tools (19)
|
|
121
129
|
|
|
122
|
-
| Group
|
|
123
|
-
|
|
|
124
|
-
| Onboarding
|
|
125
|
-
| Documents
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
| Diagrams
|
|
130
|
-
|
|
|
131
|
-
|
|
|
132
|
-
| Source code (fallback) | `list_source_files`
|
|
133
|
-
|
|
|
134
|
-
|
|
|
135
|
-
| Metadata
|
|
136
|
-
|
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
| ADR audit
|
|
141
|
-
|
|
|
142
|
-
| Retrodocumentation
|
|
130
|
+
| Group | Tool | Description |
|
|
131
|
+
| ---------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| Onboarding | `get_server_guide` | Returns the server guide: workflow, conventions, diagram rules. |
|
|
133
|
+
| Documents | `list_documents` | Inventory: `id`, `title`, `category`, `folder`, `linkHref`. |
|
|
134
|
+
| | `read_document` | Raw Markdown content of a document. |
|
|
135
|
+
| | `create_document` | Create a new `.md` file (filename from configured pattern, optional `date` override for retrodoc). |
|
|
136
|
+
| | `update_document` | Overwrite an existing doc (drift correction, supersede). |
|
|
137
|
+
| Diagrams | `list_diagrams` | List saved diagrams. |
|
|
138
|
+
| | `read_diagram` | Read nodes + edges of one diagram. |
|
|
139
|
+
| | `create_diagram` | Create / overwrite a diagram (server-side guardrails enforce C4 progression and edge labels). |
|
|
140
|
+
| Source code (fallback) | `list_source_files` | List files under `sourceRoot` (ignored: `node_modules`, `dist`, `.git`…). |
|
|
141
|
+
| | `read_source_file` | Read a file under `sourceRoot`. |
|
|
142
|
+
| | `search_source` | Grep-like text search under `sourceRoot`. |
|
|
143
|
+
| Metadata | `list_metadata` | Source-file bindings of a doc. |
|
|
144
|
+
| | `get_accuracy` | Per-entry status (`unchanged` / `modified` / `missing`) + weighted accuracy ∈ [0, 1]. |
|
|
145
|
+
| | `add_metadata` | Bind a source file (path under `sourceRoot`), records SHA-256. **Skips god files.** |
|
|
146
|
+
| | `remove_metadata` | Detach a binding (idempotent — for renames/deletes). |
|
|
147
|
+
| | `refresh_metadata` | Re-hash every binding (re-baseline after an update). |
|
|
148
|
+
| ADR audit | `list_adrs_below_accuracy` | Up to 10 ADRs whose accuracy < 80%, sorted most-degraded first. Excludes `SuperSeeded` and non-ADRs. |
|
|
149
|
+
| | `review_adr_relevance` | Factual report on one ADR + drifted files to re-read. Returns a `state` to drive the LLM decision tree. |
|
|
150
|
+
| Retrodocumentation | `retrodocument_adrs_from_git` | Up to 200 git commits (oldest first) classified `candidate` / `trivial` / `merge`, with god-file flags. Used to backfill missing ADRs. |
|
|
143
151
|
|
|
144
152
|
### Prompts (10)
|
|
145
153
|
|
|
146
|
-
| Group
|
|
147
|
-
|
|
|
148
|
-
| ADR lifecycle | `create-adr` | A feature has just been implemented or modified. Records the decision, supersedes a prior ADR if any.
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
| Diagrams
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
154
|
+
| Group | Prompt | When |
|
|
155
|
+
| ------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------- |
|
|
156
|
+
| ADR lifecycle | `create-adr` | A feature has just been implemented or modified. Records the decision, supersedes a prior ADR if any. |
|
|
157
|
+
| | `audit-adrs-drift` | Batch audit: bring every drifting ADR back to a clear state (re-baseline or user-confirmed supersession). |
|
|
158
|
+
| | `review-adr-relevance` | Single ADR review against its bound source files. |
|
|
159
|
+
| | `retrodocument-adrs-from-git` | Backfill ADRs from git history when the project lacks them. |
|
|
160
|
+
| Diagrams | `generate-context-diagram` | DEFAULT. C4 context diagram, gated server-side. |
|
|
161
|
+
| | `generate-container-diagram` | Explicit-only. C4 container diagram of one system. |
|
|
162
|
+
| | `generate-uml-diagram` | Explicit-only. UML class/sequence/state/activity/use-case. |
|
|
163
|
+
| | `generate-screen-guide` | Explicit-only. Annotated screenshot with post-it callouts. |
|
|
164
|
+
| | `update-diagram-from-docs` | Re-read source documents to update existing diagrams. |
|
|
165
|
+
| | `flow`, `erd` | Linear flow / entity-relationship diagrams. |
|
|
158
166
|
|
|
159
167
|
A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for inspection.
|
|
160
168
|
|
|
@@ -174,7 +182,7 @@ A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for ins
|
|
|
174
182
|
|
|
175
183
|
|
|
176
184
|
|
|
177
|
-
|
|
178
186
|
|
|
179
187
|
---
|
|
180
188
|
|
|
@@ -228,12 +236,12 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
228
236
|
}
|
|
229
237
|
```
|
|
230
238
|
|
|
231
|
-
| Field
|
|
232
|
-
|
|
|
233
|
-
| `filenamePattern`
|
|
234
|
-
| `extraFiles`
|
|
235
|
-
| `sourceRoot`
|
|
236
|
-
| `blockedFileExtensions` | File-attachment safety list, editable from Admin.
|
|
239
|
+
| Field | Role |
|
|
240
|
+
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `filenamePattern` | Filename convention used to parse date / category / title. `[Category]` token mandatory, exactly once. |
|
|
242
|
+
| `extraFiles` | Ordered Markdown files **outside** the docs folder (e.g. `README.md`, `CLAUDE.md`). Shown in General first. |
|
|
243
|
+
| `sourceRoot` | Where your code lives (relative to docs folder). Defaults to `..`. Used by MCP source + metadata tools. |
|
|
244
|
+
| `blockedFileExtensions` | File-attachment safety list, editable from Admin. |
|
|
237
245
|
|
|
238
246
|
**All paths are relative POSIX** so `.living-doc.json` stays portable. Legacy absolute paths are silently migrated on first read.
|
|
239
247
|
|
|
@@ -243,26 +251,24 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
243
251
|
|
|
244
252
|
## Export
|
|
245
253
|
|
|
246
|
-
| Format
|
|
247
|
-
|
|
|
248
|
-
| PDF (per doc)
|
|
249
|
-
| HTML — Notion mode
|
|
250
|
-
| HTML — Confluence mode
|
|
251
|
-
| Markdown bundle
|
|
254
|
+
| Format | Endpoint | Notes |
|
|
255
|
+
| ---------------------- | --------------------------- | -------------------------------------------------- |
|
|
256
|
+
| PDF (per doc) | `POST /api/export/html` | Browser print dialog from the rendered HTML. |
|
|
257
|
+
| HTML — Notion mode | `POST /api/export/html` | Single HTML bundle suitable for Notion import. |
|
|
258
|
+
| HTML — Confluence mode | `POST /api/export/html` | Zipped HTML bundle suitable for Confluence import. |
|
|
259
|
+
| Markdown bundle | `POST /api/export/markdown` | Zip of every document with normalized links. |
|
|
252
260
|
|
|
253
261
|
---
|
|
254
262
|
|
|
255
263
|
## UI surfaces
|
|
256
264
|
|
|
257
|
-
| URL
|
|
258
|
-
|
|
|
259
|
-
| `/`
|
|
260
|
-
| `/admin`
|
|
261
|
-
| `/diagram?id=`
|
|
262
|
-
| `/shape-editor`
|
|
263
|
-
| `/context`
|
|
264
|
-
|
|
265
|
-
|
|
265
|
+
| URL | Page |
|
|
266
|
+
| --------------- | -------------------------------------------------------------------------------------------- |
|
|
267
|
+
| `/` | Viewer — sidebar, document rendering, inline edit, snippets, search, attachments. |
|
|
268
|
+
| `/admin` | Config — title, theme, filename pattern, extra files, source root, file safety list. |
|
|
269
|
+
| `/diagram?id=` | Diagram editor (vis-network) with C4 conventions, ports, alignment guides, undo/redo. |
|
|
270
|
+
| `/shape-editor` | Custom shape library editor — SVG icons, default colors, ports. |
|
|
271
|
+
| `/context` | AI context page — instructions, rules, memory, **MCP explorer** (try tools live in-browser). |
|
|
266
272
|
|
|
267
273
|
---
|
|
268
274
|
|
|
@@ -271,42 +277,42 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
271
277
|
<details>
|
|
272
278
|
<summary>Full HTTP API (click to expand)</summary>
|
|
273
279
|
|
|
274
|
-
| Method | Endpoint | Description
|
|
275
|
-
| -------- | ------------------------------ |
|
|
276
|
-
| `GET` | `/api/documents` | List documents with metadata (includes extra files).
|
|
277
|
-
| `GET` | `/api/documents/:id` | Document content + rendered HTML.
|
|
278
|
-
| `POST` | `/api/documents` | Create from `{ title, category, folder?, content?, date? }`.
|
|
279
|
-
| `PUT` | `/api/documents/:id` | Save content to disk.
|
|
280
|
-
| `DELETE` | `/api/documents/:id` | Delete a document.
|
|
281
|
-
| `GET` | `/api/documents/search?q=` | Full-text search.
|
|
282
|
-
| `GET` | `/api/config` | Read config.
|
|
280
|
+
| Method | Endpoint | Description |
|
|
281
|
+
| -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
282
|
+
| `GET` | `/api/documents` | List documents with metadata (includes extra files). |
|
|
283
|
+
| `GET` | `/api/documents/:id` | Document content + rendered HTML. |
|
|
284
|
+
| `POST` | `/api/documents` | Create from `{ title, category, folder?, content?, date? }`. |
|
|
285
|
+
| `PUT` | `/api/documents/:id` | Save content to disk. |
|
|
286
|
+
| `DELETE` | `/api/documents/:id` | Delete a document. |
|
|
287
|
+
| `GET` | `/api/documents/search?q=` | Full-text search. |
|
|
288
|
+
| `GET` | `/api/config` | Read config. |
|
|
283
289
|
| `PUT` | `/api/config` | Update config (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`, …). |
|
|
284
|
-
| `GET` | `/api/browse?path=` | List directories and `.md` files at a path.
|
|
285
|
-
| `POST` | `/api/browse/mkdir` | Create a folder under the docs root.
|
|
286
|
-
| `POST` | `/api/images/upload` | Upload a base64 image → `<docs>/images/`.
|
|
287
|
-
| `POST` | `/api/files/upload` | Upload a base64 attachment → `<docs>/files/`.
|
|
288
|
-
| `GET` | `/api/files` | List every attachment (chronological).
|
|
289
|
-
| `PUT` | `/api/files/:filename` | Replace an attachment.
|
|
290
|
-
| `DELETE` | `/api/files/:filename` | Delete an attachment.
|
|
291
|
-
| `GET` | `/api/metadata/:docId` | Reliability report for one doc.
|
|
292
|
-
| `POST` | `/api/metadata/:docId` | Add or replace a binding.
|
|
293
|
-
| `DELETE` | `/api/metadata/:docId` | Remove a binding.
|
|
294
|
-
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline hashes.
|
|
295
|
-
| `GET` | `/api/browse-source?path=` | Navigate the source tree rooted at `sourceRoot`.
|
|
296
|
-
| `GET` | `/api/diagrams` | List saved diagrams.
|
|
297
|
-
| `GET` | `/api/diagrams/:id` | Read a single diagram (nodes + edges).
|
|
298
|
-
| `PUT` | `/api/diagrams/:id` | Create or update a diagram.
|
|
299
|
-
| `DELETE` | `/api/diagrams/:id` | Delete a diagram.
|
|
300
|
-
| `GET` | `/api/shape-libraries` | List custom shape libraries.
|
|
301
|
-
| `PUT` | `/api/shape-libraries/:id` | Save a shape library.
|
|
302
|
-
| `GET` | `/api/annotations[/:docId]` | List annotations (all docs / one doc).
|
|
303
|
-
| `POST` | `/api/annotations/:docId` | Add an annotation.
|
|
304
|
-
| `DELETE` | `/api/annotations/:docId/:id` | Delete one annotation.
|
|
305
|
-
| `POST` | `/api/export/html` | HTML export — Notion / Confluence modes.
|
|
306
|
-
| `POST` | `/api/export/markdown` | Markdown bundle export.
|
|
307
|
-
| `GET` | `/api/wordcloud?path=&ext=` | Recursively concatenate matching source files as raw text.
|
|
308
|
-
| `POST` | `/mcp` | Model Context Protocol endpoint (Streamable HTTP).
|
|
309
|
-
| `GET` | `/mcp` | Live tool + prompt schema summary.
|
|
290
|
+
| `GET` | `/api/browse?path=` | List directories and `.md` files at a path. |
|
|
291
|
+
| `POST` | `/api/browse/mkdir` | Create a folder under the docs root. |
|
|
292
|
+
| `POST` | `/api/images/upload` | Upload a base64 image → `<docs>/images/`. |
|
|
293
|
+
| `POST` | `/api/files/upload` | Upload a base64 attachment → `<docs>/files/`. |
|
|
294
|
+
| `GET` | `/api/files` | List every attachment (chronological). |
|
|
295
|
+
| `PUT` | `/api/files/:filename` | Replace an attachment. |
|
|
296
|
+
| `DELETE` | `/api/files/:filename` | Delete an attachment. |
|
|
297
|
+
| `GET` | `/api/metadata/:docId` | Reliability report for one doc. |
|
|
298
|
+
| `POST` | `/api/metadata/:docId` | Add or replace a binding. |
|
|
299
|
+
| `DELETE` | `/api/metadata/:docId` | Remove a binding. |
|
|
300
|
+
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline hashes. |
|
|
301
|
+
| `GET` | `/api/browse-source?path=` | Navigate the source tree rooted at `sourceRoot`. |
|
|
302
|
+
| `GET` | `/api/diagrams` | List saved diagrams. |
|
|
303
|
+
| `GET` | `/api/diagrams/:id` | Read a single diagram (nodes + edges). |
|
|
304
|
+
| `PUT` | `/api/diagrams/:id` | Create or update a diagram. |
|
|
305
|
+
| `DELETE` | `/api/diagrams/:id` | Delete a diagram. |
|
|
306
|
+
| `GET` | `/api/shape-libraries` | List custom shape libraries. |
|
|
307
|
+
| `PUT` | `/api/shape-libraries/:id` | Save a shape library. |
|
|
308
|
+
| `GET` | `/api/annotations[/:docId]` | List annotations (all docs / one doc). |
|
|
309
|
+
| `POST` | `/api/annotations/:docId` | Add an annotation. |
|
|
310
|
+
| `DELETE` | `/api/annotations/:docId/:id` | Delete one annotation. |
|
|
311
|
+
| `POST` | `/api/export/html` | HTML export — Notion / Confluence modes. |
|
|
312
|
+
| `POST` | `/api/export/markdown` | Markdown bundle export. |
|
|
313
|
+
| `GET` | `/api/wordcloud?path=&ext=` | Recursively concatenate matching source files as raw text. |
|
|
314
|
+
| `POST` | `/mcp` | Model Context Protocol endpoint (Streamable HTTP). |
|
|
315
|
+
| `GET` | `/mcp` | Live tool + prompt schema summary. |
|
|
310
316
|
|
|
311
317
|
</details>
|
|
312
318
|
|
|
@@ -318,6 +324,7 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
318
324
|
git clone https://github.com/craftskillz/living-documentation.git
|
|
319
325
|
cd living-documentation
|
|
320
326
|
npm install
|
|
327
|
+
npm run setup-hooks # one-time: enable .githooks/ as core.hooksPath
|
|
321
328
|
npm run dev -- ./documentation # nodemon + ts-node, watches src + bin
|
|
322
329
|
npm run build # tsc → dist/ + copy frontend assets
|
|
323
330
|
npm run test:e2e # Playwright end-to-end (~3 s, ~30 MCP specs)
|
|
@@ -326,6 +333,10 @@ npm run test:coverage # c8 V8-native coverage
|
|
|
326
333
|
|
|
327
334
|
End-to-end tests use **Playwright**. Each test spawns a real CLI child process against a fresh fixture on a random port — no leaking state, runs in parallel. Server-side coverage via **c8** (V8 native, ~72% baseline overall, 83% on `src/routes` and `src/lib`).
|
|
328
335
|
|
|
336
|
+
### Contributing
|
|
337
|
+
|
|
338
|
+
This repository ships with a `pre-commit` hook (under `.githooks/`) that enforces the bilingual README contract: if you touch `README.md` you must also touch `README.fr.md`, and vice-versa. Run `npm run setup-hooks` once after cloning to activate it. The same check runs in CI on every PR (see `.github/workflows/readme-sync.yml`), so the rule is enforced even if a contributor forgets the local setup.
|
|
339
|
+
|
|
329
340
|
---
|
|
330
341
|
|
|
331
342
|
## License
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "living-documentation",
|
|
3
|
-
"version": "8.
|
|
3
|
+
"version": "8.12.0",
|
|
4
4
|
"description": "Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams and detect drift while you code.",
|
|
5
5
|
"main": "dist/src/server.js",
|
|
6
6
|
"bin": {
|
|
@@ -20,6 +20,8 @@
|
|
|
20
20
|
"test:e2e": "npm run build && playwright test",
|
|
21
21
|
"test:e2e:ui": "playwright test --ui",
|
|
22
22
|
"test:coverage": "rm -rf coverage && npm run build && mkdir -p coverage/tmp && COVERAGE=1 NODE_V8_COVERAGE=coverage/tmp playwright test && c8 report",
|
|
23
|
+
"setup-hooks": "git config core.hooksPath .githooks && echo '✓ Git hooks active (.githooks/pre-commit)'",
|
|
24
|
+
"check:readme-sync": "./scripts/check-readme-sync.sh",
|
|
23
25
|
"prepublishOnly": "npm run build"
|
|
24
26
|
},
|
|
25
27
|
"keywords": [
|
|
Binary file
|
|
Binary file
|
|
Binary file
|