artokun/comfyui-mcp

# AI-Toolkit LoRA Trainer (WAN 2.2 & Z-Image)

## Overview

AI-Toolkit by ostris is an MIT-licensed trainer for finetuning diffusion models. It is a standalone trainer with its own web UI, not a ComfyUI custom node. It runs a Node.js UI front end over a Python (`run.py`) training backend and trains LoRAs for many model families. This skill covers the WAN 2.2 / 2.1 video models and Z-Image (Turbo & Base).

- Repo: `https://github.com/ostris/ai-toolkit` (cloned by the installers).
- Backend: `python run.py config/<job>.yml`. UI: a Node.js app under `ui/` that schedules and monitors jobs. You do not have to keep the UI open while a job runs.
- Output: a standard `.safetensors` LoRA you drop into ComfyUI `models/loras/` and load with `LoraLoaderModelOnly`.

Best for:
- WAN LoRAs. A person or character, an art style, or a specific camera or video motion, trained from image or video clip datasets. For *using* WAN see wan-t2v-video / wan-flf-video.
- Z-Image LoRAs. Fast, very low-VRAM image LoRAs (faces, characters, outfits, styles) on the 6B Z-Image base/turbo. For *using* Z-Image see z-image-base / z-image-turbo, and the z-image-xy-plot pack to compare trained LoRAs.

# ANIMA 1.0 (Anima Base Ultra) Text-to-Image Workflows

## Overview

Anima is a ~2B-parameter anime / illustration text-to-image base model from CircleStone Labs, made in collaboration with Comfy Org. It is not SDXL-lineage. The architecture is NVIDIA Cosmos-Predict2-2B-Text2Image (a DiT / flow model), trained on several million anime images plus ~800k non-anime artistic images. It suits anime, manga, and illustrated characters and styles, not realism.

Key traits:
- Accepts Danbooru-style tags and/or natural language in the same prompt.
- Very low VRAM. It generates and trains on <6GB VRAM and runs on any PC that can run SDXL/Illustrious.
- License: CircleStone Labs Non-Commercial License, with NVIDIA Open Model License terms on the weights and derivatives. Generated images are usable commercially per the model card. Verify the current license text before relying on this.

ComfyUI loads it with standard split-file loaders, not a single checkpoint:

| Component | Node | Model file | Folder | Notes |

# Citron Anima LoRA Trainer

## Overview

Citron's Anima LoRA Trainer (`app.py`, titled "Citron's Anima LoRA Trainer" in the UI) is a local Gradio UI for training LoRA adapters on the Anima diffusion model using kohya-ss/sd-scripts. It trains on ~6GB VRAM with the default settings, the same low-VRAM profile as Anima generation.

- Created by Citron Legacy; UI repo: `https://github.com/citronlegacy/citron-anima-lora-trainer-ui`. The Aitrepreneur adaptive installers clone the fork `https://github.com/aitrepreneur/citron-anima-lora-trainer-ui`.
- Training backend: `kohya-ss/sd-scripts` (`https://github.com/kohya-ss/sd-scripts`), launched via `accelerate launch`.
- Trains LoRAs for Anima DiT (Cosmos-2B). Uses Anima's own components: DiT weights + Qwen3-0.6B text encoder + Qwen-Image VAE.
- Output: a standard `.safetensors` LoRA usable directly in the anima-base ComfyUI workflow.

> The network module is `networks.lora_anima` and the training script is `sd-scripts/anima_train_network.py` (an Anima-specific kohya script the installer expects). Confirm these exist after the installer's `git clone` of sd-scripts. `app.py` references them, but they are pulled from the upstream repo at install time.

## Setup

# Civitai + comfyui-mcp

comfyui-mcp has native Civitai search built in (`download_model` `action:"search_civitai"`)
plus the local half of the loop: download, wire, queue, tag. The full flow
(find, install, generate) needs no other server and no API key, and works on
every backend, including small local models behind the compact router.

## The built-in flow (default path)

