@contentrain/mcp 3.0.2 → 3.1.0

package/dist/{server-DdxWpNBH.mjs → server-BtzVY7yp.mjs}

@@ -1,31 +1,31 @@
-import { a as planContentSave, i as planModelDelete, n as planVocabularySave, o as planContentDelete, r as planModelSave, t as planVocabularyDelete } from "./ops-BzbThweu.mjs";
-import { n as contentFilePath, t as contentDirPath } from "./paths-CmVw5Cw2.mjs";
-import { a as readJson, n as ensureDir, r as pathExists, s as writeJson, t as contentrainDir } from "./fs-DLbVB-Ek.mjs";
-import { a as writeMeta, i as readMeta, o as writeMetaEntries, r as mergeEntryMeta, t as applyStatusChange } from "./meta-manager-B_Se183X.mjs";
-import { r as createGit } from "./identity-D8QoGxhT.mjs";
-import { n as readVocabulary, t as readConfig } from "./config-VlRKRwAS.mjs";
-import { a as deleteRemoteBranch, c as pruneMergedRemoteBranches, i as cleanupMergedBranches, n as checkBranchHealth, s as listRemoteCrBranches } from "./branch-lifecycle-B6PXZ2N7.mjs";
-import { T as writeContent, _ as resolveContentDir, b as resolveMdFilePath, c as listModels, d as validateModelDefinition, f as writeModel, i as countEntries, l as readModel, m as listContent, o as fieldDefZodSchema, p as deleteContent, r as checkReferences, v as resolveJsonFilePath, y as resolveLocaleStrategy } from "./model-manager-DgyKMjLN.mjs";
-import { n as readContext } from "./context-C3x6I3cE.mjs";
-import { i as mergeBranch, n as createTransaction, r as ensureContentBranch, t as buildBranchName } from "./transaction-BW9ektWu.mjs";
-import { n as isMerged, t as LocalProvider } from "./local-Db5X9mjZ.mjs";
-import { n as isToolAvailable, t as TOOL_REQUIREMENTS } from "./availability-Dgcmvv99.mjs";
-import { t as detectStack } from "./detect-B0oXbQaP.mjs";
-import { t as TOOL_ANNOTATIONS } from "./annotations-C-tQVmot.mjs";
-import { n as listTemplates, t as getTemplate } from "./templates-CAkTIRkE.mjs";
-import { n as mapProviderError } from "./errors-CvBS12e7.mjs";
-import { t as validateProject } from "./validator-0sJ9vh1j.mjs";
-import { t as OverlayReader } from "./overlay-reader-CkU_pGXZ.mjs";
-import { t as buildGraph } from "./graph-builder-BEocwW13.mjs";
-import { n as scanSummary, t as scanCandidates } from "./scanner-BSvXjfkp.mjs";
-import { n as applyExtract, r as applyReuse } from "./apply-manager-BybvnUVC.mjs";
-import { t as runDoctor } from "./doctor-DNPuGgcg.mjs";
+import { n as readContext } from "./context-CxpTATh4.mjs";
+import { D as contentDirPath, O as contentFilePath, T as writeContent, _ as resolveContentDir, b as resolveMdFilePath, c as listModels, d as validateModelDefinition, f as writeModel, i as countEntries, l as readModel, m as listContent, o as fieldDefZodSchema, p as deleteContent, r as checkReferences, v as resolveJsonFilePath, y as resolveLocaleStrategy } from "./model-manager-DqwL8ptm.mjs";
+import { a as planModelDelete, i as planModelSave, n as planVocabularySave, o as planContentSave, s as planContentDelete, t as planVocabularyDelete } from "./ops-BfrdZ6GK.mjs";
+import { a as readJson, n as ensureDir, r as pathExists, s as writeJson, t as contentrainDir } from "./fs-DJv5G8uL.mjs";
+import { a as writeMeta, i as readMeta, o as writeMetaEntries, r as mergeEntryMeta, t as applyStatusChange } from "./meta-manager-g3shoZES.mjs";
+import { t as OverlayReader } from "./overlay-reader-Bx1YxGXq.mjs";
+import { n as readVocabulary, t as readConfig } from "./config-B8a4JBT1.mjs";
+import { t as validateProject } from "./validator-B2GhPM3L.mjs";
+import { r as createGit } from "./identity-CxAB9Qb8.mjs";
+import { a as contentBranchRelation, c as listRemoteCrBranches, i as cleanupMergedBranches, n as checkBranchHealth, o as deleteRemoteBranch, u as pruneMergedRemoteBranches } from "./branch-lifecycle-DUOoyNWn.mjs";
+import { i as ensureContentBranch, n as buildBranchName, o as mergeBranch, r as createTransaction } from "./transaction-BxDiiakv.mjs";
+import { n as isMerged, t as LocalProvider } from "./local-bnn6yrG7.mjs";
+import { n as isToolAvailable, t as TOOL_REQUIREMENTS } from "./availability-DYHNoP0_.mjs";
+import { t as detectStack } from "./detect-CI32ynpq.mjs";
+import { t as TOOL_ANNOTATIONS } from "./annotations-CXHPnS-M.mjs";
+import { n as listTemplates, t as getTemplate } from "./templates-BZbohJc8.mjs";
+import { t as normalizeOperationError } from "./errors-BmLE-JSC.mjs";
+import { t as reconcileBranches } from "./reconcile-M7KBZtdn.mjs";
+import { t as buildGraph } from "./graph-builder-C9NS7y-a.mjs";
+import { n as scanSummary, t as scanCandidates } from "./scanner-CEiT8Tgx.mjs";
+import { n as applyExtract, r as applyReuse } from "./apply-manager-DsNq7Zhm.mjs";
+import { t as runDoctor } from "./doctor-B7G0oFxO.mjs";
 import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CONTENTRAIN_BRANCH } from "@contentrain/types";
 import { appendFile, readFile, writeFile } from "node:fs/promises";
