@hanna84/mcp-writing 2.3.0 → 2.5.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.5.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.4.0...v2.5.0)
+
+- feat(styleguide): add prose styleguide bootstrap suggestions [`#87`](https://github.com/hannasdev/mcp-writing.git
+/pull/87)
+
+#### [v2.4.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.3.0...v2.4.0)
+
+> 26 April 2026
+
+- feat(styleguide): add config update preview and prose drift checks [`#86`](https://github.com/hannasdev/mcp-writing.git
+/pull/86)
+- Release 2.4.0 [`1655c06`](https://github.com/hannasdev/mcp-writing.git
+/commit/1655c06088824e608c2795b61707b963e541c3fb)
+
 #### [v2.3.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.2.0...v2.3.0)
 
+> 26 April 2026
+
 - feat(styleguide): generate prose styleguide skill from resolved config [`#85`](https://github.com/hannasdev/mcp-writing.git
 /pull/85)
+- Release 2.3.0 [`3490851`](https://github.com/hannasdev/mcp-writing.git
+/commit/3490851ccc94989c4a487790b4b35c6a15fac860)
 
 #### [v2.2.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.1.0...v2.2.0)

package/index.js

@@ -21,8 +21,16 @@ import {
   STYLEGUIDE_CONFIG_BASENAME,
   STYLEGUIDE_ENUMS,
   buildStyleguideConfigDraft,
+  previewStyleguideConfigUpdate,
   resolveStyleguideConfig,
+  summarizeStyleguideConfig,
+  updateStyleguideConfig,
 } from "./prose-styleguide.js";
+import {
+  detectStyleguideSignals,
+  analyzeSceneStyleguideDrift,
+  suggestStyleguideUpdatesFromScenes,
+} from "./prose-styleguide-drift.js";
 import {
   PROSE_STYLEGUIDE_SKILL_BASENAME,
   PROSE_STYLEGUIDE_SKILL_DIRNAME,
@@ -1518,6 +1526,425 @@ function createMcpServer() {
     }
   );
 
