@hanna84/mcp-writing 2.17.1 → 2.18.0

package/CHANGELOG.md

@@ -4,11 +4,21 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.18.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.17.1...v2.18.0)
+
+- feat(reference): complete Phase 4D scene reference suggestion flow [`#163`](https://github.com/hannasdev/mcp-writing.git
+/pull/163)
+
 #### [v2.17.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.17.0...v2.17.1)
 
+> 1 May 2026
+
 - docs: mark reference-docs Phase 4C complete [`#162`](https://github.com/hannasdev/mcp-writing.git
 /pull/162)
+- Release 2.17.1 [`65ba9a1`](https://github.com/hannasdev/mcp-writing.git
+/commit/65ba9a118afc4c1d484a5f3f714d00a021eac48e)
 
 #### [v2.17.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.16.2...v2.17.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.17.1",
+  "version": "2.18.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/sync/sync.js

@@ -698,8 +698,27 @@ export function indexWorldFile(db, syncDir, file, meta) {
 
   if (!kind || !isCanonicalWorldEntityFile(syncDir, file, meta)) return;
 
+  const indexWorldEntityReferenceLinks = ({ sourceKind, sourceId }) => {
+    const explicitReferenceLinks = collectExplicitReferenceLinks(
+      meta,
+      ["reference_links", "explicit_reference_links"],
+      { defaultRelation: "informs" }
+    );
+
+    if (explicitReferenceLinks.hasField) {
+      indexExplicitReferenceLinksForSource(db, {
+        sourceKind,
+        sourceProjectId: project_id ?? "",
+        sourceId,
+        links: explicitReferenceLinks.links,
+        defaultRelation: "informs",
+      });
+    }
+  };
+
   if (kind === "character") {
     if (!meta.character_id) return;
+
     db.prepare(`
       INSERT INTO characters (character_id, project_id, universe_id, name, role, arc_summary, first_appearance, file_path)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
@@ -717,8 +736,10 @@ export function indexWorldFile(db, syncDir, file, meta) {
         meta.character_id, t
       );
     }
+    indexWorldEntityReferenceLinks({ sourceKind: "character", sourceId: meta.character_id });
   } else if (kind === "place") {
     if (!meta.place_id) return;
+
     db.prepare(`
       INSERT INTO places (place_id, project_id, universe_id, name, file_path)
       VALUES (?, ?, ?, ?, ?)
@@ -727,6 +748,7 @@ export function indexWorldFile(db, syncDir, file, meta) {
       meta.place_id, project_id ?? null, universe_id ?? null,
       meta.name ?? meta.place_id, file
     );
+    indexWorldEntityReferenceLinks({ sourceKind: "place", sourceId: meta.place_id });
   }
 }
 

package/src/tools/metadata.js

@@ -1,46 +1,13 @@
 import { z } from "zod";
 import fs from "node:fs";
 import matter from "gray-matter";
-import { readMeta, writeMeta, indexSceneFile, normalizeSceneMetaForPath, normalizeReferenceLinkList } from "../sync/sync.js";
+import { readMeta, writeMeta, indexSceneFile, normalizeSceneMetaForPath } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
-
-function upsertSerializedReferenceLinks(existing, targetDocId, relation, { defaultRelation }) {
-  const normalized = normalizeReferenceLinkList(existing ?? [], { defaultRelation });
-  const filtered = normalized.filter((entry) => entry.targetDocId !== targetDocId);
-  filtered.push({ targetDocId, relation });
-  return filtered.map((entry) => ({
-    target_doc_id: entry.targetDocId,
-    relation: entry.relation,
-  }));
-}
-
-function persistSceneReferenceLink({ scenePath, syncDir, targetDocId, relation }) {
-  const { meta } = readMeta(scenePath, syncDir, { writable: true });
-  const existingExplicit = [
-    ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
-    ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),
-  ];
-  const nextReferenceLinks = upsertSerializedReferenceLinks(existingExplicit, targetDocId, relation, {
-    defaultRelation: "informs",
-  });
-
-  const nextMeta = {
-    ...meta,
-    reference_links: nextReferenceLinks,
-  };
-  delete nextMeta.explicit_reference_links;
-
-  if (relation === "informs") {
-    const existingIds = Array.isArray(meta.reference_ids)
-      ? meta.reference_ids
-      : typeof meta.reference_ids === "string"
-        ? meta.reference_ids.split(",")
-        : [];
-    nextMeta.reference_ids = [...new Set([...existingIds.map((value) => String(value).trim()).filter(Boolean), targetDocId])];
-  }
-
-  writeMeta(scenePath, nextMeta);
-}
+import {
+  persistSceneReferenceLink,
+  upsertExplicitReferenceLinkRow,
+  upsertSerializedReferenceLinks,
+} from "./reference-link-persistence.js";
 
 function persistReferenceDocLink({ filePath, targetDocId, relation }) {
   const raw = fs.readFileSync(filePath, "utf8");
@@ -74,6 +41,165 @@ function persistReferenceDocLink({ filePath, targetDocId, relation }) {
   fs.writeFileSync(filePath, matter.stringify(parsed.content, nextData), "utf8");
 }
 
+function persistCharacterReferenceLink({ characterPath, syncDir, targetDocId, relation }) {
+  const { meta } = readMeta(characterPath, syncDir, { writable: true });
+  const existingExplicit = [
+    ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
+    ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),
+  ];
+  const nextReferenceLinks = upsertSerializedReferenceLinks(existingExplicit, targetDocId, relation, {
+    defaultRelation: "informs",
+  });
+
+  const nextMeta = {
+    ...meta,
+    reference_links: nextReferenceLinks,
+  };
+  delete nextMeta.explicit_reference_links;
+
+  writeMeta(characterPath, nextMeta);
+}
+
+function persistPlaceReferenceLink({ placePath, syncDir, targetDocId, relation }) {
+  const { meta } = readMeta(placePath, syncDir, { writable: true });
+  const existingExplicit = [
+    ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
+    ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),
+  ];
+  const nextReferenceLinks = upsertSerializedReferenceLinks(existingExplicit, targetDocId, relation, {
+    defaultRelation: "informs",
+  });
+
+  const nextMeta = {
+    ...meta,
+    reference_links: nextReferenceLinks,
+  };
+  delete nextMeta.explicit_reference_links;
+
+  writeMeta(placePath, nextMeta);
+}
+
+function resolveProjectScopedSource({
+  db,
+  errorResponse,
+  sourceId,
+  sourceProjectId,
+  table,
+  idColumn,
+  label,
+}) {
+  if (sourceProjectId) {
+    const scoped = db.prepare(`
+      SELECT ${idColumn} AS source_id, project_id, file_path
+      FROM ${table}
+      WHERE ${idColumn} = ? AND project_id = ?
+      LIMIT 1
+    `).get(sourceId, sourceProjectId);
+    if (!scoped) {
+      return { error: errorResponse("NOT_FOUND", `${label} '${sourceId}' not found in project '${sourceProjectId}'.`) };
+    }
+    return {
+      value: {
+        resolvedSourceProjectId: scoped.project_id ?? "",
+        sourceFilePath: scoped.file_path,
+      },
+    };
+  }
+
+  const matches = db.prepare(`
+    SELECT ${idColumn} AS source_id, project_id, file_path
+    FROM ${table}
+    WHERE ${idColumn} = ?
+    ORDER BY project_id
+  `).all(sourceId);
+
+  if (matches.length === 0) {
+    return { error: errorResponse("NOT_FOUND", `${label} '${sourceId}' not found.`) };
+  }
+  if (matches.length > 1) {
+    return {
+      error: errorResponse(
+        "CONFLICT",
+        `${label} ID '${sourceId}' exists in multiple projects. Provide source_project_id to disambiguate.`,
+        { source_id: sourceId, project_ids: matches.map((row) => row.project_id) }
+      ),
+    };
+  }
+
+  return {
+    value: {
+      resolvedSourceProjectId: matches[0].project_id ?? "",
+      sourceFilePath: matches[0].file_path,
+    },
+  };
+}
+
+function resolveReferenceLinkSource({
+  db,
+  errorResponse,
+  sourceKind,
+  sourceId,
+  sourceProjectId,
+  targetDocId,
+}) {
+  if (sourceKind === "reference") {
+    const sourceDoc = db.prepare(`
+      SELECT doc_id, project_id, file_path
+      FROM reference_docs
+      WHERE doc_id = ?
+      LIMIT 1
+    `).get(sourceId);
+    if (!sourceDoc) {
+      return { error: errorResponse("NOT_FOUND", `Source reference doc '${sourceId}' not found.`) };
+    }
+    if (sourceId === targetDocId) {
+      return { error: errorResponse("VALIDATION_ERROR", "Self-links are not allowed for reference sources.") };
+    }
+    const resolvedSourceProjectId = sourceDoc.project_id ?? "";
+    if ((sourceProjectId ?? "") !== "" && sourceProjectId !== resolvedSourceProjectId) {
+      const resolvedSourceProjectLabel = resolvedSourceProjectId === ""
+        ? "unscoped/no project"
+        : `project '${resolvedSourceProjectId}'`;
+      const requestedSourceProjectLabel = sourceProjectId === ""
+        ? "unscoped/no project"
+        : `project '${sourceProjectId}'`;
+      return {
+        error: errorResponse(
+          "CONFLICT",
+          `Source reference doc '${sourceId}' belongs to ${resolvedSourceProjectLabel}, not ${requestedSourceProjectLabel}.`,
+          {
+            source_id: sourceId,
+            source_project_id: sourceProjectId,
+            resolved_source_project_id: resolvedSourceProjectId,
+          }
+        ),
+      };
+    }
+    return {
+      value: {
+        resolvedSourceProjectId,
+        sourceFilePath: sourceDoc.file_path,
+      },
+    };
+  }
+
+  const sourceConfigByKind = {
+    scene: { table: "scenes", idColumn: "scene_id", label: "Scene" },
+    character: { table: "characters", idColumn: "character_id", label: "Character" },
+    place: { table: "places", idColumn: "place_id", label: "Place" },
+  };
+  const config = sourceConfigByKind[sourceKind];
+  return resolveProjectScopedSource({
+    db,
+    errorResponse,
+    sourceId,
+    sourceProjectId,
+    table: config.table,
+    idColumn: config.idColumn,
+    label: config.label,
+  });
+}
+
 export function registerMetadataTools(s, {
   db,
   SYNC_DIR,
@@ -243,11 +369,11 @@ export function registerMetadataTools(s, {
   // ---- upsert_reference_link -----------------------------------------------
   s.tool(
     "upsert_reference_link",
-    "Create or update an explicit reference link from a scene or reference doc to a target reference doc. If a link already exists between the same source and target, this updates the relation. Only available when the sync dir is writable.",
+    "Create or update an explicit reference link from a scene, character, place, or reference doc to a target reference doc. If a link already exists between the same source and target, this updates the relation. Only available when the sync dir is writable.",
     {
-      source_kind: z.enum(["scene", "reference"]).describe("Link source kind."),
-      source_id: z.string().describe("Source scene_id or reference doc_id."),
-      source_project_id: z.string().optional().describe("Optional project scope for the source. For scene sources, use this to disambiguate an ambiguous scene_id across projects. For reference sources, when provided, it is treated as an ownership check and must match the source reference doc's project."),
+      source_kind: z.enum(["scene", "character", "place", "reference"]).describe("Link source kind."),
+      source_id: z.string().describe("Source scene_id, character_id, place_id, or reference doc_id."),
+      source_project_id: z.string().optional().describe("Optional project scope for the source. For scene/character/place sources, use this to disambiguate an ambiguous source_id across projects. For reference sources, when provided, it is treated as an ownership check and must match the source reference doc's project."),
       target_doc_id: z.string().describe("Target reference doc_id."),
       relation: z.string().describe("Relationship label (for example: 'informs', 'related', 'history_of'). The value is trimmed and lowercased before validation."),
     },
@@ -274,109 +400,77 @@ export function registerMetadataTools(s, {
         return errorResponse("NOT_FOUND", `Target reference doc '${target_doc_id}' not found.`);
       }
 
-      let resolvedSourceProjectId;
-      let sourceScenePath = null;
-      let sourceReferencePath = null;
-      if (source_kind === "scene") {
-        if (source_project_id) {
-          const scene = db.prepare(`
-            SELECT scene_id, project_id, file_path
-            FROM scenes
-            WHERE scene_id = ? AND project_id = ?
-            LIMIT 1
-          `).get(source_id, source_project_id);
-          if (!scene) {
-            return errorResponse("NOT_FOUND", `Scene '${source_id}' not found in project '${source_project_id}'.`);
-          }
-          resolvedSourceProjectId = scene.project_id ?? "";
-          sourceScenePath = scene.file_path;
-        } else {
-          const matches = db.prepare(`
-            SELECT scene_id, project_id, file_path
-            FROM scenes
-            WHERE scene_id = ?
-            ORDER BY project_id
-          `).all(source_id);
-          if (matches.length === 0) {
-            return errorResponse("NOT_FOUND", `Scene '${source_id}' not found.`);
-          }
-          if (matches.length > 1) {
-            return errorResponse(
-              "CONFLICT",
-              `Scene ID '${source_id}' exists in multiple projects. Provide source_project_id to disambiguate.`,
-              { source_id, project_ids: matches.map(row => row.project_id) }
-            );
-          }
-          resolvedSourceProjectId = matches[0].project_id ?? "";
-          sourceScenePath = matches[0].file_path;
-        }
-      } else {
-        const sourceDoc = db.prepare(`
-          SELECT doc_id, project_id, file_path
-          FROM reference_docs
-          WHERE doc_id = ?
-          LIMIT 1
-        `).get(source_id);
-        if (!sourceDoc) {
-          return errorResponse("NOT_FOUND", `Source reference doc '${source_id}' not found.`);
-        }
-        if (source_id === target_doc_id) {
-          return errorResponse("VALIDATION_ERROR", "Self-links are not allowed for reference sources.");
-        }
-        resolvedSourceProjectId = sourceDoc.project_id ?? "";
-        if ((source_project_id ?? "") !== "" && source_project_id !== resolvedSourceProjectId) {
-          const resolvedSourceProjectLabel = resolvedSourceProjectId === ""
-            ? "unscoped/no project"
-            : `project '${resolvedSourceProjectId}'`;
-          const requestedSourceProjectLabel = source_project_id === ""
-            ? "unscoped/no project"
-            : `project '${source_project_id}'`;
-          return errorResponse(
-            "CONFLICT",
-            `Source reference doc '${source_id}' belongs to ${resolvedSourceProjectLabel}, not ${requestedSourceProjectLabel}.`,
-            {
-              source_id,
-              source_project_id,
-              resolved_source_project_id: resolvedSourceProjectId,
-            }
-          );
-        }
-        sourceReferencePath = sourceDoc.file_path;
+      const sourceResolution = resolveReferenceLinkSource({
+        db,
+        errorResponse,
+        sourceKind: source_kind,
+        sourceId: source_id,
+        sourceProjectId: source_project_id,
+        targetDocId: target_doc_id,
+      });
+      if (sourceResolution.error) {
+        return sourceResolution.error;
       }
+      const { resolvedSourceProjectId, sourceFilePath } = sourceResolution.value;
 
       try {
         if (source_kind === "scene") {
-          if (!sourceScenePath) {
+          if (!sourceFilePath) {
             return errorResponse("STALE_PATH", `Scene '${source_id}' has no indexed file path. Run sync() to refresh.`, {
               source_id,
               source_project_id: resolvedSourceProjectId,
             });
           }
           persistSceneReferenceLink({
-            scenePath: sourceScenePath,
+            scenePath: sourceFilePath,
+            syncDir: SYNC_DIR,
+            targetDocId: target_doc_id,
+            relation: normalizedRelation,
+          });
+        } else if (source_kind === "character") {
+          if (!sourceFilePath) {
+            return errorResponse("STALE_PATH", `Character '${source_id}' has no indexed file path. Run sync() to refresh.`, {
+              source_id,
+              source_project_id: resolvedSourceProjectId,
+            });
+          }
+          persistCharacterReferenceLink({
+            characterPath: sourceFilePath,
+            syncDir: SYNC_DIR,
+            targetDocId: target_doc_id,
+            relation: normalizedRelation,
+          });
+        } else if (source_kind === "place") {
+          if (!sourceFilePath) {
+            return errorResponse("STALE_PATH", `Place '${source_id}' has no indexed file path. Run sync() to refresh.`, {
+              source_id,
+              source_project_id: resolvedSourceProjectId,
+            });
+          }
+          persistPlaceReferenceLink({
+            placePath: sourceFilePath,
             syncDir: SYNC_DIR,
             targetDocId: target_doc_id,
             relation: normalizedRelation,
           });
         } else {
-          if (!sourceReferencePath) {
+          if (!sourceFilePath) {
             return errorResponse("STALE_PATH", `Reference doc '${source_id}' has no indexed file path. Run sync() to refresh.`, {
               source_id,
             });
           }
           persistReferenceDocLink({
-            filePath: sourceReferencePath,
+            filePath: sourceFilePath,
             targetDocId: target_doc_id,
             relation: normalizedRelation,
           });
         }
       } catch (err) {
         if (err?.code === "ENOENT") {
-          const indexedPath = source_kind === "scene" ? sourceScenePath : sourceReferencePath;
           return errorResponse(
             "STALE_PATH",
             `Source file for ${source_kind} '${source_id}' not found at indexed path — run sync() to refresh.`,
-            { indexed_path: indexedPath }
+            { indexed_path: sourceFilePath }
           );
         }
         return errorResponse("IO_ERROR", `Failed to persist link metadata: ${err.message}`);
@@ -384,16 +478,13 @@ export function registerMetadataTools(s, {
 
       try {
         db.exec("BEGIN");
-        db.prepare(`
-          DELETE FROM reference_links
-          WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND target_doc_id = ?
-        `).run(source_kind, resolvedSourceProjectId, source_id, target_doc_id);
-
-        db.prepare(`
-          INSERT INTO reference_links (
-            source_kind, source_project_id, source_id, target_doc_id, relation, origin
-          ) VALUES (?, ?, ?, ?, ?, 'explicit')
-        `).run(source_kind, resolvedSourceProjectId, source_id, target_doc_id, normalizedRelation);
+        upsertExplicitReferenceLinkRow(db, {
+          sourceKind: source_kind,
+          sourceProjectId: resolvedSourceProjectId,
+          sourceId: source_id,
+          targetDocId: target_doc_id,
+          relation: normalizedRelation,
+        });
         db.exec("COMMIT");
       } catch (err) {
         try {

package/src/tools/reference-link-persistence.js

@@ -0,0 +1,77 @@
+import { readMeta, writeMeta, normalizeReferenceLinkList } from "../sync/sync.js";
+
+let savepointCounter = 0;
+
+export function upsertSerializedReferenceLinks(existing, targetDocId, relation, { defaultRelation }) {
+  const normalized = normalizeReferenceLinkList(existing ?? [], { defaultRelation });
+  const filtered = normalized.filter((entry) => entry.targetDocId !== targetDocId);
+  filtered.push({ targetDocId, relation });
+  return filtered.map((entry) => ({
+    target_doc_id: entry.targetDocId,
+    relation: entry.relation,
+  }));
+}
+
+export function persistSceneReferenceLink({ scenePath, syncDir, targetDocId, relation }) {
+  const { meta } = readMeta(scenePath, syncDir, { writable: true });
+  const existingExplicit = [
+    ...(Array.isArray(meta.reference_links) ? meta.reference_links : meta.reference_links ? [meta.reference_links] : []),
+    ...(Array.isArray(meta.explicit_reference_links) ? meta.explicit_reference_links : meta.explicit_reference_links ? [meta.explicit_reference_links] : []),
+  ];
+  const nextReferenceLinks = upsertSerializedReferenceLinks(existingExplicit, targetDocId, relation, {
+    defaultRelation: "informs",
+  });
+
+  const nextMeta = {
+    ...meta,
+    reference_links: nextReferenceLinks,
+  };
+  delete nextMeta.explicit_reference_links;
+
+  if (relation === "informs") {
+    const existingIds = Array.isArray(meta.reference_ids)
+      ? meta.reference_ids
+      : typeof meta.reference_ids === "string"
+        ? meta.reference_ids.split(",")
+        : [];
+    nextMeta.reference_ids = [...new Set([...existingIds.map((value) => String(value).trim()).filter(Boolean), targetDocId])];
+  }
+
+  writeMeta(scenePath, nextMeta);
+}
+
+export function upsertExplicitReferenceLinkRow(
+  db,
+  { sourceKind, sourceProjectId, sourceId, targetDocId, relation }
+) {
+  const deleteStmt = db.prepare(`
+    DELETE FROM reference_links
+    WHERE source_kind = ? AND source_project_id = ? AND source_id = ? AND target_doc_id = ?
+  `);
+  const insertStmt = db.prepare(`
+    INSERT INTO reference_links (
+      source_kind, source_project_id, source_id, target_doc_id, relation, origin
+    ) VALUES (?, ?, ?, ?, ?, 'explicit')
+  `);
+
+  const runUpsertBody = () => {
+    deleteStmt.run(sourceKind, sourceProjectId, sourceId, targetDocId);
+    insertStmt.run(sourceKind, sourceProjectId, sourceId, targetDocId, relation);
+  };
+
+  if (typeof db.transaction === "function") {
+    db.transaction(runUpsertBody)();
+    return;
+  }
+
+  const savepointName = `reference_link_upsert_${savepointCounter += 1}`;
+  db.exec(`SAVEPOINT ${savepointName};`);
+  try {
+    runUpsertBody();
+    db.exec(`RELEASE SAVEPOINT ${savepointName};`);
+  } catch (err) {
+    db.exec(`ROLLBACK TO SAVEPOINT ${savepointName};`);
+    db.exec(`RELEASE SAVEPOINT ${savepointName};`);
+    throw err;
+  }
+}

package/src/tools/search.js

@@ -1,10 +1,63 @@
 import { z } from "zod";
 import fs from "node:fs";
 import matter from "gray-matter";
+import { readMeta } from "../sync/sync.js";
+import { persistSceneReferenceLink, upsertExplicitReferenceLinkRow } from "./reference-link-persistence.js";
+
+function accumulateSuggestionScore(scoreMap, rows, sourceLabel) {
+  for (const row of rows) {
+    const key = `${row.target_doc_id}:${row.relation}`;
+    if (!scoreMap.has(key)) {
+      scoreMap.set(key, {
+        doc_id: row.target_doc_id,
+        relation: row.relation,
+        score: 0,
+        sources: [],
+      });
+    }
+    const entry = scoreMap.get(key);
+    entry.score += 1;
+    entry.sources.push(`${sourceLabel}: ${row.source_name ?? row.source_id}`);
+  }
+}
+
+function normalizeEntityIdList(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry).trim()).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function readSceneEntityIdsFromMetadata({ scenePath, syncDir }) {
+  const { meta } = readMeta(scenePath, syncDir, { writable: false });
+  return {
+    characterIds: normalizeEntityIdList(meta.characters),
+    placeIds: normalizeEntityIdList(meta.places),
+  };
+}
+
+function selectApplyCandidates(enrichedCandidates, selectedDocIds, maxApply) {
+  const selectedSet = selectedDocIds ? new Set(selectedDocIds) : null;
+  const chosenByDocId = new Map();
+
+  for (const candidate of enrichedCandidates) {
+    if (selectedSet && !selectedSet.has(candidate.doc_id)) continue;
+    if (!chosenByDocId.has(candidate.doc_id)) {
+      chosenByDocId.set(candidate.doc_id, candidate);
+    }
+  }
+
+  const uniqueCandidates = Array.from(chosenByDocId.values());
+  return uniqueCandidates.slice(0, maxApply ?? uniqueCandidates.length);
+}
 
 export function registerSearchTools(s, {
   db,
   SYNC_DIR,
+  SYNC_DIR_WRITABLE,
   GIT_ENABLED,
   errorResponse,
   paginateRows,
@@ -740,4 +793,264 @@ export function registerSearchTools(s, {
       return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
     }
   );
+
+  // ---- suggest_scene_references --------------------------------------------
+  s.tool(
+    "suggest_scene_references",
+    "Suggest reference documents for a scene by aggregating links from the scene's characters and places. Returns weighted candidates ranked by how many entities in the scene link to each reference. Excludes any explicit scene → reference links already present. In apply mode, can persist selected suggestions as explicit scene links in one call.",
+    {
+      scene_id: z.string().describe("Scene ID (e.g. 'sc-011-sebastian')."),
+      project_id: z.string().optional().describe("Optional project scope to disambiguate an ambiguous scene_id across projects."),
+      mode: z.enum(["preview", "apply"]).optional().describe("Use 'preview' (default) to list candidates only, or 'apply' to persist selected suggestions as explicit scene links."),
+      selected_doc_ids: z.array(z.string()).optional().describe("Optional allowlist of doc_ids to apply when mode='apply'. If omitted, applies top-ranked candidates."),
+      max_apply: z.number().int().min(1).optional().describe("Optional cap for how many candidates to apply when mode='apply'."),
+      min_score: z.number().int().min(1).optional().describe("Optional minimum candidate score. Candidates below this are excluded from preview/apply. Defaults to 1."),
+    },
+    async ({ scene_id, project_id, mode = "preview", selected_doc_ids, max_apply, min_score = 1 }) => {
+      // Resolve scene
+      let sceneQuery = `SELECT scene_id, project_id, file_path FROM scenes WHERE scene_id = ?`;
+      const sceneParams = [scene_id];
+      if (project_id) {
+        sceneQuery += ` AND project_id = ?`;
+        sceneParams.push(project_id);
+      }
+      
+      const scenes = db.prepare(sceneQuery).all(...sceneParams);
+      if (scenes.length === 0) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found${project_id ? ` in project '${project_id}'` : ""}.`);
+      }
+      if (scenes.length > 1) {
+        return errorResponse(
+          "CONFLICT",
+          `Scene ID '${scene_id}' exists in multiple projects. Provide project_id to disambiguate.`,
+          { scene_id, project_ids: scenes.map(s => s.project_id) }
+        );
+      }
+
+      const resolvedScene = scenes[0];
+      const resolvedProjectId = resolvedScene.project_id ?? "";
+
+      if (mode === "apply" && !SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot apply suggestions: sync dir is read-only.");
+      }
+
+      let characterIds = [];
+      let placeIds = [];
+      let loadedSceneEntitiesFromMetadata = false;
+
+      if (resolvedScene.file_path) {
+        try {
+          const entities = readSceneEntityIdsFromMetadata({
+            scenePath: resolvedScene.file_path,
+            syncDir: SYNC_DIR,
+          });
+            characterIds = entities.characterIds;
+            placeIds = entities.placeIds;
+            loadedSceneEntitiesFromMetadata = true;
+        } catch (err) {
+          void err;
+        }
+      }
+
+      if (!loadedSceneEntitiesFromMetadata) {
+        // Fallback for scenes without readable indexed file paths.
+        characterIds = db.prepare(`
+          SELECT character_id FROM scene_characters WHERE scene_id = ?
+        `).all(scene_id).map((row) => row.character_id);
+
+        placeIds = db.prepare(`
+          SELECT place_id FROM scene_places WHERE scene_id = ?
+        `).all(scene_id).map((row) => row.place_id);
+      }
+
+      // Get explicit scene → reference links already present
+      const existingSceneLinks = db.prepare(`
+        SELECT target_doc_id
+        FROM reference_links
+        WHERE source_kind = 'scene' AND source_project_id = ? AND source_id = ? AND origin = 'explicit'
+      `).all(resolvedProjectId, scene_id);
+      const existingSceneDocIds = new Set(existingSceneLinks.map((link) => link.target_doc_id));
+
+      // Load all character/place source links in project scope and aggregate in memory.
+      const characterReferenceLinks = characterIds.length > 0
+        ? db.prepare(`
+            SELECT rl.target_doc_id, rl.relation, rl.source_id AS source_id, c.name AS source_name
+            FROM reference_links rl
+            LEFT JOIN characters c
+              ON c.character_id = rl.source_id
+             AND c.project_id = rl.source_project_id
+            WHERE rl.source_kind = 'character'
+              AND rl.source_project_id = ?
+              AND rl.source_id IN (${characterIds.map(() => "?").join(",")})
+          `).all(resolvedProjectId, ...characterIds)
+        : [];
+
+      const placeReferenceLinks = placeIds.length > 0
+        ? db.prepare(`
+            SELECT rl.target_doc_id, rl.relation, rl.source_id AS source_id, p.name AS source_name
+            FROM reference_links rl
+            LEFT JOIN places p
+              ON p.place_id = rl.source_id
+             AND p.project_id = rl.source_project_id
+            WHERE rl.source_kind = 'place'
+              AND rl.source_project_id = ?
+              AND rl.source_id IN (${placeIds.map(() => "?").join(",")})
+          `).all(resolvedProjectId, ...placeIds)
+        : [];
+
+      // Merge and score
+      const scoreMap = new Map(); // key: "doc_id:relation" → { doc_id, relation, score, sources: [...] }
+      accumulateSuggestionScore(scoreMap, characterReferenceLinks, "character");
+      accumulateSuggestionScore(scoreMap, placeReferenceLinks, "place");
+
+      // Filter out already explicit scene links and deduplicate sources
+        const candidates = Array.from(scoreMap.values())
+        .filter(entry => !existingSceneDocIds.has(entry.doc_id))
+        .filter(entry => entry.score >= min_score)
+        .map(entry => ({
+          ...entry,
+          sources: [...new Set(entry.sources)], // deduplicate
+        }))
+          .sort((a, b) => b.score - a.score || a.doc_id.localeCompare(b.doc_id) || a.relation.localeCompare(b.relation));
+
+      const candidateDocIds = [...new Set(candidates.map(candidate => candidate.doc_id))];
+      const docsById = candidateDocIds.length > 0
+        ? new Map(
+            db.prepare(`
+              SELECT doc_id, type, title, summary, project_id, universe_id
+              FROM reference_docs
+              WHERE doc_id IN (${candidateDocIds.map(() => "?").join(",")})
+            `)
+              .all(...candidateDocIds)
+              .map(row => [row.doc_id, row])
+          )
+        : new Map();
+
+      // Enrich with reference doc metadata
+        const enriched = candidates
+          .filter(candidate => docsById.has(candidate.doc_id))
+          .map(candidate => {
+            const doc = docsById.get(candidate.doc_id);
+            return {
+              ...candidate,
+              title: doc.title,
+              type: doc.type,
+              summary: doc.summary,
+            };
+          });
+
+        const skippedMissingDocIds = candidateDocIds.filter((docId) => !docsById.has(docId));
+
+      if (enriched.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              scene_id,
+              project_id: resolvedProjectId,
+              total_candidates: 0,
+              message: "No reference suggestions found. Scene characters and places have no linked references.",
+              skipped_missing_doc_ids: skippedMissingDocIds,
+              candidates: [],
+            }, null, 2),
+          }],
+        };
+      }
+
+
+      if (mode === "apply") {
+        if (!resolvedScene.file_path) {
+          return errorResponse("STALE_PATH", `Scene '${scene_id}' has no indexed file path. Run sync() to refresh.`, {
+            scene_id,
+            project_id: resolvedProjectId,
+          });
+        }
+
+          const toApply = selectApplyCandidates(enriched, selected_doc_ids, max_apply);
+
+        const appliedLinks = [];
+        const failedLinks = [];
+
+        for (const candidate of toApply) {
+          try {
+            persistSceneReferenceLink({
+              scenePath: resolvedScene.file_path,
+              syncDir: SYNC_DIR,
+              targetDocId: candidate.doc_id,
+              relation: candidate.relation,
+            });
+          } catch (err) {
+            failedLinks.push({
+              target_doc_id: candidate.doc_id,
+              relation: candidate.relation,
+              stage: "metadata",
+              code: err?.code ?? "IO_ERROR",
+              message: err?.code === "ENOENT"
+                ? `Scene file for '${scene_id}' not found at indexed path — run sync() to refresh.`
+                : `Failed to persist scene reference link metadata: ${err.message}`,
+            });
+            continue;
+          }
+
+          try {
+            upsertExplicitReferenceLinkRow(db, {
+              sourceKind: "scene",
+              sourceProjectId: resolvedProjectId,
+              sourceId: scene_id,
+              targetDocId: candidate.doc_id,
+              relation: candidate.relation,
+            });
+          } catch (err) {
+            failedLinks.push({
+              target_doc_id: candidate.doc_id,
+              relation: candidate.relation,
+              stage: "index",
+              code: err?.code ?? "IO_ERROR",
+              message: `Failed to persist scene reference link index row: ${err.message}`,
+            });
+            continue;
+          }
+
+          appliedLinks.push({
+            source_kind: "scene",
+            source_project_id: resolvedProjectId,
+            source_id: scene_id,
+            target_doc_id: candidate.doc_id,
+            relation: candidate.relation,
+            origin: "explicit",
+          });
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              scene_id,
+              project_id: resolvedProjectId,
+              mode,
+              total_candidates: enriched.length,
+                skipped_missing_doc_ids: skippedMissingDocIds,
+              applied_count: appliedLinks.length,
+              applied_links: appliedLinks,
+              failed_count: failedLinks.length,
+              failed_links: failedLinks,
+              candidates: enriched,
+            }, null, 2),
+          }],
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            scene_id,
+            project_id: resolvedProjectId,
+            total_candidates: enriched.length,
+              skipped_missing_doc_ids: skippedMissingDocIds,
+            candidates: enriched,
+          }, null, 2),
+        }],
+      };
+    }
+  );
 }