@hanna84/mcp-writing 2.10.4 → 2.10.6

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.10.6](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.5...v2.10.6)
+
+- refactor(index): extract getRuntimeDiagnostics into runtime-diagnostics.js [`#110`](https://github.com/hannasdev/mcp-writing.git
+/pull/110)
+
+#### [v2.10.5](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.10.4...v2.10.5)
+
+> 27 April 2026
+
+- refactor(index): extract workflow catalogue module [`#109`](https://github.com/hannasdev/mcp-writing.git
+/pull/109)
+- Release 2.10.5 [`bee9b2b`](https://github.com/hannasdev/mcp-writing.git
+/commit/bee9b2bee5992cfc69571d95ab1dc281d89d8812)
+
 #### [v2.10.4](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.3...v2.10.4)
 
+> 27 April 2026
+
 - fix(review-bundles): guard oversized scene_ids in planner [`#108`](https://github.com/hannasdev/mcp-writing.git
 /pull/108)
+- Release 2.10.4 [`6afb4e5`](https://github.com/hannasdev/mcp-writing.git
+/commit/6afb4e51408ce9a42ade76087f4a2f86a6b13c19)
 
 #### [v2.10.3](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.10.2...v2.10.3)

package/git.js

@@ -35,7 +35,7 @@ export function initGitRepository(dirPath) {
     }
     return true;
   } catch (err) {
-    throw new Error(`Failed to initialize git repository: ${err.message}`);
+    throw new Error(`Failed to initialize git repository: ${err.message}`, { cause: err });
   }
 }
 
@@ -98,7 +98,7 @@ export function createSnapshot(dirPath, filePath, sceneId, instruction, options
         reason: "no changes to commit",
       };
     }
-    throw new Error(`Failed to create snapshot: ${err.message}`);
+    throw new Error(`Failed to create snapshot: ${err.message}`, { cause: err });
   }
 }
 
@@ -137,7 +137,7 @@ export function listSnapshots(dirPath, filePath) {
     if (err.message.includes("your current branch") || err.status === 128) {
       return [];
     }
-    throw new Error(`Failed to list snapshots: ${err.message}`);
+    throw new Error(`Failed to list snapshots: ${err.message}`, { cause: err });
   }
 }
 
@@ -163,10 +163,16 @@ export function getSceneProseAtCommit(dirPath, filePath, commitHash) {
 
     return content;
   } catch (err) {
+    // ENOENT from execFileSync means the git binary was not found on PATH — not a missing file in the commit.
     if (err.code === "ENOENT") {
-      throw new Error(`File not found in commit ${commitHash}`);
+      throw new Error("git executable not found; ensure git is installed and on PATH", { cause: err });
     }
-    throw new Error(`Failed to retrieve scene prose: ${err.message}`);
+    // git exit 128 with "path ... does not exist in" or "bad object" indicates missing path/commit.
+    const stderr = err?.stderr ? String(err.stderr) : "";
+    if (err.status === 128 && (stderr.includes("does not exist in") || stderr.includes("bad object"))) {
+      throw new Error(`File not found in commit ${commitHash}`, { cause: err });
+    }
+    throw new Error(`Failed to retrieve scene prose: ${err.message}`, { cause: err });
   }
 }
 

package/index.js

@@ -25,6 +25,8 @@ import { registerMetadataTools } from "./tools/metadata.js";
 import { registerReviewBundleTools } from "./tools/review-bundles.js";
 import { registerStyleguideTools } from "./tools/styleguide.js";
 import { registerEditingTools } from "./tools/editing.js";
+import { WORKFLOW_CATALOGUE } from "./workflow-catalogue.js";
+import { getRuntimeDiagnostics } from "./runtime-diagnostics.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -199,78 +201,16 @@ function generateProposalId() {
   return `proposal-${randomUUID()}`;
 }
 
