@hanna84/mcp-writing 1.14.0 → 1.16.0

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.16.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.15.0...v1.16.0)
+
+- feat: add create_review_bundle markdown artifact generation [`#74`](https://github.com/hannasdev/mcp-writing.git
+/pull/74)
+
+#### [v1.15.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.14.0...v1.15.0)
+
+> 24 April 2026
+
+- feat: add review bundle preview planner tool [`#73`](https://github.com/hannasdev/mcp-writing.git
+/pull/73)
+- Release 1.15.0 [`0ec37c6`](https://github.com/hannasdev/mcp-writing.git
+/commit/0ec37c69aa16fb1f4f28e01fae9b864158f1b85e)
+
 #### [v1.14.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.13.2...v1.14.0)
 
+> 24 April 2026
+
 - feat(scrivener-direct): graduate from beta to stable [`#72`](https://github.com/hannasdev/mcp-writing.git
 /pull/72)
+- Release 1.14.0 [`4baf0c3`](https://github.com/hannasdev/mcp-writing.git
+/commit/4baf0c38eed39337a58c8503d382dc1db6987c6a)
 
 #### [v1.13.2](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.13.1...v1.13.2)

package/index.js

@@ -13,10 +13,17 @@ import yaml from "js-yaml";
 import { z } from "zod";
 import { openDb } from "./db.js";
 import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, getFileWriteDiagnostics, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
-import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
+import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit, getHeadCommitHash } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { importScrivenerSync, validateProjectId } from "./importer.js";
 import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
+import {
+  REVIEW_BUNDLE_PROFILES,
+  REVIEW_BUNDLE_STRICTNESS,
+  ReviewBundlePlanError,
+  buildReviewBundlePlan,
+  createReviewBundleArtifacts,
+} from "./review-bundles.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -44,6 +51,47 @@ function isPathInsideSyncDir(candidatePath) {
   return !(rel.startsWith("..") || path.isAbsolute(rel));
 }
 
