@hanna84/mcp-writing 1.11.1 → 1.11.3

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.3](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.2...v1.11.3)
+
+- docs: reorganize AI-first documentation into scoped instructions [`#62`](https://github.com/hannasdev/mcp-writing.git
+/pull/62)
+
+#### [v1.11.2](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.11.1...v1.11.2)
+
+> 23 April 2026
+
+- Scrivener beta: opt-in chapter organization + raw keyword tags [`#60`](https://github.com/hannasdev/mcp-writing.git
+/pull/60)
+- Release 1.11.2 [`3d8dfe5`](https://github.com/hannasdev/mcp-writing.git
+/commit/3d8dfe5c75ee29ab1dfe2f242c1ea837d810995f)
+
 #### [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)

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

@@ -775,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."),
@@ -897,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) {
@@ -943,6 +944,7 @@ function createMcpServer() {
           projectId: project_id,
           scenesDir: normalizedScenesDir,
           dryRun: Boolean(dry_run),
+          organizeByChapters: Boolean(organize_by_chapters),
         });
       } catch (error) {
         return errorResponse(
@@ -973,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,
@@ -1009,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')."),
@@ -1089,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) {
@@ -1136,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,
@@ -1423,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
@@ -1581,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
@@ -1859,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 ?
@@ -1876,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 ?
@@ -1942,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 = ?
@@ -2283,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.1",
+  "version": "1.11.3",
   "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

@@ -61,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,
@@ -121,6 +125,7 @@ async 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;

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,