Merge pull request #1690 from NeuralFault/docs

docs: add settings documentation, restructure env vars, update ROCm platform docs

Author: mohnjiles

docs/README.md

@@ -52,11 +52,7 @@ Current Status: In-progress - Structure is in-place and planned docs are current
 - Community Workflows *(planned)* — Browsing community workflows via OpenArt
 
 ### Settings
-- Overview *(planned)* — Navigating the settings hub
-- General *(planned)* — Theme, language, data directory, and shared folder settings
-- Accounts *(planned)* — Lykos account, OAuth login, and API tokens
-- Inference Settings *(planned)* — Inference UI behavior and defaults
-- Updates *(planned)* — Auto-update channel and frequency settings
+- [Settings](settings/settings.md) — All application settings covering General, Accounts, Checkpoint Manager, Package Environment, Model Browser, Workflow Browser, Console, Appearance, System, and Debug Options
 
 ### Advanced
 - [Overview](advanced/overview.md) — Advanced configuration and technical reference

docs/advanced/environment-variables.md

@@ -143,26 +143,31 @@ Most users should leave these alone unless they are troubleshooting a specific R
 | `COMFYUI_ENABLE_MIOPEN` | `1` | Tells ComfyUI to keep the MIOpen-backed path enabled on ROCm builds where it may otherwise be disabled by default. Without this enabled, ComfyUI disables the `cudnn` backend path in its backend calls for RDNA3, RDNA3.5, and RDNA4 AMD GPUs, which in turn disables the MIOpen-backed functions that rely on that path. This variable is needed for MIOpen to function properly in those setups. |
 | `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL` | `1` | Enables the experimental ROCm AOTriton path in compatible PyTorch builds. In Stability Matrix's Windows ROCm ComfyUI integration, this is used for TheRock technical-preview PyTorch builds to enable AOTriton-provided built-in Flash Attention and PyTorch SDPA memory-efficient attention paths. |
 
-For some Windows ROCm-based ComfyUI launches, Stability Matrix already applies several of these optimizations automatically in package code, including:
+For Windows ROCm-based WebUI package launches, Stability Matrix already applies several of these optimizations automatically at package launch as a general all-round baseline. Variables automatically utilized at package launch include:
 
