@contentrain/skills 0.9.4 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentrain/skills",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "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.4.3",
-    "@contentrain/rules": "0.7.2",
-    "@contentrain/wp-import": "0.4.6"
+    "@contentrain/mcp": "3.10.1",
+    "@contentrain/rules": "0.7.3",
+    "@contentrain/wp-import": "0.13.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

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

@@ -36,9 +36,11 @@ REST returns more than WXR (rendered HTML, media metadata, per-type discovery);
 **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"
+CONTENTRAIN_WP_APP_PASSWORD="xxxx xxxx xxxx xxxx" npx contentrain import https://example.com --auth user
 ```
 
+Ask the user to set the password in the environment (or run the command themselves for the hidden prompt). Never put `user:password` on the command line: it lands in shell history. A WXR import leaves author and commenter e-mail addresses out of the store; add `--include-emails` only when the user asks and the repository stays private.
+
 Check first, so you tell the user what they will get rather than discovering it after:
 
 ```bash
@@ -76,7 +78,7 @@ Open `import-report.json` and tell the user what it says. These fields decide wh
 | `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.
+**Known gap:** post bodies carry shortcodes (`[gallery]`) verbatim: WordPress syntax, not portable content. Gutenberg block delimiters are stripped (the markup stays); self-closing server-rendered blocks (`wp:latest-posts`, `wp:block`) leave nothing and are counted in `blocks_dynamic_dropped`. Say so — do not present the import as clean markup when shortcodes remain.
 
 ### 4. Validate
 

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

@@ -76,7 +76,7 @@ Inferred types are a guess from one value. Check `meta_fields` and `acf_fields`
 
 ## 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`, and so are theme / page-builder internals that store design rather than content: GeneratePress elements (`gp_elements`, `gp-elements`), GenerateBlocks styles (`gblocks_*`, `gblocks-*`), Elementor templates (`elementor_library`, `e-landing-page`) and form definitions (`wpcf7_contact_form`, `wpforms*`). Membership and other content-bearing CPTs stay; ACF field records stay too, since their cross-model parents are part of the lossless import. Attachments are not skipped content — they arrive as the `media` collection.
+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`, and so are theme / page-builder internals that store design rather than content: GeneratePress elements (`gp_elements`, `gp-elements`), GenerateBlocks styles (`gblocks_*`, `gblocks-*`), Elementor templates (`elementor_library`) and form definitions (`wpcf7_contact_form`, `wpforms*`). Elementor landing pages (`e-landing-page`) are not internals: they are public pages at `/<slug>/`, so they import as `page` — into the `pages` model, with their slug, permalink (`link`) and meta, sharing the page address space (a clash gets the usual slug move). Over REST the type is listed only when it is `show_in_rest`; a site that hides it must be imported from a WXR export. Membership and other content-bearing CPTs stay; ACF field records stay too, since their cross-model parents are part of the lossless import. 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).
 
@@ -90,6 +90,6 @@ A relation whose target was not part of the import (a comment on a skipped post
 
 ## 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.
+- **Gutenberg block delimiters** (`<!-- wp:… -->`, `<!-- /wp:… -->`) are stripped from `body`; the markup inside every block stays. Self-closing, server-rendered blocks (`wp:latest-posts`, `wp:block`, `wp:query`) hold no markup and disappear: `blocks_dynamic_dropped` in the report counts them by name. **Shortcodes** (`[gallery]`) stay verbatim in `body`; 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-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