@hanna84/mcp-writing 3.3.1 → 3.4.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).
 
+#### [v3.4.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v3.3.2...v3.4.0)
+
+- feat: add client-agnostic styleguide setup contract and VS Code handoff [`#176`](https://github.com/hannasdev/mcp-writing.git
+/pull/176)
+
+#### [v3.3.2](https://github.com/hannasdev/mcp-writing.git
+/compare/v3.3.1...v3.3.2)
+
+> 5 May 2026
+
+- docs: split PRD overview and add client-agnostic setup PRD [`#175`](https://github.com/hannasdev/mcp-writing.git
+/pull/175)
+- Release 3.3.2 [`de30625`](https://github.com/hannasdev/mcp-writing.git
+/commit/de30625c1ff4a25065f124bb26f95397c6db5493)
+
 #### [v3.3.1](https://github.com/hannasdev/mcp-writing.git
 /compare/v3.3.0...v3.3.1)
 
+> 3 May 2026
+
 - fix(review-comments): enforce command-specific flags and add failure-path tests [`#174`](https://github.com/hannasdev/mcp-writing.git
 /pull/174)
+- Release 3.3.1 [`736bc90`](https://github.com/hannasdev/mcp-writing.git
+/commit/736bc90a224885b700b5de331a2f9e333a11f1c8)
 
 #### [v3.3.0](https://github.com/hannasdev/mcp-writing.git
 /compare/v3.2.1...v3.3.0)

package/README.md

@@ -16,6 +16,12 @@ WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npx -y @hanna84/mcp-writ
 
 The CLI wrapper defaults to stdio transport and adds the Node 22 SQLite flag automatically when needed.
 
