@se-studio/contentful-cms 3.9.3 → 3.10.0

package/docs/mcp/hosted-guide.md

@@ -20,7 +20,7 @@ All `save` operations create **drafts only**. A human must review and publish in
 | Tool | Purpose |
 |------|---------|
 | `cms_edit` | Run any cms-edit command via an `args` array |
-| `cms_edit_request_staged_upload` | Get a presigned upload URL for binary files (then `curl` + `asset upload --staged`) |
+| `cms_edit_request_staged_upload` | Presigned URL for binaries. Raster/video: then `cms_edit_media` prepare. SVG/PDF/Lottie: then `asset upload --staged` |
 | `cms_edit_version` | Check the installed cms-edit version (no session required) |
 | `cms_edit_help` | Guide topics (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) **or** playbooks (`create-from-json`, `fields-component`, …) |
 
@@ -130,7 +130,7 @@ Always run `diff` before `save`. To abandon changes: `["discard"]`.
 | Task | Where |
 |------|-------|
 | Edit copy, add sections, create pages/articles | **Agent + cms-edit** (drafts) |
-| Upload new images and files | **Agent + cms-edit** (`asset upload`) — search/reuse first |
+| Upload new images and files | **Agent + cms-edit** — search/reuse first; raster/video via `cms_edit_media` import |
 | Publish approved drafts | **Contentful UI** |
 | Edit copy directly in Contentful | **Avoid** — use cms-edit instead |
 
@@ -138,12 +138,13 @@ cms-edit saves **drafts only**. A colleague must **publish in Contentful** for c
 
 ## Asset upload (hosted MCP)
 
-Hosted connectors have **no server filesystem** and **reject `asset upload --base64`**. Use staged upload for all images and binary files.
+Hosted connectors have **no server filesystem** and **reject `asset upload --base64`**. Raster/video: staged intake then **media pipeline**. SVG/PDF/Lottie: staged then `asset upload --staged`.
 
 | Source | When | Example |
 |--------|------|---------|
-| **Staged upload** (required for binary) | All images and files on hosted MCP | See **Staged upload** below |
-| **`--url`** (last resort) | File already on public HTTPS fetchable by the host | `["asset", "upload", "--url", "https://…/photo.png", "--mime", "image/png", "--file-name", "photo.png"]` |
+| **Staged + pipeline** | jpeg/png/webp/gif/mp4 | `cms_edit_media` prepare `stagedUploadIds` → import (required for video) |
+| **`--url`** | Pipeline-ready **images** only, or SVG/PDF | `["asset", "upload", "--url", "https://….blob.vercel-storage.com/ready.jpg"]` |
+| **Staged consume** | SVG/PDF/Lottie | `asset upload --staged` |
 
 **After upload:** note the returned asset `id`, attach to the entry (`asset set @root media <id>` for person portraits), then `diff` → `save`. Upload alone does not update entries.
 
@@ -168,10 +169,10 @@ Keeps binary **out of MCP tool args**. The agent uploads via `curl`, then passes
 
 1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
 2. Run the returned `curlCommand` in a shell (POST multipart to `uploadUrl`)
-3. `cms_edit` with the returned `consumeArgs` (includes `asset upload --staged <uploadId>`)
-4. Link and save as usual
+3. Follow `consumeArgs`: **media prepare** (`cms_edit_media` / `media prepare --staged-ids`) for jpeg/png/webp/gif/mp4; **asset upload --staged** for SVG/PDF/Lottie
+4. For pipeline jobs: wait → catalog → **import** (required for video). Then link and save
 
-Hosted limit: **4 MB** per staged file (Vercel body limit). Rate limit: **1000 upload URLs per user per hour**. TTL: **60 minutes**, single-use.
+Hosted limit: **4 MB** per staged file (Vercel body limit). Rate limit: **1000 upload URLs per user per hour**. TTL: **60 minutes**. Raster/video staged files are intake (GET by the pipeline); they are not consumed into CMA.
 
 ## Featured images (articles)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.9.3",
+  "version": "3.10.0",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",

package/skills/core/SKILL.md

@@ -31,7 +31,8 @@ Use this skill when you need to read or edit content in Contentful using **hoste
 All `save` operations create **draft** versions. A human must review and publish in Contentful.
 
 **Assets:** Upload **is** supported (`asset upload`). Default workflow: **search and reuse** existing assets first (`index sync` → `asset search`). When uploading:
-- **Hosted MCP:** always `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
+- **Raster/video:** `cms_edit_request_staged_upload` → curl → `cms_edit_media` prepare (`stagedUploadIds`) → wait → catalog → import with real alt. Never `asset upload --staged/--url/--base64` for jpeg/png/webp/gif/mp4.
+- **SVG/PDF/Lottie:** `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
 - Use a **sensible fileName** and **descriptive title** (and alt text where the site uses it)
 - Avoid oversized images — width over **2000px** is usually wasteful for web (exact limits vary by project; check `asset audit` / media review guidance)
 - Prefer `--if-exists-by-filename` to avoid duplicates
@@ -371,13 +372,8 @@ cms-edit asset search "hero background"
 cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
-# Local CLI — URL or base64 (hosted MCP rejects --base64)
-cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
-cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
-
-# Hosted MCP — always staged upload for binary files
-# cms_edit_request_staged_upload → curl uploadUrl → consumeArgs
-# cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "photo.png"]
+# Raster/video: cms_edit_media prepare → wait → catalog → import (video: import only).
+# SVG/PDF/Lottie: cms_edit_request_staged_upload → curl → asset upload --staged
 
 # Upload and create a Media wrapper in one step (--media-name defaults to asset title)
 cms-edit asset upload ./figure.png --with-media --media-position Middle