@hanna84/mcp-writing 2.18.0 → 3.0.0

package/src/scripts/manual/test-scenarios.mjs

@@ -1,5 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { callToolParsed } from "./mcp-result.mjs";
 
 const BASE_URL = "http://localhost:3000";
 
@@ -22,8 +23,8 @@ async function connect() {
 }
 
 async function callTool(client, name, args = {}) {
-  const result = await client.callTool({ name, arguments: args });
-  return result.content?.[0]?.text ?? "";
+  const result = await callToolParsed(client, name, args);
+  return result.text;
 }
 
 const results = [];
@@ -45,12 +46,9 @@ async function runScenarios() {
     try {
       const text = await callTool(client, "find_scenes", { project_id: "the-lamb" });
       const parsed = JSON.parse(text);
-      const isArray = Array.isArray(parsed);
-      const isEnvelope = !isArray && parsed.results && parsed.total_count !== undefined;
-      
-      if (isArray) {
-        log("1a", "PASS", `Got array of ${parsed.length} scenes (backward compat)`);
-      } else if (isEnvelope) {
+      const isEnvelope = parsed && parsed.results && parsed.total_count !== undefined;
+
+      if (isEnvelope) {
         log("1b", "PASS", `Got envelope with results: ${parsed.results.length}, total_count: ${parsed.total_count}`);
       } else {
         log("1c", "FAIL", `Unknown shape: ${JSON.stringify(parsed).slice(0, 100)}`);
@@ -241,17 +239,23 @@ async function runScenarios() {
       const ga = JSON.parse(await callTool(client, "get_arc", { character_id: "char-mira-nystrom", page_size: 1 }));
       const sm = JSON.parse(await callTool(client, "search_metadata", { query: "scene", page_size: 1 }));
       const lt = JSON.parse(await callTool(client, "list_threads", { project_id: "the-lamb" }));
+      const lc = JSON.parse(await callTool(client, "list_characters", { project_id: "the-lamb" }));
+      const lp = JSON.parse(await callTool(client, "list_places", { project_id: "the-lamb" }));
+      const sr = JSON.parse(await callTool(client, "search_reference", { query: "scene" }));
 
       const commonFields = ["results", "total_count"];
       const fsHas = commonFields.every(f => f in fs);
       const gaHas = commonFields.every(f => f in ga);
       const smHas = commonFields.every(f => f in sm);
       const ltHas = commonFields.every(f => f in lt);
+      const lcHas = commonFields.every(f => f in lc);
+      const lpHas = commonFields.every(f => f in lp);
+      const srHas = commonFields.every(f => f in sr);
 
-      if (fsHas && gaHas && smHas && ltHas) {
-        log("11", "PASS", `All tools have results + total_count envelope`);
+      if (fsHas && gaHas && smHas && ltHas && lcHas && lpHas && srHas) {
+        log("11", "PASS", `All metadata-read tools have results + total_count envelope`);
       } else {
-        log("11", "FAIL", `Missing fields: fs=${fsHas}, ga=${gaHas}, sm=${smHas}, lt=${ltHas}`);
+        log("11", "FAIL", `Missing fields: fs=${fsHas}, ga=${gaHas}, sm=${smHas}, lt=${ltHas}, lc=${lcHas}, lp=${lpHas}, sr=${srHas}`);
       }
     } catch (err) {
       log("11", "FAIL", err.message);
@@ -267,14 +271,22 @@ async function runScenarios() {
         ga: JSON.parse(await callTool(client, "get_arc", { character_id: "char-mira-nystrom" })),
         sm: JSON.parse(await callTool(client, "search_metadata", { query: "scene" })),
         lt: JSON.parse(await callTool(client, "list_threads", { project_id: "the-lamb" })),
+        lc: JSON.parse(await callTool(client, "list_characters", { project_id: "the-lamb" })),
+        lp: JSON.parse(await callTool(client, "list_places", { project_id: "the-lamb" })),
+        sr: JSON.parse(await callTool(client, "search_reference", { query: "scene" })),
       };
 
-      const allValid = Object.values(smoke).every(obj => obj !== null && typeof obj === "object");
+      const allValid = Object.values(smoke).every(obj => (
+        obj !== null
+        && typeof obj === "object"
+        && "results" in obj
+        && "total_count" in obj
+      ));
       
       if (allValid) {
-        log("12", "PASS", `All 4 tools parsed as valid JSON objects`);
+        log("12", "PASS", `All sampled metadata-read tools returned envelope responses`);
       } else {
-        log("12", "FAIL", `Some responses did not parse as JSON`);
+        log("12", "FAIL", `Some responses did not match envelope shape`);
       }
     } catch (err) {
       log("12", "FAIL", err.message);

package/src/scripts/manual/test.mjs

@@ -1,5 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { callToolParsed } from "./mcp-result.mjs";
 
 const BASE_URL = "http://localhost:3000";
 
@@ -12,9 +13,10 @@ let failed = 0;
 
 async function test(label, toolName, args, check) {
   try {
-    const result = await client.callTool({ name: toolName, arguments: args });
-    const text = result.content?.[0]?.text ?? "";
-    const ok = check(text);
+    const parsed = await callToolParsed(client, toolName, args);
+    const text = parsed.text;
+    const result = parsed.raw;
+    const ok = check(text, result);
     if (ok) {
       console.log(`  ✓  ${label}`);
       passed++;
@@ -77,7 +79,12 @@ console.log("\n── get_scene_prose ──────────────
 await test(
   "returns prose for sc-001",
   "get_scene_prose", { scene_id: "sc-001" },
-  t => t.includes("gangway") && t.includes("Marcus")
+  (t, result) => {
+    if (result.structuredContent?.warning) {
+      console.log(`     warning: ${result.structuredContent.warning}`);
+    }
+    return t.includes("gangway") && t.includes("Marcus");
+  }
 );
 
 await test(

package/src/scripts/manual-validation.mjs

@@ -7,6 +7,7 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { URL as NodeURL } from "node:url";
 import { execSync } from "node:child_process";
 import fs from "node:fs";
+import { callToolParsed } from "./manual/mcp-result.mjs";
 
 const ROOT = process.cwd();
 
@@ -38,7 +39,8 @@ async function connectClient(url) {
 
 async function callTool(client, name, args = {}) {
   try {
-    return await client.callTool({ name, arguments: args });
+    const parsed = await callToolParsed(client, name, args);
+    return parsed.raw;
   } catch (e) {
     return { error: e.message };
   }
@@ -48,12 +50,14 @@ function parseResponse(result) {
   if (result.error) return { error: result.error };
   try {
     const text = result.content?.[0]?.text;
+    const structured = result.structuredContent;
     if (!text) return { raw: result };
     // Try to parse as JSON
     try {
-      return JSON.parse(text);
+      const parsed = JSON.parse(text);
+      return structured ? { ...parsed, _structured: structured } : parsed;
     } catch {
-      return { text };
+      return structured ? { text, _structured: structured } : { text };
     }
   } catch {
     return { raw: result };
@@ -218,7 +222,10 @@ async function runPhaseB() {
       const proseRes = await callTool(client, "get_scene_prose", { scene_id: results.firstSceneId });
       const proseData = parseResponse(proseRes);
       results.proseExcerpt = proseData.prose?.slice(0, 200) || proseData.text?.slice(0, 200) || proseRes.content?.[0]?.text?.slice(0, 200) || "(no prose)";
+      results.proseWarning = proseData._structured?.warning || null;
+      results.proseNextStep = proseData._structured?.next_step || null;
       console.log("get_scene_prose excerpt:", results.proseExcerpt.slice(0, 150) + "...");
+      if (results.proseWarning) console.log("get_scene_prose warning:", results.proseWarning);
     } else {
       results.proseExcerpt = "(no scene_id available)";
     }
@@ -260,6 +267,7 @@ async function main() {
   console.log("  Place count:", phaseB.placeCount);
   console.log("  Airport search count:", phaseB.airportSearchCount);
   console.log("  First scene_id:", phaseB.firstSceneId || "N/A");
+  if (phaseB.proseWarning) console.log("  Prose warning:", phaseB.proseWarning);
   console.log("  Prose excerpt (200 chars):", phaseB.proseExcerpt?.slice(0, 200) || "N/A");
   if (phaseB.warnings.length) console.log("  Lint warnings:", phaseB.warnings.length > 0 ? "Yes (see above)" : "None");
   if (phaseB.errors.length) console.log("  Errors:", phaseB.errors);

package/src/scripts/mcp-debug-client.mjs

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { URL as NodeURL } from "node:url";
+import { callToolParsed } from "./manual/mcp-result.mjs";
 
 const ROOT = process.cwd();
 
@@ -31,11 +32,11 @@ try {
   const transport = new SSEClientTransport(new NodeURL(`${BASE}/sse`));
   await client.connect(transport);
   
-  await client.callTool({ name: "sync", arguments: {} });
+  await callToolParsed(client, "sync", {});
   
-  const scenes = await client.callTool({ name: "find_scenes", arguments: { project_id: "scrivener-export", page_size: 3, page: 1 } });
+  const scenes = await callToolParsed(client, "find_scenes", { project_id: "scrivener-export", page_size: 3, page: 1 });
   console.log("=== find_scenes raw response ===");
-  console.log(JSON.stringify(scenes, null, 2));
+  console.log(JSON.stringify(scenes.raw, null, 2));
   
   await client.close();
 } finally {

package/src/sync/sync.js

@@ -919,13 +919,10 @@ function pruneMissingScenes(db, seenSceneKeys, syncDir) {
       WHERE source_kind = 'scene' AND source_project_id = ? AND source_id = ?
     `).run(row.project_id ?? "", row.scene_id);
     db.prepare(`DELETE FROM scenes WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
-
-    const remainingScene = db.prepare(`SELECT 1 FROM scenes WHERE scene_id = ? LIMIT 1`).get(row.scene_id);
-    if (!remainingScene) {
-      db.prepare(`DELETE FROM scene_characters WHERE scene_id = ?`).run(row.scene_id);
-      db.prepare(`DELETE FROM scene_places WHERE scene_id = ?`).run(row.scene_id);
-      db.prepare(`DELETE FROM scene_tags WHERE scene_id = ?`).run(row.scene_id);
-    }
+    db.prepare(`DELETE FROM scene_characters WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+    db.prepare(`DELETE FROM scene_places WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+    db.prepare(`DELETE FROM scene_tags WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+    db.prepare(`DELETE FROM scene_threads WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
   }
 }
 
@@ -994,14 +991,14 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
     new Date().toISOString()
   );
 
-  db.prepare(`DELETE FROM scene_characters WHERE scene_id = ?`).run(meta.scene_id);
-  db.prepare(`DELETE FROM scene_places WHERE scene_id = ?`).run(meta.scene_id);
-  db.prepare(`DELETE FROM scene_tags WHERE scene_id = ?`).run(meta.scene_id);
+  db.prepare(`DELETE FROM scene_characters WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
+  db.prepare(`DELETE FROM scene_places WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
+  db.prepare(`DELETE FROM scene_tags WHERE scene_id = ? AND project_id = ?`).run(meta.scene_id, project_id);
 
   for (const c of (meta.characters ?? [])) {
     // Version continuity markers (e.g. v7.3, v3.3b) are tracked as tags, not characters
     if (/^v\d[\d.a-z]*$/i.test(c)) {
-      db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, tag) VALUES (?, ?)`).run(meta.scene_id, c);
+      db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, project_id, tag) VALUES (?, ?, ?)`).run(meta.scene_id, project_id, c);
       continue;
     }
     let cid = c;
@@ -1021,23 +1018,23 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
       }
       if (row) cid = row.character_id;
     }
-    db.prepare(`INSERT OR IGNORE INTO scene_characters (scene_id, character_id) VALUES (?, ?)`).run(
-      meta.scene_id, cid
+    db.prepare(`INSERT OR IGNORE INTO scene_characters (scene_id, project_id, character_id) VALUES (?, ?, ?)`).run(
+      meta.scene_id, project_id, cid
     );
   }
   for (const p of (meta.places ?? [])) {
-    db.prepare(`INSERT OR IGNORE INTO scene_places (scene_id, place_id) VALUES (?, ?)`).run(
-      meta.scene_id, p
+    db.prepare(`INSERT OR IGNORE INTO scene_places (scene_id, project_id, place_id) VALUES (?, ?, ?)`).run(
+      meta.scene_id, project_id, p
     );
   }
   for (const t of (meta.tags ?? [])) {
-    db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, tag) VALUES (?, ?)`).run(
-      meta.scene_id, t
+    db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, project_id, tag) VALUES (?, ?, ?)`).run(
+      meta.scene_id, project_id, t
     );
   }
   for (const v of (meta.versions ?? [])) {
-    db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, tag) VALUES (?, ?)`).run(
-      meta.scene_id, v
+    db.prepare(`INSERT OR IGNORE INTO scene_tags (scene_id, project_id, tag) VALUES (?, ?, ?)`).run(
+      meta.scene_id, project_id, v
     );
   }
 

package/src/tools/editing.js

@@ -25,20 +25,37 @@ export function registerEditingTools(s, {
   // ---- propose_edit --------------------------------------------------------
   s.tool(
     "propose_edit",
-    "Generate a proposed revision for a scene. Returns a proposal_id and a diff preview. Nothing is written yet — you must call commit_edit to apply the change. This tool requires git to be available.",
+    "Generate a proposed revision for a scene. Returns a proposal_id and a diff preview. Nothing is written yet — you must call commit_edit to apply the change. This tool requires git to be available. If scene IDs are reused across projects, omitting project_id returns CONFLICT with candidate project_ids.",
     {
       scene_id: z.string().describe("The scene_id to revise (e.g. 'sc-011-sebastian')."),
+      project_id: z.string().optional().describe("Optional project ID to disambiguate duplicate scene IDs across projects."),
       instruction: z.string().describe("A brief instruction for the edit (e.g. 'Tighten the opening paragraph'). Used in the git commit message."),
       revised_prose: z.string().describe("The complete revised prose text for the scene."),
     },
-    async ({ scene_id, instruction, revised_prose }) => {
+    async ({ scene_id, project_id, instruction, revised_prose }) => {
       if (!GIT_ENABLED) {
         return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported. Ensure git is installed and the sync directory is writable.");
       }
 
-      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
-      if (!scene) {
-        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found. Hint: call find_scenes to get valid scene IDs.`);
+      let scene;
+      if (project_id) {
+        scene = db.prepare(`SELECT file_path, project_id FROM scenes WHERE scene_id = ? AND project_id = ?`).get(scene_id, project_id);
+        if (!scene) {
+          return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'. Hint: call find_scenes with project_id to get valid scene IDs.`);
+        }
+      } else {
+        const scenes = db.prepare(`SELECT file_path, project_id FROM scenes WHERE scene_id = ? ORDER BY project_id`).all(scene_id);
+        if (scenes.length === 0) {
+          return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found. Hint: call find_scenes to get valid scene IDs.`);
+        }
+        if (scenes.length > 1) {
+          return errorResponse(
+            "CONFLICT",
+            `Scene ID '${scene_id}' exists in multiple projects. Provide project_id to disambiguate.`,
+            { scene_id, project_ids: scenes.map(s => s.project_id) }
+          );
+        }
+        scene = scenes[0];
       }
 
       try {
@@ -66,6 +83,7 @@ export function registerEditingTools(s, {
         const proposalId = generateProposalId();
         pendingProposals.set(proposalId, {
           scene_id,
+          project_id: scene.project_id,
           scene_file_path: scene.file_path,
           instruction,
           revised_prose,
@@ -85,12 +103,16 @@ export function registerEditingTools(s, {
         return jsonResponse({
           proposal_id: proposalId,
           scene_id,
+          project_id: scene.project_id,
           instruction,
           diff_preview: diffPreview,
           noop,
           note: noop
             ? "This proposal matches the current scene file. Calling commit_edit will be a no-op."
             : "Review the diff above. Call commit_edit with this proposal_id to apply the change.",
+          next_step: noop
+            ? "If this was intentional, no action is required. Otherwise, adjust revised_prose and call propose_edit again."
+            : "Review diff_preview, then call commit_edit to apply or discard_edit to reject.",
         });
       } catch (err) {
         if (err.code === "ENOENT") {
@@ -107,9 +129,10 @@ export function registerEditingTools(s, {
     "Apply a proposed edit and commit it to git. First creates a pre-edit snapshot, then writes the revised prose and metadata back to disk. The scene metadata stale flag is cleared.",
     {
       scene_id: z.string().describe("The scene_id being revised."),
+      project_id: z.string().optional().describe("Optional project ID. Required when scene IDs are duplicated across projects."),
       proposal_id: z.string().describe("The proposal_id returned by propose_edit."),
     },
-    async ({ scene_id, proposal_id }) => {
+    async ({ scene_id, project_id, proposal_id }) => {
       if (!GIT_ENABLED) {
         return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported.");
       }
@@ -123,6 +146,27 @@ export function registerEditingTools(s, {
         return errorResponse("INVALID_EDIT", `Proposal '${proposal_id}' is for scene '${proposal.scene_id}', not '${scene_id}'.`);
       }
 
+      if (!project_id && proposal.project_id) {
+        const projectMatches = db.prepare(`SELECT project_id FROM scenes WHERE scene_id = ? ORDER BY project_id`).all(scene_id);
+        if (projectMatches.length > 1) {
+          return errorResponse(
+            "CONFLICT",
+            `Scene ID '${scene_id}' exists in multiple projects. Provide project_id to disambiguate commit_edit.`,
+            {
+              scene_id,
+              project_ids: projectMatches.map((row) => row.project_id),
+              proposal_project_id: proposal.project_id,
+              proposal_id,
+              next_step: `Retry commit_edit with project_id '${proposal.project_id}' and the same proposal_id.`,
+            }
+          );
+        }
+      }
+
+      if (project_id && proposal.project_id && proposal.project_id !== project_id) {
+        return errorResponse("INVALID_EDIT", `Proposal '${proposal_id}' is for project '${proposal.project_id}', not '${project_id}'.`);
+      }
+
       try {
         const proseWriteDiagnostics = getFileWriteDiagnostics(proposal.scene_file_path);
         if (proseWriteDiagnostics.stat_error_code === "EACCES" || proseWriteDiagnostics.stat_error_code === "EPERM") {
@@ -184,10 +228,12 @@ export function registerEditingTools(s, {
           return jsonResponse({
             ok: true,
             scene_id,
+            project_id: proposal.project_id ?? null,
             proposal_id,
             snapshot_commit: null,
             noop: true,
             message: `Proposal for scene '${scene_id}' matches the current file. Nothing was written.`,
+            next_step: "No changes were applied. If you still need edits, call propose_edit with revised prose.",
           });
         }
 
@@ -204,10 +250,12 @@ export function registerEditingTools(s, {
         return jsonResponse({
           ok: true,
           scene_id,
+          project_id: proposal.project_id ?? null,
           proposal_id,
           snapshot_commit: snapshot.commit_hash,
           noop: false,
           message: `Applied edit to scene '${scene_id}'${snapshot.commit_hash ? ` (snapshot: ${snapshot.commit_hash.substring(0, 7)})` : " (no pre-edit snapshot needed)"}`,
+          next_step: "Edit applied. Run get_scene_prose to verify prose, then continue with additional targeted edits if needed.",
         });
       } catch (err) {
         if (err.code === "ENOENT") {
@@ -236,6 +284,7 @@ export function registerEditingTools(s, {
         ok: true,
         proposal_id,
         message: `Discarded proposal '${proposal_id}' for scene '${proposal.scene_id}'.`,
+        next_step: "Proposal discarded. Call propose_edit again if you want to stage a revised alternative.",
       });
     }
   );
@@ -293,15 +342,32 @@ export function registerEditingTools(s, {
     "List git commit history for a scene, with timestamps and commit messages. Use this to find commit hashes for get_scene_prose historical retrieval.",
     {
       scene_id: z.string().describe("The scene_id to list snapshots for."),
+      project_id: z.string().optional().describe("Optional project ID to disambiguate duplicate scene IDs across projects."),
     },
-    async ({ scene_id }) => {
+    async ({ scene_id, project_id }) => {
       if (!GIT_ENABLED) {
         return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be retrieved.");
       }
 
-      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
-      if (!scene) {
-        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+      let scene;
+      if (project_id) {
+        scene = db.prepare(`SELECT file_path, project_id FROM scenes WHERE scene_id = ? AND project_id = ?`).get(scene_id, project_id);
+        if (!scene) {
+          return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+        }
+      } else {
+        const scenes = db.prepare(`SELECT file_path, project_id FROM scenes WHERE scene_id = ? ORDER BY project_id`).all(scene_id);
+        if (scenes.length === 0) {
+          return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+        }
+        if (scenes.length > 1) {
+          return errorResponse(
+            "CONFLICT",
+            `Scene ID '${scene_id}' exists in multiple projects. Provide project_id to disambiguate.`,
+            { scene_id, project_ids: scenes.map((row) => row.project_id) }
+          );
+        }
+        scene = scenes[0];
       }
 
       try {
@@ -312,6 +378,7 @@ export function registerEditingTools(s, {
 
         return jsonResponse({
           scene_id,
+          project_id: scene.project_id ?? null,
           snapshots: snapshots.map(s => ({
             commit_hash: s.commit_hash,
             short_hash: s.commit_hash.substring(0, 7),

package/src/tools/metadata.js

@@ -347,15 +347,15 @@ export function registerMetadataTools(s, {
       `).run(thread_id, project_id, thread_name, status ?? "active");
 
       db.prepare(`
-        INSERT INTO scene_threads (scene_id, thread_id, beat)
-        VALUES (?, ?, ?)
-        ON CONFLICT (scene_id, thread_id) DO UPDATE SET
+        INSERT INTO scene_threads (scene_id, project_id, thread_id, beat)
+        VALUES (?, ?, ?, ?)
+        ON CONFLICT (scene_id, project_id, thread_id) DO UPDATE SET
           beat = excluded.beat
-      `).run(scene_id, thread_id, beat ?? null);
+      `).run(scene_id, project_id, thread_id, beat ?? null);
 
       const thread = db.prepare(`SELECT * FROM threads WHERE thread_id = ?`).get(thread_id);
-      const link = db.prepare(`SELECT scene_id, thread_id, beat FROM scene_threads WHERE scene_id = ? AND thread_id = ?`)
-        .get(scene_id, thread_id);
+      const link = db.prepare(`SELECT scene_id, project_id, thread_id, beat FROM scene_threads WHERE scene_id = ? AND project_id = ? AND thread_id = ?`)
+        .get(scene_id, project_id, thread_id);
 
       return jsonResponse({
         ok: true,

package/src/tools/review-bundles.js

@@ -74,7 +74,12 @@ export function registerReviewBundleTools(s, {
           bundle_name,
           format,
         });
-        return jsonResponse(plan);
+        return jsonResponse({
+          ...plan,
+          next_step: plan.strictness_result?.can_proceed
+            ? "Preview complete. Review warnings and planned_outputs, then call create_review_bundle with the same scope and output_dir."
+            : "Preview complete, but strictness blockers are present. Resolve blockers (for example stale metadata) or switch to strictness='warn' before create_review_bundle.",
+        });
       } catch (error) {
         if (error instanceof ReviewBundlePlanError) {
           return errorResponse(error.code, error.message, error.details);
@@ -172,7 +177,11 @@ export function registerReviewBundleTools(s, {
           return errorResponse(
             "STRICTNESS_BLOCKED",
             "Bundle generation blocked by strictness policy.",
-            { strictness_result: plan.strictness_result, warning_summary: plan.warning_summary }
+            {
+              strictness_result: plan.strictness_result,
+              warning_summary: plan.warning_summary,
+              next_step: "Resolve blockers from strictness_result (for example by running enrich_scene on stale scenes), then re-run create_review_bundle.",
+            }
           );
         }
 
@@ -200,6 +209,7 @@ export function registerReviewBundleTools(s, {
             generated_at: artifacts.generated_at,
             project_id: plan.resolved_scope.project_id,
           },
+          next_step: "Bundle created. Share output_paths with reviewers, or run preview_review_bundle again to adjust scope/profile before regenerating.",
         });
       } catch (error) {
         if (error instanceof ReviewBundlePlanError) {