Keep workflows out of the node pack

H3_QUALITY_NOTES.md

@@ -0,0 +1,49 @@
+# MiniMax H3 quality and memory notes
+
+These settings are what the working two-pass workflow uses. They were isolated by A/B runs on the same
+checkpoint, seed and prompt.
+
+## Keep
+
+- First pass: `euler` / `beta57`, 8 steps, cfg 1, shifts `0 / 0`.
+- Second pass: fp32 `minimax_h3_latent_upscaler_3d_conv_v1_fp32.pth`, 1 MP, 3 steps, start sigma 0.9035, `er_sde`.
+- Performance: `comfy kitchen attention`, `ffn_chunks` 2, sparse attention off.
+- Save: NVENC `slow`, quality, CQ 19, 8-bit, 48 fps.
+- Loader: `quality`, explicit `minimax` clip type.
+- LoRAs: free to toggle. The reference stack is Realism 1.5, Age -0.5, Flat Chested 0.75,
+  Ref2VA Motion 0.75, GalaxyAce 1.0, Moawxx audio 1.0, SexGod 1.0.
+
+## What makes it worse
+
+| Setting | Effect |
+|---|---|
+| `er_sde` + `simple` | Coloured chroma speckle over skin and flat surfaces |
+| fp16 latent upscaler | Washed contrast, low skin texture, plastic look |
+| sparse attention on | Smeared fine detail |
+| `ffn_chunks` 1 | Second-stage out-of-memory on 16 GB |
+| NVENC fastest/fast/balanced | Bands on gradients and flat walls |
+| shift 12/3 at 8 steps | Harsher, less stable result |
+
+## Memory
+
+More enabled LoRAs use more VRAM. If the second stage OOMs, raise `ffn_chunks` to 3 or 4. Do not turn on
+sparse attention as the first fix; it costs detail. The node also unloads everything between the first and
+second pass and decodes the first pass only after both sampling passes.
+
+## Headless
+
+Use `PromptForge_H3_AllInOne_Modes_v5.api.json`. It is already in `/prompt` format. The normal workflow
+file stores the image picker as an extra leading widget on Load Image; order-based converters that ignore
+that read the filename as the description and send no picture.
+
+## Text writer sampling (Qwen3-VL)
+
+Use the model card values: temperature 0.7, top_p 0.8, top_k 20, repetition_penalty 1.0, presence_penalty 1.0-1.5.
+Thinking mode would be 0.6 / 0.95 / 20 / 1.0, but the writer runs with thinking off.
+
+Bad: temperature near 0 or greedy, no_repeat_ngram_size 4 forced on, repetition penalty above 1.15, top_p above
+0.95 for long structured prompts, and stopping the sampler on the first repeated phrase. Those cause the
+"starts fine, then rambles and never ends" failure.
+
+Presence 1.5 is the Qwen serving value, but HF counts the whole prompt as "seen", so on very long prompts it
+can be too strong. 1.0 is the default here; drop to 0.5 or 0 if the prose starts sounding forced.

README.md

