Contentrain · ABB65 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.changeset/cli-init-framework-wiring.md b/.changeset/cli-init-framework-wiring.md
@@ -0,0 +1,5 @@
+---
+"contentrain": patch
+---
+
+`contentrain init` now prints stack-aware SDK wiring guidance after setup: for bundler stacks (Nuxt/Next/Vite/etc.) it shows the `#contentrain` subpath import, points to the `contentrain-sdk` bundler-alias skill, and recommends a `prebuild`/`predev` generate step (because `.contentrain/client/` is git-ignored and must be regenerated on fresh clones / CI). Nuxt projects also get a server-only reminder.
diff --git a/.changeset/mcp-branch-lifecycle-context-validators.md b/.changeset/mcp-branch-lifecycle-context-validators.md
@@ -0,0 +1,29 @@
+---
+"@contentrain/mcp": minor
+"@contentrain/types": patch
+---
+
+Harden the git/branch lifecycle, redesign context.json handling, and fix validator false positives.
+
+**Git & branches**
+
+- Machine-generated `[contentrain]` commits now pass `--no-verify`, so repos with commitlint / husky / lefthook `commit-msg` hooks no longer reject Contentrain writes.
+- Feature branches are pruned automatically: a failed save no longer leaks a dangling `cr/*` branch, and merged branches (auto-merge or `contentrain_merge`) are deleted after landing.
+- Branch-health thresholds are now configurable via `config.json` — `branchWarnLimit` (default 50) and `branchBlockLimit` (default 80) — instead of being hardcoded.
+- **New tools:** `contentrain_branch_list` (pending `cr/*` branches + merge status) and `contentrain_branch_delete` (remove a stale/failed branch; the `contentrain` branch is protected).
+- `contentrain_merge` can now target a branch by `model` (+ optional `locale`/`latest`), not just the exact timestamped branch name.
+- `contentrain_submit` with no git remote now guides you to `contentrain_merge` (local landing) instead of failing with a bare "configure a remote".
+- Git/hook failures are returned as structured, ANSI-stripped errors (`{ error, stage, hook?, code?, agent_hint? }`) instead of a raw escaped color blob.
+
+**context.json**
+
+- `context.json` is no longer committed on feature branches; it is regenerated deterministically on the `contentrain` branch after merge (single-threaded). This removes the merge-conflict class that hit parallel content saves on different branches.
+- `contentrain_status` now derives `stats.models`/`stats.entries` live instead of echoing a possibly-stale `context.json`.
+
+**Validation**
+
+- Non-i18n models are validated against a single locale, eliminating phantom per-locale "orphan content" warnings (and the wrong-locale meta files `--fix` used to write) in multi-locale projects.
+- Polymorphic multi-relations (`relations` targeting multiple models) accept `{ model, ref }` items, matching the generated SDK type instead of being rejected as "must be a string".
+- Relation-integrity resolves targets at the target model's own storage locale (with a default-locale fallback for i18n:true targets), removing false "broken relation" errors.
+- `contentrain_content_save`'s inline validation now evaluates the committed/overlaid state, so freshly created locale files are no longer reported as "missing".
+- `contentrain_validate --fix` lands cosmetic structural fixes via auto-merge instead of spawning a pending review branch.
diff --git a/.changeset/query-document-sort-include-generator-fixes.md b/.changeset/query-document-sort-include-generator-fixes.md
@@ -0,0 +1,17 @@
+---
+"@contentrain/query": major
+---
+
+Fix generated client correctness and align with the platform.
+
+**Breaking:** the generated document body field is now `body` (was `content`), matching `@contentrain/types` `DocumentEntry.body` and the MCP `document_save` schema. Update consumers reading `.content` on document entries to `.body`, and regenerate the client.
+
+Also fixed in the generated runtime + types:
+
+- **Dictionary interpolation was broken** in generated output — the param regex lost its escaping during emit, so `dictionary('ui').get('key', { name })` returned the raw `{name}` template. Now interpolates correctly.
+- **`DocumentQuery.sort()` added** — documents can now be ordered (e.g. by `published_at`); previously only collections could sort, and calling `.sort()` on a document query threw.
+- **`include()` now resolves relations across i18n boundaries** — an i18n:false relation target (e.g. `author`) is resolved whether or not `.locale()` was set, and i18n:true targets resolve when no explicit locale is passed. Previously one side silently stayed an unresolved id string.
+- **Generated types corrected** — no more duplicate `slug` member when a document model declares a `slug` field; relation fields are typed as `id | ResolvedTarget` (and `include(...)` arguments are constrained to model keys) so resolved relations are no longer plain `string`.
+- **String frontmatter is no longer numerically coerced** — a string-typed field like `"007"` keeps its value instead of becoming `7`.
+- **`where(field, 'ne', x)` on array fields** is now the complement of `eq` (membership), matching `eq` semantics.
+- Removed dead/misleading CJS proxy code; documented the required `await init()` for CommonJS.
diff --git a/.changeset/rules-skills-branch-tools-docs.md b/.changeset/rules-skills-branch-tools-docs.md
@@ -0,0 +1,11 @@
+---
+"@contentrain/rules": minor
+"@contentrain/skills": minor
+---
+
+Document the new `contentrain_branch_list` / `contentrain_branch_delete` MCP tools and fix SDK wiring guidance.
+
+- `MCP_TOOLS` / the essential guardrails / the MCP tool reference now include the two new branch tools (19 tools total) and the model/locale/latest selector for `contentrain_merge`.
+- Bundler-config snippets for Vite and Nuxt use `import.meta.url` + `fileURLToPath` instead of `__dirname` (which is undefined in ESM `vite.config.ts` / `nuxt.config.ts`), and now cover Nuxt 4's `app/` + `server/` layout.
+- The generate skill documents wiring `contentrain generate` into a `prebuild`/`predev` step, since `.contentrain/client/` is git-ignored and must be regenerated on fresh clones / CI.
+- Clarified the two generator invocations: `contentrain generate` (CLI) vs `npx contentrain-query generate` (the `@contentrain/query` bin).
diff --git a/AGENTS.md b/AGENTS.md
@@ -48,15 +48,15 @@ Load `packages/rules/essential/contentrain-essentials.md` (~120 lines) for compa
 - Architecture (MCP = deterministic infra, Agent = intelligence)
 - Four model kinds (singleton, collection, document, dictionary)
 - Content format rules (JSON only, canonical serialization)