+function resolveOutputDirWithinSync(outputDir) {
+  let resolvedOutputDir = path.resolve(outputDir);
+  let existingAncestor = resolvedOutputDir;
+
+  while (!fs.existsSync(existingAncestor)) {
+    const parentDir = path.dirname(existingAncestor);
+    if (parentDir === existingAncestor) {
+      throw new ReviewBundlePlanError(
+        "INVALID_OUTPUT_DIR",
+        "output_dir must be inside WRITING_SYNC_DIR.",
+        { output_dir: resolvedOutputDir, sync_dir: SYNC_DIR_ABS }
+      );
+    }
+    existingAncestor = parentDir;
+  }
+
+  let realExistingAncestor;
+  try {
+    realExistingAncestor = fs.realpathSync.native(existingAncestor);
+  } catch (err) {
+    throw new ReviewBundlePlanError(
+      "INVALID_OUTPUT_DIR",
+      "output_dir ancestor could not be resolved: path may be inaccessible.",
+      { output_dir: outputDir, existing_ancestor: existingAncestor, cause: err.message }
+    );
+  }
+  const relativeFromAncestor = path.relative(existingAncestor, resolvedOutputDir);
+  resolvedOutputDir = path.resolve(realExistingAncestor, relativeFromAncestor);
+
+  const relativeToSyncDir = path.relative(SYNC_DIR_REAL, resolvedOutputDir);
+  if (relativeToSyncDir.startsWith("..") || path.isAbsolute(relativeToSyncDir)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_OUTPUT_DIR",
+      "output_dir must be inside WRITING_SYNC_DIR.",
+      { output_dir: resolvedOutputDir, sync_dir: SYNC_DIR_ABS }
+    );
+  }
+
+  return { resolvedOutputDir, relativeToSyncDir };
+}
+
 function parsePositiveIntEnv(rawValue, defaultValue) {
   const parsed = parseInt(rawValue ?? String(defaultValue), 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
@@ -1298,6 +1346,180 @@ 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.",
+    {
+      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 or editor_detailed."),
+      part: z.number().int().optional().describe("Optional part filter."),
+      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      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."),
+      bundle_name: z.string().optional().describe("Optional output bundle base name override (slugified in planned outputs)."),
+    },
+    async ({
+      project_id,
+      profile,
+      part,
+      chapter,
+      tag,
+      scene_ids,
+      strictness = "warn",
+      include_scene_ids = true,
+      include_metadata_sidebar = false,
+      include_paragraph_anchors = false,
+      bundle_name,
+    }) => {
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      try {
+        const plan = buildReviewBundlePlan(db, {
+          project_id,
+          profile,
+          part,
+          chapter,
+          tag,
+          scene_ids,
+          strictness,
+          include_scene_ids,
+          include_metadata_sidebar,
+          include_paragraph_anchors,
+          bundle_name,
+        });
+        return jsonResponse(plan);
+      } catch (error) {
+        if (error instanceof ReviewBundlePlanError) {
+          return errorResponse(error.code, error.message, error.details);
+        }
+        return errorResponse(
+          "PREVIEW_FAILED",
+          error instanceof Error ? error.message : "Failed to generate review bundle preview."
+        );
+      }
+    }
+  );
+
+  // ---- 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.",
+    {
+      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 or editor_detailed."),
+      output_dir: z.string().describe("Directory path to write bundle artifacts into."),
+      part: z.number().int().optional().describe("Optional part filter."),
+      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      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)."),
+      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."),
+    },
+    async ({
+      project_id,
+      profile,
+      output_dir,
+      part,
+      chapter,
+      tag,
+      scene_ids,
+      strictness = "warn",
+      include_scene_ids = true,
+      include_metadata_sidebar = false,
+      include_paragraph_anchors = false,
+      bundle_name,
+      source_commit,
+    }) => {
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      try {
+        const { resolvedOutputDir, relativeToSyncDir } = resolveOutputDirWithinSync(output_dir);
+        const outputDirSegments = relativeToSyncDir
+          .split(path.sep)
+          .filter(Boolean)
+          .map(segment => segment.toLowerCase());
+        if (outputDirSegments.includes("scenes")) {
+          return errorResponse(
+            "INVALID_OUTPUT_DIR",
+            "output_dir cannot be inside a scenes directory. Choose a dedicated export folder under WRITING_SYNC_DIR.",
+            { output_dir: resolvedOutputDir }
+          );
+        }
+
+        const plan = buildReviewBundlePlan(db, {
+          project_id,
+          profile,
+          part,
+          chapter,
+          tag,
+          scene_ids,
+          strictness,
+          include_scene_ids,
+          include_metadata_sidebar,
+          include_paragraph_anchors,
+          bundle_name,
+        });
+
+        if (!plan.strictness_result.can_proceed) {
+          return errorResponse(
+            "STRICTNESS_BLOCKED",
+            "Bundle generation blocked by strictness policy.",
+            { strictness_result: plan.strictness_result, warning_summary: plan.warning_summary }
+          );
+        }
+
+        const provenanceCommit = source_commit ?? (GIT_ENABLED ? getHeadCommitHash(SYNC_DIR) : null);
+        const artifacts = createReviewBundleArtifacts(db, {
+          plan,
+          output_dir: resolvedOutputDir,
+          source_commit: provenanceCommit,
+          syncDir: SYNC_DIR_ABS,
+        });
+
+        return jsonResponse({
+          ok: true,
+          bundle_id: artifacts.bundle_id,
+          output_paths: artifacts.output_paths,
+          summary: {
+            scene_count: plan.summary.scene_count,
+            profile: plan.profile,
+            applied_filters: plan.resolved_scope.filters,
+          },
+          warnings: plan.warnings,
+          warning_summary: plan.warning_summary,
+          provenance: {
+            source_commit: provenanceCommit,
+            generated_at: artifacts.generated_at,
+            project_id: plan.resolved_scope.project_id,
+          },
+        });
+      } catch (error) {
+        if (error instanceof ReviewBundlePlanError) {
+          return errorResponse(error.code, error.message, error.details);
+        }
+        return errorResponse(
+          "CREATE_BUNDLE_FAILED",
+          error instanceof Error ? error.message : "Failed to create review bundle artifacts."
+        );
+      }
+    }
+  );
+
   // ---- find_scenes ---------------------------------------------------------
   s.tool(
     "find_scenes",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -14,6 +14,7 @@
     "git.js",
     "world-entity-templates.js",
     "metadata-lint.js",
+    "review-bundles.js",
     "scripts/",
     "README.md",
     "CHANGELOG.md"

package/review-bundles.js

@@ -0,0 +1,705 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+
+const MAX_SORT_VALUE = Number.MAX_SAFE_INTEGER;
+
+export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed"];
+export const REVIEW_BUNDLE_STRICTNESS = ["warn", "fail"];
+
+export class ReviewBundlePlanError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = "ReviewBundlePlanError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function normalizeSortNumber(value) {
+  return Number.isInteger(value) ? value : MAX_SORT_VALUE;
+}
+
+function sceneSort(a, b) {
+  const partDiff = normalizeSortNumber(a.part) - normalizeSortNumber(b.part);
+  if (partDiff !== 0) return partDiff;
+
+  const chapterDiff = normalizeSortNumber(a.chapter) - normalizeSortNumber(b.chapter);
+  if (chapterDiff !== 0) return chapterDiff;
+
+  const timelineDiff = normalizeSortNumber(a.timeline_position) - normalizeSortNumber(b.timeline_position);
+  if (timelineDiff !== 0) return timelineDiff;
+
+  return String(a.scene_id).localeCompare(String(b.scene_id));
+}
+
+function buildWarningSummary(warnings) {
+  const summary = {};
+  for (const warning of warnings) {
+    const type = warning.type ?? "unknown";
+    if (!summary[type]) {
+      summary[type] = { count: 0, examples: [] };
+    }
+    summary[type].count += 1;
+    if (summary[type].examples.length < 5) {
+      summary[type].examples.push(warning.message);
+    }
+  }
+  return summary;
+}
+
+function slugifyBundleName(value) {
+  const slug = String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "review-bundle";
+}
+
+function escapeMarkdown(text) {
+  return String(text ?? "")
+    .replace(/\\/g, "\\\\")
+    .replace(/([*_`\[\]#])/g, "\\$1");
+}
+
+function resolveOutputFilePath(outputDir, fileName) {
+  const normalizedOutputDir = path.resolve(outputDir);
+  const target = path.resolve(normalizedOutputDir, fileName);
+  const rel = path.relative(normalizedOutputDir, target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_OUTPUT_PATH",
+      `Output file '${fileName}' resolves outside output_dir.`,
+      { output_dir: normalizedOutputDir, file_name: fileName }
+    );
+  }
+  return target;
+}
+
+function assertProfile(profile) {
+  if (!REVIEW_BUNDLE_PROFILES.includes(profile)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_PROFILE",
+      `Unsupported review bundle profile '${profile}'.`,
+      { supported_profiles: REVIEW_BUNDLE_PROFILES }
+    );
+  }
+}
+
+function assertStrictness(strictness) {
+  if (!REVIEW_BUNDLE_STRICTNESS.includes(strictness)) {
+    throw new ReviewBundlePlanError(
+      "INVALID_STRICTNESS",
+      `Unsupported strictness '${strictness}'.`,
+      { supported_strictness: REVIEW_BUNDLE_STRICTNESS }
+    );
+  }
+}
+
+function resolveRequestedSceneIds(dbHandle, projectId, sceneIds) {
+  if (!Array.isArray(sceneIds) || sceneIds.length === 0) {
+    return { requested: [], existing: new Set() };
+  }
+
+  const placeholders = sceneIds.map(() => "?").join(",");
+  const rows = dbHandle.prepare(
+    `SELECT scene_id FROM scenes WHERE project_id = ? AND scene_id IN (${placeholders})`
+  ).all(projectId, ...sceneIds);
+
+  return {
+    requested: sceneIds,
+    existing: new Set(rows.map(row => row.scene_id)),
+  };
+}
+
+export function buildReviewBundlePlan(dbHandle, {
+  project_id,
+  profile,
+  part,
+  chapter,
+  tag,
+  scene_ids,
+  strictness = "warn",
+  include_scene_ids = true,
+  include_metadata_sidebar = false,
+  include_paragraph_anchors = false,
+  bundle_name,
+} = {}) {
+  if (!project_id) {
+    throw new ReviewBundlePlanError("INVALID_PROJECT_ID", "project_id is required.");
+  }
+
+  assertProfile(profile);
+  assertStrictness(strictness);
+
+  const projectRow = dbHandle.prepare(`SELECT project_id FROM projects WHERE project_id = ?`).get(project_id);
+  if (!projectRow) {
+    throw new ReviewBundlePlanError("NOT_FOUND", `Project '${project_id}' not found.`);
+  }
+
+  const requestedSceneIds = resolveRequestedSceneIds(dbHandle, project_id, scene_ids);
+  const conditions = ["s.project_id = ?"];
+  const params = [project_id];
+  const joins = [];
+
+  if (tag) {
+    joins.push("JOIN scene_tags st ON st.scene_id = s.scene_id AND st.tag = ?");
+    params.push(tag);
+  }
+  if (Array.isArray(scene_ids) && scene_ids.length > 0) {
+    const placeholders = scene_ids.map(() => "?").join(",");
+    conditions.push(`s.scene_id IN (${placeholders})`);
+    params.push(...scene_ids);
+  }
+  if (part !== undefined) {
+    conditions.push("s.part = ?");
+    params.push(part);
+  }
+  if (chapter !== undefined) {
+    conditions.push("s.chapter = ?");
+    params.push(chapter);
+  }
+
+  let query = `
+    SELECT DISTINCT
+      s.scene_id,
+      s.project_id,
+      s.title,
+      s.part,
+      s.chapter,
+      s.timeline_position,
+      s.word_count,
+      s.logline,
+      s.pov,
+      s.save_the_cat_beat,
+      s.metadata_stale
+    FROM scenes s
+  `;
+
+  if (joins.length > 0) {
+    query += ` ${joins.join(" ")}`;
+  }
+  query += ` WHERE ${conditions.join(" AND ")}`;
+
+  const rows = dbHandle.prepare(query).all(...params).sort(sceneSort);
+  if (rows.length === 0) {
+    throw new ReviewBundlePlanError(
+      "NO_RESULTS",
+      "No scenes matched the requested review bundle scope.",
+      {
+        project_id,
+        filters: {
+          ...(part !== undefined ? { part } : {}),
+          ...(chapter !== undefined ? { chapter } : {}),
+          ...(tag ? { tag } : {}),
+          ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
+        },
+      }
+    );
+  }
+
+  const includedSceneIds = new Set(rows.map(row => row.scene_id));
+  const excludedSceneIds = requestedSceneIds.requested.filter(sceneId => !includedSceneIds.has(sceneId));
+  const notFoundSceneIds = requestedSceneIds.requested.filter(sceneId => !requestedSceneIds.existing.has(sceneId));
+  const filteredOutSceneIds = excludedSceneIds.filter(sceneId => requestedSceneIds.existing.has(sceneId));
+
+  const warnings = [];
+
+  if (notFoundSceneIds.length > 0) {
+    warnings.push({
+      type: "requested_scene_ids_not_found",
+      message: `${notFoundSceneIds.length} requested scene_id value(s) do not exist in project '${project_id}'.`,
+      scene_ids: notFoundSceneIds,
+    });
+  }
+
+  if (filteredOutSceneIds.length > 0) {
+    warnings.push({
+      type: "requested_scene_ids_filtered_out",
+      message: `${filteredOutSceneIds.length} requested scene_id value(s) were excluded by additional filters.`,
+      scene_ids: filteredOutSceneIds,
+    });
+  }
+
+  const staleRows = rows.filter(row => Number(row.metadata_stale) === 1);
+  if (staleRows.length > 0) {
+    warnings.push({
+      type: "metadata_stale",
+      message: `${staleRows.length} scene(s) have stale metadata and may need re-enrichment before editorial use.`,
+      count: staleRows.length,
+    });
+  }
+
+  const missingOrderingRows = rows.filter(
+    row => row.part == null || row.chapter == null || row.timeline_position == null
+  );
+  if (missingOrderingRows.length > 0) {
+    warnings.push({
+      type: "missing_ordering_fields",
+      message: `${missingOrderingRows.length} scene(s) are missing part/chapter/timeline_position metadata; fallback ordering was applied.`,
+      count: missingOrderingRows.length,
+    });
+  }
+
+  const missingWordCountRows = rows.filter(row => row.word_count == null);
+  if (missingWordCountRows.length > 0) {
+    warnings.push({
+      type: "missing_word_count",
+      message: `${missingWordCountRows.length} scene(s) are missing word_count; estimated_word_count may be low.`,
+      count: missingWordCountRows.length,
+    });
+  }
+
+  const blockers = [];
+  if (strictness === "fail" && staleRows.length > 0) {
+    blockers.push({
+      code: "STALE_METADATA",
+      message: `${staleRows.length} scene(s) are marked metadata_stale.`,
+      scene_ids: staleRows.map(row => row.scene_id),
+    });
+  }
+
+  const estimatedWordCount = rows.reduce((sum, row) => {
+    const count = Number(row.word_count);
+    return sum + (Number.isFinite(count) ? count : 0);
+  }, 0);
+
+  const safeBundleName = slugifyBundleName(bundle_name || `${project_id}-${profile}`);
+  const appliedFilters = {
+    ...(part !== undefined ? { part } : {}),
+    ...(chapter !== undefined ? { chapter } : {}),
+    ...(tag ? { tag } : {}),
+    ...(Array.isArray(scene_ids) ? { scene_ids } : {}),
+  };
+
+  return {
+    ok: true,
+    profile,
+    resolved_scope: {
+      project_id,
+      filters: appliedFilters,
+      options: {
+        include_scene_ids: Boolean(include_scene_ids),
+        include_metadata_sidebar: Boolean(include_metadata_sidebar),
+        include_paragraph_anchors: Boolean(include_paragraph_anchors),
+      },
+    },
+    ordering: rows.map(row => ({
+      scene_id: row.scene_id,
+      project_id: row.project_id,
+      title: row.title,
+      part: row.part,
+      chapter: row.chapter,
+      timeline_position: row.timeline_position,
+      metadata_stale: Number(row.metadata_stale) === 1,
+    })),
+    summary: {
+      scene_count: rows.length,
+      estimated_word_count: estimatedWordCount,
+      excluded_scene_ids: excludedSceneIds,
+    },
+    warnings,
+    warning_summary: buildWarningSummary(warnings),
+    strictness_result: {
+      strictness,
+      can_proceed: blockers.length === 0,
+      blockers,
+    },
+    planned_outputs: [
+      `${safeBundleName}.md`,
+      `${safeBundleName}.manifest.json`,
+    ],
+  };
+}
+
+function loadBundleSceneRows(dbHandle, projectId, sceneIds) {
+  if (!Array.isArray(sceneIds) || sceneIds.length === 0) return [];
+  const rows = [];
+  // 900 is safely below SQLite's per-query bound of 999 host parameters
+  // (one slot is used by the project_id binding, leaving 998 for scene_id placeholders;
+  // 900 gives extra headroom for any future additions to the query).
+  const chunkSize = 900;
+  for (let offset = 0; offset < sceneIds.length; offset += chunkSize) {
+    const chunk = sceneIds.slice(offset, offset + chunkSize);
+    const placeholders = chunk.map(() => "?").join(",");
+    const chunkRows = dbHandle.prepare(`
+      SELECT
+        scene_id,
+        project_id,
+        title,
+        part,
+        chapter,
+        timeline_position,
+        logline,
+        pov,
+        save_the_cat_beat,
+        file_path
+      FROM scenes
+      WHERE project_id = ? AND scene_id IN (${placeholders})
+    `).all(projectId, ...chunk);
+    rows.push(...chunkRows);
+  }
+
+  const rowMap = new Map(rows.map(row => [row.scene_id, row]));
+  const orderedRows = [];
+  const missingSceneIds = [];
+
+  for (const sceneId of sceneIds) {
+    const row = rowMap.get(sceneId);
+    if (row) {
+      orderedRows.push(row);
+    } else {
+      missingSceneIds.push(sceneId);
+    }
+  }
+
+  if (missingSceneIds.length > 0) {
+    throw new ReviewBundlePlanError(
+      "MISSING_SCENE_ROWS",
+      `Bundle includes ${missingSceneIds.length} scene(s) that could not be loaded from the database.`,
+      {
+        project_id: projectId,
+        missing_scene_ids: missingSceneIds,
+        requested_scene_count: sceneIds.length,
+        resolved_scene_count: orderedRows.length,
+      }
+    );
+  }
+
+  return orderedRows;
+}
+
+function normalizeRelativePath(inputPath) {
+  return String(inputPath).replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function resolveSceneFilePath(filePath, { syncDir } = {}) {
+  if (!filePath || !syncDir) return null;
+
+  const normalizedSyncDir = path.resolve(syncDir);
+  let realSyncDir;
+  try {
+    realSyncDir = fs.realpathSync.native(normalizedSyncDir);
+  } catch {
+    return null;
+  }
+
+  const rel = normalizeRelativePath(filePath);
+  const candidates = [];
+
+  if (path.isAbsolute(filePath)) {
+    // Canonicalize the absolute path (resolve symlinks) so the boundary check
+    // works correctly even when syncDir itself contains a symlink component
+    // (e.g. macOS /var → /private/var or /tmp → /private/tmp).
+    const resolvedAbsolute = path.resolve(filePath);
+    let canonicalAbsolute;
+
+    if (fs.existsSync(resolvedAbsolute)) {
+      try {
+        canonicalAbsolute = fs.realpathSync.native(resolvedAbsolute);
+      } catch {
+        // Cannot canonicalize — skip this candidate.
+      }
+    } else {
+      // File doesn't exist yet; walk up to the nearest existing ancestor,
+      // canonicalize that, then reconstruct the full path.
+      let ancestor = resolvedAbsolute;
+      const segments = [];
+      while (!fs.existsSync(ancestor)) {
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor) { ancestor = null; break; }
+        segments.unshift(path.basename(ancestor));
+        ancestor = parent;
+      }
+      if (ancestor) {
+        try {
+          const realAncestor = fs.realpathSync.native(ancestor);
+          canonicalAbsolute = path.resolve(realAncestor, ...segments);
+        } catch {
+          // Cannot canonicalize.
+        }
+      }
+    }
+
+    if (canonicalAbsolute) {
+      const relFromSync = path.relative(realSyncDir, canonicalAbsolute);
+      if (!relFromSync.startsWith("..") && !path.isAbsolute(relFromSync)) {
+        candidates.push(canonicalAbsolute);
+      }
+    }
+  } else {
+    candidates.push(path.resolve(realSyncDir, rel));
+    // Scrivener External Folder Sync sometimes stores paths prefixed with
+    // "sync/" (the name of the sync folder itself) relative to the project
+    // root. Strip that prefix so we can find the file within realSyncDir.
+    if (rel === "sync" || rel.startsWith("sync/")) {
+      candidates.push(path.resolve(realSyncDir, rel.replace(/^sync\/?/, "")));
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) {
+      // Before returning a non-existent path, verify it is still inside realSyncDir.
+      // A relative filePath with .. segments could otherwise escape the boundary.
+      const relFromSync = path.relative(realSyncDir, candidate);
+      if (!relFromSync.startsWith("..") && !path.isAbsolute(relFromSync)) {
+        return candidate;
+      }
+      continue;
+    }
+
+    // File exists: validate realpath stays inside syncDir to catch symlink escapes.
+    // (For absolute paths this is already canonicalized; for relative paths, verify.)
+    try {
+      const realCandidate = fs.realpathSync.native(candidate);
+      const relReal = path.relative(realSyncDir, realCandidate);
+      if (!relReal.startsWith("..") && !path.isAbsolute(relReal)) {
+        return realCandidate;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return null;
+}
+
+function readProse(filePath, { syncDir } = {}) {
+  const resolvedPath = resolveSceneFilePath(filePath, { syncDir });
+  if (!resolvedPath) return null;
+  try {
+    const raw = fs.readFileSync(resolvedPath, "utf8");
+    return matter(raw).content.trim();
+  } catch (error) {
+    const errorCode = error && typeof error === "object" && "code" in error && typeof error.code === "string"
+      ? error.code
+      : null;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new ReviewBundlePlanError(
+      "SCENE_PROSE_READ_FAILED",
+      `Failed to read scene prose from ${resolvedPath}.`,
+      {
+        file_path: filePath,
+        resolved_path: resolvedPath,
+        error_code: errorCode,
+        cause: errorMessage,
+      }
+    );
+  }
+}
+
+function renderSceneBlock(scene, options) {
+  const {
+    profile,
+    includeSceneIds,
+    includeMetadataSidebar,
+    includeParagraphAnchors,
+  } = options;
+
+  const title = scene.title || scene.scene_id;
+  const sceneHeading = includeSceneIds
+    ? `## ${escapeMarkdown(title)} (${escapeMarkdown(scene.scene_id)})`
+    : `## ${escapeMarkdown(title)}`;
+
+  const parts = [sceneHeading];
+
+  if (profile === "outline_discussion") {
+    const summaryParts = [];
+    if (scene.pov) summaryParts.push(`POV: ${scene.pov}`);
+    if (scene.save_the_cat_beat) summaryParts.push(`Beat: ${scene.save_the_cat_beat}`);
+    if (scene.part != null) summaryParts.push(`Part: ${scene.part}`);
+    if (scene.chapter != null) summaryParts.push(`Chapter: ${scene.chapter}`);
+    if (summaryParts.length > 0) {
+      parts.push(`_${escapeMarkdown(summaryParts.join(" | "))}_`);
+    }
+    if (scene.logline) {
+      parts.push(escapeMarkdown(scene.logline.trim()));
+    }
+    return parts.join("\n\n");
+  }
+
+  if (includeMetadataSidebar) {
+    const sidebar = [
+      scene.part != null ? `part: ${scene.part}` : null,
+      scene.chapter != null ? `chapter: ${scene.chapter}` : null,
+      scene.timeline_position != null ? `timeline_position: ${scene.timeline_position}` : null,
+      scene.pov ? `pov: ${escapeMarkdown(scene.pov)}` : null,
+      scene.save_the_cat_beat ? `beat: ${escapeMarkdown(scene.save_the_cat_beat)}` : null,
+    ].filter(Boolean);
+    if (sidebar.length > 0) {
+      parts.push(`> ${sidebar.join("  \\\n> ")}`);
+    }
+  }
+
+  const prose = scene.prose ?? "";
+  if (!includeParagraphAnchors || prose.length === 0) {
+    parts.push(prose);
+    return parts.join("\n\n");
+  }
+
+  const paragraphs = prose
+    .split(/\n\s*\n/g)
+    .map(p => p.trim())
+    .filter(Boolean);
+  // Sanitize scene_id for safe embedding in an HTML comment: restrict to
+  // alphanumerics, hyphens, underscores, and dots to prevent "-->" or other
+  // sequences from prematurely terminating the comment.
+  const safeSceneId = scene.scene_id.replace(/[^a-zA-Z0-9\-_.]/g, "_");
+  const anchoredParagraphs = paragraphs.map((paragraph, index) => {
+    return `<!-- ${safeSceneId}:p${index + 1} -->\n${paragraph}`;
+  });
+  parts.push(anchoredParagraphs.join("\n\n"));
+  return parts.join("\n\n");
+}
+
+export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir: syncDirOpt } = {}) {
+  const profile = plan.profile;
+  const includeSceneIds = Boolean(plan.resolved_scope?.options?.include_scene_ids);
+  const includeMetadataSidebar = Boolean(plan.resolved_scope?.options?.include_metadata_sidebar);
+  const includeParagraphAnchors = Boolean(plan.resolved_scope?.options?.include_paragraph_anchors);
+  // Prefer explicitly threaded syncDir; fall back to env (with "./sync" default matching index.js).
+  // Prefer explicitly threaded syncDir; fall back to env.
+  // No further fallback: if syncDir is null, resolveSceneFilePath returns null
+  // and SCENE_PROSE_READ_FAILED is thrown, making misconfiguration explicit.
+  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 sections = [];
+
+  const headerLines = [
+    `# Review Bundle: ${escapeMarkdown(plan.resolved_scope.project_id)}`,
+    "",
+    `- Profile: ${profile}`,
+    `- Generated at: ${generatedAt ?? new Date().toISOString()}`,
+    `- Scene count: ${plan.summary.scene_count}`,
+  ];
+  sections.push(headerLines.join("\n"));
+
+  for (const scene of rows) {
+    let prose = "";
+    if (profile === "editor_detailed") {
+      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 withProse = { ...scene, prose };
+    sections.push(renderSceneBlock(withProse, {
+      profile,
+      includeSceneIds,
+      includeMetadataSidebar,
+      includeParagraphAnchors,
+    }));
+  }
+
+  return sections.join("\n\n---\n\n").trim() + "\n";
+}
+
+export function createReviewBundleArtifacts(dbHandle, {
+  plan,
+  output_dir,
+  source_commit = null,
+  syncDir,
+}) {
+  if (!output_dir) {
+    throw new ReviewBundlePlanError("INVALID_OUTPUT_DIR", "output_dir is required.");
+  }
+
+  const normalizedOutputDir = path.resolve(output_dir);
+  if (fs.existsSync(normalizedOutputDir)) {
+    if (!fs.statSync(normalizedOutputDir).isDirectory()) {
+      throw new ReviewBundlePlanError(
+        "INVALID_OUTPUT_DIR",
+        `output_dir exists but is not a directory: ${normalizedOutputDir}`
+      );
+    }
+  } else {
+    fs.mkdirSync(normalizedOutputDir, { recursive: true });
+  }
+  try {
+    fs.accessSync(normalizedOutputDir, fs.constants.W_OK);
+  } catch {
+    throw new ReviewBundlePlanError(
+      "INVALID_OUTPUT_DIR",
+      `output_dir is not writable: ${normalizedOutputDir}`
+    );
+  }
+
+  const markdownFileName = plan.planned_outputs.find(name => name.endsWith(".md"));
+  const manifestFileName = plan.planned_outputs.find(name => name.endsWith(".manifest.json"));
+  if (!markdownFileName || !manifestFileName) {
+    throw new ReviewBundlePlanError(
+      "INVALID_PLAN_OUTPUTS",
+      "Plan is missing expected markdown/manifest filenames."
+    );
+  }
+
+  const markdownPath = resolveOutputFilePath(normalizedOutputDir, markdownFileName);
+  const manifestPath = resolveOutputFilePath(normalizedOutputDir, manifestFileName);
+
+  const generatedAt = new Date().toISOString();
+  const markdown = renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDir });
+  const manifest = {
+    bundle_id: path.basename(markdownFileName, ".md"),
+    profile: plan.profile,
+    generated_at: generatedAt,
+    provenance: {
+      source_commit: source_commit ?? null,
+      project_id: plan.resolved_scope.project_id,
+    },
+    summary: plan.summary,
+    warning_summary: plan.warning_summary,
+    warnings: plan.warnings,
+    resolved_scope: plan.resolved_scope,
+    scene_ids: plan.ordering.map(row => row.scene_id),
+  };
+
+  for (const outputPath of [markdownPath, manifestPath]) {
+    try {
+      const stat = fs.lstatSync(outputPath);
+      if (stat.isSymbolicLink()) {
+        throw new ReviewBundlePlanError(
+          "INVALID_OUTPUT_PATH",
+          `Refusing to write: target path is a symlink: ${outputPath}`
+        );
+      }
+      if (!stat.isFile()) {
+        throw new ReviewBundlePlanError(
+          "INVALID_OUTPUT_PATH",
+          `Refusing to write: target path exists but is not a regular file: ${outputPath}`
+        );
+      }
+    } catch (error) {
+      if (error instanceof ReviewBundlePlanError) throw error;
+      if (error?.code !== "ENOENT") throw error;
+      // ENOENT — file doesn't exist yet, which is the expected case.
+      // Note: there is an inherent TOCTOU window between this lstat check and the
+      // writeFileSync below. This is acceptable for a local tool where the caller
+      // controls the output directory.
+    }
+  }
+
+  fs.writeFileSync(markdownPath, markdown, "utf8");
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+
+  return {
+    bundle_id: manifest.bundle_id,
+    output_paths: {
+      bundle_markdown: markdownPath,
+      manifest_json: manifestPath,
+    },
+    generated_at: generatedAt,
+  };
+
+}

