@hanna84/mcp-writing 2.0.4 → 2.2.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.2.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.1.0...v2.2.0)
+
+- feat(styleguide): add prose styleguide config resolution and MCP tools [`#84`](https://github.com/hannasdev/mcp-writing.git
+/pull/84)
+
+#### [v2.1.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.0.4...v2.1.0)
+
+> 25 April 2026
+
+- feat(tools): add scene character normalization utility [`#83`](https://github.com/hannasdev/mcp-writing.git
+/pull/83)
+- Release 2.1.0 [`33b5b31`](https://github.com/hannasdev/mcp-writing.git
+/commit/33b5b31846576ef18385e6678f74cc109995fcac)
+
 #### [v2.0.4](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.0.3...v2.0.4)
 
+> 25 April 2026
+
 - docs(prd): mark review-bundles and scrivener-direct as done [`#82`](https://github.com/hannasdev/mcp-writing.git
 /pull/82)
+- Release 2.0.4 [`775bbcf`](https://github.com/hannasdev/mcp-writing.git
+/commit/775bbcfa0fb93e2b9828a94fa60ad53b29c7313c)
 
 #### [v2.0.3](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.0.2...v2.0.3)

package/index.js

@@ -17,6 +17,12 @@ import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, lis
 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 {
+  STYLEGUIDE_CONFIG_BASENAME,
+  STYLEGUIDE_ENUMS,
+  buildStyleguideConfigDraft,
+  resolveStyleguideConfig,
+} from "./prose-styleguide.js";
 import {
   REVIEW_BUNDLE_PROFILES,
   REVIEW_BUNDLE_STRICTNESS,
@@ -51,6 +57,31 @@ function isPathInsideSyncDir(candidatePath) {
   return !(rel.startsWith("..") || path.isAbsolute(rel));
 }
 
+// Like isPathInsideSyncDir, but works for paths that do not yet exist by
+// walking up to the nearest existing ancestor before canonicalising.
+function isPathCandidateInsideSyncDir(candidatePath) {
+  const resolvedCandidate = path.resolve(candidatePath);
+
+  let existingAncestor = resolvedCandidate;
+  while (!fs.existsSync(existingAncestor)) {
+    const parent = path.dirname(existingAncestor);
+    if (parent === existingAncestor) break;
+    existingAncestor = parent;
+  }
+
+  const canonicalBase = (() => {
+    try {
+      return fs.realpathSync(existingAncestor);
+    } catch {
+      return existingAncestor;
+    }
+  })();
+
+  const canonical = path.resolve(canonicalBase, path.relative(existingAncestor, resolvedCandidate));
+  const rel = path.relative(SYNC_DIR_REAL, canonical);
+  return !(rel.startsWith("..") || path.isAbsolute(rel));
+}
+
 function resolveOutputDirWithinSync(outputDir) {
   let resolvedOutputDir = path.resolve(outputDir);
   let existingAncestor = resolvedOutputDir;
@@ -1346,6 +1377,142 @@ function createMcpServer() {
     }
   );
 
+  // ---- prose styleguide ---------------------------------------------------
+  s.tool(
+    "setup_prose_styleguide_config",
+    "Create prose-styleguide.config.yaml at sync root or project root using language defaults plus optional explicit overrides.",
+    {
+      scope: z.enum(["sync_root", "project_root"]).optional().describe("Config write target scope. Defaults to project_root when project_id is supplied, otherwise sync_root."),
+      project_id: z.string().optional().describe("Project ID when writing project_root config (e.g. 'the-lamb' or 'universe-1/book-1')."),
+      language: z.enum(STYLEGUIDE_ENUMS.language).describe("Primary writing language. Seeds language-specific defaults."),
+      overrides: z.object({
+        spelling: z.enum(STYLEGUIDE_ENUMS.spelling).optional(),
+        quotation_style: z.enum(STYLEGUIDE_ENUMS.quotation_style).optional(),
+        quotation_style_nested: z.enum(STYLEGUIDE_ENUMS.quotation_style_nested).optional(),
+        em_dash_spacing: z.enum(STYLEGUIDE_ENUMS.em_dash_spacing).optional(),
+        ellipsis_style: z.enum(STYLEGUIDE_ENUMS.ellipsis_style).optional(),
+        abbreviation_periods: z.enum(STYLEGUIDE_ENUMS.abbreviation_periods).optional(),
+        oxford_comma: z.enum(STYLEGUIDE_ENUMS.oxford_comma).optional(),
+        numbers: z.enum(STYLEGUIDE_ENUMS.numbers).optional(),
+        date_format: z.enum(STYLEGUIDE_ENUMS.date_format).optional(),
+        time_format: z.enum(STYLEGUIDE_ENUMS.time_format).optional(),
+        tense: z.string().optional(),
+        pov: z.enum(STYLEGUIDE_ENUMS.pov).optional(),
+        dialogue_tags: z.enum(STYLEGUIDE_ENUMS.dialogue_tags).optional(),
+        sentence_fragments: z.enum(STYLEGUIDE_ENUMS.sentence_fragments).optional(),
+      }).optional().describe("Optional overrides layered on top of language defaults."),
+      voice_notes: z.string().optional().describe("Optional freeform voice notes to include in config."),
+      overwrite: z.boolean().optional().describe("If true, replaces an existing config file at the target location."),
+    },
+    async ({ scope, project_id, language, overrides = {}, voice_notes, overwrite = false }) => {
+      const resolvedScope = scope ?? (project_id ? "project_root" : "sync_root");
+
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      if (resolvedScope === "project_root" && !project_id) {
+        return errorResponse(
+          "PROJECT_ID_REQUIRED",
+          "project_id is required when scope=project_root."
+        );
+      }
+
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse(
+          "SYNC_DIR_NOT_WRITABLE",
+          "Cannot write styleguide config because WRITING_SYNC_DIR is not writable in this runtime.",
+          { sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      const targetPath = resolvedScope === "sync_root"
+        ? path.join(SYNC_DIR, STYLEGUIDE_CONFIG_BASENAME)
+        : path.join(resolveProjectRoot(project_id), STYLEGUIDE_CONFIG_BASENAME);
+
+      if (!isPathCandidateInsideSyncDir(targetPath)) {
+        return errorResponse(
+          "INVALID_CONFIG_PATH",
+          "Resolved styleguide config path must be inside WRITING_SYNC_DIR.",
+          { target_path: path.resolve(targetPath), sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      if (fs.existsSync(targetPath) && !overwrite) {
+        return errorResponse(
+          "STYLEGUIDE_CONFIG_EXISTS",
+          "Styleguide config already exists at target path. Set overwrite=true to replace it.",
+          { target_path: path.resolve(targetPath) }
+        );
+      }
+
+      const draft = buildStyleguideConfigDraft({
+        language,
+        overrides,
+        voice_notes,
+      });
+      if (!draft.ok) {
+        return errorResponse(
+          draft.error.code,
+          draft.error.message,
+          draft.error.details
+        );
+      }
+
+      fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+      fs.writeFileSync(targetPath, yaml.dump(draft.config, { lineWidth: 120 }), "utf8");
+
+      return jsonResponse({
+        ok: true,
+        scope: resolvedScope,
+        file_path: path.resolve(targetPath),
+        config: draft.config,
+        inferred_defaults: draft.inferred_defaults,
+        warnings: draft.warnings,
+      });
+    }
+  );
+
+  s.tool(
+    "get_prose_styleguide_config",
+    "Resolve prose-styleguide.config.yaml with cascading precedence (sync root, then universe root, then project root). Applies language-derived defaults and nested quotation defaults when omitted.",
+    {
+      project_id: z.string().optional().describe("Optional project ID for project-scoped resolution (e.g. 'the-lamb' or 'universe-1/book-1')."),
+    },
+    async ({ project_id }) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      const resolved = resolveStyleguideConfig({
+        syncDir: SYNC_DIR,
+        projectId: project_id,
+      });
+
+      if (!resolved.ok) {
+        return errorResponse(
+          resolved.error.code,
+          resolved.error.message,
+          resolved.error.details
+        );
+      }
+
+      return jsonResponse({
+        ok: true,
+        styleguide: resolved,
+        next_step: resolved.setup_required
+          ? "No prose-styleguide.config.yaml was found. Run setup to create one at sync root or project root."
+          : "Config resolved successfully.",
+      });
+    }
+  );
+
   // ---- preview_review_bundle ----------------------------------------------
   s.tool(
     "preview_review_bundle",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -15,7 +15,9 @@
     "git.js",
     "world-entity-templates.js",
     "metadata-lint.js",
+    "scene-character-normalization.js",
     "review-bundles.js",
+    "prose-styleguide.js",
     "scripts/",
     "README.md",
     "CHANGELOG.md"
@@ -31,6 +33,7 @@
     "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",
+    "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/",

package/prose-styleguide.js

@@ -0,0 +1,494 @@
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+export const STYLEGUIDE_CONFIG_BASENAME = "prose-styleguide.config.yaml";
+
+const ENUMS = {
+  language: [
+    "english_us",
+    "english_uk",
+    "english_au",
+    "english_ca",
+    "swedish",
+    "norwegian",
+    "danish",
+    "finnish",
+    "french",
+    "italian",
+    "russian",
+    "portuguese_pt",
+    "portuguese_br",
+    "german",
+    "dutch",
+    "polish",
+    "czech",
+    "hungarian",
+    "spanish",
+    "irish",
+    "japanese",
+    "korean",
+    "chinese_traditional",
+    "chinese_simplified",
+  ],
+  spelling: ["uk", "us", "au", "ca"],
+  quotation_style: [
+    "double",
+    "single",
+    "guillemets",
+    "low9",
+    "dialogue_dash_en",
+    "dialogue_dash_em",
+    "corner_brackets",
+  ],
+  quotation_style_nested: [
+    "double",
+    "single",
+    "guillemets_single",
+    "low9_single",
+    "corner_brackets_double",
+  ],
+  em_dash_spacing: ["closed", "spaced"],
+  ellipsis_style: ["three_periods", "ellipsis_char", "spaced"],
+  abbreviation_periods: ["with", "without"],
+  oxford_comma: ["yes", "no"],
+  numbers: ["spell_under_10", "spell_under_100", "always_spell", "numerals"],
+  date_format: ["mdy", "dmy"],
+  time_format: ["12h", "24h"],
+  tense: ["present", "past"],
+  pov: ["first", "third_limited", "third_omniscient"],
+  dialogue_tags: ["minimal", "expressive"],
+  sentence_fragments: ["disallow", "intentional"],
+};
+
+export const STYLEGUIDE_ENUMS = Object.freeze(
+  Object.fromEntries(
+    Object.entries(ENUMS).map(([key, values]) => [key, [...values]])
+  )
+);
+
+// Fields that are valid in a config but are not enum-constrained.
+const SPECIAL_FIELDS = new Set(["voice_notes"]);
+
+const LANGUAGE_DEFAULTS = {
+  english_us: {
+    spelling: "us",
+    quotation_style: "double",
+    em_dash_spacing: "closed",
+    abbreviation_periods: "with",
+    oxford_comma: "yes",
+    date_format: "mdy",
+  },
+  english_uk: {
+    spelling: "uk",
+    quotation_style: "single",
+    em_dash_spacing: "spaced",
+    abbreviation_periods: "without",
+    oxford_comma: "no",
+    date_format: "dmy",
+  },
+  english_au: {
+    spelling: "au",
+    quotation_style: "double",
+    em_dash_spacing: "closed",
+    abbreviation_periods: "without",
+    oxford_comma: "yes",
+    date_format: "dmy",
+  },
+  english_ca: {
+    spelling: "ca",
+    quotation_style: "double",
+    em_dash_spacing: "spaced",
+    abbreviation_periods: "without",
+    oxford_comma: "yes",
+    date_format: "dmy",
+  },
+  swedish: {
+    quotation_style: "dialogue_dash_en",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  norwegian: {
+    quotation_style: "dialogue_dash_en",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  danish: {
+    quotation_style: "dialogue_dash_en",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  finnish: {
+    quotation_style: "guillemets",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  french: {
+    quotation_style: "guillemets",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  italian: {
+    quotation_style: "guillemets",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  russian: {
+    quotation_style: "guillemets",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  portuguese_pt: {
+    quotation_style: "guillemets",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  portuguese_br: {
+    quotation_style: "double",
+    em_dash_spacing: "closed",
+    date_format: "dmy",
+  },
+  german: {
+    quotation_style: "low9",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  dutch: {
+    quotation_style: "low9",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  polish: {
+    quotation_style: "low9",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  czech: {
+    quotation_style: "low9",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  hungarian: {
+    quotation_style: "low9",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  spanish: {
+    quotation_style: "dialogue_dash_em",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  irish: {
+    quotation_style: "dialogue_dash_em",
+    em_dash_spacing: "spaced",
+    date_format: "dmy",
+  },
+  japanese: {
+    quotation_style: "corner_brackets",
+  },
+  korean: {
+    quotation_style: "corner_brackets",
+  },
+  chinese_traditional: {
+    quotation_style: "corner_brackets",
+  },
+  chinese_simplified: {
+    quotation_style: "double",
+  },
+};
+
+function projectRootFromId(syncDir, projectId) {
+  if (!projectId.includes("/")) {
+    return path.join(syncDir, "projects", projectId);
+  }
+  const [universeId, projectSlug] = projectId.split("/");
+  return path.join(syncDir, "universes", universeId, projectSlug);
+}
+
+function inferNestedQuotationStyle(quotationStyle) {
+  if (quotationStyle === "double") return "single";
+  if (quotationStyle === "single") return "double";
+  if (quotationStyle === "guillemets") return "guillemets_single";
+  if (quotationStyle === "low9") return "low9_single";
+  if (quotationStyle === "corner_brackets") return "corner_brackets_double";
+  return null;
+}
+
+function normalizeTense(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return null;
+
+  if (trimmed.startsWith("present")) return "present";
+  if (trimmed.startsWith("past")) return "past";
+  return trimmed;
+}
+
+function normalizeConfigShape(rawConfig) {
+  const normalized = Object.create(null);
+  for (const [key, value] of Object.entries(rawConfig ?? {})) {
+    // Skip null/undefined — treat as unset, same as a missing key.
+    if (value === null || value === undefined) continue;
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (trimmed !== "") {
+        normalized[key] = trimmed;
+      }
+      continue;
+    }
+    normalized[key] = value;
+  }
+  return normalized;
+}
+
+function validateConfig(config, sourcePath) {
+  const normalized = normalizeConfigShape(config);
+  const sanitized = Object.create(null);
+  const errors = [];
+  const unknownFields = [];
+
+  for (const [key, value] of Object.entries(normalized)) {
+    if (!Object.hasOwn(ENUMS, key) && !SPECIAL_FIELDS.has(key)) {
+      unknownFields.push(key);
+      continue;
+    }
+
+    if (SPECIAL_FIELDS.has(key)) {
+      if (typeof value !== "string") {
+        errors.push({
+          code: "INVALID_TYPE",
+          field: key,
+          message: `${key} must be a string.`,
+          source: sourcePath,
+        });
+      }
+      if (typeof value === "string") {
+        sanitized[key] = value;
+      }
+      continue;
+    }
+
+    if (typeof value !== "string") {
+      errors.push({
+        code: "INVALID_TYPE",
+        field: key,
+        message: `${key} must be a string enum value.`,
+        source: sourcePath,
+      });
+      continue;
+    }
+
+    const valueToCheck = key === "tense" ? normalizeTense(value) : value;
+    if (!ENUMS[key].includes(valueToCheck)) {
+      errors.push({
+        code: "INVALID_ENUM",
+        field: key,
+        message: `${key} must be one of: ${ENUMS[key].join(", ")}.`,
+        source: sourcePath,
+        received: value,
+      });
+      continue;
+    }
+
+    sanitized[key] = value;
+  }
+
+  return {
+    normalized: sanitized,
+    errors,
+    unknownFields,
+  };
+}
+
+function readConfigFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+
+  let parsed;
+  try {
+    parsed = yaml.load(fs.readFileSync(filePath, "utf8"));
+  } catch (error) {
+    return {
+      ok: false,
+      errors: [{
+        code: "INVALID_YAML",
+        message: error instanceof Error ? error.message : "Invalid YAML.",
+        source: filePath,
+      }],
+    };
+  }
+
+  if (parsed === null || parsed === undefined) {
+    return { ok: true, config: {} };
+  }
+
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      ok: false,
+      errors: [{
+        code: "INVALID_CONFIG",
+        message: "Config file must parse to an object.",
+        source: filePath,
+      }],
+    };
+  }
+
+  const { normalized, errors, unknownFields } = validateConfig(parsed, filePath);
+  if (errors.length > 0) {
+    return { ok: false, errors };
+  }
+
+  return {
+    ok: true,
+    config: normalized,
+    unknown_fields: unknownFields,
+  };
+}
+
+function getConfigCandidates(syncDir, projectId) {
+  const candidates = [
+    {
+      scope: "sync_root",
+      file_path: path.join(syncDir, STYLEGUIDE_CONFIG_BASENAME),
+    },
+  ];
+
+  if (!projectId) return candidates;
+
+  if (projectId.includes("/")) {
+    const [universeId] = projectId.split("/");
+    candidates.push({
+      scope: "universe_root",
+      file_path: path.join(syncDir, "universes", universeId, STYLEGUIDE_CONFIG_BASENAME),
+    });
+  }
+
+  candidates.push({
+    scope: "project_root",
+    file_path: path.join(projectRootFromId(syncDir, projectId), STYLEGUIDE_CONFIG_BASENAME),
+  });
+
+  return candidates;
+}
+
+function applyDerivedDefaults(config) {
+  const resolved = { ...config };
+  const inferred_defaults = {};
+
+  if (resolved.language && LANGUAGE_DEFAULTS[resolved.language]) {
+    const defaults = LANGUAGE_DEFAULTS[resolved.language];
+    for (const [key, value] of Object.entries(defaults)) {
+      if (resolved[key] === undefined) {
+        resolved[key] = value;
+        inferred_defaults[key] = value;
+      }
+    }
+  }
+
+  if (!resolved.quotation_style_nested && resolved.quotation_style) {
+    const nested = inferNestedQuotationStyle(resolved.quotation_style);
+    if (nested) {
+      resolved.quotation_style_nested = nested;
+      inferred_defaults.quotation_style_nested = nested;
+    }
+  }
+
+  if (resolved.tense) {
+    resolved.tense = normalizeTense(resolved.tense);
+  }
+
+  return { resolved, inferred_defaults };
+}
+
+export function buildStyleguideConfigDraft({ language, overrides = {}, voice_notes }) {
+  const overrideValidation = validateConfig(overrides, "<overrides>");
+  if (overrideValidation.errors.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_STYLEGUIDE_OVERRIDE",
+        message: "Requested styleguide overrides failed validation.",
+        details: overrideValidation.errors,
+      },
+    };
+  }
+
+  if (!ENUMS.language.includes(language)) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_STYLEGUIDE_LANGUAGE",
+        message: `language must be one of: ${ENUMS.language.join(", ")}.`,
+      },
+    };
+  }
+
+  const merged = {
+    ...overrideValidation.normalized,
+    language,
+  };
+
+  if (typeof voice_notes === "string" && voice_notes.trim()) {
+    merged.voice_notes = voice_notes.trim();
+  }
+
+  const { resolved, inferred_defaults } = applyDerivedDefaults(merged);
+  return {
+    ok: true,
+    config: resolved,
+    inferred_defaults,
+    warnings: {
+      unknown_fields: overrideValidation.unknownFields,
+    },
+  };
+}
+
+export function resolveStyleguideConfig({ syncDir, projectId }) {
+  const candidates = getConfigCandidates(syncDir, projectId);
+  const sources = [];
+  const unknownFields = [];
+  const merged = Object.create(null);
+
+  for (const candidate of candidates) {
+    const loaded = readConfigFile(candidate.file_path);
+    if (loaded === null) continue;
+
+    if (!loaded.ok) {
+      return {
+        ok: false,
+        error: {
+          code: "INVALID_STYLEGUIDE_CONFIG",
+          message: "Styleguide config validation failed.",
+          details: {
+            file_path: candidate.file_path,
+            issues: loaded.errors,
+          },
+        },
+      };
+    }
+
+    Object.assign(merged, loaded.config);
+    if (loaded.unknown_fields?.length) {
+      for (const field of loaded.unknown_fields) {
+        unknownFields.push({ scope: candidate.scope, field, source: candidate.file_path });
+      }
+    }
+
+    sources.push({
+      scope: candidate.scope,
+      file_path: candidate.file_path,
+    });
+  }
+
+  const { resolved, inferred_defaults } = applyDerivedDefaults(merged);
+  return {
+    ok: true,
+    config_found: sources.length > 0,
+    setup_required: sources.length === 0,
+    resolved_config: sources.length > 0 ? resolved : null,
+    inferred_defaults,
+    sources,
+    warnings: {
+      unknown_fields: unknownFields,
+    },
+  };
+}

package/scene-character-batch.js

@@ -1,69 +1,10 @@
 import fs from "node:fs";
 import matter from "gray-matter";
+import { buildCharacterNormalizationContext, escapeRegex, resolveCharacterReference } from "./scene-character-normalization.js";
 import { normalizeSceneMetaForPath, readMeta, writeMeta } from "./sync.js";
 
-const NON_DISTINCTIVE_TOKENS = new Set([
-  "the",
-  "and",
-  "for",
-  "with",
-  "from",
-  "into",
-  "onto",
-  "over",
-  "under",
-  "after",
-  "before",
-  "about",
-  "around",
-]);
-
-function escapeRegex(text) {
-  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-
-function isDistinctiveToken(token) {
-  return Boolean(token) && token.length >= 3 && !NON_DISTINCTIVE_TOKENS.has(token);
-}
-
 function normalizeCharacterRows(rows) {
-  const clean = rows
-    .filter(row => row?.character_id && row?.name)
-    .map(row => {
-      const phrase_tokens = String(row.name).toLowerCase().split(/\s+/).filter(Boolean);
-      const tokens = [...new Set(phrase_tokens)];
-      return {
-        character_id: row.character_id,
-        name: String(row.name).trim(),
-        phrase_tokens,
-        tokens,
-        informative_tokens: tokens.filter(isDistinctiveToken),
-        full_name_regex: phrase_tokens.length > 1
-          ? new RegExp(`\\b${phrase_tokens.map(escapeRegex).join("\\s+")}\\b`, "i")
-          : null,
-      };
-    })
-    .filter(row => row.name.length > 0);
-
-  const tokenMap = new Map();
-  const byId = new Map();
-  const nameMap = new Map();
-  for (const row of clean) {
-    byId.set(row.character_id, row);
-
-    const normalizedName = row.name.toLowerCase();
-    const exactNameIds = nameMap.get(normalizedName) ?? [];
-    exactNameIds.push(row.character_id);
-    nameMap.set(normalizedName, exactNameIds);
-
-    for (const token of row.informative_tokens) {
-      const ids = tokenMap.get(token) ?? [];
-      ids.push(row.character_id);
-      tokenMap.set(token, ids);
-    }
-  }
-
-  return { clean, tokenMap, byId, nameMap };
+  return buildCharacterNormalizationContext(rows);
 }
 
 function inferCharactersFromProse(prose, characterRows) {
@@ -113,32 +54,7 @@ function inferCharactersFromProse(prose, characterRows) {
 }
 
 function resolveCharacterEntry(entry, characterRows) {
-  const value = String(entry ?? "").trim();
-  if (!value) return null;
-
-  if (characterRows.byId.has(value)) {
-    return value;
-  }
-
-  const exactNameIds = characterRows.nameMap.get(value.toLowerCase());
-  if (exactNameIds?.length === 1) {
-    return exactNameIds[0];
-  }
-
-  const words = value.toLowerCase().split(/\s+/).filter(isDistinctiveToken);
-  if (words.length === 0) {
-    return value;
-  }
-
-  const matches = characterRows.clean.filter(row =>
-    words.every(word => row.informative_tokens.includes(word))
-  );
-
-  if (matches.length === 1) {
-    return matches[0].character_id;
-  }
-
-  return value;
+  return resolveCharacterReference(entry, characterRows);
 }
 
 function pruneLessSpecificCharacters(characterIds, fullNameMatches, characterRows) {

package/scene-character-normalization.js

@@ -0,0 +1,199 @@
+export const NON_DISTINCTIVE_TOKENS = new Set([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "into",
+  "onto",
+  "over",
+  "under",
+  "after",
+  "before",
+  "about",
+  "around",
+]);
+
+export function escapeRegex(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function isDistinctiveToken(token) {
+  const normalized = String(token ?? "").trim().toLowerCase();
+  return Boolean(normalized) && normalized.length >= 3 && !NON_DISTINCTIVE_TOKENS.has(normalized);
+}
+
+function normalizeRawCharacterValues(values) {
+  const raw = Array.isArray(values) ? values : [];
+  const seen = new Set();
+  const normalized = [];
+
+  for (const value of raw) {
+    const text = String(value ?? "").trim();
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    normalized.push(text);
+  }
+
+  return normalized;
+}
+
+function tokenizeValue(value) {
+  return [...new Set(String(value ?? "").toLowerCase().split(/\s+/).filter(isDistinctiveToken))];
+}
+
+export function buildCharacterNormalizationContext(rows) {
+  const clean = (Array.isArray(rows) ? rows : [])
+    .filter(row => row?.character_id && row?.name)
+    .map(row => {
+      const character_id = String(row.character_id).trim();
+      const name = String(row.name).trim();
+      const phrase_tokens = name.toLowerCase().split(/\s+/).filter(Boolean);
+      const tokens = [...new Set(phrase_tokens)];
+      return {
+        character_id,
+        name,
+        phrase_tokens,
+        tokens,
+        informative_tokens: tokens.filter(isDistinctiveToken),
+        full_name_regex: phrase_tokens.length > 1
+          ? new RegExp(`\\b${phrase_tokens.map(escapeRegex).join("\\s+")}\\b`, "i")
+          : null,
+      };
+    })
+    .filter(row => row.character_id.length > 0 && row.name.length > 0);
+
+  const byId = new Map();
+  const nameMap = new Map();
+  const tokenMap = new Map();
+  for (const row of clean) {
+    byId.set(row.character_id, row);
+    const normalizedName = row.name.toLowerCase();
+    const ids = nameMap.get(normalizedName) ?? [];
+    ids.push(row.character_id);
+    nameMap.set(normalizedName, ids);
+
+    for (const token of row.informative_tokens) {
+      const tokenIds = tokenMap.get(token) ?? [];
+      tokenIds.push(row.character_id);
+      tokenMap.set(token, tokenIds);
+    }
+  }
+
+  return { clean, byId, nameMap, tokenMap };
+}
+
+export function resolveCharacterReference(value, context) {
+  const text = String(value ?? "").trim();
+  if (!text) return null;
+
+  if (context.byId.has(text)) {
+    return text;
+  }
+
+  const exactNameIds = context.nameMap.get(text.toLowerCase());
+  if (exactNameIds?.length === 1) {
+    return exactNameIds[0];
+  }
+
+  const words = text.toLowerCase().split(/\s+/).filter(isDistinctiveToken);
+  if (words.length === 0) {
+    return text;
+  }
+
+  const matches = context.clean.filter(row =>
+    words.every(word => row.informative_tokens.includes(word))
+  );
+
+  if (matches.length === 1) {
+    return matches[0].character_id;
+  }
+
+  return text;
+}
+
+function isProperSubset(subsetTokens, supersetTokens) {
+  if (subsetTokens.length < 2 || subsetTokens.length >= supersetTokens.length) {
+    return false;
+  }
+  return subsetTokens.every(token => supersetTokens.includes(token));
+}
+
+function hasMoreSpecificNonCanonicalSource(candidate, sourceInfo) {
+  if (!sourceInfo || sourceInfo.hadCanonicalSource || sourceInfo.nonCanonicalTokens.length === 0) {
+    return false;
+  }
+
+  return sourceInfo.nonCanonicalTokens.some(tokens => isProperSubset(candidate.informative_tokens, tokens));
+}
+
+function pruneLessSpecificCanonicalIds(values, context, sourceMap) {
+  return values.filter((value, idx) => {
+    const row = context.byId.get(value);
+    if (!row || row.informative_tokens.length === 0) {
+      return true;
+    }
+
+    const rowSource = sourceMap.get(value);
+    if (!rowSource?.hadCanonicalSource) {
+      return true;
+    }
+
+    for (let i = 0; i < values.length; i++) {
+      if (i === idx) continue;
+
+      const otherId = values[i];
+      const other = context.byId.get(otherId);
+      if (!other || other.informative_tokens.length === 0) continue;
+
+      if (
+        isProperSubset(row.informative_tokens, other.informative_tokens)
+        && hasMoreSpecificNonCanonicalSource(row, sourceMap.get(otherId))
+      ) {
+        return false;
+      }
+    }
+
+    return true;
+  });
+}
+
+export function normalizeSceneCharacters(values, context) {
+  const before = normalizeRawCharacterValues(values);
+  const resolved = [];
+  const seen = new Set();
+  const sourceMap = new Map();
+
+  for (const value of before) {
+    const normalized = resolveCharacterReference(value, context);
+    if (!normalized) continue;
+
+    const source = sourceMap.get(normalized) ?? {
+      hadCanonicalSource: false,
+      nonCanonicalTokens: [],
+    };
+
+    if (context.byId.has(value)) {
+      source.hadCanonicalSource = true;
+    } else {
+      source.nonCanonicalTokens.push(tokenizeValue(value));
+    }
+    sourceMap.set(normalized, source);
+
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    resolved.push(normalized);
+  }
+
+  const after = pruneLessSpecificCanonicalIds(resolved, context, sourceMap);
+  const beforeSet = new Set(before);
+  const afterSet = new Set(after);
+
+  return {
+    before,
+    after,
+    changed: before.length !== after.length || before.some((value, idx) => after[idx] !== value),
+    added: after.filter(value => !beforeSet.has(value)),
+    removed: before.filter(value => !afterSet.has(value)),
+  };
+}

package/scripts/normalize-scene-characters.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { openDb } from "../db.js";
+import { buildCharacterNormalizationContext, normalizeSceneCharacters } from "../scene-character-normalization.js";
+import { normalizeSceneMetaForPath, readMeta, syncAll, writeMeta } from "../sync.js";
+
+function readRequiredValue(argv, index, option) {
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("-")) {
+    throw new Error(`${option} requires a value.`);
+  }
+  return value;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    syncDir: process.env.WRITING_SYNC_DIR ?? "./sync",
+    projectId: null,
+    write: false,
+    json: false,
+    limit: null,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--sync-dir" || arg === "-d") {
+      opts.syncDir = readRequiredValue(argv, i, arg);
+      i++;
+    } else if (arg === "--project-id" || arg === "-p") {
+      opts.projectId = readRequiredValue(argv, i, arg);
+      i++;
+    } else if (arg === "--limit" || arg === "-n") {
+      opts.limit = Number.parseInt(readRequiredValue(argv, i, arg), 10);
+      i++;
+    } else if (arg === "--write") {
+      opts.write = true;
+    } else if (arg === "--json") {
+      opts.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      opts.help = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (opts.limit !== null && (!Number.isInteger(opts.limit) || opts.limit <= 0)) {
+    throw new Error("--limit must be a positive integer.");
+  }
+
+  return opts;
+}
+
+function usage() {
+  return [
+    "Usage:",
+    "  node --experimental-sqlite scripts/normalize-scene-characters.mjs [--sync-dir <dir>] [--project-id <id>] [--limit <n>] [--write] [--json]",
+    "",
+    "Options:",
+    "  --sync-dir, -d   WRITING_SYNC_DIR root (default: env WRITING_SYNC_DIR or ./sync)",
+    "  --project-id, -p Restrict to one project_id",
+    "  --limit, -n      Process at most N scenes",
+    "  --write          Apply changes (default: dry-run)",
+    "  --json           Emit machine-readable JSON summary",
+    "",
+    "Note: Uses an in-memory sqlite index for analysis; no mcp.sqlite file is created in sync_dir.",
+  ].join("\n");
+}
+
+function queryRows(db, sql, ...params) {
+  return db.prepare(sql).all(...params);
+}
+
+function resolveCharacterRows(db, projectId) {
+  return queryRows(
+    db,
+    `SELECT character_id, name
+       FROM characters
+      WHERE project_id = ?
+         OR universe_id = (SELECT universe_id FROM projects WHERE project_id = ?)
+      ORDER BY length(name) DESC`,
+    projectId,
+    projectId
+  );
+}
+
+function resolveScenes(db, projectId, limit) {
+  const limitClause = Number.isInteger(limit) ? ` LIMIT ${limit}` : "";
+  if (!projectId) {
+    return queryRows(
+      db,
+      `SELECT scene_id, project_id, file_path
+         FROM scenes
+        ORDER BY project_id, part, chapter, timeline_position, scene_id${limitClause}`
+    );
+  }
+  return queryRows(
+    db,
+    `SELECT scene_id, project_id, file_path
+       FROM scenes
+      WHERE project_id = ?
+      ORDER BY part, chapter, timeline_position, scene_id${limitClause}`,
+    projectId
+  );
+}
+
+function runNormalization({ syncDir, projectId, write, limit }) {
+  const db = openDb(":memory:");
+  try {
+    // Refresh index so character/name resolution uses current canonical sheets and sidecars.
+    syncAll(db, syncDir, { quiet: true, writable: false });
+
+    const scenes = resolveScenes(db, projectId, limit);
+    const contextCache = new Map();
+
+    const getContextForProject = (sceneProjectId) => {
+      const key = sceneProjectId ?? "__none__";
+      if (contextCache.has(key)) return contextCache.get(key);
+
+      const context = buildCharacterNormalizationContext(resolveCharacterRows(db, sceneProjectId));
+      contextCache.set(key, context);
+      return context;
+    };
+
+    const changed = [];
+    let processedScenes = 0;
+
+    for (const scene of scenes) {
+      const { meta } = readMeta(scene.file_path, syncDir, { writable: false });
+      if (!Array.isArray(meta.characters) || meta.characters.length === 0) {
+        processedScenes++;
+        continue;
+      }
+
+      const normalized = normalizeSceneCharacters(meta.characters, getContextForProject(scene.project_id));
+      processedScenes++;
+
+      if (!normalized.changed) continue;
+
+      if (write) {
+        const updatedMeta = normalizeSceneMetaForPath(syncDir, scene.file_path, {
+          ...meta,
+          characters: normalized.after,
+        }).meta;
+        writeMeta(scene.file_path, updatedMeta);
+      }
+
+      changed.push({
+        scene_id: scene.scene_id,
+        project_id: scene.project_id,
+        file_path: scene.file_path,
+        before_characters: normalized.before,
+        after_characters: normalized.after,
+        added: normalized.added,
+        removed: normalized.removed,
+      });
+    }
+
+    return {
+      ok: true,
+      mode: write ? "write" : "dry_run",
+      sync_dir: path.resolve(syncDir),
+      project_id: projectId,
+      processed_scenes: processedScenes,
+      scenes_changed: changed.length,
+      character_reference_count: [...contextCache.values()].reduce((sum, ctx) => sum + ctx.clean.length, 0),
+      changes: changed,
+    };
+  } finally {
+    db.close();
+  }
+}
+
+function printTextSummary(result) {
+  process.stdout.write(`normalize-scene-characters (${result.mode})\n`);
+  process.stdout.write(`sync_dir: ${result.sync_dir}\n`);
+  process.stdout.write(`project_id: ${result.project_id ?? "(all projects)"}\n`);
+  process.stdout.write(`processed_scenes: ${result.processed_scenes}\n`);
+  process.stdout.write(`scenes_changed: ${result.scenes_changed}\n`);
+  process.stdout.write(`character_reference_count: ${result.character_reference_count}\n`);
+
+  const preview = result.changes.slice(0, 20);
+  for (const row of preview) {
+    process.stdout.write(`- ${row.scene_id} (${row.project_id})\n`);
+    process.stdout.write(`  added: ${row.added.join(", ") || "(none)"}\n`);
+    process.stdout.write(`  removed: ${row.removed.join(", ") || "(none)"}\n`);
+  }
+  if (result.changes.length > preview.length) {
+    process.stdout.write(`... ${result.changes.length - preview.length} more changed scene(s)\n`);
+  }
+
+  if (result.mode === "write") {
+    process.stdout.write("next_step: run sync() to refresh DB indexes from updated sidecars\n");
+  }
+}
+
+function main() {
+  try {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+      process.stdout.write(`${usage()}\n`);
+      return;
+    }
+
+    const result = runNormalization({
+      syncDir: path.resolve(opts.syncDir),
+      projectId: opts.projectId,
+      write: opts.write,
+      limit: opts.limit,
+    });
+
+    if (opts.json) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      return;
+    }
+    printTextSummary(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${message}\n`);
+    process.stderr.write(`${usage()}\n`);
+    process.exit(1);
+  }
+}
+
+main();