living-documentation 7.11.0 → 7.12.0

package/README.md

@@ -10,6 +10,18 @@ No cloud, no database, no build step — just point it at a folder where you add
 
 ## Features
 
+### Reliability gauge — keep your docs honest
+
+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.
+
+- **Bind source files** to any doc via the `🗂 Metadata` button in the doc header — pick any file under `sourceRoot` (your project root, configurable in Admin). Each binding stores the file's SHA-256 hash.
+- **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.
+- **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.
+- **`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?".
+- **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.
+
+### Other features
+
 - **Sidebar** grouped by folder → category, sorted alphabetically; **General** always first
 [![README Diagrams](./images/readme-sidebar.png)](/diagram?id=d1775399110713)
 
@@ -224,16 +236,21 @@ living-documentation/
 │   │   ├── wordcloud.ts         Word cloud raw text reader
 │   │   ├── diagrams.ts          Diagrams CRUD API (vis-network JSON)
 │   │   ├── annotations.ts       Per-document highlight markers API
+│   │   ├── metadata.ts          Source-file bindings + reliability report
+│   │   ├── browse-source.ts     Source tree navigator (rooted at sourceRoot)
 │   │   └── export.ts            HTML export (PDF, Notion, Confluence zip)
 │   ├── mcp/
 │   │   ├── server.ts            Model Context Protocol server (Streamable HTTP)
 │   │   └── tools/
 │   │       ├── documents.ts     MCP tools: list/read/create document
 │   │       ├── diagrams.ts      MCP tools: list/read/create diagram
-│   │       └── source.ts        MCP tools: list/read/search source files
+│   │       ├── source.ts        MCP tools: list/read/search source files
+│   │       └── metadata.ts      MCP tools: list_metadata, get_accuracy, add_metadata, refresh_metadata
 │   ├── lib/
 │   │   ├── parser.ts            Filename parser
-│   │   └── config.ts            Config management (.living-doc.json)
+│   │   ├── config.ts            Config management (.living-doc.json)
+│   │   ├── metadata.ts          .metadata.json store + reliability formula
+│   │   └── hash.ts              sha256File helper
 │   └── frontend/
 │       ├── index.html           Main viewer shell
 │       ├── admin.html           Admin panel
@@ -271,6 +288,14 @@ living-documentation/
 | `POST`   | `/api/browse/mkdir`            | Create a new folder under the docs root                            |
 | `POST`   | `/api/images/upload`           | Upload a base64 image; saved to `DOCS_FOLDER/images/`              |
 | `POST`   | `/api/files/upload`            | Upload a base64 file attachment; saved to `DOCS_FOLDER/files/`     |
+| `GET`    | `/api/files`                   | List every file under `DOCS_FOLDER/files/` (chronological)         |
+| `PUT`    | `/api/files/:filename`         | Replace an existing attachment with a new base64 payload           |
+| `DELETE` | `/api/files/:filename`         | Delete an attachment                                               |
+| `GET`    | `/api/metadata/:docId`         | Reliability report for one doc (per-entry status + score)          |
+| `POST`   | `/api/metadata/:docId`         | Add or replace a source-file binding for a doc                     |
+| `DELETE` | `/api/metadata/:docId`         | Remove a binding                                                   |
+| `POST`   | `/api/metadata/:docId/refresh` | Re-hash all bindings (re-baseline after the doc has been updated)  |
+| `GET`    | `/api/browse-source?path=`     | Navigate the source tree rooted at `sourceRoot`                    |
 | `GET`    | `/api/diagrams`                | List saved diagrams                                                |
 | `GET`    | `/api/diagrams/:id`            | Read a single diagram (nodes + edges)                              |
 | `PUT`    | `/api/diagrams/:id`            | Create or update a diagram                                         |
@@ -317,6 +342,10 @@ A `GET http://localhost:4321/mcp` returns a JSON summary of available tools for
 | `list_source_files` | List project source files under `sourceRoot` (fallback only) |
 | `read_source_file` | Read a source file under `sourceRoot` (fallback only) |
 | `search_source` | Grep-like text search across files under `sourceRoot` |
