/comfyui-node-update

name: comfyui-node-update
description: >
  Write and improve documentation for ComfyUI nodes in per-node JSON files.
  Use when asked to document nodes, write node descriptions, add tips to nodes,
  improve node docs, enrich node content, fill in empty node descriptions, or
  batch-write documentation for new/updated nodes. Also triggers on "write docs
  for nodes", "document the new nodes", "improve node tips", "fill in node
  descriptions", "enrich nodes", "node content pass", "update nodes",
  "sync comfyui nodes", "new comfyui version", or "node enrichment".

Node Documentation Writer

Write original, beginner-friendly documentation for ComfyUI nodes. Each node is stored as an individual JSON file. Use the embedded docs as a reference source but always rewrite content — never copy-paste.

File Structure

Node data is split into per-node JSON files organized by section and category:

src/data/nodes/
  _metadata.json                              — metadata + schema_version
  comfy_nodes/<category>/<NodeName>.json      — core ComfyUI nodes (511)
  partner_nodes/<category>/<NodeName>.json    — API/partner nodes (203)
  subgraph_blueprints/<category>/<Name>.json  — subgraph blueprints (65)
  extensions/<category>/<NodeName>.json       — extension nodes (1)

The top-level directories (`comfy_nodes`, `partner_nodes`, `subgraph_blueprints`, `extensions`) match the tree pane sections. Below that, the category path matches the node's `category` field with spaces replaced by hyphens.

Key files

• **Per-node data:** `src/data/nodes/<section>/<category>/<NodeName>.json`
• **Metadata:** `src/data/nodes/_metadata.json`
• **Export data:** `exports/comfyui_nodes_*.json` (structural source of truth)
• **Embedded docs:** `embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md` (reference only)
• **Update plan:** `exports/NODE_UPDATE_PLAN.md` (progress tracking)
• **Extraction script:** `scripts/extract-comfyui-nodes.sh` (pulls from running ComfyUI)
• **Import script:** `scripts/import-new-nodes.sh` (creates skeletal files, updates metadata)

Finding a node file

To locate a node's JSON file:

find src/data/nodes -name 'KSampler.json'
# → src/data/nodes/comfy_nodes/sampling/KSampler.json

To search across all nodes:

rg '"documentation_complete": false' src/data/nodes/ -l

Content Fields to Write

For each node, write these fields:

| Field | What to write | Length | |---|---|---| | `description` | Technical but clear explanation of what the node does | 50–200 chars | | `beginner_description` | Plain-language explanation for someone new to ComfyUI | 100–400 chars | | `tips.general_tips` | Practical advice any user should know | 2–5 tips | | `tips.beginner_tips` | "Start here" guidance with specific values and settings | 2–4 tips | | `tips.advanced_tips` | Power-user techniques, edge cases, combo strategies | 1–4 tips (skip for simple nodes) | | `use_cases` | Concrete scenarios with context | 2–4 use cases | | `common_errors` | Real problems users hit, with actionable fixes | 1–4 errors | | `complexity_level` | `"beginner"`, `"intermediate"`, or `"advanced"` | — | | `documentation_complete` | Set `true` when all content fields are filled | — |

Writing Standards

Voice & Audience

• Write for people learning ComfyUI, not ML researchers
• Use active voice: "Connect to VAE Decode" not "Should be connected to"
• Explain WHY, not just WHAT: "Lower CFG (4–6) gives the model more creative

freedom" not "CFG controls guidance strength"

• Use analogies for complex concepts: "Think of it like adjusting the contrast

on a photo" not "Modifies the latent tensor distribution"

description

One or two sentences. Technical but accessible. State what the node does and its role in a workflow.

**Good:** "Loads a Stable Diffusion checkpoint file containing the model weights, text encoder, and VAE needed for image generation."

**Bad:** "Checkpoint loader node." (too short, says nothing) **Bad:** Copy-pasting the export's `description` field verbatim.

beginner_description

Explain the node as if the reader has used ComfyUI for a week. Avoid jargon or explain it inline. Say what it does in practical terms.

**Good:** "This node loads the AI model that generates your images. Think of it as picking which artist you want to work with — different checkpoints produce different styles, from photorealistic to anime to oil paintings."

**Bad:** "Loads checkpoint files for diffusion model inference." (jargon) **Bad:** Repeating `description` with slightly different words.

tips

Each tip must be **specific and actionable**. Include concrete values, settings, node names, or workflows.

**Good tip:** "Start with euler sampler, 25 steps, CFG 7.5 — this works reliably for most models and gives good results in about 10 seconds."

**Bad tip:** "Experiment with different settings to find what works best." (vague, unhelpful)

**Good tip:** "For Flux models, set CFG to 1.0 and use the FluxGuidance node instead — Flux uses guidance differently than SD 1.5 or SDXL."

**Bad tip:** "Different models may require different settings." (obvious)

use_cases

Use an array of objects with `scenario` and `context`:

[
  {
    "scenario": "Text-to-image generation",
    "context": "The most common workflow — connect Empty Latent Image as input with denoise 1.0 to generate from scratch"
  }
]

common_errors

Use an array of objects with `symptom` and `solution`:

[
  {
    "symptom": "Black or completely blank images",
    "solution": "CFG scale too high (>15). Lower to 7–9 range. Also check that model, VAE, and conditioning are all connected."
  }
]

How to Use Embedded Docs

The embedded docs at `embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md` are a **reference source**, not a template.

1. Read the embedded doc to understand what the node does 2. Read the input/output tables to understand parameters 3. Note any tips, notes,