@se-studio/skills 1.9.5 → 1.9.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.9.6
+
+### Patch Changes
+
+- Document that cms-edit `publish plan --id` is exact ids only. Use `--with-parents` (or open the parent/listing and `publish plan`) when those pages must republish so live listings are not stale.
+
 ## 1.9.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.9.5",
+  "version": "1.9.6",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/skills/contentful-cms-core/SKILL.md

@@ -21,7 +21,7 @@ Use this skill when you need to read or edit content in Contentful using **hoste
 
 **Edit a tree:** `open` → `export from-json` → edit JSON → `apply from-json` (`--staged` when over 8k). Tiny patches: `set` / `rtf` / `add` then `diff` → `save`. Long HtmlComponent fields: `kind=text` then `set --staged`.
 
-**Never publish.** Hosted MCP cannot see your disk — send JSON in the tool call **only if under 8192 bytes**.
+**Do not publish while saving.** Hosted MCP cannot see your disk — send JSON in the tool call **only if under 8192 bytes**. Publish is a later plan, and only after the user says yes. `publish plan --id` publishes **only those ids** (no parent/listing republish). If a parent or listing page must go live so production is not stale, pass `--with-parents`, or open that page / `--from-session` and `publish plan` without `--id`.
 
 ## Safety Rules
 
@@ -32,9 +32,11 @@ 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:
-- **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`)
+**Assets:** Upload **is** supported (`asset upload`). Default workflow: **search and reuse** existing assets first (`index sync` → `asset search`). Search by concept (`asset search --concept` / `--concept-all`) finds a subject and a tone, including files no page uses yet. Concepts are not blog tags. When uploading:
+- **Raster/video:** `cms_edit_request_staged_upload` → curl → `cms_edit_media` prepare → wait → catalog → import with real alt. Video, and an image master over 4MB, is a presigned direct PUT (100MB, `intake: direct`) then prepare with that URL. Smaller images still use `stagedUploadIds`. Never `asset upload --staged/--url/--base64` for jpeg/png/webp/gif/mp4. The stored asset is the processed file.
+- **Replace** an existing id with `asset replace --url` of the processed `…/packs/…/ready/…` file (`--dry-run` first). The id and the file name stay. Draft. No publish flag.
+- **SVG/PDF/Lottie:** `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`). 4MB function cap.
+- **Title:** `asset set-title`. **Alt:** `asset set-description`, written from the picture. Do not emotion-score headshots, logos, icons, or illustrations.
 - **HtmlComponent / large JSON:** `cms_edit_request_staged_upload` with `kind=text` or `kind=json` → curl → `set --staged`, `rtf --staged`, `create from-json --staged`, or `apply from-json --staged`. Hosted MCP rejects inline `--json`/`--content` over 8192 bytes. If the wrapper schema has no `kind`, use `cms_edit` `["staged-upload", "request", "--kind", "json", "--file-name", "...", "--mime", "application/json"]` (or `--kind text`), then curl, then `--staged`.
 - 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)
@@ -376,9 +378,13 @@ cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
 # Raster/video: cms_edit_media prepare → wait → catalog → import (video: import only).
+# Video and image masters over 4MB: direct intake (100MB), then prepare --https-urls.
 # Do not `asset upload` jpeg/png/webp/gif/mp4. Do not convert GIF/MP4 with local ffmpeg.
 # Animated GIF: leave as GIF; pipeline emits gif-converted MP4 for Media mute-loop, not featuredImage.
-# SVG/PDF/Lottie: cms_edit_request_staged_upload → curl → asset upload --staged
+# SVG/PDF/Lottie: cms_edit_request_staged_upload → curl → asset upload --staged (4MB)
+# Replace in place: asset replace <id> --url <processed ready url> --dry-run
+# Title: asset set-title. Alt: asset set-description. Concepts: asset concept assign (not taxonomy-from-json)
+# Concept search: asset search --concept <id> --concept-all <id>
 
 # Create a Media wrapper for an existing asset (name defaults to asset title)
 cms-edit create media --asset-id <asset-id>
@@ -394,7 +400,7 @@ cms-edit asset info 5xKj2abcDef
 cms-edit asset set @c0 visual 5xKj2abcDef
 ```
 
-JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?, mediaIds? }`. Max upload size is **10MB** per file.
+JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?, mediaIds? }`. Bytes through the process are **10MB**. Hosted function POST is **4MB**. Video and large image masters are **100MB** direct-to-storage, then the pipeline.
 
 **Idempotent upload:** `--if-exists-by-filename` is check-then-create. Do not upload the same `fileName` in parallel — serialize per fileName or re-run to converge.
 
@@ -576,7 +582,7 @@ cms-edit diff
 
 # 7. Save as draft
 cms-edit save
-# → "Saved 1 entry as draft. A human must publish for changes to go live."
+# → "Saved 1 entry as draft. Publish only if the user asks, with publish plan and an explicit yes."
 ```
 
 ## Common Patterns
@@ -828,7 +834,7 @@ Use `"components"` not `"content"`. Nested discriminator is `"type"` not `"compo
 - String `fields` values become Rich Text when they auto-detect as Markdown (same heuristic), HTML (tag-like), or Rich Text JSON (`nodeType: document`). Otherwise strings stay as-is — use `{ "value": "…", "format": "text"|"markdown"|"html"|"json" }` or `cms-edit rtf` with `--text|--markdown|--html|--rtf-json`.
 - `target` sets which content array to use: `topContent`, `content` (default), or `bottomContent`.
 - Slugs must not have a trailing slash — `from-json` strips it with a warning, but avoid it in source JSON.
-- All entries are created as **drafts**. A human must publish in Contentful.
+- All entries are created as **drafts**. Publish later with `publish plan`, then `publish apply` only after the user says yes. With `--id`, add `--with-parents` when parent/listing pages must republish.
 - `--dry-run` prints the full plan without writing anything.
 
 ## Find Existing Entries (for existingId)
@@ -857,7 +863,14 @@ cms-edit list --type article --sort date -n 20
 cms-edit index dump --reference-only          # Full catalog snapshot in terminal
 ```
 
-**Note on bulk publish:** The tool cannot publish entries — all saves create drafts only. This is intentional. Review and publish drafts from the Contentful web app.
+**Note on publish:** Saves create drafts. Then `publish plan`, then `publish apply --plan <id>` only after the user says yes.
+
+- **Open page** or `--from-session`: publishes that page's draft and what it needs (linked drafts, then the page). The page publish is what refreshes the live URL.
+- **`--id`**: publishes **only the named ids**. Repeat `--id` for more than one. It does **not** walk linked drafts or parent/listing pages, so those live pages can stay stale.
+- **`--id` + `--with-parents`**: opts into the parent walk (linked drafts and upstream pages). Use this whenever a parent or listing page must republish. Equivalent: open the parent/listing and `publish plan` without `--id`.
+- **`--content-type schema`** (and other webhook types): publishes those entries; pages that use them are not republished.
+
+If someone else also changed an entry, ask all versus mine and `publish choose`. The Contentful role must allow it. Unpublish, archive, and revalidate use the same plan-then-yes rule. Do not apply a plan on your own.
 
 ## Concurrent Sessions
 

package/skills/contentful-cms-editor-tasks/SKILL.md

@@ -60,11 +60,11 @@ Capability playbooks require:
 1. **Propose** scope to the user — wait for approval
 2. **Dry-run** when available (`--dry-run`, `bulk-rtf-replace --dry-run`, etc.)
 3. **`diff`** before every `save`
-4. **Summarize** what changed; remind that publish is manual in Contentful
+4. **Summarize** what changed; remind that publish is a later `publish plan` after an explicit yes. `publish plan --id` is exact ids only — if a parent or listing page must go live, use `--with-parents` (or open that page and `publish plan`). See `task-publish-handoff`.
 
 ## Media default
 
-**Search and reuse assets first** (`index sync` → `asset search`). Upload only when no match; use `--if-exists-by-filename` when uploading.
+**Search and reuse assets first** (`index sync` → `asset search`). Search by concept (`--concept`, `--concept-all`) finds a subject and a tone. Concepts are not blog tags. Upload only when no match; use `--if-exists-by-filename` when uploading. Replace an in-use file with `asset replace` so the id and the file name stay. Alt is `asset set-description`, written from the picture. Do not emotion-score headshots, logos, icons, or illustrations.
 
 **Space-wide media audit** (filename, alt, size, dimensions, usage) → read **`task-media-review`**, then skill **`contentful-cms-media-review`** for the spreadsheet.