@imenam/mcp-documentor 1.0.56 → 1.0.58

package/dist/src/core/storage-engine.d.ts

@@ -5,6 +5,17 @@ interface GlobalConfig {
     projects: string[];
     foldersMigrated?: boolean;
 }
+/**
+ * GitHub sync settings. Sourced exclusively from environment variables — the
+ * repository, branch and token are administration concerns and must never be
+ * settable by the agent at runtime.
+ */
+export interface SyncConfig {
+    remoteUrl: string;
+    branch: string;
+    /** PAT for HTTPS auth (MCP_DOCUMENTOR_SYNC_TOKEN). */
+    token?: string;
+}
 export declare class StorageEngine {
     private rootDir;
     private historyStore?;
@@ -13,8 +24,19 @@ export declare class StorageEngine {
     getDataDir(): string;
     getProjectDir(project?: string): string;
     private getConfigPath;
+    private getLocalStatePath;
+    private readLocalState;
+    private writeLocalState;
+    /**
+     * Returns the merged config. The shared part (projects list, migration flags)
+     * comes from config.json (versioned), while currentProject is a machine-local
+     * preference sourced from local-state.json (gitignored). Legacy config.json
+     * files that still embed currentProject are migrated transparently.
+     */
     getConfig(): GlobalConfig;
     saveConfig(config: GlobalConfig): void;
+    /** Reads sync settings from environment variables (admin-controlled, not agent-settable). */
+    getSyncConfig(): SyncConfig | undefined;
     ensureProject(project: string): void;
     private walkMdFiles;
     private docIdToFilePath;

package/dist/src/core/storage-engine.js

@@ -27,22 +27,81 @@ export class StorageEngine {
     getConfigPath() {
         return path.join(this.getDataDir(), "config.json");
     }
+    getLocalStatePath() {
+        return path.join(this.getDataDir(), "local-state.json");
+    }
+    readLocalState() {
+        const p = this.getLocalStatePath();
+        if (fs.existsSync(p)) {
+            try {
+                return JSON.parse(fs.readFileSync(p, "utf-8"));
+            }
+            catch {
+                logger.warn("Failed to parse local-state.json, using defaults");
+            }
+        }
+        return {};
+    }
+    writeLocalState(state) {
+        const p = this.getLocalStatePath();
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, JSON.stringify(state, null, 2), "utf-8");
+    }
+    /**
+     * Returns the merged config. The shared part (projects list, migration flags)
+     * comes from config.json (versioned), while currentProject is a machine-local
+     * preference sourced from local-state.json (gitignored). Legacy config.json
+     * files that still embed currentProject are migrated transparently.
+     */
     getConfig() {
         const configPath = this.getConfigPath();
+        let shared = {};
         if (fs.existsSync(configPath)) {
             try {
-                return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+                shared = JSON.parse(fs.readFileSync(configPath, "utf-8"));
             }
             catch {
                 logger.warn("Failed to parse config.json, using defaults");
             }
         }
-        return { currentProject: "default", projects: ["default"] };
+        const local = this.readLocalState();
+        const projects = shared.projects ?? ["default"];
+        // Migrate a legacy currentProject embedded in config.json into local-state.
+        if (shared.currentProject !== undefined && local.currentProject === undefined) {
+            local.currentProject = shared.currentProject;
+            this.writeLocalState(local);
+            delete shared.currentProject;
+            fs.writeFileSync(configPath, JSON.stringify(shared, null, 2), "utf-8");
+            logger.info("Migrated currentProject from config.json to local-state.json");
+        }
+        return {
+            currentProject: local.currentProject ?? projects[0] ?? "default",
+            projects,
+            foldersMigrated: shared.foldersMigrated,
+        };
     }
     saveConfig(config) {
+        // Shared, versioned part → config.json (currentProject is intentionally excluded).
         const configPath = this.getConfigPath();
+        const shared = {
+            projects: config.projects,
+            foldersMigrated: config.foldersMigrated,
+        };
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
-        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+        fs.writeFileSync(configPath, JSON.stringify(shared, null, 2), "utf-8");
+        // Machine-local part → local-state.json.
+        const local = this.readLocalState();
+        local.currentProject = config.currentProject;
+        this.writeLocalState(local);
+    }
+    /** Reads sync settings from environment variables (admin-controlled, not agent-settable). */
+    getSyncConfig() {
+        const remoteUrl = process.env.MCP_DOCUMENTOR_SYNC_REMOTE?.trim();
+        if (!remoteUrl)
+            return undefined;
+        const branch = process.env.MCP_DOCUMENTOR_SYNC_BRANCH?.trim() || "main";
+        const token = process.env.MCP_DOCUMENTOR_SYNC_TOKEN?.trim() || undefined;
+        return { remoteUrl, branch, token };
     }
     ensureProject(project) {
         const projectDir = path.join(this.getDataDir(), "projects", project);

package/dist/src/index.js

@@ -18,6 +18,7 @@ import { updateDoc } from "./tools/update-doc.js";
 import { searchDocs } from "./tools/search-docs.js";
 import { checkFreshness, computeFreshness } from "./tools/check-freshness.js";
 import { findAndHashSection } from "./core/section-tracker.js";
+import { toAbsolutePath } from "./core/path-resolver.js";
 import { setProject } from "./tools/set-project.js";
 import { listProjects } from "./tools/list-projects.js";
 import { refreshFileSnapshot } from "./tools/refresh-file-snapshot.js";
@@ -39,6 +40,8 @@ import { prepareExportBundle } from "./tools/prepare-export-bundle.js";
 import { deleteExportBundle } from "./tools/delete-export-bundle.js";
 import { uploadImage } from "./tools/upload-image.js";
 import { getImage } from "./tools/get-image.js";
+import { SyncEngine } from "./core/git-sync.js";
+import { syncStatus, pullDocs, pushDocs, syncDocs, resolveSyncConflict } from "./tools/sync.js";
 import { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -75,6 +78,7 @@ embeddingStore.init(storageEngine.getDataDir(), openaiModel);
 const historyStore = new HistoryStore();
 historyStore.init(storageEngine.getDataDir());
 storageEngine.setHistoryStore(historyStore);
+const syncEngine = new SyncEngine(storageEngine);
 const server = new Server({ name: "mcp-documentor", version: APP_VERSION }, { capabilities: { tools: {} } });
 let guiLauncher;
 const sseControllers = new Set();
@@ -155,7 +159,7 @@ async function handleGetInitialState(msg) {
         for (const doc of docs) {
             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);
+                const report = computeFreshness(full.tracked_files, config.currentProject);
                 doc.isStale = report.status === "stale";
             }
         }
@@ -193,7 +197,7 @@ async function handleUpdateProject(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files);
+                const report = computeFreshness(full.tracked_files, project);
                 doc.isStale = report.status === "stale";
             }
         }
@@ -229,11 +233,12 @@ async function handleListProjects(msg) {
 }
 async function handleListDocs(msg) {
     try {
+        const currentProject = storageEngine.getConfig().currentProject;
         const docs = await storageEngine.listDocs();
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files);
+                const report = computeFreshness(full.tracked_files, currentProject);
                 doc.isStale = report.status === "stale";
             }
         }
