docs: VitePress docs site + Azure SWA deploy workflow

.github/workflows/docs-site.yml

@@ -0,0 +1,73 @@
+name: Docs Site
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+concurrency:
+  group: docs-site-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_and_deploy:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    name: Build and deploy docs site
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build VitePress site
+        working-directory: docs
+        run: npx vitepress build .
+
+      - name: Deploy to Azure Static Web Apps
+        uses: Azure/static-web-apps-deploy@v1
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_DOCS }}
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          action: upload
+          app_location: 'docs/.vitepress/dist'
+          skip_app_build: true
+
+  build_check:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    name: Build check (docs site)
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build VitePress site
+        working-directory: docs
+        run: npx vitepress build .

docs/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+.vitepress/dist
+.vitepress/cache

docs/.vitepress/config.mts

@@ -0,0 +1,96 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Stability Matrix Docs',
+  description: 'Documentation for Stability Matrix, a multi-platform package manager for Stable Diffusion and related AI tools.',
+
+  // Keep README.md as the single source of truth for the home page content,
+  // while serving it at the site root (index.html) instead of /README.html.
+  rewrites: {
+    'README.md': 'index.md'
+  },
+
+  // Dead-link checking stays ON (default) so a future PR that breaks a
+  // relative link fails the build instead of shipping silently.
+  ignoreDeadLinks: false,
+
+  appearance: 'dark',
+
+  themeConfig: {
+    outline: 'deep',
+
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Getting Started', link: '/getting-started/overview' },
+      { text: 'Package Manager', link: '/package-manager/overview' },
+      { text: 'Inference', link: '/inference/overview' },
+      { text: 'Advanced', link: '/advanced/overview' },
+      { text: 'Tips and Tricks', link: '/tips/overview' },
+      { text: 'Troubleshooting', link: '/troubleshooting/common-issues' }
+    ],
+
+    sidebar: {
+      '/getting-started/': [
+        {
+          text: 'Getting Started',
+          items: [
+            { text: 'Overview', link: '/getting-started/overview' },
+            { text: 'Installation', link: '/getting-started/installation' },
+            { text: 'First Launch', link: '/getting-started/first-launch' },
+            { text: 'Data Directory', link: '/getting-started/data-directory' }
+          ]
+        }
+      ],
+      '/package-manager/': [
+        {
+          text: 'Package Manager',
+          items: [
+            { text: 'Overview', link: '/package-manager/overview' },
+            { text: 'Supported Packages', link: '/package-manager/supported-packages' },
+            { text: 'Installing Packages', link: '/package-manager/installing-packages' }
+          ]
+        }
+      ],
+      '/inference/': [
+        {
+          text: 'Inference',
+          items: [
+            { text: 'Overview', link: '/inference/overview' }
+          ]
+        }
+      ],
+      '/advanced/': [
+        {
+          text: 'Advanced',
+          items: [
+            { text: 'Overview', link: '/advanced/overview' },
+            { text: 'Hardware Support', link: '/advanced/hardware-support' },
+            { text: 'ComfyUI Integration', link: '/advanced/comfyui-integration' },
+            { text: 'Environment Variables', link: '/advanced/environment-variables' }
+          ]
+        }
+      ],
+      '/tips/': [
+        {
+          text: 'Tips and Tricks',
+          items: [
+            { text: 'Overview', link: '/tips/overview' },
+            { text: 'Terminology', link: '/tips/terminology' }
+          ]
+        }
+      ],
+      '/troubleshooting/': [
+        {
+          text: 'Troubleshooting',
+          items: [
+            { text: 'Common Issues', link: '/troubleshooting/common-issues' }
+          ]
+        }
+      ]
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/LykosAI/StabilityMatrix' }
+    ]
+  }
+})

docs/README.md

