living-ai-documentation 3.8.0 → 3.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/README.fr.md +34 -34
  2. package/README.md +34 -34
  3. package/dist/frontend-svelte/assets/{index-DjxzmWM2.css → index-BUIF7V-I.css} +1 -1
  4. package/dist/frontend-svelte/assets/{index-DtFeYGCb.js → index-CTftqQJm.js} +39 -37
  5. package/dist/frontend-svelte/assets/{main-CyzsNGva.js → main-c5eMrXS4.js} +1 -1
  6. package/dist/frontend-svelte/i18n/en.json +6 -1
  7. package/dist/frontend-svelte/i18n/fr.json +6 -1
  8. package/dist/frontend-svelte/index.html +2 -2
  9. package/dist/src/lib/compareBlock.d.ts +35 -0
  10. package/dist/src/lib/compareBlock.d.ts.map +1 -0
  11. package/dist/src/lib/compareBlock.js +76 -0
  12. package/dist/src/lib/compareBlock.js.map +1 -0
  13. package/dist/src/routes/documents.d.ts.map +1 -1
  14. package/dist/src/routes/documents.js +3 -3
  15. package/dist/src/routes/documents.js.map +1 -1
  16. package/dist/src/routes/export.js +2 -2
  17. package/dist/src/routes/export.js.map +1 -1
  18. package/dist/starter-doc/.living-doc.json +56 -1
  19. package/dist/starter-doc/AI/PROJECT-INSTRUCTIONS.md +13 -13
  20. package/dist/starter-doc/WORKLOG/ROADMAP.md +3 -3
  21. package/dist/starter-doc-fr/AI/PROJECT-INSTRUCTIONS.md +13 -13
  22. package/dist/starter-doc-fr/WORKLOG/ROADMAP.md +3 -3
  23. package/package.json +1 -1
package/README.fr.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [🇬🇧 Read in English](./README.md)
4
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.**
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
6
 
7
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
8
 
@@ -19,14 +19,14 @@ npx living-ai-documentation@latest ./docs # servir un dossier existant
19
19
 
20
20
  ## Deux usages
21
21
 
22
- ### 1. Avec un agent IA — la fonctionnalité phare
22
+ ### 1. Avec un agent IA , la fonctionnalité phare
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
26
  | Ce que vous dites… | Ce que l'agent déclenche… | Ce qui se passe |
27
27
  | ------------------------------------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
28
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. |
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
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
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
32
  | _« donne-moi la big picture »_ | `generate-context-diagram` | Crée un diagramme C4 de contexte **dérivé des documents**, jamais inventé. |
@@ -35,7 +35,7 @@ Living Documentation embarque un **serveur MCP** sur `POST /mcp`. N'importe quel
35
35
 
36
36
  ### 2. Sans IA, en solo
37
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.
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
39
 
40
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
41
 
@@ -44,7 +44,7 @@ Les deux modes se mélangent : prendre des notes en solo toute la semaine, puis
44
44
  ## Démarrage rapide
45
45
 
