@imenam/mcp-documentor 1.0.77 → 1.0.78

package/README.md

@@ -9,6 +9,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
+- **Track a branch, not a checkout** — point a project at a GitHub branch (`MCP_DOCUMENTOR_CODE_REPO`) and freshness is measured against *published* code: switching branches or editing without committing no longer makes docs look stale, and a server with no copy of the codebase (an MCP gateway) can still verify them
 - **Semantic search** — find relevant docs by meaning (requires an OpenAI API key)
 - **Multi-project support** — organize docs into separate projects; every MCP tool names the project it targets, and the GUI's project selector is a per-browser view preference
 - **GUI** — built-in web interface, either behind the proxy (`PROXY_URL`) or served directly on a local port (`APP_PORT`); with neither, the GUI worker is not started
@@ -94,6 +95,9 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `MCP_LOG_DIR` | No | Overrides the log directory of both the server and the GUI worker (default: `<package>/.docs-data/logs`). Must be set in the MCP client config — the package `.env` is loaded after the logger starts |
 | `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"}` |
+| `MCP_DOCUMENTOR_CODE_REPO` | No | Track a **GitHub branch** instead of the local working copy. Either one spec applied to every project — `owner/repo`, a GitHub URL, optional `#branch` suffix — or a JSON map of per-project specs, e.g. `{"web":"you/web#main","legacy":"local"}` (the value `local` opts a project back out to its working copy). Setting it is what enables the mode (see [Tracking a GitHub branch](#tracking-a-github-branch-instead-of-the-working-copy)) |
+| `MCP_DOCUMENTOR_CODE_BRANCH` | No | Branch used for repositories carrying no `#branch` suffix (default: the repository's own default branch) |
+| `MCP_DOCUMENTOR_CODE_TOKEN` | No | GitHub token used to read the code; falls back to `MCP_DOCUMENTOR_SYNC_TOKEN` |
 | `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 of the documentation sync repo to push/pull docs on (default: `main`) |
@@ -260,6 +264,60 @@ Review the report (`converted` / `kept absolute (outside root)` / `projects skip
 
 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.
 
+## Tracking a GitHub branch instead of the working copy
+
+By default, freshness is measured against the **working copy on the machine running the server**. That has two consequences: switching git branches locally flips docs in and out of `stale` even though the deployed code never moved, and a server that has no copy of the codebase — typically an MCP gateway on another host — cannot verify anything at all.
+
+Pointing a project at a repository makes the documentation track **one branch of published code** instead:
+
+```jsonc
+{
+  "env": {
+    "MCP_DOCUMENTOR_CODE_REPO": "you/my-repo#main",
+    // optional: reuses MCP_DOCUMENTOR_SYNC_TOKEN when omitted
+    "MCP_DOCUMENTOR_CODE_TOKEN": "github_pat_..."
+  }
+}
+```
+
+A repository names exactly one codebase, so an instance serving **several projects** gives `MCP_DOCUMENTOR_CODE_REPO` a JSON map instead of a single spec — a leading `{` is what tells the two apart:
+
+```jsonc
+"MCP_DOCUMENTOR_CODE_REPO": "{\"web\":\"you/web#main\",\"api\":\"you/api#main\",\"legacy\":\"local\"}"
+```
+
+Projects absent from the map, and projects whose value is `local`, keep reading their local working copy. **With the variable unset, nothing changes** — the local behaviour is untouched.
+
+The token needs **Contents: Read** on the code repository (a different repo from the docs sync one, so either widen the existing PAT's scope or issue a second one).
+
+### What changes once a project tracks a branch
+
+| | Local working copy (default) | GitHub branch |
+|---|---|---|
+| Sees uncommitted edits | yes | no — only what is pushed |
+| Affected by `git checkout` | yes | no |
+| Needs the codebase on the server | yes | no |
+| `git_diff_doc` baseline | last commit before the snapshot date | the exact commit the snapshot was taken at |
+
+Every report names the source it used (`Code source: GitHub you/my-repo@main`), so a verdict is never ambiguous. If the source cannot be reached — network, auth, rate limit — the status is `unverifiable` with the reason attached, **never** `stale`.
+
+### Paths and migration
+
+Stored tracked-file paths are already relative to the code root, and a code root is normally the repository root — so **existing docs keep working as-is**, with no migration and no mass re-snapshot. Two details make the switch seamless:
+
+- Hashes are computed on line-ending-normalised content, so a snapshot taken from a CRLF checkout still matches the LF blob in the repository. Hashes stored by earlier versions are still recognised.
+- Absolute paths sent by an agent are reduced by the code root when one is configured, and otherwise matched against the repository tree by their longest unambiguous suffix (a bare filename is only accepted when the repository holds exactly one file by that name).
+
+Docs snapshotted before the switch carry no source commit: `check_freshness` works immediately, while `git_diff_doc` will ask for one `refresh_file_snapshot` to anchor them on the branch.
+
+### API usage
+
+Freshness is **never computed in the background** — only when something asks for it: a `check_freshness` / `list_docs` / `get_doc` call, or the GUI loading a project's list. So the cost is bounded per request, not per unit of time.
+
+Within one such request, the branch head is resolved **once** and every tracked file is compared against that same commit — no mixed verdict if someone pushes mid-scan. The next request resolves it again, so a push is visible immediately: there is no staleness window to configure.
+
+Everything else is content-addressed and therefore cached for the life of the process: a commit's tree by its sha, a file's bytes by its blob sha. Each tracked file also records the blob sha it was snapshotted at, so an unchanged file is proven untouched without being downloaded at all. A full scan of an unchanged repository costs about two API calls — not one per file.
+
 ## 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

@@ -20,6 +20,8 @@ export declare const TrackedFileSchema: z.ZodObject<{
         sectionHash: z.ZodString;
         lineCount: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    sourceRevision: z.ZodOptional<z.ZodString>;
+    sourceBlobId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type TrackedFile = z.infer<typeof TrackedFileSchema>;
 export declare const TrackedFileInputLineSchema: z.ZodObject<{
@@ -50,6 +52,8 @@ export declare const DocSchema: z.ZodObject<{
             sectionHash: z.ZodString;
             lineCount: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>>>;
+        sourceRevision: z.ZodOptional<z.ZodString>;
+        sourceBlobId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
     folder: z.ZodOptional<z.ZodString>;
@@ -91,6 +95,8 @@ export declare const FreshnessReportSchema: z.ZodObject<{
     anchors_lost: z.ZodDefault<z.ZodArray<z.ZodString>>;
     broken: z.ZodDefault<z.ZodArray<z.ZodString>>;
     total: z.ZodNumber;
+    source: z.ZodOptional<z.ZodString>;
+    sourceError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
 export declare const CreateDocArgsSchema: z.ZodObject<{

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

@@ -12,6 +12,18 @@ export const TrackedFileSchema = z.object({
     lastModifiedAt: z.string(),
     contentHash: z.string().optional(),
     sections: z.array(TrackedSectionSchema).optional(),
+    /**
+     * Commit the snapshot was taken at, when the project reads its code from a repository.
+     * Absent for snapshots taken from a local working copy, which has no revision to record.
+     * `git_diff_doc` uses it as the diff base.
+     */
+    sourceRevision: z.string().optional(),
+    /**
+     * Content identity the source can hand over without transferring the file — the git blob sha
+     * on GitHub. When it still matches, the file is provably untouched and never gets downloaded,
+     * which is what keeps a full freshness scan down to a couple of API calls.
+     */
+    sourceBlobId: z.string().optional(),
 });
 export const TrackedFileInputLineSchema = z.object({
     start: z.number().int().positive(),
@@ -44,6 +56,10 @@ export const FreshnessReportSchema = z.object({
     /** Entries with neither sections nor contentHash (pre hash-based tracking) — cannot be checked until re-tracked. */
     broken: z.array(z.string()).default([]),
     total: z.number(),
+    /** Where the code was read from, e.g. "GitHub Imena/mcp-documentor@main" or "local working copy". */
+    source: z.string().optional(),
+    /** Set when the source could not be consulted at all (network, auth, rate limit) — the report is then "unverifiable", never "stale". */
+    sourceError: z.string().optional(),
 });
 /**
  * Every tool that targets a specific documentation entry takes this. It is mandatory
@@ -59,7 +75,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. Provide absolute paths, or paths relative to the project's configured code root (MCP_DOCUMENTOR_CODE_ROOT); paths under the root are stored relative to it so the docs stay portable across machines. Tracked files must exist."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's code root; they are stored relative to that root so the docs stay portable across machines. Tracked files must exist at the project's code source — which is the local working copy by default, or a branch of a GitHub repository when one is configured for the project (check_freshness reports which)."),
     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"),
@@ -72,7 +88,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). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's configured code root (MCP_DOCUMENTOR_CODE_ROOT)."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's code root."),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),
     related_docs: z.array(z.string()).optional().describe("Paths of related documentation entries (replaces existing)"),
 });

package/dist/src/cli/setup-mcp.js

@@ -67,6 +67,9 @@ const GENERATED_VARS = [
 ];
 const OPTIONAL_VARS = [
     ["MCP_DOCUMENTOR_CODE_ROOTS", 'code roots par projet, ex: {"my-proj":"/srv/my-proj"}'],
+    ["MCP_DOCUMENTOR_CODE_REPO", 'repo GitHub suivi au lieu de la copie locale : "owner/repo#main", ou une map JSON par projet {"my-proj":"owner/repo#main","legacy":"local"}'],
+    ["MCP_DOCUMENTOR_CODE_BRANCH", "branche suivie quand le repo n'a pas de suffixe #branche"],
+    ["MCP_DOCUMENTOR_CODE_TOKEN", "PAT GitHub pour lire le code (défaut : MCP_DOCUMENTOR_SYNC_TOKEN)"],
     ["READ_ONLY", "1/true pour désactiver toutes les écritures"],
     ["SYNC_PULL_ON_START", "false pour désactiver le pull au démarrage"],
 ];

package/dist/src/core/code-operation.d.ts

@@ -0,0 +1,10 @@
+/** Runs `fn` as one operation. Anything it starts, however deeply nested, shares one scratch space. */
+export declare function runInCodeOperation<T>(fn: () => T): T;
+/**
+ * Computes `key` at most once per operation. Outside an operation there is nothing to share, so
+ * `compute` simply runs.
+ *
+ * The promise is what gets memoised, so concurrent callers await the same in-flight request — and
+ * a failure is remembered too, rather than retried once per tracked file.
+ */
+export declare function oncePerOperation<T>(key: string, compute: () => Promise<T>): Promise<T>;

package/dist/src/core/code-operation.js

@@ -0,0 +1,42 @@
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * Scratch space shared by everything that runs while handling one request — one MCP tool call,
+ * one GUI message — and discarded when it ends.
+ *
+ * It exists for facts that must be *fresh at the moment the user asks* but *constant while the
+ * answer is being computed*. Resolving which commit a branch points at is the one such fact:
+ *
+ *  - re-resolving it per tracked file would cost one API call per file and, worse, let a push
+ *    landing mid-scan produce a verdict where some docs were judged against the old commit and
+ *    others against the new one;
+ *  - caching it for a fixed duration would answer a question asked *now* with a branch head read
+ *    minutes ago, and nothing would ever recompute it in between — freshness is only ever
+ *    computed on demand, there is no background scan to catch up.
+ *
+ * Scoping it to the operation gives both: always the current branch head, resolved exactly once.
+ * Content caches do not belong here — blobs and trees are addressed by their own sha, so they are
+ * immutable and stay cached for the life of the process.
+ */
+const storage = new AsyncLocalStorage();
+/** Runs `fn` as one operation. Anything it starts, however deeply nested, shares one scratch space. */
+export function runInCodeOperation(fn) {
+    return storage.run(new Map(), fn);
+}
+/**
+ * Computes `key` at most once per operation. Outside an operation there is nothing to share, so
+ * `compute` simply runs.
+ *
+ * The promise is what gets memoised, so concurrent callers await the same in-flight request — and
+ * a failure is remembered too, rather than retried once per tracked file.
+ */
+export function oncePerOperation(key, compute) {
+    const store = storage.getStore();
+    if (!store)
+        return compute();
+    const pending = store.get(key);
+    if (pending)
+        return pending;
+    const promise = compute();
+    store.set(key, promise);
+    return promise;
+}

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

@@ -3,8 +3,15 @@ export interface CodeRefResult {
     content: string;
     additionalTrackedFiles: TrackedFileInput[];
 }
-export declare function resolveCodeRefs(content: string): CodeRefResult;
-export declare function snapshotTrackedFiles(inputs: TrackedFileInput[], project: string): TrackedFile[];
+/**
+ * Expands every `[copy-from-codebase|path|start|end]` marker with the referenced lines, read
+ * from the project's code source, and reports each reference so the caller can track it.
+ *
+ * A reference that cannot be read is left in place untouched — the marker is more useful to the
+ * agent than a silently empty block.
+ */
+export declare function resolveCodeRefs(content: string, project: string): Promise<CodeRefResult>;
+export declare function snapshotTrackedFiles(inputs: TrackedFileInput[], project: string): Promise<TrackedFile[]>;
 export interface ResnapshotResult {
     tracked: TrackedFile[];
     /** Files already tracked whose stored snapshot was carried over untouched. */
@@ -23,7 +30,7 @@ export interface ResnapshotResult {
  * doc that was stale before this call is still stale after it. Files that were not tracked before
  * necessarily carry a snapshot of their current content: there is no earlier state to preserve.
  */
-export declare function resnapshotPreserving(existing: TrackedFile[], inputs: TrackedFileInput[], project: string): ResnapshotResult;
+export declare function resnapshotPreserving(existing: TrackedFile[], inputs: TrackedFileInput[], project: string): Promise<ResnapshotResult>;
 /**
  * Merges snapshotted tracked files into an existing list, without ever refreshing what is
  * already tracked — acknowledging staleness is `refresh_file_snapshot`'s job alone.
@@ -32,4 +39,4 @@ export declare function resnapshotPreserving(existing: TrackedFile[], inputs: Tr
  *   that region is appended; existing sections keep their stored hash.
  * - Otherwise the existing entry is left untouched.
  */
-export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[], project: string): TrackedFile[];
+export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[], project: string): Promise<TrackedFile[]>;

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

@@ -1,8 +1,8 @@
-import crypto from "crypto";
-import fs from "fs";
 import path from "path";
-import { snapshotSection } from "./section-tracker.js";
-import { toAbsolutePath, toStoredPath } from "./path-resolver.js";
+import { createLogger } from "@imenam/mcp-gui-interface";
+import { snapshotSection, hashFileContent } from "./section-tracker.js";
+import { getCodeSource } from "./code-source.js";
+const logger = createLogger("CodeRefResolver");
 const EXT_TO_LANG = {
     ts: "typescript",
     tsx: "tsx",
@@ -26,78 +26,103 @@ const EXT_TO_LANG = {
 // Syntax: [copy-from-codebase|/absolute/path/to/file.ts|10|50]
 // Using | as separator to avoid conflicts with Windows drive letters (C:\...)
 const CODE_REF_REGEX = /\[copy-from-codebase\|([^|]+)\|(\d+)\|(\d+)\]/g;
-function computeFileHash(absolutePath) {
-    return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
-}
-export function resolveCodeRefs(content) {
+/**
+ * Expands every `[copy-from-codebase|path|start|end]` marker with the referenced lines, read
+ * from the project's code source, and reports each reference so the caller can track it.
+ *
+ * A reference that cannot be read is left in place untouched — the marker is more useful to the
+ * agent than a silently empty block.
+ */
+export async function resolveCodeRefs(content, project) {
+    const matches = [...content.matchAll(CODE_REF_REGEX)];
+    if (matches.length === 0)
+        return { content, additionalTrackedFiles: [] };
+    const source = getCodeSource(project);
     const additionalTrackedFiles = [];
-    const resolved = content.replace(CODE_REF_REGEX, (match, filePath, startStr, endStr) => {
+    const replacements = new Map();
+    for (const match of matches) {
+        const [marker, filePath, startStr, endStr] = match;
+        if (replacements.has(marker))
+            continue;
         const start = parseInt(startStr, 10);
         const end = parseInt(endStr, 10);
-        if (!fs.existsSync(filePath)) {
-            console.warn(`[copy-from-codebase] File not found: ${filePath}`);
-            return match;
+        let file;
+        try {
+            file = await source.read(await source.toStoredPath(filePath));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn(`[copy-from-codebase] Could not read ${filePath} from ${source.label}: ${message}`);
+            continue;
+        }
+        if (!file) {
+            logger.warn(`[copy-from-codebase] File not found in ${source.label}: ${filePath}`);
+            continue;
         }
-        const lines = fs.readFileSync(filePath, "utf-8").split("\n");
-        const extracted = lines.slice(start - 1, end).join("\n");
-        const ext = path.extname(filePath).slice(1).toLowerCase();
-        const lang = EXT_TO_LANG[ext] ?? "";
+        const extracted = file.content.lines.slice(start - 1, end).join("\n");
+        const lang = EXT_TO_LANG[path.extname(filePath).slice(1).toLowerCase()] ?? "";
+        replacements.set(marker, `\`\`\`${lang}\n${extracted}\n\`\`\``);
         additionalTrackedFiles.push({ path: filePath, lines: [{ start, end }] });
-        return `\`\`\`${lang}\n${extracted}\n\`\`\``;
-    });
+    }
+    const resolved = content.replace(CODE_REF_REGEX, (marker) => replacements.get(marker) ?? marker);
     return { content: resolved, additionalTrackedFiles };
 }
-export function snapshotTrackedFiles(inputs, project) {
+export async function snapshotTrackedFiles(inputs, project) {
+    const source = getCodeSource(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;
-        // A relative input path means "relative to the project's code root" — the same
-        // convention used everywhere a stored path is read back. Never the server's cwd.
-        const absolutePath = toAbsolutePath(fp, project);
-        if (!absolutePath) {
-            throw new Error(`Cannot track "${fp}": the path is relative but no code root is configured for project "${project}". Provide an absolute path or set MCP_DOCUMENTOR_CODE_ROOT.`);
-        }
-        if (!fs.existsSync(absolutePath)) {
-            throw new Error(`Cannot track "${fp}": file not found at ${absolutePath}. Tracking snapshots the file content, so the file must exist.`);
-        }
-        const storedPath = toStoredPath(absolutePath, project);
-        const mtime = fs.statSync(absolutePath).mtime.toISOString();
-        const isWhole = typeof input === "string" || input.lines.length === 0;
+        const lines = typeof input === "string" ? [] : input.lines;
+        const storedPath = await toStoredPathOrThrow(source, fp, project);
         const existing = byPath.get(storedPath);
-        if (isWhole) {
-            byPath.set(storedPath, { absolutePath, mtime, lineRanges: [], wholeFile: true });
+        if (lines.length === 0) {
+            byPath.set(storedPath, { lineRanges: [], wholeFile: true });
         }
         else if (existing) {
-            if (!existing.wholeFile) {
-                existing.lineRanges.push(...input.lines);
-            }
+            if (!existing.wholeFile)
+                existing.lineRanges.push(...lines);
         }
         else {
-            byPath.set(storedPath, {
-                absolutePath,
-                mtime,
-                lineRanges: [...input.lines],
-                wholeFile: false,
-            });
+            byPath.set(storedPath, { lineRanges: [...lines], wholeFile: false });
         }
     }
     const tracked = [];
-    for (const [storedPath, { absolutePath, mtime, lineRanges, wholeFile }] of byPath) {
+    for (const [storedPath, { lineRanges, wholeFile }] of byPath) {
+        const file = await source.read(storedPath);
+        if (!file) {
+            throw new Error(`Cannot track "${storedPath}": not found in ${source.label}. Tracking snapshots the file content, so the file must exist there.`);
+        }
         const validRanges = lineRanges.filter(({ start, end }) => start <= end);
+        const base = {
+            path: storedPath,
+            lastModifiedAt: file.lastModifiedAt,
+            sourceRevision: file.revision,
+            sourceBlobId: file.blobId,
+        };
         if (!wholeFile && validRanges.length > 0) {
-            const sections = dedupeSections(validRanges.map(({ start, end }) => snapshotSection(absolutePath, start, end)));
-            tracked.push({ path: storedPath, lastModifiedAt: mtime, sections });
+            const sections = dedupeSections(validRanges.map(({ start, end }) => snapshotSection(file.content, start, end)));
+            tracked.push({ ...base, sections });
         }
         else {
             // Whole-file tracking — also the landing spot when every provided range was
             // invalid, so an entry never ends up with neither sections nor contentHash.
-            tracked.push({ path: storedPath, lastModifiedAt: mtime, contentHash: computeFileHash(absolutePath) });
+            tracked.push({ ...base, contentHash: hashFileContent(file.content) });
         }
     }
     return tracked;
 }
+/** Maps an agent-supplied path to its stored form, turning a source-specific failure into a clear error. */
+async function toStoredPathOrThrow(source, inputPath, project) {
+    try {
+        return await source.toStoredPath(inputPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Cannot track "${inputPath}" for project "${project}": ${message}`);
+    }
+}
 const sameLines = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
 /** Two sections describe the same region when they were anchored on the same top/bottom lines. */
 function sameRegion(a, b) {
@@ -137,8 +162,8 @@ function carryOverSnapshot(previous, fresh) {
  * doc that was stale before this call is still stale after it. Files that were not tracked before
  * necessarily carry a snapshot of their current content: there is no earlier state to preserve.
  */
-export function resnapshotPreserving(existing, inputs, project) {
-    const fresh = snapshotTrackedFiles(inputs, project);
+export async function resnapshotPreserving(existing, inputs, project) {
+    const fresh = await snapshotTrackedFiles(inputs, project);
     const byPath = new Map(existing.map((tf) => [tf.path, tf]));
     const preserved = [];
     const added = [];
@@ -167,13 +192,13 @@ export function resnapshotPreserving(existing, inputs, project) {
  *   that region is appended; existing sections keep their stored hash.
  * - Otherwise the existing entry is left untouched.
  */
-export function mergeTrackedFiles(existing, additions, project) {
+export async function mergeTrackedFiles(existing, additions, project) {
     if (additions.length === 0)
         return existing;
-    const snapshotted = snapshotTrackedFiles(additions, project);
+    const snapshotted = await snapshotTrackedFiles(additions, project);
     const result = [...existing];
     for (const newTf of snapshotted) {
-        const idx = result.findIndex(tf => tf.path === newTf.path);
+        const idx = result.findIndex((tf) => tf.path === newTf.path);
         if (idx < 0) {
             result.push(newTf);
             continue;

package/dist/src/core/code-source.d.ts

@@ -0,0 +1,79 @@
+import type { TrackedSection } from "../../shared/schemas/doc.schema.js";
+import { type FileContent } from "./section-tracker.js";
+import { GitHubCodeApi } from "./github-code-api.js";
+/**
+ * Where a project's source code is read from when checking or snapshotting documentation.
+ *
+ * Two backends:
+ *
+ *  - **local** — the working copy on this machine, resolved through the code roots. This is the
+ *    original behaviour and stays the default: it sees uncommitted work, and it sees whichever
+ *    branch happens to be checked out.
+ *  - **github** — one branch of one repository, read over the GitHub API. The documentation then
+ *    tracks *published* code: switching branches locally, or editing without committing, no longer
+ *    makes docs look stale, and a server that has no copy of the codebase at all (an MCP gateway)
+ *    can still verify freshness.
+ *
+ * A project uses the GitHub backend only when a repository is configured for it. With no
+ * repository set, everything behaves exactly as before.
+ *
+ *   MCP_DOCUMENTOR_CODE_REPO      the repository to read code from, in either of two shapes:
+ *                                 a single spec — "owner/repo", a GitHub URL, with an optional
+ *                                 "#branch" suffix — applied to every project, or a JSON map of
+ *                                 per-project specs, e.g.
+ *                                 {"web":"Imena/web#main","legacy":"local"}
+ *                                 — the value "local" opts a project back out to its working copy
+ *   MCP_DOCUMENTOR_CODE_BRANCH    branch used when a repository carries no "#branch" suffix
+ *                                 (default: the repository's own default branch)
+ *   MCP_DOCUMENTOR_CODE_TOKEN     GitHub token; falls back to MCP_DOCUMENTOR_SYNC_TOKEN
+ */
+/** One file as it exists at the source. */
+export interface SourceFile {
+    content: FileContent;
+    /** Snapshot timestamp — the file's mtime locally, the commit date at the tracked ref on GitHub. */
+    lastModifiedAt: string;
+    /** The commit the content was read at; absent for the local filesystem, which has no revision. */
+    revision?: string;
+    /** Content identity at the source — the git blob sha on GitHub. See `CodeSource.contentId`. */
+    blobId?: string;
+}
+export interface CodeSource {
+    readonly kind: "local" | "github";
+    /** Short description of where this source reads from, for reports and error messages. */
+    readonly label: string;
+    /**
+     * Reads a stored tracked path. Returns undefined when the file does not exist at the source.
+     * Throws when the source itself could not be consulted (network, auth, rate limit) — callers
+     * must not read that as "the file changed".
+     */
+    read(storedPath: string): Promise<SourceFile | undefined>;
+    /**
+     * Identity of a file's content, obtained without transferring it — undefined when the source
+     * has no such shortcut, or when the file is absent. A stored identity that still matches proves
+     * the file is untouched, so freshness can be settled without reading anything.
+     */
+    contentId(storedPath: string): Promise<string | undefined>;
+    /** Converts a path supplied by an agent into the portable form persisted in a doc. */
+    toStoredPath(inputPath: string): Promise<string>;
+}
+/** Test-only / config-reload: drops the memoised environment snapshot and every cached source. */
+export declare function resetCodeSourceCache(): void;
+/** The code source a project reads from. Memoised — the configuration is environment-fixed. */
+export declare function getCodeSource(project: string): CodeSource;
+/**
+ * Where each tracked section of a file currently sits, as 1-indexed line ranges — `undefined`
+ * for a section whose anchors no longer match, and `undefined` for every section when the file
+ * itself cannot be read. Used to show positions without storing them.
+ */
+export declare function locateTrackedSections(project: string, storedPath: string, sections: TrackedSection[]): Promise<Array<{
+    start: number;
+    end: number;
+} | undefined>>;
+/**
+ * Stored form of an agent-supplied path, for callers that only use it to match against paths a
+ * doc already tracks. A path the source cannot place is returned normalised rather than raising:
+ * it simply matches nothing, which is the right outcome for a filter.
+ */
+export declare function toStoredPathForMatching(project: string, inputPath: string): Promise<string>;
+/** The GitHub client behind a project's source, or undefined when it reads the local working copy. */
+export declare function getGitHubApi(project: string): GitHubCodeApi | undefined;