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

package/docs/editor-tasks/article-tags.md

@@ -0,0 +1,47 @@
+# Capability: Article tags
+
+## Intent phrases
+
+- update article tags
+- retag articles
+- add tags to blog posts
+
+## Requires capabilities
+
+`articles` and `tags`
+
+## Prerequisites
+
+- `cms_edit ["index", "sync"]`
+- Resolve tag IDs: `resolve --tag-slug <slug> --tag-type-slug <type>` or `list --type tag`
+
+## Steps
+
+**Batch (many articles):**
+
+1. Build `tags.json` with an `articles` array (see `cms-edit help article-tags-from-json`)
+2. `cms_edit ["article-tags-from-json", "--json", "<tags-json>", "--dry-run"]`
+3. User confirms tag slugs per article
+4. `cms_edit ["article-tags-from-json", "--json", "<tags-json>"]`
+
+**Single article (session):**
+
+1. `cms_edit ["open", "--article-slug", "<slug>"]`
+2. `cms_edit ["set", "@p0", "tags", "<id1>,<id2>", "--links"]` (or `--append`)
+3. `cms_edit ["diff"]` → `cms_edit ["save"]`
+
+## Confirmation gates
+
+1. List target articles and tag slugs — user confirms
+2. `diff` before each `save` when using sessions
+
+## Out of scope
+
+- Publish
+- Creating new tags (see **Taxonomy** capability first)
+
+## Related resources
+
+- `cms-edit://customer/articles`
+- `task-taxonomy`
+- `cms-edit help article-tags-from-json`

package/docs/editor-tasks/authors-import.md

@@ -0,0 +1,53 @@
+# Capability: Authors (person entries)
+
+## Intent phrases
+
+- create authors
+- import people from spreadsheet
+- add team members to CMS
+
+## Requires capabilities
+
+`persons`
+
+## Prerequisites
+
+- `cms_edit ["index", "sync"]` if linking to articles
+- Convert spreadsheet to a structured list (name, slug, jobTitle, bio, email)
+
+## Steps
+
+**Batch import (recommended):**
+
+1. Build `authors.json` with a `persons` array (see `cms-edit help person-from-json`)
+2. `cms_edit ["create", "person-from-json", "--json", "<authors-json>", "--dry-run"]`
+3. User confirms the list
+4. `cms_edit ["create", "person-from-json", "--json", "<authors-json>", "--if-not-exists"]`
+
+**Single person:**
+
+```bash
+cms_edit ["create", "person", "--slug", "<slug>", "--name", "<name>", "--job-title", "…", "--bio-markdown", "…"]
+```
+
+**Link to articles:**
+
+```
+cms_edit ["open", "--article-slug", "<slug>"]
+cms_edit ["set", "@p0", "authors", "<personId1>,<personId2>", "--links"]
+cms_edit ["diff"] → cms_edit ["save"]
+```
+
+## Confirmation gates
+
+1. Show person list from spreadsheet — user confirms
+2. `diff` before `save` when using sessions
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/routing` (people URL base if configured)
+- `cms-edit help person-from-json`

package/docs/editor-tasks/bulk-find-replace.md

@@ -0,0 +1,52 @@
+# Capability: Bulk find-replace in rich text
+
+## Intent phrases
+
+- find and replace across pages
+- change text sitewide in body copy
+- update legal boilerplate everywhere
+
+## Requires capabilities
+
+`bulkRtfFindReplace`
+
+## Prerequisites
+
+- `cms_edit ["index", "sync"]` if catalog may be stale
+- `cms_edit ["list", "--type", "page"]` / `["list", "--type", "article"]` or `cms_edit ["search", "<find text>"]` to list affected entries
+- Read `cms-edit://customer/routing` for slug rules
+
+## Steps
+
+1. **Discover scope** — `search` or `list --type page|article`; propose affected page/article count to the user
+2. **Dry-run bulk replace:**
+   ```
+   cms_edit ["bulk-rtf-replace", "--find", "…", "--replace-plain", "…", "--dry-run"]
+   ```
+   Optional: `--include article`, `--prefix resources/blog`
+3. **User approves** find/replace text and match count
+4. **Apply:**
+   ```
+   cms_edit ["bulk-rtf-replace", "--find", "…", "--replace-plain", "…"]
+   ```
+5. Summarize how many entries were updated
+
+For a **small** number of entries, or when per-entry `diff` is required, use session workflow: `open` → `rtf replace` → `diff` → `save`.
+
+For scalar fields on many entries (when the field exists on this schema), prefer `batch set` with entry IDs.
+
+## Confirmation gates
+
+1. Propose find/replace text and affected entry count — **wait for user approval**
+2. Dry-run before apply
+3. Report summary when complete
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/capabilities`
+- `cms-edit://customer/site-facts` (if present — canonical values to apply)
+- `cms-edit help bulk-rtf-replace`

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