package/scripts/manual/run_create_review_bundle.js

@@ -0,0 +1,64 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import path from "path";
+import process from "process";
+
+async function main() {
+  const [projectId, profile, outputDir, ...flags] = process.argv.slice(2);
+  if (!projectId || !profile || !outputDir) {
+    console.error("Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_create_review_bundle.js <project_id> <profile> <output_dir> [--anchors] [--bundle-name <name>]");
+    process.exit(1);
+  }
+
+  if (!process.env.WRITING_SYNC_DIR) {
+    console.error(
+      "WRITING_SYNC_DIR is required. Set it to the root of your sync directory.\n" +
+      "Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_create_review_bundle.js <project_id> <profile> <output_dir>"
+    );
+    process.exit(1);
+  }
+
+  const includeParagraphAnchors = flags.includes("--anchors");
+  const bundleNameIdx = flags.indexOf("--bundle-name");
+  const bundleName = bundleNameIdx !== -1 ? flags[bundleNameIdx + 1] : undefined;
+
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: ["--experimental-sqlite", path.join(process.cwd(), "index.js")],
+    env: {
+      ...process.env,
+      MCP_TRANSPORT: "stdio",
+      WRITING_SYNC_DIR: process.env.WRITING_SYNC_DIR
+    }
+  });
+
+  const client = new Client({
+    name: "test-client",
+    version: "1.0.0"
+  }, {
+    capabilities: {}
+  });
+
+  try {
+    await client.connect(transport);
+    const result = await client.callTool({
+      name: "create_review_bundle",
+      arguments: {
+        project_id: projectId,
+        profile: profile,
+        output_dir: outputDir,
+        ...(includeParagraphAnchors ? { include_paragraph_anchors: true } : {}),
+        ...(bundleName ? { bundle_name: bundleName } : {})
+      }
+    });
+
+    console.log(JSON.stringify(result, null, 2));
+  } catch (e) {
+    console.error(e);
+    process.exitCode = 1;
+  } finally {
+    process.exit(process.exitCode ?? 0);
+  }
+}
+
+main();

