@se-studio/contentful-cms 3.7.4 → 3.9.0

package/dist/mcp/tools/cms-edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"cms-edit.js","sourceRoot":"","sources":["../../../src/mcp/tools/cms-edit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cms-edit.js","sourceRoot":"","sources":["../../../src/mcp/tools/cms-edit.ts"],"names":[],"mappings":"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"}

package/dist/mcp/tools/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAGrB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CA4BhF"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/help.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGzE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAGrB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAuEhF"}

package/dist/mcp/tools/help.js

@@ -1,20 +1,61 @@
 import { z } from 'zod';
+import { EMBEDDED_HELP_TOPIC_NAMES, EMBEDDED_HELP_TOPICS } from '../../generated/help-topics.js';
 import { GUIDE_TOPICS, getGuideTopicMarkdown, } from '../guide.js';
 import { prefixHostedToolDescription } from '../hosted-metadata.js';
 export function registerHelpTool(server, hosted) {
-    server.tool('cms_edit_help', prefixHostedToolDescription('Return the cms-edit getting-started guide by topic. No session or Contentful credentials required.', hosted), {
+    server.tool('cms_edit_help', prefixHostedToolDescription('Return cms-edit help: getting-started guide topics (overview, workflow, commands, troubleshooting, hosted) or embedded playbooks (create-from-json, workflow, fields, …). No Contentful credentials required.', hosted), {
         topic: z
-            .enum(GUIDE_TOPICS)
+            .string()
             .optional()
-            .describe('Guide section: overview (default), workflow, commands, troubleshooting, or hosted.'),
+            .describe(`Guide: ${GUIDE_TOPICS.join(', ')} (default overview). Playbooks: ${EMBEDDED_HELP_TOPIC_NAMES.join(', ')}.`),
     }, async ({ topic }) => {
-        const resolvedTopic = (topic ?? 'overview');
-        const markdown = getGuideTopicMarkdown(resolvedTopic, hosted);
+        const resolvedTopic = topic ?? 'overview';
+        const guideAlias = resolvedTopic.startsWith('guide/')
+            ? resolvedTopic.slice('guide/'.length)
+            : resolvedTopic === 'guide'
+                ? 'overview'
+                : undefined;
+        if (guideAlias && GUIDE_TOPICS.includes(guideAlias)) {
+            const markdown = getGuideTopicMarkdown(guideAlias, hosted);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ ok: true, topic: resolvedTopic, markdown }),
+                    },
+                ],
+            };
+        }
+        const playbook = EMBEDDED_HELP_TOPICS[resolvedTopic];
+        if (playbook) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ ok: true, topic: resolvedTopic, markdown: playbook }),
+                    },
+                ],
+            };
+        }
+        if (GUIDE_TOPICS.includes(resolvedTopic)) {
+            const markdown = getGuideTopicMarkdown(resolvedTopic, hosted);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ ok: true, topic: resolvedTopic, markdown }),
+                    },
+                ],
+            };
+        }
         return {
             content: [
                 {
                     type: 'text',
-                    text: JSON.stringify({ ok: true, topic: resolvedTopic, markdown }),
+                    text: JSON.stringify({
+                        ok: false,
+                        error: `Unknown help topic "${resolvedTopic}". Guide: ${GUIDE_TOPICS.join(', ')}. Playbooks: ${EMBEDDED_HELP_TOPIC_NAMES.join(', ')}.`,
+                    }),
                 },
             ],
         };