@@ -0,0 +1,39 @@
+# Capability: Clone page structure
+
+## Intent phrases
+
+- copy page layout
+- duplicate page structure
+- use existing page as template
+
+## Requires capabilities
+
+`pages`
+
+## Prerequisites
+
+- Identify source page slug and target slug/title
+- Read `cms-edit://customer/components-index`
+
+## Steps
+
+1. `cms_edit ["open", "--page-slug", "<source-slug>"]`
+2. `cms_edit ["snapshot"]` — note template and component tree
+3. `cms_edit ["list", "--type", "template"]` — confirm template ID
+4. Build `create from-json` payload mirroring structure with new slug/title
+5. `create from-json --dry-run --strict` → create → `save`
+6. Adjust copy/fields on the new page
+
+## Confirmation gates
+
+1. Confirm source page, new slug, and title
+2. `--dry-run --strict` before create
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/components-index`
+- `task-create-page`

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

@@ -0,0 +1,77 @@
+# Capability: Create an article
+
+## Intent phrases
+
+- create a blog post
+- new article
+- add publication
+- press release
+- case study
+
+## Requires capabilities
+
+`articles`
+
+## Prerequisites
+
+- Read `cms-edit://customer/articles`, `defaults`, `routing`, `components-index`
+- `cms_edit ["index", "sync"]`
+- `cms_edit ["list", "--type", "articleType"]` — every article needs an article type
+- **External package** (Drive, Figma, brief, zip, multi-file): complete **`task-source-readiness-review`** first, then treat the soft-proof as the composition plan
+- Field-only creates (title/slug/type already decided, no external pack): readiness optional
+
+## Steps
+
+1. Resolve article type slug/name (`list --type articleType`)
+2. Read site **`articles`** playbook for required fields, tags, lab rules, and which components belong in `content`
+3. **Check template hierarchy** — inspect `articleType.articleTemplate` (`peek --id <template-id>`). Do not add hero/layout components to `content` when the template's `preContent` / `postContent` already provides them
+4. **Composition follows the site playbook and the soft-proof** — prefer **source sequence**. Do not invent side-by-side / pair layouts unless the source is a true pair. Merge continuous prose into fewer body blocks when nothing visual sits between.
+5. **Do not rewrite source copy** — structure and place only; flag issues for the human
+6. Ask about custom images; apply `defaults` and playbook rules for `featuredImage` and `visuals` (set explicitly when the playbook requires both). Prefer reuse (`task-media-reuse-and-upload`); use labeled placeholders for missing soft-proof slots
+7. Build `create from-json` payload (article fields + body components per playbook) **or** incremental `add` / `set` / `rtf` for multi-block work
+8. `cms_edit ["create", "from-json", "--json", "<compact-json>", "--dry-run", "--strict"]`
+9. On approval, create and `save`
+10. `task-preview-verify` — include multi-block soft-proof QA when the article is multi-block
+
+Or minimal shell (simple creates only):
+
+```
+cms_edit ["create", "article", "--slug", "<slug>", "--title", "<title>", "--article-type-slug", "<type>"]
+```
+
+## Before save
+
+Confirm (site playbook may add more):
+
+- [ ] `title`, `slug`, `date`, `articleType` correct
+- [ ] `description` set and under ~160 characters when used for SEO meta (site playbook may require 120–160 and refuse thin text)
+- [ ] `tags` / primary tag set when URL includes a topic segment
+- [ ] `featuredImage` and `visuals` per playbook (`featuredImage` landscape for OG when used for social)
+- [ ] `content` matches soft-proof order; only component types the playbook allows (no duplicate heroes from template)
+- [ ] No invented pairs/headings; missing art still represented as placeholders when GO-WITH-GAPS
+- [ ] Component `cmsLabel` values renamed from defaults ("New …")
+- [ ] `indexed` / `hidden` per playbook (lab ports often `hidden: true`, `indexed: false`)
+- [ ] `diff` reviewed, then `save`
+
+## Confirmation gates
+
+1. Source readiness + soft-proof when building from an external package
+2. Confirm slug, title, article type, tags, and image choices with the user (light **yes** is enough)
+3. `--dry-run --strict` before create when using from-json
+4. `diff` before `save`
+
+## Out of scope
+
+- Publish
+- Rewriting source copy
+- Inventing layout not in the source / soft-proof
+
+## Related resources
+
+- `cms-edit://customer/articles`
+- `cms-edit://customer/defaults`
+- `task-source-readiness-review`
+- `task-create-from-document`
+- `task-preview-verify`
+- `task-media-reuse-and-upload`
+- `cms-edit help fields-article` — field reference and template hierarchy

