CMS Changelog Sync

Push draft release notes to Strapi (release-notes content type). Docs changelog stays full; CMS uses committed staging with popup-sized copy.

Architecture

Three separate steps — stop for human review between each:

changelog/index.mdx                    ← docs source of truth (full EN)
        │
        ▼  Step 1: pnpm cms:prepare:en
staging/en/changelog/index.mdx         ← simplified popup EN → **review & approve**
        │
        ▼  Step 2: pnpm cms:prepare:locales
staging/{zh,ja,ko,fr,ru,es}/…          ← translated from staging EN → **review & approve**
        │
        ▼  Step 3: pnpm cms:preview → cms:sync  (only after user confirms)
Strapi CMS (draft) → manual Publish → published-versions.json

Never edit docs zh/changelog/ for CMS. Never auto-publish in Strapi. Never use pnpm translate for CMS — that pipeline is for Mintlify docs only.

Three-step workflow (local)

Step	Command	What it does	Gate
1. Simplify EN	`pnpm cms:prepare:en -- --force v0.26.0`	docs → LLM → `staging/en/`	Review EN staging
2. Translate	`pnpm cms:prepare:locales -- --force v0.26.0`	`staging/en/` → `staging/{zh,ja,ko,fr,ru,es}/`	Review locale staging
3. Push CMS	`pnpm cms:preview` then `pnpm cms:sync`	staging → Strapi drafts	Strapi review → `cms:publish`

pnpm cms:prepare without --en-only / --translate-only prints help and exits — use the step-specific scripts above.

Translation workflow (CMS staging)

Step 2 only. Input = simplified EN staging, not docs changelog.

staging/en/changelog/index.mdx          ← input (Step 1 output, human-approved)
        │
        ▼  pnpm cms:prepare:locales -- v0.26.0
staging/zh|ja|ko|fr|ru|es/changelog/…   ← output (popup copy per locale, ready to sync)
        │
        ▼  pnpm cms:sync  (Step 3, after user confirms)
Strapi release-notes (draft)

	Mintlify docs (`pnpm translate`)	CMS popup (`pnpm cms:prepare:locales`)
English source	`changelog/index.mdx` (full docs)	`staging/en/changelog/index.mdx` (simplified popup)
Output path	`zh/changelog/index.mdx`, etc.	`staging/zh/changelog/index.mdx`, etc.
Purpose	Docs site	Strapi in-app notification
Mix pipelines?	No	No

Key points:

cms:prepare:locales does not re-simplify English — it reads each project’s own staging EN (staging/en/ and staging/cloud/en/)
If staging EN is missing the version, translate fails — run cms:prepare:en first
Target locales: zh, ja, ko, fr, ru, es (see cms-config.json)
--force re-translates existing locale blocks (common after manual EN edits)
Never copy comfyui locale files onto cloud; cloud campaign shortlinks live on cloud EN

Environment (`.env.local`)

Variable	Used by	Notes
`TRANSLATE_API_KEY`	prepare	Same as `pnpm translate`
`TRANSLATE_API_BASE_URL`	prepare	e.g. `https://api.deepseek.com`
`TRANSLATE_API_MODEL`	prepare	e.g. `deepseek-v4-pro`
`CMS_BASE_URL`	sync, delete-drafts	e.g. `https://cms.comfy.org`
`CMS_API_TOKEN`	sync, delete-drafts	Strapi API token
`CMS_PROJECT`	optional	Default `comfyui`; also `--project cloud` on CLI

CI: CMS_BASE_URL / TRANSLATE_API_BASE_URL → GitHub Variables; tokens → Secrets. Prompt: .github/scripts/cms/cms-simplify-prompt.ts
Config: .github/scripts/cms/cms-config.json → simplify

Rule	Value
Total bullets per version	up to 10 (`max_bullets_total: 10`)
Section headings max	3 (`max_sections: 3`)
Section order	New Open-Source Model Support → Partner Node Updates → New Node Updates (optional)
Words per version	~60–120
Bullet format	`[Name](pr_url): 6–12 words with one key trait`
PR links	Keep when source has them; never invent URLs
New Node Updates	Optional by default for new built-in nodes. Omit from CMS popup even if docs has New Nodes, unless a human asks or the version has a core-node lifecycle change (deprecation, removal, replacement, EOL)
Node lifecycle	Never drop. Deprecation, removal, replacement, and EOL belong in Partner Node Updates (partner/API) or New Node Updates (core/built-in). See Node lifecycle (deprecation, removal, replacement, EOL)
Drop	Bug fixes, performance, pure Load3D plumbing, internal refactors, ComfyUI-WIKI dependency bumps (see below), and ordinary New Nodes unless requested. Do not drop lifecycle items