46
46
  ```bash
47
- # Assistant interactif — crée un dossier de doc de démarrage (EN ou FR), scaffold
47
+ # Assistant interactif , crée un dossier de doc de démarrage (EN ou FR), scaffold
48
48
  # AGENTS.md / CLAUDE.md / memory/MEMORY.md à la racine du projet et fait des symlinks
49
49
  # dans <docs>/AI/ pour que les agents IA les trouvent.
50
50
  npx living-ai-documentation@latest
@@ -113,13 +113,13 @@ Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sa
113
113
 
114
114
  ## Concepts centraux
115
115
 
116
- - **Markdown sur disque** — chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
117
- - **Pattern de nom de fichier** — par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`. Configurable ; date, catégorie et titre sont extraits. Les fichiers hors pattern apparaissent sous **General**.
116
+ - **Markdown sur disque** , chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
117
+ - **Pattern de nom de fichier** , par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`. Configurable ; date, catégorie et titre sont extraits. Les fichiers hors pattern apparaissent sous **General**.
118
118
  - **Dossiers → catégories → docs** dans le sidebar. Les noms de dossiers deviennent les libellés ; un préfixe numérique (`1_TUTORIAL`, `2_REFERENCE`) contrôle l'ordre sans s'afficher dans l'UI.
119
119
  - **Les ADR** sont le journal canonique des décisions. Le serveur MCP impose un frontmatter normalisé (`**date:**`, `**status:**`, `**description:**`, `**tags:**`) et un statut initial `To be validated` que seul un humain promeut.
120
120
  - **`sourceRoot`** désigne le code du projet. Les tools MCP source (`list_source_files`, `read_source_file`, `search_source`) et l'attache de métadonnées en dépendent. Défaut : parent du dossier de doc.
121
- - **Métadonnées source + jauge de fiabilité** — lier un document à ses fichiers source. Chaque lien stocke un SHA-256. La jauge dans le header (`🔴 → 🟡 → 🟢`) reflète `unchanged / total`. Dès qu'un fichier change ou disparaît, la dérive est visible. Les **god files** (`package.json`, lock files, manifests, barrels) sont exclus par convention.
122
- - **Les diagrammes sont des vues dérivées** — ils citent les documents qui les justifient (`evidence`). Ils ne peuvent pas introduire un concept absent de la documentation.
121
+ - **Métadonnées source + jauge de fiabilité** , lier un document à ses fichiers source. Chaque lien stocke un SHA-256. La jauge dans le header (`🔴 → 🟡 → 🟢`) reflète `unchanged / total`. Dès qu'un fichier change ou disparaît, la dérive est visible. Les **god files** (`package.json`, lock files, manifests, barrels) sont exclus par convention.
122
+ - **Les diagrammes sont des vues dérivées** , ils citent les documents qui les justifient (`evidence`). Ils ne peuvent pas introduire un concept absent de la documentation.
123
123
 
124
124
  ---
125
125
 
@@ -143,7 +143,7 @@ Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sa
143
143
  | Métadonnées | `list_metadata` | Fichiers source liés à un document. |
144
144
  | | `get_accuracy` | Statut par entrée (`unchanged` / `modified` / `missing`) + accuracy pondérée ∈ [0, 1]. |
145
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). |
146
+ | | `remove_metadata` | Détache un lien (idempotent , pour renames/deletes). |
147
147
  | | `refresh_metadata` | Re-hashe chaque lien (re-baseline après une mise à jour). |
148
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
149
  | | `review_adr_relevance` | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state` pour piloter le LLM. |
@@ -170,15 +170,15 @@ Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et promp
170
170
 
171
171
  ## Fonctionnalités d'édition
172
172
 
173
- - **Éditeur inline** — édition de n'importe quel document dans le navigateur, sauvegarde disque instantanée.
174
- - **Panneau Snippets** (`🧩 Snippets`) — constructions Markdown pré-fabriquées au curseur : blocs repliables, liens (in-doc, cross-doc, ancre), listes, blocs de code, blockquotes, séparateurs, images. Plus un **éditeur de tableaux** (grille dynamique → tableau Markdown aligné) et un **éditeur d'arborescence** (indentation → ASCII tree avec `├──` / `└──`). Sélectionner un snippet existant **détecte son type** et pré-remplit le formulaire pour édition.
175
- - **Paste d'image** — colle depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, insertion en Markdown.
176
- - **Pièces jointes** — glisser, déposer, coller ou choisir n'importe quel fichier non-image (PDF, archive, doc bureautique). Upload sous `<docs>/files/`, insertion en pill trombone. Extensions bloquées et limites configurables en Admin.
177
- - **Recherche plein-texte** — filtre filename instantané + recherche serveur de contenu ; pour chaque fichier liste chaque occurrence, surlignée, navigable.
178
- - **Préfixe de recherche `metadata://<nomdefichier>`** — recherche inverse : quels documents référencent cette pièce jointe ?
179
- - **Annotations** — marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
180
- - **Navigation par ancre** — `[label](#heading-slug)` scrolle correctement après le rendu async ; IDs auto-générés.
181
- - **Mode sombre** — suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
173
+ - **Éditeur inline** , édition de n'importe quel document dans le navigateur, sauvegarde disque instantanée.
174
+ - **Panneau Snippets** (`🧩 Snippets`) , constructions Markdown pré-fabriquées au curseur : blocs repliables, liens (in-doc, cross-doc, ancre), listes, blocs de code, blockquotes, séparateurs, images. Plus un **éditeur de tableaux** (grille dynamique → tableau Markdown aligné) et un **éditeur d'arborescence** (indentation → ASCII tree avec `├──` / `└──`). Sélectionner un snippet existant **détecte son type** et pré-remplit le formulaire pour édition.
175
+ - **Paste d'image** , colle depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, insertion en Markdown.
176
+ - **Pièces jointes** , glisser, déposer, coller ou choisir n'importe quel fichier non-image (PDF, archive, doc bureautique). Upload sous `<docs>/files/`, insertion en pill trombone. Extensions bloquées et limites configurables en Admin.
177
+ - **Recherche plein-texte** , filtre filename instantané + recherche serveur de contenu ; pour chaque fichier liste chaque occurrence, surlignée, navigable.
178
+ - **Préfixe de recherche `metadata://<nomdefichier>`** , recherche inverse : quels documents référencent cette pièce jointe ?
179
+ - **Annotations** , marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
180
+ - **Navigation par ancre** , `[label](#heading-slug)` scrolle correctement après le rendu async ; IDs auto-générés.
181
+ - **Mode sombre** , suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
182
182
 
