docs fixes

Author: vavo

Dockerfile

@@ -441,6 +441,7 @@ RUN set -eux; \
 
 # Copy app/UI sources late to improve build caching on frequent code changes
 COPY apps /opt/pilot/apps
+COPY docs /opt/pilot/docs
 COPY README.md /opt/pilot/README.md
 COPY CHANGELOG /opt/pilot/CHANGELOG
 

apps/Portal/app.py

@@ -602,23 +602,64 @@ async def add_no_cache_headers(request: Request, call_next):
 DOCS_ROOT_PRIMARY = Path("/opt/pilot/docs")
 DOCS_ROOT_FALLBACK = Path("/workspace/docs")
 DOCS_ROOT_DEV = Path(__file__).resolve().parents[2] / "docs"
+DOCS_ROOT_WORKSPACE_REPO = WORKSPACE_ROOT / "lora-pilot" / "docs"
+DOCS_ROOT_CWD = Path.cwd() / "docs"
+DOCS_ROOT_ENV = os.environ.get("DOCS_ROOT", "").strip()
 DOCS_SITEMAP_PRIMARY = DOCS_ROOT_PRIMARY / "README.md"
 DOCS_SITEMAP_FALLBACK = DOCS_ROOT_FALLBACK / "README.md"
 DOCS_SITEMAP_DEV = DOCS_ROOT_DEV / "README.md"
 
 
 def _docs_root_candidates() -> list[Path]:
     roots: list[Path] = []
-    for candidate in (DOCS_ROOT_PRIMARY, DOCS_ROOT_FALLBACK, DOCS_ROOT_DEV):
+    raw_candidates = [
+        DOCS_ROOT_PRIMARY,
+        DOCS_ROOT_FALLBACK,
+        DOCS_ROOT_DEV,
+        DOCS_ROOT_WORKSPACE_REPO,
+        DOCS_ROOT_CWD,
+    ]
+    if DOCS_ROOT_ENV:
+        raw_candidates.insert(0, Path(DOCS_ROOT_ENV))
+
+    for candidate in raw_candidates:
         try:
             resolved = candidate.resolve()
         except Exception:
             continue
         if resolved.exists() and resolved.is_dir():
-            roots.append(resolved)
+            if resolved not in roots:
+                roots.append(resolved)
     return roots
 
 
+def _build_docs_sitemap_fallback() -> str:
+    root = next(iter(_docs_root_candidates()), None)
+    if root is None:
+        return (
+            "# Documentation\n\n"
+            "Docs sitemap was not found in this runtime image.\n\n"
+            "- `docs/README.md`: Not found in runtime filesystem\n"
+            "- Set `DOCS_ROOT` to a valid docs directory if you mount docs externally.\n"
+            "- For bundled docs, use an image build that includes `docs/`.\n"
+        )
+
+    files = sorted(p for p in root.rglob("*.md") if p.is_file())
+    lines = [
+        "# Documentation",
+        "",
+        f"_Auto-generated sitemap from `{root}` because `docs/README.md` was not found._",
+        "",
+    ]
+    for p in files:
+        rel = p.relative_to(root).as_posix()
+        title = p.stem.replace("-", " ").replace("_", " ").strip().title() or rel
+        lines.append(f"- [{title}]({rel})")
+    if len(lines) == 4:
+        lines.append("- No markdown files found under resolved docs root.")
+    return "\n".join(lines) + "\n"
+
+
 def _validate_docs_relative_path(raw_path: str) -> Optional[PurePosixPath]:
     value = (raw_path or "").strip().replace("\\", "/")
     if not value:
@@ -2549,10 +2590,11 @@ def get_changelog():
 
 @app.get("/api/docs/sitemap")
 def get_docs_sitemap():
-    for candidate in (DOCS_SITEMAP_PRIMARY, DOCS_SITEMAP_FALLBACK, DOCS_SITEMAP_DEV):
+    for root in _docs_root_candidates():
+        candidate = root / "README.md"
         if candidate.exists():
             return {"content": candidate.read_text(encoding="utf-8"), "source": "docs/README.md"}
-    raise HTTPException(status_code=404, detail="docs/README.md not found")
+    return {"content": _build_docs_sitemap_fallback(), "source": "docs/README.md"}
 
 
 @app.get("/api/docs/file")

docs/components/README.md