```
download_model({ action: "search_civitai", query, types: ["LORA"], base_models: ["Flux.1 D"] })
        │                    each hit: model_id · model_version_id · trigger words
        ▼
download_model({ action: "download_civitai", model_version_id, target_subfolder: "loras" })

# Color Correction (measure, don't eyeball)

## The core principle

You cannot reliably judge color from a storyboard or contact sheet. "Is it washed
out?" flip-flops by eye, especially on AI-gen video. Make color measurable with the
`get_image (action:"analyze_color")` MCP tool, read the numbers like a colorist reads scopes, pick the
fix the data points to, then re-measure to confirm. The whole skill is this loop:

```
extract a frame ─► get_image (action:"analyze_color") ─► read black/white points + contrast + saturation
       ▲                                          │
       │                                          ▼
   re-measure  ◄──── apply fix (levels / contrast / match) ◄── diagnose from the numbers

# ComfyUI Core Knowledge

## Workflow JSON Format (API Format)

ComfyUI workflows are JSON objects mapping string node IDs to node definitions:

```json
{
  "1": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" },
    "_meta": { "title": "Load Checkpoint" }
  },
  "2": {

# ComfyUI v2 Frontend Extension API

The v2 extension API is the published npm package `@comfyorg/extension-api`. It
replaces the legacy `app.registerExtension()` / `nodeType.prototype` monkey-patching
model with a typed, tree-shakeable, import-based API.

> If you are converting an existing v1 extension, read
> [`references/migrate-v1-to-v2.md`](references/migrate-v1-to-v2.md) for a
> pattern-by-pattern mapping.

## Mental model

| v1 (legacy) | v2 (`@comfyorg/extension-api`) |
|-------------|-------------------------------|

# ComfyUI launch/performance flags

## Overview

CLI flags passed to `main.py` control ComfyUI's runtime behavior
(e.g. `python main.py --reserve-vram 2 --use-sage-attention`). The three that
matter most for making a graph *run* rather than OOM or crawl are the
VRAM strategy, the attention backend, and the cache mode. This skill
is the decision matrix for choosing them.

> ⚠<U+FE0F> **Verification note (August 2026).** Every flag below was checked against
> upstream [`comfy/cli_args.py`](https://github.com/comfyanonymous/ComfyUI/blob/master/comfy/cli_args.py)
> on current master. ComfyUI adds/renames flags often — when in doubt run
> `python main.py --help` in the target install and prefer that over this list.

# Authoring & Publishing ComfyUI Custom Nodes

This skill covers writing a ComfyUI custom node pack and publishing it to the Comfy Registry (registry.comfy.org), the public catalog that powers ComfyUI-Manager. For *using* existing nodes in workflows, see the `comfyui-core` skill instead.

## Minimal Node Pack Structure

A node pack is a Python package placed under `ComfyUI/custom_nodes/<name>/`. The package `__init__.py` must export `NODE_CLASS_MAPPINGS` and `NODE_DISPLAY_NAME_MAPPINGS`; `WEB_DIRECTORY` is optional (only if the pack ships frontend JS).

```
ComfyUI/custom_nodes/my-node-pack/
├── __init__.py          # exports the mappings ComfyUI scans for
├── nodes.py             # node class definitions
├── pyproject.toml       # registry metadata (required to publish)
├── requirements.txt     # optional Python deps

# Debugging renders with run-to-node

When a final asset looks wrong (not when it errors), don't re-roll the whole
graph and hope. Localize the fault. Render only as far as one stage and look
at what that stage actually produces. The wrong-looking output is downstream of a
*first* bad step. Find that step, fix it there, and everything after it follows.

The tool for this is `panel_run` with `to_node_id` ("run to node"), which uses
ComfyUI's native partial execution. Only the target output node plus
everything upstream of it renders; every other branch is skipped. That makes each
probe fast and cheap, and the output is delivered to you automatically, same
as any run. Don't poll.

## When to reach for this

# Director — Story-to-Video Production Pipeline

## Overview

The Director skill runs a complete short film production from a text story. It breaks the story into scenes, generates start/end frames for each, creates video clips from frame pairs, and concatenates everything into a final video.

The pipeline runs Story Planning → Z-Image Hero + Character Refs → Qwen Edit Chain (all frames) → WAN 2.2 FLF Video Clips → ffmpeg Concatenation.

