@imenam/mcp-documentor 1.0.85 → 1.0.87

package/dist/src/core/local-state.js

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Machine-local state, in `<data dir>/local-state.json`. The sync repository's .gitignore excludes
+ * this file, so what it holds never leaves the machine: the code roots — where this machine keeps
+ * each project's repository — and the report of the one-time migration of the code-source
+ * environment variables.
+ */
+export class LocalState {
+    dataDir;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+    }
+    get filePath() {
+        return path.join(this.dataDir, "local-state.json");
+    }
+    read() {
+        if (!fs.existsSync(this.filePath))
+            return {};
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.filePath, "utf-8"));
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        }
+        catch {
+            throw new Error(`${this.filePath} is not valid JSON — fix or delete it.`);
+        }
+    }
+    write(state) {
+        fs.mkdirSync(this.dataDir, { recursive: true });
+        fs.writeFileSync(this.filePath, JSON.stringify(state, null, 2), "utf-8");
+    }
+    getCodeRoots() {
+        const roots = this.read().codeRoots;
+        return { default: roots?.default, byProject: { ...(roots?.byProject ?? {}) } };
+    }
+    /** The project's own root, else the machine default. */
+    getCodeRoot(project) {
+        const roots = this.getCodeRoots();
+        return roots.byProject[project] ?? roots.default;
+    }
+    /** Sets the machine default root, or removes it when `root` is undefined. */
+    setDefaultCodeRoot(root) {
+        const state = this.read();
+        const roots = { byProject: {}, ...state.codeRoots };
+        if (root)
+            roots.default = root;
+        else
+            delete roots.default;
+        state.codeRoots = roots;
+        this.write(state);
+    }
+    /** Sets a project's own root, or removes it — the project then uses the default — when undefined. */
+    setProjectCodeRoot(project, root) {
+        const state = this.read();
+        const byProject = { ...(state.codeRoots?.byProject ?? {}) };
+        if (root)
+            byProject[project] = root;
+        else
+            delete byProject[project];
+        state.codeRoots = { ...state.codeRoots, byProject };
+        this.write(state);
+    }
+    getMigrationReport() {
+        return this.read().codeSourceMigration;
+    }
+    setMigrationReport(report) {
+        const state = this.read();
+        state.codeSourceMigration = report;
+        this.write(state);
+    }
+    markMigrationReportSeen() {
+        const state = this.read();
+        if (!state.codeSourceMigration)
+            return;
+        state.codeSourceMigration.seen = true;
+        this.write(state);
+    }
+}

package/dist/src/core/migrate-code-sources.d.ts

@@ -0,0 +1,17 @@
+import type { StorageEngine } from "./storage-engine.js";
+import type { LocalState } from "./local-state.js";
+/**
+ * Moves the code-source environment variables into the project settings and the machine-local
+ * code roots, once per machine.
+ *
+ *  - MCP_DOCUMENTOR_CODE_REPO (+ MCP_DOCUMENTOR_CODE_BRANCH for specs without "#branch") becomes
+ *    the code source of each project it names. A project that already has a code source — written
+ *    by another machine and pulled — keeps it.
+ *  - MCP_DOCUMENTOR_CODE_ROOTS becomes the code root of each project it names, on this machine.
+ *  - MCP_DOCUMENTOR_CODE_ROOT seeds the default code root (see `seedDefaultCodeRoot`); it is not
+ *    one of the variables to remove.
+ *
+ * The outcome is recorded as a report in the local state; the GUI shows it until acknowledged.
+ * Once recorded, the migrated variables are never read again: their presence is only logged.
+ */
+export declare function migrateCodeSources(storageEngine: StorageEngine, localState: LocalState): void;

package/dist/src/core/migrate-code-sources.js

