@contentrain/skills 0.8.1 → 0.9.1

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.1",
+  "version": "0.9.1",
   "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.1.8",
-    "@contentrain/rules": "0.7.1"
+    "@contentrain/mcp": "3.3.1",
+    "@contentrain/rules": "0.7.1",
+    "@contentrain/wp-import": "0.2.2"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

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

@@ -416,7 +416,8 @@ Run git-backed batch operations on existing content 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
 
@@ -428,8 +429,9 @@ Run git-backed batch operations on existing content entries.
 
 #### 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-bulk/SKILL.md

@@ -49,6 +49,8 @@ Confirm:
 - `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
 

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

@@ -143,7 +143,7 @@ works bundled behaves the same on CDN.
 | `in` | `.where('category', 'in', ['a','b'])` | In array |
 | `contains` | `.where('tags', 'contains', 'vue')` | String/array contains |
 
-### CDN Entry Metadata, Media & Forms
+### CDN Entry Metadata, Media, Forms & Comments
 
 ```typescript
 // Entry metadata (status, publish_at, expire_at)
@@ -154,10 +154,16 @@ const media = client.media()
 const asset = await media.asset('hero.jpg')
 const url = media.url(asset, 'thumb')
 
-// Forms (config fetch + submit)
+// Forms — public /api/forms/v1, no API key (values go under `data`; captcha + honeypot beside it)
 const form = client.form()
-const config = await form.config('contact')
-const result = await form.submit('contact', { name: 'Alice' })
+const config = await form.config('contact')   // fields keyed by id, captcha, captchaSiteKey, honeypotField
+const result = await form.submit('contact', { name: 'Alice' }, { captchaToken, honeypot: '' })
+// { success, message } | { success: false, errors: [{ field, message }] }; 403/404/429 throw ContentrainError
+
+// Comments — public /api/comments/v1, approved comments only, body is plain text (render escaped)
+const comments = client.comments()
+const thread = await comments.thread('posts', entryId, { locale: 'en' })
+await comments.submit('posts', entryId, { author: { name: 'Ada', email }, body: 'Great post', parentId }, { locale: 'en' })
 
 // Conversation API (external AI content operations)
 const conv = client.conversation()

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