@contentrain/rules 0.7.0 → 0.7.1

package/dist/index.cjs

@@ -100,6 +100,7 @@ const MCP_TOOLS = [
 	"contentrain_validate",
 	"contentrain_submit",
 	"contentrain_merge",
+	"contentrain_reconcile",
 	"contentrain_branch_list",
 	"contentrain_branch_delete",
 	"contentrain_bulk",

package/dist/index.d.cts

@@ -40,7 +40,7 @@ declare const MODEL_PROPERTIES: readonly [{
   readonly required: true;
 }];
 type ModelProperty = (typeof MODEL_PROPERTIES)[number]['name'];
-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_vocabulary_save", "contentrain_vocabulary_delete", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_merge", "contentrain_branch_list", "contentrain_branch_delete", "contentrain_bulk", "contentrain_doctor", "contentrain_media_list", "contentrain_media_get", "contentrain_media_ingest", "contentrain_media_update", "contentrain_media_delete"];
+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_vocabulary_save", "contentrain_vocabulary_delete", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_merge", "contentrain_reconcile", "contentrain_branch_list", "contentrain_branch_delete", "contentrain_bulk", "contentrain_doctor", "contentrain_media_list", "contentrain_media_get", "contentrain_media_ingest", "contentrain_media_update", "contentrain_media_delete"];
 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

@@ -40,7 +40,7 @@ declare const MODEL_PROPERTIES: readonly [{
   readonly required: true;
 }];
 type ModelProperty = (typeof MODEL_PROPERTIES)[number]['name'];
-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_vocabulary_save", "contentrain_vocabulary_delete", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_merge", "contentrain_branch_list", "contentrain_branch_delete", "contentrain_bulk", "contentrain_doctor", "contentrain_media_list", "contentrain_media_get", "contentrain_media_ingest", "contentrain_media_update", "contentrain_media_delete"];
+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_vocabulary_save", "contentrain_vocabulary_delete", "contentrain_scan", "contentrain_apply", "contentrain_validate", "contentrain_submit", "contentrain_merge", "contentrain_reconcile", "contentrain_branch_list", "contentrain_branch_delete", "contentrain_bulk", "contentrain_doctor", "contentrain_media_list", "contentrain_media_get", "contentrain_media_ingest", "contentrain_media_update", "contentrain_media_delete"];
 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.mjs

@@ -99,6 +99,7 @@ const MCP_TOOLS = [
 	"contentrain_validate",
 	"contentrain_submit",
 	"contentrain_merge",
+	"contentrain_reconcile",
 	"contentrain_branch_list",
 	"contentrain_branch_delete",
 	"contentrain_bulk",

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// ─── Model Definition Properties ───\n//\n// The parity anchor for the model schema. Docs describing `ModelDefinition` drift\n// silently: nothing failed when a property landed in @contentrain/types and never\n// reached schema-rules.md. The tests in tests/mcp-parity.test.ts assert this list\n// against MODEL_FIELD_ORDER in @contentrain/mcp and against the prose tables.\n\nexport const MODEL_PROPERTIES = [\n  { name: 'id', required: true },\n  { name: 'name', required: true },\n  { name: 'kind', required: true },\n  { name: 'domain', required: true },\n  { name: 'i18n', required: true },\n  { name: 'title_field', required: true },\n  { name: 'description', required: false },\n  { name: 'content_path', required: false },\n  { name: 'locale_strategy', required: false },\n  // `required` here means \"documented as required\", not the TS optionality.\n  // `fields` is `fields?` on the interface but every non-dictionary model needs\n  // it — a collection with no fields cannot even name a title_field. The\n  // per-kind nuance lives in the docs cell (\"Yes (except dictionary)\").\n  { name: 'fields', required: true },\n] as const\n\nexport type ModelProperty = (typeof MODEL_PROPERTIES)[number]['name']\n\n// ─── MCP Tools (26 tools: 21 core + 5 media) ───\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_vocabulary_save', 'contentrain_vocabulary_delete',\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  // Media tools — registered only when the provider exposes a media stack\n  // (Studio MCP Cloud); absent from local stdio servers.\n  'contentrain_media_list', 'contentrain_media_get', 'contentrain_media_ingest',\n  'contentrain_media_update', 'contentrain_media_delete',\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;AAUhF,MAAa,mBAAmB;CAC9B;EAAE,MAAM;EAAM,UAAU;EAAM;CAC9B;EAAE,MAAM;EAAQ,UAAU;EAAM;CAChC;EAAE,MAAM;EAAQ,UAAU;EAAM;CAChC;EAAE,MAAM;EAAU,UAAU;EAAM;CAClC;EAAE,MAAM;EAAQ,UAAU;EAAM;CAChC;EAAE,MAAM;EAAe,UAAU;EAAM;CACvC;EAAE,MAAM;EAAe,UAAU;EAAO;CACxC;EAAE,MAAM;EAAgB,UAAU;EAAO;CACzC;EAAE,MAAM;EAAmB,UAAU;EAAO;CAK5C;EAAE,MAAM;EAAU,UAAU;EAAM;CACnC;AAMD,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;CAA+B;CAC/B;CAAoB;CACpB;CAAwB;CACxB;CACA;CAA2B;CAC3B;CACA;CAGA;CAA0B;CAAyB;CACnD;CAA4B;CAC7B;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// ─── Model Definition Properties ───\n//\n// The parity anchor for the model schema. Docs describing `ModelDefinition` drift\n// silently: nothing failed when a property landed in @contentrain/types and never\n// reached schema-rules.md. The tests in tests/mcp-parity.test.ts assert this list\n// against MODEL_FIELD_ORDER in @contentrain/mcp and against the prose tables.\n\nexport const MODEL_PROPERTIES = [\n  { name: 'id', required: true },\n  { name: 'name', required: true },\n  { name: 'kind', required: true },\n  { name: 'domain', required: true },\n  { name: 'i18n', required: true },\n  { name: 'title_field', required: true },\n  { name: 'description', required: false },\n  { name: 'content_path', required: false },\n  { name: 'locale_strategy', required: false },\n  // `required` here means \"documented as required\", not the TS optionality.\n  // `fields` is `fields?` on the interface but every non-dictionary model needs\n  // it — a collection with no fields cannot even name a title_field. The\n  // per-kind nuance lives in the docs cell (\"Yes (except dictionary)\").\n  { name: 'fields', required: true },\n] as const\n\nexport type ModelProperty = (typeof MODEL_PROPERTIES)[number]['name']\n\n// ─── MCP Tools (27 tools: 22 core + 5 media) ───\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_vocabulary_save', 'contentrain_vocabulary_delete',\n  'contentrain_scan', 'contentrain_apply',\n  'contentrain_validate', 'contentrain_submit',\n  'contentrain_merge', 'contentrain_reconcile',\n  'contentrain_branch_list', 'contentrain_branch_delete',\n  'contentrain_bulk',\n  'contentrain_doctor',\n  // Media tools — registered only when the provider exposes a media stack\n  // (Studio MCP Cloud); absent from local stdio servers.\n  'contentrain_media_list', 'contentrain_media_get', 'contentrain_media_ingest',\n  'contentrain_media_update', 'contentrain_media_delete',\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;AAUhF,MAAa,mBAAmB;CAC9B;EAAE,MAAM;EAAM,UAAU;EAAM;CAC9B;EAAE,MAAM;EAAQ,UAAU;EAAM;CAChC;EAAE,MAAM;EAAQ,UAAU;EAAM;CAChC;EAAE,MAAM;EAAU,UAAU;EAAM;CAClC;EAAE,MAAM;EAAQ,UAAU;EAAM;CAChC;EAAE,MAAM;EAAe,UAAU;EAAM;CACvC;EAAE,MAAM;EAAe,UAAU;EAAO;CACxC;EAAE,MAAM;EAAgB,UAAU;EAAO;CACzC;EAAE,MAAM;EAAmB,UAAU;EAAO;CAK5C;EAAE,MAAM;EAAU,UAAU;EAAM;CACnC;AAMD,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;CAA+B;CAC/B;CAAoB;CACpB;CAAwB;CACxB;CAAqB;CACrB;CAA2B;CAC3B;CACA;CAGA;CAA0B;CAAyB;CACnD;CAA4B;CAC7B;AAMD,MAAa,uBAAuB;AAIpC,MAAa,SAAS;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAS;CAAO"}

package/essential/contentrain-essentials.md

@@ -33,7 +33,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 - **NEVER** edit `.contentrain/context.json` — MCP writes, agents read
 - **NEVER** include system fields in content data: `id`, `status`, `source`, `updated_by`, `updated_at`, `createdAt`, `updatedAt`
 - **ALWAYS** use MCP tools — do not write `.contentrain/` JSON files directly
-- **Publishing is yours, not MCP's.** `contentrain_content_save` preserves an existing entry's `status`; only a brand-new entry starts at `draft`. To change publish state, call `contentrain_bulk update_status` deliberately — and note that on the CDN a collection entry is delivered only when its status is `published`.
+- **Publishing is yours, not MCP's.** `contentrain_content_save` preserves an existing entry's `status`; only a brand-new entry starts at `draft`. To change publish state, call `contentrain_bulk update_status` deliberately (`entry_ids` for collections, `slugs` for documents, neither for singletons/dictionaries) — and note that on the CDN an entry is delivered only when its status is `published`. `publish_at`/`expire_at` on `content_save` never change status: they gate delivery of a published entry, live in meta only, and `null` clears them.
 - **Schema validity is MCP's.** `contentrain_content_save` validates before it writes and **refuses** the save on any error — nothing is committed, so there is no branch to clean up. Fix the values and call it again. Warnings (email/url/colour/phone heuristics, `accept` extension checks) do not block; they come back in the response.
 - **Every model declares its `title_field`.** Required on create, and it must stay correct when you rename or drop a field. It names the field shown as an entry's title and must be a `string`/`text`/`slug`/`email`/`url`/`code`/`markdown`/`richtext` field on that model; dictionaries have no fields, so they use the reserved value `"key"`. Pick what a human reads to tell entries apart — the headline, the name, the question — never the slug, icon or a relation ID. Consumers used to guess this and titled rows `i-lucide-bot`.
 - **A declared constraint is a real constraint.** `model_save` rejects a property declared where it cannot apply (`options` on a non-select, `accept` on a non-media field, `unique` on a singleton) rather than accepting it and doing nothing. The one exception is `maxSize`, which MCP cannot enforce — your media provider does, at ingest, and `model_save` says so.
@@ -59,6 +59,7 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 | `contentrain_validate` | Validate content against schemas |
 | `contentrain_submit` | Push branches to remote |
 | `contentrain_merge` | Merge a review-mode branch into contentrain locally (by exact branch or model) |
+| `contentrain_reconcile` | Content-aware three-way merge of a diverged contentrain ↔ base pair (dry_run first) |
 | `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) |
@@ -92,6 +93,8 @@ Media tools appear only when the provider exposes a media stack; discover paths
 - The `contentrain` branch is protected from deletion
 - context.json is never committed on feature branches — it is regenerated on the `contentrain` branch after merge
 - Never create branches manually, never commit directly to main or the `contentrain` branch
+- The one legitimate exception: a dual-domain migration (package bump + `.contentrain/` schema change) lands on the base branch via PR — afterwards `contentrain` and the base have diverged, and writes report `base_advance: "blocked_diverged"` (the content is safe on `contentrain`; only the fast-forward is pending)
+- Divergence is reconciled with `contentrain_reconcile`: dry_run first, review the plan and conflicts, collect resolutions from the editor for anything two-sided, then execute — it lands as a two-parent merge commit and the fast-forward advance works again
 - 50+ active `cr/*` branches = warning, 80+ = blocked
 
 ## CLI Serve — Review & Approval

package/package.json

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

package/shared/mcp-usage.md

@@ -166,25 +166,26 @@ Each entry in the `entries` array has this shape:
 
 | Tool | Purpose | Parameters |
 |------|---------|------------|
-| `contentrain_bulk` | Run git-backed batch operations on existing content entries | `operation`, `model`, `source_locale?`, `target_locale?`, `entry_ids?`, `status?`, `confirm?` |
+| `contentrain_bulk` | Run git-backed batch operations on existing content entries | `operation`, `model`, `source_locale?`, `target_locale?`, `entry_ids?`, `slugs?`, `locale?`, `status?`, `confirm?` |
 
 #### contentrain_bulk operations
 
 - `copy_locale`: copy one locale to another for an i18n-enabled `collection`, `singleton`, or `dictionary` model. Requires `source_locale` and `target_locale`.
-- `update_status`: update entry metadata status for a `collection` model. Requires `entry_ids` and `status`.
+- `update_status`: update entry metadata status. Requires `status`, plus the list that matches the model's meta layout: `entry_ids` for a `collection`, `slugs` for a `document`, and neither for a `singleton` or `dictionary` (one meta record per locale). Pass `locale` to scope the change; otherwise every supported locale is rewritten.
 - `delete_entries`: delete multiple entries from a `collection` model. Requires `entry_ids` and `confirm: true`.
 
 #### contentrain_bulk rules
 
 - ALWAYS verify the target model with `contentrain_describe` or `contentrain_status` before running a bulk operation.
 - `copy_locale` MUST NOT be used on non-i18n models.
-- `update_status` and `delete_entries` are collection-only operations.
+- `update_status` is the only way to change publish state. `publish_at` on `contentrain_content_save` does not publish — it gates delivery of an entry that is already `published`.
+- `delete_entries` is a collection-only operation.
 - Bulk operations create branches and commits like other write tools; validate afterward when content shape may have changed.
 
 #### contentrain_validate parameters
 
 - `model`: validate a specific model only (omit for all models).
-- `fix`: auto-fix structural issues like canonical sort, orphan meta, missing locale files, and stray non-i18n meta layout (default: false). Stray-meta cleanup is deterministic: it prunes extras when the default-locale meta is authoritative, or migrates a lone stray to the default path — it never merges or downgrades a status.
+- `fix`: auto-fix structural issues like canonical sort, orphan meta, missing locale files, stray non-i18n meta layout, and `publish_at`/`expire_at` copies an older `content_save` left in document frontmatter (stripped only when meta holds the same key), and backfill a missing model `title_field` (default: false). Stray-meta cleanup is deterministic: it prunes extras when the default-locale meta is authoritative, or migrates a lone stray to the default path — it never merges or downgrades a status.
 
 #### contentrain_submit parameters
 

package/shared/workflow-rules.md

@@ -153,6 +153,19 @@ Contentrain's storage format is designed to minimize Git merge conflicts:
 - When a conflict occurs, the agent should NOT attempt to resolve it. Inform the user and direct them to Studio.
 - Collection object-map format with sorted keys means ~0.3% chance of conflict for two new entries in a 350-entry collection.
 
+### 4.4 Branch Divergence and Reconcile
+
+The `contentrain` branch normally contains the base branch, so advancing the base is always a fast-forward. The invariant breaks legitimately in exactly one case: a **dual-domain migration** — a package bump and a `.contentrain/` schema change that must ship as one atomic PR to the base branch. After it lands, the branches have **diverged**.
+
+- Divergence is a product state, not an error. Writes still land on `contentrain` and report `base_advance: "blocked_diverged"`; nothing is lost.
+- The exit is `contentrain_reconcile` (CLI: `npx contentrain reconcile`) — a content-aware three-way merge. Always dry-run first.
+- Everything one side changed merges mechanically (entry-, key-, and term+locale-level). Only the same item changed differently on both sides becomes a `ConflictItem`.
+- Conflicts are content decisions: take them to the editor/user, collect `{ id, choose }` resolutions, run again. NEVER guess a side.
+- Conflict ids hash position AND values — a decision made against a stale preview is dropped and re-asked. This is intended, not a bug.
+- The result is a two-parent merge commit on `contentrain`; the fast-forward advance works again afterwards.
+
+**Dual-domain migration recipe**: (1) build the migration on an isolated branch and land it on the base branch via PR — never hand-edit `.contentrain/` on the base outside this exception; (2) immediately after the PR merges, run the reconcile (Studio does this from its health check; locally run `npx contentrain reconcile`); (3) resume normal writes.
+
 ---
 
 ## 5. Workflow States