Commit ca4e755 for stable-diffusion.cpp
commit ca4e755dfa75559ad99e2fd644b0692f776290df
Author: leejet <leejet714@gmail.com>
Date: Sat Nov 14 18:01:50 2026 +0800
docs: reorganize documentation and improve README navigation
diff --git a/.gitignore b/.gitignore
index 1a4646a..13a7754 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,7 +16,7 @@ logs/
*.exe
*.gguf
output*.png
-models*
+/models*
*.log
preview.png
.claude/
diff --git a/AGENTS.md b/AGENTS.md
index a480408..9579846 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -91,7 +91,11 @@ documentation.
### Documentation and Tooling
* `docs/` - documentation for supported models, build options, behavior, and
- workflows.
+ workflows; start from `docs/README.md`.
+* `docs/models/` - model and component usage guides, including LoRAs, adapters,
+ auxiliary models, and model-specific examples.
+* `docs/guides/` - shared usage workflows, configuration, and performance guides.
+* `docs/development/` - internal implementation and model integration conventions.
* `scripts/` - development, model processing, build automation, formatting, and
tooling scripts.
* `cmake/` - CMake support modules.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 15045dc..42d61e0 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -31,19 +31,28 @@ PRs should include:
## Documentation
-Write model usage guides in `docs/` for users. Focus on supported weights,
-setup, runnable commands, parameter meanings, output behavior, and practical
-limits such as memory requirements. Include technical details only when they
-help users choose settings or troubleshoot a problem.
+Write model and component usage guides in `docs/models/` for users. Focus on
+supported weights, setup, runnable commands, parameter meanings, output behavior,
+and practical limits such as memory requirements. Include technical details only
+when they help users choose settings or troubleshoot a problem.
+
+Put shared usage workflows and configuration in `docs/guides/`, and internal
+implementation details and development conventions in `docs/development/`.
+Keep build, Docker, and troubleshooting guides at the root of `docs/`.
+Link new documentation from [the documentation index](docs/README.md) or
+[the model index](docs/models/README.md), as appropriate. Keep supported model
+entries and their guide links in the project README.
Keep tensor layouts, internal class names, kernel implementation details,
algorithm derivations, and development history out of usage guides. Keep task-specific
profiling logs, numerical comparison procedures, and test artifacts local, and
summarize relevant verification results in the PR description.
-## README UI Listings
+## Application and UI Listings
-The [UIs list in the README](README.md#uis) only includes open-source projects that use `stable-diffusion.cpp` as a backend. Do not submit PRs to add closed-source UIs.
+The [applications and UIs list](docs/ecosystem.md#applications-and-uis) only
+includes open-source projects that use `stable-diffusion.cpp` as a backend.
+Do not submit PRs to add closed-source applications or UIs.
## Server Recipes
@@ -76,7 +85,8 @@ Naming conventions:
Some older code in the project may not fully follow the current conventions. Please do not submit PRs that only rewrite existing code to match style rules.
-When adding or modifying model implementations, follow the model config and weight detection conventions in [docs/model_config.md](docs/model_config.md).
+When adding or modifying model implementations, follow the
+[model config and weight detection conventions](docs/development/model_config.md).
## Tokenizer Data
diff --git a/README.md b/README.md
index 92103a3..224d112 100644
--- a/README.md
+++ b/README.md
@@ -39,68 +39,69 @@ API and command-line option may change frequently.***
- Plain C/C++ implementation based on [ggml](https://github.com/ggml-org/ggml), working in the same way as [llama.cpp](https://github.com/ggml-org/llama.cpp)
- Super lightweight and without external dependencies
+- Built-in [Web UI](./examples/server/README.md) for image and video generation
- Supported models
- Image Models
- - [SD1.x, SD2.x, SD-Turbo](./docs/sd.md)
- - [SDXL, SDXL-Turbo](./docs/sd.md)
- - [Some SD1.x and SDXL distilled models](./docs/distilled_sd.md)
- - [SD3/SD3.5](./docs/sd3.md)
- - [FLUX.1-dev/FLUX.1-schnell](./docs/flux.md)
- - [FLUX.2-dev/FLUX.2-klein](./docs/flux2.md)
- - [FLUX.3 Image Klein / Klein Base](./docs/flux3.md)
- - [MOSS-Image-Base / MOSS-Image-SFT](./docs/moss_image.md)
- - [Fibo 2.0 Dev](./docs/fibo2.md)
- - [Lens](./docs/lens.md)
- - [Chroma](./docs/chroma.md)
- - [Chroma1-Radiance](./docs/chroma_radiance.md)
- - [Qwen Image](./docs/qwen_image.md)
- - [Qwen Image 2.1](./docs/qwen_image_2.1.md)
- - [PiD](./docs/pid.md)
- - [LongCat Image](./docs/longcat_image.md)
- - [Z-Image](./docs/z_image.md)
- - [Z-Image L2P](./docs/z_image_l2p.md)
- - [MiniT2I](./docs/minit2i.md)
- - [P-H3-Image](./docs/p_h3_image.md)
- - [MiniMax-H3-Image](./docs/minimax_h3_image.md)
- - [SenseNova U1.5](./docs/sensenova_u1.md)
- - [Ovis-Image](./docs/ovis_image.md)
- - [Anima](./docs/anima.md)
- - [ERNIE-Image](./docs/ernie_image.md)
- - [Boogu Image](./docs/boogu_image.md)
- - [Krea2](./docs/krea2.md)
- - [Mage-Flow](./docs/mage_flow.md)
- - [SeFi-Image](./docs/sefi_image.md)
- - [HiDream-O1-Image](./docs/hidream_o1_image.md)
- - [Ideogram4](./docs/ideogram4.md)
- - [LLaDA-Image](./docs/llada_image.md)
- - [Ming-Image Design](./docs/ming_image.md)
- - [PixArt](./docs/pixart.md)
- - [Iris-3B](./docs/iris.md)
- - [Image Edit Models](./docs/edit.md)
- - [FLUX.1-Kontext-dev](./docs/kontext.md)
- - [Qwen Image Edit series](./docs/qwen_image_edit.md)
- - [LongCat Image Edit](./docs/longcat_image.md)
- - [Boogu Image Edit](./docs/boogu_image.md)
- - [Mage-Flow-Edit](./docs/mage_flow.md#image-editing)
- - [LLaDA-Image Edit](./docs/llada_image.md#image-editing)
- - [Fibo 2.0 Dev / Edit Turbo](./docs/fibo2.md#editing-and-turbo)
+ - [SD1.x, SD2.x, SD-Turbo](./docs/models/sd.md)
+ - [SDXL, SDXL-Turbo](./docs/models/sd.md)
+ - [Some SD1.x and SDXL distilled models](./docs/models/distilled_sd.md)
+ - [SD3/SD3.5](./docs/models/sd3.md)
+ - [FLUX.1-dev/FLUX.1-schnell](./docs/models/flux.md)
+ - [FLUX.2-dev/FLUX.2-klein](./docs/models/flux2.md)
+ - [FLUX.3 Image Klein / Klein Base](./docs/models/flux3.md)
+ - [MOSS-Image-Base / MOSS-Image-SFT](./docs/models/moss_image.md)
+ - [Fibo 2.0 Dev](./docs/models/fibo2.md)
+ - [Lens](./docs/models/lens.md)
+ - [Chroma](./docs/models/chroma.md)
+ - [Chroma1-Radiance](./docs/models/chroma_radiance.md)
+ - [Qwen Image](./docs/models/qwen_image.md)
+ - [Qwen Image 2.1](./docs/models/qwen_image_2.1.md)
+ - [PiD](./docs/models/pid.md)
+ - [LongCat Image](./docs/models/longcat_image.md)
+ - [Z-Image](./docs/models/z_image.md)
+ - [Z-Image L2P](./docs/models/z_image_l2p.md)
+ - [MiniT2I](./docs/models/minit2i.md)
+ - [P-H3-Image](./docs/models/p_h3_image.md)
+ - [MiniMax-H3-Image](./docs/models/minimax_h3_image.md)
+ - [SenseNova U1.5](./docs/models/sensenova_u1.md)
+ - [Ovis-Image](./docs/models/ovis_image.md)
+ - [Anima](./docs/models/anima.md)
+ - [ERNIE-Image](./docs/models/ernie_image.md)
+ - [Boogu Image](./docs/models/boogu_image.md)
+ - [Krea2](./docs/models/krea2.md)
+ - [Mage-Flow](./docs/models/mage_flow.md)
+ - [SeFi-Image](./docs/models/sefi_image.md)
+ - [HiDream-O1-Image](./docs/models/hidream_o1_image.md)
+ - [Ideogram4](./docs/models/ideogram4.md)
+ - [LLaDA-Image](./docs/models/llada_image.md)
+ - [Ming-Image Design](./docs/models/ming_image.md)
+ - [PixArt](./docs/models/pixart.md)
+ - [Iris-3B](./docs/models/iris.md)
+ - [Image Edit Models](./docs/guides/edit.md)
+ - [FLUX.1-Kontext-dev](./docs/models/kontext.md)
+ - [Qwen Image Edit series](./docs/models/qwen_image_edit.md)
+ - [LongCat Image Edit](./docs/models/longcat_image.md)
+ - [Boogu Image Edit](./docs/models/boogu_image.md)
+ - [Mage-Flow-Edit](./docs/models/mage_flow.md#image-editing)
+ - [LLaDA-Image Edit](./docs/models/llada_image.md#image-editing)
+ - [Fibo 2.0 Dev / Edit Turbo](./docs/models/fibo2.md#examples)
- Video Models
- - [Wan2.1/Wan2.2](./docs/wan.md)
- - [MiniMax-H3](./docs/minimax_h3.md)
- - [LTX-2.3/LTX-2.5](./docs/ltx2.md)
- - [HunyuanVideo 1.5](./docs/hunyuan_video.md)
- - [LingBot-Video](./docs/lingbot_video.md)
+ - [Wan2.1/Wan2.2](./docs/models/wan.md)
+ - [MiniMax-H3](./docs/models/minimax_h3.md)
+ - [LTX-2.3/LTX-2.5](./docs/models/ltx2.md)
+ - [HunyuanVideo 1.5](./docs/models/hunyuan_video.md)
+ - [LingBot-Video](./docs/models/lingbot_video.md)
- Video Upscale Models
- - [RelayVSR](./docs/relay_vsr.md)
- - [SeedVR2](./docs/seedvr2.md)
- - [PhotoMaker](./docs/photo_maker.md) support.
- - [IP-Adapter](./docs/ip_adapter.md) support (SD 1.5 and SDXL, including Plus)
+ - [RelayVSR](./docs/models/relay_vsr.md)
+ - [SeedVR2](./docs/models/seedvr2.md)
+ - [PhotoMaker](./docs/models/photo_maker.md) support.
+ - [IP-Adapter](./docs/models/ip_adapter.md) support (SD 1.5 and SDXL, including Plus)
- Control Net support with SD 1.5
- - [ADetailer](./docs/adetailer.md)
+ - [ADetailer](./docs/models/adetailer.md)
- LoRA support, same as [stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Features#lora)
- Latent Consistency Models support (LCM/LCM-LoRA)
- - Faster and memory efficient latent decoding with [TAESD](./docs/taesd.md)
- - Upscale images generated with [ESRGAN](./docs/esrgan.md)
+ - Faster and memory efficient latent decoding with [TAESD](./docs/models/taesd.md)
+ - Upscale images generated with [ESRGAN](./docs/models/esrgan.md)
- Supported backends
- CPU (AVX, AVX2 and AVX512 support for x86 architectures)
- CUDA
@@ -122,16 +123,7 @@ API and command-line option may change frequently.***
- Negative prompt
- [stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui) style tokenizer (not all the features, only token weighting for now)
- VAE tiling processing for reduce memory usage
-- Sampling method
- - `Euler A`
- - `Euler`
- - `Heun`
- - `DPM2`
- - `DPM++ 2M`
- - [`DPM++ 2M v2`](https://github.com/AUTOMATIC1111/stable-diffusion-webui/discussions/8457)
- - `DPM++ 2S a`
- - `ER-SDE`
- - [`LCM`](https://github.com/AUTOMATIC1111/stable-diffusion-webui/issues/13952)
+- Support for a wide range of [sampling methods and schedulers](./docs/guides/sampling.md)
- Cross-platform reproducibility
- `--rng cuda`, default, consistent with the `stable-diffusion-webui GPU RNG`
- `--rng cpu`, consistent with the `comfyui RNG`
@@ -139,73 +131,67 @@ API and command-line option may change frequently.***
## Quick Start
-### Get the sd executable
+### Get the executables
-- Download pre-built binaries from the [releases page](https://github.com/leejet/stable-diffusion.cpp/releases)
+- Download and extract pre-built binaries from the [releases page](https://github.com/leejet/stable-diffusion.cpp/releases)
- Or build from source by following the [build guide](./docs/build.md)
+Run the commands below from the directory containing `sd-server` and `sd-cli`
+(typically `build/bin/` or `build/bin/Release/` for source builds). On Windows,
+use `.\sd-server.exe` and `.\sd-cli.exe` in place of `./sd-server` and `./sd-cli`.
+
### Download model weights
-- download weights(.ckpt or .safetensors or .gguf). For example
- - Stable Diffusion v1.5 from https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5
+Choose a model from the [model guides](./docs/models/README.md) and download its
+weights and required components into a `models/` directory. For a simple example,
+download Stable Diffusion v1.5:
+
+```sh
+mkdir models
+curl -L -o models/v1-5-pruned-emaonly.safetensors https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors
+```
+
+### Option 1: Web UI
+
+Start the server:
- ```sh
- curl -L -O https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors
- ```
+```sh
+./sd-server --model-dir ./models
+```
+
+Open <http://127.0.0.1:1234/>, choose the matching model recipe and downloaded
+component files, then click **Load models**. Enter a prompt and generate an image.
-### Generate an image with just one command
+For startup scripts, frontend build requirements, and server options, see the
+[server guide](./examples/server/README.md).
+
+### Option 2: CLI
+
+Generate an image with one command:
```sh
-./bin/sd-cli -m ../models/v1-5-pruned-emaonly.safetensors -p "a lovely cat"
+./sd-cli -m ./models/v1-5-pruned-emaonly.safetensors -p "a lovely cat"
```
-***For detailed command-line arguments, check out [cli doc](./examples/cli/README.md).***
+Run `./sd-cli --help` for the full list of command-line options. See the
+[CLI guide](./examples/cli/README.md) for additional usage notes.
## Performance
-If you want to improve performance or reduce VRAM/RAM usage, please refer to [performance guide](./docs/performance.md).
-For runtime and parameter backend placement, see the [backend selection guide](./docs/backend.md).
+If you want to improve performance or reduce VRAM/RAM usage, please refer to [performance guide](./docs/guides/performance.md).
+For runtime and parameter backend placement, see the [backend selection guide](./docs/guides/backend.md).
+
+## Documentation
-## More Guides
+Browse the [documentation index](./docs/README.md) or jump to a topic:
+- [Getting started: build, Docker, CLI, and server](./docs/README.md#get-started)
+- [Models and components](./docs/models/README.md)
+- [Generation and inputs](./docs/README.md#generation-and-inputs)
+- [Devices and performance](./docs/README.md#devices-and-performance)
+- [Weights and quantization](./docs/README.md#weights-and-quantization)
- [Troubleshooting](./docs/troubleshooting.md)
-- [Backend selection](./docs/backend.md)
-- [RPC](./docs/rpc.md)
-- [LoRA](./docs/lora.md)
-- [LCM/LCM-LoRA](./docs/lcm.md)
-- [Docker](./docs/docker.md)
-- [Quantization and GGUF](./docs/quantization_and_gguf.md)
-- [INT8 convrot safetensors](./docs/int8_convrot.md)
-- [Inference acceleration via caching](./docs/caching.md)
-
-## Bindings
-
-These projects wrap `stable-diffusion.cpp` for easier use in other languages/frameworks.
-
-* Golang (non-cgo): [seasonjs/stable-diffusion](https://github.com/seasonjs/stable-diffusion)
-* Golang (cgo): [Binozo/GoStableDiffusion](https://github.com/Binozo/GoStableDiffusion)
-* Golang (non-cgo): [l8bloom/gosd](https://github.com/l8bloom/gosd)
-* C#: [DarthAffe/StableDiffusion.NET](https://github.com/DarthAffe/StableDiffusion.NET)
-* Python: [william-murray1204/stable-diffusion-cpp-python](https://github.com/william-murray1204/stable-diffusion-cpp-python)
-* Rust: [newfla/diffusion-rs](https://github.com/newfla/diffusion-rs)
-* Flutter/Dart: [rmatif/Local-Diffusion](https://github.com/rmatif/Local-Diffusion)
-
-## UIs
-
-These projects use `stable-diffusion.cpp` as a backend for their image generation.
-
-- [GIMP Plugins](https://github.com/themanyone/gimp-plugins)
-- [Stable Diffusion GUI](https://github.com/fszontagh/sd.cpp.gui.wx)
-- [Stable Diffusion CLI-GUI](https://github.com/piallai/stable-diffusion.cpp)
-- [Local Diffusion](https://github.com/rmatif/Local-Diffusion)
-- [sd.cpp-webui](https://github.com/daniandtheweb/sd.cpp-webui)
-- [LocalAI](https://github.com/mudler/LocalAI)
-- [Neural-Pixel](https://github.com/Luiz-Alcantara/Neural-Pixel)
-- [KoboldCpp](https://github.com/LostRuins/koboldcpp)
-- [Kokon](https://github.com/GabrieleLozupone/kokon)
-- [NodeTool](https://github.com/nodetool-ai/nodetool)
-- [Quo](https://github.com/quo-ai/quo)
-- [Prisme](https://github.com/d3Ita/prisme)
+- [Development and contributing](./docs/README.md#development)
## Contributors
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..45ccdd9
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,45 @@
+# Documentation
+
+For the project overview and supported models, see the [project README](../README.md).
+
+## Get started
+
+- [Model and component guides](models/README.md): download weights and run model-specific examples.
+- [Build from source](build.md)
+- [Docker](docker.md)
+- [CLI usage guide](../examples/cli/README.md)
+- [Server setup](../examples/server/README.md)
+- [Server API reference](../examples/server/api.md)
+- [Community bindings, applications, and UIs](ecosystem.md)
+- [Troubleshooting](troubleshooting.md)
+
+## Generation and inputs
+
+- [Sampling methods and schedulers](guides/sampling.md)
+- [Image editing](guides/edit.md)
+- [Images in prompts](guides/prompt_images.md)
+- [Image preprocessing](guides/image_preprocessing.md)
+- [Generation results and metadata](guides/generation_metadata.md)
+- [JSON tokenizers](guides/tokenizers.md)
+
+## Devices and performance
+
+- [Backend selection and device placement](guides/backend.md)
+- [Performance and memory usage](guides/performance.md)
+- [Inference caching](guides/caching.md)
+- [RPC](guides/rpc.md)
+- [SageAttention](guides/sage_attention.md)
+
+## Weights and quantization
+
+- [Quantization and GGUF conversion](guides/quantization_and_gguf.md)
+- [Importance matrix quantization](guides/imatrix.md)
+- [INT8 and INT4 convrot weights](guides/int8_convrot.md)
+
+## Development
+
+- [Model configuration and integration conventions](development/model_config.md)
+- [ggml operator extensions](development/ggml_extensions.md)
+- [Backend performance probes](development/backend_probe.md)
+- [Position embedding cache](development/pe_cache.md)
+- [Contribution guidelines](../CONTRIBUTING.md)
diff --git a/docs/build.md b/docs/build.md
index ec9077f..af8a336 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -101,7 +101,7 @@ cmake --build . --config Release
The sd.cpp SageAttention extension is included when using CUDA with patched
GGML (`SD_USE_UPSTREAM_GGML=OFF`).
-See [SageAttention](sage_attention.md) for GPU requirements and `--sage-attn` usage.
+See [SageAttention](guides/sage_attention.md) for GPU requirements and `--sage-attn` usage.
This provides GPU acceleration using NVIDIA GPU. Make sure to have the CUDA toolkit installed. You can download it from your Linux distro's package manager (e.g. `apt install nvidia-cuda-toolkit`) or from here: [CUDA Toolkit](https://developer.nvidia.com/cuda-downloads). Recommended to have at least 4 GB of VRAM.
diff --git a/docs/backend_probe.md b/docs/development/backend_probe.md
similarity index 100%
rename from docs/backend_probe.md
rename to docs/development/backend_probe.md
diff --git a/docs/ggml_extensions.md b/docs/development/ggml_extensions.md
similarity index 100%
rename from docs/ggml_extensions.md
rename to docs/development/ggml_extensions.md
diff --git a/docs/model_config.md b/docs/development/model_config.md
similarity index 100%
rename from docs/model_config.md
rename to docs/development/model_config.md
diff --git a/docs/pe_cache.md b/docs/development/pe_cache.md
similarity index 100%
rename from docs/pe_cache.md
rename to docs/development/pe_cache.md
diff --git a/docs/ecosystem.md b/docs/ecosystem.md
new file mode 100644
index 0000000..7420c69
--- /dev/null
+++ b/docs/ecosystem.md
@@ -0,0 +1,31 @@
+# Bindings, Applications, and UIs
+
+## Bindings
+
+These projects wrap `stable-diffusion.cpp` for easier use in other languages/frameworks.
+
+* Golang (non-cgo): [seasonjs/stable-diffusion](https://github.com/seasonjs/stable-diffusion)
+* Golang (cgo): [Binozo/GoStableDiffusion](https://github.com/Binozo/GoStableDiffusion)
+* Golang (non-cgo): [l8bloom/gosd](https://github.com/l8bloom/gosd)
+* C#: [DarthAffe/StableDiffusion.NET](https://github.com/DarthAffe/StableDiffusion.NET)
+* Python: [william-murray1204/stable-diffusion-cpp-python](https://github.com/william-murray1204/stable-diffusion-cpp-python)
+* Rust: [newfla/diffusion-rs](https://github.com/newfla/diffusion-rs)
+* Flutter/Dart: [rmatif/Local-Diffusion](https://github.com/rmatif/Local-Diffusion)
+
+## Applications and UIs
+
+These projects include dedicated interfaces for `stable-diffusion.cpp` and
+applications that integrate it as an image generation backend.
+
+- [GIMP Plugins](https://github.com/themanyone/gimp-plugins)
+- [Stable Diffusion GUI](https://github.com/fszontagh/sd.cpp.gui.wx)
+- [Stable Diffusion CLI-GUI](https://github.com/piallai/stable-diffusion.cpp)
+- [Local Diffusion](https://github.com/rmatif/Local-Diffusion)
+- [sd.cpp-webui](https://github.com/daniandtheweb/sd.cpp-webui)
+- [LocalAI](https://github.com/mudler/LocalAI)
+- [Neural-Pixel](https://github.com/Luiz-Alcantara/Neural-Pixel)
+- [KoboldCpp](https://github.com/LostRuins/koboldcpp)
+- [Kokon](https://github.com/GabrieleLozupone/kokon)
+- [NodeTool](https://github.com/nodetool-ai/nodetool)
+- [Quo](https://github.com/quo-ai/quo)
+- [Prisme](https://github.com/d3Ita/prisme)
diff --git a/docs/backend.md b/docs/guides/backend.md
similarity index 100%
rename from docs/backend.md
rename to docs/guides/backend.md
diff --git a/docs/caching.md b/docs/guides/caching.md
similarity index 100%
rename from docs/caching.md
rename to docs/guides/caching.md
diff --git a/docs/edit.md b/docs/guides/edit.md
similarity index 90%
rename from docs/edit.md
rename to docs/guides/edit.md
index 1312854..a12cc83 100644
--- a/docs/edit.md
+++ b/docs/guides/edit.md
@@ -9,17 +9,17 @@ Depending on the architecture, different models handle reference images differen
| Model | Default Preset |
| :--- | :--- |
-| [**FLUX.1-Kontext-dev**](./kontext.md) | `flux_kontext` |
-| [**LongCat Image Edit**](./longcat_image.md) | `longcat` |
-| [**Qwen Image Edit**](./qwen_image_edit.md) | `qwen` |
+| [**FLUX.1-Kontext-dev**](../models/kontext.md) | `flux_kontext` |
+| [**LongCat Image Edit**](../models/longcat_image.md) | `longcat` |
+| [**Qwen Image Edit**](../models/qwen_image_edit.md) | `qwen` |
| **Qwen Image LAYERED** | `qwen_layered` |
-| [**Flux.2 [Dev] / Flux.2 [Klein]**](./flux2.md) | `flux2` |
-| [**FLUX.3 Image Klein / Klein Base**](./flux3.md) | `flux2` |
-| [**Boogu Image Edit**](./boogu_image.md) | `z_image_omni` |
+| [**Flux.2 [Dev] / Flux.2 [Klein]**](../models/flux2.md) | `flux2` |
+| [**FLUX.3 Image Klein / Klein Base**](../models/flux3.md) | `flux2` |
+| [**Boogu Image Edit**](../models/boogu_image.md) | `z_image_omni` |
| **Krea2 (Community Edit LoRAs)** | `krea2_ostris_edit` |
-| [**Mage-Flow-Edit**](./mage_flow.md#image-editing) | `mage_flow` |
-| [**LLaDA-Image**](./llada_image.md#image-editing) | `llada_image` |
-| [**Fibo 2.0 Dev / Edit Turbo**](./fibo2.md#examples) | `fibo2` |
+| [**Mage-Flow-Edit**](../models/mage_flow.md#image-editing) | `mage_flow` |
+| [**LLaDA-Image**](../models/llada_image.md#image-editing) | `llada_image` |
+| [**Fibo 2.0 Dev / Edit Turbo**](../models/fibo2.md#examples) | `fibo2` |
| **Anima (Community Edit LoRAs)** | `cosmos_reference` |
Stable-diffusion.spp also supports basic Unet-based editing models like instruct-pix2pix or CosXL-Edit. This document is not about those.
@@ -98,7 +98,7 @@ For a technical overview of how each preset is configured, see the table below.
| `flux_kontext` | No | `fixed` | `none` | |
| `longcat` | Yes | `fixed` | `area` | |
| `flux2` | No | `increase` | `none` | |
-| `fibo2` | Yes | `increase` | `longest` | Shared reference crops; clean reference timesteps; see [Fibo 2.0](./fibo2.md) |
+| `fibo2` | Yes | `increase` | `longest` | Shared reference crops; clean reference timesteps; see [Fibo 2.0](../models/fibo2.md) |
| `qwen` | Yes | `increase` | `area` | |
| `qwen_layered` | Yes | `decrease` | `area` | |
| `mage_flow` | Yes | `increase` | `longest` | `vlm_max_size = 384`, VAE input resized to target |
diff --git a/docs/generation_metadata.md b/docs/guides/generation_metadata.md
similarity index 100%
rename from docs/generation_metadata.md
rename to docs/guides/generation_metadata.md
diff --git a/docs/image_preprocessing.md b/docs/guides/image_preprocessing.md
similarity index 100%
rename from docs/image_preprocessing.md
rename to docs/guides/image_preprocessing.md
diff --git a/docs/imatrix.md b/docs/guides/imatrix.md
similarity index 100%
rename from docs/imatrix.md
rename to docs/guides/imatrix.md
diff --git a/docs/int8_convrot.md b/docs/guides/int8_convrot.md
similarity index 99%
rename from docs/int8_convrot.md
rename to docs/guides/int8_convrot.md
index cf6219e..c105f15 100644
--- a/docs/int8_convrot.md
+++ b/docs/guides/int8_convrot.md
@@ -5,7 +5,7 @@ sd.cpp can load and execute ComfyUI `int8_tensorwise` safetensors with `convrot`
This uses sd.cpp's INT8 tensorwise/convrot operators through the patched GGML
extension API. Schemas and graph builders live in sd.cpp, alongside the
backend kernels and fusion rules; GGML supplies generic dispatch and workspace
-services. See [operator extensions](ggml_extensions.md) for the implementation
+services. See [operator extensions](../development/ggml_extensions.md) for the implementation
and the preserved INT8 API entry points.
Builds with `SD_USE_UPSTREAM_GGML=ON` reject these files during loading.
diff --git a/docs/performance.md b/docs/guides/performance.md
similarity index 99%
rename from docs/performance.md
rename to docs/guides/performance.md
index 1f5771c..76fb3da 100644
--- a/docs/performance.md
+++ b/docs/guides/performance.md
@@ -95,7 +95,7 @@ Execution failures are not retried, and encoding has no automatic OOM retry.
`--temporal-tiling` remains independent of spatial tiling. The original MiniMax-H3
video VAE uses spatial tiling (256x256 pixels and 25% overlap by default) and its own
temporal windows. With `--vae-tiling`, its overlap follows `--vae-tile-overlap` and
-explicit spatial sizes are honored. [Sol-H3-VAE](minimax_h3.md#sol-h3-vae-decoding)
+explicit spatial sizes are honored. [Sol-H3-VAE](../models/minimax_h3.md#sol-h3-vae-decoding)
decodes the whole clip by default and supports opt-in spatial and block-aligned
temporal tiling. Tiling may affect output quality.
diff --git a/docs/prompt_images.md b/docs/guides/prompt_images.md
similarity index 99%
rename from docs/prompt_images.md
rename to docs/guides/prompt_images.md
index 01a8703..726a797 100644
--- a/docs/prompt_images.md
+++ b/docs/guides/prompt_images.md
@@ -11,7 +11,7 @@ Inline images are available to conditioners using Qwen2.5-VL, Qwen3-VL, or
Qwen3.5 with compatible vision weights. Supply the vision encoder with
`--llm_vision` or use a combined text/vision encoder. Each model keeps its own
prompt template, text weighting, padding, and output-layer selection. Missing
-vision weights or a text-only LLM produce an error. See [MOSS-Image setup](moss_image.md)
+vision weights or a text-only LLM produce an error. See [MOSS-Image setup](../models/moss_image.md)
for a Qwen3.5 example.
## CLI
diff --git a/docs/quantization_and_gguf.md b/docs/guides/quantization_and_gguf.md
similarity index 100%
rename from docs/quantization_and_gguf.md
rename to docs/guides/quantization_and_gguf.md
diff --git a/docs/rpc.md b/docs/guides/rpc.md
similarity index 98%
rename from docs/rpc.md
rename to docs/guides/rpc.md
index cb28e25..6edd61d 100644
--- a/docs/rpc.md
+++ b/docs/guides/rpc.md
@@ -17,7 +17,7 @@ cmake .. \
cmake --build . --config Release -j $(nproc)
```
-> **Note:** Ensure you add the other flags you would normally use (e.g., `-DSD_VULKAN=ON`, `-DSD_CUDA=ON`, `-DSD_HIPBLAS=ON`, or `-DGGML_METAL=ON`), for more information about building `stable-diffusion.cpp` from source, please refer to the [build.md](build.md) documentation.
+> **Note:** Ensure you add the other flags you would normally use (e.g., `-DSD_VULKAN=ON`, `-DSD_CUDA=ON`, `-DSD_HIPBLAS=ON`, or `-DGGML_METAL=ON`), for more information about building `stable-diffusion.cpp` from source, please refer to the [build.md](../build.md) documentation.
## 2. Ensure `llama.cpp` is at the correct commit
diff --git a/docs/sage_attention.md b/docs/guides/sage_attention.md
similarity index 100%
rename from docs/sage_attention.md
rename to docs/guides/sage_attention.md
diff --git a/docs/guides/sampling.md b/docs/guides/sampling.md
new file mode 100644
index 0000000..499a9f0
--- /dev/null
+++ b/docs/guides/sampling.md
@@ -0,0 +1,125 @@
+# Sampling methods and schedulers
+
+The sampling method controls how each denoising step updates the image or video
+latent. The scheduler chooses the noise levels (sigmas) used across those steps.
+Choose both according to the [model guide](../models/README.md) for your checkpoint.
+
+## Usage
+
+For example, using the Stable Diffusion 1.5 checkpoint from the
+[quick start](../../README.md#quick-start):
+
+```sh
+./sd-cli -m ./models/v1-5-pruned-emaonly.safetensors \
+ --sampling-method euler_a --scheduler discrete --steps 20 -p "a lovely cat"
+```
+
+Run this from the directory containing `sd-cli`. On Windows, use `sd-cli.exe`
+with your shell's path and line-continuation syntax.
+
+| CLI option | Purpose |
+| --- | --- |
+| `--sampling-method NAME` | Select the sampling method. |
+| `--scheduler NAME` | Select the sigma scheduler. |
+| `--steps N` | Set the number of sampling steps. |
+| `--high-noise-sampling-method NAME` | Select the high-noise sampler for two-stage video models. |
+| `--sigmas VALUES_OR_PRESET` | Supply a custom schedule instead of generating one with the scheduler. |
+| `--hires-sigmas VALUES_OR_PRESET` | Supply a custom schedule for the highres fix second pass. |
+
+The names below are the exact, case-sensitive CLI values. Run `./sd-cli --help`
+to check the options supported by your installed build.
+
+For native server requests, use `sample_params.sample_method` and
+`sample_params.scheduler`. See the [server API reference](../../examples/server/api.md)
+for request fields and capability discovery.
+
+## Sampling methods
+
+| Method | CLI value |
+| --- | --- |
+| Euler | `euler` |
+| Euler ancestral | `euler_a` |
+| Heun | `heun` |
+| DPM2 | `dpm2` |
+| DPM++ 2S ancestral | `dpm++2s_a` |
+| DPM++ 2M | `dpm++2m` |
+| DPM++ 2M v2 (modified) | `dpm++2mv2` |
+| iPNDM | `ipndm` |
+| iPNDM V | `ipndm_v` |
+| LCM | `lcm` |
+| DDIM trailing | `ddim_trailing` |
+| TCD | `tcd` |
+| RES Multistep | `res_multistep` |
+| RES 2S | `res_2s` |
+| ER-SDE | `er_sde` |
+| Euler CFG++ | `euler_cfg_pp` |
+| Euler ancestral CFG++ | `euler_a_cfg_pp` |
+| Euler GE (gradient estimation) | `euler_ge` |
+| DPM++ 2M SDE | `dpm++2m_sde` |
+| DPM++ 2M SDE with Brownian tree noise | `dpm++2m_sde_bt` |
+| LMS | `lms` |
+
+## Schedulers
+
+| Scheduler | CLI value |
+| --- | --- |
+| Discrete | `discrete` |
+| Karras | `karras` |
+| Exponential | `exponential` |
+| AYS | `ays` |
+| GITS | `gits` |
+| SGM Uniform | `sgm_uniform` |
+| Simple | `simple` |
+| SmoothStep | `smoothstep` |
+| KL Optimal | `kl_optimal` |
+| LCM | `lcm` |
+| Bong Tangent | `bong_tangent` |
+| LTX-2 | `ltx2` |
+| Logit Normal | `logit_normal` |
+| FLUX.2 | `flux2` |
+| FLUX | `flux` |
+| Beta | `beta` |
+| LLaDA-Image | `llada_image` |
+
+`normal` is accepted as an alias for `discrete`.
+
+## Defaults and model compatibility
+
+Omitting `--sampling-method` and `--scheduler` uses defaults selected for the
+model and sampler. A Web UI recipe can supply its own defaults.
+
+- For EDM v-prediction checkpoints, the automatic scheduler is `exponential`.
+ Otherwise, the `lcm` and `tcd` samplers default to the `lcm` scheduler, and
+ `ddim_trailing` defaults to `simple`. Other samplers use the model's default
+ scheduler.
+- AYS has reference schedules for SD 1.x, SDXL, and SVD. It is not designed for
+ SD 2.x or other model families.
+- GITS requires at least two steps.
+- Model-specific schedules should follow the matching guide, such as
+ [FLUX.2](../models/flux2.md), [LTX-2](../models/ltx2.md),
+ [Ideogram4](../models/ideogram4.md), or [LLaDA-Image](../models/llada_image.md).
+- Some models use specialized sampling paths or schedules, such as
+ [SeFi-Image](../models/sefi_image.md). Changing a generic sampler or scheduler
+ option may not change that model's behavior.
+- For few-step checkpoints or adapters, keep the sampler, step count, guidance,
+ and schedule specified in the model guide. See [LCM/LCM-LoRA](../models/lcm.md)
+ for an example.
+
+## Custom sigma schedules
+
+`--sigmas` accepts comma-separated noise levels or one of the presets below.
+Supply descending values ending in zero when specifying your own schedule, for
+example `--sigmas "14.61,7.8,3.5,0.0"`. The values replace the generated schedule;
+the number of sampling steps becomes the number of values minus one.
+
+| Preset | Steps | Model guide |
+| --- | --- | --- |
+| `qwen-image-2.1-turbo` | 8 | [Qwen Image 2.1 Turbo](../models/qwen_image_2.1.md#turbo) |
+| `p-h3-image` | 8 | [P-H3-Image](../models/p_h3_image.md) |
+| `minimax-h3-image` | 6 | [MiniMax-H3-Image](../models/minimax_h3_image.md) |
+| `hyperflow-h3-flash-4` | 4 | [HyperFlow H3 Flash](../models/minimax_h3.md#hyperflow-h3-flash) |
+| `hyperflow-h3-flash-6` | 6 | [HyperFlow H3 Flash](../models/minimax_h3.md#hyperflow-h3-flash) |
+| `hyperflow-h3-flash-8` | 8 | [HyperFlow H3 Flash](../models/minimax_h3.md#hyperflow-h3-flash) |
+
+`--hires-sigmas` accepts the same format and presets for the highres fix second
+pass. Use each preset with the checkpoint and settings in its model guide.
diff --git a/docs/tokenizers.md b/docs/guides/tokenizers.md
similarity index 100%
rename from docs/tokenizers.md
rename to docs/guides/tokenizers.md
diff --git a/docs/models/README.md b/docs/models/README.md
new file mode 100644
index 0000000..0f33958
--- /dev/null
+++ b/docs/models/README.md
@@ -0,0 +1,85 @@
+# Model and component guides
+
+Each guide covers weights, setup, and runnable examples for a model or component.
+For shared generation options, device configuration, and troubleshooting, see the
+[documentation index](../README.md).
+
+## Image generation
+
+- [Anima](anima.md)
+- [Boogu Image](boogu_image.md)
+- [Chroma](chroma.md)
+- [Chroma1-Radiance](chroma_radiance.md)
+- [Distilled SD and SDXL models](distilled_sd.md)
+- [ERNIE-Image](ernie_image.md)
+- [Fibo 2.0](fibo2.md)
+- [FLUX.1](flux.md)
+- [FLUX.2](flux2.md)
+- [FLUX.3 Image](flux3.md)
+- [HiDream-O1-Image](hidream_o1_image.md)
+- [Ideogram4](ideogram4.md)
+- [Iris-3B](iris.md)
+- [Krea2](krea2.md)
+- [Lens](lens.md)
+- [LLaDA-Image](llada_image.md)
+- [LongCat Image](longcat_image.md)
+- [Mage-Flow](mage_flow.md)
+- [Ming-Image Design](ming_image.md)
+- [MiniMax-H3-Image](minimax_h3_image.md)
+- [MiniT2I](minit2i.md)
+- [MOSS-Image](moss_image.md)
+- [Ovis-Image](ovis_image.md)
+- [P-H3-Image](p_h3_image.md)
+- [PiD](pid.md)
+- [PixArt](pixart.md)
+- [Qwen Image](qwen_image.md)
+- [Qwen Image 2.1](qwen_image_2.1.md)
+- [SeFi-Image](sefi_image.md)
+- [SenseNova U1.5](sensenova_u1.md)
+- [Stable Diffusion 1.x, 2.x, and SDXL, including Turbo variants](sd.md)
+- [Stable Diffusion 3 / 3.5](sd3.md)
+- [Z-Image](z_image.md)
+- [Z-Image L2P](z_image_l2p.md)
+
+## Image editing
+
+See the [image editing guide](../guides/edit.md) for shared reference-image options
+and model presets. Models that support both generation and editing use the same
+model guide.
+
+- [Boogu Image Edit](boogu_image.md#boogu-image-edit)
+- [Fibo 2.0 Dev / Edit Turbo](fibo2.md#examples)
+- [FLUX.1-Kontext-dev](kontext.md)
+- [FLUX.2](flux2.md)
+- [FLUX.3 Image](flux3.md)
+- [LLaDA-Image editing](llada_image.md#image-editing)
+- [LongCat Image Edit](longcat_image.md)
+- [Mage-Flow-Edit](mage_flow.md#image-editing)
+- [MiniMax-H3-Image reference-image editing](minimax_h3_image.md#reference-image-editing)
+- [Qwen Image 2.1 editing](qwen_image_2.1.md#image-editing)
+- [Qwen Image Edit series](qwen_image_edit.md)
+
+## Video generation
+
+- [HunyuanVideo 1.5](hunyuan_video.md)
+- [LingBot-Video](lingbot_video.md)
+- [LTX-2.3 / LTX-2.5](ltx2.md)
+- [MiniMax-H3](minimax_h3.md)
+- [Wan2.1 / Wan2.2](wan.md)
+
+## Image and video super-resolution
+
+- [ESRGAN and MoSR](esrgan.md)
+- [RelayVSR](relay_vsr.md)
+- [SeedVR2](seedvr2.md)
+
+## LoRAs, adapters, and auxiliary models
+
+- [ADetailer](adetailer.md)
+- [AnimateDiff](animatediff.md)
+- [IP-Adapter](ip_adapter.md)
+- [LCM / LCM-LoRA](lcm.md)
+- [LoRA](lora.md)
+- [PhotoMaker](photo_maker.md)
+- [PuLID-Flux](pulid.md)
+- [TAESD and related tiny autoencoders](taesd.md)
diff --git a/docs/adetailer.md b/docs/models/adetailer.md
similarity index 100%
rename from docs/adetailer.md
rename to docs/models/adetailer.md
diff --git a/docs/anima.md b/docs/models/anima.md
similarity index 93%
rename from docs/anima.md
rename to docs/models/anima.md
index 18b9495..cebe378 100644
--- a/docs/anima.md
+++ b/docs/models/anima.md
@@ -18,4 +18,4 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\anima-preview.safetensors --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_3_06b_base.safetensors -p "a lovely cat holding a sign says 'anima.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu
```
-<img alt="anima image example" src="../assets/anima/example.png" />
+<img alt="anima image example" src="../../assets/anima/example.png" />
diff --git a/docs/animatediff.md b/docs/models/animatediff.md
similarity index 87%
rename from docs/animatediff.md
rename to docs/models/animatediff.md
index 80c46ae..2486fb4 100644
--- a/docs/animatediff.md
+++ b/docs/models/animatediff.md
@@ -97,19 +97,19 @@ AnimateDiff output style.
| Prompt | Sample |
|---------------------------------------|--------|
-| B&W man on stormy coastline | <img src="../assets/animatediff/v3_man.gif" width="256"/> |
-| Close-up rabbit macro shot | <img src="../assets/animatediff/v3_rabbit.gif" width="256"/> |
-| Coastline, storm, waves, lightning | <img src="../assets/animatediff/v3_coast.gif" width="256"/> |
-| Old house, storm, forest, night | <img src="../assets/animatediff/v3_house.gif" width="256"/> |
+| B&W man on stormy coastline | <img src="../../assets/animatediff/v3_man.gif" width="256"/> |
+| Close-up rabbit macro shot | <img src="../../assets/animatediff/v3_rabbit.gif" width="256"/> |
+| Coastline, storm, waves, lightning | <img src="../../assets/animatediff/v3_coast.gif" width="256"/> |
+| Old house, storm, forest, night | <img src="../../assets/animatediff/v3_house.gif" width="256"/> |
### v2 (384x384, `mm_sd_v15_v2.ckpt`)
| Prompt | Sample |
|---------------------------------------|--------|
-| B&W man on stormy coastline | <img src="../assets/animatediff/v2_man.gif" width="256"/> |
-| Close-up rabbit macro shot | <img src="../assets/animatediff/v2_rabbit.gif" width="256"/> |
-| Coastline, storm, waves, lightning | <img src="../assets/animatediff/v2_coast.gif" width="256"/> |
-| Old house, storm, forest, night | <img src="../assets/animatediff/v2_house.gif" width="256"/> |
+| B&W man on stormy coastline | <img src="../../assets/animatediff/v2_man.gif" width="256"/> |
+| Close-up rabbit macro shot | <img src="../../assets/animatediff/v2_rabbit.gif" width="256"/> |
+| Coastline, storm, waves, lightning | <img src="../../assets/animatediff/v2_coast.gif" width="256"/> |
+| Old house, storm, forest, night | <img src="../../assets/animatediff/v2_house.gif" width="256"/> |
Motion is strong for scenes with motion cues in the prompt (storm/waves/wind)
and subtle for static subjects (close-up macro), matching reference behavior.
@@ -122,7 +122,7 @@ Attaching the `v3_sd15_adapter` LoRA sharpens the base UNet output toward
the training distribution the motion module was fine-tuned against. Same
prompt, seed, config as above:
-<img src="../assets/animatediff/v3_rabbit_domain_lora.gif" width="256"/>
+<img src="../../assets/animatediff/v3_rabbit_domain_lora.gif" width="256"/>
Individual fur strands, glowing inner-ear, and richer forest detail become
visible compared to the no-LoRA rendering.
@@ -140,7 +140,7 @@ Pass a pre-rendered image via `-i / --init-img` to animate FROM it. All N output
Left: init image rendered with `-M img_gen`. Right: 8-frame vid_gen output.
-<img src="../assets/animatediff/img2video_demo.gif" width="512"/>
+<img src="../../assets/animatediff/img2video_demo.gif" width="512"/>
```
sd-cli -M img_gen ... -o init.png # any high-quality still
diff --git a/docs/boogu_image.md b/docs/models/boogu_image.md
similarity index 87%
rename from docs/boogu_image.md
rename to docs/models/boogu_image.md
index c5ad97d..2a54f4b 100644
--- a/docs/boogu_image.md
+++ b/docs/models/boogu_image.md
@@ -20,7 +20,7 @@ Boogu Image uses a Boogu diffusion transformer, the FLUX VAE, and Qwen3-VL as th
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\boogu_image_base_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --vae ..\models\vae\ae.sft -p "a lovely cat" -v --offload-to-cpu
```
-<img width="256" alt="Boogu Image Base example" src="../assets/boogu/example.png" />
+<img width="256" alt="Boogu Image Base example" src="../../assets/boogu/example.png" />
### Boogu Image Edit
@@ -28,4 +28,4 @@ Boogu Image uses a Boogu diffusion transformer, the FLUX VAE, and Qwen3-VL as th
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\boogu_image_edit_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\mmproj-Qwen3VL-8B-Instruct-F16.gguf --vae ..\models\vae\ae.sft -v --offload-to-cpu -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'boogu.cpp'"
```
-<img width="256" alt="Boogu Image Edit example" src="../assets/boogu/edit_example.png" />
\ No newline at end of file
+<img width="256" alt="Boogu Image Edit example" src="../../assets/boogu/edit_example.png" />
\ No newline at end of file
diff --git a/docs/chroma.md b/docs/models/chroma.md
similarity index 97%
rename from docs/chroma.md
rename to docs/models/chroma.md
index 606a85f..ccf63c6 100644
--- a/docs/chroma.md
+++ b/docs/models/chroma.md
@@ -27,6 +27,6 @@ For example:
.\bin\Release\sd-cli.exe --diffusion-model ..\models\chroma-unlocked-v40-q8_0.gguf --vae ..\models\ae.sft --t5xxl ..\models\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'chroma.cpp'" --cfg-scale 4.0 --sampling-method euler -v --model-args chroma_use_dit_mask=false --clip-on-cpu
```
-
+
diff --git a/docs/chroma_radiance.md b/docs/models/chroma_radiance.md
similarity index 89%
rename from docs/chroma_radiance.md
rename to docs/models/chroma_radiance.md
index fdd6d0a..892db78 100644
--- a/docs/chroma_radiance.md
+++ b/docs/models/chroma_radiance.md
@@ -15,7 +15,7 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Chroma1-Radiance-v0.4-Q8_0.gguf --t5xxl ..\models\clip\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'chroma radiance cpp'" --cfg-scale 4.0 --sampling-method euler -v
```
-<img alt="Chroma1-Radiance" src="../assets/flux/chroma1-radiance.png" />
+<img alt="Chroma1-Radiance" src="../../assets/flux/chroma1-radiance.png" />
diff --git a/docs/distilled_sd.md b/docs/models/distilled_sd.md
similarity index 100%
rename from docs/distilled_sd.md
rename to docs/models/distilled_sd.md
diff --git a/docs/ernie_image.md b/docs/models/ernie_image.md
similarity index 87%
rename from docs/ernie_image.md
rename to docs/models/ernie_image.md
index 3b1fc12..a12eb9a 100644
--- a/docs/ernie_image.md
+++ b/docs/models/ernie_image.md
@@ -24,7 +24,7 @@ You can run ERNIE-Image with stable-diffusion.cpp on GPUs with 4GB of VRAM — o
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\ernie-image-turbo.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\ministral-3-3b.safetensors -p "a lovely cat" --cfg-scale 1.0 --steps 8 -v --offload-to-cpu
```
-<img width="256" alt="ERNIE-Image Turbo example" src="../assets/ernie_image/turbo_example.png" />
+<img width="256" alt="ERNIE-Image Turbo example" src="../../assets/ernie_image/turbo_example.png" />
### ERNIE-Image
@@ -32,4 +32,4 @@ You can run ERNIE-Image with stable-diffusion.cpp on GPUs with 4GB of VRAM — o
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\ernie-image-UD-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\ministral-3-3b.safetensors -p "a lovely cat" --cfg-scale 5.0 -v --offload-to-cpu
```
-<img width="256" alt="ERNIE-Image example" src="../assets/ernie_image/example.png" />
+<img width="256" alt="ERNIE-Image example" src="../../assets/ernie_image/example.png" />
diff --git a/docs/esrgan.md b/docs/models/esrgan.md
similarity index 100%
rename from docs/esrgan.md
rename to docs/models/esrgan.md
diff --git a/docs/fibo2.md b/docs/models/fibo2.md
similarity index 91%
rename from docs/fibo2.md
rename to docs/models/fibo2.md
index 064d800..d440c95 100644
--- a/docs/fibo2.md
+++ b/docs/models/fibo2.md
@@ -16,7 +16,7 @@ Fibo 2.0 uses a Fibo diffusion transformer, the standard FLUX.2 VAE, and Qwen3-V
The original Diffusers weights from [briaai/Fibo-2.0-dev](https://huggingface.co/briaai/Fibo-2.0-dev) and [briaai/Fibo-2.0-edit-turbo](https://huggingface.co/briaai/Fibo-2.0-edit-turbo) are also supported. Pass the transformer's `diffusion_pytorch_model.safetensors.index.json` to `--diffusion-model` and keep its shards alongside it.
-INT8 convrot weights load directly; see [INT8 convrot](./int8_convrot.md) for backend requirements.
+INT8 convrot weights load directly; see [INT8 convrot](../guides/int8_convrot.md) for backend requirements.
## Examples
@@ -28,13 +28,13 @@ Dev supports both text-to-image generation and reference-image editing.
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\fibo2_dev_int8_convrot.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'fibo2.cpp'" --cfg-scale 5.0 --sampling-method euler -v --offload-to-cpu
```
-<img src="../assets/fibo2/t2i.png" />
+<img src="../../assets/fibo2/t2i.png" />
```
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\fibo2_dev_int8_convrot.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\flux2_ae.safetensors -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'fibo2.cpp'" --cfg-scale 5.0 --sampling-method euler -v --offload-to-cpu
```
-<img src="../assets/fibo2/dev_edit.png" />
+<img src="../../assets/fibo2/dev_edit.png" />
### Fibo 2.0 Edit Turbo
@@ -44,7 +44,7 @@ Edit Turbo is distilled for reference-image editing in 4 steps with CFG 1.
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\fibo2_edit_turbo_int8_convrot.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\flux2_ae.safetensors -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'fibo2.cpp'" --cfg-scale 1 --steps 4 --sampling-method euler -v --offload-to-cpu
```
-The BF16 files accept the same options. Use dimensions divisible by 16. Repeat `-r` to use multiple reference images; instructions can refer to `<image_1>`, `<image_2>`, etc. See [Image Editing](./edit.md) for reference-image preprocessing options. Separate GGUF text encoders need their vision projector passed with `--llm_vision` for editing.
+The BF16 files accept the same options. Use dimensions divisible by 16. Repeat `-r` to use multiple reference images; instructions can refer to `<image_1>`, `<image_2>`, etc. See [Image Editing](../guides/edit.md) for reference-image preprocessing options. Separate GGUF text encoders need their vision projector passed with `--llm_vision` for editing.
The automatic `fibo2` reference preset combines `resize_single_ref_to_target=true`, `vae_size_buckets=true`, `vae_center_crop=true`, and `vlm_use_vae_input=true`. A single reference is scaled to cover the output dimensions and center-cropped. Multiple references use dimensions divisible by 16, chosen within ±10% of one megapixel to minimize cropping for each image's aspect ratio; `vae_input_max_pixels` overrides that target area. The VAE and vision encoder receive the same crops, with smaller copies used by the vision encoder. These are generic reference-image options and can be overridden individually: for example, `--ref-image-args vae_center_crop=false` uses direct resizing, while `resize_before_vae=false` skips this automatic crop and resize step entirely.
diff --git a/docs/flux.md b/docs/models/flux.md
similarity index 90%
rename from docs/flux.md
rename to docs/models/flux.md
index 6c61600..96267f5 100644
--- a/docs/flux.md
+++ b/docs/models/flux.md
@@ -36,7 +36,7 @@ Using formats of different precisions will yield results of varying quality.
| Type | q8_0 | q4_0 | q4_k | q3_k | q2_k |
|---- | ---- |---- |---- |---- |---- |
| **Memory** | 12068.09 MB | 6394.53 MB | 6395.17 MB | 4888.16 MB | 3735.73 MB |
-| **Result** |  | | | ||
+| **Result** |  | | | ||
@@ -49,7 +49,7 @@ Using formats of different precisions will yield results of varying quality.
| q8_0 |
| ---- |
-| |
+| |
## Run with LoRA
@@ -63,4 +63,4 @@ Since many flux LoRA training libraries have used various LoRA naming formats, i
.\bin\Release\sd-cli.exe --diffusion-model ..\models\flux1-dev-q8_0.gguf --vae ...\models\ae.sft --clip_l ..\models\clip_l.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -p "a lovely cat holding a sign says 'flux.cpp'<lora:realism_lora_comfy_converted:1>" --cfg-scale 1.0 --sampling-method euler -v --lora-model-dir ../models --clip-on-cpu
```
-
+
diff --git a/docs/flux2.md b/docs/models/flux2.md
similarity index 88%
rename from docs/flux2.md
rename to docs/models/flux2.md
index 53fc8be..6838c19 100644
--- a/docs/flux2.md
+++ b/docs/models/flux2.md
@@ -19,7 +19,7 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux2-dev-Q4_K_S.gguf --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\Mistral-Small-3.2-24B-Instruct-2506-Q4_K_M.gguf -r .\kontext_input.png -p "change 'flux.cpp' to 'flux2-dev.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu
```
-<img alt="flux2 example" src="../assets/flux2/example.png" />
+<img alt="flux2 example" src="../../assets/flux2/example.png" />
## Flux.2 klein 4B / Flux.2 klein base 4B
@@ -45,19 +45,19 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-4b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "a lovely cat" --cfg-scale 1.0 --steps 4 -v --offload-to-cpu
```
-<img alt="flux2-klein-4b" src="../assets/flux2/flux2-klein-4b.png" />
+<img alt="flux2-klein-4b" src="../../assets/flux2/flux2-klein-4b.png" />
```
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-4b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -r .\kontext_input.png -p "change 'flux.cpp' to 'klein.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu --steps 4
```
-<img alt="flux2-klein-4b-edit" src="../assets/flux2/flux2-klein-4b-edit.png" />
+<img alt="flux2-klein-4b-edit" src="../../assets/flux2/flux2-klein-4b-edit.png" />
```
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-base-4b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "a lovely cat" --cfg-scale 4.0 --steps 20 -v --offload-to-cpu
```
-<img alt="flux2-klein-base-4b" src="../assets/flux2/flux2-klein-base-4b.png" />
+<img alt="flux2-klein-base-4b" src="../../assets/flux2/flux2-klein-base-4b.png" />
## Flux.2 klein 9B / Flux.2 klein base 9B
@@ -81,16 +81,16 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-9b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_8b.safetensors -p "a lovely cat" --cfg-scale 1.0 --steps 4 -v --offload-to-cpu
```
-<img alt="flux2-klein-9b" src="../assets/flux2/flux2-klein-9b.png" />
+<img alt="flux2-klein-9b" src="../../assets/flux2/flux2-klein-9b.png" />
```
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-9b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_8b.safetensors -r .\kontext_input.png -p "change 'flux.cpp' to 'klein.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu --steps 4
```
-<img alt="flux2-klein-9b-edit" src="../assets/flux2/flux2-klein-9b-edit.png" />
+<img alt="flux2-klein-9b-edit" src="../../assets/flux2/flux2-klein-9b-edit.png" />
```
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-2-klein-base-9b.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\qwen_3_8b.safetensors -p "a lovely cat" --cfg-scale 4.0 --steps 20 -v --offload-to-cpu
```
-<img alt="flux2-klein-base-9b" src="../assets/flux2/flux2-klein-base-9b.png" />
\ No newline at end of file
+<img alt="flux2-klein-base-9b" src="../../assets/flux2/flux2-klein-base-9b.png" />
\ No newline at end of file
diff --git a/docs/flux3.md b/docs/models/flux3.md
similarity index 90%
rename from docs/flux3.md
rename to docs/models/flux3.md
index 8bc0b2e..f4986bb 100644
--- a/docs/flux3.md
+++ b/docs/models/flux3.md
@@ -29,15 +29,15 @@ The distilled model uses 16 steps and CFG 1.0.
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'flux3.cpp'" --cfg-scale 1.0 --steps 16 --sampling-method euler -v --offload-to-cpu
```
-<img src="../assets/flux3/flux3-image-klein.png" />
+<img src="../../assets/flux3/flux3-image-klein.png" />
```
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein.safetensors --vae ..\models\vae\flux2_ae.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'flux3-image-klein.cpp'" --cfg-scale 1.0 --sampling-method euler -v --offload-to-cpu --steps 16
```
-<img src="../assets/flux3/flux3-image-klein-edit.png" />
+<img src="../../assets/flux3/flux3-image-klein-edit.png" />
-Repeat `-r` to use multiple reference images, up to 10. See [Image Editing](./edit.md) for reference-image preprocessing options.
+Repeat `-r` to use multiple reference images, up to 10. See [Image Editing](../guides/edit.md) for reference-image preprocessing options.
### FLUX.3 Image Klein Base
@@ -45,6 +45,6 @@ Repeat `-r` to use multiple reference images, up to 10. See [Image Editing](./ed
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\flux-3-image-klein-base.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p "a lovely cat holding a sign says 'flux3.cpp'" --cfg-scale 3.5 --steps 20 --sampling-method euler -v --offload-to-cpu
```
-<img src="../assets/flux3/flux3-image-klein-base.png" />
+<img src="../../assets/flux3/flux3-image-klein-base.png" />
The default discrete scheduler uses the upstream time shift of 6.93 for both models. Use `--flow-shift` to override it.
diff --git a/docs/hidream_o1_image.md b/docs/models/hidream_o1_image.md
similarity index 83%
rename from docs/hidream_o1_image.md
rename to docs/models/hidream_o1_image.md
index 5291642..2fc29e3 100644
--- a/docs/hidream_o1_image.md
+++ b/docs/models/hidream_o1_image.md
@@ -16,5 +16,5 @@
'hidream o1 cpp'" --cfg-scale 1.0 -v -H 1024 -W 1024
```
-<img width="256" alt="HiDream-O1-Image-Dev example" src="../assets/hidream-o1/dev_example.png" />
+<img width="256" alt="HiDream-O1-Image-Dev example" src="../../assets/hidream-o1/dev_example.png" />
diff --git a/docs/hunyuan_video.md b/docs/models/hunyuan_video.md
similarity index 92%
rename from docs/hunyuan_video.md
rename to docs/models/hunyuan_video.md
index fadb884..cee2a2a 100644
--- a/docs/hunyuan_video.md
+++ b/docs/models/hunyuan_video.md
@@ -21,4 +21,4 @@ and ByT5 Small GlyphXL for glyph-aware text conditioning.
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\hunyuanvideo1.5_720p_t2v_fp16.safetensors --vae ..\models\vae\hunyuanvideo15_vae_fp16.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --t5xxl ..\models\text_encoders\byt5_small_glyphxl_fp16.safetensors -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -W 1280 -H 720 --offload-to-cpu --video-frames 33 --vae-tiling
```
-<video src=../assets/hunyuan_video/hy1.5_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
\ No newline at end of file
+<video src=../../assets/hunyuan_video/hy1.5_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
\ No newline at end of file
diff --git a/docs/ideogram4.md b/docs/models/ideogram4.md
similarity index 98%
rename from docs/ideogram4.md
rename to docs/models/ideogram4.md
index f0f1dd2..61c09f4 100644
--- a/docs/ideogram4.md
+++ b/docs/models/ideogram4.md
@@ -52,4 +52,4 @@ If you want lower VRAM usage, you can change the quantization from q8_0 to a low
.\bin\Release\sd-cli.exe --diffusion-model ideogram4-Q8_0.gguf --uncond-diffusion-model ideogram4_uncond-Q8_0.gguf --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors -p '{"high_level_description":"A square 1024 x 1024 luxury fashion magazine cover featuring exactly one short chubby fluffy cat as the main model. The cat sits on a soft ivory studio floor, facing the viewer with a stylish calm expression, wearing tiny black sunglasses, a red silk scarf, and a small gold collar charm. In front of the cat on the floor is a wide horizontal luxury nameplate that clearly reads ideogram4.cpp. The whole design feels premium, fashionable, clean, and editorial.","style_description":{"aesthetics":"luxury fashion magazine cover, high-end pet couture campaign, minimalist editorial design, elegant studio photography, soft paper texture, refined typography, fashionable and polished","lighting":"Soft diffused studio lighting, gentle spotlight on the cat, subtle floor shadow, warm ivory highlights, clean separation between subject and background","photo":"high-resolution fashion editorial photography look, front-facing cat portrait, crisp fur details, glossy sunglasses, clear readable nameplate text, shallow depth of field","medium":"mixed media fashion photography and premium editorial graphic design","color_palette":["#F4EFE7","#111111","#D8B56D","#B73A3A","#FFFFFF","#8A7A6A"]},"compositional_deconstruction":{"canvas":"Square 1024 x 1024 canvas with a normal upright orientation. Do not rotate the poster or any text. Use a clean fashion magazine cover layout.","background":"Warm ivory studio backdrop with subtle paper grain, a soft spotlight gradient, faint floor shadow, and a few minimal gold editorial lines. The background is spacious, premium, and uncluttered.","layout":"Top center has a small elegant headline. Center area features one cat as the main fashion model. Lower foreground has a wide horizontal luxury nameplate placed on the floor in front of the cat. Bottom center has a small footer. All text is horizontal, upright, and readable left to right.","elements":[{"type":"text","desc":"Top center headline reading LOOK WHAT I FOUND in a refined high-fashion serif font. The headline is horizontal, centered, elegant, and secondary to the nameplate text."},{"type":"obj","desc":"Exactly one short chubby fluffy cat sitting in the center like a luxury fashion model. The cat has a large round head, compact body, short legs, soft detailed fur, expressive eyes, and a calm confident pose. The cat is cute and rounded, not tall, not stretched, not duplicated."},{"type":"obj","desc":"Tiny glossy black sunglasses worn naturally by the cat, slightly oversized but still showing the cat face clearly. The sunglasses add a chic fashion-editorial attitude."},{"type":"obj","desc":"A red silk scarf tied neatly around the cat neck, with soft folds and a couture feeling. The scarf must not cover the cat face or the nameplate."},{"type":"obj","desc":"A small gold collar charm or fashion accessory under the scarf, subtle and premium, adding a luxury campaign detail."},{"type":"obj","desc":"In the lower foreground, place a wide horizontal luxury nameplate on the floor in front of the cat. The nameplate is low, flat, landscape-oriented, much wider than tall, like a fashion show seat card or premium display plaque. It is centered, front-facing, level, and fully visible. It must not become vertical, tall, standing, rotated, or side-facing."},{"type":"text","desc":"Print the exact text ideogram4.cpp only on the wide horizontal nameplate. Use clean bold black lettering, perfectly spelled, lowercase, with the number 4 and .cpp extension. The text must fit completely inside the nameplate, stay horizontal, and be readable from left to right."},{"type":"obj","desc":"Add sparse premium editorial accents around the edges: thin gold lines, small code brackets, tiny cursor marks, subtle dots, and minimal geometric details. No extra cats, no stickers, no animal faces, no busy decorations."},{"type":"text","desc":"Bottom center footer reading tiny paws, big compile energy in a small refined monospace or editorial font. The footer is horizontal, centered, understated, and much smaller than the nameplate text."}]}}' -v --offload-to-cpu -H 1024 -W 1024
```
-<img alt="ideogram4 image example" src="../assets/ideogram4/example.png" />
+<img alt="ideogram4 image example" src="../../assets/ideogram4/example.png" />
diff --git a/docs/ip_adapter.md b/docs/models/ip_adapter.md
similarity index 100%
rename from docs/ip_adapter.md
rename to docs/models/ip_adapter.md
diff --git a/docs/iris.md b/docs/models/iris.md
similarity index 92%
rename from docs/iris.md
rename to docs/models/iris.md
index 322a3da..c279a13 100644
--- a/docs/iris.md
+++ b/docs/models/iris.md
@@ -16,7 +16,7 @@ Iris-3B generates images directly in pixel space and uses Qwen3-VL-4B-Instruct a
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\iris-3b.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf -p "a lovely cat" --cfg-scale 3 -H 1024 -W 1024
```
-<img width="256" alt="iris-3b example" src="../assets/iris/example.png" />
+<img width="256" alt="iris-3b example" src="../../assets/iris/example.png" />
## Notes
diff --git a/docs/kontext.md b/docs/models/kontext.md
similarity index 92%
rename from docs/kontext.md
rename to docs/models/kontext.md
index 46da3c3..d150b13 100644
--- a/docs/kontext.md
+++ b/docs/models/kontext.md
@@ -33,7 +33,7 @@ For example:
| ref_image | prompt | output |
| ---- | ---- |---- |
-|  | change 'flux.cpp' to 'kontext.cpp' | |
+|  | change 'flux.cpp' to 'kontext.cpp' | |
diff --git a/docs/krea2.md b/docs/models/krea2.md
similarity index 93%
rename from docs/krea2.md
rename to docs/models/krea2.md
index 67fad02..b49fc67 100644
--- a/docs/krea2.md
+++ b/docs/models/krea2.md
@@ -24,4 +24,4 @@ Krea2 uses a Krea2 diffusion transformer, the Wan2.1 VAE, and Qwen3-VL 4B as the
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Krea-2-Raw-Q8_0.gguf --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\wan_2.1_vae.safetensors -p "a lovely cat holding a sign says 'krea2.cpp'" -v --offload-to-cpu
```
-<img width="256" alt="Krea2 Raw example" src="../assets/krea2/example.png" />
+<img width="256" alt="Krea2 Raw example" src="../../assets/krea2/example.png" />
diff --git a/docs/lcm.md b/docs/models/lcm.md
similarity index 90%
rename from docs/lcm.md
rename to docs/models/lcm.md
index 3a11938..f12fa5b 100644
--- a/docs/lcm.md
+++ b/docs/models/lcm.md
@@ -12,4 +12,4 @@ Here's a simple example:
| without LCM-LoRA (--cfg-scale 7) | with LCM-LoRA (--cfg-scale 1) |
| ---- |---- |
-|  | |
\ No newline at end of file
+|  | |
\ No newline at end of file
diff --git a/docs/lens.md b/docs/models/lens.md
similarity index 88%
rename from docs/lens.md
rename to docs/models/lens.md
index 09e9575..c7aac77 100644
--- a/docs/lens.md
+++ b/docs/models/lens.md
@@ -15,7 +15,7 @@ Lens uses a Lens diffusion transformer, the FLUX.2 VAE, and GPT-OSS-20B as the L
- Download GPT-OSS-20B tokenizer.json
- https://huggingface.co/openai/gpt-oss-20b/tree/main
-Lens and Lens Turbo require an external GPT-OSS `tokenizer.json` matching the text encoder checkpoint. Save it as `tokenizer_gpt_oss.json` and pass it with `--tokenizer`; the tokenizer is not embedded in sd.cpp. See [JSON tokenizers](tokenizers.md) for CLI and C API usage.
+Lens and Lens Turbo require an external GPT-OSS `tokenizer.json` matching the text encoder checkpoint. Save it as `tokenizer_gpt_oss.json` and pass it with `--tokenizer`; the tokenizer is not embedded in sd.cpp. See [JSON tokenizers](../guides/tokenizers.md) for CLI and C API usage.
## Examples
@@ -25,7 +25,7 @@ Lens and Lens Turbo require an external GPT-OSS `tokenizer.json` matching the te
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\lens_bf16.safetensors --llm "..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf" --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json --vae ..\models\vae\flux2_ae.safetensors --cfg-scale 5.0 -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" -v
```
-<img width="256" alt="Lens example" src="../assets/lens/example.png" />
+<img width="256" alt="Lens example" src="../../assets/lens/example.png" />
### Lens Turbo
@@ -33,4 +33,4 @@ Lens and Lens Turbo require an external GPT-OSS `tokenizer.json` matching the te
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\lens_turbo_bf16.safetensors --llm "..\models\text_encoders\gpt-oss-20b-UD-Q8_K_XL.gguf" --tokenizer ..\models\tokenizers\tokenizer_gpt_oss.json --vae ..\models\vae\flux2_ae.safetensors --cfg-scale 1.0 -p "A crystal dragon soaring through an aurora borealis sky, its entire body made of transparent faceted crystal refracting the green and purple aurora light into rainbow spectra, ice particles trailing from its wings, high fantasy digital art" -v --steps 4
```
-<img width="256" alt="Lens Turbo example" src="../assets/lens/turbo_example.png" />
+<img width="256" alt="Lens Turbo example" src="../../assets/lens/turbo_example.png" />
diff --git a/docs/lingbot_video.md b/docs/models/lingbot_video.md
similarity index 100%
rename from docs/lingbot_video.md
rename to docs/models/lingbot_video.md
diff --git a/docs/llada_image.md b/docs/models/llada_image.md
similarity index 94%
rename from docs/llada_image.md
rename to docs/models/llada_image.md
index d939e78..94cb5c8 100644
--- a/docs/llada_image.md
+++ b/docs/models/llada_image.md
@@ -17,7 +17,7 @@ than a clean error, so keep each checkpoint's files together.
Both need an external LLaDA2 `tokenizer.json`, which is not embedded in sd.cpp and is the same
file for either checkpoint. Take `tokenizer/tokenizer.json` from either repository and pass it
-with `--tokenizer`. See [JSON tokenizers](tokenizers.md) for CLI and C API usage.
+with `--tokenizer`. See [JSON tokenizers](../guides/tokenizers.md) for CLI and C API usage.
### LLaDA-Image-Turbo (4 steps)
@@ -105,7 +105,7 @@ save_file(merged, "llada_connectors.safetensors")
--output output.png
```
-<img width="256" alt="LLaDA-Image example" src="../assets/llada_image/example.png" />
+<img width="256" alt="LLaDA-Image example" src="../../assets/llada_image/example.png" />
### Image editing
@@ -125,9 +125,9 @@ save_file(merged, "llada_connectors.safetensors")
--output output.png
```
-<img width="256" alt="LLaDA-Image edit example" src="../assets/llada_image/edit_example.png" />
+<img width="256" alt="LLaDA-Image edit example" src="../../assets/llada_image/edit_example.png" />
-See [edit.md](./edit.md) for the shared reference-image options. LLaDA-Image uses the
+See [edit.md](../guides/edit.md) for the shared reference-image options. LLaDA-Image uses the
`llada_image` preset by default, resizing the reference image to the output width and height
before VAE encoding. SigVQ uses bilinear resizing to half the output resolution and inputs
normalized to `[-1, 1]`. CFG keeps the source latent in both branches and uses SigVQ features
diff --git a/docs/longcat_image.md b/docs/models/longcat_image.md
similarity index 95%
rename from docs/longcat_image.md
rename to docs/models/longcat_image.md
index ae730b4..fa70c08 100644
--- a/docs/longcat_image.md
+++ b/docs/models/longcat_image.md
@@ -27,4 +27,4 @@ LongCat uses quoted text for character-level text rendering. Put target text ins
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\LongCat-Image-Q4_K_M.gguf --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf -p "a lovely cat holding a sign says 'longcat.cpp'" --cfg-scale 5.0 --sampling-method euler --flow-shift 3 -v --offload-to-cpu
```
-<img alt="longcat example" src="../assets/longcat/example.png" />
+<img alt="longcat example" src="../../assets/longcat/example.png" />
diff --git a/docs/lora.md b/docs/models/lora.md
similarity index 100%
rename from docs/lora.md
rename to docs/models/lora.md
diff --git a/docs/ltx2.md b/docs/models/ltx2.md
similarity index 98%
rename from docs/ltx2.md
rename to docs/models/ltx2.md
index e42698f..10cd8ad 100644
--- a/docs/ltx2.md
+++ b/docs/models/ltx2.md
@@ -59,7 +59,7 @@ To run the text encoder quantized, convert it once with sd-cli:
```
<video
- src="../assets/ltx2/t2v.webm"
+ src="../../assets/ltx2/t2v.webm"
controls
muted
style="max-width: 100%; height: auto;"></video>
@@ -71,7 +71,7 @@ To run the text encoder quantized, convert it once with sd-cli:
```
<video
- src="../assets/ltx2/i2v.webm"
+ src="../../assets/ltx2/i2v.webm"
controls
muted
style="max-width: 100%; height: auto;"></video>
@@ -83,7 +83,7 @@ To run the text encoder quantized, convert it once with sd-cli:
```
<video
- src="../assets/ltx2/flf2v.webm"
+ src="../../assets/ltx2/flf2v.webm"
controls
muted
style="max-width: 100%; height: auto;"></video>
@@ -105,7 +105,7 @@ By default, the hires refine pass uses the main sampler and scheduler, then trim
```
<video
- src="../assets/ltx2/hires_i2v.webm"
+ src="../../assets/ltx2/hires_i2v.webm"
controls
muted
style="max-width: 100%; height: auto;"></video>
diff --git a/docs/mage_flow.md b/docs/models/mage_flow.md
similarity index 91%
rename from docs/mage_flow.md
rename to docs/models/mage_flow.md
index 0adef4a..5948f93 100644
--- a/docs/mage_flow.md
+++ b/docs/models/mage_flow.md
@@ -18,7 +18,7 @@ Use 30 steps for Base models and 4 steps with `--cfg-scale 1` for Turbo models.
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Mage-Flow-Turbo.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --vae ..\models\vae\mage_vae.safetensors -p "a lovely cat holding a sign says 'mage.cpp'" --cfg-scale 1.0 --steps 4 -v --offload-to-cpu
```
-<img width="256" alt="Mage-Flow example" src="../assets/mage_flow/example.png" />
+<img width="256" alt="Mage-Flow example" src="../../assets/mage_flow/example.png" />
## Image editing
@@ -30,4 +30,4 @@ For the Turbo edit checkpoint, use 4 steps and `--cfg-scale 1`.
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Mage-Flow-Edit.safetensors --llm ..\models\text_encoders\Qwen3-VL-4B-Instruct-Q4_K_M.gguf --llm_vision ..\models\text_encoders\Qwen3-VL-4B-Instruct-mmproj-BF16.gguf --vae ..\models\vae\mage_vae.safetensors -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'mage.cpp'" --cfg-scale 4.0 --sampling-method euler -v --offload-to-cpu
```
-<img width="256" alt="Mage-Flow-Edit example" src="../assets/mage_flow/edit_example.png" />
+<img width="256" alt="Mage-Flow-Edit example" src="../../assets/mage_flow/edit_example.png" />
diff --git a/docs/ming_image.md b/docs/models/ming_image.md
similarity index 94%
rename from docs/ming_image.md
rename to docs/models/ming_image.md
index c242559..8f48135 100644
--- a/docs/ming_image.md
+++ b/docs/models/ming_image.md
@@ -13,7 +13,7 @@
- Download Ling tokenizer
- tokenizer.json: https://huggingface.co/inclusionAI/Ming-Image-0.1-Design/blob/main/mllm/tokenizer.json
-The example below uses `ming_image_0.1_design_bf16.safetensors` for the DiT. You can also use `ming_image_0.1_design_int8_convrot.safetensors` with [INT8 convrot support](int8_convrot.md). Use the BF16 text encoder.
+The example below uses `ming_image_0.1_design_bf16.safetensors` for the DiT. You can also use `ming_image_0.1_design_int8_convrot.safetensors` with [INT8 convrot support](../guides/int8_convrot.md). Use the BF16 text encoder.
## Text-to-image
diff --git a/docs/minimax_h3.md b/docs/models/minimax_h3.md
similarity index 97%
rename from docs/minimax_h3.md
rename to docs/models/minimax_h3.md
index 8f1444d..40f3800 100644
--- a/docs/minimax_h3.md
+++ b/docs/models/minimax_h3.md
@@ -62,7 +62,7 @@ are detected from their weights.
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "A cute American Shorthair silver tabby kitten surfs on a tropical ocean wave, riding a white surfboard with the clear text 'sd.cpp' on it. Cinematic tracking shot, realistic water, bright sunlight, smooth motion, and consistent character appearance. Add upbeat tropical surf-rock background music with cheerful drums and guitar, synchronized with the kitten’s energetic surfing." --cfg-scale 1.0 -v -W 864 -H 480 --offload-to-cpu --rng cpu --fps 24 --video-frames 56
```
-<video src=../assets/minimax-h3/t2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/minimax-h3/t2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
Omitting `--audio-vae` still runs the joint diffusion model but produces video without a
decoded audio track.
@@ -75,7 +75,7 @@ Add `--init-img` for I2VA, or both `--init-img` and `--end-img` for FL2VA:
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_fl2va-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "a lovely cat" -i ..\assets\ernie_image\turbo_example.png --cfg-scale 1.0 -v -W 864 -H 480 --offload-to-cpu --rng cpu --fps 24 --video-frames 56
```
-<video src=../assets/minimax-h3/i2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/minimax-h3/i2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
## Reference-to-audio-video conditioning
@@ -86,7 +86,7 @@ video soundtracks, and standalone audio references:
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\minimax_h3_ref2va_pruned-Q4_K_M.gguf --vae ..\models\vae\minimax_h3_video_vae_fp16.safetensors --audio-vae ..\models\vae\minimax_h3_audio_vae_fp32.safetensors --llm ..\models\text_encoders\qwen3vl_32b_minimax_h3-Q4_K_M.gguf -p "Use the cat from <Picture 1> as the main character. Keep the cat’s appearance, fur color, facial features, and identity consistent with the reference image. Create a 2-second cinematic video: start with an extreme close-up shot of the cat’s face, focusing on its cute expression and detailed fur texture. The camera slowly rotates around the cat’s head, creating a dynamic reveal. Then smoothly pull back and zoom out to reveal the full scene: the cat is standing confidently on a surfboard, riding ocean waves. Water splashes around the board, sea breeze gently moves the cat’s fur, and the cat maintains a cute and fearless expression while surfing. Smooth camera movement, cinematic orbit shot, seamless zoom-out transition, low-angle wide shot, realistic ocean environment, golden sunlight, dynamic waves, high-quality realistic style, natural motion, no distortion, keep the cat’s identity unchanged." -r ..\assets\ernie_image\turbo_example.png --cfg-scale 1.0 -v -W 864 -H 480 --offload-to-cpu --rng cpu --fps 24 --video-frames 56
```
-<video src=../assets/minimax-h3/r2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/minimax-h3/r2av.mp4 controls="controls" muted="muted" type="video/mp4"></video>
`--ref-image`, `--ref-video`, and `--ref-audio` can each be repeated. A
reference video is a directory of image frames sorted lexicographically and is
diff --git a/docs/minimax_h3_image.md b/docs/models/minimax_h3_image.md
similarity index 100%
rename from docs/minimax_h3_image.md
rename to docs/models/minimax_h3_image.md
diff --git a/docs/minit2i.md b/docs/models/minit2i.md
similarity index 100%
rename from docs/minit2i.md
rename to docs/models/minit2i.md
diff --git a/docs/moss_image.md b/docs/models/moss_image.md
similarity index 97%
rename from docs/moss_image.md
rename to docs/models/moss_image.md
index 27ab26f..67e7964 100644
--- a/docs/moss_image.md
+++ b/docs/models/moss_image.md
@@ -32,6 +32,6 @@ Pass the external `tokenizer.json` with `--tokenizer`; Qwen3.5 uses a different
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\moss_image_sft_int8_convrot_attn.safetensors --llm ..\models\text_encoders\Qwen3.5-9B-Q4_K_M.gguf --vae ..\models\vae\flux2_ae.safetensors --tokenizer ..\models\tokenizers\tokenizer_qwen3.5.json --cfg-scale 3.0 -p "a lovely cat holding a sign says 'moss-image.cpp'" -v --offload-to-cpu -H 1024 -W 1024
```
-<img src="../assets/moss/sft.png" />
+<img src="../../assets/moss/sft.png" />
Use dimensions divisible by 16. The default discrete scheduler uses the upstream time shift of 5. Use `--flow-shift` to override it. The negative CFG branch skips DiT layer 22 (zero-based), matching the upstream pipeline.
diff --git a/docs/ovis_image.md b/docs/models/ovis_image.md
similarity index 89%
rename from docs/ovis_image.md
rename to docs/models/ovis_image.md
index c561ff5..fefb835 100644
--- a/docs/ovis_image.md
+++ b/docs/models/ovis_image.md
@@ -16,4 +16,4 @@
.\bin\Release\sd-cli.exe --diffusion-model ovis_image-Q4_0.gguf --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\ovis_2.5.safetensors -p "a lovely cat" --cfg-scale 5.0 -v --offload-to-cpu
```
-<img alt="ovis image example" src="../assets/ovis_image/example.png" />
\ No newline at end of file
+<img alt="ovis image example" src="../../assets/ovis_image/example.png" />
\ No newline at end of file
diff --git a/docs/p_h3_image.md b/docs/models/p_h3_image.md
similarity index 100%
rename from docs/p_h3_image.md
rename to docs/models/p_h3_image.md
diff --git a/docs/photo_maker.md b/docs/models/photo_maker.md
similarity index 100%
rename from docs/photo_maker.md
rename to docs/models/photo_maker.md
diff --git a/docs/pid.md b/docs/models/pid.md
similarity index 89%
rename from docs/pid.md
rename to docs/models/pid.md
index 3737f32..26cec92 100644
--- a/docs/pid.md
+++ b/docs/models/pid.md
@@ -22,7 +22,7 @@ In stable-diffusion.cpp, PiD currently runs as an image edit pipeline: provide a
The official PiD model card should be checked before use. At the time of the initial PiD release, the official weights are under the NSCLv1 non-commercial license.
-PiD and PiD 1.5 require an external Gemma 2 `tokenizer.json` matching the text encoder checkpoint. Save it as `tokenizer_gemma2.json` and pass it with `--tokenizer`; the tokenizer is not embedded in sd.cpp. See [JSON tokenizers](tokenizers.md) for CLI and C API usage.
+PiD and PiD 1.5 require an external Gemma 2 `tokenizer.json` matching the text encoder checkpoint. Save it as `tokenizer_gemma2.json` and pass it with `--tokenizer`; the tokenizer is not embedded in sd.cpp. See [JSON tokenizers](../guides/tokenizers.md) for CLI and C API usage.
## Examples
@@ -32,10 +32,10 @@ PiD and PiD 1.5 require an external Gemma 2 `tokenizer.json` matching the text e
Before:
-<img width="256" alt="ERNIE-Image Turbo example" src="../assets/ernie_image/turbo_example.png" />
+<img width="256" alt="ERNIE-Image Turbo example" src="../../assets/ernie_image/turbo_example.png" />
After:
-<img width="1024" alt="PiD example" src="../assets/pid/example.png" />
+<img width="1024" alt="PiD example" src="../../assets/pid/example.png" />
## Notes
diff --git a/docs/pixart.md b/docs/models/pixart.md
similarity index 100%
rename from docs/pixart.md
rename to docs/models/pixart.md
diff --git a/docs/pulid.md b/docs/models/pulid.md
similarity index 98%
rename from docs/pulid.md
rename to docs/models/pulid.md
index 429c7fc..469a273 100644
--- a/docs/pulid.md
+++ b/docs/models/pulid.md
@@ -33,7 +33,7 @@ Each cross-attention layer takes the current image tokens as query, the
Three files in addition to the standard Flux weight set:
1. **Flux base** (transformer + VAE + clip_l + t5xxl) -- exactly as
- [docs/flux.md](flux.md) describes.
+ [FLUX.1 guide](flux.md) describes.
2. **PuLID weights** -- download from
[guozinan/PuLID](https://huggingface.co/guozinan/PuLID):
- `pulid_flux_v0.9.0.safetensors` or `pulid_flux_v0.9.1.safetensors`
@@ -52,7 +52,7 @@ to a `.pulidembd` binary file (about 131 KB). Run it once per source
person; the same file is reused for any number of generations.
A reference Python script is provided alongside this docs file at
-[`scripts/pulid_extract_id.py`](../scripts/pulid_extract_id.py). It
+[`scripts/pulid_extract_id.py`](../../scripts/pulid_extract_id.py). It
requires:
- A working CUDA / CPU PyTorch stack
- `insightface`, `facexlib`, `eva-clip`, `torchvision`, `opencv-python`,
diff --git a/docs/qwen_image.md b/docs/models/qwen_image.md
similarity index 95%
rename from docs/qwen_image.md
rename to docs/models/qwen_image.md
index 00ee50e..0fd1fa2 100644
--- a/docs/qwen_image.md
+++ b/docs/models/qwen_image.md
@@ -17,7 +17,7 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen-image-Q8_0.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf -p '一个穿着"QWEN"标志的T恤的中国美女正拿着黑色的马克笔面相镜头微笑。她身后的玻璃板上手写体写着 “一、Qwen-Image的技术路线： 探索视觉生成基础模型的极限，开创理解与生成一体化的未来。二、Qwen-Image的模型特色：1、复杂文字渲染。支持中英渲染、自动布局； 2、精准图像编辑。支持文字编辑、物体增减、风格变换。三、Qwen-Image的未来愿景：赋能专业内容创作、助力生成式AI发展。”' --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu -H 1024 -W 1024 --flow-shift 3
```
-<img alt="qwen example" src="../assets/qwen/example.png" />
+<img alt="qwen example" src="../../assets/qwen/example.png" />
diff --git a/docs/qwen_image_2.1.md b/docs/models/qwen_image_2.1.md
similarity index 90%
rename from docs/qwen_image_2.1.md
rename to docs/models/qwen_image_2.1.md
index 8663731..d708ae8 100644
--- a/docs/qwen_image_2.1.md
+++ b/docs/models/qwen_image_2.1.md
@@ -28,7 +28,7 @@ Run the following commands from the build directory. Use image dimensions divisi
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen_image_2.1_int8_convrot.safetensors --vae ..\models\vae\qwen_image_2.1_vae_bf16.safetensors --llm ..\models\text_encoders\Qwen3VL-8B-Instruct-Q4_K_M.gguf -p "a lovely cat holding a sign says 'qwen2.1.cpp'" --cfg-scale 6.0 --sampling-method euler -v --offload-to-cpu -o qwen_image_2.1.png
```
-<img alt="Qwen Image 2.1 example" src="../assets/qwen/qwen_image_2.1.png" />
+<img alt="Qwen Image 2.1 example" src="../../assets/qwen/qwen_image_2.1.png" />
To use GGUF diffusion weights, set `--diffusion-model` to the path of a file such as `qwen_image_2.1-Q4_K.gguf`.
@@ -91,8 +91,8 @@ Since transparency is decided by the prompt rather than by the input or an expli
Here are some examples ran with Q6_K quantization:
| Input | Prompt | Output |
| --- | --- | --- |
-|  | This is an RGBA image with transparency. Replace the text "BLOOM" with "Qwen Image 2.1", keeping the same font of the original text. The image has alpha channel and the background is transparent. |  |
-|  | This is an RGBA image with transparency. Remove the background of the image, keeping only the text and cat. The image has alpha channel and the background is transparent. |  |
+|  | This is an RGBA image with transparency. Replace the text "BLOOM" with "Qwen Image 2.1", keeping the same font of the original text. The image has alpha channel and the background is transparent. |  |
+|  | This is an RGBA image with transparency. Remove the background of the image, keeping only the text and cat. The image has alpha channel and the background is transparent. |  |
### Other features
diff --git a/docs/qwen_image_edit.md b/docs/models/qwen_image_edit.md
similarity index 91%
rename from docs/qwen_image_edit.md
rename to docs/models/qwen_image_edit.md
index 2d53d83..945e0b8 100644
--- a/docs/qwen_image_edit.md
+++ b/docs/models/qwen_image_edit.md
@@ -26,7 +26,7 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Qwen_Image_Edit-Q8_0.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'edit.cpp'" --seed 1118877715456453
```
-<img alt="qwen_image_edit" src="../assets/qwen/qwen_image_edit.png" />
+<img alt="qwen_image_edit" src="../../assets/qwen/qwen_image_edit.png" />
### Qwen Image Edit 2509
@@ -35,7 +35,7 @@
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\Qwen-Image-Edit-2509-Q4_K_S.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\Qwen2.5-VL-7B-Instruct-Q8_0.gguf --llm_vision ..\models\text_encoders\Qwen2.5-VL-7B-Instruct.mmproj-Q8_0.gguf --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'Qwen Image Edit 2509'"
```
-<img alt="qwen_image_edit_2509" src="../assets/qwen/qwen_image_edit_2509.png" />
+<img alt="qwen_image_edit_2509" src="../../assets/qwen/qwen_image_edit_2509.png" />
### Qwen Image Edit 2511
@@ -45,4 +45,4 @@ To use the new Qwen Image Edit 2511 mode, `--model-args qwen_image_zero_cond_t=t
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\qwen-image-edit-2511-Q4_K_M.gguf --vae ..\models\vae\qwen_image_vae.safetensors --llm ..\models\text_encoders\qwen_2.5_vl_7b.safetensors --cfg-scale 2.5 --sampling-method euler -v --offload-to-cpu --flow-shift 3 -r ..\assets\flux\flux1-dev-q8_0.png -p "change 'flux.cpp' to 'edit.cpp'" --model-args qwen_image_zero_cond_t=true
```
-<img alt="qwen_image_edit_2509" src="../assets/qwen/qwen_image_edit_2511.png" />
+<img alt="qwen_image_edit_2509" src="../../assets/qwen/qwen_image_edit_2511.png" />
diff --git a/docs/relay_vsr.md b/docs/models/relay_vsr.md
similarity index 96%
rename from docs/relay_vsr.md
rename to docs/models/relay_vsr.md
index e35f5fd..5485d42 100644
--- a/docs/relay_vsr.md
+++ b/docs/models/relay_vsr.md
@@ -43,7 +43,7 @@ and use `-o output.png` (or JPEG/WebP). No FPS setting is needed for an image.
The default 16 selects reference frames 0, 15, 30, and so on, and always
includes the final frame. Every input frame appears once in the output.
- `--flash-attn auto` and `--conv-direct auto` are enabled by default. See
- [backend selection](backend.md) to choose a device or weight placement.
+ [backend selection](../guides/backend.md) to choose a device or weight placement.
- Sampler, scheduler, and step settings do not configure RelayVSR.
`--vsr-temporal-chunk-size` is a SeedVR2 option.
- Long videos require enough system memory to hold the input and output frames.
diff --git a/docs/sd.md b/docs/models/sd.md
similarity index 88%
rename from docs/sd.md
rename to docs/models/sd.md
index 44a4c1f..746d52e 100644
--- a/docs/sd.md
+++ b/docs/models/sd.md
@@ -21,7 +21,7 @@ Using formats of different precisions will yield results of varying quality.
| f32 | f16 |q8_0 |q5_0 |q5_1 |q4_0 |q4_1 |
| ---- |---- |---- |---- |---- |---- |---- |
-|  | | | | | | |
+|  | | | | | | |
### img2img example
@@ -33,5 +33,5 @@ Using formats of different precisions will yield results of varying quality.
```
<p align="center">
- <img src="../assets/img2img_output.png" width="256x">
+ <img src="../../assets/img2img_output.png" width="256x">
</p>
diff --git a/docs/sd3.md b/docs/models/sd3.md
similarity index 96%
rename from docs/sd3.md
rename to docs/models/sd3.md
index 3893659..932406b 100644
--- a/docs/sd3.md
+++ b/docs/models/sd3.md
@@ -17,4 +17,4 @@ For example:
.\bin\Release\sd-cli.exe -m ..\models\sd3.5_large.safetensors --clip_l ..\models\clip_l.safetensors --clip_g ..\models\clip_g.safetensors --t5xxl ..\models\t5xxl_fp16.safetensors -H 1024 -W 1024 -p 'a lovely cat holding a sign says \"Stable diffusion 3.5 Large\"' --cfg-scale 4.5 --sampling-method euler -v --clip-on-cpu
```
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/seedvr2.md b/docs/models/seedvr2.md
similarity index 97%
rename from docs/seedvr2.md
rename to docs/models/seedvr2.md
index 24f5503..b5b4b1b 100644
--- a/docs/seedvr2.md
+++ b/docs/models/seedvr2.md
@@ -59,7 +59,7 @@ use an output pattern such as `-o restored/%06d.png`.
- If you run out of GPU memory, try `--vsr-temporal-chunk-size 1`. A five-frame
chunk at 1728x960 output resolution exceeded 24 GB of GPU memory in testing.
- `--flash-attn auto` and `--conv-direct auto` are enabled by default. See
- [backend selection](backend.md) to choose a device or weight placement.
+ [backend selection](../guides/backend.md) to choose a device or weight placement.
- SeedVR2 does not use sampler, scheduler, or step settings.
`--vsr-window-size` is a RelayVSR option and does not affect SeedVR2.
diff --git a/docs/sefi_image.md b/docs/models/sefi_image.md
similarity index 96%
rename from docs/sefi_image.md
rename to docs/models/sefi_image.md
index 9989e4f..f588da8 100644
--- a/docs/sefi_image.md
+++ b/docs/models/sefi_image.md
@@ -47,4 +47,4 @@ The dispatcher picks `alpha` from the filename (`turbo` substring => 1.0, otherw
./build/bin/sd-cli --diffusion-model /path/to/sefi_5b_turbo.safetensors --vae /path/to/flux2_ae.safetensors --llm /path/to/qwen3_vl_4b.safetensors -p "a photograph of an orange tabby cat sitting on a couch" --cfg-scale 1.0 --steps 4 -W 1024 -H 1024 -s 42 --max-vram 8 --offload-to-cpu -o out.png
```
-<img alt="SeFi-Image 5B turbo example" src="../assets/sefi_image/example.png" />
+<img alt="SeFi-Image 5B turbo example" src="../../assets/sefi_image/example.png" />
diff --git a/docs/sensenova_u1.md b/docs/models/sensenova_u1.md
similarity index 100%
rename from docs/sensenova_u1.md
rename to docs/models/sensenova_u1.md
diff --git a/docs/taesd.md b/docs/models/taesd.md
similarity index 100%
rename from docs/taesd.md
rename to docs/models/taesd.md
diff --git a/docs/wan.md b/docs/models/wan.md
similarity index 93%
rename from docs/wan.md
rename to docs/models/wan.md
index 2031de7..ac0f4b9 100644
--- a/docs/wan.md
+++ b/docs/models/wan.md
@@ -70,7 +70,7 @@ Wan models require `-M vid_gen`, including single-frame generation. `--video-fra
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1_t2v_1.3B_fp16.safetensors --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --video-frames 33 --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.1_1.3B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_1.3B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.1 T2V 14B
@@ -78,7 +78,7 @@ Wan models require `-M vid_gen`, including single-frame generation. `--video-fra
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-t2v-14b-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --video-frames 33 --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.1_14B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_14B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
@@ -88,7 +88,7 @@ Wan models require `-M vid_gen`, including single-frame generation. `--video-fra
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-i2v-14b-480p-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf --clip_vision ..\models\clip_vision\clip_vision_h.safetensors -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --video-frames 33 --offload-to-cpu -i ..\assets\cat_with_sd_cpp_42.png --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.1_14B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_14B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.2 T2V A14B
@@ -96,7 +96,7 @@ Wan models require `-M vid_gen`, including single-frame generation. `--video-fra
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --video-frames 33 --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.2_14B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_14B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.2 I2V A14B
@@ -104,7 +104,7 @@ Wan models require `-M vid_gen`, including single-frame generation. `--video-fra
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --video-frames 33 --offload-to-cpu -i ..\assets\cat_with_sd_cpp_42.png --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.2_14B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_14B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.2 S2V 14B
@@ -154,7 +154,7 @@ Notes:
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --flow-shift 3.0
```
-<img width="832" height="480" alt="Wan2 2_14B_t2i" src="../assets/wan/Wan2.2_14B_t2i.png" />
+<img width="832" height="480" alt="Wan2 2_14B_t2i" src="../../assets/wan/Wan2.2_14B_t2i.png" />
### Wan2.2 T2V 14B with Lora
@@ -162,7 +162,7 @@ Notes:
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-T2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat<lora:wan2.2_t2v_lightx2v_4steps_lora_v1.1_low_noise:1><lora:|high_noise|wan2.2_t2v_lightx2v_4steps_lora_v1.1_high_noise:1>" --cfg-scale 3.5 --sampling-method euler --steps 4 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 4 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --offload-to-cpu --lora-model-dir ..\models\loras --video-frames 33 --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.2_14B_t2v_lora.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_14B_t2v_lora.mp4 controls="controls" muted="muted" type="video/mp4"></video>
@@ -174,7 +174,7 @@ Notes:
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.2_ti2v_5B_fp16.safetensors --vae ..\models\vae\wan2.2_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --offload-to-cpu --video-frames 33 --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.2_5B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_5B_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
#### I2V
@@ -182,7 +182,7 @@ Notes:
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.2_ti2v_5B_fp16.safetensors --vae ..\models\vae\wan2.2_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --offload-to-cpu --video-frames 33 -i ..\assets\cat_with_sd_cpp_42.png --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.2_5B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_5B_i2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
TI2V 5B can decode multiple latent frames together when temporal tiling is enabled. For example, `--temporal-tiling --vae-tiling --vae-tile-size 256x256 --extra-tiling-args "temporal_tile_frames=4,temporal_decode_frames=2"` keeps up to four latent frames in each temporal tile and decodes up to two at once, with spatial tiles of 256×256 pixels. `temporal_decode_frames` defaults to `1`, preserving frame-by-frame decoding; other model versions ignore it. Increasing it requires more memory. Adjust the spatial tile size to fit the available memory.
@@ -193,7 +193,7 @@ TI2V 5B can decode multiple latent frames together when temporal tiling is enabl
```
-<video src=../assets/wan/Wan2.1_14B_flf2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_14B_flf2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.2 FLF2V 14B
@@ -201,7 +201,7 @@ TI2V 5B can decode multiple latent frames together when temporal tiling is enabl
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-LowNoise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-I2V-A14B-HighNoise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -p "glass flower blossom" -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部，畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 --video-frames 33 --offload-to-cpu --init-img ..\..\ComfyUI\input\start_image.png --end-img ..\..\ComfyUI\input\end_image.png --flow-shift 3.0
```
-<video src=../assets/wan/Wan2.2_14B_flf2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_14B_flf2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.1 VACE 1.3B
@@ -211,7 +211,7 @@ TI2V 5B can decode multiple latent frames together when temporal tiling is enabl
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --video-frames 1 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.1_1.3B_vace_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_1.3B_vace_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
#### R2V
@@ -220,7 +220,7 @@ TI2V 5B can decode multiple latent frames together when temporal tiling is enabl
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 -i ..\assets\cat_with_sd_cpp_42.png --video-frames 33 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.1_1.3B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_1.3B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
#### V2V
@@ -231,7 +231,7 @@ ffmpeg -i ..\..\ComfyUI\input\post+depth.mp4 -qscale:v 1 -vf fps=8 post+depth\fr
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\wan2.1-vace-1.3b-q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 -i ..\..\ComfyUI\input\dance_girl.jpg --control-video ./post+depth --video-frames 33 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.1_1.3B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_1.3B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.1 VACE 14B
@@ -241,7 +241,7 @@ ffmpeg -i ..\..\ComfyUI\input\post+depth.mp4 -qscale:v 1 -vf fps=8 post+depth\fr
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 --video-frames 33 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.1_14B_vace_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_14B_vace_t2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
#### R2V
@@ -250,7 +250,7 @@ ffmpeg -i ..\..\ComfyUI\input\post+depth.mp4 -qscale:v 1 -vf fps=8 post+depth\fr
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 -i ..\assets\cat_with_sd_cpp_42.png --video-frames 33 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.1_14B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_14B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
@@ -260,7 +260,7 @@ ffmpeg -i ..\..\ComfyUI\input\post+depth.mp4 -qscale:v 1 -vf fps=8 post+depth\fr
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.1_14B_VACE-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "The girl is dancing in a sea of flowers, slowly moving her hands. There is a close - up shot of her upper body. The character is surrounded by other transparent glass flowers in the style of Nicoletta Ceccoli, creating a beautiful, surreal, and emotionally expressive movie scene with a white. transparent feel and a dreamyl atmosphere." --cfg-scale 6.0 --sampling-method euler -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 480 -H 832 -i ..\..\ComfyUI\input\dance_girl.jpg --control-video ./post+depth --video-frames 33 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.1_14B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.1_14B_vace_v2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
### Wan2.2 VACE-Fun A14B
@@ -274,7 +274,7 @@ for the reference image, same as Wan2.1 VACE.
.\bin\Release\sd-cli.exe -M vid_gen --diffusion-model ..\models\diffusion_models\Wan2.2-VACE-Fun-A14B-low-noise-Q8_0.gguf --high-noise-diffusion-model ..\models\diffusion_models\Wan2.2-VACE-Fun-A14B-high-noise-Q8_0.gguf --vae ..\models\vae\wan_2.1_vae.safetensors --t5xxl ..\models\text_encoders\umt5-xxl-encoder-Q8_0.gguf -p "a lovely cat" --cfg-scale 3.5 --sampling-method euler --steps 10 --high-noise-cfg-scale 3.5 --high-noise-sampling-method euler --high-noise-steps 8 -v -n "色调艳丽，过曝，静态，细节模糊不清，字幕，风格，作品，画作，画面，静止，整体发灰，最差质量，低质量，JPEG压缩残留，丑陋的，残缺的，多余的手指，画得不好的手部，画得不好的脸部， 畸形的，毁容的，形态畸形的肢体，手指融合，静止不动的画面，杂乱的背景，三条腿，背景人很多，倒着走" -W 832 -H 480 -i ..\assets\cat_with_sd_cpp_42.png --video-frames 33 --offload-to-cpu
```
-<video src=../assets/wan/Wan2.2_A14B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
+<video src=../../assets/wan/Wan2.2_A14B_vace_r2v.mp4 controls="controls" muted="muted" type="video/mp4"></video>
#### T2V
diff --git a/docs/z_image.md b/docs/models/z_image.md
similarity index 77%
rename from docs/z_image.md
rename to docs/models/z_image.md
index 8dca319..6913ece 100644
--- a/docs/z_image.md
+++ b/docs/models/z_image.md
@@ -24,7 +24,7 @@ You can run Z-Image with stable-diffusion.cpp on GPUs with 4GB of VRAM — or ev
.\bin\Release\sd-cli.exe --diffusion-model z_image_turbo-Q3_K.gguf --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\Qwen3-4B-Instruct-2507-Q4_K_M.gguf -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" --cfg-scale 1.0 -v --offload-to-cpu -H 1024 -W 512 --steps 8
```
-<img width="256" alt="z-image example" src="../assets/z_image/q3_K.png" />
+<img width="256" alt="z-image example" src="../../assets/z_image/q3_K.png" />
### Z-Image-Base
@@ -32,10 +32,10 @@ You can run Z-Image with stable-diffusion.cpp on GPUs with 4GB of VRAM — or ev
.\bin\Release\sd-cli.exe --diffusion-model ..\models\diffusion_models\z_image_bf16.safetensors --vae ..\models\vae\ae.sft --llm ..\models\text_encoders\qwen_3_4b.safetensors -p "A cinematic, melancholic photograph of a solitary hooded figure walking through a sprawling, rain-slicked metropolis at night. The city lights are a chaotic blur of neon orange and cool blue, reflecting on the wet asphalt. The scene evokes a sense of being a single component in a vast machine. Superimposed over the image in a sleek, modern, slightly glitched font is the philosophical quote: 'THE CITY IS A CIRCUIT BOARD, AND I AM A BROKEN TRANSISTOR.' -- moody, atmospheric, profound, dark academic" --cfg-scale 5.0 -v --offload-to-cpu -H 1024 -W 512
```
-<img width="256" alt="z-image example" src="../assets/z_image/base_bf16.png" />
+<img width="256" alt="z-image example" src="../../assets/z_image/base_bf16.png" />
## Comparison of Different Quantization Types
| bf16 | q8_0 | q6_K | q5_0 | q4_K | q4_0 | q3_K | q2_K|
|---|---|---|---|---|---|---|---|
-| <img width="256" alt="bf16" src="../assets/z_image/bf16.png" /> | <img width="256" alt="q8_0" src="../assets/z_image/q8_0.png" /> | <img width="256" alt="q6_K" src="../assets/z_image/q6_K.png" /> | <img width="256" alt="q5_0" src="../assets/z_image/q5_0.png" /> | <img width="256" alt="q4_K" src="../assets/z_image/q4_K.png" /> | <img width="256" alt="q4_0" src="../assets/z_image/q4_0.png" /> | <img width="256" alt="q3_K" src="../assets/z_image/q3_K.png" /> | <img width="256" alt="q2_K" src="../assets/z_image/q2_K.png" /> |
\ No newline at end of file
+| <img width="256" alt="bf16" src="../../assets/z_image/bf16.png" /> | <img width="256" alt="q8_0" src="../../assets/z_image/q8_0.png" /> | <img width="256" alt="q6_K" src="../../assets/z_image/q6_K.png" /> | <img width="256" alt="q5_0" src="../../assets/z_image/q5_0.png" /> | <img width="256" alt="q4_K" src="../../assets/z_image/q4_K.png" /> | <img width="256" alt="q4_0" src="../../assets/z_image/q4_0.png" /> | <img width="256" alt="q3_K" src="../../assets/z_image/q3_K.png" /> | <img width="256" alt="q2_K" src="../../assets/z_image/q2_K.png" /> |
\ No newline at end of file
diff --git a/docs/z_image_l2p.md b/docs/models/z_image_l2p.md
similarity index 100%
rename from docs/z_image_l2p.md
rename to docs/models/z_image_l2p.md
diff --git a/examples/cli/README.md b/examples/cli/README.md
index 5789455..2072e1c 100644
--- a/examples/cli/README.md
+++ b/examples/cli/README.md
@@ -6,13 +6,16 @@ For detailed command-line arguments, run:
./bin/sd-cli -h
```
+See [sampling methods and schedulers](../../docs/guides/sampling.md) for supported
+names, defaults, and custom sigma schedules.
+
Logging defaults to `info`. Use `--log-level <level>` to select `debug`, `verbose`,
`info`, `warn`, or `error` (from most to least detailed). Each level includes
messages at that level and all less detailed levels. `-v` and `--verbose` are
equivalent to `--log-level verbose`. If repeated, the last logging option wins.
`--flash-attn on|off|auto` defaults to `auto`, selecting flash attention for each
-compute backend during context creation. See [Backend selection](../../docs/backend.md#flash-attention---flash-attn-onoffauto)
+compute backend during context creation. See [Backend selection](../../docs/guides/backend.md#flash-attention---flash-attn-onoffauto)
for probing behavior.
Use module assignments such as `--flash-attn auto,te=off,vae=on` to override
individual modules.
@@ -20,15 +23,15 @@ individual modules.
`--conv-direct on|off|auto` also defaults to `auto`, enabling direct convolution
on backends with implicit GEMM implementations. Use `--conv-direct auto,vae=off`
for module overrides; supported modules are `diffusion`, `vae`, and `controlnet`.
-See [Direct convolution](../../docs/backend.md#direct-convolution---conv-direct-onoffauto).
+See [Direct convolution](../../docs/guides/backend.md#direct-convolution---conv-direct-onoffauto).
For direct image repair or automatic post-generation YOLOv8 detection followed by cropped inpainting, see
-[ADetailer](../../docs/adetailer.md).
+[ADetailer](../../docs/models/adetailer.md).
Use repeatable `--image-preprocess` rules to select resizing, cropping, padding,
and resampling separately for each image input. Add `canny=true` to any input
rule for edge detection. See
-[Image preprocessing](../../docs/image_preprocessing.md) for input selectors,
+[Image preprocessing](../../docs/guides/image_preprocessing.md) for input selectors,
input defaults, downstream model processing, mask alignment, and examples.
Metadata mode inspects PNG, JPEG, WebP (including animated WebP), AVI, WebM, and Matroska
@@ -46,6 +49,6 @@ container metadata without loading any model. Use `--image` for both images and
For completely black or white images or videos, NaNs, and the `--linear-scale` /
`--attn-scale` workaround, see [Troubleshooting](../../docs/troubleshooting.md).
-Generation outputs embed the core [generation record](../../docs/generation_metadata.md).
+Generation outputs embed the core [generation record](../../docs/guides/generation_metadata.md).
Images retain the native JSON and an additional WebUI-compatible infotext.
`--disable-image-metadata` omits both from files.
diff --git a/examples/server/api.md b/examples/server/api.md
index fe43128..dca1351 100644
--- a/examples/server/api.md
+++ b/examples/server/api.md
@@ -16,7 +16,7 @@ Image and video requests can include interleaved images in `prompt` or
`prompt_images` object mapping each ID to a base64 image or image data URI.
For `OpenAI API` and `sdapi`, pass `prompt_images` through `sd_cpp_extra_args`
embedded inside `prompt`. IDs are resolved against that request's images.
-See [images in prompts](../../docs/prompt_images.md) for examples and supported
+See [images in prompts](../../docs/guides/prompt_images.md) for examples and supported
LLM encoders.
Global LoRA rule:
@@ -983,7 +983,7 @@ Shared default fields used by both `img_gen` and `vid_gen`:
| `output_format` | `string` |
| `output_compression` | `integer` |
-`vae_tiling_params.tile_size_w` and `tile_size_h` are in **image pixels**, with `0` selecting the 256-pixel default. Both encode and decode use these sizes without an encoding multiplier. Positive `rel_size_w`/`rel_size_h` values override the corresponding absolute size: values up to 1 are dimension fractions, and values greater than 1 are target tile counts. Set `enabled` to use spatial tiling. Sizes are aligned down to the VAE scale factor and capped at the input dimensions; explicit sizes below the minimum supported tile size are rejected. These fields previously used latent units; see [VAE tiling](../../docs/performance.md#use-vae-tiling-to-reduce-encode-and-decode-memory-usage) for migration and OOM retry behavior.
+`vae_tiling_params.tile_size_w` and `tile_size_h` are in **image pixels**, with `0` selecting the 256-pixel default. Both encode and decode use these sizes without an encoding multiplier. Positive `rel_size_w`/`rel_size_h` values override the corresponding absolute size: values up to 1 are dimension fractions, and values greater than 1 are target tile counts. Set `enabled` to use spatial tiling. Sizes are aligned down to the VAE scale factor and capped at the input dimensions; explicit sizes below the minimum supported tile size are rejected. These fields previously used latent units; see [VAE tiling](../../docs/guides/performance.md#use-vae-tiling-to-reduce-encode-and-decode-memory-usage) for migration and OOM retry behavior.
`vae_tiling_params.extra_tiling_args` accepts a key=value list. Supported video VAEs accept `temporal_tile_frames` (alias `temporal_tile_size`, default `4`) and `temporal_tile_overlap` (default `1`). Wan2.2 TI2V 5B uses `temporal_decode_frames` (default `1`) to decode multiple latent frames per forward pass, trading additional memory for throughput; other model versions ignore this option.
LTX and Wan preserve causal state between temporal tiles. Hunyuan Video and TAEHV use overlap blending. MiniMax H3 keeps its model-specific fixed temporal windows because its latent-to-frame mapping is non-linear.
@@ -1255,7 +1255,7 @@ Example:
Native image/video requests and SDAPI accept `image_preprocess` as a rule string
or array of rule strings. OpenAI-compatible requests can supply it in
-`sd_cpp_extra_args`. See [Image preprocessing](../../docs/image_preprocessing.md)
+`sd_cpp_extra_args`. See [Image preprocessing](../../docs/guides/image_preprocessing.md)
for one-time input geometry, native-resolution decoding, mask alignment, and
`canny=true` for edge detection on any supported image input.
@@ -1616,7 +1616,7 @@ Example:
- Other video model families currently ignore `ref_images`.
- `features_by_mode.vid_gen` does not currently advertise `ref_images`; its absence is not an indication that MiniMax-H3 reference images are unsupported.
-See [MiniMax-H3 reference conditioning](../../docs/minimax_h3.md#reference-to-audio-video-conditioning) for model requirements and prompt examples.
+See [MiniMax-H3 reference conditioning](../../docs/models/minimax_h3.md#reference-to-audio-video-conditioning) for model requirements and prompt examples.
### LoRA Rules
@@ -1911,5 +1911,5 @@ result items and OpenAI image items contain the parameter snapshot with each
image's actual seed and without `batch_count`. Native video
results contain the video request snapshot. SD API `info.generation_info` is an array
aligned with `info.infotexts` and `info.all_seeds`; the outer `parameters` field
-remains the request echo. See [generation metadata](../../docs/generation_metadata.md)
+remains the request echo. See [generation metadata](../../docs/guides/generation_metadata.md)
for field semantics, postprocessing and container storage.
diff --git a/examples/server/recipes/README.md b/examples/server/recipes/README.md
index dcf9d69..9405fdb 100644
--- a/examples/server/recipes/README.md
+++ b/examples/server/recipes/README.md
@@ -56,7 +56,7 @@ prompt, a style preset, or a collection of sampling settings.
has different native inpainting/control conditioning, beyond its layer count
([model card](https://huggingface.co/ostris/Flex.2-preview)). SDXS uses an
adjusted AutoEncoderTiny and a one-step model, rather than only a shallower
- ordinary SD checkpoint ([runtime guide](../../../docs/distilled_sd.md#sdxs-512-dreamshaper)).
+ ordinary SD checkpoint ([runtime guide](../../../docs/models/distilled_sd.md#sdxs-512-dreamshaper)).
Their native components stay in their own model recipe.
- Quantization, file format, prompt wording, seeds, step counts and CFG values
are not grounds for another recipe. Differences in required components,
diff --git a/examples/server/recipes/defaults.md b/examples/server/recipes/defaults.md
index 0e2b63c..fdccc96 100644
--- a/examples/server/recipes/defaults.md
+++ b/examples/server/recipes/defaults.md
@@ -70,11 +70,11 @@ For community edit adapters and other optional extensions, these are the base-mo
| `ming-image` | 1 | 12 | 1024 × 1024 | [Source](https://huggingface.co/inclusionAI/Ming-Image-0.1-Design) |
| `minimax-h3-fl2va` | 1 | — | 1344 × 768 | [Source](https://huggingface.co/docs/diffusers/main/en/api/pipelines/minimax_h3) Guidance-distilled; official 768p canvas. No fixed step count is prescribed here; the upstream API counts sigma grid points rather than sd.cpp denoising steps. |
| `minimax-h3-ref2va` | 1 | — | 1344 × 768 | [Source](https://huggingface.co/docs/diffusers/main/en/api/pipelines/minimax_h3) Guidance-distilled; official 768p canvas. No fixed step count is prescribed here; the upstream API counts sigma grid points rather than sd.cpp denoising steps. |
-| `minimax-h3-image` | 1 | 6 | 1024 × 1024 | [Runtime guide](../../../docs/minimax_h3_image.md) Dedicated image VAE and fixed PDD sigma schedule. |
+| `minimax-h3-image` | 1 | 6 | 1024 × 1024 | [Runtime guide](../../../docs/models/minimax_h3_image.md) Dedicated image VAE and fixed PDD sigma schedule. |
| `minit2i` | 2.5 | 20 | 512 × 512 | [Source](https://huggingface.co/MiniT2I/MiniT2I/raw/main/pipeline.py) B/16 example and native model size; L/16 uses CFG 6. |
| `moss-image-base` | 3 | 20 | 1024 × 1024 | [Source](https://huggingface.co/OpenMOSS-Team/MOSS-Image-Base) |
| `moss-image-sft` | 3 | 20 | 1024 × 1024 | [Source](https://huggingface.co/OpenMOSS-Team/MOSS-Image-SFT) |
-| `p-h3-image` | 1 | 8 | 1024 × 1024 | [Runtime guide](../../../docs/p_h3_image.md) Fixed P-H3 sigma schedule; upstream 2912 × 2912 reduced to the catalog default. |
+| `p-h3-image` | 1 | 8 | 1024 × 1024 | [Runtime guide](../../../docs/models/p_h3_image.md) Fixed P-H3 sigma schedule; upstream 2912 × 2912 reduced to the catalog default. |
| `nitrosd-realism` | 1 | 1 | 1024 × 1024 | [Source](https://huggingface.co/ChenDY/NitroFusion) |
| `ovis-image` | 5 | 20 | 1024 × 1024 | [Source](https://huggingface.co/ATH-MaaS/Ovis-Image-7B) |
| `pid` | 1 | 4 | 2048 × 2048 | [Source](https://huggingface.co/nvidia/PiD) Standalone PiD decoding at 2K; guidance is handled by the upstream generator. |