-import "simple-git";
 import { z } from "zod";
+import "simple-git";
 //#region src/tools/context.ts
 function registerContextTools(server, provider, projectRoot) {
 	server.tool("contentrain_status", "Get full project status (read-only). Returns config, models, context. Do NOT manually edit .contentrain/ based on this output.", {}, TOOL_ANNOTATIONS["contentrain_status"], async () => {
@@ -78,18 +78,35 @@ function registerContextTools(server, provider, projectRoot) {
 			} : { size: 0 }
 		};
 		if (projectRoot) {
-			if (await pathExists(join(projectRoot, ".git"))) try {
-				const cleanup = await cleanupMergedBranches(projectRoot);
-				const health = await checkBranchHealth(projectRoot);
-				result["branches"] = {
-					total: health.total,
-					merged: health.merged,
-					unmerged: health.unmerged,
-					cleaned_up: cleanup.deleted
-				};
-				if (health.message) result["branch_warning"] = health.message;
-				if (health.blocked) errors.push(health.message);
-			} catch {}
+			if (await pathExists(join(projectRoot, ".git"))) {
+				try {
+					const cleanup = await cleanupMergedBranches(projectRoot);
+					const health = await checkBranchHealth(projectRoot);
+					result["branches"] = {
+						total: health.total,
+						merged: health.merged,
+						unmerged: health.unmerged,
+						cleaned_up: cleanup.deleted
+					};
+					if (health.message) result["branch_warning"] = health.message;
+					if (health.blocked) errors.push(health.message);
+				} catch {}
+				try {
+					const git = createGit(projectRoot);
+					const branches = await git.branchLocal();
+					if (branches.all.includes(CONTENTRAIN_BRANCH)) {
+						const baseBranch = config?.repository?.default_branch ?? (branches.current !== CONTENTRAIN_BRANCH ? branches.current : "main");
+						const relation = await contentBranchRelation(git, baseBranch);
+						result["content_branch"] = {
+							base: baseBranch,
+							ahead: relation.ahead,
+							behind: relation.behind,
+							relation: relation.relation
+						};
+						if (relation.relation === "diverged") result["content_branch_warning"] = `"${CONTENTRAIN_BRANCH}" and "${baseBranch}" have diverged (${relation.ahead} ahead / ${relation.behind} behind). Writes still land on "${CONTENTRAIN_BRANCH}", but "${baseBranch}" cannot fast-forward until the branches are reconciled.`;
+					}
+				} catch {}
+			}
 		}
 		if (errors.length > 0) result["validation"] = {
 			errors: errors.length,
@@ -411,57 +428,6 @@ function generateImportSnippet(model, stack, locale) {
 	return snippets;
 }
 //#endregion
-//#region src/git/errors.ts
-/**
-* Error normalization for git-backed MCP operations.
-*
-* `simple-git` surfaces a failed `git commit`/`push`/`merge` as a `GitError`
-* whose `message` is the raw subprocess stderr — which, for hook tooling
-* (commitlint, husky, lefthook), is colorized multi-line text. Returning that
-* verbatim inside a JSON error produces an unreadable ANSI-escaped blob.
-*
-* This helper strips ANSI, preserves any structured fields the thrown error
-* already carries (`code`/`agent_hint`/`developer_action`), and detects git
-* hook rejections so the agent gets an actionable, structured envelope.
-*/
-const ANSI_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
-function stripAnsi(input) {
-	return input.replace(ANSI_RE, "");
-}
-/**
-* Normalize any thrown error into a structured, ANSI-free envelope for MCP
-* tool responses. `stage` labels where it happened (e.g. 'content_save').
-*/
-function normalizeOperationError(err, stage) {
-	const e = err;
-	const message = stripAnsi(e?.message ?? String(err)).trim();
-	const out = { error: message };
-	if (stage) out.stage = stage;
-	if (e?.code) out.code = e.code;
-	if (e?.agent_hint) out.agent_hint = e.agent_hint;
-	if (e?.developer_action) out.developer_action = e.developer_action;
-	if (!out.code) {
-		const mapped = mapProviderError(err);
-		if (mapped) {
-			out.error = mapped.error;
-			out.code = mapped.code;
-			out.agent_hint = mapped.agent_hint;
-			if (mapped.developer_action) out.developer_action = mapped.developer_action;
-			return out;
-		}
-	}
-	if (!out.code) {
-		const hookName = /\b(commit-msg|pre-commit|prepare-commit-msg|pre-push)\b/i.exec(message)?.[1];
-		const hookTool = /\b(commitlint|husky|lefthook)\b/i.exec(message)?.[1];
-		if (hookName || hookTool) {
-			out.stage = out.stage ?? "git-commit";
-			out.hook = hookName ?? hookTool;
-			out.agent_hint = out.agent_hint ?? "A git hook rejected the Contentrain commit. Contentrain commits with --no-verify, but a wrapping CLI or server-side hook may still run. Ask the developer to allow machine-generated \"[contentrain]\" commits or to exclude cr/* branches from the hook.";
-		}
-	}
-	return out;
-}
-//#endregion
 //#region src/tools/guards.ts
 /**
 * Emit a uniform "capability not available" response for tools that
@@ -484,6 +450,104 @@ function capabilityError(tool, capability) {
 	};
 }
 //#endregion
+//#region src/tools/commit-plan.ts
+/**
+* Context payload describing the operation, threaded into the local
+* transaction so it can regenerate `.contentrain/context.json` on the
+* contentrain branch after merge. Kept as a loose object so tool-specific
+* payloads can add optional fields (`locale`, `entries`) without churning
+* the helper's signature. Remote providers ignore it — see
+* `commitThroughProvider` below.
+*/
+const COMMIT_AUTHOR = {
+	name: "Contentrain",
+	email: "ai@contentrain.io"
+};
+/**
+* The `git` object every write tool reports. One producer instead of nine
+* hand-rolled literals, so `base_advance`/`remote_push` cannot drift between
+* tools. Both fields appear only when the provider reported them (local
+* auto-merge) — remote/review responses keep their previous shape.
+*/
+function gitReport(input) {
+	return {
+		branch: input.branch,
+		action: input.action,
+		commit: input.commit,
+		...input.sync ? { sync: input.sync } : {},
+		...input.base_advance ? { base_advance: input.base_advance } : {},
+		...input.remote_push ? { remote_push: input.remote_push } : {}
+	};
+}
+/**
+* Next-step guidance for a partial success — empty when the base advanced
+* and the push landed.
+*/
+function divergenceNextSteps(input) {
+	const steps = [];
+	if (input.base_advance === "blocked_diverged") steps.push("DIVERGED: the content is safe on the contentrain branch, but the base branch has commits contentrain does not — run contentrain_reconcile (dry_run first) to merge them and restore the fast-forward advance");
+	if (input.remote_push === "rejected") steps.push("PUSH REJECTED: the remote refused the contentrain push even after a retry — the local and remote contentrain branches have diverged; fetch and run contentrain_reconcile");
+	return steps;
+}
+/**
+* Commit a plan's changes through whichever provider is wired into the
+* tool handler. Encapsulates the LocalProvider vs remote RepoProvider
+* dispatch that every write-side tool (content_save, content_delete,
+* model_save, model_delete) used to inline:
+*
+* - **localWorktree providers** — go through the worktree-backed transaction.
+*   `context` payload is threaded as an extra write-through and the
+*   transaction layer decides `auto-merged` vs `pending-review` based on
+*   the project's configured workflow. Selective-sync result is surfaced
+*   to the caller via `sync`.
+*
+* - **Any other RepoProvider** — only the plan's own changes are
+*   committed. Feature branches NEVER carry `.contentrain/context.json`:
+*   the file embeds timestamps, so two parallel cr/* branches forked from
+*   the same contentrain commit would always conflict on it and the
+*   second merge would fail permanently. This mirrors the local
+*   transaction flow, which regenerates context.json on the contentrain
+*   branch after merge (single-threaded, deterministic). Remote flows
+*   always report `pending-review`; Studio (or whatever orchestrator is
+*   driving the server) owns the merge AND the post-merge context
+*   regeneration on the contentrain branch (`buildContextChange` from
+*   `@contentrain/mcp/core/context` is exported for exactly that).
+*
+* The return shape is deliberately uniform so callers don't have to
+* branch on provider type again.
+*/
+async function commitThroughProvider(provider, input) {
+	const { branch, changes, message, contextPayload } = input;
+	if (provider.capabilities.localWorktree) {
+		const result = await provider.applyPlan({
+			branch,
+			changes,
+			message,
+			author: COMMIT_AUTHOR,
+			context: contextPayload
+		});
+		return {
+			commitSha: result.sha,
+			workflowAction: result.workflowAction ?? "pending-review",
+			sync: result.sync,
+			warning: result.warning,
+			base_advance: result.base_advance,
+			remote_push: result.remote_push
+		};
+	}
+	const allChanges = changes.toSorted((a, b) => a.path.localeCompare(b.path));
+	return {
+		commitSha: (await provider.applyPlan({
+			branch,
+			changes: allChanges,
+			message,
+			author: COMMIT_AUTHOR,
+			base: CONTENTRAIN_BRANCH
+		})).sha,
+		workflowAction: "pending-review"
+	};
+}
+//#endregion
 //#region src/tools/setup.ts
 function registerSetupTools(server, _provider, projectRoot) {
 	server.tool("contentrain_init", "Initialize .contentrain/ structure. Changes are auto-committed to git — do NOT manually create .contentrain/ files.", {
@@ -602,12 +666,15 @@ function registerSetupTools(server, _provider, projectRoot) {
 						".contentrain/meta/"
 					],
 					gitignore_updated: true,
-					git: {
+					git: gitReport({
 						branch,
 						action: gitResult.action,
 						commit: gitResult.commit,
-						...gitResult.sync ? { sync: gitResult.sync } : {}
-					},
+						sync: gitResult.sync,
+						base_advance: gitResult.base_advance,
+						remote_push: gitResult.remote_push
+					}),
+					...gitResult.warning ? { warning: gitResult.warning } : {},
 					next_steps: ["Create models with contentrain_model_save or contentrain_scaffold", "Use contentrain_scan to find hardcoded strings"]
 				}, null, 2)
 			}] };
@@ -706,12 +773,15 @@ function registerSetupTools(server, _provider, projectRoot) {
 					models_created: modelsCreated,
 					content_created: contentCreated,
 					vocabulary_terms_added: vocabAdded,
-					git: {
+					git: gitReport({
 						branch,
 						action: gitResult.action,
 						commit: gitResult.commit,
-						...gitResult.sync ? { sync: gitResult.sync } : {}
-					},
+						sync: gitResult.sync,
+						base_advance: gitResult.base_advance,
+						remote_push: gitResult.remote_push
+					}),
+					...gitResult.warning ? { warning: gitResult.warning } : {},
 					context_updated: true,
 					next_steps: [
 						"Customize models with contentrain_model_save",
@@ -799,75 +869,6 @@ async function mergeVocabulary(projectRoot, newTerms, _locales) {
 	return added;
 }
 //#endregion
-//#region src/tools/commit-plan.ts
-/**
-* Context payload describing the operation, threaded into the local
-* transaction so it can regenerate `.contentrain/context.json` on the
-* contentrain branch after merge. Kept as a loose object so tool-specific
-* payloads can add optional fields (`locale`, `entries`) without churning
-* the helper's signature. Remote providers ignore it — see
-* `commitThroughProvider` below.
-*/
-const COMMIT_AUTHOR = {
-	name: "Contentrain",
-	email: "ai@contentrain.io"
-};
-/**
-* Commit a plan's changes through whichever provider is wired into the
-* tool handler. Encapsulates the LocalProvider vs remote RepoProvider
-* dispatch that every write-side tool (content_save, content_delete,
-* model_save, model_delete) used to inline:
-*
-* - **localWorktree providers** — go through the worktree-backed transaction.
-*   `context` payload is threaded as an extra write-through and the
-*   transaction layer decides `auto-merged` vs `pending-review` based on
-*   the project's configured workflow. Selective-sync result is surfaced
-*   to the caller via `sync`.
-*
-* - **Any other RepoProvider** — only the plan's own changes are
-*   committed. Feature branches NEVER carry `.contentrain/context.json`:
-*   the file embeds timestamps, so two parallel cr/* branches forked from
-*   the same contentrain commit would always conflict on it and the
-*   second merge would fail permanently. This mirrors the local
-*   transaction flow, which regenerates context.json on the contentrain
-*   branch after merge (single-threaded, deterministic). Remote flows
-*   always report `pending-review`; Studio (or whatever orchestrator is
-*   driving the server) owns the merge AND the post-merge context
-*   regeneration on the contentrain branch (`buildContextChange` from
-*   `@contentrain/mcp/core/context` is exported for exactly that).
-*
-* The return shape is deliberately uniform so callers don't have to
-* branch on provider type again.
-*/
-async function commitThroughProvider(provider, input) {
-	const { branch, changes, message, contextPayload } = input;
-	if (provider.capabilities.localWorktree) {
-		const result = await provider.applyPlan({
-			branch,
-			changes,
-			message,
-			author: COMMIT_AUTHOR,
-			context: contextPayload
-		});
-		return {
-			commitSha: result.sha,
-			workflowAction: result.workflowAction ?? "pending-review",
-			sync: result.sync
-		};
-	}
-	const allChanges = changes.toSorted((a, b) => a.path.localeCompare(b.path));
-	return {
-		commitSha: (await provider.applyPlan({
-			branch,
-			changes: allChanges,
-			message,
-			author: COMMIT_AUTHOR,
-			base: CONTENTRAIN_BRANCH
-		})).sha,
-		workflowAction: "pending-review"
-	};
-}
-//#endregion
 //#region src/tools/model.ts
 const fieldDefSchema = fieldDefZodSchema;
 function registerModelTools(server, provider, projectRoot) {
@@ -951,19 +952,14 @@ function registerModelTools(server, provider, projectRoot) {
 			tool: "contentrain_model_save",
 			model: input.id
 		};
-		let commitSha;
-		let workflowAction;
-		let sync;
+		let commit;
 		try {
-			const result = await commitThroughProvider(provider, {
+			commit = await commitThroughProvider(provider, {
 				branch,
 				changes: savePlan.changes,
 				message,
 				contextPayload
 			});
-			commitSha = result.commitSha;
-			workflowAction = result.workflowAction;
-			sync = result.sync;
 		} catch (error) {
 			return {
 				content: [{
@@ -995,17 +991,24 @@ function registerModelTools(server, provider, projectRoot) {
 					errors: []
 				},
 				...schemaWarnings.length > 0 ? { schema_warnings: schemaWarnings } : {},
-				git: {
+				git: gitReport({
 					branch,
-					action: workflowAction,
-					commit: commitSha,
-					...sync ? { sync } : {}
-				},
+					action: commit.workflowAction,
+					commit: commit.commitSha,
+					sync: commit.sync,
+					base_advance: commit.base_advance,
+					remote_push: commit.remote_push
+				}),
+				...commit.warning ? { warning: commit.warning } : {},
 				context_updated: true,
 				content_path: contentPath + "/",
 				...displayPath ? { example_file: displayPath } : {},
 				...importSnippet ? { import_snippet: importSnippet } : {},
-				next_steps: [...schemaWarnings.length > 0 ? ["REVIEW: see schema_warnings — some declared constraints are not enforced by MCP"] : [], "Add content with contentrain_content_save"]
+				next_steps: [
+					...divergenceNextSteps(commit),
+					...schemaWarnings.length > 0 ? ["REVIEW: see schema_warnings — some declared constraints are not enforced by MCP"] : [],
+					"Add content with contentrain_content_save"
+				]
 			}, null, 2)
 		}] };
 	});
@@ -1057,33 +1060,32 @@ function registerModelTools(server, provider, projectRoot) {
 			tool: "contentrain_model_delete",
 			model: modelId
 		};
-		let commitSha;
-		let workflowAction;
-		let sync;
 		try {
-			const result = await commitThroughProvider(provider, {
+			const commit = await commitThroughProvider(provider, {
 				branch,
 				changes: deletePlan.changes,
 				message,
 				contextPayload
 			});
-			commitSha = result.commitSha;
-			workflowAction = result.workflowAction;
-			sync = result.sync;
+			const nextSteps = divergenceNextSteps(commit);
 			return { content: [{
 				type: "text",
 				text: JSON.stringify({
 					status: "committed",
 					message: "Model deleted and committed to git. Do NOT manually edit .contentrain/ files.",
 					deleted: true,
-					git: {
+					git: gitReport({
 						branch,
-						action: workflowAction,
-						commit: commitSha,
-						...sync ? { sync } : {}
-					},
+						action: commit.workflowAction,
+						commit: commit.commitSha,
+						sync: commit.sync,
+						base_advance: commit.base_advance,
+						remote_push: commit.remote_push
+					}),
+					...commit.warning ? { warning: commit.warning } : {},
 					files_removed: deletePlan.result,
-					context_updated: true
+					context_updated: true,
+					...nextSteps.length > 0 ? { next_steps: nextSteps } : {}
 				}, null, 2)
 			}] };
 		} catch (error) {
@@ -1221,19 +1223,14 @@ function registerContentTools(server, provider, projectRoot) {
 			locale: input.entries[0]?.locale,
 			entries: entryIds
 		};
-		let commitSha;
-		let workflowAction;
-		let sync;
+		let commit;
 		try {
-			const result = await commitThroughProvider(provider, {
+			commit = await commitThroughProvider(provider, {
 				branch,
 				changes: plan.changes,
 				message,
 				contextPayload
 			});
-			commitSha = result.commitSha;
-			workflowAction = result.workflowAction;
-			sync = result.sync;
 		} catch (error) {
 			return {
 				content: [{
@@ -1251,12 +1248,15 @@ function registerContentTools(server, provider, projectRoot) {
 				status: "committed",
 				message: "Content saved and committed to git. Do NOT manually edit .contentrain/ files.",
 				results: plan.result,
-				git: {
+				git: gitReport({
 					branch,
-					action: workflowAction,
-					commit: commitSha,
-					...sync ? { sync } : {}
-				},
+					action: commit.workflowAction,
+					commit: commit.commitSha,
+					sync: commit.sync,
+					base_advance: commit.base_advance,
+					remote_push: commit.remote_push
+				}),
+				...commit.warning ? { warning: commit.warning } : {},
 				...allAdvisories.length > 0 ? {
 					advisories: allAdvisories,
 					advisory_note: "Save succeeded. Review these warnings and consider consolidating duplicate values."
@@ -1268,6 +1268,7 @@ function registerContentTools(server, provider, projectRoot) {
 				},
 				context_updated: true,
 				next_steps: [
+					...divergenceNextSteps(commit),
 					...allAdvisories.length > 0 ? ["ADVISORY: Duplicate values detected — review advisories above"] : [],
 					...warnings.length > 0 ? ["REVIEW: see warnings above — the save was not blocked by them"] : [],
 					...model.kind === "collection" ? ["Use contentrain_content_list to verify", "Add more entries or publish"] : ["Use contentrain_content_list to verify"]
@@ -1337,19 +1338,14 @@ function registerContentTools(server, provider, projectRoot) {
 			model: input.model,
 			locale: input.locale
 		};
-		let commitSha;
-		let workflowAction;
-		let sync;
 		try {
-			const result = await commitThroughProvider(provider, {
+			const commit = await commitThroughProvider(provider, {
 				branch,
 				changes: deletePlan.changes,
 				message,
 				contextPayload
 			});
-			commitSha = result.commitSha;
-			workflowAction = result.workflowAction;
-			sync = result.sync;
+			const nextSteps = divergenceNextSteps(commit);
 			return { content: [{
 				type: "text",
 				text: JSON.stringify({
@@ -1357,13 +1353,17 @@ function registerContentTools(server, provider, projectRoot) {
 					message: "Content deleted and committed to git. Do NOT manually edit .contentrain/ files.",
 					deleted: true,
 					files_removed: deletePlan.result,
-					git: {
+					git: gitReport({
 						branch,
-						action: workflowAction,
-						commit: commitSha,
-						...sync ? { sync } : {}
-					},
-					context_updated: true
+						action: commit.workflowAction,
+						commit: commit.commitSha,
+						sync: commit.sync,
+						base_advance: commit.base_advance,
+						remote_push: commit.remote_push
+					}),
+					...commit.warning ? { warning: commit.warning } : {},
+					context_updated: true,
+					...nextSteps.length > 0 ? { next_steps: nextSteps } : {}
 				}, null, 2)
 			}] };
 		} catch (error) {
@@ -1523,6 +1523,9 @@ function registerVocabularyTools(server, provider) {
 					total_terms: plan.result.total,
 					commit: commit.commitSha,
 					workflow_action: commit.workflowAction,
+					...commit.base_advance ? { base_advance: commit.base_advance } : {},
+					...commit.remote_push ? { remote_push: commit.remote_push } : {},
+					...commit.warning ? { warning: commit.warning } : {},
 					...plan.advisories.length > 0 ? { advisories: plan.advisories } : {}
 				}, null, 2)
 			}] };
@@ -1595,6 +1598,9 @@ function registerVocabularyTools(server, provider) {
 					total_terms: plan.result.total,
 					commit: commit.commitSha,
 					workflow_action: commit.workflowAction,
+					...commit.base_advance ? { base_advance: commit.base_advance } : {},
+					...commit.remote_push ? { remote_push: commit.remote_push } : {},
+					...commit.warning ? { warning: commit.warning } : {},
 					...plan.advisories.length > 0 ? { advisories: plan.advisories } : {}
 				}, null, 2)
 			}] };
@@ -1697,7 +1703,7 @@ function registerWorkflowTools(server, provider, projectRoot) {
 							model: input.model ?? "*"
 						});
 						const gitResult = await tx.complete();
-						const nextSteps = [];
+						const nextSteps = [...divergenceNextSteps(gitResult)];
 						if (result.summary.errors > 0) nextSteps.push("Fix remaining errors manually");
 						if (result.summary.warnings > 0) nextSteps.push("Review warnings");
 						nextSteps.push("Run contentrain_validate again to verify");
@@ -1707,12 +1713,15 @@ function registerWorkflowTools(server, provider, projectRoot) {
 								status: "committed",
 								message: `Validation complete. ${result.fixed} issue(s) auto-fixed and committed to git. Do NOT manually edit .contentrain/ files.`,
 								...result,
-								git: {
+								git: gitReport({
 									branch,
 									action: gitResult.action,
 									commit: gitResult.commit,
-									...gitResult.sync ? { sync: gitResult.sync } : {}
-								},
+									sync: gitResult.sync,
+									base_advance: gitResult.base_advance,
+									remote_push: gitResult.remote_push
+								}),
+								...gitResult.warning ? { warning: gitResult.warning } : {},
 								context_updated: true,
 								next_steps: nextSteps
 							}, null, 2)
@@ -1918,8 +1927,12 @@ function registerWorkflowTools(server, provider, projectRoot) {
 					action: result.action,
 					commit: result.commit,
 					sync: result.sync,
+					base_advance: result.base_advance,
+					remote_push: result.remote_push,
+					...result.warning ? { warning: result.warning } : {},
 					...result.remote ? { remote: result.remote } : {},
 					next_steps: [
+						...divergenceNextSteps(result),
 						"Run `contentrain generate` (or `npx contentrain-query generate`) to update the SDK client",
 						"Run contentrain_validate to verify content integrity",
 						result.sync.skipped.length > 0 ? `${result.sync.skipped.length} file(s) skipped due to local changes — resolve manually` : "",
@@ -2060,6 +2073,96 @@ function registerWorkflowTools(server, provider, projectRoot) {
 	});
 }
 //#endregion
+//#region src/tools/reconcile.ts
+const resolutionSchema = z.union([z.object({
+	id: z.string().describe("Conflict id from a previous dry-run"),
+	choose: z.enum(["ours", "theirs"]).describe("Take the contentrain side (ours) or the base-branch side (theirs)")
+}), z.object({
+	id: z.string().describe("Conflict id from a previous dry-run"),
+	value: z.unknown().describe("Hand-authored replacement value")
+})]);
+function registerReconcileTools(server, provider, projectRoot) {
+	server.tool("contentrain_reconcile", "Reconcile a diverged contentrain ↔ base-branch pair with a content-aware three-way merge. DRY RUN (default, dry_run:true): reports what would merge and which conflicts need a decision — touches nothing. EXECUTE (dry_run:false): performs the merge as a two-parent commit on contentrain and fast-forwards the base branch. Everything one side changed merges mechanically (entry-, key-, term+locale-level); only the same item changed differently on both sides becomes a conflict. Answer conflicts by passing resolutions (from the dry-run ids) and running again — a resolution whose values changed since the dry-run is dropped and the conflict re-reported. Recommended workflow: always run dry_run first, review the summary and conflicts, then execute.", {
+		dry_run: z.boolean().optional().default(true).describe("Defaults to preview mode (dry_run:true). Set dry_run:false to execute after reviewing the preview."),
+		resolutions: z.array(resolutionSchema).optional().describe("Decisions for conflicts reported by a previous dry-run, matched by id")
+	}, TOOL_ANNOTATIONS["contentrain_reconcile"], async (input) => {
+		if (!provider.capabilities.localWorktree || !projectRoot) return capabilityError("contentrain_reconcile", "localWorktree");
+		if (!await readConfig(provider)) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({ error: "Project not initialized. Run contentrain_init first." })
+			}],
+			isError: true
+		};
+		try {
+			const result = await reconcileBranches(projectRoot, {
+				dryRun: input.dry_run,
+				resolutions: input.resolutions,
+				source: "mcp-local"
+			});
+			if (result.action === "in_sync") return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					status: "in_sync",
+					message: `"${result.base}" is already contained in the contentrain branch — nothing to reconcile.`,
+					base: result.base
+				}, null, 2)
+			}] };
+			if (result.action === "preview") return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					status: "preview",
+					dry_run: true,
+					base: result.base,
+					merge_base: result.merge_base,
+					summary: result.plan.result,
+					changes: result.plan.changes.map((c) => ({
+						path: c.path,
+						action: c.content === null ? "delete" : "write"
+					})),
+					conflicts: result.plan.conflicts,
+					...result.plan.advisories.length > 0 ? { advisories: result.plan.advisories } : {},
+					next_steps: result.plan.conflicts.length > 0 ? [`${result.plan.conflicts.length} conflict(s) need a decision — collect resolutions ({ id, choose: 'ours'|'theirs' } or { id, value }) and call contentrain_reconcile again`, "Conflicts are content decisions: ask the editor/user, do not guess"] : ["Plan is clean — run contentrain_reconcile with dry_run:false to execute"]
+				}, null, 2)
+			}] };
+			if (result.action === "conflicts") return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					status: "conflicts",
+					message: `${result.plan.conflicts.length} conflict(s) remain — nothing was written.`,
+					base: result.base,
+					conflicts: result.plan.conflicts,
+					...result.plan.advisories.length > 0 ? { advisories: result.plan.advisories } : {},
+					agent_hint: "Each conflict is a content decision. Ask the editor/user which side (or value) should win, then pass resolutions and run again."
+				}, null, 2)
+			}] };
+			return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					status: "reconciled",
+					message: `Merged "${result.base}" into the contentrain branch and fast-forwarded "${result.base}".`,
+					base: result.base,
+					commit: result.commit,
+					base_advance: result.base_advance,
+					...result.remote_push ? { remote_push: result.remote_push } : {},
+					...result.sync ? { sync: result.sync } : {},
+					summary: result.plan.result,
+					...result.plan.advisories.length > 0 ? { advisories: result.plan.advisories } : {},
+					next_steps: ["Run contentrain_validate to verify content integrity", "Run `contentrain generate` to refresh the SDK client"]
+				}, null, 2)
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(normalizeOperationError(error, "reconcile"), null, 2)
+				}],
+				isError: true
+			};
+		}
+	});
+}
+//#endregion
 //#region src/tools/normalize.ts
 function registerNormalizeTools(server, provider, projectRoot) {
 	server.tool("contentrain_scan", "Scan project source code for content strings. Three modes: \"graph\" builds import/component graph for project intelligence, \"candidates\" extracts string literals with pre-filtering and pagination, \"summary\" provides quick overview stats. Read-only — no changes to disk or git. MCP finds strings deterministically; the agent decides what is content. Recommended workflow: start with \"summary\" or \"graph\" for orientation, then paginate through \"candidates\" to evaluate strings.", {
@@ -2434,12 +2537,16 @@ function registerBulkTools(server, _provider, projectRoot) {
 							operation: "copy_locale",
 							message: `Copied ${copiedCount} entries from ${input.source_locale} to ${input.target_locale}.`,
 							copied: copiedCount,
-							git: {
+							git: gitReport({
 								branch,
 								action: gitResult.action,
 								commit: gitResult.commit,
-								...gitResult.sync ? { sync: gitResult.sync } : {}
-							},
+								sync: gitResult.sync,
+								base_advance: gitResult.base_advance,
+								remote_push: gitResult.remote_push
+							}),
+							...gitResult.warning ? { warning: gitResult.warning } : {},
+							...divergenceNextSteps(gitResult).length > 0 ? { next_steps: divergenceNextSteps(gitResult) } : {},
 							context_updated: true
 						}, null, 2)
 					}] };
