@hanna84/mcp-writing 3.9.5 → 3.11.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.11.0](https://github.com/hannasdev/mcp-writing/compare/v3.10.0...v3.11.0)
+
+- feat(structure): add explicit scene chapter assignment [`#203`](https://github.com/hannasdev/mcp-writing/pull/203)
+
+#### [v3.10.0](https://github.com/hannasdev/mcp-writing/compare/v3.9.5...v3.10.0)
+
+> 18 May 2026
+
+- feat: add read-only structure diagnostics [`#202`](https://github.com/hannasdev/mcp-writing/pull/202)
+- Release 3.10.0 [`d9b1dfb`](https://github.com/hannasdev/mcp-writing/commit/d9b1dfbce6e0391d035725f3c0671253f53ad455)
+
 #### [v3.9.5](https://github.com/hannasdev/mcp-writing/compare/v3.9.4...v3.9.5)
 
+> 18 May 2026
+
 - refactor(sync): complete target architecture M3 [`#201`](https://github.com/hannasdev/mcp-writing/pull/201)
+- Release 3.9.5 [`9cd308a`](https://github.com/hannasdev/mcp-writing/commit/9cd308aa838a7c3992183ee8c0acce53d61f75cd)
 
 #### [v3.9.4](https://github.com/hannasdev/mcp-writing/compare/v3.9.3...v3.9.4)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.9.5",
+  "version": "3.11.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/structure/scene-chapter-assignment.js

@@ -0,0 +1,77 @@
+import { applySceneStructurePatch } from "./structure-inference.js";
+
+export function buildSceneChapterAssignmentPlan(syncDir, filePath, meta = {}, { chapter } = {}) {
+  if (chapter === undefined) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a canonical chapter or null to clear the scene chapter link.",
+      },
+    };
+  }
+
+  const currentStructure = applySceneStructurePatch(syncDir, filePath, meta);
+  const pathChapter = currentStructure.chapterStructure.chapter ?? null;
+  const pathChapterNumber = currentStructure.derived.chapter ?? null;
+
+  if (chapter === null) {
+    if (pathChapter || pathChapterNumber !== null) {
+      return {
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: "chapter_id cannot be cleared for a scene whose file path implies a chapter.",
+          details: {
+            path_chapter: pathChapter?.chapter_id ?? pathChapterNumber,
+          },
+        },
+      };
+    }
+
+    return {
+      ok: true,
+      meta: applySceneStructurePatch(syncDir, filePath, meta, { chapter: null }).meta,
+      assignedChapter: null,
+      previousChapterId: meta.chapter_id ?? null,
+    };
+  }
+
+  if (pathChapter && pathChapter.chapter_id !== chapter.chapter_id) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Cannot assign a scene to a different chapter while its file path implies another canonical chapter.",
+        details: {
+          requested_chapter_id: chapter.chapter_id,
+          requested_chapter: chapter.sort_index,
+          path_chapter: pathChapter.chapter_id,
+          path_chapter_number: pathChapterNumber,
+        },
+      },
+    };
+  }
+
+  if (!pathChapter && pathChapterNumber !== null && pathChapterNumber !== chapter.sort_index) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Cannot assign a scene to a different chapter while its file path implies another compatibility chapter.",
+        details: {
+          requested_chapter_id: chapter.chapter_id,
+          requested_chapter: chapter.sort_index,
+          path_chapter: pathChapterNumber,
+        },
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    meta: applySceneStructurePatch(syncDir, filePath, meta, { chapter }).meta,
+    assignedChapter: chapter,
+    previousChapterId: meta.chapter_id ?? null,
+  };
+}

package/src/structure/structure-diagnostics.js

