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

package/docs/editor-tasks/source-readiness-review.md

@@ -0,0 +1,116 @@
+# Capability: Source readiness review
+
+## Intent phrases
+
+- source readiness
+- review brief before create
+- is this package ready
+- intake case study assets
+- check gaps before building
+- review source package
+- ready to build from document
+
+## Requires capabilities
+
+`pages` or `articles`
+
+## Purpose
+
+Decide whether an external package (document, Drive folder, Figma, production ref, or mix) is **good enough to build CMS structure from** — before any `create` / bulk `save`.
+
+**cms-edit does not rewrite source copy.** Its job is a **faithful representation**: place and structure existing words and assets into the site’s components. Flag quality issues; do not “improve” prose, invent headlines, or invent pair layouts.
+
+## Prerequisites
+
+- Sources available (paste, Drive MCP, Figma link, zip, production URL, etc.)
+- Read site `cms-edit://customer/articles` and/or `pages`, plus `components-index` / `routing` as relevant
+
+## Source hierarchy (when sources disagree)
+
+Prefer, in order, unless the user overrides:
+
+1. **Sequence & layout** — Figma / approved comps
+2. **Art files** — Drive / export package
+3. **Words** — approved copy doc (as written)
+4. **CMS patterns** — production page / site playbook (how to map, not what to invent)
+
+If title, order, or hero asset **conflict** and the user has not decided → **NO-GO** until they choose.
+
+## Steps
+
+1. **Inventory sources** — list every doc, asset, and design ref; note missing items.
+2. **Build inventory table** (required):
+
+   | # | Role | Source file / ref | Status (ready / resize / missing) | Intended CMS mapping |
+   |---|------|-------------------|-----------------------------------|----------------------|
+   | 1 | … | … | … | … |
+
+3. **Build beat sheet** — ordered narrative + visual beats mapped to **registered** component/collection types only (from `components-index` / site playbook). Prefer **source order** over CMS convenience.
+4. **Score verdict** using the threshold below.
+5. **Post one-screen soft-proof** — numbered final `content` (or page stack) order + gap list + verdict.
+6. **Ask for a light human confirm** — accept **yes** / **go** / **proceed** (or equivalent). Do not build on silence if the package is non-trivial.
+7. On **GO** or **GO-WITH-GAPS** + yes → hand off to `task-create-from-document` / `task-create-article` / `task-create-page` with the soft-proof as the plan.
+8. On **NO-GO** → stop; list what is blocking (do not invent structure to unblock).
+
+## Gap threshold
+
+### NO-GO (any one is enough)
+
+- **Sequence unknown** — no Figma/comps/ordered list; building would invent order
+- **Narrative incomplete** — missing major beats the site playbook expects for that content type
+- **Would invent structure** — pairing images the design does not pair; inventing section titles; inventing side-by-side layouts
+- **Conflicting sources** with no owner decision (H1/title, order, hero asset)
+
+### GO-WITH-GAPS
+
+- Sequence **clear** and narrative **usable as written**
+- Missing art slots **≤ 3** **or** **≤ ~25%** of planned visual beats — each **named** with a placeholder strategy
+- Optional/spare assets missing is fine
+- Meta description can be drafted **from existing copy only** (no invented claims); still include in soft-proof for human yes
+
+### GO
+
+- Same as GO-WITH-GAPS with art complete for the soft-proof (or explicit reuse of existing CMS assets identified by id/filename)
+
+## Faithful structure rules
+
+1. **Do not rewrite copy** — structure and place only; flag issues for the human.
+2. **Design sequence beats CMS convenience** — do not invent pair/side-by-side collections unless the source is a true pair.
+3. **Placeholders beat reordering** — keep the slot; label the gap (do not drop missing beats and renumber silently).
+4. **Merge continuous prose** — do not split body-only blocks without a layout reason (art, quote, or design break between).
+5. **Hero / template owns page H1** when the site template provides it — body headings only when the source has section titles.
+6. **Lab / draft flags** — follow site playbook (`lab/…`, `hidden`, `indexed`) for experiments.
+
+## Soft-proof format (minimum)
+
+```text
+Verdict: GO | GO-WITH-GAPS | NO-GO
+Gaps: …
+1. … (component/collection type) — source …
+2. …
+Copy: unchanged from source (list any human decisions only)
+```
+
+## Confirmation gates
+
+1. Verdict + soft-proof posted
+2. Human **yes** (or equivalent) before create when package is non-trivial
+3. NO-GO never proceeds to create without new sources or explicit human override of the blocking item
+
+## Out of scope
+
+- Rewriting or “polishing” source copy
+- Brand voice passes
+- Publish
+- Inventing assets or layout not in the package
+
+## Related resources
+
+- `cms-edit://customer/articles` / `pages` (site composition)
+- `cms-edit://customer/components-index`
+- `task-create-from-document`
+- `task-create-article`
+- `task-create-page`
+- `task-media-pipeline-prepare`
+- `task-media-reuse-and-upload`
+- `task-preview-verify`

