docs(qwen-image-layered): document the layers widget and the layers + 1 output

[christian-byrne]

Problem

tutorials/image/qwen/qwen-image-layered.mdx has no section on the layers widget and never says what a generation produces. A reader following the template gets three images out of a layers = 2 run and has no way to know that the first one is not a layer.

These semantics are not written down anywhere: not in core, not on docs.comfy.org, not on the Hugging Face model card. A core maintainer could not work them out from the code and had to ask.

What is actually true

comfyanonymous, on this model:

it's a model specific thing, it's because this model is an image generation model that regenerates the full image and the layers

so if you set layers to zero you get only the original image

but if you set layers to 2 you get the original image + 2 layers

the first image is exactly the same as the original and should be discarded

and all the layers when composited together should recreate the original image

Verified against source:

• comfy_extras/nodes_qwen.py:109-130: EmptyQwenImageLayeredLatentImage allocates torch.zeros([batch_size, 16, layers + 1, height // 8, width // 8]), and layers has min=0.
• comfy_extras/nodes_latent.py:217-256: LatentCutToBatch with dim="t" reshapes the temporal axis into the batch dimension, so the decoded z-order is purely the batch index. Nothing else carries it.
• comfy/sd.py:791 sets output_channels from encoder.conv1.weight; the Qwen-Image-Layered VAE ships that as [96, 4, 3, 3, 3], so it decodes to 4 channels.
• The shipped template templates/image_qwen_image_layered.json wires EmptyQwenImageLayeredLatentImage (layers = 2) into LatentCutToBatch(dim="t") into VAEDecode into SaveImage, which is why the default run saves 3 images.

Change

A new ## Layers and output section on the English page and its zh / ja / ko mirrors, covering:

• the layers + 1 output count, with a small table for 0 / 2 / 5
• that image 0 is the full image, not a layer, and should be discarded when only the layers are wanted
• that layers = 0 is valid and yields that image alone
• the reconstruction guarantee, framed as a check the reader can actually run
• the temporal-axis mechanism and the fact that z-order is positional with no z-index field or per-layer metadata
• that decoded layers carry alpha

No screenshots needed: this page embeds none, and it stated no output count that is now contradicted.

Translations

zh / ja / ko were regenerated with the repo's own pipeline (pnpm translate on the new block only, incremental), then read back and repunctuated by hand so the new section matches the fullwidth punctuation and latin spacing of the surrounding text on each page. pnpm translate:check-truncation reports no issues for this page.

Related, not fixed here

comfyanonymous also said "our qwen layered template is slightly wrong", meaning the template saves the duplicate first image. That is a fix in Comfy-Org/workflow_templates, not here.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
comfy	🟢 Ready	View Preview	Aug 6, 2026, 10:34 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 26 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b49014e3-e1c5-426a-9d5d-69d6f60167bc

📥 Commits

Reviewing files that changed from the base of the PR and between 2943e37 and 7cceea2.

📒 Files selected for processing (4)

• ja/tutorials/image/qwen/qwen-image-layered.mdx
• ko/tutorials/image/qwen/qwen-image-layered.mdx
• tutorials/image/qwen/qwen-image-layered.mdx
• zh/tutorials/image/qwen/qwen-image-layered.mdx

---

_{Comment @coderabbitai help to get the list of available commands.}