+## VS Code extension
+
+For VS Code-native setup flows (including prose styleguide setup), use:
+
+- [hannasdev/mcp-writing-vscode](https://github.com/hannasdev/mcp-writing-vscode)
+
 ## What it does
 
 Instead of feeding an entire manuscript to an AI and hoping it fits in the context window, `mcp-writing` builds a structured index from your scene files. The AI queries that index first — finding relevant characters, beats, and loglines — then loads only the specific prose it needs.
@@ -37,6 +43,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 | Guide | Description |
 |---|---|
 | [docs/setup.md](docs/setup.md) | Prerequisites, first-time setup, Scrivener import, native sync format |
+| [mcp-writing-vscode](https://github.com/hannasdev/mcp-writing-vscode) | VS Code extension for client-native setup flows |
 | [docs/docker.md](docs/docker.md) | Docker Compose, OpenClaw integration, SSH hardening |
 | [docs/data-ownership.md](docs/data-ownership.md) | Which tools write which files, import safety rules |
 | [docs/tools.md](docs/tools.md) | Full tool reference — auto-generated from source |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",
@@ -29,6 +29,7 @@
     "./prose-styleguide.js": "./src/styleguide/prose-styleguide.js",
     "./prose-styleguide-drift.js": "./src/styleguide/prose-styleguide-drift.js",
     "./prose-styleguide-skill.js": "./src/styleguide/prose-styleguide-skill.js",
+    "./setup-contract.js": "./src/setup/setup-contract.js",
     "./tools/*": "./src/tools/*",
     "./scripts/*": "./src/scripts/*",
     "./src/*": "./src/*",
@@ -45,6 +46,7 @@
     "src/core/",
     "src/review-bundles/",
     "src/runtime/",
+    "src/setup/",
     "src/scripts/",
     "src/styleguide/",
     "src/sync/",
@@ -68,7 +70,7 @@
     "normalize:scene-characters": "node --experimental-sqlite src/scripts/normalize-scene-characters.mjs",
     "setup:openclaw-env": "sh src/scripts/setup-openclaw-env.sh",
     "release": "release-it",
-    "lint": "eslint *.js src/index.js src/core src/review-bundles src/runtime src/scripts src/styleguide src/sync src/tools src/workflows src/world",
+    "lint": "eslint *.js src/index.js src/core src/review-bundles src/runtime src/setup src/scripts src/styleguide src/sync src/tools src/workflows src/world",
     "guard:legacy-root-imports": "node src/scripts/check-legacy-root-imports.mjs",
     "docs": "node src/scripts/generate-tool-docs.mjs",
     "lint:metadata": "node src/scripts/lint-metadata.mjs",

package/src/index.js

@@ -18,7 +18,18 @@ import {
   readEntityMetadata,
   resolveBatchTargetScenes,
 } from "./core/helpers.js";
-import { STYLEGUIDE_CONFIG_BASENAME } from "./styleguide/prose-styleguide.js";
+import { STYLEGUIDE_CONFIG_BASENAME, resolveStyleguideConfig } from "./styleguide/prose-styleguide.js";
+import {
+  PROSE_STYLEGUIDE_SKILL_BASENAME,
+  PROSE_STYLEGUIDE_SKILL_DIRNAME,
+} from "./styleguide/prose-styleguide-skill.js";
+import {
+  loadSetupContract,
+  deriveStyleguideSetupStatus,
+  resolveStyleguideSetupAnswers,
+  buildStyleguideSetupArtifactPlan,
+} from "./setup/setup-contract.js";
+import { validateSetupContractContext } from "./setup/setup-contract-response-schema.js";
 import { registerSyncTools } from "./tools/sync.js";
 import { registerSearchTools } from "./tools/search.js";
 import { registerMetadataTools } from "./tools/metadata.js";
@@ -87,6 +98,7 @@ const MCP_SERVER_VERSION = typeof pkg.version === "string" && pkg.version.trim()
   ? pkg.version
   : "0.0.0";
 const asyncJobs = new Map();
+const styleguideSetupContract = loadSetupContract({ rootDir: ROOT_DIR, contractId: "styleguide_setup_v1" });
 
 function paginateRows(rows, { page, pageSize, forcePagination = false }) {
   const totalCount = rows.length;
@@ -355,6 +367,70 @@ function createMcpServer() {
       const syncRootExists = fs.existsSync(syncRootConfigPath);
       const universeRootExists = universeRootConfigPath !== null && fs.existsSync(universeRootConfigPath);
       const projectRootExists = projectRootConfigPath !== null && fs.existsSync(projectRootConfigPath);
+      const styleguideExists = {
+        sync_root: syncRootExists,
+        universe_root: universeRootExists,
+        project_root: projectRootExists,
+      };
+      const syncRootSkillPath = path.join(
+        SYNC_DIR,
+        PROSE_STYLEGUIDE_SKILL_DIRNAME,
+        PROSE_STYLEGUIDE_SKILL_BASENAME
+      );
+      const styleguideSkillExists = fs.existsSync(syncRootSkillPath);
+
+      const styleguideResolution = resolveStyleguideConfig({
+        syncDir: SYNC_DIR,
+        projectId: project_id ?? undefined,
+      });
+      const styleguideValid = styleguideResolution.ok;
+      const styleguideSetupStatus = deriveStyleguideSetupStatus({
+        styleguideExists,
+        styleguideValid,
+        styleguideSkillExists,
+        styleguideEnforcementMode: STYLEGUIDE_ENFORCEMENT_MODE,
+      });
+      const setupPlanPreview = (() => {
+        if (!styleguideSetupContract.ok) return null;
+        const resolved = resolveStyleguideSetupAnswers({
+          contract: styleguideSetupContract.contract,
+          answers: {},
+          inferred: { project_id },
+        });
+        if (!resolved.ok) return null;
+        const plan = buildStyleguideSetupArtifactPlan({
+          resolvedAnswers: resolved.resolved_answers,
+          sceneCount: scene_count,
+          setupStatus: styleguideSetupStatus.status,
+        });
+        return {
+          flow_id: "styleguide_setup_v1",
+          default_scope: resolved.resolved_answers.scope,
+          actions: plan.actions,
+        };
+      })();
+
+      const setupContractContext = styleguideSetupContract.ok
+        ? {
+          contract_id: styleguideSetupContract.contract_id,
+          schema_version: styleguideSetupContract.contract.schema_version,
+          styleguide_setup_status: styleguideSetupStatus.status,
+          setup_recommended: styleguideSetupStatus.setup_recommended,
+          ...(setupPlanPreview ? { plan_preview: setupPlanPreview } : {}),
+        }
+        : {
+          contract_id: "styleguide_setup_v1",
+          status: "unavailable",
+          error_code: styleguideSetupContract.error.code,
+        };
+      const setupContractContextCheck = validateSetupContractContext(setupContractContext);
+      if (!setupContractContextCheck.ok) {
+        return errorResponse(
+          setupContractContextCheck.error.code,
+          setupContractContextCheck.error.message,
+          setupContractContextCheck.error.details
+        );
+      }
 
       return jsonResponse({
         ok: true,
@@ -362,11 +438,8 @@ function createMcpServer() {
           project_id,
           scene_count,
           sync_dir: SYNC_DIR_ABS,
-          styleguide_exists: {
-            sync_root: syncRootExists,
-            universe_root: universeRootExists,
-            project_root: projectRootExists,
-          },
+          styleguide_exists: styleguideExists,
+          setup_contract: setupContractContextCheck.value,
           git_available: GIT_AVAILABLE,
           pending_proposals: pendingProposals.size,
           db_migration_warnings: DB_STARTUP_WARNINGS,
@@ -378,7 +451,8 @@ function createMcpServer() {
           "If a tool returns a next_step field (in a success or error response), follow it before trying anything else.",
           "Use find_scenes without filters to discover what project_ids are indexed.",
           "When calling bootstrap_prose_styleguide_config or check_prose_styleguide_drift, set max_scenes to context.scene_count to avoid the default limit.",
-          "Styleguide tools resolve config in priority order: project_root > universe_root > sync_root. If any styleguide_exists field is true, a config exists and styleguide tools will work — do not run setup_prose_styleguide_config unless ALL styleguide_exists fields are false.",
+          "Use context.setup_contract.styleguide_setup_status to decide whether styleguide setup is missing/invalid and advisory/blocking.",
+          "Styleguide tools resolve config in priority order: project_root > universe_root > sync_root. If any styleguide_exists field is true, a config exists and styleguide tools will work. For invalid setup states, use setup_contract plan preview actions (which may set overwrite=true for repair).",
           ...(DB_STARTUP_WARNINGS.length > 0
             ? ["Database migration warnings are present in context.db_migration_warnings. Run sync() now, then run enrich_scene(scene_id, project_id) for stale scenes you touch."]
             : []),

package/src/setup/contracts/styleguide_setup_v1.json

@@ -0,0 +1,146 @@
+{
+  "schema_version": "1.0.0",
+  "flows": [
+    {
+      "id": "styleguide_setup_v1",
+      "label": "Set up prose styleguide",
+      "questions": [
+        "scope",
+        "project_id",
+        "language",
+        "bootstrap_from_scenes",
+        "high_impact_overrides",
+        "voice_notes"
+      ],
+      "artifact_targets": [
+        "prose_styleguide_config",
+        "prose_styleguide_skill"
+      ],
+      "completion_rules": [
+        "styleguide_config_exists",
+        "styleguide_config_valid",
+        "skill_present_when_sync_scope"
+      ]
+    }
+  ],
+  "questions": {
+    "scope": {
+      "label": "Config scope",
+      "help_text": "Choose where the prose styleguide config should be written.",
+      "blocking": true,
+      "ask_mode": "always",
+      "input_type": "enum",
+      "allowed_values": [
+        "project_root",
+        "sync_root"
+      ],
+      "write_target": "setup.scope"
+    },
+    "project_id": {
+      "label": "Project ID",
+      "help_text": "Required when scope is project_root.",
+      "blocking": true,
+      "ask_mode": "inferred_with_confirmation",
+      "input_type": "string",
+      "write_target": "setup.project_id"
+    },
+    "language": {
+      "label": "Primary language",
+      "help_text": "Seeds styleguide defaults.",
+      "blocking": true,
+      "ask_mode": "always",
+      "input_type": "enum",
+      "allowed_values": [
+        "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"
+      ],
+      "write_target": "styleguide.language"
+    },
+    "bootstrap_from_scenes": {
+      "label": "Bootstrap from existing scenes",
+      "help_text": "Optionally infer likely conventions from manuscript prose before final confirmation.",
+      "blocking": false,
+      "ask_mode": "low_risk_keep_change",
+      "input_type": "boolean",
+      "write_target": "setup.bootstrap_from_scenes"
+    },
+    "high_impact_overrides": {
+      "label": "High-impact convention overrides",
+      "help_text": "Confirm or override punctuation, numbers, and formatting conventions.",
+      "blocking": false,
+      "ask_mode": "inferred_with_confirmation",
+      "input_type": "object",
+      "write_target": "styleguide.overrides"
+    },
+    "voice_notes": {
+      "label": "Voice notes",
+      "help_text": "Optional freeform guidance for tone and craft preferences.",
+      "blocking": false,
+      "ask_mode": "low_risk_keep_change",
+      "input_type": "string",
+      "write_target": "styleguide.voice_notes"
+    }
+  },
+  "defaults": {
+    "scope": "project_root",
+    "language": "english_us",
+    "bootstrap_from_scenes": true
+  },
+  "validation_rules": [
+    {
+      "id": "project_id_required_for_project_root",
+      "when": {
+        "scope": "project_root"
+      },
+      "rule": "project_id is required"
+    },
+    {
+      "id": "language_must_be_supported",
+      "rule": "language must be one of allowed_values"
+    }
+  ],
+  "artifact_targets": {
+    "prose_styleguide_config": {
+      "path": "prose-styleguide.config.yaml",
+      "owner": "mcp_writing_runtime"
+    },
+    "prose_styleguide_skill": {
+      "path": "skills/prose-styleguide/SKILL.md",
+      "owner": "mcp_writing_runtime",
+      "condition": "scope == sync_root"
+    }
+  },
+  "completion_rules": {
+    "styleguide_config_exists": {
+      "derived_from": "filesystem"
+    },
+    "styleguide_config_valid": {
+      "derived_from": "config_validation"
+    },
+    "skill_present_when_sync_scope": {
+      "derived_from": "filesystem_conditional"
+    }
+  }
+}

package/src/setup/setup-contract-response-schema.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+
+const actionSchema = z.object({
+  tool: z.string().min(1),
+  arguments: z.record(z.string(), z.unknown()),
+  mode: z.enum(["preview_or_confirm", "write"]).optional(),
+  note: z.string().min(1).optional(),
+});
+
+const planPreviewSchema = z.object({
+  flow_id: z.literal("styleguide_setup_v1"),
+  default_scope: z.enum(["project_root", "sync_root"]),
+  actions: z.array(actionSchema),
+});
+
+export const setupContractContextSchema = z.union([
+  z.object({
+    contract_id: z.literal("styleguide_setup_v1"),
+    schema_version: z.string().min(1),
+    styleguide_setup_status: z.enum([
+      "missing_advisory",
+      "missing_blocking",
+      "invalid_advisory",
+      "invalid_blocking",
+      "complete",
+    ]),
+    setup_recommended: z.boolean(),
+    plan_preview: planPreviewSchema,
+  }),
+  z.object({
+    contract_id: z.literal("styleguide_setup_v1"),
+    status: z.literal("unavailable"),
+    error_code: z.string().min(1),
+  }),
+]);
+
+export function validateSetupContractContext(payload) {
+  const parsed = setupContractContextSchema.safeParse(payload);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_SETUP_CONTRACT_CONTEXT",
+        message: "describe_workflows produced an invalid setup_contract context payload.",
+        details: {
+          issues: parsed.error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+          })),
+        },
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    value: parsed.data,
+  };
+}

package/src/setup/setup-contract.js

@@ -0,0 +1,315 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+
+const questionSchema = z.object({
+  label: z.string().min(1),
+  help_text: z.string().min(1),
+  blocking: z.boolean(),
+  ask_mode: z.enum(["always", "inferred_with_confirmation", "low_risk_keep_change"]),
+  input_type: z.enum(["enum", "string", "boolean", "object"]),
+  allowed_values: z.array(z.string()).optional(),
+  write_target: z.string().min(1),
+});
+
+const flowSchema = z.object({
+  id: z.string().min(1),
+  label: z.string().min(1),
+  questions: z.array(z.string()).min(1),
+  artifact_targets: z.array(z.string()).min(1),
+  completion_rules: z.array(z.string()).min(1),
+});
+
+export const setupContractSchema = z.object({
+  schema_version: z.string().min(1),
+  flows: z.array(flowSchema).min(1),
+  questions: z.record(z.string(), questionSchema),
+  defaults: z.record(z.string(), z.union([z.string(), z.boolean()])),
+  validation_rules: z.array(z.object({
+    id: z.string().min(1),
+    when: z.record(z.string(), z.string()).optional(),
+    rule: z.string().min(1),
+  })),
+  artifact_targets: z.record(z.string(), z.object({
+    path: z.string().min(1),
+    owner: z.string().min(1),
+    condition: z.string().optional(),
+  })),
+  completion_rules: z.record(z.string(), z.object({
+    derived_from: z.enum(["filesystem", "config_validation", "filesystem_conditional"]),
+  })),
+});
+
+const CONTRACT_RELATIVE_PATHS = {
+  styleguide_setup_v1: path.join("src", "setup", "contracts", "styleguide_setup_v1.json"),
+};
+
+function getFlowById(contract, flowId) {
+  return contract.flows.find((flow) => flow.id === flowId) ?? null;
+}
+
+function parseJsonFile(filePath) {
+  const raw = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+export function loadSetupContract({ rootDir, contractId = "styleguide_setup_v1" }) {
+  const relativePath = CONTRACT_RELATIVE_PATHS[contractId];
+  if (!relativePath) {
+    return {
+      ok: false,
+      error: {
+        code: "SETUP_CONTRACT_NOT_FOUND",
+        message: `Unknown setup contract id: ${contractId}`,
+        details: { contract_id: contractId },
+      },
+    };
+  }
+
+  const contractPath = path.join(rootDir, relativePath);
+  if (!fs.existsSync(contractPath)) {
+    return {
+      ok: false,
+      error: {
+        code: "SETUP_CONTRACT_FILE_MISSING",
+        message: `Setup contract file not found: ${path.resolve(contractPath)}`,
+        details: { contract_id: contractId, contract_path: path.resolve(contractPath) },
+      },
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = parseJsonFile(contractPath);
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: "SETUP_CONTRACT_INVALID_JSON",
+        message: `Failed to parse setup contract JSON: ${error instanceof Error ? error.message : String(error)}`,
+        details: { contract_id: contractId, contract_path: path.resolve(contractPath) },
+      },
+    };
+  }
+
+  const validated = setupContractSchema.safeParse(parsed);
+  if (!validated.success) {
+    return {
+      ok: false,
+      error: {
+        code: "SETUP_CONTRACT_SCHEMA_INVALID",
+        message: "Setup contract does not match required schema.",
+        details: {
+          contract_id: contractId,
+          contract_path: path.resolve(contractPath),
+          issues: validated.error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+          })),
+        },
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    contract_id: contractId,
+    contract_path: path.resolve(contractPath),
+    contract: validated.data,
+  };
+}
+
+export function resolveStyleguideSetupAnswers({
+  contract,
+  flowId = "styleguide_setup_v1",
+  answers = {},
+  inferred = {},
+}) {
+  const flow = getFlowById(contract, flowId);
+  if (!flow) {
+    return {
+      ok: false,
+      error: {
+        code: "SETUP_FLOW_NOT_FOUND",
+        message: `Flow not found in setup contract: ${flowId}`,
+        details: { flow_id: flowId },
+      },
+    };
+  }
+
+  const defaultScope = inferred.project_id
+    ? (contract.defaults.scope ?? "project_root")
+    : "sync_root";
+  const scope = answers.scope ?? defaultScope;
+  const language = answers.language ?? contract.defaults.language;
+  const bootstrapFromScenes = answers.bootstrap_from_scenes ?? contract.defaults.bootstrap_from_scenes;
+  const projectId = answers.project_id ?? inferred.project_id ?? null;
+  const overrides = answers.high_impact_overrides ?? {};
+  const voiceNotes = answers.voice_notes;
+
+  if (typeof bootstrapFromScenes !== "boolean") {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_SETUP_BOOTSTRAP_FLAG",
+        message: "bootstrap_from_scenes must be a boolean.",
+        details: {
+          bootstrap_from_scenes: bootstrapFromScenes,
+        },
+      },
+    };
+  }
+
+  const scopeQuestion = contract.questions.scope;
+  if (!scopeQuestion.allowed_values?.includes(scope)) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_SETUP_SCOPE",
+        message: "scope must be one of the setup contract allowed_values.",
+        details: {
+          scope,
+          allowed_values: scopeQuestion.allowed_values ?? [],
+        },
+      },
+    };
+  }
+
+  const languageQuestion = contract.questions.language;
+  if (!languageQuestion.allowed_values?.includes(language)) {
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_SETUP_LANGUAGE",
+        message: "language must be one of the setup contract allowed_values.",
+        details: {
+          language,
+          allowed_values: languageQuestion.allowed_values ?? [],
+        },
+      },
+    };
+  }
+
+  if (scope === "project_root" && !projectId) {
+    return {
+      ok: false,
+      error: {
+        code: "SETUP_PROJECT_ID_REQUIRED",
+        message: "project_id is required when scope is project_root.",
+        details: { scope, project_id: projectId },
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    flow,
+    resolved_answers: {
+      scope,
+      project_id: projectId,
+      language,
+      bootstrap_from_scenes: bootstrapFromScenes,
+      high_impact_overrides: overrides,
+      voice_notes: typeof voiceNotes === "string" && voiceNotes.trim().length > 0
+        ? voiceNotes
+        : undefined,
+    },
+  };
+}
+
+export function buildStyleguideSetupArtifactPlan({
+  resolvedAnswers,
+  sceneCount = 0,
+  setupStatus = "missing_advisory",
+}) {
+  const replaceExistingArtifacts = typeof setupStatus === "string" && setupStatus.startsWith("invalid_");
+  const configAction = {
+    tool: "setup_prose_styleguide_config",
+    arguments: {
+      scope: resolvedAnswers.scope,
+      language: resolvedAnswers.language,
+      ...(resolvedAnswers.project_id ? { project_id: resolvedAnswers.project_id } : {}),
+      ...(Object.keys(resolvedAnswers.high_impact_overrides ?? {}).length > 0
+        ? { overrides: resolvedAnswers.high_impact_overrides }
+        : {}),
+      ...(resolvedAnswers.voice_notes ? { voice_notes: resolvedAnswers.voice_notes } : {}),
+      overwrite: replaceExistingArtifacts,
+    },
+    mode: "write",
+  };
+
+  const actions = [];
+  if (resolvedAnswers.bootstrap_from_scenes && resolvedAnswers.project_id) {
+    actions.push({
+      tool: "bootstrap_prose_styleguide_config",
+      arguments: {
+        project_id: resolvedAnswers.project_id,
+        max_scenes: Math.max(1, sceneCount || 1),
+      },
+      mode: "preview_or_confirm",
+      note: "Use bootstrap suggested_config to populate setup_prose_styleguide_config.overrides before executing write actions.",
+    });
+  }
+
+  actions.push(configAction);
+
+  if (resolvedAnswers.scope === "sync_root") {
+    actions.push({
+      tool: "setup_prose_styleguide_skill",
+      arguments: { overwrite: true },
+      mode: "write",
+    });
+  }
+
+  return {
+    ok: true,
+    artifact_targets: [
+      "prose-styleguide.config.yaml",
+      ...(resolvedAnswers.scope === "sync_root" ? ["skills/prose-styleguide/SKILL.md"] : []),
+    ],
+    actions,
+  };
+}
+
+export function deriveStyleguideSetupStatus({
+  styleguideExists,
+  styleguideValid,
+  styleguideSkillExists,
+  styleguideEnforcementMode,
+}) {
+  const anyStyleguideExists = Boolean(
+    styleguideExists?.sync_root
+    || styleguideExists?.universe_root
+    || styleguideExists?.project_root
+  );
+  const isBlockingMode = styleguideEnforcementMode === "required";
+
+  if (!anyStyleguideExists) {
+    return {
+      status: isBlockingMode ? "missing_blocking" : "missing_advisory",
+      setup_recommended: true,
+    };
+  }
+
+  if (!styleguideValid) {
+    return {
+      status: isBlockingMode ? "invalid_blocking" : "invalid_advisory",
+      setup_recommended: true,
+    };
+  }
+
+  const requiresSyncRootSkill = Boolean(styleguideExists?.sync_root)
+    && !styleguideExists?.universe_root
+    && !styleguideExists?.project_root;
+  if (requiresSyncRootSkill && !styleguideSkillExists) {
+    return {
+      status: isBlockingMode ? "invalid_blocking" : "invalid_advisory",
+      setup_recommended: true,
+    };
+  }
+
+  return {
+    status: "complete",
+    setup_recommended: false,
+  };
+}