@contentrain/skills 0.8.0 → 0.9.0

package/README.md

@@ -26,7 +26,7 @@ pnpm add @contentrain/skills
 ### Via skills CLI (install skills into your AI agent)
 
 ```bash
-# Install all 15 skills
+# Install all 16 skills
 npx skills add Contentrain/ai/packages/skills
 
 # Install a specific skill
@@ -64,6 +64,7 @@ Published under `skills/` — 15 production skills:
 | `contentrain-serve` | Start the local review and normalize UI |
 | `contentrain-diff` | View content diffs between branches |
 | `contentrain-doctor` | Diagnose project health issues |
+| `contentrain-migrate-wordpress` | Import a WordPress site and wire it to a framework |
 
 Each skill directory contains:
 

package/dist/index.cjs

@@ -66,6 +66,10 @@ const AGENT_SKILLS = [
 	{
 		name: "contentrain-doctor",
 		description: "Diagnose project health issues"
+	},
+	{
+		name: "contentrain-migrate-wordpress",
+		description: "Import a WordPress site into a .contentrain store and wire it to a framework"
 	}
 ];
 const WORKFLOW_SKILLS = [

package/dist/index.d.cts

@@ -50,6 +50,9 @@ declare const AGENT_SKILLS: readonly [{
 }, {
   readonly name: "contentrain-doctor";
   readonly description: "Diagnose project health issues";
+}, {
+  readonly name: "contentrain-migrate-wordpress";
+  readonly description: "Import a WordPress site into a .contentrain store and wire it to a framework";
 }];
 type AgentSkillName = (typeof AGENT_SKILLS)[number]['name'];
 declare const WORKFLOW_SKILLS: readonly ["contentrain-init", "contentrain-model", "contentrain-content", "contentrain-bulk", "contentrain-normalize", "contentrain-validate-fix", "contentrain-review", "contentrain-diff", "contentrain-doctor", "contentrain-serve", "contentrain-translate", "contentrain-generate"];

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AASA;;;;;cAAa,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkBD,cAAA,WAAyB,YAAA;AAAA,cAIxB,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";;AASA;;;;;cAAa,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmBD,cAAA,WAAyB,YAAA;AAAA,cAIxB,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}

package/dist/index.d.mts

@@ -50,6 +50,9 @@ declare const AGENT_SKILLS: readonly [{
 }, {
   readonly name: "contentrain-doctor";
   readonly description: "Diagnose project health issues";
+}, {
+  readonly name: "contentrain-migrate-wordpress";
+  readonly description: "Import a WordPress site into a .contentrain store and wire it to a framework";
 }];
 type AgentSkillName = (typeof AGENT_SKILLS)[number]['name'];
 declare const WORKFLOW_SKILLS: readonly ["contentrain-init", "contentrain-model", "contentrain-content", "contentrain-bulk", "contentrain-normalize", "contentrain-validate-fix", "contentrain-review", "contentrain-diff", "contentrain-doctor", "contentrain-serve", "contentrain-translate", "contentrain-generate"];

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AASA;;;;;cAAa,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkBD,cAAA,WAAyB,YAAA;AAAA,cAIxB,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/index.ts"],"mappings":";;AASA;;;;;cAAa,YAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAmBD,cAAA,WAAyB,YAAA;AAAA,cAIxB,eAAA;AAAA,KAeD,aAAA,WAAwB,eAAA;AAAA,cAIvB,gBAAA;AAAA,KACD,cAAA,WAAyB,gBAAA"}

package/dist/index.mjs

@@ -65,6 +65,10 @@ const AGENT_SKILLS = [
 	{
 		name: "contentrain-doctor",
 		description: "Diagnose project health issues"
+	},
+	{
+		name: "contentrain-migrate-wordpress",
+		description: "Import a WordPress site into a .contentrain store and wire it to a framework"
 	}
 ];
 const WORKFLOW_SKILLS = [

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/skills — AI agent skills for Contentrain\n *\n * Agent Skills standard format: SKILL.md + references/ for progressive disclosure.\n * Also includes workflow procedures and framework integration guides.\n */\n\n// ─── Agent Skills Catalog ───\n\nexport const AGENT_SKILLS = [\n  { name: 'contentrain', description: 'Contentrain CMS architecture, content formats, and MCP tool usage' },\n  { name: 'contentrain-normalize', description: 'Two-phase normalize: extract hardcoded strings and patch source files' },\n  { name: 'contentrain-quality', description: 'Content quality, SEO, accessibility, and media rules' },\n  { name: 'contentrain-sdk', description: 'Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access' },\n  { name: 'contentrain-content', description: 'Create and manage content entries for existing models' },\n  { name: 'contentrain-model', description: 'Design and save model definitions' },\n  { name: 'contentrain-init', description: 'Initialize a new Contentrain project' },\n  { name: 'contentrain-bulk', description: 'Batch operations on content entries' },\n  { name: 'contentrain-validate-fix', description: 'Validate content and auto-fix structural issues' },\n  { name: 'contentrain-review', description: 'Review content changes before publishing' },\n  { name: 'contentrain-translate', description: 'Translate content across supported locales' },\n  { name: 'contentrain-generate', description: 'Generate the typed SDK client from models' },\n  { name: 'contentrain-serve', description: 'Start the local review and normalize UI' },\n  { name: 'contentrain-diff', description: 'View content diffs between branches' },\n  { name: 'contentrain-doctor', description: 'Diagnose project health issues' },\n] as const\n\nexport type AgentSkillName = (typeof AGENT_SKILLS)[number]['name']\n\n// ─── Workflow Skills (backward compat) ───\n\nexport const WORKFLOW_SKILLS = [\n  'contentrain-init',\n  'contentrain-model',\n  'contentrain-content',\n  'contentrain-bulk',\n  'contentrain-normalize',\n  'contentrain-validate-fix',\n  'contentrain-review',\n  'contentrain-diff',\n  'contentrain-doctor',\n  'contentrain-serve',\n  'contentrain-translate',\n  'contentrain-generate',\n] as const\n\nexport type WorkflowSkill = (typeof WORKFLOW_SKILLS)[number]\n\n// ─── Framework Guides ───\n\nexport const FRAMEWORK_GUIDES = ['nuxt', 'next', 'astro', 'sveltekit', 'vue', 'react', 'expo', 'react-native', 'node'] as const\nexport type FrameworkGuide = (typeof FRAMEWORK_GUIDES)[number]\n"],"mappings":";;;;;;;AASA,MAAa,eAAe;CAC1B;EAAE,MAAM;EAAe,aAAa;EAAqE;CACzG;EAAE,MAAM;EAAyB,aAAa;EAAyE;CACvH;EAAE,MAAM;EAAuB,aAAa;EAAwD;CACpG;EAAE,MAAM;EAAmB,aAAa;EAAiF;CACzH;EAAE,MAAM;EAAuB,aAAa;EAAyD;CACrG;EAAE,MAAM;EAAqB,aAAa;EAAqC;CAC/E;EAAE,MAAM;EAAoB,aAAa;EAAwC;CACjF;EAAE,MAAM;EAAoB,aAAa;EAAuC;CAChF;EAAE,MAAM;EAA4B,aAAa;EAAmD;CACpG;EAAE,MAAM;EAAsB,aAAa;EAA4C;CACvF;EAAE,MAAM;EAAyB,aAAa;EAA8C;CAC5F;EAAE,MAAM;EAAwB,aAAa;EAA6C;CAC1F;EAAE,MAAM;EAAqB,aAAa;EAA2C;CACrF;EAAE,MAAM;EAAoB,aAAa;EAAuC;CAChF;EAAE,MAAM;EAAsB,aAAa;EAAkC;CAC9E;AAMD,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAMD,MAAa,mBAAmB;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAO;CAAS;CAAQ;CAAgB;CAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * @contentrain/skills — AI agent skills for Contentrain\n *\n * Agent Skills standard format: SKILL.md + references/ for progressive disclosure.\n * Also includes workflow procedures and framework integration guides.\n */\n\n// ─── Agent Skills Catalog ───\n\nexport const AGENT_SKILLS = [\n  { name: 'contentrain', description: 'Contentrain CMS architecture, content formats, and MCP tool usage' },\n  { name: 'contentrain-normalize', description: 'Two-phase normalize: extract hardcoded strings and patch source files' },\n  { name: 'contentrain-quality', description: 'Content quality, SEO, accessibility, and media rules' },\n  { name: 'contentrain-sdk', description: 'Query SDK usage: #contentrain imports, QueryBuilder, type-safe content access' },\n  { name: 'contentrain-content', description: 'Create and manage content entries for existing models' },\n  { name: 'contentrain-model', description: 'Design and save model definitions' },\n  { name: 'contentrain-init', description: 'Initialize a new Contentrain project' },\n  { name: 'contentrain-bulk', description: 'Batch operations on content entries' },\n  { name: 'contentrain-validate-fix', description: 'Validate content and auto-fix structural issues' },\n  { name: 'contentrain-review', description: 'Review content changes before publishing' },\n  { name: 'contentrain-translate', description: 'Translate content across supported locales' },\n  { name: 'contentrain-generate', description: 'Generate the typed SDK client from models' },\n  { name: 'contentrain-serve', description: 'Start the local review and normalize UI' },\n  { name: 'contentrain-diff', description: 'View content diffs between branches' },\n  { name: 'contentrain-doctor', description: 'Diagnose project health issues' },\n  { name: 'contentrain-migrate-wordpress', description: 'Import a WordPress site into a .contentrain store and wire it to a framework' },\n] as const\n\nexport type AgentSkillName = (typeof AGENT_SKILLS)[number]['name']\n\n// ─── Workflow Skills (backward compat) ───\n\nexport const WORKFLOW_SKILLS = [\n  'contentrain-init',\n  'contentrain-model',\n  'contentrain-content',\n  'contentrain-bulk',\n  'contentrain-normalize',\n  'contentrain-validate-fix',\n  'contentrain-review',\n  'contentrain-diff',\n  'contentrain-doctor',\n  'contentrain-serve',\n  'contentrain-translate',\n  'contentrain-generate',\n] as const\n\nexport type WorkflowSkill = (typeof WORKFLOW_SKILLS)[number]\n\n// ─── Framework Guides ───\n\nexport const FRAMEWORK_GUIDES = ['nuxt', 'next', 'astro', 'sveltekit', 'vue', 'react', 'expo', 'react-native', 'node'] as const\nexport type FrameworkGuide = (typeof FRAMEWORK_GUIDES)[number]\n"],"mappings":";;;;;;;AASA,MAAa,eAAe;CAC1B;EAAE,MAAM;EAAe,aAAa;EAAqE;CACzG;EAAE,MAAM;EAAyB,aAAa;EAAyE;CACvH;EAAE,MAAM;EAAuB,aAAa;EAAwD;CACpG;EAAE,MAAM;EAAmB,aAAa;EAAiF;CACzH;EAAE,MAAM;EAAuB,aAAa;EAAyD;CACrG;EAAE,MAAM;EAAqB,aAAa;EAAqC;CAC/E;EAAE,MAAM;EAAoB,aAAa;EAAwC;CACjF;EAAE,MAAM;EAAoB,aAAa;EAAuC;CAChF;EAAE,MAAM;EAA4B,aAAa;EAAmD;CACpG;EAAE,MAAM;EAAsB,aAAa;EAA4C;CACvF;EAAE,MAAM;EAAyB,aAAa;EAA8C;CAC5F;EAAE,MAAM;EAAwB,aAAa;EAA6C;CAC1F;EAAE,MAAM;EAAqB,aAAa;EAA2C;CACrF;EAAE,MAAM;EAAoB,aAAa;EAAuC;CAChF;EAAE,MAAM;EAAsB,aAAa;EAAkC;CAC7E;EAAE,MAAM;EAAiC,aAAa;EAAgF;CACvI;AAMD,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAMD,MAAa,mBAAmB;CAAC;CAAQ;CAAQ;CAAS;CAAa;CAAO;CAAS;CAAQ;CAAgB;CAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -61,8 +61,9 @@
     "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.3.0",
+    "@contentrain/rules": "0.7.1",
+    "@contentrain/wp-import": "0.2.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 | 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,22 +412,26 @@ 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`) |
+| `confirm` | boolean | Conditional | For `delete_entries` (must be `true`; not needed while `dry_run: true`) |
+| `dry_run` | boolean | No | Preview: runs the operation in a throwaway worktree and reports what would change, committing nothing. Default `false` |
 
 #### Operations
 
 | 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
 
