@hanna84/mcp-writing 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -4,11 +4,31 @@ 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).
 
+#### [v1.11.2](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.1...v1.11.2)
+
+- Scrivener beta: opt-in chapter organization + raw keyword tags [`#60`](https://github.com/hannasdev/mcp-writing.git
+/pull/60)
+
+#### [v1.11.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.0...v1.11.1)
+
+> 22 April 2026
+
+- Implement graceful batch cancellation and complete Phase D coverage [`#59`](https://github.com/hannasdev/mcp-writing.git
+/pull/59)
+- Release 1.11.1 [`85bb5c6`](https://github.com/hannasdev/mcp-writing.git
+/commit/85bb5c6c3643256eb6866c7b75cc3e3f87ce1412)
+
 #### [v1.11.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.10.0...v1.11.0)
 
+> 21 April 2026
+
 - feat: add reusable manual real-data Scrivener test runner [`#58`](https://github.com/hannasdev/mcp-writing.git
 /pull/58)
+- Release 1.11.0 [`5938d51`](https://github.com/hannasdev/mcp-writing.git
+/commit/5938d51b277dcce2f5fcfe728ff2112d3af644e5)
 
 #### [v1.10.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.9.4...v1.10.0)

package/README.md

@@ -76,5 +76,17 @@ Goal: let AI propose prose edits without losing control of your draft.
 
 Outcome: you get AI speed with explicit approval and recoverable history for every applied change.
 
+### 5) Refreshing scene-character links after imports or major rewrites
+
+Goal: rebuild scene-to-character links in a controlled way after imported prose changes or metadata drift.
+
+1. Start with `enrich_scene_characters_batch` using the default `dry_run=true` to preview inferred links for a project, chapter, or explicit scene list.
+2. Poll `get_async_job_status` until the batch job completes, then review `job.result.results` for changed scenes, ambiguous matches, and partial failures.
+3. Spot-check a few affected scenes with `get_scene_prose` if the changes touch important continuity or cast-heavy chapters.
+4. Re-run `enrich_scene_characters_batch` with `dry_run=false` once the preview looks correct.
+5. If you want a destructive overwrite instead of additive merge behavior, use `replace_mode=replace` with `confirm_replace=true` deliberately.
+
+Outcome: character-link maintenance becomes a preview-first batch operation instead of a one-off regex script or manual sidecar cleanup.
+
 ## License
 AGPL-3.0-only

package/db.js

