@imenam/mcp-documentor 1.0.57 → 1.0.59

package/README.md

@@ -8,6 +8,7 @@ Connect it to Cursor, Claude Desktop, or any MCP-compatible agent to let your AI
 
 - **Create & update docs** — write markdown documentation entries linked to source files; prefer partial edits via `patch_doc`
 - **Staleness tracking** — automatically detects when tracked files have changed since the last doc update
+- **Portable code references** — tracked-file paths are stored relative to a configurable code root (`MCP_DOCUMENTOR_CODE_ROOT`), so synced docs resolve their source files on any machine regardless of where the repos live
 - **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
 - **Multi-project support** — organize docs into separate projects; MCP tools work across projects; `set_project` only changes what the GUI shows
 - **GUI** — built-in web interface when a proxy is configured (`PROXY_URL`); without it, the GUI worker is not started
@@ -32,6 +33,7 @@ Global install exposes:
 
 - `mcp-documentor` — MCP server
 - `mcp-documentor-migrate` — CLI helper for migrating inline doc links (see `scripts/migrate-links.js`)
+- `mcp-documentor-migrate-paths` — one-shot migration of tracked-file paths from absolute to code-root-relative (see [Portable tracked-file paths](#portable-tracked-file-paths))
 
 ## MCP Configuration
 
@@ -59,9 +61,11 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `MCP_DOCUMENTOR_OPENAI_MODEL` | No | Embedding model (default: `text-embedding-3-small`) |
 | `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+| `MCP_DOCUMENTOR_CODE_ROOT` | No | Base directory that tracked-file paths are stored relative to, keeping docs portable across machines (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
+| `MCP_DOCUMENTOR_CODE_ROOTS` | No | JSON map of per-project code-root overrides, e.g. `{"my-proj":"/srv/my-proj"}` |
 | `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |
 | `MCP_DOCUMENTOR_SYNC_REMOTE` | No | HTTPS URL of the private GitHub repo to sync with; enables GitHub sync when set |
-| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch to sync (default: `main`) |
+| `MCP_DOCUMENTOR_SYNC_BRANCH` | No | Branch of the documentation sync repo to push/pull docs on (default: `main`) |
 | `MCP_DOCUMENTOR_SYNC_TOKEN` | No | Fine-grained GitHub PAT used for HTTPS auth (see GitHub sync) |
 | `SYNC_PULL_ON_START` | No | Set to `false` to disable the automatic pull at server startup |
 
@@ -148,7 +152,7 @@ The sync target is **administrator-controlled**: the repository, branch and toke
       "args": ["-y", "@imenam/mcp-documentor"],
       "env": {
         "MCP_DOCUMENTOR_SYNC_REMOTE": "https://github.com/<you>/my-docs.git",
-        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // optional, defaults to "main"
+        "MCP_DOCUMENTOR_SYNC_BRANCH": "main",            // branch of the docs sync repo, optional, defaults to "main"
         "MCP_DOCUMENTOR_SYNC_TOKEN": "github_pat_..."
       }
     }
@@ -177,6 +181,50 @@ then run `push_docs` to publish the resolution. If you have **uncommitted** loca
 
 > Read-only machines (`READ_ONLY=1`) can still `pull_docs` and `sync_status`, but `push_docs`, `sync_docs`, and `resolve_sync_conflict` are disabled.
 
+## Portable tracked-file paths
+
+When docs are synced across machines, absolute tracked-file paths break: the codebase rarely lives at the same absolute location everywhere. To stay portable, tracked-file paths are stored **relative to a configurable code root** and resolved back to absolute paths on demand.
+
+Agents keep passing **absolute** paths to `create_doc` / `update_doc` (and in `[copy-from-codebase|…]` tags) as usual — the conversion to a stored relative path happens automatically server-side. No change in how the agent works.
+
+### Configuration
+
+Set the code root per machine (it is machine-local, so it lives in the environment, never in the synced data):
+
+```jsonc
+{
+  "env": {
+    "MCP_DOCUMENTOR_CODE_ROOT": "/home/you/code/repos",
+    // optional per-project overrides when repos don't share a common parent:
+    "MCP_DOCUMENTOR_CODE_ROOTS": "{\"my-proj\":\"/srv/my-proj\"}"
+  }
+}
+```
+
+Resolution precedence: `MCP_DOCUMENTOR_CODE_ROOTS[project]` → `MCP_DOCUMENTOR_CODE_ROOT` → none.
+
+| Stored path | On read |
+|---|---|
+| Relative + code root configured | resolved against the root |
+| Relative + **no** root on this machine | reported as `unverifiable` (source absent) instead of a false `stale` |
+| Absolute (legacy, or file outside the root) | used as-is |
+
+The feature is **opt-in**: with no code root configured, behaviour is unchanged (paths stored and resolved as absolute).
+
+### Migrating existing docs
+
+Docs created before this feature store absolute paths. Convert them in one shot with the bundled `mcp-documentor-migrate-paths`:
+
+```bash
+MCP_DOCUMENTOR_CODE_ROOT="/home/you/code/repos" \
+MCP_DATA_DIR="/path/to/your/data" \
+  npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
+```
+
+Review the report (`converted` / `kept absolute (outside root)` / `projects skipped`), then re-run without `--dry-run`. Finally publish with `sync_docs` (never commit the data dir by hand). The data dir is resolved like the server: `--data-dir` flag → `MCP_DATA_DIR` → package-relative fallback.
+
+This is a **one-time** operation, and must run on the machine whose OS/filesystem **created** the stored absolute paths (path semantics differ between Windows and POSIX). Once migrated and synced, every other machine just `pull_docs` and sets its own `MCP_DOCUMENTOR_CODE_ROOT` — no migration needed.
+
 ## Data Storage
 
 By default, data lives under **`.docs-data`** next to the resolved package root (the folder that contains `package.json` for the running install). Set **`MCP_DATA_DIR`** to use another directory. Contents include projects, SQLite/embeddings, and logs under `.docs-data/logs`. This tree is **not** part of the npm package; it is created at runtime.

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

@@ -80,6 +80,7 @@ export declare const FreshnessReportSchema: z.ZodObject<{
         up_to_date: "up_to_date";
         stale: "stale";
         no_tracking: "no_tracking";
+        unverifiable: "unverifiable";
     }>;
     modified: z.ZodArray<z.ZodString>;
     missing: z.ZodArray<z.ZodString>;

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

@@ -36,7 +36,7 @@ export const DocSchema = z.object({
     updatedAt: z.string(),
 });
 export const FreshnessReportSchema = z.object({
-    status: z.enum(["up_to_date", "stale", "no_tracking"]),
+    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable"]),
     modified: z.array(z.string()),
     missing: z.array(z.string()),
     unchanged: z.array(z.string()),
@@ -47,7 +47,7 @@ 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."),
+    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."),
     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 +59,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."),
+    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."),
     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)"),
 });
