@imenam/mcp-documentor 1.0.34 → 1.0.36

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

@@ -1,10 +1,37 @@
 import { z } from "zod";
+export declare const TrackedSectionSchema: z.ZodObject<{
+    anchors: z.ZodObject<{
+        top: z.ZodArray<z.ZodString>;
+        bottom: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    sectionHash: z.ZodString;
+}, z.core.$strip>;
+export type TrackedSection = z.infer<typeof TrackedSectionSchema>;
 export declare const TrackedFileSchema: z.ZodObject<{
     path: z.ZodString;
     lastModifiedAt: z.ZodString;
     contentHash: z.ZodOptional<z.ZodString>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        anchors: z.ZodObject<{
+            top: z.ZodArray<z.ZodString>;
+            bottom: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        sectionHash: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type TrackedFile = z.infer<typeof TrackedFileSchema>;
+export declare const TrackedFileInputLineSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+}, z.core.$strip>;
+export declare const TrackedFileInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    path: z.ZodString;
+    lines: z.ZodArray<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export type TrackedFileInput = z.infer<typeof TrackedFileInputSchema>;
 export declare const DocSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -13,6 +40,13 @@ export declare const DocSchema: z.ZodObject<{
         path: z.ZodString;
         lastModifiedAt: z.ZodString;
         contentHash: z.ZodOptional<z.ZodString>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            anchors: z.ZodObject<{
+                top: z.ZodArray<z.ZodString>;
+                bottom: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+            sectionHash: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
     folder: z.ZodOptional<z.ZodString>;
@@ -47,13 +81,20 @@ export declare const FreshnessReportSchema: z.ZodObject<{
     modified: z.ZodArray<z.ZodString>;
     missing: z.ZodArray<z.ZodString>;
     unchanged: z.ZodArray<z.ZodString>;
+    anchors_lost: z.ZodDefault<z.ZodArray<z.ZodString>>;
     total: z.ZodNumber;
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
 export declare const CreateDocArgsSchema: z.ZodObject<{
     title: z.ZodString;
     content: z.ZodString;
-    tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        lines: z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     folder: z.ZodOptional<z.ZodString>;
     related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -62,7 +103,13 @@ export declare const UpdateDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
-    tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        lines: z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;

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

@@ -1,9 +1,28 @@
 import { z } from "zod";
+export const TrackedSectionSchema = z.object({
+    anchors: z.object({
+        top: z.array(z.string()),
+        bottom: z.array(z.string()),
+    }),
+    sectionHash: z.string(),
+});
 export const TrackedFileSchema = z.object({
     path: z.string(),
     lastModifiedAt: z.string(),
     contentHash: z.string().optional(),
-});
+    sections: z.array(TrackedSectionSchema).optional(),
+});
+export const TrackedFileInputLineSchema = z.object({
+    start: z.number().int().positive(),
+    end: z.number().int().positive(),
+});
+export const TrackedFileInputSchema = z.union([
+    z.string(),
+    z.object({
+        path: z.string(),
+        lines: z.array(TrackedFileInputLineSchema).min(1),
+    }),
+]);
 export const DocSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -20,12 +39,13 @@ export const FreshnessReportSchema = z.object({
     modified: z.array(z.string()),
     missing: z.array(z.string()),
     unchanged: z.array(z.string()),
+    anchors_lost: 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().describe("Documentation content in markdown"),
-    tracked_files: z.array(z.string()).optional().describe("File paths to track for staleness detection"),
+    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."),
     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"),
@@ -34,7 +54,7 @@ export const UpdateDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
     title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
-    tracked_files: z.array(z.string()).optional().describe("New list of file paths (replaces existing)"),
+    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."),
     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/section-tracker.d.ts

@@ -0,0 +1,40 @@
+import type { TrackedSection } from "../../shared/schemas/doc.schema.js";
+/**
+ * Reads a file and snapshots a section defined by 1-indexed [start, end] line numbers.
+ * Extracts top/bottom anchor lines and computes a hash of the section content.
+ * The `lines` input is intentionally not persisted — only anchors and sectionHash are stored.
+ */
+export declare function snapshotSection(absolutePath: string, start: number, end: number): TrackedSection;
+type FindResult = {
+    found: false;
+} | {
+    found: true;
+    currentHash: string;
+    lines: {
+        start: number;
+        end: number;
+    };
+};
+/**
+ * Locates a tracked section in the current file content using its stored anchors,
+ * then hashes the found content for comparison with the stored sectionHash.
+ * Also returns the current 1-indexed line range where the section was found,
+ * so callers can display it without storing it.
+ *
+ * Returns { found: false } if the anchors cannot be located — which is treated as stale,
+ * since the surrounding context has changed enough to invalidate the documentation.
+ */
+export declare function findAndHashSection(absolutePath: string, section: TrackedSection): FindResult;
+type RelocateResult = {
+    found: false;
+} | {
+    found: true;
+    refreshed: TrackedSection;
+};
+/**
+ * Locates a section by its current anchors, then refreshes its sectionHash to match
+ * the current file content. Used by refresh_file_snapshot to acknowledge changes.
+ * Anchors are kept as-is (they were found successfully); only sectionHash is updated.
+ */
+export declare function relocateAndRefreshSection(absolutePath: string, section: TrackedSection): RelocateResult;
+export {};

package/dist/src/core/section-tracker.js

@@ -0,0 +1,99 @@
+import crypto from "crypto";
+import fs from "fs";
+const ANCHOR_SIZE = 3;
+/**
+ * Reads a file and snapshots a section defined by 1-indexed [start, end] line numbers.
+ * Extracts top/bottom anchor lines and computes a hash of the section content.
+ * The `lines` input is intentionally not persisted — only anchors and sectionHash are stored.
+ */
+export function snapshotSection(absolutePath, start, end) {
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const allLines = fileContent.split("\n");
+    const startIdx = Math.max(0, start - 1);
+    const endIdx = Math.min(allLines.length - 1, end - 1);
+    const sectionLines = allLines.slice(startIdx, endIdx + 1);
+    let top;
+    let bottom;
+    if (sectionLines.length < ANCHOR_SIZE * 2) {
+        // Short section: all lines become the top anchor; bottom is empty (section = top anchor)
+        top = [...sectionLines];
+        bottom = [];
+    }
+    else {
+        top = sectionLines.slice(0, ANCHOR_SIZE);
+        bottom = sectionLines.slice(sectionLines.length - ANCHOR_SIZE);
+    }
+    const sectionHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+    return { anchors: { top, bottom }, sectionHash };
+}
+/**
+ * Locates a tracked section in the current file content using its stored anchors,
+ * then hashes the found content for comparison with the stored sectionHash.
+ * Also returns the current 1-indexed line range where the section was found,
+ * so callers can display it without storing it.
+ *
+ * Returns { found: false } if the anchors cannot be located — which is treated as stale,
+ * since the surrounding context has changed enough to invalidate the documentation.
+ */
+export function findAndHashSection(absolutePath, section) {
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const fileLines = fileContent.split("\n");
+    const { top, bottom } = section.anchors;
+    if (bottom.length === 0) {
+        // Short-section path: the top anchor IS the full section content
+        for (let i = 0; i <= fileLines.length - top.length; i++) {
+            if (top.every((line, j) => fileLines[i + j] === line)) {
+                const sectionLines = fileLines.slice(i, i + top.length);
+                const currentHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+                return { found: true, currentHash, lines: { start: i + 1, end: i + top.length } };
+            }
+        }
+        return { found: false };
+    }
+    // Normal path: locate top anchor, then search for bottom anchor below it
+    for (let i = 0; i <= fileLines.length - top.length; i++) {
+        if (!top.every((line, j) => fileLines[i + j] === line))
+            continue;
+        const searchStart = i + top.length;
+        for (let k = searchStart; k <= fileLines.length - bottom.length; k++) {
+            if (!bottom.every((line, j) => fileLines[k + j] === line))
+                continue;
+            const sectionLines = fileLines.slice(i, k + bottom.length);
+            const currentHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+            return { found: true, currentHash, lines: { start: i + 1, end: k + bottom.length } };
+        }
+    }
+    return { found: false };
+}
+/**
+ * Locates a section by its current anchors, then refreshes its sectionHash to match
+ * the current file content. Used by refresh_file_snapshot to acknowledge changes.
+ * Anchors are kept as-is (they were found successfully); only sectionHash is updated.
+ */
+export function relocateAndRefreshSection(absolutePath, section) {
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const fileLines = fileContent.split("\n");
+    const { top, bottom } = section.anchors;
+    if (bottom.length === 0) {
+        for (let i = 0; i <= fileLines.length - top.length; i++) {
+            if (top.every((line, j) => fileLines[i + j] === line)) {
+                const sectionHash = crypto.createHash("sha256").update(fileLines.slice(i, i + top.length).join("\n")).digest("hex");
+                return { found: true, refreshed: { anchors: section.anchors, sectionHash } };
+            }
+        }
+        return { found: false };
+    }
+    for (let i = 0; i <= fileLines.length - top.length; i++) {
+        if (!top.every((line, j) => fileLines[i + j] === line))
+            continue;
+        const searchStart = i + top.length;
+        for (let k = searchStart; k <= fileLines.length - bottom.length; k++) {
+            if (!bottom.every((line, j) => fileLines[k + j] === line))
+                continue;
+            const sectionLines = fileLines.slice(i, k + bottom.length);
+            const sectionHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+            return { found: true, refreshed: { anchors: section.anchors, sectionHash } };
+        }
+    }
+    return { found: false };
+}

package/dist/src/index.js

@@ -450,8 +450,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         content: { type: "string", description: "Documentation content in markdown. To link to another document inline, use the syntax [text](doc://target-doc-id) — the viewer will navigate to that document on click. To link to a heading within the same document, use [text](#heading-slug). Use check_links to validate both types. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql." },
                         tracked_files: {
                             type: "array",
-                            items: { type: "string" },
-                            description: "File paths to track for staleness detection",
+                            items: {
+                                oneOf: [
+                                    { type: "string", description: "Plain file path for whole-file tracking" },
+                                    {
+                                        type: "object",
+                                        properties: {
+                                            path: { type: "string", description: "File path to track" },
+                                            lines: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
+                                                        end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
+                                                    },
+                                                    required: ["start", "end"],
+                                                },
+                                                minItems: 1,
+                                                description: "One or more line ranges to track within the file",
+                                            },
+                                        },
+                                        required: ["path", "lines"],
+                                        description: "Granular section tracking: only the specified line ranges are monitored",
+                                    },
+                                ],
+                            },
+                            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).",
                         },
                         tags: {
                             type: "array",
@@ -504,8 +529,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         content: { type: "string", description: "New content (replaces existing). Supports [text](doc://target-doc-path) to link inline to other documents, and [text](#heading-slug) to link to headings within this document. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql." },
                         tracked_files: {
                             type: "array",
-                            items: { type: "string" },
-                            description: "New list of file paths (replaces existing)",
+                            items: {
+                                oneOf: [
+                                    { type: "string", description: "Plain file path for whole-file tracking" },
+                                    {
+                                        type: "object",
+                                        properties: {
+                                            path: { type: "string", description: "File path to track" },
+                                            lines: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
+                                                        end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
+                                                    },
+                                                    required: ["start", "end"],
+                                                },
+                                                minItems: 1,
+                                                description: "One or more line ranges to track within the file",
+                                            },
+                                        },
+                                        required: ["path", "lines"],
+                                        description: "Granular section tracking: only the specified line ranges are monitored",
+                                    },
+                                ],
+                            },
+                            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).",
                         },
                         tags: {
                             type: "array",

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

@@ -2,23 +2,52 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { CheckFreshnessArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { findAndHashSection } from "../core/section-tracker.js";
 export function computeFileHash(absolutePath) {
     return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
 }
 export function computeFreshness(trackedFiles) {
     if (!trackedFiles || trackedFiles.length === 0) {
-        return { status: "no_tracking", modified: [], missing: [], unchanged: [], total: 0 };
+        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], total: 0 };
     }
     const modified = [];
     const missing = [];
     const unchanged = [];
+    const anchors_lost = [];
     for (const tracked of trackedFiles) {
         const absolutePath = path.resolve(process.cwd(), tracked.path);
         if (!fs.existsSync(absolutePath)) {
             missing.push(tracked.path);
             continue;
         }
-        if (tracked.contentHash) {
+        if (tracked.sections && tracked.sections.length > 0) {
+            let sectionStale = false;
+            let anchorLost = false;
+            for (const section of tracked.sections) {
+                const result = findAndHashSection(absolutePath, section);
+                if (!result.found) {
+                    sectionStale = true;
+                    anchorLost = true;
+                    break;
+                }
+                else if (result.currentHash !== section.sectionHash) {
+                    sectionStale = true;
+                    break;
+                }
+            }
+            if (sectionStale) {
+                if (anchorLost) {
+                    anchors_lost.push(tracked.path);
+                }
+                else {
+                    modified.push(tracked.path);
+                }
+            }
+            else {
+                unchanged.push(tracked.path);
+            }
+        }
+        else if (tracked.contentHash) {
             const currentHash = computeFileHash(absolutePath);
             if (currentHash !== tracked.contentHash) {
                 modified.push(tracked.path);
@@ -39,12 +68,13 @@ export function computeFreshness(trackedFiles) {
             }
         }
     }
-    const isStale = modified.length > 0 || missing.length > 0;
+    const isStale = modified.length > 0 || missing.length > 0 || anchors_lost.length > 0;
     return {
         status: isStale ? "stale" : "up_to_date",
         modified,
         missing,
         unchanged,
+        anchors_lost,
         total: trackedFiles.length,
     };
 }
@@ -55,13 +85,19 @@ export function formatFreshnessReport(title, report) {
     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`;
-    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    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).`;
     if (report.modified.length > 0) {
-        text += `\n\nModified files:\n${report.modified.map((f) => `  - ${f}`).join("\n")}`;
+        text += `\n\nModified files (call refresh_file_snapshot to acknowledge):\n${report.modified.map((f) => `  - ${f}`).join("\n")}`;
     }
     if (report.missing.length > 0) {
         text += `\n\nMissing files:\n${report.missing.map((f) => `  - ${f}`).join("\n")}`;
     }
+    if (anchorLostCount > 0) {
+        text += `\n\n⚠ Files with lost anchors — refresh_file_snapshot cannot fix this:\n${report.anchors_lost.map((f) => `  - ${f}`).join("\n")}`;
+        text += `\n  → The tracked section(s) could not be located in the current file content (anchors were likely modified by a recent commit).`;
+        text += `\n  → Required action: call update_doc with the new line numbers to re-establish section tracking.`;
+    }
     return text;
 }
 export async function checkFreshness(storageEngine, args) {
@@ -96,6 +132,7 @@ export async function checkFreshness(storageEngine, args) {
                     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}`);
                 }
@@ -136,6 +173,7 @@ export async function checkFreshness(storageEngine, args) {
                     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}`);
                 }

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

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import { CreateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
+import { snapshotSection } from "../core/section-tracker.js";
 function slugify(title) {
     return title
         .normalize("NFD")
@@ -10,17 +11,24 @@ function slugify(title) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-|-$/g, "");
 }
-function snapshotTrackedFiles(filePaths) {
+function snapshotTrackedFiles(inputs) {
     const tracked = [];
-    for (const fp of filePaths) {
+    for (const input of inputs) {
+        const fp = typeof input === "string" ? input : input.path;
         const absolutePath = path.resolve(process.cwd(), fp);
-        let mtime = new Date().toISOString();
-        let contentHash;
-        if (fs.existsSync(absolutePath)) {
-            mtime = fs.statSync(absolutePath).mtime.toISOString();
-            contentHash = computeFileHash(absolutePath);
+        const mtime = fs.existsSync(absolutePath)
+            ? fs.statSync(absolutePath).mtime.toISOString()
+            : new Date().toISOString();
+        if (typeof input !== "string" && input.lines.length > 0 && fs.existsSync(absolutePath)) {
+            const sections = input.lines
+                .filter(({ start, end }) => start <= end)
+                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+        }
+        else {
+            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
         }
-        tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
     }
     return tracked;
 }

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

@@ -1,5 +1,6 @@
 import { GetDocMetadataArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
+import { findAndHashSection } from "../core/section-tracker.js";
 export async function getDocMetadata(storageEngine, args) {
     try {
         const validated = GetDocMetadataArgsSchema.parse(args);
@@ -24,9 +25,20 @@ export async function getDocMetadata(storageEngine, args) {
         text += `**Freshness:** ${report.status}\n`;
         if (doc.tracked_files.length > 0) {
             text += `\nTracked files (${doc.tracked_files.length} total):\n`;
-            text += doc.tracked_files
-                .map((f) => `  ${fileStatusIcon(f.path)} — ${f.path}\n  Snapshot: ${f.lastModifiedAt}`)
-                .join("\n");
+            text += doc.tracked_files.map((f) => {
+                let entry = `  ${fileStatusIcon(f.path)} — ${f.path}\n  Snapshot: ${f.lastModifiedAt}`;
+                if (f.sections && f.sections.length > 0) {
+                    const sectionLines = f.sections.map((section, idx) => {
+                        const result = findAndHashSection(f.path, section);
+                        const location = result.found
+                            ? `lines ${result.lines.start}–${result.lines.end}`
+                            : "section introuvable (ancres modifiées)";
+                        return `    - Section ${idx + 1}: ${location}`;
+                    });
+                    entry += `\n  Sections (position actuelle):\n${sectionLines.join("\n")}`;
+                }
+                return entry;
+            }).join("\n");
         }
         else {
             text += "\nNo tracked files.";

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

@@ -1,5 +1,6 @@
 import { GetDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
+import { findAndHashSection } from "../core/section-tracker.js";
 export async function getDoc(storageEngine, args) {
     try {
         const validated = GetDocArgsSchema.parse(args);
@@ -9,7 +10,19 @@ export async function getDoc(storageEngine, args) {
         }
         const { doc, project: resolvedProject } = resolved;
         const trackedFilesText = doc.tracked_files.length > 0
-            ? doc.tracked_files.map((f) => `  - ${f.path} (snapshot: ${f.lastModifiedAt})`).join("\n")
+            ? doc.tracked_files.map((f) => {
+                if (f.sections && f.sections.length > 0) {
+                    const sectionLines = f.sections.map((section, idx) => {
+                        const result = findAndHashSection(f.path, section);
+                        const location = result.found
+                            ? `lines ${result.lines.start}–${result.lines.end}`
+                            : "section introuvable";
+                        return `    - Section ${idx + 1}: ${location}`;
+                    });
+                    return `  - ${f.path} (snapshot: ${f.lastModifiedAt})\n${sectionLines.join("\n")}`;
+                }
+                return `  - ${f.path} (snapshot: ${f.lastModifiedAt})`;
+            }).join("\n")
             : "  (none)";
         const freshnessReport = computeFreshness(doc.tracked_files);
         const stalenessBanner = freshnessReport.status === "stale"

package/dist/src/tools/refresh-file-snapshot.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { RefreshFileSnapshotArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
+import { relocateAndRefreshSection } from "../core/section-tracker.js";
 export async function refreshFileSnapshot(storageEngine, historyStore, args) {
     try {
         const validated = RefreshFileSnapshotArgsSchema.parse(args);
@@ -15,6 +16,7 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
             const refreshed = [];
             const missing = [];
             const skipped = [];
+            const anchorsLost = [];
             for (const tracked of doc.tracked_files) {
                 if (validated.file_paths && !validated.file_paths.includes(tracked.path)) {
                     skipped.push(tracked.path);
@@ -25,16 +27,39 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
                     continue;
                 }
                 tracked.lastModifiedAt = fs.statSync(tracked.path).mtime.toISOString();
-                tracked.contentHash = computeFileHash(tracked.path);
-                refreshed.push(tracked.path);
+                if (tracked.sections && tracked.sections.length > 0) {
+                    let hasLostAnchors = false;
+                    const refreshedSections = tracked.sections.map((section) => {
+                        const result = relocateAndRefreshSection(tracked.path, section);
+                        if (!result.found)
+                            hasLostAnchors = true;
+                        return result.found ? result.refreshed : section;
+                    });
+                    tracked.sections = refreshedSections;
+                    if (hasLostAnchors) {
+                        anchorsLost.push(tracked.path);
+                    }
+                    else {
+                        refreshed.push(tracked.path);
+                    }
+                }
+                else {
+                    tracked.contentHash = computeFileHash(tracked.path);
+                    refreshed.push(tracked.path);
+                }
             }
             await storageEngine.saveDoc(doc, resolvedProject);
             historyStore.record(resolvedProject, doc, "snapshot");
-            let section = `**${doc.title}** [${docPath}]: refreshed ${refreshed.length}, missing ${missing.length}, skipped ${skipped.length}`;
+            let section = `**${doc.title}** [${docPath}]: refreshed ${refreshed.length}, anchors lost ${anchorsLost.length}, missing ${missing.length}, skipped ${skipped.length}`;
             if (refreshed.length > 0)
                 section += `\n${refreshed.map((f) => `  ✓ ${f}`).join("\n")}`;
             if (missing.length > 0)
-                section += `\n${missing.map((f) => `  ✗ ${f}`).join("\n")}`;
+                section += `\n${missing.map((f) => `  ✗ missing: ${f}`).join("\n")}`;
+            if (anchorsLost.length > 0) {
+                section += `\n${anchorsLost.map((f) => `  ⚠ anchors lost: ${f}`).join("\n")}`;
+                section += `\n  → refresh_file_snapshot cannot fix this. The tracked section(s) could not be located in the current file content.`;
+                section += `\n  → Required action: call update_doc with the new line numbers to re-establish section tracking.`;
+            }
             docSections.push(section);
         }
         return { content: [{ type: "text", text: docSections.join("\n\n") }] };

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

@@ -2,17 +2,25 @@ import fs from "fs";
 import path from "path";
 import { UpdateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
-function snapshotTrackedFiles(filePaths) {
+import { snapshotSection } from "../core/section-tracker.js";
+function snapshotTrackedFiles(inputs) {
     const tracked = [];
-    for (const fp of filePaths) {
+    for (const input of inputs) {
+        const fp = typeof input === "string" ? input : input.path;
         const absolutePath = path.resolve(process.cwd(), fp);
-        let mtime = new Date().toISOString();
-        let contentHash;
-        if (fs.existsSync(absolutePath)) {
-            mtime = fs.statSync(absolutePath).mtime.toISOString();
-            contentHash = computeFileHash(absolutePath);
+        const mtime = fs.existsSync(absolutePath)
+            ? fs.statSync(absolutePath).mtime.toISOString()
+            : new Date().toISOString();
+        if (typeof input !== "string" && input.lines.length > 0 && fs.existsSync(absolutePath)) {
+            const sections = input.lines
+                .filter(({ start, end }) => start <= end)
+                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+        }
+        else {
+            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
         }
-        tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
     }
     return tracked;
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.34";
+export declare const APP_VERSION = "1.0.36";

package/dist/src/version.js

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

package/package.json

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