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, 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.

Phase 2: Extract — Pull fresh node data from the running instance

Only after the user confirms ComfyUI is running:

1. Run extraction:

   ./scripts/extract-comfyui-nodes.sh
   

2. Run import (creates skeletal files for new nodes, removes old ones, updates metadata):

   ./scripts/import-new-nodes.sh
   

3. Report the delta to the user (new/removed/total counts)

Phase 3: Enrich — Write documentation for new nodes

Find nodes with documentation_complete: false and enrich them using parallel subagents grouped by section:

# Check how many need enrichment
rg '"documentation_complete": false' src/data/nodes/ -l | wc -l

Dispatch 3 parallel subagents (one per section):

• comfy_nodes: Read embedded docs at embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md if available, write all content fields
• partner_nodes: API nodes — always mention API key requirement, cloud processing, costs
• subgraph_blueprints: Workflow templates — emphasize ready-to-use nature, customization tips

After enrichment:

1. Verify: rg '"documentation_complete": false' src/data/nodes/ -l | wc -l → should be 0
2. Build: pnpm run build
3. Update exports/NODE_UPDATE_PLAN.md with the version history entry

---

Workflow

Batch documenting nodes

When asked to document a set of nodes (e.g. "document the new audio nodes"):

1. Find target nodes: find src/data/nodes -name '*.json' -path '*audio*'
2. Group nodes by category for context
3. For each node: a. Read the per-node JSON file b. Read the embedded doc if it exists: embedded-docs/comfyui_embedded_docs/docs/<NodeName>/en.md c. Read the export entry for structural context: check exports/comfyui_nodes_*.json d. Write all content fields e. Set documentation_complete: true
4. Write updated JSON back to the same per-node file (edit in place)
5. Update progress in exports/NODE_UPDATE_PLAN.md if relevant

Improving existing nodes

When asked to improve node docs:

1. Identify nodes with weak content:
   • documentation_complete: false
   • Empty beginner_description
   • Generic tips like "Experiment with settings"
   • Empty use_cases or common_errors
   • description under 50 chars
2. Rewrite weak fields following the standards above
3. Keep existing good content — don't rewrite what's already well-written

Quality check

To find nodes needing work:

# Incomplete nodes
rg '"documentation_complete": false' src/data/nodes/ -l | wc -l

# Nodes where beginner_description copies description
python3 -c "
import json, os
for root, dirs, files in os.walk('src/data/nodes'):
    for f in files:
        if not f.endswith('.json') or f == '_metadata.json': continue
        path = os.path.join(root, f)
        try:
            with open(path) as fh: d = json.load(fh)
        except json.JSONDecodeError:
            print(f'BAD_JSON: {path}')
            continue
        except UnicodeDecodeError:
            continue
        desc = d.get('description','')
        bdesc = d.get('beginner_description','')
        if desc and desc == bdesc:
            print(f'LAZY: {d.get(\"name\",f)}  ({path})')
"

# Nodes missing tips
python3 -c "
import json, os
for root, dirs, files in os.walk('src/data/nodes'):
    for f in files:
        if not f.endswith('.json') or f == '_metadata.json': continue
        path = os.path.join(root, f)
        try:
            with open(os.path.join(root, f)) as fh: d = json.load(fh)
        except json.JSONDecodeError:
            print(f'BAD_JSON: {path}')
            continue
        except UnicodeDecodeError:
            continue
        if not d.get('tips',{}).get('general_tips'):
            print(d.get('name', f))
"

Category-Specific Guidance

API nodes (api node/...) — found in partner_nodes/

• Always mention: requires API key, uses cloud processing, may have costs
• Note the provider and what type of media it handles
• Mention rate limits or size restrictions if the embedded doc says
• Don't write advanced_tips unless there's something genuinely advanced

Dataset nodes (dataset/...)

• Explain how it fits into a training data pipeline
• Mention what formats it accepts/produces
• Note batch processing behavior

Sampling nodes (sampling/...)

• Explain what the sampler/scheduler does in practical terms
• Give recommended starting values
• Note which models it works best with
• Compare to common alternatives (euler vs dpm++ etc.)

Latent nodes (latent/...)

• Always mention: "Connect to VAE Decode to see the result as an image"
• Explain the latent space concept briefly for beginners
• Note resolution requirements if applicable

Audio nodes (audio/...)

• Explain the audio format requirements
• Note sample rate / channel constraints
• Describe how it fits into audio workflows

Subagent Usage

For large batches (50+ nodes), use parallel subagents grouped by category. Each subagent gets a category batch and writes docs for all nodes in that group. This keeps context focused and produces more consistent output within a category.

Coordination: The subagents should write their results to per-node JSON files (different files per node, so no write conflicts) rather than editing a single shared plan file. A single coordinator agent can update exports/NODE_UPDATE_PLAN.md after all workers complete.