@contentrain/skills 0.7.0 → 0.8.0

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.0",
   "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.0.0",
+    "@contentrain/rules": "0.7.0"
   },
   "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 | 21 MCP tools (scan, apply, validate, merge, 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'` |

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
 
@@ -161,6 +164,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).

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-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
 

package/skills/contentrain-model/SKILL.md

@@ -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/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" } }
     }
   ],