-- 17 MCP tools with mandatory calling protocols
+- 19 MCP tools with mandatory calling protocols
 - Git workflow (dedicated contentrain branch, worktree isolation)
 - Security boundaries
 
 ## Packages
 
 | Directory | npm | What it does |
 |-----------|-----|-------------|
-| `packages/mcp` | `@contentrain/mcp` | 17 MCP tools — content operations engine |
+| `packages/mcp` | `@contentrain/mcp` | 19 MCP tools — content operations engine |
 | `packages/cli` | `contentrain` | CLI + Serve UI + MCP stdio entrypoint |
 | `packages/sdk/js` | `@contentrain/query` | Generated TypeScript query SDK |
 | `packages/types` | `@contentrain/types` | Shared type definitions |

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -11,7 +11,7 @@ MIT-licensed monorepo for Contentrain's open-source packages: MCP tools, CLI, Ty
 ```
 contentrain-ai/
 ├── packages/
-│   ├── mcp/          — 17 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers (simple-git + zod + MCP SDK)
+│   ├── mcp/          — 19 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers (simple-git + zod + MCP SDK)
 │   ├── cli/          — citty + tsdown (init/serve/validate/normalize/connect)
 │   ├── types/        — Shared TypeScript types (@contentrain/types)
 │   ├── rules/        — AI agent quality rules & conventions
@@ -77,7 +77,7 @@ When working with Contentrain content operations (models, content, normalize, va
 - **Collection storage = object-map** — `{ entryId: { fields } }`, sorted by ID
 - **Canonical serialization** — deterministic JSON output, sorted keys, 2-space indent, trailing newline
 - **Dedicated contentrain branch** — content state SSOT, created at init, auto-synced with baseBranch via update-ref. Developer's working tree is never mutated during MCP operations
-- **context.json** — committed with content changes (not separately), Studio/IDE reads
+- **context.json** — NOT committed on feature branches; regenerated deterministically on the `contentrain` branch after merge (single-threaded), so parallel content saves never conflict on it. Studio/IDE reads it; `contentrain_status` derives live stats rather than trusting the file
 - **Workflow config** — `"auto-merge"` or `"review"` in config.json
 - **Agent-MCP split** — MCP = deterministic infra, Agent = intelligence. MCP does NOT make content decisions
 - **Normalize two phases** — Phase 1: Extraction (content-only), Phase 2: Reuse (source patching). Separate branches, separate reviews
@@ -90,7 +90,7 @@ When working with Contentrain content operations (models, content, normalize, va
 
 | Package | Name | Description |
 |---|---|---|
-| packages/mcp | @contentrain/mcp | 17 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers |
+| packages/mcp | @contentrain/mcp | 19 MCP tools, stdio + HTTP transports, Local / GitHub / GitLab providers |
 | packages/cli | contentrain | CLI (npx contentrain) |
 | packages/types | @contentrain/types | Shared TypeScript types |
 | packages/rules | @contentrain/rules | AI agent quality rules & conventions |

diff --git a/README.md b/README.md
@@ -94,7 +94,7 @@ This is the strongest entry point into the product:
 
 ```
 ┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