@@ -80,7 +80,7 @@ export const SearchDocsArgsSchema = z.object({
 });
 export const RefreshFileSnapshotArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to refresh, e.g. ['backend/auth/authentication', 'setup']"),
-    file_paths: z.array(z.string()).optional().describe("Specific tracked file paths to refresh, as absolute paths (refreshes all tracked files if omitted)"),
+    file_paths: z.array(z.string()).optional().describe("Specific tracked files to refresh, as absolute paths (they are matched against the stored paths, relative or absolute). Refreshes all tracked files if omitted."),
 });
 export const GetDocMetadataArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry, e.g. 'backend/auth/authentication'"),
@@ -101,7 +101,7 @@ export const CheckLinksArgsSchema = z.object({
 });
 export const GitDiffDocArgsSchema = z.object({
     paths: z.array(z.string()).min(1).describe("Paths of documentation entries to diff, e.g. ['backend/auth/authentication']"),
-    file_paths: z.array(z.string()).optional().describe("Specific tracked file paths to diff (all tracked files if omitted)"),
+    file_paths: z.array(z.string()).optional().describe("Specific tracked files to diff, as absolute paths (matched against the stored paths, relative or absolute). All tracked files if omitted."),
 });
 export const SetProjectArgsSchema = z.object({
     project: z.string().describe("Project name to switch to (created if it does not exist)"),

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

@@ -4,11 +4,11 @@ export interface CodeRefResult {
     additionalTrackedFiles: TrackedFileInput[];
 }
 export declare function resolveCodeRefs(content: string): CodeRefResult;
-export declare function snapshotTrackedFiles(inputs: TrackedFileInput[]): TrackedFile[];
+export declare function snapshotTrackedFiles(inputs: TrackedFileInput[], project: string): TrackedFile[];
 /**
  * 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.
  */
-export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[]): TrackedFile[];
+export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[], project: string): TrackedFile[];

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

