Add GenAI: ComfyUI and FaceFusion local tooling

.gitignore

@@ -42,3 +42,19 @@ notification.mp3
 /cache
 trace.json
 /sysinfo-????-??-??-??-??.json
+
+# GenAI project (local runtime, models, media)
+/GenAI/runtime/
+/GenAI/runtime/**
+/GenAI/models/**/*
+!/GenAI/models/README.md
+/GenAI/inputs/**/*
+!/GenAI/inputs/README.md
+/GenAI/outputs/**/*
+!/GenAI/outputs/README.md
+/GenAI/logs/**/*
+!/GenAI/logs/README.md
+/GenAI/config/settings.env
+/GenAI/config/local-paths.json
+/GenAI/config/model-manifest.json
+/GenAI/config/facefusion.ini

GenAI/.gitignore

@@ -0,0 +1,64 @@
+# Local configuration
+config/settings.env
+config/local-paths.json
+config/facefusion.ini
+config/model-manifest.json
+
+# Runtime clones and environments
+runtime/comfyui/
+runtime/facefusion/
+runtime/environments/
+runtime/facefusion-temp/
+
+# Models and caches
+models/**/*.ckpt
+models/**/*.safetensors
+models/**/*.onnx
+models/**/*.pth
+models/**/*.pt
+models/**/*.bin
+models/**/*.gguf
+models/**/.cache/
+**/.hf_cache/
+**/.cache/huggingface/
+
+# User media (never commit private faces or outputs)
+inputs/**/*
+!inputs/README.md
+!inputs/**/.gitkeep
+outputs/**/*
+!outputs/README.md
+!outputs/**/.gitkeep
+
+# Logs and secrets
+logs/**/*
+!logs/README.md
+!logs/**/.gitkeep
+*.env
+!config/settings.example.env
+secrets/
+tokens/
+*.pem
+*.key
+
+# Generated and temporary
+**/__pycache__/
+**/*.pyc
+**/.pytest_cache/
+**/temp/
+**/tmp/
+**/*.tmp
+benchmark/
+
+# OS and IDE
+.DS_Store
+Thumbs.db
+desktop.ini
+.vscode/
+.idea/
+
+# Installers
+*.exe
+*.msi
+*.dmg
+*.pkg

GenAI/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.0] - 2026-06-14
+
+### Added
+- Initial GenAI project scaffold
+- ComfyUI v0.9.2 and FaceFusion 3.6.1 upstream pins
+- Windows PowerShell and macOS shell scripts (setup, launch, doctor, repair, reset, update, smoke-test)
+- Separate venv environments under `runtime/environments/`
+- Starter ComfyUI workflow and tutorial documentation
+- Configuration templates and validation tests
+- Architecture decision records (ADR-001 through ADR-004)
+
+### Not tested in CI
+- Full ComfyUI image generation (requires user checkpoint)
+- FaceFusion face swap (requires authorized local media)
+- Apple Silicon MPS / CoreML hardware acceleration
+- NVIDIA RTX 4090 CUDA acceleration

GenAI/README.md

@@ -0,0 +1,70 @@
+# GenAI
+
+Local generative-AI tooling for **ComfyUI** (Stable Diffusion workflows) and **FaceFusion** (image/video face swapping), isolated from the parent AUTOMATIC1111 WebUI in this repository.
+
+## What this project provides
+
+| Component | Purpose | Upstream pin |
+|-----------|---------|--------------|
+| ComfyUI | Stable Diffusion workflow interface | [v0.9.2](https://github.com/comfyanonymous/ComfyUI/releases/tag/v0.9.2) |
+| FaceFusion | Authorized face swap (image + video) | [3.6.1](https://github.com/facefusion/facefusion/releases/tag/3.6.1) |
+
+- **Separate Python environments** for ComfyUI and FaceFusion
+- **Windows (RTX 4090)** and **macOS (Apple Silicon)** scripts
+- **Pinned upstream commits** in `upstreams.lock.json`
+- **Tutorials**, starter workflows, diagnostics, and repair tooling
+
+FaceFusion is the **only** supported face-swapping application in this project. Roop and Roop-derived extensions are intentionally excluded.
+
+## Quick start (Windows + NVIDIA)
+
+```powershell
+cd GenAI
+.\scripts\windows\setup-all.ps1
+.\scripts\windows\doctor.ps1
+.\scripts\windows\launch-comfyui.ps1
+```
+
+Place a checkpoint in `models/comfyui/checkpoints/` (see [models/README.md](models/README.md)), then load `workflows/comfyui/beginner-text-to-image.json` in ComfyUI.
+
+## Quick start (macOS Apple Silicon)
+
+```bash
+cd GenAI
+chmod +x scripts/macos/*.sh scripts/lib/common.sh
+./scripts/macos/setup-all.sh
+./scripts/macos/doctor.sh
+./scripts/macos/launch-comfyui.sh
+```
+
+## Configuration
+
+1. Copy `config/settings.example.env` → `config/settings.env` (auto-created on first setup)
+2. Copy `config/local-paths.example.json` → `config/local-paths.json`
+3. Default bind address: **127.0.0.1** (localhost only)
+
+## Scripts
+
+| Action | Windows | macOS |
+|--------|---------|-------|
+| Setup all | `setup-all.ps1` | `setup-all.sh` |
+| Launch ComfyUI | `launch-comfyui.ps1` | `launch-comfyui.sh` |
+| Launch FaceFusion | `launch-facefusion.ps1` | `launch-facefusion.sh` |
+| Diagnostics | `doctor.ps1` | `doctor.sh` |
+| Smoke tests | `smoke-test.ps1` | `smoke-test.sh` |
+| Repair envs | `repair.ps1` | `repair.sh` |
+| Reset runtime | `reset-runtime.ps1 -Confirm` | `reset-runtime.sh --confirm` |
+
+## Documentation
+
+Start at [docs/00-start-here.md](docs/00-start-here.md).
+
+## Privacy and lawful use
+
+Use only consenting subjects, licensed media, or synthetic fixtures. See [docs/facefusion/10-consent-provenance-and-safety.md](docs/facefusion/10-consent-provenance-and-safety.md).
+
+## Relationship to parent repo
+
+This `GenAI/` tree is **additive** and self-contained. It does not require changes to AUTOMATIC1111 WebUI files (`webui-user.bat`, `modules/`, etc.). If your working tree has unrelated local edits to those files, keep them separate from GenAI commits.
+
+**Port note:** FaceFusion defaults to **7861** to avoid conflicting with the parent WebUI default (**7860**).

GenAI/config/facefusion.example.ini

@@ -0,0 +1,10 @@
+[paths]
+temp_path =
+output_path =
+
+[execution]
+execution_providers =
+execution_device_ids = 0
+
+[uis]
+open_browser = true

GenAI/config/local-paths.example.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "runtimeRoot": "runtime",
+  "comfyui": {
+    "cloneDir": "runtime/comfyui",
+    "envDir": "runtime/environments/comfyui",
+    "modelsDir": "models/comfyui",
+    "inputDir": "inputs/comfyui",
+    "outputDir": "outputs/comfyui",
+    "logDir": "logs/comfyui"
+  },
+  "facefusion": {
+    "cloneDir": "runtime/facefusion",
+    "envDir": "runtime/environments/facefusion",
+    "modelsDir": "models/facefusion",
+    "inputDir": "inputs/facefusion",
+    "outputDir": "outputs/facefusion",
+    "tempDir": "runtime/facefusion-temp",
+    "logDir": "logs/facefusion"
+  }
+}

GenAI/config/model-manifest.example.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "models": [
+    {
+      "displayName": "SD 1.5 Base",
+      "category": "checkpoint",
+      "source": "https://huggingface.co/runwayml/stable-diffusion-v1-5",
+      "repository": "runwayml/stable-diffusion-v1-5",
+      "version": "v1-5",
+      "filename": "v1-5-pruned-emaonly.safetensors",
+      "SHA256": "",
+      "license": "CreativeML Open RAIL-M",
+      "baseModel": "SD1.5",
+      "intendedUse": "General text-to-image starter checkpoint",
+      "obtainedAt": "",
+      "notes": "Place in models/comfyui/checkpoints/. Accept Hugging Face license manually before download."
+    }
+  ]
+}

GenAI/config/settings.example.env

@@ -0,0 +1,20 @@
+# Copy to settings.env and adjust. settings.env is git-ignored.
+# All paths may contain spaces; quote values in shell scripts when exporting.
+
+GENAI_HOST=127.0.0.1
+COMFYUI_PORT=8188
+# Default 7861 avoids collision with parent A1111 WebUI (7860)
+FACEFUSION_PORT=7861
+
+# Performance profile: compatibility | balanced | performance
+GENAI_PROFILE=balanced
+
+# Windows FaceFusion execution provider: cuda | directml | cpu
+# macOS FaceFusion execution provider: coreml | cpu
+FACEFUSION_EXECUTION_PROVIDER=cuda
+
+# Optional external model root (leave empty to use GenAI/models only)
+EXTERNAL_MODEL_ROOT=
+
+# Reserved for future explicit update workflows (currently manual via upstreams.lock.json)
+UPDATE_CHANNEL=pinned

GenAI/docs/00-start-here.md

@@ -0,0 +1,52 @@
+# Start here
+
+Welcome to **GenAI** — a self-contained local stack for:
+
+1. **ComfyUI** — generate and edit images with Stable Diffusion workflows  
+2. **FaceFusion** — swap faces in images and videos (authorized use only)
+
+## Prerequisites
+
+### Windows (RTX 4090 target)
+- Windows 10/11, 64-bit
+- [Git for Windows](https://git-scm.com/download/win)
+- Python 3.10–3.12 with **Add to PATH**
+- Latest [NVIDIA driver](https://www.nvidia.com/drivers)
+- [FFmpeg](https://ffmpeg.org/download.html) (for FaceFusion video)
+- ~50 GB free disk (apps + models)
+
+### macOS (Apple Silicon target)
+- macOS 13+ recommended
+- Xcode Command Line Tools / Homebrew
+- Python 3.10–3.12, Git, FFmpeg (`brew install ffmpeg python@3.12 git`)
+
+## Installation path
+
+| Step | Windows | macOS |
+|------|---------|-------|
+| 1. Enter project | `cd GenAI` | `cd GenAI` |
+| 2. Setup | `.\scripts\windows\setup-all.ps1` | `./scripts/macos/setup-all.sh` |
+| 3. Verify | `.\scripts\windows\doctor.ps1` | `./scripts/macos/doctor.sh` |
+| 4. Add a checkpoint | See [models/README.md](../models/README.md) | Same |
+| 5. First image | [02-first-image.md](stable-diffusion/02-first-image.md) | Same |
+
+## Learning paths
+
+**Stable Diffusion (ComfyUI)**  
+→ [01-fundamentals.md](stable-diffusion/01-fundamentals.md) → [02-first-image.md](stable-diffusion/02-first-image.md) → [11-comfyui-fundamentals.md](stable-diffusion/11-comfyui-fundamentals.md)
+
+**FaceFusion**  
+→ [01-overview.md](facefusion/01-overview.md) → [02-first-image-face-swap.md](facefusion/02-first-image-face-swap.md) → [03-video-face-swap.md](facefusion/03-video-face-swap.md)
+
+## Important boundaries
+
+- This project **does not** replace the parent AUTOMATIC1111 WebUI in the repo root.
+- **Roop is not supported.** Use FaceFusion only.
+- Default network binding is **localhost** — do not expose to LAN without understanding the risk.
+- **Never commit** private faces, videos, or model weights to Git.
+
+## Get help
+
+- Diagnostics: `doctor.ps1` / `doctor.sh`
+- Static tests: `smoke-test.ps1` / `smoke-test.sh`
+- Troubleshooting: [stable-diffusion/15-troubleshooting.md](stable-diffusion/15-troubleshooting.md), [facefusion/09-troubleshooting.md](facefusion/09-troubleshooting.md)

GenAI/docs/01-system-overview.md

@@ -0,0 +1,60 @@
+# System overview
+
+```
+GenAI/
+├── config/           # Example + local settings (local files git-ignored)
+├── docs/             # Tutorials and architecture
+├── models/           # Checkpoints, LoRAs, FaceFusion weights (git-ignored contents)
+├── inputs/           # Your source media (git-ignored)
+├── outputs/          # Generated results (git-ignored)
+├── logs/             # Setup and runtime logs
+├── runtime/
+│   ├── comfyui/              # Cloned ComfyUI (git-ignored)
+│   ├── facefusion/           # Cloned FaceFusion (git-ignored)
+│   ├── environments/
+│   │   ├── comfyui/          # ComfyUI Python venv
+│   │   └── facefusion/       # FaceFusion Python venv
+│   └── facefusion-temp/      # Video frame temp (git-ignored)
+├── scripts/
+│   ├── windows/      # PowerShell entrypoints
+│   ├── macos/        # Bash entrypoints
+│   └── lib/          # Shared helpers
+├── tests/            # Static validation
+├── workflows/        # ComfyUI JSON + FaceFusion job examples
+└── upstreams.lock.json
+```
+
+## Data flow — ComfyUI
+
+1. Checkpoint in `models/comfyui/checkpoints/`
+2. Load workflow JSON in browser UI
+3. ComfyUI writes images to its output folder (configure Save Image node prefix)
+4. Generation metadata embedded in PNG when using default Save Image
+
+## Data flow — FaceFusion
+
+1. Source face + target image/video in `inputs/facefusion/`
+2. Launch FaceFusion UI or CLI
+3. Processed output in `outputs/facefusion/`
+4. Temp frames in `runtime/facefusion-temp/` during video jobs
+
+## Isolation guarantees
+
+| Concern | ComfyUI | FaceFusion |
+|---------|---------|------------|
+| Python venv | `runtime/environments/comfyui` | `runtime/environments/facefusion` |
+| Upstream clone | `runtime/comfyui` | `runtime/facefusion` |
+| Default port | 8188 | 7861 (Gradio) |
+| GPU stack | PyTorch CUDA / MPS | ONNX Runtime providers |
+
+Applications do not require each other to be running.
+
+## Configuration files
+
+| File | In Git | Purpose |
+|------|--------|---------|
+| `config/settings.example.env` | Yes | Template for host, ports, profile |
+| `config/settings.env` | No | Your overrides |
+| `config/local-paths.example.json` | Yes | Directory layout |
+| `config/local-paths.json` | No | Your path overrides |
+| `upstreams.lock.json` | Yes | Pinned upstream commits |