package/docs/editor-tasks/taxonomy.md

@@ -0,0 +1,51 @@
+# Capability: Taxonomy setup
+
+## Intent phrases
+
+- create tags
+- set up taxonomy
+- add tag types and tags
+
+## Requires capabilities
+
+`tags`
+
+## Prerequisites
+
+- `cms_edit ["index", "sync"]`
+
+## Steps
+
+**From JSON (batch):**
+
+```
+cms_edit ["create", "taxonomy-from-json", "--json", "<taxonomy-json>", "--if-not-exists"]
+```
+
+**Individual entries:**
+
+```
+cms_edit ["create", "tag-type", "--slug", "topic", "--name", "Topic", "--if-not-exists"]
+cms_edit ["create", "tag", "--slug", "mental-health", "--name", "Mental Health", "--tag-type-slug", "topic", "--if-not-exists"]
+```
+
+Verify:
+
+```
+cms_edit ["list", "--type", "tagType"]
+cms_edit ["list", "--type", "tag"]
+```
+
+## Confirmation gates
+
+1. Show taxonomy plan before import
+2. Summarize created vs existing IDs
+
+## Out of scope
+
+- Publish
+- Assigning tags to articles (see **Article tags** capability)
+
+## Related resources
+
+- `cms-edit://customer/routing`

package/docs/help/article-tags-from-json.md

@@ -0,0 +1,62 @@
+# cms-edit article-tags-from-json — Batch Article Tagging
+
+`article-tags-from-json` sets the `tags` link array on one or more articles from a JSON file. Tag slugs are resolved via the local index — run `cms-edit index sync` first.
+
+```bash
+cms-edit index sync
+cms-edit article-tags-from-json --json '{...}' --dry-run
+cms-edit article-tags-from-json --json '{...}'
+```
+
+All writes create **drafts** only.
+
+**Batch behaviour:** Processes every article in the file. Failures on one article do not stop the rest — the command exits non-zero if any item failed and prints which slugs succeeded vs failed.
+
+---
+
+## JSON schema
+
+```jsonc
+{
+  "articles": [
+    {
+      "articleSlug": "resources/blog/my-post",
+      "tagSlugs": ["asco-2025", "oncology"],
+      "append": false
+    },
+    {
+      "articleSlug": "resources/blog/another-post",
+      "tagSlugs": ["press-release"],
+      "append": true
+    }
+  ]
+}
+```
+
+| Key | Required | Description |
+|---|---|---|
+| `articleSlug` | Yes | Article slug (with or without leading `/`) |
+| `tagSlugs` | Yes | Tag slugs to apply |
+| `append` | No | When `true`, append to existing tags (deduped). Default: replace |
+
+---
+
+## Session alternative (single article)
+
+```bash
+cms-edit open --article-slug resources/blog/my-post
+cms-edit set @p0 tags <id1>,<id2> --links
+cms-edit diff && cms-edit save
+```
+
+Resolve tag IDs: `cms-edit resolve --tag-slug <slug> --json`
+
+---
+
+## Related commands
+
+| Command | Purpose |
+|---|---|
+| `cms-edit create tag` | Create a new tag |
+| `cms-edit create taxonomy-from-json` | Bootstrap tagTypes and tags |
+| `cms-edit help taxonomy-from-json` | Taxonomy batch import |

package/docs/help/asset-review.md