+  s.tool(
+    "summarize_prose_styleguide_config",
+    "Summarize the currently resolved prose styleguide config in plain language for review or confirmation.",
+    {
+      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
+        );
+      }
+      if (resolved.setup_required || !resolved.resolved_config) {
+        return errorResponse(
+          "STYLEGUIDE_CONFIG_REQUIRED",
+          "Cannot summarize prose styleguide config before prose-styleguide.config.yaml is set up.",
+          {
+            project_id: project_id ?? null,
+            next_step: "Run setup_prose_styleguide_config or bootstrap_prose_styleguide_config.",
+          }
+        );
+      }
+
+      const summary = summarizeStyleguideConfig({
+        resolvedConfig: resolved.resolved_config,
+        inferredDefaults: resolved.inferred_defaults,
+      });
+      if (!summary.ok) {
+        return errorResponse(summary.error.code, summary.error.message);
+      }
+
+      return jsonResponse({
+        ok: true,
+        project_id: project_id ?? null,
+        summary_text: summary.summary_text,
+        summary_lines: summary.summary_lines,
+        styleguide: resolved,
+      });
+    }
+  );
+
+  s.tool(
+    "bootstrap_prose_styleguide_config",
+    "Detect dominant prose conventions from existing scenes and suggest initial prose-styleguide config values.",
+    {
+      project_id: z.string().describe("Project ID to analyze (e.g. 'the-lamb' or 'universe-1/book-1')."),
+      scene_ids: z.array(z.string()).optional().describe("Optional scene_id allowlist to analyze."),
+      part: z.number().int().optional().describe("Optional part filter."),
+      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      max_scenes: z.number().int().positive().optional().describe("Maximum number of scenes to analyze (default: 50)."),
+      min_agreement: z.number().min(0).max(1).optional().describe("Minimum agreement ratio for suggested fields (default: 0.6)."),
+      min_evidence: z.number().int().positive().optional().describe("Minimum number of observed scenes per field before suggesting it (default: 3)."),
+      include_scene_signals: z.boolean().optional().describe("If true, include per-scene detected signals in the response."),
+    },
+    async ({
+      project_id,
+      scene_ids,
+      part,
+      chapter,
+      max_scenes = 50,
+      min_agreement = 0.6,
+      min_evidence = 3,
+      include_scene_signals = false,
+    }) => {
+      const projectIdCheck = validateProjectId(project_id);
+      if (!projectIdCheck.ok) {
+        return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+      }
+
+      const targetResolution = resolveBatchTargetScenes(db, {
+        projectId: project_id,
+        sceneIds: scene_ids,
+        part,
+        chapter,
+        onlyStale: false,
+      });
+      if (!targetResolution.ok) {
+        return errorResponse(targetResolution.code, targetResolution.message, targetResolution.details);
+      }
+
+      const targetScenes = targetResolution.rows;
+      if (targetScenes.length === 0) {
+        return errorResponse(
+          "NOT_FOUND",
+          `No scenes were found for project '${project_id}' with the requested filters.`,
+          { project_id, scene_ids: scene_ids ?? null, part: part ?? null, chapter: chapter ?? null }
+        );
+      }
+
+      if (targetScenes.length > max_scenes) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          `Matched ${targetScenes.length} scenes, which exceeds max_scenes=${max_scenes}.`,
+          { matched_scenes: targetScenes.length, max_scenes, project_id }
+        );
+      }
+
+      const sceneSignals = [];
+      let unreadableScenes = 0;
+
+      for (const scene of targetScenes) {
+        try {
+          const raw = fs.readFileSync(scene.file_path, "utf8");
+          const prose = matter(raw).content;
+          sceneSignals.push({
+            scene_id: scene.scene_id,
+            observed: detectStyleguideSignals(prose),
+          });
+        } catch {
+          unreadableScenes += 1;
+          sceneSignals.push({
+            scene_id: scene.scene_id,
+            observed: {},
+          });
+        }
+      }
+
+      const suggestedConfig = suggestStyleguideUpdatesFromScenes({
+        sceneAnalyses: sceneSignals,
+        resolvedConfig: null,
+        minAgreement: min_agreement,
+        minEvidence: min_evidence,
+      });
+
+      return jsonResponse({
+        ok: true,
+        project_id,
+        checked_scenes: sceneSignals.length,
+        unreadable_scenes: unreadableScenes,
+        suggested_config: suggestedConfig,
+        next_step: "Review suggested_config, then write accepted fields via update_prose_styleguide_config.",
+        scene_signals: include_scene_signals ? sceneSignals : undefined,
+      });
+    }
+  );
+
+  s.tool(
+    "update_prose_styleguide_config",
+    "Update an existing prose-styleguide.config.yaml at sync-root or project-root scope by writing only explicit field changes.",
+    {
+      scope: z.enum(["sync_root", "project_root"]).describe("Config scope to update."),
+      project_id: z.string().optional().describe("Project ID when updating project_root config (e.g. 'the-lamb' or 'universe-1/book-1')."),
+      updates: z.object({
+        language: z.enum(STYLEGUIDE_ENUMS.language).optional(),
+        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(),
+        voice_notes: z.string().optional(),
+      }).strict().describe("Explicit config field changes to write at the selected scope."),
+    },
+    async ({ scope, project_id, updates }) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      if (scope === "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 update styleguide config because WRITING_SYNC_DIR is not writable in this runtime.",
+          { sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      const updated = updateStyleguideConfig({
+        syncDir: SYNC_DIR,
+        scope,
+        projectId: project_id,
+        updates,
+      });
+      if (!updated.ok) {
+        return errorResponse(
+          updated.error.code,
+          updated.error.message,
+          updated.error.details
+        );
+      }
+
+      return jsonResponse({
+        ok: true,
+        scope: updated.scope,
+        project_id: updated.project_id,
+        file_path: path.resolve(updated.file_path),
+        config: updated.config,
+        changed_fields: updated.changed_fields,
+        noop: Boolean(updated.noop),
+        message: updated.message,
+        warnings: updated.warnings,
+      });
+    }
+  );
+
+  s.tool(
+    "preview_prose_styleguide_config_update",
+    "Preview how explicit updates would change an existing prose-styleguide.config.yaml without writing any files.",
+    {
+      scope: z.enum(["sync_root", "project_root"]).describe("Config scope to preview updates for."),
+      project_id: z.string().optional().describe("Project ID when previewing project_root config updates (e.g. 'the-lamb' or 'universe-1/book-1')."),
+      updates: z.object({
+        language: z.enum(STYLEGUIDE_ENUMS.language).optional(),
+        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(),
+        voice_notes: z.string().optional(),
+      }).strict().describe("Explicit config field changes to preview at the selected scope."),
+    },
+    async ({ scope, project_id, updates }) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      if (scope === "project_root" && !project_id) {
+        return errorResponse(
+          "PROJECT_ID_REQUIRED",
+          "project_id is required when scope=project_root."
+        );
+      }
+
+      const preview = previewStyleguideConfigUpdate({
+        syncDir: SYNC_DIR,
+        scope,
+        projectId: project_id,
+        updates,
+      });
+      if (!preview.ok) {
+        return errorResponse(
+          preview.error.code,
+          preview.error.message,
+          preview.error.details
+        );
+      }
+
+      return jsonResponse({
+        ok: true,
+        scope: preview.scope,
+        project_id: preview.project_id,
+        file_path: path.resolve(preview.file_path),
+        current_config: preview.current_config,
+        next_config: preview.config,
+        changed_fields: preview.changed_fields,
+        noop: preview.changed_fields.length === 0,
+        message: preview.changed_fields.length === 0
+          ? "No changes detected for requested styleguide updates."
+          : "Preview generated.",
+        warnings: preview.warnings,
+      });
+    }
+  );
+
+  s.tool(
+    "check_prose_styleguide_drift",
+    "Detect styleguide drift by comparing declared config conventions against observed signals in scene prose.",
+    {
+      project_id: z.string().describe("Project ID to analyze (e.g. 'the-lamb' or 'universe-1/book-1')."),
+      scene_ids: z.array(z.string()).optional().describe("Optional scene_id allowlist to analyze."),
+      part: z.number().int().optional().describe("Optional part filter."),
+      chapter: z.number().int().optional().describe("Optional chapter filter."),
+      max_scenes: z.number().int().positive().optional().describe("Maximum number of scenes to analyze (default: 50)."),
+      min_agreement: z.number().min(0).max(1).optional().describe("Minimum agreement ratio for suggested updates (default: 0.6)."),
+      include_clean_scenes: z.boolean().optional().describe("If true, include scenes with no detected drift in scene_results."),
+    },
+    async ({
+      project_id,
+      scene_ids,
+      part,
+      chapter,
+      max_scenes = 50,
+      min_agreement = 0.6,
+      include_clean_scenes = false,
+    }) => {
+      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
+        );
+      }
+      if (resolved.setup_required || !resolved.resolved_config) {
+        return errorResponse(
+          "STYLEGUIDE_CONFIG_REQUIRED",
+          "Cannot check prose styleguide drift before prose-styleguide.config.yaml is set up.",
+          {
+            project_id,
+            next_step: "Run setup_prose_styleguide_config or bootstrap_prose_styleguide_config.",
+          }
+        );
+      }
+
+      const targetResolution = resolveBatchTargetScenes(db, {
+        projectId: project_id,
+        sceneIds: scene_ids,
+        part,
+        chapter,
+        onlyStale: false,
+      });
+      if (!targetResolution.ok) {
+        return errorResponse(targetResolution.code, targetResolution.message, targetResolution.details);
+      }
+
+      const targetScenes = targetResolution.rows;
+      if (targetScenes.length > max_scenes) {
+        return errorResponse(
+          "VALIDATION_ERROR",
+          `Matched ${targetScenes.length} scenes, which exceeds max_scenes=${max_scenes}.`,
+          { matched_scenes: targetScenes.length, max_scenes, project_id }
+        );
+      }
+
+      const sceneAnalyses = [];
+      for (const scene of targetScenes) {
+        let prose;
+        try {
+          const raw = fs.readFileSync(scene.file_path, "utf8");
+          prose = matter(raw).content;
+        } catch {
+          sceneAnalyses.push({
+            scene_id: scene.scene_id,
+            observed: {},
+            drift: [{ field: "scene_file", declared: "readable", observed: "unreadable" }],
+          });
+          continue;
+        }
+
+        const analysis = analyzeSceneStyleguideDrift({
+          prose,
+          resolvedConfig: resolved.resolved_config,
+        });
+        sceneAnalyses.push({
+          scene_id: scene.scene_id,
+          observed: analysis.observed,
+          drift: analysis.drift,
+        });
+      }
+
+      const suggestedUpdates = suggestStyleguideUpdatesFromScenes({
+        sceneAnalyses,
+        resolvedConfig: resolved.resolved_config,
+        minAgreement: min_agreement,
+      });
+
+      const filteredScenes = include_clean_scenes
+        ? sceneAnalyses
+        : sceneAnalyses.filter((scene) => scene.drift.length > 0);
+
+      const driftByField = {};
+      for (const scene of sceneAnalyses) {
+        for (const entry of scene.drift) {
+          driftByField[entry.field] = (driftByField[entry.field] ?? 0) + 1;
+        }
+      }
+
+      return jsonResponse({
+        ok: true,
+        project_id,
+        checked_scenes: sceneAnalyses.length,
+        scenes_with_drift: sceneAnalyses.filter((scene) => scene.drift.length > 0).length,
+        drift_by_field: driftByField,
+        scene_results: filteredScenes,
+        suggested_updates: suggestedUpdates,
+      });
+    }
+  );
+
   s.tool(
     "setup_prose_styleguide_skill",
     "Generate skills/prose-styleguide.md from the resolved prose styleguide config and universal craft rules.",
@@ -1558,7 +1985,7 @@ function createMcpServer() {
           "Cannot generate prose-styleguide.md before prose-styleguide.config.yaml is set up.",
           {
             project_id: project_id ?? null,
-            next_step: "Run setup_prose_styleguide_config first.",
+            next_step: "Run setup_prose_styleguide_config or bootstrap_prose_styleguide_config first.",
           }
         );
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",
@@ -18,6 +18,7 @@
     "scene-character-normalization.js",
     "review-bundles.js",
     "prose-styleguide.js",
+    "prose-styleguide-drift.js",
     "prose-styleguide-skill.js",
     "scripts/",
     "README.md",

package/prose-styleguide-drift.js

@@ -0,0 +1,125 @@
+function detectQuotationStyle(prose) {
+  const counts = {
+    double: (prose.match(/"[^"]{2,}"/g) ?? []).length,
+    guillemets: (prose.match(/«[^»]{2,}»/g) ?? []).length,
+    low9: (prose.match(/„[^“]{2,}“/g) ?? []).length,
+    corner_brackets: (prose.match(/「[^」]{2,}」/g) ?? []).length,
+    dialogue_dash_en: (prose.match(/^\s*–\s/mg) ?? []).length,
+    dialogue_dash_em: (prose.match(/^\s*—\s/mg) ?? []).length,
+    single: (prose.match(/'[^'\n]{2,}'/g) ?? []).length,
+  };
+
+  let best = null;
+  let bestCount = 0;
+  for (const [style, count] of Object.entries(counts)) {
+    if (count > bestCount) {
+      best = style;
+      bestCount = count;
+    }
+  }
+  return bestCount > 0 ? best : null;
+}
+
+function detectEmDashSpacing(prose) {
+  const spaced = (prose.match(/\s—\s/g) ?? []).length;
+  const closed = (prose.match(/\S—\S/g) ?? []).length;
+  if (spaced === 0 && closed === 0) return null;
+  return spaced >= closed ? "spaced" : "closed";
+}
+
+function detectSpellingVariant(prose) {
+  const lower = prose.toLowerCase();
+  const ukSignals = ["colour", "realise", "centre", "honour", "travelling"];
+  const usSignals = ["color", "realize", "center", "honor", "traveling"];
+
+  const countHits = (signals) => signals.reduce((sum, word) => {
+    const re = new RegExp(`\\b${word}\\b`, "g");
+    return sum + (lower.match(re) ?? []).length;
+  }, 0);
+
+  const uk = countHits(ukSignals);
+  const us = countHits(usSignals);
+  if (uk === 0 && us === 0) return null;
+  return uk >= us ? "uk" : "us";
+}
+
+function detectTenseHint(prose) {
+  const lower = prose.toLowerCase();
+  const past = (lower.match(/\b(was|were|had|did)\b/g) ?? []).length;
+  const present = (lower.match(/\b(is|are|has|do)\b/g) ?? []).length;
+  if (past === 0 && present === 0) return null;
+  return present >= past ? "present" : "past";
+}
+
+function mostCommonValue(values) {
+  const counts = new Map();
+  for (const value of values) {
+    if (!value) continue;
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  if (counts.size === 0) return null;
+
+  let bestValue = null;
+  let bestCount = 0;
+  for (const [value, count] of counts.entries()) {
+    if (count > bestCount) {
+      bestValue = value;
+      bestCount = count;
+    }
+  }
+  return { value: bestValue, count: bestCount, total: values.filter(Boolean).length };
+}
+
+export function detectStyleguideSignals(prose) {
+  return {
+    quotation_style: detectQuotationStyle(prose),
+    em_dash_spacing: detectEmDashSpacing(prose),
+    spelling: detectSpellingVariant(prose),
+    tense: detectTenseHint(prose),
+  };
+}
+
+export function analyzeSceneStyleguideDrift({ prose, resolvedConfig }) {
+  const observed = detectStyleguideSignals(prose);
+  const drift = [];
+
+  for (const field of ["quotation_style", "em_dash_spacing", "spelling", "tense"]) {
+    const declared = resolvedConfig?.[field];
+    const seen = observed[field];
+    if (!declared || !seen) continue;
+    if (declared !== seen) {
+      drift.push({ field, declared, observed: seen });
+    }
+  }
+
+  return { observed, drift };
+}
+
+export function suggestStyleguideUpdatesFromScenes({
+  sceneAnalyses,
+  resolvedConfig,
+  minAgreement = 0.6,
+  minEvidence = 3,
+}) {
+  const suggestions = {};
+
+  for (const field of ["quotation_style", "em_dash_spacing", "spelling", "tense"]) {
+    const values = sceneAnalyses.map((scene) => scene.observed?.[field] ?? null);
+    const common = mostCommonValue(values);
+    if (!common) continue;
+    if (common.total < minEvidence) continue;
+
+    const agreement = common.total > 0 ? common.count / common.total : 0;
+    const fieldThreshold = field === "tense" ? Math.max(minAgreement, 0.75) : minAgreement;
+    if (agreement < fieldThreshold) continue;
+    if (resolvedConfig?.[field] === common.value) continue;
+
+    suggestions[field] = {
+      suggested_value: common.value,
+      agreement,
+      based_on_scenes: common.total,
+    };
+  }
+
+  return suggestions;
+}

package/prose-styleguide.js

@@ -67,6 +67,25 @@ export const STYLEGUIDE_ENUMS = Object.freeze(
   )
 );
 
+const STYLEGUIDE_FIELD_ORDER = [
+  "language",
+  "spelling",
+  "quotation_style",
+  "quotation_style_nested",
+  "em_dash_spacing",
+  "ellipsis_style",
+  "abbreviation_periods",
+  "oxford_comma",
+  "numbers",
+  "date_format",
+  "time_format",
+  "tense",
+  "pov",
+  "dialogue_tags",
+  "sentence_fragments",
+  "voice_notes",
+];
+
 // Fields that are valid in a config but are not enum-constrained.
 const SPECIAL_FIELDS = new Set(["voice_notes"]);
 
@@ -344,6 +363,98 @@ function readConfigFile(filePath) {
   };
 }
 
+function configPathForScope(syncDir, scope, projectId) {
+  if (scope === "sync_root") {
+    return path.join(syncDir, STYLEGUIDE_CONFIG_BASENAME);
+  }
+  return path.join(projectRootFromId(syncDir, projectId), STYLEGUIDE_CONFIG_BASENAME);
+}
+
+function prepareStyleguideConfigUpdate({ syncDir, scope, projectId, updates = {} }) {
+  if (scope === "project_root" && !projectId) {
+    return {
+      ok: false,
+      error: {
+        code: "PROJECT_ID_REQUIRED",
+        message: "project_id is required when scope=project_root.",
+        details: { scope, project_id: projectId ?? null },
+      },
+    };
+  }
+
+  const filePath = configPathForScope(syncDir, scope, projectId);
+  const current = readConfigFile(filePath);
+
+  if (current === null) {
+    return {
+      ok: false,
+      error: {
+        code: "STYLEGUIDE_CONFIG_NOT_FOUND",
+        message: "Cannot update styleguide config because no config exists at the requested scope.",
+        details: { file_path: filePath, scope, project_id: projectId ?? null },
+      },
+    };
+  }
+
+  if (!current.ok) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_STYLEGUIDE_CONFIG",
+        message: "Styleguide config validation failed.",
+        details: { file_path: filePath, issues: current.errors },
+      },
+    };
+  }
+
+  const validatedUpdates = validateConfig(updates, "<updates>");
+  if (validatedUpdates.errors.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_STYLEGUIDE_UPDATE",
+        message: "Requested styleguide updates failed validation.",
+        details: validatedUpdates.errors,
+      },
+    };
+  }
+
+  const merged = Object.create(null);
+  Object.assign(merged, current.config, validatedUpdates.normalized);
+
+  const ordered = Object.create(null);
+  for (const key of STYLEGUIDE_FIELD_ORDER) {
+    if (merged[key] !== undefined) {
+      ordered[key] = merged[key];
+    }
+  }
+
+  const changedFields = [];
+  const allKeys = new Set([...Object.keys(current.config ?? {}), ...Object.keys(ordered)]);
+  for (const key of allKeys) {
+    if (current.config?.[key] !== ordered[key]) {
+      changedFields.push({
+        field: key,
+        before: current.config?.[key],
+        after: ordered[key],
+      });
+    }
+  }
+
+  return {
+    ok: true,
+    file_path: filePath,
+    scope,
+    project_id: projectId ?? null,
+    current_config: current.config,
+    config: ordered,
+    changed_fields: changedFields,
+    warnings: {
+      unknown_fields: validatedUpdates.unknownFields,
+    },
+  };
+}
+
 function getConfigCandidates(syncDir, projectId) {
   const candidates = [
     {
@@ -442,6 +553,80 @@ export function buildStyleguideConfigDraft({ language, overrides = {}, voice_not
   };
 }
 
+export function summarizeStyleguideConfig({ resolvedConfig, inferredDefaults = {} }) {
+  if (!resolvedConfig || typeof resolvedConfig !== "object") {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_STYLEGUIDE_CONFIG",
+        message: "Cannot summarize styleguide config without a resolved config object.",
+      },
+    };
+  }
+
+  const lines = [];
+  if (resolvedConfig.language) lines.push(`Writing language: ${resolvedConfig.language}.`);
+  if (resolvedConfig.spelling) lines.push(`Spelling variant: ${resolvedConfig.spelling}.`);
+  if (resolvedConfig.quotation_style) lines.push(`Dialogue punctuation uses ${resolvedConfig.quotation_style}.`);
+  if (resolvedConfig.quotation_style_nested) lines.push(`Nested quotations use ${resolvedConfig.quotation_style_nested}.`);
+  if (resolvedConfig.tense) lines.push(`Default narrative tense: ${resolvedConfig.tense}.`);
+  if (resolvedConfig.pov) lines.push(`Default POV: ${resolvedConfig.pov}.`);
+  if (resolvedConfig.dialogue_tags) lines.push(`Dialogue tag policy: ${resolvedConfig.dialogue_tags}.`);
+  if (resolvedConfig.sentence_fragments) lines.push(`Sentence fragments: ${resolvedConfig.sentence_fragments}.`);
+  if (resolvedConfig.date_format) lines.push(`Date format: ${resolvedConfig.date_format}.`);
+  if (resolvedConfig.time_format) lines.push(`Time format: ${resolvedConfig.time_format}.`);
+  if (resolvedConfig.voice_notes) lines.push(`Voice notes: ${resolvedConfig.voice_notes}`);
+
+  const inferred = Object.keys(inferredDefaults);
+  if (inferred.length > 0) {
+    lines.push(`Inferred defaults currently fill: ${inferred.join(", ")}.`);
+  }
+
+  return {
+    ok: true,
+    summary_text: lines.join(" "),
+    summary_lines: lines,
+  };
+}
+
+export function updateStyleguideConfig({ syncDir, scope, projectId, updates = {} }) {
+  const prepared = prepareStyleguideConfigUpdate({ syncDir, scope, projectId, updates });
+  if (!prepared.ok) return prepared;
+
+  if (prepared.changed_fields.length === 0) {
+    return {
+      ok: true,
+      file_path: prepared.file_path,
+      scope: prepared.scope,
+      project_id: prepared.project_id,
+      config: prepared.config,
+      changed_fields: prepared.changed_fields,
+      warnings: prepared.warnings,
+      noop: true,
+      message: "No changes detected for requested styleguide updates.",
+    };
+  }
+
+  fs.mkdirSync(path.dirname(prepared.file_path), { recursive: true });
+  fs.writeFileSync(prepared.file_path, yaml.dump(prepared.config, { lineWidth: 120 }), "utf8");
+
+  return {
+    ok: true,
+    file_path: prepared.file_path,
+    scope: prepared.scope,
+    project_id: prepared.project_id,
+    config: prepared.config,
+    changed_fields: prepared.changed_fields,
+    warnings: prepared.warnings,
+    noop: false,
+    message: "Styleguide config updated.",
+  };
+}
+
+export function previewStyleguideConfigUpdate({ syncDir, scope, projectId, updates = {} }) {
+  return prepareStyleguideConfigUpdate({ syncDir, scope, projectId, updates });
+}
+
 export function resolveStyleguideConfig({ syncDir, projectId }) {
   const candidates = getConfigCandidates(syncDir, projectId);
   const sources = [];