183
183
  ![Sidebar groupé par dossier → catégorie](/images/readme-sidebar.png)
184
184
 
@@ -190,10 +190,10 @@ Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et promp
190
190
 
191
191
  Éditeur de diagrammes canvas intégré (vis-network), accessible via `/diagram?id=...`.
192
192
 
193
- - **Progression C4 imposée** — contexte d'abord (défaut), conteneur/composant seulement sur demande explicite. UML sur demande explicite.
194
- - **`kind` architectural vs `renderAs` visuel** — sépare le concept (`software_system`, `database`, `queue`, `api`, `cloud_service`…) de la forme (`box`, `ellipse`, `database`, `actor`, `post-it`…). Le MCP choisit des défauts sensés pour chaque `kind`.
195
- - **Provenance documentaire (`evidence`)** — chaque nœud / arête architectural peut citer le document et la section qui le justifient. L'éditeur lève des warnings si l'evidence manque.
196
- - **Bibliothèques de formes personnalisées** sur `/shape-editor` — définissez vos propres formes (icônes SVG, ports, couleurs par défaut) et réutilisez-les.
193
+ - **Progression C4 imposée** , contexte d'abord (défaut), conteneur/composant seulement sur demande explicite. UML sur demande explicite.
194
+ - **`kind` architectural vs `renderAs` visuel** , sépare le concept (`software_system`, `database`, `queue`, `api`, `cloud_service`…) de la forme (`box`, `ellipse`, `database`, `actor`, `post-it`…). Le MCP choisit des défauts sensés pour chaque `kind`.
195
+ - **Provenance documentaire (`evidence`)** , chaque nœud / arête architectural peut citer le document et la section qui le justifient. L'éditeur lève des warnings si l'evidence manque.
196
+ - **Bibliothèques de formes personnalisées** sur `/shape-editor` , définissez vos propres formes (icônes SVG, ports, couleurs par défaut) et réutilisez-les.
197
197
  - **Ports** pour arêtes ancrées, **guides d'alignement**, **undo/redo**, **snap-to-grid**, **paste d'image**, **export PNG**, **deep-link** vers un diagramme par id.
198
198
 
199
199
  ---
@@ -213,7 +213,7 @@ docs/
213
213
 
214
214
  - Le tag `[Category]` est extrait du filename quel que soit le dossier.
215
215
  - Les fichiers sans `[Category]` tombent sous **General**. **General** est toujours rendu en premier.
216
- - Les dossiers sont triés alphabétiquement — préfixer par `1_`, `2_`… pour forcer un ordre ; le préfixe est caché dans l'UI mais visible au survol.
216
+ - Les dossiers sont triés alphabétiquement , préfixer par `1_`, `2_`… pour forcer un ordre ; le préfixe est caché dans l'UI mais visible au survol.
217
217
  - L'imbrication de sous-dossiers est récursive.
218
218
 
219
219
  ![Pattern de filename](/images/readme-filename-pattern.png)
@@ -254,8 +254,8 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
254
254
  | Format | Endpoint | Notes |
255
255
  | ---------------------- | --------------------------- | ------------------------------------------------------------------ |
256
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. |
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
259
  | Bundle Markdown | `POST /api/export/markdown` | Zip de tous les documents avec liens normalisés. |
260
260
 
261
261
  ---
