@hanna84/mcp-writing 3.12.0 → 3.13.0

package/CHANGELOG.md

@@ -4,9 +4,16 @@ 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.13.0](https://github.com/hannasdev/mcp-writing/compare/v3.12.0...v3.13.0)
+
+- feat(structure): add explicit M7 mutation commands [`#205`](https://github.com/hannasdev/mcp-writing/pull/205)
+
 #### [v3.12.0](https://github.com/hannasdev/mcp-writing/compare/v3.11.0...v3.12.0)
 
+> 18 May 2026
+
 - feat(structure): normalize chapter compatibility resolution [`#204`](https://github.com/hannasdev/mcp-writing/pull/204)
+- Release 3.12.0 [`6f9c540`](https://github.com/hannasdev/mcp-writing/commit/6f9c540e66eef75a224841a9768b485ed9a26557)
 
 #### [v3.11.0](https://github.com/hannasdev/mcp-writing/compare/v3.10.0...v3.11.0)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.12.0",
+  "version": "3.13.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/chapter-commands.js

@@ -0,0 +1,512 @@
+import { slugifyChapterValue } from "./structure-inference.js";
+
+export function deriveCanonicalChapterId({ chapterId, sortIndex, title }) {
+  if (chapterId) return chapterId;
+  const slug = slugifyChapterValue(title) || `chapter-${sortIndex}`;
+  return `ch-${String(sortIndex).padStart(2, "0")}-${slug}`;
+}
+
+export function buildCreateChapterPlan(db, {
+  projectId,
+  title,
+  sortIndex,
+  chapterId,
+  logline = null,
+  updatedAt = new Date().toISOString(),
+}) {
+  const normalizedTitle = typeof title === "string" ? title.trim() : "";
+  const normalizedChapterId = typeof chapterId === "string" ? chapterId.trim() : null;
+  const normalizedLogline = typeof logline === "string" && logline.trim() ? logline.trim() : null;
+
+  if (!normalizedTitle) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a non-empty chapter title.",
+      },
+    };
+  }
+
+  if (!Number.isInteger(sortIndex) || sortIndex < 1) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "sort_index must be a positive integer.",
+        details: { sort_index: sortIndex },
+      },
+    };
+  }
+
+  const project = db.prepare(`
+    SELECT project_id
+    FROM projects
+    WHERE project_id = ?
+  `).get(projectId);
+  if (!project) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_FOUND",
+        message: `Project '${projectId}' not found.`,
+        details: { project_id: projectId },
+      },
+    };
+  }
+
+  const resolvedChapterId = deriveCanonicalChapterId({
+    chapterId: normalizedChapterId,
+    sortIndex,
+    title: normalizedTitle,
+  });
+
+  const existingById = db.prepare(`
+    SELECT chapter_id, title, sort_index
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, resolvedChapterId);
+  if (existingById) {
+    return {
+      ok: false,
+      error: {
+        code: "ALREADY_EXISTS",
+        message: `Chapter '${resolvedChapterId}' already exists in project '${projectId}'.`,
+        details: {
+          project_id: projectId,
+          chapter_id: resolvedChapterId,
+          existing_title: existingById.title,
+          existing_sort_index: existingById.sort_index,
+        },
+      },
+    };
+  }
+
+  const existingBySortIndex = db.prepare(`
+    SELECT chapter_id, title, sort_index
+    FROM chapters
+    WHERE project_id = ? AND sort_index = ?
+  `).get(projectId, sortIndex);
+  if (existingBySortIndex) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Chapter sort_index ${sortIndex} is already used in project '${projectId}'.`,
+        details: {
+          project_id: projectId,
+          sort_index: sortIndex,
+          existing_chapter_id: existingBySortIndex.chapter_id,
+          existing_title: existingBySortIndex.title,
+          next_step: "Use list_chapters to choose an unused sort_index, or wait for reorder_chapter when changing existing order.",
+        },
+      },
+    };
+  }
+
+  const existingByTitle = db.prepare(`
+    SELECT chapter_id, title, sort_index
+    FROM chapters
+    WHERE project_id = ? AND title = ?
+  `).get(projectId, normalizedTitle);
+  if (existingByTitle) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Chapter title '${normalizedTitle}' is already used in project '${projectId}'.`,
+        details: {
+          project_id: projectId,
+          title: normalizedTitle,
+          existing_chapter_id: existingByTitle.chapter_id,
+          existing_sort_index: existingByTitle.sort_index,
+          next_step: "Use a distinct title, or wait for rename_chapter when changing an existing chapter title.",
+        },
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    chapter: {
+      chapter_id: resolvedChapterId,
+      project_id: projectId,
+      title: normalizedTitle,
+      sort_index: sortIndex,
+      logline: normalizedLogline,
+      source_path: null,
+      source_checksum: null,
+      metadata_stale: 0,
+      updated_at: updatedAt,
+    },
+    diagnostics: [
+      {
+        code: "REPRESENTATION_DEFERRED",
+        severity: "info",
+        message: "Created canonical chapter state only; no scene files, sidecars, or Scrivener-compatible folders were generated.",
+        next_step: "Use assign_scene_to_chapter to place unchaptered scenes in this chapter, then run diagnose_structure if folder-derived structure may disagree.",
+      },
+    ],
+  };
+}
+
+export function buildRenameChapterPlan(db, {
+  projectId,
+  chapterId,
+  title,
+  updatedAt = new Date().toISOString(),
+}) {
+  const normalizedTitle = typeof title === "string" ? title.trim() : "";
+
+  if (!normalizedTitle) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a non-empty chapter title.",
+      },
+    };
+  }
+
+  const chapter = db.prepare(`
+    SELECT chapter_id, project_id, title, sort_index, logline, source_path, source_checksum, metadata_stale
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, chapterId);
+  if (!chapter) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_FOUND",
+        message: `Chapter '${chapterId}' not found in project '${projectId}'.`,
+        details: { project_id: projectId, chapter_id: chapterId },
+      },
+    };
+  }
+
+  const existingByTitle = db.prepare(`
+    SELECT chapter_id, title, sort_index
+    FROM chapters
+    WHERE project_id = ? AND title = ? AND chapter_id != ?
+  `).get(projectId, normalizedTitle, chapterId);
+  if (existingByTitle) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Chapter title '${normalizedTitle}' is already used in project '${projectId}'.`,
+        details: {
+          project_id: projectId,
+          title: normalizedTitle,
+          existing_chapter_id: existingByTitle.chapter_id,
+          existing_sort_index: existingByTitle.sort_index,
+        },
+      },
+    };
+  }
+
+  const diagnostics = [];
+  if (chapter.source_path) {
+    diagnostics.push({
+      code: "REPRESENTATION_NOT_RENAMED",
+      severity: "warning",
+      message: "Renamed canonical chapter state and explicit scene compatibility fields only; the existing chapter source folder was not renamed.",
+      next_step: "Run diagnose_structure after sync if folder-derived structure still reports the old title.",
+      details: {
+        source_path: chapter.source_path,
+      },
+    });
+  }
+
+  return {
+    ok: true,
+    previousChapter: chapter,
+    chapter: {
+      ...chapter,
+      title: normalizedTitle,
+      updated_at: updatedAt,
+    },
+    diagnostics,
+  };
+}
+
+export function buildReorderChapterPlan(db, {
+  projectId,
+  chapterId,
+  sortIndex,
+  updatedAt = new Date().toISOString(),
+}) {
+  if (!Number.isInteger(sortIndex) || sortIndex < 1) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "sort_index must be a positive integer.",
+        details: { sort_index: sortIndex },
+      },
+    };
+  }
+
+  const chapter = db.prepare(`
+    SELECT chapter_id, project_id, title, sort_index, logline, source_path, source_checksum, metadata_stale
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, chapterId);
+  if (!chapter) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_FOUND",
+        message: `Chapter '${chapterId}' not found in project '${projectId}'.`,
+        details: { project_id: projectId, chapter_id: chapterId },
+      },
+    };
+  }
+
+  const existingBySortIndex = db.prepare(`
+    SELECT chapter_id, title, sort_index
+    FROM chapters
+    WHERE project_id = ? AND sort_index = ? AND chapter_id != ?
+  `).get(projectId, sortIndex, chapterId);
+  if (existingBySortIndex) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Chapter sort_index ${sortIndex} is already used in project '${projectId}'.`,
+        details: {
+          project_id: projectId,
+          sort_index: sortIndex,
+          existing_chapter_id: existingBySortIndex.chapter_id,
+          existing_title: existingBySortIndex.title,
+          next_step: "Choose an unused sort_index. Automatic resequencing is not part of this command yet.",
+        },
+      },
+    };
+  }
+
+  const diagnostics = [];
+  if (chapter.source_path) {
+    diagnostics.push({
+      code: "REPRESENTATION_NOT_REORDERED",
+      severity: "warning",
+      message: "Reordered canonical chapter state and explicit scene compatibility fields only; the existing chapter source folder was not renamed or moved.",
+      next_step: "Run diagnose_structure after sync if folder-derived structure still reports the old order.",
+      details: {
+        source_path: chapter.source_path,
+      },
+    });
+  }
+
+  return {
+    ok: true,
+    previousChapter: chapter,
+    chapter: {
+      ...chapter,
+      sort_index: sortIndex,
+      updated_at: updatedAt,
+    },
+    diagnostics,
+  };
+}
+
+export function buildAttachEpigraphPlan(db, {
+  projectId,
+  epigraphId,
+  chapterId,
+  updatedAt = new Date().toISOString(),
+}) {
+  const normalizedEpigraphId = typeof epigraphId === "string" ? epigraphId.trim() : "";
+  const normalizedChapterId = typeof chapterId === "string" ? chapterId.trim() : "";
+
+  if (!normalizedEpigraphId) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a non-empty epigraph_id.",
+      },
+    };
+  }
+
+  if (!normalizedChapterId) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide a non-empty chapter_id.",
+      },
+    };
+  }
+
+  const chapter = db.prepare(`
+    SELECT chapter_id, project_id, title, sort_index, logline, source_path, source_checksum, metadata_stale
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, normalizedChapterId);
+  if (!chapter) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_FOUND",
+        message: `Chapter '${normalizedChapterId}' not found in project '${projectId}'.`,
+        details: { project_id: projectId, chapter_id: normalizedChapterId },
+      },
+    };
+  }
+
+  const epigraph = db.prepare(`
+    SELECT epigraph_id, project_id, chapter_id, body, file_path, prose_checksum, metadata_stale
+    FROM epigraphs
+    WHERE project_id = ? AND epigraph_id = ?
+  `).get(projectId, normalizedEpigraphId);
+  if (!epigraph) {
+    return {
+      ok: false,
+      error: {
+        code: "NOT_FOUND",
+        message: `Epigraph '${normalizedEpigraphId}' not found in project '${projectId}'.`,
+        details: { project_id: projectId, epigraph_id: normalizedEpigraphId },
+      },
+    };
+  }
+
+  const existingForChapter = db.prepare(`
+    SELECT epigraph_id, chapter_id
+    FROM epigraphs
+    WHERE project_id = ? AND chapter_id = ? AND epigraph_id != ?
+  `).get(projectId, normalizedChapterId, normalizedEpigraphId);
+  if (existingForChapter) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: `Chapter '${normalizedChapterId}' already has epigraph '${existingForChapter.epigraph_id}'.`,
+        details: {
+          project_id: projectId,
+          chapter_id: normalizedChapterId,
+          epigraph_id: normalizedEpigraphId,
+          existing_epigraph_id: existingForChapter.epigraph_id,
+          next_step: "Use find_epigraphs to inspect the current chapter epigraph before reattaching another one.",
+        },
+      },
+    };
+  }
+
+  const previousChapter = db.prepare(`
+    SELECT chapter_id, title, sort_index
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, epigraph.chapter_id);
+
+  const diagnostics = [];
+  if (epigraph.file_path) {
+    diagnostics.push({
+      code: "REPRESENTATION_NOT_MOVED",
+      severity: "warning",
+      message: "Attached canonical epigraph state and explicit epigraph sidecar fields only; the existing epigraph source file was not moved.",
+      next_step: "Run diagnose_structure after sync if folder-derived structure still reports the previous chapter.",
+      details: {
+        file_path: epigraph.file_path,
+      },
+    });
+  }
+
+  return {
+    ok: true,
+    previousChapter,
+    chapter,
+    epigraph: {
+      ...epigraph,
+      chapter_id: normalizedChapterId,
+      updated_at: updatedAt,
+    },
+    diagnostics,
+  };
+}
+
+export function insertCanonicalChapter(db, chapter) {
+  db.prepare(`
+    INSERT INTO chapters (
+      chapter_id, project_id, title, sort_index, logline, source_path, source_checksum, metadata_stale, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    chapter.chapter_id,
+    chapter.project_id,
+    chapter.title,
+    chapter.sort_index,
+    chapter.logline,
+    chapter.source_path,
+    chapter.source_checksum,
+    chapter.metadata_stale,
+    chapter.updated_at
+  );
+}
+
+export function renameCanonicalChapter(db, chapter) {
+  db.prepare(`
+    UPDATE chapters
+    SET title = ?,
+        updated_at = ?
+    WHERE project_id = ? AND chapter_id = ?
+  `).run(
+    chapter.title,
+    chapter.updated_at,
+    chapter.project_id,
+    chapter.chapter_id
+  );
+
+  db.prepare(`
+    UPDATE scenes
+    SET chapter_title = ?,
+        updated_at = ?
+    WHERE project_id = ? AND chapter_id = ?
+  `).run(
+    chapter.title,
+    chapter.updated_at,
+    chapter.project_id,
+    chapter.chapter_id
+  );
+}
+
+export function attachCanonicalEpigraph(db, epigraph) {
+  db.prepare(`
+    UPDATE epigraphs
+    SET chapter_id = ?,
+        updated_at = ?
+    WHERE project_id = ? AND epigraph_id = ?
+  `).run(
+    epigraph.chapter_id,
+    epigraph.updated_at,
+    epigraph.project_id,
+    epigraph.epigraph_id
+  );
+}
+
+export function reorderCanonicalChapter(db, chapter) {
+  db.prepare(`
+    UPDATE chapters
+    SET sort_index = ?,
+        updated_at = ?
+    WHERE project_id = ? AND chapter_id = ?
+  `).run(
+    chapter.sort_index,
+    chapter.updated_at,
+    chapter.project_id,
+    chapter.chapter_id
+  );
+
+  db.prepare(`
+    UPDATE scenes
+    SET chapter = ?,
+        chapter_title = ?,
+        updated_at = ?
+    WHERE project_id = ? AND chapter_id = ?
+  `).run(
+    chapter.sort_index,
+    chapter.title,
+    chapter.updated_at,
+    chapter.project_id,
+    chapter.chapter_id
+  );
+}

