@se-studio/contentful-cms 3.8.0 → 3.9.0

package/docs/mcp/hosted-guide.md

@@ -22,7 +22,7 @@ All `save` operations create **drafts only**. A human must review and publish in
 | `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_version` | Check the installed cms-edit version (no session required) |
-| `cms_edit_help` | Read this guide by topic (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) |
+| `cms_edit_help` | Guide topics (`overview`, `workflow`, `commands`, `troubleshooting`, `hosted`) **or** playbooks (`create-from-json`, `fields-component`, …) |
 
 ## Customer editor pack (read first)
 
@@ -183,18 +183,29 @@ Read `cms-edit://customer/defaults` when present. Otherwise:
 
 Run `["index", "sync"]` before resolving assets by filename.
 
+## JSON payloads (filesystem vs no filesystem)
+
+Hosted MCP cannot see your disk. Same commands either way:
+
+- **Filesystem client:** write `page.json`, then `cms_edit ["create", "from-json", "--json-base64", "<base64 of file>", "--dry-run", "--strict"]`
+- **No filesystem (Desktop):** put the JSON in `--json` on the tool call
+
+Never use a local `cms-edit` binary, `--file`, or stdin for content.
+
 ## Create content
 
 ### Create a page
 
 ```
-["index", "sync"]
-["list", "--type", "template"]
-["create", "page", "--slug", "/about-us", "--title", "About Us", "--template-id", "<id>"]
-["snapshot"]
+["schema", "component"]
+["help", "create-from-json"]
+["create", "from-json", "--json", "{...}", "--dry-run", "--strict"]
+["create", "from-json", "--json", "{...}"]
 ```
 
-Or use `create from-json` with `--dry-run --strict` for multi-section pages.
+Use `"components"` (not `"content"`) and nested `"type"` (not `"componentType"`). Peek a live entry or `schema <ct>` before authoring field ids.
+
+Empty `components` fails validation. Incremental `add`/`set` is for tiny patches only.
 
 ### Create an article
 
@@ -349,6 +360,6 @@ After upgrading cms-edit, run `["index", "sync"]` once so the local index includ
 
 **Editing:** `set <ref> <field> <value>`, `rtf <ref> <field> --content "<md>"`, `diff`, `save`, `discard`
 
-**Creating:** `create page --slug … --title …`, `create article --slug … --title … --article-type-slug …`, `create from-json --file …`, `add <type> --content-type … --parent @c0 --target content`
+**Creating:** `create from-json --json … --dry-run --strict`, `export from-json`, `apply from-json --json …`, `create page` / `create article` for empty shells, `add` for tiny inserts
 
 **Other:** `health`, `version`, `guide [topic]`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",
@@ -72,9 +72,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.10",
-    "@types/node": "^26.2.0",
+    "@types/node": "^24.13.3",
     "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
+    "@types/react-dom": "^19.2.5",
     "@upstash/redis": "^1.38.2",
     "next": "^16.3.2",
     "react": "^19.2.8",

package/skills/core/SKILL.md

@@ -13,14 +13,13 @@ Use this skill when you need to read or edit content in Contentful using **hoste
 
 ## Overview
 
-`cms-edit` lets you read and edit Contentful draft content without publishing. It uses a **snapshot → ref → edit → save** workflow:
+`cms-edit` lets you read and edit Contentful draft content without publishing.
 
-1. `open` a page to load the content tree into a session
-2. `snapshot` to see the tree with `@ref` labels
-3. `read` an entry to inspect its fields
-4. `set` / `rtf` to modify fields
-5. `diff` to review changes
-6. `save` to write drafts to Contentful (NEVER publishes)
+**New page/article:** `schema` for this space → `create from-json --dry-run --strict` → `create from-json` (`--json` or `--json-base64`). Nested tree key is `components`; discriminator is `type`.
+
+**Edit a tree:** `open` → `export from-json` → edit JSON → `apply from-json`. Tiny patches: `set` / `rtf` / `add` then `diff` → `save`.
+
+**Never publish.** Hosted MCP cannot see your disk — send JSON in the tool call.
 
 ## Safety Rules
 
@@ -159,15 +158,10 @@ Markdown support:
 - `` `inline code` ``
 - `---` for horizontal rule
 
-For any content with multiple paragraphs or newlines, use `printf` piped to stdin — `\n` in a double-quoted shell string is **not** interpreted as a newline by bash:
+For multi-paragraph Markdown, pass `--content` or `--base64` on MCP (no stdin, no `--file`):
 
-```bash
-# Correct — printf interprets \n properly
-printf '## Why it matters\n\nOur platform helps teams **move faster**.\n\n- Instant setup\n- No code required\n' | cms-edit rtf @c1 body --markdown -
-
-# Also correct — file input
-cms-edit rtf @c1 body --markdown --content "# Heading\n\nBody."
-cms-edit rtf @c1 body --markdown - < path/to/file.md
+```
+cms_edit ["rtf", "@c1", "body", "--content", "## Why it matters\n\nOur platform helps teams **move faster**."]
 ```
 
 Single-line content (no newlines) can be passed as a quoted argument directly:
@@ -679,12 +673,11 @@ cms-edit peek --id <entryId>         # Look up by entry ID
 
 ## Batch Operations (batch run)
 
-Run a sequence of operations from a JSON file or stdin.
+Run a sequence of operations from `--json` or `--json-base64` (hosted MCP).
 
-```bash
-cms-edit batch run --json '[...]'            # Run batch ops from inline JSON
-echo '[...]' | cms-edit batch run             # Pipe from stdin
-cms-edit batch run --json '[...]' --dry-run  # Validate without saving
+```
+cms_edit ["batch", "run", "--json", "[...]"]
+cms_edit ["batch", "run", "--json-base64", "<b64>", "--dry-run"]
 ```
 
 Supported ops: `open`, `set`, `rtf`, `rtf-replace`, `save`, `add`, `links-add`.
@@ -715,13 +708,17 @@ Example `ops.json` — update an existing page with a new CTA that has two butto
 
 ## Create Page or Article from JSON
 
-Create a complete page or article — including all components, fields, and CTA links — from a single declarative JSON file. This is the recommended approach for creating multiple pages or articles in bulk.
+Create a complete page or article from `--json` or `--json-base64`. Dry-run is local (no CMA) once the index is warm.
 
-```bash
-cms-edit create from-json --json '{...}'            # Create from inline JSON
-cms-edit create from-json --json '{...}' --dry-run  # Preview without writing
-cat page.json | cms-edit create from-json             # Pipe from stdin
 ```
+cms_edit ["help", "create-from-json"]
+cms_edit ["create", "from-json", "--json", "{...}", "--dry-run", "--strict"]
+cms_edit ["create", "from-json", "--json-base64", "<b64>"]
+cms_edit ["export", "from-json"]
+cms_edit ["apply", "from-json", "--json-base64", "<b64>"]
+```
+
+Use `"components"` not `"content"`. Nested discriminator is `"type"` not `"componentType"`. Empty `components` fails. `schema <contentType>` for this space’s field ids.
 
 **Page JSON schema:**