-function getRuntimeDiagnostics() {
-  const warnings = [];
-  const recommendations = [];
-
-  if (OWNERSHIP_GUARD_MODE_RAW !== OWNERSHIP_GUARD_MODE) {
-    warnings.push(
-      `OWNERSHIP_GUARD_MODE_INVALID: Unsupported OWNERSHIP_GUARD_MODE=${OWNERSHIP_GUARD_MODE_RAW_DISPLAY}. Falling back to 'warn'.`
-    );
-    recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid_override_ignored) {
-    warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
-    recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid_override_invalid) {
-    warnings.push("RUNTIME_UID_OVERRIDE_INVALID: RUNTIME_UID_OVERRIDE must be a non-negative integer when enabled.");
-    recommendations.push("Set RUNTIME_UID_OVERRIDE to a non-negative integer, or unset it.");
-  }
-
-  if (!SYNC_DIR_WRITABLE) {
-    warnings.push("SYNC_DIR_READ_ONLY: sync dir is read-only; metadata write-back and prose editing tools are unavailable.");
-    recommendations.push("Mount WRITING_SYNC_DIR with write access (avoid read-only mounts like ':ro').");
-    recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.supported && SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths > 0) {
-    warnings.push(
-      `OWNERSHIP_MISMATCH: ${SYNC_OWNERSHIP_DIAGNOSTICS.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid}.`
-    );
-    recommendations.push(
-      `Repair ownership once on host: sudo chown -R "$(id -u):$(id -g)" "${SYNC_DIR_ABS}"`
-    );
-    recommendations.push(
-      "For Docker/OpenClaw, run container as host user (compose: user: \"${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}\")."
-    );
-  }
-
-  if (OWNERSHIP_GUARD_MODE === "fail" && SYNC_OWNERSHIP_DIAGNOSTICS.runtime_uid === 0) {
-    warnings.push(
-      "OWNERSHIP_GUARD_SKIPPED_FOR_ROOT: OWNERSHIP_GUARD_MODE=fail is skipped because runtime UID is 0 (root)."
-    );
-    recommendations.push("Prefer running as a non-root host-mapped UID/GID to make ownership guard checks meaningful.");
-  }
-
-  if (SYNC_OWNERSHIP_DIAGNOSTICS.supported && SYNC_OWNERSHIP_DIAGNOSTICS.root_owned_paths > 0) {
-    warnings.push(
-      `ROOT_OWNED_PATHS: ${SYNC_OWNERSHIP_DIAGNOSTICS.root_owned_paths} sampled path(s) are owned by UID 0 (root).`
-    );
-  }
-
-  if (!GIT_AVAILABLE) {
-    warnings.push("GIT_NOT_FOUND: git is not available on PATH; snapshot/edit tools are unavailable.");
-    recommendations.push("Install git in the runtime image/environment.");
-  }
-
-  if (GIT_AVAILABLE && SYNC_DIR_WRITABLE && !GIT_ENABLED) {
-    warnings.push("GIT_DISABLED: git is available but repository snapshot tools are not active.");
-    recommendations.push("Ensure WRITING_SYNC_DIR points to a writable git repository root, or allow mcp-writing to initialize one.");
-  }
-
-  if (GIT_AVAILABLE && !SYNC_DIR_WRITABLE) {
-    recommendations.push("If git reports 'dubious ownership' for mounted repos, add: git config --system --add safe.directory /sync");
-  }
-
-  recommendations.push("If indexing finds many files without scene_id, run scripts/import.js first for Scrivener Draft exports, then run sync.");
-
-  return { warnings, recommendations };
-}
-
-const RUNTIME_DIAGNOSTICS = getRuntimeDiagnostics();
+const RUNTIME_DIAGNOSTICS = getRuntimeDiagnostics({
+  ownershipGuardModeRaw: OWNERSHIP_GUARD_MODE_RAW,
+  ownershipGuardMode: OWNERSHIP_GUARD_MODE,
+  ownershipGuardModeRawDisplay: OWNERSHIP_GUARD_MODE_RAW_DISPLAY,
+  syncDirWritable: SYNC_DIR_WRITABLE,
+  syncDirAbs: SYNC_DIR_ABS,
+  syncOwnershipDiagnostics: SYNC_OWNERSHIP_DIAGNOSTICS,
+  gitAvailable: GIT_AVAILABLE,
+  gitEnabled: GIT_ENABLED,
+});
 if (RUNTIME_DIAGNOSTICS.warnings.length) {
   process.stderr.write(`[mcp-writing] Runtime diagnostics:\n`);
   for (const line of RUNTIME_DIAGNOSTICS.warnings) {
@@ -357,102 +297,6 @@ function maxScenesNextStep(matchedCount) {
   return `Re-run with max_scenes set to at least ${matchedCount}.`;
 }
 
-const WORKFLOW_CATALOGUE = [
-  {
-    id: "first_time_setup",
-    label: "First-time setup",
-    use_when: "Connecting to a project for the first time or verifying the runtime is correctly configured.",
-    steps: [
-      { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
-      { tool: "sync", note: "Index scenes from disk." },
-    ],
-  },
-  {
-    id: "styleguide_setup_new",
-    label: "Styleguide setup (new project)",
-    use_when: "No prose styleguide config exists and you want to create one based on the manuscript's existing conventions.",
-    steps: [
-      { tool: "describe_workflows", note: "Check context.scene_count; use that value as max_scenes in the next call." },
-      { tool: "bootstrap_prose_styleguide_config", note: "Detect dominant conventions. Confirm suggestions with the user before applying." },
-      { tool: "setup_prose_styleguide_config", note: "Only if ALL context.styleguide_exists fields are false — a config at any scope is sufficient. Create at project_root scope (requires project_id and language e.g. 'english_us'), or sync_root if no project_id is known." },
-      { tool: "update_prose_styleguide_config", note: "Apply the fields accepted from bootstrap suggestions." },
-    ],
-  },
-  {
-    id: "styleguide_drift_check",
-    label: "Styleguide drift check",
-    use_when: "A styleguide config exists and you want to check whether recent scenes conform to it.",
-    steps: [
-      { tool: "get_prose_styleguide_config", note: "Confirm the currently resolved config." },
-      { tool: "check_prose_styleguide_drift", note: "Detect non-conforming scenes. Pass project_id from context.project_id and set max_scenes from context.scene_count." },
-      { tool: "update_prose_styleguide_config", note: "If drift found and user approves, update config or note the outliers." },
-    ],
-  },
-  {
-    id: "manuscript_exploration",
-    label: "Manuscript exploration",
-    use_when: "Answering questions about the manuscript, finding scenes, or getting an overview.",
-    steps: [
-      { tool: "find_scenes", note: "Filter by character, beat, tag, part, chapter, or POV. No filters returns all scenes." },
-      { tool: "get_scene_prose", note: "Load prose for specific scenes identified by find_scenes." },
-      { tool: "get_chapter_prose", note: "Load all prose for a chapter. Use sparingly — large chapters can overflow context." },
-      { tool: "search_metadata", note: "Full-text search across scene metadata fields." },
-    ],
-  },
-  {
-    id: "prose_editing",
-    label: "Prose editing",
-    use_when: "Revising scene prose. All edits require explicit user confirmation before writing.",
-    steps: [
-      { tool: "find_scenes", note: "Identify the target scene." },
-      { tool: "get_scene_prose", note: "Load the current prose." },
-      { tool: "propose_edit", note: "Stage a revision; returns a diff preview and a proposal_id." },
-      { tool: "commit_edit", note: "Write the revision after the user confirms. Runs preflight checks before writing." },
-      { tool: "discard_edit", note: "Reject the revision if the user does not approve." },
-    ],
-  },
-  {
-    id: "character_management",
-    label: "Character management",
-    use_when: "Finding characters, reading their sheets, or updating character details.",
-    steps: [
-      { tool: "list_characters", note: "Find character_id values." },
-      { tool: "get_character_sheet", note: "Read full character details." },
-      { tool: "create_character_sheet", note: "Create a new character. Requires exactly one of project_id or universe_id." },
-      { tool: "update_character_sheet", note: "Edit character metadata." },
-    ],
-  },
-  {
-    id: "place_management",
-    label: "Place management",
-    use_when: "Finding locations, reading place sheets, or updating place details.",
-    steps: [
-      { tool: "list_places", note: "Find place_id values." },
-      { tool: "get_place_sheet", note: "Read full place details." },
-      { tool: "create_place_sheet", note: "Create a new place. Requires exactly one of project_id or universe_id." },
-      { tool: "update_place_sheet", note: "Edit place metadata." },
-    ],
-  },
-  {
-    id: "review_bundle",
-    label: "Review bundle",
-    use_when: "Preparing a formatted bundle for human review (outline, editorial, or beta read profile).",
-    steps: [
-      { tool: "preview_review_bundle", note: "Check which scenes would be included and the estimated size. Requires project_id and profile." },
-      { tool: "create_review_bundle", note: "Generate the bundle. Requires project_id." },
-    ],
-  },
-  {
-    id: "async_job_tracking",
-    label: "Async job tracking",
-    use_when: "A tool returned a job_id instead of an immediate result (e.g. import_scrivener_sync_async).",
-    steps: [
-      { tool: "get_async_job_status", note: "Poll with the job_id until status is 'completed' or 'failed'." },
-      { tool: "sync", note: "Call after a completed job that modified files on disk." },
-    ],
-  },
-];
-
 // ---------------------------------------------------------------------------
 // MCP server factory
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.10.4",
+  "version": "2.10.6",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -16,6 +16,8 @@
     "sync.js",
     "git.js",
     "world-entity-templates.js",
+    "workflow-catalogue.js",
+    "runtime-diagnostics.js",
     "metadata-lint.js",
     "scene-character-normalization.js",
     "review-bundles.js",
@@ -44,7 +46,7 @@
     "normalize:scene-characters": "node --experimental-sqlite scripts/normalize-scene-characters.mjs",
     "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/ tools/",
+    "lint": "eslint *.js scripts/ tools/",
     "docs": "node scripts/generate-tool-docs.mjs",
     "lint:metadata": "node scripts/lint-metadata.mjs",
     "test:unit": "node --experimental-sqlite --test test/unit/*.test.mjs",

package/review-bundles-planner.js

@@ -16,7 +16,7 @@ export class ReviewBundlePlanError extends Error {
 
 export function normalizeRecipientDisplayName(recipientName) {
   const normalized = String(recipientName ?? "")
-    .replace(/[\x00-\x1f\x7f]+/g, " ")
+    .replace(/[\x00-\x1f\x7f]+/g, " ") // eslint-disable-line no-control-regex
     .replace(/\s+/g, " ")
     .trim()
     .slice(0, 100);

package/review-bundles-renderer.js

@@ -7,7 +7,7 @@ import { ReviewBundlePlanError, normalizeRecipientDisplayName } from "./review-b
 function escapeMarkdown(text) {
   return String(text ?? "")
     .replace(/\\/g, "\\\\")
-    .replace(/([*_`\[\]#])/g, "\\$1");
+    .replace(/([*_`[\]#])/g, "\\$1");
 }
 
 function renderBetaNoticeMarkdown({ projectId, recipientName }) {

package/runtime-diagnostics.js

@@ -0,0 +1,97 @@
+/**
+ * getRuntimeDiagnostics
+ *
+ * Inspects the startup environment and returns { warnings, recommendations }.
+ * All inputs are passed explicitly so this module has no side effects and
+ * is straightforward to test.
+ *
+ * @param {object} opts
+ * @param {string}  opts.ownershipGuardModeRaw      Raw env value before normalisation
+ * @param {string}  opts.ownershipGuardMode          Normalised value ("warn" | "fail")
+ * @param {string}  opts.ownershipGuardModeRawDisplay JSON.stringify of the raw value
+ * @param {boolean} opts.syncDirWritable
+ * @param {string}  opts.syncDirAbs                 Resolved absolute path shown in messages
+ * @param {object}  opts.syncOwnershipDiagnostics   Result of getSyncOwnershipDiagnostics()
+ * @param {boolean} opts.gitAvailable
+ * @param {boolean} opts.gitEnabled
+ * @returns {{ warnings: string[], recommendations: string[] }}
+ */
+export function getRuntimeDiagnostics({
+  ownershipGuardModeRaw,
+  ownershipGuardMode,
+  ownershipGuardModeRawDisplay,
+  syncDirWritable,
+  syncDirAbs,
+  syncOwnershipDiagnostics,
+  gitAvailable,
+  gitEnabled,
+}) {
+  const warnings = [];
+  const recommendations = [];
+
+  if (ownershipGuardModeRaw !== ownershipGuardMode) {
+    warnings.push(
+      `OWNERSHIP_GUARD_MODE_INVALID: Unsupported OWNERSHIP_GUARD_MODE=${ownershipGuardModeRawDisplay}. Falling back to 'warn'.`
+    );
+    recommendations.push("Set OWNERSHIP_GUARD_MODE to either 'warn' or 'fail'.");
+  }
+
+  if (syncOwnershipDiagnostics.runtime_uid_override_ignored) {
+    warnings.push("RUNTIME_UID_OVERRIDE_IGNORED: RUNTIME_UID_OVERRIDE is ignored unless NODE_ENV=test or ALLOW_RUNTIME_UID_OVERRIDE=1.");
+    recommendations.push("Avoid RUNTIME_UID_OVERRIDE in production runtime environments.");
+  }
+
+  if (syncOwnershipDiagnostics.runtime_uid_override_invalid) {
+    warnings.push("RUNTIME_UID_OVERRIDE_INVALID: RUNTIME_UID_OVERRIDE must be a non-negative integer when enabled.");
+    recommendations.push("Set RUNTIME_UID_OVERRIDE to a non-negative integer, or unset it.");
+  }
+
+  if (!syncDirWritable) {
+    warnings.push("SYNC_DIR_READ_ONLY: sync dir is read-only; metadata write-back and prose editing tools are unavailable.");
+    recommendations.push("Mount WRITING_SYNC_DIR with write access (avoid read-only mounts like ':ro').");
+    recommendations.push("If running in Docker/OpenClaw, verify volume ownership and permissions for the container user.");
+  }
+
+  if (syncOwnershipDiagnostics.supported && syncOwnershipDiagnostics.non_runtime_owned_paths > 0) {
+    warnings.push(
+      `OWNERSHIP_MISMATCH: ${syncOwnershipDiagnostics.non_runtime_owned_paths} sampled path(s) are not owned by runtime UID ${syncOwnershipDiagnostics.runtime_uid}.`
+    );
+    recommendations.push(
+      `Repair ownership once on host: sudo chown -R "$(id -u):$(id -g)" "${syncDirAbs}"`
+    );
+    recommendations.push(
+      "For Docker/OpenClaw, run container as host user (compose: user: \"${OPENCLAW_UID:-1000}:${OPENCLAW_GID:-1000}\")."
+    );
+  }
+
+  if (ownershipGuardMode === "fail" && syncOwnershipDiagnostics.runtime_uid === 0) {
+    warnings.push(
+      "OWNERSHIP_GUARD_SKIPPED_FOR_ROOT: OWNERSHIP_GUARD_MODE=fail is skipped because runtime UID is 0 (root)."
+    );
+    recommendations.push("Prefer running as a non-root host-mapped UID/GID to make ownership guard checks meaningful.");
+  }
+
+  if (syncOwnershipDiagnostics.supported && syncOwnershipDiagnostics.root_owned_paths > 0) {
+    warnings.push(
+      `ROOT_OWNED_PATHS: ${syncOwnershipDiagnostics.root_owned_paths} sampled path(s) are owned by UID 0 (root).`
+    );
+  }
+
+  if (!gitAvailable) {
+    warnings.push("GIT_NOT_FOUND: git is not available on PATH; snapshot/edit tools are unavailable.");
+    recommendations.push("Install git in the runtime image/environment.");
+  }
+
+  if (gitAvailable && syncDirWritable && !gitEnabled) {
+    warnings.push("GIT_DISABLED: git is available but repository snapshot tools are not active.");
+    recommendations.push("Ensure WRITING_SYNC_DIR points to a writable git repository root, or allow mcp-writing to initialize one.");
+  }
+
+  if (gitAvailable && !syncDirWritable) {
+    recommendations.push("If git reports 'dubious ownership' for mounted repos, add: git config --system --add safe.directory /sync");
+  }
+
+  recommendations.push("If indexing finds many files without scene_id, run scripts/import.js first for Scrivener Draft exports, then run sync.");
+
+  return { warnings, recommendations };
+}

package/scrivener-direct.js

@@ -705,7 +705,7 @@ export function mergeScrivenerProjectMetadata({
       });
     }
 
-    let didRelocate = false;
+    let didRelocate;
 
     if (dryRun) {
       logger(`  DRY   ${filename}`);

package/workflow-catalogue.js

@@ -0,0 +1,95 @@
+export const WORKFLOW_CATALOGUE = [
+  {
+    id: "first_time_setup",
+    label: "First-time setup",
+    use_when: "Connecting to a project for the first time or verifying the runtime is correctly configured.",
+    steps: [
+      { tool: "get_runtime_config", note: "Verify sync dir, writability, and git availability." },
+      { tool: "sync", note: "Index scenes from disk." },
+    ],
+  },
+  {
+    id: "styleguide_setup_new",
+    label: "Styleguide setup (new project)",
+    use_when: "No prose styleguide config exists and you want to create one based on the manuscript's existing conventions.",
+    steps: [
+      { tool: "describe_workflows", note: "Check context.scene_count; use that value as max_scenes in the next call." },
+      { tool: "bootstrap_prose_styleguide_config", note: "Detect dominant conventions. Confirm suggestions with the user before applying." },
+      { tool: "setup_prose_styleguide_config", note: "Only if ALL context.styleguide_exists fields are false — a config at any scope is sufficient. Create at project_root scope (requires project_id and language e.g. 'english_us'), or sync_root if no project_id is known." },
+      { tool: "update_prose_styleguide_config", note: "Apply the fields accepted from bootstrap suggestions." },
+    ],
+  },
+  {
+    id: "styleguide_drift_check",
+    label: "Styleguide drift check",
+    use_when: "A styleguide config exists and you want to check whether recent scenes conform to it.",
+    steps: [
+      { tool: "get_prose_styleguide_config", note: "Confirm the currently resolved config." },
+      { tool: "check_prose_styleguide_drift", note: "Detect non-conforming scenes. Pass project_id from context.project_id and set max_scenes from context.scene_count." },
+      { tool: "update_prose_styleguide_config", note: "If drift found and user approves, update config or note the outliers." },
+    ],
+  },
+  {
+    id: "manuscript_exploration",
+    label: "Manuscript exploration",
+    use_when: "Answering questions about the manuscript, finding scenes, or getting an overview.",
+    steps: [
+      { tool: "find_scenes", note: "Filter by character, beat, tag, part, chapter, or POV. No filters returns all scenes." },
+      { tool: "get_scene_prose", note: "Load prose for specific scenes identified by find_scenes." },
+      { tool: "get_chapter_prose", note: "Load all prose for a chapter. Use sparingly — large chapters can overflow context." },
+      { tool: "search_metadata", note: "Full-text search across scene metadata fields." },
+    ],
+  },
+  {
+    id: "prose_editing",
+    label: "Prose editing",
+    use_when: "Revising scene prose. All edits require explicit user confirmation before writing.",
+    steps: [
+      { tool: "find_scenes", note: "Identify the target scene." },
+      { tool: "get_scene_prose", note: "Load the current prose." },
+      { tool: "propose_edit", note: "Stage a revision; returns a diff preview and a proposal_id." },
+      { tool: "commit_edit", note: "Write the revision after the user confirms. Runs preflight checks before writing." },
+      { tool: "discard_edit", note: "Reject the revision if the user does not approve." },
+    ],
+  },
+  {
+    id: "character_management",
+    label: "Character management",
+    use_when: "Finding characters, reading their sheets, or updating character details.",
+    steps: [
+      { tool: "list_characters", note: "Find character_id values." },
+      { tool: "get_character_sheet", note: "Read full character details." },
+      { tool: "create_character_sheet", note: "Create a new character. Requires exactly one of project_id or universe_id." },
+      { tool: "update_character_sheet", note: "Edit character metadata." },
+    ],
+  },
+  {
+    id: "place_management",
+    label: "Place management",
+    use_when: "Finding locations, reading place sheets, or updating place details.",
+    steps: [
+      { tool: "list_places", note: "Find place_id values." },
+      { tool: "get_place_sheet", note: "Read full place details." },
+      { tool: "create_place_sheet", note: "Create a new place. Requires exactly one of project_id or universe_id." },
+      { tool: "update_place_sheet", note: "Edit place metadata." },
+    ],
+  },
+  {
+    id: "review_bundle",
+    label: "Review bundle",
+    use_when: "Preparing a formatted bundle for human review (outline, editorial, or beta read profile).",
+    steps: [
+      { tool: "preview_review_bundle", note: "Check which scenes would be included and the estimated size. Requires project_id and profile." },
+      { tool: "create_review_bundle", note: "Generate the bundle. Requires project_id." },
+    ],
+  },
+  {
+    id: "async_job_tracking",
+    label: "Async job tracking",
+    use_when: "A tool returned a job_id instead of an immediate result (e.g. import_scrivener_sync_async).",
+    steps: [
+      { tool: "get_async_job_status", note: "Poll with the job_id until status is 'completed' or 'failed'." },
+      { tool: "sync", note: "Call after a completed job that modified files on disk." },
+    ],
+  },
+];