@imenam/mcp-documentor 1.0.61 → 1.0.63

package/dist/shared/schemas/doc.schema.d.ts

@@ -65,6 +65,8 @@ export interface DocSummary {
     updatedAt: string;
     tags: string[];
     isStale: boolean;
+    /** True when tracked entries have no snapshot and freshness cannot be computed. */
+    isBroken?: boolean;
     folder?: string;
 }
 export interface DocMatch {
@@ -81,11 +83,13 @@ export declare const FreshnessReportSchema: z.ZodObject<{
         stale: "stale";
         no_tracking: "no_tracking";
         unverifiable: "unverifiable";
+        broken: "broken";
     }>;
     modified: z.ZodArray<z.ZodString>;
     missing: z.ZodArray<z.ZodString>;
     unchanged: z.ZodArray<z.ZodString>;
     anchors_lost: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    broken: z.ZodDefault<z.ZodArray<z.ZodString>>;
     total: z.ZodNumber;
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;

package/dist/shared/schemas/doc.schema.js

@@ -36,18 +36,20 @@ export const DocSchema = z.object({
     updatedAt: z.string(),
 });
 export const FreshnessReportSchema = z.object({
-    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable"]),
+    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable", "broken"]),
     modified: z.array(z.string()),
     missing: z.array(z.string()),
     unchanged: z.array(z.string()),
     anchors_lost: z.array(z.string()).default([]),
+    /** Entries with neither sections nor contentHash (pre hash-based tracking) — cannot be checked until re-tracked. */
+    broken: z.array(z.string()).default([]),
     total: z.number(),
 });
 export const CreateDocArgsSchema = z.object({
     title: z.string().describe("Title of the documentation entry"),
     content: z.string().optional().describe("Documentation content in markdown"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
-    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths; when MCP_DOCUMENTOR_CODE_ROOT is configured they are stored relative to it so the docs stay portable across machines."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's configured code root (MCP_DOCUMENTOR_CODE_ROOT); paths under the root are stored relative to it so the docs stay portable across machines. Tracked files must exist."),
     tags: z.array(z.string()).optional().describe("Tags for categorization"),
     folder: z.string().optional().describe("Folder path for organization, e.g. 'frontend/components'"),
     related_docs: z.array(z.string()).optional().describe("IDs of related documentation entries"),
@@ -59,7 +61,7 @@ export const UpdateDocArgsSchema = z.object({
     title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
-    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths; when MCP_DOCUMENTOR_CODE_ROOT is configured they are stored relative to it so the docs stay portable across machines."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's configured code root (MCP_DOCUMENTOR_CODE_ROOT)."),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),
     related_docs: z.array(z.string()).optional().describe("Paths of related documentation entries (replaces existing)"),
 });

package/dist/src/core/code-ref-resolver.d.ts

@@ -5,10 +5,31 @@ export interface CodeRefResult {
 }
 export declare function resolveCodeRefs(content: string): CodeRefResult;
 export declare function snapshotTrackedFiles(inputs: TrackedFileInput[], project: string): TrackedFile[];
+export interface ResnapshotResult {
+    tracked: TrackedFile[];
+    /** Files already tracked whose stored snapshot was carried over untouched. */
+    preserved: string[];
+    /** Files that were not tracked before; their snapshot is an initialisation, not a refresh. */
+    added: string[];
+    /** Files whose tracking scope changed, leaving no prior snapshot to carry over. */
+    reset: string[];
+}
+/**
+ * Rebuilds a tracked-file list from `inputs`, keeping the stored snapshot of every file that
+ * was already tracked with the same scope.
+ *
+ * Re-declaring `tracked_files` states which files a doc depends on — it says nothing about whether
+ * the doc still describes them correctly. Only `refresh_file_snapshot` may acknowledge that, so a
+ * doc that was stale before this call is still stale after it. Files that were not tracked before
+ * necessarily carry a snapshot of their current content: there is no earlier state to preserve.
+ */
+export declare function resnapshotPreserving(existing: TrackedFile[], inputs: TrackedFileInput[], project: string): ResnapshotResult;
 /**
- * Merges snapshotted tracked files into an existing list.
- * - If a file is not yet tracked: appended.
- * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
- * - Otherwise (whole-file tracking involved): the existing entry is replaced.
+ * Merges snapshotted tracked files into an existing list, without ever refreshing what is
+ * already tracked — acknowledging staleness is `refresh_file_snapshot`'s job alone.
+ * - If a file is not yet tracked: appended with a snapshot of its current content.
+ * - If a file is already tracked by section and the addition covers a region not yet tracked:
+ *   that region is appended; existing sections keep their stored hash.
+ * - Otherwise the existing entry is left untouched.
  */
 export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[], project: string): TrackedFile[];