+| `list_metadata` | List the source-file bindings of every doc |
+| `get_accuracy` | Get the reliability report of a doc (per-entry status + ratio) — detect drift |
+| `add_metadata` | Bind a source file to a doc (stores the SHA-256 hash) |
+| `refresh_metadata` | Re-hash all bindings for a doc — re-baseline after the doc has been rewritten |
 
 Prompts (`generate-context-diagram`, `generate-container-diagram`, `generate-uml-diagram`, `update-diagram-from-docs`, `generate-screen-guide`, `flow`, `erd`) are exposed alongside the tools for clients that surface MCP prompts to the user.
 

package/dist/src/frontend/accuracy-gauge.js

@@ -29,7 +29,10 @@ function renderAccuracyGauge(report) {
   if (label) label.textContent = window.t("accuracy.label");
   if (bar) {
     bar.style.width = pct + "%";
-    bar.style.backgroundColor = color;
+    // The gradient spans the full track width, so we stretch the background
+    // to (100/pct)× the bar width — this way the bar only shows the left
+    // portion of the red→green gradient corresponding to its percentage.
+    bar.style.backgroundSize = pct > 0 ? `${10000 / pct}% 100%` : "100% 100%";
   }
   if (value) {
     value.textContent = pct + "%";

package/dist/src/frontend/i18n/en.json

@@ -100,11 +100,11 @@
   "metadata.add": "Add source file",
   "metadata.refresh": "Refresh hashes",
   "metadata.remove": "Remove",
-  "metadata.empty": "No metadata yet — add a source file to start tracking accuracy.",
+  "metadata.empty": "No metadata yet — add a source file to start tracking reliability.",
   "metadata.status.unchanged": "Unchanged",
   "metadata.status.modified": "Modified",
   "metadata.status.missing": "Missing",
-  "accuracy.label": "Accuracy",
+  "accuracy.label": "Reliability",
   "accuracy.tooltip": "Unchanged: {unchanged} · Modified: {modified} · Missing: {missing} · Total: {total}",
 
   "modal.new_folder.title": "New folder",

package/dist/src/frontend/i18n/fr.json

@@ -104,7 +104,7 @@
   "metadata.status.unchanged": "Inchangé",
   "metadata.status.modified": "Modifié",
   "metadata.status.missing": "Manquant",
-  "accuracy.label": "Justesse",
+  "accuracy.label": "Fiabilité",
   "accuracy.tooltip": "Inchangés : {unchanged} · Modifiés : {modified} · Manquants : {missing} · Total : {total}",
 
   "modal.new_folder.title": "Nouveau dossier",

package/dist/src/frontend/index.html

@@ -647,20 +647,20 @@
               <div
                 id="accuracy-gauge"
                 onclick="openMetadataModal()"
-                class="hidden no-print mt-3 flex items-center gap-3 ml-auto w-full sm:w-80 cursor-pointer select-none"
+                class="hidden no-print mt-5 flex items-center gap-3 mr-auto w-full sm:w-80 cursor-pointer select-none"
               >
                 <span
                   id="accuracy-gauge-label"
                   data-i18n="accuracy.label"
                   class="text-xs text-gray-500 dark:text-gray-400 shrink-0"
-                >Accuracy</span>
+                >Reliability</span>
                 <div
-                  class="flex-1 h-2 rounded-full bg-gray-200 dark:bg-gray-700 overflow-hidden"
+                  class="flex-1 h-4 rounded-full bg-gray-200 dark:bg-gray-700 overflow-hidden"
                 >
                   <div
                     id="accuracy-gauge-bar"
                     class="h-full transition-all"
-                    style="width: 0%; background-color: #9ca3af"
+                    style="width: 0%; background: linear-gradient(to right, #dc2626, #f97316, #eab308, #16a34a); background-size: 100% 100%; background-repeat: no-repeat;"
                   ></div>
                 </div>
                 <span

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "living-documentation",
-  "version": "7.11.0",
+  "version": "7.12.0",
   "description": "A CLI tool that serves a local Markdown documentation viewer",
   "main": "dist/src/server.js",
   "bin": {