@hanna84/mcp-writing 1.16.2 → 2.0.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).
 
+#### [v2.0.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v1.17.0...v2.0.0)
+
+- feat(review-bundles)!: add PDF export via pdfkit [`#78`](https://github.com/hannasdev/mcp-writing.git
+/pull/78)
+
+#### [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)
 
+> 25 April 2026
+
 - docs: close out review bundles M1 and add troubleshooting guidance [`#76`](https://github.com/hannasdev/mcp-writing.git
 /pull/76)
+- Release 1.16.2 [`557623a`](https://github.com/hannasdev/mcp-writing.git
+/commit/557623afb18e4f5f5dbec565eee1cbd481051275)
 
 #### [v1.16.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v1.16.0...v1.16.1)

package/index.js

@@ -1349,19 +1349,21 @@ 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 or editor_detailed."),
+      profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       part: z.number().int().optional().describe("Optional part filter."),
       chapter: z.number().int().optional().describe("Optional 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."),
+      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,
@@ -1374,7 +1376,9 @@ function createMcpServer() {
       include_scene_ids = true,
       include_metadata_sidebar = false,
       include_paragraph_anchors = false,
+      recipient_name,
       bundle_name,
+      format = "pdf",
     }) => {
       const projectIdCheck = validateProjectId(project_id);
       if (!projectIdCheck.ok) {
@@ -1393,7 +1397,9 @@ function createMcpServer() {
           include_scene_ids,
           include_metadata_sidebar,
           include_paragraph_anchors,
+          recipient_name,
           bundle_name,
+          format,
         });
         return jsonResponse(plan);
       } catch (error) {
@@ -1411,21 +1417,23 @@ 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 or editor_detailed."),
+      profile: z.enum(REVIEW_BUNDLE_PROFILES).describe("Bundle profile: outline_discussion, editor_detailed, or beta_reader_personalized."),
       output_dir: z.string().describe("Directory path to write bundle artifacts into."),
       part: z.number().int().optional().describe("Optional part filter."),
       chapter: z.number().int().optional().describe("Optional 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)."),
+      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,
@@ -1439,8 +1447,10 @@ function createMcpServer() {
       include_scene_ids = true,
       include_metadata_sidebar = false,
       include_paragraph_anchors = false,
+      recipient_name,
       bundle_name,
       source_commit,
+      format = "pdf",
     }) => {
       const projectIdCheck = validateProjectId(project_id);
       if (!projectIdCheck.ok) {
@@ -1472,7 +1482,9 @@ function createMcpServer() {
           include_scene_ids,
           include_metadata_sidebar,
           include_paragraph_anchors,
+          recipient_name,
           bundle_name,
+          format,
         });
 
         if (!plan.strictness_result.can_proceed) {
@@ -1484,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,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "1.16.2",
+  "version": "2.0.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -29,6 +29,7 @@
     "manual:test": "node scripts/manual/test.mjs",
     "manual:scenarios": "node scripts/manual/test-scenarios.mjs",
     "manual:merge-beta-test": "node scripts/manual/run_mcp_test.js",
+    "manual:review-bundle": "node scripts/manual/run_create_review_bundle.js",
     "setup:openclaw-env": "sh scripts/setup-openclaw-env.sh",
     "release": "release-it",
     "lint": "eslint index.js importer.js db.js sync.js metadata-lint.js scripts/",
@@ -55,6 +56,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,10 +1,11 @@
 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;
 
-export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed"];
+export const REVIEW_BUNDLE_PROFILES = ["outline_discussion", "editor_detailed", "beta_reader_personalized"];
 export const REVIEW_BUNDLE_STRICTNESS = ["warn", "fail"];
 
 export class ReviewBundlePlanError extends Error {
@@ -63,6 +64,62 @@ function escapeMarkdown(text) {
     .replace(/([*_`\[\]#])/g, "\\$1");
 }
 
+function normalizeRecipientDisplayName(recipientName) {
+  const normalized = String(recipientName ?? "")
+    .replace(/[\x00-\x1f\x7f]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 100);
+
+  return normalized || "Beta Reader";
+}
+
+function renderBetaNoticeMarkdown({ projectId, recipientName }) {
+  const displayName = normalizeRecipientDisplayName(recipientName);
+  return [
+    "# Non-Distribution Notice",
+    "",
+    `This review packet is prepared for ${escapeMarkdown(displayName)} for private beta-reading purposes only.`,
+    "",
+    "Please do not distribute, repost, or share this material without explicit author permission.",
+    "",
+    "This notice is informational only and is not legal advice.",
+    "",
+    `Project: ${escapeMarkdown(projectId)}`,
+  ].join("\n") + "\n";
+}
+
+function renderBetaFeedbackFormMarkdown({ projectId, recipientName, generatedAt }) {
+  const displayName = normalizeRecipientDisplayName(recipientName);
+  const feedbackDate = String(generatedAt ?? new Date().toISOString()).slice(0, 10);
+  return [
+    "# Beta Reader Feedback Form",
+    "",
+    `- Project: ${escapeMarkdown(projectId)}`,
+    `- Reader: ${escapeMarkdown(displayName)}`,
+    `- Date: ${feedbackDate}`,
+    "",
+    "## Big-Picture Questions",
+    "",
+    "1. Which sections felt most compelling, and why?",
+    "2. Where did pacing feel slow, rushed, or unclear?",
+    "3. Were any character motivations confusing or unconvincing?",
+    "",
+    "## Scene-Level Notes",
+    "",
+    "Use scene IDs when possible.",
+    "",
+    "- Scene ID:",
+    "- Comment:",
+    "- Severity (nit / moderate / major):",
+    "",
+    "## Final Thoughts",
+    "",
+    "- What should be prioritized in the next revision?",
+    "- Any continuity concerns to flag?",
+  ].join("\n") + "\n";
+}
+
 function resolveOutputFilePath(outputDir, fileName) {
   const normalizedOutputDir = path.resolve(outputDir);
   const target = path.resolve(normalizedOutputDir, fileName);
@@ -97,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() };
@@ -125,6 +194,8 @@ export function buildReviewBundlePlan(dbHandle, {
   include_metadata_sidebar = false,
   include_paragraph_anchors = false,
   bundle_name,
+  recipient_name,
+  format = "pdf",
 } = {}) {
   if (!project_id) {
     throw new ReviewBundlePlanError("INVALID_PROJECT_ID", "project_id is required.");
@@ -132,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) {
@@ -264,6 +336,9 @@ export function buildReviewBundlePlan(dbHandle, {
     const count = Number(row.word_count);
     return sum + (Number.isFinite(count) ? count : 0);
   }, 0);
+  const resolvedRecipientName = profile === "beta_reader_personalized"
+    ? normalizeRecipientDisplayName(recipient_name)
+    : undefined;
 
   const safeBundleName = slugifyBundleName(bundle_name || `${project_id}-${profile}`);
   const appliedFilters = {
@@ -283,6 +358,7 @@ export function buildReviewBundlePlan(dbHandle, {
         include_scene_ids: Boolean(include_scene_ids),
         include_metadata_sidebar: Boolean(include_metadata_sidebar),
         include_paragraph_anchors: Boolean(include_paragraph_anchors),
+        ...(resolvedRecipientName ? { recipient_name: resolvedRecipientName } : {}),
       },
     },
     ordering: rows.map(row => ({
@@ -307,7 +383,14 @@ 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`,
+            `${safeBundleName}.feedback-form.md`,
+          ]
+        : []),
       `${safeBundleName}.manifest.json`,
     ],
   };
@@ -567,19 +650,35 @@ export function renderReviewBundleMarkdown(dbHandle, plan, { generatedAt, syncDi
   const sceneIds = plan.ordering.map(row => row.scene_id);
   const rows = loadBundleSceneRows(dbHandle, plan.resolved_scope.project_id, sceneIds);
   const sections = [];
+  const recipientName = plan.resolved_scope?.options?.recipient_name;
+  const recipientDisplayName = normalizeRecipientDisplayName(recipientName);
 
   const headerLines = [
     `# Review Bundle: ${escapeMarkdown(plan.resolved_scope.project_id)}`,
     "",
     `- Profile: ${profile}`,
+    ...(profile === "beta_reader_personalized"
+      ? [`- Recipient: ${escapeMarkdown(recipientDisplayName)}`]
+      : []),
     `- Generated at: ${generatedAt ?? new Date().toISOString()}`,
     `- Scene count: ${plan.summary.scene_count}`,
   ];
   sections.push(headerLines.join("\n"));
 
+  if (profile === "beta_reader_personalized") {
+    sections.push(
+      [
+        "## Usage Notice",
+        "",
+        "This beta-reader draft is intended for private review and feedback.",
+        "Please do not redistribute without explicit author permission.",
+      ].join("\n")
+    );
+  }
+
   for (const scene of rows) {
     let prose = "";
-    if (profile === "editor_detailed") {
+    if (profile === "editor_detailed" || profile === "beta_reader_personalized") {
       const resolved = readProse(scene.file_path, { syncDir });
       if (resolved === null) {
         throw new ReviewBundlePlanError(
@@ -606,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,
@@ -636,22 +878,59 @@ export function createReviewBundleArtifacts(dbHandle, {
     );
   }
 
-  const markdownFileName = plan.planned_outputs.find(name => name.endsWith(".md"));
+  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")
+  ) ?? 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 })
+    : null;
+  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: {
@@ -665,7 +944,7 @@ export function createReviewBundleArtifacts(dbHandle, {
     scene_ids: plan.ordering.map(row => row.scene_id),
   };
 
-  for (const outputPath of [markdownPath, manifestPath]) {
+  for (const outputPath of [markdownPath, pdfPath, manifestPath, noticePath, feedbackPath].filter(Boolean)) {
     try {
       const stat = fs.lstatSync(outputPath);
       if (stat.isSymbolicLink()) {
@@ -690,14 +969,28 @@ 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");
+  }
+  if (feedbackPath && betaFeedbackForm != null) {
+    fs.writeFileSync(feedbackPath, betaFeedbackForm, "utf8");
+  }
 
   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 } : {}),
     },
     generated_at: generatedAt,
   };

package/scripts/manual/run_create_review_bundle.js

@@ -2,11 +2,12 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import path from "path";
 import process from "process";
+import fs from "node:fs";
 
 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>]");
+    console.error("Usage: WRITING_SYNC_DIR=/path/to/sync node scripts/manual/run_create_review_bundle.js <project_id> <profile> <output_dir> [--anchors] [--recipient <name>] [--bundle-name <name>] [--skip-preview] [--show-files]");
     process.exit(1);
   }
 
@@ -19,8 +20,28 @@ async function main() {
   }
 
   const includeParagraphAnchors = flags.includes("--anchors");
+  const skipPreview = flags.includes("--skip-preview");
+  const showFiles = flags.includes("--show-files");
   const bundleNameIdx = flags.indexOf("--bundle-name");
   const bundleName = bundleNameIdx !== -1 ? flags[bundleNameIdx + 1] : undefined;
+  const recipientIdx = flags.indexOf("--recipient");
+  const recipientName = recipientIdx !== -1 ? flags[recipientIdx + 1] : undefined;
+
+  const baseArguments = {
+    project_id: projectId,
+    profile,
+    ...(includeParagraphAnchors ? { include_paragraph_anchors: true } : {}),
+    ...(bundleName ? { bundle_name: bundleName } : {}),
+    ...(recipientName ? { recipient_name: recipientName } : {}),
+  };
+
+  function printArtifactExcerpt(label, filePath) {
+    if (!filePath || !fs.existsSync(filePath)) return;
+    const content = fs.readFileSync(filePath, "utf8");
+    const excerpt = content.split("\n").slice(0, 20).join("\n");
+    console.log(`\n--- ${label}: ${filePath} ---`);
+    console.log(excerpt);
+  }
 
   const transport = new StdioClientTransport({
     command: process.execPath,
@@ -41,18 +62,38 @@ async function main() {
 
   try {
     await client.connect(transport);
+
+    if (!skipPreview) {
+      const previewResult = await client.callTool({
+        name: "preview_review_bundle",
+        arguments: baseArguments,
+      });
+      const previewText = previewResult.content?.[0]?.text ?? "";
+      console.log("\n=== preview_review_bundle ===");
+      console.log(previewText);
+    }
+
     const result = await client.callTool({
       name: "create_review_bundle",
       arguments: {
-        project_id: projectId,
-        profile: profile,
+        ...baseArguments,
         output_dir: outputDir,
-        ...(includeParagraphAnchors ? { include_paragraph_anchors: true } : {}),
-        ...(bundleName ? { bundle_name: bundleName } : {})
       }
     });
 
-    console.log(JSON.stringify(result, null, 2));
+    const resultText = result.content?.[0]?.text ?? "";
+    console.log("\n=== create_review_bundle ===");
+    console.log(resultText);
+
+    if (showFiles) {
+      const parsed = JSON.parse(resultText);
+      if (parsed.ok && parsed.output_paths) {
+        printArtifactExcerpt("Bundle Markdown", parsed.output_paths.bundle_markdown);
+        printArtifactExcerpt("Manifest JSON", parsed.output_paths.manifest_json);
+        printArtifactExcerpt("Notice Markdown", parsed.output_paths.notice_md);
+        printArtifactExcerpt("Feedback Form Markdown", parsed.output_paths.feedback_form_md);
+      }
+    }
   } catch (e) {
     console.error(e);
     process.exitCode = 1;

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);
+});