@@ -264,11 +264,11 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
264
264
 
265
265
  | URL | Page |
266
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. |
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
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). |
270
+ | `/shape-editor` | Éditeur de bibliothèques de formes personnalisées , icônes SVG, couleurs par défaut, ports. |
271
+ | `/context` | Page de contexte IA , instructions, règles, mémoire, **explorateur MCP** (tester les tools en live). |
272
272
 
273
273
  ---
274
274
 
@@ -308,7 +308,7 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
308
308
  | `GET` | `/api/annotations[/:docId]` | Liste les annotations (tous docs / un doc). |
309
309
  | `POST` | `/api/annotations/:docId` | Ajoute une annotation. |
310
310
  | `DELETE` | `/api/annotations/:docId/:id` | Supprime une annotation. |
311
- | `POST` | `/api/export/html` | Export HTML — modes Notion / Confluence. |
311
+ | `POST` | `/api/export/html` | Export HTML , modes Notion / Confluence. |
312
312
  | `POST` | `/api/export/markdown` | Export bundle Markdown. |
313
313
  | `GET` | `/api/wordcloud?path=&ext=` | Concatène récursivement les fichiers source filtrés en texte brut. |
314
314
  | `POST` | `/mcp` | Endpoint Model Context Protocol (Streamable HTTP). |
@@ -333,11 +333,11 @@ npm run test:coverage # couverture c8 V8-natif
333
333
 
334
334
  En **dev**, ouvrez l'UI sur **http://localhost:5174** (Vite sert l'app Svelte avec HMR et proxy `/api`, `/mcp`, `/images`, `/files` vers le backend Express sur `:4321`).
335
335
 
336
- 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`).
336
+ 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`).
337
337
 
338
338
  ### Tester le package publié en local
339
339
 
340
- Pas besoin de publier une version. Le CLI démarre un **unique serveur Express** qui sert l'UI Svelte pré-buildée **et** l'API/MCP sur un seul port — Vite (`:5174`) n'existe qu'en dev et pas pour l'utilisateur final.
340
+ Pas besoin de publier une version. Le CLI démarre un **unique serveur Express** qui sert l'UI Svelte pré-buildée **et** l'API/MCP sur un seul port , Vite (`:5174`) n'existe qu'en dev et pas pour l'utilisateur final.
341
341
 
342
342
  ```bash
343
343
  # Lance l'artefact de production exact, puis ouvrez http://localhost:4321
@@ -361,4 +361,4 @@ Ce dépôt embarque un hook `pre-commit` (dans `.githooks/`) qui impose le contr
361
361
 
362
362
  ## Licence
363
363
 
364
- [AGPL-3.0](./LICENSE) — © Youssef MEDAGHRI-ALAOUI.
364
+ [AGPL-3.0](./LICENSE) , © Youssef MEDAGHRI-ALAOUI.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [🇫🇷 Lire en français](./README.fr.md)
4
4
 
5
- > **Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams, and detect drift while you code.**
5
+ > **Local Markdown documentation hub with a built-in MCP server , coding agents create ADRs, draw diagrams, and detect drift while you code.**
6
6
 
7
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.
8
8
 
@@ -19,14 +19,14 @@ npx living-ai-documentation@latest ./docs # serve an existing folder
19
19
 
20
20
  ## Two ways to use it
21
21
 
22
- ### 1. With an AI coding agent — the killer feature
22
+ ### 1. With an AI coding agent , the killer feature
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
26
  | You say… | The agent triggers… | What happens |
27
27
  | ---------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
28
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. |
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
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
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
32
  | _"give me the big picture"_ | `generate-context-diagram` | Creates a C4 context diagram **derived from the docs**, never invented. |
@@ -35,7 +35,7 @@ Living Documentation ships an **MCP server** on `POST /mcp`. Any MCP-aware agent
35
35
 
36
36
  ### 2. Solo, no AI
37
37
 
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.
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.
39
39
 
40
40
  The two modes mix freely: jot notes solo all week, then let your agent record the ADR when the feature actually lands.
41
41
 
@@ -44,7 +44,7 @@ The two modes mix freely: jot notes solo all week, then let your agent record th
44
44
  ## Quick start
45
45
 
46
46
  ```bash
