@se-studio/contentful-cms 0.0.0-next16-20260822103555

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

@@ -0,0 +1,382 @@
+# 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.
+
+```bash
+cms-edit create from-json --json '{...}'
+cms-edit create from-json --json '{...}' --dry-run   # validate without writing
+cms-edit create from-json --json '{...}' --strict    # fail on unknown JSON keys
+cms-edit create from-json --json '{...}' --if-not-exists  # return existing ID when slug exists
+```
+
+Run `cms-edit index sync` before using any `*AssetFilename` shorthand (index-backed exact `file.fileName` lookup).
+
+---
+
+## Full JSON Schema
+
+```jsonc
+{
+  // "page" (default) or "article". Auto-detected as "article" if articleTypeId is present.
+  "type": "page",
+
+  // Required. The URL slug. Leading slash is stripped automatically. Trailing slash triggers a warning.
+  "slug": "/solutions/hepatology",
+
+  // Required. The page title (also used as cmsLabel if cmsLabel is omitted).
+  "title": "Hepatology Solutions",
+
+  // Optional. SEO meta description.
+  "description": "Evidence generation for hepatology research.",
+
+  // Optional. Override the Contentful entry label shown in the entry list.
+  "cmsLabel": "Hepatology Solutions Page",
+
+  // Page-only: link to an existing template entry by ID.
+  "templateId": "4xKpzQ2abc123",
+
+  // Page/article: featured image — asset ID (either key; warn if both differ).
+  "featuredImage": "7yBnmR9xyz456",
+  // "featuredImageId": "7yBnmR9xyz456",  // alias
+
+  // Exact Contentful asset fileName (requires cms-edit index sync).
+  // "featuredImageAssetFilename": "hero.jpg",
+
+  // Article-only: download asset (ID or fileName shorthands).
+  // "download": "assetId",
+  // "downloadAssetFilename": "report.pdf",
+
+  // Page-only: whether the page is indexed by search engines (default: not set = inherit).
+  "indexed": true,
+
+  // Page-only: whether the page is hidden from the sitemap (default: false).
+  "hidden": false,
+
+  // Article-only (required for articles): one of articleTypeId, articleTypeSlug, or articleTypeName.
+  // Prefer slug for marketers: cms-edit list --type articleType
+  "articleTypeSlug": "resources/blog",
+
+  // Article-only: publication date in YYYY-MM-DD format. Defaults to today.
+  "date": "2025-01-15",
+
+  // Array of components to create and link to the page's content field.
+  "components": [
+    // ... see Component Schema below
+  ]
+}
+```
+
+---
+
+## Explicit link shorthands (no guessing)
+
+Use **named keys** only — the CLI does not infer whether a string is an asset ID, Media entry ID, or file name.
+
+### Page / article (top-level)
+
+| JSON key | Sets field | Value |
+|----------|------------|-------|
+| `featuredImage` or `featuredImageId` | `featuredImage` | Asset ID |
+| `featuredImageAssetFilename` | `featuredImage` | Exact asset `fileName` (index) |
+| `download` or `downloadId` | `download` | Asset ID (article) |
+| `downloadAssetFilename` | `download` | Exact asset `fileName` (article) |
+| `icon` / `iconId` / `iconAssetFilename` | `icon` | Asset (article, when field exists) |
+| `templateId` | `template` | Entry ID |
+| `articleTypeId` | `articleType` | Entry ID (articles) |
+| `topContentIds`, `visualsIds`, … | See `cms-edit help fields-taxonomy` | Entry ID arrays |
+
+### Component `fields`
+
+| JSON key | Sets field | Value |
+|----------|------------|-------|
+| `visualId` | `visual` | Media / video entry ID |
+| `visual` (string) | `visual` | Entry ID only (same as `visualId`) |
+| `visualAssetId` | `visual` | Asset ID when the field is an Asset link |
+| `visualAssetFilename` | `visual` | Exact asset `fileName` → reuse or create Media |
+| `visualMediaName` | (with `visualAssetFilename`) | Optional Media entry name when creating (default: **asset title**) |
+| `visualMedia` | `visual` | `{ "assetId", "name", "position?", "width?" }` — always creates Media; `name` should match asset title unless you need a distinct wrapper label |
+| `mobileVisualId`, `mobileVisualAssetFilename`, … | `mobileVisual` | Same pattern |
+
+Unknown top-level or `fields` keys that are not on the content type: **warning** by default; use `--strict` or `--dry-run` to **fail** instead.
+
+### Comparison with `taxonomy-from-json`
+
+| | `taxonomy-from-json` | `create from-json` |
+|--|----------------------|-------------------|
+| Unknown fields on dry-run | Error (strict) | Error (strict) |
+| Unknown fields on create | Warn | Warn |
+| `--strict` on create | — | Supported |
+
+---
+
+## Component Schema
+
+Each item in `components` (and `items` for collections) follows this shape:
+
+```jsonc
+{
+  // --- Option A: Create a new entry ---
+
+  // Contentful content type ID. One of: component, collection, externalComponent, person
+  // Default: "component"
+  "contentType": "component",
+
+  // The type discriminator value (e.g. HeroSimple, TextBlock, CardGrid).
+  // Run `cms-edit schema types <content-type>` to see valid values.
+  "type": "HeroSimple",
+
+  // Optional. Human-readable label in Contentful's entry list. Defaults to `type`.
+  "cmsLabel": "Homepage Hero",
+
+  // Which field on the parent to attach to. Default: "content" (page) or "contents" (collection).
+  // Use "topContent" or "bottomContent" for template slots.
+  "target": "content",
+
+  // Scalar and rich text fields to set. See "Field Values" section below.
+  "fields": {
+    "heading": "Welcome to Hepatology",
+    "preHeading": "Our Speciality",
+    "body": "We have been building cohorts...\n\nWith over a decade of experience.",
+    "backgroundColour": "Navy",
+    "textColour": "White"
+  },
+
+  // CTA link entries to create and attach to the component's `links` field.
+  "links": [
+    // ... see Link Schema below
+  ],
+
+  // Child items for collection components. Same schema as a component.
+  "items": [
+    // ... nested components
+  ],
+
+  // --- Option B: Link an existing entry (no fields set) ---
+  // "existingId": "4xKpzQ2abc123",
+  // "comment": "Shared footer CTA — managed separately"
+}
+```
+
+---
+
+## Field Values
+
+Fields in the `fields` object accept several value formats.
+
+### Strings — Automatic RichText Conversion
+
+**The tool uses the Contentful content model to determine if a field is RichText.** For confirmed RichText fields, any string is always converted to a RichText document — no special markers needed.
+
+For fields where the schema is unavailable, the tool falls back to a heuristic. To trigger Markdown conversion in the heuristic path, use one of these markers:
+
+| Marker | Example | Produces |
+|---|---|---|
+| `\n\n` (double newline) | `"First.\n\nSecond."` | Two paragraphs |
+| `- ` (list item) | `"- Item one\n- Item two"` | Unordered list |
+| `# ` (heading) | `"# Heading\n\nBody."` | Heading + paragraph |
+| `**text**` | `"**bold** text"` | Bold inline |
+| `> ` (blockquote) | `"> A quote"` | Blockquote |
+
+**For single-sentence body fields:** Always include `\n\n` at the end to ensure conversion:
+```json
+"body": "Pedestal Health has been building cohorts in this space for over a decade.\n\n"
+```
+
+### Explicit Format Object
+
+Use an explicit format wrapper to be unambiguous:
+```jsonc
+"body": { "value": "Plain text paragraph.", "format": "text" }
+"body": { "value": "## Heading\n\nContent.", "format": "markdown" }
+"body": { "value": "<p>HTML content</p>", "format": "html" }
+```
+
+Accepted formats: `"text"`, `"markdown"`, `"html"`, `"json"` (raw Contentful RichText document).
+
+### Other Value Types
+
+```jsonc
+"indexed": true,        // boolean
+"heading": null,        // null clears the field
+"someNumber": 42        // number
+```
+
+---
+
+## Link Schema
+
+```jsonc
+{
+  // Link type. One of: "external" (default), "internal", "download", "blank"
+  "type": "internal",
+
+  // Display label for the CTA button.
+  "label": "Learn More",
+
+  // For "internal": resolve by slug (preferred) or by entry ID.
+  "slug": "/solutions/hepatology",
+  // "id": "4xKpzQ2abc123",   // alternative to slug
+
+  // For "external": the URL.
+  // "href": "https://example.com",
+
+  // For "download": the asset ID.
+  // "assetId": "7yBnmR9xyz456",
+
+  // Link to an existing link entry (skips creation).
+  // "existingId": "2aZxQw1def789"
+}
+```
+
+---
+
+## Critical Rules
+
+### Rule 1: Create Leaf Pages First
+
+Internal links resolve at creation time. If page A links to page B and B does not yet exist in Contentful, the creation fails and **page A is left partially created** (the page entry exists but with no content).
+
+**Always create leaf pages (the targets of links) before the pages that link to them.**
+
+```bash
+# Wrong order: /solutions links to /solutions/hepatology which doesn't exist yet
+cms-edit create from-json --json '{...}'      # FAILS mid-run
+
+# Correct order: leaf page first, parent page second
+cms-edit create from-json --json '{...}'     # succeeds
+cms-edit create from-json --json '{...}'      # succeeds — slug resolves
+```
+
+Use `--dry-run` to catch missing slugs before writing anything (see below).
+
+### Rule 2: Always Run --dry-run First
+
+`--dry-run` validates the plan without creating anything in Contentful. It prints the component tree and checks that all internal link slugs exist:
+
+```bash
+cms-edit create from-json --json '{...}' --dry-run
+```
+
+Example output when a slug is missing:
+```
+[dry-run] Would create page:
+  slug: /solutions
+  title: Solutions
+  ...
+
+✗ Internal link slug not found in Contentful: "/solutions/hepatology"
+✗ Internal link slug not found in Contentful: "/solutions/dermatology"
+  Create the target pages first, then re-run. See: cms-edit help create-from-json
+```
+
+### Rule 3: Use body Strings Consistently
+
+Even if a body field is short, include `\n\n` at the end to ensure the string is treated as a paragraph of rich text:
+
+```jsonc
+// Good — explicit double newline ensures conversion
+"body": "A single-sentence description.\n\n"
+
+// Also good — multi-paragraph body
+"body": "First paragraph.\n\nSecond paragraph."
+
+// Risky for heuristic-path fields — no markers, may pass as plain string
+"body": "A single-sentence description."
+```
+
+---
+
+## Recovery: Partial Page Created
+
+If a run fails mid-way (e.g. a missing internal link slug), the page entry is already in Contentful but with no content. The error message shows the page ID:
+
+```
+✗ Component creation failed: No entry found with slug "/solutions/hepatology".
+✗ The page entry was already created in Contentful (partial state) — ID: 4xKpzQ2abc123, slug: /solutions
+  Inspect with: cms-edit open --page-slug /solutions
+  Remove with: delete the entry in Contentful at https://app.contentful.com/spaces/...
+  Tip: run with --dry-run first to validate all internal link slugs exist.
+```
+
+Options:
+1. Delete the partial entry in Contentful, fix the dependency order, and re-run.
+2. Repair the partial entry using `cms-edit batch run` with targeted `set`/`rtf` operations.
+3. Use `cms-edit open --page-slug /solutions` + individual `add` operations to rebuild the content.
+
+---
+
+## Complete Example
+
+A two-component page:
+
+```json
+{
+  "type": "page",
+  "slug": "/solutions/hepatology",
+  "title": "Hepatology Solutions",
+  "description": "Evidence generation for hepatology research.",
+  "components": [
+    {
+      "contentType": "component",
+      "type": "HeroSimple",
+      "cmsLabel": "Hepatology Hero",
+      "fields": {
+        "heading": "Hepatology Evidence Generation",
+        "preHeading": "Our Speciality",
+        "body": "We have been building cohorts in hepatology for over a decade.\n\nOur work spans NASH, HCC, and liver transplantation.",
+        "backgroundColour": "Navy",
+        "textColour": "White"
+      },
+      "links": [
+        { "type": "internal", "label": "Contact Us", "slug": "/contact" }
+      ]
+    },
+    {
+      "contentType": "collection",
+      "type": "CardGrid",
+      "cmsLabel": "Hepatology Capabilities",
+      "fields": {
+        "heading": "What We Offer"
+      },
+      "items": [
+        {
+          "contentType": "component",
+          "type": "Generic",
+          "cmsLabel": "Capability — Cohort Building",
+          "fields": {
+            "heading": "Cohort Building",
+            "body": "- Disease characterization\n- Protocol design\n- Long-term follow-up"
+          }
+        },
+        {
+          "contentType": "component",
+          "type": "Generic",
+          "cmsLabel": "Capability — Evidence Review",
+          "fields": {
+            "heading": "Evidence Review",
+            "body": "Systematic literature reviews and meta-analyses.\n\nSuitable for regulatory submission."
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Run:
+```bash
+cms-edit create from-json --json '{...}' --dry-run   # validate first
+cms-edit create from-json --json '{...}'             # create for real
+cms-edit open --page-slug /solutions/hepatology              # inspect result
+```
+
+---
+
+## After Creation
+
+Once created:
+1. Run `cms-edit open --page-slug /<slug>` to inspect the result.
+2. Fix any field values with `cms-edit set` or `cms-edit rtf`.
+3. Publish in the Contentful web app when ready.
+
+The tool prints the Contentful web app URL for the new entry after creation.

package/docs/help/fields-article.md

@@ -0,0 +1,161 @@
+# cms-edit — Article Field Reference
+
+An `article` entry is a blog post, news item, or publication. It has a slug, date, article type classification, and usually a `content` array of body components.
+
+Read `cms-edit://customer/articles` for site-specific playbooks (press releases, publications, tag rules).
+
+---
+
+## Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `slug` | Text | Yes | URL slug without leading or trailing slash. Example: `part1/part2/part3` |
+| `title` | Text | Yes | Article title |
+| `description` | Text | No | SEO meta description — keep under ~160 characters when used for meta |
+| `subtitle` | Text | No | Display line on news/publication heroes (site-specific) |
+| `cmsLabel` | Text | No | Label in Contentful's entry list. Defaults to `title` |
+| `date` | Date | Yes | Publication date in `YYYY-MM-DD` format. Defaults to today in `create from-json` |
+| `articleType` | Link (Entry) | Yes | Link to an `articleType` entry (categorises the article) |
+| `tags` | Array of Links | No | Tag entries (often drives URL topic segment when primary tag is in slug) |
+| `content` | Array of Links | No | Body components — see [Template hierarchy](#template-hierarchy) before adding heroes |
+| `template` | Link (Entry) | No | Per-article layout override (rare); overrides `articleType.articleTemplate` |
+| `featuredImage` | Link (Asset) | No | Often used for OpenGraph / social sharing — prefer **landscape** (wider than tall) |
+| `visuals` | Array of Links | No | Media entries — on many sites drives on-page hero and listing thumbnails |
+| `download` | Link (Asset) | No | Downloadable file (e.g. PDF poster) |
+| `icon` | Link (Asset) | No | Icon asset |
+| `authors` | Array of Links | No | Person entries (ordered bylines) |
+| `externalLink` | Text | No | External URL (e.g. DOI, journal link) |
+| `indexed` | Boolean | Yes | Search indexing (default `true`) |
+| `hidden` | Boolean | Yes | Sitemap visibility (default `false`) |
+
+### `featuredImage` vs `visuals`
+
+On sites that use **both** fields, they often serve different purposes:
+
+| Field | Typical use |
+|-------|-------------|
+| `visuals` | On-page hero image and listing/card thumbnail |
+| `featuredImage` | OpenGraph and social sharing cards (landscape) |
+
+Read `cms-edit://customer/articles` and `defaults` for site rules. When the playbook requires both, set each explicitly — do not omit `featuredImage` expecting inheritance to fill gaps on listing or OG surfaces.
+
+---
+
+## Template hierarchy
+
+Rendered article layout is assembled from the article entry **and** a resolved **template** entry:
+
+1. Article `template` field (if set) — takes precedence
+2. Else linked `articleType` → `articleTemplate` field
+
+Template entries provide `preContent` and `postContent` arrays that wrap the article's `content` field. On many marketing sites, **heroes and shells live in the template**, not in per-article `content`.
+
+Before adding components to an article:
+
+```bash
+cms-edit list --type articleType
+# Note articleTemplate on the target type, then inspect that template:
+cms-edit peek --id <template-entry-id>
+```
+
+**Do not duplicate** hero or layout components in `content` when the resolved template's `preContent` / `postContent` already provides them. The site playbook (`cms-edit://customer/articles`) lists which component types belong in `content` (e.g. rich text only).
+
+> **Note:** `articleType.articlePageTopContent` exists in Contentful on some spaces but is **not** read by the standard article converter — use `articleTemplate` → `preContent` instead.
+
+---
+
+## Finding article types (required)
+
+```bash
+cms-edit list --type articleType
+```
+
+Every article must link to an **articleType**. Prefer slug-based lookup for marketers:
+
+- CLI: `--article-type-slug resources/blog` or `--article-type-name "Blog"`
+- JSON: `articleTypeSlug` or `articleTypeName` (or `articleTypeId` if you have the ID)
+
+---
+
+## Listing Recent Articles
+
+Sort by publication `date` (matches the website), not `sys.updatedAt`:
+
+```bash
+cms-edit list --type article --sort date -n 10
+cms-edit search "keyword" --type article
+cms-edit list --type article --sort date
+```
+
+To find **draft** articles: `cms-edit list --type article --sort date` (preview index includes drafts), then `cms-edit peek --article-slug <slug>` or `cms-edit open --id <id>`. `peek` and `open` load draft content — only `list --published` is published-only.
+
+---
+
+## Reading Article Fields
+
+```bash
+cms-edit open --article-slug /news/2025-hepatology-study
+cms-edit read @c0              # all fields
+cms-edit read @c0 date
+cms-edit read @c0 description
+```
+
+---
+
+## Setting Article Fields
+
+```bash
+cms-edit set @c0 title "Updated Article Title"
+cms-edit set @c0 description "New meta description."
+cms-edit set @c0 date "2025-06-01"
+```
+
+---
+
+## Adding Content to an Article
+
+Check [Template hierarchy](#template-hierarchy) and the site articles playbook first.
+
+```bash
+# Add a component to the article's content array
+cms-edit add TextBlock component
+
+# Add a collection
+cms-edit add CardGrid collection
+
+# Insert after a specific component
+cms-edit add Generic component --after @c3
+```
+
+Rename component `cmsLabel` from defaults like "New Article rich text" to a descriptive label (site playbook may specify a pattern).
+
+---
+
+## In create from-json
+
+```json
+{
+  "type": "article",
+  "slug": "news/2025-hepatology-study",
+  "title": "New Hepatology Cohort Study Published",
+  "description": "A landmark study on hepatology cohort data.",
+  "date": "2025-06-01",
+  "articleTypeSlug": "resources/blog",
+  "featuredImageAssetFilename": "hero-landscape.jpg",
+  "visualsIds": ["<media-entry-id>"],
+  "components": [
+    {
+      "contentType": "component",
+      "type": "TextBlock",
+      "fields": {
+        "heading": "Study Overview",
+        "body": "The study included 1,200 patients.\n\nResults showed significant improvement.",
+        "cmsLabel": "News — New Hepatology Cohort Study Published"
+      }
+    }
+  ]
+}
+```
+
+Auto-detection: if `articleTypeId` is present and `type` is omitted, the entry is automatically created as an article.

package/docs/help/fields-collection.md

@@ -0,0 +1,133 @@
+# cms-edit — Collection Field Reference
+
+A `collection` entry is a group of components — a card grid, timeline, category explorer, etc. The `collectionType` field picks which visual layout to use. Children are stored in the `contents` field.
+
+---
+
+## Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `cmsLabel` | Text | Human-readable label in Contentful's entry list |
+| `collectionType` | Text | Variant discriminator — e.g. `CardGrid`, `Timeline`, `CategoryExplorer`. Run `cms-edit types` to see valid values |
+| `heading` | Text | Section heading |
+| `preHeading` | Text | Small label above the heading. Rendered as `<p>`, not a heading tag |
+| `postHeading` | Text | Small label below the heading. Rendered as `<p>`, not a heading tag |
+| `body` | RichText | Introductory body text for the collection |
+| `links` | Array of Links | CTA link entries for the collection as a whole |
+| `contents` | Array of Links | The child component/collection entries in display order |
+| `backgroundColour` | Text | Named background colour |
+| `textColour` | Text | Named text colour |
+
+---
+
+## Reading Collection Fields
+
+```bash
+cms-edit open --page-slug /solutions
+cms-edit snapshot
+# A collection appears as a nested group in the tree, e.g.:
+#   @c3   collection  [draft]  CardGrid
+#     @c4   component  [draft]  Card — Hepatology
+#     @c5   component  [draft]  Card — Dermatology
+
+cms-edit read @c3              # all fields on the collection
+cms-edit read @c3 heading      # just the heading
+```
+
+---
+
+## Setting Collection Fields
+
+```bash
+cms-edit set @c3 heading "Our Solutions"
+cms-edit set @c3 preHeading "What We Do"
+cms-edit rtf @c3 body "An overview of our capabilities.\n\nSelect a speciality below."
+cms-edit set @c3 backgroundColour "Grey"
+```
+
+---
+
+## Adding Child Items
+
+```bash
+# Add a new child component inside a collection
+cms-edit add Generic component --parent @c3
+
+# Re-snapshot after add — refs are renumbered
+cms-edit snapshot
+
+# Then set fields on the new child
+cms-edit set @c4 heading "New Card Heading"
+```
+
+**Important:** After any `add --parent` operation, all entries that come after the collection in the depth-first tree are renumbered. Always re-snapshot or use variable binding in `run` batches. See `cms-edit help run`.
+
+---
+
+## Reordering Children
+
+```bash
+# Move a child to a specific position (0-indexed) within its parent
+cms-edit move @c5 0      # move to first position
+cms-edit move @c4 2      # move to third position
+```
+
+---
+
+## Removing a Child
+
+```bash
+cms-edit remove @c5      # unlinks from parent; does not delete the entry
+```
+
+---
+
+## In create from-json
+
+Collections use `"contentType": "collection"` and their children go in `"items"`. The `items` array maps to the `contents` field in Contentful:
+
+```json
+{
+  "contentType": "collection",
+  "type": "CardGrid",
+  "cmsLabel": "Solutions Cards",
+  "fields": {
+    "heading": "Our Solutions",
+    "preHeading": "What We Offer",
+    "body": "Choose a speciality area below.\n\n",
+    "backgroundColour": "Grey"
+  },
+  "links": [
+    { "type": "internal", "label": "See All Solutions", "slug": "/solutions" }
+  ],
+  "items": [
+    {
+      "contentType": "component",
+      "type": "Generic",
+      "cmsLabel": "Card — Hepatology",
+      "fields": {
+        "heading": "Hepatology",
+        "body": "Evidence generation for liver disease.\n\n"
+      },
+      "links": [
+        { "type": "internal", "label": "Learn More", "slug": "/solutions/hepatology" }
+      ]
+    },
+    {
+      "contentType": "component",
+      "type": "Generic",
+      "cmsLabel": "Card — Dermatology",
+      "fields": {
+        "heading": "Dermatology",
+        "body": "Real-world data for skin conditions.\n\n"
+      },
+      "links": [
+        { "type": "internal", "label": "Learn More", "slug": "/solutions/dermatology" }
+      ]
+    }
+  ]
+}
+```
+
+**Note:** Internal links in `items[].links` must resolve — the target pages must exist in Contentful before running `create from-json`. Use `--dry-run` to validate all slugs first. See `cms-edit help create-from-json`.