@@ -2,6 +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";
 const EXT_TO_LANG = {
     ts: "typescript",
     tsx: "tsx",
@@ -46,18 +47,21 @@ export function resolveCodeRefs(content) {
     });
     return { content: resolved, additionalTrackedFiles };
 }
-export function snapshotTrackedFiles(inputs) {
+export function snapshotTrackedFiles(inputs, project) {
+    // Keyed on the *stored* (portable) path so two inputs pointing at the same
+    // file dedupe regardless of how the agent spelled the path.
     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();
         const isWhole = typeof input === "string" || input.lines.length === 0;
-        const existing = byPath.get(absolutePath);
+        const existing = byPath.get(storedPath);
         if (isWhole) {
-            byPath.set(absolutePath, { mtime, lineRanges: [], wholeFile: true });
+            byPath.set(storedPath, { absolutePath, mtime, lineRanges: [], wholeFile: true });
         }
         else if (existing) {
             if (!existing.wholeFile) {
@@ -65,7 +69,8 @@ export function snapshotTrackedFiles(inputs) {
             }
         }
         else {
-            byPath.set(absolutePath, {
+            byPath.set(storedPath, {
+                absolutePath,
                 mtime,
                 lineRanges: [...input.lines],
                 wholeFile: false,
@@ -73,16 +78,16 @@ export function snapshotTrackedFiles(inputs) {
         }
     }
     const tracked = [];
-    for (const [absolutePath, { mtime, lineRanges, wholeFile }] of byPath) {
+    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));
-            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+            tracked.push({ path: storedPath, lastModifiedAt: mtime, sections });
         }
         else {
             const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
-            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
+            tracked.push({ path: storedPath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
         }
     }
     return tracked;
@@ -93,10 +98,10 @@ export function snapshotTrackedFiles(inputs) {
  * - 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.
  */
-export function mergeTrackedFiles(existing, additions) {
+export function mergeTrackedFiles(existing, additions, project) {
     if (additions.length === 0)
         return existing;
-    const snapshotted = snapshotTrackedFiles(additions);
+    const snapshotted = snapshotTrackedFiles(additions, project);
     const result = [...existing];
     for (const newTf of snapshotted) {
         const idx = result.findIndex(tf => tf.path === newTf.path);

package/dist/src/core/path-resolver.d.ts

@@ -0,0 +1,20 @@
+/** Test-only: clears the memoised env snapshot so a changed env is re-read. */
+export declare function resetCodeRootsCache(): void;
+/** The configured code root for a project, or undefined if none applies. */
+export declare function getCodeRoot(project: string): string | undefined;
+/**
+ * Converts an input path (typically the absolute path supplied by an agent)
+ * into the portable form persisted in a doc.
+ *
+ * Falls back to an absolute path — with a warning — when there is no code root,
+ * or when the file lives outside the root (including a different Windows drive).
+ */
+export declare function toStoredPath(inputPath: string, project: string): string;
+/**
+ * Resolves a stored path to an absolute filesystem path on this machine.
+ *
+ *  - absolute stored path (legacy / fallback)  → returned as-is
+ *  - relative stored path + configured root     → joined with the root
+ *  - relative stored path + no root configured  → undefined (unverifiable here)
+ */
+export declare function toAbsolutePath(stored: string, project: string): string | undefined;

package/dist/src/core/path-resolver.js

@@ -0,0 +1,82 @@
+import path from "path";
+import { createLogger } from "@imenam/mcp-gui-interface";
+const logger = createLogger("PathResolver");
+let cached;
+function loadCodeRoots() {
+    if (cached)
+        return cached;
+    const defaultRoot = process.env.MCP_DOCUMENTOR_CODE_ROOT?.trim() || undefined;
+    let byProject = {};
+    const rawMap = process.env.MCP_DOCUMENTOR_CODE_ROOTS?.trim();
+    if (rawMap) {
+        try {
+            const parsed = JSON.parse(rawMap);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                for (const [proj, root] of Object.entries(parsed)) {
+                    if (typeof root === "string" && root.trim() !== "") {
+                        byProject[proj] = root.trim();
+                    }
+                }
+            }
+            else {
+                logger.warn("MCP_DOCUMENTOR_CODE_ROOTS is not a JSON object, ignoring it");
+            }
+        }
+        catch {
+            logger.warn("Failed to parse MCP_DOCUMENTOR_CODE_ROOTS as JSON, ignoring it");
+        }
+    }
+    cached = { default: defaultRoot, byProject };
+    return cached;
+}
+/** Test-only: clears the memoised env snapshot so a changed env is re-read. */
+export function resetCodeRootsCache() {
+    cached = undefined;
+}
+/** The configured code root for a project, or undefined if none applies. */
+export function getCodeRoot(project) {
+    const roots = loadCodeRoots();
+    return roots.byProject[project] ?? roots.default;
+}
+function toForwardSlashes(p) {
+    return p.split(path.sep).join("/");
+}
+/**
+ * Converts an input path (typically the absolute path supplied by an agent)
+ * into the portable form persisted in a doc.
+ *
+ * Falls back to an absolute path — with a warning — when there is no code root,
+ * or when the file lives outside the root (including a different Windows drive).
+ */
+export function toStoredPath(inputPath, project) {
+    const abs = path.resolve(process.cwd(), inputPath);
+    const root = getCodeRoot(project);
+    if (!root) {
+        return toForwardSlashes(abs);
+    }
+    const rel = path.relative(path.resolve(root), abs);
+    // `rel` escaping the root ("../…") or being absolute (different drive on
+    // Windows) means the file is not under the root — keep it absolute.
+    if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+        logger.warn(`tracked file "${abs}" is outside the code root for project "${project}" (${root}); storing as an absolute path`);
+        return toForwardSlashes(abs);
+    }
+    return toForwardSlashes(rel);
+}
+/**
+ * Resolves a stored path to an absolute filesystem path on this machine.
+ *
+ *  - absolute stored path (legacy / fallback)  → returned as-is
+ *  - relative stored path + configured root     → joined with the root
+ *  - relative stored path + no root configured  → undefined (unverifiable here)
+ */
+export function toAbsolutePath(stored, project) {
+    if (path.isAbsolute(stored)) {
+        return stored;
+    }
+    const root = getCodeRoot(project);
+    if (!root) {
+        return undefined;
+    }
+    return path.resolve(root, stored);
+}

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";
@@ -158,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";
             }
         }
@@ -196,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";
             }
         }
@@ -232,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";
             }
         }
@@ -344,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 },
@@ -420,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);
@@ -462,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,

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()) {

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

@@ -2,6 +2,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";
+import { toAbsolutePath, toStoredPath } from "../core/path-resolver.js";
 export async function refreshFileSnapshot(storageEngine, historyStore, args) {
     try {
         const validated = RefreshFileSnapshotArgsSchema.parse(args);
@@ -17,24 +18,26 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
             const missing = [];
             const skipped = [];
             const anchorsLost = [];
-            // Normalize to forward slashes and lowercase for case-insensitive comparison on Windows
-            // (e.g. stored 'c:\...' vs provided 'C:\...'). file_paths must be absolute paths.
+            // Normalize to forward slashes and lowercase for case-insensitive comparison
+            // on Windows. Agent-supplied file_paths are absolute; map them to the stored
+            // (portable) form so they match tracked.path regardless of representation.
             const norm = (p) => p.replace(/\\/g, "/").toLowerCase();
-            const resolvedFilePaths = validated.file_paths?.map(norm);
+            const resolvedFilePaths = validated.file_paths?.map((p) => norm(toStoredPath(p, resolvedProject)));
             for (const tracked of doc.tracked_files) {
                 if (resolvedFilePaths && !resolvedFilePaths.includes(norm(tracked.path))) {
                     skipped.push(tracked.path);
                     continue;
                 }
-                if (!fs.existsSync(tracked.path)) {
+                const absolutePath = toAbsolutePath(tracked.path, resolvedProject);
+                if (!absolutePath || !fs.existsSync(absolutePath)) {
                     missing.push(tracked.path);
                     continue;
                 }
-                tracked.lastModifiedAt = fs.statSync(tracked.path).mtime.toISOString();
+                tracked.lastModifiedAt = fs.statSync(absolutePath).mtime.toISOString();
                 if (tracked.sections && tracked.sections.length > 0) {
                     let hasLostAnchors = false;
                     const refreshedSections = tracked.sections.map((section) => {
-                        const result = relocateAndRefreshSection(tracked.path, section);
+                        const result = relocateAndRefreshSection(absolutePath, section);
                         if (!result.found)
                             hasLostAnchors = true;
                         return result.found ? result.refreshed : section;
@@ -48,7 +51,7 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
                     }
                 }
                 else {
-                    tracked.contentHash = computeFileHash(tracked.path);
+                    tracked.contentHash = computeFileHash(absolutePath);
                     refreshed.push(tracked.path);
                 }
             }

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

@@ -28,10 +28,10 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             doc.tracked_files = snapshotTrackedFiles([
                 ...validated.tracked_files,
                 ...additionalTrackedFiles,
-            ]);
+            ], resolvedProject);
         }
         else {
-            doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles);
+            doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
         }
         if (validated.tags !== undefined) {
             doc.tags = validated.tags;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.57";
+export declare const APP_VERSION = "1.0.59";

package/dist/src/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.57",
+  "version": "1.0.59",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -41,7 +41,8 @@
   "type": "module",
   "bin": {
     "mcp-documentor": "dist/src/index.js",
-    "mcp-documentor-migrate": "scripts/migrate-links.js"
+    "mcp-documentor-migrate": "scripts/migrate-links.js",
+    "mcp-documentor-migrate-paths": "scripts/migrate-paths-to-relative.js"
   },
   "files": [
     "dist",

package/scripts/migrate-paths-to-relative.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * migrate-paths-to-relative.js
+ *
+ * One-shot migration that rewrites the absolute paths stored in each doc's
+ * `tracked_files[].path` into the portable, code-root-relative form introduced
+ * alongside GitHub documentation sync. Portable paths let an agent running on a
+ * different machine (where the codebase lives at a different absolute location)
+ * resolve tracked files correctly.
+ *
+ * Resolution reuses the compiled path-resolver (dist/) so it behaves exactly
+ * like the running server — RUN `npm run build` FIRST.
+ *
+ * The conversion is driven by the same environment variables as the server:
+ *   MCP_DOCUMENTOR_CODE_ROOT    default code root
+ *   MCP_DOCUMENTOR_CODE_ROOTS   JSON map of per-project overrides
+ *
+ * A tracked file whose absolute path is NOT under the project's code root is
+ * left absolute and reported, so nothing is silently broken.
+ *
+ * The data dir is resolved like the server: --data-dir flag, else MCP_DATA_DIR,
+ * else <package>/data. The MCP_DATA_DIR fallback is what makes npx usable.
+ *
+ * Usage (from a clone):
+ *   node scripts/migrate-paths-to-relative.js [--dry-run] [--data-dir <dir>]
+ *
+ * Usage (npx install — no clone):
+ *   MCP_DOCUMENTOR_CODE_ROOT="<repos root>" MCP_DATA_DIR="<your data dir>" \
+ *     npx -p @imenam/mcp-documentor mcp-documentor-migrate-paths --dry-run
+ *
+ * This migration is a ONE-TIME operation: run it once on the machine where the
+ * stored absolute paths are valid, publish the result (sync_docs / push_docs),
+ * and every other machine just pulls and sets its own MCP_DOCUMENTOR_CODE_ROOT.
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import matter from "gray-matter";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, "..");
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+
+// Data dir resolution mirrors the server (StorageEngine.getDataDir):
+//   --data-dir flag  >  MCP_DATA_DIR env  >  <package>/data fallback.
+// The env fallback is what makes `npx` work: the data lives in the user's
+// MCP_DATA_DIR, not inside the npx package cache.
+const dataDirArgIdx = args.indexOf("--data-dir");
+const dataDir =
+  dataDirArgIdx !== -1 && args[dataDirArgIdx + 1]
+    ? args[dataDirArgIdx + 1]
+    : process.env.MCP_DATA_DIR && process.env.MCP_DATA_DIR.trim() !== ""
+      ? process.env.MCP_DATA_DIR.trim()
+      : path.join(rootDir, "data");
+
+// ---------------------------------------------------------------------------
+// Reuse the compiled resolver so migration matches runtime behaviour exactly.
+// ---------------------------------------------------------------------------
+
+const resolverPath = path.join(rootDir, "dist", "src", "core", "path-resolver.js");
+if (!fs.existsSync(resolverPath)) {
+  console.error(`[ERROR] Compiled resolver not found at: ${resolverPath}`);
+  console.error("        Run `npm run build` before this migration.");
+  process.exit(1);
+}
+const { getCodeRoot, toStoredPath } = await import(pathToFileURL(resolverPath).href);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function walkMdFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkMdFiles(fullPath));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function filePathToDocId(filePath, projectDir) {
+  return path.relative(projectDir, filePath).replace(/\.md$/, "").split(path.sep).join("/");
+}
+
+// ---------------------------------------------------------------------------
+// Load config
+// ---------------------------------------------------------------------------
+
+const configPath = path.join(dataDir, "config.json");
+if (!fs.existsSync(configPath)) {
+  console.error(`[ERROR] config.json not found at: ${configPath}`);
+  console.error("        Make sure --data-dir points to the right directory.");
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+const projects = config.projects ?? ["default"];
+
+console.log(`${dryRun ? "[DRY RUN] " : ""}migrate-paths-to-relative`);
+console.log(`Data dir : ${dataDir}`);
+console.log(`Projects : ${projects.length}`);
+console.log("");
+
+// ---------------------------------------------------------------------------
+// Migrate
+// ---------------------------------------------------------------------------
+
+let totalDocsChanged = 0;
+let totalConverted = 0;
+let totalLeftAbsolute = 0;
+const projectsWithoutRoot = [];
+
+for (const project of projects) {
+  const root = getCodeRoot(project);
+  if (!root) {
+    projectsWithoutRoot.push(project);
+    continue;
+  }
+
+  const projectDir = path.join(dataDir, "projects", project);
+  const files = walkMdFiles(projectDir);
+  if (files.length === 0) continue;
+
+  const docChanges = [];
+
+  for (const filePath of files) {
+    const fullId = filePathToDocId(filePath, projectDir);
+    const parsed = matter(fs.readFileSync(filePath, "utf-8"));
+    const tracked = parsed.data.tracked_files;
+    if (!Array.isArray(tracked) || tracked.length === 0) continue;
+
+    let docChanged = false;
+    for (const tf of tracked) {
+      if (!tf || typeof tf.path !== "string") continue;
+      if (!path.isAbsolute(tf.path)) continue; // already relative
+
+      const stored = toStoredPath(tf.path, project);
+      if (path.isAbsolute(stored)) {
+        // Outside the root (or different drive) — resolver kept it absolute.
+        totalLeftAbsolute++;
+        docChanges.push(`  [${fullId}] KEPT ABSOLUTE (outside root): ${tf.path}`);
+        continue;
+      }
+
+      docChanges.push(`  [${fullId}] "${tf.path}"  →  "${stored}"`);
+      tf.path = stored;
+      docChanged = true;
+      totalConverted++;
+    }
+
+    if (docChanged) {
+      totalDocsChanged++;
+      if (!dryRun) {
+        fs.writeFileSync(filePath, matter.stringify(parsed.content, parsed.data), "utf-8");
+      }
+    }
+  }
+
+  if (docChanges.length > 0) {
+    console.log(`### Project: ${project}  (root: ${root})`);
+    docChanges.forEach((c) => console.log(c));
+    console.log("");
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log("─".repeat(60));
+console.log(`Paths converted to relative : ${totalConverted}`);
+console.log(`Paths kept absolute         : ${totalLeftAbsolute}  ← outside the code root`);
+console.log(`Docs modified               : ${totalDocsChanged}`);
+if (projectsWithoutRoot.length > 0) {
+  console.log("");
+  console.log(`Projects skipped (no code root configured): ${projectsWithoutRoot.length}`);
+  console.log(`  ${projectsWithoutRoot.join(", ")}`);
+  console.log("  → set MCP_DOCUMENTOR_CODE_ROOT or add them to MCP_DOCUMENTOR_CODE_ROOTS to migrate them.");
+}
+
+if (dryRun) {
+  console.log("");
+  console.log("[DRY RUN] No files were modified. Run without --dry-run to apply.");
+}