@contentrain/skills 0.9.3 → 0.9.5

package/README.md

@@ -1,7 +1,7 @@
 # `@contentrain/skills`
 
 [![npm version](https://img.shields.io/npm/v/%40contentrain%2Fskills?label=%40contentrain%2Fskills)](https://www.npmjs.com/package/@contentrain/skills)
-[![Agent Skills](https://img.shields.io/badge/Agent_Skills-15_skills-8B5CF6)](https://agentskills.io)
+[![Agent Skills](https://img.shields.io/badge/Agent_Skills-16_skills-8B5CF6)](https://agentskills.io)
 [![GitHub source](https://img.shields.io/badge/source-Contentrain%2Fai-181717?logo=github)](https://github.com/Contentrain/ai/tree/main/packages/skills)
 [![Docs](https://img.shields.io/badge/docs-ai.contentrain.io-0f172a)](https://ai.contentrain.io/packages/skills)
 
@@ -45,7 +45,7 @@ Works with Claude Code, Cursor, Windsurf, GitHub Copilot, OpenAI Codex, Gemini C
 
 ### Agent Skills (standard format)
 
-Published under `skills/` — 15 production skills:
+Published under `skills/` — 16 production skills:
 
 | Skill | Description |
 |-------|-------------|
@@ -128,7 +128,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 26: 21 core + 5 media).
+- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 27: 22 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.9.3",
+  "version": "0.9.5",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -61,9 +61,9 @@
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@contentrain/mcp": "3.3.3",
-    "@contentrain/rules": "0.7.2",
-    "@contentrain/wp-import": "0.4.1"
+    "@contentrain/mcp": "3.9.0",
+    "@contentrain/rules": "0.7.3",
+    "@contentrain/wp-import": "0.9.4"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

package/skills/contentrain/SKILL.md

@@ -12,16 +12,19 @@ Contentrain is a Git-based, AI-first content management system. Content lives in
 
 ## Ecosystem Overview
 
-Contentrain consists of 6 packages that work together:
+Contentrain consists of 9 packages that work together:
 
 | Package | Role | How agent uses it |
 |---|---|---|
-| @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/mcp | 27 MCP tools (scan, apply, validate, merge, reconcile, doctor...) | MCP tool calls |
+| contentrain (CLI) | init, serve, generate, doctor, diff, status, import | Shell commands |
 | @contentrain/types | Shared TypeScript contracts | Type safety |
 | @contentrain/query | Generated SDK client (Prisma-pattern) | `import from '#contentrain'` |
-| @contentrain/rules | Behavioral guardrails (~86 lines, always-loaded) | Auto-loaded by IDE |
+| @contentrain/rules | Behavioral guardrails (~145 lines, always-loaded) | Auto-loaded by IDE |
 | @contentrain/skills | Procedural workflows (this file) | On-demand by agent |
+| @contentrain/wp-import | WordPress WXR/REST → `RawIR` → a `.contentrain` store | `contentrain import wordpress` |
+| @contentrain/emitter-astro | `ProjectIR` → a complete Astro project | Called by the migration engine |
+| @contentrain/verify | Offline SEO, indexing, link and asset gates for a built site | `npx @contentrain/verify dist` |
 
 ### CLI Serve — Review & Approval Bridge
 

package/skills/contentrain/references/content-formats.md

@@ -196,8 +196,9 @@ Several fields are managed by the platform. Agents MUST NOT set or modify them.
 | `i18n: false` on model | Single file: `data.json` (or `{slug}.md` for documents) |
 | Locale code | ISO 639-1: `en`, `tr`, `de`, `fr`, `ja`, `ar` |
 | ID/slug are locale-agnostic | Same entry ID or document slug across all locales |
-| Entry parity (collections) | All locales MUST have the same set of entry IDs |
-| Key parity (dictionaries) | All locales MUST have the same set of keys |
+| Entry parity (collections) | All covered locales MUST have the same set of entry IDs |
+| Key parity (dictionaries) | All covered locales MUST have the same set of keys |
+| `locales` on model (optional) | The project locales this model covers — a subset of `locales.supported`. Absent means all of them. Parity is checked against it |
 
 ### Validation Checks
 

package/skills/contentrain/references/i18n.md

@@ -15,7 +15,8 @@ Every rule applies whenever the project has more than one locale configured.
 ### 1.1 Coverage Requirement
 
 - Read `.contentrain/config.json` → `locales.supported` to determine the full list of supported locales.
-- EVERY entry that exists in the source locale MUST have a corresponding entry in ALL supported target locales.
+- A model MAY narrow that list with an optional `locales` array (a subset of `locales.supported`). When present, it — not the project list — is the model's coverage. Absent means every supported locale.
+- EVERY entry that exists in the source locale MUST have a corresponding entry in ALL of the model's covered target locales.
 - Missing translations are deployment blockers. Treat a missing locale file as an error, not a warning.
 
 ### 1.2 Dictionary Entries

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 |
+| `locales` | string[] | No | The project locales this model covers — a subset of `config.locales.supported`. Absent means all of them, which is what parity is validated against. Declare it only for a genuinely partial model (a partially-translated site) |
 | `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 |

package/skills/contentrain/references/schema-types.md

@@ -97,8 +97,8 @@ In v1, media fields store URL/path strings only. Upload and processing are out o
 
 | Type | Cardinality | Storage |
 |------|-------------|---------|
-| `relation` | One-to-one | `"entry-id"` (string) |
-| `relations` | One-to-many | `["id-1", "id-2"]` (string array) |
+| `relation` | One-to-one | `"entry-id"` (string); `{ "model": "page", "ref": "entry-id" }` when `model` lists several targets |
+| `relations` | One-to-many | `["id-1", "id-2"]` (string array); `[{ "model", "ref" }, …]` when `model` lists several targets |
 
 ### Relation Examples
 

package/skills/contentrain-quality/references/media.md

@@ -14,7 +14,7 @@ Follow these guidelines when populating image, video, or file fields in any cont
 
 Media references are stored in one of two models. Identify which one the project uses before populating image, video, or file fields. The asset rules below (dimensions, formats, size limits, naming) apply to **both**; only the **Asset Organization** section (paths under `assets_path`, relative references) is specific to the local-file model.
 
-1. **Local file model (default / OSS).** Media lives on disk under `config.json > assets_path` (default `.contentrain/assets/`) and is referenced by a **relative path from the project root** (e.g. `.contentrain/assets/blog/hero.webp`). To turn relative paths into URLs at read time, set `config.json > cdn.url` (or `contentrain generate --cdnBaseUrl <base>`) and use the `media()` resolver baked into the `@contentrain/query` generated client — `media('media/...') → {cdn.url}/{path}`.
+1. **Local file model (default / OSS).** Media lives on disk under `config.json > assets_path` (default `.contentrain/assets/`) and is referenced by a **relative path from the project root** (e.g. `.contentrain/assets/blog/hero.webp`). To turn relative paths into URLs at read time, set `config.json > cdn.url` (or `contentrain generate --mediaBaseUrl <base>`) and use the `media()`/`mediaBody()` resolvers baked into the `@contentrain/query` generated client — `media('media/...') → {mediaBaseUrl}/{path}`, `mediaBody(markdown)` for `](media/...)` references inside markdown. The Astro loader (`contentrainLoader({ mediaBaseUrl })`) applies the same resolver automatically to media fields and markdown bodies.
 
 2. **Studio CDN model.** Media lives in the Studio CDN/object store and is referenced by a relative storage path (`media/...`) returned by the media library. Pass either that `media/...` path or its URL to `contentrain_content_save`: in **cloud mode** the value is **automatically normalized to an absolute public delivery URL** on save (`{base}/{path}`), in both media fields and markdown bodies, so the committed content renders in a browser anywhere with no SDK. In **local mode** the relative path is kept verbatim. The rewrite is idempotent and never touches external URLs (`http(s)://`, `//`, `data:`) or already-absolute delivery URLs — so for external images (a CDN or Unsplash URL), just save the URL directly.
 

package/skills/contentrain-sdk/SKILL.md

@@ -83,16 +83,19 @@ const doc = document('blog-post').bySlug('getting-started')
 Media / image / file field values are plain strings. How you turn them into a URL depends on the storage model:
 
 - **Studio-CDN content** already carries absolute delivery URLs — the write path normalizes `media/...` references on save — so use the field value directly, no resolution needed.
-- **Relative-path content** (OSS / local-file model, values like `media/...`) resolves through an optional `media()` helper baked into the generated client. Set `config.json > cdn.url` (or run `contentrain generate --cdnBaseUrl <base>`) and the client exports it:
+- **Relative-path content** (OSS / local-file model, values like `media/...`) resolves through optional `media()`/`mediaBody()` helpers baked into the generated client. Set `config.json > cdn.url` (or run `contentrain generate --mediaBaseUrl <base>`) and the client exports them:
 
 ```typescript
-import { media } from '#contentrain'
+import { media, mediaBody } from '#contentrain'
 
-media('media/original/hero.webp')          // → '{cdn.url}/media/original/hero.webp'
+media('media/original/hero.webp')          // → '{mediaBaseUrl}/media/original/hero.webp'
 media('https://images.unsplash.com/x.jpg') // → unchanged (external pass-through)
+mediaBody('See ![cover](media/hero.webp)') // → resolves `](media/...)` refs inside markdown
 ```
 
-`media()` is omitted when no base is configured, and is idempotent — external URLs (`http(s)://`, `//`, `data:`) and already-absolute delivery URLs pass through untouched. It is the **local-mode** counterpart of CDN mode's `client.media()` (which returns a `MediaAccessor` over the media manifest, below).
+Both take an optional second argument overriding the baked base for that call — a Nuxt app passes its own `useRuntimeConfig()` value here instead of rebaking per environment. The Astro loader (`contentrainLoader({ mediaBaseUrl })`) applies the same resolver automatically.
+
+`media()`/`mediaBody()` do not exist on the client at all when no base is configured at generate time — not a pass-through, an absent export. A host that never bakes a base in (reading it purely from its own runtime config or env, e.g. Nuxt) must import `resolveMediaUrl(value, base)` / `resolveMediaRefsInBody(markdown, base)` from `@contentrain/query` directly instead of going through the generated client. Both take a nullable base and no-op when it is absent, so calling them unconditionally is safe. `media()`, when present, is idempotent — external URLs (`http(s)://`, `//`, `data:`) and already-absolute delivery URLs pass through untouched. It is the **local-mode** counterpart of CDN mode's `client.media()` (which returns a `MediaAccessor` over the media manifest, below).
 
 ## CDN Mode (Remote Data)
 
@@ -189,7 +192,7 @@ const history = await conv.history(response.conversationId)
 - Locale fallback chain: explicit → config default → first available
 - Generated files in `.contentrain/client/` are **immutable** — always regenerate, never edit
 - Run `contentrain generate` after any model change
-- **Media**: Studio-CDN fields already carry absolute URLs; for relative `media/...` values set `config.cdn.url` (or `generate --cdnBaseUrl`) and resolve with the generated `media()` helper
+- **Media**: Studio-CDN fields already carry absolute URLs; for relative `media/...` values set `config.cdn.url` (or `generate --mediaBaseUrl`) and resolve with the generated `media()`/`mediaBody()` helpers
 
 ## Framework Integration
 

package/workflows/contentrain-model.md

@@ -120,7 +120,9 @@ Example:
 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.
+`"key"` — the entry key is the title. A singleton made of section objects
+(`hero`, `services`) names a section's heading with a dotted path,
+`"hero.heading"` — one level into an `object` field, never an array.
 
 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