package/docs/editor-tasks/create-from-document.md

@@ -0,0 +1,77 @@
+# Capability: Create from a document
+
+## Intent phrases
+
+- create from Google Doc
+- import from document
+- build page from a brief
+- build article from Drive
+- create from Figma and copy
+
+## Requires capabilities
+
+`pages` or `articles`
+
+## Prerequisites
+
+- Fetch package materials (Google Drive MCP, paste, Figma link, zip, production ref, or mix)
+- Read `cms-edit://customer/components-index`, `routing`, and for articles **`articles`**
+- **Non-trivial packages:** complete **`task-source-readiness-review`** first (inventory → beat sheet → verdict → light human yes)
+
+## Steps
+
+### Phase 0 — Source readiness (mandatory for external packages)
+
+1. Run **`task-source-readiness-review`** (or follow it inline).
+2. Accept multi-source packages — not only a single Google Doc (Drive assets + Figma sequence + copy doc is normal).
+3. On **NO-GO**, stop. On **GO** / **GO-WITH-GAPS**, keep the soft-proof as the build plan.
+4. **Do not rewrite source copy.** Structure and place only.
+
+### Phase 1 — Media pack (when the package has Drive/binary masters)
+
+1. If the package includes a **folder of images/videos** (typical case study): run **`task-media-pipeline-prepare`** **before** building blocks.
+2. Prefer pipeline **ready public URLs** + reuse-first import over mid-build staged upload of oversized masters.
+3. On import: use **`onlyWithOverrides` or `sourceNames`** so only beat-sheet assets land in Contentful; **dryRun first**; use unique `fileName` overrides when you must not reuse prior lab assets.
+4. Keep the `sourceName → assetId` / `mediaId` map for Phase 2 field linking. Singular component visuals: `set @cN visual <mediaId> --link` (never `add --target visual`).
+5. Skip this phase only when every needed visual is already in the Contentful library (confirmed via `asset search`).
+
+### Phase 2 — Plan and create
+
+1. Read `cms-edit://customer/tasks-index` and relevant playbooks (`articles` / `pages`).
+2. Map soft-proof beats to **registered** component types only — prefer **source order** over CMS convenience (do not invent side-by-side pairs unless the source is a true pair).
+3. **Propose plan** (can reuse the soft-proof): slug, title, template/article type, ordered component list, gap/placeholder list, **asset map** — **ask user to confirm** with a light **yes** if not already confirmed.
+4. For pages: `list --type template` — pick template; check template `preContent` / `postContent` so heroes are not duplicated.
+5. For articles: resolve `articleType`; apply site SEO and lab rules from `articles` playbook.
+6. Build `create from-json` payload **or** prefer incremental `open` → `add` / `set` / `rtf` for large multi-block work. Link visuals using the pack map from Phase 1.
+7. `cms_edit ["create", "from-json", "--json", "<compact-json>", "--dry-run", "--strict"]` when using JSON (or `--json-base64` for large payloads).
+8. On approval, create and `save`.
+9. `cms_edit ["preview", "urls", "<slug>"]` — follow **`task-preview-verify`** (including multi-block soft-proof QA when relevant).
+10. Remind user to publish in Contentful UI (never publish lab entries unless explicitly asked).
+
+Use MCP prompts `cms_edit_create_from_doc` or `cms_edit_create_article_from_doc` when available — still run readiness first for external packages.
+
+## Confirmation gates
+
+1. Source readiness verdict + soft-proof (non-trivial packages)
+2. Plain-English plan — light human **yes** before create
+3. `--dry-run --strict` when using from-json
+4. `diff` before `save`
+
+## Out of scope
+
+- Publish
+- **Rewriting source copy** (flag only)
+- Asset upload without reuse check (see **Media** capability)
+- Mid-article ffmpeg / Drive size thrash — use **`task-media-pipeline-prepare`** first
+- Inventing layout, section titles, or pair collections absent from the source
+
+## Related resources
+
+- `cms-edit://customer/components-index`
+- `cms-edit://customer/articles` / `pages`
+- `task-source-readiness-review`
+- `task-media-pipeline-prepare`
+- `task-create-article`
+- `task-create-page`
+- `task-media-reuse-and-upload`
+- `task-preview-verify`

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

