living-documentation 8.11.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 +104 -100
- package/README.md +105 -101
- package/images/living_documentation.jpg +0 -0
- package/images/readme-intelligent-search-demo.jpg +0 -0
- package/package.json +1 -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
CHANGED
|
@@ -13,7 +13,7 @@ npx living-documentation # assistant interactif (EN/FR)
|
|
|
13
13
|
npx living-documentation ./docs # servir un dossier existant
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
@@ -23,15 +23,15 @@ npx living-documentation ./docs # servir un dossier existant
|
|
|
23
23
|
|
|
24
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
25
|
|
|
26
|
-
| Ce que vous dites…
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
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
33
|
|
|
34
|
-
**Tous les nouveaux ADR atterrissent en `To be validated`.**
|
|
34
|
+
**Tous les nouveaux ADR atterrissent en `To be validated`.** _Vous_ les promouvez. L'agent ne promeut jamais à votre place.
|
|
35
35
|
|
|
36
36
|
### 2. Sans IA, en solo
|
|
37
37
|
|
|
@@ -80,7 +80,10 @@ Ou manuellement dans `.claude/settings.json` :
|
|
|
80
80
|
```json
|
|
81
81
|
{
|
|
82
82
|
"mcpServers": {
|
|
83
|
-
"living-documentation": {
|
|
83
|
+
"living-documentation": {
|
|
84
|
+
"type": "http",
|
|
85
|
+
"url": "http://localhost:4321/mcp"
|
|
86
|
+
}
|
|
84
87
|
}
|
|
85
88
|
}
|
|
86
89
|
```
|
|
@@ -92,7 +95,10 @@ Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS),
|
|
|
92
95
|
```json
|
|
93
96
|
{
|
|
94
97
|
"mcpServers": {
|
|
95
|
-
"living-documentation": {
|
|
98
|
+
"living-documentation": {
|
|
99
|
+
"type": "http",
|
|
100
|
+
"url": "http://localhost:4321/mcp"
|
|
101
|
+
}
|
|
96
102
|
}
|
|
97
103
|
}
|
|
98
104
|
```
|
|
@@ -121,42 +127,42 @@ Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sa
|
|
|
121
127
|
|
|
122
128
|
### Tools (19)
|
|
123
129
|
|
|
124
|
-
| Groupe
|
|
125
|
-
|
|
|
126
|
-
| Onboarding
|
|
127
|
-
| Documents
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
| Diagrammes
|
|
132
|
-
|
|
|
133
|
-
|
|
|
134
|
-
| Code source (fallback) | `list_source_files`
|
|
135
|
-
|
|
|
136
|
-
|
|
|
137
|
-
| Métadonnées
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
| Audit ADR
|
|
143
|
-
|
|
|
144
|
-
| Rétrodocumentation
|
|
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. |
|
|
145
151
|
|
|
146
152
|
### Prompts (10)
|
|
147
153
|
|
|
148
|
-
| Groupe
|
|
149
|
-
|
|
|
154
|
+
| Groupe | Prompt | Quand l'invoquer |
|
|
155
|
+
| ---------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
150
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. |
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
154
|
-
| Diagrammes
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
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. |
|
|
160
166
|
|
|
161
167
|
Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et prompts pour inspection.
|
|
162
168
|
|
|
@@ -176,7 +182,7 @@ Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et promp
|
|
|
176
182
|
|
|
177
183
|
|
|
178
184
|
|
|
179
|
-
|
|
180
186
|
|
|
181
187
|
---
|
|
182
188
|
|
|
@@ -230,12 +236,12 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
|
|
|
230
236
|
}
|
|
231
237
|
```
|
|
232
238
|
|
|
233
|
-
| Champ
|
|
234
|
-
|
|
|
235
|
-
| `filenamePattern`
|
|
236
|
-
| `extraFiles`
|
|
237
|
-
| `sourceRoot`
|
|
238
|
-
| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable en Admin.
|
|
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. |
|
|
239
245
|
|
|
240
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.
|
|
241
247
|
|
|
@@ -245,26 +251,24 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
|
|
|
245
251
|
|
|
246
252
|
## Export
|
|
247
253
|
|
|
248
|
-
| Format
|
|
249
|
-
|
|
|
250
|
-
| PDF (par doc)
|
|
251
|
-
| HTML — mode Notion
|
|
252
|
-
| HTML — mode Confluence
|
|
253
|
-
| Bundle Markdown
|
|
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. |
|
|
254
260
|
|
|
255
261
|
---
|
|
256
262
|
|
|
257
263
|
## Surfaces UI
|
|
258
264
|
|
|
259
|
-
| URL
|
|
260
|
-
|
|
|
261
|
-
| `/`
|
|
262
|
-
| `/admin`
|
|
263
|
-
| `/diagram?id=`
|
|
264
|
-
| `/shape-editor`
|
|
265
|
-
| `/context`
|
|
266
|
-
|
|
267
|
-
|
|
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). |
|
|
268
272
|
|
|
269
273
|
---
|
|
270
274
|
|
|
@@ -273,42 +277,42 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
|
|
|
273
277
|
<details>
|
|
274
278
|
<summary>API HTTP complète (cliquer pour déplier)</summary>
|
|
275
279
|
|
|
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.
|
|
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. |
|
|
285
289
|
| `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.
|
|
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. |
|
|
312
316
|
|
|
313
317
|
</details>
|
|
314
318
|
|
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ npx living-documentation # interactive wizard (EN/FR)
|
|
|
13
13
|
npx living-documentation ./docs # serve an existing folder
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
|
|
17
17
|
|
|
18
18
|
---
|
|
19
19
|
|
|
@@ -23,15 +23,15 @@ npx living-documentation ./docs # serve an existing folder
|
|
|
23
23
|
|
|
24
24
|
Living Documentation ships an **MCP server** on `POST /mcp`. Any MCP-aware agent can read, create and audit your project's documentation autonomously.
|
|
25
25
|
|
|
26
|
-
| You say…
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
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. |
|
|
33
33
|
|
|
34
|
-
**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.
|
|
35
35
|
|
|
36
36
|
### 2. Solo, no AI
|
|
37
37
|
|
|
@@ -80,7 +80,10 @@ Or manually in `.claude/settings.json`:
|
|
|
80
80
|
```json
|
|
81
81
|
{
|
|
82
82
|
"mcpServers": {
|
|
83
|
-
"living-documentation": {
|
|
83
|
+
"living-documentation": {
|
|
84
|
+
"type": "http",
|
|
85
|
+
"url": "http://localhost:4321/mcp"
|
|
86
|
+
}
|
|
84
87
|
}
|
|
85
88
|
}
|
|
86
89
|
```
|
|
@@ -92,7 +95,10 @@ In `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), th
|
|
|
92
95
|
```json
|
|
93
96
|
{
|
|
94
97
|
"mcpServers": {
|
|
95
|
-
"living-documentation": {
|
|
98
|
+
"living-documentation": {
|
|
99
|
+
"type": "http",
|
|
100
|
+
"url": "http://localhost:4321/mcp"
|
|
101
|
+
}
|
|
96
102
|
}
|
|
97
103
|
}
|
|
98
104
|
```
|
|
@@ -121,42 +127,42 @@ Use the same HTTP endpoint: `http://localhost:4321/mcp` (Streamable HTTP transpo
|
|
|
121
127
|
|
|
122
128
|
### Tools (19)
|
|
123
129
|
|
|
124
|
-
| Group
|
|
125
|
-
|
|
|
126
|
-
| Onboarding
|
|
127
|
-
| Documents
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
|
131
|
-
| Diagrams
|
|
132
|
-
|
|
|
133
|
-
|
|
|
134
|
-
| Source code (fallback) | `list_source_files`
|
|
135
|
-
|
|
|
136
|
-
|
|
|
137
|
-
| Metadata
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
| ADR audit
|
|
143
|
-
|
|
|
144
|
-
| 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. |
|
|
145
151
|
|
|
146
152
|
### Prompts (10)
|
|
147
153
|
|
|
148
|
-
| Group
|
|
149
|
-
|
|
|
150
|
-
| ADR lifecycle | `create-adr` | A feature has just been implemented or modified. Records the decision, supersedes a prior ADR if any.
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
154
|
-
| Diagrams
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
|
|
|
158
|
-
|
|
|
159
|
-
|
|
|
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. |
|
|
160
166
|
|
|
161
167
|
A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for inspection.
|
|
162
168
|
|
|
@@ -176,7 +182,7 @@ A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for ins
|
|
|
176
182
|
|
|
177
183
|
|
|
178
184
|
|
|
179
|
-
|
|
180
186
|
|
|
181
187
|
---
|
|
182
188
|
|
|
@@ -230,12 +236,12 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
230
236
|
}
|
|
231
237
|
```
|
|
232
238
|
|
|
233
|
-
| Field
|
|
234
|
-
|
|
|
235
|
-
| `filenamePattern`
|
|
236
|
-
| `extraFiles`
|
|
237
|
-
| `sourceRoot`
|
|
238
|
-
| `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. |
|
|
239
245
|
|
|
240
246
|
**All paths are relative POSIX** so `.living-doc.json` stays portable. Legacy absolute paths are silently migrated on first read.
|
|
241
247
|
|
|
@@ -245,26 +251,24 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
245
251
|
|
|
246
252
|
## Export
|
|
247
253
|
|
|
248
|
-
| Format
|
|
249
|
-
|
|
|
250
|
-
| PDF (per doc)
|
|
251
|
-
| HTML — Notion mode
|
|
252
|
-
| HTML — Confluence mode
|
|
253
|
-
| 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. |
|
|
254
260
|
|
|
255
261
|
---
|
|
256
262
|
|
|
257
263
|
## UI surfaces
|
|
258
264
|
|
|
259
|
-
| URL
|
|
260
|
-
|
|
|
261
|
-
| `/`
|
|
262
|
-
| `/admin`
|
|
263
|
-
| `/diagram?id=`
|
|
264
|
-
| `/shape-editor`
|
|
265
|
-
| `/context`
|
|
266
|
-
|
|
267
|
-
|
|
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). |
|
|
268
272
|
|
|
269
273
|
---
|
|
270
274
|
|
|
@@ -273,42 +277,42 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
273
277
|
<details>
|
|
274
278
|
<summary>Full HTTP API (click to expand)</summary>
|
|
275
279
|
|
|
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.
|
|
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. |
|
|
285
289
|
| `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.
|
|
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. |
|
|
312
316
|
|
|
313
317
|
</details>
|
|
314
318
|
|
|
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": {
|
|
Binary file
|
|
Binary file
|
|
Binary file
|