@se-studio/contentful-cms 3.4.3 → 3.4.4

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

@@ -25,7 +25,8 @@ Normalize a **folder of designer masters** into short-lived **public HTTPS URLs*
   - `MEDIA_PIPELINE_TENANT` (e.g. `se`, not the cms-edit projectKey)
 - Drive folder shared **Viewer** with pipeline service account  
   `media-pipeline-reader@se-media-pipeline.iam.gserviceaccount.com`  
-  (or “anyone with the link” if using API-key Drive mode on the pipeline)
+  (or “anyone with the link” if using API-key Drive mode on the pipeline).  
+  **If prepare/status reports `drive_inaccessible` or `drive_empty_or_unshared`:** fix the share first, then re-prepare **once**. Do not treat “no media files” as a wrong folder path until share is confirmed.
 - Profile default: `case-study-v1`
 
 ## When to use
@@ -106,26 +107,44 @@ Each asset includes:
 
 After drafting titles/alts from **previewUrl** / **posterUrl**:
 
+**Prefer filtering** so unused files in a shared Drive folder are not uploaded:
+
+| Param | Use |
+|-------|-----|
+| `sourceNames` | Exact catalog `sourceName` allowlist (Drive file names) |
+| `excludeSourceNames` | Skip specific files |
+| `onlyWithOverrides` | Import only assets that have an `overrides` row (typical case-study path) |
+
 ```json
 {
   "action": "import",
   "jobId": "<jobId>",
   "withMedia": true,
+  "onlyWithOverrides": true,
   "overrides": [
-    { "sourceName": "OM1_Hero.jpg", "title": "OM1 hero", "alt": "…" }
-  ]
+    { "sourceName": "OM1_Hero.jpg", "title": "OM1 hero", "alt": "…", "fileName": "se-om1-hero-v3.jpg" }
+  ],
+  "dryRun": true
 }
 ```
 
-Optional: `"dryRun": true` to preview the map without writing.
+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`.
 
-CLI: `cms-edit media import --job <id> [--dry-run] [--with-media] [--overrides-json '[…]']`
+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 '[…]']`
 
 Import:
 
-1. Searches existing assets by fileName  
-2. Else uploads from `readyUrl` as the authenticated Contentful user  
-3. Returns `map: { sourceName → { assetId, mediaId?, … } }` for page build  
+1. Filters catalog (allowlist / exclude / onlyWithOverrides)  
+2. Searches existing assets by fileName  
+3. Else uploads from `readyUrl` as the authenticated Contentful user  
+4. Returns `map`, `skipped[]`, and `counts` for page build  
+
+**Linking Media to components:** use singular Entry links with  
+`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.
 
@@ -135,3 +154,4 @@ Manual `asset upload --url` remains available for one-offs.
 - Rate limits apply (prepares/hour, concurrent jobs).  
 - Never document or request `MEDIA_PIPELINE_API_KEY` or Blob tokens in chat.
 - `provisioning` is **not** a real pipeline phase; do not treat it as “still encoding” for many minutes.
+- If the MCP client times out (~180s) on `set`/`rtf`/`import`, **read / catalog / diff before retrying** — the server may already have applied the change.

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

@@ -23,8 +23,12 @@
    - `cms_edit ["asset", "search", "--filename-match", "<partial-name>"]`
    - `cms_edit ["list", "--type", "media", "--asset-filename-match", "<partial>"]`
 3. If match found — link by asset ID or filename in `set` / `create from-json` (`featuredImageAssetFilename`, `visualAssetFilename`, etc.)
-4. For **`visuals`** (Media entry array): prefer an **existing Media entry** — `cms_edit ["list", "--type", "media", "--asset-id", "<assetId>"]` — then `set @root visuals <mediaEntryId> --links`. Do **not** `create media` or use `asset upload --with-media` when a wrapper already exists.
-5. `create media` only when no Media entry wraps that asset (RTF embeds, or first article in a new composite batch — then **reuse that media ID** on sibling entries)
+4. For **`visuals`** (Media entry **array** on page/article): prefer an **existing Media entry** — `cms_edit ["list", "--type", "media", "--asset-id", "<assetId>"]` — then `set @root visuals <mediaEntryId> --links`. Do **not** `create media` or use `asset upload --with-media` when a wrapper already exists.
+5. For **singular** component fields (e.g. `visual` on a component):  
+   `cms_edit ["set", "@cN", "visual", "<mediaEntryId>", "--link"]`  
+   **Never** `add media --parent @cN --target visual` — `add --target` only works for Entry-link **arrays** (`content`, `contents`, …). Bad `add --target` is rejected; it used to orphan Media drafts.
+6. `create media` only when no Media entry wraps that asset (RTF embeds, or first article in a new composite batch — then **reuse that media ID** on sibling entries)
+7. Bare Contentful entry IDs work with `set` (no `@` required) for mid-session Media field tweaks (width/autoplay/loop) after import — `set <mediaEntryId> width 75`.
 
 ## Upload only when no match
 
@@ -89,7 +93,13 @@ cms_edit ["diff"]
 cms_edit ["save"]
 ```
 