@@ -0,0 +1,80 @@
+# Stability Matrix Documentation
+
+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 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.
+
+## Table of Contents
+
+### Getting Started
+- [Overview](getting-started/overview.md) — What Stability Matrix is and what it can do and minimal requirements/recommendations on hardware
+- [Installation](getting-started/installation.md) — Installing on Windows, macOS, and Linux
+- [First Launch](getting-started/first-launch.md) — Walking through the setup wizard
+- [Data Directory](getting-started/data-directory.md) — Choosing and managing your data directory
+
+### Package Manager
+- [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 *(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 *(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 *(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 *(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 *(planned)* — Image gallery, sorting, filtering, and batch operations
+- Image Metadata *(planned)* — Reading embedded generation parameters and ComfyUI node data
+
+### Workflows
+- Overview *(planned)* — Browsing and managing ComfyUI workflows
+- 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
+
+### Advanced
+- [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 *(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 *(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/comfyui-integration.md

@@ -0,0 +1,103 @@
+# ComfyUI Integration
+
+The Stability Matrix Inference UI is built on top of ComfyUI's API and WebSocket protocol. Understanding this integration is useful if you want to use ComfyUI's own web interface, use the API directly, or troubleshoot connection issues.
+
+[`Section Overview`](overview.md) | [`Home`](../README.md)
+
+## Table of Contents
+
+- [How Stability Matrix Uses ComfyUI](#how-stability-matrix-uses-comfyui)
+- [ComfyUI as a Standalone Package](#comfyui-as-a-standalone-package)
+- [The ComfyUI Web Interface](#the-comfyui-web-interface)
+- [Custom Nodes](#custom-nodes)
+- [The ComfyUI API and WebSocket](#the-comfyui-api-and-websocket)
+
+---
+
+## How Stability Matrix Uses ComfyUI
+
+The Inference UI does not replace ComfyUI. It uses ComfyUI as its execution backend.
+
+When you configure a generation tab in Stability Matrix, the app builds a real ComfyUI prompt graph behind the scenes. The inference view models and modules assemble that graph with a node builder, adding the same kinds of nodes you would use manually in ComfyUI: model loaders, text encoders, samplers, VAE encode/decode steps, ControlNet preprocessors, image loaders, tiled VAE nodes, video nodes, and output preview nodes.
+
+In practical terms, that means:
+
+- every generation from the Inference UI is sent to ComfyUI as workflow-style node JSON
+- local input images are uploaded into ComfyUI's input area before execution when needed
+- some auxiliary files are copied into the local ComfyUI package directory when the workflow requires them
+- progress, active-node changes, and preview images are streamed back while the workflow is running
+- final outputs are fetched from ComfyUI after execution finishes, then saved by Stability Matrix with its own project and parameter metadata layered on top
+
+So the relationship is best understood as: Stability Matrix provides a curated native UI, while ComfyUI is the engine actually running the graph.
+
+The reverse is not fully symmetrical. Everything the Inference UI does is representable as a ComfyUI workflow, but not every arbitrary ComfyUI workflow is exposed through the Inference UI's built-in cards and panels.
+
+## ComfyUI as a Standalone Package
+
+ComfyUI is available as an installable package in Stability Matrix's Package Manager. When you launch that package through Stability Matrix, the Inference UI connects to it as its local backend.
+
+By default, the ComfyUI package uses host `127.0.0.1` and port `8188`, and the Inference client connects to `http://127.0.0.1:8188`. If you change the ComfyUI launch arguments inside Stability Matrix, the Inference UI reads those host and port values and connects to the configured address instead.
+
+This matters because the Inference UI is not tied to a hardcoded browser tab or embedded widget. It is a client talking to a running ComfyUI server. If the package is stopped, the Inference UI loses its backend. If the package is restarted, the Inference UI reconnects to that backend.
+
+Stability Matrix also knows when it is talking to a locally managed ComfyUI install. In that case it can:
+
+- upload inputs directly to the local package's `input` folder when needed
+- read outputs from the local `output` directory
+- manage custom-node installs through the package extension system
+- restart the package after extension changes when necessary
+
+## The ComfyUI Web Interface
+
+The Inference UI and the ComfyUI web interface are meant to coexist.
+
+Once the ComfyUI package is running, you can open ComfyUI's own browser-based node graph from the Launch page. That graph editor gives you direct access to the raw workflow layer, which is useful when you want to:
+
+- inspect or modify workflows beyond what the Inference UI currently exposes
+- use custom nodes or advanced graph structures that do not have native Inference UI cards
+- import or build community workflows directly in ComfyUI
+- debug a workflow at the node level
+
+This is one of the main strengths of the integration: you can start with Stability Matrix's simpler native controls, then move into ComfyUI's graph editor when you need lower-level control.
+
+Community and exported ComfyUI workflows are also commonly shared as JSON files. Those can be opened in ComfyUI directly, and they are often the easiest way to exchange complex graphs with other users.
+
+## Custom Nodes
+
+ComfyUI's functionality can be extended with custom nodes, and Stability Matrix is aware of that extension model.
+
+For ComfyUI packages installed through Stability Matrix, custom nodes live in the `custom_nodes` directory. You can install them in two common ways:
+
+- use the Extensions browser in Stability Matrix for the ComfyUI package
+- manually clone a node repository into `custom_nodes`
+
+Stability Matrix's ComfyUI package uses extension manifests for custom-node discovery. On new ComfyUI installs, ComfyUI Manager is also installed automatically through the package setup process, and the accompanying `--enable-manager` launch argument is enabled by default. That gives the ComfyUI side an in-browser extension manager out of the box.
+
+There is also a deeper integration point in the Inference UI itself: when a built workflow declares required Comfy extensions, Stability Matrix checks whether those extensions are already installed before the first batch runs. If required extensions are missing or version-constrained extensions are out of date, Stability Matrix can prompt you to install or update them and then restart the ComfyUI package so the changes take effect.
+
+This does not eliminate the need to understand custom nodes, but it does reduce some of the manual work when a workflow depends on specific ComfyUI extensions.
+
+## The ComfyUI API and WebSocket
+
+For advanced users, the integration is straightforward: Stability Matrix talks to ComfyUI over its normal local API and websocket endpoints.
+
+The main pieces used by Stability Matrix are:
+
+- REST base address: `http://127.0.0.1:8188/` by default
+- `POST /prompt` to submit the generated node graph for execution
+- `POST /interrupt` to cancel a running generation
+- `POST /upload/image` to send input images into ComfyUI
+- `GET /history/{promptId}` to retrieve executed outputs after the prompt finishes
+- `GET /view` to download output images returned by ComfyUI history
+- WebSocket at `ws://127.0.0.1:8188/ws?clientId=...` for live status, running-node changes, progress data, execution errors, and preview-image bytes
+
+In practice, the websocket is what makes the Inference UI feel live. It is how Stability Matrix receives step progress, node execution state, and preview frames while ComfyUI is still working.
+
+The REST side is used for the request-response parts of the workflow:
+
+- upload inputs
+- queue the prompt
+- interrupt if cancelled
+- fetch history and outputs when execution completes
+
+If you are troubleshooting connection issues, those are the paths to keep in mind. If you are building your own automation around a local ComfyUI instance, Stability Matrix is effectively using the same public backend surface that advanced users can script against themselves.