@@ -341,15 +346,15 @@ async function handleCreateDocIPC(msg) {
             data: { success: true, id },
             timestamp: new Date().toISOString(),
         });
+        const config = storageEngine.getConfig();
         const docs = await storageEngine.listDocs();
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files);
+                const report = computeFreshness(full.tracked_files, config.currentProject);
                 doc.isStale = report.status === "stale";
             }
         }
-        const config = storageEngine.getConfig();
         broadcastToGUI({
             type: "INITIAL_STATE",
             data: { config, docs, projects: config.projects },
@@ -417,7 +422,9 @@ async function handleGetFileSection(msg) {
         const trackedFile = resolved.doc.tracked_files.find((f) => f.path === filePath);
         if (!trackedFile || !trackedFile.sections?.length)
             throw new Error("No sections for this file");
-        const absolutePath = path.resolve(process.cwd(), filePath);
+        const absolutePath = toAbsolutePath(trackedFile.path, resolved.project);
+        if (!absolutePath)
+            throw new Error("Cannot resolve file on this machine (no code root configured)");
         const fileLines = fs.readFileSync(absolutePath, "utf-8").split("\n");
         const sections = trackedFile.sections.map((section) => {
             const result = findAndHashSection(absolutePath, section);
@@ -459,7 +466,7 @@ async function handleCheckFreshness(msg) {
             });
             return;
         }
-        const report = computeFreshness(doc.tracked_files);
+        const report = computeFreshness(doc.tracked_files, resolved.project);
         broadcastToGUI({
             type: "CHECK_FRESHNESS_RESPONSE",
             correlationId: msg.correlationId,
@@ -1030,6 +1037,48 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 required: ["uri"],
             },
         },
+        {
+            name: "sync_status",
+            description: "Show the synchronization status: current branch, how many commits the local repo is ahead/behind the remote, conflicted files, and uncommitted changes. The sync target (repository, branch, token) is fixed by the server administrator via environment variables and cannot be changed from here.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "pull_docs",
+            description: "Pull documentation updates from the GitHub remote. Defensive: only fast-forwards a clean working tree, never auto-merges a divergent history (local data is never overwritten). Reindexes embeddings for new documents after a successful update.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "push_docs",
+            description: "Commit local documentation changes (markdown + assets + project list) and push them to the GitHub remote.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: { type: "string", description: "Optional commit message (a default with machine name and timestamp is used otherwise)" },
+                },
+            },
+        },
+        {
+            name: "sync_docs",
+            description: "Full synchronization: pull (defensive) then push. If the pull reveals a divergence or conflict, the push is skipped so it can be resolved first.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    message: { type: "string", description: "Optional commit message for the push step" },
+                },
+            },
+        },
+        {
+            name: "resolve_sync_conflict",
+            description: "Bulk-resolve sync merge conflicts by keeping one side for the conflicted files, then stage them. For nuanced resolution, edit the conflicted markdown files directly instead. After resolving, run push_docs.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    strategy: { type: "string", enum: ["mine", "theirs"], description: "'mine' keeps the local version, 'theirs' keeps the incoming remote version" },
+                    paths: { type: "array", items: { type: "string" }, description: "Specific conflicted file paths to resolve (defaults to all conflicted files)" },
+                },
+                required: ["strategy"],
+            },
+        },
     ];
     return {
         tools: isReadOnly() ? tools.filter((t) => !WRITE_TOOLS.has(t.name)) : tools,
@@ -1111,6 +1160,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await uploadImage(storageEngine, args);
             case "get_image":
                 return await getImage(storageEngine, args);
+            case "sync_status":
+                return await syncStatus(syncEngine);
+            case "pull_docs":
+                return await pullDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore);
+            case "push_docs":
+                return await pushDocs(syncEngine, args);
+            case "sync_docs":
+                return await syncDocs(syncEngine, storageEngine, embeddingEngine, embeddingStore, args);
+            case "resolve_sync_conflict":
+                return await resolveSyncConflict(syncEngine, args);
             default:
                 throw new Error(`Tool not found: ${name}`);
         }