package/src/structure/scene-chapter-assignment.js

@@ -1,5 +1,14 @@
 import { applySceneStructurePatch } from "./structure-inference.js";
 
+function buildAssignedChapterPayload({ chapterId, sortIndex, title }) {
+  if (!chapterId) return null;
+  return {
+    chapter_id: chapterId,
+    sort_index: sortIndex ?? null,
+    title: title ?? null,
+  };
+}
+
 export function buildSceneChapterAssignmentPlan(syncDir, filePath, meta = {}, { chapter } = {}) {
   if (chapter === undefined) {
     return {
@@ -75,3 +84,64 @@ export function buildSceneChapterAssignmentPlan(syncDir, filePath, meta = {}, {
     previousChapterId: meta.chapter_id ?? null,
   };
 }
+
+export function buildMoveScenePlan(syncDir, filePath, meta = {}, {
+  currentScene,
+  chapter,
+  timelinePosition,
+} = {}) {
+  if (chapter === undefined && timelinePosition === undefined) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "Provide chapter_id and/or timeline_position for move_scene.",
+      },
+    };
+  }
+
+  if (timelinePosition !== undefined && (!Number.isInteger(timelinePosition) || timelinePosition < 1)) {
+    return {
+      ok: false,
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "timeline_position must be a positive integer.",
+        details: { timeline_position: timelinePosition },
+      },
+    };
+  }
+
+  const assignmentPlan = chapter === undefined
+    ? {
+      ok: true,
+      meta,
+      assignedChapter: buildAssignedChapterPayload({
+        chapterId: meta.chapter_id ?? currentScene?.chapter_id ?? null,
+        sortIndex: meta.chapter ?? currentScene?.chapter ?? null,
+        title: meta.chapter_title ?? currentScene?.chapter_title ?? null,
+      }),
+      previousChapterId: meta.chapter_id ?? currentScene?.chapter_id ?? null,
+    }
+    : buildSceneChapterAssignmentPlan(syncDir, filePath, meta, { chapter });
+
+  if (!assignmentPlan.ok) return assignmentPlan;
+
+  const shouldCarryIndexedTimelinePosition = timelinePosition === undefined
+    && chapter !== undefined
+    && meta.timeline_position === undefined
+    && currentScene?.timeline_position != null;
+  const movedMeta = {
+    ...assignmentPlan.meta,
+    ...(shouldCarryIndexedTimelinePosition ? { timeline_position: currentScene.timeline_position } : {}),
+    ...(timelinePosition !== undefined ? { timeline_position: timelinePosition } : {}),
+  };
+
+  return {
+    ok: true,
+    meta: movedMeta,
+    assignedChapter: assignmentPlan.assignedChapter,
+    previousChapterId: assignmentPlan.previousChapterId ?? currentScene?.chapter_id ?? null,
+    previousTimelinePosition: meta.timeline_position ?? currentScene?.timeline_position ?? null,
+    timelinePosition: movedMeta.timeline_position ?? null,
+  };
+}