package/dist/src/core/code-ref-resolver.js

@@ -2,7 +2,7 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { snapshotSection } from "./section-tracker.js";
-import { toStoredPath } from "./path-resolver.js";
+import { toAbsolutePath, toStoredPath } from "./path-resolver.js";
 const EXT_TO_LANG = {
     ts: "typescript",
     tsx: "tsx",
@@ -53,11 +53,17 @@ export function snapshotTrackedFiles(inputs, project) {
     const byPath = new Map();
     for (const input of inputs) {
         const fp = typeof input === "string" ? input : input.path;
-        const absolutePath = path.resolve(process.cwd(), fp);
-        const storedPath = toStoredPath(fp, project);
-        const mtime = fs.existsSync(absolutePath)
-            ? fs.statSync(absolutePath).mtime.toISOString()
-            : new Date().toISOString();
+        // A relative input path means "relative to the project's code root" — the same
+        // convention used everywhere a stored path is read back. Never the server's cwd.
+        const absolutePath = toAbsolutePath(fp, project);
+        if (!absolutePath) {
+            throw new Error(`Cannot track "${fp}": the path is relative but no code root is configured for project "${project}". Provide an absolute path or set MCP_DOCUMENTOR_CODE_ROOT.`);
+        }
+        if (!fs.existsSync(absolutePath)) {
+            throw new Error(`Cannot track "${fp}": file not found at ${absolutePath}. Tracking snapshots the file content, so the file must exist.`);
+        }
+        const storedPath = toStoredPath(absolutePath, project);
+        const mtime = fs.statSync(absolutePath).mtime.toISOString();
         const isWhole = typeof input === "string" || input.lines.length === 0;
         const existing = byPath.get(storedPath);
         if (isWhole) {
@@ -79,24 +85,87 @@ export function snapshotTrackedFiles(inputs, project) {
     }
     const tracked = [];
     for (const [storedPath, { absolutePath, mtime, lineRanges, wholeFile }] of byPath) {
-        if (!wholeFile && lineRanges.length > 0 && fs.existsSync(absolutePath)) {
-            const sections = lineRanges
-                .filter(({ start, end }) => start <= end)
-                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+        const validRanges = lineRanges.filter(({ start, end }) => start <= end);
+        if (!wholeFile && validRanges.length > 0) {
+            const sections = dedupeSections(validRanges.map(({ start, end }) => snapshotSection(absolutePath, start, end)));
             tracked.push({ path: storedPath, lastModifiedAt: mtime, sections });
         }
         else {
-            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
-            tracked.push({ path: storedPath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
+            // Whole-file tracking — also the landing spot when every provided range was
+            // invalid, so an entry never ends up with neither sections nor contentHash.
+            tracked.push({ path: storedPath, lastModifiedAt: mtime, contentHash: computeFileHash(absolutePath) });
         }
     }
     return tracked;
 }
+const sameLines = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+/** Two sections describe the same region when they were anchored on the same top/bottom lines. */
+function sameRegion(a, b) {
+    return sameLines(a.anchors.top, b.anchors.top) && sameLines(a.anchors.bottom, b.anchors.bottom);
+}
+function dedupeSections(sections) {
+    const unique = [];
+    for (const section of sections) {
+        if (!unique.some((kept) => sameRegion(kept, section)))
+            unique.push(section);
+    }
+    return unique;
+}
+/**
+ * Carries a previously stored snapshot over to a freshly snapshotted entry for the same file.
+ *
+ * Returns `undefined` when nothing can be carried over — the file was tracked whole and is now
+ * tracked by section (or the reverse), so no prior hash describes the newly tracked region.
+ */
+function carryOverSnapshot(previous, fresh) {
+    if (!fresh.sections && !previous.sections)
+        return previous;
+    if (!fresh.sections || !previous.sections)
+        return undefined;
+    const sections = fresh.sections.map((section) => previous.sections.find((prev) => sameRegion(prev, section)) ?? section);
+    const carriedAny = sections.some((section, i) => section !== fresh.sections[i]);
+    if (!carriedAny)
+        return undefined;
+    return { ...previous, sections, lastModifiedAt: previous.lastModifiedAt };
+}
 /**
- * Merges snapshotted tracked files into an existing list.
- * - If a file is not yet tracked: appended.
- * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
- * - Otherwise (whole-file tracking involved): the existing entry is replaced.
+ * Rebuilds a tracked-file list from `inputs`, keeping the stored snapshot of every file that
+ * was already tracked with the same scope.
+ *
+ * Re-declaring `tracked_files` states which files a doc depends on — it says nothing about whether
+ * the doc still describes them correctly. Only `refresh_file_snapshot` may acknowledge that, so a
+ * doc that was stale before this call is still stale after it. Files that were not tracked before
+ * necessarily carry a snapshot of their current content: there is no earlier state to preserve.
+ */
+export function resnapshotPreserving(existing, inputs, project) {
+    const fresh = snapshotTrackedFiles(inputs, project);
+    const byPath = new Map(existing.map((tf) => [tf.path, tf]));
+    const preserved = [];
+    const added = [];
+    const reset = [];
+    const tracked = fresh.map((entry) => {
+        const previous = byPath.get(entry.path);
+        if (!previous) {
+            added.push(entry.path);
+            return entry;
+        }
+        const carried = carryOverSnapshot(previous, entry);
+        if (!carried) {
+            reset.push(entry.path);
+            return entry;
+        }
+        preserved.push(entry.path);
+        return carried;
+    });
+    return { tracked, preserved, added, reset };
+}
+/**
+ * Merges snapshotted tracked files into an existing list, without ever refreshing what is
+ * already tracked — acknowledging staleness is `refresh_file_snapshot`'s job alone.
+ * - If a file is not yet tracked: appended with a snapshot of its current content.
+ * - If a file is already tracked by section and the addition covers a region not yet tracked:
+ *   that region is appended; existing sections keep their stored hash.
+ * - Otherwise the existing entry is left untouched.
  */
 export function mergeTrackedFiles(existing, additions, project) {
     if (additions.length === 0)
@@ -107,16 +176,14 @@ export function mergeTrackedFiles(existing, additions, project) {
         const idx = result.findIndex(tf => tf.path === newTf.path);
         if (idx < 0) {
             result.push(newTf);
+            continue;
         }
-        else if (newTf.sections && result[idx].sections) {
-            result[idx] = {
-                ...result[idx],
-                sections: [...result[idx].sections, ...newTf.sections],
-                lastModifiedAt: newTf.lastModifiedAt,
-            };
-        }
-        else {
-            result[idx] = newTf;
+        const current = result[idx];
+        if (!newTf.sections || !current.sections)
+            continue;
+        const novel = newTf.sections.filter((section) => !current.sections.some((kept) => sameRegion(kept, section)));
+        if (novel.length > 0) {
+            result[idx] = { ...current, sections: [...current.sections, ...novel] };
         }
     }
     return result;

package/dist/src/index.js

@@ -160,7 +160,8 @@ async function handleGetInitialState(msg) {
             const full = await storageEngine.getDoc(doc.id); // doc.id is now the full path
             if (full && full.tracked_files.length > 0) {
                 const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale";
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         const bundles = storageEngine.getBundles();
@@ -198,7 +199,8 @@ async function handleUpdateProject(msg) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
                 const report = computeFreshness(full.tracked_files, project);
-                doc.isStale = report.status === "stale";
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -239,7 +241,8 @@ async function handleListDocs(msg) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
                 const report = computeFreshness(full.tracked_files, currentProject);
-                doc.isStale = report.status === "stale";
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -352,7 +355,8 @@ async function handleCreateDocIPC(msg) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
                 const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale";
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -684,7 +688,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                                 },
                             ],
                         },
-                        description: "Files to track for staleness detection. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
+                        description: "Files to track for staleness detection. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change). Paths are absolute, or relative to the project's code root. Tracked files must exist.",
                     },
                     tags: {
                         type: "array",
@@ -764,7 +768,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                                 },
                             ],
                         },
-                        description: "New list of tracked files (replaces existing). Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
+                        description: "New list of tracked files (replaces existing). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change). Paths are absolute, or relative to the project's code root.",
                     },
                     tags: {
                         type: "array",

package/dist/src/tools/check-freshness.js

@@ -8,12 +8,13 @@ export function computeFileHash(absolutePath) {
 }
 export function computeFreshness(trackedFiles, project) {
     if (!trackedFiles || trackedFiles.length === 0) {
-        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], total: 0 };
+        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], broken: [], total: 0 };
     }
     const modified = [];
     const missing = [];
     const unchanged = [];
     const anchors_lost = [];
+    const broken = [];
     for (const tracked of trackedFiles) {
         // A relative path with no code root configured on this machine is not
         // resolvable here — count it as absent so we end up "unverifiable" rather
@@ -60,15 +61,11 @@ export function computeFreshness(trackedFiles, project) {
             }
         }
         else {
-            const currentMtime = fs.statSync(absolutePath).mtime.getTime();
-            const storedMtime = new Date(tracked.lastModifiedAt).getTime();
-            const STALENESS_TOLERANCE_MS = 2000;
-            if (currentMtime > storedMtime + STALENESS_TOLERANCE_MS) {
-                modified.push(tracked.path);
-            }
-            else {
-                unchanged.push(tracked.path);
-            }
+            // Hash comparison is the only freshness system. An entry with neither
+            // sections nor contentHash predates it and cannot be checked — it is
+            // reported as broken (never checked by any other means) so readers can
+            // still expose the doc and its tracked list to the agent for re-tracking.
+            broken.push(tracked.path);
         }
     }
     // When every tracked file is absent, the source code simply isn't present on
@@ -78,15 +75,18 @@ export function computeFreshness(trackedFiles, project) {
     // change signal (likely deletions) and still counts as stale.
     const allMissing = missing.length === trackedFiles.length;
     if (allMissing) {
-        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, total: trackedFiles.length };
+        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, broken, total: trackedFiles.length };
     }
     const isStale = modified.length > 0 || missing.length > 0 || anchors_lost.length > 0;
+    // Broken tracking outranks everything: no freshness verdict is trustworthy
+    // until the broken entries are re-tracked.
     return {
-        status: isStale ? "stale" : "up_to_date",
+        status: broken.length > 0 ? "broken" : isStale ? "stale" : "up_to_date",
         modified,
         missing,
         unchanged,
         anchors_lost,
+        broken,
         total: trackedFiles.length,
     };
 }
@@ -97,11 +97,23 @@ export function formatFreshnessReport(title, report) {
     if (report.status === "unverifiable") {
         return `UNVERIFIABLE: "${title}" — none of the ${report.total} tracked file(s) are present on this machine, so freshness cannot be checked here. This is expected when the documentation is cloned without its source codebase.`;
     }
-    let text = report.status === "stale"
-        ? `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`
-        : `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    let text;
+    if (report.status === "broken") {
+        text = `BROKEN TRACKING: "${title}" — some tracked entries have no content snapshot and cannot be checked.\n`;
+    }
+    else if (report.status === "stale") {
+        text = `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`;
+    }
+    else {
+        text = `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    }
     const anchorLostCount = report.anchors_lost?.length ?? 0;