@@ -2560,12 +2667,16 @@ function registerBulkTools(server, _provider, projectRoot) {
 							updated: updatedCount,
 							updated_by_locale: updatedPerLocale,
 							not_found: notFound.length > 0 ? notFound : void 0,
-							git: {
+							git: gitReport({
 								branch,
 								action: gitResult.action,
 								commit: gitResult.commit,
-								...gitResult.sync ? { sync: gitResult.sync } : {}
-							},
+								sync: gitResult.sync,
+								base_advance: gitResult.base_advance,
+								remote_push: gitResult.remote_push
+							}),
+							...gitResult.warning ? { warning: gitResult.warning } : {},
+							...divergenceNextSteps(gitResult).length > 0 ? { next_steps: divergenceNextSteps(gitResult) } : {},
 							context_updated: true
 						}, null, 2)
 					}] };
@@ -2631,12 +2742,16 @@ function registerBulkTools(server, _provider, projectRoot) {
 							message: `Deleted ${input.entry_ids.length} entries.`,
 							deleted: input.entry_ids.length,
 							files_removed: allRemoved,
-							git: {
+							git: gitReport({
 								branch,
 								action: gitResult.action,
 								commit: gitResult.commit,
-								...gitResult.sync ? { sync: gitResult.sync } : {}
-							},
+								sync: gitResult.sync,
+								base_advance: gitResult.base_advance,
+								remote_push: gitResult.remote_push
+							}),
+							...gitResult.warning ? { warning: gitResult.warning } : {},
+							...divergenceNextSteps(gitResult).length > 0 ? { next_steps: divergenceNextSteps(gitResult) } : {},
 							context_updated: true
 						}, null, 2)
 					}] };
@@ -2806,7 +2921,7 @@ function registerMediaTools(server, provider, _projectRoot) {
 }
 //#endregion
 //#region package.json
-var version = "3.0.2";
+var version = "3.1.0";
 //#endregion
 //#region src/server.ts
 /**
@@ -2845,6 +2960,7 @@ function createServer(input) {
 	registerContentTools(server, provider, projectRoot);
 	registerVocabularyTools(server, provider);
 	registerWorkflowTools(server, provider, projectRoot);
+	registerReconcileTools(server, provider, projectRoot);
 	registerNormalizeTools(server, provider, projectRoot);
 	registerBulkTools(server, provider, projectRoot);
 	registerDoctorTools(server, provider, projectRoot);
@@ -2880,4 +2996,4 @@ function resolveServerContext(input) {
 //#endregion
 export { createServer as n, DEFAULT_INSTRUCTIONS as t };
 
-//# sourceMappingURL=server-DdxWpNBH.mjs.map
+//# sourceMappingURL=server-BtzVY7yp.mjs.map