@@ -0,0 +1,380 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import {
+  inferChapterStructureFromPath,
+  normalizeSceneMetaForPath,
+} from "./structure-inference.js";
+
+function sidecarPath(filePath) {
+  return filePath.replace(/\.(md|txt)$/, ".meta.yaml");
+}
+
+function normalizeRelativePath(syncDir, filePath) {
+  return path.relative(syncDir, filePath).split(path.sep).join("/");
+}
+
+function isPathInsideSyncDir(syncDir, filePath) {
+  const relativePath = path.relative(path.resolve(syncDir), path.resolve(filePath));
+  return relativePath !== "" && !relativePath.startsWith("..") && !path.isAbsolute(relativePath);
+}
+
+function readStructureMetadata(filePath) {
+  const sidecar = sidecarPath(filePath);
+  if (fs.existsSync(sidecar)) {
+    const raw = fs.readFileSync(sidecar, "utf8");
+    return yaml.load(raw) ?? {};
+  }
+
+  const raw = fs.readFileSync(filePath, "utf8");
+  return matter(raw).data ?? {};
+}
+
+function readObservedStructure(syncDir, filePath) {
+  const sourceMeta = readStructureMetadata(filePath);
+  const { meta } = normalizeSceneMetaForPath(syncDir, filePath, sourceMeta);
+  return {
+    meta,
+    chapterStructure: inferChapterStructureFromPath(syncDir, filePath, meta),
+  };
+}
+
+function createDiagnostic(type, message, details = {}, {
+  severity = "warning",
+  nextStep = null,
+} = {}) {
+  return {
+    type,
+    severity,
+    message,
+    details,
+    ...(nextStep ? { next_step: nextStep } : {}),
+  };
+}
+
+function addDiagnostic(diagnostics, type, message, details = {}, options = {}) {
+  diagnostics.push(createDiagnostic(type, message, details, options));
+}
+
+function countBy(items, key) {
+  const result = {};
+  for (const item of items) {
+    const value = item[key] ?? "unknown";
+    result[value] = (result[value] ?? 0) + 1;
+  }
+  return result;
+}
+
+function projectClause(projectId, alias = "") {
+  const prefix = alias ? `${alias}.` : "";
+  return projectId ? { sql: ` AND ${prefix}project_id = ?`, params: [projectId] } : { sql: "", params: [] };
+}
+
+function readIndexedSceneRows(db, projectId) {
+  const scope = projectClause(projectId);
+  return db.prepare(`
+    SELECT scene_id, project_id, chapter_id, scene_role, chapter, chapter_title, file_path
+    FROM scenes
+    WHERE 1 = 1${scope.sql}
+    ORDER BY project_id, scene_id
+  `).all(...scope.params);
+}
+
+function readIndexedEpigraphRows(db, projectId) {
+  const scope = projectClause(projectId);
+  return db.prepare(`
+    SELECT epigraph_id, project_id, chapter_id, file_path
+    FROM epigraphs
+    WHERE 1 = 1${scope.sql}
+    ORDER BY project_id, epigraph_id
+  `).all(...scope.params);
+}
+
+function diagnoseUnknownChapterLinks(db, diagnostics, projectId) {
+  const sceneScope = projectClause(projectId, "s");
+  const scenes = db.prepare(`
+    SELECT s.scene_id, s.project_id, s.chapter_id, s.file_path
+    FROM scenes s
+    LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
+    WHERE s.chapter_id IS NOT NULL AND s.chapter_id != '' AND c.chapter_id IS NULL${sceneScope.sql}
+    ORDER BY s.project_id, s.scene_id
+  `).all(...sceneScope.params);
+
+  for (const scene of scenes) {
+    addDiagnostic(
+      diagnostics,
+      "scene_unknown_chapter",
+      `Scene "${scene.scene_id}" in project "${scene.project_id}" references unknown chapter_id "${scene.chapter_id}".`,
+      {
+        project_id: scene.project_id,
+        scene_id: scene.scene_id,
+        chapter_id: scene.chapter_id,
+        file_path: scene.file_path,
+      },
+      { nextStep: "Run sync to refresh canonical chapter indexes, then use an explicit structure workflow once available if the link is still invalid." }
+    );
+  }
+
+  const epigraphScope = projectClause(projectId, "e");
+  const epigraphs = db.prepare(`
+    SELECT e.epigraph_id, e.project_id, e.chapter_id, e.file_path
+    FROM epigraphs e
+    LEFT JOIN chapters c ON c.project_id = e.project_id AND c.chapter_id = e.chapter_id
+    WHERE c.chapter_id IS NULL${epigraphScope.sql}
+    ORDER BY e.project_id, e.epigraph_id
+  `).all(...epigraphScope.params);
+
+  for (const epigraph of epigraphs) {
+    addDiagnostic(
+      diagnostics,
+      "epigraph_unknown_chapter",
+      `Epigraph "${epigraph.epigraph_id}" in project "${epigraph.project_id}" references unknown chapter_id "${epigraph.chapter_id}".`,
+      {
+        project_id: epigraph.project_id,
+        epigraph_id: epigraph.epigraph_id,
+        chapter_id: epigraph.chapter_id,
+        file_path: epigraph.file_path,
+      },
+      { nextStep: "Check the epigraph file path and chapter sidecar fields before applying any repair." }
+    );
+  }
+}
+
+function diagnoseNumericCompatibility(db, diagnostics, projectId) {
+  const scope = projectClause(projectId, "s");
+  const rows = db.prepare(`
+    SELECT s.scene_id, s.project_id, s.chapter_id, s.chapter, s.chapter_title,
+           c.sort_index, c.title
+    FROM scenes s
+    JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
+    WHERE (
+      (s.chapter IS NOT NULL AND s.chapter != c.sort_index)
+      OR (s.chapter_title IS NOT NULL AND s.chapter_title != c.title)
+    )${scope.sql}
+    ORDER BY s.project_id, s.scene_id
+  `).all(...scope.params);
+
+  for (const row of rows) {
+    addDiagnostic(
+      diagnostics,
+      "numeric_chapter_identity_mismatch",
+      `Scene "${row.scene_id}" compatibility chapter fields disagree with canonical chapter "${row.chapter_id}".`,
+      {
+        project_id: row.project_id,
+        scene_id: row.scene_id,
+        chapter_id: row.chapter_id,
+        scene_chapter: row.chapter,
+        canonical_chapter: row.sort_index,
+        scene_chapter_title: row.chapter_title,
+        canonical_chapter_title: row.title,
+      },
+      { nextStep: "Prefer canonical chapter_id in workflows; update compatibility fields only through sanctioned structure paths." }
+    );
+  }
+}
+
+function diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs }) {
+  const observedChapterFolders = new Map();
+  const roleFolders = new Map();
+
+  for (const scene of scenes) {
+    if (!scene.file_path || !fs.existsSync(scene.file_path)) continue;
+    if (!isPathInsideSyncDir(syncDir, scene.file_path)) {
+      addDiagnostic(
+        diagnostics,
+        "indexed_path_outside_sync_root",
+        `Scene "${scene.scene_id}" has an indexed file path outside the active sync root.`,
+        {
+          project_id: scene.project_id,
+          scene_id: scene.scene_id,
+          file_path: scene.file_path,
+          sync_dir: syncDir,
+        },
+        { nextStep: "Run sync with the current sync root before trusting file-derived structure diagnostics." }
+      );
+      continue;
+    }
+
+    let observed;
+    try {
+      observed = readObservedStructure(syncDir, scene.file_path);
+    } catch (error) {
+      addDiagnostic(
+        diagnostics,
+        "structure_file_read_failed",
+        `Could not read structure metadata for scene "${scene.scene_id}": ${error.message}`,
+        {
+          project_id: scene.project_id,
+          scene_id: scene.scene_id,
+          file_path: scene.file_path,
+        },
+        { severity: "info", nextStep: "Run sync after confirming the file still exists and has readable metadata." }
+      );
+      continue;
+    }
+
+    const chapter = observed.chapterStructure.chapter;
+    if (chapter) {
+      const key = `${scene.project_id}::${chapter.sort_index}`;
+      const existing = observedChapterFolders.get(key) ?? new Set();
+      existing.add(chapter.folder_key);
+      observedChapterFolders.set(key, existing);
+
+      if (scene.chapter_id && scene.chapter_id !== chapter.chapter_id) {
+        addDiagnostic(
+          diagnostics,
+          "folder_canonical_mismatch",
+          `Scene "${scene.scene_id}" is indexed to chapter_id "${scene.chapter_id}" but its folder implies "${chapter.chapter_id}".`,
+          {
+            project_id: scene.project_id,
+            scene_id: scene.scene_id,
+            indexed_chapter_id: scene.chapter_id,
+            observed_chapter_id: chapter.chapter_id,
+            observed_chapter: chapter.sort_index,
+            relative_path: normalizeRelativePath(syncDir, scene.file_path),
+          },
+          { nextStep: "Inspect the file location and sidecar before changing canonical chapter links." }
+        );
+      }
+    }
+
+    if (observed.chapterStructure.role && ["prologue", "epilogue"].includes(observed.chapterStructure.role)) {
+      const key = `${scene.project_id}::${observed.chapterStructure.role}`;
+      const existing = roleFolders.get(key) ?? new Set();
+      existing.add(path.dirname(scene.file_path));
+      roleFolders.set(key, existing);
+    }
+  }
+
+  for (const [key, folders] of observedChapterFolders.entries()) {
+    if (folders.size <= 1) continue;
+    const [projectId, sortIndex] = key.split("::");
+    addDiagnostic(
+      diagnostics,
+      "duplicate_chapter_sort_index",
+      `Project "${projectId}" has multiple observed folders for chapter order ${sortIndex}.`,
+      {
+        project_id: projectId,
+        chapter: Number(sortIndex),
+        folders: [...folders].sort(),
+      },
+      { nextStep: "Resolve the duplicate folder-derived chapter order before relying on canonical structure diagnostics." }
+    );
+  }
+
+  for (const [key, folders] of roleFolders.entries()) {
+    if (folders.size <= 1) continue;
+    const [projectId, role] = key.split("::");
+    addDiagnostic(
+      diagnostics,
+      "multiple_scene_role",
+      `Project "${projectId}" has multiple observed ${role} folders.`,
+      {
+        project_id: projectId,
+        scene_role: role,
+        folders: [...folders].sort().map(folder => normalizeRelativePath(syncDir, folder)),
+      },
+      { nextStep: `Decide which ${role} folder is canonical before running repair or mutation workflows.` }
+    );
+  }
+
+  for (const epigraph of epigraphs) {
+    if (!epigraph.file_path || !fs.existsSync(epigraph.file_path)) continue;
+    if (!isPathInsideSyncDir(syncDir, epigraph.file_path)) {
+      addDiagnostic(
+        diagnostics,
+        "indexed_path_outside_sync_root",
+        `Epigraph "${epigraph.epigraph_id}" has an indexed file path outside the active sync root.`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          file_path: epigraph.file_path,
+          sync_dir: syncDir,
+        },
+        { nextStep: "Run sync with the current sync root before trusting file-derived structure diagnostics." }
+      );
+      continue;
+    }
+
+    let observed;
+    try {
+      observed = readObservedStructure(syncDir, epigraph.file_path);
+    } catch (error) {
+      addDiagnostic(
+        diagnostics,
+        "structure_file_read_failed",
+        `Could not read structure metadata for epigraph "${epigraph.epigraph_id}": ${error.message}`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          file_path: epigraph.file_path,
+        },
+        { severity: "info", nextStep: "Run sync after confirming the epigraph file still exists and has readable metadata." }
+      );
+      continue;
+    }
+
+    const observedChapterId = observed.chapterStructure.chapter?.chapter_id ?? observed.meta.chapter_id ?? null;
+    if (observedChapterId && epigraph.chapter_id !== observedChapterId) {
+      addDiagnostic(
+        diagnostics,
+        "epigraph_chapter_conflict",
+        `Epigraph "${epigraph.epigraph_id}" is indexed to chapter_id "${epigraph.chapter_id}" but its file implies "${observedChapterId}".`,
+        {
+          project_id: epigraph.project_id,
+          epigraph_id: epigraph.epigraph_id,
+          indexed_chapter_id: epigraph.chapter_id,
+          observed_chapter_id: observedChapterId,
+          relative_path: normalizeRelativePath(syncDir, epigraph.file_path),
+        },
+        { nextStep: "Inspect the epigraph sidecar and folder before reassigning it." }
+      );
+    }
+  }
+}
+
+export function runStructureDiagnostics(db, {
+  syncDir,
+  projectId = null,
+} = {}) {
+  const diagnostics = [];
+  const scenes = readIndexedSceneRows(db, projectId);
+  const epigraphs = readIndexedEpigraphRows(db, projectId);
+
+  diagnoseUnknownChapterLinks(db, diagnostics, projectId);
+  diagnoseNumericCompatibility(db, diagnostics, projectId);
+
+  if (syncDir) {
+    diagnoseObservedFiles(syncDir, diagnostics, { scenes, epigraphs });
+  }
+
+  diagnostics.sort((a, b) => {
+    const projectCompare = String(a.details.project_id ?? "").localeCompare(String(b.details.project_id ?? ""));
+    if (projectCompare) return projectCompare;
+    const typeCompare = a.type.localeCompare(b.type);
+    if (typeCompare) return typeCompare;
+    return a.message.localeCompare(b.message);
+  });
+
+  return {
+    ok: diagnostics.length === 0,
+    checked: {
+      project_id: projectId,
+      scenes: scenes.length,
+      epigraphs: epigraphs.length,
+    },
+    summary: {
+      total: diagnostics.length,
+      by_type: countBy(diagnostics, "type"),
+      by_severity: countBy(diagnostics, "severity"),
+    },
+    diagnostics,
+    next_steps: diagnostics.length
+      ? [
+        "Review diagnostics before applying any structure repair.",
+        "Run sync after external file moves, then re-run diagnose_structure to confirm remaining drift.",
+      ]
+      : ["No structure drift detected in the current index."],
+  };
+}