@@ -1,200 +1,55 @@
-# Components Overview
-
-LoRA Pilot integrates multiple AI tools and services into a unified workspace. Each component serves a specific purpose in the AI workflow, from dataset preparation to model training and inference.
-
-## 🧩 Component Architecture
-
+# Components
+
+This section is the map of LoRA Pilot components. Keep this page as an index; use component pages for actual workflows and settings.
+
+## Component Index
+
+| Component | Role | Default Port/Route | Page |
+|---|---|---|---|
+| Kohya SS | Full training UI | `6666` | [Kohya SS](kohya-ss.md) |
+| AI Toolkit | Modern training stack | `8675` | [AI Toolkit](ai-toolkit.md) |
+| Diffusion Pipe | Experimental training + TensorBoard | `4444` | [Diffusion Pipe](diffusion-pipe.md) |
+| ComfyUI | Node-based inference | `5555` | [ComfyUI](comfyui.md) |
+| InvokeAI | UI-first inference | `9090` | [InvokeAI](invokeai.md) |
+| TrainPilot | Guided Kohya launcher | ControlPilot tab | [TrainPilot](trainpilot.md) |
+| TagPilot | Dataset prep/tagging | `/tagpilot/` on `7878` | [TagPilot](tagpilot.md) |
+| MediaPilot | Output curation/gallery | `/mediapilot/` on `7878` | [MediaPilot](mediapilot.md) |
+| Copilot Sidecar | Optional coding assistant backend | `7879` (internal/local) | [Copilot Sidecar](copilot-sidecar.md) |
+
+## How They Fit Together
+
+1. Prepare data in TagPilot.
+2. Train with TrainPilot/Kohya/AI Toolkit/Diffusion Pipe.
+3. Generate in ComfyUI or InvokeAI.
+4. Review and curate in MediaPilot.
+
+## Shared Paths
+
+All components are wired to the same workspace:
+- `/workspace/models`
+- `/workspace/datasets`
+- `/workspace/outputs`
+- `/workspace/config`
+- `/workspace/logs`
+
+## Quick Ops
+
+```bash
+# Service state
+docker exec lora-pilot supervisorctl status
+
+# Logs
+docker exec lora-pilot tail -n 200 /workspace/logs/controlpilot.out.log
+docker exec lora-pilot tail -n 200 /workspace/logs/comfy.out.log
+docker exec lora-pilot tail -n 200 /workspace/logs/invoke.out.log
 ```