@@ -1122,9 +1181,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
     }
 });
+async function syncPullOnStartup() {
+    if (!syncEngine.isConfigured())
+        return;
+    if ((process.env.SYNC_PULL_ON_START ?? "").trim().toLowerCase() === "false")
+        return;
+    try {
+        const res = await syncEngine.pull();
+        if (res.status === "updated") {
+            logger.info(`Startup sync: pulled ${res.changed.length} changed file(s).`);
+            if (embeddingEngine.isConfigured()) {
+                await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, {});
+            }
+        }
+        else if (res.status === "diverged") {
+            logger.warn(`Startup sync: local history diverged (ahead ${res.ahead}, behind ${res.behind}). Started on local data — run sync_status / sync_docs to reconcile.`);
+        }
+        else if (res.status === "conflict") {
+            logger.warn(`Startup sync: merge conflict in ${res.conflicted.length} file(s). Started on local data — resolve with resolve_sync_conflict.`);
+        }
+        else {
+            logger.info("Startup sync: already up to date.");
+        }
+    }
+    catch (err) {
+        logger.error(`Startup sync failed (non-fatal): ${err?.message ?? err}`);
+    }
+}
 async function main() {
     await migrateFolders(storageEngine);
     await migrateEmbeddings(embeddingStore, storageEngine);
+    await syncPullOnStartup();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logger.info("MCP Server connected and running on stdio");

package/dist/src/tools/check-freshness.d.ts

@@ -1,7 +1,7 @@
 import type { TrackedFile, FreshnessReport } from "../../shared/schemas/doc.schema.js";
 import type { StorageEngine } from "../core/storage-engine.js";
 export declare function computeFileHash(absolutePath: string): string;
-export declare function computeFreshness(trackedFiles: TrackedFile[]): FreshnessReport;
+export declare function computeFreshness(trackedFiles: TrackedFile[], project: string): FreshnessReport;
 export declare function formatFreshnessReport(title: string, report: FreshnessReport): string;
 export declare function checkFreshness(storageEngine: StorageEngine, args: unknown): Promise<{
     isError: boolean;

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

@@ -1,12 +1,12 @@
 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";
+import { toAbsolutePath } from "../core/path-resolver.js";
 export function computeFileHash(absolutePath) {
     return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
 }
-export function computeFreshness(trackedFiles) {
+export function computeFreshness(trackedFiles, project) {
     if (!trackedFiles || trackedFiles.length === 0) {
         return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], total: 0 };
     }
@@ -15,8 +15,11 @@ export function computeFreshness(trackedFiles) {
     const unchanged = [];
     const anchors_lost = [];
     for (const tracked of trackedFiles) {
-        const absolutePath = path.resolve(process.cwd(), tracked.path);
-        if (!fs.existsSync(absolutePath)) {
+        // 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
+        // than crying wolf with "stale".
+        const absolutePath = toAbsolutePath(tracked.path, project);
+        if (!absolutePath || !fs.existsSync(absolutePath)) {
             missing.push(tracked.path);
             continue;
         }
@@ -68,6 +71,15 @@ export function computeFreshness(trackedFiles) {
             }
         }
     }
+    // When every tracked file is absent, the source code simply isn't present on
+    // this machine (e.g. docs cloned without the codebase) — we can't verify
+    // freshness, so report "unverifiable" rather than crying wolf with "stale".
+    // A partial absence (some files missing, others present) is treated as a real
+    // 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 };
+    }
     const isStale = modified.length > 0 || missing.length > 0 || anchors_lost.length > 0;
     return {
         status: isStale ? "stale" : "up_to_date",
@@ -82,6 +94,9 @@ export function formatFreshnessReport(title, report) {
     if (report.status === "no_tracking") {
         return `No tracked files for "${title}". Use tracked_files when creating or updating the doc to enable staleness detection.`;
     }
+    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`;
@@ -100,6 +115,15 @@ export function formatFreshnessReport(title, report) {
     }
     return text;
 }
+/** Cap on how many "not tracking any file" doc titles are listed before collapsing into a count. */
+const UNTRACKED_LIST_LIMIT = 10;
+/** Renders the untracked-docs list, truncated past UNTRACKED_LIST_LIMIT to avoid flooding the context. */
+function renderUntrackedList(titles, heading) {
+    const shown = titles.slice(0, UNTRACKED_LIST_LIMIT).map((t) => `  - ${t}`);
+    const remaining = titles.length - UNTRACKED_LIST_LIMIT;
+    const suffix = remaining > 0 ? `\n  … and ${remaining} more` : "";
+    return `\n\n${heading}\n${shown.join("\n")}${suffix}`;
+}
 export async function checkFreshness(storageEngine, args) {
     try {
         const validated = CheckFreshnessArgsSchema.parse(args);
@@ -108,8 +132,8 @@ export async function checkFreshness(storageEngine, args) {
             if (!resolved) {
                 return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
             }
-            const { doc } = resolved;
-            const report = computeFreshness(doc.tracked_files);
+            const { doc, project } = resolved;
+            const report = computeFreshness(doc.tracked_files, project);
             return { content: [{ type: "text", text: formatFreshnessReport(doc.title, report) }] };
         }
         if (validated.project) {
@@ -120,14 +144,18 @@ export async function checkFreshness(storageEngine, args) {
             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);
+                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}`),
@@ -141,12 +169,12 @@ export async function checkFreshness(storageEngine, args) {
                 }
             }
             let text = `# Freshness report — project "${validated.project}"\n\n`;
-            text += `${summaries.length} doc(s) scanned: **${stale.length} stale**, ${upToDate} up to date, ${noTracking.length} untracked.\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 += `\n\n## Untracked docs (no staleness detection)\n${noTracking.map((t) => `  - ${t}`).join("\n")}`;
+                text += renderUntrackedList(noTracking, "## Docs not tracking any file (no staleness detection)");
             }
             return { content: [{ type: "text", text }] };
         }