-│  AI Agent    │────▶│  MCP (17 tools)  │────▶│ .contentrain/│
+│  AI Agent    │────▶│  MCP (19 tools)  │────▶│ .contentrain/│
 │  (decides)   │     │  (enforces)      │     │ (stores)     │
 └─────────────┘     └──────────────────┘     └──────┬───────┘
                                                      │
@@ -145,7 +145,7 @@ Works with Nuxt, Next.js, Astro, SvelteKit, Vue, React, Node, Go, Python, Swift,
 
 - **Git-native** — every write goes through worktree isolation + review branches
 - **Normalize flow** — scan codebase for hardcoded strings → extract → create i18n-ready content → patch source files
-- **MCP engine** — 17 tools over stdio or HTTP transport, works with Claude Code, Cursor, Windsurf, or any MCP client
+- **MCP engine** — 19 tools over stdio or HTTP transport, works with Claude Code, Cursor, Windsurf, or any MCP client
 - **Provider-agnostic engine** — the same tool surface runs over a local worktree, GitHub, or GitLab (self-hosted included) with zero tool-code changes. HTTP transport available for remote drivers such as Studio.
 - **Canonical serialization** — sorted keys, deterministic output, clean git diffs, conflict-free parallel edits
 - **Agent rules & skills** — behavioral policies and step-by-step workflows ship as npm packages
@@ -176,7 +176,7 @@ See [`AGENTS.md`](AGENTS.md) for the full skill catalog and agent guidance.
 
 | Package | npm | Role |
 |---|---|---|
