@contentrain/skills 0.5.2 → 0.6.0

package/README.md

@@ -127,7 +127,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 17).
+- `skills/contentrain/references/mcp-tools.md` must have an `### <tool>` heading for every tool in the MCP `TOOL_NAMES` registry (currently 24: 19 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.5.2",
+  "version": "0.6.0",
   "license": "MIT",
   "description": "AI agent skills for Contentrain — workflow procedures, framework integration guides",
   "type": "module",
@@ -61,7 +61,7 @@
     "tsdown": "^0.21.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0",
-    "@contentrain/mcp": "1.5.2"
+    "@contentrain/mcp": "1.10.0"
   },
   "scripts": {
     "build": "tsdown src/index.ts --format esm,cjs --dts",

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

@@ -357,3 +357,67 @@ Run git-backed batch operations on existing content entries.
 - `copy_locale` MUST NOT be used on non-i18n models
 - Bulk operations create branches and commits like other write tools
 - Validate afterward when content shape may have changed
+
+## Media Tools
+
+Media tools are a deterministic passthrough to the provider's media stack. They are **registered only when the provider exposes one** (e.g. Studio MCP Cloud) — local stdio servers and plain GitHub/GitLab providers never list them. The flow: list assets → pick a `media/...` path → reference it in media/image/file fields via `contentrain_content_save` (paths are normalized to absolute delivery URLs when the provider sets `mediaBaseUrl`).
+
+### contentrain_media_list
+
+List media assets with optional filtering and cursor pagination. Read-only.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `search` | string | No | Substring match on filename/path/alt |
+| `tag` | string | No | Only assets carrying this tag |
+| `limit` | number | No | Page size (1–100, provider may clamp) |
+| `cursor` | string | No | Opaque cursor from a previous response |
+
+Returns `{ assets[], next_cursor?, total? }`. Each asset carries `id`, `path` (`media/...`), optional `url`, `mime`, `size`, `alt`, `tags`, `createdAt`, `meta`.
+
+### contentrain_media_get
+
+Get a single media asset by id. Read-only.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Asset id from `contentrain_media_list` |
+
+Returns `{ asset }` or an error with a discovery hint for unknown ids.
+
+### contentrain_media_ingest
+
+Ingest an asset from a source URL. The provider fetches the URL server-side under its own SSRF/MIME/size policy — MCP never fetches it. The only open-world tool (`openWorldHint: true`).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | Source URL to fetch server-side |
+| `filename` | string | No | Target filename override |
+| `alt` | string | No | Alt text |
+| `tags` | string[] | No | Tags to attach (max 20) |
+
+Returns `{ status: "ingested", asset }` — use `asset.path` in content fields afterward.
+
+### contentrain_media_update
+
+Update asset metadata. Never touches the binary.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Asset id to update |
+| `alt` | string | No | New alt text |
+| `tags` | string[] | No | Replacement tag list (max 20) |
+| `filename` | string | No | New filename |
+
+Returns `{ status: "updated", asset }`.
+
+### contentrain_media_delete
+
+Delete an asset from the media stack. Destructive — content entries referencing its path are NOT rewritten; check references first with `contentrain_content_list`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Asset id to delete |
+| `confirm` | boolean | Yes | Must be `true` to confirm |
+
+Returns `{ status: "deleted", id }`.

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

@@ -10,6 +10,18 @@ Follow these guidelines when populating image, video, or file fields in any cont
 
 ---
 
+## Storage & Reference Models
+
+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}`.
+
+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.
+
+Never hand-build delivery URLs or guess the CDN base. Save the path or URL the media library gives you; the platform resolves it.
+
+---
+
 ## Image Dimensions (Recommended)
 
 1. Use these standard dimensions unless the project's `context.json` specifies overrides:

package/skills/contentrain-sdk/SKILL.md

@@ -78,6 +78,22 @@ const doc = document('blog-post').bySlug('getting-started')
 | `.where(field, op, value)` | Operator filter (same ops as QueryBuilder) |
 | `.include(relation)` | Resolve relation fields |
 
+### Media
+
+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:
+
+```typescript
+import { media } from '#contentrain'
+
+media('media/original/hero.webp')          // → '{cdn.url}/media/original/hero.webp'
+media('https://images.unsplash.com/x.jpg') // → unchanged (external pass-through)
+```
+
+`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).
+
 ## CDN Mode (Remote Data)
 
 For server-side or client-side apps that fetch content from Contentrain Studio CDN:
@@ -151,6 +167,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
 
 ## Framework Integration