Style: principle-only prompt in cms-simplify-prompt.ts (no concrete version examples — avoids LLM contamination). prepare:en copies docs URLs and local-length copy into Cloud. After it runs, rewrite Cloud EN (links and wording) before translating. Never invent URLs. Copy length (local vs Cloud): Cloud popup users skim. After merge, shorten Cloud bullets so they do not list every node, mode, or task type. One short clause is enough: added the model, or one capability. Local CMS (staging/en/) and docs changelog/index.mdx can keep the fuller scope (which nodes, which modes). Do not shorten local to match Cloud. Example: docs/local may say H3 Max landed on text-to-video, first-last-frame, and reference nodes. Cloud: Added H3 Max model support. Lifecycle bullets stay on Cloud; only shorten the wording, do not omit the deprecation, removal, replacement, or EOL.

Bullet links (docs, local CMS, Cloud CMS)

Resolve each feature bullet before cms:prepare:locales. Search these sources every time a new version lands:

Source	Where
Template index	templates/index.json (raw: `https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/templates/index.json`)
Blog	blog.comfy.org (archive)

Match a template by name, title, or models to the changelog item. Match a blog post only if it covers this product or version (MiniMax H3 day-0 is not MiniMax H3 Max). Video templates: when several templates exist, pick one by suffix on name, in this order: r2v → i2v → t2v. Example: api_minimax_h3_max_r2v over _i2v / _t2v. If none of those suffixes exist, use the remaining matching template (flf2v, edit, and similar). Cloud URL shape: https://cloud.comfy.org/?template=<name> (no UTM unless the user supplied one).

Surface	Link priority (first match wins)
Cloud CMS (`staging/cloud/`)	1. UTM / `links.comfy.org` URL the user provided 2. Cloud template URL from the index 3. GitHub PR 4. ComfyUI repo commit/tag/compare
Docs `changelog/index.mdx` and local CMS (`staging/en/` etc.)	1. Matching blog.comfy.org post 2. GitHub PR 3. ComfyUI repo commit/tag/compare

Do not put Cloud ?template= URLs on docs or local popup. Do not copy local blog/PR links onto Cloud when a template (or user UTM) exists. After prepare:en merges comfyui → cloud, replace Cloud bullets that still point at PRs if the index has a template.

ComfyUI-WIKI commits (omit from changelog)

When curating changelog/index.mdx from ComfyUI git history, do not add bullets for commits routinely opened by ComfyUI-WIKI — they are dependency/content syncs, not core release features:

Skip	Typical commit / PR pattern
Embedded docs	`chore: update embedded docs to v…`, `comfyui-embedded-docs` in `requirements.txt`
Workflow templates	`chore: update workflow templates to v…`, `comfyui-workflow-templates` in `requirements.txt`
Model blueprints	`Add new model blueprints`, blueprint starter workflows in template library

Also omit standalone frontend package semver bumps unless tied to a user-visible fix worth its own bullet. CMS simplify must never promote WIKI-only items into popup copy even if they appear in the full docs block.

Node lifecycle (deprecation, removal, replacement, EOL)

When curating changelog/index.mdx or simplifying CMS staging, do not skip user-facing node lifecycle changes. These are not “minor cleanup.” Users need to know a node or model option is going away, already gone, or swapped for a successor.

Change	What to write	Where
Deprecated	Mark the node or model as deprecated. Include the date or version if the source has one	Partner or node section below
Removed	Say what was removed (node, model option, or API). Prefer “removed” over vague “updated”	Same
Replaced	Name both the old node/model and the replacement. One bullet can cover the swap	Same
EOL / retired	State EOL or retirement, plus what users should use instead when a successor exists	Same

Section placement:

Partner / API nodes (including a partner model option dropped from an existing node): put the bullet under Partner Node Updates. Partner removals, deprecations, replacements, and EOL are first-class partner updates, not an optional extra.
Core / built-in nodes (non-partner): put the bullet under New Node Updates (or New Nodes if that is the heading already in the docs block). For CMS, emit New Node Updates when the only reason to include that section is a lifecycle change, even if nobody asked to list ordinary new nodes.

Writing rules:

Prefer a title that states the event: Kling EOL, Reve deprecated, Google Veo with “Removed …” in the body. Do not bury a removal inside an unrelated “added X” bullet.
If the same PR both adds a successor and removes the old node, you may use one bullet that names both. If they are separate products, use two bullets (add under the usual new-item style; lifecycle under this rule).
Keep Cloud copy short, but still mention the event: Removed retiring Veo 2 and Veo 3.0. Do not drop lifecycle bullets when shortening Cloud.
CMS simplify must keep these items. They are not in the Drop list. Do not treat “removed” or “deprecated” as internal refactors.

Example staging shape

Placeholders only. New Node Updates is optional for ordinary new nodes, and required when a core/built-in lifecycle change is in the source:

**New Open-Source Model Support**
* [**Model Name**](source_url): Short description with 1–2 traits from the release data

**Partner Node Updates**
* [**Partner Node**](source_url): Partner scope and capability from the release data
* [**Partner Node EOL**](source_url): Removed or retired partner nodes, and the replacement when one exists

Only when a human asks to include ordinary new nodes, or when a core/built-in node is deprecated, removed, replaced, or EOL:

**New Node Updates**
* [**Node Name**](source_url): What the node does and why it matters
* [**Node Name deprecated**](source_url): Deprecated or removed; name the replacement when one exists

Sync adds header: # ComfyUI vX.Y.Z via format-cms-content.ts.

Projects (comfyui + cloud)

cms:prepare may generate both projects so staging stays mirrored. For cms:sync and cms:publish, agents must treat comfyui as the default project and pass --project comfyui. Only sync or publish cloud after the user explicitly confirms cloud, using --project cloud. Same changelog content; Strapi project field and CMS header differ (# ComfyUI vs # Cloud).

Project	Staging path	CMS header
`comfyui`	`staging/{locale}/…`	`# ComfyUI vX.Y.Z`
`cloud`	`staging/cloud/{locale}/…`	`# Cloud vX.Y.Z`

When prepare:en targets both projects, it runs the LLM once on comfyui, then merges those version blocks into cloud while keeping any tracking shortlinks already on cloud EN for that version. prepare:locales translates each project from its own staging EN. It does not copy comfyui locale files onto cloud. With --project cloud alone, cloud is prepared directly. Sync/publish must be project-scoped by agents: --project comfyui first, then --project cloud only after explicit cloud approval. Single project: --project comfyui, --project cloud, or CMS_PROJECT=<project>. Mark a version high attention:

pnpm cms:set-attention -- cloud v0.24.0 high --save

Commands

Command	Action
`pnpm cms:prepare:en`	Step 1 — LLM simplify docs EN → `staging/en/` (no translation)
`pnpm cms:prepare:locales`	Step 2 — translate `staging/en/` → `staging/{zh,ja,ko,fr,ru,es}/` (does not re-simplify EN)
`pnpm cms:preview -- v0.25.1`	Step 3a — Dry-run Strapi push
`pnpm cms:sync -- v0.25.1`	Step 3b — Push/update drafts (run only after user confirms staging)
`pnpm cms:publish -- v0.25.1`	Publish + refresh `published-versions.json`
`pnpm cms:prepare`	Prints three-step help and exits when no mode flag is passed
`pnpm cms:set-attention -- cloud v0.24.0 high`	Set attention low/high in Strapi
`pnpm cms:delete-drafts --preview`	List deletable Strapi drafts
`pnpm cms:delete-drafts`	Delete drafts (keeps published)

Flags (after --):

--force — re-simplify/re-translate even if staging has the version; on sync, update already-published CMS entries (default skips published)
--preview / --dry-run — no API writes
--project cloud — single project only (default = both)
v0.25.1 — explicit version(s)

Env:

CMS_SYNC_ALL=1 — include already-published versions (backfill)
Without it, local default = all unpublished EN versions per published-versions.json

Requires Bun. Loads .env.local automatically.

Standard workflow

New release version

Add full <Update> block to changelog/index.mdx (docs quality, unchanged). Set each bullet URL using Bullet links (blog → PR → repo for docs). If the release deprecates, removes, replaces, or EOLs a node (especially a Partner Node), add that under Partner Node Updates or New Node Updates per Node lifecycle.
Step 1 — Simplify EN — review before translating:
pnpm cms:prepare:en -- --force v0.25.1
Inspect: .github/scripts/cms/staging/en/changelog/index.mdx (blog/PR/repo, fuller copy). Rewrite .github/scripts/cms/staging/cloud/en/changelog/index.mdx: user UTM or ?template= from the index, and shorter bullets (model support, not every node). → stop until approved

Step 2 — Translate — from approved staging EN only:

pnpm cms:prepare:locales -- v0.25.1          # first translate
pnpm cms:prepare:locales -- --force v0.25.1 # re-translate after EN edits

Inspect: .github/scripts/cms/staging/zh/changelog/index.mdx (and other locales) → stop until approved

Step 3 — Push ComfyUI drafts (only after user confirms staging):

pnpm cms:preview -- --project comfyui v0.25.1
pnpm cms:sync -- --project comfyui v0.25.1

Publish ComfyUI after Strapi review:

pnpm cms:publish --preview -- --project comfyui v0.25.1
pnpm cms:publish -- --project comfyui v0.25.1

Cloud is separate: run cloud preview/sync/publish only after the user explicitly confirms cloud, using --project cloud.
Commit .github/scripts/cms/staging/ and .github/scripts/cms/published-versions.json after publish.

Catch up all unpublished versions locally

pnpm cms:prepare:en -- --force              # Step 1: all unpublished EN
pnpm cms:prepare:locales -- --force         # Step 2: all locales
pnpm cms:preview
pnpm cms:sync                               # Step 3: after review

After prompt or config changes

Re-run with --force. Staging without --force skips existing <Update> blocks.

Version selection logic

Context	Versions processed
Local, no args	EN not in `published-versions.json` (≥ `min_version` 0.21.0)
Local + `CMS_SYNC_ALL=1`	All ≥ min_version
Explicit `v0.25.1`	That version only
CI (`CMS_SYNC_BEFORE` / `CMS_SYNC_AFTER`)	New/changed `<Update>` blocks in git diff only

cms:sync skips locales already published per registry. Published EN in CMS is never overwritten.

Key files

Path	Role
`changelog/index.mdx`	Full docs EN changelog
`.github/scripts/cms/staging/`	CMS popup content generated by prepare; review and commit
`.github/scripts/cms/cms-config.json`	Locales, min version, simplify limits
`.github/scripts/cms/published-versions.json`	Published registry (commit after Strapi publish)
`.github/scripts/cms/prepare-cms-changelog.ts`	Prepare pipeline
`.github/scripts/cms/sync-to-strapi.ts`	Strapi draft sync
`.github/scripts/cms/publish-cms-drafts.ts`	Draft → published
`.github/scripts/cms/delete-cms-drafts.ts`	Clean bad drafts
`.github/workflows/cms-changelog-sync.yml`	CI: prepare → preview → sync on main (changelog paths only)

Agent checklist

When user asks to update CMS release notes:

Troubleshooting

Issue	Fix
Only one version simplified	Old behavior was latest-only; now defaults to unpublished. Use `CMS_SYNC_ALL=1` for all.
Staging skipped	Version already exists — add `--force`
Strapi VERSION shows `-`	Bulk sync bug: `version` field null; delete drafts and re-sync
Delete draft 500	Use `pnpm cms:delete-drafts` (locale-only DELETE, not `status=draft`)
`English base draft missing` on locale sync	Ensure EN draft exists first; sync creates EN before other locales
Background prepare still running	`pkill -f prepare-cms-changelog.ts`

docs-i18n-translate — Mintlify docs ja/zh/ko (pnpm translate)
docs-i18n-review — translation quality review (pnpm translate:review)

Docs vs CMS (do not confuse)

	Docs site	CMS popup
Source	`changelog/index.mdx`	`staging/en/…`
Length	Full detail	3–5 bullets
New Nodes	Keep in full changelog	Optional for ordinary new nodes; keep deprecation / removal / replacement / EOL
i18n	`zh/changelog/` etc.	`staging/zh/` etc.
Deploy	Mintlify	Strapi draft → publish

Get Started

Agent Tools

Basic Concepts

Interface Guide

Tutorials

Comfy Cloud Nodes

Partner Nodes

SKILL

CMS Changelog Sync

Architecture

Three-step workflow (local)

Translation workflow (CMS staging)

Environment (`.env.local`)

Bullet links (docs, local CMS, Cloud CMS)

ComfyUI-WIKI commits (omit from changelog)

Node lifecycle (deprecation, removal, replacement, EOL)

Example staging shape

Projects (comfyui + cloud)

Commands

Standard workflow

New release version

Catch up all unpublished versions locally

After prompt or config changes

Version selection logic

Key files

Agent checklist

Troubleshooting

Docs vs CMS (do not confuse)

​CMS Changelog Sync

​Architecture

​Three-step workflow (local)

​Translation workflow (CMS staging)

​Environment (.env.local)

​Simplification rules (EN popup)

​Bullet links (docs, local CMS, Cloud CMS)

​ComfyUI-WIKI commits (omit from changelog)

​Node lifecycle (deprecation, removal, replacement, EOL)

​Example staging shape

​Projects (comfyui + cloud)

​Commands

​Standard workflow

​New release version

​Catch up all unpublished versions locally

​After prompt or config changes

​Version selection logic

​Key files

​Agent checklist

​Troubleshooting

​Related skills

​Docs vs CMS (do not confuse)

CMS Changelog Sync

Architecture

Three-step workflow (local)

Translation workflow (CMS staging)

Environment (`.env.local`)

Simplification rules (EN popup)

Bullet links (docs, local CMS, Cloud CMS)

ComfyUI-WIKI commits (omit from changelog)

Node lifecycle (deprecation, removal, replacement, EOL)

Example staging shape

Projects (comfyui + cloud)

Commands

Standard workflow

New release version

Catch up all unpublished versions locally

After prompt or config changes

Version selection logic

Key files

Agent checklist

Troubleshooting

Related skills

Docs vs CMS (do not confuse)