@contentrain/skills 0.7.0 → 0.8.1

package/README.md

@@ -127,7 +127,7 @@ This reduces always-loaded context from thousands of lines to just the essential
 
 `@contentrain/skills` is kept in lockstep with the MCP tool registry via cross-package parity tests (`tests/mcp-parity.test.ts`):
 
-- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 24: 19 core + 5 media).
+- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 26: 21 core + 5 media).
 - Key skills (normalize, translate) must not reference legacy `contentrain/{operation}/...` branch prefixes — MCP now emits `cr/*`.
 
 When MCP's surface changes, these tests fail until the skill docs catch up.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -61,7 +61,8 @@
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@contentrain/mcp": "2.3.0"
+    "@contentrain/mcp": "3.1.8",
+    "@contentrain/rules": "0.7.1"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

package/skills/contentrain/SKILL.md

@@ -16,7 +16,7 @@ Contentrain consists of 6 packages that work together:
 
 | Package | Role | How agent uses it |
 |---|---|---|
-| @contentrain/mcp | 19 MCP tools (scan, apply, validate, merge, doctor...) | MCP tool calls |
+| @contentrain/mcp | 22 MCP tools (scan, apply, validate, merge, reconcile, doctor...) | MCP tool calls |
 | contentrain (CLI) | init, serve, generate, doctor, diff, status | Shell commands |
 | @contentrain/types | Shared TypeScript contracts | Type safety |
 | @contentrain/query | Generated SDK client (Prisma-pattern) | `import from '#contentrain'` |
@@ -121,8 +121,9 @@ slug: getting-started
 | `contentrain_scan` | Scan project for structure or content candidates |
 | `contentrain_apply` | Apply normalize operation (extract or reuse) |
 | `contentrain_validate` | Validate content against model schemas |