47
- # Interactive wizard — creates a starter doc folder (EN or FR), scaffolds
47
+ # Interactive wizard , creates a starter doc folder (EN or FR), scaffolds
48
48
  # AGENTS.md / CLAUDE.md / memory/MEMORY.md at the project root and symlinks
49
49
  # them into <docs>/AI/ so AI agents can find them.
50
50
  npx living-ai-documentation@latest
@@ -113,13 +113,13 @@ Use the same HTTP endpoint: `http://localhost:4321/mcp` (Streamable HTTP transpo
113
113
 
114
114
  ## Core concepts
115
115
 
116
- - **Markdown on disk** — each document is a `.md` file. Configuration lives in `.living-doc.json` next to it. Both are git-friendly.
117
- - **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**.
116
+ - **Markdown on disk** , each document is a `.md` file. Configuration lives in `.living-doc.json` next to it. Both are git-friendly.
117
+ - **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**.
118
118
  - **Folders → categories → docs** in the sidebar. Folder names become the labels; numeric prefixes (`1_TUTORIAL`, `2_REFERENCE`) control order without showing in the UI.
119
119
  - **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.
120
120
  - **`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.
121
- - **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.
122
- - **Diagrams are derived views** — they cite the documents they're built from (`evidence`). They cannot introduce concepts absent from the docs.
121
+ - **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.
122
+ - **Diagrams are derived views** , they cite the documents they're built from (`evidence`). They cannot introduce concepts absent from the docs.
123
123
 
124
124
  ---
125
125
 
@@ -143,7 +143,7 @@ Use the same HTTP endpoint: `http://localhost:4321/mcp` (Streamable HTTP transpo
143
143
  | Metadata | `list_metadata` | Source-file bindings of a doc. |
144
144
  | | `get_accuracy` | Per-entry status (`unchanged` / `modified` / `missing`) + weighted accuracy ∈ [0, 1]. |
145
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). |
146
+ | | `remove_metadata` | Detach a binding (idempotent , for renames/deletes). |
147
147
  | | `refresh_metadata` | Re-hash every binding (re-baseline after an update). |
148
148
  | ADR audit | `list_adrs_below_accuracy` | Up to 10 ADRs whose accuracy < 80%, sorted most-degraded first. Excludes `SuperSeeded` and non-ADRs. |
149
149
  | | `review_adr_relevance` | Factual report on one ADR + drifted files to re-read. Returns a `state` to drive the LLM decision tree. |
@@ -170,15 +170,15 @@ A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for ins
170
170
 
171
171
  ## Authoring features
172
172
 
173
- - **Inline editor** — edit any doc in the browser, saves to disk instantly.
174
- - **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.
175
- - **Image paste** — paste from clipboard while editing, auto-uploaded to `<docs>/images/`, inserted as Markdown.
176
- - **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.
177
- - **Full-text search** — instant filename filter + server-side content search; for each file lists every occurrence, highlights and jumps to them.
178
- - **`metadata://<filename>` search prefix** — reverse-lookup: which documents reference this attachment?
179
- - **Annotations** — persistent highlight markers per document (yellow / pink / green / blue).
180
- - **Anchor navigation** — `[label](#heading-slug)` scrolls correctly after async render; IDs auto-generated.
181
- - **Dark mode** — follows system preference, manually toggleable. Syntax highlighting always dark.
173
+ - **Inline editor** , edit any doc in the browser, saves to disk instantly.
174
+ - **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.
175
+ - **Image paste** , paste from clipboard while editing, auto-uploaded to `<docs>/images/`, inserted as Markdown.
176
+ - **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.
177
+ - **Full-text search** , instant filename filter + server-side content search; for each file lists every occurrence, highlights and jumps to them.
178
+ - **`metadata://<filename>` search prefix** , reverse-lookup: which documents reference this attachment?
179
+ - **Annotations** , persistent highlight markers per document (yellow / pink / green / blue).
180
+ - **Anchor navigation** , `[label](#heading-slug)` scrolls correctly after async render; IDs auto-generated.
181
+ - **Dark mode** , follows system preference, manually toggleable. Syntax highlighting always dark.
182
182
 
183
183
  ![Sidebar grouped by folder → category](/images/readme-sidebar.png)
184
184
 
@@ -190,10 +190,10 @@ A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for ins
190
190
 
191
191
  Built-in canvas diagram editor (vis-network), accessible at `/diagram?id=...`.
192
192
 
