@hanna84/mcp-writing 3.26.0 → 3.28.0

package/CHANGELOG.md

@@ -4,9 +4,23 @@ 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).
 
+#### [v3.28.0](https://github.com/hannasdev/mcp-writing/compare/v3.27.0...v3.28.0)
+
+- feat: make restore plans easier to scan [`#238`](https://github.com/hannasdev/mcp-writing/pull/238)
+
+#### [v3.27.0](https://github.com/hannasdev/mcp-writing/compare/v3.26.0...v3.27.0)
+
+> 6 June 2026
+
+- feat(metadata): accept forgiving relationship evidence inputs [`#237`](https://github.com/hannasdev/mcp-writing/pull/237)
+- Release 3.27.0 [`ef5423b`](https://github.com/hannasdev/mcp-writing/commit/ef5423b044274b75bf60327772c9a944b94123c1)
+
 #### [v3.26.0](https://github.com/hannasdev/mcp-writing/compare/v3.25.0...v3.26.0)
 
+> 6 June 2026
+
 - feat: add canonical target resolver [`#236`](https://github.com/hannasdev/mcp-writing/pull/236)
+- Release 3.26.0 [`bb01109`](https://github.com/hannasdev/mcp-writing/commit/bb01109bdef98ad7020ffabc4fd249017b51998c)
 
 #### [v3.25.0](https://github.com/hannasdev/mcp-writing/compare/v3.24.1...v3.25.0)
 

package/README.md

@@ -152,7 +152,7 @@ Outcome: subplot structure stays visible and auditable, which reduces dropped th
 Goal: keep indexes accurate without manually re-tagging everything.
 
 1. After rewriting scenes, call `enrich_scene` to re-derive lightweight metadata from current prose.
-2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags). It rejects scene `characters` and `places`; use `connect_character_place_evidence` when a scene proves paired sheet-backed character/place evidence, `connect_scene_character_evidence` for character-only evidence, and `connect_scene_place_evidence` for place-only evidence. Use `audit_relationship_metadata` for retained sidecar/frontmatter relationship fields. Use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering.
+2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags). It rejects scene `characters` and `places`; use `connect_character_place_evidence` when a scene proves paired sheet-backed character/place evidence, `connect_scene_character_evidence` for character-only evidence, and `connect_scene_place_evidence` for place-only evidence. Those relationship evidence tools prefer canonical IDs but also accept unambiguous scene titles, character names, place names, and case variants; ambiguous or suggested-only matches fail without mutating state. Use `audit_relationship_metadata` for retained sidecar/frontmatter relationship fields. Use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering.
 3. Use `search_metadata` for keyword/FTS metadata searches across indexed titles, loglines, tags, characters, places, and versions, and use `find_scenes` to verify scenes are discoverable under structured filters. After identifying likely scenes, use `get_scene_prose` for prose context.
 
 Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.26.0",
+  "version": "3.28.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/core/canonical-target-resolution.js

@@ -211,6 +211,17 @@ function resolveFromRows({
   formatCandidate,
 }) {
   const normalizedInput = normalizeValue(input);
+  if (!normalizedInput) {
+    return buildResolutionFailure({
+      targetKind,
+      input,
+      projectId,
+      universeId,
+      candidateLimit,
+      candidates: [],
+    });
+  }
+
   const exactIdRows = rows.filter(row => row[idField] === input);
   if (exactIdRows.length === 1) {
     const candidate = formatCandidate(exactIdRows[0], { matchedField: idField, matchType: "exact_id" });

package/src/structure/project-backup-restore.js

@@ -873,6 +873,88 @@ function buildRestorePlan(currentSnapshot, backupSnapshot, { projectId }) {
   };
 }
 
+function buildPlanSummary(plan) {
+  return {
+    totals: { ...plan.totals },
+    by_domain: plan.by_domain,
+    destructive_change_count: plan.destructive_change_count,
+    cross_scope_change_count: plan.cross_scope_change_count,
+    has_destructive_changes: plan.destructive_change_count > 0,
+    has_cross_scope_changes: plan.cross_scope_change_count > 0,
+    requires_destructive_confirmation: plan.destructive_change_count > 0,
+    requires_cross_scope_confirmation: plan.cross_scope_change_count > 0,
+  };
+}
+
+function buildPlanDetailPolicy({ includeUnchanged, omittedUnchangedChangeCount }) {
+  return {
+    include_unchanged: includeUnchanged,
+    unchanged_rows_included: includeUnchanged,
+    omitted_unchanged_change_count: omittedUnchangedChangeCount,
+    full_plan_available: true,
+    full_plan_next_step: includeUnchanged
+      ? "This response includes unchanged rows. Pass include_unchanged=false to suppress unchanged row details while keeping plan_summary counts."
+      : "Rerun the restore plan with include_unchanged=true or omit include_unchanged to retrieve unchanged row details.",
+  };
+}
+
+function applyPlanDetailPolicy(plan, { includeUnchanged }) {
+  if (includeUnchanged) {
+    return {
+      plan,
+      planDetailPolicy: buildPlanDetailPolicy({
+        includeUnchanged,
+        omittedUnchangedChangeCount: 0,
+      }),
+    };
+  }
+
+  const visibleChanges = [];
+  let omittedUnchangedChangeCount = 0;
+  for (const change of plan.changes) {
+    if (change.action === "unchanged") {
+      omittedUnchangedChangeCount += 1;
+    } else {
+      visibleChanges.push(change);
+    }
+  }
+
+  return {
+    plan: {
+      ...plan,
+      changes: visibleChanges,
+    },
+    planDetailPolicy: buildPlanDetailPolicy({
+      includeUnchanged,
+      omittedUnchangedChangeCount,
+    }),
+  };
+}
+
+const BLOCKING_REQUIREMENT_PRIORITY = new Map([
+  ["project_restore_current_snapshot_confirmation_required", 0],
+  ["project_restore_current_snapshot_changed", 1],
+  ["project_restore_destructive_confirmation_required", 2],
+  ["project_restore_cross_scope_confirmation_required", 3],
+]);
+
+function buildBlockingRequirements(diagnostics) {
+  return [...diagnostics]
+    .sort((left, right) => {
+      const priorityDelta =
+        (BLOCKING_REQUIREMENT_PRIORITY.get(left.type) ?? 99) -
+        (BLOCKING_REQUIREMENT_PRIORITY.get(right.type) ?? 99);
+      if (priorityDelta !== 0) return priorityDelta;
+      return left.type.localeCompare(right.type);
+    })
+    .map(diagnostic => ({
+      type: diagnostic.type,
+      message: diagnostic.message,
+      next_step: diagnostic.next_step ?? null,
+      details: diagnostic.details,
+    }));
+}
+
 function placeholders(values) {
   return values.map(() => "?").join(",") || "NULL";
 }
@@ -1059,6 +1141,7 @@ export function restoreProjectFromBackup(db, {
   confirmDestructive = false,
   confirmCrossScope = false,
   expectedCurrentSnapshotChecksum = null,
+  includeUnchanged = true,
   applicationVersion = "0.0.0",
 } = {}) {
   const resolvedBackupDir = resolveBackupDir(backupPath ?? path.join(syncDir, "project-backups", projectId));
@@ -1150,6 +1233,10 @@ export function restoreProjectFromBackup(db, {
   }
 
   const plan = buildRestorePlan(current.snapshot, snapshot, { projectId });
+  const planSummary = buildPlanSummary(plan);
+  const { plan: responsePlan, planDetailPolicy } = applyPlanDetailPolicy(plan, {
+    includeUnchanged: includeUnchanged !== false,
+  });
   const applyDiagnostics = [];
   if (dryRun === false) {
     if (typeof expectedCurrentSnapshotChecksum !== "string" || expectedCurrentSnapshotChecksum === "") {
@@ -1222,8 +1309,11 @@ export function restoreProjectFromBackup(db, {
       dry_run: Boolean(dryRun),
       project_id: projectId,
       backup_dir: resolvedBackupDir,
+      blocking_requirements: buildBlockingRequirements(applyDiagnostics),
       diagnostics: applyDiagnostics,
-      plan,
+      plan_summary: planSummary,
+      plan_detail_policy: planDetailPolicy,
+      plan: responsePlan,
       next_step: "Resolve confirmation requirements before applying this trusted backup.",
     };
   }
@@ -1259,7 +1349,9 @@ export function restoreProjectFromBackup(db, {
           },
           { severity: "error", nextStep: "Review the database error and retry after resolving conflicts." }
         )],
-        plan,
+        plan_summary: planSummary,
+        plan_detail_policy: planDetailPolicy,
+        plan: responsePlan,
         next_step: "Resolve restore write diagnostics before retrying.",
       };
     }
@@ -1279,7 +1371,9 @@ export function restoreProjectFromBackup(db, {
     },
     current_snapshot_checksum: current.checksum,
     backup_snapshot_checksum: manifest.checksums.canonical_snapshot_sha256,
-    plan,
+    plan_summary: planSummary,
+    plan_detail_policy: planDetailPolicy,
+    plan: responsePlan,
     applied: dryRun ? null : {
       restored: true,
       destructive_confirmed: Boolean(confirmDestructive),

package/src/tools/metadata.js

@@ -5,6 +5,11 @@ import matter from "gray-matter";
 import { readMeta, readSourceMeta, writeMeta, indexSceneFile, isManagedStructureProject, normalizeSceneMetaForPath, resolveSceneCharacterCompatibilityId } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
+import {
+  resolveCharacterTargetForProject,
+  resolvePlaceTargetForProject,
+  resolveSceneTarget,
+} from "../core/canonical-target-resolution.js";
 import {
   FILESYSTEM_ARTIFACT_CLASSES,
   assertRegularFileReadTarget,
@@ -130,38 +135,26 @@ function buildRelationshipMetadataBoundaryDetails({ projectId, sceneId, blockedF
   };
 }
 
-function relationshipEvidenceNotFoundDetails({ lookupKind, input, projectId, sceneId }) {
-  const details = {
-    lookup_kind: lookupKind,
-    input,
-    project_id: projectId,
-  };
-  if (sceneId !== undefined) {
-    details.scene_id = sceneId;
-  }
-
-  if (lookupKind === "scene") {
-    return {
-      ...details,
-      next_step: "Use find_scenes with the project_id to confirm the canonical scene_id, then retry the relationship evidence tool.",
-    };
-  }
+function alreadyLinkedRelationshipNextStep({ entityKind }) {
+  return `This ${entityKind} was already linked to the scene, so no canonical relationship rows changed. Use the scene_relationships field in this response to inspect current links; call get_scene_prose with the scene_id and project_id if prose context is needed.`;
+}
 
-  if (lookupKind === "character") {
-    return {
-      ...details,
-      next_step: "Use list_characters to find the stable character_id for this project or universe, then retry the relationship evidence tool.",
-    };
+function mergeResolvedFrom(...resolutions) {
+  const merged = {};
+  for (const resolution of resolutions) {
+    if (resolution?.resolved_from) {
+      Object.assign(merged, resolution.resolved_from);
+    }
   }
-
-  return {
-    ...details,
-    next_step: "Use list_places to find the stable place_id for this project or universe, then retry the relationship evidence tool.",
-  };
+  return Object.keys(merged).length > 0 ? merged : undefined;
 }
 
-function alreadyLinkedRelationshipNextStep({ entityKind }) {
-  return `This ${entityKind} was already linked to the scene, so no canonical relationship rows changed. Use the scene_relationships field in this response to inspect current links; call get_scene_prose with the scene_id and project_id if prose context is needed.`;
+function relationshipEvidenceResolutionError(errorResponse, resolution, { sceneId } = {}) {
+  const details = {
+    ...(resolution.error.details ?? {}),
+    ...(sceneId !== undefined ? { scene_id: sceneId } : {}),
+  };
+  return errorResponse(resolution.error.code, resolution.error.message, details);
 }
 
 function persistReferenceDocLink({ filePath, syncDir, targetDocId, relation }) {
@@ -461,21 +454,6 @@ function resolveCharacterForProject(db, { characterId, projectId }) {
   `).get(characterId, projectId, universeId);
 }
 
-function resolvePlaceForProject(db, { placeId, projectId }) {
-  const universeId = getProjectUniverseId(db, projectId);
-  return db.prepare(`
-    SELECT place_id, project_id, universe_id, name
-    FROM places
-    WHERE place_id = ?
-      AND (
-        project_id = ?
-        OR (universe_id IS NOT NULL AND universe_id = ?)
-        OR (project_id IS NULL AND universe_id IS NULL)
-      )
-    LIMIT 1
-  `).get(placeId, projectId, universeId);
-}
-
 function querySceneRelationshipSnapshot(db, { sceneId, projectId }) {
   return {
     characters: db.prepare(`
@@ -890,61 +868,53 @@ export function registerMetadataTools(s, {
       return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
     }
 
+    const sceneResolution = resolveSceneTarget(db, {
+      projectId: project_id,
+      input: scene_id,
+      argumentName: "scene_id",
+    });
+    if (!sceneResolution.ok) {
+      return relationshipEvidenceResolutionError(errorResponse, sceneResolution);
+    }
+    const canonicalSceneId = sceneResolution.scene_id;
+
     const scene = db.prepare(`
       SELECT scene_id, project_id, file_path
       FROM scenes
       WHERE scene_id = ? AND project_id = ?
-    `).get(scene_id, project_id);
-    if (!scene) {
-      return errorResponse(
-        "NOT_FOUND",
-        `Scene '${scene_id}' not found in project '${project_id}'.`,
-        relationshipEvidenceNotFoundDetails({
-          lookupKind: "scene",
-          input: scene_id,
-          projectId: project_id,
-        })
-      );
-    }
+    `).get(canonicalSceneId, project_id);
 
-    const character = resolveCharacterForProject(db, { characterId: character_id, projectId: project_id });
-    if (!character) {
-      return errorResponse(
-        "NOT_FOUND",
-        `Character '${character_id}' is not indexed for project '${project_id}' or its universe.`,
-        relationshipEvidenceNotFoundDetails({
-          lookupKind: "character",
-          input: character_id,
-          projectId: project_id,
-          sceneId: scene_id,
-        })
-      );
+    const characterResolution = resolveCharacterTargetForProject(db, {
+      projectId: project_id,
+      input: character_id,
+      argumentName: "character_id",
+    });
+    if (!characterResolution.ok) {
+      return relationshipEvidenceResolutionError(errorResponse, characterResolution, { sceneId: canonicalSceneId });
     }
-    const place = resolvePlaceForProject(db, { placeId: place_id, projectId: project_id });
-    if (!place) {
-      return errorResponse(
-        "NOT_FOUND",
-        `Place '${place_id}' is not indexed for project '${project_id}' or its universe.`,
-        relationshipEvidenceNotFoundDetails({
-          lookupKind: "place",
-          input: place_id,
-          projectId: project_id,
-          sceneId: scene_id,
-        })
-      );
+    const canonicalCharacterId = characterResolution.character_id;
+
+    const placeResolution = resolvePlaceTargetForProject(db, {
+      projectId: project_id,
+      input: place_id,
+      argumentName: "place_id",
+    });
+    if (!placeResolution.ok) {
+      return relationshipEvidenceResolutionError(errorResponse, placeResolution, { sceneId: canonicalSceneId });
     }
+    const canonicalPlaceId = placeResolution.place_id;
 
-    const before = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
+    const before = querySceneRelationshipSnapshot(db, { sceneId: canonicalSceneId, projectId: project_id });
     try {
       db.exec("BEGIN");
       db.prepare(`
         INSERT OR IGNORE INTO scene_characters (scene_id, project_id, character_id)
         VALUES (?, ?, ?)
-      `).run(scene_id, project_id, character_id);
+      `).run(canonicalSceneId, project_id, canonicalCharacterId);
       db.prepare(`
         INSERT OR IGNORE INTO scene_places (scene_id, project_id, place_id)
         VALUES (?, ?, ?)
-      `).run(scene_id, project_id, place_id);
+      `).run(canonicalSceneId, project_id, canonicalPlaceId);
       db.exec("COMMIT");
     } catch (err) {
       try {
@@ -952,10 +922,10 @@ export function registerMetadataTools(s, {
       } catch (rollbackErr) {
         void rollbackErr;
       }
-      return errorResponse("IO_ERROR", `Failed to connect character/place evidence for scene '${scene_id}': ${err.message}`);
+      return errorResponse("IO_ERROR", `Failed to connect character/place evidence for scene '${canonicalSceneId}': ${err.message}`);
     }
 
-    const after = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
+    const after = querySceneRelationshipSnapshot(db, { sceneId: canonicalSceneId, projectId: project_id });
     const backupResult = refreshProjectScopedBackupAfterMutation(db, {
       syncDir: SYNC_DIR,
       projectId: project_id,
@@ -963,11 +933,11 @@ export function registerMetadataTools(s, {
       operation: "connect_character_place_evidence",
       actor: createToolActor("connect_character_place_evidence"),
       affected: {
-        scenes: [scene_id],
-        characters: [character_id],
-        places: [place_id],
+        scenes: [canonicalSceneId],
+        characters: [canonicalCharacterId],
+        places: [canonicalPlaceId],
       },
-      summary: `Connected character "${character_id}" and place "${place_id}" as evidence in scene "${scene_id}".`,
+      summary: `Connected character "${canonicalCharacterId}" and place "${canonicalPlaceId}" as evidence in scene "${canonicalSceneId}".`,
       before: {
         scene_relationships: before,
       },
@@ -984,10 +954,10 @@ export function registerMetadataTools(s, {
       compatibilityDiagnostics.push({
         code: "STALE_PATH",
         severity: "warning",
-        message: `Canonical scene relationship evidence was committed, but scene '${scene_id}' has no indexed file path for generated compatibility output.`,
+        message: `Canonical scene relationship evidence was committed, but scene '${canonicalSceneId}' has no indexed file path for generated compatibility output.`,
         next_step: "Treat SQLite and project backup artifacts as current. Run sync and inspect the indexed scene path before retrying compatibility output.",
         details: {
-          scene_id,
+          scene_id: canonicalSceneId,
           project_id,
           indexed_path: null,
         },
@@ -996,7 +966,7 @@ export function registerMetadataTools(s, {
       try {
         writeSceneRelationshipCompatibilityOutput({
           db,
-          sceneId: scene_id,
+          sceneId: canonicalSceneId,
           projectId: project_id,
           scenePath: scene.file_path,
           syncDir: SYNC_DIR,
@@ -1009,7 +979,7 @@ export function registerMetadataTools(s, {
           message: `Canonical scene relationship evidence was committed, but generated scene metadata compatibility output could not be refreshed: ${err.message}`,
           next_step: "Treat SQLite and project backup artifacts as current. Run sync and inspect the indexed scene path before retrying compatibility output.",
           details: {
-            scene_id,
+            scene_id: canonicalSceneId,
             project_id,
             indexed_path: scene.file_path,
           },
@@ -1017,13 +987,15 @@ export function registerMetadataTools(s, {
       }
     }
 
+    const resolvedFrom = mergeResolvedFrom(sceneResolution, characterResolution, placeResolution);
     return jsonResponse({
       ok: true,
       action: "connected",
-      scene_id,
+      scene_id: canonicalSceneId,
       project_id,
-      character_id,
-      place_id,
+      character_id: canonicalCharacterId,
+      place_id: canonicalPlaceId,
+      ...(resolvedFrom ? { resolved_from: resolvedFrom } : {}),
       note: note ?? null,
       mutation_order: [
         "validated_request",
@@ -1059,45 +1031,36 @@ export function registerMetadataTools(s, {
       return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
     }
 
+    const sceneResolution = resolveSceneTarget(db, {
+      projectId: project_id,
+      input: scene_id,
+      argumentName: "scene_id",
+    });
+    if (!sceneResolution.ok) {
+      return relationshipEvidenceResolutionError(errorResponse, sceneResolution);
+    }
+    const canonicalSceneId = sceneResolution.scene_id;
+
     const scene = db.prepare(`
       SELECT scene_id, project_id, file_path
       FROM scenes
       WHERE scene_id = ? AND project_id = ?
-    `).get(scene_id, project_id);
-    if (!scene) {
-      return errorResponse(
-        "NOT_FOUND",
-        `Scene '${scene_id}' not found in project '${project_id}'.`,
-        relationshipEvidenceNotFoundDetails({
-          lookupKind: "scene",
-          input: scene_id,
-          projectId: project_id,
-        })
-      );
-    }
+    `).get(canonicalSceneId, project_id);
 
-    if (!resolveEntity(entity_id)) {
-      const label = entityKind[0].toUpperCase() + entityKind.slice(1);
-      return errorResponse(
-        "NOT_FOUND",
-        `${label} '${entity_id}' is not indexed for project '${project_id}' or its universe.`,
-        relationshipEvidenceNotFoundDetails({
-          lookupKind: entityKind,
-          input: entity_id,
-          projectId: project_id,
-          sceneId: scene_id,
-        })
-      );
+    const entityResolution = resolveEntity(entity_id);
+    if (!entityResolution.ok) {
+      return relationshipEvidenceResolutionError(errorResponse, entityResolution, { sceneId: canonicalSceneId });
     }
+    const canonicalEntityId = entityResolution[idField];
 
-    const before = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
-    const alreadyLinked = before[entityKind === "character" ? "characters" : "places"].includes(entity_id);
+    const before = querySceneRelationshipSnapshot(db, { sceneId: canonicalSceneId, projectId: project_id });
+    const alreadyLinked = before[entityKind === "character" ? "characters" : "places"].includes(canonicalEntityId);
     try {
       db.exec("BEGIN");
       db.prepare(`
         INSERT OR IGNORE INTO ${tableName} (scene_id, project_id, ${idField})
         VALUES (?, ?, ?)
-      `).run(scene_id, project_id, entity_id);
+      `).run(canonicalSceneId, project_id, canonicalEntityId);
       db.exec("COMMIT");
     } catch (err) {
       try {
@@ -1105,10 +1068,10 @@ export function registerMetadataTools(s, {
       } catch (rollbackErr) {
         void rollbackErr;
       }
-      return errorResponse("IO_ERROR", `Failed to connect scene ${entityKind} evidence for scene '${scene_id}': ${err.message}`);
+      return errorResponse("IO_ERROR", `Failed to connect scene ${entityKind} evidence for scene '${canonicalSceneId}': ${err.message}`);
     }
 
-    const after = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
+    const after = querySceneRelationshipSnapshot(db, { sceneId: canonicalSceneId, projectId: project_id });
     const backupResult = refreshProjectScopedBackupAfterMutation(db, {
       syncDir: SYNC_DIR,
       projectId: project_id,
@@ -1116,10 +1079,10 @@ export function registerMetadataTools(s, {
       operation,
       actor: createToolActor(operation),
       affected: {
-        scenes: [scene_id],
-        [`${entityKind}s`]: [entity_id],
+        scenes: [canonicalSceneId],
+        [`${entityKind}s`]: [canonicalEntityId],
       },
-      summary: `Connected ${entityKind} "${entity_id}" as evidence in scene "${scene_id}".`,
+      summary: `Connected ${entityKind} "${canonicalEntityId}" as evidence in scene "${canonicalSceneId}".`,
       before: {
         scene_relationships: before,
       },
@@ -1136,10 +1099,10 @@ export function registerMetadataTools(s, {
       compatibilityDiagnostics.push({
         code: "STALE_PATH",
         severity: "warning",
-        message: `Canonical scene ${entityKind} evidence was committed, but scene '${scene_id}' has no indexed file path for generated compatibility output.`,
+        message: `Canonical scene ${entityKind} evidence was committed, but scene '${canonicalSceneId}' has no indexed file path for generated compatibility output.`,
         next_step: "Treat SQLite and project backup artifacts as current. Run sync and inspect the indexed scene path before retrying compatibility output.",
         details: {
-          scene_id,
+          scene_id: canonicalSceneId,
           project_id,
           indexed_path: null,
         },
@@ -1148,7 +1111,7 @@ export function registerMetadataTools(s, {
       try {
         writeSceneRelationshipCompatibilityOutput({
           db,
-          sceneId: scene_id,
+          sceneId: canonicalSceneId,
           projectId: project_id,
           scenePath: scene.file_path,
           syncDir: SYNC_DIR,
@@ -1161,7 +1124,7 @@ export function registerMetadataTools(s, {
           message: `Canonical scene ${entityKind} evidence was committed, but generated scene metadata compatibility output could not be refreshed: ${err.message}`,
           next_step: "Treat SQLite and project backup artifacts as current. Run sync and inspect the indexed scene path before retrying compatibility output.",
           details: {
-            scene_id,
+            scene_id: canonicalSceneId,
             project_id,
             indexed_path: scene.file_path,
           },
@@ -1169,6 +1132,7 @@ export function registerMetadataTools(s, {
       }
     }
 
+    const resolvedFrom = mergeResolvedFrom(sceneResolution, entityResolution);
     return jsonResponse({
       ok: true,
       action: "connected",
@@ -1177,9 +1141,10 @@ export function registerMetadataTools(s, {
       ...(alreadyLinked
         ? { next_step: alreadyLinkedRelationshipNextStep({ entityKind }) }
         : {}),
-      scene_id,
+      scene_id: canonicalSceneId,
       project_id,
-      [idField]: entity_id,
+      [idField]: canonicalEntityId,
+      ...(resolvedFrom ? { resolved_from: resolvedFrom } : {}),
       note: note ?? null,
       scene_relationships: after,
       mutation_order: [
@@ -1207,7 +1172,11 @@ export function registerMetadataTools(s, {
       entityKind: "character",
       idField: "character_id",
       tableName: "scene_characters",
-      resolveEntity: (characterId) => resolveCharacterForProject(db, { characterId, projectId: args.project_id }),
+      resolveEntity: (characterId) => resolveCharacterTargetForProject(db, {
+        projectId: args.project_id,
+        input: characterId,
+        argumentName: "character_id",
+      }),
     });
   }
 
@@ -1222,7 +1191,11 @@ export function registerMetadataTools(s, {
       entityKind: "place",
       idField: "place_id",
       tableName: "scene_places",
-      resolveEntity: (placeId) => resolvePlaceForProject(db, { placeId, projectId: args.project_id }),
+      resolveEntity: (placeId) => resolvePlaceTargetForProject(db, {
+        projectId: args.project_id,
+        input: placeId,
+        argumentName: "place_id",
+      }),
     });
   }
 
@@ -1733,12 +1706,12 @@ export function registerMetadataTools(s, {
   // ---- connect_character_place_evidence ------------------------------------
   s.tool(
     "connect_character_place_evidence",
-    "Connect a character and place as paired scene-backed story evidence. This outcome-level workflow covers sheet-backed character/place associations: SQLite scene relationship indexes commit first, project backups refresh after commit, and scene sidecar characters/places are regenerated only as generated compatibility output from canonical indexes. Use connect_scene_character_evidence or connect_scene_place_evidence for one-sided scene evidence.",
+    "Connect a character and place as paired scene-backed story evidence. This outcome-level workflow covers sheet-backed character/place associations: SQLite scene relationship indexes commit first, project backups refresh after commit, and scene sidecar characters/places are regenerated only as generated compatibility output from canonical indexes. Canonical IDs are preferred; unambiguous case-insensitive scene titles, character names, place names, and ID variants are resolved to canonical IDs before mutation. Ambiguous or suggested-only matches fail without mutating state. Use connect_scene_character_evidence or connect_scene_place_evidence for one-sided scene evidence.",
     {
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
-      scene_id: z.string().describe("Scene that provides the evidence for this character/place association."),
-      character_id: z.string().describe("Character present in the scene. Use list_characters to find valid IDs."),
-      place_id: z.string().describe("Place present in the scene. Use list_places to find valid IDs."),
+      scene_id: z.string().describe("Scene that provides the evidence. Prefer canonical scene_id; an unambiguous case-insensitive scene_id or unique scene title in this project is also accepted."),
+      character_id: z.string().describe("Character present in the scene. Prefer canonical character_id; an unambiguous case-insensitive character_id or character name in this project/universe scope is also accepted."),
+      place_id: z.string().describe("Place present in the scene. Prefer canonical place_id; an unambiguous case-insensitive place_id or place name in this project/universe scope is also accepted."),
       note: z.string().optional().describe("Optional review note explaining the evidence. Stored in operation history, not in compatibility sidecars."),
     },
     async (args) => connectCharacterPlaceEvidence(args)
@@ -1747,11 +1720,11 @@ export function registerMetadataTools(s, {
   // ---- connect_scene_character_evidence -----------------------------------
   s.tool(
     "connect_scene_character_evidence",
-    "Connect a sheet-backed character to a scene without requiring paired place evidence. This outcome-level workflow records character-only scene evidence in SQLite first, refreshes project backups after commit, and regenerates scene sidecar characters/places only as generated compatibility output from canonical indexes.",
+    "Connect a sheet-backed character to a scene without requiring paired place evidence. This outcome-level workflow records character-only scene evidence in SQLite first, refreshes project backups after commit, and regenerates scene sidecar characters/places only as generated compatibility output from canonical indexes. Canonical IDs are preferred; unambiguous case-insensitive scene titles, character names, and ID variants are resolved to canonical IDs before mutation. Ambiguous or suggested-only matches fail without mutating state.",
     {
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
-      scene_id: z.string().describe("Scene that provides the evidence for this character."),
-      character_id: z.string().describe("Sheet-backed character_id present in the scene. Use list_characters to find valid IDs; freeform names are rejected."),
+      scene_id: z.string().describe("Scene that provides the evidence. Prefer canonical scene_id; an unambiguous case-insensitive scene_id or unique scene title in this project is also accepted."),
+      character_id: z.string().describe("Sheet-backed character present in the scene. Prefer canonical character_id; an unambiguous case-insensitive character_id or character name in this project/universe scope is also accepted."),
       note: z.string().optional().describe("Optional review note explaining the evidence. Stored in operation history, not in compatibility sidecars."),
     },
     async (args) => connectSceneCharacterEvidence(args)
@@ -1760,11 +1733,11 @@ export function registerMetadataTools(s, {
   // ---- connect_scene_place_evidence ---------------------------------------
   s.tool(
     "connect_scene_place_evidence",
-    "Connect a sheet-backed place to a scene without requiring paired character evidence. This outcome-level workflow records place-only scene evidence in SQLite first, refreshes project backups after commit, and regenerates scene sidecar characters/places only as generated compatibility output from canonical indexes.",
+    "Connect a sheet-backed place to a scene without requiring paired character evidence. This outcome-level workflow records place-only scene evidence in SQLite first, refreshes project backups after commit, and regenerates scene sidecar characters/places only as generated compatibility output from canonical indexes. Canonical IDs are preferred; unambiguous case-insensitive scene titles, place names, and ID variants are resolved to canonical IDs before mutation. Ambiguous or suggested-only matches fail without mutating state.",
     {
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
-      scene_id: z.string().describe("Scene that provides the evidence for this place."),
-      place_id: z.string().describe("Sheet-backed place_id present in the scene. Use list_places to find valid IDs; freeform names are rejected."),
+      scene_id: z.string().describe("Scene that provides the evidence. Prefer canonical scene_id; an unambiguous case-insensitive scene_id or unique scene title in this project is also accepted."),
+      place_id: z.string().describe("Sheet-backed place present in the scene. Prefer canonical place_id; an unambiguous case-insensitive place_id or place name in this project/universe scope is also accepted."),
       note: z.string().optional().describe("Optional review note explaining the evidence. Stored in operation history, not in compatibility sidecars."),
     },
     async (args) => connectScenePlaceEvidence(args)

package/src/tools/sync.js

@@ -338,7 +338,7 @@ export function registerSyncTools(s, {
 
   s.tool(
     "restore_project_from_backup",
-    "Explicitly restore a project from a trusted generated project backup bundle. Defaults to dry-run planning; dry_run=false applies canonical SQLite changes transactionally after the reviewed current snapshot checksum and required destructive or cross-scope confirmations are provided.",
+    "Explicitly restore a project from a trusted generated project backup bundle. Defaults to dry-run planning; dry_run=false applies canonical SQLite changes transactionally after the reviewed current snapshot checksum and required destructive or cross-scope confirmations are provided. Restore plan and confirmation-refusal responses include compact plan_summary details; confirmation refusals include blocking_requirements. include_unchanged=false suppresses unchanged row details while preserving summary counts.",
     {
       project_id: z.string().describe("Project ID to restore (e.g. 'test-novel' or 'universe-1/book-1-the-lamb')."),
       backup_path: z.string().optional().describe("Path under WRITING_SYNC_DIR to a project backup directory, manifest.json, or canonical.snapshot.json. Defaults to project-backups/<project_id>."),
@@ -346,8 +346,9 @@ export function registerSyncTools(s, {
       confirm_destructive: z.boolean().optional().describe("Required with dry_run=false when the restore plan includes delete candidates."),
       confirm_cross_scope: z.boolean().optional().describe("Required with dry_run=false when the restore plan changes universe-scoped records."),
       expected_current_snapshot_checksum: z.string().optional().describe("Required with dry_run=false; pass the current_snapshot_checksum returned by the reviewed dry-run plan to guard against state changes before apply."),
+      include_unchanged: z.boolean().optional().describe("If false, suppress unchanged rows from plan.changes while preserving plan_summary counts. Defaults to true for compatibility."),
     },
-    async ({ project_id, backup_path, dry_run = true, confirm_destructive = false, confirm_cross_scope = false, expected_current_snapshot_checksum = null } = {}) => {
+    async ({ project_id, backup_path, dry_run = true, confirm_destructive = false, confirm_cross_scope = false, expected_current_snapshot_checksum = null, include_unchanged = true } = {}) => {
       if (!SYNC_DIR_WRITABLE && dry_run === false) {
         return errorResponse("READ_ONLY", "Cannot restore project from backup: server is in read-only mode for canonical structure mutations.");
       }
@@ -374,6 +375,7 @@ export function registerSyncTools(s, {
           confirmDestructive: confirm_destructive,
           confirmCrossScope: confirm_cross_scope,
           expectedCurrentSnapshotChecksum: expected_current_snapshot_checksum,
+          includeUnchanged: include_unchanged,
           applicationVersion: MCP_SERVER_VERSION,
         }));
       } catch (error) {