@@ -0,0 +1,56 @@
+# Asset review
+
+`cms-edit asset review` audits visual assets (images, videos, Lottie JSON) from the local index.
+
+## Sync first
+
+```bash
+cms-edit index sync
+```
+
+Default: **Preview API** (includes drafts). Use `--published` on sync/review for delivery-only content.
+
+## Run
+
+```bash
+cms-edit asset review
+cms-edit --json-output asset review --space brightline > media-review.json
+cms-edit --json-output asset review --include-usage --usage-limit 5
+cms-edit --json-output asset review --include-usage --include-passing --usage-limit 0 > image-inventory.json
+```
+
+`--include-usage` adds slug-bearing page/article ancestry per asset (slower; uses CMA walk-up). By default only the first **50** assets in the report get usages (`--usage-limit 50`). Raise the limit for larger batches, or pass `--usage-limit 0` for unlimited (fine locally; hosted MCP may timeout on large spaces). Use with `--include-passing` for a full image inventory (replaces the old `audit images` command).
+
+## Checks
+
+- Filename quality (stock IDs, camera defaults, generic names)
+- Alt text (`description` on asset)
+- Dimensions (max width, default 2000px; SVG/Lottie skipped)
+- File size (defaults: 800 KB images, 8 MB video, 400 KB Lottie)
+- Animated GIF (`image/gif`)
+- No media wrapper (warning — may still be used in rich text)
+
+## Options
+
+| Flag | Default |
+|------|---------|
+| `--max-width` | 2000 |
+| `--max-image-kb` | 800 |
+| `--max-video-mb` | 8 |
+| `--max-lottie-kb` | 400 |
+| `--include-passing` | off (failures only) |
+| `--include-usage` | off (no usage ancestry in JSON) |
+| `--usage-limit` | 50 when `--include-usage` is set (`0` = unlimited) |
+| `--published` | off (Preview index) |
+
+Exit code **1** when any asset has failing issues.
+
+## Spreadsheet
+
+Use the **contentful-cms-media-review** skill with `--json` output to build an Excel workbook.
+
+## Fix alt text
+
+```bash
+cms-edit asset set-description <asset-id> "Descriptive alt text"
+```

package/docs/help/batch-run.md