@@ -0,0 +1,45 @@
+# Capability: Create a page
+
+## Intent phrases
+
+- create a new page
+- add a landing page
+- new marketing page
+
+## Requires capabilities
+
+`pages`
+
+## Prerequisites
+
+- Read `cms-edit://customer/components-index` and `cms-edit://customer/routing`
+- `cms_edit ["index", "sync"]` for template lookup
+
+## 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"]`
+
+For multi-component pages, prefer `create from-json --json '{…}' --dry-run --strict` first.
+
+After each `add`, set `heading` then `cmsLabel` (not left as `New Generic`).
+
+Test/agent pages: `indexed: false`, omit `hidden` (visible on production when published).
+
+## Confirmation gates
+
+1. Confirm slug, title, and template with user
+2. `create from-json --dry-run --strict` before create when using JSON
+3. `diff` before `save`
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/components-index`
+- `task-create-from-document` for doc-driven pages

package/docs/editor-tasks/edit-rich-text.md

@@ -0,0 +1,44 @@
+# Capability: Edit rich text
+
+## Intent phrases
+
+- edit body copy
+- update a paragraph
+- change rich text content
+
+## Requires capabilities
+
+Always available.
+
+## Prerequisites
+
+- Open session on the target page or article
+- `snapshot` to locate RTF fields on `@ref` nodes
+
+## Steps
+
+1. `cms_edit ["open", "--page-slug", "<slug>"]`
+2. `cms_edit ["snapshot"]`
+3. `cms_edit ["read", "@cN", "body"]` — inspect RTF field name
+4. `cms_edit ["rtf", "@cN", "body", "--content", "<markdown or plain>"]`
+5. `cms_edit ["diff"]`
+6. `cms_edit ["save"]`
+
+For partial updates within one RTF field:
+
+```
+cms_edit ["rtf", "replace", "@cN", "body", "--find", "old text", "--replace-plain", "new text"]
+```
+
+## Confirmation gates
+
+1. Identify the `@ref` and field before editing
+2. Show `diff` before `save`
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/components-index`

package/docs/editor-tasks/edit-scalar-fields.md

@@ -0,0 +1,47 @@
+# Capability: Edit scalar fields
+
+## Intent phrases
+
+- change a field on a page or article
+- update title or description
+- set a tracking field
+
+## Requires capabilities
+
+Always available.
+
+## Prerequisites
+
+- Open the target entry: `open --page-slug` or `open --article-slug`
+- `snapshot` to find `@ref` IDs
+
+## Steps
+
+1. `cms_edit ["open", "--page-slug", "<slug>"]` (or `--article-slug`)
+2. `cms_edit ["snapshot"]`
+3. `cms_edit ["read", "@p0", "fieldName"]` — inspect current value
+4. `cms_edit ["set", "@p0", "fieldName", "new value"]`
+5. `cms_edit ["diff"]` — review all changes
+6. `cms_edit ["save"]`
+
+For unrelated entries in one session, use `batch set`:
+
+```
+cms_edit ["batch", "set", "<entryId>:description=New meta", "<entryId2>:title=New title"]
+cms_edit ["batch", "save"]
+```
+
+## Confirmation gates
+
+1. State which entry and field you will change
+2. Show `diff` before `save`
+
+## Out of scope
+
+- Publish (human in Contentful UI)
+- Rich text fields (use **Edit rich text** capability)
+
+## Related resources
+
+- `cms-edit://customer/routing`
+- `cms-edit://customer/components-index`

package/docs/editor-tasks/featured-images.md

@@ -0,0 +1,46 @@
+# Capability: Featured images
+
+## Intent phrases
+
+- set featured image
+- social sharing image
+- OG image for article
+
+## Requires capabilities
+
+`pages` or `articles`
+
+## Prerequisites
+
+- Read `cms-edit://customer/defaults` for article inheritance rules
+- **Reuse-first:** `task-media-reuse-and-upload`
+
+## Steps
+
+**Articles — decision tree:**
+
+1. Custom image on article when editor provides one
+2. Else inherit from linked **articleType** featured image
+3. Else site default from `editor.defaults`
+
+**Pages:** **required** for new pages (reuse-first). No automatic fallback — set explicitly or via from-json.
+
+```
+cms_edit ["set", "@p0", "featuredImage", "<assetId>", "--links"]
+```
+
+Or in from-json: `featuredImageAssetFilename` after `index sync`.
+
+## Confirmation gates
+
+1. Confirm image choice (custom vs inherited)
+2. `diff` before `save`
+
+## Out of scope
+
+- Publish
+
+## Related resources
+
+- `cms-edit://customer/defaults`
+- `task-media-reuse-and-upload`