living-ai-documentation 2.5.0 → 3.0.0

package/README.fr.md

@@ -13,7 +13,7 @@ npx living-ai-documentation@latest                # assistant interactif (EN/FR)
 npx living-ai-documentation@latest ./docs         # servir un dossier existant
 ```
 
-![Viewer Living Documentation](./images/living_documentation.jpg)
+![Viewer Living Documentation](/images/living_documentation.jpg)
 
 ---
 
@@ -180,9 +180,9 @@ Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et promp
 - **Navigation par ancre** — `[label](#heading-slug)` scrolle correctement après le rendu async ; IDs auto-générés.
 - **Mode sombre** — suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
 
-![Sidebar groupé par dossier → catégorie](./images/readme-sidebar.png)
+![Sidebar groupé par dossier → catégorie](/images/readme-sidebar.png)
 
-![Recherche plein-texte](./images/readme-intelligent-search-demo.jpg)
+![Recherche plein-texte](/images/readme-intelligent-search-demo.jpg)
 
 ---
 
@@ -216,7 +216,7 @@ docs/
 - 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.
 - L'imbrication de sous-dossiers est récursive.
 
-![Pattern de filename](./images/readme-filename-pattern.png)
+![Pattern de filename](/images/readme-filename-pattern.png)
 
 ---
 
@@ -245,7 +245,7 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
 
 **Tous les chemins sont relatifs POSIX** pour que `.living-doc.json` reste portable. Les chemins absolus legacy sont migrés silencieusement à la première lecture.
 
-![Extra files](./images/readme-extra-files.png)
+![Extra files](/images/readme-extra-files.png)
 
 ---
 
@@ -325,14 +325,34 @@ git clone https://github.com/craftskillz/living-documentation.git
 cd living-documentation
 npm install
 npm run setup-hooks                      # une fois : active .githooks/ comme core.hooksPath
-npm run dev -- ./documentation          # nodemon + ts-node, watch src + bin
-npm run build                            # tsc → dist/ + copie des assets frontend
+npm run dev -- ./documentation          # Vite (UI sur :5174, HMR) + backend Express (:4321)
+npm run build                            # tsc (serveur) + vite build (UI → dist/frontend-svelte)
 npm run test:e2e                         # Playwright end-to-end (~3 s, ~30 specs MCP)
 npm run test:coverage                    # couverture c8 V8-natif
 ```
 
+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`).
+
 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`).
 
+### Tester le package publié en local
+
+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.
+
+```bash
+# Lance l'artefact de production exact, puis ouvrez http://localhost:4321
+npm run build
+node dist/bin/cli.js ./documentation
+
+# Le plus fidèle : construire le tarball que npm publierait (respecte "files"), puis le lancer
+npm pack                                 # → living-ai-documentation-<version>.tgz
+npx ./living-ai-documentation-*.tgz ./documentation
+
+npm pack --dry-run                       # inspecter exactement les fichiers qui seraient publiés
+```
+
+> En production, il n'y a pas de `:5174`. L'endpoint MCP auquel les clients se connectent est **`http://localhost:4321/mcp`** (Express, port par défaut).
+
 ### Contribuer
 
 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.

package/README.md

@@ -13,7 +13,7 @@ npx living-ai-documentation@latest                # interactive wizard (EN/FR)
 npx living-ai-documentation@latest ./docs         # serve an existing folder
 ```
 
-![Living Documentation viewer](./images/living_documentation.jpg)
+![Living Documentation viewer](/images/living_documentation.jpg)
 
 ---
 
@@ -180,9 +180,9 @@ A `GET http://localhost:4321/mcp` returns the live tool + prompt schemas for ins
 - **Anchor navigation** — `[label](#heading-slug)` scrolls correctly after async render; IDs auto-generated.
 - **Dark mode** — follows system preference, manually toggleable. Syntax highlighting always dark.
 
-![Sidebar grouped by folder → category](./images/readme-sidebar.png)
+![Sidebar grouped by folder → category](/images/readme-sidebar.png)
 
-![Full-text search](./images/readme-intelligent-search-demo.jpg)
+![Full-text search](/images/readme-intelligent-search-demo.jpg)
 
 ---
 
@@ -216,7 +216,7 @@ docs/
 - Folders are sorted alphabetically — prefix with `1_`, `2_`… to force an order; the prefix is hidden in the UI but visible on hover.
 - Subdirectory nesting is supported recursively.
 
-![Filename pattern](./images/readme-filename-pattern.png)
+![Filename pattern](/images/readme-filename-pattern.png)
 
 ---
 
@@ -245,7 +245,7 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
 
 **All paths are relative POSIX** so `.living-doc.json` stays portable. Legacy absolute paths are silently migrated on first read.
 
-![Extra files](./images/readme-extra-files.png)
+![Extra files](/images/readme-extra-files.png)
 
 ---
 
@@ -325,14 +325,34 @@ git clone https://github.com/craftskillz/living-documentation.git
 cd living-documentation
 npm install
 npm run setup-hooks                      # one-time: enable .githooks/ as core.hooksPath
-npm run dev -- ./documentation          # nodemon + ts-node, watches src + bin
-npm run build                            # tsc → dist/ + copy frontend assets
+npm run dev -- ./documentation          # Vite (UI on :5174, HMR) + Express backend (:4321)
+npm run build                            # tsc (server) + vite build (UI → dist/frontend-svelte)
 npm run test:e2e                         # Playwright end-to-end (~3 s, ~30 MCP specs)
 npm run test:coverage                    # c8 V8-native coverage
 ```
 
+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`).
+
 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`).
 
+### Test the published package locally
+
+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.
+
+```bash
+# Run the exact production artifact, then open http://localhost:4321
+npm run build
+node dist/bin/cli.js ./documentation
+
+# Most faithful: build the tarball npm would publish (respects "files"), then run it
+npm pack                                 # → living-ai-documentation-<version>.tgz
+npx ./living-ai-documentation-*.tgz ./documentation
+
+npm pack --dry-run                       # inspect exactly which files would be published
+```
+
+> In production there is no `:5174`. The MCP endpoint clients connect to is **`http://localhost:4321/mcp`** (Express, default port).
+
 ### Contributing
 
 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.