Deploy Z Image Turbo

Cause: Encoder count is model-specific and modern models pair a small CLIP with a large, easy-to-forget LLM/VL encoder: HiDream's QuadrupleCLIPLoader needs FOUR (incl. llama-3.1-8b fp8_scaled ~8.5GB); HunyuanVideo needs DUAL (clip_l + llava_llama3, +vision for i2v); Qwen-Image needs Qwen-2.5-VL-7B (~7GB fp8 to ~16GB bf16); Z-Image needs Qwen-3-4B (8GB). A 'not in list' error usually means you shipped N-1.

Fix: Ship the full encoder set for the exact model; the missing piece is almost always the large LLM/VL encoder, not the CLIP.

Cause: Z-Image Turbo is a photoreal-leaning generalist, not an anime model; Z-Anime (SeeSee21 fine-tune) is a separate community model on the identical architecture and loads via the same zimage deploy path. Encoder architecture is Qwen-3-4B, VAE = Flux's ae.safetensors (335MB). fp8 diffusion 6.15GB (fits 12GB), bf16 12.3GB; GGUF Q3-Q8 for low VRAM.

Fix: A Turbo base and its fine-tunes share architecture + VAE (and the Qwen-3-4B encoder architecture — a fine-tune may ship its own tuned encoder weights, e.g. Z-Anime's qwen_3_4b-engineer-v4-fp8), so one zimage deploy path serves both.

Cause: ComfyUI-GGUF's UnetLoaderGGUF reads a dedicated 'unet_gguf' folder key (fed from both unet and diffusion_models). models/unet is the reliably-covered location; the equivalent .safetensors goes in models/diffusion_models.

Fix: Route .gguf diffusion weights to models/unet (canonical, always covered). A GGUF in diffusion_models may not appear depending on ComfyUI/GGUF version — don't rely on it.

Cause: Unpinned by default: models pull from floating HF /resolve/main (branch HEAD), custom nodes are git-clone-latest (no SHA), Docker tags are reused, and only ~95% file-size is validated, not content hash. An upstream re-upload or newer node code silently changed bytes/behavior behind unchanged names.

Fix: Pin weights to a commit/revision, nodes to a SHA, images to a digest. Verify a pinned HF URL with `curl -sI -r 0-0 -A 'Mozilla/5.0' -L '<url>'` — MUST include -L (HF /resolve/ 302-redirects to a CDN; without -L you see 302 not 206).

Cause: The node was pinned to a commit predating when the required node class was added upstream. (The inverse also bites: a too-NEW pin can fail to import, forcing a rollback to an older release.)

Fix: Two-sided constraint: pin new enough that EVERY referenced node class is registered, but NOT so new it needs a ComfyUI newer than the baked image. Verify the pinned commit's NODE_CLASS_MAPPINGS registers all referenced classes AND imports cleanly against the deployed ComfyUI.

Cause: A reused mutable Docker tag means the container host serves an image it already cached under that tag and skips the re-pull after a rebuild (unless pull policy forces it or a differing digest is detected) — so it runs the stale image.

Fix: Push to a fresh tag or an immutable @sha256 digest. Treat 'not taking effect after rebuild' as a pull-cache symptom first.