@se-studio/contentful-cms 3.13.1 → 3.14.0

package/docs/editor-tasks/publish-handoff.md

@@ -1,41 +1,42 @@
-# Capability: Publish handoff
+# Capability: Publish
 
 ## Intent phrases
 
 - publish changes
+- unpublish
+- archive
+- revalidate this page
 - go live
-- make changes live
 
 ## Requires capabilities
 
-Always available.
+The signed-in Contentful user must have the matching role permission. AI Editor cannot publish.
 
 ## What cms-edit does
 
-- Creates and updates **drafts only**
-- **Cannot** publish, unpublish, archive, or delete published entries
+`save` creates drafts. Publishing is a separate command.
 
-## Handoff steps
+1. `publish plan` (or `unpublish plan`, `archive plan`, `revalidate plan`) is read-only. It returns a plan id.
+2. If someone else also changed an entry in that plan, stop and ask: publish **all** of those entries, or **mine** only. One entry cannot be split by field. Record the answer with `publish choose --plan <id> --scope all|mine`.
+3. Apply only after the user says yes: `publish apply --plan <id>`. Do not apply on your own. The same yes is required for unpublish, archive, and revalidate.
 
-1. Ensure all edits are saved (`diff` was reviewed)
-2. Run `cms_edit ["preview", "urls", "<slug>"]` (or use session entry id after save)
-3. Give the user **both** links:
-   - **Live preview (publish here)** — `app.contentful.com/.../entries/.../preview/...` — open this to review and click the green **Publish** button at the top
-   - **Preview (staging site)** — full staging URL for a full-page check (optional)
-4. Tell the user which entry was changed (title, slug, CMS label)
-5. Remind them: production URL updates 1–3 minutes after publish
+## What gets published
 
-## Confirmation gates
-
-1. Never claim changes are live until a human publishes
-2. Always include the **Live preview** link when `contentfulLivePreview` is available
-3. List draft entries awaiting publish
+- A page publishes its draft and changed assets and components first, then the page. That page publish is what refreshes the live site.
+- The walk does not enter another page, article, or person, and it does not enter a shared template.
+- `schema`, `template`, `navigation`, and the other webhook types can be the target (`--content-type schema`, `--id`, or `--from-session`). Publishing them refreshes caches through their own webhook. Do not republish every page that uses them.
+- A schema linked only from an unpublished page is named in the plan. Publishing the schema does not add that link to the live page.
+- A component publishes its own changes, then the pages that use it. The parent walk climbs through components and collections and stops at the first root. A template on that path is republished itself, because its webhook refreshes the pages that use it. The walk does not continue into those pages.
+- `location` is a root only when the site's `project.json` lists it under `publish.extraRootContentTypes` and the editor pack has been regenerated.
+- Unpublish and archive affect the named entries only, not their children. A published entry is unpublished before it is archived.
+- `redirect` is refused. Redirects go live on deploy.
 
-## Out of scope
+## Revalidate
 
-- Automated publish (intentionally unsupported)
+`revalidate plan` refreshes production cache for the named pages and does not publish. The host needs `REVALIDATION_SECRET` and `PRODUCTION_SITE_URL`. If those are missing, publishing the page still refreshes the site through the Contentful webhook.
 
-## Related resources
+## Confirmation gates
 
-- `cms-edit://customer/task-preview-verify`
-- `cms-edit://customer/overview`
+1. Do not apply a plan unless the user has said yes for that plan id.
+2. Do not claim the site is updated until apply succeeds.
+3. There is no scheduled publish.

package/docs/help/index.md

@@ -1,6 +1,6 @@
 # cms-edit — Help Index
 
-`cms-edit` is an opinionated CLI for reading and editing Contentful draft content across SE Studio apps. It provides a snapshot → ref → edit → save workflow. **All writes create drafts — nothing is published automatically.**
+`cms-edit` is an opinionated CLI for reading and editing Contentful content across SE Studio apps. It provides a snapshot → ref → edit → save workflow. **Saves create drafts.** Publish, unpublish, and archive use a plan and an explicit yes, and only when the Contentful role allows it.
 
 ---
 