-`MIOPEN_FIND_MODE=2`
-
-`MIOPEN_SEARCH_CUTOFF=1`
-
-`MIOPEN_FIND_ENFORCE=1`
-
-`TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1` (RDNA3 / RDNA3.5 / RDNA4 only, and additionally excluded on the gfx1152/gfx1153 APU architectures where AOTriton isn't yet supported)
-
-`FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`
-
-`COMFYUI_ENABLE_MIOPEN=1` (RDNA3 / RDNA3.5 / RDNA4 only, no gfx1152/gfx1153 exclusion)
-
-`PYTORCH_ALLOC_CONF=max_split_size_mb:512,garbage_collection_threshold:0.8`
+| Variable | Value | Notes |
+|---|---|---|
+| `MIOPEN_FIND_MODE` | `2` | |
+| `MIOPEN_SEARCH_CUTOFF` | `1` | |
+| `MIOPEN_FIND_ENFORCE` | `1` | |
+| `TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL` | `1` | Enables the experimental ROCm AOTriton path. Applied only on RDNA3 / RDNA3.5 / RDNA4 GPUs, and additionally excluded on gfx1152/gfx1153 APU architectures where AOTriton isn't yet supported. |
+| `FLASH_ATTENTION_TRITON_AMD_ENABLE` | `TRUE` | Enables the Triton-based Flash Attention implementation for AMD GPUs, providing an efficient attention path when the native ROCm Flash Attention is unavailable and instead provided by a separate FA Python package. |
+| `COMFYUI_ENABLE_MIOPEN` | `1` | Keeps the MIOpen-backed path enabled in ComfyUI on RDNA3 / RDNA3.5 / RDNA4 GPUs. |
+| `PYTORCH_ALLOC_CONF` | `max_split_size_mb:512,garbage_collection_threshold:0.8` | |
+
+Environment Variables automatically enabled for legacy AMD GPU architectures (Vega/GCN5, RDNA1, RDNA2) where certain backend paths are not supported by the hardware or supported well:
+| Variable | Value | Notes |
+|---|---|---|
+| `TORCH_BACKENDS_CUDA_FLASH_SDP_ENABLED` | `0` | Disables the Flash SDP backend. |
+| `TORCH_BACKENDS_CUDA_MEM_EFF_SDP_ENABLED` | `0` | Disables the memory-efficient SDP backend. |
+| `TORCH_BACKENDS_CUDA_MATH_SDP_ENABLED` | `1` | Enables the math SDP backend as the fallback attention implementation. |
 
 
-Linux installs do not currently get the same automatic overrides, so they will need to be enabled by the user.
+> [!NOTE]
+> Linux installs do not currently get the same automatic overrides, so they will need to be enabled by the user.
 
-If you're using the ComfyUI-Zluda package specifically, it also sets its own environment variables at launch on top of the above: `FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`, `MIOPEN_FIND_MODE=2`, `MIOPEN_LOG_LEVEL=3`, and `ZLUDA_COMGR_LOG_LEVEL=1`. If you're wondering why those already appear to be set for a ZLUDA install, this is why.
+> [!NOTE]
+> ComfyUI-Zluda is not managed by Stability Matrix's internal ROCm handling. If you're using the ComfyUI-Zluda package specifically, it also sets its own environment variables at launch similar to some of the above: `FLASH_ATTENTION_TRITON_AMD_ENABLE=TRUE`, `MIOPEN_FIND_MODE=2`, `MIOPEN_LOG_LEVEL=3`, and `ZLUDA_COMGR_LOG_LEVEL=1`. If you're wondering why those already appear to be set for a ZLUDA install, this is why.
 
 Whatever you set in Stability Matrix's own environment-variable editor is applied last, so it always overrides these auto-applied defaults if the same variable name is used.
 

docs/advanced/hardware-support.md

@@ -40,11 +40,11 @@ The lists below describe what the code checks for. Because hardware detection wo
 
 ## AMD on Windows
 
-AMD support on Windows is the most involved case, because there are three different paths depending on your GPU and package: native ROCm (technical preview), ZLUDA, and DirectML.
+AMD support on Windows is the most involved case, because there are three different paths depending on your GPU and package: native ROCm, ZLUDA, and DirectML.
 
-### Native ROCm (TheRock technical preview)
+### Native ROCm
 
-Stability Matrix can install AMD's native ROCm PyTorch on Windows using AMD's TheRock multi-architecture wheels. This path is gated to a specific set of GPU architectures. The code recognizes the following `gfx` architectures as supported on Windows:
+Stability Matrix can install AMD's native ROCm PyTorch on Windows using AMD's official multi-architecture wheels. This path is gated to a specific set of GPU architectures. The code recognizes the following `gfx` architectures as supported on Windows:
 
 - **RDNA4** — `gfx120x` (e.g. RX 9070, RX 9060 families).
 - **RDNA3 / RDNA3.5** — `gfx110x` (RDNA3 desktop and mobile) and `gfx115x` (RDNA3.5 APUs such as the 890M / 8060S / Z2 Extreme families).
@@ -54,15 +54,17 @@ Architectures in the `gfx110x`, `gfx115x`, and `gfx120x` ranges are treated as "
 
 **What Stability Matrix does automatically:**
 
-- When a supported AMD GPU is present on Windows, ROCm becomes the recommended backend for ROCm-capable packages (currently ComfyUI and Comfy-based flows via SwarmUI).
-- Torch is installed from AMD's ROCm multi-arch index (`repo.amd.com/rocm/whl-multi-arch/`) as device-specific wheels (`torch[device-gfxNNNN]`). Vega parts (`gfx900` / `gfx906`) pull from the nightly multi-arch feed instead, since TheRock currently only publishes their device packages there.
+- When a supported AMD GPU is present on Windows, ROCm becomes the recommended backend for ROCm-capable packages.
+- Torch is installed from AMD's ROCm multi-arch index (`repo.amd.com/rocm/whl-multi-arch/`) as device-specific wheels (`torch[device-gfxNNNN]`). Vega parts (`gfx900` / `gfx906`) pull from the 'TheRock' nightly multi-arch feed instead, since these architecture builds currently are only available there instead of the stable production distribution stream.
 - On modern architectures it applies a set of ROCm performance and attention environment variables at launch (MIOpen find-mode tuning, AOTriton experimental flash attention, `COMFYUI_ENABLE_MIOPEN`, and an allocator tuning string). AOTriton is excluded on the `gfx1152` / `gfx1153` APU architectures, which it does not yet support. Legacy architectures instead force a math SDP fallback. The full variable list and exactly which ones are auto-applied are documented in [Environment Variables](environment-variables.md#amd-and-rocm-variables).
-- ComfyUI offers optional extra commands for supported AMD GPUs, including **Install Triton and SageAttention (ROCm)**, **Install Flash Attention (ROCm)** (legacy architectures), an **Install ROCm Development SDK** step, and an **Install bitsandbytes (ROCm)** step for Python 3.12 environments.
+- ComfyUI offers optional extra commands for supported AMD GPUs, including **Install Triton and SageAttention (ROCm)** (Sage Attention 1.x), **Install Flash Attention (ROCm)** (legacy architectures), an **Install ROCm Development SDK** step, and an **Install bitsandbytes (ROCm)** step for Python 3.12 environments.
+- **Packages:** ComfyUI, Stable Diffusion WebUI Reforge, InvokeAI, SwarmUI, and Wan2GP are supported by this install path.
+  > [!NOTE] While not managed by Stability Matrix for ROCm installs, SD.Next has a Windows-native ROCm install when the "ROCm" Pytorch index is selected in Advanced Installation Options during initial package install and `--use-rocm` is set in launch options. This install path is internally handled by SD.Next itself and currently only supports RDNA2 dedicated GPUs, RDNA3, RDNA3.5, and RDNA4 GPUs.
 
 **Caveats:**
 
-- Windows AMD ROCm is explicitly experimental. Stability Matrix prints a notice asking you to report issues to Stability Matrix first, since the setup may not be officially supported by the upstream package developers.
-- Only the architectures listed above are eligible. If your AMD GPU is not on the list, the recommended default becomes ZLUDA or DirectML instead.
+- Windows AMD ROCm implementation for Stability Matrix is explicitly in an experimental state. While these package installations are generally in a working state, untested or edge-case issues and incompatibilities may appear. Stability Matrix prints a notice asking you to report issues to Stability Matrix first, since the setup may not be officially supported by the upstream package developers.
+- Only the architectures listed above are eligible. If your AMD GPU is not on the list, the recommended default becomes ZLUDA or DirectML instead. For a more detailed list of compatible AMD GPU architectures, please refer to the ROCm/TheRock [GPU Support](https://github.com/ROCm/TheRock/blob/main/SUPPORTED_GPUS.md#rocm-on-windows) table.
 
 ### ZLUDA
 

docs/getting-started/overview.md

@@ -43,7 +43,7 @@ Stability Matrix is cross-platform, but the exact release formats and hardware t
 | Operating System | Version / Target | Architecture | Notes |
 |---|---|---|---|
 | Windows | Windows 10 and Windows 11 | x64 | Official release builds are published for `win-x64`. This is the broadest-supported desktop target for Stability Matrix and most package workflows. |
-| Linux | Modern x86-64 desktop distributions | x64 | Official Linux releases are published for `linux-x64`, primarily as an AppImage, with an AUR package also available for Arch-based systems. Depending on the distribution, AppImage/runtime support packages such as `libfuse2`, `libappimage`, or `libxcrypt-compat` may be needed if they are not already provided by the system. |
+| Linux | Modern x86-64 desktop distributions | x64 | Official Linux releases are published for `linux-x64`, primarily as an AppImage, with an AUR package also available for Arch-based systems. Depending on the distribution, runtime support packages such as `fuse3` or `libxcrypt-compat` may be needed if they are not already provided by the system. |
 | macOS | Apple Silicon Macs, with macOS 12.3 or later recommended for AI workflows | arm64 | Official macOS releases are published for Apple Silicon (`osx-arm64`) as a `.dmg`. The app's AI workflows rely on the MPS backend on Apple Silicon. |
 
 In other words, the practical supported release targets are Windows x64, Linux x64, and Apple Silicon macOS. Some project files include additional runtime identifiers, but the documented source-build support and the release pipeline currently focus on `win-x64`, `linux-x64`, and `osx-arm64`. For work from a local checkout instead of a packaged release, a planned Building from Source and Contributing page will serve as the documentation entry point and link to the repository's contributor guide.

docs/package-manager/installing-packages.md

@@ -96,7 +96,7 @@ The **PyTorch backend** determines which GPU acceleration library your package u
 | Backend | Platform | GPU | Notes |
 |---------|----------|-----|-------|
 | **CUDA** | Windows, Linux | NVIDIA (GTX 900-series and newer) | Best performance and broadest compatibility. CUDA toolkit is bundled with PyTorch; no separate driver installation beyond standard NVIDIA drivers. Turing (RTX 2000-series) or newer recommended. |
-| **ROCm** | Windows, Linux | AMD (select GPUs per platform) | Native AMD GPU acceleration. On Linux, requires system-level ROCm installation. On Windows, uses AMD's TheRock technical preview builds. Per-chip compatibility details are planned for a future Hardware Support page. |
+| **ROCm** | Windows, Linux | AMD (select GPUs per platform) | Native AMD GPU acceleration. On Linux, requires system-level ROCm installation. Package support is more limited on Windows. Per-chip compatibility details are planned for a future Hardware Support page. |
 | **DirectML** | Windows | AMD, Intel, some NVIDIA | Microsoft's DirectML API. Broad compatibility but slower performance than CUDA or ROCm. Development is largely stagnant; consider native ROCm, or ZLUDA if need be, as an alternative for AMD GPUs. |
 | **ZLUDA** | Windows | AMD (via CUDA translation layer) | Experimental CUDA-to-AMD translation layer. Used by the ComfyUI-Zluda, SD.Next, and AMDGPU Forge packages. Generally faster than DirectML for supported operations. |
 | **IPEX** | Windows, Linux | Intel Arc (discrete and integrated) | Intel Extension for PyTorch. Requires Intel Arc GPU (A-series, B-series) or modern Intel Core Ultra with integrated Arc graphics. |