@hanna84/mcp-writing 1.17.0 → 2.0.1

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).
 
+#### [v2.0.1](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.0.0...v2.0.1)
+
+- fix(package): include scene-character-batch in published files [`#79`](https://github.com/hannasdev/mcp-writing.git
+/pull/79)
+
+### [v2.0.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.17.0...v2.0.0)
+
+> 25 April 2026
+
+- feat(review-bundles)!: add PDF export via pdfkit [`#78`](https://github.com/hannasdev/mcp-writing.git
+/pull/78)
+- Release 2.0.0 [`ddccb28`](https://github.com/hannasdev/mcp-writing.git
+/commit/ddccb2869c6787b0cb64897d067886d59f7cb6e6)
+
 #### [v1.17.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.16.2...v1.17.0)
 
+> 25 April 2026
+
 - feat: add beta_reader_personalized review bundle profile [`#77`](https://github.com/hannasdev/mcp-writing.git
 /pull/77)
+- Release 1.17.0 [`1cf0a19`](https://github.com/hannasdev/mcp-writing.git
+/commit/1cf0a194bc73073655043072722a9c97cd17c923)
 
 #### [v1.16.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.16.1...v1.16.2)

package/index.js

@@ -1349,7 +1349,7 @@ function createMcpServer() {
   // ---- preview_review_bundle ----------------------------------------------
   s.tool(
     "preview_review_bundle",
-    "Dry-run planning tool for review bundles. Resolves scene scope, deterministic ordering, warnings, and planned output filenames without writing files. Note: include_scene_ids/include_metadata_sidebar/include_paragraph_anchors are advisory placeholders in Phase 4A.1 and do not alter planning semantics yet.",
+    "Dry-run planning tool for review bundles. Resolves scene scope, deterministic ordering, warnings, and planned output filenames without writing files. Rendering options are accepted for API consistency and reflected in resolved_scope.options, but do not change planning output.",
     {
       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."),
@@ -1358,11 +1358,12 @@ function createMcpServer() {
       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."),
-      include_scene_ids: z.boolean().optional().describe("Advisory placeholder for later rendering behavior (default true). Included in preview output options, but does not change planning results in Phase 4A.1."),
-      include_metadata_sidebar: z.boolean().optional().describe("Advisory placeholder for later rendering behavior (default false). Included in preview output options, but does not change planning results in Phase 4A.1."),
-      include_paragraph_anchors: z.boolean().optional().describe("Advisory placeholder for later rendering behavior (default false). Included in preview output options, but does not change planning results in Phase 4A.1."),
+      include_scene_ids: z.boolean().optional().describe("Rendering option (default true). Echoed in resolved_scope.options for downstream rendering; does not change planning results."),
+      include_metadata_sidebar: z.boolean().optional().describe("Rendering option (default false). Echoed in resolved_scope.options for downstream rendering; does not change planning results."),
+      include_paragraph_anchors: z.boolean().optional().describe("Rendering option (default false). Echoed in resolved_scope.options for downstream rendering; does not change planning results."),
       recipient_name: z.string().optional().describe("Optional recipient display name for beta_reader_personalized profile."),
       bundle_name: z.string().optional().describe("Optional output bundle base name override (slugified in planned outputs)."),
+      format: z.enum(["pdf", "markdown", "both"]).optional().describe("Planned output format: pdf (default), markdown, or both. Affects planned_outputs filenames only; preview_review_bundle does not render artifacts."),
     },
     async ({
       project_id,
@@ -1377,6 +1378,7 @@ function createMcpServer() {
       include_paragraph_anchors = false,
       recipient_name,
       bundle_name,
+      format = "pdf",
     }) => {
       const projectIdCheck = validateProjectId(project_id);
       if (!projectIdCheck.ok) {
@@ -1397,6 +1399,7 @@ function createMcpServer() {
           include_paragraph_anchors,
           recipient_name,
           bundle_name,
+          format,
         });
         return jsonResponse(plan);
       } catch (error) {
@@ -1414,7 +1417,7 @@ function createMcpServer() {
   // ---- create_review_bundle -----------------------------------------------
   s.tool(
     "create_review_bundle",
-    "Generate markdown review bundle artifacts from planned scene scope. Writes files only under output_dir and returns manifest/provenance details.",
+    "Generate review bundle artifacts (PDF/markdown) from planned scene scope. Writes files only under output_dir and returns manifest/provenance details.",
     {
       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."),
@@ -1424,12 +1427,13 @@ function createMcpServer() {
       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."),
-      include_scene_ids: z.boolean().optional().describe("Include scene IDs in markdown headings (default true)."),
-      include_metadata_sidebar: z.boolean().optional().describe("Include metadata sidebar in markdown output (default false)."),
-      include_paragraph_anchors: z.boolean().optional().describe("Include paragraph anchors in markdown output (default false)."),
+      include_scene_ids: z.boolean().optional().describe("Include scene IDs in headings (default true). Applies to both PDF and markdown."),
+      include_metadata_sidebar: z.boolean().optional().describe("Include metadata sidebar in markdown output (default false). Markdown only — no effect on PDF."),
+      include_paragraph_anchors: z.boolean().optional().describe("Include paragraph anchors in markdown output (default false). Markdown only — no effect on PDF."),
       recipient_name: z.string().optional().describe("Optional recipient display name for beta_reader_personalized profile."),
       bundle_name: z.string().optional().describe("Optional output bundle base name override (slugified in filenames)."),
       source_commit: z.string().optional().describe("Optional explicit source commit for provenance. Defaults to current HEAD when available."),
+      format: z.enum(["pdf", "markdown", "both"]).optional().describe("Output format: pdf (default), markdown, or both."),
     },
     async ({
       project_id,
@@ -1446,6 +1450,7 @@ function createMcpServer() {
       recipient_name,
       bundle_name,
       source_commit,
+      format = "pdf",
     }) => {
       const projectIdCheck = validateProjectId(project_id);
       if (!projectIdCheck.ok) {
@@ -1479,6 +1484,7 @@ function createMcpServer() {
           include_paragraph_anchors,
           recipient_name,
           bundle_name,
+          format,
         });
 
         if (!plan.strictness_result.can_proceed) {
@@ -1490,7 +1496,7 @@ function createMcpServer() {
         }
 
         const provenanceCommit = source_commit ?? (GIT_ENABLED ? getHeadCommitHash(SYNC_DIR) : null);
-        const artifacts = createReviewBundleArtifacts(db, {
+        const artifacts = await createReviewBundleArtifacts(db, {
           plan,
           output_dir: resolvedOutputDir,
           source_commit: provenanceCommit,

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.17.0",
+  "version": "2.0.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
   "files": [
     "index.js",
     "async-progress.js",
+    "scene-character-batch.js",
     "scrivener-direct.js",
     "importer.js",
     "db.js",
@@ -56,6 +57,7 @@
     "@xmldom/xmldom": "^0.9.10",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.1",
+    "pdfkit": "^0.14.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/review-bundles.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
+import PDFDocument from "pdfkit";
 
 const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
 
@@ -153,6 +154,18 @@ function assertStrictness(strictness) {
   }
 }
 
+export const REVIEW_BUNDLE_FORMATS = ["pdf", "markdown", "both"];
+
+function assertFormat(format) {
+  if (!REVIEW_BUNDLE_FORMATS.includes(format)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_FORMAT",
+      `Unsupported format '${format}'.`,
+      { supported_formats: REVIEW_BUNDLE_FORMATS }
+    );
+  }
+}
+
 function resolveRequestedSceneIds(dbHandle, projectId, sceneIds) {
   if (!Array.isArray(sceneIds) || sceneIds.length === 0) {
     return { requested: [], existing: new Set() };
@@ -182,6 +195,7 @@ export function buildReviewBundlePlan(dbHandle, {
   include_paragraph_anchors = false,
   bundle_name,
   recipient_name,
+  format = "pdf",
 } = {}) {
   if (!project_id) {
     throw new ReviewBundlePlanError("INVALID_PROJECT_ID", "project_id is required.");
@@ -189,6 +203,7 @@ export function buildReviewBundlePlan(dbHandle, {
 
   assertProfile(profile);
   assertStrictness(strictness);
+  assertFormat(format);
 
   const projectRow = dbHandle.prepare(`SELECT project_id FROM projects WHERE project_id = ?`).get(project_id);
   if (!projectRow) {
@@ -368,7 +383,8 @@ export function buildReviewBundlePlan(dbHandle, {
       blockers,
     },
     planned_outputs: [
-      `${safeBundleName}.md`,
+      ...(format === "markdown" || format === "both" ? [`${safeBundleName}.md`] : []),
+      ...(format === "pdf" || format === "both" ? [`${safeBundleName}.pdf`] : []),
       ...(profile === "beta_reader_personalized"
         ? [
             `${safeBundleName}.notice.md`,
@@ -689,7 +705,150 @@ export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDi
   return sections.join("\n\n---\n\n").trim() + "\n";
 }
 
-export function createReviewBundleArtifacts(dbHandle, {
+/**
+ * Render a review bundle plan to PDF format using pdfkit.
+ * Returns a buffer containing the PDF document.
+ */
+export function renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir: syncDirOpt } = {}) {
+  const profile = plan.profile;
+  const includeSceneIds = Boolean(plan.resolved_scope?.options?.include_scene_ids);
+  const syncDir = syncDirOpt ?? process.env.WRITING_SYNC_DIR ?? null;
+
+  const sceneIds = plan.ordering.map(row => row.scene_id);
+  const rows = loadBundleSceneRows(dbHandle, plan.resolved_scope.project_id, sceneIds);
+  const recipientName = plan.resolved_scope?.options?.recipient_name;
+  const recipientDisplayName = normalizeRecipientDisplayName(recipientName);
+
+  // Create PDF document in memory (we'll pipe to buffer)
+  const doc = new PDFDocument({
+    size: "Letter",
+    margin: 50,
+  });
+
+  // Register listeners before any content is written so render-time errors
+  // always reject the returned Promise.
+  const chunks = [];
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    };
+
+    doc.on("data", chunk => chunks.push(chunk));
+    doc.on("error", fail);
+    doc.on("end", () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks));
+    });
+
+    try {
+      // Title and metadata
+      doc.fontSize(24).font("Helvetica-Bold").text(`Review Bundle: ${plan.resolved_scope.project_id}`, { align: "left" });
+      doc.moveDown(0.5);
+      doc.fontSize(11).font("Helvetica");
+      doc.text(`Profile: ${profile}`, { align: "left" });
+      if (profile === "beta_reader_personalized") {
+        doc.text(`Recipient: ${recipientDisplayName}`, { align: "left" });
+      }
+      doc.text(`Generated: ${generatedAt ?? new Date().toISOString()}`, { align: "left" });
+      doc.text(`Scenes: ${plan.summary.scene_count}`, { align: "left" });
+      doc.moveDown();
+
+      // Usage notice for beta profile
+      if (profile === "beta_reader_personalized") {
+        doc.fontSize(12).font("Helvetica-Bold").text("Usage Notice", { align: "left" });
+        doc.moveDown(0.3);
+        const noticeWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+        doc.fontSize(10).font("Helvetica");
+        doc.text("This beta-reader draft is intended for private review and feedback. Please do not redistribute without explicit author permission.", {
+          align: "left",
+          width: noticeWidth,
+        });
+        doc.moveDown();
+      }
+
+      // Render scenes
+      for (const scene of rows) {
+        // Scene heading
+        doc.fontSize(14).font("Helvetica-Bold");
+        let heading = scene.title || scene.scene_id;
+        if (includeSceneIds) {
+          heading += ` [${scene.scene_id}]`;
+        }
+        doc.text(heading, { align: "left" });
+        doc.moveDown(0.2);
+
+        // Scene metadata (one-liner)
+        const metaParts = [];
+        if (scene.pov) metaParts.push(`POV: ${scene.pov}`);
+        if (scene.save_the_cat_beat) metaParts.push(`Beat: ${scene.save_the_cat_beat}`);
+        if (metaParts.length > 0) {
+          const metaWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+          doc.fontSize(9).font("Helvetica-Oblique");
+          doc.text(metaParts.join(" • "), { align: "left", width: metaWidth });
+          doc.font("Helvetica");
+          doc.moveDown(0.2);
+        }
+
+        // Logline
+        if (scene.logline) {
+          doc.fontSize(10).font("Helvetica-Oblique");
+          const textWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+          doc.text(`"${scene.logline}"`, { align: "left", width: textWidth });
+          doc.moveDown(0.3);
+        }
+
+        // Prose (only for detailed/beta profiles)
+        if (profile === "editor_detailed" || profile === "beta_reader_personalized") {
+          let prose = "";
+          const resolved = readProse(scene.file_path, { syncDir });
+          if (resolved === null) {
+            throw new ReviewBundlePlanError(
+              "SCENE_PROSE_READ_FAILED",
+              `Scene prose is unavailable for scene ${scene.scene_id}: file_path is null or could not be resolved within syncDir.`,
+              {
+                scene_id: scene.scene_id,
+                file_path: scene.file_path ?? null,
+                sync_dir: syncDir,
+              }
+            );
+          }
+          prose = resolved;
+
+          const textWidth = doc.page.width - doc.page.margins.left - doc.page.margins.right;
+          doc.fontSize(10).font("Helvetica");
+          doc.text(prose, {
+            align: "left",
+            width: textWidth,
+            lineGap: 3,
+          });
+        }
+
+        doc.moveDown(0.5);
+        // Add page break between scenes only for prose-including profiles where
+        // clear scene separation matters. For outline_discussion, let content flow.
+        const includesProse = profile === "editor_detailed" || profile === "beta_reader_personalized";
+        if (includesProse && scene !== rows[rows.length - 1]) {
+          doc.addPage();
+        }
+      }
+
+      doc.end();
+    } catch (error) {
+      fail(error);
+      try {
+        doc.end();
+      } catch {
+        // Ignore errors from end() during failure cleanup.
+      }
+    }
+  });
+}
+
+export async function createReviewBundleArtifacts(dbHandle, {
   plan,
   output_dir,
   source_commit = null,
@@ -721,27 +880,45 @@ export function createReviewBundleArtifacts(dbHandle, {
 
   const noticeFileName = plan.planned_outputs.find(name => name.endsWith(".notice.md")) ?? null;
   const feedbackFileName = plan.planned_outputs.find(name => name.endsWith(".feedback-form.md")) ?? null;
+  // Derive which outputs to write from the plan itself, not from the format param,
+  // so plan and artifacts always stay in sync.
   const markdownFileName = plan.planned_outputs.find(
-    name =>
-      name.endsWith(".md") &&
-      !name.endsWith(".notice.md") &&
-      !name.endsWith(".feedback-form.md")
-  );
+    name => name.endsWith(".md") && !name.endsWith(".notice.md") && !name.endsWith(".feedback-form.md")
+  ) ?? null;
+  const pdfFileName = plan.planned_outputs.find(name => name.endsWith(".pdf")) ?? null;
   const manifestFileName = plan.planned_outputs.find(name => name.endsWith(".manifest.json"));
-  if (!markdownFileName || !manifestFileName) {
+
+  if (!manifestFileName) {
+    throw new ReviewBundlePlanError(
+      "INVALID_PLAN_OUTPUTS",
+      "Plan is missing expected manifest filename."
+    );
+  }
+
+  if (!markdownFileName && !pdfFileName) {
     throw new ReviewBundlePlanError(
       "INVALID_PLAN_OUTPUTS",
-      "Plan is missing expected markdown/manifest filenames."
+      "Plan has no primary bundle output (neither .md nor .pdf) in planned_outputs."
     );
   }
 
-  const markdownPath = resolveOutputFilePath(normalizedOutputDir, markdownFileName);
+  const markdownPath = markdownFileName ? resolveOutputFilePath(normalizedOutputDir, markdownFileName) : null;
+  const pdfPath = pdfFileName ? resolveOutputFilePath(normalizedOutputDir, pdfFileName) : null;
   const manifestPath = resolveOutputFilePath(normalizedOutputDir, manifestFileName);
   const noticePath = noticeFileName ? resolveOutputFilePath(normalizedOutputDir, noticeFileName) : null;
   const feedbackPath = feedbackFileName ? resolveOutputFilePath(normalizedOutputDir, feedbackFileName) : null;
 
   const generatedAt = new Date().toISOString();
-  const markdown = renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir });
+
+  // Render markdown if needed
+  const markdown = markdownPath ? renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir }) : null;
+
+  // Render PDF if needed
+  let pdfBuffer = null;
+  if (pdfPath) {
+    pdfBuffer = await renderReviewBundlePdf(dbHandle, plan, { generatedAt, syncDir });
+  }
+
   const recipientName = plan.resolved_scope?.options?.recipient_name;
   const betaNotice = plan.profile === "beta_reader_personalized"
     ? renderBetaNoticeMarkdown({ projectId: plan.resolved_scope.project_id, recipientName })
@@ -749,8 +926,11 @@ export function createReviewBundleArtifacts(dbHandle, {
   const betaFeedbackForm = plan.profile === "beta_reader_personalized"
     ? renderBetaFeedbackFormMarkdown({ projectId: plan.resolved_scope.project_id, recipientName, generatedAt })
     : null;
+
+  // Use the bundle ID from whichever primary file exists
+  const bundleIdFileName = markdownFileName || pdfFileName;
   const manifest = {
-    bundle_id: path.basename(markdownFileName, ".md"),
+    bundle_id: path.basename(bundleIdFileName, path.extname(bundleIdFileName)),
     profile: plan.profile,
     generated_at: generatedAt,
     provenance: {
@@ -764,7 +944,7 @@ export function createReviewBundleArtifacts(dbHandle, {
     scene_ids: plan.ordering.map(row => row.scene_id),
   };
 
-  for (const outputPath of [markdownPath, manifestPath, noticePath, feedbackPath].filter(Boolean)) {
+  for (const outputPath of [markdownPath, pdfPath, manifestPath, noticePath, feedbackPath].filter(Boolean)) {
     try {
       const stat = fs.lstatSync(outputPath);
       if (stat.isSymbolicLink()) {
@@ -789,7 +969,12 @@ export function createReviewBundleArtifacts(dbHandle, {
     }
   }
 
-  fs.writeFileSync(markdownPath, markdown, "utf8");
+  if (markdownPath && markdown != null) {
+    fs.writeFileSync(markdownPath, markdown, "utf8");
+  }
+  if (pdfPath && pdfBuffer != null) {
+    fs.writeFileSync(pdfPath, pdfBuffer);
+  }
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
   if (noticePath && betaNotice != null) {
     fs.writeFileSync(noticePath, betaNotice, "utf8");
@@ -801,7 +986,8 @@ export function createReviewBundleArtifacts(dbHandle, {
   return {
     bundle_id: manifest.bundle_id,
     output_paths: {
-      bundle_markdown: markdownPath,
+      ...(markdownPath ? { bundle_markdown: markdownPath } : {}),
+      ...(pdfPath ? { bundle_pdf: pdfPath } : {}),
       manifest_json: manifestPath,
       ...(noticePath ? { notice_md: noticePath } : {}),
       ...(feedbackPath ? { feedback_form_md: feedbackPath } : {}),

package/scene-character-batch.js

@@ -0,0 +1,221 @@
+import fs from "node:fs";
+import matter from "gray-matter";
+import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
+
+function escapeRegex(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function normalizeCharacterRows(rows) {
+  const clean = rows
+    .filter(row => row?.character_id && row?.name)
+    .map(row => ({
+      character_id: row.character_id,
+      name: String(row.name).trim(),
+      tokens: [...new Set(String(row.name).toLowerCase().split(/\s+/).filter(Boolean))],
+    }))
+    .filter(row => row.name.length > 0);
+
+  const tokenMap = new Map();
+  for (const row of clean) {
+    for (const token of row.tokens) {
+      if (!token || token.length < 3) continue;
+      const ids = tokenMap.get(token) ?? [];
+      ids.push(row.character_id);
+      tokenMap.set(token, ids);
+    }
+  }
+
+  return { clean, tokenMap };
+}
+
+function inferCharactersFromProse(prose, characterRows) {
+  const { clean, tokenMap } = characterRows;
+  const inferred = new Set();
+  const ambiguous_tokens = [];
+
+  for (const row of clean) {
+    if (row.tokens.length > 1) {
+      const pattern = row.tokens.map(escapeRegex).join("\\s+");
+      const regex = new RegExp(`\\b${pattern}\\b`, "i");
+      if (regex.test(prose)) {
+        inferred.add(row.character_id);
+        continue;
+      }
+    }
+
+    for (const token of row.tokens) {
+      if (!token || token.length < 3) continue;
+      const tokenRegex = new RegExp(`\\b${escapeRegex(token)}\\b`, "i");
+      if (!tokenRegex.test(prose)) continue;
+
+      const tokenIds = tokenMap.get(token) ?? [];
+      if (tokenIds.length === 1) {
+        inferred.add(row.character_id);
+      } else if (!ambiguous_tokens.includes(token)) {
+        ambiguous_tokens.push(token);
+      }
+    }
+  }
+
+  return {
+    inferred_characters: [...inferred],
+    ambiguous_tokens,
+  };
+}
+
+function nextTurn() {
+  return new Promise(resolve => setImmediate(resolve));
+}
+
+function getInterSceneDelayMs() {
+  const raw = Number(process.env.MCP_WRITING_SCENE_CHARACTER_BATCH_DELAY_MS ?? 0);
+  return Number.isFinite(raw) && raw > 0 ? raw : 0;
+}
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function runSceneCharacterBatch({ syncDir, args, onProgress, shouldCancel }) {
+  const {
+    project_id,
+    dry_run = true,
+    replace_mode = "merge",
+    include_match_details = false,
+    project_exists = true,
+    target_scenes = [],
+    character_rows = [],
+  } = args;
+
+  const targetScenes = Array.isArray(target_scenes) ? target_scenes : [];
+  const characterRows = Array.isArray(character_rows) ? character_rows : [];
+  const normalizedCharacterRows = normalizeCharacterRows(characterRows);
+
+  const results = [];
+  let processed_scenes = 0;
+  let scenes_changed = 0;
+  let failed_scenes = 0;
+  let links_added = 0;
+  let links_removed = 0;
+  const interSceneDelayMs = getInterSceneDelayMs();
+
+  const emitProgress = () => {
+    if (typeof onProgress !== "function") return;
+    onProgress({
+      total_scenes: targetScenes.length,
+      processed_scenes,
+      scenes_changed,
+      failed_scenes,
+    });
+  };
+
+  emitProgress();
+
+  for (const scene of targetScenes) {
+    await nextTurn();
+
+    if (typeof shouldCancel === "function" && shouldCancel()) {
+      break;
+    }
+
+    try {
+      const raw = fs.readFileSync(scene.file_path, "utf8");
+      const { content: prose } = matter(raw);
+      const { meta } = readMeta(scene.file_path, syncDir, { writable: !dry_run });
+
+      const before_characters = [...new Set((meta.characters ?? []).map(String).filter(Boolean))];
+      const inference = inferCharactersFromProse(prose, normalizedCharacterRows);
+      const inferred_characters = inference.inferred_characters;
+
+      const afterSet = new Set(before_characters);
+      if (replace_mode === "replace") {
+        afterSet.clear();
+      }
+      for (const characterId of inferred_characters) {
+        afterSet.add(characterId);
+      }
+
+      const after_characters = [...afterSet];
+      const beforeSet = new Set(before_characters);
+      const added = after_characters.filter(id => !beforeSet.has(id));
+      const afterSetLookup = new Set(after_characters);
+      const removed = before_characters.filter(id => !afterSetLookup.has(id));
+      const changed = added.length > 0 || removed.length > 0;
+
+      if (!dry_run && changed) {
+        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
+          ...meta,
+          characters: after_characters,
+        }).meta;
+
+        writeMeta(scene.file_path, updatedMeta);
+      }
+
+      scenes_changed += changed ? 1 : 0;
+      links_added += added.length;
+      links_removed += removed.length;
+
+      const hasInferredMatches = inferred_characters.length > 0;
+      const sceneStatus = changed
+        ? "changed"
+        : (!hasInferredMatches && inference.ambiguous_tokens.length > 0 ? "skipped_ambiguous" : "unchanged");
+
+      results.push({
+        scene_id: scene.scene_id,
+        file_path: scene.file_path,
+        before_characters,
+        inferred_characters,
+        after_characters,
+        added,
+        removed,
+        changed,
+        status: sceneStatus,
+        ...(include_match_details ? { match_details: { ambiguous_tokens: inference.ambiguous_tokens } } : {}),
+      });
+    } catch (error) {
+      failed_scenes += 1;
+      results.push({
+        scene_id: scene.scene_id,
+        file_path: scene.file_path,
+        before_characters: [],
+        inferred_characters: [],
+        after_characters: [],
+        added: [],
+        removed: [],
+        changed: false,
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error),
+      });
+    } finally {
+      processed_scenes += 1;
+      emitProgress();
+      if (interSceneDelayMs > 0) {
+        await delay(interSceneDelayMs);
+      }
+    }
+  }
+
+  const warnings = [];
+  if (failed_scenes > 0) {
+    warnings.push("PARTIAL_SUCCESS: one or more scenes failed to process.");
+  }
+  if (!project_exists && targetScenes.length === 0) {
+    warnings.push(`PROJECT_NOT_FOUND_WARNING: project '${project_id}' was not found; nothing to process.`);
+  }
+
+  return {
+    ok: true,
+    cancelled: Boolean(typeof shouldCancel === "function" && shouldCancel() && processed_scenes < targetScenes.length),
+    project_id,
+    dry_run: Boolean(dry_run),
+    total_scenes: targetScenes.length,
+    processed_scenes,
+    scenes_changed,
+    failed_scenes,
+    links_added,
+    links_removed,
+    results,
+    ...(warnings.length > 0 ? { warning: warnings.join(" ") } : {}),
+  };
+}

package/scripts/profile-review-bundles.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * Profile review-bundle generation performance
+ * Usage: node --experimental-sqlite scripts/profile-review-bundles.mjs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { openDb } from "../db.js";
+import { syncAll } from "../sync.js";
+import { isGitRepository, getHeadCommitHash } from "../git.js";
+import {
+  buildReviewBundlePlan,
+  createReviewBundleArtifacts,
+} from "../review-bundles.js";
+
+const PROJECT_SYNC_DIR = process.env.WRITING_SYNC_DIR ?? process.argv[2] ?? null;
+const DB_PATH = process.env.DB_PATH ?? (PROJECT_SYNC_DIR ? path.join(PROJECT_SYNC_DIR, ".mcp", "writing.db") : null);
+const PROFILES = ["outline_discussion", "editor_detailed", "beta_reader_personalized"];
+
+/**
+ * @typedef {Object} ProfileResult
+ * @property {string} scenario
+ * @property {string} profile
+ * @property {number} sceneCount
+ * @property {number} wordCount
+ * @property {number} durationMs
+ * @property {number} [outputSize]
+ */
+
+/**
+ * @param {string} syncDir
+ * @param {string} projectId
+ * @param {string} profile
+ * @param {Record<string, any>} [filters={}]
+ * @returns {Promise<ProfileResult|null>}
+ */
+async function profileScenario(
+  syncDir,
+  projectId,
+  profile,
+  filters = {}
+) {
+  console.log(
+    `  Profiling ${profile} with ${JSON.stringify(filters || "full project")}...`
+  );
+
+  const db = await openDb(DB_PATH);
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "profile-"));
+
+  try {
+    // Time the planning phase
+    const planStart = performance.now();
+    let plan;
+    try {
+      plan = await buildReviewBundlePlan(db, {
+        project_id: projectId,
+        profile,
+        ...filters,
+      });
+    } catch (err) {
+      console.error(`  ✗ Planning failed: ${err.message}`);
+      return null;
+    }
+    const planMs = performance.now() - planStart;
+
+    // Time the artifact generation phase
+    const createStart = performance.now();
+    try {
+      await createReviewBundleArtifacts(db, {
+        plan,
+        output_dir: tmpDir,
+        syncDir,
+        source_commit: await getHeadCommitHash(syncDir),
+      });
+    } catch (err) {
+      console.error(`  ✗ Creation failed: ${err.message}`);
+      return null;
+    }
+    const createMs = performance.now() - createStart;
+
+    // Measure output size
+    let outputSize = 0;
+    const files = fs.readdirSync(tmpDir);
+    for (const file of files) {
+      const filePath = path.join(tmpDir, file);
+      const stat = fs.statSync(filePath);
+      outputSize += stat.size;
+    }
+
+    const totalMs = planMs + createMs;
+    const sceneCount = plan.ordering?.length ?? 0;
+    const wordCount = plan.summary?.estimated_word_count ?? 0;
+
+    console.log(
+      `    ✓ ${sceneCount} scenes, ~${wordCount.toLocaleString()} words, ${outputSize.toLocaleString()} bytes`
+    );
+    console.log(`    Planning: ${planMs.toFixed(2)}ms, Creation: ${createMs.toFixed(2)}ms, Total: ${totalMs.toFixed(2)}ms`);
+
+    return {
+      scenario: `${projectId} ${Object.keys(filters).length === 0 ? "full" : JSON.stringify(filters)}`,
+      profile,
+      sceneCount,
+      wordCount,
+      durationMs: totalMs,
+      outputSize,
+    };
+  } finally {
+    // Clean up temp directory
+    if (fs.existsSync(tmpDir)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    db.close();
+  }
+}
+
+async function main() {
+  if (!PROJECT_SYNC_DIR) {
+    console.error("✗ WRITING_SYNC_DIR env var or a path argument is required.");
+    console.error("  Usage: WRITING_SYNC_DIR=/path/to/project node --experimental-sqlite scripts/profile-review-bundles.mjs");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(PROJECT_SYNC_DIR)) {
+    console.error(`✗ Project directory not found: ${PROJECT_SYNC_DIR}`);
+    process.exit(1);
+  }
+
+  if (!isGitRepository(PROJECT_SYNC_DIR)) {
+    console.error(`✗ Not a git repository: ${PROJECT_SYNC_DIR}`);
+    process.exit(1);
+  }
+
+  console.log("🔍 Review Bundles Performance Profile");
+  console.log(`   Sync Dir: ${PROJECT_SYNC_DIR}`);
+  console.log(`   Starting: ${new Date().toISOString()}\n`);
+
+  // Sync the database first
+  console.log("📇 Syncing project database...");
+  const syncDb = await openDb(DB_PATH);
+  try {
+    await syncAll(syncDb, PROJECT_SYNC_DIR);
+  } finally {
+    syncDb.close();
+  }
+  console.log("   ✓ Sync complete\n");
+
+  const results = [];
+
+  // Test scenarios for book-1-the-lamb (has 118 scenes)
+  const projectId = "universe-1/book-1-the-lamb";
+
+  console.log(`📖 Profiling ${projectId}:\n`);
+
+  // Scenario 1: Full project with all profiles
+  console.log("Scenario 1: Full project\n");
+  for (const profile of PROFILES) {
+    const result = await profileScenario(PROJECT_SYNC_DIR, projectId, profile);
+    if (result) results.push(result);
+  }
+
+  // Scenario 2: Single chapter (if available)
+  console.log("\nScenario 2: Single chapter (chapter 1)\n");
+  for (const profile of PROFILES) {
+    const result = await profileScenario(PROJECT_SYNC_DIR, projectId, profile, {
+      chapter: 1,
+    });
+    if (result) results.push(result);
+  }
+
+  // Scenario 3: Subset by scene_ids (first 10 scenes)
+  console.log("\nScenario 3: Subset by scene_ids (first 10 scenes)\n");
+  for (const profile of PROFILES) {
+    const result = await profileScenario(PROJECT_SYNC_DIR, projectId, profile, {
+      scene_ids: ["sc-001", "sc-002", "sc-003", "sc-004", "sc-005", "sc-006", "sc-007", "sc-008", "sc-009", "sc-010"],
+    });
+    if (result) results.push(result);
+  }
+
+  // Print summary
+  console.log("\n\n📊 Performance Summary\n");
+  console.log("Profile | Scenario | Scenes | Words | Output (KB) | Duration (ms)");
+  console.log(
+    "--------|----------|--------|-------|-------------|---------------"
+  );
+
+  for (const result of results) {
+    if (!result) continue;
+    const outputKb = (result.outputSize / 1024).toFixed(1);
+    const scenarioShort = result.scenario.replace(/universe-1\//, "").substring(0, 30);
+    console.log(
+      `${result.profile.padEnd(15)} | ${scenarioShort.padEnd(30)} | ${String(result.sceneCount).padEnd(6)} | ${String(result.wordCount).padEnd(5)} | ${outputKb.padEnd(11)} | ${result.durationMs.toFixed(2)}`
+    );
+  }
+
+  // Analysis
+  console.log("\n📈 Analysis:\n");
+
+  const fullProjectResults = results.filter(
+    (r) => r.scenario.includes("full")
+  );
+  const editorResults = fullProjectResults.filter(
+    (r) => r.profile === "editor_detailed"
+  );
+
+  if (editorResults.length > 0) {
+    const editorMs = editorResults[0].durationMs;
+    console.log(`• Full project (editor_detailed): ${editorMs.toFixed(2)}ms`);
+
+    if (editorMs > 5000) {
+      console.log(
+        "  ⚠️  Generation takes > 5s. Async generation would be beneficial."
+      );
+    } else if (editorMs > 1000) {
+      console.log(
+        "  ⚠️  Generation takes 1-5s. Async could improve UX for slow networks."
+      );
+    } else {
+      console.log("  ✓ Generation is fast (< 1s). Sync is sufficient for now.");
+    }
+  }
+
+  console.log(
+    "\n✓ Profile complete: " + new Date().toISOString()
+  );
+}
+
+main().catch((err) => {
+  console.error("✗ Profile failed:", err);
+  process.exit(1);
+});