package/dist/mcp/tools/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../../../src/mcp/tools/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,YAAY,EAEZ,qBAAqB,GAEtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEpE,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,MAAsB;IACxE,MAAM,CAAC,IAAI,CACT,eAAe,EACf,2BAA2B,CACzB,oGAAoG,EACpG,MAAM,CACP,EACD;QACE,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,YAAY,CAAC;aAClB,QAAQ,EAAE;aACV,QAAQ,CACP,oFAAoF,CACrF;KACJ,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,MAAM,aAAa,GAAG,CAAC,KAAK,IAAI,UAAU,CAAe,CAAC;QAC1D,MAAM,QAAQ,GAAG,qBAAqB,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QAC9D,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;iBACnE;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../../src/mcp/tools/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACjG,OAAO,EACL,YAAY,EAEZ,qBAAqB,GAEtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEpE,MAAM,UAAU,gBAAgB,CAAC,MAAiB,EAAE,MAAsB;IACxE,MAAM,CAAC,IAAI,CACT,eAAe,EACf,2BAA2B,CACzB,+MAA+M,EAC/M,MAAM,CACP,EACD;QACE,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,UAAU,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,mCAAmC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC5G;KACJ,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE;QAClB,MAAM,aAAa,GAAG,KAAK,IAAI,UAAU,CAAC;QAC1C,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,CAAC,QAAQ,CAAC;YACnD,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;YACtC,CAAC,CAAC,aAAa,KAAK,OAAO;gBACzB,CAAC,CAAC,UAAU;gBACZ,CAAC,CAAC,SAAS,CAAC;QAEhB,IAAI,UAAU,IAAK,YAAkC,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3E,MAAM,QAAQ,GAAG,qBAAqB,CAAC,UAAwB,EAAE,MAAM,CAAC,CAAC;YACzE,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;qBACnE;iBACF;aACF,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,oBAAoB,CAAC,aAAa,CAAC,CAAC;QACrD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;qBAC7E;iBACF;aACF,CAAC;QACJ,CAAC;QAED,IAAK,YAAkC,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;YAChE,MAAM,QAAQ,GAAG,qBAAqB,CAAC,aAA2B,EAAE,MAAM,CAAC,CAAC;YAC5E,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;qBACnE;iBACF;aACF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;wBACnB,EAAE,EAAE,KAAK;wBACT,KAAK,EAAE,uBAAuB,aAAa,aAAa,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;qBACvI,CAAC;iBACH;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/docs/FUNCTIONAL_SPEC.md

@@ -10,7 +10,7 @@
 
 **CLI binary (`cms-edit`)** — invoked with subcommands and arguments from a terminal or shell script.
 
-**Hosted MCP server** — deployed per site at `/api/mcp` (OAuth). Exposes `cms_edit`, `cms_edit_help`, `cms_edit_customer`, guide/customer resources, and onboarding prompts. Local stdio MCP is not supported; IDE/terminal agents use the `cms-edit` CLI directly.
+**Hosted MCP server** — deployed per site at `/api/mcp` (OAuth). Exposes `cms_edit`, `cms_edit_help`, `cms_edit_customer`, guide/customer resources, and onboarding prompts. Local stdio MCP is not supported. The local `cms-edit` binary is for pack/host tooling only.
 
 ---
 

package/docs/editor-tasks/create-page.md

@@ -17,13 +17,13 @@
 
 ## Steps
 
-1. `cms_edit ["list", "--type", "template"]` — pick template ID
-2. `cms_edit ["create", "page", "--slug", "<slug>", "--title", "<title>", "--template-id", "<id>"]`
-3. `cms_edit ["snapshot"]` — review structure
-4. Add components: `add <ComponentType>`; set fields with `set` / `rtf`
-5. `cms_edit ["diff"]` → `cms_edit ["save"]`
+1. `cms_edit ["schema", "component"]` and `cms_edit ["schema", "types", "component"]` — this space’s fields/enums
+2. `cms_edit_help` topic `create-from-json` (or `cms_edit ["help", "create-from-json"]`)
+3. Draft JSON with `"components"` and nested `"type"`. Filesystem: `--json-base64`. Desktop: `--json`.
+4. `cms_edit ["create", "from-json", "--json", "{…}", "--dry-run", "--strict"]` then without `--dry-run`
+5. To edit later: `open` → `export from-json` → `apply from-json`
 
-For multi-component pages, prefer `create from-json --json '{…}' --dry-run --strict` first.
+`add` / `set` / `rtf` only for tiny patches after the tree exists.
 
 After each `add`, set `heading` then `cmsLabel` (not left as `New Generic`).
 

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

@@ -78,7 +78,7 @@ The URL must be fetchable by the hosted MCP server. Do not use local-only URLs.
 
 ### Local CLI (only when user approves)
 
-Local `cms-edit` may use `--base64` or `--url` when the user explicitly approves local CLI (see repo `Agents.md`). Hosted agents must not use local CLI without permission.
+Hosted MCP uses `cms_edit_request_staged_upload` then `asset upload --staged`. Do not use the local `cms-edit` CLI for uploads.
 
 ## Link uploaded asset to an entry
 

package/docs/help/create-from-json.md

@@ -1,6 +1,29 @@
 # cms-edit create from-json — Complete Guide
 