@@ -0,0 +1,222 @@
+# cms-edit batch run — JSON Operation Scripts
+
+`batch run` executes a sequence of `cms-edit` operations from a JSON file. It is best suited for **patching fields on existing entries** — for creating complete new pages, use `create from-json` instead.
+
+```bash
+cms-edit batch run --json '[...]'
+cms-edit batch run --json '[...]' --dry-run   # validate without saving
+```
+
+---
+
+## Batch File Format
+
+A batch file is a JSON array of operation objects:
+
+```json
+[
+  { "cmd": "open", "args": ["/solutions"] },
+  { "cmd": "set",  "args": ["@c1", "heading", "New Heading"] },
+  { "cmd": "rtf",  "args": ["@c2", "body", "Updated body.\n\nSecond paragraph."] },
+  { "cmd": "save" }
+]
+```
+
+Each operation has:
+
+| Field | Type | Description |
+|---|---|---|
+| `cmd` | string | The operation to execute (see Supported Commands) |
+| `args` | string[] | Positional arguments (same as CLI args) |
+| `opts` | object | Named options (same as CLI flags, without `--`) |
+| `onError` | `"stop"` \| `"continue"` | What to do if this step fails. Default: `"stop"` |
+| `as` | string | Variable name to bind the ref assigned by an `add` op (e.g. `"$item"`) |
+
+---
+
+## Supported Commands
+
+### `open`
+Load a page or article by slug.
+```json
+{ "cmd": "open", "args": ["/solutions"] }
+```
+
+### `set`
+Set a scalar field on an entry.
+```json
+{ "cmd": "set", "args": ["@c1", "heading", "New Heading"] }
+{ "cmd": "set", "args": ["@c2", "backgroundColour", "Navy"] }
+{ "cmd": "set", "args": ["@c3", "heading", null] }
+```
+
+### `rtf`
+Set a rich text field from a markdown string.
+```json
+{ "cmd": "rtf", "args": ["@c2", "body", "## Heading\n\nParagraph text."] }
+```
+
+### `rtf-replace`
+Find and replace text within an existing rich text field.
+```json
+{
+  "cmd": "rtf-replace",
+  "args": ["@c2", "body"],
+  "opts": {
+    "find": "old phrase",
+    "replacePlain": "new phrase",
+    "mode": "all"
+  }
+}
+```
+Options: `find` (required), `replacePlain`, `replaceMarkdown`, `mode` (`"all"` or `"exactlyOne"`), `ignoreMarks`, `tableCol`, `tableRow`, `section`.
+
+### `add`
+Create a new entry and link it into the tree.
+```json
+{ "cmd": "add", "args": ["HeroSimple", "component"] }
+{ "cmd": "add", "args": ["Generic", "component"], "opts": { "parent": "@c3" } }
+{ "cmd": "add", "args": ["Generic", "component"], "opts": { "after": "@c5" } }
+{ "cmd": "add", "args": ["Generic", "component"], "opts": { "target": "topContent" } }
+```
+Options: `parent` (ref of a collection to add inside), `after` (ref to insert after), `target` (field name, default `"content"`), `existingId` (link an existing entry instead of creating).
+
+### `links-add`
+Create a new CTA link and attach it to an entry's `links` field.
+```json
+{ "cmd": "links-add", "args": ["@c1"], "opts": { "type": "external", "label": "Learn More", "href": "https://example.com", "variant": "link" } }
+{ "cmd": "links-add", "args": ["@c1"], "opts": { "type": "internal", "label": "Contact", "slug": "/contact" } }
+```
+Options: `type`, `label`, `href`, `slug`, `id`, `assetId`, `variant`.
+
+### `save`
+Write all modified entries to Contentful as drafts.
+```json
+{ "cmd": "save" }
+```
+
+---
+
+## Variable Binding — Safe `add` + `set` Patterns
+
+**The problem:** After an `add parent @cN` operation, all entries that come after `@cN` in the depth-first tree are renumbered. Any `set` using a hardcoded `@cM` ref may then target the wrong entry, and the batch reports `✓` — a silent false positive.
+
+**The solution:** Use `"as": "$varname"` on the `add` op to capture the assigned ref, then use `"$varname"` in subsequent `set`/`rtf` args:
+
+```json
+[
+  { "cmd": "open", "args": ["/solutions/hepatology"] },
+  {
+    "cmd": "add",
+    "args": ["Generic", "component"],
+    "opts": { "parent": "@c3" },
+    "as": "$item1"
+  },
+  { "cmd": "set", "args": ["$item1", "heading", "2017 — Cohort Launch"] },
+  { "cmd": "rtf", "args": ["$item1", "body", "The cohort was established.\n\nInitial enrolment began."] },
+  {
+    "cmd": "add",
+    "args": ["Generic", "component"],
+    "opts": { "parent": "@c3" },
+    "as": "$item2"
+  },
+  { "cmd": "set", "args": ["$item2", "heading", "2019 — First Publication"] },
+  { "cmd": "save" }
+]
+```
+
+`$item1` and `$item2` always refer to the entries that were just created, regardless of how subsequent adds shift ref numbers.
+
+---
+
+## Ref Renumbering — What Happens Under the Hood
+
+After any `add parent @cN`, refs are reassigned in depth-first traversal order from the root. Items that came *after* `@cN` in the tree get bumped forward.
+
+**Example:** Page with 10 entries (`@c0`–`@c9`). Timeline collection is `@c8`, Disease Areas is `@c9`.
+
+| After add | New item ref | Disease Areas ref |
+|---|---|---|
+| Initial | — | @c9 |
+| Add 1 to @c8 | @c9 | @c10 |
+| Add 2 to @c8 | @c10 | @c11 |
+| Add 3 to @c8 | @c11 | @c12 |
+
+If you write `set @c10 heading "..."` after Add 1, you are setting Disease Areas — not the new item. The batch reports `✓` because the field was set successfully, just on the wrong entry.
+
+**The tool warns when this happens:**
+```
+  ✓ [3] add  — Created component "Generic" as @c9 (ID: abc123)
+  ⚠  Refs renumbered after add-to-parent. Use "as": "$varname" on the add op and "$varname" in subsequent args to avoid ref drift.
+```
+
+---
+
+## Safe Patterns
+
+### Pattern A — Variable binding (recommended)
+Use `"as": "$name"` and `"$name"` in args. Refs always point to the right entry.
+
+### Pattern B — All adds first, then sets
+Do all `add` operations in one batch. Re-snapshot to see final refs. Write a second batch with `set`/`rtf` on the stable refs.
+
+```bash
+# Batch 1: add all items
+cms-edit batch run --json '[...]'
+
+# Inspect final refs
+cms-edit snapshot
+
+# Batch 2: set fields using the stable refs from snapshot
+cms-edit batch run --json '[...]'
+```
+
+### Pattern C — Append to end only
+If new items go at the end of the tree (after all existing entries), no existing refs are displaced. Use `after` to append at the tail.
+
+### Pattern D — Use `create from-json` for new pages
+For building complete page trees from scratch, `create from-json` is safer than a `run` batch — it manages internal refs automatically and validates slugs before writing.
+
+---
+
+## Complete Example — Patching Fields on an Existing Page
+
+```json
+[
+  { "cmd": "open", "args": ["/solutions"] },
+  { "cmd": "set",  "args": ["@c1", "heading", "Evidence-Driven Solutions"] },
+  { "cmd": "set",  "args": ["@c1", "preHeading", "What We Do"] },
+  {
+    "cmd": "rtf",
+    "args": [
+      "@c2",
+      "body",
+      "We partner with life sciences companies.\n\nOur platform integrates real-world data across disease areas."
+    ]
+  },
+  { "cmd": "save" }
+]
+```
+
+Run:
+```bash
+cms-edit batch run --json '[...]' --dry-run   # validate first
+cms-edit batch run --json '[...]'             # apply
+cms-edit open --page-slug /solutions       # inspect result
+```
+
+---
+
+## Error Handling
+
+By default, execution stops on the first error. Use `"onError": "continue"` to keep running:
+
+```json
+[
+  { "cmd": "open", "args": ["/solutions"] },
+  { "cmd": "set",  "args": ["@c99", "heading", "Test"], "onError": "continue" },
+  { "cmd": "save" }
+]
+```
+
+The final exit code is non-zero if any step failed, even with `"continue"`.

