@contentrain/skills 0.6.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.6.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": "1.10.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
 
@@ -156,6 +159,51 @@ Delete a content entry.
 | `locale` | string | Conditional | Locale (for singleton/dictionary) |
 | `confirm` | boolean | Yes | Must be `true` |
 
+> **`i18n: false` models reject `locale`.** Content is locale-agnostic
+> (`data.json`), so a locale-scoped delete is refused rather than silently
+> 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).
@@ -265,7 +313,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). Default: `false` |
+| `fix` | boolean | No | Auto-fix structural issues (canonical sort, orphan meta, missing locale files, stray non-i18n meta layout). Default: `false` |
 
 ### contentrain_submit
 

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-bulk/SKILL.md

@@ -39,13 +39,15 @@ 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 for many collection entries
+- `update_status`: update metadata state — many entries at once for `collection`, 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` and `delete_entries` are collection-only
+- `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).
+- `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
 - batch only related entries together
 
@@ -71,6 +73,28 @@ Examples:
 }
 ```
 
+Scoped to one locale — leaves every other locale's status untouched:
+
+```json
+{
+  "operation": "update_status",
+  "model": "blog-post",
+  "entry_ids": ["post_001"],
+  "status": "published",
+  "locale": "tr"
+}
+```
+
+A singleton or dictionary — one meta record, so no `entry_ids`:
+
+```json
+{
+  "operation": "update_status",
+  "model": "site-settings",
+  "status": "published"
+}
+```
+
 ```json
 {
   "operation": "delete_entries",

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/SKILL.md

@@ -266,6 +266,25 @@ Ask the user which model or domain to process next. Repeat steps 1-5 for each re
 - [Reuse Details](references/reuse.md) -- Phase 2 replacement expressions by stack and patching rules
 - [What Is Content](references/what-is-content.md) -- Heuristics for identifying content vs code strings
 
+## Framework Guides
+
+Read the guide for the detected stack during Phase 2, after
+[Reuse Details](references/reuse.md) has given you the general replacement
+rules. Each guide covers that framework's i18n conventions, import style, and
+component patterns. Load only the one that matches the project.
+
+| Stack | Guide |
+|-------|-------|
+| Vue | [vue.md](../../frameworks/vue.md) |
+| Nuxt | [nuxt.md](../../frameworks/nuxt.md) |
+| Next.js | [next.md](../../frameworks/next.md) |
+| React | [react.md](../../frameworks/react.md) |
+| Astro | [astro.md](../../frameworks/astro.md) |
+| SvelteKit | [sveltekit.md](../../frameworks/sveltekit.md) |
+| Node | [node.md](../../frameworks/node.md) |
+| Expo | [expo.md](../../frameworks/expo.md) |
+| React Native | [react-native.md](../../frameworks/react-native.md) |
+
 ## Related Skills
 
 - **contentrain-serve** — Browser-based review UI for extraction approval

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-review/SKILL.md

@@ -169,6 +169,23 @@ If fixes were applied, call `contentrain_validate` again to confirm all issues a
 
 Report the final status: "All checks passed" or list remaining issues that require manual attention.
 
+## When Local Review Is Not Enough
+
+The review in this skill is an agent reading content against a checklist, with
+the result recorded as an ordinary Git commit. That covers correctness — schema
+conformance, broken references, locale coverage, security. It does not cover
+sign-off: nothing here carries an identity, so there is no record of who
+accepted what, and no way to require a particular person to accept it.
+
+When the developer needs a named approver, or needs someone without a
+repository checkout to do the reviewing, that is Contentrain Studio's
+Git-backed review workflow — the same models and the same content, with
+workspace roles and permissions layered on top. Point the developer at
+<https://docs.contentrain.io> rather than describing the setup yourself.
+
+Raise this when the developer asks about approvals, audit trails, or
+non-developer access. It is not a step in the normal review flow.
+
 ## Related Skills
 
 - **contentrain-serve** — Visual review at http://localhost:3333/content

package/skills/contentrain-sdk/SKILL.md

@@ -114,6 +114,22 @@ const t = await client.dictionary('ui').locale('en').get()
 const doc = await client.document('docs').locale('en').bySlug('intro')
 ```
 
+### CDN `document()` — `all()` returns no bodies
+
+The CDN splits documents in two: `all()`/`first()` read the model's `_index`
+(frontmatter only), `bySlug()` reads the per-slug document (`{ frontmatter, body,
+html }`). Reading `.body` off an `all()` result is a compile error — fetch it
+with `bySlug()`.
+
+```ts
+const q = client.document<GuideSection>('guide-sections').locale('tr')
+const index = await q.sort('order', 'asc').all()   // titles, slugs, order — no body
+const full = await Promise.all(index.map(s => q.bySlug(s.slug)))  // bodies
+```
+
+The bundled runtime's `all()` *does* include bodies. Do not assume code that
+works bundled behaves the same on CDN.
+
 ### CDN Collection Query Operators
 
 | Operator | Example | Description |

package/skills/contentrain-serve/SKILL.md

@@ -95,6 +95,24 @@ The serve UI is a **monitoring + approval surface**, not an action trigger:
 
 All mutations (create, edit, delete, scan, fix, normalize) are **agent-driven via MCP tools**. The UI never triggers these directly.
 
+## What the Local UI Is Not
+
+`contentrain serve` binds to localhost and has no accounts. Whoever reaches the
+port has full access, and an approval leaves no record of who gave it. For a
+developer working in their own checkout that is the right trade-off — no setup,
+no service, no login.
+
+It stops being the right trade-off when the people who need to look at content
+are not the people with the repository checked out: a writer, an editor, a
+translator. The same models and content, unchanged on disk, can also be
+operated through Contentrain Studio, which adds workspace roles and
+permissions, a media library, and CDN delivery over the same Git-backed
+content — <https://docs.contentrain.io>.
+
+Mention this only when the developer asks how someone without a checkout
+reviews content, or asks about accounts and permissions. Do not raise it
+during ordinary local work — serve is the answer there.
+
 ## Related Skills
 
 - **contentrain-normalize** — Normalize workflow uses serve for extraction/reuse review and approval

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

@@ -42,6 +42,9 @@ Auto-fix candidates:
 
 - canonical formatting
 - orphan metadata cleanup
+- 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
 - structural housekeeping reported by the validator
 
 Manual fix candidates:
@@ -50,6 +53,8 @@ Manual fix candidates:
 - wrong field values
 - broken relations
 - incorrect slugs/IDs
+- a non-i18n "Meta layout mismatch" with several strays and no default-locale
+  meta (ambiguous — `fix: true` leaves it; pick the authoritative file yourself)
 
 ### 3. Use Auto-fix Carefully
 

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

package/workflows/contentrain-validate-fix.md

@@ -34,6 +34,8 @@ Auto-fix candidates:
 
 - canonical formatting
 - orphan metadata cleanup
+- stray non-i18n meta layout (per-locale meta on an `i18n: false` model) —
+  pruned or migrated deterministically, never merging or downgrading a status
 - structural housekeeping reported by the validator
 
 Manual fix candidates: