@hanna84/mcp-writing 3.10.0 → 3.12.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.12.0](https://github.com/hannasdev/mcp-writing/compare/v3.11.0...v3.12.0)
+
+- feat(structure): normalize chapter compatibility resolution [`#204`](https://github.com/hannasdev/mcp-writing/pull/204)
+
+#### [v3.11.0](https://github.com/hannasdev/mcp-writing/compare/v3.10.0...v3.11.0)
+
+> 18 May 2026
+
+- feat(structure): add explicit scene chapter assignment [`#203`](https://github.com/hannasdev/mcp-writing/pull/203)
+- Release 3.11.0 [`7e73355`](https://github.com/hannasdev/mcp-writing/commit/7e73355bb4bb38845daf90e0d438e3c7e3c9c268)
+
 #### [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)
 

package/package.json

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

package/src/core/chapter-resolution.js

@@ -1,29 +1,85 @@
-export function resolveChapterByCompatibilityKey(db, { projectId, chapterNumber, chapterId }) {
-  if (!projectId) return null;
-  if (chapterId) {
-    return db.prepare(`
-      SELECT chapter_id, project_id, title, sort_index, logline, metadata_stale
-      FROM chapters
-      WHERE project_id = ? AND chapter_id = ?
-    `).get(projectId, chapterId);
-  }
-  if (chapterNumber == null) return null;
+function chapterNotFoundError({ chapterNumber, chapterId }) {
+  return {
+    code: "NOT_FOUND",
+    message: "Chapter not found for the provided project and identifier.",
+    details: {
+      chapter: chapterNumber ?? null,
+      chapter_id: chapterId ?? null,
+    },
+  };
+}
+
+function ambiguousChapterError({ projectId, chapterNumber, candidates }) {
+  return {
+    code: "AMBIGUOUS_CHAPTER",
+    message: `Compatibility chapter ${chapterNumber} resolves to multiple canonical chapter identities in project '${projectId}'. Use chapter_id instead.`,
+    details: {
+      project_id: projectId,
+      chapter: chapterNumber,
+      candidate_chapter_ids: candidates.map(row => row.chapter_id),
+    },
+  };
+}
+
+function selectCanonicalChapterById(db, { projectId, chapterId }) {
+  return db.prepare(`
+    SELECT chapter_id, project_id, title, sort_index, logline, metadata_stale
+    FROM chapters
+    WHERE project_id = ? AND chapter_id = ?
+  `).get(projectId, chapterId);
+}
 
-  const canonicalChapter = db.prepare(`
+function selectCanonicalChaptersByNumber(db, { projectId, chapterNumber }) {
+  return db.prepare(`
     SELECT chapter_id, project_id, title, sort_index, logline, metadata_stale
     FROM chapters
     WHERE project_id = ? AND sort_index = ?
-  `).get(projectId, chapterNumber);
-  if (canonicalChapter) return canonicalChapter;
+    ORDER BY chapter_id
+  `).all(projectId, chapterNumber);
+}
 
+function selectSceneDerivedChaptersByNumber(db, { projectId, chapterNumber }) {
   return db.prepare(`
-    SELECT chapter_id, project_id, chapter_title AS title, chapter AS sort_index, NULL AS logline, MAX(metadata_stale) AS metadata_stale
+    SELECT
+      chapter_id,
+      project_id,
+      COALESCE(MAX(chapter_title), chapter_id) AS title,
+      chapter AS sort_index,
+      NULL AS logline,
+      MAX(metadata_stale) AS metadata_stale
     FROM scenes
-    WHERE project_id = ? AND chapter = ? AND chapter_id IS NOT NULL
-    GROUP BY chapter_id, project_id, chapter_title, chapter
+    WHERE project_id = ?
+      AND chapter = ?
+      AND chapter_id IS NOT NULL
+      AND chapter_id != ''
+    GROUP BY chapter_id, project_id, chapter
     ORDER BY chapter_id
-    LIMIT 1
-  `).get(projectId, chapterNumber);
+  `).all(projectId, chapterNumber);
+}
+
+export function resolveChapterByCompatibilityKey(db, { projectId, chapterNumber, chapterId }) {
+  const result = resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterNumber, chapterId });
+  return result?.chapter ?? null;
+}
+
+export function resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterNumber, chapterId }) {
+  if (!projectId) return { chapter: null };
+  if (chapterId) {
+    return { chapter: selectCanonicalChapterById(db, { projectId, chapterId }) ?? null };
+  }
+  if (chapterNumber == null) return { chapter: null };
+
+  const canonicalChapters = selectCanonicalChaptersByNumber(db, { projectId, chapterNumber });
+  if (canonicalChapters.length > 1) {
+    return { error: ambiguousChapterError({ projectId, chapterNumber, candidates: canonicalChapters }) };
+  }
+  if (canonicalChapters.length === 1) return { chapter: canonicalChapters[0] };
+
+  const sceneDerivedChapters = selectSceneDerivedChaptersByNumber(db, { projectId, chapterNumber });
+  if (sceneDerivedChapters.length > 1) {
+    return { error: ambiguousChapterError({ projectId, chapterNumber, candidates: sceneDerivedChapters }) };
+  }
+  return { chapter: sceneDerivedChapters[0] ?? null };
 }
 
 export function resolveValidatedChapterFilter(db, { projectId, chapterNumber, chapterId }) {
@@ -31,31 +87,103 @@ export function resolveValidatedChapterFilter(db, { projectId, chapterNumber, ch
   if (!chapterId && chapterNumber == null) return { chapter: null };
 
   const resolvedById = chapterId
-    ? resolveChapterByCompatibilityKey(db, { projectId, chapterId })
+    ? resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterId })
     : null;
   const resolvedByNumber = chapterNumber != null
-    ? resolveChapterByCompatibilityKey(db, { projectId, chapterNumber })
+    ? resolveChapterByCompatibilityKeyDetailed(db, { projectId, chapterNumber })
     : null;
 
+  if (resolvedById?.error) return { error: resolvedById.error };
+  if (resolvedByNumber?.error) return { error: resolvedByNumber.error };
+
+  if (chapterId && !resolvedById?.chapter) {
+    return { error: chapterNotFoundError({ chapterNumber, chapterId }) };
+  }
+  if (chapterNumber != null && !resolvedByNumber?.chapter) {
+    return { error: chapterNotFoundError({ chapterNumber, chapterId }) };
+  }
+
   if (chapterId && chapterNumber != null) {
-    if (!resolvedById || !resolvedByNumber) {
+    if (resolvedById.chapter.chapter_id !== resolvedByNumber.chapter.chapter_id) {
       return {
         error: {
-          code: "NOT_FOUND",
-          message: "Chapter not found for the provided project and identifier.",
+          code: "VALIDATION_ERROR",
+          message: "chapter_id and chapter must refer to the same canonical chapter when both are provided.",
+          details: {
+            chapter_id: resolvedById.chapter.chapter_id,
+            chapter: chapterNumber,
+            resolved_chapter_id: resolvedByNumber.chapter.chapter_id,
+          },
         },
       };
     }
-    if (resolvedById.chapter_id !== resolvedByNumber.chapter_id) {
+    return { chapter: resolvedById.chapter };
+  }
+
+  return { chapter: resolvedById?.chapter ?? resolvedByNumber?.chapter ?? null };
+}
+
+export function resolveValidatedChapterNumberFilters(db, { projectId, chapterNumbers }) {
+  if (!projectId || chapterNumbers == null) return { chapters: [] };
+  const invalidChapterNumbers = chapterNumbers.filter(value => !Number.isInteger(value));
+  if (invalidChapterNumbers.length > 0) {
+    return {
+      error: {
+        code: "VALIDATION_ERROR",
+        message: "chapters must contain only integer chapter numbers.",
+        details: {
+          project_id: projectId,
+          invalid_chapters: invalidChapterNumbers,
+          requested_chapters: chapterNumbers,
+        },
+      },
+    };
+  }
+  const normalizedChapterNumbers = Array.from(new Set(chapterNumbers)).sort((a, b) => a - b);
+  const chapters = [];
+  const seenChapterIds = new Set();
+
+  for (const chapterNumber of normalizedChapterNumbers) {
+    const resolved = resolveValidatedChapterFilter(db, {
+      projectId,
+      chapterNumber,
+    });
+
+    if (resolved.error) {
       return {
         error: {
-          code: "VALIDATION_ERROR",
-          message: "chapter_id and chapter must refer to the same canonical chapter when both are provided.",
+          ...resolved.error,
+          details: {
+            ...(resolved.error.details ?? {}),
+            project_id: projectId,
+            requested_chapters: normalizedChapterNumbers,
+          },
         },
       };
     }
-    return { chapter: resolvedById };
+
+    if (!resolved.chapter) {
+      return {
+        error: {
+          code: "NOT_FOUND",
+          message: "Chapter not found for the provided project and identifier.",
+          details: {
+            project_id: projectId,
+            chapter: chapterNumber,
+            requested_chapters: normalizedChapterNumbers,
+          },
+        },
+      };
+    }
+
+    if (!seenChapterIds.has(resolved.chapter.chapter_id)) {
+      chapters.push(resolved.chapter);
+      seenChapterIds.add(resolved.chapter.chapter_id);
+    }
   }
 
-  return { chapter: resolvedById ?? resolvedByNumber ?? null };
+  return {
+    chapters,
+    chapter_numbers: normalizedChapterNumbers,
+  };
 }

package/src/core/helpers.js

@@ -156,12 +156,6 @@ export function resolveBatchTargetScenes(dbHandle, {
   if (resolvedChapterFilter.chapter) {
     conditions.push("chapter_id = ?");
     params.push(resolvedChapterFilter.chapter.chapter_id);
-  } else if (chapterId !== undefined) {
-    conditions.push("chapter_id = ?");
-    params.push(chapterId);
-  } else if (chapter !== undefined) {
-    conditions.push("chapter = ?");
-    params.push(chapter);
   }
   if (onlyStale) {
     conditions.push("metadata_stale = 1");

package/src/review-bundles/review-bundles-planner.js

@@ -1,3 +1,8 @@
+import {
+  resolveValidatedChapterFilter,
+  resolveValidatedChapterNumberFilters,
+} from "../core/chapter-resolution.js";
+
 const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
 const MAX_SCENE_ID_FILTER_PARAMS = 900;
 const MAX_CHAPTER_FILTER_PARAMS = 900;
@@ -33,7 +38,7 @@ function sceneSort(a, b) {
   const partDiff = normalizeSortNumber(a.part) - normalizeSortNumber(b.part);
   if (partDiff !== 0) return partDiff;
 
-  const chapterDiff = normalizeSortNumber(a.chapter) - normalizeSortNumber(b.chapter);
+  const chapterDiff = normalizeSortNumber(a.canonical_chapter_sort ?? a.chapter) - normalizeSortNumber(b.canonical_chapter_sort ?? b.chapter);
   if (chapterDiff !== 0) return chapterDiff;
 
   const timelineDiff = normalizeSortNumber(a.timeline_position) - normalizeSortNumber(b.timeline_position);
@@ -201,6 +206,40 @@ export function buildReviewBundlePlan(dbHandle, {
     throw new ReviewBundlePlanError("NOT_FOUND", `Project '${project_id}' not found.`);
   }
 
+  const resolvedChapterFilter = (chapter !== undefined || chapter_id !== undefined)
+    ? resolveValidatedChapterFilter(dbHandle, {
+        projectId: project_id,
+        chapterNumber: chapter,
+        chapterId: chapter_id,
+      })
+    : { chapter: null };
+  if (resolvedChapterFilter.error) {
+    throw new ReviewBundlePlanError(
+      resolvedChapterFilter.error.code,
+      resolvedChapterFilter.error.message,
+      {
+        ...(resolvedChapterFilter.error.details ?? {}),
+        project_id,
+        chapter: chapter ?? null,
+        chapter_id: chapter_id ?? null,
+      }
+    );
+  }
+
+  const resolvedChapterSet = Array.isArray(normalizedChapters)
+    ? resolveValidatedChapterNumberFilters(dbHandle, {
+        projectId: project_id,
+        chapterNumbers: normalizedChapters,
+      })
+    : { chapters: [] };
+  if (resolvedChapterSet.error) {
+    throw new ReviewBundlePlanError(
+      resolvedChapterSet.error.code,
+      resolvedChapterSet.error.message,
+      resolvedChapterSet.error.details
+    );
+  }
+
   const requestedSceneIds = resolveRequestedSceneIds(dbHandle, project_id, scene_ids);
   const conditions = ["s.project_id = ?"];
   const joins = [];
@@ -220,24 +259,22 @@ export function buildReviewBundlePlan(dbHandle, {
     conditions.push("s.part = ?");
     conditionParams.push(part);
   }
-  if (chapter !== undefined) {
-    conditions.push("s.chapter = ?");
-    conditionParams.push(chapter);
-  }
-  if (chapter_id !== undefined) {
+  if (resolvedChapterFilter.chapter) {
     conditions.push("s.chapter_id = ?");
-    conditionParams.push(chapter_id);
+    conditionParams.push(resolvedChapterFilter.chapter.chapter_id);
   }
-  if (Array.isArray(normalizedChapters) && normalizedChapters.length > 0) {
-    const placeholders = normalizedChapters.map(() => "?").join(",");
-    conditions.push(`s.chapter IN (${placeholders})`);
-    conditionParams.push(...normalizedChapters);
+  if (resolvedChapterSet.chapters.length > 0) {
+    const placeholders = resolvedChapterSet.chapters.map(() => "?").join(",");
+    conditions.push(`s.chapter_id IN (${placeholders})`);
+    conditionParams.push(...resolvedChapterSet.chapters.map(row => row.chapter_id));
   }
 
   let query = `
     SELECT DISTINCT
       s.scene_id,
       s.project_id,
+      s.chapter_id,
+      c.sort_index AS canonical_chapter_sort,
       s.title,
       s.part,
       s.chapter,
@@ -248,6 +285,7 @@ export function buildReviewBundlePlan(dbHandle, {
       s.save_the_cat_beat,
       s.metadata_stale
     FROM scenes s
+    LEFT JOIN chapters c ON c.project_id = s.project_id AND c.chapter_id = s.chapter_id
   `;
 
   if (joins.length > 0) {
@@ -354,6 +392,10 @@ export function buildReviewBundlePlan(dbHandle, {
     ...(chapter !== undefined ? { chapter } : {}),
     ...(chapter_id !== undefined ? { chapter_id } : {}),
     ...(Array.isArray(normalizedChapters) ? { chapters: normalizedChapters } : {}),
+    ...(resolvedChapterFilter.chapter ? { resolved_chapter_id: resolvedChapterFilter.chapter.chapter_id } : {}),
+    ...(resolvedChapterSet.chapters.length > 0
+      ? { resolved_chapter_ids: resolvedChapterSet.chapters.map(row => row.chapter_id) }
+      : {}),
     ...(tag ? { tag } : {}),
     ...(Array.isArray(normalizedSceneIds) ? { scene_ids: normalizedSceneIds } : {}),
   };
@@ -389,9 +431,11 @@ export function buildReviewBundlePlan(dbHandle, {
     ordering: rows.map(row => ({
       scene_id: row.scene_id,
       project_id: row.project_id,
+      chapter_id: row.chapter_id,
       title: row.title,
       part: row.part,
       chapter: row.chapter,
+      canonical_chapter_sort: row.canonical_chapter_sort,
       timeline_position: row.timeline_position,
       metadata_stale: Number(row.metadata_stale) === 1,
     })),

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/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/review-bundles.js

@@ -27,9 +27,9 @@ export function registerReviewBundleTools(s, {
       project_id: z.string().describe("Project ID to scope the review bundle (e.g. 'test-novel')."),
       profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional compatibility chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
-      chapters: z.array(z.number().int()).min(1).optional().describe("Optional chapter-set filter. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
+      chapters: z.array(z.number().int()).min(1).optional().describe("Optional compatibility chapter-set filter resolved through canonical chapter identities. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
       scene_ids: z.array(z.string()).optional().describe("Optional explicit scene_id allowlist. Intersects with other filters."),
       strictness: z.enum(REVIEW_BUNDLE_STRICTNESS).optional().describe("Strictness mode: warn (default) or fail."),
@@ -124,9 +124,9 @@ export function registerReviewBundleTools(s, {
       profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       output_dir: z.string().describe("Directory path to write bundle artifacts into."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional compatibility chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
-      chapters: z.array(z.number().int()).min(1).optional().describe("Optional chapter-set filter. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
+      chapters: z.array(z.number().int()).min(1).optional().describe("Optional compatibility chapter-set filter resolved through canonical chapter identities. Use this for one/few specific chapters. Do not combine with chapter or chapter_id."),
       tag: z.string().optional().describe("Optional tag filter (exact match)."),
       scene_ids: z.array(z.string()).optional().describe("Optional explicit scene_id allowlist. Intersects with other filters."),
       strictness: z.enum(REVIEW_BUNDLE_STRICTNESS).optional().describe("Strictness mode: warn (default) or fail."),

package/src/tools/search.js

@@ -131,8 +131,10 @@ export function registerSearchTools(s, {
       if (resolvedChapterFilter.chapter) {
         conditions.push(`s.chapter_id = ?`);
         params.push(resolvedChapterFilter.chapter.chapter_id);
-      } else if (chapter_id)  { conditions.push(`s.chapter_id = ?`);         params.push(chapter_id); }
-      else if (chapter) { conditions.push(`s.chapter = ?`);           params.push(chapter); }
+      } else if (chapter != null && !project_id) {
+        conditions.push(`s.chapter = ?`);
+        params.push(chapter);
+      }
       if (pov)         { conditions.push(`s.pov = ?`);                params.push(pov); }
 
       if (joins.length)      query += " " + joins.join(" ");

package/src/tools/styleguide.js

@@ -382,7 +382,7 @@ export function registerStyleguideTools(s, {
       project_id: z.string().describe("Project ID to analyze (e.g. 'the-lamb' or 'universe-1/book-1')."),
       scene_ids: z.array(z.string()).optional().describe("Optional scene_id allowlist to analyze."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       max_scenes: z.number().int().positive().optional().describe("Maximum number of scenes to analyze (default: 50)."),
       min_agreement: z.number().min(0).max(1).optional().describe("Minimum agreement ratio for suggested fields (default: 0.6)."),
@@ -632,7 +632,7 @@ export function registerStyleguideTools(s, {
       project_id: z.string().describe("Project ID to analyze (e.g. 'the-lamb' or 'universe-1/book-1')."),
       scene_ids: z.array(z.string()).optional().describe("Optional scene_id allowlist to analyze."),
       part: z.number().int().optional().describe("Optional part filter."),
-      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       max_scenes: z.number().int().positive().optional().describe("Maximum number of scenes to analyze (default: 50)."),
       min_agreement: z.number().min(0).max(1).optional().describe("Minimum agreement ratio for suggested updates (default: 0.6)."),

package/src/tools/sync.js

@@ -355,7 +355,7 @@ export function registerSyncTools(s, {
       project_id: z.string().describe("Project ID (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
       scene_ids: z.array(z.string()).optional().describe("Optional allowlist of scene IDs to process before other filters are applied."),
       part: z.number().int().optional().describe("Optional part number filter."),
-      chapter: z.number().int().optional().describe("Optional chapter number filter."),
+      chapter: z.number().int().optional().describe("Optional compatibility chapter number resolved through canonical chapter identity."),
       chapter_id: z.string().optional().describe("Optional canonical chapter identifier."),
       only_stale: z.boolean().optional().describe("If true, only process scenes currently marked metadata_stale."),
       dry_run: z.boolean().optional().describe("If true (default), returns preview results without writing sidecars."),

package/src/workflows/workflow-catalogue.js

@@ -75,6 +75,17 @@ export const WORKFLOW_CATALOGUE = [
       { 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",