@@ -161,14 +189,18 @@ export async function checkFreshness(storageEngine, args) {
             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);
+                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}`),
@@ -184,12 +216,12 @@ export async function checkFreshness(storageEngine, args) {
             totalDocs += summaries.length;
             totalStale += stale.length;
             let block = `## ${proj}\n\n`;
-            block += `${summaries.length} doc(s): **${stale.length} stale**, ${upToDate} up to date, ${noTracking.length} untracked.`;
+            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 += `\n\n### Untracked docs\n${noTracking.map((t) => `  - ${t}`).join("\n")}`;
+                block += renderUntrackedList(noTracking, "### Docs not tracking any file");
             }
             projectBlocks.push(block);
         }

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

@@ -31,11 +31,12 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         if (project) {
             storageEngine.ensureProject(project);
         }
+        const resolvedProject = project ?? storageEngine.getConfig().currentProject;
         const allTrackedInputs = [
             ...(validated.tracked_files ?? []),
             ...additionalTrackedFiles,
         ];
-        const trackedFiles = allTrackedInputs.length > 0 ? snapshotTrackedFiles(allTrackedInputs) : [];
+        const trackedFiles = allTrackedInputs.length > 0 ? snapshotTrackedFiles(allTrackedInputs, resolvedProject) : [];
         const folder = validated.folder;
         const doc = {
             id,
@@ -48,7 +49,6 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
             createdAt: now,
             updatedAt: now,
         };