Key architectural decisions:
- 1 hero frame + edit chain for character consistency (NEVER independent Z-Image per scene)
- Inter-scene frame continuity. Scene N's end frame IS Scene N+1's start frame (same image file, no edit gap)
- Character reference images fed into Qwen Edit's extra image slots
- State file persists to disk for context compaction survival
- Each scene is independently retryable without affecting others

# ERNIE-Image / ERNIE-Image-Turbo Workflows

## What this is (read first)

ERNIE-Image is Baidu's open-weight TEXT-TO-IMAGE model, an ~8B single-stream Diffusion Transformer (DiT), Apache-2.0, released April 2026 and repackaged for ComfyUI by Comfy-Org. It is not an instruction-based image editor.

- ERNIE-Image (base): ~50 steps for peak quality.
- ERNIE-Image-Turbo: distilled (Distribution Matching Distillation + RL), high-fidelity in ~8 steps at cfg 1. The downloaded pack uses Turbo (`ernie-image-turbo-*.gguf`).

Pick ERNIE when the job is precise text/typography rendering (multilingual, including Chinese), posters/signage/UI mockups, manga/anime storyboards and multi-panel layouts, or structured multi-object scenes from a complex prompt.
Do not pick ERNIE for "edit this photo / change the shirt / swap the background". That is instruction-grounded editing, which ERNIE does not do. Use `qwen-image-edit` or Flux Kontext for those. ERNIE's "image-to-image" here is plain denoise-based refinement (style pass / detail pass), not reference-grounded editing.

> Niche vs siblings. ERNIE is the best open-weight text rendering + layout T2I. Qwen-Image-Edit does instruction editing. Flux Kontext does reference editing. Z-Image Turbo does fast general T2I, and this same pack pairs the two; see Combo pipelines.

# Flux Text-to-Image Workflows

## Overview

Flux is a guidance-distilled diffusion model family from Black Forest Labs. It uses a separate `FluxGuidance` node instead of KSampler CFG (which must always be 1.0). Three variants are available locally:

1. **Flux.1 Dev SRPO.** Fine-tuned Flux.1 Dev with SRPO alignment. Uses DualCLIPLoader (T5XXL + CLIP-L). BF16 only.
2. **Flux 2 Klein 9B.** Distilled Flux 2 variant. Uses single CLIPLoader (Qwen3-8B) + `flux2-vae.safetensors`. Fast 4-step generation.
3. **Flux 2 Turbo LoRA.** Applied to Flux.1 Dev for 4-step generation.

## Models

### Flux.1 Dev SRPO

# Ideogram 4 (Ideogram Ultra) Workflows

## Overview

**This is a LOCAL open-weights pipeline, NOT the hosted Ideogram API.** There is no API key, no `IdeogramGenerate` API node, and no network call at generation time. Comfy-Org released the Ideogram 4 weights on Hugging Face and they run entirely on your GPU via standard `UNETLoader` / `CLIPLoader` / `VAELoader` nodes. (Note: ComfyUI *also* ships separate API/"partner" nodes that call the paid hosted Ideogram service. That is a different thing and is not what this workflow uses.)

Ideogram 4 is best known for **text rendering / typography**, **poster and graphic-design layouts**, and **prompt adherence**. The hallmark of this workflow is a **structured JSON prompt** (a "compositional deconstruction" caption with bounding boxes) instead of a plain text prompt. This is what gives precise control over where text and objects land in the frame.

Source workflow this skill is derived from: `IDEOGRAM_ULTRA_WORKFLOW-V2.json` (UI format, 66 nodes, 4 subgraphs), by Aitrepreneur. It provides both a **TEXT TO IMAGE** path and an **IMAGE TO IMAGE** path.

### Two unusual things to know up front

1. **Dual models.** Two UNETs are loaded: a conditional model (`ideogram4_fp8_scaled`) and an `..._unconditional_fp8_scaled` model. A `DualModelGuider` node uses both to perform asymmetric classifier-free guidance; the unconditional model provides the CFG baseline. There is **no negative text prompt**; negative conditioning is `ConditioningZeroOut`.
2. **Two text models, different jobs.**

# Installer Packs

