Merge pull request #3 from LykosAI/docs-review-fixups

docs: review fixups — factual corrections, link hygiene, and a few new pages

Author: NeuralFault

docs/README.md

@@ -2,8 +2,8 @@
 
 Stability Matrix is a multi-platform package manager for Stable Diffusion and related AI image/video generation tools. This documentation covers all major features and sections of the application.
 
-This docuemtation is intended to provide a detailed guide and explaination of the many functions of Stability Matrix, its installation and use for both new and current users, and also more detailed and technical material for advanced users.
-While it contains information on a vast majority of application specific functions, It also contains information that applies to AI image, video, and related generation aspects that can be useful both inside and outside of Stability Matrix.
+This documentation is intended to provide a detailed guide and explanation of the many functions of Stability Matrix, its installation and use for both new and current users, and also more detailed and technical material for advanced users.
+While it contains information on a vast majority of application specific functions, it also contains information that applies to AI image, video, and related generation aspects that can be useful both inside and outside of Stability Matrix.
 While not all encompassing on every minute detail, it is intended to be updated as new features and changes are released to the project as well as new ecosystem/model/usage information as-needed.
 
 Current Status: In-progress - Structure is in-place and planned docs are currently being progressively created and added.
@@ -20,57 +20,61 @@ Current Status: In-progress - Structure is in-place and planned docs are current
 - [Overview](package-manager/overview.md) — Managing AI packages in Stability Matrix
 - [Supported Packages](package-manager/supported-packages.md) — Full list of supported inference and training packages
 - [Installing Packages](package-manager/installing-packages.md) — One-click install, hardware selection, GPU backends
-- [Managing Packages](package-manager/managing-packages.md) — Launching, monitoring, updating, and deleting installed packages
-- [Launch Arguments](package-manager/launch-arguments.md) — Configuring launch arguments per package
-- [Extensions](package-manager/extensions.md) — Browsing and managing package plugins and extensions
+- Managing Packages *(planned)* — Launching, monitoring, updating, and deleting installed packages
+- Launch Arguments *(planned)* — Configuring launch arguments per package
+- Extensions *(planned)* — Browsing and managing package plugins and extensions
 
 ### Inference
 - [Overview](inference/overview.md) — The Inference UI, panel layout, and project files
-- [Text to Image](inference/text-to-image.md) — Generating images from text prompts
-- [Image to Image](inference/image-to-image.md) — Using an image as a generation starting point
-- [Image Upscale](inference/image-upscale.md) — Upscaling images with AI upscaler models
-- [Video Generation](inference/video-generation.md) — Generating video with WAN and SVD models
-- [Advanced Controls](inference/advanced-controls.md) — ControlNet, FaceDetailer, FreeU, LayerDiffuse, and more
+- Text to Image *(planned)* — Generating images from text prompts
+- Image to Image *(planned)* — Using an image as a generation starting point
+- Image Upscale *(planned)* — Upscaling images with AI upscaler models
+- Video Generation *(planned)* — Generating video with WAN and SVD models
+- Advanced Controls *(planned)* — ControlNet, FaceDetailer, FreeU, LayerDiffuse, and more
 
 ### Checkpoint Manager
-- [Overview](checkpoint-manager/overview.md) — Centralized model storage shared across all packages
-- [Model Categories](checkpoint-manager/model-categories.md) — All supported model folder types explained
-- [Metadata Editing](checkpoint-manager/metadata-editing.md) — Importing CivitAI metadata and editing model info
+- Overview *(planned)* — Centralized model storage shared across all packages
+- Model Categories *(planned)* — All supported model folder types explained
+- Metadata Editing *(planned)* — Importing CivitAI metadata and editing model info
 
 ### Model Browser
-- [Overview](model-browser/overview.md) — Multi-source model browser and download queue
-- [CivitAI](model-browser/civitai.md) — Browsing and downloading from CivitAI
-- [HuggingFace](model-browser/huggingface.md) — Browsing and downloading from HuggingFace
-- [OpenModelDB](model-browser/openmodeldb.md) — Browsing upscaler models from OpenModelDB
+- Overview *(planned)* — Multi-source model browser and download queue
+- CivitAI *(planned)* — Browsing and downloading from CivitAI
+- HuggingFace *(planned)* — Browsing and downloading from HuggingFace
+- OpenModelDB *(planned)* — Browsing upscaler models from OpenModelDB
 
 ### Outputs
-- [Overview](outputs/overview.md) — Image gallery, sorting, filtering, and batch operations
-- [Image Metadata](outputs/image-metadata.md) — Reading embedded generation parameters and ComfyUI node data
+- Overview *(planned)* — Image gallery, sorting, filtering, and batch operations
+- Image Metadata *(planned)* — Reading embedded generation parameters and ComfyUI node data
 
 ### Workflows
-- [Overview](workflows/overview.md) — Browsing and managing ComfyUI workflows
-- [Community Workflows](workflows/community-workflows.md) — Browsing community workflows via OpenArt
+- Overview *(planned)* — Browsing and managing ComfyUI workflows
+- Community Workflows *(planned)* — Browsing community workflows via OpenArt
 
 ### Settings
