@se-studio/contentful-cms 3.9.4 → 3.10.1

package/docs/editor-tasks/media-pipeline-prepare.md

@@ -33,10 +33,13 @@ Normalize a **folder of designer masters** into short-lived **public HTTPS URLs*
 
 | Situation | Action |
 |-----------|--------|
-| Drive/Figma package with large JPEGs/videos | **This task first**, then structure build |
-| Single small image already in library | `task-media-reuse-and-upload` only |
-| Masters already under limits and catalogued | Reuse search only |
-| Prior prepare already reached `succeeded` + catalog | **Reuse that jobId** — do not re-prepare the whole folder |
+| Drive folder of masters | This task with `driveFolderUrl` |
+| Staged files (curl after `cms_edit_request_staged_upload`) | This task with `stagedUploadIds` — one prepare for the batch |
+| Public HTTPS on allowed hosts | This task with `httpsUrls` |
+| Single SVG/PDF/Lottie | `task-media-reuse-and-upload` asset upload --staged |
+| Prior prepare already reached `succeeded` + catalog | **Reuse that jobId** — do not re-prepare |
+
+Do **not** use `asset upload --staged/--base64` for jpeg/png/webp/gif/mp4. **Video** must use **import** (not `asset upload --url`, even on a Blob ready host). Raster `--url` is allowed only for pipeline ready image hosts.
 
 ## Steps (agent — single auth)
 
@@ -44,6 +47,8 @@ Normalize a **folder of designer masters** into short-lived **public HTTPS URLs*
 
 Call MCP tool **`cms_edit_media`**:
 
+Drive:
+
 ```json
 {
   "action": "prepare",
@@ -51,23 +56,27 @@ Call MCP tool **`cms_edit_media`**:
   "profile": "case-study-v1",
   "sourceNames": [
     "BusinessCards copy.jpg",
-    "ArcticDB x3 Screens Tablet-1920.mp4",
-    "ADB_Macbook_HomeLoop.mp4"
+    "ArcticDB x3 Screens Tablet-1920.mp4"
   ]
 }
 ```
 
-| Param | On prepare |
-|-------|------------|
-| omit `sourceNames` | Encode **entire** folder (slow for large case-study packs) |
-| non-empty `sourceNames` | **Allowlist** — only exact Drive file names are downloaded/encoded |
-| `excludeSourceNames` | Skip these names (always) |
+Staged (after curl PUT/POST to each `uploadUrl`):
+
+```json
+{
+  "action": "prepare",
+  "stagedUploadIds": ["<uploadId1>", "<uploadId2>"]
+}
+```
 
 CLI:
 
 ```bash
 cms-edit media prepare --drive-folder "https://drive.google.com/drive/folders/…" \
   --source-names "BusinessCards copy.jpg,ADB_Macbook_HomeLoop.mp4"
+
+cms-edit media prepare --staged-ids "id1,id2"
 ```
 
 Expect `{ ok: true, jobId, status: "queued", pollHint }`.
@@ -103,7 +112,7 @@ or
 
 - Do **not** invent assets for gaps.
 - Do **not** wait 5–10+ minutes on `provisioning`.
-- Do **not** thrash prepares (rate limit + concurrent max typically **2** per user).
+- Do **not** thrash prepares (rate limit **100**/hour, concurrent max typically **4** per user).
 - On `429` / too many concurrent: call `status` once on any stuck old `jobId` (to free slots if past grace), then prepare again **once**.
 - Prefer **reusing** a job that already reached `succeeded` + catalog over preparing again for the same Drive folder.
 
@@ -117,9 +126,10 @@ Each asset includes:
 
 | Field | Use |
 |-------|-----|
-| `readyUrl` | `asset upload --url` into Contentful |
+| `readyUrl` | Import via `cms_edit_media` import only (CMA gate: pipeline ready hosts) |
 | `previewUrl` / `posterUrl` | Agent vision for **title / fileName / alt** (when present) |
-| `altDraft` / `titleDraft` | Filename seeds only — improve before save |
+| `altDraft` / `titleDraft` | Filename seeds only — improve before import |
+| `role` `gif-converted` | Animated GIF became MP4 — Media mute-loop, not `featuredImage` |
 
 ### 4. Import into Contentful (reuse-first)
 