package/src/tools/metadata.js

@@ -4,7 +4,17 @@ 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 { buildMoveScenePlan, buildSceneChapterAssignmentPlan } from "../structure/scene-chapter-assignment.js";
+import {
+  buildCreateChapterPlan,
+  buildRenameChapterPlan,
+  buildReorderChapterPlan,
+  buildAttachEpigraphPlan,
+  insertCanonicalChapter,
+  renameCanonicalChapter,
+  reorderCanonicalChapter,
+  attachCanonicalEpigraph,
+} from "../structure/chapter-commands.js";
 import {
   persistSceneReferenceLink,
   upsertExplicitReferenceLinkRow,
@@ -81,6 +91,41 @@ function persistPlaceReferenceLink({ placePath, syncDir, targetDocId, relation }
   writeMeta(placePath, nextMeta);
 }
 
+function writeStructureSidecarUpdates(updates, { failureCode }) {
+  const failures = [];
+  let updatedCount = 0;
+
+  for (const update of updates) {
+    try {
+      writeMeta(update.filePath, update.meta);
+      updatedCount += 1;
+    } catch (err) {
+      failures.push({
+        file_path: update.filePath,
+        message: err.message,
+      });
+    }
+  }
+
+  return {
+    updatedCount,
+    diagnostics: failures.length
+      ? [
+        {
+          code: failureCode,
+          severity: "warning",
+          message: "Canonical structure was updated, but one or more explicit sidecar compatibility updates failed.",
+          next_step: "Inspect the failed sidecar paths, then run sync and diagnose_structure before making more structure changes.",
+          details: {
+            failed_sidecar_count: failures.length,
+            failures,
+          },
+        },
+      ]
+      : [],
+  };
+}
+
 function resolveProjectScopedSource({
   db,
   errorResponse,
@@ -511,6 +556,541 @@ export function registerMetadataTools(s, {
     }
   );
 
+  // ---- create_chapter ------------------------------------------------------
+  s.tool(
+    "create_chapter",
+    "Create a canonical chapter record through the explicit structure workflow. Writes canonical chapter state only; it does not create scene files, sidecars, or Scrivener-compatible folders. Use assign_scene_to_chapter afterward to place unchaptered scenes in the new chapter.",
+    {
+      project_id: z.string().describe("Project the chapter belongs to (e.g. 'the-lamb')."),
+      title: z.string().describe("Human-readable chapter title."),
+      sort_index: z.number().int().min(1).describe("Canonical chapter order within the project. Must be unused."),
+      chapter_id: z.string().optional().describe("Optional canonical chapter identifier. If omitted, one is derived from sort_index and title."),
+      logline: z.string().optional().describe("Optional chapter-level logline."),
+    },
+    async ({ project_id, title, sort_index, chapter_id, logline }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot create chapter: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      const plan = buildCreateChapterPlan(db, {
+        projectId: project_id,
+        title,
+        sortIndex: sort_index,
+        chapterId: chapter_id,
+        logline,
+      });
+      if (!plan.ok) {
+        return errorResponse(plan.error.code, plan.error.message, {
+          project_id,
+          title,
+          sort_index,
+          chapter_id: chapter_id ?? null,
+          ...(plan.error.details ?? {}),
+        });
+      }
+
+      try {
+        db.exec("BEGIN");
+        insertCanonicalChapter(db, plan.chapter);
+        db.exec("COMMIT");
+      } catch (err) {
+        try {
+          db.exec("ROLLBACK");
+        } catch (rollbackErr) {
+          void rollbackErr;
+        }
+        return errorResponse("IO_ERROR", `Failed to create chapter '${plan.chapter.chapter_id}': ${err.message}`);
+      }
+
+      return jsonResponse({
+        ok: true,
+        action: "created",
+        chapter: {
+          chapter_id: plan.chapter.chapter_id,
+          project_id: plan.chapter.project_id,
+          title: plan.chapter.title,
+          sort_index: plan.chapter.sort_index,
+          logline: plan.chapter.logline,
+          metadata_stale: plan.chapter.metadata_stale,
+        },
+        diagnostics: plan.diagnostics,
+        next_steps: [
+          "Use assign_scene_to_chapter to place unchaptered scenes in this chapter.",
+          "Run diagnose_structure if existing folders or sidecars may imply conflicting structure.",
+        ],
+      });
+    }
+  );
+
+  // ---- rename_chapter ------------------------------------------------------
+  s.tool(
+    "rename_chapter",
+    "Rename a canonical chapter through the explicit structure workflow. Updates canonical chapter state and explicit scene chapter_title compatibility fields; it does not rename scene files, sidecars by path-derived structure, or Scrivener-compatible folders.",
+    {
+      project_id: z.string().describe("Project the chapter belongs to (e.g. 'the-lamb')."),
+      chapter_id: z.string().describe("Canonical chapter identifier. Use list_chapters to find valid values."),
+      title: z.string().describe("New human-readable chapter title."),
+    },
+    async ({ project_id, chapter_id, title }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot rename chapter: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      const plan = buildRenameChapterPlan(db, {
+        projectId: project_id,
+        chapterId: chapter_id,
+        title,
+      });
+      if (!plan.ok) {
+        return errorResponse(plan.error.code, plan.error.message, {
+          project_id,
+          chapter_id,
+          title,
+          ...(plan.error.details ?? {}),
+        });
+      }
+
+      const linkedScenes = db.prepare(`
+        SELECT scene_id, project_id, file_path
+        FROM scenes
+        WHERE project_id = ? AND chapter_id = ?
+        ORDER BY scene_id
+      `).all(project_id, chapter_id);
+
+      const sidecarUpdates = [];
+      try {
+        for (const scene of linkedScenes) {
+          const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
+          if (meta.chapter_id === chapter_id) {
+            sidecarUpdates.push({
+              scene,
+              filePath: scene.file_path,
+              meta: {
+                ...meta,
+                chapter_title: plan.chapter.title,
+              },
+            });
+          }
+        }
+
+        db.exec("BEGIN");
+        renameCanonicalChapter(db, plan.chapter);
+        db.exec("COMMIT");
+      } catch (err) {
+        try {
+          db.exec("ROLLBACK");
+        } catch (rollbackErr) {
+          void rollbackErr;
+        }
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Cannot rename chapter '${chapter_id}': an indexed scene file is missing. Run sync() to refresh.`, {
+            project_id,
+            chapter_id,
+          });
+        }
+        return errorResponse("IO_ERROR", `Failed to rename chapter '${chapter_id}': ${err.message}`);
+      }
+
+      const sidecarWriteResult = writeStructureSidecarUpdates(sidecarUpdates, {
+        failureCode: "SCENE_SIDECAR_UPDATE_FAILED",
+      });
+
+      return jsonResponse({
+        ok: true,
+        action: "renamed",
+        chapter: {
+          chapter_id: plan.chapter.chapter_id,
+          project_id: plan.chapter.project_id,
+          title: plan.chapter.title,
+          sort_index: plan.chapter.sort_index,
+          logline: plan.chapter.logline,
+          metadata_stale: plan.chapter.metadata_stale,
+        },
+        previous_title: plan.previousChapter.title,
+        updated_scene_count: linkedScenes.length,
+        updated_sidecar_count: sidecarWriteResult.updatedCount,
+        diagnostics: [
+          ...plan.diagnostics,
+          ...sidecarWriteResult.diagnostics,
+        ],
+        next_steps: [
+          "Use list_chapters to confirm the canonical title.",
+          "Run diagnose_structure if folder-derived structure may still use the previous chapter title.",
+        ],
+      });
+    }
+  );
+
+  // ---- reorder_chapter -----------------------------------------------------
+  s.tool(
+    "reorder_chapter",
+    "Reorder a canonical chapter through the explicit structure workflow. Updates canonical chapter order and explicit scene chapter/chapter_title compatibility fields; it does not rename, move, or resequence scene files, sidecars by path-derived structure, or Scrivener-compatible folders.",
+    {
+      project_id: z.string().describe("Project the chapter belongs to (e.g. 'the-lamb')."),
+      chapter_id: z.string().describe("Canonical chapter identifier. Use list_chapters to find valid values."),
+      sort_index: z.number().int().min(1).describe("New canonical chapter order within the project. Must be unused."),
+    },
+    async ({ project_id, chapter_id, sort_index }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot reorder chapter: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      const plan = buildReorderChapterPlan(db, {
+        projectId: project_id,
+        chapterId: chapter_id,
+        sortIndex: sort_index,
+      });
+      if (!plan.ok) {
+        return errorResponse(plan.error.code, plan.error.message, {
+          project_id,
+          chapter_id,
+          sort_index,
+          ...(plan.error.details ?? {}),
+        });
+      }
+
+      const linkedScenes = db.prepare(`
+        SELECT scene_id, project_id, file_path
+        FROM scenes
+        WHERE project_id = ? AND chapter_id = ?
+        ORDER BY scene_id
+      `).all(project_id, chapter_id);
+
+      const sidecarUpdates = [];
+      try {
+        for (const scene of linkedScenes) {
+          const { meta } = readMeta(scene.file_path, SYNC_DIR, { writable: true });
+          if (meta.chapter_id === chapter_id) {
+            sidecarUpdates.push({
+              scene,
+              filePath: scene.file_path,
+              meta: {
+                ...meta,
+                chapter: plan.chapter.sort_index,
+                chapter_title: plan.chapter.title,
+              },
+            });
+          }
+        }
+
+        db.exec("BEGIN");
+        reorderCanonicalChapter(db, plan.chapter);
+        db.exec("COMMIT");
+      } catch (err) {
+        try {
+          db.exec("ROLLBACK");
+        } catch (rollbackErr) {
+          void rollbackErr;
+        }
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Cannot reorder chapter '${chapter_id}': an indexed scene file is missing. Run sync() to refresh.`, {
+            project_id,
+            chapter_id,
+          });
+        }
+        return errorResponse("IO_ERROR", `Failed to reorder chapter '${chapter_id}': ${err.message}`);
+      }
+
+      const sidecarWriteResult = writeStructureSidecarUpdates(sidecarUpdates, {
+        failureCode: "SCENE_SIDECAR_UPDATE_FAILED",
+      });
+
+      return jsonResponse({
+        ok: true,
+        action: "reordered",
+        chapter: {
+          chapter_id: plan.chapter.chapter_id,
+          project_id: plan.chapter.project_id,
+          title: plan.chapter.title,
+          sort_index: plan.chapter.sort_index,
+          logline: plan.chapter.logline,
+          metadata_stale: plan.chapter.metadata_stale,
+        },
+        previous_sort_index: plan.previousChapter.sort_index,
+        updated_scene_count: linkedScenes.length,
+        updated_sidecar_count: sidecarWriteResult.updatedCount,
+        diagnostics: [
+          ...plan.diagnostics,
+          ...sidecarWriteResult.diagnostics,
+        ],
+        next_steps: [
+          "Use list_chapters to confirm canonical order.",
+          "Run diagnose_structure if folder-derived structure may still use the previous order.",
+        ],
+      });
+    }
+  );
+
+  // ---- attach_epigraph -----------------------------------------------------
+  s.tool(
+    "attach_epigraph",
+    "Attach an existing canonical epigraph to a canonical chapter through the explicit structure workflow. Updates canonical epigraph linkage and explicit epigraph sidecar fields; it does not move, rename, or create epigraph source files or Scrivener-compatible folders.",
+    {
+      project_id: z.string().describe("Project the epigraph belongs to (e.g. 'the-lamb')."),
+      epigraph_id: z.string().describe("Canonical epigraph identifier. Use find_epigraphs to find valid values."),
+      chapter_id: z.string().describe("Canonical chapter identifier. Use list_chapters to find valid values."),
+    },
+    async ({ project_id, epigraph_id, chapter_id }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot attach epigraph: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      const plan = buildAttachEpigraphPlan(db, {
+        projectId: project_id,
+        epigraphId: epigraph_id,
+        chapterId: chapter_id,
+      });
+      if (!plan.ok) {
+        return errorResponse(plan.error.code, plan.error.message, {
+          project_id,
+          epigraph_id,
+          chapter_id,
+          ...(plan.error.details ?? {}),
+        });
+      }
+
+      try {
+        const { meta } = readMeta(plan.epigraph.file_path, SYNC_DIR, { writable: true });
+        const sidecarUpdate = {
+          filePath: plan.epigraph.file_path,
+          meta: {
+            ...meta,
+            kind: meta.kind ?? "epigraph",
+            epigraph_id: plan.epigraph.epigraph_id,
+            chapter_id: plan.chapter.chapter_id,
+            chapter: plan.chapter.sort_index,
+            chapter_title: plan.chapter.title,
+          },
+        };
+
+        db.exec("BEGIN");
+        attachCanonicalEpigraph(db, plan.epigraph);
+        db.exec("COMMIT");
+
+        const sidecarWriteResult = writeStructureSidecarUpdates([sidecarUpdate], {
+          failureCode: "EPIGRAPH_SIDECAR_UPDATE_FAILED",
+        });
+
+        return jsonResponse({
+          ok: true,
+          action: "attached",
+          epigraph: {
+            epigraph_id: plan.epigraph.epigraph_id,
+            project_id: plan.epigraph.project_id,
+            chapter_id: plan.epigraph.chapter_id,
+            metadata_stale: plan.epigraph.metadata_stale,
+          },
+          chapter: {
+            chapter_id: plan.chapter.chapter_id,
+            title: plan.chapter.title,
+            sort_index: plan.chapter.sort_index,
+          },
+          previous_chapter: plan.previousChapter
+            ? {
+              chapter_id: plan.previousChapter.chapter_id,
+              title: plan.previousChapter.title,
+              sort_index: plan.previousChapter.sort_index,
+            }
+            : null,
+          updated_sidecar_count: sidecarWriteResult.updatedCount,
+          diagnostics: [
+            ...plan.diagnostics,
+            ...sidecarWriteResult.diagnostics,
+          ],
+          next_steps: [
+            "Use find_epigraphs to confirm the canonical epigraph attachment.",
+            "Run diagnose_structure if folder-derived structure may still imply the previous chapter.",
+          ],
+        });
+      } catch (err) {
+        try {
+          db.exec("ROLLBACK");
+        } catch (rollbackErr) {
+          void rollbackErr;
+        }
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Cannot attach epigraph '${epigraph_id}': the indexed epigraph file is missing. Run sync() to refresh.`, {
+            project_id,
+            epigraph_id,
+            chapter_id,
+          });
+        }
+        return errorResponse("IO_ERROR", `Failed to attach epigraph '${epigraph_id}': ${err.message}`);
+      }
+    }
+  );
+
+  // ---- move_scene ----------------------------------------------------------
+  s.tool(
+    "move_scene",
+    "Move a scene through the explicit structure workflow. Updates canonical chapter linkage and/or timeline_position in the scene sidecar and index; it does not move, rename, or resequence scene files or Scrivener-compatible folders.",
+    {
+      scene_id: z.string().describe("The scene_id to move (e.g. 'sc-011-sebastian')."),
+      project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
+      chapter_id: z.string().optional().describe("Optional canonical chapter identifier. Use list_chapters to find valid values. Omit to keep the current chapter."),
+      timeline_position: z.number().int().min(1).optional().describe("Optional new position within the target chapter. Must be unused."),
+    },
+    async ({ scene_id, project_id, chapter_id, timeline_position }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot move scene: sync dir is read-only.");
+      }
+
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      if (chapter_id === undefined && timeline_position === undefined) {
+        return errorResponse("VALIDATION_ERROR", "Provide chapter_id and/or timeline_position for move_scene.", {
+          project_id,
+          scene_id,
+        });
+      }
+
+      const scene = db.prepare(`
+        SELECT scene_id, project_id, chapter_id, chapter, chapter_title, timeline_position, 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 = undefined;
+      if (chapter_id !== undefined) {
+        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 = buildMoveScenePlan(SYNC_DIR, scene.file_path, meta, {
+          currentScene: scene,
+          chapter,
+          timelinePosition: timeline_position,
+        });
+        if (!plan.ok) {
+          return errorResponse(plan.error.code, plan.error.message, {
+            project_id,
+            scene_id,
+            chapter_id: chapter_id ?? null,
+            timeline_position: timeline_position ?? null,
+            ...(plan.error.details ?? {}),
+          });
+        }
+
+        const targetChapterId = plan.meta.chapter_id ?? null;
+        const effectiveTimelinePosition = plan.timelinePosition;
+        const targetChapterChanged = chapter_id !== undefined
+          && (plan.previousChapterId ?? null) !== targetChapterId;
+        if (effectiveTimelinePosition != null && (timeline_position !== undefined || targetChapterChanged)) {
+          const positionConflict = targetChapterId === null
+            ? db.prepare(`
+              SELECT scene_id
+              FROM scenes
+              WHERE project_id = ? AND chapter_id IS NULL AND timeline_position = ? AND scene_id != ?
+              ORDER BY scene_id
+              LIMIT 1
+            `).get(project_id, effectiveTimelinePosition, scene_id)
+            : db.prepare(`
+              SELECT scene_id
+              FROM scenes
+              WHERE project_id = ? AND chapter_id = ? AND timeline_position = ? AND scene_id != ?
+              ORDER BY scene_id
+              LIMIT 1
+            `).get(project_id, targetChapterId, effectiveTimelinePosition, scene_id);
+
+          if (positionConflict) {
+            return errorResponse("VALIDATION_ERROR", `timeline_position ${effectiveTimelinePosition} is already used in the target chapter.`, {
+              project_id,
+              scene_id,
+              chapter_id: targetChapterId,
+              timeline_position: effectiveTimelinePosition,
+              existing_scene_id: positionConflict.scene_id,
+              next_step: "Choose an unused timeline_position. Automatic resequencing is not part of this command yet.",
+            });
+          }
+        }
+
+        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: "moved",
+          scene_id,
+          project_id,
+          previous_chapter_id: plan.previousChapterId,
+          previous_timeline_position: plan.previousTimelinePosition,
+          chapter: plan.assignedChapter,
+          timeline_position: plan.timelinePosition,
+          diagnostics: [
+            {
+              code: "REPRESENTATION_NOT_MOVED",
+              severity: "warning",
+              message: "Moved canonical scene structure fields only; the existing scene source file was not moved or renamed.",
+              next_step: "Run diagnose_structure if folder-derived structure may still imply the previous placement.",
+              details: {
+                file_path: scene.file_path,
+              },
+            },
+          ],
+          next_steps: [
+            "Use find_scenes to confirm the scene's canonical chapter and timeline_position.",
+            "Run diagnose_structure if folder-derived structure may still imply the previous placement.",
+          ],
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path. Run sync() to refresh.`, {
+            indexed_path: scene.file_path,
+          });
+        }
+        return errorResponse("IO_ERROR", `Failed to move scene '${scene_id}': ${err.message}`);
+      }
+    }
+  );
+
   // ---- assign_scene_to_chapter --------------------------------------------
   s.tool(
     "assign_scene_to_chapter",

package/src/workflows/workflow-catalogue.js

@@ -77,11 +77,16 @@ export const WORKFLOW_CATALOGUE = [
   },
   {
     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.",
+    label: "Manage chapter structure",
+    use_when: "Use when the user wants to create, rename, or reorder a canonical chapter, attach an epigraph to a chapter, move a scene into a canonical chapter or position, 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: "list_chapters", note: "Inspect existing canonical chapters before creating or assigning chapter structure." },
+      { tool: "create_chapter", note: "Use when the intended canonical chapter does not exist yet; this creates chapter state only and does not generate folders or scene files." },
+      { tool: "rename_chapter", note: "Use when the canonical chapter title should change; this does not rename folders or generated representation paths." },
+      { tool: "reorder_chapter", note: "Use when the canonical chapter order should change to an unused sort_index; this does not rename folders or generated representation paths." },
+      { tool: "attach_epigraph", note: "Use when an existing canonical epigraph should belong to a different canonical chapter; this does not move the epigraph source file." },
+      { tool: "move_scene", note: "Use when a scene should move to another canonical chapter and/or unused timeline_position; this does not move the scene source file." },
       { 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." },
     ],