@hanna84/mcp-writing 3.23.1 → 3.24.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.24.0](https://github.com/hannasdev/mcp-writing/compare/v3.23.2...v3.24.0)
+
+- feat: add one-sided scene evidence workflows [`#233`](https://github.com/hannasdev/mcp-writing/pull/233)
+
+#### [v3.23.2](https://github.com/hannasdev/mcp-writing/compare/v3.23.1...v3.23.2)
+
+> 6 June 2026
+
+- docs: clarify relationship workflow guidance [`#232`](https://github.com/hannasdev/mcp-writing/pull/232)
+- Release 3.23.2 [`a4bd2e9`](https://github.com/hannasdev/mcp-writing/commit/a4bd2e9e957ebaf8b933325d04202411ab0b86e8)
+
 #### [v3.23.1](https://github.com/hannasdev/mcp-writing/compare/v3.23.0...v3.23.1)
 
+> 30 May 2026
+
 - fix: align relationship compatibility sync and audit [`#231`](https://github.com/hannasdev/mcp-writing/pull/231)
+- Release 3.23.1 [`f0b643b`](https://github.com/hannasdev/mcp-writing/commit/f0b643bcb7b09adf066380d37718b09001dd3020)
 
 #### [v3.23.0](https://github.com/hannasdev/mcp-writing/compare/v3.22.5...v3.23.0)
 

package/README.md

@@ -30,7 +30,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 - **Core platform complete:** Metadata-first analysis, SQLite-canonical structural and relationship metadata, compatibility sidecar maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
 - **Recently completed:** Database Backup and Recovery added project backup export, freshness diagnostics, advisory operation history, automatic backup refresh after sanctioned project-scoped canonical mutations, dry-run restore planning, transactional restore application, and backup/restore operations guidance.
 - **Previous milestone:** Docker, CI, and Deployment Workflow made Docker a supported way to build, run, smoke-test, and deploy Writing MCP.
-- **Active development:** Architecture Alignment Follow-up M5, documenting sidecar compatibility, migration, and deprecation expectations.
+- **Active development:** Relationship Metadata Boundary M3, aligning workflow and generated documentation around SQLite-canonical relationship authority.
 - **Deferred backlog:** OpenClaw integration, client-agnostic setup, divisions, and embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
 
@@ -153,7 +153,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); use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering. Numeric chapter filters are compatibility aliases for read scopes, not mutation targets.
+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.
 3. Use `search_metadata` and `find_scenes` to verify scenes are discoverable under the expected filters.
 
 Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.
@@ -179,7 +179,7 @@ Goal: rebuild scene-to-character links in a controlled way after imported prose
 4. Re-run `enrich_scene_characters_batch` with `dry_run=false` once the preview looks correct.
 5. If you want a destructive overwrite instead of additive merge behavior, use `replace_mode=replace` with `confirm_replace=true` deliberately.
 
-Outcome: character-link maintenance becomes a preview-first batch operation instead of a one-off regex script or manual sidecar cleanup.
+Outcome: character-link maintenance becomes a preview-first relationship repair operation instead of a one-off regex script or manual sidecar cleanup.
 
 ### 6) Post-upgrade recovery after legacy migration warnings
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.23.1",
+  "version": "3.24.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/tools/metadata.js

@@ -119,9 +119,14 @@ function buildRelationshipMetadataBoundaryDetails({ projectId, sceneId, blockedF
     scene_id: sceneId,
     blocked_fields: blockedFields,
     boundary: "scene_relationship_metadata",
-    relationship_tools: ["connect_character_place_evidence", "audit_relationship_metadata"],
+    relationship_tools: [
+      "connect_character_place_evidence",
+      "connect_scene_character_evidence",
+      "connect_scene_place_evidence",
+      "audit_relationship_metadata",
+    ],
     discovery_workflows: ["describe_workflows", "find_scenes", "list_characters", "list_places"],
-    next_step: "Use find_scenes, list_characters, and list_places to identify stable IDs. Use connect_character_place_evidence only when the scene proves paired sheet-backed character/place evidence; use audit_relationship_metadata to review legacy sidecar/frontmatter relationship fields. Character-only or place-only scene evidence is not changed through update_scene_metadata.",
+    next_step: "Use find_scenes, list_characters, and list_places to identify stable IDs. Use connect_character_place_evidence when the scene proves paired sheet-backed character/place evidence, connect_scene_character_evidence for character-only evidence, connect_scene_place_evidence for place-only evidence, and audit_relationship_metadata to review legacy sidecar/frontmatter relationship fields.",
   };
 }
 
@@ -526,11 +531,50 @@ function buildSceneMetadataSearchKeywords(meta, relationshipSnapshot) {
 }
 
 function restoreSceneRelationshipSearchKeywords(db, { sceneId, projectId, meta, snapshot }) {
-  db.prepare(`
-    UPDATE scenes_fts
-    SET keywords = ?
+  const existingFts = db.prepare(`
+    SELECT logline, title
+    FROM scenes_fts
     WHERE scene_id = ? AND project_id = ?
-  `).run(buildSceneMetadataSearchKeywords(meta, snapshot), sceneId, projectId);
+  `).get(sceneId, projectId);
+  try {
+    db.exec("SAVEPOINT scene_relationship_fts_refresh");
+    db.prepare(`DELETE FROM scenes_fts WHERE scene_id = ? AND project_id = ?`).run(sceneId, projectId);
+    db.prepare(`
+      INSERT INTO scenes_fts (scene_id, project_id, logline, title, keywords)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(
+      sceneId,
+      projectId,
+      meta.logline ?? meta.synopsis ?? existingFts?.logline ?? "",
+      meta.title ?? existingFts?.title ?? "",
+      buildSceneMetadataSearchKeywords(meta, snapshot),
+    );
+    db.exec("RELEASE scene_relationship_fts_refresh");
+  } catch (err) {
+    try {
+      db.exec("ROLLBACK TO scene_relationship_fts_refresh");
+      db.exec("RELEASE scene_relationship_fts_refresh");
+    } catch (rollbackErr) {
+      void rollbackErr;
+    }
+    throw err;
+  }
+}
+
+function writeSceneRelationshipCompatibilityOutput({ db, sceneId, projectId, scenePath, syncDir, snapshot }) {
+  const { sourceMeta } = readSourceMeta(scenePath, syncDir, { writable: true });
+  const nextMeta = {
+    ...sourceMeta,
+    characters: uniqueSorted(snapshot.characters),
+    places: uniqueSorted(snapshot.places),
+  };
+  writeMeta(scenePath, nextMeta, { syncDir });
+  restoreSceneRelationshipSearchKeywords(db, {
+    sceneId,
+    projectId,
+    meta: nextMeta,
+    snapshot,
+  });
 }
 
 export function registerMetadataTools(s, {
@@ -890,12 +934,14 @@ export function registerMetadataTools(s, {
       });
     } else {
       try {
-        const { sourceMeta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
-        writeMeta(scene.file_path, {
-          ...sourceMeta,
-          characters: uniqueSorted([...normalizeStringList(sourceMeta.characters), character_id]),
-          places: uniqueSorted([...normalizeStringList(sourceMeta.places), place_id]),
-        }, { syncDir: SYNC_DIR });
+        writeSceneRelationshipCompatibilityOutput({
+          db,
+          sceneId: scene_id,
+          projectId: project_id,
+          scenePath: scene.file_path,
+          syncDir: SYNC_DIR,
+          snapshot: after,
+        });
       } catch (err) {
         compatibilityDiagnostics.push({
           code: err?.code ?? "COMPATIBILITY_OUTPUT_FAILED",
@@ -933,6 +979,172 @@ export function registerMetadataTools(s, {
     });
   }
 
+  async function connectOneSidedSceneEvidence({
+    project_id,
+    scene_id,
+    entity_id,
+    note,
+  }, {
+    operation,
+    entityKind,
+    idField,
+    tableName,
+    resolveEntity,
+  }) {
+    if (!SYNC_DIR_WRITABLE) {
+      return errorResponse("READ_ONLY", `Cannot connect scene ${entityKind} evidence: sync dir is read-only.`);
+    }
+    const projectIdCheck = validateProjectId(project_id);
+    if (!projectIdCheck.ok) {
+      return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_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}'.`);
+    }
+
+    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.`);
+    }
+
+    const before = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
+    const alreadyLinked = before[entityKind === "character" ? "characters" : "places"].includes(entity_id);
+    try {
+      db.exec("BEGIN");
+      db.prepare(`
+        INSERT OR IGNORE INTO ${tableName} (scene_id, project_id, ${idField})
+        VALUES (?, ?, ?)
+      `).run(scene_id, project_id, entity_id);
+      db.exec("COMMIT");
+    } catch (err) {
+      try {
+        db.exec("ROLLBACK");
+      } catch (rollbackErr) {
+        void rollbackErr;
+      }
+      return errorResponse("IO_ERROR", `Failed to connect scene ${entityKind} evidence for scene '${scene_id}': ${err.message}`);
+    }
+
+    const after = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
+    const backupResult = refreshProjectScopedBackupAfterMutation(db, {
+      syncDir: SYNC_DIR,
+      projectId: project_id,
+      applicationVersion: MCP_SERVER_VERSION,
+      operation,
+      actor: createToolActor(operation),
+      affected: {
+        scenes: [scene_id],
+        [`${entityKind}s`]: [entity_id],
+      },
+      summary: `Connected ${entityKind} "${entity_id}" as evidence in scene "${scene_id}".`,
+      before: {
+        scene_relationships: before,
+      },
+      after: {
+        scene_relationships: after,
+      },
+      metadata: {
+        note: note ?? null,
+      },
+    });
+
+    const compatibilityDiagnostics = [];
+    if (!scene.file_path) {
+      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.`,
+        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,
+          project_id,
+          indexed_path: null,
+        },
+      });
+    } else {
+      try {
+        writeSceneRelationshipCompatibilityOutput({
+          db,
+          sceneId: scene_id,
+          projectId: project_id,
+          scenePath: scene.file_path,
+          syncDir: SYNC_DIR,
+          snapshot: after,
+        });
+      } catch (err) {
+        compatibilityDiagnostics.push({
+          code: err?.code ?? "COMPATIBILITY_OUTPUT_FAILED",
+          severity: "warning",
+          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,
+            project_id,
+            indexed_path: scene.file_path,
+          },
+        });
+      }
+    }
+
+    return jsonResponse({
+      ok: true,
+      action: "connected",
+      already_linked: alreadyLinked,
+      scene_id,
+      project_id,
+      [idField]: entity_id,
+      note: note ?? null,
+      scene_relationships: after,
+      mutation_order: [
+        "validated_request",
+        "sqlite_commit",
+        "project_backup_refresh",
+        "compatibility_output_refresh",
+      ],
+      compatibility_output: buildCompatibilityOutput({
+        refreshed: compatibilityDiagnostics.length === 0,
+        diagnostics: compatibilityDiagnostics,
+      }),
+      ...backupMutationFields(backupResult),
+    });
+  }
+
+  async function connectSceneCharacterEvidence(args) {
+    return connectOneSidedSceneEvidence({
+      project_id: args.project_id,
+      scene_id: args.scene_id,
+      entity_id: args.character_id,
+      note: args.note,
+    }, {
+      operation: "connect_scene_character_evidence",
+      entityKind: "character",
+      idField: "character_id",
+      tableName: "scene_characters",
+      resolveEntity: (characterId) => resolveCharacterForProject(db, { characterId, projectId: args.project_id }),
+    });
+  }
+
+  async function connectScenePlaceEvidence(args) {
+    return connectOneSidedSceneEvidence({
+      project_id: args.project_id,
+      scene_id: args.scene_id,
+      entity_id: args.place_id,
+      note: args.note,
+    }, {
+      operation: "connect_scene_place_evidence",
+      entityKind: "place",
+      idField: "place_id",
+      tableName: "scene_places",
+      resolveEntity: (placeId) => resolvePlaceForProject(db, { placeId, projectId: args.project_id }),
+    });
+  }
+
   async function recordCharacterRelationshipBeat({
     project_id,
     from_character,
@@ -1120,7 +1332,7 @@ export function registerMetadataTools(s, {
               project_id: scene.project_id,
               compatibility: compatibilityRelationships,
               canonical: canonicalRelationships,
-              next_step: "Treat SQLite relationship rows as canonical. Use find_scenes, list_characters, and list_places to inspect stable IDs; use connect_character_place_evidence for paired sheet-backed evidence or leave character-only/place-only repairs to a deliberately named future workflow.",
+              next_step: "Treat SQLite relationship rows as canonical. Use find_scenes, list_characters, and list_places to inspect stable IDs; use connect_character_place_evidence when evidence is paired, connect_scene_character_evidence for character-only evidence, and connect_scene_place_evidence for place-only evidence.",
             });
           }
         }
@@ -1213,7 +1425,7 @@ export function registerMetadataTools(s, {
         compatibility_note_count: diagnostics.filter(diagnostic => diagnostic.severity === "info").length,
       },
       next_steps: [
-        "Use connect_character_place_evidence for scene-backed character/place relationships.",
+        "Use connect_character_place_evidence when scene-backed character/place evidence is paired; use connect_scene_character_evidence or connect_scene_place_evidence for one-sided scene evidence.",
         "Use record_character_relationship_beat for relationship arcs between characters.",
         "Use link_reference_evidence for explicit reference evidence.",
         "Use export_project_backup when a fresh recovery snapshot is needed.",
@@ -1440,7 +1652,7 @@ export function registerMetadataTools(s, {
   // ---- connect_character_place_evidence ------------------------------------
   s.tool(
     "connect_character_place_evidence",
-    "Connect a character and place as scene-backed story evidence. This is the outcome-level workflow for character/place association: SQLite scene relationship indexes commit first, project backups refresh after commit, and scene sidecar characters/places are refreshed only as generated compatibility output.",
+    "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.",
     {
       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."),
@@ -1451,6 +1663,32 @@ export function registerMetadataTools(s, {
     async (args) => connectCharacterPlaceEvidence(args)
   );
 
+  // ---- 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.",
+    {
+      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."),
+      note: z.string().optional().describe("Optional review note explaining the evidence. Stored in operation history, not in compatibility sidecars."),
+    },
+    async (args) => connectSceneCharacterEvidence(args)
+  );
+
+  // ---- 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.",
+    {
+      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."),
+      note: z.string().optional().describe("Optional review note explaining the evidence. Stored in operation history, not in compatibility sidecars."),
+    },
+    async (args) => connectScenePlaceEvidence(args)
+  );
+
   // ---- record_character_relationship_beat ----------------------------------
   s.tool(
     "record_character_relationship_beat",
@@ -1470,7 +1708,7 @@ export function registerMetadataTools(s, {
   // ---- audit_relationship_metadata -----------------------------------------
   s.tool(
     "audit_relationship_metadata",
-    "Review relationship metadata authority, stale indexes, and retained compatibility notes without mutating SQLite or files. Use this before repair work when character/place associations, sidecar tags, scene threads, or recovery readiness look stale or ambiguous.",
+    "Review relationship metadata authority, stale indexes, retained compatibility notes, and scene character/place sidecar drift without mutating SQLite or files. Use this before repair work when character/place associations, sidecar tags, scene threads, or recovery readiness look stale or ambiguous.",
     {
       project_id: z.string().optional().describe("Optional project scope for the audit."),
     },
@@ -2344,7 +2582,7 @@ export function registerMetadataTools(s, {
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",
-    "Update one or more non-structural, non-relationship metadata fields for a scene. Writes only supplied allowed fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose, mirrors path-derived structure, or changes scene character/place relationship authority. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Relationship fields (characters, places) are rejected here; use discovery workflows plus connect_character_place_evidence for paired sheet-backed character/place evidence, and audit_relationship_metadata for legacy sidecar/frontmatter relationship review. Allowed changes are immediately reflected in the index. Only available when the sync dir is writable.",
+    "Update one or more non-structural, non-relationship metadata fields for a scene. Writes only supplied allowed fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose, mirrors path-derived structure, or changes scene character/place relationship authority. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Relationship fields (characters, places) are rejected here; use discovery workflows plus connect_character_place_evidence when evidence is paired, connect_scene_character_evidence for character-only evidence, connect_scene_place_evidence for place-only evidence, and audit_relationship_metadata for legacy sidecar/frontmatter relationship review. Allowed changes are immediately reflected in the index. Only available when the sync dir is writable.",
     {
       scene_id:   z.string().describe("The scene_id to update (e.g. 'sc-011-sebastian')."),
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
@@ -2361,8 +2599,8 @@ export function registerMetadataTools(s, {
         timeline_position: z.number().int().optional().describe("Rejected by update_scene_metadata. Use move_scene for ordering changes."),
         story_time:        z.string().optional(),
         tags:              z.array(z.string()).optional(),
-        characters:        z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence for paired sheet-backed evidence, and audit_relationship_metadata for compatibility review."),
-        places:            z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence for paired sheet-backed evidence, and audit_relationship_metadata for compatibility review."),
+        characters:        z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence when evidence is paired, connect_scene_character_evidence for character-only evidence, and audit_relationship_metadata for compatibility review."),
+        places:            z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence when evidence is paired, connect_scene_place_evidence for place-only evidence, and audit_relationship_metadata for compatibility review."),
       }).describe("Fields to update. Only supplied keys are changed."),
     },
     async ({ scene_id, project_id, fields }) => {
@@ -2607,7 +2845,7 @@ export function registerMetadataTools(s, {
   // ---- update_place_sheet --------------------------------------------------
   s.tool(
     "update_place_sheet",
-    "Update canonical place profile fields and retained compatibility notes. The place name commits to SQLite first and refreshes project backups; associated_characters and tags are compatibility/review metadata only. For current character/place relationship authority, use connect_character_place_evidence.",
+    "Update canonical place profile fields and retained compatibility notes. The place name commits to SQLite first and refreshes project backups; associated_characters and tags are compatibility/review metadata only. Use connect_character_place_evidence when scene-backed character/place evidence is paired, or connect_scene_place_evidence when scene evidence is place-only.",
     {
       place_id: z.string().describe("The place_id to update (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
       fields: z.object({
@@ -2716,7 +2954,7 @@ export function registerMetadataTools(s, {
         }),
         non_canonical_fields: ["associated_characters", "tags"].filter(field => Object.hasOwn(fields, field)),
         next_step: Object.hasOwn(fields, "associated_characters")
-          ? "Use connect_character_place_evidence to make scene-backed character/place associations authoritative."
+          ? "Use connect_character_place_evidence when paired scene-backed character/place evidence should become authoritative; use connect_scene_character_evidence or connect_scene_place_evidence for one-sided scene evidence."
           : undefined,
         ...backupMutationFields(backupResult),
       });

package/src/tools/search.js

@@ -609,7 +609,7 @@ export function registerSearchTools(s, {
   // ---- get_place_sheet -----------------------------------------------------
   s.tool(
     "get_place_sheet",
-    "Get full place details, including canonical sheet content plus retained sidecar associated_characters and tags as compatibility/review notes. Use connect_character_place_evidence for current scene-backed character/place authority. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
+    "Get full place details, including canonical sheet content plus retained sidecar associated_characters and tags as compatibility/review notes. Use connect_character_place_evidence when scene-backed character/place evidence is paired, or connect_scene_place_evidence when scene evidence is place-only. Response shape note: returns a structured envelope (`results`, `total_count`) with one result row.",
     {
       place_id: z.string().describe("The place_id to look up (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
     },

package/src/workflows/workflow-catalogue.js

@@ -68,12 +68,14 @@ export const WORKFLOW_CATALOGUE = [
     label: "Track and repair story relationships",
     use_when: "Use when the user wants to track an arc, link evidence, review stale relationships, repair metadata parity, or prepare generated recovery material for relationship metadata.",
     steps: [
-      { tool: "find_scenes", note: "Identify scene_id and project_id from story context before recording relationships." },
+      { tool: "find_scenes", note: "Identify scene_id and project_id from story context before recording relationships; use list_characters and list_places when stable entity IDs need disambiguation." },
       { tool: "track_thread_arc", note: "Use when a scene should carry a storyline, subplot, setup, escalation, reveal, reversal, payoff, or other thread beat." },
-      { tool: "connect_character_place_evidence", note: "Use when a scene proves a character/place association; SQLite scene relationship indexes commit first and sidecar characters/places remain generated compatibility output." },
+      { tool: "connect_character_place_evidence", note: "Use when a scene proves paired sheet-backed character/place evidence; SQLite scene relationship indexes commit first and sidecar characters/places remain generated compatibility output." },
+      { tool: "connect_scene_character_evidence", note: "Use when a scene proves sheet-backed character evidence without a specific place association; SQLite scene character links commit first and sidecar characters/places remain generated compatibility output." },
+      { tool: "connect_scene_place_evidence", note: "Use when a scene proves sheet-backed place evidence without a specific character association; SQLite scene place links commit first and sidecar characters/places remain generated compatibility output." },
       { tool: "record_character_relationship_beat", note: "Use when a scene proves a relationship beat between two characters without exposing the character_relationships table." },
       { tool: "link_reference_evidence", note: "Use when scene, character, place, or reference evidence should point to a reference document; SQLite commits first and compatibility output is generated transparency." },
-      { tool: "audit_relationship_metadata", note: "Use before repair work to review stale relationship indexes and sidecar-only compatibility notes without mutating canonical state." },
+      { tool: "audit_relationship_metadata", note: "Use before repair work to review stale relationship indexes, retained sidecar/frontmatter characters or places, and compatibility drift without mutating canonical state." },
       { tool: "suggest_scene_references", note: "Use preview first to review candidate scene-reference links from character/place evidence; use apply only after the relationship outcome is intended." },
       { tool: "enrich_scene_characters_batch", note: "Use dry_run first when prose-derived character relationship parity needs repair across multiple scenes; apply mode syncs SQLite after compatibility output and refreshes backups for changed scenes." },
       { tool: "diagnose_project_backups", note: "Relationship mutation tools refresh project backups after canonical commits; run this if backup_warnings were returned or recovery readiness matters." },
@@ -101,9 +103,11 @@ export const WORKFLOW_CATALOGUE = [
     steps: [
       { tool: "sync", note: "Refresh SQLite indexes from current compatibility inputs, then review warnings instead of patching sidecars as the first repair step." },
       { tool: "diagnose_structure", note: "Use when sidecar, frontmatter, folder, chapter, epigraph, or generated-export structure appears to disagree with SQLite canonical state." },
-      { tool: "audit_relationship_metadata", note: "Use when sidecar threads, tags, flags, associated_characters, characters, places, or reference aliases need authority classification before repair." },
+      { tool: "audit_relationship_metadata", note: "Use when sidecar threads, tags, flags, associated_characters, characters, places, or reference aliases need authority classification before repair; relationship fields are compatibility input/review evidence, not generic metadata writes." },
       { tool: "track_thread_arc", note: "Use for current thread authority instead of editing sidecar threads." },
-      { tool: "connect_character_place_evidence", note: "Use for current scene-backed character/place authority instead of editing sidecar relationship lists." },
+      { tool: "connect_character_place_evidence", note: "Use for paired scene-backed character/place evidence instead of editing sidecar relationship lists or sending characters/places through update_scene_metadata." },
+      { tool: "connect_scene_character_evidence", note: "Use for character-only scene evidence instead of editing sidecar characters or sending characters through update_scene_metadata." },
+      { tool: "connect_scene_place_evidence", note: "Use for place-only scene evidence instead of editing sidecar places or sending places through update_scene_metadata." },
       { tool: "link_reference_evidence", note: "Use for current reference-link authority instead of editing sidecar/frontmatter aliases." },
       { tool: "export_project_backup", note: "Generate a recovery snapshot from SQLite canonical state after meaningful canonical migration or repair work; editing backup artifacts does not mutate current state." },
     ],