@@ -146,9 +156,10 @@ After drafting titles/alts from **previewUrl** / **posterUrl**:
 }
 ```
 
-1. Always **`dryRun: true` first** — check `existing: true/false` per asset (reuse is by **fileName**).
-2. When you need **new** assets instead of reusing prior runs, set `overrides[].fileName` to unique names.
-3. Then import without `dryRun`.
+1. Always **`dryRun: true` first** — check `existing: true/false` per asset (reuse is by **fileName**). Missing alt on new files is reported as `altFailures` / per-row `alt_required`; dryRun still returns `ok: true`.
+2. New uploads **fail** without review-quality `overrides[].alt` when you import for real (not empty, not the filename).
+3. When you need **new** assets instead of reusing prior runs, set `overrides[].fileName` to unique names.
+4. Then import without `dryRun`.
 
 CLI:  
 `cms-edit media import --job <id> [--dry-run] [--with-media] [--only-with-overrides] [--source-names a.jpg,b.jpg] [--exclude-source-names x.jpg] [--overrides-json '[…]']`
@@ -164,7 +175,7 @@ Import:
 `cms_edit ["set", "@cN", "visual", "<mediaId>", "--link"]`  
 — **never** `add … --target visual` (`add` only supports content **arrays**).
 
-Manual `asset upload --url` remains available for one-offs.
+Manual `asset upload --url` is allowed only for **pipeline-ready images** (Vercel Blob / `MEDIA_PIPELINE_READY_HOSTS`, https in production). **Video** must use **import**. Always prefer import for new masters.
 
 ### Hardening notes (for agents)
 

package/docs/editor-tasks/media-reuse-and-upload.md

@@ -32,30 +32,39 @@
 
 ## Upload only when no match
 
-### Oversized masters / whole Drive folders
+### Raster images and video (required)
 
-If files are near or over **4 MB** (hosted staged) or **10 MB** (URL/local), or the user shared a **Drive folder of masters**, do **not** improvise compression in chat.
+Encode via **`task-media-pipeline-prepare`**. Intake can be:
 
-1. Run **`task-media-pipeline-prepare`** (Drive folder → ready public URLs under limits)
-2. Return here and import with **`--url`** + reuse-first filename search
+1. A **Drive folder**, or
+2. **Staged upload** (4 MB): `cms_edit_request_staged_upload` → curl → `cms_edit_media` prepare with `stagedUploadIds` (see returned `consumeArgs`), or
+3. **httpsUrls** on pipeline-allowed hosts
 
-### Hosted MCP (default)
+Then wait → catalog → **import** with `overrides[].alt`. Do **not** `asset upload --staged/--base64` for jpeg/png/webp/gif/mp4. Do **not** `asset upload --url` for **video** (import only). Raster `--url` only for pipeline ready image hosts.
 
-**Always use staged upload** for ad-hoc small binaries. Do not pass base64 in `cms_edit` args — hosted MCP rejects `asset upload --base64`.
+Animated GIFs become **MP4** (`gif-converted`) — attach as mute-loop Media / video visual, not `featuredImage`.
+
+### SVG, PDF, Lottie
+
+These may skip the pipeline. On hosted MCP use staged upload then `asset upload --staged`.
+
+### Hosted MCP (SVG/PDF/Lottie only)
+
+**Always use staged upload** for ad-hoc binaries. Do not pass base64 in `cms_edit` args — hosted MCP rejects `asset upload --base64`.
 
 1. `cms_edit_request_staged_upload` with `fileName`, `mimeType`, optional `byteLength`, optional `title`
 2. Run the returned `curlCommand` in a shell (POST file to `uploadUrl`)
-3. `cms_edit` with the returned `consumeArgs` (e.g. `["asset","upload","--staged","<uploadId>",…]`)
+3. Follow `consumeArgs`: **media prepare** for photos/video; **asset upload --staged** for SVG/PDF/Lottie
 
 Rules:
 
-- Staged upload keeps binary **out of MCP args** — only a short `uploadId` is passed to Contentful
-- Hosted limit: **4 MB** per file; **1000 upload URLs per user per hour**; TTL **60 minutes**; single-use
-- **PNG** when the source has transparency (portraits on brand-colour cards); JPEG flattens alpha
-- Upload alone does **not** attach the asset — follow with **link + save** (below)
+- Staged upload keeps binary **out of MCP args**
+- Hosted limit: **4 MB** per file; **1000 upload URLs per user per hour**; TTL **60 minutes**
+- Raster/video staged files stay in Redis until pipeline fetches them (GET); they are not written to CMA
+- Upload/import alone does **not** attach the asset — follow with **link + save** (below)
 - Use `--if-exists-by-filename` (with `--file-name`) to avoid duplicate assets when re-running
 
-After staged upload, create a Media wrapper **only when none exists** for that asset:
+After import, create a Media wrapper **only when none exists** for that asset:
 
 ```
 cms_edit ["list", "--type", "media", "--asset-id", "<newPortraitAssetId>"]
