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.
Hard gate: Cloud push / publish (ask every time)
Whenever the user asks to push, sync, or publish to CMS (in any language), agents must:
- Default to
--project comfyuionly. Do not runcms:sync/cms:publish/cms:previewfor cloud in the same turn as the request. - Stop and ask a second confirmation about Cloud, even if the user already mentioned Cloud links, templates, or “push both”. Ask in plain language, for example:
Should Cloud go to CMS this time as well? Please check Cloud staging (links and copy) yourself, then confirm. Until you confirm, I will only handle comfyui.
- Run
--project cloudfor preview/sync/publish only after the user replies with an explicit yes for Cloud in this conversation turn chain (e.g. “yes, push Cloud”, “cloud too”). Linking shortlinks earlier, preparing staging, or saying “push to CMS” alone is not Cloud approval. - If unsure, ask again. Never infer Cloud approval from prior releases, PR text, or that Cloud staging already exists.
cms:prepare:en / cms:prepare:locales may still prepare both projects’ staging files. The gate applies to Strapi preview, push, and publish (cms:preview, cms:sync, cms:publish), not to local staging generation.
Write this skill and related CMS agent docs in English. Match the user’s language only when asking the confirmation question in chat.
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 -- --project comfyui (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:localesdoes not re-simplify English — it reads each project's own staging EN (staging/en/andstaging/cloud/en/)- If staging EN is missing the version, translate fails — run
cms:prepare:enfirst - Target locales: zh, ja, ko, fr, ru, es (see
cms-config.json) --forcere-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.
Simplification rules (EN popup)
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), a target for optional items. Lifecycle bullets are mandatory and may take the version over it |
| 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 ordinary 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 partner removals, deprecations, replacements, or EOL. 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.
OSS bullets name the model, not the plumbing. After prepare:en, rewrite open-source bullets to match names users already see in tutorials/ (checkpoint family, fl2va / ref2va, ControlNet Union, and similar). If a tutorial page already documents the model, the popup should say we added support for that model. Do not describe loader internals: optional VAE, keyframe wiring, skipped LoRA keys, unless that is the only user-facing change.
LoRA / trainer format: say we support LoRAs trained in that format (or by that trainer). Do not mention the previous load bug.
Removals, deprecations, EOL: keep them on the popup (do not drop as housekeeping). On Cloud, still list the retired node or model names so users know which graphs break. The "one short clause" Cloud rule does not apply to removal bullets.
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. Search the whole index: partner api_* and OSS video_*, image_*, 3d_* (and any other prefix). Do not grep api_ only. 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, fun_controlnet_union, 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 Veowith "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.
- Overflow: lifecycle bullets outrank the bullet limit. If a version has more items than
max_bullets_total, keep every lifecycle bullet and drop optional items first (ordinary new-node additions, then minor partner tweaks). Never omit a deprecation, removal, replacement, or EOL to stay under the limit.
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.
Cloud is never implied. Follow Hard gate: Cloud push / publish above: ask every time the user requests a CMS push or publish; run --project cloud only after they explicitly confirm Cloud in that request chain.
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 ask for Cloud confirmation, then --project cloud only after that yes.
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 tochangelog/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.1Inspect:
.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 approvedStep 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 editsInspect:
.github/scripts/cms/staging/zh/changelog/index.mdx(and other locales) → stop until approvedStep 3 — Push ComfyUI drafts (only after user confirms staging):
pnpm cms:preview -- --project comfyui v0.25.1 pnpm cms:sync -- --project comfyui v0.25.1Publish ComfyUI after Strapi review:
pnpm cms:publish --preview -- --project comfyui v0.25.1 pnpm cms:publish -- --project comfyui v0.25.1Cloud is separate (hard gate): before any cloud
cms:preview/cms:sync/cms:publish, ask the user to manually confirm Cloud (see Hard gate: Cloud push / publish). Do not treat “push to CMS” or pasted Cloud URLs as that confirmation. Only then:pnpm cms:preview -- --project cloud v0.25.1 pnpm cms:sync -- --project cloud v0.25.1 pnpm cms:publish -- --project cloud v0.25.1 # only if they asked to publishCommit
.github/scripts/cms/staging/and.github/scripts/cms/published-versions.jsonafter 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 -- --project comfyui
pnpm cms:sync -- --project comfyui # Step 3: after review (comfyui only)
# Cloud preview/sync/publish: only after Hard gate confirmation, with --project cloud
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:
- Confirm
changelog/index.mdxhas the new<Update>block - Resolve bullet URLs: search the full template
index.json(api_*and OSSvideo_*/image_*/3d_*) and blog.comfy.org/archive; Cloud = user UTM then?template=(video r2v → i2v → t2v); docs/local = blog then PR then repo - Align OSS popup names with existing
tutorials/model names (added support for X). Not loader plumbing - Shorten Cloud EN bullets (added model support, skip node lists). Keep local/docs more detailed. Exception: Cloud removal/EOL bullets still list what was retired
- LoRA format bullets: support that trainer/format, not the previous skip-keys bug
- Record node lifecycle in the matching section: partner deprecation / removal / replacement / EOL under Partner Node Updates; core/built-in lifecycle under New Node Updates. Name the replacement node when one exists. Do not drop these from docs or CMS
- Omit ComfyUI-WIKI items (embedded docs, workflow templates, model blueprints) unless user explicitly asks
- Run
pnpm cms:prepare:en; rewrite Cloud EN links; show staging EN → wait for user approval - Run
pnpm cms:prepare:locales(notcms:prepare:en) → wait for user approval - Run
pnpm cms:preview -- --project comfyui ...thenpnpm cms:sync -- --project comfyui ...only after user confirms staging - Before any Cloud push/publish: stop and ask the user to manually confirm Cloud (hard gate). Do not sync/publish
--project clouduntil they explicitly say yes this time - Remind: Strapi publish is manual; then
--writeon published-versions - Commit
.github/scripts/cms/staging/together withpublished-versions.jsonafter publish - Do not shorten docs changelog for CMS — staging is separate
- Do not run bulk
CMS_SYNC_ALLprepare/sync without user consent (many API calls)
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 |
Related skills
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 |