-    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${anchorLostCount} with lost anchors, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    const brokenCount = report.broken?.length ?? 0;
+    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${anchorLostCount} with lost anchors, ${brokenCount} with broken tracking, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    if (brokenCount > 0) {
+        text += `\n\n⚠ Files with broken tracking — no snapshot to compare against:\n${report.broken.map((f) => `  - ${f}`).join("\n")}`;
+        text += `\n  → These entries predate hash-based tracking. Re-read the source files and re-declare them in tracked_files via update_doc, or call refresh_file_snapshot if the doc content is still accurate.`;
+    }
     if (report.modified.length > 0) {
         text += `\n\nModified files (call refresh_file_snapshot to acknowledge):\n${report.modified.map((f) => `  - ${f}`).join("\n")}`;
     }
@@ -124,6 +136,58 @@ function renderUntrackedList(titles, heading) {
     const suffix = remaining > 0 ? `\n  … and ${remaining} more` : "";
     return `\n\n${heading}\n${shown.join("\n")}${suffix}`;
 }
+async function scanProjectFreshness(storageEngine, project) {
+    const summaries = await storageEngine.listDocs(project);
+    const scan = { docCount: summaries.length, stale: [], noTracking: [], broken: [], upToDate: 0, unverifiable: 0 };
+    for (const summary of summaries) {
+        const doc = await storageEngine.getDoc(summary.id, project);
+        if (!doc)
+            continue;
+        const report = computeFreshness(doc.tracked_files, project);
+        if (report.status === "broken") {
+            const files = report.broken.map((f) => `    • no snapshot: ${f}`).join("\n");
+            scan.broken.push(`  - **${doc.title}** [${doc.id}]\n${files}`);
+        }
+        else if (report.status === "no_tracking") {
+            scan.noTracking.push(doc.title);
+        }
+        else if (report.status === "unverifiable") {
+            scan.unverifiable++;
+        }
+        else if (report.status === "stale") {
+            const details = [
+                ...report.modified.map((f) => `    • modified: ${f}`),
+                ...report.missing.map((f) => `    • missing: ${f}`),
+                ...(report.anchors_lost ?? []).map((f) => `    • ⚠ anchors lost (needs update_doc): ${f}`),
+            ].join("\n");
+            scan.stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
+        }
+        else {
+            scan.upToDate++;
+        }
+    }
+    return scan;
+}
+function renderScanSummary(scan) {
+    let text = `${scan.docCount} doc(s) scanned: **${scan.stale.length} stale**, ${scan.upToDate} up to date, ${scan.unverifiable} unverifiable (source absent), ${scan.noTracking.length} not tracking any file`;
+    if (scan.broken.length > 0)
+        text += `, **${scan.broken.length} with broken tracking**`;
+    return text + ".";
+}
+function renderScanSections(scan, headingLevel) {
+    let text = "";
+    if (scan.broken.length > 0) {
+        text += `\n\n${headingLevel} Docs with broken tracking — fix required\n\n${scan.broken.join("\n")}`;
+        text += `\n  → These docs could not be checked. Re-read the source files and re-declare tracked_files via update_doc, then call refresh_file_snapshot if the doc content is still accurate.`;
+    }
+    if (scan.stale.length > 0) {
+        text += `\n\n${headingLevel} Stale docs\n\n${scan.stale.join("\n\n")}`;
+    }
+    if (scan.noTracking.length > 0) {
+        text += renderUntrackedList(scan.noTracking, `${headingLevel} Docs not tracking any file (no staleness detection)`);
+    }
+    return text;
+}
 export async function checkFreshness(storageEngine, args) {
     try {
         const validated = CheckFreshnessArgsSchema.parse(args);
@@ -137,45 +201,11 @@ export async function checkFreshness(storageEngine, args) {
             return { content: [{ type: "text", text: formatFreshnessReport(doc.title, report) }] };
         }
         if (validated.project) {
-            const summaries = await storageEngine.listDocs(validated.project);
-            if (summaries.length === 0) {
+            const scan = await scanProjectFreshness(storageEngine, validated.project);
+            if (scan.docCount === 0) {
                 return { content: [{ type: "text", text: `No documentation entries found in project "${validated.project}".` }] };
             }
-            const stale = [];
-            const noTracking = [];
-            let upToDate = 0;
-            let unverifiable = 0;
-            for (const summary of summaries) {
-                const doc = await storageEngine.getDoc(summary.id, validated.project);
-                if (!doc)
-                    continue;
-                const report = computeFreshness(doc.tracked_files, validated.project);
-                if (report.status === "no_tracking") {
-                    noTracking.push(doc.title);
-                }
-                else if (report.status === "unverifiable") {
-                    unverifiable++;
-                }
-                else if (report.status === "stale") {
-                    const details = [
-                        ...report.modified.map((f) => `    • modified: ${f}`),
-                        ...report.missing.map((f) => `    • missing: ${f}`),
-                        ...(report.anchors_lost ?? []).map((f) => `    • ⚠ anchors lost (needs update_doc): ${f}`),
-                    ].join("\n");
-                    stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
-                }
-                else {
-                    upToDate++;
-                }
-            }
-            let text = `# Freshness report — project "${validated.project}"\n\n`;
-            text += `${summaries.length} doc(s) scanned: **${stale.length} stale**, ${upToDate} up to date, ${unverifiable} unverifiable (source absent), ${noTracking.length} not tracking any file.\n`;
-            if (stale.length > 0) {
-                text += `\n## Stale docs\n\n${stale.join("\n\n")}`;
-            }
-            if (noTracking.length > 0) {
-                text += renderUntrackedList(noTracking, "## Docs not tracking any file (no staleness detection)");
-            }
+            const text = `# Freshness report — project "${validated.project}"\n\n${renderScanSummary(scan)}${renderScanSections(scan, "##")}`;
             return { content: [{ type: "text", text }] };
         }
         // No id, no project → scan all projects
@@ -184,49 +214,16 @@ export async function checkFreshness(storageEngine, args) {
         const projectBlocks = [];
         let totalDocs = 0;
         let totalStale = 0;
+        let totalBroken = 0;
         for (const proj of allProjects) {
-            const summaries = await storageEngine.listDocs(proj);
-            const stale = [];
-            const noTracking = [];
-            let upToDate = 0;
-            let unverifiable = 0;
-            for (const summary of summaries) {
-                const doc = await storageEngine.getDoc(summary.id, proj);
-                if (!doc)
-                    continue;
-                const report = computeFreshness(doc.tracked_files, proj);
-                if (report.status === "no_tracking") {
-                    noTracking.push(doc.title);
-                }
-                else if (report.status === "unverifiable") {
-                    unverifiable++;
-                }
-                else if (report.status === "stale") {
-                    const details = [
-                        ...report.modified.map((f) => `    • modified: ${f}`),
-                        ...report.missing.map((f) => `    • missing: ${f}`),
-                        ...(report.anchors_lost ?? []).map((f) => `    • ⚠ anchors lost (needs update_doc): ${f}`),
-                    ].join("\n");
-                    stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
-                }
-                else {
-                    upToDate++;
-                }
-            }
-            totalDocs += summaries.length;
-            totalStale += stale.length;
-            let block = `## ${proj}\n\n`;
-            block += `${summaries.length} doc(s): **${stale.length} stale**, ${upToDate} up to date, ${unverifiable} unverifiable (source absent), ${noTracking.length} not tracking any file.`;
-            if (stale.length > 0) {
-                block += `\n\n### Stale docs\n\n${stale.join("\n\n")}`;
-            }
-            if (noTracking.length > 0) {
-                block += renderUntrackedList(noTracking, "### Docs not tracking any file");
-            }
-            projectBlocks.push(block);
+            const scan = await scanProjectFreshness(storageEngine, proj);
+            totalDocs += scan.docCount;
+            totalStale += scan.stale.length;
+            totalBroken += scan.broken.length;
+            projectBlocks.push(`## ${proj}\n\n${renderScanSummary(scan)}${renderScanSections(scan, "###")}`);
         }
         let text = `# Freshness report — all projects (${allProjects.length})\n\n`;
-        text += `Total: ${totalDocs} doc(s) across all projects, **${totalStale} stale**.\n\n`;
+        text += `Total: ${totalDocs} doc(s) across all projects, **${totalStale} stale**${totalBroken > 0 ? `, **${totalBroken} with broken tracking**` : ""}.\n\n`;
         text += projectBlocks.join("\n\n---\n\n");
         return { content: [{ type: "text", text }] };
     }

package/dist/src/tools/get-doc-metadata.js

@@ -13,6 +13,8 @@ export async function getDocMetadata(storageEngine, args) {
         const { doc, project } = resolved;
         const report = computeFreshness(doc.tracked_files, project);
         const fileStatusIcon = (filePath) => {
+            if (report.broken.includes(filePath))
+                return "⚠ broken tracking (no snapshot — re-declare via update_doc or run refresh_file_snapshot)";
             if (report.modified.includes(filePath))
                 return "✗ modified";
             if (report.missing.includes(filePath))

package/dist/src/tools/get-doc.js

@@ -29,8 +29,20 @@ export async function getDoc(storageEngine, args) {
             }).join("\n")
             : "  (none)";
         const freshnessReport = computeFreshness(doc.tracked_files, resolvedProject);
-        const stalenessBanner = freshnessReport.status === "stale"
-            ? [
+        let stalenessBanner = "";
+        if (freshnessReport.status === "broken") {
+            stalenessBanner = [
+                `> [!WARNING]`,
+                `> **Le suivi de fichiers de cette documentation est cassé.**`,
+                `> Les entrées suivantes n'ont aucun snapshot de contenu et ne peuvent pas être vérifiées :`,
+                ...freshnessReport.broken.map((f) => `> - \`${f}\` *(aucun snapshot)*`),
+                `>`,
+                `> La fraîcheur de ce document est invérifiable tant que ces entrées ne sont pas re-suivies. Relisez les fichiers sources et re-déclarez-les via \`update_doc\` (tracked_files), ou appelez \`refresh_file_snapshot\` si le contenu ci-dessous est encore exact.`,
+                ``,
+            ].join("\n");
+        }
+        else if (freshnessReport.status === "stale") {
+            stalenessBanner = [
                 `> [!WARNING]`,
                 `> **Cette documentation est potentiellement obsolète.**`,
                 `> Les fichiers suivants ont été modifiés depuis la dernière mise à jour de ce document :`,
@@ -41,8 +53,8 @@ export async function getDoc(storageEngine, args) {
                 `>`,
                 `> Vérifiez si le contenu ci-dessous est toujours valide. Si nécessaire, utilisez \`git_diff_doc\` pour voir les changements, puis mettez à jour la documentation avec \`patch_doc\` ou \`update_doc\`.`,
                 ``,
-            ].join("\n")
-            : "";
+            ].join("\n");
+        }
         const text = [
             stalenessBanner,
             `# ${doc.title}`,

package/dist/src/tools/git-diff-doc.js

@@ -62,7 +62,9 @@ export async function gitDiffDoc(storageEngine, args) {
             }
             else {
                 const freshness = computeFreshness(doc.tracked_files, project);
-                const changedPaths = new Set([...freshness.modified, ...freshness.missing]);
+                // Broken entries (no snapshot) can't be hash-compared, but the git diff
+                // is still the best signal the agent has to re-assess them — include them.
+                const changedPaths = new Set([...freshness.modified, ...freshness.missing, ...freshness.broken]);
                 filesToDiff = doc.tracked_files.filter((tf) => changedPaths.has(tf.path));
             }
             if (filesToDiff.length === 0) {

package/dist/src/tools/list-docs.js

@@ -21,7 +21,7 @@ function renderProjectDocs(summaries, totalLabel) {
         if (key)
             lines.push(`\n  📁 ${key}`);
         for (const s of groups.get(key)) {
-            const staleTag = s.isStale ? " [STALE]" : "";
+            const staleTag = s.isBroken ? " [BROKEN TRACKING]" : s.isStale ? " [STALE]" : "";
             const tags = s.tags.length > 0 ? ` (${s.tags.join(", ")})` : "";
             const indent = key ? "    " : "  ";
             lines.push(`${indent}- ${s.title} [${s.id}]${tags}${staleTag} — updated ${s.updatedAt}`);
@@ -43,6 +43,7 @@ export async function listDocs(storageEngine, args) {
                 if (doc && doc.tracked_files.length > 0) {
                     const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
+                    summary.isBroken = report.status === "broken";
                 }
             }
             if (summaries.length === 0) {
@@ -61,6 +62,7 @@ export async function listDocs(storageEngine, args) {
                 if (doc && doc.tracked_files.length > 0) {
                     const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
+                    summary.isBroken = report.status === "broken";
                 }
             }
             grandTotal += summaries.length;

package/dist/src/tools/update-doc.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import { UpdateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { persistDraft } from "../core/draft-store.js";
-import { resolveCodeRefs, snapshotTrackedFiles, mergeTrackedFiles } from "../core/code-ref-resolver.js";
+import { resolveCodeRefs, resnapshotPreserving, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 export async function updateDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = UpdateDocArgsSchema.parse(args);
@@ -24,11 +24,16 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             doc.content = content;
             additionalTrackedFiles = refs;
         }
+        // Re-declaring tracked_files must never acknowledge staleness — that is
+        // refresh_file_snapshot's job alone. Snapshots of files already tracked with
+        // the same scope are carried over as-is; only genuinely new entries get one.
+        let trackedResult;
         if (validated.tracked_files !== undefined) {
-            doc.tracked_files = snapshotTrackedFiles([
+            trackedResult = resnapshotPreserving(doc.tracked_files, [
                 ...validated.tracked_files,
                 ...additionalTrackedFiles,
             ], resolvedProject);
+            doc.tracked_files = trackedResult.tracked;
         }
         else {
             doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
@@ -57,8 +62,16 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             changes.push("content");
         if (validated.content_file !== undefined)
             changes.push("content (from file)");
-        if (validated.tracked_files !== undefined)
-            changes.push(`tracked_files (${doc.tracked_files.length} files)`);
+        if (trackedResult !== undefined) {
+            const parts = [`${doc.tracked_files.length} files`];
+            if (trackedResult.preserved.length > 0)
+                parts.push(`${trackedResult.preserved.length} kept their existing snapshot`);
+            if (trackedResult.added.length > 0)
+                parts.push(`${trackedResult.added.length} newly tracked`);
+            if (trackedResult.reset.length > 0)
+                parts.push(`${trackedResult.reset.length} re-snapshotted (tracking scope changed): ${trackedResult.reset.join(", ")}`);
+            changes.push(`tracked_files (${parts.join("; ")}). Staleness is unaffected — use refresh_file_snapshot to acknowledge file changes.`);
+        }
         if (validated.tags !== undefined)
             changes.push(`tags (${doc.tags.join(", ") || "none"})`);
         if (validated.related_docs !== undefined)

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.61";
+export declare const APP_VERSION = "1.0.63";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.61';
+export const APP_VERSION = '1.0.63';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.61",
+  "version": "1.0.63",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",