-| `contentrain_submit` | Push contentrain/* branches to remote |
+| `contentrain_submit` | Push cr/* branches to remote |
 | `contentrain_merge` | Merge a review-mode branch into contentrain locally |
+| `contentrain_reconcile` | Content-aware three-way merge of a diverged contentrain ↔ base pair |
 | `contentrain_bulk` | Run batch operations on existing content |
 
 ## Calling Sequences

package/skills/contentrain/references/architecture.md

@@ -81,6 +81,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 },
@@ -100,6 +101,7 @@ Model definitions live at `.contentrain/models/{model-id}.json`. One file per mo
 | `kind` | string | Yes | `singleton`, `collection`, `document`, `dictionary` |
 | `domain` | string | Yes | Organizational group (maps to content subdirectory) |
 | `i18n` | boolean | Yes | Whether model supports multiple locales |
+| `title_field` | string | Yes | Field shown as an entry's title. Must name a field on this model whose type can render as text; dictionaries use `"key"` |
 | `description` | string | No | Model description for docs and agent context |
 | `fields` | object | Yes (except dictionary) | Field definitions. Dictionary has NO fields |
 | `content_path` | string | No | Framework-relative path. When set, content writes here instead of `.contentrain/content/` |

package/skills/contentrain/references/content-formats.md

@@ -183,6 +183,7 @@ Several fields are managed by the platform. Agents MUST NOT set or modify them.
 | `status` | `.contentrain/meta/` | Platform workflow engine |
 | `source` | `.contentrain/meta/` | Set by MCP: `"agent"`, `"human"`, or `"import"` |
 | `updated_by` | `.contentrain/meta/` | Set by MCP: agent name or user email |
+| `updated_at` | `.contentrain/meta/` | Set by MCP on every write, ISO 8601 UTC. Absent on entries written before the field existed — absent means unknown, never backfilled |
 | `approved_by` | `.contentrain/meta/` | Set by Studio on review approval |
 
 **Rule:** When creating content via `contentrain_content_save`, provide only the content fields defined in the model. Do not include `id`, `createdAt`, `updatedAt`, `status`, or any metadata fields.

package/skills/contentrain/references/mcp-tools.md

@@ -88,6 +88,7 @@ Create or update a model definition (upsert).
 | `kind` | string | Yes | `singleton`, `collection`, `document`, `dictionary` |
 | `domain` | string | Yes | Organizational group |
 | `i18n` | boolean | Yes | Whether model supports localization |
+| `title_field` | string | Yes | Field shown as an entry's title. Must name a field on this model typed `string`, `text`, `slug`, `email`, `url`, `code`, `markdown` or `richtext`. Dictionaries have no fields — use `"key"` |
 | `fields` | object | No | Field definitions (not for dictionary) |
 | `description` | string | No | Model description |
 | `content_path` | string | No | Framework-relative path for content files |
@@ -95,6 +96,8 @@ Create or update a model definition (upsert).
 
 Notes:
 - Upserts by model ID: existing model is updated, new model is created
+- `title_field` is required on create AND must stay correct when you rename or drop a field
+- Pick what a reader uses to tell entries apart — the headline, the name, the question. Not the slug, not the icon, not a relation ID
 - `locale_strategy: "none"` requires `i18n: false`
 - `content_path` overrides default `.contentrain/content/` location
 
@@ -129,7 +132,9 @@ Each entry in the `entries` array:
   "id": "optional-entry-id",
   "slug": "optional-slug",
   "locale": "en",
-  "data": { "field_name": "field_value" }
+  "data": { "field_name": "field_value" },
+  "publish_at": "2026-04-01T00:00:00Z",
+  "expire_at": "2026-06-30T23:59:59Z"
 }
 ```
 
@@ -142,6 +147,8 @@ Each entry in the `entries` array:
 | **Singleton** | `locale`, `data` | No `id` or `slug` needed |
 | **Dictionary** | `locale`, `data` | `data` is flat key-value: `{ "auth.login": "Log In" }` |
 
+**Scheduling** (`publish_at`, `expire_at`, optional, ISO 8601) sits next to `data`, never inside it. It is stored in meta only and **never changes `status`** — a past `publish_at` does not publish a draft; the dates gate delivery of an entry that is already `published`. Pass `null` to clear a date; omit the key to leave it unchanged. To publish, use `contentrain_bulk update_status`.
+
 **NEVER include system fields** (`status`, `source`, `updated_by`, `updated_at`, `createdAt`, `updatedAt`) in `data`.
 
 ### contentrain_content_delete
@@ -161,6 +168,46 @@ Delete a content entry.
 > mapped onto `data.json` + the default-locale meta. Omit `locale`; use
 > `contentrain_validate` `fix: true` to clean up stray per-locale meta.
 
+### contentrain_vocabulary_save
+
+Add or update canonical vocabulary terms. Merges — a term you omit is untouched.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `terms` | object | Yes | `{ "term-slug": { "en": "…", "tr": "…" } }` |
+
+The **outer** key is the term (kebab-case, locale-independent); the **inner**
+key is a locale code. Grouping by locale at the top level is the common
+mistake and produces a vocabulary that matches nothing — the tool rejects it.
+
+```json
+{
+  "terms": {
+    "sign-in": { "en": "Sign in", "tr": "Giriş yap" },
+    "add-to-cart": { "en": "Add to cart", "tr": "Sepete ekle" }
+  }
+}
+```
+
+Notes:
+- This is the only supported way to write `.contentrain/vocabulary.json` — do not edit it by hand
+- Replacing an existing translation is allowed and reported in `advisories`
+- Two terms sharing a translation is reported too; that is what a vocabulary exists to prevent
+
+### contentrain_vocabulary_delete
+
+Remove canonical terms by slug. Content already using a term is not touched —
+the vocabulary only advises.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `terms` | string[] | Yes | Term slugs to remove |
+| `confirm` | boolean | Yes | Must be `true` |
+
+A slug that is not in the vocabulary is reported in `missing`, not an error,
+and a call that matches nothing returns `status: "no-op"` without creating a
+branch.
+
 ### contentrain_content_list
 
 List content entries for a model (read-only).
@@ -270,7 +317,7 @@ Validate project content against model schemas.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `model` | string | No | Validate specific model only (omit for all) |
-| `fix` | boolean | No | Auto-fix structural issues (canonical sort, orphan meta, missing locale files, stray non-i18n meta layout). Default: `false` |
+| `fix` | boolean | No | Auto-fix structural issues (canonical sort, orphan meta, missing locale files, stray non-i18n meta layout, `publish_at`/`expire_at` copies an older `content_save` left in document frontmatter) and backfill a missing model `title_field`. Default: `false` |
 
 ### contentrain_submit
 
@@ -297,7 +344,28 @@ Target the branch by exact name, or resolve it by model:
 
 \* Provide either `branch` or `model`. Ambiguous model matches return the candidate branches so you can pick one (or pass `latest: true`).
 
-Returns `{ branch, action, commit, sync }` — `sync.skipped[]` lists files the selective sync skipped because the developer has uncommitted changes. The CLI surfaces this as a warning.
+Returns `{ branch, action, commit, sync, base_advance, remote_push }` — `sync.skipped[]` lists files the selective sync skipped because the developer has uncommitted changes; `base_advance: "blocked_diverged"` means the merge landed on `contentrain` but the base branch has diverged and was not advanced (run `contentrain_reconcile`). The CLI surfaces these as warnings.
+
+### contentrain_reconcile
+
+Content-aware three-way merge of a diverged `contentrain` ↔ base-branch pair. The divergence exists when the base branch holds commits `contentrain` does not (typically a dual-domain migration PR); until it is reconciled, every auto-merge write reports `base_advance: "blocked_diverged"`. Everything one side changed merges mechanically (entry-, key-, and term+locale-level); only the same item changed differently on both sides becomes a conflict. Local-filesystem only (`localWorktree`).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dry_run` | boolean | No | Default `true` — preview the plan and conflicts, touch nothing. Set `false` to execute |
+| `resolutions` | array | No | Decisions for conflicts from a previous dry-run: `{ id, choose: "ours"\|"theirs" }` or `{ id, value }` |
+
+```json
+{ "dry_run": true }
+```
+
+Returns `{ status: "in_sync" | "preview" | "conflicts" | "reconciled", summary, changes, conflicts, ... }`. On execute it lands as a two-parent merge commit on `contentrain` and fast-forwards the base branch.
+
+Notes:
+- Always dry-run first. Conflicts are content decisions — ask the editor/user which side wins; never guess.
+- Conflict ids hash position AND values: a resolution made against a stale preview is dropped and the conflict re-reported with a fresh id.
+- Document bodies are never text-merged; two-sided body edits always conflict.
+- Non-content files that conflict (source code committed to both branches) abort with `RECONCILE_SOURCE_CONFLICT` — those need a manual git merge.
 
 ### contentrain_branch_list
 
@@ -344,7 +412,9 @@ Run git-backed batch operations on existing content entries.
 | `model` | string | Yes | Target model ID |
 | `source_locale` | string | Conditional | For `copy_locale` |
 | `target_locale` | string | Conditional | For `copy_locale` |
-| `entry_ids` | string[] | Conditional | For `update_status` and `delete_entries` |
+| `entry_ids` | string[] | Conditional | For `update_status` on collections, and for `delete_entries` |
+| `slugs` | string[] | Conditional | For `update_status` on documents — documents are keyed by slug, not entry ID |
+| `locale` | string | No | Scope `update_status` to one locale (i18n models); default is every supported locale |
 | `status` | string | Conditional | For `update_status` |
 | `confirm` | boolean | Conditional | For `delete_entries` (must be `true`) |
 
@@ -353,7 +423,7 @@ Run git-backed batch operations on existing content entries.
 | Operation | Applicable Kinds | Required Params |
 |-----------|-----------------|-----------------|
 | `copy_locale` | collection, singleton, dictionary (i18n only) | `source_locale`, `target_locale` |
-| `update_status` | collection only | `entry_ids`, `status` |
+| `update_status` | collection (`entry_ids`), document (`slugs`), singleton and dictionary (neither) | `status`, plus the list that matches the kind |
 | `delete_entries` | collection only | `entry_ids`, `confirm: true` |
 
 #### Rules

package/skills/contentrain/references/model-kinds.md

@@ -28,6 +28,7 @@ Contentrain has four model kinds, each with distinct storage format, ID manageme
   "kind": "singleton",
   "domain": "marketing",
   "i18n": true,
+  "title_field": "title",
   "fields": {
     "title": { "type": "string", "required": true, "max": 80 },
     "subtitle": { "type": "text", "max": 200 },
@@ -73,6 +74,7 @@ Contentrain has four model kinds, each with distinct storage format, ID manageme
   "kind": "collection",
   "domain": "marketing",
   "i18n": true,
+  "title_field": "name",
   "fields": {
     "name": { "type": "string", "required": true },
     "role": { "type": "string", "required": true },
@@ -148,6 +150,7 @@ MCP tools return collections as arrays with `id` injected:
   "kind": "document",
   "domain": "blog",
   "i18n": true,
+  "title_field": "title",
   "fields": {
     "title": { "type": "string", "required": true, "max": 120 },
     "slug": { "type": "slug", "required": true, "unique": true },
@@ -204,7 +207,8 @@ Your markdown body content here...
   "name": "Error Messages",
   "kind": "dictionary",
   "domain": "system",
-  "i18n": true
+  "i18n": true,
+  "title_field": "key"
 }
 ```
 

package/skills/contentrain/references/schema-types.md

@@ -165,6 +165,8 @@ In v1, media fields store URL/path strings only. Upload and processing are out o
 | `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) |
+| `label` | ALL | Editor label: a string, or an object keyed by locale (`{ "en": "Body", "tr": "Gövde" }`). Absent shows the raw field name |
+| `order` | ALL | Display position, ascending. Absent sorts last, alphabetically. Fractional values allowed |
 
 ## Omission Rules
 

package/skills/contentrain/references/workflow.md

@@ -157,6 +157,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

package/skills/contentrain-bulk/SKILL.md

@@ -39,13 +39,14 @@ Confirm:
 ### 2. Pick the Correct Bulk Operation
 
 - `copy_locale`: clone one locale to another for i18n-enabled `collection`, `singleton`, or `dictionary` models
-- `update_status`: update metadata state — many entries at once for `collection`, or the single record of a `singleton`/`dictionary`
+- `update_status`: update metadata state — many entries at once for `collection` (by `entry_ids`) or `document` (by `slugs`), or the single record of a `singleton`/`dictionary`
 - `delete_entries`: remove many collection entries at once
 
 ### 3. Apply Safety Rules
 
 - never use `copy_locale` on non-i18n models
-- `update_status` takes `entry_ids` for `collection` models and **rejects them** for `singleton`/`dictionary` — those have one meta record per locale, so omit `entry_ids` entirely. Document models are not supported (their meta is keyed by slug).
+- `update_status` addresses records the way their meta is laid out: `entry_ids` for `collection` models, `slugs` for `document` models (meta is one file per slug — the same identity `contentrain_content_save` uses), and **neither** for `singleton`/`dictionary`, which have one meta record per locale. The wrong list is rejected with a message naming the right one.
+- `publish_at` on `contentrain_content_save` does **not** publish — it gates delivery of an already-published entry. `update_status` is the only way to change status.
 - `delete_entries` is collection-only
 - `update_status` rewrites every supported locale unless you pass `locale`. Pass it when restoring one locale's status, or you will change the other's too.
 - confirm entry IDs before delete operations
@@ -85,7 +86,19 @@ Scoped to one locale — leaves every other locale's status untouched:
 }
 ```
 
-A singleton or dictionary — one meta record, so no `entry_ids`:
+A document model — meta is one file per slug, so pass `slugs`, not `entry_ids`:
+
+```json
+{
+  "operation": "update_status",
+  "model": "guide-sections",
+  "slugs": ["instagram-9", "instagram-10", "instagram-11"],
+  "status": "published",
+  "locale": "tr"
+}
+```
+
+A singleton or dictionary — one meta record, so no `entry_ids` or `slugs`:
 
 ```json
 {

package/skills/contentrain-content/SKILL.md

@@ -63,7 +63,7 @@ If the user's request does not match an existing model, offer to create one firs
 
 - Check `.contentrain/vocabulary.json` for canonical terms. All content must use these terms consistently across locales. Do not use alternative spellings or synonyms for vocabulary-defined terms.
 - Check `.contentrain/context.json` for tone conventions (professional, casual, technical).
-- **For dictionaries:** Before creating any new key, call `contentrain_content_list` on the target model and scan existing values. If the value you intend to write already exists under a different key, REUSE the existing key instead of creating a new one. MCP will also warn you via `advisories` in the save response if duplicates are detected.
+- **For dictionaries:** Before creating any new key, call `contentrain_content_list` on the target model and scan existing values. If the value you intend to write already exists under a different key, REUSE the existing key instead of creating a new one. MCP will also warn you via `advisories` in the save response if duplicates are detected. Replacing an existing key's value is allowed — the response reports what was replaced, so read the advisories rather than assuming a save was purely additive.
 
 ### 5. Generate Content
 
@@ -167,7 +167,7 @@ For large content operations (10+ entries), also recommend running `contentrain
 Call `contentrain_submit` to push branches to remote:
 
 - Write operations already create branches and commit changes automatically.
-- `contentrain_submit` pushes unmerged `contentrain/*` branches to the remote.
+- `contentrain_submit` pushes unmerged `cr/*` branches to the remote.
 - In `auto-merge` mode, branches are already merged to the base branch during the write operation.
 - In `review` mode, branches are pushed for team review.
 

package/skills/contentrain-model/SKILL.md

@@ -65,7 +65,7 @@ Default rules:
 Follow these rules:
 
 - model IDs must be kebab-case
-- field names must be snake_case
+- field names must be snake_case — for *new* fields. A field an existing model already has under a legacy name (`creativeWork`) is kept by `contentrain_model_save` and reported in `schema_warnings`; never rename it just to satisfy the rule, since the rename must reach its content keys in every locale and every consumer too
 - relation fields must define a target `model`
 - prefer small, explicit schemas over large generic `object` blobs
 - only mark fields as `required` when the content truly cannot function without them
@@ -95,6 +95,7 @@ Before writing, show:
 - domain
 - `i18n` behavior
 - field list with types
+- `title_field` — which field titles an entry, and why that one
 - relation targets
 - any custom `content_path` / `locale_strategy`
 
@@ -113,6 +114,7 @@ Example:
   "kind": "singleton",
   "domain": "marketing",
   "i18n": true,
+  "title_field": "title",
   "fields": {
     "title": { "type": "string", "required": true },
     "subtitle": { "type": "text" },
@@ -122,6 +124,29 @@ Example:
 }
 ```
 
+`title_field` is required. It names the field shown as an entry's title in
+listings, pickers and relation references, and must be a field on this model
+typed `string`, `text`, `slug`, `email`, `url`, `code`, `markdown` or
+`richtext`. Dictionary models have no fields, so they use the reserved value
+`"key"` — the entry key is the title.
+
+Choose what a reader uses to tell one entry from another: the headline, the
+name, the question. Not the slug, not the icon, not a relation ID. Consumers
+that had to infer this picked the icon over the headline, which is why the
+property exists.
+
+**When updating an existing model**, re-check `title_field` in the same call:
+renaming or removing the field it points at makes the model invalid.
+
+Give every field a `label` and an `order`. Fields are stored alphabetically, so
+without `order` an editor lists them alphabetically — on a sixteen-field article
+model that puts `author` first and `title` fifteenth. Without `label` it shows
+the raw key: `body_public`, `is_category_hero`.
+
+Number `order` in tens (10, 20, 30) so a field can be inserted later without
+renumbering. Use a per-locale `label` (`{ "en": "…", "tr": "…" }`) on a
+multilingual project; a plain string is one label for every locale.
+
 ### 8. Validate Downstream Impact
 
 After changing a model:

package/skills/contentrain-normalize/references/extraction.md

@@ -67,6 +67,7 @@ After evaluation, write the plan as `.contentrain/normalize-plan.json`:
       "kind": "singleton",
       "domain": "marketing",
       "i18n": true,
+      "title_field": "title",
       "fields": {
         "title": { "type": "string", "required": true },
         "subtitle": { "type": "string" }

package/skills/contentrain-validate-fix/SKILL.md

@@ -45,6 +45,13 @@ Auto-fix candidates:
 - stray non-i18n meta layout (an `i18n: false` model with per-locale meta files
   left by older versions) — pruned or migrated deterministically, never merging
   or downgrading a status
+- `publish_at`/`expire_at` copies an older `content_save` left in document
+  frontmatter — stripped only when the meta record holds the same key, so the
+  value is never lost and an author's own frontmatter field is never touched
+- a missing model `title_field` — backfilled by the same ranking Studio's title
+  resolver uses (required name-like field first; slug/url/code never inferred),
+  reported as a notice naming the rule. Read it: if the pick is wrong, correct it
+  with `contentrain_model_save`
 - structural housekeeping reported by the validator
 
 Manual fix candidates:

package/workflows/contentrain-content.md

@@ -100,6 +100,7 @@ contentrain_content_save({
 - **collection:** `{ "id": "optional-id", "locale": "en", "data": { "name": "John", "role": "CEO" } }` -- omit `id` to auto-generate, provide `id` to update.
 - **document:** `{ "slug": "getting-started", "locale": "en", "data": { "title": "Getting Started", "body": "# Welcome\n..." } }` -- `slug` is required, use `"body"` key for markdown content.
 - **dictionary:** `{ "locale": "en", "data": { "auth.login": "Log In", "auth.logout": "Log Out" } }` -- flat key-value pairs, no `id` or `slug`.
+  Saves merge: keys you omit are kept, and replacing an existing key's value is allowed. The response reports what was replaced, so read `advisories` rather than assuming a save was purely additive.
 
 **Critical rules:**
 - NEVER include system fields (`status`, `source`, `updated_by`, `approved_by`) in `data`. These are managed in meta files, not content. Temporal data (created/updated timestamps) comes from git history.

package/workflows/contentrain-model.md

@@ -87,6 +87,7 @@ Before writing, show:
 - domain
 - `i18n` behavior
 - field list with types
+- `title_field` — which field titles an entry, and why that one
 - relation targets
 - any custom `content_path` / `locale_strategy`
 
@@ -105,6 +106,7 @@ Example:
   "kind": "singleton",
   "domain": "marketing",
   "i18n": true,
+  "title_field": "title",
   "fields": {
     "title": { "type": "string", "required": true },
     "subtitle": { "type": "text" },
@@ -114,6 +116,29 @@ Example:
 }
 ```
 
+`title_field` is required. It names the field shown as an entry's title in
+listings, pickers and relation references, and must be a field on this model
+typed `string`, `text`, `slug`, `email`, `url`, `code`, `markdown` or
+`richtext`. Dictionary models have no fields, so they use the reserved value
+`"key"` — the entry key is the title.
+
+Choose what a reader uses to tell one entry from another: the headline, the
+name, the question. Not the slug, not the icon, not a relation ID. Consumers
+that had to infer this picked the icon over the headline, which is why the
+property exists.
+
+**When updating an existing model**, re-check `title_field` in the same call:
+renaming or removing the field it points at makes the model invalid.
+
+Give every field a `label` and an `order`. Fields are stored alphabetically, so
+without `order` an editor lists them alphabetically — on a sixteen-field article
+model that puts `author` first and `title` fifteenth. Without `label` it shows
+the raw key: `body_public`, `is_category_hero`.
+
+Number `order` in tens (10, 20, 30) so a field can be inserted later without
+renumbering. Use a per-locale `label` (`{ "en": "…", "tr": "…" }`) on a
+multilingual project; a plain string is one label for every locale.
+
 ### 8. Validate Downstream Impact
 
 After changing a model:

package/workflows/contentrain-normalize.md

@@ -93,6 +93,7 @@ After evaluating candidates, write the plan as `.contentrain/normalize-plan.json
       "kind": "singleton",
       "domain": "marketing",
       "i18n": true,
+      "title_field": "title",
       "fields": { "title": { "type": "string", "required": true }, "subtitle": { "type": "string" } }
     }
   ],