@contentrain/rules 0.3.3 → 0.5.0

package/README.md

@@ -10,15 +10,16 @@ Shared AI-agent rules for Contentrain.
 Start here:
 
 - [2-minute product demo](https://ai.contentrain.io/demo)
-- [Rules & skills docs](https://ai.contentrain.io/packages/rules)
+- [Rules & skills docs](https://ai.contentrain.io/packages/rules)
 
-This package is the policy layer of the Contentrain ecosystem. It defines how agents should behave when they work with:
+This package is the **policy layer** of the Contentrain ecosystem. It defines how agents should behave when they work with:
 
-- Contentrain MCP tools
+- Contentrain MCP tools (17 operations)
 - schema and model design
-- content quality
-- normalize workflows
+- content quality (SEO, accessibility, media, i18n)
+- normalize workflows (extraction + reuse)
 - git-backed review flows
+- security guardrails
 
 If `@contentrain/mcp` is the deterministic execution layer, `@contentrain/rules` is the behavioral contract.
 
@@ -32,71 +33,100 @@ pnpm add @contentrain/rules
 
 ### Essential guardrails
 
-Published under `essential/*`:
+Published under `essential/`:
 
-- `contentrain-essentials.md` — compact, always-loaded rules (~86 lines) covering architecture, model kinds, MCP tools, mandatory protocols, and security basics
+- `contentrain-essentials.md` — compact, always-loaded rules covering architecture, model kinds, MCP tools, mandatory protocols, git workflow, and security basics.
+
+### Shared quality rules
+
+Published under `shared/` — detailed standards per domain:
+
+- `content-quality.md` — structure, required fields, content completeness
+- `seo-rules.md` — meta optimization, keywords, canonical URLs
+- `accessibility-rules.md` — alt text, ARIA labels, color contrast
+- `media-rules.md` — image optimization, responsive sizing, asset naming
+- `schema-rules.md` — model design, field types, relations, inheritance
+- `i18n-quality.md` — translation completeness, locale parity
+- `security-rules.md` — sensitive data patterns, secret detection, XSS prevention
+- `mcp-usage.md` — tool invocation patterns, git workflows, trust levels
+- `normalize-rules.md` — extraction and reuse constraints, scope safety
+- `workflow-rules.md` — review mode, approval flows, branch lifecycle
+- `content-conventions.md` — naming, slug generation, status conventions
 
 ### Prompt layers
 
-Published under `prompts/*`:
+Published under `prompts/` — mode-specific context the agent loads per task:
 
-- `common.md`
-- `generate-mode.md`
-- `normalize-mode.md`
-- `review-mode.md`
+- `common.md` — shared preamble for all agent modes
+- `generate-mode.md` — content creation constraints
+- `normalize-mode.md` — string extraction and patching workflows
+- `review-mode.md` — content validation and change review
 
 ### Context bridge
 
-Published under `context/*`:
+Published under `context/`:
 
-- `context-bridge.md`
+- `context-bridge.md` — how to integrate rules into agent context systems
+- `templates/` — framework-specific context JSON for `nuxt`, `next`, `astro`, `sveltekit`
 
 ## Public Exports
 
-The package root exports constants that can be used by tooling:
+The package root exports constants for tooling:
 
 - `FIELD_TYPES` — 27 flat field types
-- `MODEL_KINDS` — singleton, collection, document, dictionary
-- `MCP_TOOLS` — 15 MCP tool names
+- `MODEL_KINDS` — `singleton`, `collection`, `document`, `dictionary`
+- `MCP_TOOLS` — 17 MCP tool names (includes `contentrain_merge` and `contentrain_doctor`)
 - `ESSENTIAL_RULES_FILE` — path to essential guardrails markdown
 - `STACKS` — supported framework stacks
 
-## Example
+## Quick Example
 
 ```ts
 import { MCP_TOOLS, ESSENTIAL_RULES_FILE, FIELD_TYPES } from '@contentrain/rules'
 
-console.log(MCP_TOOLS.includes('contentrain_validate'))
-console.log(ESSENTIAL_RULES_FILE) // 'essential/contentrain-essentials.md'
-console.log(FIELD_TYPES.length)   // 27
+console.log(MCP_TOOLS.length)                            // 17
+console.log(MCP_TOOLS.includes('contentrain_merge'))     // true
+console.log(MCP_TOOLS.includes('contentrain_doctor'))    // true
+console.log(ESSENTIAL_RULES_FILE)                        // 'essential/contentrain-essentials.md'
+console.log(FIELD_TYPES.length)                          // 27
 ```
 
 ## Design Role
 
 `@contentrain/rules` exists to keep agent behavior aligned across tools and environments.
 
-It should answer questions like:
+Typical questions it answers:
+
+- What is acceptable content quality? (shared quality rules)
+- How should an agent use MCP tools safely? (mcp-usage + tool reference)
+- What is the normalize contract? (normalize-rules)
+- What workflow and review constraints exist? (workflow-rules)
+
+Detailed procedures and step-by-step guides live in `@contentrain/skills` (Agent Skills standard format).
+
+## Parity with `@contentrain/mcp`
+
+`@contentrain/rules` is kept in lockstep with the MCP tool registry via cross-package parity tests. When a new MCP tool is registered in `@contentrain/mcp`:
 
-- What is acceptable content quality?
-- How should an agent use MCP tools?
-- What is the normalize contract?
-- What workflow and review constraints exist?
+- `MCP_TOOLS` must include it (otherwise `tests/mcp-parity.test.ts` fails)
+- the essentials document must mention it
+- the skills reference must have a `### <tool>` section
 
-Detailed reference material and step-by-step procedures live in `@contentrain/skills` (Agent Skills standard format).
+When MCP's branch-naming convention changes (e.g. `contentrain/*` → `cr/*`), the rules prose must follow — the parity test scans the rules for the legacy prefix and fails if it reappears.
 
 ## Relationship To Other Packages
 
 - `@contentrain/mcp` enforces file, validation, and git behavior
 - `@contentrain/skills` provides Agent Skills with progressive disclosure (SKILL.md + references/)
-- `contentrain` exposes CLI and serve UX
+- `contentrain` (CLI) installs rules + skills into the IDE during `contentrain init`
 - `@contentrain/query` is the generated runtime consumption layer
 
 Rule of thumb:
 
-- `rules` = essential guardrails (always loaded, ~86 lines)
-- `skills` = detailed procedures and reference docs (on-demand)
+- `rules` = policy layer (quality standards, constraints, essentials)
+- `skills` = procedural layer (workflows, detailed reference docs)
 
-See [`AGENTS.md`](../../AGENTS.md) at the repo root for agent-level project guidance.
+See [`AGENTS.md`](../../AGENTS.md) at the repo root for project-level agent guidance.
 
 ## Build
 

package/dist/index.cjs

@@ -55,7 +55,11 @@ const MCP_TOOLS = [
 	"contentrain_apply",
 	"contentrain_validate",
 	"contentrain_submit",
-	"contentrain_bulk"
+	"contentrain_merge",
+	"contentrain_branch_list",
+	"contentrain_branch_delete",
+	"contentrain_bulk",
+	"contentrain_doctor"
 ];
 const ESSENTIAL_RULES_FILE = "essential/contentrain-essentials.md";
 const STACKS = [

package/dist/index.d.cts

@@ -8,7 +8,7 @@ declare const FIELD_TYPES: readonly ["string", "text", "email", "url", "slug", "
 type FieldType = (typeof FIELD_TYPES)[number];
 declare const MODEL_KINDS: readonly ["singleton", "collection", "document", "dictionary"];
 type ModelKind = (typeof MODEL_KINDS)[number];
-declare const MCP_TOOLS: readonly ["contentrain_status", "contentrain_describe", "contentrain_describe_format", "contentrain_init", "contentrain_scaffold", "contentrain_model_save", "contentrain_model_delete", "contentrain_content_save", "contentrain_content_delete", "contentrain_content_list", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_bulk"];
+declare const MCP_TOOLS: readonly ["contentrain_status", "contentrain_describe", "contentrain_describe_format", "contentrain_init", "contentrain_scaffold", "contentrain_model_save", "contentrain_model_delete", "contentrain_content_save", "contentrain_content_delete", "contentrain_content_list", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_merge", "contentrain_branch_list", "contentrain_branch_delete", "contentrain_bulk", "contentrain_doctor"];
 type McpTool = (typeof MCP_TOOLS)[number];
 declare const ESSENTIAL_RULES_FILE: "essential/contentrain-essentials.md";
 declare const STACKS: readonly ["nuxt", "next", "astro", "sveltekit", "react", "node"];

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAUD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAaD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.d.mts

@@ -8,7 +8,7 @@ declare const FIELD_TYPES: readonly ["string", "text", "email", "url", "slug", "
 type FieldType = (typeof FIELD_TYPES)[number];
 declare const MODEL_KINDS: readonly ["singleton", "collection", "document", "dictionary"];
 type ModelKind = (typeof MODEL_KINDS)[number];
-declare const MCP_TOOLS: readonly ["contentrain_status", "contentrain_describe", "contentrain_describe_format", "contentrain_init", "contentrain_scaffold", "contentrain_model_save", "contentrain_model_delete", "contentrain_content_save", "contentrain_content_delete", "contentrain_content_list", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_bulk"];
+declare const MCP_TOOLS: readonly ["contentrain_status", "contentrain_describe", "contentrain_describe_format", "contentrain_init", "contentrain_scaffold", "contentrain_model_save", "contentrain_model_delete", "contentrain_content_save", "contentrain_content_delete", "contentrain_content_list", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_merge", "contentrain_branch_list", "contentrain_branch_delete", "contentrain_bulk", "contentrain_doctor"];
 type McpTool = (typeof MCP_TOOLS)[number];
 declare const ESSENTIAL_RULES_FILE: "essential/contentrain-essentials.md";
 declare const STACKS: readonly ["nuxt", "next", "astro", "sveltekit", "react", "node"];

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAUD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AAQA;;;;cAAa,WAAA;AAAA,KAUD,SAAA,WAAoB,WAAA;AAAA,cAInB,WAAA;AAAA,KACD,SAAA,WAAoB,WAAA;AAAA,cAInB,SAAA;AAAA,KAaD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.mjs

@@ -54,7 +54,11 @@ const MCP_TOOLS = [
 	"contentrain_apply",
 	"contentrain_validate",
 	"contentrain_submit",
-	"contentrain_bulk"
+	"contentrain_merge",
+	"contentrain_branch_list",
+	"contentrain_branch_delete",
+	"contentrain_bulk",
+	"contentrain_doctor"
 ];
 const ESSENTIAL_RULES_FILE = "essential/contentrain-essentials.md";
 const STACKS = [

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/rules — AI agent rules for Contentrain\n *\n * Quality standards, architecture conventions, and IDE integration.\n */\n\n// ─── Field Types (27 flat types) ───\n\nexport const FIELD_TYPES = [\n  'string', 'text', 'email', 'url', 'slug', 'color', 'phone', 'code', 'icon',\n  'markdown', 'richtext',\n  'number', 'integer', 'decimal', 'percent', 'rating',\n  'boolean', 'date', 'datetime',\n  'image', 'video', 'file',\n  'relation', 'relations',\n  'select', 'array', 'object',\n] as const\n\nexport type FieldType = (typeof FIELD_TYPES)[number]\n\n// ─── Model Kinds ───\n\nexport const MODEL_KINDS = ['singleton', 'collection', 'document', 'dictionary'] as const\nexport type ModelKind = (typeof MODEL_KINDS)[number]\n\n// ─── MCP Tools (15 tools) ───\n\nexport const MCP_TOOLS = [\n  'contentrain_status', 'contentrain_describe', 'contentrain_describe_format',\n  'contentrain_init', 'contentrain_scaffold',\n  'contentrain_model_save', 'contentrain_model_delete',\n  'contentrain_content_save', 'contentrain_content_delete', 'contentrain_content_list',\n  'contentrain_scan', 'contentrain_apply',\n  'contentrain_validate', 'contentrain_submit',\n  'contentrain_bulk',\n] as const\n\nexport type McpTool = (typeof MCP_TOOLS)[number]\n\n// ─── Essential Rules ───\n\nexport const ESSENTIAL_RULES_FILE = 'essential/contentrain-essentials.md' as const\n\n// ─── Stacks ───\n\nexport const STACKS = ['nuxt', 'next', 'astro', 'sveltekit', 'react', 'node'] as const\nexport type Stack = (typeof STACKS)[number]\n"],"mappings":";;;;;;AAQA,MAAa,cAAc;CACzB;CAAU;CAAQ;CAAS;CAAO;CAAQ;CAAS;CAAS;CAAQ;CACpE;CAAY;CACZ;CAAU;CAAW;CAAW;CAAW;CAC3C;CAAW;CAAQ;CACnB;CAAS;CAAS;CAClB;CAAY;CACZ;CAAU;CAAS;CACpB;AAMD,MAAa,cAAc;CAAC;CAAa;CAAc;CAAY;CAAa;AAKhF,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;CAAoB;CACpB;CAAwB;CACxB;CACD;AAMD,MAAa,uBAAuB;AAIpC,MAAa,SAAS;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAS;CAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/rules — AI agent rules for Contentrain\n *\n * Quality standards, architecture conventions, and IDE integration.\n */\n\n// ─── Field Types (27 flat types) ───\n\nexport const FIELD_TYPES = [\n  'string', 'text', 'email', 'url', 'slug', 'color', 'phone', 'code', 'icon',\n  'markdown', 'richtext',\n  'number', 'integer', 'decimal', 'percent', 'rating',\n  'boolean', 'date', 'datetime',\n  'image', 'video', 'file',\n  'relation', 'relations',\n  'select', 'array', 'object',\n] as const\n\nexport type FieldType = (typeof FIELD_TYPES)[number]\n\n// ─── Model Kinds ───\n\nexport const MODEL_KINDS = ['singleton', 'collection', 'document', 'dictionary'] as const\nexport type ModelKind = (typeof MODEL_KINDS)[number]\n\n// ─── MCP Tools (19 tools) ───\n\nexport const MCP_TOOLS = [\n  'contentrain_status', 'contentrain_describe', 'contentrain_describe_format',\n  'contentrain_init', 'contentrain_scaffold',\n  'contentrain_model_save', 'contentrain_model_delete',\n  'contentrain_content_save', 'contentrain_content_delete', 'contentrain_content_list',\n  'contentrain_scan', 'contentrain_apply',\n  'contentrain_validate', 'contentrain_submit',\n  'contentrain_merge',\n  'contentrain_branch_list', 'contentrain_branch_delete',\n  'contentrain_bulk',\n  'contentrain_doctor',\n] as const\n\nexport type McpTool = (typeof MCP_TOOLS)[number]\n\n// ─── Essential Rules ───\n\nexport const ESSENTIAL_RULES_FILE = 'essential/contentrain-essentials.md' as const\n\n// ─── Stacks ───\n\nexport const STACKS = ['nuxt', 'next', 'astro', 'sveltekit', 'react', 'node'] as const\nexport type Stack = (typeof STACKS)[number]\n"],"mappings":";;;;;;AAQA,MAAa,cAAc;CACzB;CAAU;CAAQ;CAAS;CAAO;CAAQ;CAAS;CAAS;CAAQ;CACpE;CAAY;CACZ;CAAU;CAAW;CAAW;CAAW;CAC3C;CAAW;CAAQ;CACnB;CAAS;CAAS;CAClB;CAAY;CACZ;CAAU;CAAS;CACpB;AAMD,MAAa,cAAc;CAAC;CAAa;CAAc;CAAY;CAAa;AAKhF,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;CAAoB;CACpB;CAAwB;CACxB;CACA;CAA2B;CAC3B;CACA;CACD;AAMD,MAAa,uBAAuB;AAIpC,MAAa,SAAS;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAS;CAAO"}

package/essential/contentrain-essentials.md

@@ -52,8 +52,11 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 | `contentrain_apply` | Apply normalize (extract/reuse) |
 | `contentrain_validate` | Validate content against schemas |
 | `contentrain_submit` | Push branches to remote |
-| `contentrain_merge` | Merge a review-mode branch into contentrain locally |
+| `contentrain_merge` | Merge a review-mode branch into contentrain locally (by exact branch or model) |
+| `contentrain_branch_list` | List pending `cr/*` branches + merge status |
+| `contentrain_branch_delete` | Delete a stale/failed `cr/*` branch (the contentrain branch is protected) |
 | `contentrain_bulk` | Batch operations (copy_locale/update_status/delete_entries) |
+| `contentrain_doctor` | Project health report (env + structure + orphan content + branch pressure + SDK freshness) |
 
 ## Mandatory Protocols
 
@@ -68,7 +71,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 
 - A dedicated `contentrain` branch is the single source of truth for content state, created at init
 - Every write operation creates a temporary worktree on the `contentrain` branch automatically
-- Feature branches (`contentrain/{operation}/{model}/{locale}/{timestamp}`) are created from `contentrain` for each operation
+- Feature branches (`cr/{operation}/{model}/{locale}/{timestamp}`) are created from `contentrain` for each operation
 - **auto-merge** mode: feature branch merges into `contentrain`, then `contentrain` advances baseBranch via update-ref (fast-forward), then `.contentrain/` files are selectively synced to the developer's working tree
 - **review** mode: feature branch pushed to remote for team review
 - Developer's working tree is never mutated during MCP git operations (no stash, no checkout, no merge on the developer's tree)
@@ -76,7 +79,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 - The `contentrain` branch is protected from deletion
 - context.json is committed together with content changes, not as a separate commit
 - Never create branches manually, never commit directly to main or the `contentrain` branch
-- 50+ active branches = warning, 80+ = blocked
+- 50+ active `cr/*` branches = warning, 80+ = blocked
 
 ## CLI Serve — Review & Approval
 
@@ -111,6 +114,13 @@ This regenerates `.contentrain/client/` — required for `#contentrain` imports
 - Collection entry IDs and dictionary keys must match across all locales
 - IDs and slugs are locale-agnostic — same reference works everywhere
 
+## Content Governance
+
+- **No duplicate values** — before creating a dictionary key, check if the value already exists under another key (MCP warns automatically via advisories)
+- **Vocabulary first** — check `.contentrain/vocabulary.json` for canonical terms before creating content. Use approved terms exactly, do not invent synonyms
+- **Run validation** — after bulk content operations, call `contentrain_validate` to catch duplicate values, missing translations, and schema issues
+- **Periodic health check** — run `contentrain doctor --usage` to detect unused keys, duplicate values, and locale coverage gaps
+
 ## Security
 
 - No `<script>`, `javascript:`, or event handlers in richtext/markdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/rules",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "AI agent rules for Contentrain — quality standards, architecture conventions, IDE integration",
   "type": "module",
@@ -54,7 +54,8 @@
     "@types/node": "^22.0.0",
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "@contentrain/mcp": "1.5.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

package/prompts/normalize-mode.md

@@ -12,7 +12,7 @@ This mode converts a codebase with hardcoded strings into a Contentrain-managed
 |--------|---------------------|----------------|
 | Purpose | Pull content from source code into `.contentrain/` | Patch source files to reference extracted content |
 | Source files modified | No | Yes |
-| Branch pattern | `contentrain/normalize/extract/{domain}/{timestamp}` | `contentrain/normalize/reuse/{model}/{locale}/{timestamp}` |
+| Branch pattern | `cr/normalize/extract/{domain}/{timestamp}` | `cr/normalize/reuse/{model}/{locale}/{timestamp}` |
 | Prerequisite | Initialized `.contentrain/` | Completed extraction (content exists) |
 | Workflow mode | Always `review` | Always `review` |
 | Standalone value | Yes — content is manageable in Studio immediately | Depends on Phase 1 |

package/prompts/review-mode.md

@@ -2,14 +2,14 @@
 
 > **Prerequisites:** Read `prompts/common.md` first. All shared rules apply.
 
-This mode is for reviewing content changes on pending `contentrain/*` branches before they are merged. You act as a content quality reviewer, applying all Contentrain rules systematically.
+This mode is for reviewing content changes on pending `cr/*` branches before they are merged. You act as a content quality reviewer, applying all Contentrain rules systematically.
 
 ---
 
 ## Pipeline
 
 ```
-Step 1: List open contentrain/* branches
+Step 1: List open cr/* branches
 Step 2: Show diffs for selected branch
 Step 3: Apply review checklist
 Step 4: Recommend action
@@ -19,19 +19,19 @@ Step 4: Recommend action
 
 ## Step 1: List Pending Branches
 
-Call `contentrain_status` to see pending changes and open branches. Identify branches with the `contentrain/` prefix that are awaiting review.
+Call `contentrain_status` to see pending changes and open branches. Identify branches with the `cr/` prefix that are awaiting review.
 
 Branch naming convention:
 ```
-contentrain/{operation}/{model}/{locale}/{timestamp}
+cr/{operation}/{model}/{locale}/{timestamp}
 ```
 
 Common branch types:
-- `contentrain/content/...` — content updates
-- `contentrain/model/...` — model changes
-- `contentrain/normalize/extract/...` — normalize extraction
-- `contentrain/normalize/reuse/...` — normalize reuse (source patching)
-- `contentrain/new/scaffold-...` — scaffold operations
+- `cr/content/...` — content updates
+- `cr/model/...` — model changes
+- `cr/normalize/extract/...` — normalize extraction
+- `cr/normalize/reuse/...` — normalize reuse (source patching)
+- `cr/new/scaffold-...` — scaffold operations
 
 ---
 

package/shared/mcp-usage.md

@@ -156,7 +156,8 @@ Each entry in the `entries` array has this shape:
 | Tool | Purpose | Parameters |
 |------|---------|------------|
 | `contentrain_validate` | Validate project content against model schemas | `model?`, `fix?` (bool) |
-| `contentrain_submit` | Push contentrain/* branches to remote | `branches?` (string[]), `message?` |
+| `contentrain_submit` | Push `cr/*` branches to the remote | `branches?` (string[]), `message?` |
+| `contentrain_merge` | Merge a review-mode branch into `contentrain` and fast-forward the base | `branch`, `confirm: true` |
 
 ### 2.7 Bulk Tools
 
@@ -184,9 +185,15 @@ Each entry in the `entries` array has this shape:
 
 #### contentrain_submit parameters
 
-- `branches`: specific branch names to push (omit for all contentrain/* branches).
+- `branches`: specific branch names to push (omit for all `cr/*` branches).
 - `message`: optional message for the push operation.
 
+#### contentrain_merge parameters
+
+- `branch`: feature branch to merge (e.g. `cr/content/blog/...`).
+- `confirm`: must be `true` to execute.
+- Local-only: MCP runs the merge through a worktree + `update-ref` + selective sync. Use it when the workflow is `review` and the change has been approved.
+
 ---
 
 ## 3. Calling Sequences (Pipelines)
@@ -287,7 +294,7 @@ contentrain_apply(mode: "reuse", scope: {model: "model-id"}, dry_run: true) (pre
 
 - A dedicated `contentrain` branch is the single source of truth for content state, created at init and protected from deletion.
 - Every write operation creates a temporary worktree on a new feature branch forked from `contentrain`.
-- Branch naming: `contentrain/{operation}/{model}/{timestamp}` (locale included when applicable).
+- Branch naming: `cr/{operation}/{model}[/{locale}]/{timestamp}-{suffix}` (locale included when applicable; legacy `contentrain/*` branches are auto-migrated on first init).
 - You do not create branches manually. MCP handles Git transactions.
 - Developer's working tree is never mutated during MCP operations (no stash, no checkout, no merge on the developer's tree).
 - context.json is committed together with content changes, not as a separate commit.
@@ -297,9 +304,35 @@ contentrain_apply(mode: "reuse", scope: {model: "model-id"}, dry_run: true) (pre
 ### 4.7 Branch Health
 
 - MCP enforces branch health limits: 50+ active branches triggers a warning, 80+ blocks new write operations.
-- If blocked, merge or delete old `contentrain/*` branches before proceeding.
+- If blocked, merge or delete old `cr/*` branches before proceeding.
 - `contentrain_status` reports branch health automatically.
 
+### 4.8 Transport and Provider Capabilities
+
+MCP runs over three transports / provider combinations: **LocalProvider** (stdio or HTTP), **GitHubProvider** (HTTP only), and **GitLabProvider** (HTTP only). Each provider advertises a capability set that gates which tools are available.
+
+| Capability | Local | GitHub | GitLab | Tools affected |
+|---|---|---|---|---|
+| `localWorktree` | ✓ | — | — | `init`, `scaffold`, `validate --fix`, `submit`, `merge`, `bulk` |
+| `sourceRead` | ✓ | — | — | `apply` (extract mode) |
+| `sourceWrite` | ✓ | — | — | `apply` (reuse mode) |
+| `astScan` | ✓ | — | — | `scan` |
+| `pushRemote` | ✓ | ✓ | ✓ | `submit` |
+| `branchProtection` | — | ✓ | ✓ | merge fallback detection |
+| `pullRequestFallback` | — | ✓ | ✓ | merge fallback creation |
+
+When a tool is called on a provider that lacks the required capability, MCP returns a uniform error:
+
+```json
+{
+  "error": "contentrain_scan requires local filesystem access.",
+  "capability_required": "astScan",
+  "hint": "This tool is unavailable when MCP is driven by a remote provider. Use a LocalProvider or the stdio transport."
+}
+```
+
+If the agent is driving a remote-only session (e.g. Studio-hosted MCP over HTTP + GitHubProvider), normalize and other local-only tools must run in a separate local checkout before content is pushed.
+
 ---
 
 ## 5. Tool Details
@@ -401,7 +434,8 @@ Keep suggestions brief and contextual. Do not repeat them if already mentioned.
 | `VALIDATION_FAILED` | Content does not match schema | Fix errors reported by `contentrain_validate`, then retry |
 | `REFERENCED_MODEL` | Attempting to delete a model referenced by others | Remove relation fields from referencing models first |
 | `LOCALE_MISMATCH` | Locale not in supported list | Check `config.locales.supported`, add locale or use a supported one |
-| `BRANCH_BLOCKED` | Too many active contentrain/* branches (80+) | Merge or delete old branches before creating new ones |
+| `BRANCH_BLOCKED` | Too many active `cr/*` branches (80+) | Merge or delete old branches before creating new ones |
+| `capability_required` | Tool requires a capability the active provider does not expose (e.g. `astScan` on a GitHubProvider) | Switch to a LocalProvider session, or run the tool in a local checkout before returning to the remote flow |
 
 ### Rule: Always Check Status After Errors
 

package/shared/normalize-rules.md

@@ -22,7 +22,7 @@ Each phase produces a separate branch for independent review. This separation en
 | Purpose | Pull content from source to `.contentrain/` | Patch source files with content references |
 | Scope | Full project scan | Per model or per domain |
 | Source files modified | No | Yes |
-| Branch pattern | `contentrain/normalize/extract/{domain}/{timestamp}` | `contentrain/normalize/reuse/{model}/{locale}/{timestamp}` |
+| Branch pattern | `cr/normalize/extract/{domain}/{timestamp}-{suffix}` | `cr/normalize/reuse/{model}/{locale}/{timestamp}-{suffix}` |
 | Prerequisite | Initialized `.contentrain/` | Completed extraction (content exists in `.contentrain/`) |
 | Workflow mode | Always `review` | Always `review` |
 | Standalone value | Yes -- content is manageable in Studio immediately | Depends on Phase 1 |

package/shared/workflow-rules.md

@@ -43,25 +43,26 @@ Contentrain supports two workflow modes, configured in `.contentrain/config.json
 All Contentrain branches follow a strict naming pattern:
 
 ```
-contentrain/{operation}/{model}/{locale}/{timestamp}
+cr/{operation}/{model}/{locale}/{timestamp}
 ```
 
 ### Examples
 
 | Scenario | Branch Name |
 |----------|-------------|
-| Content update | `contentrain/content/blog-post/en/1710300000` |
-| Model creation | `contentrain/model/team-member/1710300000` |
-| Normalize extraction | `contentrain/normalize/extract/blog/1710300000` |
-| Normalize reuse | `contentrain/normalize/reuse/marketing-hero/en/1710300000` |
-| Scaffold | `contentrain/new/scaffold-landing/en/1710300000` |
+| Content update | `cr/content/blog-post/en/1710300000-a1b2` |
+| Model creation | `cr/model/team-member/1710300000-c3d4` |
+| Normalize extraction | `cr/normalize/extract/blog/1710300000-e5f6` |
+| Normalize reuse | `cr/normalize/reuse/marketing-hero/en/1710300000-0789` |
+| Scaffold | `cr/new/scaffold-landing/en/1710300000-1234` |
 
 ### Rules
 
 - Branches are created automatically by MCP tools. Do NOT create them manually.
-- The `{timestamp}` component ensures uniqueness.
+- The `{timestamp}-{suffix}` component ensures uniqueness across concurrent writes.
 - `{locale}` is included when the operation is locale-specific.
 - `{model}` is included when the operation targets a specific model.
+- Legacy `contentrain/*` branches from pre-`cr/*` installations are auto-migrated on first init.
 
 ---