@@ -68,17 +77,11 @@ To rename an existing Media wrapper: `cms_edit ["batch", "set", "<media-entry-id
 
 Avoid `asset upload --with-media` when multiple entries will share the same image (e.g. news composites) — it creates duplicate Media entries. Upload the asset only, then one shared `create media`, then link the media ID on each entry.
 
-**Prefer `--url`** when the file is already on **public HTTPS** under size limits — especially **media-pipeline ready pack URLs**:
-
-```
-cms_edit ["asset", "upload", "--url", "https://<public-https-url>/file.png", "--mime", "image/png", "--file-name", "headshot-name-1200.png", "--title", "…", "--if-exists-by-filename"]
-```
-
-The URL must be fetchable by the hosted MCP server. Do not use local-only URLs.
+**Prefer pipeline import** for encoded masters. **Video** must use import. `asset upload --url` is only for **pipeline ready images** (or SVG/PDF/Lottie). A random PNG or Contentful CDN master is rejected.
 
 ### Local CLI (only when user approves)
 
-Hosted MCP uses `cms_edit_request_staged_upload` then `asset upload --staged`. Do not use the local `cms-edit` CLI for uploads.
+Hosted MCP uses `cms_edit_request_staged_upload` then **media prepare** for raster/video (or `asset upload --staged` for SVG/PDF/Lottie). Do not use the local `cms-edit` CLI for uploads.
 
 ## Link uploaded asset to an entry
 

package/docs/editor-tasks/navigation.md

@@ -18,16 +18,21 @@
 ## Steps
 
 1. `cms_edit ["list", "--type", "navigation"]` — find nav entry
-2. `cms_edit ["nav", "open", "--id", "<navigationId>"]` or by slug
-3. `snapshot` — inspect nav items
-4. Add/clone/link items per navigation commands
-5. `diff` → `save`
+2. `cms_edit ["nav", "open", "--nav-id", "<navigationId>"]` or `["nav", "open", "--nav-name", "Main menu"]` — **not** `--id`
+3. `snapshot` — inspect nav items (array field may be `entries`, `items`, or `navigationItems`)
+4. **Ask** whether the change is **global** (template `menu`) or **page-specific** (`page.menu` override). Nested children (often the last header CTA) are usually **shared**.
+   - Global: `set` on the existing NavigationItem
+   - Page-specific: new NavigationItem + cloned/new menu, then `set` `page.menu` — do not mutate the shared item
+5. Add/clone/link items per navigation commands. `nav clone` is **shallow** for nested `navigationItems`.
+6. `diff` → `save`
+
+`peek` is one-shot. `open` / `nav open` persist. `preview urls /slug` follows that slug even if session `_mcp` is another page.
 
 See `contentful-cms-navigation` skill for full command reference in dev environments.
 
 ## Confirmation gates
 
-1. Confirm which menu (header/footer) and link changes
+1. Confirm which menu (header/footer) and whether the edit is global vs this page
 2. `diff` before `save`
 
 ## Out of scope
@@ -36,4 +41,4 @@ See `contentful-cms-navigation` skill for full command reference in dev environm
 
 ## Related resources
 
-- `cms-edit://customer/routing`
+- `cms-edit://customer/routing`

package/docs/help/lookup.md

@@ -1,6 +1,8 @@
-# Flat lookup flags (`open`, `resolve`, `nav open`)
+# Flat lookup flags (`open`, `peek`, `resolve`)
 
-cms-edit resolves entries using **explicit flags** — not positional slugs. Provide **exactly one** primary lookup flag per command. Scope flags (for example `--tag-type-name` with `--tag-name`) do not count as a second primary.
+cms-edit resolves entries using **explicit flags** — not positional slugs. Provide **exactly one** primary lookup flag per command. Scope flags (for example `--tag-type-name` with `--tag-name`, or `--nav-id` with `--nav-item-title`) do not count as a second primary.
+
+`cms-edit nav open` is separate: pass **`--nav-id` or `--nav-name`**, never `--id`. `--nav-id` alone is not a `resolve` primary.
 
 Run `cms-edit index sync` once per space (or let commands auto-sync) so catalog types resolve from the local index.
 
@@ -98,9 +100,10 @@ Navigation entries use the **`name`** field (not slug).
 | `--nav-item-id` | `navigationItem` entry ID |
 | `--nav-item-title` | `navigationItem.fields.title` |
 