@@ -0,0 +1,157 @@
+import { createLogger } from "@imenam/mcp-gui-interface";
+import { parseRepoSpec } from "./github-code-api.js";
+import { hasCodeSourceConfig, writeCodeSourceConfig } from "./project-settings.js";
+const logger = createLogger("MigrateCodeSources");
+const REPO_VAR = "MCP_DOCUMENTOR_CODE_REPO";
+const BRANCH_VAR = "MCP_DOCUMENTOR_CODE_BRANCH";
+const ROOTS_VAR = "MCP_DOCUMENTOR_CODE_ROOTS";
+const ROOT_VAR = "MCP_DOCUMENTOR_CODE_ROOT";
+const short = (name) => name.replace(/^MCP_DOCUMENTOR_/, "");
+function readVar(name) {
+    return process.env[name]?.trim() || undefined;
+}
+/** Entries of a JSON map variable, keeping non-empty string values only. */
+function readJsonMap(name, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${name} looks like a JSON map but could not be parsed`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`${name} is not a JSON object`);
+    }
+    return Object.entries(parsed)
+        .filter((entry) => typeof entry[1] === "string" && entry[1].trim() !== "")
+        .map(([project, value]) => [project, value.trim()]);
+}
+/** The (project, spec) pairs MCP_DOCUMENTOR_CODE_REPO declares: one spec for all, or a JSON map. */
+function readRepoSpecs(raw, projects) {
+    if (!raw.startsWith("{"))
+        return projects.map((project) => [project, raw]);
+    return readJsonMap(REPO_VAR, raw);
+}
+/**
+ * MCP_DOCUMENTOR_CODE_ROOT seeds the default code root of a data directory that has none — the
+ * setup writes it with the repository's folder. Once a default root is stored, the variable is
+ * not read again: a different value is only logged.
+ */
+function seedDefaultCodeRoot(localState) {
+    const envRoot = readVar(ROOT_VAR);
+    if (!envRoot)
+        return undefined;
+    const stored = localState.getCodeRoots().default;
+    if (stored === undefined) {
+        localState.setDefaultCodeRoot(envRoot);
+        logger.info(`Default code root set from ${ROOT_VAR}: ${envRoot}`);
+        return { kind: "code-root", status: "imported", detail: `Default code root · ${envRoot}`, from: short(ROOT_VAR) };
+    }
+    if (stored !== envRoot) {
+        logger.info(`${ROOT_VAR} (${envRoot}) is ignored: the default code root of this machine is ${stored}.`);
+    }
+    return undefined;
+}
+function migrateRepos(storageEngine, projects, entries) {
+    const repoRaw = readVar(REPO_VAR);
+    if (!repoRaw)
+        return;
+    const defaultBranch = readVar(BRANCH_VAR);
+    let specs = [];
+    try {
+        specs = readRepoSpecs(repoRaw, projects);
+    }
+    catch (err) {
+        entries.push({ kind: "github", status: "error", detail: `Not imported — ${err.message}`, from: short(REPO_VAR) });
+    }
+    for (const [project, spec] of specs) {
+        if (!projects.includes(project)) {
+            entries.push({ project, kind: "github", status: "skipped", detail: "Not imported — no such project", from: short(REPO_VAR) });
+            continue;
+        }
+        const projectDir = storageEngine.getProjectDir(project);
+        if (hasCodeSourceConfig(projectDir)) {
+            entries.push({ project, kind: "github", status: "skipped", detail: "Already configured — kept as is", from: short(REPO_VAR) });
+            continue;
+        }
+        if (spec.toLowerCase() === "local") {
+            writeCodeSourceConfig(projectDir, { kind: "local" });
+            entries.push({ project, kind: "local", status: "imported", detail: "Local working copy", from: `${short(REPO_VAR)} "local"` });
+            continue;
+        }
+        let config;
+        let from = short(REPO_VAR);
+        try {
+            const parsed = parseRepoSpec(spec);
+            const branch = parsed.ref ?? defaultBranch;
+            if (!parsed.ref && defaultBranch)
+                from += ` + ${short(BRANCH_VAR)}`;
+            config = { kind: "github", repo: `${parsed.owner}/${parsed.repo}`, ...(branch && { branch }) };
+        }
+        catch (err) {
+            entries.push({ project, kind: "github", status: "error", detail: `Not imported — ${err.message}`, from });
+            continue;
+        }
+        writeCodeSourceConfig(projectDir, config);
+        entries.push({ project, kind: "github", status: "imported", detail: `${config.repo} · ${config.branch ?? "default branch"}`, from });
+    }
+}
+function migrateCodeRoots(localState, projects, entries) {
+    const rootsRaw = readVar(ROOTS_VAR);
+    if (!rootsRaw)
+        return;
+    let roots = [];
+    try {
+        roots = readJsonMap(ROOTS_VAR, rootsRaw);
+    }
+    catch (err) {
+        entries.push({ kind: "code-root", status: "error", detail: `Not imported — ${err.message}`, from: short(ROOTS_VAR) });
+    }
+    const existing = localState.getCodeRoots().byProject;
+    for (const [project, root] of roots) {
+        if (!projects.includes(project)) {
+            entries.push({ project, kind: "code-root", status: "skipped", detail: "Not imported — no such project", from: short(ROOTS_VAR) });
+        }
+        else if (existing[project] !== undefined) {
+            entries.push({ project, kind: "code-root", status: "skipped", detail: "Code root already set — kept as is", from: short(ROOTS_VAR) });
+        }
+        else {
+            localState.setProjectCodeRoot(project, root);
+            entries.push({ project, kind: "code-root", status: "imported", detail: `Code root · ${root}`, from: short(ROOTS_VAR) });
+        }
+    }
+}
+/**
+ * Moves the code-source environment variables into the project settings and the machine-local
+ * code roots, once per machine.
+ *
+ *  - MCP_DOCUMENTOR_CODE_REPO (+ MCP_DOCUMENTOR_CODE_BRANCH for specs without "#branch") becomes
+ *    the code source of each project it names. A project that already has a code source — written
+ *    by another machine and pulled — keeps it.
+ *  - MCP_DOCUMENTOR_CODE_ROOTS becomes the code root of each project it names, on this machine.
+ *  - MCP_DOCUMENTOR_CODE_ROOT seeds the default code root (see `seedDefaultCodeRoot`); it is not
+ *    one of the variables to remove.
+ *
+ * The outcome is recorded as a report in the local state; the GUI shows it until acknowledged.
+ * Once recorded, the migrated variables are never read again: their presence is only logged.
+ */
+export function migrateCodeSources(storageEngine, localState) {
+    const seeded = seedDefaultCodeRoot(localState);
+    const present = [REPO_VAR, BRANCH_VAR, ROOTS_VAR].filter((name) => readVar(name) !== undefined);
+    if (present.length === 0)
+        return;
+    if (localState.getMigrationReport()) {
+        logger.warn(`${present.join(", ")} ${present.length > 1 ? "are" : "is"} set but no longer read — code sources and code roots ` +
+            `are configured per project in the GUI. Remove ${present.length > 1 ? "them" : "it"} from the MCP configuration.`);
+        return;
+    }
+    const projects = storageEngine.getConfig().projects;
+    const entries = [];
+    migrateRepos(storageEngine, projects, entries);
+    migrateCodeRoots(localState, projects, entries);
+    if (seeded)
+        entries.push(seeded);
+    localState.setMigrationReport({ migratedAt: new Date().toISOString(), entries, variables: present, seen: false });
+    logger.info(`Code sources migrated from ${present.join(", ")}: ${entries.filter((e) => e.status === "imported").length} imported, ` +
+        `${entries.filter((e) => e.status !== "imported").length} not imported. These variables are no longer read.`);
+}

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

@@ -1,20 +1,40 @@
-/** 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. */
+/**
+ * Resolves tracked-file paths between two representations:
+ *
+ *  - **stored**   — what we persist in a doc's `tracked_files[].path`. Portable
+ *    across machines: relative to the project's "code root" and using forward
+ *    slashes. Absolute paths may still appear (files located outside any code
+ *    root) and are handled transparently.
+ *  - **absolute** — a real filesystem path on the current machine, used for any
+ *    `fs`/`git` access.
+ *
+ * The code root is machine-local — each machine clones its repos wherever it
+ * wants — so it is read from the machine-local state (a default root, and
+ * per-project roots), through the provider installed with `setCodeRootProvider`.
+ *
+ * Without a code root, paths are stored absolute and only absolute stored paths
+ * can be resolved.
+ */
+/** The code root that applies to a project on this machine, or undefined. */
+export type CodeRootProvider = (project: string) => string | undefined;
+export declare function setCodeRootProvider(value: CodeRootProvider): void;
+/** The code root that applies to a project on this machine, or undefined if none is set. */
 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).
+ * Keeps 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.
+ * Resolves a stored path against a given code root:
  *
- *  - 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)
+ *  - absolute stored path                 → returned as-is
+ *  - relative stored path + a root        → joined with the root
+ *  - relative stored path + no root       → undefined (unverifiable here)
  */
+export declare function resolveAgainstRoot(stored: string, root: string | undefined): string | undefined;
+/** Resolves a stored path to an absolute filesystem path on this machine. */
 export declare function toAbsolutePath(stored: string, project: string): string | undefined;

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

@@ -1,42 +1,15 @@
 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;
+let provider;
+export function setCodeRootProvider(value) {
+    provider = value;
 }
-/** The configured code root for a project, or undefined if none applies. */
+/** The code root that applies to a project on this machine, or undefined if none is set. */
 export function getCodeRoot(project) {
-    const roots = loadCodeRoots();
-    return roots.byProject[project] ?? roots.default;
+    if (!provider)
+        throw new Error("code roots are read before setCodeRootProvider was called");
+    return provider(project);
 }
 function toForwardSlashes(p) {
     return p.split(path.sep).join("/");
@@ -45,8 +18,8 @@ function toForwardSlashes(p) {
  * 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).
+ * Keeps 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);
@@ -64,19 +37,22 @@ export function toStoredPath(inputPath, project) {
     return toForwardSlashes(rel);
 }
 /**
- * Resolves a stored path to an absolute filesystem path on this machine.
+ * Resolves a stored path against a given code root:
  *
- *  - 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)
+ *  - absolute stored path                 → returned as-is
+ *  - relative stored path + a root        → joined with the root
+ *  - relative stored path + no root       → undefined (unverifiable here)
  */
-export function toAbsolutePath(stored, project) {
+export function resolveAgainstRoot(stored, root) {
     if (path.isAbsolute(stored)) {
         return stored;
     }
-    const root = getCodeRoot(project);
     if (!root) {
         return undefined;
     }
     return path.resolve(root, stored);
 }
+/** Resolves a stored path to an absolute filesystem path on this machine. */
+export function toAbsolutePath(stored, project) {
+    return resolveAgainstRoot(stored, getCodeRoot(project));
+}

package/dist/src/core/project-settings.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/**
+ * Where a project's source code is read from.
+ *
+ *  - `local`  — the working copy on this machine, resolved through the code roots.
+ *  - `github` — one branch of one repository, read over the GitHub API. `branch` undefined means
+ *               the repository's default branch.
+ */
+export declare const CodeSourceConfigSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"local">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"github">;
+    repo: z.ZodString;
+    branch: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type CodeSourceConfig = z.infer<typeof CodeSourceConfigSchema>;
+/** Whether the project has a code source written in its settings. */
+export declare function hasCodeSourceConfig(projectDir: string): boolean;
+/** The project's code source. Throws when the settings file exists but cannot be read. */
+export declare function readCodeSourceConfig(projectDir: string): CodeSourceConfig;
+export declare function writeCodeSourceConfig(projectDir: string, config: CodeSourceConfig): void;

package/dist/src/core/project-settings.js

@@ -0,0 +1,63 @@
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+/**
+ * Where a project's source code is read from.
+ *
+ *  - `local`  — the working copy on this machine, resolved through the code roots.
+ *  - `github` — one branch of one repository, read over the GitHub API. `branch` undefined means
+ *               the repository's default branch.
+ */
+export const CodeSourceConfigSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("local") }),
+    z.object({
+        kind: z.literal("github"),
+        repo: z.string().regex(/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/, 'expected "owner/repo"'),
+        branch: z.string().min(1).optional(),
+    }),
+]);
+const ProjectSettingsSchema = z.object({
+    codeSource: CodeSourceConfigSchema.optional(),
+});
+/**
+ * Per-project settings, in `projects/<project>/project.json`. The file lives next to the docs, so
+ * it is versioned and synchronised with them: every machine reads the same code source.
+ */
+function settingsPath(projectDir) {
+    return path.join(projectDir, "project.json");
+}
+/** A project without settings, or without a code source in them, reads its local working copy. */
+const DEFAULT_CODE_SOURCE = { kind: "local" };
+function readSettings(projectDir) {
+    const file = settingsPath(projectDir);
+    if (!fs.existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON`);
+    }
+    const parsed = ProjectSettingsSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`${file} is invalid: ${parsed.error.issues.map((i) => `${i.path.join(".")} ${i.message}`).join("; ")}`);
+    }
+    return parsed.data;
+}
+/** Whether the project has a code source written in its settings. */
+export function hasCodeSourceConfig(projectDir) {
+    return readSettings(projectDir).codeSource !== undefined;
+}
+/** The project's code source. Throws when the settings file exists but cannot be read. */
+export function readCodeSourceConfig(projectDir) {
+    return readSettings(projectDir).codeSource ?? DEFAULT_CODE_SOURCE;
+}
+export function writeCodeSourceConfig(projectDir, config) {
+    const validated = CodeSourceConfigSchema.parse(config);
+    const file = settingsPath(projectDir);
+    const settings = fs.existsSync(file) ? readSettings(projectDir) : {};
+    settings.codeSource = validated;
+    fs.mkdirSync(projectDir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+}

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

@@ -58,9 +58,19 @@ export declare class StorageEngine {
      */
     listDocsDetailed(project: string): Promise<DocListing[]>;
     deleteDoc(id: string, project: string): Promise<boolean>;
-    moveDoc(oldId: string, newId: string, project: string): Promise<boolean>;
+    /**
+     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own
+     * same-project references (`doc://id`, bare related_docs) are qualified with the
+     * source project so they keep pointing at the same entries; the history records
+     * a delete in the source project and a create in the target.
+     */
+    moveDoc(oldId: string, project: string, newId: string, newProject: string): Promise<boolean>;
     getBundles(): ExportBundle[];
     saveBundles(bundles: ExportBundle[]): void;
-    rewriteLinks(oldId: string, newId: string, project: string): Promise<string[]>;
+    /**
+     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`.
+     * In the source project, bare references become qualified when the doc left it.
+     */
+    rewriteLinks(oldId: string, project: string, newId: string, newProject: string): Promise<string[]>;
 }
 export {};

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

@@ -227,24 +227,37 @@ export class StorageEngine {
         logger.info(`Doc deleted: ${filePath}`);
         return true;
     }
-    async moveDoc(oldId, newId, project) {
+    /**
+     * Moves a doc to `newId` in `newProject`. Across projects, the moved doc's own
+     * same-project references (`doc://id`, bare related_docs) are qualified with the
+     * source project so they keep pointing at the same entries; the history records
+     * a delete in the source project and a create in the target.
+     */
+    async moveDoc(oldId, project, newId, newProject) {
         const projectDir = this.getProjectDir(project);
         const oldFilePath = this.docIdToFilePath(oldId, projectDir);
         if (!fs.existsSync(oldFilePath))
             return false;
-        const newFilePath = this.docIdToFilePath(newId, projectDir);
+        const newProjectDir = this.getProjectDir(newProject);
+        const newFilePath = this.docIdToFilePath(newId, newProjectDir);
         if (fs.existsSync(newFilePath)) {
-            throw new Error(`A document already exists at path "${newId}".`);
+            throw new Error(`A document already exists at path "${newId}" in project "${newProject}".`);
         }
         const doc = await this.getDoc(oldId, project);
         if (!doc)
             return false;
+        const crossProject = newProject !== project;
+        if (crossProject) {
+            this.historyStore?.record(project, doc, "delete");
+            doc.content = doc.content.replace(/doc:\/\/([^):#\s]+)(?=[)#\s]|$)/g, `doc://${project}:$1`);
+            doc.related_docs = doc.related_docs.map((ref) => (ref.includes(":") ? ref : `${project}:${ref}`));
+        }
         const newParts = newId.split("/");
         doc.id = newId;
         doc.folder = newParts.length > 1 ? newParts.slice(0, -1).join("/") : undefined;
         doc.updatedAt = new Date().toISOString();
         fs.mkdirSync(path.dirname(newFilePath), { recursive: true });
-        await this.saveDoc(doc, project, "update");
+        await this.saveDoc(doc, newProject, crossProject ? "create" : "update");
         fs.unlinkSync(oldFilePath);
         this.cleanEmptyDirs(path.dirname(oldFilePath), projectDir);
         logger.info(`Doc moved: ${oldFilePath} → ${newFilePath}`);
@@ -265,22 +278,29 @@ export class StorageEngine {
         const p = path.join(this.getDataDir(), "export-bundles.json");
         fs.writeFileSync(p, JSON.stringify(bundles, null, 2), "utf-8");
     }
-    async rewriteLinks(oldId, newId, project) {
+    /**
+     * Rewrites every reference to `project:oldId` so it points at `newProject:newId`.
+     * In the source project, bare references become qualified when the doc left it.
+     */
+    async rewriteLinks(oldId, project, newId, newProject) {
         const config = this.getConfig();
         const proj = project;
+        const crossProject = newProject !== proj;
+        const qualifiedTarget = `${newProject}:${newId}`;
+        const bareTarget = crossProject ? qualifiedTarget : newId;
+        const boundary = "(?=[)#\\s]|$)";
         const updated = [];
-        // Within the same project: rewrite same-project refs and explicit self-cross-project refs
+        // Within the source project: rewrite bare refs and explicit self-cross-project refs
         const sameProjDocs = await this.listDocs(proj);
         for (const summary of sameProjDocs) {
-            if (summary.id === newId)
+            if (!crossProject && summary.id === newId)
                 continue;
             const doc = await this.getDoc(summary.id, proj);
             if (!doc)
                 continue;
             let changed = false;
-            let newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(oldId)}`, "g"), `doc://${newId}`);
-            // Also rewrite explicit self cross-project refs (doc://proj:oldId → doc://proj:newId)
-            newContent = newContent.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}`, "g"), `doc://${proj}:${newId}`);
+            let newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(oldId)}${boundary}`, "g"), `doc://${bareTarget}`);
+            newContent = newContent.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}${boundary}`, "g"), `doc://${qualifiedTarget}`);
             if (newContent !== doc.content) {
                 doc.content = newContent;
                 changed = true;
@@ -288,11 +308,11 @@ export class StorageEngine {
             const newRelated = doc.related_docs.map((ref) => {
                 if (ref === oldId) {
                     changed = true;
-                    return newId;
+                    return bareTarget;
                 }
                 if (ref === `${proj}:${oldId}`) {
                     changed = true;
-                    return `${proj}:${newId}`;
+                    return qualifiedTarget;
                 }
                 return ref;
             });
@@ -303,7 +323,7 @@ export class StorageEngine {
                 updated.push(summary.id);
             }
         }
-        // In other projects: rewrite cross-project refs pointing to this project
+        // In other projects: rewrite cross-project refs pointing to the source project
         for (const otherProj of config.projects) {
             if (otherProj === proj)
                 continue;
@@ -313,7 +333,7 @@ export class StorageEngine {
                 if (!doc)
                     continue;
                 let changed = false;
-                const newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}`, "g"), `doc://${proj}:${newId}`);
+                const newContent = doc.content.replace(new RegExp(`doc://${escapeRegex(proj)}:${escapeRegex(oldId)}${boundary}`, "g"), `doc://${qualifiedTarget}`);
                 if (newContent !== doc.content) {
                     doc.content = newContent;
                     changed = true;
@@ -321,7 +341,7 @@ export class StorageEngine {
                 const newRelated = doc.related_docs.map((ref) => {
                     if (ref === `${proj}:${oldId}`) {
                         changed = true;
-                        return `${proj}:${newId}`;
+                        return qualifiedTarget;
                     }
                     return ref;
                 });