+- ALWAYS preview with `dry_run: true` first — the response carries `would_copy` / `would_replace`, `would_update` + `not_found`, or `would_delete` + `files_to_remove`, and nothing survives the run
 - ALWAYS verify the target model with `contentrain_describe` or `contentrain_status` before running bulk
-- `copy_locale` MUST NOT be used on non-i18n models
+- `copy_locale` MUST NOT be used on non-i18n models, and it REPLACES the target locale — `would_replace` in the preview is how many records that costs
 - Bulk operations create branches and commits like other write tools
 - Validate afterward when content shape may have changed
 

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,15 +39,18 @@ 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.
+- **preview first**: `dry_run: true` runs the operation in a throwaway worktree and reports what would change (`would_copy`/`would_replace`, `would_update` + `not_found`, `would_delete` + `files_to_remove`) without committing anything. A preview needs no `confirm`
+- `copy_locale` REPLACES the target locale — the preview's `would_replace` is how many records that costs
 - confirm entry IDs before delete operations
 - batch only related entries together
 
@@ -85,7 +88,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-migrate-wordpress/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: contentrain-migrate-wordpress
+description: "Import a WordPress site into a .contentrain content store and wire it to a framework. Use when migrating from WordPress, running contentrain import, handling a WXR export or REST URL, or connecting imported content to Astro, Nuxt or Next."
+metadata:
+  author: Contentrain
+  version: "1.0.0"
+---
+
+# Skill: Migrate a WordPress Site
+
+> WordPress content → canonical `.contentrain` store → validated → typed client or Astro collections.
+
+---
+
+## When to Use
+
+The user wants to move a WordPress site's **content** into Contentrain: "import my WordPress site", "migrate from WP", "I have a WXR export", "pull posts from wordpress.com", "turn this WP blog into Astro".
+
+**This skill moves content, not design.** Themes, page-builder layouts and rendered HTML are a different problem (a full site clone is the Contentrain migration service). What this skill produces is a clean content store the user's own frontend reads.
+
+---
+
+## Steps
+
+### 1. Pick the source
+
+Two sources, and the choice is usually made for you:
+
+| Source | Use when | Command |
+|---|---|---|
+| **REST URL** | The site is online and `/wp-json/wp/v2/` answers | `npx contentrain import https://example.com` |
+| **WXR export** | The site is offline, behind auth, or the user has a `.xml` from Tools → Export | `npx contentrain import ./export.xml` |
+
+REST returns more than WXR (rendered HTML, media metadata, per-type discovery); WXR is complete but rawer. If both exist, prefer REST.
+
+**Private or partial REST.** A site can answer `/wp-json` but hide drafts, private types and some fields. An Application Password lifts the run to `rest_auth`:
+
+```bash
+npx contentrain import https://example.com --auth "user:xxxx xxxx xxxx xxxx"
+```
+
+Check first, so you tell the user what they will get rather than discovering it after:
+
+```bash
+curl -s "https://example.com/wp-json/wp/v2/types" | head -c 400
+```
+
+A `401`/`403` means auth is needed. A `404` or an HTML page means REST is disabled or blocked — use WXR.
+
+### 2. Import
+
+```bash
+npx contentrain import <source> --out ./my-site
+```
+
+`--force` is required to overwrite an existing `.contentrain/`. **Never pass it without asking** — it replaces models and content the user may have edited.
+
+What lands on disk:
+
+- `.contentrain/models/*.json` + `.contentrain/content/**` — the canonical store
+- `import-report.json` — what was inferred, rewritten or dropped
+- `entry-source-map.json` — `wp_post_id → { model_id, entry_id }`, the only record connecting the new store to the old site
+- `comments-export.json` — written when the source has comments (`contentrain-comments@1`)
+
+Models the importer creates: `posts`, `pages` (and one collection per custom post type), `authors`, `media`, `menus`, `menu-items`, `comments`, a `site` singleton, and one collection per taxonomy.
+
+### 3. Read the report before declaring success
+
+Open `import-report.json` and tell the user what it says. These fields decide whether the import is usable:
+
+| Field | Means | What to do |
+|---|---|---|
+| `skipped_types` | Post types not imported | Ask if any are needed; a second run with `--auth` may reach them |
+| `dropped_relations` | Relations pointing outside the import | Usually a partial import — check the skipped types first |
+| `slug_rewritten` / `slug_fallback` | Slugs changed to be valid | Affects URLs → the user needs redirects |
+| `title_fallback` | Entries that had no title | They exist but are unlabelled; worth a pass |
+| `acf_fields` / `meta_fields` | Custom fields found and their inferred types | Verify the types match intent before content is edited |
+
+**Known gap:** post bodies carry Gutenberg block comments and shortcodes verbatim. They render as-is in HTML but they are WordPress syntax, not portable content. Say so — do not present the import as clean markup when it is not.
+
+### 4. Validate
+
+```bash
+npx contentrain validate
+```
+
+Fix what it reports before anything reads the store. Structural problems are cheapest here, and the SDK generator will refuse a broken store anyway. See `contentrain-validate-fix` for the fix loop.
+
+### 5. Wire the content to the framework
+
+**Astro** — the content layer, no client generation:
+
+```ts
+// src/content.config.ts
+import { defineCollection, z } from 'astro:content'
+import { contentrainLoader } from '@contentrain/query/astro'
+
+export const collections = {
+  posts: defineCollection({
+    loader: contentrainLoader({ model: 'posts' }),
+    schema: z.object({ title: z.string(), slug: z.string() }).passthrough(),
+  }),
+}
+```
+
+Then `getCollection('posts')` in pages. Documents also get `<Content />`.
+
+**Everything else** (Nuxt, Next, SvelteKit, plain Node) — the generated client:
+
+```bash
+npx contentrain generate
+```
+
+```ts
+import { query } from '#contentrain'
+const posts = query('posts').where('status', '=', 'published').all()
+```
+
+See `contentrain-generate` for the generator and `contentrain-sdk` for the query API.
+
+### 6. Hand back what is still open
+
+Close the loop honestly. Three things survive the import and need a decision:
+
+1. **Comments.** `comments-export.json` is a payload, not a running service. Either a comments service imports it, or comments stay on WordPress, or they are dropped. The user chooses.
+2. **URLs.** Any rewritten slug is a broken inbound link. `entry-source-map.json` plus the report's slug counts are what a redirect list is built from.
+3. **Media.** The importer records media metadata; the files themselves still live on the old host until they are moved.
+
+---
+
+## Guardrails
+
+- **Read the report, always.** An import that "worked" while dropping half the post types is worse than one that failed — it looks finished.
+- **`--force` is destructive.** Ask first, every time.
+- **Never invent content.** If a field is empty after import, it was empty (or unreachable) in the source. Say that instead of filling it.
+- **Do not edit `entry-source-map.json`.** It is the only link back to the WordPress ids; comments intake and redirects both read it.
+- **Re-importing is not syncing.** A second import overwrites; it does not merge changes made in Contentrain since the first one.
+
+---
+
+## Related
+
+- `contentrain-validate-fix` — the validation loop
+- `contentrain-generate` — typed client generation
+- `contentrain-sdk` — querying the generated client
+- `contentrain-model` — reshaping the imported models
+- `references/wordpress-mapping.md` — how WordPress concepts land in Contentrain

