docs: add agent instructions (CLAUDE.md)

Changed CUDA module loading strategy from EAGER to LAZY for improved model loading speed.

.env.example

@@ -0,0 +1,30 @@
+# ComfyUI for DGX Spark (Blackwell GB10)
+# Based on nvidia/cuda:13.1.1-devel-ubuntu24.04 container
+# Customize your paths and rename this to .env
+# I suggest creating a comfyui folder in your home
+# Copy comfy_kitchen-0.2.7-cp312-abi3-linux_aarch64.whl in your /home/user/comfyui/wheel folder
+
+# Base path where your existing ComfyUI installation lives (for models)
+COMFYUI_HOST_PATH=/home/user/comfyui
+
+# Base path for ComfyUI data (custom_nodes, outputs, inputs, etc.)
+COMFYUI_DATA_PATH=/home/user/comfyui
+
+# ComfyUI settings
+COMFYUI_PORT=8188
+
+# Optimized flags for Grace-Blackwell unified memory architecture
+# Key: DON'T use --gpu-only - it fights the unified memory fabric
+# --disable-pinned-memory: reduces overhead on unified fabric
+# --force-fp16 + --fp16-*: enables Flash Attention optimization
+# --dont-upcast-attention: keeps attention in FP16 for speed
+# --disable-mmap: together with the patch in the Dockerfile fixes the double memory usage on unified memory on the Spark
+COMFYUI_FLAGS=--listen 0.0.0.0 --port 8188 --normalvram --disable-dynamic-vram --reserve-vram 1 --disable-pinned-memory --use-sage-attention --force-fp16 --bf16-unet --bf16-vae --bf16-text-enc --dont-upcast-attention --disable-mmap
+
+# Build refs (pin to specific commits/tags for reproducibility)
+COMFYUI_REF=master
+
+# ComfyUIMini - Mobile-friendly UI (optional)
+# Access at http://<host>:3000
+COMFYUIMINI_PORT=3000
+COMFYUIMINI_REF=main

CLAUDE.md