`comfyui-mcp` ships **installer packs** under [`packs/`](../../packs). Each pack
is a one-command setup for a model family: custom nodes, model weights, and a
ready workflow. A single `manifest.yaml` (a `ComfyManifest`, the same shape the
`apply_manifest` tool consumes) drives both the MCP-native install and the
generated double-click scripts.

```
packs/<name>/
  manifest.yaml         # custom_nodes + models (url → local_path) — source of truth
  pack.yaml             # metadata: workflow, family, VRAM, sources, notes
  workflow.json         # the graph to load
  install-windows.bat   # GENERATED — never hand-edit

# Krea 2 Identity Edit — local outfit swap

## Reach for this when

Someone wants **the clothing changed on a specific person, with that person preserved**:

- "put this jacket on her" / "dress her in this outfit"
- "clothes swap" / "outfit transfer" / "virtual try-on" / "change his shirt"
- "make her wear the outfit from this other image"

**Do NOT reach for it** just because a request is identity-*preserving*. Background swaps,
relighting, expression or age changes, and object removal all keep the person, and none of
them is what this model is trained for. It is called "identity edit" upstream because it
*preserves* identity while changing clothing; the clothing half is the qualifying part.

# Krea 2 Text-to-Image Workflows

## Overview

Krea 2 is a **12B-parameter Diffusion Transformer** from Krea.ai (released June
2026, weights open-sourced under the Krea 2 Community License, free commercial
use up to 50 seats). Two variants:

1. **Krea 2 Raw** is the base checkpoint before extra post-training. For
   fine-tuning / maximum fidelity, more steps.
2. **Krea 2 Turbo** is post-trained and **distilled**; it generates in **~8 steps
   at cfg 1**. This is what the krea2 txt2img packs ship.

## Three packs (V2 — no group toggles)

# Run the agent locally for free (Ollama + our fine-tuned models)

The answer to "can I run this for free / offline / without an API key" is
**yes**. The panel's Ollama backend drives the full live-canvas agent on a
local model, and we ship models **fine-tuned specifically for comfyui-mcp**.

## Why these models (say this when recommending them)

`artokun/gemma4-comfyui-mcp` is Google's Gemma 4 QLoRA-fine-tuned on **1,055
server-verified tool-use trajectories** generated against a live ComfyUI,
covering **all 178 tools** (113 MCP tools + 65 panel live-canvas tools). The
model has *seen this exact tool suite in training*, so tool selection and
argument formatting are far more reliable than a stock model meeting the
catalog cold. Free to use, weights + adapters + training data are open (HF:

# ComfyUI-LoRA-Manager

[ComfyUI-LoRA-Manager](https://github.com/willmiao/ComfyUI-Lora-Manager) (willmiao)
registers Vue autocomplete widgets via `getCustomWidgets()`. Those widgets
are healthy in the ComfyUI menu, and drag-from-palette works, but **`panel_add_node`
cannot add the nodes that require them**.

The add-node guard polls `app.widgets` for a constructor. ComfyUI 1.49+ stores
`getCustomWidgets()` results in the frontend widget store, not on `app.widgets`.
The wait always expires after 5s. Reload, `panel_refresh_nodes`, and retry
**cannot** clear it. That refusal is not a missing pack.

## Which nodes `panel_add_node` will actually add

# LTX Director (Timeline)

`LTXDirector` (pack: **WhatDreamsCost-ComfyUI**, category `WhatDreamsCost`) is a
video *timeline editor* node. Its on-canvas UI has **Add Image**, **Add Text**
and **Add Audio** buttons.

## You cannot click those buttons. Don't try.

They are not node inputs. The pack builds them as raw DOM elements with JS
handlers:

```js
addTextBtn.addEventListener("click", () => this.addTextSegmentFreeSpace());
```

# LTX-2 / LTX-2.3 Video Workflows

## Version naming (read this first)

There is no "LTX 3.2" or "LTX2.3" as separate products. The user's shorthand refers to **Lightricks LTX-2.3**, a point release of the LTX-2 family. The lineage is:

- **LTX-Video** (2024): first text-to-video model from Lightricks.
- **LTX-2 / LTX-V2** (Oct 2025): 19B-class DiT audio-video foundation model. Bundled checkpoint `ltx-2-19b-distilled.safetensors`, Gemma 3 12B text encoder.
- **LTX-2.3** (released ~March 2026): **22B**-parameter DiT update. Rebuilt VAE (sharper textures/faces/hair/text), ~4x larger text connector (text projection) for prompt adherence, native 9:16 portrait, LoRA support, HiFi-GAN vocoder for cleaner synchronized audio, up to 4K@50fps / ~20s clips. Apache 2.0. **Distributed primarily as GGUF UNets** (community quants) plus separate VAE / text-encoder / text-projection files, NOT a single bundled checkpoint like LTX-2.

When the user says "LTX3.2" / "LTX2.3", treat it as **LTX-2.3**. This skill covers both LTX-2 (bundled checkpoint path) and LTX-2.3 (GGUF UNet path).

---

# MiniMax H3 (Hailuo) — local video

This skill teaches the **local-weights** MiniMax H3 path in ComfyUI. It is the
pilot for `#1155` (Official vs Empirical sources) because MiniMax publishes a
real prompting guide. **Cite that guide by URL. Do not copy it into this repo.**