193
- - **C4 progression enforced** — context first (default), container/component only on explicit request. UML on explicit request.
194
- - **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`.
195
- - **Evidence provenance** — every architectural node/edge can cite the document and section that justifies it. The editor surfaces missing-evidence warnings.
196
- - **Custom shape libraries** at `/shape-editor` — define your own shapes (SVG icons, ports, default colors) and reuse them across diagrams.
193
+ - **C4 progression enforced** , context first (default), container/component only on explicit request. UML on explicit request.
194
+ - **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`.
195
+ - **Evidence provenance** , every architectural node/edge can cite the document and section that justifies it. The editor surfaces missing-evidence warnings.
196
+ - **Custom shape libraries** at `/shape-editor` , define your own shapes (SVG icons, ports, default colors) and reuse them across diagrams.
197
197
  - **Ports** for anchored edges, **alignment guides**, **undo/redo**, **snap-to-grid**, **paste images**, **PNG export**, **deep-link** to a diagram by id.
198
198
 
199
199
  ---
@@ -213,7 +213,7 @@ docs/
213
213
 
214
214
  - The `[Category]` tag is parsed from the filename regardless of the folder.
215
215
  - Files without a `[Category]` fall under **General**. **General** is always rendered first.
216
- - Folders are sorted alphabetically — prefix with `1_`, `2_`… to force an order; the prefix is hidden in the UI but visible on hover.
216
+ - Folders are sorted alphabetically , prefix with `1_`, `2_`… to force an order; the prefix is hidden in the UI but visible on hover.
217
217
  - Subdirectory nesting is supported recursively.
218
218
 
219
219
  ![Filename pattern](/images/readme-filename-pattern.png)
@@ -254,8 +254,8 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
254
254
  | Format | Endpoint | Notes |
255
255
  | ---------------------- | --------------------------- | -------------------------------------------------- |
256
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. |
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
259
  | Markdown bundle | `POST /api/export/markdown` | Zip of every document with normalized links. |
260
260
 
261
261
  ---
@@ -264,11 +264,11 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
264
264
 
265
265
  | URL | Page |
266
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. |
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
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). |
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). |
272
272
 
273
273
  ---
274
274
 
@@ -308,7 +308,7 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
308
308
  | `GET` | `/api/annotations[/:docId]` | List annotations (all docs / one doc). |
309
309
  | `POST` | `/api/annotations/:docId` | Add an annotation. |
310
310
  | `DELETE` | `/api/annotations/:docId/:id` | Delete one annotation. |
311
- | `POST` | `/api/export/html` | HTML export — Notion / Confluence modes. |
311
+ | `POST` | `/api/export/html` | HTML export , Notion / Confluence modes. |
312
312
  | `POST` | `/api/export/markdown` | Markdown bundle export. |
313
313
  | `GET` | `/api/wordcloud?path=&ext=` | Recursively concatenate matching source files as raw text. |
314
314
  | `POST` | `/mcp` | Model Context Protocol endpoint (Streamable HTTP). |
@@ -333,11 +333,11 @@ npm run test:coverage # c8 V8-native coverage
333
333
 
334
334
  In **dev**, open the UI on **http://localhost:5174** (Vite serves the Svelte app with HMR and proxies `/api`, `/mcp`, `/images`, `/files` to the Express backend on `:4321`).
335
335
 
336
- 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`).
336
+ 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`).
337
337
 
338
338
  ### Test the published package locally
339
339
 
340
- No need to publish a version. The CLI starts a **single Express server** that serves the pre-built Svelte UI **and** the API/MCP on one port — Vite (`:5174`) is dev-only and does not exist for end users.
340
+ No need to publish a version. The CLI starts a **single Express server** that serves the pre-built Svelte UI **and** the API/MCP on one port , Vite (`:5174`) is dev-only and does not exist for end users.
341
341
 
342
342
  ```bash
343
343
  # Run the exact production artifact, then open http://localhost:4321
@@ -361,4 +361,4 @@ This repository ships with a `pre-commit` hook (under `.githooks/`) that enforce
361
361
 
362
362
  ## License
363
363
 
364
- [AGPL-3.0](./LICENSE) — © Youssef MEDAGHRI-ALAOUI.
364
+ [AGPL-3.0](./LICENSE) , © Youssef MEDAGHRI-ALAOUI.