@@ -18,6 +18,7 @@ export const SCHEMA = `
     title             TEXT,
     part              INTEGER,
     chapter           INTEGER,
+    chapter_title     TEXT,
     pov               TEXT,
     logline           TEXT,
     scene_change      TEXT,
@@ -124,6 +125,11 @@ export function openDb(dbPath) {
   const db = new DatabaseSync(dbPath);
   db.exec(SCHEMA);
 
+  const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
+  if (!sceneColumns.some(column => column.name === "chapter_title")) {
+    db.exec(`ALTER TABLE scenes ADD COLUMN chapter_title TEXT;`);
+  }
+
   // Rebuild legacy FTS table if it predates keyword indexing.
   // Preserve existing indexed rows so metadata search remains available
   // even before the next sync pass repopulates from source files.

package/importer.js

@@ -107,20 +107,35 @@ function loadYamlFile(filePath) {
   }
 }
 
+function walkSidecarFiles(dir, fileList = []) {
+  if (!fs.existsSync(dir)) return fileList;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      // Skip nested mirror trees under scenes/ (e.g. scenes/projects/... or scenes/universes/...)
+      // to avoid accidental reconciliation against duplicated sidecars.
+      if (/^(projects|universes)$/i.test(entry.name)) continue;
+      walkSidecarFiles(full, fileList);
+    } else if (entry.isFile() && entry.name.endsWith(".meta.yaml")) {
+      fileList.push(full);
+    }
+  }
+
+  return fileList;
+}
+
 function buildExistingSceneIndex(dir) {
   const byBinderId = new Map();
   if (!fs.existsSync(dir)) return byBinderId;
 
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile() || !entry.name.endsWith(".meta.yaml")) continue;
-
-    const sidecarPath = path.join(dir, entry.name);
+  for (const sidecarPath of walkSidecarFiles(dir)) {
     const proseCandidates = [
       sidecarPath.replace(/\.meta\.yaml$/, ".txt"),
       sidecarPath.replace(/\.meta\.yaml$/, ".md"),
     ];
     const prosePath = proseCandidates.find(candidate => fs.existsSync(candidate)) ?? null;
-    const proseName = prosePath ? path.basename(prosePath) : entry.name.replace(/\.meta\.yaml$/, ".txt");
+    const proseName = prosePath ? path.basename(prosePath) : path.basename(sidecarPath).replace(/\.meta\.yaml$/, ".txt");
     const parsedName = parseFilename(proseName);
     const meta = loadYamlFile(sidecarPath);
     const binderId = meta.external_source === "scrivener" && meta.external_id
@@ -342,7 +357,12 @@ export function importScrivenerSync({
     const title = cleanTitle(rawTitle);
     const existingScene = existingScenes.get(String(binderId)) ?? null;
     const sceneId = existingScene?.meta?.scene_id ?? makeSceneId(binderId, title);
-    const destFile = path.join(scenesDir, `${seq.toString().padStart(3, "0")} ${rawTitle} [${binderId}].${ext}`);
+    const targetDir = existingScene?.prosePath
+      ? path.dirname(existingScene.prosePath)
+      : existingScene?.sidecarPath
+        ? path.dirname(existingScene.sidecarPath)
+        : scenesDir;
+    const destFile = path.join(targetDir, `${seq.toString().padStart(3, "0")} ${rawTitle} [${binderId}].${ext}`);
     const sidecar = destFile.replace(/\.(txt|md)$/, ".meta.yaml");
 
     const meta = {
@@ -366,6 +386,7 @@ export function importScrivenerSync({
       }
       logger(`        scene_id: ${sceneId}, beat: ${beatCarry ?? "(none)"}`);
     } else {
+      fs.mkdirSync(path.dirname(destFile), { recursive: true });
       fs.copyFileSync(file, destFile);
       fs.writeFileSync(sidecar, yaml.dump(meta, { lineWidth: 120 }), "utf8");
 

package/index.js

@@ -17,6 +17,7 @@ import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, lis
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { importScrivenerSync, validateProjectId } from "./importer.js";
 import { mergeScrivenerProjectMetadata } from "./scrivener-direct.js";
+import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -119,12 +120,14 @@ function toPublicJob(job, includeResult = true) {
     finished_at: job.finishedAt,
     pid: job.pid,
     error: job.error,
+    ...(job.progress ? { progress: job.progress } : {}),
     ...(includeResult ? { result: job.result } : {}),
   };
 }
 
 function startAsyncJob({ kind, requestPayload, onComplete }) {
   pruneAsyncJobs();
+  const progressPrefix = ASYNC_PROGRESS_PREFIX;
 
   const id = randomUUID();
   const tmpPrefix = path.join(os.tmpdir(), "mcp-writing-job-");
@@ -156,14 +159,38 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
     requestPath,
     resultPath,
     result: null,
+    progress: null,
     error: null,
     onComplete,
     child,
   };
   asyncJobs.set(id, job);
 
-  child.stdout.on("data", () => {
-    // worker writes structured output to resultPath; stdout is ignored here
+  let stdoutBuffer = "";
+  child.stdout.on("data", (chunk) => {
+    stdoutBuffer += chunk.toString("utf8");
+    const lines = stdoutBuffer.split("\n");
+    stdoutBuffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith(progressPrefix)) continue;
+      const payload = trimmed.slice(progressPrefix.length);
+      try {
+        const progress = JSON.parse(payload);
+        if (progress && typeof progress === "object") {
+          const nextProgress = {
+            total_scenes: Number(progress.total_scenes ?? 0),
+            processed_scenes: Number(progress.processed_scenes ?? 0),
+            scenes_changed: Number(progress.scenes_changed ?? 0),
+            failed_scenes: Number(progress.failed_scenes ?? 0),
+          };
+          job.progress = nextProgress;
+        }
+      } catch {
+        // Ignore malformed progress lines; they are best-effort telemetry.
+      }
+    }
   });
   child.stderr.on("data", () => {
     // avoid crashing on stderr backpressure for noisy runs
@@ -187,12 +214,32 @@ function startAsyncJob({ kind, requestPayload, onComplete }) {
     const payload = readJsonIfExists(resultPath);
     const successful = payload?.ok === true;
     const cancelledBySignal = signal === "SIGTERM" || signal === "SIGKILL";
+    const cancelledByPayload = payload?.cancelled === true;
 
     job.finishedAt = new Date().toISOString();
     job.result = payload;
 
+    const hasProgressFields = payload && (
+      payload.total_scenes !== undefined
+      || payload.processed_scenes !== undefined
+      || payload.scenes_changed !== undefined
+      || payload.failed_scenes !== undefined
+    );
+
+    if (payload && payload.ok === true && hasProgressFields) {
+      job.progress = {
+        total_scenes: Number(payload.total_scenes ?? job.progress?.total_scenes ?? 0),
+        processed_scenes: Number(payload.processed_scenes ?? job.progress?.processed_scenes ?? 0),
+        scenes_changed: Number(payload.scenes_changed ?? job.progress?.scenes_changed ?? 0),
+        failed_scenes: Number(payload.failed_scenes ?? job.progress?.failed_scenes ?? 0),
+      };
+    }
+
     if (job.status === "cancelling") {
-      if (successful && !cancelledBySignal) {
+      if (cancelledByPayload) {
+        job.status = "cancelled";
+        job.error = "Async job cancelled after returning partial results.";
+      } else if (successful && !cancelledBySignal) {
         // Race: cancellation was requested as work completed successfully.
         job.status = "completed";
       } else {
@@ -379,6 +426,63 @@ function resolveWorldEntityDir({ kind, projectId, universeId, name }) {
   };
 }
 
+function resolveBatchTargetScenes(dbHandle, {
+  projectId,
+  sceneIds,
+  part,
+  chapter,
+  onlyStale,
+}) {
+  const projectExists = Boolean(
+    dbHandle.prepare(`SELECT 1 FROM projects WHERE project_id = ? LIMIT 1`).get(projectId)
+  );
+
+  if (sceneIds?.length) {
+    const placeholders = sceneIds.map(() => "?").join(",");
+    const existingRows = dbHandle.prepare(
+      `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
+    ).all(projectId, ...sceneIds);
+    const existing = new Set(existingRows.map(row => row.scene_id));
+    const missing = sceneIds.filter(sceneId => !existing.has(sceneId));
+    if (missing.length > 0) {
+      return { ok: false, code: "NOT_FOUND", message: `Requested scene IDs were not found in project '${projectId}'.`, details: { missing_scene_ids: missing, project_id: projectId } };
+    }
+  }
+
+  const conditions = ["project_id = ?"];
+  const params = [projectId];
+
+  if (sceneIds?.length) {
+    const placeholders = sceneIds.map(() => "?").join(",");
+    conditions.push(`scene_id IN (${placeholders})`);
+    params.push(...sceneIds);
+  }
+  if (part !== undefined) {
+    conditions.push("part = ?");
+    params.push(part);
+  }
+  if (chapter !== undefined) {
+    conditions.push("chapter = ?");
+    params.push(chapter);
+  }
+  if (onlyStale) {
+    conditions.push("metadata_stale = 1");
+  }
+
+  const query = `
+    SELECT scene_id, project_id, file_path
+    FROM scenes
+    WHERE ${conditions.join(" AND ")}
+    ORDER BY part, chapter, timeline_position
+  `;
+
+  return {
+    ok: true,
+    rows: dbHandle.prepare(query).all(...params),
+    project_exists: projectExists,
+  };
+}
+
 function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId, meta }) {
   const prefix = kind === "character" ? "char" : "place";
   const idKey = kind === "character" ? "character_id" : "place_id";
@@ -671,7 +775,7 @@ function createMcpServer() {
   // ---- import_scrivener_sync ----------------------------------------------
   s.tool(
     "import_scrivener_sync",
-    "Import Scrivener External Folder Sync Draft files into this server's WRITING_SYNC_DIR by generating scene sidecars and reconciling by Scrivener binder ID. Use this for first-time setup before 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().",
     {
       source_dir: z.string().describe("Path to Scrivener external sync folder (the folder that contains Draft/, or Draft/ itself)."),
       project_id: z.string().optional().describe("Project ID override (e.g. 'the-lamb'). Defaults to a slug derived from WRITING_SYNC_DIR."),
@@ -793,15 +897,16 @@ function createMcpServer() {
   // ---- merge_scrivener_project_beta --------------------------------------
   s.tool(
     "merge_scrivener_project_beta",
-    "[BETA] Merge metadata directly from a Scrivener .scriv project into existing scene sidecars. This path is opt-in and may be sensitive to Scrivener internal format changes. Requires scenes sidecars to already exist (for example, from import_scrivener_sync).",
+    "[BETA] Merge metadata directly from a Scrivener .scriv project into existing scene sidecars. This path is opt-in, requires sidecars to already exist (for example, from import_scrivener_sync), and may be sensitive to Scrivener internal format changes.",
     {
       source_project_dir: z.string().describe("Path to a Scrivener .scriv bundle directory."),
       project_id: z.string().optional().describe("Project ID containing existing sidecars (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb'). Defaults to a slug derived from WRITING_SYNC_DIR."),
       scenes_dir: z.string().optional().describe("Absolute path to the scenes directory containing .meta.yaml sidecars. Overrides the path derived from project_id. Use this for non-standard sync layouts."),
       dry_run: z.boolean().optional().describe("If true (default), reports planned merges without writing files."),
       auto_sync: z.boolean().optional().describe("If true (default), runs sync() after a non-dry-run merge."),
+      organize_by_chapters: z.boolean().optional().describe("If true (default false), relocate scene files into chapter-based folder hierarchies (e.g., chapter-7-harbor/). Chapter metadata is always extracted to sidecars regardless of this flag."),
     },
-    async ({ source_project_dir, project_id, scenes_dir, dry_run = true, auto_sync = true }) => {
+    async ({ source_project_dir, project_id, scenes_dir, dry_run = true, auto_sync = true, organize_by_chapters = false }) => {
       if (project_id !== undefined) {
         const projectIdCheck = validateProjectId(project_id);
         if (!projectIdCheck.ok) {
@@ -839,6 +944,7 @@ function createMcpServer() {
           projectId: project_id,
           scenesDir: normalizedScenesDir,
           dryRun: Boolean(dry_run),
+          organizeByChapters: Boolean(organize_by_chapters),
         });
       } catch (error) {
         return errorResponse(
@@ -869,10 +975,14 @@ function createMcpServer() {
           dry_run: mergeResult.dryRun,
           sidecar_files: mergeResult.sidecarFiles,
           updated: mergeResult.updated,
+          relocated: mergeResult.relocated,
           unchanged: mergeResult.unchanged,
           no_data: mergeResult.noData,
           field_add_counts: mergeResult.fieldAddCounts,
           preview_changes: mergeResult.previewChanges,
+          warnings: mergeResult.warnings,
+          warnings_truncated: mergeResult.warningsTruncated,
+          warning_summary: mergeResult.warningSummary,
           stats: {
             sync_map_entries: mergeResult.stats.syncMapEntries,
             keyword_map_entries: mergeResult.stats.keywordMapEntries,
@@ -905,7 +1015,7 @@ function createMcpServer() {
   // ---- async import/merge jobs --------------------------------------------
   s.tool(
     "import_scrivener_sync_async",
-    "Start an asynchronous Scrivener External Folder Sync import job. Returns immediately with a job_id to poll via get_async_job_status.",
+    "[STABLE] Start an asynchronous Scrivener External Folder Sync import job. This is the recommended default import path when the sync tree is large. Returns immediately with a job_id to poll via get_async_job_status.",
     {
       source_dir: z.string().describe("Path to Scrivener external sync folder (the folder that contains Draft/, or Draft/ itself)."),
       project_id: z.string().optional().describe("Project ID override (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
@@ -985,15 +1095,16 @@ function createMcpServer() {
 
   s.tool(
     "merge_scrivener_project_beta_async",
-    "Start an asynchronous beta Scrivener metadata merge job. Returns immediately with a job_id to poll via get_async_job_status.",
+    "[BETA] Start an asynchronous Scrivener metadata merge job from a `.scriv` project into existing scene sidecars. Use this only after the stable import path has created sidecars. Returns immediately with a job_id to poll via get_async_job_status.",
     {
       source_project_dir: z.string().describe("Path to a Scrivener .scriv bundle directory."),
       project_id: z.string().optional().describe("Project ID containing existing sidecars (e.g. 'the-lamb' or 'universe-1/book-1-the-lamb')."),
       scenes_dir: z.string().optional().describe("Absolute path to the scenes directory containing .meta.yaml sidecars. Overrides the path derived from project_id."),
       dry_run: z.boolean().optional().describe("If true (default), reports planned merges without writing files."),
       auto_sync: z.boolean().optional().describe("If true, runs sync() after a non-dry-run async merge finishes."),
+      organize_by_chapters: z.boolean().optional().describe("If true (default false), relocate scene files into chapter-based folder hierarchies. Chapter metadata is always extracted to sidecars."),
     },
-    async ({ source_project_dir, project_id, scenes_dir, dry_run = true, auto_sync = false }) => {
+    async ({ source_project_dir, project_id, scenes_dir, dry_run = true, auto_sync = false, organize_by_chapters = false }) => {
       if (project_id !== undefined) {
         const projectIdCheck = validateProjectId(project_id);
         if (!projectIdCheck.ok) {
@@ -1032,6 +1143,7 @@ function createMcpServer() {
             project_id,
             scenes_dir: normalizedScenesDir,
             dry_run: Boolean(dry_run),
+            organize_by_chapters: Boolean(organize_by_chapters),
           },
           context: {
             sync_dir: SYNC_DIR,
@@ -1062,9 +1174,129 @@ function createMcpServer() {
     }
   );
 
+  s.tool(
+    "enrich_scene_characters_batch",
+    "Start an asynchronous batch job that infers scene character mentions and updates scene metadata links. Version 1 uses canonical character names only (no aliases). Defaults to dry_run=true.",
+    {
+      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."),
+      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."),
+      replace_mode: z.enum(["merge", "replace"]).optional().describe("merge (default): add inferred IDs; replace: overwrite characters with inferred IDs."),
+      max_scenes: z.number().int().positive().optional().describe("Hard guardrail for resolved scene count (default: 200)."),
+      include_match_details: z.boolean().optional().describe("If true, include extra match diagnostics per scene."),
+      confirm_replace: z.boolean().optional().describe("Must be true when replace_mode=replace."),
+    },
+    async ({
+      project_id,
+      scene_ids,
+      part,
+      chapter,
+      only_stale = false,
+      dry_run = true,
+      replace_mode = "merge",
+      max_scenes = 200,
+      include_match_details = false,
+      confirm_replace = false,
+    }) => {
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      if (replace_mode === "replace" && !confirm_replace) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          "replace_mode=replace requires confirm_replace=true.",
+          { replace_mode, confirm_replace }
+        );
+      }
+
+      if (!dry_run && !SYNC_DIR_WRITABLE) {
+        return errorResponse(
+          "READ_ONLY",
+          "Cannot run batch character enrichment in write mode: sync dir is read-only.",
+          { sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      const characterRows = db.prepare(`
+        SELECT character_id, name
+        FROM characters
+        WHERE project_id = ? OR universe_id = (SELECT universe_id FROM projects WHERE project_id = ?)
+        ORDER BY length(name) DESC
+      `).all(project_id, project_id);
+
+      const targetResolution = resolveBatchTargetScenes(db, {
+        projectId: project_id,
+        sceneIds: scene_ids,
+        part,
+        chapter,
+        onlyStale: Boolean(only_stale),
+      });
+      if (!targetResolution.ok) {
+        return errorResponse(targetResolution.code, targetResolution.message, targetResolution.details);
+      }
+
+      const targetScenes = targetResolution.rows;
+      const projectExists = targetResolution.project_exists !== false;
+      if (targetScenes.length > max_scenes) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          `Matched ${targetScenes.length} scenes, which exceeds max_scenes=${max_scenes}.`,
+          {
+            matched_scenes: targetScenes.length,
+            max_scenes,
+            project_id,
+          }
+        );
+      }
+
+      const job = startAsyncJob({
+        kind: "enrich_scene_characters_batch",
+        requestPayload: {
+          kind: "enrich_scene_characters_batch",
+          args: {
+            project_id,
+            dry_run: Boolean(dry_run),
+            replace_mode,
+            include_match_details: Boolean(include_match_details),
+            project_exists: projectExists,
+            target_scenes: targetScenes,
+            character_rows: characterRows,
+          },
+          context: { sync_dir: SYNC_DIR },
+        },
+        onComplete: (completedJob) => {
+          if (dry_run || completedJob.status !== "completed" || !completedJob.result?.ok) return;
+
+          syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+
+          const changedScenes = (completedJob.result.results ?? [])
+            .filter(row => row.status === "changed")
+            .map(row => row.scene_id);
+
+          for (const sceneId of changedScenes) {
+            db.prepare(`UPDATE scenes SET metadata_stale = 0 WHERE scene_id = ? AND project_id = ?`)
+              .run(sceneId, project_id);
+          }
+        },
+      });
+
+      return jsonResponse({
+        ok: true,
+        async: true,
+        job: toPublicJob(job, false),
+        next_step: "Call get_async_job_status with job_id until status is 'completed', 'failed', or 'cancelled'.",
+      });
+    }
+  );
+
   s.tool(
     "get_async_job_status",
-    "Get status and result for an asynchronous job started by import_scrivener_sync_async or merge_scrivener_project_beta_async.",
+    "Get status and result for an asynchronous job started by async tools such as import_scrivener_sync_async, merge_scrivener_project_beta_async, or enrich_scene_characters_batch.",
     {
       job_id: z.string().describe("Job ID returned by an async start tool."),
       include_result: z.boolean().optional().describe("If true (default), includes completed result payload when available."),
@@ -1081,7 +1313,7 @@ function createMcpServer() {
 
   s.tool(
     "list_async_jobs",
-    "List asynchronous import/merge jobs currently known to this server.",
+    "List asynchronous jobs currently known to this server.",
     {
       include_results: z.boolean().optional().describe("If true, includes completed result payloads."),
     },
@@ -1199,7 +1431,7 @@ function createMcpServer() {
     },
     async ({ project_id, character, beat, tag, part, chapter, pov, page, page_size }) => {
       let query = `
-        SELECT DISTINCT s.scene_id, s.project_id, s.title, s.part, s.chapter, s.pov,
+        SELECT DISTINCT s.scene_id, s.project_id, s.title, s.part, s.chapter, s.chapter_title, s.pov,
                s.logline, s.scene_change, s.causality, s.stakes, s.scene_functions,
                s.save_the_cat_beat, s.timeline_position, s.story_time,
                s.word_count, s.metadata_stale
@@ -1357,7 +1589,7 @@ function createMcpServer() {
     },
     async ({ character_id, project_id, page, page_size }) => {
       let query = `
-        SELECT s.scene_id, s.project_id, s.part, s.chapter, s.title, s.logline,
+        SELECT s.scene_id, s.project_id, s.part, s.chapter, s.chapter_title, s.title, s.logline,
                s.scene_change, s.causality, s.stakes, s.scene_functions,
                s.save_the_cat_beat, s.timeline_position, s.story_time, s.pov, s.metadata_stale
         FROM scenes s
@@ -1635,7 +1867,7 @@ function createMcpServer() {
 
       if (!shouldPaginate) {
         const rows = db.prepare(`
-          SELECT f.scene_id, f.project_id, s.title, s.logline, s.part, s.chapter, s.metadata_stale
+          SELECT f.scene_id, f.project_id, s.title, s.logline, s.part, s.chapter, s.chapter_title, s.metadata_stale
           FROM scenes_fts f
           JOIN scenes s ON s.scene_id = f.scene_id AND s.project_id = f.project_id
           WHERE scenes_fts MATCH ?
@@ -1652,7 +1884,7 @@ function createMcpServer() {
       const offset = (normalizedPage - 1) * safePageSize;
 
       const rows = db.prepare(`
-        SELECT f.scene_id, f.project_id, s.title, s.logline, s.part, s.chapter, s.metadata_stale
+        SELECT f.scene_id, f.project_id, s.title, s.logline, s.part, s.chapter, s.chapter_title, s.metadata_stale
         FROM scenes_fts f
         JOIN scenes s ON s.scene_id = f.scene_id AND s.project_id = f.project_id
         WHERE scenes_fts MATCH ?
@@ -1718,7 +1950,7 @@ function createMcpServer() {
       }
 
       const rows = db.prepare(`
-        SELECT s.scene_id, s.project_id, s.part, s.chapter, s.title, s.logline,
+        SELECT s.scene_id, s.project_id, s.part, s.chapter, s.chapter_title, s.title, s.logline,
                st.beat AS thread_beat, s.timeline_position, s.story_time, s.metadata_stale
         FROM scenes s
         JOIN scene_threads st ON st.scene_id = s.scene_id AND st.thread_id = ?
@@ -2059,7 +2291,7 @@ function createMcpServer() {
       let query = `
         SELECT r.from_character, r.to_character, r.relationship_type, r.strength,
                r.scene_id, r.note,
-               s.part, s.chapter, s.timeline_position, s.title AS scene_title
+               s.part, s.chapter, s.chapter_title, s.timeline_position, s.title AS scene_title
         FROM character_relationships r
         LEFT JOIN scenes s ON s.scene_id = r.scene_id
         WHERE r.from_character = ? AND r.to_character = ?

package/metadata-lint.js

@@ -32,6 +32,7 @@ const sceneSchema = z.object({
   title: z.string().min(1).optional(),
   part: z.number().int().positive().optional(),
   chapter: z.number().int().positive().optional(),
+  chapter_title: z.string().min(1).optional(),
   pov: z.string().min(1).optional(),
   logline: z.string().min(1).optional(),
   save_the_cat_beat: z.string().min(1).optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",

package/scripts/async-job-runner.mjs

@@ -2,12 +2,24 @@ import fs from "node:fs";
 import path from "node:path";
 import { importScrivenerSync } from "../importer.js";
 import { mergeScrivenerProjectMetadata } from "../scrivener-direct.js";
+import { runSceneCharacterBatch } from "../scene-character-batch.js";
+import { ASYNC_PROGRESS_PREFIX } from "../async-progress.js";
+
+const PROGRESS_PREFIX = ASYNC_PROGRESS_PREFIX;
 
 function writeResult(resultPath, payload) {
   fs.mkdirSync(path.dirname(resultPath), { recursive: true });
   fs.writeFileSync(resultPath, JSON.stringify(payload, null, 2), "utf8");
 }
 
+function writeProgress(payload) {
+  try {
+    process.stdout.write(`${PROGRESS_PREFIX}${JSON.stringify(payload)}\n`);
+  } catch {
+    // Best-effort only; never fail the job due to progress telemetry.
+  }
+}
+
 function normalizeImportResult(importResult) {
   const importPayload = {
     source_dir: importResult.scrivenerDir,
@@ -49,10 +61,14 @@ function normalizeMergeResult(mergeResult) {
       dry_run: mergeResult.dryRun,
       sidecar_files: mergeResult.sidecarFiles,
       updated: mergeResult.updated,
+      relocated: mergeResult.relocated,
       unchanged: mergeResult.unchanged,
       no_data: mergeResult.noData,
       field_add_counts: mergeResult.fieldAddCounts,
       preview_changes: mergeResult.previewChanges,
+      warnings: mergeResult.warnings,
+      warnings_truncated: mergeResult.warningsTruncated,
+      warning_summary: mergeResult.warningSummary,
       stats: {
         sync_map_entries: mergeResult.stats.syncMapEntries,
         keyword_map_entries: mergeResult.stats.keywordMapEntries,
@@ -68,7 +84,14 @@ function normalizeMergeResult(mergeResult) {
   };
 }
 
-function main() {
+function normalizeSceneCharacterBatchResult(batchResult) {
+  return {
+    ok: true,
+    ...batchResult,
+  };
+}
+
+async function main() {
   const requestPath = process.argv[2];
   const resultPath = process.argv[3];
 
@@ -102,16 +125,43 @@ function main() {
       projectId: request.args?.project_id,
       scenesDir: request.args?.scenes_dir,
       dryRun: Boolean(request.args?.dry_run),
+      organizeByChapters: Boolean(request.args?.organize_by_chapters),
     });
     writeResult(resultPath, normalizeMergeResult(result));
     return;
   }
 
+  if (request.kind === "enrich_scene_characters_batch") {
+    let cancellationRequested = false;
+    const handleSigterm = () => {
+      cancellationRequested = true;
+    };
+    process.on("SIGTERM", handleSigterm);
+
+    const result = await runSceneCharacterBatch({
+      syncDir,
+      args: {
+        project_id: request.args?.project_id,
+        dry_run: Boolean(request.args?.dry_run),
+        replace_mode: request.args?.replace_mode ?? "merge",
+        include_match_details: Boolean(request.args?.include_match_details),
+        project_exists: request.args?.project_exists !== false,
+        target_scenes: request.args?.target_scenes ?? [],
+        character_rows: request.args?.character_rows ?? [],
+      },
+      onProgress: progress => writeProgress({ kind: request.kind, ...progress }),
+      shouldCancel: () => cancellationRequested,
+    });
+    process.off("SIGTERM", handleSigterm);
+    writeResult(resultPath, normalizeSceneCharacterBatchResult(result));
+    return;
+  }
+
   throw new Error(`Unsupported async job kind '${request.kind}'.`);
 }
 
 try {
-  main();
+  await main();
 } catch (error) {
   const resultPath = process.argv[3];
   if (resultPath) {

package/scripts/generate-tool-docs.mjs

@@ -425,9 +425,9 @@ function generateMarkdown(tools) {
       lines.push('_No parameters._');
     } else {
       lines.push('| Parameter | Type | Required | Description |');
-      lines.push('|-----------|------|:--------:|-------------|');
+      lines.push('| --- | --- | :---: | --- |');
       for (const p of tool.params) {
-        const req  = p.optional ? '' : '✓';
+        const req  = p.optional ? 'No' : 'Yes';
         const desc = p.description.replace(/\|/g, '\\|'); // escape pipes
         lines.push(`| \`${p.name}\` | \`${p.type}\` | ${req} | ${desc} |`);
       }

package/scripts/merge-scrivx.js

@@ -11,6 +11,7 @@
  * Options:
  *   --project <id>    Project ID (default: derived from mcp-sync-dir name)
  *   --dry-run         Show what would change without writing anything
+ *   --organize-by-chapters  Relocate scene files into part/chapter folders
  *
  * What it merges into scene sidecars:
  *   synopsis          - from Files/Data/<UUID>/synopsis.txt
@@ -34,13 +35,14 @@ import { mergeScrivenerProjectMetadata } from "../scrivener-direct.js";
 // ---------------------------------------------------------------------------
 const args = process.argv.slice(2);
 if (args.length < 2 || args[0] === "--help") {
-  console.log("Usage: node scripts/merge-scrivx.js <path-to.scriv> <mcp-sync-dir> [--project <id>] [--dry-run]");
+  console.log("Usage: node scripts/merge-scrivx.js <path-to.scriv> <mcp-sync-dir> [--project <id>] [--dry-run] [--organize-by-chapters]");
   process.exit(args[0] === "--help" ? 0 : 1);
 }
 
 const scrivPath  = path.resolve(args[0]);
 const mcpSyncDir = path.resolve(args[1]);
 const dryRun     = args.includes("--dry-run");
+const organizeByChapters = args.includes("--organize-by-chapters");
 const projectIdx = args.indexOf("--project");
 const projectId  = projectIdx !== -1
   ? args[projectIdx + 1]
@@ -58,6 +60,7 @@ try {
     mcpSyncDir,
     projectId,
     dryRun,
+    organizeByChapters,
     logger: line => console.log(line),
   });
 } catch (err) {

package/scrivener-direct.js

@@ -23,6 +23,9 @@ function children(el, tag) {
 
 function walkYamls(dir, list = []) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory() && /^(projects|universes)$/i.test(entry.name)) {
+      continue;
+    }
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) walkYamls(full, list);
     else if (entry.name.endsWith(".meta.yaml")) list.push(full);
@@ -34,29 +37,170 @@ function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+function slugifyPathSegment(value) {
+  return String(value ?? "")
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 50);
+}
+
+function chapterFolderName(chapter, chapterTitle) {
+  if (chapter === null || chapter === undefined) return null;
+  const suffix = slugifyPathSegment(chapterTitle);
+  return suffix ? `chapter-${chapter}-${suffix}` : `chapter-${chapter}`;
+}
+
+function sceneContainerDir(scenesDir, part, chapter, chapterTitle, organizeByChapters = true) {
+  const segments = [scenesDir];
+  if (!organizeByChapters) {
+    return path.join(...segments);
+  }
+  if (part !== null && part !== undefined) segments.push(`part-${part}`);
+  const chapterDir = chapterFolderName(chapter, chapterTitle);
+  if (chapterDir) segments.push(chapterDir);
+  return path.join(...segments);
+}
+
+function findProsePathForSidecar(sidecarPath) {
+  const proseCandidates = [
+    sidecarPath.replace(/\.meta\.yaml$/, ".md"),
+    sidecarPath.replace(/\.meta\.yaml$/, ".txt"),
+  ];
+  return proseCandidates.find(candidate => fs.existsSync(candidate)) ?? null;
+}
+
+function moveFileIfNeeded(fromPath, toPath) {
+  if (!fromPath || fromPath === toPath) return;
+  fs.mkdirSync(path.dirname(toPath), { recursive: true });
+  if (fs.existsSync(toPath)) {
+    return {
+      moved: false,
+      warning: {
+        code: "relocate_destination_exists",
+        message: "Skipped moving prose file because destination already exists.",
+        from_path: fromPath,
+        to_path: toPath,
+      },
+    };
+  }
+
+  try {
+    fs.renameSync(fromPath, toPath);
+  } catch (error) {
+    if (!error || typeof error !== "object" || error.code !== "EXDEV") {
+      throw error;
+    }
+    fs.copyFileSync(fromPath, toPath);
+    fs.unlinkSync(fromPath);
+  }
+
+  return { moved: true };
+}
+
+const KNOWN_CUSTOM_FIELD_IDS = new Set([
+  "savethecat!",
+  "causality",
+  "stakes",
+  "change",
+  "f:character",
+  "f:mood",
+  "f:theme",
+]);
+
+const MAX_RETURNED_WARNINGS = 25;
+
+function recordWarning(summary, warning) {
+  if (!summary[warning.code]) {
+    summary[warning.code] = { count: 0, examples: [] };
+  }
+
+  const entry = summary[warning.code];
+  entry.count++;
+
+  if (entry.examples.length < 5) {
+    const example = { message: warning.message };
+    for (const key of ["file", "sync_number", "field_id", "value", "uuid", "from_path", "to_path", "moved_to"]) {
+      if (warning[key] !== undefined && warning[key] !== null) {
+        example[key] = warning[key];
+      }
+    }
+    entry.examples.push(example);
+  }
+}
+
+function pushWarning(warnings, warningSummary, warning) {
+  recordWarning(warningSummary, warning);
+
+  if (warnings.length < MAX_RETURNED_WARNINGS) {
+    warnings.push(warning);
+    return false;
+  }
+
+  return true;
+}
+
 function buildMergeDataFromProject(projectData, uuid) {
-  const { metaByUUID, partByUUID, chapterByUUID } = projectData;
-  const { customFields, characters, versions, synopsis } = metaByUUID[uuid] ?? {};
+  const { metaByUUID, partByUUID, chapterByUUID, chapterTitleByUUID } = projectData;
+  const { customFields, tags, synopsis } = metaByUUID[uuid] ?? {};
   const part = partByUUID[uuid] ?? null;
   const chapter = chapterByUUID[uuid] ?? null;
+  const chapterTitle = chapterTitleByUUID[uuid] ?? null;
+  const warnings = [];
 
-  if (!customFields && !characters && !versions && !synopsis && part === null && chapter === null) return null;
+  if (!customFields && !tags && !synopsis && part === null && chapter === null && !chapterTitle) {
+    return { mergeData: null, warnings };
+  }
 
   const out = {};
 
   if (part !== null) out.part = part;
   if (chapter !== null) out.chapter = chapter;
+  if (chapterTitle) out.chapter_title = chapterTitle;
   if (synopsis) out.synopsis = synopsis;
-  if (characters?.length) out.characters = characters;
-  if (versions?.length) out.versions = versions;
+  if (tags?.length) out.tags = tags;
+
+  for (const [fieldId, value] of Object.entries(customFields ?? {})) {
+    if (!KNOWN_CUSTOM_FIELD_IDS.has(fieldId) && String(value ?? "").trim()) {
+      warnings.push({
+        code: "ignored_custom_field",
+        message: `Ignored unsupported Scrivener custom field '${fieldId}'.`,
+        field_id: fieldId,
+        value: String(value),
+        uuid,
+      });
+    }
+  }
 
   const stcBeat = customFields?.["savethecat!"];
   if (stcBeat && typeof stcBeat === "string" && stcBeat.trim()) {
     out.save_the_cat_beat = stcBeat.trim();
   }
 
-  const causality = Number(customFields?.["causality"] ?? 0);
-  const stakes = Number(customFields?.["stakes"] ?? 0);
+  const causalityRaw = customFields?.["causality"];
+  const stakesRaw = customFields?.["stakes"];
+  const causality = Number(causalityRaw ?? 0);
+  const stakes = Number(stakesRaw ?? 0);
+  if (causalityRaw !== undefined && String(causalityRaw).trim() && Number.isNaN(causality)) {
+    warnings.push({
+      code: "invalid_custom_field_value",
+      message: "Ignored non-numeric Scrivener custom field value for 'causality'.",
+      field_id: "causality",
+      value: String(causalityRaw),
+      uuid,
+    });
+  }
+  if (stakesRaw !== undefined && String(stakesRaw).trim() && Number.isNaN(stakes)) {
+    warnings.push({
+      code: "invalid_custom_field_value",
+      message: "Ignored non-numeric Scrivener custom field value for 'stakes'.",
+      field_id: "stakes",
+      value: String(stakesRaw),
+      uuid,
+    });
+  }
   if (causality) out.causality = causality;
   if (stakes) out.stakes = stakes;
 
@@ -69,7 +213,10 @@ function buildMergeDataFromProject(projectData, uuid) {
   if (customFields?.["f:theme"] === "Yes" || customFields?.["f:theme"] === true) fnFlags.push("theme");
   if (fnFlags.length) out.scene_functions = fnFlags;
 
-  return Object.keys(out).length ? out : null;
+  return {
+    mergeData: Object.keys(out).length ? out : null,
+    warnings,
+  };
 }
 
 export function mergeSidecarData(existing, mergeData) {
@@ -144,15 +291,13 @@ export function loadScrivenerProjectData(scrivPath) {
       }
     }
 
-    const characters = [];
-    const versions = [];
+    const tags = [];
     const kwEl = children(item, "Keywords")[0];
     if (kwEl) {
       for (const kwId of children(kwEl, "KeywordID")) {
         const name = keywordMap[text(kwId)];
         if (!name) continue;
-        if (/^v\d[\d.a-z]*$/i.test(name)) versions.push(name);
-        else characters.push(name);
+        tags.push(name);
       }
     }
 
@@ -163,11 +308,16 @@ export function loadScrivenerProjectData(scrivPath) {
       if (candidate) synopsis = candidate;
     }
 
-    metaByUUID[uuid] = { customFields, characters, versions, synopsis };
+    metaByUUID[uuid] = {
+      customFields,
+      tags: [...new Set(tags)],
+      synopsis,
+    };
   }
 
   const partByUUID = {};
   const chapterByUUID = {};
+  const chapterTitleByUUID = {};
   let partNum = 0;
   let chapterNum = 0;
 
@@ -176,21 +326,29 @@ export function loadScrivenerProjectData(scrivPath) {
       const uuid = attr(child, "UUID");
       const type = attr(child, "Type");
       const childrenEl = children(child, "Children")[0];
+      const title = text(children(child, "Title")[0]);
 
       if (type === "Folder" && currentPart === null) {
         partNum++;
-        if (childrenEl) walkHierarchy(childrenEl, partNum, null);
+        if (childrenEl) walkHierarchy(childrenEl, { number: partNum, title }, null);
       } else if (type === "Folder") {
         chapterNum++;
+        const nextChapter = { number: chapterNum, title };
         if (uuid) {
-          partByUUID[uuid] = currentPart;
+          if (currentPart?.number !== null && currentPart?.number !== undefined) {
+            partByUUID[uuid] = currentPart.number;
+          }
           chapterByUUID[uuid] = chapterNum;
+          if (title) chapterTitleByUUID[uuid] = title;
         }
-        if (childrenEl) walkHierarchy(childrenEl, currentPart, chapterNum);
+        if (childrenEl) walkHierarchy(childrenEl, currentPart, nextChapter);
       } else if (type === "Text") {
-        if (uuid && currentChapter !== null) {
-          partByUUID[uuid] = currentPart;
-          chapterByUUID[uuid] = currentChapter;
+        if (uuid && currentChapter?.number !== null && currentChapter?.number !== undefined) {
+          if (currentPart?.number !== null && currentPart?.number !== undefined) {
+            partByUUID[uuid] = currentPart.number;
+          }
+          chapterByUUID[uuid] = currentChapter.number;
+          if (currentChapter.title) chapterTitleByUUID[uuid] = currentChapter.title;
         }
       }
     }
@@ -214,6 +372,7 @@ export function loadScrivenerProjectData(scrivPath) {
     metaByUUID,
     partByUUID,
     chapterByUUID,
+    chapterTitleByUUID,
   };
 }
 
@@ -223,6 +382,7 @@ export function mergeScrivenerProjectMetadata({
   projectId,
   scenesDir: scenesDirOverride,
   dryRun = false,
+  organizeByChapters = false,
   logger = () => {},
 }) {
   const mcpSyncDirAbs = path.resolve(mcpSyncDir);
@@ -268,15 +428,25 @@ export function mergeScrivenerProjectMetadata({
   let unchanged = 0;
   let noData = 0;
   let skippedNoBracketId = 0;
+  let relocated = 0;
   const fieldAddCounts = {};
   const previewChanges = [];
+  const warnings = [];
+  const warningSummary = {};
+  let warningsTruncated = false;
 
   for (const sidecarPath of sidecarFiles) {
     const filename = path.basename(sidecarPath);
+    const prosePath = findProsePathForSidecar(sidecarPath);
     const match = filename.match(/\[(\d+)\]\.meta\.yaml$/);
     if (!match) {
       logger(`  SKIP  (no bracket ID) ${filename}`);
       skippedNoBracketId++;
+      warningsTruncated = pushWarning(warnings, warningSummary, {
+        code: "missing_bracket_id",
+        message: "Skipped sidecar because filename does not include a Scrivener sync number in brackets.",
+        file: filename,
+      }) || warningsTruncated;
       continue;
     }
 
@@ -285,10 +455,20 @@ export function mergeScrivenerProjectMetadata({
     if (!uuid) {
       logger(`  SKIP  (no UUID for [${syncNum}]) ${filename}`);
       noData++;
+      warningsTruncated = pushWarning(warnings, warningSummary, {
+        code: "missing_uuid_mapping",
+        message: `Skipped sidecar because Scrivener sync number [${syncNum}] has no UUID mapping in the project.`,
+        file: filename,
+        sync_number: syncNum,
+      }) || warningsTruncated;
       continue;
     }
 
-    const mergeData = buildMergeDataFromProject(projectData, uuid);
+    const { mergeData, warnings: mergeWarnings } = buildMergeDataFromProject(projectData, uuid);
+    for (const warning of mergeWarnings) {
+      warningsTruncated = pushWarning(warnings, warningSummary, { ...warning, file: filename }) || warningsTruncated;
+    }
+
     if (!mergeData) {
       unchanged++;
       continue;
@@ -300,8 +480,22 @@ export function mergeScrivenerProjectMetadata({
     }
     const existing = existingRaw ?? {};
     const { merged, changed, newKeys } = mergeSidecarData(existing, mergeData);
-
-    if (!changed) {
+    const effective = changed ? merged : existing;
+    const targetDir = sceneContainerDir(
+      scenesDir,
+      effective.part ?? null,
+      effective.chapter ?? null,
+      effective.chapter_title ?? null,
+      organizeByChapters,
+    );
+    const targetSidecarPath = organizeByChapters ? path.join(targetDir, filename) : sidecarPath;
+    const targetProsePath = prosePath
+      ? (organizeByChapters ? path.join(targetDir, path.basename(prosePath)) : prosePath)
+      : null;
+    const needsMove = path.resolve(sidecarPath) !== path.resolve(targetSidecarPath)
+      || (prosePath && targetProsePath && path.resolve(prosePath) !== path.resolve(targetProsePath));
+
+    if (!changed && !needsMove) {
       unchanged++;
       continue;
     }
@@ -311,23 +505,92 @@ export function mergeScrivenerProjectMetadata({
     }
 
     if (previewChanges.length < 25) {
-      previewChanges.push({ file: filename, added_keys: [...newKeys] });
+      previewChanges.push({
+        file: filename,
+        added_keys: [...newKeys],
+        ...(needsMove ? { moved_to: path.relative(scenesDir, targetSidecarPath) || filename } : {}),
+      });
     }
 
+    let didRelocate = false;
+
     if (dryRun) {
       logger(`  DRY   ${filename}`);
       for (const key of newKeys) {
         logger(`        + ${key}: ${JSON.stringify(mergeData[key]).slice(0, 80)}`);
       }
+      if (needsMove) {
+        logger(`        -> ${path.relative(scenesDir, targetSidecarPath) || filename}`);
+      }
+      didRelocate = needsMove;
     } else {
-      fs.writeFileSync(sidecarPath, yaml.dump(merged, { lineWidth: 120 }), "utf8");
-      logger(`  OK    ${filename}  [+${newKeys.join(", ")}]`);
+      let proseMoveWarning = null;
+      let shouldRelocateSidecar = organizeByChapters;
+
+      if (
+        shouldRelocateSidecar
+        && path.resolve(sidecarPath) !== path.resolve(targetSidecarPath)
+        && fs.existsSync(targetSidecarPath)
+      ) {
+        shouldRelocateSidecar = false;
+        warningsTruncated = pushWarning(
+          warnings,
+          warningSummary,
+          {
+            code: "relocate_sidecar_destination_exists",
+            message: "Skipped relocating sidecar because destination already exists.",
+            from_path: sidecarPath,
+            to_path: targetSidecarPath,
+            file: filename,
+          }
+        ) || warningsTruncated;
+      }
+
+      if (shouldRelocateSidecar && prosePath && targetProsePath) {
+        const moveResult = moveFileIfNeeded(prosePath, targetProsePath);
+        if (moveResult?.warning) {
+          proseMoveWarning = moveResult.warning;
+          shouldRelocateSidecar = false;
+          warningsTruncated = pushWarning(
+            warnings,
+            warningSummary,
+            {
+              ...moveResult.warning,
+              file: filename,
+            }
+          ) || warningsTruncated;
+        }
+      }
+
+      const finalSidecarPath = shouldRelocateSidecar ? targetSidecarPath : sidecarPath;
+      fs.mkdirSync(path.dirname(finalSidecarPath), { recursive: true });
+      fs.writeFileSync(finalSidecarPath, yaml.dump(effective, { lineWidth: 120 }), "utf8");
+      if (
+        shouldRelocateSidecar
+        && path.resolve(sidecarPath) !== path.resolve(targetSidecarPath)
+        && fs.existsSync(sidecarPath)
+      ) {
+        fs.unlinkSync(sidecarPath);
+      }
+
+      const changes = [];
+      if (newKeys.length) changes.push(`+${newKeys.join(", ")}`);
+      if (needsMove && shouldRelocateSidecar) {
+        changes.push(`moved to ${path.relative(scenesDir, targetSidecarPath) || filename}`);
+      }
+      if (proseMoveWarning) {
+        changes.push("sidecar kept in place (prose move skipped)");
+      }
+      logger(`  OK    ${filename}${changes.length ? `  [${changes.join("; ")}]` : ""}`);
+      didRelocate = needsMove && shouldRelocateSidecar;
     }
+    if (didRelocate) relocated++;
     updated++;
   }
 
   logger(`\n${"─".repeat(50)}`);
   logger(`Updated:   ${updated} sidecars${dryRun ? " (dry run)" : ""}`);
+  if (relocated) logger(`Relocated: ${relocated} scene file pair(s)`);
   logger(`Unchanged: ${unchanged} (already complete or no new data)`);
   if (skippedNoBracketId) logger(`Skipped:   ${skippedNoBracketId} (no bracket ID in filename)`);
   if (noData) logger(`No data:   ${noData} (no matching binder entry)`);
@@ -340,11 +603,15 @@ export function mergeScrivenerProjectMetadata({
     dryRun: Boolean(dryRun),
     sidecarFiles: sidecarFiles.length,
     updated,
+    relocated,
     unchanged,
     skippedNoBracketId,
     noData,
     fieldAddCounts,
     previewChanges,
+    warnings,
+    warningsTruncated,
+    warningSummary,
     stats: {
       syncMapEntries: Object.keys(projectData.syncNumToUUID).length,
       keywordMapEntries: Object.keys(projectData.keywordMap).length,

package/sync.js

@@ -69,10 +69,10 @@ export function inferScenePositionFromPath(syncDir, filePath) {
   let chapter = null;
 
   for (const segment of parts) {
-    const partMatch = segment.match(/^part-(\d+)$/i);
+    const partMatch = segment.match(/^part-(\d+)(?:-.+)?$/i);
     if (partMatch) part = parseInt(partMatch[1], 10);
 
-    const chapterMatch = segment.match(/^chapter-(\d+)$/i);
+    const chapterMatch = segment.match(/^chapter-(\d+)(?:-.+)?$/i);
     if (chapterMatch) chapter = parseInt(chapterMatch[1], 10);
   }
 
@@ -107,8 +107,8 @@ const UNIVERSE_PROJECT_ROOT_CACHE = new Map();
 function isProjectStructuralDir(name) {
   const normalized = String(name ?? "").toLowerCase();
   return PROJECT_STRUCTURAL_DIRS.has(normalized)
-    || /^part-\d+$/.test(normalized)
-    || /^chapter-\d+$/.test(normalized);
+    || /^part-\d+(?:-.+)?$/.test(normalized)
+    || /^chapter-\d+(?:-.+)?$/.test(normalized);
 }
 
 function isBookSlug(name) {
@@ -480,15 +480,16 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
 
   db.prepare(`
     INSERT INTO scenes (
-      scene_id, project_id, title, part, chapter, pov, logline, scene_change,
+      scene_id, project_id, title, part, chapter, chapter_title, pov, logline, scene_change,
       causality, stakes, scene_functions,
       save_the_cat_beat, timeline_position, story_time, word_count,
       file_path, prose_checksum, metadata_stale, updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT (scene_id, project_id) DO UPDATE SET
       title = excluded.title,
       part = excluded.part,
       chapter = excluded.chapter,
+      chapter_title = excluded.chapter_title,
       pov = excluded.pov,
       logline = excluded.logline,
       scene_change = excluded.scene_change,
@@ -505,7 +506,7 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
       updated_at = excluded.updated_at
   `).run(
     meta.scene_id, project_id,
-    meta.title ?? null, meta.part ?? null, meta.chapter ?? null,
+    meta.title ?? null, meta.part ?? null, meta.chapter ?? null, meta.chapter_title ?? null,
     meta.pov ?? null, meta.logline ?? meta.synopsis ?? null,
     meta.scene_change ?? meta.change ?? null,
     meta.causality ?? null, meta.stakes ?? null,