-LoRA Pilot
-├── Training Components
-│   ├── Kohya SS - Traditional LoRA trainer
-│   ├── AI Toolkit - Modern training stack
-│   └── Diffusion Pipe - Scalable pipeline
-├── Inference Components
-│   ├── ComfyUI - Node-based inference
-│   └── InvokeAI - User-friendly interface
-├── Management Components
-│   ├── ControlPilot - Central dashboard
-│   ├── TrainPilot - Training automation
-│   ├── TagPilot - Dataset tagging
-│   └── MediaPilot - Media management
-└── Development Components
-    ├── JupyterLab - Notebook environment
-    ├── Code Server - VS Code in browser
-    └── Copilot Sidecar - AI assistant
-```
-
-## 🎯 Component Matrix
-
-| Component | Purpose | Port | Technology | Use Case |
-|-----------|---------|------|------------|----------|
-| **ControlPilot** | Central management | 7878 | FastAPI/React | Service orchestration |
-| **Kohya SS** | LoRA training | 6666 | Flask/React | Traditional training |
-| **AI Toolkit** | Modern training | 8675 | Next.js/Gradio | FLUX/SDXL training |
-| **Diffusion Pipe** | Pipeline training | 4444 | Python/TensorBoard | Large-scale training |
-| **ComfyUI** | Node-based inference | 5555 | React/WebGL | Complex workflows |
-| **InvokeAI** | User inference | 9090 | React/FastAPI | Easy image generation |
-| **TrainPilot** | Training automation | - | Python/CLI | Guided training |
-| **TagPilot** | Dataset tagging | - | React/FastAPI | Dataset preparation |
-| **MediaPilot** | Media management | - | React/FastAPI | Image organization |
-| **JupyterLab** | Notebook environment | 8888 | Python/Jupyter | Development |
-| **Code Server** | Browser IDE | 8443 | VS Code | Development |
-| **Copilot Sidecar** | AI assistant | 7879 | FastAPI | Code assistance |
-
-## 🔄 Integration Benefits
-
-### Shared Resources
-- **Models**: All components access `/workspace/models`
-- **Datasets**: Shared dataset storage in `/workspace/datasets`
-- **Outputs**: Unified output directory `/workspace/outputs`
-- **Configuration**: Centralized config in `/workspace/config`
-
-### Service Orchestration
-- **Supervisor**: All services managed by supervisord
-- **Health Monitoring**: Automatic restart and health checks
-- **Log Aggregation**: Centralized logging system
-- **Resource Management**: Shared GPU and memory management
-
-### Workflow Integration
-- **Seamless Transitions**: Move between tools without data loss
-- **Format Compatibility**: Standardized model and dataset formats
-- **API Integration**: Components communicate via APIs
-- **Web Interface**: Unified access through ControlPilot
-
-## 🚀 Component Deep Dives
-
-### Training Stack
-
-#### Kohya SS
-- **Strengths**: Battle-tested, extensive model support
-- **Best For**: Traditional LoRA training, fine-tuning
-- **Models**: SD1.5, SDXL, SD3, custom architectures
-- **Features**: Advanced config, extensive documentation
-
-#### AI Toolkit
-- **Strengths**: Modern stack, FLUX.1 support, Next.js UI
-- **Best For**: Latest model training, FLUX/SDXL
-- **Models**: FLUX.1, SDXL, SD3, experimental models
-- **Features**: Gradio interface, modern workflows
-
-#### Diffusion Pipe
-- **Strengths**: Scalable, TensorBoard integration
-- **Best For**: Large-scale training, experiment tracking
-- **Models**: All supported models
-- **Features**: Pipeline architecture, experiment management
-
-### Inference Stack
-
-#### ComfyUI
-- **Strengths**: Node-based, extensible, custom workflows
-- **Best For**: Complex generation workflows, automation
-- **Features**: Custom nodes, workflow sharing, batch processing
-
-#### InvokeAI
-- **Strengths**: User-friendly, stable, good for beginners
-- **Best For**: Simple generation, image editing
-- **Features**: Canvas mode, inpainting, upscaling
-
-### Management Tools
-
-#### ControlPilot
-- **Role**: Central command center
-- **Features**: Service control, model management, file browser
-- **Integration**: Manages all other components
-
-#### TrainPilot
-- **Role**: Training automation
-- **Features**: Guided setup, profile management, progress tracking
-- **Integration**: Works with Kohya and AI Toolkit
-
-#### TagPilot
-- **Role**: Dataset preparation
-- **Features**: Image tagging, captioning, dataset export
-- **Integration**: Feeds datasets to all trainers
-
-#### MediaPilot
-- **Role**: Media organization
-- **Features**: Image browsing, metadata, batch operations
-- **Integration**: Works with all generated content
-
-## 🛠️ Technology Stack
-
-### Backend Technologies
-- **Python 3.11**: Primary language for most components
-- **FastAPI**: API framework for web services
-- **Flask**: Legacy support (Kohya SS)
-- **Node.js**: AI Toolkit UI and Next.js
-
-### Frontend Technologies
-- **React**: Modern UI framework
-- **Vue.js**: Legacy support (some components)
-- **Gradio**: AI Toolkit interface
-- **WebGL**: ComfyUI rendering
-
-### Infrastructure
-- **Docker**: Containerization
-- **Supervisor**: Process management
-- **Nginx**: Reverse proxy (some components)
-- **SQLite**: Local databases
-
-## 🔧 Configuration
-
-### Service Configuration
-Each component has its own configuration:
-- **Environment Variables**: Service-specific settings
-- **Config Files**: YAML/TOML configuration
-- **Database**: SQLite for state management
-- **Logging**: Structured logging to files
-
-### Resource Allocation
-- **GPU Sharing**: Components share GPU resources
-- **Memory Management**: Automatic memory optimization
-- **Storage**: Shared workspace with quotas
-- **Network**: Port-based service isolation
-
-## 📊 Performance Characteristics
-
-### Training Performance
-| Component | Speed | Memory Usage | Model Support |
-|-----------|-------|--------------|---------------|
-| Kohya SS | Medium | Medium | Excellent |
-| AI Toolkit | Fast | High | Good |
-| Diffusion Pipe | Fast | Medium | Excellent |
-
-### Inference Performance
-| Component | Speed | Memory Usage | Features |
-|-----------|-------|--------------|----------|
-| ComfyUI | Fast | Medium | Extensive |
-| InvokeAI | Medium | Low | User-friendly |
-
-## 🔄 Version Compatibility
-
-### Component Versions
-- **Kohya SS**: Latest stable from upstream
-- **AI Toolkit**: Tracked to specific commits
-- **ComfyUI**: Latest with custom nodes
-- **InvokeAI**: Pinned stable version
-
-### Dependency Management
-- **Shared Venvs**: Components share Python environments
-- **Version Pinning**: Critical dependencies are pinned
-- **Conflict Resolution**: Separate venvs for conflicting packages
-- **Update Strategy**: Controlled updates with testing
-
-## 🚀 Future Components
 
-### Planned Additions
-- **Training Scheduler**: Advanced training scheduling
-- **Model Registry**: Centralized model versioning
-- **Experiment Tracker**: ML experiment management
-- **API Gateway**: Unified API for all services
+## Related
 
-### Integration Opportunities
-- **Cloud Storage**: S3/Google Drive integration
-- **Model Sharing**: Community model sharing
-- **Collaboration**: Multi-user workspaces
-- **Automation**: Workflow automation tools
+- [User Guide](../user-guide/README.md)
+- [Configuration](../configuration/README.md)
+- [Documentation Home](../README.md)
 
 ---
 
-*Last updated: 2025-02-11*
+_Last updated: 2026-02-11_