package/docs/help/batch.md

@@ -0,0 +1,94 @@
+# Batch edit by entry ID
+
+Edit multiple Contentful entries by ID with scalar field updates. Useful for link variant sweeps, media flags (`autoplay`/`loop`), navigation tweaks, and other standalone updates.
+
+## Sessions
+
+| Context | What happens |
+|---------|----------------|
+| Default CLI (`--session` omitted) | Uses session name **`batch`** (does not touch a separate page session) |
+| Page session already open (e.g. MCP `_mcp`) | `batch set` **stages into that page session** — same `diff` / `save` as article work. Do **not** re-`open`. Do **not** `batch discard` (use `cms-edit discard` only if abandoning everything). |
+| Explicit isolation | `cms-edit --session link-sweep batch set …` |
+
+You can also stay on the page session without `batch`:
+
+```bash
+cms-edit set <entryId>:autoplay=true <entryId>:loop=true
+# or
+cms-edit set <entryId> autoplay true
+```
+
+## Workflow
+
+```bash
+# Queue scalar field updates (one or more entryId:field=value tokens)
+cms-edit batch set 3my7n2M84OrhOaaSLHVHvo:variant=link 7MjsLmOq52CR9C5xrYlcub:variant=button
+
+# Review pending changes
+cms-edit batch diff
+
+# Write all changes as drafts (single save)
+cms-edit batch save
+
+# Or discard without saving (pure batch sessions only)
+cms-edit batch discard
+```
+
+Mid-page (MCP / open article session):
+
+```bash
+cms-edit batch set 5uMh54rIsJRFRQSXDuJiG:autoplay=true
+cms-edit diff
+cms-edit save
+```
+
+## Token format
+
+```
+<entryId>:<fieldId>=<value>
+```
+
+- **entryId** — Contentful entry ID (alphanumeric, optional `_`/`-`, length 1–64; **not** fixed at 22 characters)
+- **fieldId** — field name on that entry's content type
+- **value** — literal token (no shell quotes needed for simple strings). Coercion follows the field type from Contentful:
+  - **Symbol** / **Text** — always stored as strings (e.g. `order=42` stays `"42"`)
+  - **Integer** / **Number** — parsed as numbers
+  - **Boolean** — `true` / `false`
+  - **null** — literal `null`
+  - Fields with enum validations (e.g. `variant`) must match allowed values
+
+Examples:
+
+```bash
+cms-edit batch set abcdefghijklmnopqrstuv:variant=link
+cms-edit batch set 5uMh54rIsJRFRQSXDuJiG:autoplay=true
+cms-edit batch set abcdefghijklmnopqrstuv:cmsLabel=Footer CTA
+```
+
+## Link variant sweep
+
+When you already know link entry IDs (from `cms-edit read @cN links` or `cms-edit links list @cN`):
+
+```bash
+cms-edit batch set \
+  idOne123456789012345678:variant=link \
+  idTwo123456789012345678:variant=button
+cms-edit batch diff
+cms-edit batch save
+```
+
+When a page is already open, prefer `cms-edit links set @cN <index> variant link` instead.
+
+## Content type schema cache
+
+Field types and enum validations are loaded from the Contentful Management API. Results are cached:
+
+- In the **session file** (`contentTypes` on the session) so `batch set` → save reuse schema without extra API calls
+- On disk at `~/.contentful-cms/content-types/<spaceId>/<environment>/` (24-hour TTL)
+
+## v1 limits
+
+- **Scalar fields only** — no rich text, entry links, asset links, or link arrays
+- **Draft-only** — same as `cms-edit save`; never publishes
+- **No cross-entry link arrays** — use page session + `cms-edit set --links` for parent arrays
+- **Partial save on failure** — if one entry fails during `batch save`, earlier entries may already be saved; the CLI lists failures and reminds you to run diff for remaining changes