-| [`@contentrain/mcp`](packages/mcp) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Fmcp)](https://www.npmjs.com/package/@contentrain/mcp) | 17 MCP tools + stdio / HTTP transport + Local / GitHub / GitLab providers |
+| [`@contentrain/mcp`](packages/mcp) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Fmcp)](https://www.npmjs.com/package/@contentrain/mcp) | 19 MCP tools + stdio / HTTP transport + Local / GitHub / GitLab providers |
 | [`contentrain`](packages/cli) | [![npm](https://img.shields.io/npm/v/contentrain)](https://www.npmjs.com/package/contentrain) | CLI + Serve UI + MCP stdio entrypoint |
 | [`@contentrain/query`](packages/sdk/js) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Fquery)](https://www.npmjs.com/package/@contentrain/query) | Generated TypeScript query SDK |
 | [`@contentrain/types`](packages/types) | [![npm](https://img.shields.io/npm/v/%40contentrain%2Ftypes)](https://www.npmjs.com/package/@contentrain/types) | Shared type definitions + constants |

diff --git a/docs/concepts.md b/docs/concepts.md
@@ -43,7 +43,7 @@ Contentrain AI inverts the traditional CMS workflow:
 
 ### 1. MCP (Infrastructure)
 
-17 tools that AI agents call to manage content:
+19 tools that AI agents call to manage content:
 
 - **Read:** `contentrain_status`, `contentrain_describe`, `contentrain_describe_format`, `contentrain_doctor`, `contentrain_content_list`
 - **Project setup:** `contentrain_init`, `contentrain_scaffold`

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -215,7 +215,7 @@ All packages are published on npm:
 | Package | Description | Install |
 |---|---|---|
 | [`contentrain`](https://www.npmjs.com/package/contentrain) | CLI (init, serve, generate, validate) | `npx contentrain init` |
-| [`@contentrain/mcp`](https://www.npmjs.com/package/@contentrain/mcp) | 17 MCP tools for AI agents | `pnpm add @contentrain/mcp` |
+| [`@contentrain/mcp`](https://www.npmjs.com/package/@contentrain/mcp) | 19 MCP tools for AI agents | `pnpm add @contentrain/mcp` |
 | [`@contentrain/query`](https://www.npmjs.com/package/@contentrain/query) | TypeScript query SDK (optional) | `pnpm add @contentrain/query` |
 | [`@contentrain/types`](https://www.npmjs.com/package/@contentrain/types) | Shared TypeScript types | `pnpm add @contentrain/types` |
 | [`@contentrain/rules`](https://www.npmjs.com/package/@contentrain/rules) | AI agent quality rules | `pnpm add @contentrain/rules` |
@@ -253,7 +253,7 @@ Want to skip setup? Start from a production-ready template with content models,
 
 - [Core Concepts](/concepts) — Models, content kinds, domains, and the governance architecture
 - [Ecosystem Map](/ecosystem) — How AI packages and Studio fit together
-- [MCP Tools](/packages/mcp) — All 17 tools available to your agent
+- [MCP Tools](/packages/mcp) — All 19 tools available to your agent
 - [Normalize Flow](/guides/normalize) — Extract hardcoded strings from existing code
 - [i18n Workflow](/guides/i18n) — Add languages to your content
 - [Framework Integration](/guides/frameworks) — Platform-specific setup patterns

diff --git a/docs/guides/embedding-mcp.md b/docs/guides/embedding-mcp.md
@@ -332,7 +332,7 @@ A GitHub Actions job:
 4. Drive it with an MCP client
 5. Let `contentrain_submit` push the `cr/*` branch
 
-All 17 tools are available because the runner has `LocalProvider`.
+All 19 tools are available because the runner has `LocalProvider`.
 
 ### Scripted automation
 

diff --git a/docs/guides/http-transport.md b/docs/guides/http-transport.md
@@ -14,7 +14,7 @@ Typical drivers:
 - **CI runners** — deterministic content operations as part of a pipeline (scaffold, validate, submit).
 - **Remote agents** — any MCP client that wants to operate a Contentrain project without a local checkout.
 
-All three tunnel the same 17 tools through the same `RepoProvider` contract. Which backend answers depends on how the server is wired — see [Providers & Transports](/guides/providers) for the capability matrix.
+All three tunnel the same 19 tools through the same `RepoProvider` contract. Which backend answers depends on how the server is wired — see [Providers & Transports](/guides/providers) for the capability matrix.
 
 ## Starting the HTTP server
 

diff --git a/docs/guides/providers.md b/docs/guides/providers.md
@@ -6,7 +6,7 @@ slug: providers
 
 # Providers & Transports
 
-Contentrain MCP runs the same 17 tools over three backends:
+Contentrain MCP runs the same 19 tools over three backends:
 
 - **LocalProvider** — simple-git + a temporary worktree on your disk. Default for `npx contentrain serve --stdio` and the HTTP transport when driven by the CLI.
 - **GitHubProvider** — Octokit over the GitHub Git Data + Repos APIs. No clone, no worktree.

diff --git a/docs/packages/cli.md b/docs/packages/cli.md
@@ -277,7 +277,7 @@ Serves REST endpoints (`/api/status`, `/api/content`, `/api/branches`, `/api/doc
 contentrain serve --stdio
 ```
 
-For IDE agents. Same 17 tools, stdio transport.
+For IDE agents. Same 19 tools, stdio transport.
 
 #### MCP HTTP
 

diff --git a/docs/packages/mcp.md b/docs/packages/mcp.md
@@ -43,7 +43,7 @@ Optional parser support for higher-quality source scanning:
 
 ## Tool Catalog
 
-The MCP server exposes **17 tools** organized by function. Each tool includes [MCP annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can distinguish safe reads from writes and destructive operations.
+The MCP server exposes **19 tools** organized by function. Each tool includes [MCP annotations](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so clients can distinguish safe reads from writes and destructive operations.
 
 | Tool | Title | Read-only | Destructive |
 |------|-------|-----------|-------------|
@@ -61,6 +61,8 @@ The MCP server exposes **17 tools** organized by function. Each tool includes [M
 | `contentrain_validate` | Validate Project | — | — |
 | `contentrain_submit` | Submit Branches | — | — |
 | `contentrain_merge` | Merge Branch | — | — |
+| `contentrain_branch_list` | List Branches | Yes | — |
+| `contentrain_branch_delete` | Delete Branch | — | **Yes** |
 | `contentrain_scan` | Scan Source Code | Yes | — |
 | `contentrain_apply` | Apply Normalize | — | — |
 | `contentrain_bulk` | Bulk Operations | — | — |
@@ -89,7 +91,9 @@ The MCP server exposes **17 tools** organized by function. Each tool includes [M
 | `contentrain_content_delete` | Remove content | Delete specific content entries |
 | `contentrain_validate` | Check & fix | Validate content against schemas, optionally auto-fix structural issues |
 | `contentrain_submit` | Push branches | Push `cr/*` review branches to remote |
-| `contentrain_merge` | Merge branches | Merge a review-mode branch into contentrain locally (no external platform needed) |
+| `contentrain_merge` | Merge branches | Merge a review-mode branch into contentrain locally (by exact branch or model; no external platform needed) |
+| `contentrain_branch_list` | Inspect branches | List pending `cr/*` branches with merge status and branch-health pressure |
+| `contentrain_branch_delete` | Clean up branches | Delete a stale/failed `cr/*` branch (the contentrain branch is protected) |
 
 ### Normalize Tools (Scan + Apply)
 
@@ -163,7 +167,7 @@ Agent drivers treat `capability_required` as a retry signal. See [Providers & Tr
 - **stdio** — `contentrain serve --stdio` or `npx contentrain-mcp`. IDE agents (Claude Code, Cursor, Windsurf) connect over stdin/stdout.
 - **HTTP** — `contentrain serve --mcpHttp --authToken $TOKEN` or the programmatic `startHttpMcpServer({...})` / `startHttpMcpServerWith({ provider })` exports. Streamable HTTP at `POST /mcp` with secure-by-default Bearer auth. See the [HTTP Transport guide](/guides/http-transport).
 
-Both transports serve the same 17 tools and the same JSON response shapes.
+Both transports serve the same 19 tools and the same JSON response shapes.
 
 ## Providers
 
@@ -291,7 +295,7 @@ This auto-creates the correct MCP config file and installs AI rules/skills.
 
 </details>
 
-Once connected, the agent has access to all 17 MCP tools and can manage your content through natural language.
+Once connected, the agent has access to all 19 MCP tools and can manage your content through natural language.
 
 ## Trust Model