-        const resolvedProject = project ?? storageEngine.getConfig().currentProject;
         await storageEngine.saveDoc(doc, resolvedProject, "create");
         if (embeddingEngine.isConfigured()) {
             const embedding = await embeddingEngine.generateEmbedding(content);

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

@@ -1,6 +1,8 @@
+import fs from "fs";
 import { GetDocMetadataArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
 import { findAndHashSection } from "../core/section-tracker.js";
+import { toAbsolutePath } from "../core/path-resolver.js";
 export async function getDocMetadata(storageEngine, args) {
     try {
         const validated = GetDocMetadataArgsSchema.parse(args);
@@ -8,8 +10,8 @@ export async function getDocMetadata(storageEngine, args) {
         if (!resolved) {
             return { isError: true, content: [{ type: "text", text: `Documentation entry "${validated.path}" not found in any project.` }] };
         }
-        const { doc } = resolved;
-        const report = computeFreshness(doc.tracked_files);
+        const { doc, project } = resolved;
+        const report = computeFreshness(doc.tracked_files, project);
         const fileStatusIcon = (filePath) => {
             if (report.modified.includes(filePath))
                 return "✗ modified";
@@ -28,8 +30,10 @@ export async function getDocMetadata(storageEngine, args) {
             text += doc.tracked_files.map((f) => {
                 let entry = `  ${fileStatusIcon(f.path)} — ${f.path}\n  File mtime: ${f.lastModifiedAt}`;
                 if (f.sections && f.sections.length > 0) {
+                    const abs = toAbsolutePath(f.path, project);
+                    const readable = abs && fs.existsSync(abs);
                     const sectionLines = f.sections.map((section, idx) => {
-                        const result = findAndHashSection(f.path, section);
+                        const result = readable ? findAndHashSection(abs, section) : { found: false };
                         const location = result.found
                             ? `lines ${result.lines.start}–${result.lines.end}`
                             : "section introuvable (ancres modifiées)";

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

@@ -1,6 +1,8 @@
+import fs from "fs";
 import { GetDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
 import { findAndHashSection } from "../core/section-tracker.js";
+import { toAbsolutePath } from "../core/path-resolver.js";
 export async function getDoc(storageEngine, args) {
     try {
         const validated = GetDocArgsSchema.parse(args);
@@ -12,8 +14,10 @@ export async function getDoc(storageEngine, args) {
         const trackedFilesText = doc.tracked_files.length > 0
             ? doc.tracked_files.map((f) => {
                 if (f.sections && f.sections.length > 0) {
+                    const abs = toAbsolutePath(f.path, resolvedProject);
+                    const readable = abs && fs.existsSync(abs);
                     const sectionLines = f.sections.map((section, idx) => {
-                        const result = findAndHashSection(f.path, section);
+                        const result = readable ? findAndHashSection(abs, section) : { found: false };
                         const location = result.found
                             ? `lines ${result.lines.start}–${result.lines.end}`
                             : "section introuvable";
@@ -24,7 +28,7 @@ export async function getDoc(storageEngine, args) {
                 return `  - ${f.path} (snapshot: ${f.lastModifiedAt})`;
             }).join("\n")
             : "  (none)";
-        const freshnessReport = computeFreshness(doc.tracked_files);
+        const freshnessReport = computeFreshness(doc.tracked_files, resolvedProject);
         const stalenessBanner = freshnessReport.status === "stale"
             ? [
                 `> [!WARNING]`,

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

@@ -2,8 +2,12 @@ import { execSync } from "child_process";
 import path from "path";
 import { GitDiffDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
-function getGitDiffForFile(tracked) {
-    const filePath = tracked.path;
+import { toAbsolutePath, toStoredPath } from "../core/path-resolver.js";
+function getGitDiffForFile(tracked, project) {
+    const filePath = toAbsolutePath(tracked.path, project);
+    if (!filePath) {
+        return `  [INFO] Cannot resolve "${tracked.path}" on this machine (no code root configured) — source absent.`;
+    }
     const fileDir = path.dirname(filePath);
     let repoRoot;
     try {
@@ -46,17 +50,18 @@ export async function gitDiffDoc(storageEngine, args) {
                 docSections.push(`## ${docPath}\n\n[ERROR] Documentation entry not found in any project.`);
                 continue;
             }
-            const { doc } = resolved;
+            const { doc, project } = resolved;
             if (!doc.tracked_files || doc.tracked_files.length === 0) {
                 docSections.push(`## ${doc.title}\n\n[INFO] No tracked files.`);
                 continue;
             }
             let filesToDiff;
             if (validated.file_paths) {
-                filesToDiff = doc.tracked_files.filter((tf) => validated.file_paths.includes(tf.path));
+                const wanted = new Set(validated.file_paths.map((p) => toStoredPath(p, project)));
+                filesToDiff = doc.tracked_files.filter((tf) => wanted.has(tf.path));
             }
             else {
-                const freshness = computeFreshness(doc.tracked_files);
+                const freshness = computeFreshness(doc.tracked_files, project);
                 const changedPaths = new Set([...freshness.modified, ...freshness.missing]);
                 filesToDiff = doc.tracked_files.filter((tf) => changedPaths.has(tf.path));
             }
@@ -75,7 +80,7 @@ export async function gitDiffDoc(storageEngine, args) {
                 return true;
             })
                 .map((tf) => {
-                const diff = getGitDiffForFile(tf);
+                const diff = getGitDiffForFile(tf, project);
                 return `### ${tf.path}\nSnapshot date: ${tf.lastModifiedAt}\n\n${diff}`;
             });
             if (fileSections.length === 0) {

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

@@ -41,7 +41,7 @@ export async function listDocs(storageEngine, args) {
             for (const summary of summaries) {
                 const doc = await storageEngine.getDoc(summary.id, proj);
                 if (doc && doc.tracked_files.length > 0) {
-                    const report = computeFreshness(doc.tracked_files);
+                    const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
                 }
             }
@@ -59,7 +59,7 @@ export async function listDocs(storageEngine, args) {
             for (const summary of summaries) {
                 const doc = await storageEngine.getDoc(summary.id, proj);
                 if (doc && doc.tracked_files.length > 0) {
-                    const report = computeFreshness(doc.tracked_files);
+                    const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
                 }
             }

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

@@ -28,7 +28,7 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
             };
         }
         doc.content = doc.content.replace(search, replacement);
-        doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles);
+        doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
         doc.updatedAt = new Date().toISOString();
         await storageEngine.saveDoc(doc, resolvedProject, "patch");
         if (embeddingEngine.isConfigured()) {