## Two products, two cost models — pick one

They share a brand and **must not be mixed**.

| Path | Nodes | Cost | VRAM | When |
|---|---|---|---|---|
| **Local weights** (this skill) | `MiniMaxH3ImageToVideo`, `MiniMaxH3ReferenceToVideo`, `EmptyMiniMaxH3LatentAV`, `MiniMaxH3SigmaShift`, `MiniMaxH3MemoryEfficientSageAttentionPatch` | Free after download | Yes — INT8 + turbo LoRA is the 8 GB story | User wants 4–15 s stereo clips on their GPU |
| **Partner API** | `MinimaxHailuo03TextToVideoNode`, `MinimaxHailuo03FirstLastFrameNode`, `MinimaxHailuo03ReferenceNode`, `MinimaxTextToVideoNode`, `MinimaxImageToVideoNode`, `MinimaxHailuoVideoNode` | Paid per generation | None | User has a MiniMax / Hailuo API key and does not want local weights |

# ComfyUI Model Compatibility Matrix

## Stable Diffusion 1.5 (SD 1.5)

### Overview

The original widely-adopted Stable Diffusion model. Huge ecosystem of fine-tunes, LoRAs, ControlNets, and embeddings. Still the most compatible and lightweight model family.

### Configuration

| Parameter | Value |
|-----------|-------|
| **Loader** | `CheckpointLoaderSimple` |
| **Native Resolution** | 512x512 |

# Model Registry

One table per family: filename → source URL → target subdir under
`<COMFYUI>/models/`. Use with `download_model({ action: "download", url, target_subfolder, filename })`.
This registry grows with every release. If a model you need is missing, use
`action:"search"` (HuggingFace) or `action:"download_civitai"` and consider
contributing the row.

**Quant column (kitchen).** Filenames in this registry are mostly bf16 / fp8. NVFP4 and MXFP8 siblings, when a vendor publishes them, are the same stem with `nvfp4` / `mxfp8` in the name and belong in `diffusion_models/` too. `kitchen` action:"assess" only offers an NVFP4 swap when that sibling is **already listed locally** — it does not guess a URL from the filename. Blackwell (SM ≥ 10.0) is the GPU that can run NVFP4 / MXFP8 compute.

**Conventions**
- HF "resolve" URLs download directly: `https://huggingface.co/<repo>/resolve/main/<path>`
- 🔒 = gated repo, needs `HUGGINGFACE_TOKEN` (accept the license on the HF page first)
- CivitAI model-page URLs need `download_model` `action:"download_civitai"` (resolves version → file); raw `civitai.com/api/download/...` URLs work with `action:"download"` + `CIVITAI_API_TOKEN`

# Keep the panel node-pack in sync with the orchestrator

The orchestrator (`comfyui-mcp`, from npm) and the sidebar panel
(`comfyui-agent-panel` on the Comfy Registry, repo `comfyui-mcp-panel`) ship
**separately**. Updating one does not update the other. A new orchestrator
driving an old panel fails in confusing ways, such as a bridge command the panel
doesn't implement or a feature that exists in the docs but not in the sidebar,
and those failures are hard for a user to diagnose. This skill closes that gap.