package/docs/help/bulk-rtf-replace.md

@@ -0,0 +1,80 @@
+# cms-edit bulk-rtf-replace — Sitewide Rich Text Find-Replace
+
+`bulk-rtf-replace` finds plain text in Rich Text fields across page and article entry trees (including linked components and collections) and replaces it in one pass.
+
+```bash
+cms-edit bulk-rtf-replace --find "Old Company Name" --replace-plain "New Company Name" --dry-run
+cms-edit bulk-rtf-replace --find "Old Company Name" --replace-plain "New Company Name"
+```
+
+**Always dry-run first** and confirm the match count with the user before saving.
+
+All saves create **drafts** only.
+
+---
+
+## How it works
+
+1. Fetches root entries (`page` and `article` by default) from Contentful
+2. For each root, loads the full linked entry tree
+3. Scans every Rich Text field on every entry in the tree
+4. Applies `replace-plain` (same engine as `cms-edit rtf replace`)
+5. Saves each modified entry as a draft
+
+---
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--find <text>` | Plain text to find (required) |
+| `--replace-plain <text>` | Plain text replacement (required) |
+| `--include <types>` | Root content types (default: `page,article`) |
+| `--prefix <slug>` | Only roots whose slug starts with this prefix (e.g. `/blog`) |
+| `--limit <n>` | Max root entries total across all `--include` types (default: 500) |
+| `--dry-run` | Report matches without saving |
+
+---
+
+## Scoped replace
+
+```bash
+# Blog articles only
+cms-edit bulk-rtf-replace \
+  --find "2024" \
+  --replace-plain "2025" \
+  --include article \
+  --prefix resources/blog \
+  --dry-run
+```
+
+---
+
+## JSON output
+
+```bash
+CMS_EDIT_JSON=1 cms-edit bulk-rtf-replace --find "foo" --replace-plain "bar" --dry-run
+```
+
+Dry-run response includes `entriesWithMatches`, `matches`, and per-entry `changes`.
+
+---
+
+## When to use sessions instead
+
+For a **small** number of entries, or when you need `diff` review per page:
+
+```bash
+cms-edit open --page-slug /about
+cms-edit rtf replace @c1 body --find "…" --replace-plain "…"
+cms-edit diff && cms-edit save
+```
+
+For **scalar** fields on many entries, prefer `cms-edit batch set`.
+
+---
+
+## Related resources
+
+- Editor task: `task-bulk-find-replace` (confirmation gates)
+- `cms-edit search <text>` — discover affected entries before bulk replace