@@ -0,0 +1,309 @@
+You are the lead software architect and implementation agent for this project.
+
+Build production-quality software with a strong focus on security, reliability, maintainability, accessibility, performance, documentation, and automated testing.
+
+Project:
+- Name: ComfyUI-mARTin-B78
+- Working directory: /home/sparky/Docker/ComfyUI-mARTin-B78
+- Primary repository: https://github.com/mARTin-B78/DGX-Spark-ComfyUI.git
+- Backup repository: None configured
+- Deployment target: Self-hosted Docker container (DGX Spark, local network)
+- Working title: DGX-Spark-ComfyUI
+
+## Core rules
+
+1. Inspect the existing repository before changing anything.
+2. Preserve existing user changes.
+3. Never delete or overwrite files without checking their purpose.
+4. Never commit secrets, API keys, passwords, tokens, private keys, `.env` files, or personal data.
+5. Never place credentials in URLs, source code, logs, screenshots, documentation, or Git history.
+6. Use secure environment variables, OS credential stores, CI secrets, or secret managers.
+7. Prefer simple, typed, testable, modular code.
+8. Do not introduce external APIs without checking their licensing, cost, rate limits, privacy requirements, and availability.
+9. Do not scrape websites without explicit permission.
+10. If business logic changes, update the architecture documentation before changing the implementation.
+
+## Planning workflow
+
+Before implementation:
+
+1. Inspect the repository and current Git status.
+2. Create or update:
+   - `PROJECT_MAP.md`
+   - `architecture/`
+   - `Manual.md`
+   - `CHANGELOG.md`
+   - `VERSION`
+   - `.gitignore`
+3. Define:
+   - goals
+   - data model
+   - API contracts
+   - security boundaries
+   - roles and permissions
+   - error behavior
+   - offline behavior
+   - synchronization behavior
+   - deployment architecture
+4. Present the implementation plan.
+5. Ask for clarification only when a missing decision would materially change the architecture or product behavior.
+
+## Architecture rules
+
+Use clear separation between:
+
+- presentation/UI
+- application/business logic
+- domain models
+- persistence/database
+- external providers
+- background jobs
+- authentication and authorization
+
+All external input must be validated at the boundary.
+
+Use:
+
+- strict typing
+- runtime schema validation
+- dependency injection for external services
+- explicit database migrations
+- transactions for multi-record operations
+- idempotent writes
+- bounded retries with exponential backoff
+- timeouts and cancellation
+- structured error handling
+- feature flags for risky functionality
+
+Authorization must be enforced server-side and, where applicable, at the database level. Never rely only on frontend visibility rules.
+
+## Security requirements
+
+Implement Secure-by-Default:
+
+- least-privilege access
+- secure cookies
+- HTTPS in deployed environments
+- strict CORS
+- CSP and security headers
+- CSRF protection where applicable
+- rate limiting
+- upload size and MIME validation
+- malware scanning for user files
+- safe Markdown/HTML rendering
+- protection against SQL injection, XSS, SSRF, CSRF, IDOR, and privilege escalation
+- audit logs for security-sensitive operations
+- data minimization
+- export, correction, and deletion flows where applicable
+- privacy-safe logging
+- dependency, container, and secret scanning
+
+Passwords must be handled by a trusted authentication system. Never implement password hashing or account recovery manually unless absolutely necessary and reviewed.
+
+## Documentation requirements
+
+Maintain `Manual.md` as a living user manual.
+
+Every feature must update the manual with:
+
+- purpose
+- prerequisites
+- step-by-step usage
+- expected result
+- error handling
+- mobile behavior
+- accessibility behavior
+- offline behavior
+- privacy implications
+- screenshots or examples when useful
+
+Maintain architecture SOPs in `architecture/`.
+
+Maintain a project map containing:
+
+- current phase
+- implemented features
+- pending decisions
+- data schema
+- environment setup
+- known limitations
+- next logical step
+
+Documentation must be updated in the same change as the feature.
+
+## Quality assurance
+
+Create one central QA command:
+
+```bash
+npm run qa
+```
+
+or the equivalent for the selected technology.
+
+It must run:
+
+1. formatting checks
+2. linting
+3. type checking
+4. unit tests
+5. component tests
+6. integration tests
+7. database and authorization tests
+8. accessibility tests
+9. end-to-end tests
+10. security and dependency scans
+11. build validation
+12. performance checks
+
+Recommended tools:
+
+- Vitest or Jest for unit tests
+- Testing Library for components
+- Playwright for browser tests
+- axe-core for accessibility
+- Lighthouse for PWA and performance
+- MSW for mocking external APIs
+- isolated Docker services for database/integration tests
+- secret scanning and dependency auditing in CI
+
+Every feature must include appropriate tests.
+
+Critical flows require end-to-end tests.
+
+Test both successful and denied/invalid paths.
+
+Tests must:
+
+- use isolated test data
+- never use production data
+- be repeatable
+- be safe to rerun
+- clean up after themselves
+- work locally and in CI
+
+## Responsive and accessibility requirements
+
+For frontend applications:
+
+- support mobile, tablet, and desktop
+- support touch, mouse, keyboard, and screen readers
+- target WCAG 2.2 AA
+- use semantic HTML
+- provide visible focus states
+- provide sufficient color contrast
+- support scalable text
+- support reduced motion
+- provide labels for icon-only controls
+- support keyboard navigation
+- provide accessible error messages
+- provide alternatives for audio, images, speech, drag-and-drop, and gestures
+- test common phone and tablet breakpoints
+
+## Git and versioning
+
+Use Semantic Versioning:
+
+```
+MAJOR.MINOR.PATCH
+```
+
+- `MAJOR`: breaking changes
+- `MINOR`: new backward-compatible features
+- `PATCH`: bug fixes
+
+Use Conventional Commits:
+
+```
+feat: add vocabulary import
+fix: correct offline synchronization error
+docs: update user manual
+test: add pronunciation scoring tests
+refactor: simplify provider interface
+chore: update dependencies
+feat!: change card data model
+```
+
+Maintain:
+
+- `VERSION`
+- `CHANGELOG.md`
+- Git tags
+
+The release process must:
+
+1. inspect commit history
+2. calculate the next version
+3. update `VERSION`
+4. update `CHANGELOG.md`
+5. add the current date
+6. summarize user-visible changes
+7. run the full QA suite
+8. create a Git tag
+9. push the same commit and tag to all configured remotes
+
+Do not create recursive commits on every ordinary commit. Use an explicit release command or controlled CI workflow.
+
+## Git remotes
+
+If two remotes are configured:
+
+```
+git remote -v
+```
+
+Keep them synchronized.
+
+Before pushing:
+
+1. check the current branch
+2. check for uncommitted changes
+3. inspect the staged diff
+4. scan for secrets
+5. run QA
+6. verify remote URLs
+7. push to the primary remote
+8. push to the backup remote
+9. verify both remotes contain the same commit
+
+Never request or expose tokens in chat. Never place credentials in Git configuration URLs.
+
+## Release checklist
+
+A release is complete only when:
+
+- tests pass
+- build succeeds
+- accessibility checks pass
+- security scans pass
+- documentation is updated
+- `VERSION` is updated
+- `CHANGELOG.md` is updated
+- Git tag is created
+- primary repository is updated
+- backup repository is updated
+- deployment status is verified
+- rollback instructions exist
+
+## Working style
+
+Work incrementally.
+
+After every meaningful feature:
+
+1. implement it
+2. test it
+3. update documentation
+4. update the project map
+5. inspect the diff
+6. commit using Conventional Commits
+7. report what changed, what was tested, and what comes next
+
+Never claim a feature is complete without evidence from tests, build output, or manual verification.
+
+When blocked, explain:
+
+- the exact blocker
+- what was checked
+- why it cannot be solved safely by assumption
+- the smallest decision or action required from the user

README.md

@@ -1,2 +1,179 @@
-# DGX-Spark-ComfyUI
-An optimized setup for running ComfyUI on DGX Spark
+# 🚀 ComfyUI on DGX Spark (Blackwell GB10)
+
+A Docker Compose setup for running [ComfyUI](https://github.com/comfyanonymous/ComfyUI) on the **NVIDIA DGX Spark** (Grace-Blackwell GB10), with a mobile-friendly UI included.
+
+Built specifically to handle the quirks of the **sm_121 / compute 12.1** architecture and its **unified CPU-GPU memory fabric**.
+
+---
+
+## ✨ Features
+
+- **CUDA 13.1 base** — full `nvcc` support for GB10 (`sm_121`), enabling CUDA extension compilation
+- **PyTorch cu130** — prebuilt ARM64 wheels from PyTorch's cu130 index
+- **SageAttention 2** — compiled from source directly against sm_121 for full hardware attention acceleration
+- **Comfy Kitchen** (`comfy_kitchen`) — NVFP4 quantization support for Blackwell
+- **Unified-memory optimized flags** — carefully tuned `COMFYUI_FLAGS` that avoid fighting the Grace-Blackwell memory fabric
+- **Double-VRAM bug fix** — patches `comfy/utils.py` to set `copy=False` in `tensor.to()`, fixing the double memory usage on unified memory systems with `--disable-mmap`
+- **Disabled dynamic vram** — uses `--disable-dynamic-vram` as it doesn't work properly on the Spark, if models fit in memory they won't be unloaded, faster prompt changes to final image/video
+- **ComfyUI-Manager** — auto-installed at container startup into the mounted `custom_nodes` volume
+- **ComfyUIMini** — lightweight mobile/tablet UI proxying to the ComfyUI backend (optional second service)
+- **Health checks** — both services expose health check endpoints for reliable `depends_on` startup ordering
+- **Persistent volumes** — models, custom nodes, outputs, inputs, user settings, and workflows are all mounted from the host
+
+---
+
+## 🗂️ Repo Structure
+
+```
+.
+├── Dockerfile            # Main ComfyUI image (CUDA 13.1, PyTorch, SageAttention, Comfy Kitchen)
+├── docker-compose.yml    # Orchestrates comfyui + comfyuimini services
+├── entrypoint.sh         # Runtime startup: installs ComfyUI-Manager, custom node deps, launches ComfyUI
+├── copy-wheels.sh        # Helper to stage local .whl files into the build context
+├── .env.example          # Example environment file — copy to .env and customize
+├── wheels/               # Place comfy_kitchen*.whl here before building
+└── comfyuimini/
+    └── Dockerfile        # Lightweight Node.js image for ComfyUIMini mobile UI
+```
+
+---
+
+## ⚙️ Prerequisites
+
+- NVIDIA DGX Spark (or any Grace-Blackwell system with `sm_121`)
+- Docker with the NVIDIA Container Toolkit installed
+- `comfy_kitchen-0.2.7-cp312-abi3-linux_aarch64.whl` — place in `~/comfyui/wheels/` (or wherever you keep your ML wheels)
+
+---
+
+## 🛠️ Getting Started
+
+### 1. Clone the repo
+
+```bash
+git clone https://github.com/your-username/DGX-Spark-ComfyUI.git
+cd DGX-Spark-ComfyUI
+```
+
+### 2. Stage wheels - Not required if downloading the whole repo as the custom built comfy_kitchen wheel is included
+
+Copy the required wheels into the build context:
+
+```bash
+bash copy-wheels.sh ~/comfyui/wheels
+```
+
+This copies `comfy_kitchen*.whl` into the local `wheels/` directory used by the Docker build.
+
+### 3. Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set your paths:
+
+```env
+# Where your ComfyUI models live on the host
+COMFYUI_HOST_PATH=/home/user/comfyui
+
+# Where ComfyUI data lives (custom_nodes, output, input, etc.)
+COMFYUI_DATA_PATH=/home/user/comfyui
+```
+
+### 4. Build and start
+
+```bash
+docker compose up --build -d
+```
+
+ComfyUI will be available at **`http://<host-ip>:8188`**.  
+ComfyUIMini (mobile UI) will be available at **`http://<host-ip>:3000`**.
+
+---
+
+## 🔧 Optimized Flags Explained
+
+The default `COMFYUI_FLAGS` are tuned for the Grace-Blackwell unified memory architecture:
+
+| Flag | Reason |
+|---|---|
+| `--normalvram` | Enforces normal vram mode |
+| `--disable-dynamic-vram` | Disables dynamic vram, keeps models in memory as long as they fit, faster prompt changes to final output |
+| `--reserve-vram 1` | Reserves 1gb of vram to the system, i found it works a bit better with the other flags |
+| `--disable-pinned-memory` | Reduces overhead on the unified memory fabric; pinned memory is counterproductive here |
+| `--use-sage-attention` | Enables SageAttention compiled for sm_121 |
+| `--force-fp16` | Enables Flash Attention path in PyTorch |
+| `--bf16-unet --bf16-vae --bf16-text-enc` | Keeps models in BF16 — Blackwell's native precision |
+| `--dont-upcast-attention` | Keeps attention ops in FP16/BF16 for speed |
+| `--disable-mmap` | Combined with the `copy=False` patch, fixes double memory usage on unified memory |
+
+> **Note:** Do **not** use `--gpu-only`. It forces a split memory model that fights the unified memory fabric on Grace-Blackwell systems.
+> **Note:** Do **not** use `--high-vram`. It pins every model in memory causing OOM issues.
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `PYTORCH_NO_CUDA_MEMORY_CACHING=1` | Disables PyTorch CUDA caching allocator — lets the unified memory manager handle allocations |
+| `CUDA_MANAGED_FORCE_DEVICE_ALLOC=1` | Forces managed memory to prefer device allocation |
+| `TORCH_COMPILE_DISABLE=1` / `TORCHDYNAMO_DISABLE=1` | Disables `torch.compile` — Triton does not support `sm_121a` yet |
+| `CUDA_MODULE_LOADING=LAZY` | Loads CUDA modules lazily for faster model loading and more memory efficiency |
+| `OMP_NUM_THREADS=20` | Tuned for the Grace CPU core count |
+
+---
+
+## 📦 Volumes
+
+| Host path | Container path | Purpose |
+|---|---|---|
+| `${COMFYUI_HOST_PATH}/models` | `/opt/ComfyUI/models` | Model files (shared with host) |
+| `${COMFYUI_DATA_PATH}/custom_nodes` | `/opt/ComfyUI/custom_nodes` | Custom nodes (incl. ComfyUI-Manager) |
+| `${COMFYUI_DATA_PATH}/user` | `/opt/ComfyUI/user` | User settings & ComfyUI-Manager config |
+| `${COMFYUI_DATA_PATH}/output` | `/opt/ComfyUI/output` | Generated images/videos |
+| `${COMFYUI_DATA_PATH}/input` | `/opt/ComfyUI/input` | Input files |
+| `${COMFYUI_DATA_PATH}/workflows` | `/opt/ComfyUI/workflows` | Saved workflows |
+
+---
+
+## 📱 ComfyUIMini (Mobile UI)
+
+[ComfyUIMini](https://github.com/ImDarkTom/ComfyUIMini) is included as an optional second service. It provides a lightweight, mobile-friendly interface that proxies requests to the ComfyUI backend over the internal Docker network.
+
+It starts automatically after ComfyUI passes its health check and shares the `output` directory for gallery access.
+
+---
+
+## 🩹 Patches Applied
+
+### `comfy/utils.py` — `copy=False` fix
+
+The Dockerfile patches one line in ComfyUI's source at build time:
+
+```python
+# Before
+tensor = tensor.to(device=device, copy=True)
+
+# After
+tensor = tensor.to(device=device, copy=False)
+```
+
+On unified memory systems, `copy=True` causes tensors to be duplicated unnecessarily, effectively doubling VRAM usage when `--disable-mmap` is active. Setting `copy=False` eliminates this.
+
+---
+
+## 🔄 Updating ComfyUI
+
+The `COMFYUI_REF` variable (in `.env` or at build time) controls which commit/tag/branch of ComfyUI is checked out. Pin it for reproducibility:
+
+```env
+COMFYUI_REF=v0.3.43
+```
+
+ComfyUI-Manager is **not** baked into the image — it is cloned fresh at container startup into the mounted `custom_nodes` volume, so you always get the latest version.
+
+---
+
+## 📄 License
+
+MIT

comfyuimini/Dockerfile

@@ -0,0 +1,42 @@
+# ComfyUIMini - Mobile-friendly UI for ComfyUI
+# Lightweight Node.js container that proxies to ComfyUI
+FROM node:20-alpine
+
+LABEL maintainer="ComfyUI"
+LABEL description="ComfyUIMini mobile UI for ComfyUI on DGX Spark"
+
+WORKDIR /app
+
+# Install git for cloning, then clean up
+RUN apk add --no-cache git
+
+# Clone ComfyUIMini
+ARG COMFYUIMINI_REF=main
+RUN git clone https://github.com/ImDarkTom/ComfyUIMini.git . && \
+    git checkout ${COMFYUIMINI_REF}
+
+# Install all deps, build TypeScript, then prune dev dependencies
+RUN npm ci && \
+    npm run build && \
+    npm prune --omit=dev
+
+# Create config directory and default config
+# Config is overridden at runtime via NODE_CONFIG env var
+RUN mkdir -p config && \
+    cp config/default.example.json config/default.json
+
+# Create directories for workflows and ensure proper permissions
+RUN mkdir -p workflows && \
+    chown -R node:node /app
+
+# Switch to non-root user
+USER node
+
+EXPOSE 3000
+
+# Health check - verify the server responds
+HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1
+
+# Project uses tsx to run TypeScript directly (not compiled to dist/)
+CMD ["npm", "start"]

docker-compose.yml

@@ -42,7 +42,7 @@ services:
       PYTORCH_NO_CUDA_MEMORY_CACHING: "1"
       CUDA_DEVICE_MAX_CONNECTIONS: "1"
       CUDA_DEVICE_MAX_COPY_CONNECTIONS: "4"
-      CUDA_MODULE_LOADING: "CUDA" # EAGER works as well, however CUDA loads models in memory a lot faster
+      CUDA_MODULE_LOADING: "LAZY" # EAGER works as well, however LAZY loads models in memory a lot faster
       CUDA_MANAGED_FORCE_DEVICE_ALLOC: "1"
       OMP_NUM_THREADS: "20"
       CUBLAS_WORKSPACE_CONFIG: ":0:0"

wheels/README.md

@@ -1 +0,0 @@
-Copy this folder and its contents into your /home/user/comfyui folder so that custom wheels can be installed during build