-`create from-json` creates a complete new page or article — including all components, collections, and CTA links — from inline JSON (`--json` or `--json-base64`). It is the recommended way to create new pages on hosted MCP.
+`create from-json` creates a complete new page or article — including all components, collections, and CTA links — from `--json` or `--json-base64`. It is the recommended way to create new pages on hosted MCP.
+
+**Agents:** do not use a local `cms-edit` binary, `--file`, or stdin. Filesystem clients encode the file as `--json-base64`. Desktop clients pass `--json` in the `cms_edit` args array.
+
+Also: `export from-json` (open session → same JSON with `existingId` / `version`) and `apply from-json` (validate, then update/create).
+
+```
+cms_edit ["help", "create-from-json"]
+cms_edit_help { "topic": "create-from-json" }
+cms_edit ["create", "from-json", "--json", "{...}", "--dry-run", "--strict"]
+```
+
+## Validation traps (fail before CMA)
+
+- Nested tree key is **`components`**, not `content` (`content` is a page field — empty page).
+- Discriminator is **`type`**, not `componentType` / `collectionType`.
+- **`components` must be non-empty**.
+- Unknown nested keys fail (`html` vs `htmlContent` — run `schema htmlComponent` for this space).
+- CTA text is **`label`**, not `linkText`.
+- Quoted `set @c1:field="value"` is rejected (quotes would be stored). Use `["set", "@c1", "field", "value"]`.
+
+Dry-run does not call CMA (slug checks use the local CDA index).
+
+---
 
 ```bash
 cms-edit create from-json --json '{...}'

package/docs/help/index.md

@@ -126,7 +126,9 @@ cms-edit batch run --json '[...]'
 ### Content Creation
 | Command | Description |
 |---|---|
-| `create from-json` | Create a page/article from a JSON file |
+| `create from-json` | Create a page/article from `--json` / `--json-base64` |
+| `export from-json` | Export the open session as from-json |
+| `apply from-json` | Apply from-json to the open session |
 | `create taxonomy-from-json` | Batch-create tagType, articleType, and tag entries |
 | `create person-from-json` | Batch-create person entries from JSON |
 | `create person` | Create a person entry (draft) |

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.7.4",
+  "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

@@ -1,24 +1,25 @@
 ---
 name: contentful-cms-core
-description: "Use cms-edit CLI to read/edit Contentful content (open → snapshot → read → set/rtf → diff → save)."
+description: "Edit Contentful drafts via hosted cms-edit MCP (open → snapshot → read → set/rtf → diff → save). Local CLI content commands are disabled."
 ---
 
-# Skill: contentful-cms CLI
+# Skill: contentful-cms (hosted MCP)
 
-Use this skill when you need to read or edit content in Contentful CMS using the `cms-edit` CLI tool.
+Use this skill when you need to read or edit content in Contentful using **hosted cms-edit MCP** (`cms_edit` with an `args` array). Command names match the old CLI (`open` → `snapshot` → `read` → `set`/`rtf` → `diff` → `save`).
+
+**Do not** run the local `cms-edit` binary for content. It refuses `open`, `save`, `set`, and other content commands. Local CLI is only for `host`, `editor-pack`, `project`, `schema`, and `guide`.
 
 **Before editing:** use skill **`contentful-cms-editor-tasks`** to read `tasks-index` and the matching capability playbook for this site (hosted MCP or local `cms-edit/<site>/editor-pack/`).
 
 ## 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.
+
+**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`.
 
-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)
+**Never publish.** Hosted MCP cannot see your disk — send JSON in the tool call.
 
 ## Safety Rules
 
@@ -31,7 +32,6 @@ All `save` operations create **draft** versions. A human must review and publish
 
 **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`)
-- **Local CLI:** `--base64` or `--url` when user approves local CLI
 - 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
@@ -158,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:
@@ -609,7 +604,7 @@ cms-edit does not capture screenshots. Use preview URL commands, then open the U
 {
   "spaces": {
     "om1": {
-      "devBaseUrl": "http://localhost:3013"
+      "devBaseUrl": "https://om1.localhost"
     }
   }
 }
@@ -678,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`.
@@ -714,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:**
 

package/skills/manifest.json

@@ -1,5 +1,5 @@
 {
-  "core": "Use cms-edit CLI to read/edit Contentful content (open → snapshot → read → set/rtf → diff → save).",
+  "core": "Edit Contentful drafts via hosted cms-edit MCP (open → snapshot → read → set/rtf → diff → save). Local CLI content commands are disabled.",
   "editor-tasks": "Route CMS editing intents to site task playbooks via tasks-index (hosted MCP resources or local editor-pack files).",
   "templates": "Create or edit templates (preContent, postContent, menu, footer, colours) in Contentful via cms-edit.",
   "setup": "Guide a user through connecting hosted cms-edit MCP for Claude or Grok (OAuth)."