@contentrain/skills 0.8.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -61,8 +61,8 @@
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@contentrain/mcp": "3.0.0",
-    "@contentrain/rules": "0.7.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 | 21 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/mcp-tools.md

@@ -132,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"
 }
 ```
 
@@ -145,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
@@ -313,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
 
@@ -340,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
 
@@ -387,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`) |
 
@@ -396,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/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

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

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: