@contentrain/rules 0.6.0 → 0.7.1

package/README.md

@@ -75,7 +75,7 @@ The package root exports constants for tooling:
 
 - `FIELD_TYPES` — 27 flat field types
 - `MODEL_KINDS` — `singleton`, `collection`, `document`, `dictionary`
-- `MCP_TOOLS` — 24 MCP tool names: 19 core + 5 media (`contentrain_media_*`, registered only on media-capable providers)
+- `MCP_TOOLS` — 26 MCP tool names: 21 core + 5 media (`contentrain_media_*`, registered only on media-capable providers)
 - `ESSENTIAL_RULES_FILE` — path to essential guardrails markdown
 - `STACKS` — supported framework stacks
 

package/dist/index.cjs

@@ -40,6 +40,48 @@ const MODEL_KINDS = [
 	"document",
 	"dictionary"
 ];
+const MODEL_PROPERTIES = [
+	{
+		name: "id",
+		required: true
+	},
+	{
+		name: "name",
+		required: true
+	},
+	{
+		name: "kind",
+		required: true
+	},
+	{
+		name: "domain",
+		required: true
+	},
+	{
+		name: "i18n",
+		required: true
+	},
+	{
+		name: "title_field",
+		required: true
+	},
+	{
+		name: "description",
+		required: false
+	},
+	{
+		name: "content_path",
+		required: false
+	},
+	{
+		name: "locale_strategy",
+		required: false
+	},
+	{
+		name: "fields",
+		required: true
+	}
+];
 const MCP_TOOLS = [
 	"contentrain_status",
 	"contentrain_describe",
@@ -51,11 +93,14 @@ const MCP_TOOLS = [
 	"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",
@@ -80,4 +125,5 @@ exports.ESSENTIAL_RULES_FILE = ESSENTIAL_RULES_FILE;
 exports.FIELD_TYPES = FIELD_TYPES;
 exports.MCP_TOOLS = MCP_TOOLS;
 exports.MODEL_KINDS = MODEL_KINDS;
+exports.MODEL_PROPERTIES = MODEL_PROPERTIES;
 exports.STACKS = STACKS;

package/dist/index.d.cts

@@ -8,11 +8,43 @@ 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_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 MODEL_PROPERTIES: readonly [{
+  readonly name: "id";
+  readonly required: true;
+}, {
+  readonly name: "name";
+  readonly required: true;
+}, {
+  readonly name: "kind";
+  readonly required: true;
+}, {
+  readonly name: "domain";
+  readonly required: true;
+}, {
+  readonly name: "i18n";
+  readonly required: true;
+}, {
+  readonly name: "title_field";
+  readonly required: true;
+}, {
+  readonly name: "description";
+  readonly required: false;
+}, {
+  readonly name: "content_path";
+  readonly required: false;
+}, {
+  readonly name: "locale_strategy";
+  readonly required: false;
+}, {
+  readonly name: "fields";
+  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_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"];
 type Stack = (typeof STACKS)[number];
 //#endregion
-export { ESSENTIAL_RULES_FILE, FIELD_TYPES, FieldType, MCP_TOOLS, MODEL_KINDS, McpTool, ModelKind, STACKS, Stack };
+export { ESSENTIAL_RULES_FILE, FIELD_TYPES, FieldType, MCP_TOOLS, MODEL_KINDS, MODEL_PROPERTIES, McpTool, ModelKind, ModelProperty, STACKS, Stack };
 //# sourceMappingURL=index.d.cts.map

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,KAiBD,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,cASnB,gBAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiBD,aAAA,WAAwB,gBAAA;AAAA,cAIvB,SAAA;AAAA,KAkBD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.d.mts

@@ -8,11 +8,43 @@ 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_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 MODEL_PROPERTIES: readonly [{
+  readonly name: "id";
+  readonly required: true;
+}, {
+  readonly name: "name";
+  readonly required: true;
+}, {
+  readonly name: "kind";
+  readonly required: true;
+}, {
+  readonly name: "domain";
+  readonly required: true;
+}, {
+  readonly name: "i18n";
+  readonly required: true;
+}, {
+  readonly name: "title_field";
+  readonly required: true;
+}, {
+  readonly name: "description";
+  readonly required: false;
+}, {
+  readonly name: "content_path";
+  readonly required: false;
+}, {
+  readonly name: "locale_strategy";
+  readonly required: false;
+}, {
+  readonly name: "fields";
+  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_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"];
 type Stack = (typeof STACKS)[number];
 //#endregion
-export { ESSENTIAL_RULES_FILE, FIELD_TYPES, FieldType, MCP_TOOLS, MODEL_KINDS, McpTool, ModelKind, STACKS, Stack };
+export { ESSENTIAL_RULES_FILE, FIELD_TYPES, FieldType, MCP_TOOLS, MODEL_KINDS, MODEL_PROPERTIES, McpTool, ModelKind, ModelProperty, STACKS, Stack };
 //# sourceMappingURL=index.d.mts.map

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,KAiBD,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,cASnB,gBAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAiBD,aAAA,WAAwB,gBAAA;AAAA,cAIvB,SAAA;AAAA,KAkBD,OAAA,WAAkB,SAAA;AAAA,cAIjB,oBAAA;AAAA,cAIA,MAAA;AAAA,KACD,KAAA,WAAgB,MAAA"}

package/dist/index.mjs

@@ -39,6 +39,48 @@ const MODEL_KINDS = [
 	"document",
 	"dictionary"
 ];
+const MODEL_PROPERTIES = [
+	{
+		name: "id",
+		required: true
+	},
+	{
+		name: "name",
+		required: true
+	},
+	{
+		name: "kind",
+		required: true
+	},
+	{
+		name: "domain",
+		required: true
+	},
+	{
+		name: "i18n",
+		required: true
+	},
+	{
+		name: "title_field",
+		required: true
+	},
+	{
+		name: "description",
+		required: false
+	},
+	{
+		name: "content_path",
+		required: false
+	},
+	{
+		name: "locale_strategy",
+		required: false
+	},
+	{
+		name: "fields",
+		required: true
+	}
+];
 const MCP_TOOLS = [
 	"contentrain_status",
 	"contentrain_describe",
@@ -50,11 +92,14 @@ const MCP_TOOLS = [
 	"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",
@@ -75,6 +120,6 @@ const STACKS = [
 	"node"
 ];
 //#endregion
-export { ESSENTIAL_RULES_FILE, FIELD_TYPES, MCP_TOOLS, MODEL_KINDS, STACKS };
+export { ESSENTIAL_RULES_FILE, FIELD_TYPES, MCP_TOOLS, MODEL_KINDS, MODEL_PROPERTIES, STACKS };
 
 //# sourceMappingURL=index.mjs.map

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 (24 tools: 19 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_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;AAKhF,MAAa,YAAY;CACvB;CAAsB;CAAwB;CAC9C;CAAoB;CACpB;CAA0B;CAC1B;CAA4B;CAA8B;CAC1D;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,6 +33,10 @@ 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 (`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.
 
 ## MCP Tools
 
@@ -46,6 +50,8 @@ MCP is **deterministic infrastructure**. The agent (you) is the **intelligence l
 | `contentrain_model_save` | Create/update model definition (upsert) |
 | `contentrain_model_delete` | Delete model (checks referential integrity) |
 | `contentrain_content_save` | Create/update content entries (upsert) |
+| `contentrain_vocabulary_save` | Add/update canonical vocabulary terms — the only supported way to write `vocabulary.json` |
+| `contentrain_vocabulary_delete` | Remove canonical terms (`confirm: true`) |
 | `contentrain_content_delete` | Delete content entry |
 | `contentrain_content_list` | List entries for a model |
 | `contentrain_scan` | Scan project (graph/candidates/summary) |
@@ -53,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) |
@@ -86,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.6.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": "1.10.0"
+    "@contentrain/mcp": "3.1.8"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

package/shared/mcp-usage.md

@@ -48,7 +48,7 @@ MCP is **deterministic infrastructure**. The agent is the **intelligence layer**
 
 | Tool | Purpose | Parameters |
 |------|---------|------------|
-| `contentrain_model_save` | Create or update a model definition (upsert) | `id`, `name`, `kind`, `domain`, `i18n`, `fields?`, `description?`, `content_path?`, `locale_strategy?` |
+| `contentrain_model_save` | Create or update a model definition (upsert) | `id`, `name`, `kind`, `domain`, `i18n`, `title_field`, `fields?`, `description?`, `content_path?`, `locale_strategy?` |
 | `contentrain_model_delete` | Delete a model and its content | `model`, `confirm: true` |
 
 ### 2.4 Content Tools
@@ -58,6 +58,8 @@ MCP is **deterministic infrastructure**. The agent is the **intelligence layer**
 | `contentrain_content_save` | Create or update content entries (upsert) | `model`, `entries` (array of entry objects) |
 | `contentrain_content_delete` | Delete a content entry | `model`, `id?`, `slug?`, `locale?`, `confirm: true` |
 | `contentrain_content_list` | List content entries for a model (read-only) | `model`, `locale?`, `filter?`, `resolve?`, `limit?`, `offset?` |
+| `contentrain_vocabulary_save` | Add or update canonical vocabulary terms (merges) | `terms` |
+| `contentrain_vocabulary_delete` | Remove canonical terms | `terms`, `confirm: true` |
 
 #### contentrain_content_save entry format
 
@@ -83,6 +85,7 @@ Each entry in the `entries` array has this shape:
 - For **collection**: use `id` to identify the entry.
 - For **document**: use `slug` to identify the entry.
 - For **singleton/dictionary**: use `locale` to identify which locale file to delete.
+- On an **`i18n: false` model**, do NOT pass `locale` — content is locale-agnostic (`data.json`), so a locale-scoped delete is rejected. Omit `locale` to delete the entry; use `contentrain_validate` with `fix: true` to remove stray per-locale meta.
 
 ### 2.5 Normalize Tools
 
@@ -163,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 (default: false).
+- `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
 
@@ -384,6 +388,7 @@ Creates or updates a model definition. Key parameters:
 - `id`: kebab-case model ID (e.g., `"blog-post"`).
 - `kind`: one of `singleton`, `collection`, `document`, `dictionary`.
 - `i18n`: whether the model supports localization.
+- `title_field`: **required** — the field shown as an entry's title. Must name a field declared on this model whose type is `string`, `text`, `slug`, `email`, `url`, `code`, `markdown` or `richtext`. Dictionary models use the reserved value `"key"`. Set it when creating a model, and keep it correct when renaming or removing fields.
 - `content_path`: optional framework-relative path (e.g., `"content/blog"`, `"locales"`). When set, content is written here instead of `.contentrain/content/`.
 - `locale_strategy`: how locale is encoded in filenames: `"file"` (default), `"suffix"`, `"directory"`, `"none"`.
 - `locale_strategy: "none"` requires `i18n: false`. All other strategies work with both `i18n: true` and `i18n: false`.

package/shared/media-rules.md

@@ -73,6 +73,12 @@ Never hand-build delivery URLs or guess the CDN base. Save the path or URL the m
 
 3. If an image exceeds the size limit, instruct the user to compress or resize it before storing. Do not silently accept oversized files.
 
+   **This one is on you.** A `maxSize` on the field does not enforce it: MCP stores a
+   path and never sees the bytes, so it cannot check the size — your media provider
+   does, when the asset is ingested. `model_save` says as much when you declare
+   `maxSize`. A field's `accept` is checked, but only against the file **extension**,
+   which can lie.
+
 4. SVG files SHOULD be optimized (e.g., with SVGO) to remove editor metadata, comments, and unnecessary attributes.
 
 ---

package/shared/schema-rules.md

@@ -92,22 +92,27 @@ A field definition describes one field in a model. Include only the properties t
 
 ### 3.1 Field Properties
 
-| Property | Applicable Types | Description |
-|----------|-----------------|-------------|
-| `type` | ALL | **Required.** One of the 27 types. |
-| `required` | ALL | Mark field as mandatory. Default: `false`. Omit if `false`. |
-| `unique` | `string`, `email`, `slug`, `integer` | Enforce uniqueness within model. Default: `false`. Omit if `false`. |
-| `default` | ALL | Default value. Omit if `null`. |
-| `min` | string/text: char count; numbers: value; array: element count | Minimum constraint. |
-| `max` | Same as `min` | Maximum constraint. |
-| `pattern` | `string`, `text`, `code` | Regex validation pattern. |
-| `options` | `select` ONLY | Fixed choices: `["draft", "published", "archived"]` |
-| `model` | `relation`, `relations` ONLY | Target model ID. String or string array for polymorphic. |
-| `items` | `array` ONLY | Element type: `"string"` or `{ "type": "object", "fields": {...} }` |
-| `fields` | `object` ONLY | Nested field definitions. |
-| `accept` | `image`, `video`, `file` | Allowed MIME types: `"image/png,image/jpeg"` |
-| `maxSize` | `image`, `video`, `file` | Maximum file size in bytes. |
-| `description` | ALL | Human-readable hint (shown in Studio UI tooltip, used as agent context). |
+A property declared where it does not apply is **rejected by `model_save`** — it is
+not silently ignored. The "Enforced by" column says who actually checks each one.
+
+| Property | Applicable Types | Enforced by | Description |
+|----------|-----------------|-------------|-------------|
+| `type` | ALL | content_save (blocks) | **Required.** One of the 27 types. |
+| `required` | ALL | content_save (blocks) | Mark field as mandatory. Default: `false`. Omit if `false`. |
+| `unique` | Any type, on `collection` and `document` models. **Not `singleton`** — it holds one record per locale, so there is nothing to be unique against. | content_save (blocks) | Enforce uniqueness within the model, per locale. Default: `false`. Omit if `false`. |
+| `default` | ALL | model_save (coherence only) | Default value. Checked against its own `type` and `options`; **not** written into content — the agent supplies values. Omit if `null`. |
+| `min` | string/text: char count; numbers: value; array: element count | content_save (blocks) | Minimum constraint. Must not exceed `max`. |
+| `max` | Same as `min` | content_save (blocks) | Maximum constraint. On a media field this limits the **path string length**, not the file — use `maxSize` for bytes (model_save warns). |
+| `pattern` | Any string-shaped type | content_save (blocks) | Regex validation pattern. Compiled at model_save, so a broken regex is rejected rather than silently disabling the rule. |
+| `options` | `select` ONLY | content_save (blocks) | Fixed choices: `["draft", "published", "archived"]` |
+| `model` | `relation`, `relations` ONLY | content_save (blocks) | Target model ID. String or string array for polymorphic. |
+| `items` | `array` ONLY | content_save (blocks) | Element type: `"string"`, or a full FieldDef — `{ "type": "string", "max": 50 }`. Items are validated by the same rules as a scalar of that type. |
+| `fields` | `object` ONLY | content_save (blocks) | Nested field definitions. Validated recursively, at model_save and at content_save. |
+| `accept` | `image`, `video`, `file` | content_save (**warns**) | Allowed MIME types: `"image/png,image/jpeg"`, `"image/*"`, `".pdf"`. MCP checks the value's **file extension** — an approximation, since it holds a path, not the bytes. Your provider enforces the real MIME type at ingest. |
+| `maxSize` | `image`, `video`, `file` | **Provider, at ingest — not MCP** | Maximum file size in bytes. MCP never sees the file, so it cannot check this; model_save says so. |
+| `description` | ALL | — | Human-readable hint (shown in Studio UI tooltip, used as agent context). |
+| `label` | ALL | — | Editor label: a string, or an object keyed by locale. Absent means the raw field name is shown. |
+| `order` | ALL | — | Display position, ascending. Absent sorts last, alphabetically. Fractional values allowed. |
 
 ### 3.2 Omission Rules
 
@@ -131,6 +136,7 @@ Model definitions live at `.contentrain/models/{model-id}.json`. One file per mo
   "kind": "document",
   "domain": "blog",
   "i18n": true,
+  "title_field": "title",
   "description": "Blog articles with markdown body",
   "fields": {
     "title": { "type": "string", "required": true, "max": 120 },
@@ -150,11 +156,23 @@ Model definitions live at `.contentrain/models/{model-id}.json`. One file per mo
 | `kind` | `string` | Yes | One of: `singleton`, `collection`, `document`, `dictionary`. |
 | `domain` | `string` | Yes | Organizational group (maps to content subdirectory). |
 | `i18n` | `boolean` | Yes | Whether the model supports multiple locales. |
+| `title_field` | `string` | Yes | Field shown as an entry's title in listings, pickers and relation references. Must name a field declared on this model whose type is `string`, `text`, `slug`, `email`, `url`, `code`, `markdown` or `richtext`. Dictionary models have no fields — they use the reserved value `"key"`, meaning the entry key is the title. |
 | `description` | `string` | No | Model description for documentation and agent context. |
 | `fields` | `object` | Yes (except dictionary) | Field definitions. Dictionary kind has NO fields. |
 | `content_path` | `string` | No | Framework-relative path for content files (e.g., `"content/blog"`, `"locales"`). When set, content is written here instead of `.contentrain/content/`. |
 | `locale_strategy` | `string` | No | How locale is encoded in file names: `"file"` (default), `"suffix"`, `"directory"`, `"none"`. |
 
+#### Choosing `title_field`
+
+Declare it on create AND keep it correct when renaming or removing fields — a
+`title_field` pointing at a field that no longer exists fails validation.
+
+Pick the field a human would read to tell one entry from another: the headline,
+the name, the question. Not the slug, not the icon, not a relation ID — those are
+identifiers, and a list titled `instagram-launch-post` or `i-lucide-bot` tells the
+reader nothing. That is exactly what consumers produced when they had to guess,
+which is why the property exists.
+
 ### 4.2 System Fields
 
 Do NOT define these in the schema. The platform manages them automatically:
@@ -164,7 +182,7 @@ Do NOT define these in the schema. The platform manages them automatically:
 | `id` | Collection | 12-char hex, used as object-map key |
 | `slug` | Document | Directory name in content path |
 | `createdAt` / `updatedAt` | All | Derived from Git commit history (not stored) |
-| `status`, `source`, `updated_by`, `approved_by` | All | Stored in `.contentrain/meta/` |
+| `status`, `source`, `updated_by`, `updated_at`, `approved_by` | All | Stored in `.contentrain/meta/` |
 
 ---
 

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