-When multiple nav items share a title, add **`--nav-id`** to scope:
+When multiple nav items share a title, add **`--nav-id`** to scope `resolve` (do not use `--nav-id` alone on `resolve`):
 
 ```bash
+cms-edit nav open --nav-id <navigation-entry-id>
 cms-edit nav open --nav-name "Main header"
 cms-edit resolve --nav-item-title "Contact" --nav-id <navigation-entry-id>
 ```

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`, …) |
 
@@ -88,7 +88,7 @@ Each step is a separate `cms_edit` call. Sessions persist in Redis between calls
 ["open", "--include-chrome", "--page-slug", "/pricing"]
 ```
 
-Default `open` / `peek` fetch the page or article tree and the template entry, but **not** template menu/footer/navigation. Edit nav with `nav open`. Use `--include-chrome` only when you need those trees.
+Default `open` / `peek` fetch the page or article tree and the template entry, but **not** template menu/footer/navigation. Edit nav with `["nav", "open", "--nav-id", "<id>"]` or `--nav-name` (not `--id`). Use `--include-chrome` only when you need those trees. Template `menu` is site-wide; `page.menu` overrides one page. Nested nav items are often shared — ask global vs page-specific before `set`.
 
 **Homepage (all SE Studio sites):** Contentful stores the marketing homepage slug as `index`. The live site URL is `/`. In cms-edit, `--page-slug /` and `--page-slug /index` are equivalent (both resolve to `index`). Read `cms-edit://customer/routing` for site-specific exceptions (e.g. Pedestal uses `home`).
 
@@ -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)
 
@@ -310,7 +311,8 @@ OAuth is two steps: Grok obtains an MCP token, then you sign in with Contentful
 | Debug session persistence | `["diagnose"]` — reports store, userId, active session key |
 
 - **`peek` is one-shot** — prints tree and **root field values** (`rootFields` in JSON). No session is created; do not chain `read @ref` afterward.
-- **Use flat lookup flags** for `open` and `peek` — same as CLI (`--page-slug`, `--id`, etc.). See `help lookup`.
+- **`open` / `nav open` persist** the session. `preview urls /slug` follows that slug even if leftover `_mcp` is another page (JSON may include `sessionRootIgnored`).
+- **Use flat lookup flags** for `open` and `peek` — same as CLI (`--page-slug`, `--id`, etc.). See `help lookup`. `nav open` uses `--nav-id` or `--nav-name` only.
 - **`read @root`** only works after `open` (uses the active session). The hint in peek output is for terminal users who already ran `open`.
 - **Do not invent flags** — there is no `--read`, `--then`, or chained peek+read syntax. One command per `cms_edit` call.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.9.4",
+  "version": "3.10.1",
   "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
@@ -69,7 +70,7 @@ cms-edit open --include-chrome --page-slug /pricing
 
 `open` / `peek` fetch the page (or article) tree and the template entry, but **not** template `menu` / `footer` / navigation. Edit nav with `nav open`. Pass `--include-chrome` only when you need those trees.
 
-**Flat lookup flags:** provide **exactly one** primary flag per `open` / `resolve` / `nav open`. See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
+**Flat lookup flags:** provide **exactly one** primary flag per `open` / `peek` / `resolve`. `nav open` uses **`--nav-id` or `--nav-name` only** (not `--id`). See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
 
 ### Step 2: Read the snapshot
 
@@ -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
@@ -403,8 +399,9 @@ JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?,
 ## Navigation
 
 ```bash
-# Open a navigation entry (navigation uses `name`, not slug)
+# Open a navigation entry (not --id). Navigation uses `name`, not slug.
 cms-edit nav open --nav-name "Main navigation"
+cms-edit nav open --nav-id <navigation-entry-id>
 
 # Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
@@ -413,11 +410,17 @@ cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
 # Link an existing NavigationItem (share items across navigations)
 cms-edit nav add --existing-id <navigationItem-entry-id>
 
-# Clone a navigation (duplicates all items)
+# Clone a navigation (first-level items only; nested children stay shared)
 cms-edit nav clone <source-nav-id>
 cms-edit nav clone <source-nav-id> --label "LP Nav" --slug lp-nav
 ```
 
+Template **`menu`** is site-wide. **`page.menu`** overrides one page. Header CTAs are often nested under a wrapper and **shared**. Before `set` on a nav item, ask whether the change is global or page-specific. Page-specific: new NavigationItem + cloned/new menu on `page.menu` — do not mutate the shared entry.
+
+`peek` is one-shot. `open` / `nav open` persist. `preview urls /slug` follows that slug even if session `_mcp` is another page.
+
+The items array field may be `entries`, `items`, or `navigationItems` — inspect `read @root` before `set @root … --links`.
+
 ## Create New Entries
 
 ```bash