-**Component visual / article featured image:** same pattern — `asset set <ref> <field> <asset-id>` (or `set … --asset`).
+**Component `visual` (Media Entry link, singular):**
+
+```
+cms_edit ["set", "@cN", "visual", "<media-entry-id>", "--link"]
+```
+
+**Article featured image / asset fields:** `asset set <ref> <field> <asset-id>` (or `set … --asset`) when the field is an Asset link.
 
 Always `diff` → `save`. Verify with `preview urls` on the public path.
 

package/docs/editor-tasks/preview-verify.md

@@ -23,11 +23,11 @@ After saving a draft, agents should return **all applicable URLs** and explain w
 
 | Target | Label | When to use |
 |--------|-------|-------------|
-| **contentfulLivePreview** | Live preview (publish here) | **Primary for editors.** Opens `app.contentful.com/.../entries/.../preview/...` — in-app preview with inspector. User clicks the green **Publish** button at the top to go live. |
-| **staging** | Preview (staging site) | Full-page check on staging, e.g. `{devBaseUrl}/resources/news/{tag}/{slug}/` (includes Vercel bypass params when configured). |
+| **contentfulLivePreview** | Live preview (publish here) | **Primary for editors when `url` is present.** Opens `app.contentful.com/.../entries/.../preview/...` — in-app preview with inspector. User clicks the green **Publish** button at the top to go live. If `url` is `null`, read `unavailableReason` / `notes` — do not invent a Live Preview link; use **staging** + **contentfulEntry** instead. |
+| **staging** | Preview (staging site) | Full-page check on staging, e.g. `{devBaseUrl}/resources/news/{tag}/{slug}/` (includes Vercel bypass params when configured). Always valid for draft visibility when staging is configured. |
 | **siteLivePreview** | Preview redirect | `{devBaseUrl}/preview?id={entryId}` — entry-aware redirect to the staging path. |
 | **production** | Production site | Published content only — compare after publish. |
-| **contentfulEntry** | Contentful entry editor | Classic entry form. Prefer **Live preview** for review and publish. |
+| **contentfulEntry** | Contentful entry editor | Classic entry form. Prefer **Live preview** when available; otherwise this is the publish path. |
 
 ## Steps
 
@@ -41,9 +41,10 @@ After saving a draft, agents should return **all applicable URLs** and explain w
    ```
    Use `--json` for machine-readable output.
 
-2. **Hand off to the editor with both links:**
-   - **Live preview** — for reviewing the draft and publishing (green Publish button in Contentful).
-   - **Preview (staging site)** — for a full-screen check on the staging deployment.
+2. **Hand off to the editor:**
+   - **Live preview** — when `url` is non-null: reviewing the draft and publishing (green Publish button in Contentful).
+   - **Preview (staging site)** — full-screen check on the staging deployment (always offer when available).
+   - If Live Preview is unavailable, say so briefly using `unavailableReason` and point at staging + classic entry editor.
 
 3. Summarize what to check before publish handoff — use the checklist below (add multi-block items when relevant).
 

package/docs/mcp/hosted-guide.md

@@ -148,6 +148,17 @@ Hosted connectors have **no server filesystem** and **reject `asset upload --bas
 
 Full workflow: `cms-edit://customer/task-media-reuse-and-upload`.
 
+### Common pitfalls (agents)
+
+| Issue | Do this |
+|-------|---------|
+| Singular Media on a component (`visual`) | `set @cN visual <mediaId> --link` — **not** `add … --target visual` |
+| Shared Drive folder has extra files | Import with `sourceNames` or `onlyWithOverrides` after catalog |
+| Prepare says no media / empty folder | Share folder **Viewer** with `media-pipeline-reader@se-media-pipeline.iam.gserviceaccount.com`, then re-prepare once |
+| MCP tool times out ~180s | `read` / `diff` / re-`catalog` before retrying the same write — server may already have saved |
+| `preview urls` has no Live Preview URL | Use staging + classic entry editor; row includes `unavailableReason` when CMA preview fails |
+| Reuse-first import matches old fileNames | dry-run first; set `overrides[].fileName` for unique names when duplication is required |
+
 ### Staged upload
 
 Keeps binary **out of MCP tool args**. The agent uploads via `curl`, then passes only a short `uploadId`.

package/package.json

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