Comfyui Node Update

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:

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, or gotchas mentioned
4. Write your own content — informed by the doc but in your own words
5. Strip any "AI-generated" disclaimer lines

What to extract from embedded docs:

• Technical understanding of what the node does
• Parameter ranges, defaults, and constraints
• Specific tips or warnings the doc mentions
• How the node fits into workflows

What NOT to do:

• Copy the intro paragraph as beginner_description
• Copy input/output tables as tips
• Use the same phrasing or structure

Node Update Workflow (ComfyUI Version Upgrade)

When a new ComfyUI version is available and you need to sync node data, follow this workflow end-to-end. The process has three phases: ask, extract, enrich.

Golden rule: Never use a stale extraction file. Always ask the user first.

Phase 1: Ask — Confirm ComfyUI is running and up to date

Always start here. Never use a stale extraction file.

Ask the user: "Is ComfyUI running and updated? Or do you need to update it first?"

If the user needs to update, first ask them for the ComfyUI repository path (or tell them to set COMFYUI_DIR). Then give these copy-paste commands:

cd <COMFYUI_DIR>
git pull
pip install -r requirements.txt
./start.sh

Say: "Run these and tell me when ComfyUI is running." Then wait. Do not proceed until the user confirms.