@@ -15,8 +15,10 @@ Owns model choice and runtime configuration; outputs a `MODEL` bundle and a `REP
 
 ### Example image workflows
 
-- `workflows/KREA2_T2I_v2.json`, `KREA2_EDIT_v2.json` — Krea 2 text-to-image and identity edit, built on PromptForge Action and Enhancer. Edit needs `comfyui-krea2edit`, `krea2-nag` and the `krea2_identity_edit_v2` LoRA.
-- `workflows/MOSS_T2I_v2.json`, `MOSS_EDIT_v2.json` — MOSS-Image text-to-image and image edit. Edit needs ComfyUI 0.43+, `ComfyUI-MOSS-Toolkit` and `moss_image_edit_lora_rank_64_bf16.safetensors`. The edit workflow uses `task = custom` with full-size reference on purpose: the native ComfyUI MOSS model needs a full-size reference.
+The pack does not bundle workflows; they live in your ComfyUI `user/default/workflows` folder.
+
+- `KREA2_T2I_v2.json`, `KREA2_EDIT_v8.json` — Krea 2 text-to-image and identity edit, built on PromptForge Action and Enhancer. Edit needs `comfyui-krea2edit`, `krea2-nag` and the `krea2_identity_edit_v2` LoRA.
+- `MOSS_T2I_v2.json`, `MOSS_EDIT_v3.json` — MOSS-Image text-to-image and image edit. Edit needs ComfyUI 0.43+, `ComfyUI-MOSS-Toolkit` and `moss_image_edit_lora_rank_64_bf16.safetensors`. The edit workflow uses `task = custom` with full-size reference on purpose: the native ComfyUI MOSS model needs a full-size reference.
 
 ### PromptForge Action (`PROMPTFORGE_ImageAction`)
 
@@ -38,7 +40,7 @@ Takes the `MODEL` bundle and writes the prompt. Only generation inputs live here
 - **Preset**: `auto` or any bundled preset (Krea 2 T2I, Krea 2 Identity Edit, MOSS Image T2I/I2I, Qwen Image T2I, MiniMax H3, Anima, ACE-Step, generic styles…).
 - **MiniMax inputs**: the MiniMax H3 presets (T2VA, I2VA, L2VA, FL2VA, Ref2VA, plus the NSFW variants) get an authoritative list of what is connected. Labels follow the H3 encoder: `<Picture 1>`, `<Picture 2>`, `<Picture 3>` for the connected images in order with gaps closed up (only `image2` connected makes it `<Picture 1>`), and `<Video 1>` for the video. Each mode uses only what it can: T2VA none, I2VA/L2VA one image as first/last frame, FL2VA two images as first and last frame, Ref2VA all images plus the video; anything else that is connected is ignored and the console says so. The frame-alignment line is written by the node for exactly the attached pictures (omitted when none), the model is told which labels do not exist, and any sentence that still cites an unattached picture, video or audio label is removed. The node attaches no audio, so `<Audio N>` only appears when your own text describes it.
 - **Video duration**: `video_seconds` sets the exact clip length; MiniMax H3 presets use it for shot budget, timestamps and the frame alignment line.
-- **Headless / API**: use `workflows/PromptForge_H3_AllInOne_Modes_v4.api.json`. It is already in `/prompt` format; the regular workflow file stores the image picker as an extra widget, so homemade order-based converters read the filename as the description and send no picture.
+- **Headless / API**: use `PromptForge_H3_AllInOne_Modes_v5.api.json`. It is already in `/prompt` format; the regular workflow file stores the image picker as an extra widget, so homemade order-based converters read the filename as the description and send no picture.
 - **Sampling**: seed, max_tokens (default 3072), temperature 0.7, top_p 0.8, top_k 20, num_beams, repetition_penalty 1.0, presence_penalty 1.0 (Qwen serving uses 1.5; 0.5-1.0 is safer on long structured prompts, 0 turns it off).
 - **Auto-retry** (`auto_retry` toggle on the Prompt Enhancer, on by default; off keeps the first output): rejects empty, too-short, degenerate/repetitive, leaked-reasoning ("Okay, the user wants…"), refusal or broken-contract output and retries up to two more times with new seeds; if every try is a loop, the longest one is returned with repeated sentences removed. Status lines name the reason (too short, repetitive, reasoning leak, refusal, negative wording). Outputs under 400 chars (40 for tag/refine/technical presets, 120 when max_tokens is below 192) count as too short.
 - **Repetition guard**: the sampler is only stopped on an unmistakable 12-gram loop; repeated sentences and repeated 5–10 word phrases are rejected afterwards. Qwen3-VL runs at its tuned 0.7 / 0.8 / 20 / 1.0 with presence penalty 1.5; a hard `no_repeat_ngram_size` is not forced, because it distorts long structured prompts.

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "ComfyUI-PromptForge"
 description = "ComfyUI prompt enhancement suite: model/config node with GPU-aware auto settings, prompt enhancer with a preset catalog, and a standalone config finder."
-version = "1.28.4"
+version = "1.28.5"
 license = { file = "LICENSE" }
 dependencies = [
     "transformers",