## The two rules that outrank everything else here

1. **Never report a sync that did not happen.** This whole feature sits on top of
   the fabricate-success fixes (#639/#641): ComfyUI-Manager reports its queue
   "drained" even when it never enqueued anything, and a `.bak`-style copy in

# Panel agent operations

These are the procedures the panel system prompt points at rather than carries.
Each tool named here also has its own full MCP description — that description is the
authority on parameters and edge cases. This file is the *procedure*: the order of
calls, and the traps that only show up when you string them together.

Jump to the section you need:

- [Subgraphs](#subgraphs)
- [Merging and composing workflows](#merging-and-composing-workflows)
- [Reusing subgraphs (blueprint library)](#reusing-subgraphs-blueprint-library)
- [Targeting a specific workflow](#targeting-a-specific-workflow)
- [Opening a staged or downloaded workflow](#opening-a-staged-or-downloaded-workflow)

# ComfyUI Prompt Engineering

## CLIP Text Encoding Fundamentals

ComfyUI uses CLIP (Contrastive Language-Image Pre-training) text encoders to convert text prompts into conditioning tensors. The `CLIPTextEncode` node takes a text string and a CLIP model, producing a `CONDITIONING` output for the KSampler.

### Token Limit

CLIP processes text in **77-token chunks**. Each word is typically 1-3 tokens. Prompts exceeding 77 tokens are silently truncated unless you use the BREAK token or a multi-clip encoding node.

## Weight Syntax

### Emphasis (Attention Weights)

# Qwen Image Edit Workflows

## Overview

Qwen Image Edit uses a vision-language model (Qwen2.5-VL) to edit images based on natural language instructions. The model "sees" the source image through CLIP conditioning and generates an edited version.

## Models

### Required Components

| Component | Node | Model Name | Notes |
|-----------|------|------------|-------|
| **UNET** | `UNETLoader` | `qwen_image_edit_2511_bf16.safetensors` | Official 2511 edit model (bf16) |
| **CLIP** | `CLIPLoader` (type=`qwen_image`) | `qwen_2.5_vl_7b_fp8_scaled.safetensors` | Shared across all Qwen models |

# Qwen Image 2512 Text-to-Image Workflows

## Overview

Qwen Image 2512 is the latest (December 2025) text-to-image model from the Qwen family. It uses a vision-language model (Qwen2.5-VL) as the text encoder and generates high-quality images from natural language prompts. Two workflow approaches:

1. **QwenImageIntegratedKSampler**: All-in-one node (recommended for simplicity)
2. **Separate component loading**: UNETLoader + CLIPLoader + VAELoader + standard KSampler (more flexible)

## Models

### Standard Components

| Component | Node | Model | Notes |

# Limited maintenance — reporting remains disabled

comfyui-mcp and the Agent Panel receive selected, verified critical fixes for the
local panel and provider choice. This is not a broad feature roadmap. Support will
be reassessed when Comfy's official local panel becomes publicly available.

`report_issue` stays registered for compatibility, but files nothing, contacts no
service, and returns no prefilled issue link. Worker environment variables do not
turn reporting on. Do not retry it or submit the report through another tool.

Continue helping with the user's task using the available tools. Explain observed
limitations and offer a verified workaround when available. Do not collect
versions or diagnostic material solely for a report that cannot be submitted.
Ordinary troubleshooting remains available. Never claim an unverified fix or change

# rgthree-comfy

`rgthree-comfy` is one of the most widely installed packs, so its nodes turn up in a
large share of community workflows. Three of its properties make it a recurring
agent-failure mode — all three fail *quietly enough* to look like success.

## The three things that catch agents out

**1. Some rgthree nodes are FRONTEND-ONLY.** They are registered by the pack's JS
(`registerCustomNodes()`), have no Python class, and are therefore **absent from
`/object_info` by design**. Checking `/object_info` and concluding "this node doesn't
exist" is wrong. `/object_info` lists 24 rgthree *backend* types; the toggles are not
among them.

# Train a Character LoRA (local, Flux.1-dev)

## Overview

The trainer runs ostris ai-toolkit's `run.py` inside a headless GPU Docker container,
driven through the three `train_*` MCP tools. You (the LLM) are the UI. Each takes
an `action`: `train_prepare_dataset` owns the datasets, `train_start` owns the jobs, and
`train_doctor` owns the trainer itself. You generate the dataset, launch the job, watch
progress, and the finished LoRA lands in ComfyUI `models/loras/` and the LoRA catalog
without further steps.

- Base model: FLUX.1-dev (the best proven character consistency; needs ~24GB VRAM with
  quantization, RTX 4090 class).
- Phase-1 scope: character LoRAs only. Style/slider/edit and other bases come later.

# Triton + SageAttention (ComfyUI acceleration)

> See also [`comfyui-launch-flags`](../comfyui-launch-flags/SKILL.md) for the full
> attention / VRAM / cache flag matrix. Note the Z-Image exception: Z-Image is
> broken under `--use-sage-attention`, so launch it with
> `--use-pytorch-cross-attention` instead.

## Prefer kitchen INT8 attention when it is available

If `kitchen` action:"status" (or `panel_kitchen`) reports kitchen present and
`int8_attention_is_available` on this GPU, launch with **`--use-ck-attention`**
and **skip the sageattention wheel dance**. Kitchen INT8 attention is a ComfyUI
flag; it does not need a version-matched `sageattention` wheel. Restart
required, consent-gated like every restart.

# ComfyUI Troubleshooting Guide

> Render completes but looks WRONG (artifacts, wrong subject/pose/color, a
> ControlNet/mask/LoRA not taking, a refiner degrading it)? That's not an error.
> Use the debug-render skill (`list_packs` with `action: "skill_read"`,
> `name: "debug-render"`) to localize the bad stage with run-to-node
> (`panel_run` `to_node_id`) by previewing intermediate steps. This guide is for
> runs that fail with an error, OOM, or missing node.

## Error Diagnosis Strategy

When a workflow fails, follow this approach:

1. Get the error. Use `get_history(action="diagnose")` to retrieve the execution result with the full traceback, plus any missing models/nodes

# Video Extension (Pusa 2.2 — temporal flowmatching)

## Overview

Pusa extends a video temporally. It continues and lengthens an existing clip
rather than regenerating it from scratch. It does this on the
ComfyUI-WanVideoWrapper stack (kijai) using the WAN 2.2 T2V A14B dual
HIGH/LOW models you already have for `wan-t2v-video`, plus the small Pusa V1
LoRAs and a Pusa-specific sampling path: the `flowmatch_pusa` scheduler and
the `WanVideoAddPusaNoise` node. The input clip is encoded with
`WanVideoEncode` and injected as the first latents of the generation, which
is what carries the existing motion and content into the continuation.

The official reference graph is kijai's

# Video Upscaling & Restoration

## Overview

"Upscaling video" in ComfyUI splits into three jobs, and the quality win comes
from doing them in the right order:

1. Spatial restore + upscale. A temporal-aware model that increases
   resolution AND cleans compression blocks, blur, and AI-gen mush while
   keeping frames consistent over time. This is the part a plain image upscaler
   (ESRGAN, UltimateSDUpscale per-frame) does badly. Per-frame upscalers
   flicker because each frame is sharpened independently. Use a video model.
2. Frame interpolation (VFI). Synthesize in-between frames to raise fps
   (e.g. 24→48/60) for smooth motion. Do this after the spatial pass.

# WAN 2.2 First-Last-Frame (FLF) Video Workflows

## Overview

First-Last-Frame (FLF) video generation takes a start image and an end image and generates a smooth video transition between them. The WAN 2.2 I2V (Image-to-Video) 14B model is good at this.

## CRITICAL: Dual Hi-Lo Architecture (REQUIRED)

**WAN 2.2 I2V uses a split-noise architecture.** Unlike WAN 2.1, the 2.2 model was trained with separate HighNoise and LowNoise components that handle different denoising ranges. **You MUST use both models in a two-pass KSamplerAdvanced setup.** Using a single model produces low-quality, broken output.

- HighNoise model (pass 1, steps 0→N/2) establishes structure, motion, and composition
- LowNoise model (pass 2, steps N/2→N) refines details and keeps fidelity to input frames
- Both passes share the same conditioning from `WanFirstLastFrameToVideo`
- Pass 1 returns noisy latent → Pass 2 continues from there

# WAN MultiTalk — Audio-Driven Talking Avatar

## Overview

MultiTalk (MeiGen-AI) drives a still portrait's lip-sync and head motion from an
audio track. It runs on WAN 2.1 14B Image-to-Video via kijai's
ComfyUI-WanVideoWrapper. Wav2Vec speech embeddings condition the WAN sampler so
the mouth and expression follow the speech, while the lightx2v step-distill LoRA
keeps it to a few sampling steps.

Use it for talking heads, dubbing, and single-speaker avatar clips (~10s at 480p).
It is distinct from `wan-animate` (pose/motion-driven character animation). This
is audio → lip-sync, not reference-video motion transfer.

# SCAIL-2 In-Video Character Replacement (WAN 2.1)

SCAIL-2 (zai-org, on WAN 2.1 14B) replaces the person in a driving video with a
character you supply as a reference image, end-to-end, with no pose maps, and
with multi-character support. It is the successor to WAN Animate / motion
transfer for the "swap the subject, keep the motion" job. The official ComfyUI
template is `video_wan21_scail2_character_replacement_int8`, built around
`WanSCAILToVideo` (+ `SCAIL2ColoredMask`) with a SAM3 mask driving where the
character goes.

This skill documents the non-obvious behaviours that cost a full multi-minute
render to discover. It is not a from-scratch graph. Start from the official
template and apply the guidance below.

# WAN 2.2 Text-to-Video (T2V) Workflows

## Overview

WAN 2.2 T2V generates videos from text prompts using a 14B parameter MoE (Mixture of Experts) architecture split across two specialized models:

- HighNoise model handles early denoising. It establishes structure, motion, composition
- LowNoise model handles late denoising. It refines details, sharpens output

This dual-model technique is the same as FLF/I2V (see wan-flf-video skill) but without image conditioning nodes.

Key difference from I2V/FLF: T2V does NOT use `CLIPVisionEncode`, `WanFirstLastFrameToVideo`, or any image input. It uses `EmptyHunyuanLatentVideo` for latent initialization and text-only conditioning.

## Models

# ComfyUI Workflow Layout & Organization

Turn a tangled graph into a clean left-to-right dataflow a human reads at a glance,
using the `panel_*` canvas tools. The golden rule: never lay out blind. Read the
real node sizes and rail positions first, then compute positions from them.

## Primitives (panel tools)

- `panel_query_graph {fields:'detail', limit:200, max_chars:60000}`. READ FIRST, every time. Returns, for the graph you're viewing:
  - each node's `pos` [x,y], `size` [w,h] (body only), and `full_height` (the
    TRUE rendered footprint = title bar + body; use this for vertical stacking),
  - all `groups` (`id`, `title`, `color`, `bounding [x,y,w,h]`),
  - and, only when inside a subgraph, the `rails`: the `input` / `output` boundary
    node positions. Everything below is computed from these numbers.

# Z-Image Text-to-Image Workflows

> **Launch flag.** Z-Image does not sample correctly under
> `--use-sage-attention` (black / garbled output). Launch ComfyUI with
> `--use-pytorch-cross-attention` for Z-Image. See
> [`comfyui-launch-flags`](../comfyui-launch-flags/SKILL.md).

## Overview

Z-Image is a 6B-parameter image generation model from Alibaba's Tongyi Lab using a Scalable Single-Stream DiT (S3-DiT) architecture. It uses a Qwen text encoder (not CLIP-L/T5). Its VAE shares the Flux VAE architecture (same tensor shapes, so the file is the same 320MB size) but ships different weights. It is NOT byte-identical to Flux's `ae.safetensors` and must be kept as a separate file (`z-image-ae.safetensors`) to avoid clobbering the Flux VAE. Two variants:

1. Z-Image Base (and RedCraft finetune). Full model, supports negative prompts, LoRA training, ControlNet. 10-30 steps.
2. Z-Image Turbo. DMD-distilled, 8-10 steps, no effective negative prompts (CFG baked in).