@@ -37,6 +37,7 @@ Available topics for `cms-edit help <topic>`:
 | `patterns` | Census published page/article stacks (Delivery API) |
 | `asset-review` | Visual asset quality review (filename, alt, size, dimensions) |
 | `lookup` | Flat flags for `open`, `resolve`, and `nav open` |
+| `publish` | Plan, then publish, unpublish, archive, or revalidate |
 
 ---
 
@@ -134,7 +135,8 @@ cms-edit batch run --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) |
+| `create person` | Create a person entry (draft). `--person-type-id` / `--person-type-slug` link a person type. `--indexed` and `--hidden` take `true` or `false`. |
+| `create person-type` | Create a personType entry (draft). `--person-template-id` links the profile template. |
 | `article-tags-from-json` | Set tags on articles from JSON |
 | `bulk-rtf-replace` | Find-replace in Rich Text across entry trees |
 | `create tag-type` | Create a tagType entry (draft) |

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

@@ -78,6 +78,7 @@ Or batch-link in a `cms-edit batch run` ops file.
 
 | Command | Purpose |
 |---|---|
-| `cms-edit create person` | Create one person |
+| `cms-edit create person` | Create one person. Optional `--person-type-id`, `--person-type-slug`, `--indexed`, `--hidden` |
+| `cms-edit create person-type` | Create one person type (draft) |
 | `cms-edit create person … --if-not-exists` | Idempotent single create |
 | `cms-edit help fields` | Field overview |

package/docs/help/publish.md

@@ -0,0 +1,45 @@
+# Publish, unpublish, archive, revalidate
+
+`save` writes drafts. These commands publish only after a plan and an explicit yes.
+
+The signed-in Contentful user must be allowed to publish, unpublish, or archive. If the role cannot, the command stops before anything is written. AI Editor cannot publish.
+
+## Plan, then yes
+
+```
+cms-edit publish plan
+cms-edit publish choose --plan <id> --scope all
+cms-edit publish apply --plan <id>
+```
+
+`plan` is read-only. If someone else also changed an entry, the plan waits. Ask whether to publish all of those entries or only this user's. Record that with `choose`. Apply only after the user says yes. The same pattern exists for `unpublish`, `archive`, and `revalidate`.
+
+## Targets
+
+Open a page, then `publish plan` publishes that page's draft and changed assets and components, then the page. A component plan climbs through other components and stops at the first page, article, or other root. A template on that path is republished itself.
+
+```
+cms-edit publish plan --content-type schema
+cms-edit publish plan --content-type schema --since 2026-10-02
+cms-edit publish plan --id <entryId>
+cms-edit publish plan --from-session
+```
+
+Schema, template, and navigation publish through their own webhooks. Pages that use them are not republished. A schema that is linked only from an unpublished page is named in the plan.
+
+A site adds extra roots in `project.json`:
+
+```json
+"publish": { "extraRootContentTypes": ["location"] }
+```
+
+Regenerate the editor pack so hosted cms-edit reads `editor-pack/publish.json`.
+
+## Revalidate
+
+```
+cms-edit revalidate plan --id <pageId>
+cms-edit revalidate apply --plan <id>
+```
+
+This refreshes production cache and does not publish. The host needs `REVALIDATION_SECRET` and `PRODUCTION_SITE_URL`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "3.13.1",
-  "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
+  "version": "3.14.0",
+  "description": "CLI tool for AI agents to edit Contentful drafts and, when the user's role allows it, publish after an explicit yes",
   "repository": {
     "type": "git",
     "url": "https://github.com/Something-Else-Studio/se-core-product",

package/skills/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.
 
 ## Safety Rules
 
@@ -576,7 +576,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 +828,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.
 - `--dry-run` prints the full plan without writing anything.
 
 ## Find Existing Entries (for existingId)
@@ -857,7 +857,7 @@ 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. `publish plan --content-type schema` (or the open page, `--id`, `--from-session`) lists what would go live. If someone else also changed an entry, ask all versus mine and `publish choose`. `publish apply --plan <id>` only after the user says yes. 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