contentrain 0.4.4 → 0.5.1

package/README.md

@@ -17,9 +17,9 @@ Start here:
 - initialize `.contentrain/` in an existing repo
 - inspect project health and validation state
 - generate the typed `#contentrain` SDK client
-- review pending `contentrain/*` branches
+- review pending `cr/*` branches
 - run the local review UI
-- expose the MCP server over stdio for IDE agents
+- expose the MCP server over stdio (IDE agents) or HTTP (Studio, CI, remote drivers)
 
 This package is the human-facing companion to:
 
@@ -27,7 +27,7 @@ This package is the human-facing companion to:
 - [`@contentrain/query`](https://github.com/Contentrain/ai/tree/main/packages/sdk/js) for generated runtime queries
 - [`@contentrain/rules`](https://github.com/Contentrain/ai/tree/main/packages/rules) and [`@contentrain/skills`](https://github.com/Contentrain/ai/tree/main/packages/skills) for agent guidance
 
-## 🚀 Install
+## Install
 
 Use `npx`:
 
@@ -47,7 +47,15 @@ Requirements:
 - Node.js 22+
 - Git available in `PATH`
 
-## 🧰 Commands
+## Global Flags
+
+| Flag | Env var | Description |
+| --- | --- | --- |
+| `--debug` | `CONTENTRAIN_DEBUG=1` | Verbose debug logging to stderr (works on every subcommand) |
+
+Example: `contentrain --debug status` or `CONTENTRAIN_DEBUG=1 contentrain validate`.
+
+## Commands
 
 | Command | Purpose |
 | --- | --- |
@@ -56,8 +64,14 @@ Requirements:
 | `contentrain doctor` | Check setup health, SDK freshness, orphan content, and branch limits |
 | `contentrain validate` | Validate content against schemas, optionally create review-branch fixes |
 | `contentrain generate` | Generate `.contentrain/client/` and `#contentrain` package imports |
-| `contentrain diff` | Review and merge or reject pending `contentrain/*` branches |
-| `contentrain serve` | Start the local review UI or the MCP stdio server |
+| `contentrain diff` | Review and merge or reject pending `cr/*` branches interactively |
+| `contentrain merge <branch>` | Merge one pending `cr/*` branch non-interactively (CI/agents) |
+| `contentrain describe <model>` | Inspect a model's schema, stats, and import snippet |
+| `contentrain describe-format` | Print the Contentrain content-format specification |
+| `contentrain scaffold --template` | Apply a template (`blog`, `landing`, `docs`, `ecommerce`, `saas`, `i18n`, `mobile`) |
+| `contentrain setup <agent\|--all>` | Configure MCP server + AI rules for IDE (Claude Code, Cursor, Windsurf, VSCode, Copilot) |
+| `contentrain skills` | Install, update, or list Contentrain AI skills and IDE rules |
+| `contentrain serve` | Start the local review UI (REST + WS), MCP stdio server (`--stdio`), or MCP HTTP server (`--mcpHttp`) |
 | `contentrain studio connect` | Connect a repository to a Studio project |
 | `contentrain studio login` | Authenticate with Contentrain Studio |
 | `contentrain studio logout` | Log out from Studio |
@@ -71,7 +85,23 @@ Requirements:
 | `contentrain studio webhooks` | Manage webhooks |
 | `contentrain studio submissions` | Manage form submissions |
 
-## 🔄 Typical Flow
+## Flag Matrix
+
+Every read command supports `--json` for CI use; write commands surface `--watch` or `--yes` where they apply:
+
+| Command | Notable flags |
+| --- | --- |
+| `status` | `--json` |
+| `doctor` | `--json`, `--usage` — non-zero exit on failure |
+| `validate` | `--json`, `--fix`, `--interactive`, `--watch`, `--model <id>` |
+| `generate` | `--json`, `--watch` |
+| `diff` | `--json` |
+| `merge` | `--yes` (skip confirm) |
+| `describe` | `--sample`, `--locale`, `--json` |
+| `scaffold` | `--template <id>`, `--locales <csv>`, `--no-sample`, `--json` |
+| `serve` | `--port`, `--host`, `--open`, `--demo`, `--stdio`, `--mcpHttp`, `--authToken` |
+
+## Typical Flow
 
 Initialize a project:
 
@@ -79,56 +109,72 @@ Initialize a project:
 contentrain init
 ```
 
-Check project state:
+Check project state (with optional JSON for CI):
 
 ```bash
 contentrain status
+contentrain status --json
+
 contentrain doctor
+contentrain doctor --json
+contentrain doctor --usage  # Analyze content key usage
 ```
 
 Generate the typed SDK client:
 
 ```bash
 contentrain generate
+contentrain generate --watch    # Watch for changes
+contentrain generate --json     # CI-friendly JSON output
 ```
 
-Validate content and create review-branch fixes when possible:
+Validate content and create review-branch fixes:
 
 ```bash
 contentrain validate
 contentrain validate --fix
+contentrain validate --watch    # Live validation in dev mode
+contentrain validate --json     # CI output
 ```
 
 Review pending changes:
 
 ```bash
 contentrain diff
+contentrain diff --json  # CI integration
 ```
 
 Open the local UI:
 
 ```bash
 contentrain serve
+contentrain serve --demo  # Start with a temporary demo project
 ```
 
-## 🖥 `serve` Modes
+Enable detailed logging:
 
-`contentrain serve` has two roles.
+```bash
+contentrain --debug status
+CONTENTRAIN_DEBUG=1 contentrain validate  # Via environment variable
+```
 
-Start the local review UI:
+## `serve` Modes
+
+`contentrain serve` has three roles.
+
+### Local review UI (default)
 
 ```bash
 contentrain serve
 contentrain serve --port 3333 --host localhost
+contentrain serve --demo  # Temporary project (no setup needed)
 ```
 
-This serves:
+Serves REST endpoints for status / content / validation / branches / normalize / doctor / describe-format / preview-merge, a WebSocket stream for live updates, and the embedded Vue `serve-ui` app bundled with the CLI.
 
-- REST endpoints for status, content, validation, branches, and normalize data
-- a WebSocket stream for live updates
-- the embedded Vue `serve-ui` app bundled with the CLI
+WebSocket event types: `connected`, `config:changed`, `context:changed`, `meta:changed`, `model:changed`, `content:changed`, `branch:created`, `branch:merged`, `branch:rejected`, `branch:merge-conflict`, `sync:warning`, `validation:updated`, `normalize:plan-updated`, `file-watch:error`.
 
-Start the MCP server for IDE integration:
+### MCP stdio (IDE agents)
 
 ```bash
 contentrain serve --stdio
@@ -136,7 +182,22 @@ contentrain serve --stdio
 
 Use stdio mode when connecting Claude Code, Cursor, Windsurf, or another MCP client to the local project.
 
-## 📦 `generate` and `#contentrain`
+### MCP HTTP (Studio, CI, remote drivers)
+
+```bash
+contentrain serve --mcpHttp --authToken $(openssl rand -hex 32)
+contentrain serve --mcpHttp --port 3333 --host 0.0.0.0 --authToken $TOKEN
+```
+
+Spins up a [Streamable HTTP MCP](https://modelcontextprotocol.io) server at `POST /mcp`. Bearer auth is **required** on non-localhost binds — the CLI hard-errors when no `--authToken` is set for an exposed interface (OWASP Secure-by-Default). Use HTTP mode when:
+
+- Studio's agent drives MCP remotely
+- a CI runner needs deterministic content operations
+- an agent on another machine orchestrates content changes
+
+HTTP sessions use the same `LocalProvider` backing as stdio — the transport differs, the behaviour does not. Remote git-host providers (`GitHubProvider`, `GitLabProvider`) are constructed by embedders who instantiate the MCP server programmatically; see the MCP package docs for that flow.
+
+## `generate` and `#contentrain`
 
 `contentrain generate` writes a typed client to `.contentrain/client/` and injects `#contentrain` imports into your `package.json`.
 
@@ -152,7 +213,30 @@ Run with watch mode during local model/content work:
 contentrain generate --watch
 ```
 
-## 👀 Review Workflow
+## IDE Setup and AI Skills
+
+Configure your IDE to use Contentrain's MCP server and AI agent rules:
+
+```bash
+contentrain setup claude-code
+contentrain setup cursor
+contentrain setup vscode
+contentrain setup --all  # Configure all detected IDEs
+```
+
+Install or update AI agent skills and IDE rules:
+
+```bash
+contentrain skills
+contentrain skills --update  # Force update
+contentrain skills --list    # List installed skills
+```
+
+This installs:
+- Contentrain Agent Skills (task guidance for Claude, Cursor, etc.)
+- IDE rules files (CLAUDE.md, .cursorrules, .windsurfrules)
+
+## Review Workflow
 
 Most write operations create feature branches from the dedicated `contentrain` branch. In review mode, these branches are pushed to remote for team review. In auto-merge mode, they are merged into the `contentrain` branch and baseBranch is advanced via update-ref.
 
@@ -165,11 +249,11 @@ contentrain diff
 
 to understand:
 
-- how many active review branches exist on the `contentrain` branch
-- whether branch health is blocking new writes
+- how many active `cr/*` review branches exist on the `contentrain` branch
+- whether branch health is blocking new writes (warning at 50, blocked at 80)
 - what changed before merging or deleting a branch
 
-## 🔗 Studio Integration
+## Studio Integration
 
 The `studio` command group connects the CLI to [Contentrain Studio](https://studio.contentrain.io) for enterprise workflows.
 
@@ -212,21 +296,11 @@ contentrain studio submissions --form contact-form
 
 Credentials are stored securely in `~/.contentrain/credentials.json` with `0o600` permissions. Use `CONTENTRAIN_STUDIO_TOKEN` environment variable for CI/CD.
 
-## 🤖 IDE Rules
-
-`contentrain init` installs project-level AI rules automatically:
-
-- `CLAUDE.md` for Claude Code or generic fallback
-- `.cursorrules` for Cursor
-- `.windsurfrules` for Windsurf
-
-If the target file already exists, Contentrain appends its rules instead of overwriting unrelated content where possible.
-
-## 📚 Documentation
+## Documentation
 
 Full documentation at **[ai.contentrain.io/packages/cli](https://ai.contentrain.io/packages/cli)**.
 
-## 🛠 Development
+## Development
 
 From the monorepo root:
 
@@ -235,3 +309,7 @@ pnpm --filter contentrain test -- --run
 pnpm --filter contentrain exec tsc --noEmit
 pnpm --filter contentrain build
 ```
+
+## License
+
+MIT

package/dist/{activity-CbkxcfDf.mjs → activity-B8j9gfsK.mjs}

@@ -1,6 +1,6 @@
-import { i as pc } from "./ui-B5mXontH.mjs";
-import { n as resolveStudioClient } from "./client-C400qHcL.mjs";
-import { t as resolveStudioContext } from "./resolve-context-Cg6JoVZt.mjs";
+import { i as pc } from "./ui-B8l_LC36.mjs";
+import { n as resolveStudioClient } from "./client-C9E9D4mb.mjs";
+import { t as resolveStudioContext } from "./resolve-context-hKVYPniC.mjs";
 import { defineCommand } from "citty";
 import { intro, log, outro, spinner } from "@clack/prompts";
 //#region src/studio/commands/activity.ts

package/dist/{branches-D2UWex1N.mjs → branches-CvpFbyrJ.mjs}

@@ -1,6 +1,6 @@
-import { i as pc, r as formatTable, t as formatCount } from "./ui-B5mXontH.mjs";
-import { n as resolveStudioClient } from "./client-C400qHcL.mjs";
-import { t as resolveStudioContext } from "./resolve-context-Cg6JoVZt.mjs";
+import { i as pc, r as formatTable, t as formatCount } from "./ui-B8l_LC36.mjs";
+import { n as resolveStudioClient } from "./client-C9E9D4mb.mjs";
+import { t as resolveStudioContext } from "./resolve-context-hKVYPniC.mjs";
 import { defineCommand } from "citty";
 import { confirm, intro, isCancel, log, outro, select, spinner } from "@clack/prompts";
 //#region src/studio/commands/branches.ts

package/dist/{cdn-build-BzC2QPNi.mjs → cdn-build-DS9FprWU.mjs}

@@ -1,6 +1,6 @@
-import { i as pc, t as formatCount } from "./ui-B5mXontH.mjs";
-import { n as resolveStudioClient } from "./client-C400qHcL.mjs";
-import { t as resolveStudioContext } from "./resolve-context-Cg6JoVZt.mjs";
+import { i as pc, t as formatCount } from "./ui-B8l_LC36.mjs";
+import { n as resolveStudioClient } from "./client-C9E9D4mb.mjs";
+import { t as resolveStudioContext } from "./resolve-context-hKVYPniC.mjs";
 import { defineCommand } from "citty";
 import { intro, log, outro, spinner } from "@clack/prompts";
 //#region src/studio/commands/cdn-build.ts

package/dist/{cdn-init-CsmqJIaQ.mjs → cdn-init-Bm4dpEJn.mjs}

@@ -1,6 +1,6 @@
-import { i as pc } from "./ui-B5mXontH.mjs";
-import { n as resolveStudioClient } from "./client-C400qHcL.mjs";
-import { t as resolveStudioContext } from "./resolve-context-Cg6JoVZt.mjs";
+import { i as pc } from "./ui-B8l_LC36.mjs";
+import { n as resolveStudioClient } from "./client-C9E9D4mb.mjs";
+import { t as resolveStudioContext } from "./resolve-context-hKVYPniC.mjs";
 import { defineCommand } from "citty";
 import { confirm, intro, isCancel, log, outro, spinner } from "@clack/prompts";
 //#region src/studio/commands/cdn-init.ts

package/dist/{connect-DJo9PSiw.mjs → connect-Bb0BrZsx.mjs}

@@ -1,6 +1,6 @@
-import { i as pc } from "./ui-B5mXontH.mjs";
-import { c as saveDefaults, n as resolveStudioClient } from "./client-C400qHcL.mjs";
-import { n as openBrowser, t as startOAuthServer } from "./oauth-server-Beppljfz.mjs";
+import { i as pc } from "./ui-B8l_LC36.mjs";
+import { c as saveDefaults, n as resolveStudioClient } from "./client-C9E9D4mb.mjs";
+import { n as openBrowser, t as startOAuthServer } from "./oauth-server-smSxDoH5.mjs";
 import { defineCommand } from "citty";
 import { confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import { simpleGit } from "simple-git";

package/dist/describe-DJ5H9Cxm.mjs

@@ -0,0 +1,106 @@
+import { i as pc } from "./ui-B8l_LC36.mjs";
+import { r as resolveProjectRoot } from "./context-OskMGy8y.mjs";
+import { t as openMcpSession } from "./mcp-client-DVWTex2i.mjs";
+import { defineCommand } from "citty";
+import { intro, log, outro } from "@clack/prompts";
+//#region src/commands/describe.ts
+/**
+* Read-only inspector for a single model, wrapping `contentrain_describe`.
+*
+* Useful for humans driving the CLI and for agents that want to sanity-
+* check a model's fields, stats, and import snippet without committing
+* anything. `--json` mirrors the MCP tool response verbatim.
+*/
+var describe_default = defineCommand({
+	meta: {
+		name: "describe",
+		description: "Show the schema, stats, and import snippet for a model"
+	},
+	args: {
+		model: {
+			type: "positional",
+			description: "Model ID (e.g. \"blog-post\", \"hero\")",
+			required: true
+		},
+		root: {
+			type: "string",
+			description: "Project root path",
+			required: false
+		},
+		sample: {
+			type: "boolean",
+			description: "Include one sample entry",
+			required: false
+		},
+		locale: {
+			type: "string",
+			description: "Locale for the sample entry",
+			required: false
+		},
+		json: {
+			type: "boolean",
+			description: "Emit raw JSON for scripts",
+			required: false
+		}
+	},
+	async run({ args }) {
+		const projectRoot = await resolveProjectRoot(args.root);
+		const modelId = String(args.model);
+		const session = await openMcpSession(projectRoot);
+		try {
+			const result = await session.call("contentrain_describe", {
+				model: modelId,
+				include_sample: Boolean(args.sample),
+				...args.locale ? { locale: String(args.locale) } : {}
+			});
+			if (args.json) {
+				process.stdout.write(JSON.stringify(result, null, 2));
+				return;
+			}
+			intro(pc.bold(`contentrain describe: ${modelId}`));
+			log.info(pc.bold("Metadata"));
+			log.message(`  Name:    ${String(result["name"] ?? "—")}`);
+			log.message(`  Kind:    ${pc.cyan(String(result["kind"] ?? "—"))}`);
+			log.message(`  Domain:  ${String(result["domain"] ?? "—")}`);
+			log.message(`  i18n:    ${result["i18n"] ? pc.green("yes") : pc.dim("no")}`);
+			if (result["description"]) log.message(`  About:   ${String(result["description"])}`);
+			const stats = result["stats"];
+			if (stats) {
+				log.info(pc.bold("\nStats"));
+				log.message(`  Total entries: ${stats.total_entries ?? 0}`);
+				if (stats.locales) for (const [loc, n] of Object.entries(stats.locales)) log.message(`    ${loc}: ${n}`);
+			}
+			const fields = result["fields"];
+			if (fields) {
+				log.info(pc.bold("\nFields"));
+				for (const [name, spec] of Object.entries(fields)) {
+					const s = spec;
+					const req = s.required ? pc.yellow(" *") : "";
+					log.message(`  ${pc.bold(name)}${req}  ${pc.dim(s.type ?? "")}`);
+				}
+			}
+			if (result["import_snippet"]) {
+				log.info(pc.bold("\nImport snippet"));
+				log.message(pc.dim(String(result["import_snippet"])));
+			}
+			const vocab = result["vocabulary_hint"];
+			if (vocab?.terms && Object.keys(vocab.terms).length > 0) {
+				log.info(pc.bold("\nVocabulary hint"));
+				if (vocab.note) log.message(pc.dim(`  ${vocab.note}`));
+				for (const term of Object.keys(vocab.terms)) log.message(`  • ${term}`);
+			}
+			if (result["sample"]) {
+				log.info(pc.bold("\nSample entry"));
+				log.message(pc.dim(JSON.stringify(result["sample"], null, 2)));
+			}
+			outro("");
+		} catch (error) {
+			log.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		} finally {
+			await session.close();
+		}
+	}
+});
+//#endregion
+export { describe_default as default };

package/dist/describe-format-CUAqB0C4.mjs

@@ -0,0 +1,50 @@
+import { i as pc } from "./ui-B8l_LC36.mjs";
+import { r as resolveProjectRoot } from "./context-OskMGy8y.mjs";
+import { t as openMcpSession } from "./mcp-client-DVWTex2i.mjs";
+import { defineCommand } from "citty";
+import { intro, log, outro } from "@clack/prompts";
+//#region src/commands/describe-format.ts
+/**
+* Dumps the Contentrain content-format specification (what
+* `contentrain_describe_format` returns). Mostly useful as a
+* copy/paste primer for humans pairing with an agent, or for a quick
+* `--json` handoff into another tool.
+*/
+var describe_format_default = defineCommand({
+	meta: {
+		name: "describe-format",
+		description: "Print the Contentrain content-format specification"
+	},
+	args: {
+		root: {
+			type: "string",
+			description: "Project root path",
+			required: false
+		},
+		json: {
+			type: "boolean",
+			description: "Emit raw JSON for scripts",
+			required: false
+		}
+	},
+	async run({ args }) {
+		const session = await openMcpSession(await resolveProjectRoot(args.root));
+		try {
+			const result = await session.call("contentrain_describe_format", {});
+			if (args.json) {
+				process.stdout.write(JSON.stringify(result, null, 2));
+				return;
+			}
+			intro(pc.bold("contentrain describe-format"));
+			log.message(pc.dim(JSON.stringify(result, null, 2)));
+			outro("");
+		} catch (error) {
+			log.error(error instanceof Error ? error.message : String(error));
+			process.exitCode = 1;
+		} finally {
+			await session.close();
+		}
+	}
+});
+//#endregion
+export { describe_format_default as default };

package/dist/{diff--halNUpG.mjs → diff-ov1j9bAb.mjs}

@@ -1,43 +1,78 @@
-import { r as resolveProjectRoot } from "./context-An3xrvcP.mjs";
-import { i as pc } from "./ui-B5mXontH.mjs";
+import { i as pc } from "./ui-B8l_LC36.mjs";
+import { r as resolveProjectRoot } from "./context-OskMGy8y.mjs";
 import { defineCommand } from "citty";
 import { confirm, intro, isCancel, log, outro, select } from "@clack/prompts";
 import { simpleGit } from "simple-git";
-import { readConfig } from "@contentrain/mcp/core/config";
 import { CONTENTRAIN_BRANCH } from "@contentrain/types";
-import { tmpdir } from "node:os";
-import { randomUUID } from "node:crypto";
-import { join } from "node:path";
+import { mergeBranch } from "@contentrain/mcp/git/transaction";
+import { branchDiff } from "@contentrain/mcp/git/branch-lifecycle";
 //#region src/commands/diff.ts
 var diff_default = defineCommand({
 	meta: {
 		name: "diff",
 		description: "Review pending contentrain branches"
 	},
-	args: { root: {
-		type: "string",
-		description: "Project root path",
-		required: false
-	} },
+	args: {
+		root: {
+			type: "string",
+			description: "Project root path",
+			required: false
+		},
+		json: {
+			type: "boolean",
+			description: "Emit pending-branches summary as JSON and exit (no interactive review)",
+			required: false
+		}
+	},
 	async run({ args }) {
 		const projectRoot = await resolveProjectRoot(args.root);
 		const git = simpleGit(projectRoot);
-		intro(pc.bold("contentrain diff"));
+		const useJson = Boolean(args.json);
+		if (!useJson) intro(pc.bold("contentrain diff"));
 		const featureBranches = (await git.branch(["--list", "cr/*"])).all.filter((b) => b !== CONTENTRAIN_BRANCH);
+		if (useJson) {
+			const payload = await Promise.all(featureBranches.map(async (branch) => {
+				try {
+					const diff = await branchDiff(projectRoot, { branch });
+					const insertions = (diff.patch.match(/^\+(?!\+\+)/gmu) ?? []).length;
+					const deletions = (diff.patch.match(/^-(?!--)/gmu) ?? []).length;
+					return {
+						name: branch,
+						base: diff.base,
+						filesChanged: diff.filesChanged,
+						insertions,
+						deletions,
+						stat: diff.stat
+					};
+				} catch (error) {
+					return {
+						name: branch,
+						base: CONTENTRAIN_BRANCH,
+						filesChanged: 0,
+						insertions: 0,
+						deletions: 0,
+						error: error instanceof Error ? error.message : String(error)
+					};
+				}
+			}));
+			process.stdout.write(JSON.stringify({ branches: payload }, null, 2));
+			return;
+		}
 		if (featureBranches.length === 0) {
 			log.message("No pending contentrain branches.");
 			outro("");
 			return;
 		}
 		log.info(pc.bold(`Pending branches (${featureBranches.length})`));
-		const baseBranch = (await readConfig(projectRoot))?.repository?.default_branch ?? ((await git.raw(["branch", "--show-current"])).trim() || "main");
 		const branchInfos = [];
 		for (const branch of featureBranches) try {
-			const diffStat = await git.diffSummary([`${baseBranch}...${branch}`]);
+			const diff = await branchDiff(projectRoot, { branch });
+			const insertions = (diff.patch.match(/^\+(?!\+\+)/gmu) ?? []).length;
+			const deletions = (diff.patch.match(/^-(?!--)/gmu) ?? []).length;
 			branchInfos.push({
 				name: branch,
-				summary: `${diffStat.changed} file(s), +${diffStat.insertions}/-${diffStat.deletions}`,
-				files: diffStat.changed
+				summary: `${diff.filesChanged} file(s), +${insertions}/-${deletions}`,
+				files: diff.filesChanged
 			});
 		} catch {
 			branchInfos.push({
@@ -63,12 +98,11 @@ var diff_default = defineCommand({
 		}
 		const selectedBranch = reviewChoice;
 		try {
-			const diff = await git.diff([`${baseBranch}...${selectedBranch}`, "--stat"]);
-			log.info(pc.bold(`\nDiff: ${selectedBranch}`));
-			log.message(diff);
-			const fullDiff = await git.diff([`${baseBranch}...${selectedBranch}`]);
-			if (fullDiff.length < 5e3) log.message(fullDiff);
-			else log.message(pc.dim(`(${Math.round(fullDiff.length / 1024)}KB diff — too large to display inline)`));
+			const detail = await branchDiff(projectRoot, { branch: selectedBranch });
+			log.info(pc.bold(`\nDiff: ${selectedBranch} (base: ${detail.base})`));
+			log.message(detail.stat);
+			if (detail.patch.length < 5e3) log.message(detail.patch);
+			else log.message(pc.dim(`(${Math.round(detail.patch.length / 1024)}KB diff — too large to display inline)`));
 		} catch (error) {
 			log.error(`Could not show diff: ${error instanceof Error ? error.message : String(error)}`);
 		}
@@ -77,7 +111,7 @@ var diff_default = defineCommand({
 			options: [
 				{
 					value: "merge",
-					label: `Merge into ${baseBranch}`
+					label: `Merge into ${CONTENTRAIN_BRANCH} + advance base`
 				},
 				{
 					value: "delete",
@@ -94,43 +128,17 @@ var diff_default = defineCommand({
 			return;
 		}
 		if (action === "merge") {
-			const confirmMerge = await confirm({ message: `Merge ${selectedBranch} into ${baseBranch}?` });
-			if (!isCancel(confirmMerge) && confirmMerge) {
-				const mergePath = join(tmpdir(), `cr-merge-${randomUUID()}`);
-				try {
-					if (!(await git.branchLocal()).all.includes(CONTENTRAIN_BRANCH)) await git.branch([CONTENTRAIN_BRANCH, baseBranch]);
-					await git.raw([
-						"worktree",
-						"add",
-						mergePath,
-						CONTENTRAIN_BRANCH
-					]);
-					const mergeGit = simpleGit(mergePath);
-					await mergeGit.merge([baseBranch, "--no-edit"]).catch(() => {});
-					await mergeGit.merge([selectedBranch, "--no-edit"]);
-					const tip = (await mergeGit.raw(["rev-parse", "HEAD"])).trim();
-					await git.raw([
-						"update-ref",
-						`refs/heads/${baseBranch}`,
-						tip
-					]);
-					if ((await git.raw(["branch", "--show-current"])).trim() === baseBranch) await git.checkout([
-						tip,
-						"--",
-						".contentrain/"
-					]);
-					await git.deleteLocalBranch(selectedBranch, true);
-					log.success(`Merged and deleted ${selectedBranch}`);
-				} catch (error) {
-					log.error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
-				} finally {
-					await git.raw([
-						"worktree",
-						"remove",
-						mergePath,
-						"--force"
-					]).catch(() => {});
+			const confirmMerge = await confirm({ message: `Merge ${selectedBranch} into ${CONTENTRAIN_BRANCH}?` });
+			if (!isCancel(confirmMerge) && confirmMerge) try {
+				const result = await mergeBranch(projectRoot, selectedBranch);
+				log.success(`Merged ${selectedBranch} (commit ${result.commit.slice(0, 8)})`);
+				if (result.sync?.skipped?.length) {
+					log.warning(`${result.sync.skipped.length} file(s) skipped during sync — you have uncommitted changes:`);
+					for (const f of result.sync.skipped) log.message(pc.dim(`    ${f}`));
+					log.message(pc.dim("  Review your working tree before running another merge."));
 				}
+			} catch (error) {
+				log.error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
 			}
 		} else if (action === "delete") {
 			const confirmDelete = await confirm({ message: `Delete ${selectedBranch}? This cannot be undone.` });