living-documentation 8.9.0 → 8.11.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 +340 -0
- package/README.md +228 -393
- package/images/living_documentation.png +0 -0
- package/images/readme-code-blocks.png +0 -0
- package/images/readme-extra-files.png +0 -0
- package/images/readme-filename-pattern.png +0 -0
- package/images/readme-intelligent-search-demo.png +0 -0
- package/images/readme-sidebar.png +0 -0
- package/package.json +20 -4
package/README.fr.md
ADDED
|
@@ -0,0 +1,340 @@
|
|
|
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": { "type": "http", "url": "http://localhost:4321/mcp" }
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Claude Desktop
|
|
89
|
+
|
|
90
|
+
Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), puis redémarrer :
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"living-documentation": { "type": "http", "url": "http://localhost:4321/mcp" }
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Cursor, Continue, tout client MCP
|
|
101
|
+
|
|
102
|
+
Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sans état).
|
|
103
|
+
|
|
104
|
+
> Le serveur Living Documentation doit tourner (`npx living-documentation ./docs`) avant que l'agent ne s'y connecte.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Concepts centraux
|
|
109
|
+
|
|
110
|
+
- **Markdown sur disque** — chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
|
|
111
|
+
- **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**.
|
|
112
|
+
- **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.
|
|
113
|
+
- **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.
|
|
114
|
+
- **`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.
|
|
115
|
+
- **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.
|
|
116
|
+
- **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.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Référence MCP
|
|
121
|
+
|
|
122
|
+
### Tools (19)
|
|
123
|
+
|
|
124
|
+
| Groupe | Tool | Description |
|
|
125
|
+
| --------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
126
|
+
| Onboarding | `get_server_guide` | Retourne le guide du serveur : workflow, conventions, règles des diagrammes. |
|
|
127
|
+
| Documents | `list_documents` | Inventaire : `id`, `title`, `category`, `folder`, `linkHref`. |
|
|
128
|
+
| | `read_document` | Contenu Markdown brut d'un document. |
|
|
129
|
+
| | `create_document` | Crée un nouveau `.md` (nom de fichier dérivé du pattern, paramètre `date` optionnel pour la rétro-doc). |
|
|
130
|
+
| | `update_document` | Écrase un document existant (correction de dérive, supersession). |
|
|
131
|
+
| Diagrammes | `list_diagrams` | Liste les diagrammes sauvegardés. |
|
|
132
|
+
| | `read_diagram` | Lit les nœuds + arêtes d'un diagramme. |
|
|
133
|
+
| | `create_diagram` | Crée / écrase un diagramme (garde-fous serveur : progression C4 et labels d'arêtes). |
|
|
134
|
+
| Code source (fallback) | `list_source_files` | Liste les fichiers sous `sourceRoot` (ignore : `node_modules`, `dist`, `.git`…). |
|
|
135
|
+
| | `read_source_file` | Lit un fichier sous `sourceRoot`. |
|
|
136
|
+
| | `search_source` | Recherche grep-like sous `sourceRoot`. |
|
|
137
|
+
| Métadonnées | `list_metadata` | Fichiers source liés à un document. |
|
|
138
|
+
| | `get_accuracy` | Statut par entrée (`unchanged` / `modified` / `missing`) + accuracy pondérée ∈ [0, 1]. |
|
|
139
|
+
| | `add_metadata` | Attache un fichier source (chemin sous `sourceRoot`), enregistre SHA-256. **Saute les god files.** |
|
|
140
|
+
| | `remove_metadata` | Détache un lien (idempotent — pour renames/deletes). |
|
|
141
|
+
| | `refresh_metadata` | Re-hashe chaque lien (re-baseline après une mise à jour). |
|
|
142
|
+
| Audit ADR | `list_adrs_below_accuracy` | Jusqu'à 10 ADR dont l'accuracy < 80 %, triés du plus dégradé. Exclut `SuperSeeded` et non-ADR. |
|
|
143
|
+
| | `review_adr_relevance` | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state` pour piloter le LLM. |
|
|
144
|
+
| 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. |
|
|
145
|
+
|
|
146
|
+
### Prompts (10)
|
|
147
|
+
|
|
148
|
+
| Groupe | Prompt | Quand l'invoquer |
|
|
149
|
+
| -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
150
|
+
| 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. |
|
|
151
|
+
| | `audit-adrs-drift` | Audit batch : ramener chaque ADR en dérive à un état clair (re-baseline ou supersession confirmée). |
|
|
152
|
+
| | `review-adr-relevance` | Revue d'un ADR précis contre ses fichiers source liés. |
|
|
153
|
+
| | `retrodocument-adrs-from-git` | Backfill d'ADR depuis l'historique git quand le projet en manque. |
|
|
154
|
+
| Diagrammes | `generate-context-diagram` | DÉFAUT. Diagramme C4 de contexte, gardé serveur. |
|
|
155
|
+
| | `generate-container-diagram` | Sur demande explicite. Diagramme C4 conteneur d'un système. |
|
|
156
|
+
| | `generate-uml-diagram` | Sur demande explicite. UML classe/séquence/état/activité/cas d'usage. |
|
|
157
|
+
| | `generate-screen-guide` | Sur demande explicite. Capture annotée avec post-it callouts. |
|
|
158
|
+
| | `update-diagram-from-docs` | Relit les documents source pour mettre à jour les diagrammes existants. |
|
|
159
|
+
| | `flow`, `erd` | Diagrammes flow linéaires / entité-relation. |
|
|
160
|
+
|
|
161
|
+
Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et prompts pour inspection.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Fonctionnalités d'édition
|
|
166
|
+
|
|
167
|
+
- **Éditeur inline** — édition de n'importe quel document dans le navigateur, sauvegarde disque instantanée.
|
|
168
|
+
- **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.
|
|
169
|
+
- **Paste d'image** — colle depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, insertion en Markdown.
|
|
170
|
+
- **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.
|
|
171
|
+
- **Recherche plein-texte** — filtre filename instantané + recherche serveur de contenu ; pour chaque fichier liste chaque occurrence, surlignée, navigable.
|
|
172
|
+
- **Préfixe de recherche `metadata://<nomdefichier>`** — recherche inverse : quels documents référencent cette pièce jointe ?
|
|
173
|
+
- **Annotations** — marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
|
|
174
|
+
- **Navigation par ancre** — `[label](#heading-slug)` scrolle correctement après le rendu async ; IDs auto-générés.
|
|
175
|
+
- **Mode sombre** — suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Éditeur de diagrammes
|
|
184
|
+
|
|
185
|
+
Éditeur de diagrammes canvas intégré (vis-network), accessible via `/diagram?id=...`.
|
|
186
|
+
|
|
187
|
+
- **Progression C4 imposée** — contexte d'abord (défaut), conteneur/composant seulement sur demande explicite. UML sur demande explicite.
|
|
188
|
+
- **`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`.
|
|
189
|
+
- **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.
|
|
190
|
+
- **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.
|
|
191
|
+
- **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.
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Organisation des fichiers
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
docs/
|
|
199
|
+
├── 2024_01_15_09_30_[DevOps]_deploy.md → catégorie : DevOps
|
|
200
|
+
├── 1_tutorial/ → dossier : Tutorial (préfixe caché dans l'UI)
|
|
201
|
+
│ └── 2024_03_01_10_00_[Onboarding]_setup.md → dossier : Tutorial / catégorie : Onboarding
|
|
202
|
+
├── adrs/
|
|
203
|
+
│ └── 2024_04_01_10_15_[Architecture]_event_sourcing.md
|
|
204
|
+
└── 2_reference/
|
|
205
|
+
└── api.md → dossier : Reference / catégorie : General
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- Le tag `[Category]` est extrait du filename quel que soit le dossier.
|
|
209
|
+
- Les fichiers sans `[Category]` tombent sous **General**. **General** est toujours rendu en premier.
|
|
210
|
+
- 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.
|
|
211
|
+
- L'imbrication de sous-dossiers est récursive.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Configuration (`.living-doc.json`)
|
|
218
|
+
|
|
219
|
+
Créé automatiquement dans votre dossier de doc au premier lancement. Modifiable depuis l'Admin ou à la main.
|
|
220
|
+
|
|
221
|
+
```json
|
|
222
|
+
{
|
|
223
|
+
"filenamePattern": "YYYY_MM_DD_HH_mm_[Category]_title",
|
|
224
|
+
"title": "Living Documentation",
|
|
225
|
+
"theme": "system",
|
|
226
|
+
"port": 4321,
|
|
227
|
+
"extraFiles": ["../README.md", "../CLAUDE.md"],
|
|
228
|
+
"sourceRoot": "../src",
|
|
229
|
+
"blockedFileExtensions": [".exe", ".bin"]
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
| Champ | Rôle |
|
|
234
|
+
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
235
|
+
| `filenamePattern` | Convention de nom de fichier utilisée pour extraire date / catégorie / titre. Le token `[Category]` est obligatoire, exactement une fois. |
|
|
236
|
+
| `extraFiles` | Fichiers Markdown ordonnés **hors** du dossier docs (ex. `README.md`, `CLAUDE.md`). Affichés en premier dans General. |
|
|
237
|
+
| `sourceRoot` | Où vit votre code (relatif au dossier docs). Défaut : `..`. Utilisé par les tools MCP source + métadonnées. |
|
|
238
|
+
| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable en Admin. |
|
|
239
|
+
|
|
240
|
+
**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.
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Export
|
|
247
|
+
|
|
248
|
+
| Format | Endpoint | Notes |
|
|
249
|
+
| ------------------------ | ----------------------- | ------------------------------------------------------------------ |
|
|
250
|
+
| PDF (par doc) | `POST /api/export/html` | Boîte de dialogue d'impression du navigateur depuis le HTML rendu. |
|
|
251
|
+
| HTML — mode Notion | `POST /api/export/html` | Bundle HTML unique adapté à l'import Notion. |
|
|
252
|
+
| HTML — mode Confluence | `POST /api/export/html` | Bundle HTML zippé adapté à l'import Confluence. |
|
|
253
|
+
| Bundle Markdown | `POST /api/export/markdown` | Zip de tous les documents avec liens normalisés. |
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Surfaces UI
|
|
258
|
+
|
|
259
|
+
| URL | Page |
|
|
260
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------- |
|
|
261
|
+
| `/` | Viewer — sidebar, rendu document, édition inline, snippets, recherche, pièces jointes. |
|
|
262
|
+
| `/admin` | Config — titre, thème, pattern de filename, extra files, source root, liste de sécurité fichiers. |
|
|
263
|
+
| `/diagram?id=` | Éditeur de diagrammes (vis-network) avec conventions C4, ports, guides d'alignement, undo/redo. |
|
|
264
|
+
| `/shape-editor` | Éditeur de bibliothèques de formes personnalisées — icônes SVG, couleurs par défaut, ports. |
|
|
265
|
+
| `/context` | Page de contexte IA — instructions, règles, mémoire, **explorateur MCP** (tester les tools en live). |
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## API REST
|
|
272
|
+
|
|
273
|
+
<details>
|
|
274
|
+
<summary>API HTTP complète (cliquer pour déplier)</summary>
|
|
275
|
+
|
|
276
|
+
| Méthode | Endpoint | Description |
|
|
277
|
+
| -------- | ------------------------------ | ------------------------------------------------------------------ |
|
|
278
|
+
| `GET` | `/api/documents` | Liste les documents avec métadonnées (inclut extra files). |
|
|
279
|
+
| `GET` | `/api/documents/:id` | Contenu du document + HTML rendu. |
|
|
280
|
+
| `POST` | `/api/documents` | Crée depuis `{ title, category, folder?, content?, date? }`. |
|
|
281
|
+
| `PUT` | `/api/documents/:id` | Sauvegarde du contenu sur disque. |
|
|
282
|
+
| `DELETE` | `/api/documents/:id` | Supprime un document. |
|
|
283
|
+
| `GET` | `/api/documents/search?q=` | Recherche plein-texte. |
|
|
284
|
+
| `GET` | `/api/config` | Lit la config. |
|
|
285
|
+
| `PUT` | `/api/config` | Met à jour la config (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`, …). |
|
|
286
|
+
| `GET` | `/api/browse?path=` | Liste les dossiers et `.md` à un chemin. |
|
|
287
|
+
| `POST` | `/api/browse/mkdir` | Crée un dossier sous la racine docs. |
|
|
288
|
+
| `POST` | `/api/images/upload` | Upload d'image base64 → `<docs>/images/`. |
|
|
289
|
+
| `POST` | `/api/files/upload` | Upload de pièce jointe base64 → `<docs>/files/`. |
|
|
290
|
+
| `GET` | `/api/files` | Liste toutes les pièces jointes (chronologique). |
|
|
291
|
+
| `PUT` | `/api/files/:filename` | Remplace une pièce jointe. |
|
|
292
|
+
| `DELETE` | `/api/files/:filename` | Supprime une pièce jointe. |
|
|
293
|
+
| `GET` | `/api/metadata/:docId` | Rapport de fiabilité d'un doc. |
|
|
294
|
+
| `POST` | `/api/metadata/:docId` | Ajoute ou remplace un lien. |
|
|
295
|
+
| `DELETE` | `/api/metadata/:docId` | Retire un lien. |
|
|
296
|
+
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline les hashes. |
|
|
297
|
+
| `GET` | `/api/browse-source?path=` | Navigue l'arbre source ancré sur `sourceRoot`. |
|
|
298
|
+
| `GET` | `/api/diagrams` | Liste les diagrammes sauvegardés. |
|
|
299
|
+
| `GET` | `/api/diagrams/:id` | Lit un diagramme (nœuds + arêtes). |
|
|
300
|
+
| `PUT` | `/api/diagrams/:id` | Crée ou met à jour un diagramme. |
|
|
301
|
+
| `DELETE` | `/api/diagrams/:id` | Supprime un diagramme. |
|
|
302
|
+
| `GET` | `/api/shape-libraries` | Liste les bibliothèques de formes personnalisées. |
|
|
303
|
+
| `PUT` | `/api/shape-libraries/:id` | Sauvegarde une bibliothèque de formes. |
|
|
304
|
+
| `GET` | `/api/annotations[/:docId]` | Liste les annotations (tous docs / un doc). |
|
|
305
|
+
| `POST` | `/api/annotations/:docId` | Ajoute une annotation. |
|
|
306
|
+
| `DELETE` | `/api/annotations/:docId/:id` | Supprime une annotation. |
|
|
307
|
+
| `POST` | `/api/export/html` | Export HTML — modes Notion / Confluence. |
|
|
308
|
+
| `POST` | `/api/export/markdown` | Export bundle Markdown. |
|
|
309
|
+
| `GET` | `/api/wordcloud?path=&ext=` | Concatène récursivement les fichiers source filtrés en texte brut. |
|
|
310
|
+
| `POST` | `/mcp` | Endpoint Model Context Protocol (Streamable HTTP). |
|
|
311
|
+
| `GET` | `/mcp` | Résumé live des schémas tools + prompts. |
|
|
312
|
+
|
|
313
|
+
</details>
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## Build et test
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
git clone https://github.com/craftskillz/living-documentation.git
|
|
321
|
+
cd living-documentation
|
|
322
|
+
npm install
|
|
323
|
+
npm run setup-hooks # une fois : active .githooks/ comme core.hooksPath
|
|
324
|
+
npm run dev -- ./documentation # nodemon + ts-node, watch src + bin
|
|
325
|
+
npm run build # tsc → dist/ + copie des assets frontend
|
|
326
|
+
npm run test:e2e # Playwright end-to-end (~3 s, ~30 specs MCP)
|
|
327
|
+
npm run test:coverage # couverture c8 V8-natif
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
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`).
|
|
331
|
+
|
|
332
|
+
### Contribuer
|
|
333
|
+
|
|
334
|
+
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.
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## Licence
|
|
339
|
+
|
|
340
|
+
[AGPL-3.0](./LICENSE) — © Youssef MEDAGHRI-ALAOUI.
|
package/README.md
CHANGED
|
@@ -1,505 +1,340 @@
|
|
|
1
1
|
# Living Documentation
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
No cloud, no database, no build step — just point it at a folder where you add your project's folder documentation composed of `.md` files (ADR : Architecture Decision Records, generally).
|
|
3
|
+
[🇫🇷 Lire en français](./README.fr.md)
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
5
|
+
> **Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams, and detect drift while you code.**
|
|
9
6
|
|
|
10
|
-
|
|
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
8
|
|
|
12
|
-
|
|
9
|
+
    
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- **Audit on demand.** Ask your agent *"audit the docs"* / *"vérifie la fiabilité de la doc"* and it invokes the `audit-doc-drift` prompt: for each drifting ADR, it reads the doc and the attached source files, then either re-baselines the hashes (description still correct) or rewrites the body and re-baselines (description out of sync). Major redesigns are surfaced back to you for a fresh `create-adr` — you stay in control of structural changes.
|
|
19
|
-
- **`To be validated` by default.** New ADRs land in a review state — *you* promote them to `Accepted`. The agent never promotes on your behalf.
|
|
20
|
-
- **Diagrams that don't lie.** Context / container / UML / flow / ERD generation is gated by server-side guardrails: diagrams are *derived* from the documents, never invented.
|
|
21
|
-
|
|
22
|
-
Setup is two lines of JSON — see **[MCP server](#mcp-server-model-context-protocol)** below.
|
|
23
|
-
|
|
24
|
-
### 2. Standalone — a note-taking hub for the new-gen developer
|
|
25
|
-
|
|
26
|
-
No AI required. Run it solo as your personal docs hub for **project meetings, architecture decisions, feature plans, dev journals, ADRs you write yourself** — all kept as Markdown on disk, git-friendly, no vendor lock-in. The full toolbox (inline editor, image paste, file attachments, built-in diagram editor, word cloud, annotations, full-text search, PDF / Notion / Confluence export…) is detailed in the **Features** section below.
|
|
11
|
+
```bash
|
|
12
|
+
npx living-documentation # interactive wizard (EN/FR)
|
|
13
|
+
npx living-documentation ./docs # serve an existing folder
|
|
14
|
+
```
|
|
27
15
|
|
|
28
|
-
|
|
16
|
+
|
|
29
17
|
|
|
30
18
|
---
|
|
31
19
|
|
|
32
|
-
##
|
|
33
|
-
|
|
34
|
-
### Reliability gauge — keep your docs honest
|
|
35
|
-
|
|
36
|
-
Living Documentation's flagship feature: each document can be **bound to the source files it describes**, so you can see at a glance whether it has drifted from the code.
|
|
20
|
+
## Two ways to use it
|
|
37
21
|
|
|
38
|
-
|
|
39
|
-
- **Reliability gauge** in the sticky doc header — a red → orange → yellow → green gradient bar that fills up as `reliability = unchanged / total`. If every bound file still matches its hash, the bar is full and green; as soon as one file is modified or deleted, the gauge drops and the colour shifts. Hidden when the doc has no bindings. Click it to open the metadata modal.
|
|
40
|
-
- **Metadata Files popup** (top bar `📁 Metadata Files`) — central place to list, **replace** or **delete** every file uploaded under `DOCS_FOLDER/files/` (PDFs, specs, mockups attached to docs). After a replace/delete, the popup closes and the search bar is auto-filled with `metadata://<filename>` so you immediately see which documents still reference it.
|
|
41
|
-
- **`metadata://<filename>` search prefix** — reverse-lookup documents by the source files they're bound to. Useful to answer "which docs am I supposed to update now that I've changed this PDF/class/module?".
|
|
42
|
-
- **MCP tools** (`list_metadata`, `get_accuracy`, `add_metadata`, `refresh_metadata`) — AI agents can detect drift, read the source & the doc, rewrite the doc and re-baseline the hashes autonomously.
|
|
22
|
+
### 1. With an AI coding agent — the killer feature
|
|
43
23
|
|
|
44
|
-
|
|
24
|
+
Living Documentation ships an **MCP server** on `POST /mcp`. Any MCP-aware agent can read, create and audit your project's documentation autonomously.
|
|
45
25
|
|
|
46
|
-
|
|
47
|
-
|
|
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. |
|
|
48
33
|
|
|
49
|
-
|
|
50
|
-
ExtraFiles (added in the admin section) are always first, always expanded in a `GENERAL Section` that holds uncategorized docs and extra files
|
|
51
|
-
[](/diagram?id=d1775399110713)
|
|
34
|
+
**All new ADRs land at `To be validated`.** *You* promote them. The agent never promotes on your behalf.
|
|
52
35
|
|
|
53
|
-
|
|
36
|
+
### 2. Solo, no AI
|
|
54
37
|
|
|
55
|
-
|
|
56
|
-
[](/diagram?id=d1775399110713)
|
|
38
|
+
A personal docs hub: ADRs, meeting notes, dev journals, feature plans, architecture sketches — all kept as Markdown on disk, git-friendly, zero vendor lock-in. Inline editor, snippets, image paste, file attachments, diagram editor, full-text search, PDF/HTML/Notion/Confluence export.
|
|
57
39
|
|
|
58
|
-
|
|
59
|
-
- **Syntax highlighting** — always dark, high-contrast code blocks
|
|
60
|
-
[](/diagram?id=d1775399110713)
|
|
61
|
-
|
|
62
|
-
- **Full-text search** — instant filter + server-side content search. Returns all the files containing searched occurences, and for each file lists all the occurences, highlight them, and visit them.
|
|
63
|
-
[](/diagram?id=d1775399110713)
|
|
64
|
-
|
|
65
|
-
- **Inline editing** — edit any document directly in the browser, saves to disk instantly
|
|
66
|
-
- **Image paste** — paste an image from clipboard in the editor; auto-uploaded and inserted as Markdown
|
|
67
|
-
- **File attachments** — drag & drop, paste or pick any non-image file (PDF, archives, office docs…) in the editor; uploaded under `DOCS_FOLDER/files/` and inserted as a paperclip link. Blocked extensions and size limits are configurable from the Admin panel.
|
|
68
|
-
- **Snippet inserter** — click **🧩 Snippets** while editing to insert pre-built Markdown constructs at the cursor position:
|
|
69
|
-
- *Simple snippets*: collapsible block (`<details>`), link, link to another document, anchor link, anchor link in another document, numbered list (3 levels), bullet list (3 levels), code block, blockquote, horizontal separator, image
|
|
70
|
-
- *Complex snippets*: **table editor** (dynamic rows/columns grid, generates aligned Markdown table) and **tree editor** (indentation-based ASCII tree, generates a `text` code block with `├──` / `└──` connectors)
|
|
71
|
-
- **Detection mode**: select an existing snippet in the editor before opening the panel — the type is detected automatically and all fields are pre-filled for editing; an informational message is shown when the selection is recognised (green) or unrecognised (orange)
|
|
72
|
-
- **Anchor navigation** — links to headings within a document (e.g. `[See section](#my-heading)`) scroll to the correct position after async rendering; heading IDs are generated automatically from their text content
|
|
73
|
-
- **Export to PDF** — Export the markdown as a PDF document
|
|
74
|
-
- **Diagram editor** — built-in canvas diagram editor; deep-link to any diagram in the C4 Model Style; Paste images into diagrams; Export PNG From Images; And Many more features ...
|
|
75
|
-
|
|
76
|
-
- **Admin panel** — configure title, theme, filename pattern, and extra files in the browser
|
|
77
|
-
- **Word Cloud** — visualise the dominant vocabulary of any folder on disk; supports `.md`, `.ts`, `.java`, `.kt`, `.py`, `.go`, `.rs`, `.cs`, `.swift`, `.rb`, `.html`, `.css`, `.yml`, `.json` and more; stop words filtered per language
|
|
40
|
+
The two modes mix freely: jot notes solo all week, then let your agent record the ADR when the feature actually lands.
|
|
78
41
|
|
|
79
42
|
---
|
|
80
43
|
|
|
81
44
|
## Quick start
|
|
82
45
|
|
|
83
46
|
```bash
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
> **The folder argument must be a relative path** (`./docs`, `../shared/docs`, etc.). Absolute paths (`/abs/...`) and `~`-prefixed paths are rejected at startup so the generated `.living-doc.json` stays portable across machines and can be committed to git.
|
|
90
|
-
|
|
91
|
-
---
|
|
47
|
+
# Interactive wizard — creates a starter doc folder (EN or FR), scaffolds
|
|
48
|
+
# AGENTS.md / CLAUDE.md / memory/MEMORY.md at the project root and symlinks
|
|
49
|
+
# them into <docs>/AI/ so AI agents can find them.
|
|
50
|
+
npx living-documentation
|
|
92
51
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
### npx (no install)
|
|
96
|
-
|
|
97
|
-
```bash
|
|
52
|
+
# Or serve an existing folder
|
|
98
53
|
npx living-documentation ./docs
|
|
54
|
+
npx living-documentation ./docs --port 4000 --open
|
|
99
55
|
```
|
|
100
56
|
|
|
101
|
-
|
|
57
|
+
Then open [http://localhost:4321](http://localhost:4321) (viewer) and [http://localhost:4321/admin](http://localhost:4321/admin) (config).
|
|
102
58
|
|
|
103
|
-
|
|
104
|
-
npm install -g living-documentation
|
|
105
|
-
living-documentation ./docs
|
|
106
|
-
```
|
|
59
|
+
> The folder argument must be a **relative path** (`./docs`, `../shared/docs`…). Absolute paths and `~` are rejected so the generated `.living-doc.json` stays portable and can be committed.
|
|
107
60
|
|
|
108
|
-
###
|
|
61
|
+
### Install
|
|
109
62
|
|
|
110
63
|
```bash
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
npm install
|
|
114
|
-
npm run dev -- ./docs # nodemon + ts-node, auto-restarts on changes
|
|
64
|
+
npx living-documentation # zero-install
|
|
65
|
+
npm install -g living-documentation # global
|
|
115
66
|
```
|
|
116
67
|
|
|
117
68
|
---
|
|
118
69
|
|
|
119
|
-
##
|
|
120
|
-
|
|
121
|
-
```
|
|
122
|
-
living-documentation [folder] [options]
|
|
123
|
-
|
|
124
|
-
Arguments:
|
|
125
|
-
folder Path to the documentation folder (default: ".")
|
|
126
|
-
|
|
127
|
-
Options:
|
|
128
|
-
-p, --port <number> Port to listen on (default: 4321)
|
|
129
|
-
-o, --open Open browser automatically
|
|
130
|
-
-V, --version Print version
|
|
131
|
-
-h, --help Show help
|
|
132
|
-
```
|
|
70
|
+
## Connect your AI agent
|
|
133
71
|
|
|
134
|
-
|
|
72
|
+
### Claude Code
|
|
135
73
|
|
|
136
74
|
```bash
|
|
137
|
-
living-documentation
|
|
138
|
-
living-documentation ./docs --port 4000 --open # override port
|
|
139
|
-
living-documentation . # current folder
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
---
|
|
143
|
-
|
|
144
|
-
## Filename convention
|
|
145
|
-
|
|
146
|
-
Documents are parsed using this default pattern:
|
|
147
|
-
|
|
148
|
-
```
|
|
149
|
-
YYYY_MM_DD_HH_mm_[Category]_title_words.md
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
| Part | Example | Parsed as |
|
|
153
|
-
| ----------------- | -------------------- | ------------------------------ |
|
|
154
|
-
| `2024_01_15` | `2024_01_15` | Date → Jan 15, 2024 |
|
|
155
|
-
| `09_30` | `09_30` | Time → 09:30 |
|
|
156
|
-
| `[DevOps]` | `[DevOps]` | Category → DevOps |
|
|
157
|
-
| `deploy_pipeline` | `deploy_pipeline` | Title → Deploy Pipeline |
|
|
158
|
-
|
|
159
|
-
**Full example:**
|
|
160
|
-
|
|
161
|
-
```
|
|
162
|
-
2024_01_15_09_30_[DevOps]_deploy_pipeline.md
|
|
163
|
-
2024_03_20_14_45_[Frontend]_react_hooks_guide.md
|
|
164
|
-
2023_11_03_11_00_[Backend]_api_versioning_strategy.md
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
Files that don't match the pattern are still shown — they appear under **General** with the filename as the title.
|
|
168
|
-
|
|
169
|
-
### Subdirectories
|
|
170
|
-
|
|
171
|
-
The docs folder is scanned **recursively**. Each subdirectory level becomes a collapsible **folder** in the sidebar, nested above the category groups extracted from filenames.
|
|
172
|
-
|
|
173
|
-
- The `[Category]` tag in the filename is always the category, regardless of which folder the file lives in.
|
|
174
|
-
- Files without a `[Category]` tag fall into **General**.
|
|
175
|
-
- Subdirectory names become the folder labels in the sidebar (title-cased).
|
|
176
|
-
- Deep nesting is supported: `adrs/test/file.md` → folder **Adrs** > subfolder **Test** > category > doc.
|
|
177
|
-
|
|
178
|
-
```
|
|
179
|
-
docs/
|
|
180
|
-
├── 2024_01_15_09_30_[DevOps]_deploy.md → (root) category: DevOps
|
|
181
|
-
├── adrs/
|
|
182
|
-
│ ├── my-decision.md → folder: Adrs / category: General
|
|
183
|
-
│ ├── 2024_03_01_10_00_[Architecture]_eventsourcing.md → folder: Adrs / category: Architecture
|
|
184
|
-
│ └── test/
|
|
185
|
-
│ └── 2024_05_01_11_15_[Architecture]_saga.md → folder: Adrs > Test / category: Architecture
|
|
186
|
-
└── guides/
|
|
187
|
-
└── 2024_06_01_14_00_[Onboarding]_setup.md → folder: Guides / category: Onboarding
|
|
188
|
-
```
|
|
189
|
-
|
|
190
|
-
**Sidebar rendering order at each level:** General first → subfolders (alphabetical) → other categories (alphabetical).
|
|
191
|
-
|
|
192
|
-
#### Controlling folder order with a numeric prefix
|
|
193
|
-
|
|
194
|
-
Folders are sorted alphabetically, which means you can control their order by prefixing the directory name with a number followed by `_`:
|
|
195
|
-
|
|
196
|
-
```
|
|
197
|
-
docs/
|
|
198
|
-
├── 1_TUTORIAL/
|
|
199
|
-
├── 2_REFERENCE/
|
|
200
|
-
└── 3_ADVANCED/
|
|
75
|
+
claude mcp add --transport http living-documentation http://localhost:4321/mcp
|
|
201
76
|
```
|
|
202
77
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
**Article header** shows one violet pill per folder segment, then a blue pill for the category.
|
|
206
|
-
|
|
207
|
-
The pattern is **configurable** in the Admin panel. Token order is respected — `[Category]_YYYY_MM_DD_HH_mm_title` is valid. `[Category]` must appear exactly once.
|
|
208
|
-
|
|
209
|
-
---
|
|
210
|
-
|
|
211
|
-
## Config file
|
|
212
|
-
|
|
213
|
-
A `.living-doc.json` file is created automatically in your docs folder on first run:
|
|
78
|
+
Or manually in `.claude/settings.json`:
|
|
214
79
|
|
|
215
80
|
```json
|
|
216
81
|
{
|
|
217
|
-
"
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
"port": 4321,
|
|
221
|
-
"extraFiles": [],
|
|
222
|
-
"sourceRoot": null
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"living-documentation": { "type": "http", "url": "http://localhost:4321/mcp" }
|
|
84
|
+
}
|
|
223
85
|
}
|
|
224
86
|
```
|
|
225
87
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
You can edit this file manually or use the **Admin panel** at [http://localhost:4321/admin](http://localhost:4321/admin).
|
|
229
|
-
|
|
230
|
-
### Extra files
|
|
88
|
+
### Claude Desktop
|
|
231
89
|
|
|
232
|
-
|
|
90
|
+
In `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), then restart:
|
|
233
91
|
|
|
234
92
|
```json
|
|
235
93
|
{
|
|
236
|
-
"
|
|
237
|
-
"
|
|
238
|
-
|
|
239
|
-
]
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"living-documentation": { "type": "http", "url": "http://localhost:4321/mcp" }
|
|
96
|
+
}
|
|
240
97
|
}
|
|
241
98
|
```
|
|
242
99
|
|
|
243
|
-
|
|
100
|
+
### Cursor, Continue, any MCP client
|
|
244
101
|
|
|
245
|
-
|
|
102
|
+
Use the same HTTP endpoint: `http://localhost:4321/mcp` (Streamable HTTP transport, stateless).
|
|
246
103
|
|
|
247
|
-
The
|
|
104
|
+
> The Living Documentation server must be running first (`npx living-documentation ./docs`) before the agent connects.
|
|
248
105
|
|
|
249
106
|
---
|
|
250
107
|
|
|
251
|
-
##
|
|
108
|
+
## Core concepts
|
|
252
109
|
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
│ │ ├── documents.ts Documents API (list, search, read, write, create, delete)
|
|
261
|
-
│ │ ├── config.ts Config API
|
|
262
|
-
│ │ ├── browse.ts Filesystem browser API (+ mkdir)
|
|
263
|
-
│ │ ├── images.ts Image upload API
|
|
264
|
-
│ │ ├── files.ts File attachment upload API (paperclip)
|
|
265
|
-
│ │ ├── wordcloud.ts Word cloud raw text reader
|
|
266
|
-
│ │ ├── diagrams.ts Diagrams CRUD API (vis-network JSON)
|
|
267
|
-
│ │ ├── annotations.ts Per-document highlight markers API
|
|
268
|
-
│ │ ├── metadata.ts Source-file bindings + reliability report
|
|
269
|
-
│ │ ├── browse-source.ts Source tree navigator (rooted at sourceRoot)
|
|
270
|
-
│ │ └── export.ts HTML export (PDF, Notion, Confluence zip)
|
|
271
|
-
│ ├── mcp/
|
|
272
|
-
│ │ ├── server.ts Model Context Protocol server (Streamable HTTP)
|
|
273
|
-
│ │ └── tools/
|
|
274
|
-
│ │ ├── documents.ts MCP tools: list/read/create document
|
|
275
|
-
│ │ ├── diagrams.ts MCP tools: list/read/create diagram
|
|
276
|
-
│ │ ├── source.ts MCP tools: list/read/search source files
|
|
277
|
-
│ │ └── metadata.ts MCP tools: list_metadata, get_accuracy, add_metadata, refresh_metadata
|
|
278
|
-
│ ├── lib/
|
|
279
|
-
│ │ ├── parser.ts Filename parser
|
|
280
|
-
│ │ ├── config.ts Config management (.living-doc.json)
|
|
281
|
-
│ │ ├── metadata.ts .metadata.json store + reliability formula
|
|
282
|
-
│ │ └── hash.ts sha256File helper
|
|
283
|
-
│ └── frontend/
|
|
284
|
-
│ ├── index.html Main viewer shell
|
|
285
|
-
│ ├── admin.html Admin panel
|
|
286
|
-
│ ├── diagram.html Diagram editor shell
|
|
287
|
-
│ ├── i18n.js i18n loader (window.t + data-i18n binding)
|
|
288
|
-
│ ├── i18n/{en,fr}.json Translation catalogs
|
|
289
|
-
│ ├── wordcloud.js Word cloud logic
|
|
290
|
-
│ ├── vendor/ Vendored browser libraries (wordcloud2.js)
|
|
291
|
-
│ ├── *.js Viewer modules (state, sidebar, search, documents, …)
|
|
292
|
-
│ └── diagram/*.js Diagram editor modules (network, panels, history, …)
|
|
293
|
-
├── scripts/
|
|
294
|
-
│ └── copy-assets.ts Build helper (copies frontend + starter-doc to dist/)
|
|
295
|
-
├── starter-doc/ English starter docs shipped with the npm package
|
|
296
|
-
├── starter-doc-fr/ French starter docs shipped with the npm package
|
|
297
|
-
├── documentation/adrs/ Architecture Decision Records for this project
|
|
298
|
-
├── package.json
|
|
299
|
-
└── tsconfig.json
|
|
300
|
-
```
|
|
110
|
+
- **Markdown on disk** — each document is a `.md` file. Configuration lives in `.living-doc.json` next to it. Both are git-friendly.
|
|
111
|
+
- **Filename pattern** — default `YYYY_MM_DD_HH_mm_[Category]_title.md`. The pattern is configurable; date, category and title are parsed from it. Files that don't match still appear under **General**.
|
|
112
|
+
- **Folders → categories → docs** in the sidebar. Folder names become the labels; numeric prefixes (`1_TUTORIAL`, `2_REFERENCE`) control order without showing in the UI.
|
|
113
|
+
- **ADRs** are the canonical decision record. The MCP server enforces a normalized frontmatter (`**date:**`, `**status:**`, `**description:**`, `**tags:**`) and a `To be validated` initial status that only a human can promote.
|
|
114
|
+
- **`sourceRoot`** points to the project's code. The MCP source tools (`list_source_files`, `read_source_file`, `search_source`) and the metadata binding rely on it. Defaults to the parent of the docs folder.
|
|
115
|
+
- **Source-file metadata + reliability gauge** — bind a doc to the source files it describes. Each binding stores a SHA-256. The gauge in the doc header (`🔴 → 🟡 → 🟢`) reflects `unchanged / total`. As soon as one bound file is modified or deleted, drift is visible. **God files** (`package.json`, lock files, manifests, barrels) are excluded by convention.
|
|
116
|
+
- **Diagrams are derived views** — they cite the documents they're built from (`evidence`). They cannot introduce concepts absent from the docs.
|
|
301
117
|
|
|
302
118
|
---
|
|
303
119
|
|
|
304
|
-
##
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
|
309
|
-
|
|
|
310
|
-
|
|
|
311
|
-
| `
|
|
312
|
-
| `
|
|
313
|
-
| `
|
|
314
|
-
| `
|
|
315
|
-
|
|
|
316
|
-
| `
|
|
317
|
-
| `
|
|
318
|
-
|
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
|
|
|
322
|
-
| `
|
|
323
|
-
| `
|
|
324
|
-
| `
|
|
325
|
-
| `
|
|
326
|
-
|
|
|
327
|
-
| `
|
|
328
|
-
| `
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
|
333
|
-
|
|
|
334
|
-
|
|
|
335
|
-
| `
|
|
336
|
-
| `
|
|
337
|
-
| `
|
|
338
|
-
|
|
|
339
|
-
| `
|
|
340
|
-
| `
|
|
341
|
-
| `
|
|
120
|
+
## MCP reference
|
|
121
|
+
|
|
122
|
+
### Tools (19)
|
|
123
|
+
|
|
124
|
+
| Group | Tool | Description |
|
|
125
|
+
| -------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
126
|
+
| Onboarding | `get_server_guide` | Returns the server guide: workflow, conventions, diagram rules. |
|
|
127
|
+
| Documents | `list_documents` | Inventory: `id`, `title`, `category`, `folder`, `linkHref`. |
|
|
128
|
+
| | `read_document` | Raw Markdown content of a document. |
|
|
129
|
+
| | `create_document` | Create a new `.md` file (filename from configured pattern, optional `date` override for retrodoc). |
|
|
130
|
+
| | `update_document` | Overwrite an existing doc (drift correction, supersede). |
|
|
131
|
+
| Diagrams | `list_diagrams` | List saved diagrams. |
|
|
132
|
+
| | `read_diagram` | Read nodes + edges of one diagram. |
|
|
133
|
+
| | `create_diagram` | Create / overwrite a diagram (server-side guardrails enforce C4 progression and edge labels). |
|
|
134
|
+
| Source code (fallback) | `list_source_files` | List files under `sourceRoot` (ignored: `node_modules`, `dist`, `.git`…). |
|
|
135
|
+
| | `read_source_file` | Read a file under `sourceRoot`. |
|
|
136
|
+
| | `search_source` | Grep-like text search under `sourceRoot`. |
|
|
137
|
+
| Metadata | `list_metadata` | Source-file bindings of a doc. |
|
|
138
|
+
| | `get_accuracy` | Per-entry status (`unchanged` / `modified` / `missing`) + weighted accuracy ∈ [0, 1]. |
|
|
139
|
+
| | `add_metadata` | Bind a source file (path under `sourceRoot`), records SHA-256. **Skips god files.** |
|
|
140
|
+
| | `remove_metadata` | Detach a binding (idempotent — for renames/deletes). |
|
|
141
|
+
| | `refresh_metadata` | Re-hash every binding (re-baseline after an update). |
|
|
142
|
+
| ADR audit | `list_adrs_below_accuracy` | Up to 10 ADRs whose accuracy < 80%, sorted most-degraded first. Excludes `SuperSeeded` and non-ADRs. |
|
|
143
|
+
| | `review_adr_relevance` | Factual report on one ADR + drifted files to re-read. Returns a `state` to drive the LLM decision tree. |
|
|
144
|
+
| 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. |
|
|
145
|
+
|
|
146
|
+
### Prompts (10)
|
|
147
|
+
|
|
148
|
+
| Group | Prompt | When |
|
|
149
|
+
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
150
|
+
| ADR lifecycle | `create-adr` | A feature has just been implemented or modified. Records the decision, supersedes a prior ADR if any. |
|
|
151
|
+
| | `audit-adrs-drift` | Batch audit: bring every drifting ADR back to a clear state (re-baseline or user-confirmed supersession). |
|
|
152
|
+
| | `review-adr-relevance` | Single ADR review against its bound source files. |
|
|
153
|
+
| | `retrodocument-adrs-from-git` | Backfill ADRs from git history when the project lacks them. |
|
|
154
|
+
| Diagrams | `generate-context-diagram` | DEFAULT. C4 context diagram, gated server-side. |
|
|
155
|
+
| | `generate-container-diagram` | Explicit-only. C4 container diagram of one system. |
|
|
156
|
+
| | `generate-uml-diagram` | Explicit-only. UML class/sequence/state/activity/use-case. |
|
|
157
|
+
| | `generate-screen-guide` | Explicit-only. Annotated screenshot with post-it callouts. |
|
|
158
|
+
| | `update-diagram-from-docs` | Re-read source documents to update existing diagrams. |
|
|
159
|
+
| | `flow`, `erd` | Linear flow / entity-relationship diagrams. |
|
|
160
|
+
|
|
161
|
+
A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for inspection.
|
|
342
162
|
|
|
343
163
|
---
|
|
344
164
|
|
|
345
|
-
##
|
|
346
|
-
|
|
347
|
-
Living Documentation exposes an **MCP server** over HTTP so that AI assistants (Claude Desktop, Claude Code, Cursor, etc.) can read and create documents and diagrams programmatically — without leaving your editor.
|
|
165
|
+
## Authoring features
|
|
348
166
|
|
|
349
|
-
|
|
167
|
+
- **Inline editor** — edit any doc in the browser, saves to disk instantly.
|
|
168
|
+
- **Snippets panel** (`🧩 Snippets`) — pre-built Markdown constructs at the cursor: collapsible blocks, links (in-doc, cross-doc, anchor), lists, code blocks, blockquotes, separators, images. Plus a **table editor** (dynamic grid → aligned Markdown table) and a **tree editor** (indentation → ASCII tree with `├──` / `└──`). Selecting an existing snippet **detects its type** and pre-fills the form for editing.
|
|
169
|
+
- **Image paste** — paste from clipboard while editing, auto-uploaded to `<docs>/images/`, inserted as Markdown.
|
|
170
|
+
- **File attachments** — drag, drop, paste or pick any non-image file (PDF, archive, office doc). Uploaded under `<docs>/files/`, inserted as a paperclip pill. Blocked extensions and size limits configurable in Admin.
|
|
171
|
+
- **Full-text search** — instant filename filter + server-side content search; for each file lists every occurrence, highlights and jumps to them.
|
|
172
|
+
- **`metadata://<filename>` search prefix** — reverse-lookup: which documents reference this attachment?
|
|
173
|
+
- **Annotations** — persistent highlight markers per document (yellow / pink / green / blue).
|
|
174
|
+
- **Anchor navigation** — `[label](#heading-slug)` scrolls correctly after async render; IDs auto-generated.
|
|
175
|
+
- **Dark mode** — follows system preference, manually toggleable. Syntax highlighting always dark.
|
|
350
176
|
|
|
351
|
-
|
|
177
|
+
|
|
352
178
|
|
|
353
|
-
|
|
354
|
-
POST http://localhost:4321/mcp
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
Transport: **Streamable HTTP** (stateless — one session per request).
|
|
358
|
-
|
|
359
|
-
A `GET http://localhost:4321/mcp` returns a JSON summary of available tools for quick inspection.
|
|
179
|
+
|
|
360
180
|
|
|
361
|
-
|
|
181
|
+
---
|
|
362
182
|
|
|
363
|
-
|
|
364
|
-
|---|---|
|
|
365
|
-
| `get_server_guide` | Return the server guide (purpose, workflow, diagram conventions, coordinate system) |
|
|
366
|
-
| `list_documents` | List all documents with their id, title, category and folder |
|
|
367
|
-
| `read_document` | Read the raw Markdown content of a document by its id |
|
|
368
|
-
| `create_document` | Create a new Markdown document (filename generated from the configured pattern) |
|
|
369
|
-
| `update_document` | Overwrite the Markdown content of an existing doc by id — used for drift correction (Scenario B) and supersede (Scenario A) |
|
|
370
|
-
| `list_diagrams` | List all saved diagrams with their id and title |
|
|
371
|
-
| `read_diagram` | Read the nodes and edges of a diagram (same shape as `create_diagram` input) |
|
|
372
|
-
| `create_diagram` | Create or overwrite a diagram from nodes and edges (shapes, colors, labels) |
|
|
373
|
-
| `list_source_files` | List project source files under `sourceRoot` (fallback only) |
|
|
374
|
-
| `read_source_file` | Read a source file under `sourceRoot` (fallback only) |
|
|
375
|
-
| `search_source` | Grep-like text search across files under `sourceRoot` |
|
|
376
|
-
| `list_metadata` | List the source-file bindings of every doc |
|
|
377
|
-
| `get_accuracy` | Get the reliability report of a doc (per-entry status + ratio) — detect drift |
|
|
378
|
-
| `add_metadata` | Bind a source file to a doc (stores the SHA-256 hash) |
|
|
379
|
-
| `remove_metadata` | Detach a source file from a doc (idempotent) — used for renames / deletes |
|
|
380
|
-
| `refresh_metadata` | Re-hash all bindings for a doc — re-baseline after the doc has been rewritten |
|
|
381
|
-
| `list_documents_below_accuracy` | List up to 10 ADRs whose reliability < 80%, sorted most-degraded first — entry point for batch drift audit |
|
|
183
|
+
## Diagram editor
|
|
382
184
|
|
|
383
|
-
|
|
185
|
+
Built-in canvas diagram editor (vis-network), accessible at `/diagram?id=...`.
|
|
384
186
|
|
|
385
|
-
-
|
|
386
|
-
-
|
|
387
|
-
-
|
|
187
|
+
- **C4 progression enforced** — context first (default), container/component only on explicit request. UML on explicit request.
|
|
188
|
+
- **Architectural `kind` vs visual `renderAs`** — separate the concept (`software_system`, `database`, `queue`, `api`, `cloud_service`…) from the shape (`box`, `ellipse`, `database`, `actor`, `post-it`…). The MCP picks sensible defaults for each `kind`.
|
|
189
|
+
- **Evidence provenance** — every architectural node/edge can cite the document and section that justifies it. The editor surfaces missing-evidence warnings.
|
|
190
|
+
- **Custom shape libraries** at `/shape-editor` — define your own shapes (SVG icons, ports, default colors) and reuse them across diagrams.
|
|
191
|
+
- **Ports** for anchored edges, **alignment guides**, **undo/redo**, **snap-to-grid**, **paste images**, **PNG export**, **deep-link** to a diagram by id.
|
|
388
192
|
|
|
389
|
-
|
|
193
|
+
---
|
|
390
194
|
|
|
391
|
-
|
|
195
|
+
## File organization
|
|
392
196
|
|
|
393
|
-
```
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
197
|
+
```
|
|
198
|
+
docs/
|
|
199
|
+
├── 2024_01_15_09_30_[DevOps]_deploy.md → category: DevOps
|
|
200
|
+
├── 1_tutorial/ → folder: Tutorial (prefix hidden in UI)
|
|
201
|
+
│ └── 2024_03_01_10_00_[Onboarding]_setup.md → folder: Tutorial / category: Onboarding
|
|
202
|
+
├── adrs/
|
|
203
|
+
│ └── 2024_04_01_10_15_[Architecture]_event_sourcing.md
|
|
204
|
+
└── 2_reference/
|
|
205
|
+
└── api.md → folder: Reference / category: General
|
|
402
206
|
```
|
|
403
207
|
|
|
404
|
-
|
|
208
|
+
- The `[Category]` tag is parsed from the filename regardless of the folder.
|
|
209
|
+
- Files without a `[Category]` fall under **General**. **General** is always rendered first.
|
|
210
|
+
- Folders are sorted alphabetically — prefix with `1_`, `2_`… to force an order; the prefix is hidden in the UI but visible on hover.
|
|
211
|
+
- Subdirectory nesting is supported recursively.
|
|
405
212
|
|
|
406
|
-
|
|
213
|
+
|
|
407
214
|
|
|
408
|
-
|
|
215
|
+
---
|
|
409
216
|
|
|
410
|
-
|
|
411
|
-
claude mcp add --transport http living-documentation http://localhost:4321/mcp
|
|
412
|
-
```
|
|
217
|
+
## Configuration (`.living-doc.json`)
|
|
413
218
|
|
|
414
|
-
|
|
219
|
+
Created automatically in your docs folder on first run. Edit in the Admin panel or by hand.
|
|
415
220
|
|
|
416
221
|
```json
|
|
417
222
|
{
|
|
418
|
-
"
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
223
|
+
"filenamePattern": "YYYY_MM_DD_HH_mm_[Category]_title",
|
|
224
|
+
"title": "Living Documentation",
|
|
225
|
+
"theme": "system",
|
|
226
|
+
"port": 4321,
|
|
227
|
+
"extraFiles": ["../README.md", "../CLAUDE.md"],
|
|
228
|
+
"sourceRoot": "../src",
|
|
229
|
+
"blockedFileExtensions": [".exe", ".bin"]
|
|
424
230
|
}
|
|
425
231
|
```
|
|
426
232
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
233
|
+
| Field | Role |
|
|
234
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
235
|
+
| `filenamePattern` | Filename convention used to parse date / category / title. `[Category]` token mandatory, exactly once. |
|
|
236
|
+
| `extraFiles` | Ordered Markdown files **outside** the docs folder (e.g. `README.md`, `CLAUDE.md`). Shown in General first. |
|
|
237
|
+
| `sourceRoot` | Where your code lives (relative to docs folder). Defaults to `..`. Used by MCP source + metadata tools. |
|
|
238
|
+
| `blockedFileExtensions` | File-attachment safety list, editable from Admin. |
|
|
430
239
|
|
|
431
|
-
|
|
432
|
-
npm run build # compiles TypeScript → dist/ and copies HTML assets
|
|
433
|
-
```
|
|
240
|
+
**All paths are relative POSIX** so `.living-doc.json` stays portable. Legacy absolute paths are silently migrated on first read.
|
|
434
241
|
|
|
435
|
-
|
|
242
|
+
|
|
436
243
|
|
|
437
244
|
---
|
|
438
245
|
|
|
439
|
-
##
|
|
246
|
+
## Export
|
|
440
247
|
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
npm run test:e2e:ui # interactive UI mode — step through actions, inspect DOM, replay
|
|
448
|
-
```
|
|
248
|
+
| Format | Endpoint | Notes |
|
|
249
|
+
| ------------------------ | --------------------- | ------------------------------------------------------------------ |
|
|
250
|
+
| PDF (per doc) | `POST /api/export/html` | Browser print dialog from the rendered HTML. |
|
|
251
|
+
| HTML — Notion mode | `POST /api/export/html` | Single HTML bundle suitable for Notion import. |
|
|
252
|
+
| HTML — Confluence mode | `POST /api/export/html` | Zipped HTML bundle suitable for Confluence import. |
|
|
253
|
+
| Markdown bundle | `POST /api/export/markdown` | Zip of every document with normalized links. |
|
|
449
254
|
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
```bash
|
|
453
|
-
npx playwright test tests/api/documents.spec.ts # a single file
|
|
454
|
-
npx playwright test -g "rejects an absolute" # by test-name regex
|
|
455
|
-
npx playwright test --headed --slow-mo=500 # watch the browser
|
|
456
|
-
npx playwright test --last-failed # rerun only failing tests
|
|
457
|
-
npx playwright show-report # open the HTML report after a run
|
|
458
|
-
```
|
|
255
|
+
---
|
|
459
256
|
|
|
460
|
-
|
|
257
|
+
## UI surfaces
|
|
461
258
|
|
|
462
|
-
|
|
259
|
+
| URL | Page |
|
|
260
|
+
| ---------------- | ---------------------------------------------------------------------------------------- |
|
|
261
|
+
| `/` | Viewer — sidebar, document rendering, inline edit, snippets, search, attachments. |
|
|
262
|
+
| `/admin` | Config — title, theme, filename pattern, extra files, source root, file safety list. |
|
|
263
|
+
| `/diagram?id=` | Diagram editor (vis-network) with C4 conventions, ports, alignment guides, undo/redo. |
|
|
264
|
+
| `/shape-editor` | Custom shape library editor — SVG icons, default colors, ports. |
|
|
265
|
+
| `/context` | AI context page — instructions, rules, memory, **MCP explorer** (try tools live in-browser). |
|
|
463
266
|
|
|
464
|
-
|
|
465
|
-
npm run test:coverage
|
|
466
|
-
open coverage/index.html # macOS — browse line-by-line coverage
|
|
467
|
-
```
|
|
267
|
+
|
|
468
268
|
|
|
469
|
-
|
|
269
|
+
---
|
|
470
270
|
|
|
471
|
-
|
|
271
|
+
## REST API
|
|
472
272
|
|
|
473
|
-
|
|
273
|
+
<details>
|
|
274
|
+
<summary>Full HTTP API (click to expand)</summary>
|
|
474
275
|
|
|
475
|
-
|
|
276
|
+
| Method | Endpoint | Description |
|
|
277
|
+
| -------- | ------------------------------ | ------------------------------------------------------------------ |
|
|
278
|
+
| `GET` | `/api/documents` | List documents with metadata (includes extra files). |
|
|
279
|
+
| `GET` | `/api/documents/:id` | Document content + rendered HTML. |
|
|
280
|
+
| `POST` | `/api/documents` | Create from `{ title, category, folder?, content?, date? }`. |
|
|
281
|
+
| `PUT` | `/api/documents/:id` | Save content to disk. |
|
|
282
|
+
| `DELETE` | `/api/documents/:id` | Delete a document. |
|
|
283
|
+
| `GET` | `/api/documents/search?q=` | Full-text search. |
|
|
284
|
+
| `GET` | `/api/config` | Read config. |
|
|
285
|
+
| `PUT` | `/api/config` | Update config (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`, …). |
|
|
286
|
+
| `GET` | `/api/browse?path=` | List directories and `.md` files at a path. |
|
|
287
|
+
| `POST` | `/api/browse/mkdir` | Create a folder under the docs root. |
|
|
288
|
+
| `POST` | `/api/images/upload` | Upload a base64 image → `<docs>/images/`. |
|
|
289
|
+
| `POST` | `/api/files/upload` | Upload a base64 attachment → `<docs>/files/`. |
|
|
290
|
+
| `GET` | `/api/files` | List every attachment (chronological). |
|
|
291
|
+
| `PUT` | `/api/files/:filename` | Replace an attachment. |
|
|
292
|
+
| `DELETE` | `/api/files/:filename` | Delete an attachment. |
|
|
293
|
+
| `GET` | `/api/metadata/:docId` | Reliability report for one doc. |
|
|
294
|
+
| `POST` | `/api/metadata/:docId` | Add or replace a binding. |
|
|
295
|
+
| `DELETE` | `/api/metadata/:docId` | Remove a binding. |
|
|
296
|
+
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline hashes. |
|
|
297
|
+
| `GET` | `/api/browse-source?path=` | Navigate the source tree rooted at `sourceRoot`. |
|
|
298
|
+
| `GET` | `/api/diagrams` | List saved diagrams. |
|
|
299
|
+
| `GET` | `/api/diagrams/:id` | Read a single diagram (nodes + edges). |
|
|
300
|
+
| `PUT` | `/api/diagrams/:id` | Create or update a diagram. |
|
|
301
|
+
| `DELETE` | `/api/diagrams/:id` | Delete a diagram. |
|
|
302
|
+
| `GET` | `/api/shape-libraries` | List custom shape libraries. |
|
|
303
|
+
| `PUT` | `/api/shape-libraries/:id` | Save a shape library. |
|
|
304
|
+
| `GET` | `/api/annotations[/:docId]` | List annotations (all docs / one doc). |
|
|
305
|
+
| `POST` | `/api/annotations/:docId` | Add an annotation. |
|
|
306
|
+
| `DELETE` | `/api/annotations/:docId/:id` | Delete one annotation. |
|
|
307
|
+
| `POST` | `/api/export/html` | HTML export — Notion / Confluence modes. |
|
|
308
|
+
| `POST` | `/api/export/markdown` | Markdown bundle export. |
|
|
309
|
+
| `GET` | `/api/wordcloud?path=&ext=` | Recursively concatenate matching source files as raw text. |
|
|
310
|
+
| `POST` | `/mcp` | Model Context Protocol endpoint (Streamable HTTP). |
|
|
311
|
+
| `GET` | `/mcp` | Live tool + prompt schema summary. |
|
|
312
|
+
|
|
313
|
+
</details>
|
|
476
314
|
|
|
477
|
-
|
|
315
|
+
---
|
|
478
316
|
|
|
479
|
-
|
|
480
|
-
- `with-metadata/` — docs + source file + `.metadata.json`
|
|
481
|
-
- `with-diagrams/` — `.diagrams.json` pre-populated
|
|
482
|
-
- `with-annotations/` — `.annotations.json` pre-populated
|
|
483
|
-
- `with-subfolders/` — nested folder tree
|
|
484
|
-
- `legacy-abs-paths/` — pre-7.25 config for migration tests
|
|
317
|
+
## Build & test
|
|
485
318
|
|
|
486
|
-
|
|
319
|
+
```bash
|
|
320
|
+
git clone https://github.com/craftskillz/living-documentation.git
|
|
321
|
+
cd living-documentation
|
|
322
|
+
npm install
|
|
323
|
+
npm run setup-hooks # one-time: enable .githooks/ as core.hooksPath
|
|
324
|
+
npm run dev -- ./documentation # nodemon + ts-node, watches src + bin
|
|
325
|
+
npm run build # tsc → dist/ + copy frontend assets
|
|
326
|
+
npm run test:e2e # Playwright end-to-end (~3 s, ~30 MCP specs)
|
|
327
|
+
npm run test:coverage # c8 V8-native coverage
|
|
328
|
+
```
|
|
487
329
|
|
|
488
|
-
|
|
489
|
-
import { test, expect } from '../helpers/ld-fixture';
|
|
330
|
+
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`).
|
|
490
331
|
|
|
491
|
-
|
|
492
|
-
test.use({ fixtureName: 'with-diagrams' });
|
|
332
|
+
### Contributing
|
|
493
333
|
|
|
494
|
-
|
|
495
|
-
const res = await request.get(`${ld.baseURL}/api/diagrams`);
|
|
496
|
-
expect(res.ok()).toBe(true);
|
|
497
|
-
});
|
|
498
|
-
});
|
|
499
|
-
```
|
|
334
|
+
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.
|
|
500
335
|
|
|
501
336
|
---
|
|
502
337
|
|
|
503
338
|
## License
|
|
504
339
|
|
|
505
|
-
AGPL-3.0
|
|
340
|
+
[AGPL-3.0](./LICENSE) — © Youssef MEDAGHRI-ALAOUI.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "living-documentation",
|
|
3
|
-
"version": "8.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "8.11.0",
|
|
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": {
|
|
7
7
|
"living-documentation": "dist/bin/cli.js"
|
|
8
8
|
},
|
|
9
9
|
"files": [
|
|
10
10
|
"dist/",
|
|
11
|
-
"
|
|
11
|
+
"images/",
|
|
12
|
+
"README.md",
|
|
13
|
+
"LICENSE"
|
|
12
14
|
],
|
|
13
15
|
"scripts": {
|
|
14
16
|
"build": "tsc && ts-node scripts/copy-assets.ts && chmod +x dist/bin/cli.js",
|
|
@@ -18,13 +20,27 @@
|
|
|
18
20
|
"test:e2e": "npm run build && playwright test",
|
|
19
21
|
"test:e2e:ui": "playwright test --ui",
|
|
20
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",
|
|
21
25
|
"prepublishOnly": "npm run build"
|
|
22
26
|
},
|
|
23
27
|
"keywords": [
|
|
24
28
|
"documentation",
|
|
29
|
+
"living-documentation",
|
|
25
30
|
"markdown",
|
|
26
31
|
"viewer",
|
|
27
|
-
"cli"
|
|
32
|
+
"cli",
|
|
33
|
+
"mcp",
|
|
34
|
+
"model-context-protocol",
|
|
35
|
+
"adr",
|
|
36
|
+
"architecture-decision-records",
|
|
37
|
+
"ai",
|
|
38
|
+
"claude",
|
|
39
|
+
"cursor",
|
|
40
|
+
"coding-agent",
|
|
41
|
+
"diagram",
|
|
42
|
+
"c4-model",
|
|
43
|
+
"drift-detection"
|
|
28
44
|
],
|
|
29
45
|
"author": "Youssef MEDAGHRI-ALAOUI",
|
|
30
46
|
"license": "AGPL-3.0",
|