@se-studio/contentful-cms 3.1.3 → 3.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/contentful-cms Changelog
 
+## 3.1.4
+
+### Patch Changes
+
+- Clarify Media entry reuse for `visuals` in task-media-reuse-and-upload (avoid duplicate wrappers on shared composites).
+
 ## 3.1.3
 
 ### Patch Changes

package/dist/generated/version.d.ts

@@ -1,3 +1,3 @@
 export declare const CMS_EDIT_PACKAGE_NAME = "@se-studio/contentful-cms";
-export declare const CMS_EDIT_VERSION = "3.1.3";
+export declare const CMS_EDIT_VERSION = "3.1.4";
 //# sourceMappingURL=version.d.ts.map

package/dist/generated/version.js

@@ -1,4 +1,4 @@
 // Generated by scripts/generate-embedded-assets.mjs — do not edit manually.
 export const CMS_EDIT_PACKAGE_NAME = "@se-studio/contentful-cms";
-export const CMS_EDIT_VERSION = "3.1.3";
+export const CMS_EDIT_VERSION = "3.1.4";
 //# sourceMappingURL=version.js.map

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

@@ -23,7 +23,8 @@
    - `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. Or `cms_edit ["create", "media", "--asset-id", "<id>", "--name", "…"]` for RTF embeds
+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)
 
 ## Upload only when no match
 
@@ -43,12 +44,15 @@ Rules:
 - Upload 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
 
-Optional Media wrapper after staged upload (RTF embeds, not person `media`):
+After staged upload, create a Media wrapper **only when none exists** for that asset:
 
 ```
-cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "figure.png", "--with-media", "--media-name", "Figure 1"]
+cms_edit ["list", "--type", "media", "--asset-id", "<newPortraitAssetId>"]
+cms_edit ["create", "media", "--asset-id", "<newPortraitAssetId>", "--name", "…"]
 ```
 
+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.
+
 **Last resort `--url`** only when the file is already on public HTTPS and staged upload is impractical:
 
 ```

package/package.json

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