package/skills/contentrain-migrate-wordpress/references/wordpress-mapping.md

@@ -0,0 +1,87 @@
+# WordPress → Contentrain mapping
+
+What `contentrain import` actually produces, so you can answer "where did my X go?" without opening the importer.
+
+## Models
+
+| WordPress | Contentrain model | Kind | Domain |
+|---|---|---|---|
+| Posts | `posts` | collection | `blog` |
+| Pages | `pages` | collection | `blog` |
+| Custom post type `event` | `event` | collection | `blog` |
+| Categories | `categories` | collection | `blog` |
+| Tags | `tags` | collection | `blog` |
+| Custom taxonomy `product_line` | `product-line` | collection | `blog` |
+| Users | `authors` | collection | `blog` |
+| Media library | `media` | collection | `assets` |
+| Menus | `menus` + `menu-items` | collection | `site` |
+| Comments | `comments` | collection | `blog` |
+| Site title / tagline / URL / language | `site` | **singleton** | `site` |
+
+Every model is `i18n: false`. WordPress multilingual plugins (WPML, Polylang) keep translations as separate posts, so they arrive as separate entries — not as locales. Reshaping them into one i18n model is a modelling decision the agent makes with the user, not something the importer guesses.
+
+## Post fields
+
+Fields are added **only when at least one entry in that post type has the data**, so an import of a site without excerpts has no `excerpt` field at all.
+
+| Field | Type | Present when |
+|---|---|---|
+| `title` | string (required) | always |
+| `slug` | slug (required, unique) | always |
+| `excerpt` | text | any entry has an excerpt |
+| `body` | richtext | any entry has content |
+| `published_at` | datetime | any entry has a date |
+| `author` | relation → `authors` | any entry has an author |
+| `<taxonomy>` | relations → that taxonomy | the type uses that taxonomy |
+| `cover` | relation → `media` | any entry has a featured image |
+| `wp_id` | integer (required, unique) | always |
+| `modified_at` | datetime | always |
+| `link` | url | always — the original permalink |
+| `parent` | relation → same model | any entry has a parent |
+| `menu_order`, `sticky`, `template` | integer / boolean / string | the source uses them |
+| `format` | select | the type uses post formats |
+| `visibility` | select `public\|private\|password` | any entry is private or password-protected |
+| `comments_open` | boolean | the source carries comment status |
+
+## Status
+
+WordPress status becomes Contentrain meta, not a field:
+
+| WP | Contentrain |
+|---|---|
+| `publish`, `inherit` | `published` |
+| `future` | `draft` + `publish_at` (the scheduled date survives) |
+| `pending` | `in_review` |
+| `trash` | `archived` |
+| everything else (`draft`, `private`, …) | `draft` |
+
+Comments map by approval: `1` → published · `spam`/`trash` → archived · anything else → `in_review`.
+
+## Custom fields
+
+- **Open meta keys** become fields with a type inferred from the value, and are listed in `import-report.json → meta_fields`.
+- **ACF fields** become fields tagged `description: "ACF"`, listed under `acf_fields`. Object-shaped values land as `object`.
+- **Underscore-prefixed meta** (`_edit_lock`, `_thumbnail_id`, `_elementor_*`, …) is WordPress plumbing and is dropped.
+- **Plugin meta** matching `jetpack|wpdc|discourse|footnotes|inline_featured|spay_|advanced_seo|rank_math|yoast` is dropped — it is plugin state, not editorial content.
+
+Inferred types are a guess from one value. Check `meta_fields` and `acf_fields` in the report before anyone edits content: fixing a wrong type later means touching every entry.
+
+## What is not imported
+
+Post types matching `attachment|nav_menu_item|wp_*|jp_*|pattern|revision|oembed_cache|customize_changeset|user_request|custom_css` are skipped and listed in `report.skipped_types`. Attachments are not skipped content — they arrive as the `media` collection.
+
+Also outside the import: themes, widgets, plugin settings, users' passwords and roles, and the media **files** themselves (only their metadata and URLs come across).
+
+## Ids and the link back
+
+Entry ids are deterministic hex derived from the WordPress id (`media:12`, `comments:34`, `menus:<slug>`), so re-running an import produces the same ids. `entry-source-map.json` records `wp_post_id → { model_id, entry_id }` — it is what a comments intake and a redirect list are built from, and nothing else records it.
+
+## Relations that point nowhere
+
+A relation whose target was not part of the import (a comment on a skipped post type, a term never listed) is either dropped and counted in `report.dropped_relations`, or — for terms referenced but not listed — added to the pool from the reference itself. A high `dropped_relations` usually means the import was partial: check `skipped_types` and whether `--auth` would reach more.
+
+## Known gaps
+
+- **Gutenberg and shortcodes** stay verbatim in `body`. `<!-- wp:paragraph -->` and `[gallery]` render as-is in HTML but they are WordPress syntax; converting them is a separate pass.
+- **Media files** stay on the old host until moved.
+- **Redirects** are not generated. `slug_rewritten` + `slug_fallback` in the report say how many URLs changed.

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:

package/workflows/contentrain-bulk.md

@@ -38,6 +38,8 @@ Confirm:
 
 - never use `copy_locale` on non-i18n models
 - `update_status` and `delete_entries` are collection-only
+- **preview first**: `dry_run: true` runs the operation in a throwaway worktree and reports what would change (`would_copy`/`would_replace`, `would_update` + `not_found`, `would_delete` + `files_to_remove`) without committing anything. A preview needs no `confirm`
+- `copy_locale` REPLACES the target locale — the preview's `would_replace` is how many records that costs
 - confirm entry IDs before delete operations
 - batch only related entries together