package/src/tools/metadata.js

@@ -4,6 +4,7 @@ import matter from "gray-matter";
 import { readMeta, writeMeta, indexSceneFile, applySceneStructurePatch } from "../sync/sync.js";
 import { validateProjectId, validateUniverseId } from "../sync/importer.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
+import { buildSceneChapterAssignmentPlan } from "../structure/scene-chapter-assignment.js";
 import {
   persistSceneReferenceLink,
   upsertExplicitReferenceLinkRow,
@@ -510,6 +511,92 @@ export function registerMetadataTools(s, {
     }
   );
 
+  // ---- assign_scene_to_chapter --------------------------------------------
+  s.tool(
+    "assign_scene_to_chapter",
+    "Assign a scene to a canonical chapter through the explicit structure workflow. Writes chapter_id plus compatibility chapter/chapter_title fields to the scene sidecar and refreshes the index. Pass chapter_id=null to clear an explicit chapter link on an unchaptered scene. Use list_chapters first to choose a valid canonical chapter_id.",
+    {
+      scene_id: z.string().describe("The scene_id to assign (e.g. 'sc-011-sebastian')."),
+      project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
+      chapter_id: z.string().nullable().describe("Canonical chapter identifier. Use list_chapters to find valid values. Pass null to clear an explicit chapter link on an unchaptered scene."),
+    },
+    async ({ scene_id, project_id, chapter_id }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot assign scene to chapter: 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, chapter_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}'.`);
+      }
+
+      let chapter = null;
+      if (chapter_id !== null) {
+        const resolvedChapterFilter = resolveValidatedChapterFilter(db, {
+          projectId: project_id,
+          chapterId: chapter_id,
+        });
+
+        if (resolvedChapterFilter.error) {
+          return errorResponse(
+            resolvedChapterFilter.error.code,
+            resolvedChapterFilter.error.message,
+            { project_id, chapter_id }
+          );
+        }
+
+        chapter = resolvedChapterFilter.chapter;
+        if (!chapter) {
+          return errorResponse("NOT_FOUND", "Chapter not found for the provided project and identifier.", {
+            project_id,
+            chapter_id,
+          });
+        }
+      }
+
+      try {
+        const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
+        const plan = buildSceneChapterAssignmentPlan(SYNC_DIR, scene.file_path, meta, { chapter });
+        if (!plan.ok) {
+          return errorResponse(plan.error.code, plan.error.message, {
+            project_id,
+            scene_id,
+            chapter_id,
+            ...(plan.error.details ?? {}),
+          });
+        }
+
+        writeMeta(scene.file_path, plan.meta);
+
+        const { content: prose } = matter(fs.readFileSync(scene.file_path, "utf8"));
+        indexSceneFile(db, SYNC_DIR, scene.file_path, plan.meta, prose);
+
+        return jsonResponse({
+          ok: true,
+          action: chapter === null ? "cleared" : "assigned",
+          scene_id,
+          project_id,
+          previous_chapter_id: plan.previousChapterId ?? scene.chapter_id ?? null,
+          chapter: plan.assignedChapter,
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path — the file may have moved. Run sync() to refresh.`, { indexed_path: scene.file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to assign scene '${scene_id}' to chapter: ${err.message}`);
+      }
+    }
+  );
+
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",