-- [Overview](settings/overview.md) — Navigating the settings hub
-- [General](settings/general.md) — Theme, language, data directory, and shared folder settings
-- [Accounts](settings/accounts.md) — Lykos account, OAuth login, and API tokens
-- [Inference Settings](settings/inference-settings.md) — Inference UI behavior and defaults
-- [Updates](settings/updates.md) — Auto-update channel and frequency 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
 
 ### Advanced
-- [Building from Source and Contributing](advanced/building-from-source.md) — Local builds, runtime targets, and where to start for code or docs contributions
-- [Shared Folders](advanced/shared-folders.md) — Folder structure, symlinks, and cross-package model sharing
+- [Overview](advanced/overview.md) — Advanced configuration and technical reference
+- Building from Source and Contributing *(planned)* — Local builds, runtime targets, and where to start for code or docs contributions
+- Shared Folders *(planned)* — Folder structure, symlinks, and cross-package model sharing
 - [Hardware Support](advanced/hardware-support.md) — CUDA, ROCm, DirectML, MPS, ZLUDA, IPEX, and CPU backends
-- [Python Environment](advanced/python-environment.md) — Virtual environments, uv, pip, and Python version management
+- Python Environment *(planned)* — Virtual environments, uv, pip, and Python version management
 - [ComfyUI Integration](advanced/comfyui-integration.md) — ComfyUI node API, WebSocket protocol, and custom nodes
 - [Environment Variables](advanced/environment-variables.md) — Per-package environment variable configuration
 
 ### Tips and Tricks
 - [Overview](tips/overview.md) — Tips and Tricks index
 - [Terminology](tips/terminology.md) — Common image generation terms and what they mean
-- [Inference UI Tips](tips/inference-ui.md) — Effective use of the built-in Inference UI
-- [Per-Package Tips](tips/per-package.md) — Package-specific tips and links to upstream documentation
-- [AMD GPU Workflow](tips/amd-gpu-workflow.md) — Getting image and video generation working on AMD hardware
-- [Model Dependencies](tips/model-dependencies.md) — Required secondary files for modern models (text encoders, VAEs, etc.)
-- [VRAM Optimization](tips/vram-optimization.md) — Reducing VRAM usage without sacrificing too much quality or speed
+- Inference UI Tips *(planned)* — Effective use of the built-in Inference UI
+- Per-Package Tips *(planned)* — Package-specific tips and links to upstream documentation
+- AMD GPU Workflow *(planned)* — Getting image and video generation working on AMD hardware
+- Model Dependencies *(planned)* — Required secondary files for modern models (text encoders, VAEs, etc.)
+- VRAM Optimization *(planned)* — Reducing VRAM usage without sacrificing too much quality or speed
+
+### Troubleshooting
+- [Common Issues](troubleshooting/common-issues.md) — Symptom-first fixes for install, launch, GPU, and Inference problems

docs/advanced/environment-variables.md

@@ -100,7 +100,7 @@ For ordinary Stability Matrix usage, the most practical variables here are `PYTO
 
 ## HuggingFace Cache Variables
 
-These variables are useful when a package downloads models, tokenizers, datasets, or other assets from the Hugging Face ecosystem. In Stability Matrix, the most common reasons to set them are moving caches off the system drive, forcing offline operation, or making Hub requests more reliable on slow connections. These are mainly to modify HuggingFace operations within Packages themselves (HF features built into WebUI's, HF download capable extensions/custom nodes)
+These variables are useful when a package downloads models, tokenizers, datasets, or other assets from the Hugging Face ecosystem. In Stability Matrix, the most common reasons to set them are moving caches off the system drive, forcing offline operation, or making Hub requests more reliable on slow connections. These mainly modify HuggingFace operations within packages themselves, such as HF features built into WebUIs or HF-download-capable extensions and custom nodes.
 
 Because Stability Matrix injects environment variables globally, remember that authentication or offline-mode settings here will affect every launched package that uses `huggingface_hub`, `transformers`, `datasets`, or a library built on top of them.
 
@@ -140,26 +140,32 @@ Most users should leave these alone unless they are troubleshooting a specific R
 | `MIOPEN_LOG_LEVEL` | `5` | Sets MIOpen log verbosity. Higher values provide more detailed internal logging and are useful when debugging solver selection, kernel compilation, or runtime failures. |
 | `MIOPEN_CHECK_NUMERICS` | `0x02` or `0x04` | Checks tensors for NaNs, infinities, and related numerical problems. This is useful when a ROCm workflow produces corrupted outputs or starts failing only on certain models or resolutions. |
 | `MIOPEN_GEMM_ENFORCE_BACKEND` | `5` | Overrides MIOpen's GEMM backend selection. This is an advanced tuning variable that can be useful when comparing rocBLAS and hipBLASLt behavior or isolating backend-specific regressions. |
-| `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 RDNA 3, RDNA 4, and newer 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. |
+| `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:
 
 `MIOPEN_FIND_MODE=2`
 
-`MIOPEN_SEARCH_CUTOFF=2`
+`MIOPEN_SEARCH_CUTOFF=1`
 
-`TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1` (RDNA3 and newer only)
+`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 and newer only)
+`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`
 
 
 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.
+
+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.
+
 For a broader reference, see the [official ROCm environment variable documentation](https://rocm.docs.amd.com/en/latest/reference/env-variables.html) and the [official MIOpen environment variable documentation](https://rocm.docs.amd.com/projects/MIOpen/en/latest/reference/env_variables.html).