@hanna84/mcp-writing 2.1.0 → 2.3.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.3.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.2.0...v2.3.0)
+
+- feat(styleguide): generate prose styleguide skill from resolved config [`#85`](https://github.com/hannasdev/mcp-writing.git
+/pull/85)
+
+#### [v2.2.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.1.0...v2.2.0)
+
+> 25 April 2026
+
+- feat(styleguide): add prose styleguide config resolution and MCP tools [`#84`](https://github.com/hannasdev/mcp-writing.git
+/pull/84)
+- Release 2.2.0 [`58ecb48`](https://github.com/hannasdev/mcp-writing.git
+/commit/58ecb480200498459e3d8876c06554d8a26c2fb5)
+
 #### [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)

package/index.js

@@ -17,6 +17,17 @@ 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 {
+  PROSE_STYLEGUIDE_SKILL_BASENAME,
+  PROSE_STYLEGUIDE_SKILL_DIRNAME,
+  buildProseStyleguideSkill,
+} from "./prose-styleguide-skill.js";
 import {
   REVIEW_BUNDLE_PROFILES,
   REVIEW_BUNDLE_STRICTNESS,
@@ -51,6 +62,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 +1382,226 @@ 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.",
+      });
+    }
+  );
+
+  s.tool(
+    "setup_prose_styleguide_skill",
+    "Generate skills/prose-styleguide.md from the resolved prose styleguide config and universal craft rules.",
+    {
+      project_id: z.string().optional().describe("Optional project ID for scoped config resolution (e.g. 'the-lamb' or 'universe-1/book-1')."),
+      overwrite: z.boolean().optional().describe("If true, replaces an existing skills/prose-styleguide.md file."),
+    },
+    async ({ project_id, overwrite = false }) => {
+      if (project_id !== undefined) {
+        const projectIdCheck = validateProjectId(project_id);
+        if (!projectIdCheck.ok) {
+          return errorResponse("INVALID_PROJECT_ID", projectIdCheck.reason, { project_id });
+        }
+      }
+
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse(
+          "SYNC_DIR_NOT_WRITABLE",
+          "Cannot write prose styleguide skill because WRITING_SYNC_DIR is not writable in this runtime.",
+          { sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      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 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.",
+          }
+        );
+      }
+
+      const skillPath = path.join(SYNC_DIR, PROSE_STYLEGUIDE_SKILL_DIRNAME, PROSE_STYLEGUIDE_SKILL_BASENAME);
+      if (!isPathCandidateInsideSyncDir(skillPath)) {
+        return errorResponse(
+          "INVALID_SKILL_PATH",
+          "Resolved prose styleguide skill path must be inside WRITING_SYNC_DIR.",
+          { target_path: path.resolve(skillPath), sync_dir: SYNC_DIR_ABS }
+        );
+      }
+
+      if (fs.existsSync(skillPath) && !overwrite) {
+        return errorResponse(
+          "STYLEGUIDE_SKILL_EXISTS",
+          "skills/prose-styleguide.md already exists. Set overwrite=true to replace it.",
+          { target_path: path.resolve(skillPath) }
+        );
+      }
+
+      const generated = buildProseStyleguideSkill({
+        resolvedConfig: resolved.resolved_config,
+        sources: resolved.sources,
+        projectId: project_id ?? null,
+      });
+      if (!generated.ok) {
+        return errorResponse(generated.error.code, generated.error.message);
+      }
+
+      fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+      fs.writeFileSync(skillPath, generated.markdown, "utf8");
+
+      return jsonResponse({
+        ok: true,
+        file_path: path.resolve(skillPath),
+        project_id: project_id ?? null,
+        injected_rules: generated.injected_rules,
+        source_count: resolved.sources.length,
+      });
+    }
+  );
+
   // ---- preview_review_bundle ----------------------------------------------
   s.tool(
     "preview_review_bundle",

package/package.json

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

package/prose-styleguide-skill.js

@@ -0,0 +1,125 @@
+export const PROSE_STYLEGUIDE_SKILL_DIRNAME = "skills";
+export const PROSE_STYLEGUIDE_SKILL_BASENAME = "prose-styleguide.md";
+
+const LANGUAGE_LABELS = {
+  english_us: "English (US)",
+  english_uk: "English (UK)",
+  english_au: "English (AU)",
+  english_ca: "English (CA)",
+  swedish: "Swedish",
+  norwegian: "Norwegian",
+  danish: "Danish",
+  finnish: "Finnish",
+  french: "French",
+  italian: "Italian",
+  russian: "Russian",
+  portuguese_pt: "Portuguese (PT)",
+  portuguese_br: "Portuguese (BR)",
+  german: "German",
+  dutch: "Dutch",
+  polish: "Polish",
+  czech: "Czech",
+  hungarian: "Hungarian",
+  spanish: "Spanish",
+  irish: "Irish",
+  japanese: "Japanese",
+  korean: "Korean",
+  chinese_traditional: "Chinese (Traditional)",
+  chinese_simplified: "Chinese (Simplified)",
+};
+
+const CONFIG_RULE_RENDERERS = {
+  language: (value) => `Primary writing language: ${LANGUAGE_LABELS[value] ?? value}.`,
+  spelling: (value) => `Spelling variant: ${value.toUpperCase()}.`,
+  quotation_style: (value) => {
+    const labels = {
+      double: "double quotes",
+      single: "single quotes",
+      guillemets: "guillemets (« »)",
+      low9: "low-9 quotation marks",
+      dialogue_dash_en: "Scandinavian en-dash dialogue",
+      dialogue_dash_em: "Spanish/Irish em-dash dialogue",
+      corner_brackets: "corner brackets (「 」)",
+    };
+    return `Dialogue quotation style: ${labels[value] ?? value}.`;
+  },
+  quotation_style_nested: (value) => `Nested quotation style: ${value}.`,
+  em_dash_spacing: (value) => `Em dash spacing: ${value}.`,
+  ellipsis_style: (value) => `Ellipsis style: ${value}.`,
+  abbreviation_periods: (value) => `Abbreviation periods: ${value}.`,
+  oxford_comma: (value) => `Oxford comma: ${value}.`,
+  numbers: (value) => `Number formatting rule: ${value}.`,
+  date_format: (value) => `Date format: ${value}.`,
+  time_format: (value) => `Time format: ${value}.`,
+  tense: (value) => `Default narrative tense: ${value}. Flag deviations as questions, not hard errors.`,
+  pov: (value) => `Default POV: ${value}. Flag shifts as intentional-or-drift questions.`,
+  dialogue_tags: (value) => `Dialogue tag policy: ${value}.`,
+  sentence_fragments: (value) => `Sentence fragments policy: ${value}.`,
+};
+
+export function buildProseStyleguideSkill({ resolvedConfig, sources = [], projectId = null }) {
+  if (!resolvedConfig || typeof resolvedConfig !== "object") {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_STYLEGUIDE_CONFIG",
+        message: "Cannot generate prose-styleguide.md without a resolved config object.",
+      },
+    };
+  }
+
+  const injectedRules = [];
+  for (const [field, renderRule] of Object.entries(CONFIG_RULE_RENDERERS)) {
+    if (resolvedConfig[field] === undefined) continue;
+    injectedRules.push(renderRule(resolvedConfig[field]));
+  }
+
+  const sourceLines = sources.length
+    ? sources.map((source) => `- ${source.scope}: ${source.file_path}`)
+    : ["- none"];
+
+  const voiceNotes = typeof resolvedConfig.voice_notes === "string" && resolvedConfig.voice_notes.trim()
+    ? resolvedConfig.voice_notes.trim().split("\n").map((line) => `> ${line}`).join("\n")
+    : "> None provided.";
+
+  const markdown = [
+    "# Prose Styleguide",
+    "",
+    "## Standing Order",
+    "Apply this styleguide by default for prose critique and edits. Preserve author voice over mechanical cleanup.",
+    "",
+    "## Resolved Scope",
+    `- Project scope: ${projectId ?? "sync-root default"}`,
+    ...sourceLines,
+    "",
+    "## Mechanical Conventions",
+    "These are injected from prose-styleguide.config.yaml and should be applied consistently:",
+    ...injectedRules.map((rule) => `- ${rule}`),
+    "",
+    "## Universal Craft Rules",
+    "- Identify scene purpose before proposing changes.",
+    "- Require transformation (emotional, relational, narrative, or thematic).",
+    "- Prefer critique before rewrite.",
+    "- Preserve cadence and specificity; avoid flattening voice.",
+    "- Ask before normalizing intentional instability (flashbacks, POV drift, syntax breaks).",
+    "",
+    "## Review Posture",
+    "- Prioritize structural issues, then convention drift, then line-level polish.",
+    "- Treat convention drift as a question when intent may be deliberate.",
+    "",
+    "## Edit Posture",
+    "- Do not shorten unless requested.",
+    "- Apply conventions consistently while preserving tone.",
+    "- Justify significant rewrites.",
+    "",
+    "## Voice Notes",
+    voiceNotes,
+    "",
+  ].join("\n");
+
+  return {
+    ok: true,
+    markdown,
+    injected_rules: injectedRules,
+  };
+}

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