package/src/tools/sync.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import matter from "gray-matter";
 import { syncAll, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath } from "../sync/sync.js";
 import { importScrivenerSync, validateProjectId } from "../sync/importer.js";
+import { runStructureDiagnostics } from "../structure/structure-diagnostics.js";
 
 export function registerSyncTools(s, {
   db,
@@ -45,6 +46,27 @@ export function registerSyncTools(s, {
     return { content: [{ type: "text", text: parts.join(" ") }] };
   });
 
+  s.tool(
+    "diagnose_structure",
+    "Run read-only structure diagnostics against the current index and sync files. Reports canonical drift, ambiguous folder-derived structure, unknown chapter links, epigraph conflicts, and compatibility chapter mismatches without repairing files or mutating the database.",
+    {
+      project_id: z.string().optional().describe("Optional project ID to limit diagnostics to one project."),
+    },
+    async ({ project_id } = {}) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      return jsonResponse(runStructureDiagnostics(db, {
+        syncDir: SYNC_DIR,
+        projectId: project_id ?? null,
+      }));
+    }
+  );
+
   s.tool(
     "import_scrivener_sync",
     "[STABLE] Import Scrivener External Folder Sync Draft files into this server's WRITING_SYNC_DIR by generating scene sidecars and reconciling by Scrivener binder ID. This is the recommended default path for first-time setup before sync().",

package/src/workflows/workflow-catalogue.js

@@ -69,11 +69,23 @@ export const WORKFLOW_CATALOGUE = [
     use_when: "Use when new material has been added, sync/import reveals metadata gaps, or normal work touches scenes or documents with weak, stale, or missing metadata support.",
     steps: [
       { tool: "sync", note: "Refresh the index and use the result as the main signal that material has changed or parity may need attention." },
+      { tool: "diagnose_structure", note: "Use when sync warning summaries suggest chapter, epigraph, or folder-derived structure drift that should be understood before repair." },
       { tool: "enrich_scene", note: "Use for lightweight opportunistic recovery when the current task is already touching a specific low-parity scene." },
       { tool: "enrich_scene_characters_batch", note: "Use when recovery scope is broad enough to justify focused catch-up work; prefer dry_run first." },
       { tool: "suggest_scene_references", note: "Use when low parity is specifically about missing scene-to-reference relationships." },
     ],
   },
+  {
+    id: "structure_assignment",
+    label: "Assign a scene to a chapter",
+    use_when: "Use when the user wants to move an unchaptered scene into a canonical chapter, repair an explicit scene chapter link, or clear a scene's explicit chapter assignment.",
+    steps: [
+      { tool: "find_scenes", note: "Identify the target scene and confirm project_id if the user did not provide both." },
+      { tool: "list_chapters", note: "Choose the canonical chapter_id for the target project before assigning." },
+      { tool: "assign_scene_to_chapter", note: "Use this named structure workflow for chapter assignment or clearing instead of editing chapter fields through generic metadata updates." },
+      { tool: "diagnose_structure", note: "Run when the assignment is part of a drift repair workflow or when folder-derived structure may disagree with the requested link." },
+    ],
+  },
   {
     id: "review_preparation",
     label: "Prepare material for human review",
@@ -90,6 +102,7 @@ export const WORKFLOW_CATALOGUE = [
     steps: [
       { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
       { tool: "sync", note: "Index scenes from disk so the main manuscript workflows can operate." },
+      { tool: "diagnose_structure", note: "Run after sync when connecting existing projects to inspect structure drift without repairing anything." },
     ],
   },
   {