package/scripts/manual/run_mcp_and_review.js

@@ -0,0 +1,78 @@
+import path from "node:path";
+import process from "node:process";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+async function callCreateBundle(client, args) {
+  const result = await client.callTool({
+    name: "create_review_bundle",
+    arguments: args,
+  });
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function main() {
+  const [projectId, outputDirArg] = process.argv.slice(2);
+  const envWritingSyncDir = process.env.WRITING_SYNC_DIR;
+
+  if (!projectId) {
+    console.error(
+      "Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_mcp_and_review.js <projectId> [outputDir]"
+    );
+    process.exit(1);
+  }
+
+  if (!envWritingSyncDir) {
+    console.error(
+      "WRITING_SYNC_DIR is required. Set it to the root of your sync directory.\n" +
+      "Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_mcp_and_review.js <projectId> [outputDir]"
+    );
+    process.exit(1);
+  }
+
+  const outputDir = outputDirArg || path.join(envWritingSyncDir, "exports");
+  const writingSyncDir = envWritingSyncDir;
+
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: ["--experimental-sqlite", path.join(process.cwd(), "index.js")],
+    env: {
+      ...process.env,
+      MCP_TRANSPORT: "stdio",
+      WRITING_SYNC_DIR: writingSyncDir,
+    },
+  });
+
+  const client = new Client(
+    { name: "manual-review-runner", version: "1.0.0" },
+    { capabilities: {} }
+  );
+
+  try {
+    await client.connect(transport);
+
+    console.log("Calling create_review_bundle (outline_discussion)...");
+    await callCreateBundle(client, {
+      project_id: projectId,
+      profile: "outline_discussion",
+      output_dir: outputDir,
+      bundle_name: "real-outline",
+    });
+
+    console.log("Calling create_review_bundle (editor_detailed)...");
+    await callCreateBundle(client, {
+      project_id: projectId,
+      profile: "editor_detailed",
+      include_paragraph_anchors: true,
+      output_dir: outputDir,
+      bundle_name: "real-editor",
+    });
+  } catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+  } finally {
+    process.exit(process.exitCode ?? 0);
+  }
+}
+
+main();